@dashai/cli 0.2.5 → 0.3.0

package/README.md

@@ -87,17 +87,21 @@ One-command local dev loop — collapses the historical two-terminal flow into a
 
 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.
 
+**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.
+
+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.
+
 Output from both children is line-prefixed (`[sdk]` cyan, `[next]` magenta) so a single terminal stays readable. Ctrl-C cleanly terminates both.
 
 Flags:
 - `--dir <path>` — Project root (default: current directory).
-- `--installation-id <id>` — Override `DASHWISE_INSTALLATION_ID` (default `"local"`).
+- `--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.
 - `--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.
+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.
 
 ### `dashwise module init [slug]`
 
@@ -113,6 +117,11 @@ Flags:
 - `--force` — Overwrite an existing non-empty directory.
 - `--custom` — Use the full Next.js custom-module scaffold.
 - `--git <url>` — Initial Git repository URL. Written to `module.json#repository.url`.
+- `--description <text>` — Module description forwarded to the backend when provisioning the dev installation (HH-CC-LDI-6). No effect under `--no-provision`.
+- `--workspace <slug-or-id>` — Target workspace for the dev installation (HH-CC-LDI-6). When omitted in a TTY, the CLI prompts; auto-picked if your account has one workspace; in non-interactive mode with multiple workspaces, errors with the list.
+- `--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`.
+
+**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.
 
 ### `dashwise module connect-git <repo-url>`
 
@@ -176,6 +185,51 @@ Flags:
 - `--dir <path>` — Project root (default: current directory).
 - `--json` — Emit the structured diff as JSON `{ ok, current_version, unchanged, meta_changes, tables_added, tables_removed, tables_changed, deps_added, deps_removed }` instead of the human-readable summary. Useful for CI gates ("fail PR if any field-removal lands without a major bump").
 
