@dashai/cli 0.8.1 → 0.9.0

package/README.md

@@ -6,7 +6,7 @@
 
 ## Status
 
-`0.5.x` — full author workflow + **Query Plane v1 author tooling** + **P7 cross-module-action observability** (shipped 2026-05-20) + **BaaS Phase 1 deploy loop** (`api-keys`, `env export`, `--deploy-target`; shipped 2026-05-24). Commands: `login`, `logout`, `profile`, `workspace`, `init` / `module init` (incl. `--custom`, `--deploy-target railway|vercel|fly`) / `connect-git` / `generate` / `dev` / `validate` / `list` / `publish` / `diff` / `pull-data` / `clone` / `query-log` / `action-log`, plus `query` (run AST queries against the local module), `pull` (sync canonical manifest from backend), `api-keys list|create|revoke`, `env export`, and `deps add` / `list` / `remove` / `check`.
+`0.5.x` — full author workflow + **Query Plane v1 author tooling** + **P7 cross-module-action observability** (shipped 2026-05-20) + **BaaS Phase 1 deploy loop** (`api-keys`, `env export`, `--deploy-target`; shipped 2026-05-24). Commands: `login`, `logout`, `profile`, `workspace`, `init` / `module init` (incl. `--custom`, `--deploy-target railway|vercel|fly`) / `connect-git` / `generate` / `dev` / `validate` / `list` / `publish` / `diff` / `pull-data` / `clone` / `query-log` / `action-log`, plus `query` (run AST queries against the local module), `pull` (sync canonical manifest from backend), `api-keys list|create|revoke`, `origins list|add|remove` (SSO callback allowlist), `env export`, and `deps` (live connect status) / `add` / `list` / `remove` / `check` / `bind` / `unbind` (cross-module dependency connect lifecycle).
 
 ## Install
 
