@archme/cli 0.4.0

package/README.md

@@ -0,0 +1,300 @@
+# archme-cli
+
+Multi-subcommand CLI for ArchitectMe. The daemon (original purpose of this
+package) is one subcommand; the others cover code analysis, OAuth login, and
+MCP API key management.
+
+See also:
+- Proposal: `../future-proposals/26-05-12-archme-cli-and-component-anchors.md`
+- Analyze methodology: `./SKILL.md`
+- Daemon commit-driven flow: `../future-proposals/26-04-29-github-app-commit-driven-updates.md`
+- Release runbook (bump → distribute → set floor): `./RELEASE.md`
+
+## Subcommands at a glance
+
+| Subcommand | Purpose |
+|---|---|
+| `archme daemon` | Local job runner — claims `archme_jobs` rows and runs Claude to update architecture |
+| `archme analyze outline\|repo\|diff\|match\|prefetch` | Code analysis primitives (tree-sitter) for keeping architecture in sync with code |
+| `archme login \| logout` | OAuth flow — authenticate this machine against ArchitectMe |
+| `archme keys list\|create\|revoke` | Manage MCP API keys for headless/CI use |
+
+## Installation
+
+```bash
+npm install -g @archme/cli
+```
+
+Requires Node 20+. `keytar` is an *optional* dependency — if its native build
+fails, credentials fall back to `~/.archme/credentials.json` (0600) and
+everything else keeps working.
+
+### Developing on the CLI
+
+From a clone, `npm link` puts the local copy on your `PATH`:
+
+```bash
+cd archme-cli
+npm install
+npm link
+
+which archme   # → <your-npm-prefix>/bin/archme
+```
+
+To uninstall: `cd archme-cli && npm unlink` (or `npm rm -g @archme/cli`).
+
+**One-off / no global install:**
+
+```bash
+npx tsx archme-cli/src/bin.ts <subcommand> [args]
+```
+
+The published package runs `dist/cli.js`, built by `npm run build` (esbuild
+inlines the repo's top-level `shared/` modules, which do not exist inside the
+package). `npm run build:check` builds and then executes the artifact — that is
+what CI and `prepublishOnly` run. When iterating on sources, prefer
+`npx tsx src/bin.ts`, which never consults `dist/`.
+
+### Do you need env config?
+
+| Goal | Env setup |
+|---|---|
+| `archme analyze` (outline / repo / diff / match / prefetch) against local files | **None.** Analyze doesn't talk to Supabase. |
+| `archme login` / `archme daemon` / `archme scan` against **prod** | **None.** Defaults are hardcoded; just `archme login && archme daemon`. |
+| Same commands against **local Supabase** | `ARCHME_ENV=local`. The per-developer OAuth client id is set up once via `npm run setup:local-daemon-oauth` from the repo root (after `supabase start`) — that writes `~/.archme/local-config.json`, which the CLI auto-reads when `ARCHME_ENV=local`. |
+| Self-hosted ArchitectMe deployment | Override individual env vars: `SUPABASE_URL=... SUPABASE_ANON_KEY=... ARCHME_DAEMON_CLIENT_ID=... ARCHME_MCP_BASE_URL=... archme daemon`. |
+
+The CLI never reads `.env` files. Configuration comes from (in order of precedence): explicit env vars > `~/.archme/local-config.json` (when `ARCHME_ENV=local`) > built-in preset for `ARCHME_ENV` (`prod` by default). The full set of overrideable vars is `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `ARCHME_DAEMON_CLIENT_ID`, `ARCHME_MCP_BASE_URL`, plus `CLONE_BASE_DIR` (daemon only, defaults to `~/.archme-job-runner/clones`).
+
+---
+
+## archme daemon
+
+Local daemon that consumes `archme_jobs` rows from Supabase and runs Claude
+on this machine to update the architecture diagram. It is the local worker
+for the GitHub-App → Supabase → laptop-daemon flow
+(see `../future-proposals/26-04-29-github-app-commit-driven-updates.md`).
+
+### How it works
+
+1. Subscribes to Supabase Realtime `INSERT` events on `archme_jobs` filtered
+   to `status = 'pending'`. On startup and reconnect, also runs a sweep over
+   any pending rows.
+2. Atomically claims a row through the `claim_archme_job` RPC using its
+   registered org device id.
+3. Requests short-lived GitHub App installation credentials for the claimed
+   job's repo, then uses the repo under `CLONE_BASE_DIR/<owner>/<repo>` as a
+   shared Git object cache.
+4. Creates a temporary detached worktree at the job's `after_sha`.
+5. Generates a temp `mcp.json` pointing at the archme MCP with
+   `?project=<slug>&branch=<branch>` from the job row.
+6. Shells out to `claude -p <prompt> --mcp-config <path>` with its working
+   directory set to that temporary worktree. Claude reads the architecture,
+   reasons about the diff, and calls `update_architecture`.
+7. Calls the `archme-job-complete` edge function to mark the row
+   `completed` (with the model's summary) or `failed` (with the error) and
+   post the GitHub check run.
+8. Runs a safety sweep every 30 seconds so pending rows are still picked up if
+   Realtime misses an event.
+
+### Setup
+
+```bash
+cd archme-cli
+npm install
+```
+
+That's it for the prod target — config defaults live in `src/config/defaults.ts`. For local-Supabase development, see "Do you need env config?" above.
+
+### Auth
+
+The daemon always uses one-time browser enrollment:
+
+```bash
+cd archme-cli
+npm run enroll
+```
+
+The command prints a code and opens `/agents/pair` in your browser. Pick the
+org this daemon should work for, then confirm the matching code while signed
+in to ArchitectMe. Pairing creates an enabled `agent_devices` row for that
+org. The daemon stores the resulting refresh token, org id, and device id in
+macOS Keychain under service `archme-daemon`, using `SUPABASE_URL` as the
+account. If Keychain is unavailable, it falls back to
+`~/.archme/credentials.json` with mode `0600`.
+
+On every token refresh the daemon persists the rotated refresh token. If the
+stored token is revoked, invalid, or missing org/device identity, startup
+exits with re-enrollment instructions.
+
+The web app must be configured with `VITE_ARCHME_DAEMON_CLIENT_ID` matching
+the pre-registered Supabase OAuth client for the daemon. That client needs
+`<app-origin>/agents/pair/callback` as an allowed redirect URI.
+
+For local Supabase, run this from the repo root after `supabase start`:
+
+```bash
+npm run setup:local-daemon-oauth
+```
+
+That creates or updates the local daemon OAuth client and writes:
+
+- `.env.local` for the Vite app (so `/agents/pair` knows the client id)
+- `~/.archme/local-config.json` for the CLI (auto-loaded when `ARCHME_ENV=local`)
+
+After that:
+
+```bash
+ARCHME_ENV=local archme login
+ARCHME_ENV=local archme daemon
+```
+
+To complete the browser step locally, the local app still needs a normal
+ArchitectMe web session. If your browser is not already signed in, configure
+the local Supabase sign-in provider before starting Supabase.
+
+### Run
+
+```bash
+npm run dev
+```
+
+Logs prefixed with `[<job-id>]` per job.
+
+### Enrollment Verification
+
+```bash
+cd archme-cli
+npm run enroll
+# confirm the browser prompt
+npm run dev
+```
+
+On macOS, the credential should be visible with:
+
+```bash
+security find-generic-password -s archme-daemon -a "$SUPABASE_URL"
+```
+
+If Keychain was unavailable, check `~/.archme/credentials.json` exists with
+mode `0600`.
+
+### Job Verification
+
+With the daemon running, enqueue a job for a watched repo/project. The watched
+repo must have a valid GitHub App `installation_id`; the daemon uses that
+installation to mint short-lived HTTPS clone/fetch credentials.
+
+```sql
+select enqueue_archme_job(
+  '<watched_repo_id>',
+  '<org_id>',
+  '<user_id>',
+  '<project_id>',
+  '<repo_owner>',
+  '<repo_name>',
+  '<repo_branch>',
+  '<archme_branch>',
+  '<before_sha>',
+  '<after_sha>',
+  false,
+  null
+);
+```
+
+Within one safety sweep the daemon should claim the row, set
+`claimed_by_device_id`, fetch the repo without persisting tokenized remotes,
+run Claude, call the completion edge function, and mark the row
+`completed`. Open the project in the web app on the same branch; the diagram
+should reflect the change, or the row's `result.summary` should explain why
+no update was needed.
+
+---
+
+## archme analyze
+
+Code analysis primitives that power keeping ArchitectMe architecture in sync
+with actual source code. Parses files with
+[web-tree-sitter](https://github.com/tree-sitter/tree-sitter/tree/master/lib/binding_web)
+and emits structured JSON that the MCP server and agents consume.
+
+Grammars are fetched on demand to `~/.archme/tools/grammars/` (override with
+`ARCHME_TOOLS_DIR`). No build step required — grammars are downloaded the
+first time a language is encountered.
+
+**Supported languages:** TypeScript, TSX, JavaScript, Python, Go, Java, Ruby,
+Rust, Swift, Kotlin.
+
+For the full agent methodology (how to run a repo scan, match anchors, and
+write architecture updates) see `./SKILL.md`.
+
+### Commands
+
+```
+archme analyze outline <file>        Emit a JSON symbol outline for a single file
+archme analyze repo                  Walk the repo and outline every supported file
+archme analyze diff <range>          Outline only files changed in a git range (e.g. HEAD~3..HEAD)
+archme analyze match <anchor-spec>   Match anchor specs (JSON file) against current symbol outlines
+archme analyze prefetch [langs...]   Pre-download grammars so first analysis is instant
+```
+
+### Example
+
+```bash
+archme analyze outline src/api/upload.ts
+```
+
+Output is a JSON envelope:
+
+```json
+{
+  "file": "src/api/upload.ts",
+  "lang": "typescript",
+  "symbols": [
+    { "kind": "function", "name": "handleUpload", "line": 12, "exported": true },
+    { "kind": "class",    "name": "UploadService", "line": 34, "exported": true }
+  ]
+}
+```
+
+`archme analyze repo` emits one envelope per file (newline-delimited JSON) and
+is the starting point for a full codebase scan.
+
+`archme analyze match <anchor-spec.json>` takes a JSON file describing named
+anchors (component → expected symbols) and reports which anchors still resolve
+and which have drifted, enabling the MCP server to flag stale architecture
+nodes.
+
+---
+
+## Auth & keys
+
+### archme login / logout
+
+```bash
+archme login    # Opens browser OAuth flow; stores token in macOS Keychain
+                # (falls back to ~/.archme/credentials.json with mode 0600)
+archme logout   # Clears stored credentials
+```
+
+OAuth flow uses the same Supabase OAuth 2.1 / PKCE mechanism as the daemon
+enrollment. Intended for interactive use; the daemon uses its own enrollment
+flow (`npm run enroll`) instead.
+
+### archme keys list | create | revoke
+
+```bash
+archme keys list             # List MCP API keys for the authenticated user
+archme keys create <name>    # Mint a new am_* key for CI / headless use
+archme keys revoke <key-id>  # Revoke a key
+```
+
+> **Currently stub** — these commands print placeholder messages. Full
+> implementation (Unkey integration, org-scoped key listing) is pending.
+
+---
+
+## Privacy / sync
+
+This directory is excluded from the work-repo sync
+(`scripts/sync-to-on-prem.sh`).

package/SKILL.md

@@ -0,0 +1,243 @@
+# archme — Agent Skill
+
+This skill teaches coding agents how to keep an archme architecture
+in sync with its codebase. It's bundled with the `@archme/cli` package.
+
+## Purpose
+
+archme is the source of truth for *architecture intent* — components,
+connections, user stories, decisions. The code is the source of truth
+for *what actually exists*. Your job is to keep the two in sync,
+using anchors as the binding between them.
+
+archme stores anchors. You produce and verify them.
+
+## What you have
+
+Two surfaces:
+
+- **archme MCP tools** (`read_architecture`, `update_architecture`,
+  `find_components_for_paths`, `get_component`, ...) — read and write
+  the architecture. Your only path to archme's data.
+
+- **`@archme/cli`** (the package shipping this skill) — local code
+  analysis. Commands:
+  - `archme analyze outline <file>` — symbols in one file (preferred for anchoring)
+  - `archme analyze repo` — bulk outline of the whole repo (JSONL, large output — prefer outline for targeted work)
+  - `archme analyze diff <range>` — structured diff of a git range
+  - `archme analyze match <anchor-spec>` — resolve anchors against current code
+  - `archme analyze prefetch` — grammar fetch for CI / airgap
+
+CLI output is always JSON. Parse it; don't grep it.
+
+## When to use what
+
+| Task | Use |
+|---|---|
+| "What files does this component live in?" | Read architecture; walk anchors |
+| "What component owns this file?" | `find_components_for_paths` |
+| "What symbols are in this file?" | `archme analyze outline` |
+| "What does this commit change?" | `archme analyze diff <range>` |
+| "Does this anchor still resolve?" | `archme analyze match` |
+| "Is the architecture missing components?" | `find_components_for_paths` on representative files; outline gaps with `archme analyze outline` |
+| "Add or update a component" | `update_architecture` MCP tool |
+
+## Anchor kinds — when to pick which
+
+An anchor is `{id, kind, source, confidence, created_at, ...}` plus
+kind-specific fields. Pick the kind based on how the component lives
+in code:
+
+- **`file`** — component lives in exactly one file
+  `{kind: "file", path: "src/api/upload.ts"}`
+
+- **`directory`** — component is a self-contained module / subtree
+  `{kind: "directory", path: "src/workers/email"}`
+
+- **`glob`** — component is a fuzzy slice across files
+  `{kind: "glob", pattern: "src/**/*.controller.ts"}`
+
+- **`symbol`** — component is a specific function or class
+  `{kind: "symbol", path: "src/api/upload.ts", name: "UploadHandler", symbolKind: "class"}`
+
+For components without code (external services, vendors, conceptual
+"Cache Layer" not yet built), use `unanchored: true` instead of
+anchors. Don't fabricate anchors to anchor something that has no code.
+
+A component can carry **multiple** anchors of mixed kinds — e.g.,
+a directory anchor for helpers plus a symbol anchor for the primary
+handler.
+
+## Confidence
+
+Set per anchor based on how the CLI verified it:
+
+- **1.0** — human-edited (you didn't produce this; preserve it)
+- **0.8** — tree-sitter parse confirmed (`analyze` returned tier 2)
+- **0.7** — glob anchor matching ≥1 file (no parse, but coverage exists)
+- **0.5** — degraded (`analyze match` returned `degraded`)
+- **0.3** — speculative (you couldn't fully verify)
+
+Server doesn't enforce these — they're conventions. Downstream
+consumers filter on them.
+
+## Workflows
+
+### Workflow: brownfield first scan
+
+```
+1. Read the current architecture (empty for a new project)
+2. Identify capabilities via explorers (code structure, git history, docs)
+3. For each component, run archme analyze outline on its key files
+   to get the symbol structure. Pick anchors from the outline.
+4. For external/conceptual components, set unanchored: true.
+5. Run archme analyze match to verify all anchors resolve.
+6. Submit components via update_architecture, including anchors.
+7. Sample 5-10 code files; call find_components_for_paths for each.
+   Every file should resolve to ≥1 component.
+8. Submit stories, connections, requirements as usual.
+```
+
+### Story granularity
+
+Before you mint a user story, decide it deserves to be one. A story should be
+**foundational — a full, meaningful user flow with its own goal**, not a fragment
+of one. A single conditional, edge case, error/redirect path, or robustness rule
+scoped to one existing surface is never a story of its own (smell test: one
+`alt`/`else` branch, touches a single component, nothing else references it).
+Instead: if it meaningfully changes how the flow behaves, fold it into the owning
+story's `sequence` as a proportional branch or step (`alt`/`else`, `break`); if
+it's a bug fix or hardening the existing sequence already depicts correctly at
+its altitude, change nothing — the story is already right. If that surface has no
+owning story yet, create the surface/flow-level story — a full flow with the rule
+as one branch of its sequence — never a story for the rule alone. This is the
+same gate the scan and daemon-diff prompts enforce verbatim (canonical source:
+`shared/storyGranularity.ts`).
+
+### Bugs you happen to notice
+
+**Don't go hunting for bugs — stay on the architecture task.** But if an obvious,
+real bug in the user's code surfaces while you read it (a null-deref, a missing
+`await`, an unhandled error path, a broken invariant), don't ignore it and don't
+fix it. The flow is passive and orchestrator-gated: a code-reading sub-agent
+**surfaces** a suspect back to the orchestrator (`Possible bug: <what>
+(file:line)` in its findings) rather than filing it; the orchestrator
+**dispatches one bug-validation sub-agent** that confirms each suspect against
+the code and **files the confirmed ones itself via `create_proposal`** (it reads
+code + writes a proposal, exactly like a build sub-agent, and never touches the
+user's code). Logging reuses the
+proposals surface, not a bespoke mechanism: a prose-only proposal (empty graph
+delta, `body` naming what's wrong, where by file:line/symbol, and why) under the
+project's standing **"Bugs" folder**, `stage: 'backlog'` so it parks until a human
+triages. The daemon injects the Bugs folder id for you; a manual scan
+finds-or-creates it (`search_proposals({ kind: 'folder', text: 'Bugs' })`, else
+`create_proposal({ kind: 'folder', title: 'Bugs' })`). Dedup by searching the
+folder by title — the same standing bug is re-noticed on every commit. Keep the
+bar high (a few per run at most, code-review-worthy only); logging a bug is
+**orthogonal** to your architecture task — still call
+`update_architecture`/`report_no_change` as normal. Canonical source:
+`shared/bugReport.ts`.
+
+### Workflow: ambient editing
+
+The user is editing `src/api/upload.ts`. You should:
+
+```
+1. Call find_components_for_paths with ["src/api/upload.ts"]
+2. Read the matching component(s) via get_component
+3. If the edit changes architectural shape (new dependency, removed
+   feature, rename), propose an update_architecture call to the user
+4. Otherwise: no action — the architecture is still valid
+```
+
+### Workflow: reviewing a diff
+
+The user wants to know what a PR/commit range affects:
+
+```
+1. Run archme analyze diff <before>..<after>
+2. Collect changed file paths from the diff output
+3. Call find_components_for_paths with those paths
+4. For each affected component, decide if the architecture needs
+   updating (new edges, removed parts, etc.)
+5. If yes: update_architecture
+```
+
+### Workflow: orphan recovery
+
+`archme analyze match` returned `orphan` for an anchor:
+
+```
+- Run archme analyze outline on the file the anchor points at
+  (if file kind: check if the path moved)
+- Run git log -- <path> to see history (renamed? deleted?)
+- Decide:
+  (a) Anchor is stale — code moved. Update the anchor's path or
+      replace with a different kind.
+  (b) Component should be removed — the code it modeled is gone.
+      Use update_architecture's componentUpdates.remove.
+  (c) Component still exists but in a different shape — re-anchor
+      via update_architecture.
+- Submit the fix
+```
+
+### Workflow: adding a new component mid-feature
+
+The user is implementing a new subsystem (e.g., adding a new worker):
+
+```
+1. Outline the new files (archme analyze outline)
+2. Decide the component's anchor kind based on file layout
+3. update_architecture with the new component + anchors
+4. Update parent component's connections if needed
+5. Optionally add a story for the new capability
+```
+
+## Trust model
+
+You are the agent of correctness:
+
+- The server **validates shape** (well-formed anchors, paths without
+  traversal, confidence in [0,1], etc.). It cannot validate semantic
+  correctness because it has no code access.
+- **You verify code existence** via `archme analyze match` before
+  submitting. Server trust depends on this.
+- The server returns warnings (e.g., `unanchored:true` with non-empty
+  anchors); they don't block writes but indicate something to clean up.
+
+## What NOT to do
+
+- **Don't fabricate anchors.** If you can't verify it via the CLI,
+  don't submit it with high confidence.
+- **Don't submit anchors with confidence > 0.8 without `analyze match`.**
+  You have a deterministic verifier; use it.
+- **Don't anchor everything as `symbol`.** Many components are not
+  single symbols — they're directories, globs, or whole files.
+- **Don't use line ranges as anchors.** Anchors are stable across
+  edits; line numbers rot on the first change.
+- **Don't try to derive cross-file references.** v1's CLI doesn't
+  do call graphs. If you need to know callers, grep for the symbol
+  name — but be explicit that it's a heuristic.
+- **Don't update `unanchored: true` components with anchors.**
+  Either it has anchors (then drop `unanchored`) or it doesn't (keep
+  `unanchored: true`).
+
+## Report friction
+
+If any part of working with archme is confusing, broken, or harder than it
+should be — a tool error you can't act on, a description that doesn't match the
+behavior, a validation rule that rejects something valid, a missing capability,
+or a step that just felt frustrating — call the `report_feedback` MCP tool to
+leave a short note in the moment: `report_feedback({ area, severity, summary,
+detail? })`, where `severity` is `frustration` (worked around it),
+`not_working` (broken/blocking), or `suggestion` (an idea). It's a welcome,
+low-friction signal, not an error — don't let the signal get lost. This is
+meta-feedback about archme's own tooling, NOT a place to log bugs in the user's
+own code.
+
+## Where to look
+
+- Spec (this skill's source of truth):
+  `future-proposals/26-05-12-archme-cli-and-component-anchors.md`
+- Tool descriptions live in the MCP server (`supabase/functions/mcp/index.ts`).
+- CLI source: `archme-cli/src/analyze/`.