@dreamboard-games/cli 0.1.30-alpha.4 → 0.1.30-alpha.40

package/README.md

@@ -1,6 +1,6 @@
 # dreamboard
 
-Dreamboard CLI for working with Dreamboard games from your own editor/tooling.
+Dreamboard for working with Dreamboard games from your own editor/tooling.
 
 Dreamboard is built to take you from napkin sketch to playable prototype without the paper cuts:
 
@@ -18,7 +18,7 @@ Published npm package:
 npm install -g dreamboard
 ```
 
-The published CLI targets Node 20+.
+The published `dreamboard` package targets Node 20+.
 
 ## Why Dreamboard
 
@@ -32,16 +32,14 @@ The published CLI targets Node 20+.
 Use browser login:
 
 ```bash
-dreamboard login
+dreamboard auth login
 ```
 
-The published CLI stores your refreshable session in:
+Dreamboard stores your refreshable session in `~/.dreamboard/auth.json` by default. The file is written atomically with owner-only permissions (`0600`).
 
-```bash
-~/.dreamboard/config.json
-```
+The operating system keychain is optional. Set `"credentialBackend": "keychain"` in `~/.dreamboard/config.json`, or use `DREAMBOARD_CREDENTIAL_BACKEND=keychain`, to opt in.
 
-That stored session includes the refresh token the CLI needs to renew access automatically. Direct JWT injection is intentionally not part of the published CLI flow.
+That stored session includes the Clerk refresh token Dreamboard needs to renew and exchange for short-lived Dreamboard API tokens automatically. Direct JWT injection is intentionally not part of the published Dreamboard flow.
 
 ## Source Checkout Setup
 
@@ -51,7 +49,7 @@ For local source-checkout development, install workspace dependencies with pnpm
 pnpm install
 ```
 
-Playwright (for `dreamboard run`):
+Playwright (for local dev-host verification):
 
 ```bash
 npx playwright install
@@ -62,146 +60,67 @@ npx playwright install
 Create a new game:
 
 ```bash
-dreamboard new my-game --description "A trick-taking card game"
+dreamboard project create my-game --description "A trick-taking card game"
 ```
 
-Clone an existing game:
+Clone an existing project:
 
 ```bash
-dreamboard clone my-game
+dreamboard project clone my-game
 ```
 
-Sync local authored changes and regenerate scaffolded files:
+Commit and push authored changes with Git:
 
 ```bash
-dreamboard sync
-dreamboard sync --update-sdk
+git add .
+git commit -m "Update game"
+git push
 ```
 
-If the remote has advanced unexpectedly, reconcile authored changes explicitly with:
+Inspect server state for an exact commit:
 
 ```bash
-dreamboard pull
+dreamboard project status --commit HEAD --wait
 ```
 
-Compile the current authored head:
+Verify an exact commit:
 
 ```bash
-dreamboard compile
-dreamboard compile --skip-local-check
+dreamboard verify --commit HEAD
 ```
 
-Inspect local vs remote state:
+Build or preview a pushed commit:
 
 ```bash
-dreamboard status
-dreamboard status --json
+dreamboard build --commit HEAD
+dreamboard preview --commit HEAD
 ```
 
-Run the game locally (server-compiled UI):
+Run tests:
 
 ```bash
