@archme/cli 0.4.1 → 0.4.2

package/README.md

@@ -1,308 +1,87 @@
-# archme-cli
+# @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
+Command-line companion for [ArchMe](https://archme.io) — maps your codebase into
+a living architecture diagram and keeps it current as you commit.
 
 ```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
-
-**For iterating on sources, use tsx directly** — it always runs current code:
-
-```bash
-cd archme-cli
-npm install
-npx tsx src/bin.ts <subcommand> [args]
-```
-
-`npm link` also works, but note the published `bin` is the *built bundle*
-(`dist/cli.js`), so linking without building leaves a dangling symlink, and a
-stale `dist/` silently shadows your edits. Build first, and rebuild after
-changes:
-
-```bash
-npm install
-npm run build     # required — bin points at dist/cli.js
-npm link
-
-which archme      # → <your-npm-prefix>/bin/archme
-```
-
-To uninstall: `cd archme-cli && npm unlink` (or `npm rm -g @archme/cli`).
-
-`npm run build` uses esbuild to inline 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.
-
-`bin/archme` (the dev shim, used by an unbuilt clone and by service units when
-`dist/` is absent) runs `src/bin.ts` via tsx. It must point at `bin.ts`, not
-`cli.ts` — `cli.ts` exports `main` without invoking it, so pointing at it makes
-every command a silent exit 0. `src/binShim.test.ts` pins this by executing it.
-
-### 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:
+Requires Node 20+ and [Claude Code](https://claude.com/claude-code) installed and
+signed in — scans and updates run on **your** Claude subscription, on your
+machine. Your code is never sent to ArchMe's servers; only the resulting
+architecture is.
 
-- `.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`)
+## 1. Scan your repo
 
-After that:
+`cd` into the repository you want mapped, then:
 
 ```bash
-ARCHME_ENV=local archme login
-ARCHME_ENV=local archme daemon
+archme init
 ```
 
-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.
+This signs you in, creates a project named after the repo, writes the agent
+config (`.mcp.json`, a `CLAUDE.md` block, the architecture skill), tells you
+what the scan will cost before spending it, and runs the scan. It prints a link
+to your board — components appear on it as they're written.
 
-### Run
+## 2. Keep it up to date
 
-```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
+`archme init` also starts watching the repo, so every push queues an architecture
+update — but nothing processes that queue until you run the agent:
 
 ```bash
-archme analyze outline src/api/upload.ts
+archme daemon start
 ```
 
-Output is a JSON envelope:
+Installs the daemon as a background service (launchd/systemd), enables it at
+login, and starts it. Run it on a machine that stays on. Each update counts
+tokens against your Claude account, the same way the scan did.
 
-```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.
+Watching a repo needs the ArchMe GitHub App installed on it; `archme init` tells
+you if that step is still missing. Not up for hosting the agent yourself? Get in
+touch at [archme.io](https://archme.io) and we'll run it for you.
 
 ---
 
-## Auth & keys
+## Other commands
 
-### 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`).
+| Command | Purpose |
+|---|---|
+| `archme init [repo-path]` | Guided setup + scan (see above); `--force` re-scans |
+| `archme scan <repo-path>` | Low-level single-pass scan into an explicit `--project` / `--branch` |
+| `archme daemon <sub>` | `start` · `stop` · `restart` · `status` · `logs` · `enable` · `disable` · `install` · `uninstall` · `run` |
+| `archme analyze <sub>` | Tree-sitter code analysis: `outline` · `repo` · `diff` · `match` · `prefetch` |
+| `archme login` / `archme logout` | Authenticate this machine against ArchMe |
+
+Every command takes `--help`. Useful flags:
+
+- `archme init --skip-scan` — wire up the repo without scanning; `--force`
+  re-scans a project that already has an architecture; `--yes` runs unattended
+  (scans are interactive by default, so you can steer them as they go).
+- `archme daemon status` — is it installed, running, and signed in?
+  `archme daemon logs -f` follows the log.
+- `archme analyze outline <file>` — JSON symbol outline for one file; `repo`
+  outlines everything, `diff <range>` only what a git range touched. Supports
+  TypeScript, TSX, JavaScript, Python, Go, Java, Ruby, Rust, Swift, and Kotlin.
+  Grammars download on first use to `~/.archme/tools/grammars/`.
+
+### Notes
+
+- **Credentials**: stored in the macOS Keychain when available, otherwise
+  `~/.archme/credentials.json` (mode `0600`). `keytar` is an *optional*
+  dependency — if its native build fails, everything still works via the file
+  store.
+- **Configuration**: no env setup needed against archme.io; the CLI never reads
+  `.env` files. Self-hosted deployments can override `SUPABASE_URL`,
+  `SUPABASE_ANON_KEY`, `ARCHME_DAEMON_CLIENT_ID`, `ARCHME_MCP_BASE_URL`, and
+  `CLONE_BASE_DIR` (daemon only, defaults to
+  `~/.archme-job-runner/clones`).
+- **Agent methodology** — how an agent scans a repo, anchors components to code,
+  and writes architecture updates — is in the `SKILL.md` bundled with this
+  package. `archme init` installs it into your repo for you.
+
+## License
+
+Proprietary — see the bundled `LICENSE`. Use is granted against the archme.io
+service; bundled open-source components keep their own terms.