+### `dashwise module destroy-dev-install` (HH-CC-LDI-9)
+
+Tear down the local-dev installation for the current module. Calls `DELETE /api/installations/dev/:installationId` and then removes the `auth.json#modules[slug]` entry. If the module had no other installs AND was never published, the backend also drops the module + its versions — tidies up dev-only modules that never shipped.
+
+```bash
+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.
+
+Flags:
+- `--dir <path>` — Project root (default: current directory).
+- `--module <slug>` — Override the module slug (default: read from local `module.json`). Useful when the project directory is gone but `auth.json` still has the entry.
+- `-y, --yes` — Skip the confirmation prompt — for CI.
+
+Errors map to user-friendly messages: `INSTALLATION_NOT_FOUND` (already destroyed elsewhere — local cache is cleaned up anyway), `INSTALLATION_KIND_NOT_LOCAL` (refuses non-local installs — use the dashboard's uninstall flow), `NOT_WORKSPACE_MEMBER`.
+
+### `dashwise module reset-dev-install` (HH-CC-LDI-9)
+
+Destroy + re-provision the local-dev install in a single command. Useful for:
+
+- Nuking accumulated test data
+- Refreshing a compromised runtime token
+- Recovering from a wedged schema state
+
+```bash
+dashwise module reset-dev-install
+```
+
+Local `module.json` (scaffold + manifest) stays intact — only the backend install + cached token get recycled. The freshly-provisioned install starts with the current `module.json`'s schema.
+
+Flags:
+- `--dir <path>` — Project root.
+- `--module <slug>` — Override slug (default: from local `module.json`).
+- `--workspace <slug-or-id>` — Target workspace for re-provisioning (passed through to `dashwise init`).
+- `-y, --yes` — Skip prompts in both destroy + re-init phases.
+
+If the destroy phase fails, the reset aborts (no point trying to provision over a still-existing install — the backend would 409 `SLUG_ALREADY_EXISTS`).
+
+### Idle GC (server-side, HH-CC-LDI-9)
+
+The backend runs a sweeper every 6h (configurable via `LOCAL_DEV_INSTALL_GC_INTERVAL_MIN`) that destroys local-dev installs idle for more than 30 days (configurable via `LOCAL_DEV_INSTALL_IDLE_DAYS`). "Idle" means no schema mutations in that window — pure data-plane queries don't refresh the timer in v1 (see `local-dev-installs-v1.md` §5 LDI-9 notes for the v1.1 follow-up).
+
+Disable with `LOCAL_DEV_INSTALL_GC_DISABLED=true` on the backend. CI fixtures, compliance freezes, etc.
+
 ### `dashwise module pull-data`
 
 Export the module's own-table rows from the owner-workspace installation to a local JSON file. Rows are keyed by manifest field slug (NOT `field_<id>` internals), so the output is reusable as test fixtures or local-dev seeds.
@@ -289,6 +343,96 @@ Flags:
 - `--tail` — Poll every 5s for new entries. Stops on Ctrl-C.
 - `--json` — Compact JSON output (ignored with `--tail`).
 
+### `dashwise table` / `dashwise field` (HH-CC-LDI-8)
+
+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).
+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`.
+
+If step 2 fails, no local changes are made (REST-first / write-back-from-GET model). If step 3 fails after step 2 succeeds, local `module.json` is left stale — `dashwise dev` reconciles automatically on next startup.
+
+**Prerequisite**: run `dashwise init <slug>` once. Without a cached per-module dev install, these commands fail with a clear "run init first" error.
+
+#### `dashwise table create <slug> --field <spec> [...]`
+
+Create a new table.
+
+```bash
+dashwise table create tasks \
+  --field title:text:required \
+  --field done:boolean \
+  --field due_at:datetime
+```
+
+Field spec: `<slug>:<type>[:flags]` where `flags` is comma-separated (`required`, `unique`). Allowed types: `text`, `long_text`, `number`, `boolean`, `date`, `datetime`, `email`, `url`, `phone`, `single_select`, `multi_select`, `link_row`, `file`, `multi_file`, `formula`, `ai`.
+
+For types that need extra config (`single_select` + `options`, `link_row` + `target`, etc.), use `--field-json '{...}'`:
+
+```bash
+dashwise table create tasks \
+  --field title:text:required \
+  --field-json '{"slug":"priority","type":"single_select","options":["low","medium","high"]}'
+```
+
+Flags:
+- `--dir <path>` — Project root.
+- `-f, --field <spec>` — Repeatable.
+- `--field-json <json>` — Repeatable.
+
+Errors: 409 `TABLE_SLUG_EXISTS`, 400 for malformed inputs, plus generic auth errors with hints to re-run `dashwise init`.
+
+#### `dashwise table delete <slug>`
+
+Drop a table. The backend soft-deletes the physical Postgres table — recoverable for 30 days via the dashboard's trash. Updates local `module.json`.
+
+```bash
+dashwise table delete tasks
+```
+
+Flags: `--dir <path>`.
+Errors: 404 `TABLE_NOT_FOUND`.
+
+#### `dashwise field add <table-slug> <field-spec>`
+
+Add a field to an existing table. Same `<slug>:<type>[:flags]` syntax as `table create --field`.
+
+```bash
+dashwise field add tasks done:boolean
+dashwise field add tasks priority --field-json '{"slug":"priority","type":"single_select","options":["low","medium"]}'
+```
+
+Flags: `--dir <path>`, `--field-json <json>` (mutually exclusive with positional spec).
+Errors: 404 `TABLE_NOT_FOUND`, 409 `FIELD_SLUG_EXISTS`.
+
+#### `dashwise field remove <table-slug> <field-slug>`
+
+Remove a field. The backend includes M2-C-FIX cascading-index-cleanup: indexes referencing the removed field are trimmed; empty indexes are dropped entirely.
+
+```bash
+dashwise field remove tasks priority
+```
+
+Flags: `--dir <path>`.
+Errors: 404 `TABLE_NOT_FOUND` / `FIELD_NOT_FOUND`.
+
+#### `dashwise field set-type <table-slug> <field-slug> <new-type>`
+
+Change a field's type.
+
+```bash
+dashwise field set-type tasks title long_text
+```
+
+Lossy changes (e.g. `text → number` with non-numeric data) are rejected by the backend's manifest validator today. v1.1 will add a structured `RETYPE_UNSAFE` precheck.
+
+Flags: `--dir <path>`.
+Errors: 404 `TABLE_NOT_FOUND` / `FIELD_NOT_FOUND`.
+
+**Not in v1**: `dashwise field rename` — per `local-dev-installs-v1.md` §7, slug renames need proper schema-migration support and land in v1.1.
+
 ### `dashwise deps`
 
 Manage cross-module dependencies declared in `module.json#dependencies`.