donebear 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/AGENTS.md +36 -21
  2. package/README.md +52 -38
  3. package/dist/cli.mjs +3757 -1818
  4. package/dist/cli.mjs.map +1 -1
  5. package/package.json +13 -10
  6. package/dist/index.d.mts +0 -1
  7. package/dist/index.mjs +0 -1
package/AGENTS.md CHANGED
@@ -6,12 +6,12 @@ Done Bear command-line interface for OAuth auth, workspace management, and task
6
6
 
7
7
  Run from repo root:
8
8
 
9
- - `npm run build --workspace=apps/cli` — build with tsdown
10
- - `npm run dev --workspace=apps/cli` — watch build
11
- - `npm run lint` — lint all workspaces (run from root)
12
- - `npm run check-types --workspace=apps/cli` — TypeScript check
13
- - `npm run test --workspace=apps/cli` — Vitest tests
14
- - `npm run lint:fix` — format/autofix before commit
9
+ - `npm run build --workspace=apps/cli`: build with tsdown
10
+ - `npm run dev --workspace=apps/cli`: watch build
11
+ - `npm run lint`: lint all workspaces (run from root)
12
+ - `npm run check-types --workspace=apps/cli`: TypeScript check
13
+ - `npm run test --workspace=apps/cli`: Vitest tests
14
+ - `npm run lint:fix`: format/autofix before commit
15
15
 
16
16
  Run CLI locally from repo root:
17
17
 
@@ -19,14 +19,21 @@ Run CLI locally from repo root:
19
19
 
20
20
  ## Agent Quickstart
21
21
 
22
- These two commands orient an AI agent before doing any work:
22
+ Three commands orient an AI agent before doing any work — mechanics, concepts,
23
+ then live state:
23
24
 
24
25
  ```bash
25
- # Discover all CLI commands and options (no auth required, ~500 tokens)
26
+ # Mechanics: every command and flag (no auth required, ~500 tokens)
26
27
  donebear spec
27
28
  donebear spec task add # Detailed spec for one command
28
29
 
29
- # Get current workspace state (requires auth)
30
+ # Concepts: what the ideas mean and how to use them well (no auth required)
31
+ donebear guide # Topic index
32
+ donebear guide agents # How to drive Done Bear as an agent
33
+ donebear guide views # Inbox/Today/Upcoming/Anytime/Someday
34
+ donebear guide bulk # Changing many tasks safely
35
+
36
+ # State: the current workspace (requires auth)
30
37
  donebear context --json
31
38
  donebear context --markdown # Markdown for system prompt injection
32
39
  ```
@@ -49,11 +56,11 @@ donebear spec task add # read field reference
49
56
  donebear context --json # check current workspace + task counts
50
57
  donebear task list --json # list open tasks
51
58
  donebear task add "Fix X" --when today --json
52
- donebear task done <id> --json
59
+ donebear task done <number> --json
53
60
 
54
- # Task id: full UUID or prefix of >= 4 chars
55
- donebear task show 8f2c --json
56
- donebear task edit 8f2c --deadline 2030-01-15 --json
61
+ # Task number: workspace-scoped positive integer
62
+ donebear task show 12 --json
63
+ donebear task edit 12 --deadline 2030-01-15 --json
57
64
 
58
65
  # Workspace targeting (no flag needed)
59
66
  donebear workspace=myorg task list --json
@@ -68,7 +75,7 @@ src/
68
75
  command-context.ts # auth/API/context resolution for commands
69
76
  command-helpers.ts # workspace normalization, task state parsing
70
77
  command-parsers.ts # input validators (positive int, etc.)
71
- manage-api.ts # legacy API helpers (GraphQL loaders)
78
+ manage-api.ts # live CLI API layer (viewer/workspaces/tasks via manage-client; other GraphQL loaders still local)
72
79
  workspace-context.ts # workspace slug validation + default resolution
73
80
  task-defaults.ts # task view-to-start field mapping
