@dashai/cli 0.5.0 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@
 
 ## Status
 
-`0.1.x` — full author workflow + **Query Plane v1 author tooling** + **P7 cross-module-action observability** (shipped 2026-05-20). Commands: `login`, `logout`, `profile`, `workspace`, `module init` (incl. `--custom`) / `connect-git` / `generate` / `dev` / `validate` / `list` / `publish` / `diff` / `pull-data` / `clone` / `query-log` / `action-log`, plus `query` (run AST queries against the local module) 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`, `env export`, and `deps add` / `list` / `remove` / `check`.
 
 ## Install
 
@@ -103,23 +103,25 @@ Flags:
 
 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]`
+### `dashwise init [slug]` / `dashwise module init [slug]`
 
-Scaffold a new DashWise module in a fresh directory. Two flavors:
+Scaffold a new DashWise module in a fresh directory. `dashwise init` is a top-level alias for `dashwise module init` — both accept the same flags. Two flavors:
 
-**Hand-authored** (default) — simple module-runtime app (isolate runtime). 10 files: `module.json`, `package.json`, `tsconfig.json`, `next.config.mjs`, `next-env.d.ts`, `.gitignore`, `.env.local.example`, `app/layout.tsx`, `app/page.tsx`, `README.md`.
+**Custom** (default since 2026-05-18) — full Next.js App Router app with SDK auth wired in (machine runtime, lands on Fly Machines once P7 ships). Files: `module.json`, `package.json`, `tsconfig.json`, `next.config.mjs`, `next-env.d.ts`, `middleware.ts` (uses `@dashai/sdk/auth/middleware`), `app/layout.tsx`, `app/page.tsx`, `app/dashboard/page.tsx` (auth-gated Server Component example), three `app/api/auth/*` route handlers, shadcn primitives + a `globals.css`, plus `CLAUDE.md` / `spec.md` / `agent-log.md` agent-facing docs. `module.json` carries `module_kind: 'custom'` + `runtime.kind: 'machine'`.
 
-**Custom** (`--custom`) — full Next.js App Router app with SDK auth wired in (machine runtime, lands on Fly Machines once P7 ships). Adds 5 files on top of the hand-authored set: `middleware.ts` (uses `@dashai/sdk/auth/middleware`), `app/dashboard/page.tsx` (auth-gated Server Component example), and three `app/api/auth/*` route handlers (`sign-in`, `callback`, `sign-out`). `module.json` carries `module_kind: 'custom'` + `runtime.kind: 'machine'`.
+**Hand-authored** (`--simple`) — the legacy simple module-runtime app (isolate runtime). 10 files total: no middleware, no `/api/auth/*`, no dashboard. Suitable for public viewers / demo modules that don't need SSO.
 
 Flags:
 - `--dir <path>` — Target directory (default `./<slug>`).
 - `--name <name>` — Human-readable module name (default: derived from slug).
 - `--force` — Overwrite an existing non-empty directory.
-- `--custom` — Use the full Next.js custom-module scaffold.
+- `--simple` — Use the legacy minimal scaffold (hand-authored, no Next.js auth wiring).
+- `--custom` — *[Deprecated alias — kept for back-compat.]* Equivalent to the default. Will be removed in a future major version.
 - `--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`.
+- `--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.
 
@@ -297,6 +299,76 @@ Flags:
 
 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).
 
+### `dashwise pull` (HH-CC-P1-E2)
+
+Fetch the canonical manifest from the backend and write it to local `module.json`. The inverse of `dashwise table create` / `field add` — useful after dashboard-side schema edits, DashAI mutations, or teammate-driven changes.
+
+The backend (`GET /api/installations/:id/schema`) is the source of truth; `pull` materializes that locally. `dashwise dev`'s watcher polls this endpoint automatically, so most authors don't need to invoke `pull` manually.
+
+```
+$ dashwise pull
+ℹ Backend at ab12cd34 — local at 9f8e7d6c. Writing module.json…
+✓ module.json updated (3 tables, 18 fields).
+```
+
+Flags:
+- `--dir <path>` — Project root (default: current directory).
+- `--dry-run` — Print the diff but don't write.
+
+### `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`.
+
+```sh
+# Mint a 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.
+dashwise api-keys list
+
+# Revoke. Irreversible. Effective on the next request.
+dashwise api-keys revoke <key-id>
+```
+
+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:
+
+| 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. |
+
+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`.
+
+```sh
+# .env syntax — copy/paste into a host that reads .env files.
+dashwise env export --format env > .env.production
+
+# Push straight into Railway.
+dashwise env export --key dwk_... --format railway | sh
+
+# Mint and inline a new key in one step.
+dashwise env export --new-key prod --format vercel | sh
+```
+
+Stdout carries only the env block (clean for piping); status chatter goes to stderr.
+
+Flags:
+- `--format env|json|railway|vercel|fly` — Output format. Default: `env`.
+- `--key dwk_<...>` — Inline an existing API key.
+- `--new-key <name>` — Mint a new API key and inline its plaintext.
+- `--dir <path>` — Project root.
+
 ### `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.