state-scenarios-cli 0.3.0 → 0.5.0

package/skills/state-scenarios/references/setup.md

@@ -0,0 +1,94 @@
+# Setup
+
+## Install and init
+
+```bash
+npm i state-scenarios zod msw          # msw only when scenarios mock the network
+npm i -D state-scenarios-cli @playwright/test
+npm i state-scenarios-react            # useScenarioState, for component state (React, Preact)
+
+npx state-scenarios init src/scenarios
+```
+
+`init` writes `src/scenarios/default.json` and `src/scenario.schema.json`, prints a wiring snippet,
+installs these skills into `.agents/skills/` (and `.claude/skills/`), and registers the MCP server
+in `.mcp.json`. It never edits your source files. `--no-skills` skips the skills and the MCP server.
+
+Vite: serve the MSW worker and let the panel save into the project.
+
+```ts
+// vite.config.ts
+import { msw } from 'msw/vite';
+import { stateScenarios } from 'state-scenarios/vite';
+
+export default { plugins: [msw({ mode: 'worker-only' }), stateScenarios({ dir: 'src/scenarios' })] };
+```
+
+Without the MSW Vite plugin: `npx msw init public`.
+
+## Wire the runtime before render
+
+```ts
+import { type ScenarioInput, startScenarios } from 'state-scenarios';
+import { mountPanel } from 'state-scenarios/panel';
+
+if (import.meta.env.DEV) {
+  const session = await startScenarios({
+    scenarios: Object.values(
+      import.meta.glob<ScenarioInput>('/src/scenarios/*.json', { eager: true, import: 'default' }),
+    ),
+    adapters: [], // see below
+    refresh: () => queryClient.resetQueries(), // when scenarios mock the network
+  });
+  mountPanel(session, { schemaPath: '../scenario.schema.json' });
+}
+// then create the router and render
+```
+
+- `await` it before rendering. The first fetches must already hit the scenario's mocks.
+- Routers read the URL once, when they're created. If a module creates the router as soon as it
+  is imported (`export const router = createBrowserRouter(...)`), a static import runs before the
+  session. Import it after:
+
+  ```ts
+  // main.ts: start the session first, then import the router
+  import type { ScenarioInput } from 'state-scenarios';
+
+  if (import.meta.env.DEV) {
+    const { startScenarios } = await import('state-scenarios');
+    await startScenarios({
+      scenarios: Object.values(
+        import.meta.glob<ScenarioInput>('/src/scenarios/*.json', { eager: true, import: 'default' }),
+      ),
+    });
+  }
+
+  const { router } = await import('./routing/router'); // created now, with the scenario's URL
+  ```
+
+- Next.js (App Router): start it from a `'use client'` wrapper in the root layout and render
+  children once it resolves. The package README has the component and the save route.
+- Apps that already run MSW: start your worker and pass it as `worker`. See topic `network`.
+
+## Connect app state
+
+Mock the network first. Add adapters for state no response can produce, such as a panel left open
+or cached data during a refetch.
+
+| State lives in | Connect with                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------ |
+| TanStack Query | `tanstackQuery(queryClient)` from `state-scenarios/tanstack-query`                                           |
+| Zustand        | `zustandAdapter(store, { schema: StoreSchema.partial() })` from `state-scenarios/zustand`                    |
+| Redux          | `withScenarioState(rootReducer, StateSchema)`, then `reduxAdapter(store)`                                    |
+| XState         | `xstateAdapter(machine, { context: ContextSchema })`, then `createActor(machine, { snapshot: xs.snapshot })` |
+| Cookies        | `cookiesAdapter()` from `state-scenarios/cookies`                                                            |
+| A component    | `useScenarioState('page', state, (s) => dispatch({ type: 'set', state: s }), Schema)`                        |
+
+Pass a Zod schema wherever an adapter accepts one: invalid scenario state is then rejected before
+anything changes. `scenarioJsonSchema({ state: { key: Schema } })` regenerates the editor schema
+with typed `state`.
+
+## Check
+
+`npx state-scenarios doctor src/scenarios --base-url http://localhost:5173` passes. Opening
+`/?scenario=default` sets `<html data-scenario="default">`.

package/skills/state-scenarios/references/verify.md

