@donebear/cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,49 @@
+# @donebear/cli
+
+Done Bear command-line interface for OAuth auth, workspace management, and task workflows.
+
+## Commands
+
+Run from repo root:
+
+- `npm run build --workspace=packages/donebear-cli` — build with tsdown
+- `npm run dev --workspace=packages/donebear-cli` — watch build
+- `npm run lint --workspace=packages/donebear-cli` — lint with Biome
+- `npm run check-types --workspace=packages/donebear-cli` — TypeScript check
+- `npm run test --workspace=packages/donebear-cli` — Vitest tests
+- `npm exec -- ultracite fix` — format/autofix before commit
+
+Run CLI locally from repo root:
+
+- `npm exec --workspace=packages/donebear-cli donebear -- --help`
+
+## Architecture
+
+```text
+src/
+  cli.ts               # Commander entrypoint + global flags
+  runtime.ts           # context parsing + error handling
+  command-context.ts   # auth/API/context resolution for commands
+  commands/
+    auth.ts            # auth login/status/logout (default command shows status)
+    whoami.ts          # current user output
+    workspace.ts       # workspace list/current/use/clear/create/join (default lists)
+    task.ts            # task list/show/add/edit/done/reopen/archive/unarchive (default lists open tasks)
+  manage-api.ts        # typed manage-api HTTP helpers
+  workspace-context.ts # workspace slug validation + default resolution
+  task-defaults.ts     # task view-to-start field mapping
+  context-store.ts     # local context cache (workspace + clientId)
+  auth-session.ts      # token precedence + refresh behavior
+  supabase.ts          # Supabase config + auth client helpers
+  oauth-callback.ts    # loopback callback server for OAuth
+  storage.ts           # stored auth session persistence
+```
+
+## 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.

package/README.md

@@ -0,0 +1,197 @@
+# @donebear/cli
+
+Done Bear CLI for OAuth auth, workspace selection, 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=packages/donebear-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=packages/donebear-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
+```
+
+Review:
+
+```bash
+$CLI task list --state open --limit 50
+$CLI task list --state all --search invoice
+$CLI task show <task-id-or-prefix>
+```
+
+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
+```
+
+Complete and clean up:
+
+```bash
+$CLI task done <id>
+$CLI task reopen <id>
+$CLI task archive <id>
+$CLI task unarchive <id>
+```
+
+Workspace:
+
+```bash
+$CLI workspace create "Personal" --slug personal --no-use
+$CLI workspace join <invite-code>
+$CLI workspace clear
+```
+
+Notes:
+- `task show|done|reopen|archive|unarchive|edit` accept a full task ID or unique ID prefix.
+- 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
+- `--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
+- `task` (default: list open) + list/show/add/edit/done/reopen/archive/unarchive
+- `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'
+```
+
+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=packages/donebear-cli
+npm run check-types --workspace=packages/donebear-cli
+npm run test --workspace=packages/donebear-cli
+npm run build --workspace=packages/donebear-cli
+```
+
+Package-local start command:
+
+```bash
+npm run start --workspace=packages/donebear-cli
+```

package/dist/cli.d.mts

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