@kitsy/coop 0.0.1 → 1.1.0

package/README.md

@@ -2,6 +2,120 @@
 
 CLI package for COOP.
 
-Commands:
+Install globally:
+
+```bash
+npm i -g @kitsy/coop
+coop --help
+```
+
+Install locally in a repo:
+
+```bash
+pnpm add -D @kitsy/coop
+pnpm exec coop --help
+```
+
+Both entrypoints operate on the nearest parent `.coop/` workspace. If no workspace log target exists, CLI errors fall back to `~/.coop/logs/cli.log` or `COOP_HOME/logs/cli.log`.
+
+Current implemented command families:
 - `coop`
+- `coop init`
+- `coop create task ...`
+- `coop create task --from <idea> --ai`
+- `coop create idea ...`
+- `coop create track ...`
+- `coop create delivery ... [--commit] [--user <user>] [--force]`
+- `coop assign task <id> --to <assignee> [--actor <actor>]`
+- `coop list tasks|ideas|alias ...`
+- `coop show task|idea ...`
+- `coop transition task ... [--user <user>] [--force]`
+- `coop graph validate|next|show|critical-path ...`
+- `coop index status|rebuild`
+- `coop plan delivery <name>`
+- `coop plan delivery <name> --monte-carlo [--iterations <n>]`
+- `coop plan capacity <track>`
+- `coop status [--today <date>]`
+- `coop view kanban`
+- `coop view timeline --delivery <name>`
+- `coop view velocity [--today <date>]`
+- `coop view burndown --delivery <name> [--today <date>]`
+- `coop view capacity [--today <date>]`
+- `coop ui [--host <host>] [--port <port>] [--no-open]`
+- `coop serve [--host <host>] [--port <port>] [--repo <path>]`
+- `coop webhook github [--host <host>] [--port <port>] [--repo <path>]`
+- `coop migrate --dry-run --to 2`
+- `coop alias ...`
+- `coop list alias [pattern]`
+- `coop config index.data yaml|json`
+- `coop config id.naming "<TYPE>-<USER>-<YYMMDD>-<RAND>"`
+- `coop config project.name <name>`
+- `coop config project.id <id>`
+- `coop config project.aliases <csv>`
+- `coop config ai.provider mock|openai|anthropic|gemini|ollama`
+- `coop config ai.model <model-name>`
+- `coop run task <id> [--step <step>] [--dry-run]`
+
+Known limitations:
+- `ext` is still a placeholder for future phases.
+- Provider-backed AI is supported for `openai`, `anthropic`, `gemini`, and `ollama` via `.coop/config.yml` + env vars.
+- Authorization is advisory and config-driven (`.coop/config.yml -> authorization`).
+- Plugin runtime supports manifest triggers under `.coop/plugins/*.yml` (webhook + console + `github_pr` actions).
+- `coop ui` is read-only and depends on local `.coop/.index` data. The command rebuilds stale indexes before launch.
+- `coop init` creates `.coop/.ignore` and `.coop/.gitignore` so logs, tmp files, and index artifacts are not committed by default.
+
+GitHub integration quick example:
+```yaml
+github:
+  owner: kitsy
+  repo: coop
+  base_branch: main
+  token_env: GITHUB_TOKEN
+  webhook_secret_env: GITHUB_WEBHOOK_SECRET
+  merge_method: squash
+```
+
+With `.coop/plugins/github-pr.yml` enabled:
+- `coop transition task PM-101 in_review` creates or updates a PR
+- `coop transition task PM-101 done` merges the linked PR
+- `coop webhook github --port 8787` receives GitHub review/merge webhooks and syncs task status
+
+API server and cross-repo dependency quick example:
+```yaml
+api:
+  host: 127.0.0.1
+  port: 3847
+  remotes:
+    platform-repo:
+      base_url: http://127.0.0.1:3848
+```
+
+With cross-repo task references such as `external:platform-repo/PM-200`:
+- `coop serve --port 3847` exposes the local read-only API
+- remote dependencies resolve through the configured API base URL when reachable
+- unreachable remotes are reported as external dependency risks
+
+Workspace identity:
+```yaml
+project:
+  name: Payments Platform
+  id: payments-platform
+  aliases:
+    - pay
+    - ledger.master
+```
+
+This identity is exposed through:
+- `GET /api/meta`
+- MCP `coop_workspace_info`
+- MCP `coop://workspace`
+
+Provider config quick example:
+```yaml
+ai:
+  provider: openai
+  model: gpt-5-mini
+  openai:
+    api_key_env: OPENAI_API_KEY
+```
 

package/bin/coop.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "../dist/index.js";
+
+await runCli(process.argv);

package/bin/coop.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+
+const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "dist", "index.js");
+const result = spawnSync(process.execPath, [script, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+process.exit(result.status ?? 1);

package/dist/index.d.ts

@@ -1 +1,15 @@
 #!/usr/bin/env node
+import { Command } from 'commander';
+
+/**
+ * Builds the root Commander program and registers implemented command groups.
+ * [SPEC: Architecture v2.0 §23]
+ */
+declare function createProgram(): Command;
+/**
+ * Executes CLI parsing and centralized error rendering/logging.
+ * [SPEC: Architecture v2.0 §23]
+ */
+declare function runCli(argv?: string[]): Promise<void>;
+
+export { createProgram, runCli };