@dashai/cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DashWise
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,373 @@
+# @dashai/cli
+
+`dashwise` — the DashWise command-line tool. Log in, author modules, publish to the marketplace.
+
+> **New here?** Start with the [building modules walk-through](../../docs/building-modules.md) — covers the full first-module flow (login → scaffold → dev → publish) with diagrams of the auth flow and an annotated manifest. This file is the per-command reference; the walk-through is the tutorial.
+
+## 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`.
+
+## Install
+
+```bash
+npm install -g @dashai/cli
+```
+
+Or run via `npx` without installing globally:
+
+```bash
+npx @dashai/cli login
+```
+
+Requires Node 20+.
+
+## Commands
+
+### `dashwise login`
+
+Sign in via the OAuth 2.0 Device Authorization Grant.
+
+```
+$ dashwise login
+┌  Logging into http://localhost:3000
+
+  Open the verification URL and confirm the code:
+
+    URL:  http://localhost:3000/cli?user_code=WXYZ-1234
+    Code: WXYZ-1234
+
+    Code expires in 10m. The CLI will keep polling until you approve.
+
+◆  Open the verification URL in your browser?
+│  ● Open now
+│  ○ I'll open it manually
+└
+
+⠙  Waiting for approval
+✓  Approved.
+✓  Logged in as alice@example.com
+└  You can now run `dashwise profile`, `dashwise workspace list`, etc.
+```
+
+Flags:
+
+- `--api-url <url>` — Override the backend URL (default: `$DASHWISE_API_URL` → saved config → `http://localhost:3000`).
+- `--no-prompt` — Skip the "open browser" prompt; just print the URL. Useful in CI / headless environments.
+- `--name <name>` — Suggested label for the minted token (default `dashwise-cli`).
+
+### `dashwise logout`
+
+Clear the local credentials and revoke the server-side token. Idempotent.
+
+### `dashwise profile`
+
+Show the current user + accessible workspaces. Refreshes the cached profile from the server; falls back to local cache on network errors.
+
+Flags:
+- `--json` — Emit a single JSON object `{ ok, user, default_workspace, workspaces, api_url }` for piping into CI / `jq`.
+
+### `dashwise workspace list`
+
+List workspaces the user belongs to. The default workspace (set via `workspace use`) is marked with `*`.
+
+Flags:
+- `--json` — Emit `{ ok, default_workspace, workspaces }` instead of the column view.
+
+### `dashwise workspace use <slug>`
+
+Set the default workspace for subsequent commands. Validates that the slug is one the user has access to.
+
+### `dashwise dev`
+
+One-command local dev loop — collapses the historical two-terminal flow into a single foreground command. Spawns two children:
+
+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.
+
+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"`).
+- `--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.
+
+### `dashwise module init [slug]`
+
+Scaffold a new DashWise module in a fresh directory. 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** (`--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'`.
+
+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.
+- `--git <url>` — Initial Git repository URL. Written to `module.json#repository.url`.
+
+### `dashwise module connect-git <repo-url>`
+
+Link the local module to a Git repository — writes `module.json#repository`. Accepts both `https://github.com/owner/repo` and `git@github.com:owner/repo` shapes.
+
+The marketplace surfaces the repo URL when set. Future `dashwise module clone <slug>` will fetch from this URL when available.
+
+Flags:
+- `--branch <name>` — Default branch (e.g. `main`). Preserved across re-connects if unchanged.
+- `--dir <path>` — Project root.
+
+### `dashwise module generate`
+
+Read the local `module.json`, POST it to `/api/modules/draft/generate-sdk`, write the returned 13-file SDK tree to `node_modules/@dashai/generated/`. Requires `dashwise login` first.
+
+Flags:
+- `--dir <path>` — Project root (default: current directory).
+- `--dry-run` — Print summary without writing files.
+
+### `dashwise module dev`
+
+Watch `module.json` for changes; auto-regenerate the typed wrappers on every save. Initial regen runs on startup; subsequent regens bump a monotonic `generation` counter so the emitted `package.json#version` shifts and cache-busts naïve consumers.
+
+The watcher coalesces editor double-saves with a 250ms debounce. Ctrl-C exits cleanly.
+
+Does NOT spawn `next dev` itself — keep that in another terminal (or use `npm run dev:next`) so its output isn't swallowed. The scaffold sets up `npm run dev` to alias to this command.
+
+Flags:
+- `--dir <path>` — Project root (default: current directory).
+- `--debounce-ms <n>` — Filesystem-change debounce window (default 250ms).
+
+### `dashwise module validate`
+
+Send the local `module.json` to the backend's manifest validator (`POST /api/modules/manifest/validate`). On failure, prints a bullet-listed issue array with the field path each issue applies to.
+
+Flag: `--dir <path>` — project root (default: current directory).
+
+### `dashwise module list`
+
+List modules you can author. Defaults to `--owned-only` (modules where you're a workspace admin); pass `--all` to include public modules too. Honors the saved default workspace; override with `--workspace <slug>`.
+
+Output is plain text columns (`SLUG`, `VERSION`, `NAME`) so it pipes cleanly into `grep` / `awk` / `column`.
+
+Flags:
+- `--all` — Include public modules you can install but do not own.
+- `--workspace <slug>` — Filter to one workspace (default: saved default).
+- `--json` — Emit `{ ok, modules, total }` instead of column-aligned text.
+
+### `dashwise module diff`
+
+Show what would change at the next `publish` vs the currently-published version. Runs entirely server-side via `POST /api/modules/:id/draft/diff` — local manifest is sent, structured diff comes back.
+
+Output groups:
+- **Meta** — top-level field changes (`module.version`, `module.name`, `module_kind`, `runtime`, `repository`)
+- **Tables added / removed / changed** — per-field `+`/`-`/`~` markers under each changed table
+- **Dependencies added / removed**
+
+Use this as a pre-publish sanity check. If everything's unchanged, exits 0 with `No changes vs vX.Y.Z`.
+
+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 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.
+
+Capped at 100 rows per table by default; raise with `--limit` (1–1000). Each table reports its `total_rows` even when truncated, so the CLI warns when you're seeing a sample rather than the full dataset.
+
+Flags:
+- `--dir <path>` — project root.
+- `--limit <n>` — Max rows per table (1–1000, default 100).
+- `--out <path>` — Output file (default: `./dashwise-data.json`).
+
+### `dashwise module clone <slug>`
+
+Bring a published module's source into a local directory. Two flavors based on what the backend has:
+
+1. **Git mode** (preferred) — when the module's published manifest carries `repository.url`, the CLI shells out to `git clone <url> <target>`. Full history; future `git pull` for updates.
+2. **Manifest-only fallback** — when no Git URL is set, the CLI writes a fresh directory with the published `module.json` + a minimal scaffold (`.gitignore`, `package.json`, `README.md`). User has to recreate `app/`.
+
+Refuses to write into a non-empty directory unless `--force` is passed.
+
+Flags:
+- `--dir <path>` — Target directory (default: `./<slug>`).
+- `--force` — Overwrite an existing non-empty directory.
+- `--no-git` — Skip `git clone` even when `repository.url` is set; use the manifest-only scaffold.
+
+### `dashwise module publish`
+
+Pack the current directory into a gzipped tarball + upload it to `POST /api/modules/:id/publish/cli`. Excludes `node_modules`, `.next`, `.git`, `.dashwise`, `dist`, etc. — the full list lives in `src/lib/tarball.ts`. Per-file 10MB cap; tarball total 100MB cap (matches the backend's `BUNDLE_TOO_LARGE` gate).
+
+Flow:
+1. Read `module.json` for the slug.
+2. Resolve `slug → module.id` via `GET /api/modules/by-slug/:slug` (404 → "create the module via UI first").
+3. Pack + show a "X files in Y MB" summary.
+4. Prompt for confirmation (skip with `--yes` for CI).
+5. Multipart-POST the tarball with `bump=<patch|minor|major>`.
+6. Print resulting version + bundle URL + hash.
+
+Flags:
+- `--bump patch|minor|major` — Required. Will prompt interactively if omitted.
+- `--dry-run` — Backend validates + builds the bundle but doesn't persist the version.
+- `-y, --yes` — Skip the confirmation prompt.
+- `--exclude <pattern...>` — Extra exclude patterns appended to the defaults.
+- `--dir <path>` — Project root.
+
+### `dashwise query`
+
+Run a typed query against the local module's installation via the `@dashai/sdk/query` plane. Three modes:
+
+| Mode | Use |
+| --- | --- |
+| `--inline "<expr>"` | One-liner. `qb`, `deps`, `db` pre-bound. Example: `--inline "qb.tasks.where({done:false}).count()"` |
+| `--file <path>` | Dynamic-import a `.mjs` / `.js` file whose default export is a `Query` / `AggQuery` / `Promise`. |
+| `--repl` | Open a Node REPL with the generated SDK pre-bound. Top-level `await` supported. Ctrl-D exits. |
+
+Pretty-prints JSON by default; `--json` emits compact JSON for piping to `jq`.
+
+Flags:
+- `--inline <expr>` — Inline JS expression mode.
+- `--file <path>` — File-based query mode (`.mjs` / `.js`; `.ts` not yet supported — use `npx tsx` directly).
+- `--repl` — Interactive REPL mode.
+- `--explain` — Call `.explain()` instead of `.execute()`. Returns the Postgres plan envelope (joined queries fully; bare own/dep/view return `EXPLAIN_NOT_SUPPORTED_YET` until Phase 5+).
+- `--stream` — Stream results as JSON-lines via SSE (one row per line, `\n`-terminated). Lets Ctrl-C cleanly cancel mid-flight. Implies `--json`. Mutually exclusive with `--explain` / `--repl`.
+- `--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).
+
+### `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.
+
+Module resolution: `--module <id-or-slug>`, falling back to `module.json#module.slug` in the current directory.
+
+```
+$ dashwise module query-log --slow --since 1h --tail
+TIME                  MS  ROWS  CODE                    AST_HASH
+2026-05-20T14:32:01   543   1k                          ab12cd34
+2026-05-20T14:31:48   612    50  -                      9f8e7d6c
+```
+
+Flags:
+- `--module <id-or-slug>` — Override module resolution.
+- `--slow` — Filter to slow queries only (`duration_ms > 500`, matches the SDK/backend default threshold).
+- `--since <duration>` — Filter to entries with `created_at >= NOW() - <duration>`. Shorthand: `30m`, `1h`, `2d`, `7d`. ISO 8601 timestamps also accepted.
+- `--limit <n>` — Max rows per call (default 50; backend caps at 500).
+- `--tail` — Poll every 5s for new entries. Last-seen `created_at` becomes the next poll's `since`. Stops on Ctrl-C.
+- `--json` — Compact JSON output.
+
+### `dashwise module action-log`
+
+Read the per-installation server-action audit log (Phase 7 slice 7.5). Shows BOTH cross-module dispatches (consumer module invoked an action on a provider module) AND own-module dispatches. Workspace-member-scoped on the backend.
+
+```
+$ dashwise module action-log --module sales --role caller --cross-module-only --since 1h
+TIME                    MS  CROSS  CALLER              ACTION                  CODE
+-------------------  -----  -----  ------------------  ----------------------  ------------------
+2026-05-20 14:32:01    142  yes    sales               archiveContact          -
+2026-05-20 14:31:48    612  yes    sales               escalateContact         -
+```
+
+`--module` resolves the slug to your accessible installation; `--installation` is the direct shape (useful in CI scripts where you already know the id).
+
+Flags:
+- `--installation <id>` — Numeric installation id (find via `dashwise module list` or the workspace UI). Mutually exclusive with `--module`.
+- `--module <slug>` — Module slug. Resolves to the caller's accessible installation of that module (first match across the caller's workspaces). Mutually exclusive with `--installation`. Most users will prefer this — pass the slug from your local `module.json`.
+- `--role <caller|provider>` — Which side of cross-module dispatches to show. `caller` (default) shows outbound (this installation invoked actions); `provider` shows inbound (others invoked this installation's actions).
+- `--slow` — Filter to slow actions (elapsed_ms > 500). Uses the partial slow-action index.
+- `--cross-module-only` — Hide own-module dispatches (`cross_module=false` rows). Useful for forensics on consumer ↔ provider call patterns.
+- `--since <duration>` — `30m`, `1h`, `6h`, `2d`, `7d`, or an ISO 8601 timestamp.
+- `--limit <n>` — Max rows per call (default 50; backend caps at 500).
+- `--tail` — Poll every 5s for new entries. Stops on Ctrl-C.
+- `--json` — Compact JSON output (ignored with `--tail`).
+
+### `dashwise deps`
+
+Manage cross-module dependencies declared in `module.json#dependencies`.
+
+**`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.
+
+Flags: `--table <slug>`, `--fields <comma-list>`, `--purpose <text>`, `--version <semver-range>`, `--dir <path>`.
+
+**`dashwise deps list`** — Print the local manifest's declared deps as column-aligned text (provider slug, version range, tables, purpose). `--json` for piping.
+
+**`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 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.
+
+### Module dev loop
+
+```bash
+dashwise login                              # one-time, saves token to ~/.config/dashwise/auth.json
+dashwise module init my-module --name "My Module"
+cd my-module
+npm install
+dashwise dev                                # one command: manifest watcher + next dev,
+                                            # auth env vars auto-injected from your CLI config
+# Now edit module.json (add a table), save, see the types update under @dashai/generated/types/rows.d.ts
+
+# Sanity-check queries against the local installation:
+dashwise query --inline "qb.tasks.count()"
+dashwise query --file ./scripts/overdue.mjs --stream | jq .
+
+# When ready to ship:
+dashwise module validate                    # local manifest sanity check
+dashwise deps check                         # verify cross-module deps still resolve
+dashwise module publish --bump patch        # pack + upload + version-bump
+```
+
+For the two-terminal flow (e.g. when debugging Next separately), substitute step 5 with:
+
+```bash
+dashwise module generate                    # materialize node_modules/@dashai/generated/
+# Terminal 1:
+dashwise module dev                         # watch module.json + auto-regen
+# Terminal 2:
+npm run dev:next                            # → next dev on :3000
+```
+
+## Configuration
+
+The CLI persists state at `$XDG_CONFIG_HOME/dashwise/auth.json` (typically `~/.config/dashwise/auth.json` on macOS/Linux). The file holds:
+
+```jsonc
+{
+  "apiUrl": "http://localhost:3000",
+  "token": "dwc_<base64url>",
+  "tokenId": 42,
+  "user": { "id": 7, "email": "alice@example.com", "username": "alice", "firstName": "Alice", "lastName": "" },
+  "workspaceSlug": "my-team"
+}
+```
+
+- The file is chmod 0600 on Unix; the token is a long-lived bearer credential.
+- `dashwise logout` deletes the file + calls `DELETE /api/auth/cli-tokens/:id` to revoke the server-side row.
+- Move the file to a different user's home and they'll be logged in as you — treat it like an SSH key.
+
+### Environment variables
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `DASHWISE_API_URL` | (saved config) → `http://localhost:3000` | Backend URL |
+| `XDG_CONFIG_HOME` | `~/.config` | Config root |
+| `DASHWISE_DEBUG` | unset | Print full stack traces on uncaught errors |
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Generic failure (network error, validation, unauthorized) |
+| 130 | User cancelled (Ctrl-C / `cancel` from a prompt) |
+
+## License
+
+MIT