@miakapp/cli 4.0.0-alpha.0 → 4.0.0-alpha.10

package/README.md

@@ -1,6 +1,6 @@
 # @miakapp/cli
 
-Build, validate, publish and roll back one Miakapp home component.
+Pair, build, validate, publish and roll back independent Miakapp house applications.
 
 The CLI is the deployment mechanism, not the source of truth. **Git belongs to
 you**: this tool never commits, never rewrites sources it did not generate and
@@ -12,11 +12,60 @@ stable exit code and one stable failure kind, and `--json` prints exactly one
 object on stdout.
 
 ```bash
-bunx @miakapp/cli init --home my-home --control-plane https://control.miakapp.app
-bunx @miakapp/cli check
-bunx @miakapp/cli publish --expected-generation 0
+printf '%s\n' "$CODE" | bunx @miakapp/cli pair --issuer "$MIAKAPP_ISSUER"
+bunx @miakapp/cli init --starter app              # manifest + app to edit; home and issuer from the context
+bun run build && bun run check                    # after the inventory and adapting app/main.ts
+bunx @miakapp/cli publish
+bunx @miakapp/cli status                          # verify what is live
 ```
 
+Use the exact issuer command shown by your deployment's `/pair` page; do not
+guess a staging issuer. Open and verify the returned `home_url` as a resident
+before handing it over.
+
+## The app starter
+
+`miakapp init --starter app` writes, beside `miakapp.yaml`, everything needed to
+build a whole-house application with nothing but this package and Bun:
+
+| File | |
+| --- | --- |
+| `app/main.ts` | the interface to edit: shows what the home shares, grouped, with stale and empty states |
+| `app/miakapp.ts` | the bridge to `window.miakapp` — byte for byte the `@miakapp/app` SDK source, which is not on npm yet |
+| `app/theme.ts` | Miakapp design tokens, themes (Minuit in dark mode, Lumière in light) and recipes, with Manrope embedded |
+| `package.json` | `build` (Bun IIFE to the manifest's artifact), `typecheck`, `check`; pins this CLI and TypeScript |
+| `tsconfig.json` | strict TypeScript for `app/` |
+| `app/README.md` | the loop, the prerequisites and what to do before publishing |
+
+Prerequisites: Node.js ≥ 22.9 for the CLI, Bun ≥ 1.2.23 for `bun run build`
+(TypeScript, from `bun install`, only for `typecheck`). The starter accepts
+`--artifact` (a plain relative `.js` path), `--release`, `--home`,
+`--control-plane` and `--context`; it cannot be combined with
+`--kind component`.
+
+It never overwrites anything: every target is checked first, and if any one
+exists the command fails with exit 2 and writes nothing. Without `--starter`,
+`init` writes `miakapp.yaml` alone, as before.
+
+The starter invents no value and offers no control. `app.requires` starts
+empty, so a fresh build shows only an empty state: inventory the house, declare
+the paths and calls, give them resident-facing names and a real layout, then
+publish.
+
+## Design
+
+`miakapp docs design` prints a short design guide and the directory of the
+files it describes: `tokens.css` (four themes: Minuit, Lumière, Miel, Craie),
+`components.css` (glass, device tile, scene, switch, level slider, stale
+banner), `fonts.css` (Manrope as a `data:` URL, since the frame has no network)
+and `gallery.html`, example screens to open in a browser. They are a starting
+point, not a framework: copy, change or ignore them.
+
+Maintainers: the generated files (`fonts.css`, `gallery.html`, the starter's
+`app/theme.ts`) come from `packages/cli/design/`; run `bun design/build.ts` in
+`packages/cli` after editing `tokens.css`, `components.css` or the gallery
+template. A test fails when they drift.
+
 ## The project file
 
 `miakapp.yaml` sits at the root of your repository:
@@ -24,24 +73,25 @@ bunx @miakapp/cli publish --expected-generation 0
 ```yaml
 schema: miakapp.project/1
 home: my-home
-control_plane: https://control.miakapp.app
+control_plane: https://control.example.test
 
-component:
-  artifact: dist/component.js
-  release: 2026-09-13.1
+app:
+  artifact: dist/app.js
+  release: 2026-10-03.1
   requires:
     state_read:
       - climate.living_room.temperature
-    event_subscribe: []
-    event_publish: []
     call:
       - lighting.set
-    presentation: []
 
 coordinator:
   entry: coordinator/main.ts
 ```
 
+`app` declares only `state_read` and `call`; events, media and reserved
+`miakapp.*` calls are unavailable. Use `miakapp init --kind component` for the
+semantic component ABI instead. Choose exactly one of `app` and `component`.
+
 `requires` is the closed RFC 0002 capability object. Lists are de-duplicated and
 sorted before they are bound into an upload capability, so the value the CLI
 sends is byte-identical on every later reconciliation read.
@@ -55,10 +105,13 @@ duplicate keys — is rejected with the offending line rather than guessed at.
 
 | Command | What it does |
 | --- | --- |
-| `init` | Writes `miakapp.yaml`. Never overwrites an existing one. |
+| `pair` | Redeems a one-time pairing code into a new stored context. |
+| `context list\|show\|use\|remove` | Manages stored contexts. Never prints a key. |
+| `init` | Writes `miakapp.yaml`; with `--starter app`, also a buildable app. Never overwrites. |
 | `agent-pack` | Offline. Installs the guide and the MCP wiring into a repository. |
 | `discover` | Offline. Inventories a Node-RED installation from its flows export. |
 | `check` | Offline. Parses the project, verifies the artifact, prints the digest. |
+| `status` | Reads the live generation, release and digest of the home. |
 | `publish` | Capability → delivery → finalization → activation, in one run. |
 | `activate` | Activates an already finalized digest at a new generation. |
 | `rollback` | Alias of `activate`, for returning to a known-good digest. |
@@ -111,9 +164,9 @@ place instead of appending another copy. `.mcp.json` is merged as a structure
 one key, by name — so every other server in it survives, and a file that does
 not parse is refused rather than replaced with a valid one.
 
-The server is registered as the bare `miakapp` command rather than an absolute
-path, because the file is committed and the next machine to check it out will
-not have this one's directory layout.
+The generated server entry uses `npx -y @miakapp/cli@<installed-version> mcp`,
+so a new machine gets the same executable as the bundled guide without relying
+on a global binary or this machine's directory layout.
 
 Run it again whenever the CLI is upgraded: an unchanged file is reported
 `unchanged`, and a guide that moved on is reported `updated`.
@@ -129,8 +182,7 @@ tools over newline-delimited JSON-RPC on stdio.
   "mcpServers": {
     "miakapp": {
       "command": "bunx",
-      "args": ["@miakapp/cli", "mcp"],
-      "env": { "MIAKAPP_HOME_KEY": "${MIAKAPP_HOME_KEY}" }
+      "args": ["@miakapp/cli", "mcp"]
     }
   }
 }
