donebear 0.3.1

package/AGENTS.md

@@ -0,0 +1,129 @@
+# donebear
+
+Done Bear command-line interface for OAuth auth, workspace management, and task workflows.
+
+## Commands
+
+Run from repo root:
+
+- `npm run build --workspace=apps/cli` — build with tsdown
+- `npm run dev --workspace=apps/cli` — watch build
+- `npm run lint --workspace=apps/cli` — lint with Oxlint
+- `npm run check-types --workspace=apps/cli` — TypeScript check
+- `npm run test --workspace=apps/cli` — Vitest tests
+- `npm exec -- ultracite fix` — format/autofix before commit
+
+Run CLI locally from repo root:
+
+- `npm exec --workspace=apps/cli donebear -- --help`
+
+## Agent Quickstart
+
+These two commands orient an AI agent before doing any work:
+
+```bash
+# Discover all CLI commands and options (no auth required, ~500 tokens)
+donebear spec
+donebear spec task add      # Detailed spec for one command
+
+# Get current workspace state (requires auth)
+donebear context --json
+donebear context --markdown  # Markdown for system prompt injection
+```
+
+### Non-interactive / CI use
+
+Set `DONEBEAR_TOKEN` instead of running `donebear auth login`:
+
+```bash
+export DONEBEAR_TOKEN=<your-token>
+donebear task list --json
+donebear task add "Fix bug" --when today --json
+```
+
+### Common agent patterns
+
+```bash
+# Discover → orient → act
+donebear spec task add           # read field reference
+donebear context --json          # check current workspace + task counts
+donebear task list --json        # list open tasks
+donebear task add "Fix X" --when today --json
+donebear task done <id> --json
+
+# Task id: full UUID or prefix of >= 4 chars
+donebear task show 8f2c --json
+donebear task edit 8f2c --deadline 2026-03-20 --json
+
+# Workspace targeting (no flag needed)
+donebear workspace=myorg task list --json
+```
+
+## Architecture
+
+```text
+src/
+  cli.ts               # Commander entrypoint + global flags
+  runtime.ts           # context parsing, error handling, interactive detection
+  command-context.ts   # auth/API/context resolution for commands
+  command-helpers.ts   # workspace normalization, task state parsing
+  command-parsers.ts   # input validators (positive int, etc.)
+  manage-api.ts        # legacy API helpers (GraphQL loaders)
+  workspace-context.ts # workspace slug validation + default resolution
+  task-defaults.ts     # task view-to-start field mapping
+  output.ts            # JSON/CSV/TSV/text/clipboard output formatting
+  types.ts             # shared TypeScript interfaces for all models
+  constants.ts         # env var names, defaults, config paths
+  errors.ts            # CliError class + exit codes
+  date-codecs.ts       # ISO 8601 date-only/instant parsing + epoch conversion
+  env.ts               # dotenv loading from workspace .env files
+  auth-session.ts      # token precedence + refresh behavior
+  supabase.ts          # Supabase config + auth client helpers
+  oauth.ts             # OAuth state generation
+  oauth-callback.ts    # loopback callback server for OAuth PKCE
+  context-store.ts     # local context cache (workspace + clientId)
+  storage.ts           # stored auth session persistence
+  browser.ts           # platform-aware URL opening
+  index.ts             # library re-exports
+  api/
+    http.ts            # base fetch wrapper, NDJSON streaming, error handling
+    sync.ts            # sync protocol (mutateModel, batch reads)
+  commands/
+    auth.ts            # auth login/status/logout
+    whoami.ts          # current user output
+    workspace.ts       # workspace list/current/use/clear/create/join
+    task.ts            # task list/show/add/edit/done/reopen/archive/unarchive
+    project.ts         # project list/show/add/edit/done/archive/unarchive
+    label.ts           # label list/show
+    team.ts            # team list/show
+    today.ts           # today's tasks shortcut
+    search.ts          # task search across workspace
+    history.ts         # workspace audit log
+    spec.ts            # progressive CLI spec (no auth, static data)
+    context.ts         # workspace state snapshot (auth + workspace required)
+    api-key.ts         # API key create/list/revoke
+    import.ts          # Things 3 import (uses import/ modules)
+    interactive.ts     # TUI mode (no args + TTY stdin)
+  import/
+    things-runner.ts   # orchestrates full Things 3 import pipeline
+    things-sqlite.ts   # reads Things 3 SQLite database
+    things-mapper.ts   # maps Things rows to Done Bear sync transactions
+    things-values.ts   # Things date/field value decoders
+    things-labels.ts   # label normalization for import dedup
+    things-recurrence.ts # Things recurrence to RRule conversion
+    things-output.ts   # import result summary formatting
+    model-id.ts        # deterministic UUID generation for imports
+    time-zone.ts       # calendar date/time zone helpers
+tests/                 # Vitest — npm run test --workspace=apps/cli
+```
+
+## Gotchas
+
+- OAuth callback defaults to `http://127.0.0.1:8787/auth/callback`; it must be allow-listed in Supabase redirect URLs.
+- Token precedence is `--token` > `DONEBEAR_TOKEN` > stored auth session.
+- API URL precedence is `--api-url` > `DONEBEAR_API_URL` > `NEXT_PUBLIC_RESERVE_MANAGE_API` > `http://127.0.0.1:3001`.
+- Local auth/context files are unencrypted and stored in the OS config dir (`DONEBEAR_CONFIG_DIR` can override).
+- `task` commands accept ID prefixes; prefix resolution is workspace-scoped and may be ambiguous without `--workspace`.
+- Use `--json` for scripts/automation and keep human-readable output as default.
+- `spec` command returns JSON regardless of `--format` — it is always machine-targeted.
+- `context --markdown` uses `--markdown` (local flag), not the global `--format` option.