@@ -0,0 +1,47 @@
+# Verify a UI change across every state
+
+Start the dev server, then:
+
+```bash
+npx state-scenarios shoot src/scenarios --base-url http://localhost:5173 --out .scenario-shots
+```
+
+For each scenario `shoot` opens the link in strict mode, waits for `ready`, saves `<name>.png`, and
+checks for unmocked requests, uncaught exceptions and `console.error` calls. `--only a,b` limits
+the run; `--json` prints the report for scripts.
+
+## When a scenario fails
+
+The terminal names a page for it: `❯ details .scenario-shots/<name>.md`. Read that page. It has:
+
+- the codes (`READY_TIMEOUT`, `UNMOCKED_REQUEST`, `SESSION_NOT_STARTED`, `SCENARIO_NOT_IN_APP`, `PAGE_ERROR`,
+  `CONSOLE_ERROR`, `ELEMENT_NOT_FOUND`) and the link that reopens the state;
+- for a ready timeout, whether the selector matched anything, plus distinctive selectors on the
+  page now;
+- for unmocked requests, `network` entries ready to paste (fill in real bodies, or record them);
+- uncaught exceptions and console errors.
+
+Look at the screenshot before changing the scenario: a ready timeout can mean the selector is
+wrong, or that the UI change broke the state. Fix the app when the screenshot shows a bug.
+
+## Evidence
+
+Look at the PNGs for the states the change touches, plus loading, empty and error. Attach the
+relevant ones to the PR. Pages for passing scenarios are deleted on each run, so the `.md` files
+in the output folder are always the current failures.
+
+## In Playwright tests
+
+```ts
+import { openScenario, unhandledRequests } from 'state-scenarios/playwright';
+
+await openScenario(page, 'orders-empty');
+expect(await unhandledRequests(page)).toEqual([]);
+```
+
+## Missing states
+
+Ask which states lack scenarios: loading, empty, error, partial data, long content, permissions,
+signed out. Capture them (topic `capture`). `npx state-scenarios suggest` asks a model to list
+candidate states from the source and drafts them into `proposed/`; treat drafts as ideas, then
+`promote` the reviewed ones.

package/skills/state-scenarios/references/writing-scenarios.md

@@ -0,0 +1,55 @@
+# Writing scenarios
+
+| Field                 | Meaning                                                                                                                                   | Through `extends`                                                        |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `name`                | kebab-case, unique                                                                                                                        | –                                                                        |
+| `extends`             | Scenario name(s) to build on; later parents win                                                                                           | –                                                                        |
+| `path`                | Route it opens at, e.g. `/orders/42`                                                                                                      | inherited                                                                |
+| `url`                 | Query params the app starts with                                                                                                          | merged; `null` removes                                                   |
+| `network[]`           | `method`, `path` (MSW syntax: `/api/users/:id`, absolute URLs, `*`), optional `query`, then one of `response`, `sequence`, `remove: true` | a child entry replaces the parent's with the same method, path and query |
+| `handlers`            | Names of MSW handlers passed to `startScenarios({ handlers })`                                                                            | combined                                                                 |
+| `state`               | Per-adapter state, keyed by adapter key                                                                                                   | deep-merged; `null` removes                                              |
+| `ready`               | Playwright selector visible once this state shows                                                                                         | not inherited                                                            |
+| `viewport`            | `{ "width": 390, "height": 844 }` for `shoot` and `record`                                                                                | inherited                                                                |
+| `description`, `tags` | For people and the panel                                                                                                                  | not inherited                                                            |
+
+Responses: `body` is sent as JSON, `text` as text (an HTML error page). `status` defaults to 200.
+`headers` sets headers. `delay` is milliseconds, or `"infinite"` to hold the request open for a
+loading state. `sequence` answers successive calls in order and repeats the last one, e.g. fail
+then succeed on retry:
+
+```json
+{
+  "name": "flaky-then-recovers",
+  "extends": "default",
+  "network": [{
+    "path": "/api/orders",
+    "sequence": [{ "status": 503, "body": { "error": "busy" } }, { "body": [{ "id": 1 }] }]
+  }],
+  "ready": "text=Order #1"
+}
+```
+
+Loading state: `"response": { "delay": "infinite" }` and `"ready": "text=Loading orders…"`.
+
+## Ready selectors
+
+`text=No orders yet`, `role=heading[name="Orders"]`, `[data-testid=empty-orders]`, or CSS. Pick
+something that is visible only in this state: a count like "0" or a heading every state shares is
+too generic. Check it against the running app (panel, or MCP `check_ready`) before saving.
+
+## Combining
+
+`?scenario=signed-in,server-error` combines scenarios like `extends`, later names winning.
+
+## Rules and validation
+
+`defineScenarioRules` checks business rules on every resolved scenario. Export `rules` from a module
+and pass it to `startScenarios({ rules })` and `--rules` on the CLI.
+
+```bash
+npx state-scenarios validate src/scenarios --rules src/scenario-rules.ts
+```
+
+Schema shape, `extends` lookups and rules are checked. Whether production can actually reach a
+state is your call: a valid scenario can describe a response the backend never sends.