-dreamboard run
-dreamboard run --players 4
-dreamboard run --seed 1337
-dreamboard run --new-session
-```
-
-If no successful compile exists for the current authored state yet, `dreamboard run` will ask you to run `dreamboard compile` first.
-By default, the CLI uses `manifest.json`'s `playerConfig.minPlayers` to decide how many seats to create.
-
-`dreamboard run` now defaults to a wait-and-observe loop when no scenario is provided:
-
-1. Reuse the previous active session (`--resume` defaults to true) unless `--new-session` is set.
-2. Subscribe to session SSE events.
-3. Exit when `YOUR_TURN` (default `--until`) or `GAME_ENDED` is received.
-4. Persist artifacts in `.dreamboard/run/`:
-   - `session.json`
-   - `events.ndjson`
-   - `latest-your-turn.json`
-   - `last-run-summary.json`
-
-`dreamboard run` is deterministic-by-default for new sessions: if `--seed` is not provided, it uses `1337`.
-
-Useful flags:
-
-- `--until YOUR_TURN|GAME_ENDED|ANY`
-- `--observe-events turns|all` (default `turns`; persist `YOUR_TURN` and `ACTION_REJECTED` messages)
-- `--seed <int>` (deterministic RNG seed for new sessions, default `1337`)
-- `--timeout-ms <ms>`
-- `--max-events <count>`
-- `--screenshot` (capture one Playwright screenshot for the selected run session)
-- `--output <path>`
-- `--delay <ms>`
-- `--width <px>`
-- `--height <px>`
-- `--scenario-driver api|ui` (default `api`)
-
-Playwright launch is now optional:
-
-1. It is launched when `--scenario-driver ui` is used.
-2. It is launched when `--screenshot` is used.
-3. Default API scenarios (`--scenario` with `--scenario-driver api`) do not require Playwright.
-4. Pure observe runs (`dreamboard run` without scenario/screenshot) do not require a browser session.
-
-## Scenario Files
-
-`dreamboard run --scenario <file>` supports scenario JSON (API driver by default):
-
-```json
-{
-  "steps": [
-    {
-      "playerId": "player-1",
-      "actionType": "playCard",
-      "parameters": { "cardId": "hearts-7" },
-      "turns": 1
-    },
-    {
-      "playerId": "player-1",
-      "actionType": "endTurn",
-      "parameters": {},
-      "turns": 1
-    }
-  ]
-}
+dreamboard test
+dreamboard test --scenario test/scenarios/main.scenario.ts
 ```
 
-`playerId` is required on every scenario step. The CLI executes all steps in order per invocation:
-
-```bash
-dreamboard run
-dreamboard run --scenario path/to/scenario.json
-dreamboard run --scenario path/to/scenario.json --scenario-driver ui
-```
-
-If there is no current `.dreamboard/run/latest-your-turn.json` for the active session (for example with `--new-session`), `dreamboard run --scenario ...` first observes SSE until it receives the initial `YOUR_TURN`, then starts executing scenario steps.
-
-API-driven scenarios are strict per step: after each `submitAction`, the CLI waits for either `ACTION_EXECUTED` or `ACTION_REJECTED`. On rejection, it stops immediately with `stopReason=scenario_rejected`.
-
-Screenshots are saved to `.dreamboard/screenshots/` by default. The CLI captures the same session selected by `--resume` / `--new-session`.
-
-To capture a screenshot during observe or scenario runs:
+Start the local dev host:
 
 ```bash
-dreamboard run --screenshot
-dreamboard run --scenario path/to/scenario.json --screenshot
-dreamboard run --screenshot --output ./shot.png --delay 1500 --width 1440 --height 900
+dreamboard dev
 ```
 
 ## Notes
 
 - Project state lives in `.dreamboard/project.json`.
-- Snapshots for `status` are stored in `.dreamboard/snapshot.json`.
-- Published/public CLI installs target Node 20+ and support remote workflows.
-- Published/public CLI builds are production-only; they do not support environment overrides or direct JWT injection.
+- Published/public `dreamboard` installs target Node 20+ and support commit-scoped
+  build, preview, release, and status workflows.
+- Published stable `dreamboard` builds are production-only and do not support environment overrides or direct JWT injection. Published alpha builds allow `--env <local|staging|prod>` for operator verification, but still reject direct JWT injection.
 - Local embedded-harness testing remains Bun-only and requires a source checkout with local backend support.
-- Internal source-checkout builds may expose extra auth and environment helpers, but those are not part of the published CLI contract.
+- Internal source-checkout builds may expose extra auth and environment helpers, but those are not part of the published Dreamboard contract.
 
 ## Skill Source
 
 - Public skill source lives under `skills/dreamboard/`.
 - `skills/dreamboard/references/*.md` are generated from `docs/` via `pnpm run sync:skill-docs`.
-- `dreamboard new` installs the bundled skill into `.agents/skills/dreamboard/` in the generated game project.
-- The Node helper script for run-artifact inspection is `.agents/skills/dreamboard/scripts/events-extract.mjs`.
-- Public GitHub repo for the CLI is [dreamboard-games/dreamboard-cli](https://github.com/dreamboard-games/dreamboard-cli).
+- `dreamboard project create` installs the bundled skill into `.agents/skills/dreamboard/` in the generated game project.
+- Public GitHub repo for Dreamboard is [dreamboard-games/dreamboard](https://github.com/dreamboard-games/dreamboard).