@archme/cli 0.4.0 → 0.4.2

package/LICENSE

@@ -0,0 +1,64 @@
+ArchitectMe CLI License
+
+Copyright (c) 2026 ArchitectMe. All rights reserved.
+
+This software (the "Software") is proprietary and is licensed, not sold.
+
+1. GRANT OF LICENSE
+
+   Subject to the terms below, you are granted a non-exclusive,
+   non-transferable, revocable license to install and use the Software solely
+   to interact with the ArchitectMe service operated at archme.io (the
+   "Service"), in connection with an active ArchitectMe account.
+
+   Use of the Software for any other purpose — including use with any service,
+   endpoint, or system other than the Service — is not licensed.
+
+2. RESTRICTIONS
+
+   You may not:
+
+   (a) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
+       Software or copies of it;
+   (b) modify, adapt, translate, or create derivative works of the Software;
+   (c) reverse engineer, decompile, or disassemble the Software, or otherwise
+       attempt to derive its source code, except to the extent that such
+       activity is expressly permitted by applicable law notwithstanding this
+       restriction;
+   (d) remove, obscure, or alter any proprietary notices contained in the
+       Software; or
+   (e) use the Software to build, train, or improve a competing product or
+       service.
+
+3. RESERVATION OF RIGHTS
+
+   All right, title, and interest in and to the Software, including all
+   intellectual property rights, remain with ArchitectMe. No rights are granted
+   except as expressly set out in this license.
+
+4. TERMINATION
+
+   This license terminates automatically if you breach any of its terms, and
+   may be terminated by ArchitectMe at any time. On termination you must cease
+   all use of the Software and destroy all copies in your possession.
+
+5. NO WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL ARCHITECTME BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+   FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER
+   DEALINGS IN THE SOFTWARE.
+
+7. THIRD-PARTY COMPONENTS
+
+   The Software incorporates third-party open-source components, which remain
+   subject to their own licenses. Nothing in this license limits your rights
+   under those licenses with respect to those components.
+
+For licensing enquiries, contact archme.io.

package/README.md

@@ -1,300 +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
-
-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.
+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.
 
-### Auth
+## 1. Scan your repo
 
-The daemon always uses one-time browser enrollment:
+`cd` into the repository you want mapped, then:
 
 ```bash
-cd archme-cli
-npm run enroll
+archme init
 ```
 
-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`.
+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.
 
-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.
+## 2. Keep it up to date
 
-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`:
+`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
-npm run setup:local-daemon-oauth
+archme daemon start
 ```
 
-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`)
+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.
 
-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.
+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.
 
 ---
 
-## 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
-```
+## Other commands
 
-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`).
+| 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.