package/dist/init-VLZQEJRD.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/init.ts"],"sourcesContent":["import { existsSync, mkdirSync, writeFileSync } from 'node:fs';\nimport { dirname, join, relative, resolve } from 'node:path';\nimport { scenarioJsonSchema } from 'state-scenarios';\n\n/** Create a scenarios dir, schema, default stub, and print a wiring snippet. */\nexport function initScenarios(scenariosDir: string, cwd = process.cwd()) {\n  const dir = resolve(cwd, scenariosDir);\n  mkdirSync(dir, { recursive: true });\n\n  const schemaPath = join(dirname(dir), 'scenario.schema.json');\n  const defaultPath = join(dir, 'default.json');\n  const schemaRel = relative(dir, schemaPath).replaceAll('\\\\', '/');\n\n  const schemaExisted = existsSync(schemaPath);\n  const defaultExisted = existsSync(defaultPath);\n\n  if (!schemaExisted) {\n    writeFileSync(schemaPath, `${JSON.stringify(scenarioJsonSchema(), null, 2)}\\n`);\n  }\n\n  if (!defaultExisted) {\n    writeFileSync(\n      defaultPath,\n      `${\n        JSON.stringify(\n          {\n            $schema: schemaRel,\n            name: 'default',\n            description: 'Happy path: record the real network, then Save as scenario from the panel',\n          },\n          null,\n          2,\n        )\n      }\\n`,\n    );\n  }\n\n  const stack = detectStack(cwd);\n  const scenariosImport = relative(cwd, dir).replaceAll('\\\\', '/');\n\n  console.log(`${defaultExisted ? 'Kept existing' : 'Created'} ${relative(cwd, defaultPath)}`);\n  console.log(`${schemaExisted ? 'Kept existing' : 'Created'} ${relative(cwd, schemaPath)}`);\n  console.log('');\n  console.log('Wire the runtime (DEV only), then open the app with ?scenario-record,');\n  console.log('click through the flow, Mark ready, and Download JSON into this folder.');\n  console.log('');\n  console.log(wiringSnippet(stack, scenariosImport));\n}\n\ntype Stack = 'vite' | 'next' | 'unknown';\n\nfunction detectStack(cwd: string): Stack {\n  if (hasFile(cwd, ['next.config.ts', 'next.config.js', 'next.config.mjs', 'next.config.cjs'])) {\n    return 'next';\n  }\n\n  if (hasFile(cwd, ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cjs'])) {\n    return 'vite';\n  }\n\n  return 'unknown';\n}\n\nfunction hasFile(cwd: string, names: string[]): boolean {\n  return names.some((name) => existsSync(join(cwd, name)));\n}\n\nfunction wiringSnippet(stack: Stack, scenariosImport: string): string {\n  // Root-relative: Vite resolves '/…' globs from the project root, wherever the snippet is pasted.\n  const glob = `import.meta.glob<ScenarioInput>('${\n    scenariosImport ? `/${scenariosImport}` : ''\n  }/*.json', { eager: true, import: 'default' })`;\n\n  if (stack === 'next') {\n    return `// Next.js (App Router): wrap children in a client <Scenarios> gate (see README).\n// List scenario JSON imports explicitly (Next has no import.meta.glob).\n// Serve the MSW worker with: npx msw init public\n//\n// mountPanel(session, { schemaPath: '../scenario.schema.json' });\n//\n// Let the panel save into ${scenariosImport || '.'}: create app/%5F%5Fstate-scenarios/save/route.ts with\n//   import { createSaveRoute } from 'state-scenarios/next';\n//   export const { GET } = createSaveRoute({ dir: '${scenariosImport || '.'}' });`;\n  }\n\n  const plugins = `import { msw } from 'msw/vite';\n//   import { stateScenarios } from 'state-scenarios/vite';\n//   plugins: [msw({ mode: 'worker-only' }), stateScenarios({ dir: '${scenariosImport || '.'}' })]\n// stateScenarios lets the panel save scenarios straight into this folder.`;\n\n  const viteNote = stack === 'vite'\n    ? `// In vite.config.ts:\\n//   ${plugins}`\n    : `// Vite, in vite.config.ts:\\n//   ${plugins}\n// Next: see README \"Next.js (App Router)\"`;\n\n  return `${viteNote}\n\nimport { type ScenarioInput, startScenarios } from 'state-scenarios';\nimport { mountPanel } from 'state-scenarios/panel';\n// import { tanstackQuery } from 'state-scenarios/tanstack-query'; // if you use it\n\nif (import.meta.env.DEV) {\n  const session = await startScenarios({\n    scenarios: Object.values(${glob}),\n    // adapters: [tanstackQuery(queryClient)],\n    // refresh: () => queryClient.resetQueries(),\n  });\n  mountPanel(session, { schemaPath: '../scenario.schema.json' });\n}\n\n// Then: open /?scenario-record → use the app → panel → Mark ready → Download JSON`;\n}\n"],"mappings":";AAAA,SAAS,YAAY,WAAW,qBAAqB;AACrD,SAAS,SAAS,MAAM,UAAU,eAAe;AACjD,SAAS,0BAA0B;AAG5B,SAAS,cAAc,cAAsB,MAAM,QAAQ,IAAI,GAAG;AACvE,QAAM,MAAM,QAAQ,KAAK,YAAY;AACrC,YAAU,KAAK,EAAE,WAAW,KAAK,CAAC;AAElC,QAAM,aAAa,KAAK,QAAQ,GAAG,GAAG,sBAAsB;AAC5D,QAAM,cAAc,KAAK,KAAK,cAAc;AAC5C,QAAM,YAAY,SAAS,KAAK,UAAU,EAAE,WAAW,MAAM,GAAG;AAEhE,QAAM,gBAAgB,WAAW,UAAU;AAC3C,QAAM,iBAAiB,WAAW,WAAW;AAE7C,MAAI,CAAC,eAAe;AAClB,kBAAc,YAAY,GAAG,KAAK,UAAU,mBAAmB,GAAG,MAAM,CAAC,CAAC;AAAA,CAAI;AAAA,EAChF;AAEA,MAAI,CAAC,gBAAgB;AACnB;AAAA,MACE;AAAA,MACA,GACE,KAAK;AAAA,QACH;AAAA,UACE,SAAS;AAAA,UACT,MAAM;AAAA,UACN,aAAa;AAAA,QACf;AAAA,QACA;AAAA,QACA;AAAA,MACF,CACF;AAAA;AAAA,IACF;AAAA,EACF;AAEA,QAAM,QAAQ,YAAY,GAAG;AAC7B,QAAM,kBAAkB,SAAS,KAAK,GAAG,EAAE,WAAW,MAAM,GAAG;AAE/D,UAAQ,IAAI,GAAG,iBAAiB,kBAAkB,SAAS,IAAI,SAAS,KAAK,WAAW,CAAC,EAAE;AAC3F,UAAQ,IAAI,GAAG,gBAAgB,kBAAkB,SAAS,IAAI,SAAS,KAAK,UAAU,CAAC,EAAE;AACzF,UAAQ,IAAI,EAAE;AACd,UAAQ,IAAI,uEAAuE;AACnF,UAAQ,IAAI,yEAAyE;AACrF,UAAQ,IAAI,EAAE;AACd,UAAQ,IAAI,cAAc,OAAO,eAAe,CAAC;AACnD;AAIA,SAAS,YAAY,KAAoB;AACvC,MAAI,QAAQ,KAAK,CAAC,kBAAkB,kBAAkB,mBAAmB,iBAAiB,CAAC,GAAG;AAC5F,WAAO;AAAA,EACT;AAEA,MAAI,QAAQ,KAAK,CAAC,kBAAkB,kBAAkB,mBAAmB,iBAAiB,CAAC,GAAG;AAC5F,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAEA,SAAS,QAAQ,KAAa,OAA0B;AACtD,SAAO,MAAM,KAAK,CAAC,SAAS,WAAW,KAAK,KAAK,IAAI,CAAC,CAAC;AACzD;AAEA,SAAS,cAAc,OAAc,iBAAiC;AAEpE,QAAM,OAAO,oCACX,kBAAkB,IAAI,eAAe,KAAK,EAC5C;AAEA,MAAI,UAAU,QAAQ;AACpB,WAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,6BAMkB,mBAAmB,GAAG;AAAA;AAAA,sDAEG,mBAAmB,GAAG;AAAA,EAC1E;AAEA,QAAM,UAAU;AAAA;AAAA,sEAEoD,mBAAmB,GAAG;AAAA;AAG1F,QAAM,WAAW,UAAU,SACvB;AAAA,OAA+B,OAAO,KACtC;AAAA,OAAqC,OAAO;AAAA;AAGhD,SAAO,GAAG,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,+BAQW,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQnC;","names":[]}