74
81
  output.ts # JSON/CSV/TSV/text/clipboard output formatting
@@ -79,31 +86,38 @@ src/
79
86
  env.ts # dotenv loading from workspace .env files
80
87
  auth-session.ts # token precedence + refresh behavior
81
88
  supabase.ts # Supabase config + auth client helpers
82
- oauth.ts # OAuth state generation
89
+ pkce.ts # OAuth PKCE verifier/challenge + state generation
83
90
  oauth-callback.ts # loopback callback server for OAuth PKCE
91
+ oauth-token.ts # authorization-code exchange
84
92
  context-store.ts # local context cache (workspace + clientId)
85
93
  storage.ts # stored auth session persistence
86
94
  browser.ts # platform-aware URL opening
87
- index.ts # library re-exports
88
95
  api/
89
96
  http.ts # base fetch wrapper, NDJSON streaming, error handling
90
- sync.ts # sync protocol (mutateModel, batch reads)
97
+ bootstrap.ts # /sync/bootstrap fetch + the content-model allowlist
91
98
  commands/
92
99
  auth.ts # auth login/status/logout
93
100
  whoami.ts # current user output
94
101
  workspace.ts # workspace list/current/use/clear/create/join
95
102
  task.ts # task list/show/add/edit/done/reopen/archive/unarchive
96
103
  project.ts # project list/show/add/edit/done/archive/unarchive
104
+ comment.ts # task comment list/add/edit/remove
97
105
  label.ts # label list/show
98
106
  team.ts # team list/show
99
107
  today.ts # today's tasks shortcut
100
108
  search.ts # task search across workspace
101
109
  history.ts # workspace audit log
102
110
  spec.ts # progressive CLI spec (no auth, static data)
111
+ guide.ts # concept guides for agents (no auth, static data)
112
+ doctor.ts # environment diagnostics (version, auth, workspace)
103
113
  context.ts # workspace state snapshot (auth + workspace required)
104
114
  api-key.ts # API key create/list/revoke
105
115
  import.ts # Things 3 import (uses import/ modules)
116
+ export.ts # workspace JSON archive (uses export/ modules)
106
117
  interactive.ts # TUI mode (no args + TTY stdin)
118
+ export/
119
+ export-runner.ts # streams /sync/bootstrap into a portable archive
120
+ export-output.ts # export result summary formatting
107
121
  import/
108
122
  things-runner.ts # orchestrates full Things 3 import pipeline
109
123
  things-sqlite.ts # reads Things 3 SQLite database
@@ -112,9 +126,9 @@ src/
112
126
  things-labels.ts # label normalization for import dedup
113
127
  things-recurrence.ts # Things recurrence to RRule conversion
114
128
  things-output.ts # import result summary formatting
115
- model-id.ts # deterministic UUID generation for imports
129
+ model-id.ts # import + idempotency-key UUIDs (composite sync ids come from @donebear/sync-ids)
116
130
  time-zone.ts # calendar date/time zone helpers
117
- tests/ # Vitest — npm run test --workspace=apps/cli
131
+ tests/ # Vitest: npm run test --workspace=apps/cli
118
132
  ```
119
133
 
120
134
  ## Gotchas
@@ -123,7 +137,8 @@ tests/ # Vitest — npm run test --workspace=apps/cli
123
137
  - Token precedence is `--token` > `DONEBEAR_TOKEN` > stored auth session.
124
138
  - API URL precedence is `--api-url` > `DONEBEAR_API_URL` > `https://api.donebear.com` (see `constants.ts`).
125
139
  - Local auth/context files are unencrypted and stored in the OS config dir (`DONEBEAR_CONFIG_DIR` can override).
126
- - `task` commands accept ID prefixes; prefix resolution is workspace-scoped and may be ambiguous without `--workspace`.
140
+ - `task` commands accept workspace-scoped positive task numbers; use `--workspace` when the active workspace is not the intended one.
127
141
  - Use `--json` for scripts/automation and keep human-readable output as default.
