Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ IKE_DATA_FILE=$(mktemp -d)/t.json go run . list # run against a scratch data f

Dependency direction: `cli` → `tui`/`mcpserver` → `store` → `task`. **All business logic lives in `internal/store/ops.go`** (Add/Complete/Restore/Move/Reorder/Rename/Delete/SetQuadrantLabel/Undo/Redo/List/ListArchive); the three frontends must stay thin wrappers over it. `internal/task` is the zero-dependency domain (Task struct, Quadrant 1–4 with default labels, and `Less`/`SortOrder`, the single definition of display order).

**Every mutating op returns the post-mutation `Data` alongside its own result** — `Add` is `(task.Task, Data, error)`, `Undo` is `(string, Data, error)`. `Mutate` already produces that value, so handing it back costs nothing and spares the caller a second read. Frontends must render the outcome from it (`d.Labels.Of(q)`, `d.List(q)`) rather than calling `Load`/`QuadrantLabels` again: a follow-up read observes a *later* file state, and the helpers that used to do it (`cli.quadrantLabels`, `mcpserver.labelsOf`) both swallowed the error to stay "cosmetic". `SetMCPEnabled` is the deliberate exception — nothing renders from it.

Listing order has exactly one definition each, as pure methods on `Data`: **`d.List(q)`** (active tasks, quadrant then rank then ID) and **`d.ListArchive()`** (newest completion first, unstamped tasks by ID). `Store.List`/`Store.ListArchive` are `Load` plus these; the TUI calls them directly on the data it already holds. The TUI used to reverse `data.Archive` instead, which agrees with `ListArchive` only while every archived task carries a `done_at`. `ListArchive` must keep returning a non-nil empty slice — `ike archive --json` emits `[]`, not `null`.

Quadrant headings are user-customizable. `task.Quadrant.Label()` gives the **default** name; `store.Data.Labels` (a sparse `map[Quadrant]string`, only renamed quadrants present) holds overrides, and **`Labels.Of(q)` is the only correct way to render a quadrant name** — it is nil-safe, so `d.Labels.Of(q)` works on a store that has never been renamed. Never print `q.Label()` in a frontend. Clearing a label deletes the map entry rather than storing `""`, so later changes to the defaults still reach users who reset. The quadrant *number* is the stable identifier for classification and scripting; only the display name varies.

Concurrency contract (`internal/store/store.go`): every mutation goes through `Store.Mutate`, which flocks a **sidecar** `tasks.json.lock` (locking the data file itself would break — atomic rename replaces the inode), re-reads fresh inside the lock, applies the change, and writes via temp-file + `os.Rename`. Never write the data file any other way. Completing a task moves it from `tasks` to `archive` with `DoneAt` stamped (`Restore` reverses that); IDs are monotonic via `next_id` and never reused. Deleting skips the archive.
Expand All @@ -41,7 +45,13 @@ Undo/redo is snapshot-based, with two stacks in the data file (each capped at `u

Data file version is **2** (ranks + history stacks). `readFile` accepts version 1 and upgrades in memory; the next write persists version 2. A newer version than `currentVersion` is still a hard error. The `redo` field was added within version 2 as `omitempty` rather than bumping again — losing redo history to an older binary is harmless, whereas a bump makes older binaries refuse the file outright.

The TUI (`internal/tui`) is a single `Model` with a mode enum (normal/input/move/archive); `model.go` holds state + key handling, `view.go` all rendering. It re-renders from `Mutate` results and polls file mtime every 2s to pick up CLI/MCP writes. `archCursor` indexes `archiveList()` (newest first), *not* `data.Archive` — use the helper when acting on the selected archive row.
The TUI (`internal/tui`) is a single `Model` with a mode enum (normal/input/move/archive); `model.go` holds state + key handling, `view.go` all rendering. It re-renders from the `Data` each op returns and polls file mtime every 2s to pick up CLI/MCP writes. `archCursor` indexes `data.ListArchive()` (newest first), *not* `data.Archive` — use the helper when acting on the selected archive row.

Every mutation goes through **`m.apply(d, err) bool`**, which either shows the error or re-renders, and *returns whether it succeeded*. Set a success status only inside `if m.apply(...)`. Signalling failure through `m.status` and sniffing it afterwards is what let a failed complete/delete/move print "done: …" over its own error while the row stayed on screen (`TestFailedMutationsDoNotReportSuccess`). Enter and leave input mode only via **`enterInput`/`exitInput`**, which set and clear all of `mode`/`editingID`/`labelTarget`/value/placeholder together — setting them field-by-field leaked the quadrant-rename placeholder into the next task edit.

The CLI is **constructed, not registered**: `NewRootCmd(open)` builds the whole tree and every command has a `newXCmd(open) *cobra.Command` constructor, where `open` yields the store (lazily, inside `RunE`, so `ike --help` still works with a broken `IKE_DATA_FILE`). Command bodies wrap in `withStore` and print to `cmd.OutOrStdout()`. Do not go back to `init()` plus a package-level `rootCmd`: that made flag variables process-global and left every `RunE` untestable — `internal/cli` sat at 18.9% coverage with `ike mcp enable|disable` at 0%, i.e. the consent toggle was tested everywhere except where users invoke it. Tests build a tree over a scratch file with `runCLI`.

Store tests are split by concern: `ops_test.go` (tasks, ordering, ranks), `history_test.go` (undo/redo), `labels_test.go`, `mcp_test.go` (the gate), `store_test.go` + `durability_test.go` (the write path). Keep new tests in the matching file rather than growing one past ~1000 lines.

## Gotchas

Expand Down
Loading