@@ -85,9 +85,11 @@ One-command local dev loop — collapses the historical two-terminal flow into a
 1. `dashwise module dev` — manifest watcher + SDK regen
 2. `next dev` — Next.js dev server (via the project's `dev:next` script if defined, else `npx next dev`)
 
-Both children inherit a pre-populated env with `DASHWISE_API_URL`, `DASHWISE_API_TOKEN`, and `DASHWISE_INSTALLATION_ID` automatically resolved from your saved CLI config (`~/.config/dashwise/auth.json`). No more copying tokens into `.env.local` by hand.
+Both children inherit a pre-populated env with the Phase 2 two-var contract (`DASHWISE_API_URL` + `DASHWISE_API_KEY`, plus a `NEXT_PUBLIC_DASHWISE_API_URL` mirror) automatically resolved from your saved CLI config (`~/.config/dashwise/auth.json`). No more copying credentials into `.env.local` by hand.
 
-**HH-CC-LDI-7:** when the current module has been provisioned via `dashwise init` (LDI-6), the per-module runtime token cached at `~/.config/dashwise/auth.json#modules[<slug>]` is automatically injected as `DASHWISE_RUNTIME_TOKEN` into both children. `DASHWISE_INSTALLATION_ID` flips to the literal `sandbox` (the URL placeholder the backend's runtime-token guard accepts) so the SDK can hit the data plane without you passing `--installation-id`. The pre-flight banner prints which auth source is in use.
+**Two-var contract:** when the current module has been provisioned via `dashwise init` / `dashwise module register`, the per-module scoped `dwk_` API key cached at `~/.config/dashwise/auth.json#modules[<slug>]` is injected as `DASHWISE_API_KEY` into both children. The key resolves the install server-side, so the SDK hits the install-agnostic `/api/module-api` — there is no `DASHWISE_INSTALLATION_ID`. `DASHWISE_API_TOKEN` (your CLI bearer), `DASHWISE_RUNTIME_TOKEN` (retired), and `DASHWISE_DEV_SESSION_ID` are **not** injected into the children — the scoped key is the only data-plane credential, and the scaffold's sign-in route uses it (via `/api/module-api/sso/start-url`) for SSO too. The pre-flight banner prints which auth source is in use.
+
+**Self-heal:** if your `auth.json` still has a legacy `runtimeToken` (pre-identity-collapse), `dashwise dev` mints a `dwk_` key via `POST /api/installations/:id/api-keys`, rewrites the entry, and tells you. If the install is gone, it points you to `dashwise init <slug> --force`.
 
 If the manifest's slug isn't in `auth.json#modules`, `dashwise dev` still starts (SSO + watcher work fine), but it prints a one-line warning that data-plane calls (db, qb) will 401 — pointing you to re-run `dashwise init <slug> --force` to provision.
 
@@ -95,13 +97,13 @@ Output from both children is line-prefixed (`[sdk]` cyan, `[next]` magenta) so a
 
 Flags:
 - `--dir <path>` — Project root (default: current directory).
-- `--installation-id <id>` — Override `DASHWISE_INSTALLATION_ID` (default `"sandbox"` if a runtime token is found, else `"local"`). Useful for prod-mode SSO testing against a real installed module.
+- `--installation-id <id>` — Run against an already-installed module (skips dev-session registration and uses prod-mode SSO against a real installed module). The id is used by `dashwise dev` internally, not injected into the child env.
 - `--api-url <url>` — Override `DASHWISE_API_URL` (default: saved config value).
 - `--port <number>` — Port for `next dev` (default: Next picks 3000 / next free).
 - `--sdk-only` — Run only the manifest watcher; skip `next dev`.
 - `--next-only` — Run only `next dev`; skip the watcher.
 
-Requires `dashwise login` first — the command refuses to start if no token is resolvable. The runtime-token injection requires `dashwise init <slug>` (LDI-6); the dev session SSO setup works without it.
+Requires `dashwise login` first — the command refuses to start if no token is resolvable. The `DASHWISE_API_KEY` injection requires `dashwise init <slug>` (or `dashwise module register`); the dev session SSO setup works without it.
 
 ### `dashwise init [slug]` / `dashwise module init [slug]`
 
@@ -123,7 +125,7 @@ Flags:
 - `--no-provision` — Skip the `POST /api/installations/dev` step (HH-CC-LDI-6). Local scaffold is still written, but the module won't have a backing dev installation — `dashwise dev` data-plane calls will fail with `UnauthenticatedError` until you re-run `dashwise init --force` or (once it ships) `dashwise module provision-dev-install`.
 - `--deploy-target railway|vercel|fly` (HH-CC-P1-D2) — Emit a platform deploy config file alongside the scaffold (`railway.json`, `vercel.json`, or `fly.toml`). Default: none (clean repo). Pair with `dashwise env export --format <platform>` to push env vars after provisioning. See [`docs/deploying.md`](../../docs/deploying.md) for the full deploy walkthrough.
 
-**Provisioning behavior (HH-CC-LDI-6):** by default, after the local scaffold is written, `dashwise init` provisions a real local-dev installation by calling `POST /api/installations/dev`. The returned runtime token (90-day JWT) is cached in `~/.config/dashwise/auth.json#modules[<slug>]` where `@dashai/sdk`'s `createDevClient({ moduleSlug })` reads it on every dev-server boot. Provisioning failures are surfaced as warnings; the local scaffold remains usable so you can retry later.
+**Provisioning behavior (HH-CC-LDI-6):** by default, after the local scaffold is written, `dashwise init` provisions a real local-dev installation by calling `POST /api/installations/dev`. The returned scoped `dwk_` API key (default 90-day expiry) is cached in `~/.config/dashwise/auth.json#modules[<slug>]` where `@dashai/sdk`'s `createDevClient({ moduleSlug })` reads it on every dev-server boot. On a `kind='local'` install the key grants self-access to your own tables, so a table you create is instantly queryable. Provisioning failures are surfaced as warnings; the local scaffold remains usable so you can retry later.
 
 ### `dashwise module connect-git <repo-url>`
 
@@ -195,7 +197,7 @@ Tear down the local-dev installation for the current module. Calls `DELETE /api/
 dashwise module destroy-dev-install
 ```
 
-Local `module.json` is preserved — only the cached runtime token + install id get cleared. Re-run `dashwise init <slug> --force` to provision a fresh install.
+Local `module.json` is preserved — only the cached API key + install id get cleared. Re-run `dashwise init <slug> --force` to provision a fresh install.
 
 Flags:
 - `--dir <path>` — Project root (default: current directory).
@@ -209,7 +211,7 @@ Errors map to user-friendly messages: `INSTALLATION_NOT_FOUND` (already destroye
 Destroy + re-provision the local-dev install in a single command. Useful for:
 
 - Nuking accumulated test data
-- Refreshing a compromised runtime token
+- Refreshing a compromised API key
 - Recovering from a wedged schema state
 
 ```bash
@@ -297,7 +299,7 @@ Flags:
 - `--json` — Compact JSON output (no pretty-print).
 - `--dir <path>` — Project root (default: current directory).
 
-Pre-reqs: `dashwise module generate` must have run (the SDK reads `node_modules/@dashai/generated`). `DASHWISE_API_URL`, `DASHWISE_INSTALLATION_ID`, `DASHWISE_API_TOKEN` must be set (the scaffold's `.env.local` is loaded automatically).
+Pre-reqs: `dashwise module generate` must have run (the SDK reads `node_modules/@dashai/generated`). `DASHWISE_API_URL` + `DASHWISE_API_KEY` must be set (the scaffold's `.env.local` is loaded automatically; `dashwise dev` injects both).
 
 ### `dashwise pull` (HH-CC-P1-E2)
 
@@ -317,36 +319,50 @@ Flags:
 
 ### `dashwise api-keys list|create|revoke` (HH-CC-P1-C4)
 
-Mint long-lived production credentials for a `production` install. Used by self-hosted deploys (Railway / Vercel / Fly / your own infra) instead of the per-CLI-session runtime token. The key format is `dwk_<43-char-base64url>`; the backend stores only a `sha256` hash so the plaintext is shown exactly once at `create`.
+Mint long-lived credentials for an install. Used by self-hosted deploys (Railway / Vercel / Fly / your own infra). Same `dwk_` key kind `dashwise init` mints for local dev, but you mint a separate one per environment. The key format is `dwk_<43-char-base64url>`; the backend stores only a `sha256` hash so the plaintext is shown exactly once at `create`.
 
 ```sh
-# Mint a key. Plaintext appears on stdout — copy it now.
+# Mint a full-access key. Plaintext appears on stdout — copy it now.
 dashwise api-keys create production
 
 # Script-friendly: capture the raw key with no other chatter.
 KEY=$(dashwise api-keys create ci --raw-only)
 
-# List all keys for the current install.
+# Least-privilege (scoped) key — any --grant flips it to default-deny.
+dashwise api-keys create readonly --grant module:tasks:read
+dashwise api-keys create writer \
+  --grant module:tasks:read,create \
+  --grant datahub:table=12:read
+
+# Expire the key after N days.
+dashwise api-keys create temp --grant module:tasks:read --expires 30
+
+# List all keys for the current install (shows each key's grants).
 dashwise api-keys list
 
 # Revoke. Irreversible. Effective on the next request.
 dashwise api-keys revoke <key-id>
 ```
 
+Create flags:
+- `--grant <spec>` (repeatable) — `module:<tableSlug>:<ops>`, `datahub:table=<id>:<ops>`, `datahub:app=<id>:<ops>`, or `datahub:workspace:<ops>`, where `<ops>` is a comma list of `create,read,update,delete`. Any grant mints a scoped (default-deny) key; minting scoped keys (or any key on a non-local install) requires workspace-admin.
+- `--expires <days>` — days until the key expires (default: never).
+- `--raw-only` — print only the plaintext key on stdout (for shell capture).
+
 The install is resolved from the cached entry in `~/.config/dashwise/auth.json#modules[<slug>]` (keyed by `module.json#module.slug`). Run from inside the module directory, or pass `--dir <path>`.
 
 Pairs with `dashwise env export --key dwk_...` to push the key into a deploy platform without ever copy-pasting it through a shell history.
 
 ### `dashwise env export` (HH-CC-P1-D1)
 
-Emit the four env vars every self-hosted deploy needs:
+Emit the Phase 2 two-var contract every self-hosted deploy needs:
 
 | Var | Source |
 |---|---|
 | `DASHWISE_API_URL` | CLI config (`apiUrl`). |
-| `NEXT_PUBLIC_DASHWISE_API_URL` | Same. |
-| `DASHWISE_INSTALLATION_ID` | `~/.config/dashwise/auth.json#modules[<slug>].installationId` (the dev install cached at `dashwise init`). |
-| `DASHWISE_API_KEY` | Placeholder by default; pass `--key dwk_...` to inline an existing key, or `--new-key <name>` to mint one in-flight. |
+| `DASHWISE_API_KEY` | Placeholder by default; pass `--key dwk_...` to inline an existing key, or `--new-key <name>` to mint one in-flight. Resolves the install server-side. |
+
+`DASHWISE_INSTALLATION_ID` is NOT emitted (the key binds the install) and `NEXT_PUBLIC_DASHWISE_API_URL` is NOT emitted (the scaffold's `next.config` derives it from `DASHWISE_API_URL`).
 
 Five output formats — `env`, `json`, `railway`, `vercel`, `fly`. The platform-specific ones wrap each var in the matching CLI invocation (`railway variables set …`, `vercel env add …`, `fly secrets set …`) so the output is directly pipeable into `sh`.
 
@@ -369,6 +385,22 @@ Flags:
 - `--new-key <name>` — Mint a new API key and inline its plaintext.
 - `--dir <path>` — Project root.
 
+### `dashwise origins list|add|remove`
+
+Manage the current module install's SSO callback-origin allowlist. The scaffold's `/api/auth/sign-in` route sends its own public origin as the SSO `callback_url`; the backend only accepts an origin that's on the install's allowlist. `kind='local'` installs (what `dashwise init` provisions) allow `http://localhost:<any-port>` implicitly, so **local dev needs no config**. A deployed custom domain must be added here.
+
+```sh
+dashwise origins list                          # show the allowlist
+dashwise origins add https://app.example.com   # add a deployed domain (https:// for non-localhost)
+dashwise origins remove https://app.example.com
+```
+
+Workspace-admin operation (uses your CLI login bearer). The install id is resolved from `~/.config/dashwise/auth.json#modules[<slug>]` — you never type it. `add` / `remove` do a client-side read-modify-write against the backend's `GET` (read) + `PUT` (full-replace) endpoints.
+
+Flags:
+- `--dir <path>` — Project root.
+- `--json` (list only) — Emit a JSON array of origins.
+
 ### `dashwise module query-log`
 
 Read the per-module SDK query log (each cross-module / `.execute()` / `.stream()` / `.explain()` dispatch writes a row to `module_query_log` server-side). Workspace-member-scoped on the backend.
@@ -419,7 +451,7 @@ Flags:
 
 Schema-mutation commands for the current module — add or drop tables, add/remove/retype fields in the dev installation. Each command:
 
-1. Calls the LDI-4 REST endpoint at `/api/installations/:id/schema/...` using the runtime token cached by `dashwise init` (LDI-6).
+1. Calls the LDI-4 REST endpoint at `/api/installations/:id/schema/...` using the scoped `dwk_` API key cached by `dashwise init` (on a `kind='local'` install the backend allows the developer to mutate their own schema; C3).
 2. Asks the backend to apply the change (manifest + physical Postgres tables update atomically server-side).
 3. Calls `GET /api/installations/:id/schema` to fetch the new manifest.
 4. Writes the response to local `module.json`.
@@ -507,18 +539,47 @@ Errors: 404 `TABLE_NOT_FOUND` / `FIELD_NOT_FOUND`.
 
 ### `dashwise deps`
 
-Manage cross-module dependencies declared in `module.json#dependencies`.
+Manage cross-module dependencies — both the declaration (in `module.json#dependencies`) and the **connect lifecycle** (whether each declared dep is actually wired to a provider installation).
 
-**`dashwise deps add <provider-slug>`** — Add a dep. Interactive in a TTY (fetches the provider's published `exposes` block, multi-select tables + fields, prompts for the required `purpose` string). Non-interactive when `--table` + `--fields` + `--purpose` are all passed.
+#### Park-not-reject — how deps connect
 
-Flags: `--table <slug>`, `--fields <comma-list>`, `--purpose <text>`, `--version <semver-range>`, `--dir <path>`.
+A dependency is *declared* in your manifest but only *connected* once a compatible provider is installed in the workspace and bound. When a dep can't bind — no provider installed yet, a version mismatch, a table/action the provider doesn't expose — the backend **parks** it (`status='unbound'`) instead of failing the install. Runtime reads against a parked dep return `DEP_UNBOUND` (the SDK surfaces this as `DepUnboundError` so your app can render a "connect your provider" state).
 
-**`dashwise deps list`** — Print the local manifest's declared deps as column-aligned text (provider slug, version range, tables, purpose). `--json` for piping.
+**Both install orders work.** You can install the consumer first (its deps park until the provider shows up) or the provider first (the consumer's deps resolve immediately at install). A parked dep auto-connects when its provider is later installed; you can also connect it by hand with `dashwise deps bind`.
 
-**`dashwise deps remove <provider-slug>`** — Drop a dep entry from the manifest. Honours `--table <slug>` to remove a single table from a multi-table dep without dropping the whole entry.
+**`dashwise deps`** (no subcommand) — Show the **live connect status** of every declared dep on your installation: a `resolved` / `unbound` chip, the version range, the bound provider's install id + version (when resolved), and the park reason (when unbound). This is the backend's per-installation truth — the thing that decides whether a runtime dep read succeeds or 409s. Requires a provisioned dev install (`dashwise init`). Workspace-member. `--json` for piping.
+
+```
+$ dashwise deps
+ℹ Cross-module dependencies for my-app (2 declared, 1 unbound):
+
+  ● resolved  crm@^1.2.0
+      provider: install #88 @ v1.3.0
+
+  ○ unbound   billing@^2.0.0
+      reason: MISSING_DEPENDENCY
+
+ℹ Connect a parked dep with `dashwise deps bind <provider-slug>` once its provider is installed.
+```
+
+**`dashwise deps add <provider-slug>`** — Add a dep to `module.json`. Interactive in a TTY (fetches the provider's published `exposes` block, multi-select tables + fields, prompts for the required `purpose` string); non-interactive when `--table` + `--fields` + `--purpose` are all passed. You can declare a dependency on an **unpublished same-workspace provider** — the backend resolves it against the provider's draft manifest; the CLI surfaces whatever answer the backend gives (it doesn't pre-validate beyond the manifest's schema shape). After writing the manifest, `deps add` shows the resulting **resolve / park status** for the new dep (the manifest is reconciled server-side on the next push, e.g. via `dashwise dev`).
+
+Flags: `--table <slug>`, `--fields <comma-list>`, `--purpose <text>`, `--version <semver-range>`, `-y/--yes`, `--dir <path>`.
+
+**`dashwise deps bind <provider-slug> [--installation <id>]`** — (Re-)connect a parked dependency to its provider installation. Re-runs single-dep resolution and snapshots the contract; on success, runtime reads succeed. If it can't bind, the command exits 1 with the **park reason** (`MISSING_DEPENDENCY`, `DEPENDENCY_VERSION_MISMATCH`, `EXPOSES_MISSING`, `EXPOSES_PRIVATE`, `ACTION_NOT_EXPOSED`, `PROVIDER_NOT_PRODUCTION`, …) and the dep stays unbound. Pass `--installation <id>` to disambiguate when the workspace has more than one candidate install of the provider. Workspace-admin.
+
+**`dashwise deps unbind <provider-slug>`** — Disconnect a bound dependency: NULLs the provider ref + contract snapshot and parks the dep (reason `MANUALLY_UNBOUND`). Runtime reads then return `DEP_UNBOUND` until you bind it again. Workspace-admin.
+
+**`dashwise deps list`** — Print the *local manifest's* declared deps as column-aligned text (provider slug, version range, tables, purpose). Offline; reads `module.json` only (contrast with the bare `dashwise deps`, which shows live backend connect status). `--json` for piping.
+
+**`dashwise deps remove <provider-slug>`** — Drop a dep entry from the manifest (local edit).
 
 **`dashwise deps check`** — Verify each declared dep still resolves against a currently-published provider (online command; requires backend reachability). Exits 1 on drift. Reported codes: `PROVIDER_NOT_FOUND`, `NO_MATCHING_VERSION`, `FIELD_NOT_EXPOSED`, `OP_NOT_ALLOWED`. `--json` available for CI integrations.
 
+> **`deps` vs `deps list` vs `deps check`:** bare `dashwise deps` reads the **backend's live connect state** for your install (resolved/unbound). `deps list` reads your **local manifest** offline. `deps check` probes **published providers** for manifest drift. Use `deps` to answer "will my cross-module reads work right now?"; `bind` / `unbind` to change that.
+
+Auth + install resolution for the online subcommands (`deps`, `bind`, `unbind`) mirror `dashwise origins`: they use your CLI login bearer (bind/unbind need workspace-admin) and resolve the install id from `~/.config/dashwise/auth.json#modules[<slug>]` — you never type it.
+
 ### Module dev loop
 
 ```bash