state-scenarios-cli 0.2.0 → 0.4.0

package/dist/doctor-URGIFA3W.js

@@ -0,0 +1,200 @@
+import {
+  checkServer,
+  contextOptions,
+  launchChromium,
+  scenarioLink
+} from "./chunk-O6QTNAAZ.js";
+import {
+  CliError
+} from "./chunk-GCYOLAFU.js";
+import {
+  inspectScenario
+} from "./chunk-YFNROT3R.js";
+
+// src/doctor.ts
+import { spawnSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var message = (err) => (err instanceof Error ? err.message : err).split("\n")[0] ?? "";
+async function runDoctor({ dir, baseURL, loadCatalog, flags, cwd = process.cwd() }) {
+  const checks = [];
+  const fail = (name, err, fix) => checks.push({
+    name,
+    status: "fail",
+    detail: message(err),
+    code: err instanceof CliError ? err.code : void 0,
+    fix
+  });
+  let catalog;
+  try {
+    catalog = loadCatalog();
+    const problems = catalog.check();
+    if (problems.length) {
+      fail(
+        "scenarios",
+        `${problems.length} invalid: ${problems[0]}`,
+        "state-scenarios validate lists them all"
+      );
+    } else checks.push({ name: "scenarios", status: "ok", detail: `${catalog.list.length} in ${dir}` });
+  } catch (err) {
+    fail("scenarios", err instanceof Error ? err : String(err), "state-scenarios validate explains it");
+  }
+  checks.push(...setupChecks(cwd));
+  try {
+    await checkServer(baseURL);
+    checks.push({ name: "dev server", status: "ok", detail: baseURL });
+  } catch (err) {
+    fail("dev server", err instanceof Error ? err : String(err));
+    return checks;
+  }
+  const resolved = (catalog?.list ?? []).flatMap((s) => {
+    try {
+      return [catalog?.resolve(s) ?? s];
+    } catch {
+      return [];
+    }
+  });
+  const mocks = resolved.some((r) => !!r.network?.length || !!r.handlers?.length);
+  if (mocks) {
+    const worker = await fetch(new URL("/mockServiceWorker.js", baseURL)).catch(() => void 0);
+    if (worker?.ok && worker.headers.get("content-type")?.includes("javascript")) {
+      checks.push({ name: "MSW worker", status: "ok", detail: "/mockServiceWorker.js is served" });
+    } else {
+      checks.push({
+        name: "MSW worker",
+        status: "fail",
+        code: "WORKER_NOT_SERVED",
+        detail: "Scenarios mock the network, but /mockServiceWorker.js is not served",
+        fix: "Vite: add msw({ mode: 'worker-only' }) from msw/vite to plugins. Otherwise: npx msw init public"
+      });
+    }
+  }
+  const browser = await launchChromium().catch((err) => err);
+  if (browser instanceof Error) {
+    fail("browser", browser);
+    return checks;
+  }
+  try {
+    const context = await browser.newContext({ baseURL, ...contextOptions(void 0, flags) });
+    const page = await context.newPage();
+    page.setDefaultTimeout(1e4);
+    const scenario = resolved.find((r) => r.name === "default") ?? resolved[0];
+    if (!scenario) {
+      await page.goto("/?scenario=");
+      const started = await page.waitForFunction(() => globalThis.stateScenariosPage, null, {
+        timeout: 1e4
+      }).then(() => true, () => false);
+      checks.push(
+        started ? { name: "session", status: "ok", detail: "startScenarios runs on page load" } : {
+          name: "session",
+          status: "fail",
+          code: "SESSION_NOT_STARTED",
+          detail: "startScenarios never ran on page load",
+          fix: SESSION_FIX
+        }
+      );
+    } else {
+      const result = await inspectScenario(page, scenario, { link: scenarioLink(baseURL, scenario) });
+      if (result.codes.includes("SESSION_NOT_STARTED")) {
+        checks.push({
+          name: "session",
+          status: "fail",
+          code: "SESSION_NOT_STARTED",
+          detail: `"${scenario.name}" never became active: ${result.error ?? ""}`,
+          fix: SESSION_FIX
+        });
+      } else if (result.codes.includes("SCENARIO_NOT_IN_APP")) {
+        checks.push({
+          name: "session",
+          status: "fail",
+          code: "SCENARIO_NOT_IN_APP",
+          detail: `The session runs, but the app has no scenario "${scenario.name}"`,
+          fix: `The app loads scenarios from a different folder or list than ${dir}: pass the folder the app uses, add the file to the app's list (Next.js lists imports by hand), or restart the dev server if the file is new`
+        });
+      } else {
+        checks.push({ name: "session", status: "ok", detail: `"${scenario.name}" opens: ${result.link}` });
+        if (result.codes.includes("READY_TIMEOUT")) {
+          checks.push({
+            name: "ready",
+            status: "warn",
+            code: "READY_TIMEOUT",
+            detail: `"${scenario.name}" never showed ${scenario.ready}`,
+            fix: result.ready?.suggestions.length ? `Selectors on the page: ${result.ready.suggestions.join(", ")}` : void 0
+          });
+        }
+        if (result.unhandled.length) {
+          checks.push({
+            name: "network",
+            status: "warn",
+            code: "UNMOCKED_REQUEST",
+            detail: `"${scenario.name}" left ${result.unhandled.length} request(s) unmocked, e.g. ${result.unhandled[0]}`,
+            fix: "Mock them in the scenario, or list third-party SDKs in startScenarios({ ignore })"
+          });
+        }
+        const hooks = await page.evaluate(() => !!globalThis.stateScenariosPage);
+        if (!hooks) {
+          checks.push({
+            name: "agent hooks",
+            status: "warn",
+            detail: "The app runs an older state-scenarios: shoot can't explain ready failures and mcp can't save",
+            fix: "Upgrade state-scenarios in the app to match the CLI"
+          });
+        }
+        const save = await page.evaluate(async (endpoint) => {
+          const res = await fetch(endpoint).catch(() => void 0);
+          return res?.ok ? JSON.stringify(await res.json()) : null;
+        }, "/__state-scenarios/save");
+        checks.push(
+          save ? {
+            name: "save to project",
+            status: "ok",
+            detail: `The panel saves into ${JSON.parse(save).dir}`
+          } : {
+            name: "save to project",
+            status: "warn",
+            detail: "The panel can only Download JSON",
+            fix: "Vite: stateScenarios({ dir }) from 'state-scenarios/vite'. Next.js: createSaveRoute (README)"
+          }
+        );
+      }
+    }
+  } catch (err) {
+    fail("session", err instanceof Error ? err : String(err));
+  } finally {
+    await browser.close();
+  }
+  return checks;
+}
+var SESSION_FIX = 'Await startScenarios before rendering, outside production-only code. If the router is created when its module loads, import it after startScenarios: const { router } = await import("./router")';
+function setupChecks(cwd) {
+  const ffmpeg = spawnSync(process.env.FFMPEG_PATH || "ffmpeg", ["-version"]);
+  const mcp = [".mcp.json", ".cursor/mcp.json"].some((f) => {
+    const path = join(cwd, f);
+    return existsSync(path) && readFileSync(path, "utf8").includes('"state-scenarios"');
+  });
+  return [
+    ffmpeg.error ? {
+      name: "ffmpeg",
+      status: "warn",
+      code: "FFMPEG_MISSING",
+      detail: "Not found: record can only save uncropped WebM",
+      fix: "Install from https://ffmpeg.org/download.html or set FFMPEG_PATH"
+    } : { name: "ffmpeg", status: "ok", detail: "Found, for record" },
+    existsSync(join(cwd, ".agents/skills/state-scenarios")) ? { name: "agent skills", status: "ok", detail: ".agents/skills/state-scenarios" } : {
+      name: "agent skills",
+      status: "warn",
+      detail: "Not installed",
+      fix: "npx state-scenarios init installs them"
+    },
+    mcp ? { name: "MCP server", status: "ok", detail: "Registered for coding agents" } : {
+      name: "MCP server",
+      status: "warn",
+      detail: "Not registered",
+      fix: "npx state-scenarios init registers it"
+    }
+  ];
+}
+export {
+  runDoctor
+};
+//# sourceMappingURL=doctor-URGIFA3W.js.map

package/dist/doctor-URGIFA3W.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/doctor.ts"],"sourcesContent":["import { spawnSync } from 'node:child_process';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport type { Catalog } from 'state-scenarios';\nimport { type BrowserFlags, checkServer, contextOptions, launchChromium, scenarioLink } from './browser.js';\nimport { CliError, type ErrorCode } from './errors.js';\nimport { inspectScenario } from './inspect.js';\n\nexport interface Check {\n  name: string;\n  status: 'ok' | 'warn' | 'fail';\n  detail: string;\n  code?: ErrorCode;\n  fix?: string;\n}\n\nconst message = (err: Error | string) => (err instanceof Error ? err.message : err).split('\\n')[0] ?? '';\n\n/**\n * Answer \"is this app wired up and worth driving?\" one check at a time, each with its fix.\n * Read-only: it opens one scenario and writes nothing.\n */\nexport async function runDoctor(\n  { dir, baseURL, loadCatalog, flags, cwd = process.cwd() }: {\n    dir: string;\n    baseURL: string;\n    loadCatalog: () => Catalog;\n    flags: BrowserFlags;\n    cwd?: string;\n  },\n): Promise<Check[]> {\n  const checks: Check[] = [];\n\n  const fail = (name: string, err: Error | string, fix?: string) =>\n    checks.push({\n      name,\n      status: 'fail',\n      detail: message(err),\n      code: err instanceof CliError ? err.code : undefined,\n      fix,\n    });\n\n  let catalog: Catalog | undefined;\n\n  try {\n    catalog = loadCatalog();\n    const problems = catalog.check();\n\n    if (problems.length) {\n      fail(\n        'scenarios',\n        `${problems.length} invalid: ${problems[0]}`,\n        'state-scenarios validate lists them all',\n      );\n    } else checks.push({ name: 'scenarios', status: 'ok', detail: `${catalog.list.length} in ${dir}` });\n  } catch (err) {\n    fail('scenarios', err instanceof Error ? err : String(err), 'state-scenarios validate explains it');\n  }\n\n  checks.push(...setupChecks(cwd));\n\n  try {\n    await checkServer(baseURL);\n    checks.push({ name: 'dev server', status: 'ok', detail: baseURL });\n  } catch (err) {\n    fail('dev server', err instanceof Error ? err : String(err));\n\n    return checks;\n  }\n\n  // Scenarios that fail to resolve are reported above; the rest can still be checked.\n  const resolved = (catalog?.list ?? []).flatMap((s) => {\n    try {\n      return [catalog?.resolve(s) ?? s];\n    } catch {\n      return [];\n    }\n  });\n\n  const mocks = resolved.some((r) => !!r.network?.length || !!r.handlers?.length);\n\n  if (mocks) {\n    const worker = await fetch(new URL('/mockServiceWorker.js', baseURL)).catch(() => undefined);\n\n    if (worker?.ok && worker.headers.get('content-type')?.includes('javascript')) {\n      checks.push({ name: 'MSW worker', status: 'ok', detail: '/mockServiceWorker.js is served' });\n    } else {\n      checks.push({\n        name: 'MSW worker',\n        status: 'fail',\n        code: 'WORKER_NOT_SERVED',\n        detail: 'Scenarios mock the network, but /mockServiceWorker.js is not served',\n        fix:\n          \"Vite: add msw({ mode: 'worker-only' }) from msw/vite to plugins. Otherwise: npx msw init public\",\n      });\n    }\n  }\n\n  const browser = await launchChromium().catch((err: Error) => err);\n\n  if (browser instanceof Error) {\n    fail('browser', browser);\n\n    return checks;\n  }\n\n  try {\n    const context = await browser.newContext({ baseURL, ...contextOptions(undefined, flags) });\n    const page = await context.newPage();\n    page.setDefaultTimeout(10_000);\n    const scenario = resolved.find((r) => r.name === 'default') ?? resolved[0];\n\n    if (!scenario) {\n      await page.goto('/?scenario=');\n\n      const started = await page.waitForFunction(() => globalThis.stateScenariosPage, null, {\n        timeout: 10_000,\n      })\n        .then(() => true, () => false);\n\n      checks.push(\n        started\n          ? { name: 'session', status: 'ok', detail: 'startScenarios runs on page load' }\n          : {\n            name: 'session',\n            status: 'fail',\n            code: 'SESSION_NOT_STARTED',\n            detail: 'startScenarios never ran on page load',\n            fix: SESSION_FIX,\n          },\n      );\n    } else {\n      const result = await inspectScenario(page, scenario, { link: scenarioLink(baseURL, scenario) });\n\n      if (result.codes.includes('SESSION_NOT_STARTED')) {\n        checks.push({\n          name: 'session',\n          status: 'fail',\n          code: 'SESSION_NOT_STARTED',\n          detail: `\"${scenario.name}\" never became active: ${result.error ?? ''}`,\n          fix: SESSION_FIX,\n        });\n      } else if (result.codes.includes('SCENARIO_NOT_IN_APP')) {\n        checks.push({\n          name: 'session',\n          status: 'fail',\n          code: 'SCENARIO_NOT_IN_APP',\n          detail: `The session runs, but the app has no scenario \"${scenario.name}\"`,\n          fix:\n            `The app loads scenarios from a different folder or list than ${dir}: pass the folder the app uses, add the file to the app's list (Next.js lists imports by hand), or restart the dev server if the file is new`,\n        });\n      } else {\n        checks.push({ name: 'session', status: 'ok', detail: `\"${scenario.name}\" opens: ${result.link}` });\n\n        if (result.codes.includes('READY_TIMEOUT')) {\n          checks.push({\n            name: 'ready',\n            status: 'warn',\n            code: 'READY_TIMEOUT',\n            detail: `\"${scenario.name}\" never showed ${scenario.ready}`,\n            fix: result.ready?.suggestions.length\n              ? `Selectors on the page: ${result.ready.suggestions.join(', ')}`\n              : undefined,\n          });\n        }\n\n        if (result.unhandled.length) {\n          checks.push({\n            name: 'network',\n            status: 'warn',\n            code: 'UNMOCKED_REQUEST',\n            detail: `\"${scenario.name}\" left ${result.unhandled.length} request(s) unmocked, e.g. ${\n              result.unhandled[0]\n            }`,\n            fix: 'Mock them in the scenario, or list third-party SDKs in startScenarios({ ignore })',\n          });\n        }\n\n        const hooks = await page.evaluate(() => !!globalThis.stateScenariosPage);\n\n        if (!hooks) {\n          checks.push({\n            name: 'agent hooks',\n            status: 'warn',\n            detail:\n              \"The app runs an older state-scenarios: shoot can't explain ready failures and mcp can't save\",\n            fix: 'Upgrade state-scenarios in the app to match the CLI',\n          });\n        }\n\n        const save = await page.evaluate(async (endpoint) => {\n          const res = await fetch(endpoint).catch(() => undefined);\n\n          return res?.ok ? JSON.stringify(await res.json()) : null;\n        }, '/__state-scenarios/save');\n\n        checks.push(\n          save\n            ? {\n              name: 'save to project',\n              status: 'ok',\n              detail: `The panel saves into ${JSON.parse(save).dir}`,\n            }\n            : {\n              name: 'save to project',\n              status: 'warn',\n              detail: 'The panel can only Download JSON',\n              fix:\n                \"Vite: stateScenarios({ dir }) from 'state-scenarios/vite'. Next.js: createSaveRoute (README)\",\n            },\n        );\n      }\n    }\n  } catch (err) {\n    // Report, don't throw: the checks so far are the answer, and --json must stay valid.\n    fail('session', err instanceof Error ? err : String(err));\n  } finally {\n    await browser.close();\n  }\n\n  return checks;\n}\n\nconst SESSION_FIX =\n  'Await startScenarios before rendering, outside production-only code. If the router is created when its module loads, import it after startScenarios: const { router } = await import(\"./router\")';\n\n/** Checks that need no browser: ffmpeg for record, and whether agents can find the skills and MCP server. */\nfunction setupChecks(cwd: string): Check[] {\n  const ffmpeg = spawnSync(process.env.FFMPEG_PATH || 'ffmpeg', ['-version']);\n\n  const mcp = ['.mcp.json', '.cursor/mcp.json'].some((f) => {\n    const path = join(cwd, f);\n\n    return existsSync(path) && readFileSync(path, 'utf8').includes('\"state-scenarios\"');\n  });\n\n  return [\n    ffmpeg.error\n      ? {\n        name: 'ffmpeg',\n        status: 'warn',\n        code: 'FFMPEG_MISSING',\n        detail: 'Not found: record can only save uncropped WebM',\n        fix: 'Install from https://ffmpeg.org/download.html or set FFMPEG_PATH',\n      }\n      : { name: 'ffmpeg', status: 'ok', detail: 'Found, for record' },\n    existsSync(join(cwd, '.agents/skills/state-scenarios'))\n      ? { name: 'agent skills', status: 'ok', detail: '.agents/skills/state-scenarios' }\n      : {\n        name: 'agent skills',\n        status: 'warn',\n        detail: 'Not installed',\n        fix: 'npx state-scenarios init installs them',\n      },\n    mcp\n      ? { name: 'MCP server', status: 'ok', detail: 'Registered for coding agents' }\n      : {\n        name: 'MCP server',\n        status: 'warn',\n        detail: 'Not registered',\n        fix: 'npx state-scenarios init registers it',\n      },\n  ];\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA,SAAS,iBAAiB;AAC1B,SAAS,YAAY,oBAAoB;AACzC,SAAS,YAAY;AAcrB,IAAM,UAAU,CAAC,SAAyB,eAAe,QAAQ,IAAI,UAAU,KAAK,MAAM,IAAI,EAAE,CAAC,KAAK;AAMtG,eAAsB,UACpB,EAAE,KAAK,SAAS,aAAa,OAAO,MAAM,QAAQ,IAAI,EAAE,GAOtC;AAClB,QAAM,SAAkB,CAAC;AAEzB,QAAM,OAAO,CAAC,MAAc,KAAqB,QAC/C,OAAO,KAAK;AAAA,IACV;AAAA,IACA,QAAQ;AAAA,IACR,QAAQ,QAAQ,GAAG;AAAA,IACnB,MAAM,eAAe,WAAW,IAAI,OAAO;AAAA,IAC3C;AAAA,EACF,CAAC;AAEH,MAAI;AAEJ,MAAI;AACF,cAAU,YAAY;AACtB,UAAM,WAAW,QAAQ,MAAM;AAE/B,QAAI,SAAS,QAAQ;AACnB;AAAA,QACE;AAAA,QACA,GAAG,SAAS,MAAM,aAAa,SAAS,CAAC,CAAC;AAAA,QAC1C;AAAA,MACF;AAAA,IACF,MAAO,QAAO,KAAK,EAAE,MAAM,aAAa,QAAQ,MAAM,QAAQ,GAAG,QAAQ,KAAK,MAAM,OAAO,GAAG,GAAG,CAAC;AAAA,EACpG,SAAS,KAAK;AACZ,SAAK,aAAa,eAAe,QAAQ,MAAM,OAAO,GAAG,GAAG,sCAAsC;AAAA,EACpG;AAEA,SAAO,KAAK,GAAG,YAAY,GAAG,CAAC;AAE/B,MAAI;AACF,UAAM,YAAY,OAAO;AACzB,WAAO,KAAK,EAAE,MAAM,cAAc,QAAQ,MAAM,QAAQ,QAAQ,CAAC;AAAA,EACnE,SAAS,KAAK;AACZ,SAAK,cAAc,eAAe,QAAQ,MAAM,OAAO,GAAG,CAAC;AAE3D,WAAO;AAAA,EACT;AAGA,QAAM,YAAY,SAAS,QAAQ,CAAC,GAAG,QAAQ,CAAC,MAAM;AACpD,QAAI;AACF,aAAO,CAAC,SAAS,QAAQ,CAAC,KAAK,CAAC;AAAA,IAClC,QAAQ;AACN,aAAO,CAAC;AAAA,IACV;AAAA,EACF,CAAC;AAED,QAAM,QAAQ,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,EAAE,UAAU,MAAM;AAE9E,MAAI,OAAO;AACT,UAAM,SAAS,MAAM,MAAM,IAAI,IAAI,yBAAyB,OAAO,CAAC,EAAE,MAAM,MAAM,MAAS;AAE3F,QAAI,QAAQ,MAAM,OAAO,QAAQ,IAAI,cAAc,GAAG,SAAS,YAAY,GAAG;AAC5E,aAAO,KAAK,EAAE,MAAM,cAAc,QAAQ,MAAM,QAAQ,kCAAkC,CAAC;AAAA,IAC7F,OAAO;AACL,aAAO,KAAK;AAAA,QACV,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,MAAM;AAAA,QACN,QAAQ;AAAA,QACR,KACE;AAAA,MACJ,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,eAAe,EAAE,MAAM,CAAC,QAAe,GAAG;AAEhE,MAAI,mBAAmB,OAAO;AAC5B,SAAK,WAAW,OAAO;AAEvB,WAAO;AAAA,EACT;AAEA,MAAI;AACF,UAAM,UAAU,MAAM,QAAQ,WAAW,EAAE,SAAS,GAAG,eAAe,QAAW,KAAK,EAAE,CAAC;AACzF,UAAM,OAAO,MAAM,QAAQ,QAAQ;AACnC,SAAK,kBAAkB,GAAM;AAC7B,UAAM,WAAW,SAAS,KAAK,CAAC,MAAM,EAAE,SAAS,SAAS,KAAK,SAAS,CAAC;AAEzE,QAAI,CAAC,UAAU;AACb,YAAM,KAAK,KAAK,aAAa;AAE7B,YAAM,UAAU,MAAM,KAAK,gBAAgB,MAAM,WAAW,oBAAoB,MAAM;AAAA,QACpF,SAAS;AAAA,MACX,CAAC,EACE,KAAK,MAAM,MAAM,MAAM,KAAK;AAE/B,aAAO;AAAA,QACL,UACI,EAAE,MAAM,WAAW,QAAQ,MAAM,QAAQ,mCAAmC,IAC5E;AAAA,UACA,MAAM;AAAA,UACN,QAAQ;AAAA,UACR,MAAM;AAAA,UACN,QAAQ;AAAA,UACR,KAAK;AAAA,QACP;AAAA,MACJ;AAAA,IACF,OAAO;AACL,YAAM,SAAS,MAAM,gBAAgB,MAAM,UAAU,EAAE,MAAM,aAAa,SAAS,QAAQ,EAAE,CAAC;AAE9F,UAAI,OAAO,MAAM,SAAS,qBAAqB,GAAG;AAChD,eAAO,KAAK;AAAA,UACV,MAAM;AAAA,UACN,QAAQ;AAAA,UACR,MAAM;AAAA,UACN,QAAQ,IAAI,SAAS,IAAI,0BAA0B,OAAO,SAAS,EAAE;AAAA,UACrE,KAAK;AAAA,QACP,CAAC;AAAA,MACH,WAAW,OAAO,MAAM,SAAS,qBAAqB,GAAG;AACvD,eAAO,KAAK;AAAA,UACV,MAAM;AAAA,UACN,QAAQ;AAAA,UACR,MAAM;AAAA,UACN,QAAQ,kDAAkD,SAAS,IAAI;AAAA,UACvE,KACE,gEAAgE,GAAG;AAAA,QACvE,CAAC;AAAA,MACH,OAAO;AACL,eAAO,KAAK,EAAE,MAAM,WAAW,QAAQ,MAAM,QAAQ,IAAI,SAAS,IAAI,YAAY,OAAO,IAAI,GAAG,CAAC;AAEjG,YAAI,OAAO,MAAM,SAAS,eAAe,GAAG;AAC1C,iBAAO,KAAK;AAAA,YACV,MAAM;AAAA,YACN,QAAQ;AAAA,YACR,MAAM;AAAA,YACN,QAAQ,IAAI,SAAS,IAAI,kBAAkB,SAAS,KAAK;AAAA,YACzD,KAAK,OAAO,OAAO,YAAY,SAC3B,0BAA0B,OAAO,MAAM,YAAY,KAAK,IAAI,CAAC,KAC7D;AAAA,UACN,CAAC;AAAA,QACH;AAEA,YAAI,OAAO,UAAU,QAAQ;AAC3B,iBAAO,KAAK;AAAA,YACV,MAAM;AAAA,YACN,QAAQ;AAAA,YACR,MAAM;AAAA,YACN,QAAQ,IAAI,SAAS,IAAI,UAAU,OAAO,UAAU,MAAM,8BACxD,OAAO,UAAU,CAAC,CACpB;AAAA,YACA,KAAK;AAAA,UACP,CAAC;AAAA,QACH;AAEA,cAAM,QAAQ,MAAM,KAAK,SAAS,MAAM,CAAC,CAAC,WAAW,kBAAkB;AAEvE,YAAI,CAAC,OAAO;AACV,iBAAO,KAAK;AAAA,YACV,MAAM;AAAA,YACN,QAAQ;AAAA,YACR,QACE;AAAA,YACF,KAAK;AAAA,UACP,CAAC;AAAA,QACH;AAEA,cAAM,OAAO,MAAM,KAAK,SAAS,OAAO,aAAa;AACnD,gBAAM,MAAM,MAAM,MAAM,QAAQ,EAAE,MAAM,MAAM,MAAS;AAEvD,iBAAO,KAAK,KAAK,KAAK,UAAU,MAAM,IAAI,KAAK,CAAC,IAAI;AAAA,QACtD,GAAG,yBAAyB;AAE5B,eAAO;AAAA,UACL,OACI;AAAA,YACA,MAAM;AAAA,YACN,QAAQ;AAAA,YACR,QAAQ,wBAAwB,KAAK,MAAM,IAAI,EAAE,GAAG;AAAA,UACtD,IACE;AAAA,YACA,MAAM;AAAA,YACN,QAAQ;AAAA,YACR,QAAQ;AAAA,YACR,KACE;AAAA,UACJ;AAAA,QACJ;AAAA,MACF;AAAA,IACF;AAAA,EACF,SAAS,KAAK;AAEZ,SAAK,WAAW,eAAe,QAAQ,MAAM,OAAO,GAAG,CAAC;AAAA,EAC1D,UAAE;AACA,UAAM,QAAQ,MAAM;AAAA,EACtB;AAEA,SAAO;AACT;AAEA,IAAM,cACJ;AAGF,SAAS,YAAY,KAAsB;AACzC,QAAM,SAAS,UAAU,QAAQ,IAAI,eAAe,UAAU,CAAC,UAAU,CAAC;AAE1E,QAAM,MAAM,CAAC,aAAa,kBAAkB,EAAE,KAAK,CAAC,MAAM;AACxD,UAAM,OAAO,KAAK,KAAK,CAAC;AAExB,WAAO,WAAW,IAAI,KAAK,aAAa,MAAM,MAAM,EAAE,SAAS,mBAAmB;AAAA,EACpF,CAAC;AAED,SAAO;AAAA,IACL,OAAO,QACH;AAAA,MACA,MAAM;AAAA,MACN,QAAQ;AAAA,MACR,MAAM;AAAA,MACN,QAAQ;AAAA,MACR,KAAK;AAAA,IACP,IACE,EAAE,MAAM,UAAU,QAAQ,MAAM,QAAQ,oBAAoB;AAAA,IAChE,WAAW,KAAK,KAAK,gCAAgC,CAAC,IAClD,EAAE,MAAM,gBAAgB,QAAQ,MAAM,QAAQ,iCAAiC,IAC/E;AAAA,MACA,MAAM;AAAA,MACN,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,KAAK;AAAA,IACP;AAAA,IACF,MACI,EAAE,MAAM,cAAc,QAAQ,MAAM,QAAQ,+BAA+B,IAC3E;AAAA,MACA,MAAM;AAAA,MACN,QAAQ;AAAA,MACR,QAAQ;AAAA,MACR,KAAK;AAAA,IACP;AAAA,EACJ;AACF;","names":[]}

package/dist/doctor.d.ts

@@ -0,0 +1,21 @@
+import type { Catalog } from 'state-scenarios';
+import { type BrowserFlags } from './browser.js';
+import { type ErrorCode } from './errors.js';
+export interface Check {
+    name: string;
+    status: 'ok' | 'warn' | 'fail';
+    detail: string;
+    code?: ErrorCode;
+    fix?: string;
+}
+/**
+ * Answer "is this app wired up and worth driving?" one check at a time, each with its fix.
+ * Read-only: it opens one scenario and writes nothing.
+ */
+export declare function runDoctor({ dir, baseURL, loadCatalog, flags, cwd }: {
+    dir: string;
+    baseURL: string;
+    loadCatalog: () => Catalog;
+    flags: BrowserFlags;
+    cwd?: string;
+}): Promise<Check[]>;

package/dist/errors-G7ODRBLT.js

@@ -0,0 +1,11 @@
+import {
+  CliError,
+  ERROR_CLASSES,
+  EXIT_CODES
+} from "./chunk-GCYOLAFU.js";
+export {
+  CliError,
+  ERROR_CLASSES,
+  EXIT_CODES
+};
+//# sourceMappingURL=errors-G7ODRBLT.js.map

package/dist/errors-G7ODRBLT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Stable error codes. The class sets the exit code, so scripts and agents can branch on
+ * either without reading messages: 1 a scenario failed, 2 configuration, 3 infrastructure.
+ */
+export declare const ERROR_CLASSES: {
+    readonly SESSION_NOT_STARTED: 'failed';
+    readonly SCENARIO_NOT_IN_APP: 'failed';
+    readonly READY_TIMEOUT: 'failed';
+    readonly UNMOCKED_REQUEST: 'failed';
+    readonly PAGE_ERROR: 'failed';
+    readonly CONSOLE_ERROR: 'failed';
+    readonly ELEMENT_NOT_FOUND: 'failed';
+    readonly STEPS_FAILED: 'failed';
+    readonly RULE_VIOLATION: 'failed';
+    readonly INVALID_ARGUMENT: 'config';
+    readonly INVALID_SCENARIO: 'config';
+    readonly UNKNOWN_SCENARIO: 'config';
+    readonly DEV_SERVER_DOWN: 'infra';
+    readonly BROWSER_MISSING: 'infra';
+    readonly FFMPEG_MISSING: 'infra';
+    readonly WORKER_NOT_SERVED: 'infra';
+};
+export type ErrorCode = keyof typeof ERROR_CLASSES;
+export declare const EXIT_CODES: {
+    readonly failed: 1;
+    readonly config: 2;
+    readonly infra: 3;
+};
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
+    get exitCode(): 1 | 2 | 3;
+}

package/dist/init-MRK4F5SV.js

@@ -0,0 +1,96 @@
+// src/init.ts
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, join, relative, resolve } from "path";
+import { scenarioJsonSchema } from "state-scenarios";
+function initScenarios(scenariosDir, cwd = process.cwd()) {
+  const dir = resolve(cwd, scenariosDir);
+  mkdirSync(dir, { recursive: true });
+  const schemaPath = join(dirname(dir), "scenario.schema.json");
+  const defaultPath = join(dir, "default.json");
+  const schemaRel = relative(dir, schemaPath).replaceAll("\\", "/");
+  const schemaExisted = existsSync(schemaPath);
+  const defaultExisted = existsSync(defaultPath);
+  if (!schemaExisted) {
+    writeFileSync(schemaPath, `${JSON.stringify(scenarioJsonSchema(), null, 2)}
+`);
+  }
+  if (!defaultExisted) {
+    writeFileSync(
+      defaultPath,
+      `${JSON.stringify(
+        {
+          $schema: schemaRel,
+          name: "default",
+          description: "Happy path: record the real network, then Save as scenario from the panel"
+        },
+        null,
+        2
+      )}
+`
+    );
+  }
+  const stack = detectStack(cwd);
+  const scenariosImport = relative(cwd, dir).replaceAll("\\", "/");
+  console.log(`${defaultExisted ? "Kept existing" : "Created"} ${relative(cwd, defaultPath)}`);
+  console.log(`${schemaExisted ? "Kept existing" : "Created"} ${relative(cwd, schemaPath)}`);
+  console.log("");
+  console.log("Wire the runtime (DEV only), then open the app with ?scenario-record,");
+  console.log("click through the flow, Mark ready, and Download JSON into this folder.");
+  console.log("");
+  console.log(wiringSnippet(stack, scenariosImport));
+  return { stack };
+}
+function detectStack(cwd) {
+  if (hasFile(cwd, ["next.config.ts", "next.config.js", "next.config.mjs", "next.config.cjs"])) {
+    return "next";
+  }
+  if (hasFile(cwd, ["vite.config.ts", "vite.config.js", "vite.config.mjs", "vite.config.cjs"])) {
+    return "vite";
+  }
+  return "unknown";
+}
+function hasFile(cwd, names) {
+  return names.some((name) => existsSync(join(cwd, name)));
+}
+function wiringSnippet(stack, scenariosImport) {
+  const glob = `import.meta.glob<ScenarioInput>('${scenariosImport ? `/${scenariosImport}` : ""}/*.json', { eager: true, import: 'default' })`;
+  if (stack === "next") {
+    return `// Next.js (App Router): wrap children in a client <Scenarios> gate (see README).
+// List scenario JSON imports explicitly (Next has no import.meta.glob).
+// Serve the MSW worker with: npx msw init public
+//
+// mountPanel(session, { schemaPath: '../scenario.schema.json' });
+//
+// Let the panel save into ${scenariosImport || "."}: create app/%5F%5Fstate-scenarios/save/route.ts with
+//   import { createSaveRoute } from 'state-scenarios/next';
+//   export const { GET } = createSaveRoute({ dir: '${scenariosImport || "."}' });`;
+  }
+  const plugins = `import { msw } from 'msw/vite';
+//   import { stateScenarios } from 'state-scenarios/vite';
+//   plugins: [msw({ mode: 'worker-only' }), stateScenarios({ dir: '${scenariosImport || "."}' })]
+// stateScenarios lets the panel save scenarios straight into this folder.`;
+  const viteNote = stack === "vite" ? `// In vite.config.ts:
+//   ${plugins}` : `// Vite, in vite.config.ts:
+//   ${plugins}
+// Next: see README "Next.js (App Router)"`;
+  return `${viteNote}
+
+import { type ScenarioInput, startScenarios } from 'state-scenarios';
+import { mountPanel } from 'state-scenarios/panel';
+// import { tanstackQuery } from 'state-scenarios/tanstack-query'; // if you use it
+
+if (import.meta.env.DEV) {
+  const session = await startScenarios({
+    scenarios: Object.values(${glob}),
+    // adapters: [tanstackQuery(queryClient)],
+    // refresh: () => queryClient.resetQueries(),
+  });
+  mountPanel(session, { schemaPath: '../scenario.schema.json' });
+}
+
+// Then: open /?scenario-record \u2192 use the app \u2192 panel \u2192 Mark ready \u2192 Download JSON`;
+}
+export {
+  initScenarios
+};
+//# sourceMappingURL=init-MRK4F5SV.js.map