package/SKILL.md

@@ -237,7 +237,6 @@ 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/`.
+- Every archme MCP tool documents its own arguments and constraints — list the
+  tools and read the description before guessing at a payload shape.
+- `archme <command> --help` documents the CLI side.

package/dist/cli.js

@@ -18312,18 +18312,19 @@ async function main(argv) {
   }
 }
 function printHelp() {
-  console.log(`archme \u2014 architecture-aware code analysis and daemon
-
-Usage:
-  archme init [repo-path]              Guided first-time setup (login, project,
-                                       agent config, scan)
-  archme daemon <subcommand>           Manage the local daemon as a service
-                                       (start|stop|status|logs|restart|enable|
-                                        disable|install|uninstall|run)
-  archme analyze <subcommand>          Code analysis (outline|repo|diff|match|prefetch)
-  archme scan <repo-path>              Run a single-pass brownfield scan
-  archme login | logout                Authenticate with archme
-  archme keys list|create|revoke       Manage MCP API keys
+  console.log(`archme \u2014 map your codebase into a living architecture diagram
+
+Start here:
+  cd <your-repo> && archme init       Set up this repo and scan it
+  archme daemon start                 Run the agent that keeps it current
+
+Other commands:
+  archme daemon <subcommand>          Manage the local daemon as a service
+                                      (start|stop|status|logs|restart|enable|
+                                       disable|install|uninstall|run)
+  archme analyze <subcommand>         Code analysis (outline|repo|diff|match|prefetch)
+  archme scan <repo-path>             Single-pass scan into an explicit project/branch
+  archme login | logout               Authenticate with archme
 
 Run 'archme init --help', 'archme daemon --help', 'archme analyze --help', or
 'archme scan --help' for subcommand help.`);

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "@archme/cli",
-  "version": "0.4.1",
-  "description": "archme command-line interface: daemon, analyze, auth, key management",
+  "version": "0.4.2",
+  "description": "Map your codebase into a living architecture diagram: run `archme init` in a repo to scan it, `archme daemon start` to keep it current on every commit.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://archme.io",
+  "bugs": {
+    "url": "https://archme.io"
+  },
+  "keywords": [
+    "architecture",
+    "architecture-diagram",
+    "codebase-map",
+    "mcp",
+    "claude-code",
+    "coding-agents",
+    "tree-sitter",
+    "static-analysis"
+  ],
   "bin": {
     "archme": "dist/cli.js"
   },