@@ -138,11 +190,17 @@ tools over newline-delimited JSON-RPC on stdio.
 
 | Tool | Command | |
 | --- | --- | --- |
+| `miakapp_pair` | `pair` | stores a new context; the code is a tool argument |
+| `miakapp_context_list` | `context list` | read-only, offline |
+| `miakapp_context_show` | `context show` | read-only, offline |
+| `miakapp_context_use` | `context use` | offline, changes the current context |
+| `miakapp_context_remove` | `context remove` | **deletes a stored key — needs `confirm: true`** |
+| `miakapp_status` | `status` | read-only |
 | `miakapp_discover` | `discover` | read-only, offline |
 | `miakapp_check` | `check` | read-only, offline |
 | `miakapp_release` | `release` | read-only |
 | `miakapp_upload` | `upload` | read-only |
-| `miakapp_init` | `init` | writes `miakapp.yaml`, never overwrites |
+| `miakapp_init` | `init` | writes `miakapp.yaml` (and the app starter with `starter: "app"`), never overwrites |
 | `miakapp_agent_pack` | `agent-pack` | offline, writes the pack into a repository |
 | `miakapp_publish` | `publish` | **moves the pointer — needs `confirm: true`** |
 | `miakapp_activate` | `activate` | **moves the pointer — needs `confirm: true`** |
@@ -154,7 +212,8 @@ drift apart. A tool argument is the option name with `_` for `-`
 (`expected_generation` → `--expected-generation`); an argument the tool does not
 declare is refused rather than ignored.
 
-The three pointer-moving tools additionally require `confirm: true`. It is
+The three pointer-moving tools and `miakapp_context_remove` additionally
+require `confirm: true`. It is
 checked before anything else and never reaches the command line, so a model that
 hallucinated a publication spends the mistake on an argument check instead of on
 a generation.
@@ -165,20 +224,69 @@ remedy — not as a JSON-RPC error. That distinction matters: a protocol error
 means the call never happened, while a publication that reached the control
 plane and failed did happen, and only `kind` says whether to reconcile.
 
