You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
pnpm-tabtab.d.ts # type declarations for @pnpm/tabtab
57
-
```
32
+
## Rules when changing code
58
33
59
-
## Key Patterns
60
-
61
-
-**Ref resolution** (`src/lib/refs.ts`): Entity references are resolved through three strategies:
62
-
-**Full name resolution** (`resolveRef` wrappers — `resolveTaskRef`, `resolveProjectRef`): Async, returns the full entity object. Tries URL → `id:` prefix → exact name match → partial substring match → raw ID fallback. Use for entities with user-facing names. Add new wrappers in `refs.ts` — `resolveRef` is private.
63
-
-**ID-only validation** (`lenientIdRef`): Synchronous, no API calls, returns an ID string. Tries `id:` prefix → URL → raw ID → error. Use for entities without a `fetchAll` endpoint (e.g., comments, reminders).
64
-
-**Context-scoped resolution** (`resolveSectionId`, `resolveParentTaskId`, `resolveWorkspaceRef`): Async, searches within a parent context (e.g., sections within a project). Each has custom logic in `refs.ts`.
65
-
-**Shared helpers**:
66
-
-`looksLikeRawId()` decides when a ref is tried as an ID — pure alpha strings (`"Work"`) and strings with spaces are names; mixed alphanumeric without spaces (`"abc123"`) are potential IDs
67
-
-`parseTodoistUrl()` extracts IDs from web URLs (task, project, label, filter)
68
-
-**Implicit view subcommand**: `td project <ref>` defaults to `td project view <ref>` via Commander's `{ isDefault: true }`. Same for task, workspace, comment, notification. Edge case: if a project/task name matches a subcommand name (e.g., "list"), the subcommand wins — user must use `td project view list`
69
-
-**Named flag aliases**: Where commands accept positional args for context (project, task, workspace), named flags are also accepted (`--project`, `--task`, `--workspace`). Error if both positional and flag are provided
-**Priority mapping**: API uses 4=p1 (highest), 1=p4 (lowest)
72
-
-**Command registration**: Each command exports `registerXxxCommand(program: Command)` function from its `index.ts` (folder-based commands) or top-level `.ts` file (flat commands). Folder-based commands split each subcommand into its own file with the index.ts wiring them to Commander.
34
+
-**Named flag aliases:** where commands accept positional args for context (project, task, workspace), named flags (`--project`, `--task`, `--workspace`) are also accepted. Error if both positional and flag are provided.
35
+
-**Implicit `view` subcommand edge case:**`td project <ref>` defaults to `td project view <ref>`. If a project/task name matches a subcommand name (e.g., `"list"`), the subcommand wins — users must use `td project view list`.
-**Priority mapping:** CLI uses `"p1"`–`"p4"` strings; API uses 4=p1 (highest), 1=p4 (lowest). Use `parsePriority` from `src/lib/task-list.ts`, never hand-roll.
38
+
-**Errors:** throw `CliError(code, message, hints?)` from `src/lib/errors.ts` for anything user-facing. The global `parseAsync().catch` in `src/index.ts` renders it correctly in JSON and pretty modes.
73
39
74
40
## Testing
75
41
76
42
Tests use vitest with mocked API. Run `npm test` before committing.
77
43
78
-
- Tests are colocated next to the command or lib module they cover (for example `src/commands/task/index.test.ts` or `src/lib/refs.test.ts`)
79
-
- Shared test helpers live in `src/test-support/` (`mock-api.ts`, `fixtures.ts`)
80
-
- When adding features, add corresponding tests
81
-
- Pattern: mock `getApi`, use `program.parseAsync()` to test commands
82
-
83
-
## Auth
84
-
85
-
Token from `TODOIST_API_TOKEN` env var or `~/.config/todoist-cli/config.json`:
86
-
87
-
```json
88
-
{ "api_token": "your-api-token" }
89
-
```
44
+
- Co-locate tests next to the command or lib module they cover.
45
+
- When adding features, add corresponding tests.
46
+
- See CODEBASE.md for the mock-api + fixtures setup.
90
47
91
48
## Skill Content (Agent Command Reference)
92
49
@@ -130,3 +87,13 @@ if (options.json) {
130
87
```
131
88
132
89
Delete, complete, uncomplete, archive, and unarchive commands do not support `--json` as they return no meaningful entity data.
90
+
91
+
## Keeping CODEBASE.md accurate
92
+
93
+
`CODEBASE.md` is a structural map, not a file index. Update it when **structure** changes — not on every new file. Triggers:
94
+
95
+
- new top-level dir under `src/`, or a new command-group folder
96
+
- a new broadly-reusable helper in `src/lib/` (the "don't reimplement" catalog)
97
+
- changes to command registration, auth/token storage, or build/test/release tooling
98
+
99
+
Adding a single subcommand to an existing group, or a narrowly-scoped helper used by one caller, does not require an update.
0 commit comments