package/README.md

@@ -0,0 +1,251 @@
+# donebear
+
+Done Bear CLI for OAuth auth, workspace management, and task workflows against `manage-api`.
+
+## Quick start
+
+1. Install workspace dependencies from repo root:
+
+```bash
+npm install
+```
+
+2. Build the CLI package:
+
+```bash
+npm run build --workspace=apps/cli
+```
+
+3. Set required environment variables:
+
+```bash
+export DONEBEAR_SUPABASE_URL="https://<project-ref>.supabase.co"
+export DONEBEAR_SUPABASE_PUBLISHABLE_KEY="<publishable-or-anon-key>"
+export DONEBEAR_API_URL="http://127.0.0.1:3001"
+```
+
+4. Define a local runner command:
+
+```bash
+CLI="npm exec --workspace=apps/cli donebear --"
+```
+
+5. Authenticate and run the core task flow:
+
+```bash
+$CLI auth login
+$CLI workspace list
+$CLI workspace use <workspace-id-or-slug>
+$CLI task add "Ship donebear CLI" --when today
+$CLI task list --state open
+```
+
+## OAuth setup
+
+The default callback URL is:
+
+```text
+http://127.0.0.1:8787/auth/callback
+```
+
+Add that URL to Supabase Auth allowed redirect URLs.
+
+Login options:
+
+```bash
+$CLI auth login --provider google
+$CLI auth login --provider github --port 8787 --timeout 180
+$CLI auth login --no-open
+```
+
+Check and clear auth:
+
+```bash
+$CLI auth status
+$CLI whoami
+$CLI auth logout
+```
+
+## Core task flows
+
+Capture:
+
+```bash
+$CLI task add "Draft release notes" --when inbox
+$CLI task add "Pay invoice" --when today --deadline 2026-03-05
+$CLI task add "Write tests" --project PROJ --team ENG
+```
+
+Review:
+
+```bash
+$CLI task list --state open --limit 50
+$CLI task list --state all --search invoice
+$CLI task show <task-id-or-prefix>
+$CLI task read <id>
+$CLI today
+$CLI search "invoice"
+```
+
+Triage/edit:
+
+```bash
+$CLI task edit <id> --title "Pay vendor invoice"
+$CLI task edit <id> --notes "Waiting for approval" --when upcoming
+$CLI task edit <id> --clear-deadline
+$CLI task append <id> "Added follow-up note"
+$CLI task prepend <id> "Priority note"
+```
+
+Complete and clean up:
+
+```bash
+$CLI task done <id>
+$CLI task reopen <id>
+$CLI task archive <id>
+$CLI task unarchive <id>
+```
+
+Checklists:
+
+```bash
+$CLI task checklist <id>
+$CLI task checklist <id> add "Subtask title"
+$CLI task checklist <id> done <item-id>
+$CLI task checklist <id> remove <item-id>
+```
+
+Projects:
+
+```bash
+$CLI project list
+$CLI project add "Q1 Launch" --key LAUNCH --target-date 2026-06-30
+$CLI project edit LAUNCH --target-date 2026-03-31
+$CLI project done LAUNCH
+$CLI project archive LAUNCH
+```
+
+Workspace:
+
+```bash
+$CLI workspace create "Personal" --slug personal --no-use
+$CLI workspace join <invite-code>
+$CLI workspace members <workspace-id>
+$CLI workspace invitations <workspace-id>
+$CLI workspace invite <workspace-id> --email user@example.com
+$CLI workspace clear
+```
+
+Notes:
+
+- `task show|done|reopen|archive|unarchive|edit` accept a full task ID or unique ID prefix (>= 4 chars).
+- `project show|edit|done|archive|unarchive` accept a full ID, project key, or name.
+- Prefix resolution uses your selected workspace, or `--workspace` if provided.
+- `task list` paginates through GraphQL results, so it is not capped at 100 tasks.
+- `donebear auth`, `donebear workspace`, and `donebear task` run sensible defaults (status, list workspaces, list open tasks).
+
+## Command reference
+
+Global options:
+
+- `--json` machine-readable output
+- `--format <format>` output format: text | json | csv | tsv
+- `--copy` copy output to clipboard
+- `--total` print count only
+- `--token <token>` explicit bearer token
+- `--api-url <url>` manage-api base URL
+- `--debug` include stack traces in failures
+- `--no-color` disable ANSI color
+
+Root commands:
+
+- `auth` (default: status) + login/status/logout
+- `workspace` (default: list) + list/current/use/clear/create/join/members/invitations/invite
+- `task` (default: list open) + list/show/add/edit/done/reopen/archive/unarchive/read/append/prepend/random/checklist
+- `project` (default: list) + list/show/add/edit/done/archive/unarchive
+- `label` (default: list) + list/show
+- `team` (default: list) + list/show
+- `today` list today's tasks
+- `search <query>` search tasks by title or notes
+- `history` workspace audit log
+- `context` workspace state snapshot (--markdown for system prompts)
+- `spec` progressive CLI spec for agent discovery (no auth required)
+- `api-key` + create/list/revoke
+- `import things` import from Things 3 (--dry-run supported)
+- `whoami` print current authenticated user (`me` alias)
+
+Run `donebear <command> --help` for aliases and short flags.
+
+## JSON and automation
+
+Example: pick current workspace id:
+
+```bash
+$CLI workspace current --json | jq -r '.workspace.id'
+```
+
+Example: list open task titles:
+
+```bash
+$CLI task list --state open --json | jq -r '.tasks[].title'
+```
+
+Example: export tasks as CSV:
+
+```bash
+$CLI task list --format csv > tasks.csv
+```
+
+Non-interactive auth with API key or token:
+
+```bash
+$CLI api-key create "CI"    # creates a long-lived API key
+export DONEBEAR_TOKEN=<key>
+$CLI task list --json
+```
+
+Auth token precedence:
+
+1. `--token <token>`
+2. `DONEBEAR_TOKEN`
+3. stored session (`auth login`)
+
+## Environment variables
+
+| Variable                            | Purpose                               | Default / fallback                                                            |
+| ----------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------- |
+| `DONEBEAR_SUPABASE_URL`             | Supabase project URL for OAuth        | fallback: `NEXT_PUBLIC_SUPABASE_URL`, `SUPABASE_URL`                          |
+| `DONEBEAR_SUPABASE_PUBLISHABLE_KEY` | Supabase publishable/anon key         | fallback: `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY`, `SUPABASE_ANON_KEY` |
+| `DONEBEAR_API_URL`                  | manage-api base URL                   | fallback: `NEXT_PUBLIC_RESERVE_MANAGE_API`, default `http://127.0.0.1:3001`   |
+| `DONEBEAR_TOKEN`                    | non-interactive bearer token          | none                                                                          |
+| `DONEBEAR_CONFIG_DIR`               | override local config/cache directory | OS config dir + `/donebear`                                                   |
+| `DONEBEAR_DEBUG`                    | enable debug logging (`1`)            | disabled                                                                      |
+
+## Exit codes
+
+| Code | Meaning                 |
+| ---- | ----------------------- |
+| `0`  | Success                 |
+| `1`  | General error           |
+| `2`  | Cancelled or timeout    |
+| `4`  | Authentication required |
+
+## Troubleshooting
+
+| Symptom                                       | Cause                                                  | Fix                                                                 |
+| --------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
+| `Not authenticated. Run donebear auth login.` | Missing or expired token                               | Run `$CLI auth login`, or pass `--token`                            |
+| OAuth times out waiting for callback          | Callback URL/port mismatch or blocked browser redirect | Verify Supabase redirect URL and retry with `--port` or `--no-open` |
+| `No default workspace selected.`              | Multiple workspaces and none selected                  | Run `$CLI workspace use <id-or-slug>`                               |
+| `Task prefix "..." is ambiguous`              | Prefix matches multiple tasks                          | Use full task ID from `task list`                                   |
+
+## Development
+
+From repo root:
+
+```bash
+npm run lint --workspace=apps/cli
+npm run check-types --workspace=apps/cli
+npm run test --workspace=apps/cli
+npm run build --workspace=apps/cli
+```

package/dist/cli.d.mts

@@ -0,0 +1,2 @@
+
+export { };