package/dist/init-MRK4F5SV.js.map

@@ -0,0 +1 @@
+{"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  return { stack };\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;AAEjD,SAAO,EAAE,MAAM;AACjB;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":[]}

package/dist/init.d.ts

@@ -0,0 +1,6 @@
+/** Create a scenarios dir, schema, default stub, and print a wiring snippet. */
+export declare function initScenarios(scenariosDir: string, cwd?: string): {
+    stack: Stack;
+};
+type Stack = 'vite' | 'next' | 'unknown';
+export {};

package/dist/inspect-LN4EACWA.js

@@ -0,0 +1,13 @@
+import {
+  failurePage,
+  inspectScenario,
+  networkEntryFor,
+  watchErrors
+} from "./chunk-YFNROT3R.js";
+export {
+  failurePage,
+  inspectScenario,
+  networkEntryFor,
+  watchErrors
+};
+//# sourceMappingURL=inspect-LN4EACWA.js.map

package/dist/inspect-LN4EACWA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/inspect.d.ts

@@ -0,0 +1,63 @@
+import type { Page } from '@playwright/test';
+import type { ReadyReport, Scenario } from 'state-scenarios';
+import type { ErrorCode } from './errors.js';
+export interface Inspection {
+    name: string;
+    ok: boolean;
+    /** Why it failed, as stable codes; empty when ok. */
+    codes: ErrorCode[];
+    /** Reopens this state in strict mode. */
+    link: string;
+    unhandled: string[];
+    pageErrors: string[];
+    consoleErrors: string[];
+    error: string | null;
+    /** Set when the ready selector didn't show: what it matched and what would. */
+    ready: (ReadyReport & {
+        selector: string;
+    }) | null;
+}
+/**
+ * Collect uncaught exceptions and console errors from now on. Browser network logs
+ * ("Failed to load resource") are left out: error scenarios cause them on purpose, and
+ * requests the scenario didn't mock are reported as unhandled instead.
+ */
+export declare function watchErrors(page: Page): {
+    pageErrors: string[];
+    consoleErrors: string[];
+};
+/** Open a scenario and report everything an agent needs to fix it. */
+export declare function inspectScenario(page: Page, scenario: Scenario, { link, strict, panel }: {
+    link: string;
+    strict?: boolean;
+    panel?: boolean;
+}): Promise<Inspection>;
+interface DraftEntry {
+    method: string;
+    path: string;
+    query?: Record<string, string>;
+    response: {
+        status: number;
+        body: Record<string, never>;
+    };
+}
+interface DraftEntry {
+    method: string;
+    path: string;
+    query?: Record<string, string>;
+    response: {
+        status: number;
+        body: Record<string, never>;
+    };
+}
+/** A network entry that answers an unmocked request, ready to paste and fill in. */
+export declare function networkEntryFor(label: string, appOrigin: string): DraftEntry;
+/**
+ * The page an agent reads when a scenario fails: what went wrong, the link that reopens it,
+ * and the fix written out where one can be.
+ */
+export declare function failurePage(r: Inspection, { screenshot, appOrigin }: {
+    screenshot: string;
+    appOrigin: string;
+}): string;
+export {};