donebear 0.4.1 → 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 +27 -12
  2. package/README.md +25 -21
  3. package/dist/cli.mjs +3699 -2219
  4. package/dist/cli.mjs.map +1 -1
  5. package/package.json +4 -13
  6. package/dist/index.d.mts +0 -1
  7. package/dist/index.mjs +0 -1
package/AGENTS.md CHANGED
@@ -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
@@ -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
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
@@ -38,8 +38,6 @@ Log in via browser OAuth:
38
38
 
39
39
  ```bash
40
40
  npx donebear auth login
41
- npx donebear auth login --provider google
42
- npx donebear auth login --provider github
43
41
  ```
44
42
 
45
43
  Check or clear your session:
@@ -70,12 +68,15 @@ npx donebear task add "Pay invoice" --when today --deadline 2026-03-05
70
68
  npx donebear task add "Write tests" --project PROJ --team ENG
71
69
  ```
72
70
 
71
+ Without `--when`, a new task lands in **Today**. Pass `--when inbox` to capture
72
+ something without scheduling it.
73
+
73
74
  List and search:
74
75
 
75
76
  ```bash
76
77
  npx donebear task list
77
78
  npx donebear task list --state all --search invoice
78
- npx donebear task show <id>
79
+ npx donebear task show <number>
79
80
  npx donebear today
80
81
  npx donebear search "invoice"
81
82
  ```
@@ -83,30 +84,30 @@ npx donebear search "invoice"
83
84
  Edit:
84
85
 
85
86
  ```bash
86
- npx donebear task edit <id> --title "Pay vendor invoice"
87
- npx donebear task edit <id> --description "Waiting for approval" --when upcoming
88
- npx donebear task edit <id> --clear-deadline
89
- 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"
90
91
  ```
91
92
 
92
93
  Complete and manage:
93
94
 
94
95
  ```bash
95
- npx donebear task done <id>
96
- npx donebear task reopen <id>
97
- npx donebear task archive <id>
96
+ npx donebear task done <number>
97
+ npx donebear task reopen <number>
98
+ npx donebear task archive <number>
98
99
  ```
99
100
 
100
101
  Checklists:
101
102
 
102
103
  ```bash
103
- npx donebear task checklist <id>
104
- npx donebear task checklist <id> add "Subtask title"
105
- npx donebear task checklist <id> done <item-id>
106
- 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>
107
108
  ```
108
109
 
109
- Task IDs can be a full UUID or a unique prefix (4+ characters).
110
+ Task numbers are positive integers scoped to a workspace.
110
111
 
111
112
  ## Projects
112
113
 
@@ -168,8 +169,11 @@ npx donebear task list --total # count only
168
169
  | `history` | n/a | Workspace audit log |
169
170
  | `context` | n/a | Workspace state snapshot (--markdown for prompts) |
170
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 |
171
174
  | `api-key` | n/a | create, list, revoke |
172
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 |
173
177
  | `whoami` | n/a | Print current user |
174
178
 
175
179
  Run `npx donebear <command> --help` for full details.
@@ -198,12 +202,12 @@ These are optional; the CLI works out of the box for production use.
198
202
 
199
203
  ## Troubleshooting
200
204
 
201
- | Symptom | Fix |
202
- | -------------------------------- | ------------------------------------------------- |
203
- | `Not authenticated` | Run `npx donebear auth login` or pass `--token` |
204
- | OAuth times out | Check browser, retry with `--port` or `--no-open` |
205
- | `No default workspace selected` | Run `npx donebear workspace use <id-or-slug>` |
206
- | `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` |
207
211
 
208
212
  ## Development
209
213