128
- - `spec` command returns JSON regardless of `--format` — it is always machine-targeted.
142
+ - `spec` command returns JSON regardless of `--format`; it is always machine-targeted.
143
+ - `guide` prints markdown in a TTY and JSON when piped (the usual auto-JSON rule). Its content is hand-maintained; `tests/guide.test.ts` fails when a guide cites a command or flag the CLI does not have. The MCP server keeps a sibling copy in `apps/manage-api/src/modules/mcp/guides.ts` — update both when the facts change.
129
144
  - `context --markdown` uses `--markdown` (local flag), not the global `--format` option.
package/README.md CHANGED
@@ -1,17 +1,20 @@
1
1
  # donebear
2
2
 
3
- Command-line interface for Done Bear.
3
+ Command-line interface for [Done Bear](https://donebear.com), a local-first GTD
4
+ task manager for the web, macOS, Windows, Linux, and
5
+ [iOS](https://donebear.com/ios).
4
6
 
5
- ## Quick start
7
+ Docs: [donebear.com/docs/cli](https://donebear.com/docs/cli) ·
8
+ Account: [app.donebear.com](https://app.donebear.com)
6
9
 
7
- Install and build from the repo root:
10
+ ## Quick start
8
11
 
9
12
  ```bash
10
- npm install
11
- npm run build --workspace=apps/cli
13
+ npm install -g donebear
14
+ donebear --help
12
15
  ```
13
16
 
14
- Run the CLI:
17
+ Or run it without installing:
15
18
 
16
19
  ```bash
17
20
  npx donebear --help
@@ -27,7 +30,7 @@ npx donebear task add "Ship donebear CLI" --when today
27
30
  npx donebear task list
28
31
  ```
29
32
 
30
- No environment variables are needed — the CLI connects to production by default.
33
+ No environment variables are needed; the CLI connects to production by default.
31
34
 
32
35
  ## Authentication
33
36
 
@@ -35,8 +38,6 @@ Log in via browser OAuth:
35
38
 
36
39
  ```bash
37
40
  npx donebear auth login
38
- npx donebear auth login --provider google
39
- npx donebear auth login --provider github
40
41
  ```
41
42
 
42
43
  Check or clear your session:
@@ -67,12 +68,15 @@ npx donebear task add "Pay invoice" --when today --deadline 2026-03-05
67
68
  npx donebear task add "Write tests" --project PROJ --team ENG
68
69
  ```
69
70
 
71
+ Without `--when`, a new task lands in **Today**. Pass `--when inbox` to capture
72
+ something without scheduling it.
73
+
70
74
  List and search:
71
75
 
72
76
  ```bash
73
77
  npx donebear task list
74
78
  npx donebear task list --state all --search invoice
75
- npx donebear task show <id>
79
+ npx donebear task show <number>
76
80
  npx donebear today
77
81
  npx donebear search "invoice"
78
82
  ```
@@ -80,30 +84,30 @@ npx donebear search "invoice"
80
84
  Edit:
81
85
 
82
86
  ```bash
83
- npx donebear task edit <id> --title "Pay vendor invoice"
84
- npx donebear task edit <id> --description "Waiting for approval" --when upcoming
85
- npx donebear task edit <id> --clear-deadline
86
- npx donebear task append <id> "Added follow-up note"
87
+ npx donebear task edit <number> --title "Pay vendor invoice"
88
+ npx donebear task edit <number> --description "Waiting for approval" --when upcoming
89
+ npx donebear task edit <number> --clear-deadline
90
+ npx donebear task append <number> "Added follow-up note"
87
91
  ```
88
92
 
89
93
  Complete and manage:
90
94
 
91
95
  ```bash
92
- npx donebear task done <id>
93
- npx donebear task reopen <id>
94
- npx donebear task archive <id>
96
+ npx donebear task done <number>
97
+ npx donebear task reopen <number>
98
+ npx donebear task archive <number>
95
99
  ```
96
100
 
97
101
  Checklists:
98
102
 
99
103
  ```bash
100
- npx donebear task checklist <id>
101
- npx donebear task checklist <id> add "Subtask title"
102
- npx donebear task checklist <id> done <item-id>
103
- npx donebear task checklist <id> remove <item-id>
104
+ npx donebear task checklist <number>
105
+ npx donebear task checklist <number> add "Subtask title"
106
+ npx donebear task checklist <number> done <item-id>
107
+ npx donebear task checklist <number> remove <item-id>
104
108
  ```
105
109
 
106
- Task IDs can be a full UUID or a unique prefix (4+ characters).
110
+ Task numbers are positive integers scoped to a workspace.
107
111
 
108
112
  ## Projects
109
113
 
@@ -160,20 +164,23 @@ npx donebear task list --total # count only
160
164
  | `project` | list | list, show, add, edit, done, archive, unarchive |
161
165
  | `label` | list | list, show |
162
166
  | `team` | list | list, show |
163
- | `today` | — | List today's tasks |
164
- | `search` | — | Search tasks by title or description |
165
- | `history` | — | Workspace audit log |
166
- | `context` | — | Workspace state snapshot (--markdown for prompts) |
167
- | `spec` | — | CLI spec for agent discovery (no auth required) |
168
- | `api-key` | — | create, list, revoke |
169
- | `import things` | — | Import from Things 3 (--dry-run supported) |
170
- | `whoami` | — | Print current user |
167
+ | `today` | n/a | List today's tasks |
168
+ | `search` | n/a | Search tasks by title or description |
169
+ | `history` | n/a | Workspace audit log |
170
+ | `context` | n/a | Workspace state snapshot (--markdown for prompts) |
171
+ | `spec` | n/a | CLI spec for agent discovery (no auth required) |
172
+ | `guide` | n/a | Concept guides for agents (no auth required) |
173
+ | `doctor` | n/a | Environment diagnostics |
174
+ | `api-key` | n/a | create, list, revoke |
175
+ | `import things` | n/a | Import from Things 3 (--dry-run supported) |
176
+ | `export` | n/a | Export a workspace as a portable JSON archive on stdout |
177
+ | `whoami` | n/a | Print current user |
171
178
 
172
179
  Run `npx donebear <command> --help` for full details.
173
180
 
174
181
  ## Environment variables
175
182
 
176
- These are optional — the CLI works out of the box for production use.
183
+ These are optional; the CLI works out of the box for production use.
177
184
 
178
185
  | Variable | Purpose | Default |
179
186
  | ----------------------------------- | ------------------------------ | -------------------------- |
@@ -195,16 +202,23 @@ These are optional — the CLI works out of the box for production use.
195
202
 
196
203
  ## Troubleshooting
197
204
 
198
- | Symptom | Fix |
199
- | -------------------------------- | ------------------------------------------------- |
200
- | `Not authenticated` | Run `npx donebear auth login` or pass `--token` |
201
- | OAuth times out | Check browser, retry with `--port` or `--no-open` |
202
- | `No default workspace selected` | Run `npx donebear workspace use <id-or-slug>` |
203
- | `Task prefix "..." is ambiguous` | Use the full task ID from `task list` |
205
+ | Symptom | Fix |
206
+ | ---------------------------------------- | ------------------------------------------------- |
207
+ | `Not authenticated` | Run `npx donebear auth login` or pass `--token` |
208
+ | OAuth times out | Check browser, retry with `--port` or `--no-open` |
209
+ | `No default workspace selected` | Run `npx donebear workspace use <id-or-slug>` |
210
+ | `Task number must be a positive integer` | Use the number from `task list` |
204
211
 
205
212
  ## Development
206
213
 
207
- From repo root:
214
+ Build from a checkout of the monorepo:
215
+
216
+ ```bash
217
+ npm install
218
+ npm run build --workspace=apps/cli
219
+ ```
220
+
221
+ Then, from repo root:
208
222
 
209
223
  ```bash
210
224
  npm run lint --workspace=apps/cli