@cabane/cli 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# cabane CLI
+
+Run a self-hosted Cabane on your own machine — **no docker, no repo**. `@cabane/cli`
+is a thin public supervisor/installer (no product source): it fetches the built
+server artifact, runs the whole stack, and keeps it updated.
+
+```sh
+npm i -g @cabane/cli                 # install the CLI (bin: `cabane`)
+cabane init                          # first-run wizard: data location, port, executor key
+cabane install --token cabdist_…     # fetch + sha256-verify + unpack the gated server artifact
+cabane up --daemon                   # supervise Postgres + server + house bridge (no flags — uses your config)
+# open http://localhost:3000, sign up
+cabane setup-agent                   # register the house bridge + put your agent on it (prompts for a cab_… token)
+```
+
+`cabane init` is the interactive first-run wizard: it asks where your data lives
+(and **shows the resolved paths** — `data/storage` for uploads, `data/pg` for the
+database), the port, an optional public URL, and your executor credential entered
+**password-style**. It persists everything to config, so a later `cabane up` needs
+no flags. Re-run it any time to reconfigure. You can still skip it and pass flags
+directly if you prefer.
+
+Every secret is entered at a hidden prompt, never on the command line — the
+`cabdist_…` distribution grant (`cabane install`), the executor key (`cabane init`
+/ `cabane set-env KEY`), and the `cab_…` access token (`cabane setup-agent`) — so
+none of them land in your shell history or on screen.
+
+The house bridge runs whatever executor you have (Claude Code, or another
+supported harness) — see [Credentials](#credentials) for making its login
+reachable. On a Claude subscription there's nothing to do; on API-key billing,
+export or persist your key.
+
+## What it supervises
+
+`cabane up` runs three children in order, with a clean SIGTERM teardown:
+
+1. **Embedded Postgres** — the `embedded-postgres` binaries (pinned pg 16.14) run
+   as a child on a local off-5432 port; data in `<CABANE_HOME>/data/pg`. No system
+   Postgres, no download at runtime (the binaries ship in the npm package).
+2. **The server** — the artifact's single-process API+SPA (`server.js`, filesystem
+   storage, the bundled SPA served via `WEB_DIST`), env composed automatically
+   (`NODE_ENV=production`, `http://localhost:<port>`, generated-once vision
+   secret). Migrations apply on boot.
+3. **The house bridge** — bundled inside the server artifact from the same commit
+   (`<appDir>/bridge`), run as the house executor so your agents answer, always in
+   version lockstep with the server. Configured by `cabane setup-agent`.
+
+## Layout (`~/.cabane-selfhost/`)
+
+```
+config.json          the CLI's config (token, port, versions, house ids)
+app/<version>/       each installed artifact tree
+data/pg/             Postgres data dir
+data/storage/        file bytes (filesystem storage backend)
+bridge/              the house bridge's isolated HOME
+logs/                server.log · bridge.log
+run/                 supervisor.pid · state.json
+```
+
+The root defaults to **`~/.cabane-selfhost/`** — deliberately _not_ `~/.cabane`,
+which a standalone `@cabane/bridge` user bridge already keys off, so a self-host
+install can never clobber a bridge's device pairing on a shared box. Override the
+whole root with the **`CABANE_HOME`** env var (the multi-instance lever); a
+pre-existing self-host install still living at `~/.cabane` is adopted in place, so
+no data moves. A `cabane install` / `set-env` pointed (via `CABANE_HOME`) at a
+directory that holds a bridge config refuses rather than overwrite it.
+
+**Relocating just the data.** `cabane init` can point the **data** leg (pg +
+storage) at any path you choose while `config.json` + `app/` stay under the root —
+handy for putting bulky uploads on a bigger disk. The default is still
+`<root>/data`; the chosen location persists in config, so `up` finds it with no
+env var or flag.
+
+**Your data is safe across upgrades.** `data/` (pg + storage) sits apart from the
+versioned `app/<version>/` tree, so `cabane install`, `cabane update`, and a
+same-version reinstall only ever touch the app tree — your account, files, and
+conversations persist untouched. `cabane status` prints the `home` + `data`
+paths so you can see it.
+
+## Commands
+
+| Command              | What it does                                                                                  |
+| -------------------- | --------------------------------------------------------------------------------------------- |
+| `cabane init`        | interactive first-run wizard: data location, port, public URL, executor credential            |
+| `cabane install`     | fetch (token → gated artifact) or `--from` a local tarball; unpack + `npm install --omit=dev` |
+| `cabane up`          | start + supervise the stack (`--daemon` for background)                                       |
+| `cabane setup-agent` | after signup: register the house bridge, assign your agent                                    |
+| `cabane update`      | install a newer published artifact (keeps N-1 for rollback)                                   |
+| `cabane set-env`     | persist `KEY=VALUE` credentials forwarded to the house bridge (`--list` / `--unset`)          |
+| `cabane down`        | stop a running stack                                                                          |
+| `cabane status`      | what's installed + running                                                                    |
+| `cabane logs`        | tail the server + bridge logs                                                                 |
+| `cabane doctor`      | preflight: diagnose common self-host failure classes (runs with the stack down)               |
+
+## Troubleshooting — `cabane doctor`
+
+When something won't start, run `cabane doctor` **first**. It's a standalone
+preflight (no server needed — it's what you reach for precisely when things are
+broken) that checks the common self-host failure classes and prints a legible
+pass/fail/warn report, each with a one-line fix, then exits non-zero if any hard
+check fails. It's strictly local — nothing phones home. v1 checks:
+
+- **Node** ≥ the required version.
+- **Executor** — Claude Code present on PATH, and a credential reachable by the
+  house bridge (subscription login, an `ANTHROPIC_*` env/persisted key, or a
+  managed-policy that would refuse your key — named specifically). Reachability
+  only; it never calls the provider.
+- **Port** free (or held by a running cabane).
+- **Embedded Postgres** — platform binaries present + data dir healthy.
+- **Storage root** — writable, and where it is.
+- **Bridge/server version** — the bridge bundled in the installed artifact
+  matches the server it ships with (a version skew from a mismatched install is
+  flagged).
+- **Disk space** for the data dir.
+- **macOS Gatekeeper** — quarantine on the Postgres binaries (macOS only).
+
+## Requirements
+
+- **Node ≥ 22.**
+- **An executor the house bridge can run** — e.g. Claude Code, or another
+  supported harness — with its credentials reachable (see [Credentials](#credentials)).
+  Cabane ships no model of its own and requires no particular provider; the house
+  bridge runs whatever executor you have.
+
+## Credentials
+
+The house bridge inherits the environment `cabane up` runs under, so your
+executor's credentials reach it — no provider is special-cased:
+
+- **Claude subscription** — a logged-in Claude Code just works; its OAuth creds
+  live on disk under `~/.claude` (pointed at by `CLAUDE_CONFIG_DIR`), so there's
+  nothing to export.
+- **API-key billing (or any executor keyed by an env var)** — the key lives in
+  your environment, not on disk, so make it reachable one of two ways:
+
+  ```sh
+  # the wizard — `cabane init` prompts for it password-style and persists it
+  cabane init
+
+  # persisted, on its own — save once; every future `up` (fresh shell, reboot) picks it up.
+  # A bare KEY prompts for the value (hidden); `KEY=VALUE` still works for scripting.
+  cabane set-env ANTHROPIC_API_KEY
+  cabane up --daemon
+
+  # ambient — export in the shell you launch from
+  export ANTHROPIC_API_KEY=sk-ant-…
+  cabane up --daemon
+  ```
+
+`set-env` stores generic `KEY=VALUE` pairs in `<CABANE_HOME>/config.json` and composes
+them into the bridge on every `up`, so it serves any executor's credentials (a
+proxy `ANTHROPIC_BASE_URL`, an `ANTHROPIC_AUTH_TOKEN`, a future harness's key) —
+not just Anthropic. A bare `cabane set-env KEY` (no `=value`) prompts for the value
+without echoing, so a secret never lands on the command line. Inspect with `cabane
+set-env --list` (values masked), remove with `cabane set-env --unset KEY`. A live shell export takes precedence over a
+persisted value; the house-class isolation vars (`HOME`, `CLAUDE_CONFIG_DIR`,
+class) always win over both. Apply a change to an already-running stack with
+`cabane down && cabane up`.
+
+## Notes
+
+- **macOS Gatekeeper** on the unsigned Postgres binaries is a known open question
+  (CT453) — documented, not yet solved. If pg fails to exec on first run, clear
+  the quarantine xattr and retry.
+- **Before it's published to npm**, install the CLI from a local tarball: `pnpm
+--filter @cabane/cli build && cd apps/cli && npm pack`, then `npm i -g
+./cabane-cli-<version>.tgz`. You can also install the _server_ artifact from a
+  local build with `cabane install --from <artifact.tgz>` instead of a token.
+
+## Publishing (maintainers)
+
+The package is publish-ready and source-free — it carries no product source, only
+the bundled supervisor. Verify the tarball first, then publish:
+
+```sh
+pnpm cli:publish:dry   # builds, then `npm publish --dry-run` — lists only dist/ + README
+pnpm cli:publish       # builds (prepublishOnly) + `npm publish --access public`
+```
+
+`cli:publish:dry` should list exactly `dist/cli.js`, `package.json`, and
+`README.md` — no `.ts`. Bump `version` in `apps/cli/package.json` before a real
+publish (npm refuses to overwrite a published version).