-## Authorization
+## Access: pairing and contexts
+
+The owner grants access in their own browser; the agent never signs in. They
+open `https://miakapp.com/pair`, choose the home, confirm, and send the
+one-time code, which `pair` trades for a **new, separately revocable** Home Key:
+
+```bash
+printf '%s\n' "$CODE" | miakapp pair      # or run it in a terminal: hidden prompt
+miakapp pair --code "$CODE"               # allowed, but lands in shell history
+```
+
+| Option | Default |
+| --- | --- |
+| `--issuer <https url>` | `https://control.miakapp.com` |
+| `--label <label>` | `miakapp-cli@<host name>`, shown in the owner's key list |
+| `--name <context>` | the paired home ID (`-2`, `-3`… if taken) |
+
+Before the code is sent, the issuer must serve a discovery document naming
+exactly itself; redirects are refused. The redeem response —
+`POST {issuer}/v1/pairing/redeem` with `{code, label}`, answered with
+`{home_key, home_id, key_id, issuer}` and `Cache-Control: no-store` — must name
+the same issuer and a key whose ID is embedded in the key. The code is sent
+once and never retried: a lost response is exit 7, because a key may exist.
+`pair` then exchanges the key for a publication token, reported as
+`publish_access`, so a key without the publish scope is caught now rather than
+at the first publication.
+
+Contexts live in `~/.miakapp` (or `$MIAKAPP_CONFIG_DIR`, absolute):
+
+| File | Holds | Mode |
+| --- | --- | --- |
+| `config.json` | context names, home IDs, issuers, key IDs, labels, current context | 0600 |
+| `credentials.json` | the Home Keys, nothing else | 0600 |
 
-The Home Key is read from `MIAKAPP_HOME_KEY` and from nowhere else. No command
-accepts it as an argument, because an argument lands in shell history, in a
-process listing and in most CI logs.
+The directory is 0700. Both files are replaced through a temporary file, an
+fsync and a rename, under a lock file, so concurrent runs never lose a context
+and a crash never leaves half a file. A credentials file readable by another
+account, a symbolic link, a foreign owner or a key that is not the one the
+context was paired with is refused rather than used.
 
 ```bash
-export MIAKAPP_HOME_KEY="$(op read op://home/miakapp/home-key)"   # or your own vault
-bunx @miakapp/cli publish --expected-generation 4
+miakapp context list
+miakapp context show [name]     # credential: stored (never printed)
+miakapp context use <name>
+miakapp context remove <name>   # local only: the owner revokes the key server-side
 ```
 
-The key is exchanged for a five-minute `components:publish` token before every
-run. Publication endpoints never accept the Home Key itself, and the CLI never
-prints either credential.
+Which Home Key a command uses, highest precedence first:
+
+1. `--context <name>`, then `MIAKAPP_CONTEXT=<name>`;
+2. `MIAKAPP_HOME_KEY` — a raw key, kept for CI and compatibility;
+3. the stored context whose home and issuer match `miakapp.yaml`, the current
+   context breaking a tie between keys for that same home.
+
+A selected context for another home — or a `MIAKAPP_HOME_KEY` this machine
+knows was paired with another home — is refused before any request, so a key
+can never publish into the wrong house. Every networked result reports
+`credential_source` and `context`, never the key.
+
+No command accepts a Home Key as an argument: an argument lands in shell
+history, in a process listing and in most CI logs. The key is exchanged for a
+five-minute `components:publish` token before every run, and publication
+endpoints never see the Home Key itself.
 
 ## Generations
 
@@ -187,11 +295,11 @@ believe the pointer holds, and `--generation` (default: expected + 1) is the one
 you are publishing. A stale expectation fails with `generation_conflict` and
 exit code 6 rather than last-write-wins.
 
-`--expected-generation` is required rather than discovered, because RFC 0004
-§13.2 publishes no read for the current pointer: the pointer lives in
-`components/{homeID}` and reaches clients as authenticated platform data. Until
-that surface exists, the CLI asks you for the number instead of guessing one —
-inventing an endpoint would be worse than an explicit flag.
+Without `--expected-generation`, `publish` and `activate` read the live pointer
+first (`GET /v1/homes/{homeId}/component-pointer`, RFC 0004 §13.2) and use its
+generation. That read takes no lock, so the activation is still a
+compare-and-set: a publication that lands in between makes this one fail with
+exit 6, never overwrites it. `miakapp status` prints the same read.
 
 ## Exit codes
 
@@ -213,14 +321,14 @@ committed, so the next step is a read — `miakapp upload <id>` or
 ## Failure output
 
 ```console
-$ miakapp publish --expected-generation 0
+$ miakapp publish
 miakapp: conflict: Activation failed with HTTP 409 generation_conflict (request Zq1...)
   Another publication advanced the pointer. Read the active generation and retry
   the activation with the observed expected_generation.
 ```
 
 ```console
-$ miakapp publish --expected-generation 0 --json
+$ miakapp publish --json
 {"ok":false,"kind":"conflict","exit_code":6,"message":"...","remedy":"..."}
 ```
 
@@ -228,3 +336,11 @@ $ miakapp publish --expected-generation 0 --json
 
 Alpha, tracking Miakapp 4. The package is `private` until the control plane it
 talks to is deployed; publishing it to npm is a deliberate, separate step.
+
+### Command help
+
+Run `miakapp help` or append `--help` / `-h` to any command, including
+`miakapp pair --help`. Help never prompts for a code or executes the command.
+`miakapp init` defaults to a whole-house app at `dist/app.js`; add
+`--starter app` for the buildable starter, or use `--kind component` for a
+semantic component at `dist/component.js`.