executable-stories-init 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# executable-stories-init
+
+Bootstrap [executable-stories](https://github.com/jagreehal/executable-stories) (Vitest and/or Playwright) into a TypeScript repo from zero. Detects your framework, package manager and monorepo layout, installs the right adapter, writes config, drops a sample story, and patches `package.json` scripts.
+
+## Install and run
+
+Run from your project root, no install required:
+
+```bash
+npx executable-stories-init@latest
+```
+
+```bash
+pnpm dlx executable-stories-init
+```
+
+```bash
+yarn dlx executable-stories-init
+```
+
+The wizard is interactive by default. Pass `--yes` (or `--json`) to run non-interactively.
+
+## What it does
+
+For each selected target (repo root, or one or more workspace packages):
+
+1. **Detects** existing Vitest / Playwright installs, an existing config, and TypeScript.
+2. **Installs** `executable-stories-vitest` / `executable-stories-playwright` and `executable-stories-formatters` using your repo's package manager (`pnpm`, `yarn`, or `npm`).
+3. **Writes** `vitest.config.ts` and/or `playwright.config.ts` pre-wired with `StoryReporter` (Markdown + HTML output to `reports/`).
+4. **Writes a sample story**: `tests/sample.story.test.ts` for Vitest, `tests/sample.story.spec.ts` for Playwright.
+5. **Patches `package.json` scripts**: adds `test` (Vitest) and/or `test:e2e` (Playwright).
+6. **Optionally writes `tsconfig.json`** when missing and `--ts` is passed.
+
+Anything already present is left alone (or skipped with a reason). Use `--force` to overwrite differing files.
+
+## Flags
+
+| Flag | Description |
+| ---- | ----------- |
+| `--vitest` | Set up Vitest. |
+| `--playwright` | Set up Playwright. |
+| `--both` | Set up both Vitest and Playwright. |
+| `--target <pkg...>` | Workspace package(s) to set up. Use `root` for the repo root. Repeatable. |
+| `--ts` / `--no-ts` | Write a minimal `tsconfig.json` if missing. |
+| `-y`, `--yes` | Non-interactive; accept defaults. |
+| `--interactive` | Force prompts even when piped. |
+| `--dry-run` | Print the plan; do not write or install. |
+| `--force` | Overwrite differing existing files. |
+| `--json` | Machine-readable output. Implies `--yes`. Requires `--vitest` / `--playwright` / `--both`. |
+
+## Examples
+
+Single-package repo, Vitest only:
+
+```bash
+npx executable-stories-init@latest --vitest --yes
+```
+
+Monorepo, Vitest in two packages and Playwright at the root:
+
+```bash
+npx executable-stories-init@latest --vitest --target packages/api --target packages/web
+npx executable-stories-init@latest --playwright --target root
+```
+
+Preview without changes:
+
+```bash
+npx executable-stories-init@latest --both --dry-run
+```
+
+CI / scripting:
+
+```bash
+npx executable-stories-init@latest --both --target root --json
+```
+
+## After it runs
+
+```bash
+cd <target>           # repeat per selected target
+<pm> install          # if you ran with --dry-run, or just to be sure
+<pm> run test         # Vitest stories
+<pm> run test:e2e     # Playwright stories (if installed)
+```
+
+Open the generated report:
+
+```bash
+# macOS
+open reports/executable-stories.html
+# Linux
+xdg-open reports/executable-stories.html
+# Windows
+start reports\executable-stories.html
+```
+
+Playwright also needs browsers on first use:
+
+```bash
+pnpm exec playwright install      # pnpm
+npm exec playwright install       # npm
+yarn playwright install           # yarn
+```
+
+## Detection rules
+
+- **Package manager** is taken from `packageManager` in the root `package.json`, then `pnpm-lock.yaml`, then `yarn.lock`, falling back to `npm`.
+- **Monorepo** is detected from `pnpm-workspace.yaml` (`packages:` entries) or `workspaces` in `package.json` (array or `{ packages: [...] }`).
+- **Already set up?** If the framework is already a dependency, install is skipped; if a `vitest.config.*` / `playwright.config.*` exists, the config write is skipped unless `--force` is passed.
+
+## Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| `0` | Success. |
+| `1` | Plan applied with failures (e.g. install failed). |
+| `2` | Invalid CLI usage (e.g. `--json` without a framework). |
+| `130` | Cancelled by user (prompt aborted or no targets selected). |

package/dist/cli/index.js

@@ -0,0 +1,621 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import process3 from "process";
+import { resolve } from "path";
+import * as p3 from "@clack/prompts";
+
+// src/factory.ts
+import process from "process";
+import { mkdir, readFile, writeFile, access } from "fs/promises";
+import { spawn as nodeSpawn } from "child_process";
+function buildOpts(flags) {
+  const isTty = process.stdin.isTTY ?? false;
+  const json = Boolean(flags.json);
+  const yes = Boolean(flags.yes);
+  const interactive = !yes && !json && (Boolean(flags.interactive) || isTty);
+  return { json, interactive };
+}
+function buildDeps(opts, cwd = process.cwd()) {
+  return {
+    cwd,
+    opts,
+    fs: {
+      readFile: (p4) => readFile(p4, "utf8"),
+      writeFile: (p4, c) => writeFile(p4, c),
+      exists: async (p4) => {
+        try {
+          await access(p4);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      mkdir: async (p4) => {
+        await mkdir(p4, { recursive: true });
+      }
+    },
+    spawn: (cmd, args, { cwd: cwd2 }) => new Promise((resolve2) => {
+      const child = nodeSpawn(cmd, args, { cwd: cwd2, stdio: ["ignore", "pipe", "pipe"] });
+      let stdout = "";
+      let stderr = "";
+      child.stdout.on("data", (d) => {
+        stdout += d.toString();
+      });
+      child.stderr.on("data", (d) => {
+        stderr += d.toString();
+      });
+      child.on("close", (code) => resolve2({ code: code ?? 0, stdout, stderr }));
+    })
+  };
+}
+
+// src/detect.ts
+import { readFile as readFile2, access as access2 } from "fs/promises";
+import { join } from "path";
+import fg from "fast-glob";
+async function exists(p4) {
+  try {
+    await access2(p4);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJson(path) {
+  return JSON.parse(await readFile2(path, "utf8"));
+}
+var EMPTY_PKG = {};
+async function detectPackageManager(cwd) {
+  const root = await readJson(join(cwd, "package.json")).catch(() => EMPTY_PKG);
+  if (typeof root.packageManager === "string") {
+    if (root.packageManager.startsWith("pnpm")) return "pnpm";
+    if (root.packageManager.startsWith("yarn")) return "yarn";
+    if (root.packageManager.startsWith("npm")) return "npm";
+  }
+  if (await exists(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (await exists(join(cwd, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+function depPresent(pkg, name) {
+  const deps = pkg?.dependencies;
+  const devDeps = pkg?.devDependencies;
+  return Boolean(deps?.[name] || devDeps?.[name]);
+}
+async function statSet(target) {
+  const flags = /* @__PURE__ */ new Set();
+  if (await exists(join(target, "tsconfig.json"))) flags.add("ts");
+  for (const f of ["vitest.config.ts", "vitest.config.js", "vitest.config.mjs"]) {
+    if (await exists(join(target, f))) {
+      flags.add("vitest-config");
+      break;
+    }
+  }
+  for (const f of ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs"]) {
+    if (await exists(join(target, f))) {
+      flags.add("playwright-config");
+      break;
+    }
+  }
+  return flags;
+}
+async function readWorkspaceGlobs(cwd) {
+  const pw = join(cwd, "pnpm-workspace.yaml");
+  if (await exists(pw)) {
+    const text = await readFile2(pw, "utf8");
+    const lines = text.split("\n");
+    const globs = [];
+    let inPackages = false;
+    for (const raw of lines) {
+      const line = raw.trim();
+      if (line.startsWith("packages:")) {
+        inPackages = true;
+        continue;
+      }
+      if (inPackages) {
+        if (line.startsWith("- ")) {
+          globs.push(line.slice(2).replace(/^["']|["']$/g, ""));
+        } else if (line && !line.startsWith("#")) {
+          break;
+        }
+      }
+    }
+    return globs;
+  }
+  const rootPkg = await readJson(join(cwd, "package.json")).catch(() => EMPTY_PKG);
+  const workspaces = rootPkg.workspaces;
+  if (Array.isArray(workspaces)) return workspaces;
+  const workspacePkgs = workspaces?.packages;
+  if (Array.isArray(workspacePkgs)) return workspacePkgs;
+  return null;
+}
+async function listWorkspacePackages(cwd) {
+  const globs = await readWorkspaceGlobs(cwd);
+  if (!globs) return [];
+  const pjPaths = await fg(globs.map((g) => g.replace(/\/?$/, "/package.json")), { cwd, absolute: true });
+  const out = [];
+  for (const pj of pjPaths) {
+    const pkg = await readJson(pj).catch(() => EMPTY_PKG);
+    if (typeof pkg.name === "string") out.push({ name: pkg.name, path: pj.replace(/\/package\.json$/, "") });
+  }
+  return out;
+}
+async function detectRepo(args, _deps) {
+  const { cwd } = args;
+  const rootPkg = await readJson(join(cwd, "package.json")).catch(() => EMPTY_PKG);
+  const packageManager = await detectPackageManager(cwd);
+  const stats = /* @__PURE__ */ new Map();
+  stats.set(cwd, await statSet(cwd));
+  const pkgCache = /* @__PURE__ */ new Map();
+  pkgCache.set(cwd, rootPkg);
+  const rootName = typeof rootPkg.name === "string" ? rootPkg.name : "root";
+  const rootCandidate = { name: rootName, path: cwd };
+  const workspacePackages = await listWorkspacePackages(cwd);
+  const isMonorepo = workspacePackages.length > 0;
+  const candidates = isMonorepo ? [rootCandidate, ...workspacePackages] : [rootCandidate];
+  for (const wp of workspacePackages) {
+    pkgCache.set(wp.path, await readJson(join(wp.path, "package.json")).catch(() => EMPTY_PKG));
+    stats.set(wp.path, await statSet(wp.path));
+  }
+  return {
+    cwd,
+    packageManager,
+    isMonorepo,
+    workspacePackages,
+    candidates,
+    hasDependency: (t, dep) => depPresent(pkgCache.get(t) ?? rootPkg, dep),
+    hasTypeScript: (t) => stats.get(t)?.has("ts") ?? false,
+    hasVitest: (t) => depPresent(pkgCache.get(t) ?? rootPkg, "vitest"),
+    hasPlaywright: (t) => depPresent(pkgCache.get(t) ?? rootPkg, "@playwright/test"),
+    hasExistingVitestConfig: (t) => stats.get(t)?.has("vitest-config") ?? false,
+    hasExistingPlaywrightConfig: (t) => stats.get(t)?.has("playwright-config") ?? false
+  };
+}
+
+// src/plan.ts
+import { join as join3 } from "path";
+
+// src/templates/index.ts
+import { readFile as readFile3 } from "fs/promises";
+import { fileURLToPath } from "url";
+import { dirname, join as join2 } from "path";
+var _fileDir = dirname(fileURLToPath(import.meta.url));
+var here = _fileDir.endsWith("/cli") ? join2(_fileDir, "..", "templates") : _fileDir;
+async function renderTemplate(name) {
+  return readFile3(join2(here, `${name}.tmpl`), "utf8");
+}
+
+// src/plan.ts
+async function resolvePlan(args, _deps) {
+  const { facts, flags } = args;
+  const ops = [];
+  if (flags.writeTsconfig) {
+    for (const target of flags.targets) {
+      if (!facts.hasTypeScript(target)) {
+        ops.push({
+          kind: "write",
+          target,
+          path: join3(target, "tsconfig.json"),
+          contents: await renderTemplate("tsconfig.json")
+        });
+      }
+    }
+  }
+  for (const target of flags.targets) {
+    if (flags.frameworks.includes("vitest")) {
+      const vitestDeps = ["vitest", "executable-stories-vitest", "executable-stories-formatters"];
+      const missing = vitestDeps.filter((dep) => !facts.hasDependency(target, dep));
+      if (missing.length > 0) {
+        ops.push({
+          kind: "install",
+          target,
+          deps: missing,
+          dev: true,
+          packageManager: facts.packageManager
+        });
+      }
+      if (!facts.hasExistingVitestConfig(target) || flags.force) {
+        ops.push({
+          kind: "write",
+          target,
+          path: join3(target, "vitest.config.ts"),
+          contents: await renderTemplate("vitest-config.ts")
+        });
+      }
+      ops.push({
+        kind: "write",
+        target,
+        path: join3(target, "src/example.story.test.ts"),
+        contents: await renderTemplate("vitest-sample.story.test.ts")
+      });
+      ops.push({ kind: "patch-package-json", target, scripts: { test: "vitest run" } });
+    }
+    if (flags.frameworks.includes("playwright")) {
+      const pwDeps = ["@playwright/test", "executable-stories-playwright", "executable-stories-formatters"];
+      const missing = pwDeps.filter((dep) => !facts.hasDependency(target, dep));
+      if (missing.length > 0) {
+        ops.push({
+          kind: "install",
+          target,
+          deps: missing,
+          dev: true,
+          packageManager: facts.packageManager
+        });
+      }
+      if (!facts.hasExistingPlaywrightConfig(target) || flags.force) {
+        ops.push({
+          kind: "write",
+          target,
+          path: join3(target, "playwright.config.ts"),
+          contents: await renderTemplate("playwright-config.ts")
+        });
+      }
+      ops.push({
+        kind: "write",
+        target,
+        path: join3(target, "tests/example.story.spec.ts"),
+        contents: await renderTemplate("playwright-sample.story.spec.ts")
+      });
+      ops.push({
+        kind: "patch-package-json",
+        target,
+        scripts: { "test:e2e": "playwright test" }
+      });
+    }
+  }
+  return {
+    ops,
+    summary: { targets: flags.targets, frameworks: flags.frameworks, packageManager: facts.packageManager }
+  };
+}
+
+// src/apply.ts
+async function applyPlan(args, deps) {
+  const { plan, dryRun, force } = args;
+  const written = [];
+  const installed = [];
+  const patched = [];
+  const skipped = [];
+  const notes = [];
+  for (const op of plan.ops) {
+    if (dryRun) {
+      notes.push(`[dry-run] ${describeOp(op)}`);
+      continue;
+    }
+    switch (op.kind) {
+      case "write":
+        await applyWrite(op, force, deps, written, skipped);
+        break;
+      case "install":
+        await applyInstall(op, deps, installed);
+        break;
+      case "patch-package-json":
+        await applyPatch(op, force, deps, patched, skipped);
+        break;
+      case "note":
+        notes.push(`${op.level}: ${op.message}`);
+        break;
+    }
+  }
+  return { ok: true, written, installed, patched, skipped, notes };
+}
+function describeOp(op) {
+  switch (op.kind) {
+    case "write":
+      return `write ${op.path}`;
+    case "install":
+      return `install ${op.deps.join(" ")} in ${op.target}`;
+    case "patch-package-json":
+      return `patch ${op.target}/package.json scripts: ${Object.keys(op.scripts).join(", ")}`;
+    case "note":
+      return op.message;
+  }
+}
+async function applyWrite(op, force, deps, written, skipped) {
+  if (await deps.fs.exists(op.path)) {
+    const existing = await deps.fs.readFile(op.path);
+    if (existing === op.contents) {
+      skipped.push({ path: op.path, reason: "identical" });
+      return;
+    }
+    if (!force) {
+      skipped.push({ path: op.path, reason: "exists; use --force to overwrite" });
+      return;
+    }
+  }
+  await deps.fs.mkdir(parentDir(op.path));
+  await deps.fs.writeFile(op.path, op.contents);
+  written.push(op.path);
+}
+async function applyInstall(op, deps, installed) {
+  const pmCmd = op.packageManager;
+  const args = pmCmd === "npm" ? ["install", "--save-dev", ...op.deps] : ["add", "-D", ...op.deps];
+  const r = await deps.spawn(pmCmd, args, { cwd: op.target });
+  if (r.code !== 0) {
+    const stderr = r.stderr.trim() || "(no stderr output)";
+    const manual = `${pmCmd} ${args.join(" ")}`;
+    throw new Error(
+      `${pmCmd} dependency install failed in ${op.target}
+command: ${manual}
+stderr: ${stderr}
+next steps:
+  1. Run with --dry-run to inspect planned operations.
+  2. Re-run install manually in target: cd ${op.target} && ${manual}
+  3. Verify your package manager and lockfile are healthy.`
+    );
+  }
+  installed.push(...op.deps);
+}
+async function applyPatch(op, force, deps, patched, skipped) {
+  const path = `${op.target}/package.json`;
+  const raw = await deps.fs.readFile(path);
+  const pkg = JSON.parse(raw);
+  pkg.scripts = pkg.scripts ?? {};
+  let changed = false;
+  for (const [name, value] of Object.entries(op.scripts)) {
+    const existing = pkg.scripts[name];
+    if (existing === value) {
+      skipped.push({ path: `${path}#scripts.${name}`, reason: "identical" });
+      continue;
+    }
+    if (existing && !force) {
+      skipped.push({ path: `${path}#scripts.${name}`, reason: `exists: ${existing}` });
+      continue;
+    }
+    pkg.scripts[name] = value;
+    changed = true;
+  }
+  if (changed) {
+    await deps.fs.writeFile(path, JSON.stringify(pkg, null, 2) + "\n");
+    patched.push(path);
+  }
+}
+function parentDir(path) {
+  if (/^[A-Za-z]:\\[^\\]+$/.test(path) || /^[A-Za-z]:\\[^\\]*\.[^\\]+$/.test(path)) {
+    return `${path.slice(0, 2)}\\`;
+  }
+  const normalized = path.replace(/\\/g, "/");
+  const idx = normalized.lastIndexOf("/");
+  if (idx <= 0) return ".";
+  const dir = normalized.slice(0, idx);
+  if (/^[A-Za-z]:$/.test(dir) && path.includes("\\")) return `${dir}\\`;
+  return dir.replace(/\//g, path.includes("\\") ? "\\" : "/");
+}
+
+// src/render/json.ts
+function renderJson(args) {
+  return JSON.stringify({ ok: args.result.ok, plan: args.plan, result: args.result }, null, 2);
+}
+
+// src/render/human.ts
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import process2 from "process";
+function renderHuman({ plan, result }) {
+  const lines = [];
+  lines.push(pc.bold("Targets:"), "  " + plan.summary.targets.join("\n  "));
+  lines.push(pc.bold("Frameworks:"), "  " + plan.summary.frameworks.join(", "));
+  if (result.written.length) {
+    lines.push(pc.green(`+ wrote (${result.written.length})`));
+    lines.push(...result.written.map((w) => "  " + w));
+  }
+  if (result.installed.length) {
+    lines.push(pc.cyan(`\u21BB installed (${result.installed.length})`));
+    lines.push(...result.installed.map((i) => "  " + i));
+  }
+  if (result.patched.length) {
+    lines.push(pc.cyan(`\u2261 patched (${result.patched.length})`));
+    lines.push(...result.patched.map((i) => "  " + i));
+  }
+  if (result.skipped.length) {
+    lines.push(pc.yellow(`~ skipped (${result.skipped.length})`));
+    lines.push(...result.skipped.map((s) => `  ${s.path}: ${s.reason}`));
+  }
+  if (result.notes.length) {
+    lines.push(pc.dim("notes"));
+    lines.push(...result.notes.map((n) => "  " + n));
+  }
+  p.note(lines.join("\n"), "summary");
+  const targets = plan.summary.targets;
+  const next = ["For each target:"];
+  const pm = plan.summary.packageManager;
+  const installCmd = pm === "yarn" ? "yarn install" : `${pm} install`;
+  const runTest = pm === "yarn" ? "yarn test" : `${pm} run test`;
+  const playwrightInstall = pm === "yarn" ? "yarn playwright install" : `${pm} exec playwright install`;
+  const openReport = reportOpenCommand();
+  for (const t of targets) {
+    next.push(`  cd ${t}`);
+    next.push(`  ${installCmd}`);
+    next.push(`  ${runTest}`);
+    if (plan.summary.frameworks.includes("playwright")) {
+      next.push(`  ${playwrightInstall}`);
+    }
+    next.push(`  ${openReport}`);
+    next.push("");
+  }
+  p.outro(`Next:
+${next.join("\n").trimEnd()}`);
+}
+function reportOpenCommand() {
+  switch (process2.platform) {
+    case "darwin":
+      return "open reports/executable-stories.html";
+    case "win32":
+      return "start reports\\executable-stories.html";
+    default:
+      return "xdg-open reports/executable-stories.html";
+  }
+}
+
+// src/wizard.ts
+import * as p2 from "@clack/prompts";
+import pc2 from "picocolors";
+async function promptTargets(facts) {
+  const choice = await p2.multiselect({
+    message: "Which package(s)?",
+    options: facts.candidates.map((c) => ({ value: c.path, label: c.name })),
+    required: true
+  });
+  if (p2.isCancel(choice)) return [];
+  return choice;
+}
+async function runWizard(args, _deps) {
+  const { facts } = args;
+  p2.intro(pc2.bgCyan(pc2.black(" executable-stories ")));
+  p2.note(summarise(facts), "detected");
+  const fw = await p2.multiselect({
+    message: "Which framework(s)?",
+    options: [
+      {
+        value: "vitest",
+        label: "Vitest",
+        hint: facts.hasVitest(facts.cwd) ? "already installed" : void 0
+      },
+      {
+        value: "playwright",
+        label: "Playwright",
+        hint: facts.hasPlaywright(facts.cwd) ? "already installed" : void 0
+      }
+    ],
+    required: true
+  });
+  if (p2.isCancel(fw)) {
+    p2.cancel("Cancelled");
+    return null;
+  }
+  return { frameworks: fw };
+}
+function summarise(facts) {
+  return [
+    `package manager: ${facts.packageManager}`,
+    `typescript: ${facts.hasTypeScript(facts.cwd) ? "yes" : "no"}`,
+    `monorepo: ${facts.isMonorepo ? `yes (${facts.workspacePackages.length} workspace packages)` : "no"}`
+  ].join("\n");
+}
+
+// src/targets.ts
+function targetLeaf(path) {
+  const normalized = path.replace(/\\/g, "/");
+  return normalized.split("/").filter(Boolean).at(-1) ?? normalized;
+}
+function unique(values) {
+  return [...new Set(values)];
+}
+function targetHelpList(facts) {
+  const names = facts.workspacePackages.map((w) => w.name);
+  const leaves = facts.workspacePackages.map((w) => targetLeaf(w.path));
+  return unique(["root", ...names, ...leaves]).join(", ");
+}
+async function resolveTargets(flag, facts, opts) {
+  if (flag && flag.length > 0) {
+    const out = [];
+    for (const t of flag) {
+      if (t === "root") {
+        out.push(facts.cwd);
+        continue;
+      }
+      const matches = facts.workspacePackages.filter(
+        (w) => w.name === t || targetLeaf(w.path) === t
+      );
+      if (matches.length === 1) out.push(matches[0].path);
+      else if (matches.length > 1) {
+        throw new Error(
+          `ambiguous target: ${t}
+matches:
+${matches.map((w) => `  - ${w.name} (${w.path})`).join("\n")}
+tip: use the full workspace package name with --target`
+        );
+      } else {
+        const validNames = targetHelpList(facts);
+        throw new Error(
+          `unknown target: ${t}
+valid targets: ${validNames}
+tip: use --target root for the repo root`
+        );
+      }
+    }
+    return unique(out);
+  }
+  if (!facts.isMonorepo) return [facts.cwd];
+  if (!opts.interactive) return [facts.cwd];
+  return promptTargets(facts);
+}
+
+// src/errors.ts
+function formatCliError(message, json) {
+  if (json) return JSON.stringify({ ok: false, error: message }, null, 2);
+  return `Error: ${message}`;
+}
+
+// src/index.ts
+async function confirmPlan(plan) {
+  const lines = [
+    `Targets: ${plan.summary.targets.join(", ")}`,
+    `Frameworks: ${plan.summary.frameworks.join(", ")}`,
+    "",
+    "Operations:",
+    ...plan.ops.map((op) => {
+      switch (op.kind) {
+        case "install":
+          return `  install ${op.deps.join(" ")} (${op.packageManager})`;
+        case "write":
+          return `  write ${op.path}`;
+        case "patch-package-json":
+          return `  patch ${op.target}/package.json scripts: ${Object.keys(op.scripts).join(", ")}`;
+        case "note":
+          return `  ${op.level}: ${op.message}`;
+      }
+    })
+  ];
+  p3.note(lines.join("\n"), "plan preview");
+  const ok = await p3.confirm({ message: "Proceed?", initialValue: true });
+  return !p3.isCancel(ok) && ok === true;
+}
+var program = new Command();
+program.name("executable-stories-init").description("Bootstrap executable-stories (Vitest + Playwright) into a TypeScript repo").argument("[target]", "target directory (defaults to cwd)").option("--vitest", "set up Vitest").option("--playwright", "set up Playwright").option("--both", "set up both Vitest and Playwright").option("--ts", "write tsconfig.json if missing").option("--no-ts", "do not write tsconfig.json").option("-y, --yes", "accept all defaults, non-interactive").option("--dry-run", "print plan but do not write or install").option("--json", "machine-readable JSON output (implies --yes)").option("--interactive", "force interactive prompts").option("--force", "overwrite differing existing files").option("--target <pkg...>", "workspace package(s) to set up (default: prompt or root)").action(async (target, opts) => {
+  const cliOpts = buildOpts(opts);
+  try {
+    const cwd = resolve(target ?? process3.cwd());
+    const deps = buildDeps(cliOpts, cwd);
+    const facts = await detectRepo({ cwd }, deps);
+    const frameworks = opts.both ? ["vitest", "playwright"] : [opts.vitest && "vitest", opts.playwright && "playwright"].filter(Boolean);
+    if (frameworks.length === 0 && cliOpts.json) {
+      console.error(formatCliError("--json requires at least one of --vitest, --playwright, --both", true));
+      process3.exit(2);
+    }
+    if (frameworks.length === 0) {
+      const chosen = await runWizard({ facts }, deps);
+      if (!chosen) process3.exit(130);
+      frameworks.push(...chosen.frameworks);
+    }
+    const targets = await resolveTargets(opts.target, facts, cliOpts);
+    if (targets.length === 0) process3.exit(130);
+    const flags = {
+      targets,
+      frameworks,
+      writeTsconfig: opts.ts === true && targets.some((t) => !facts.hasTypeScript(t)),
+      force: Boolean(opts.force)
+    };
+    const plan = await resolvePlan({ facts, flags }, deps);
+    if (cliOpts.interactive && !opts.dryRun) {
+      const ok = await confirmPlan(plan);
+      if (!ok) {
+        if (!cliOpts.json) console.log("Cancelled.");
+        process3.exit(130);
+      }
+    }
+    const result = await applyPlan({ plan, dryRun: Boolean(opts.dryRun), force: flags.force }, deps);
+    if (cliOpts.json) {
+      console.log(renderJson({ plan, result }));
+    } else {
+      renderHuman({ plan, result });
+    }
+    process3.exit(result.ok ? 0 : 1);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(formatCliError(message, cliOpts.json));
+    process3.exit(1);
+  }
+});
+await program.parseAsync(process3.argv);

package/dist/templates/index.ts

@@ -0,0 +1,22 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+// When bundled by tsup into dist/cli/index.js, import.meta.url resolves to dist/cli/.
+// Templates are copied to dist/templates/ by tsup onSuccess, so we go up one level.
+// In source (dev/test), __dirname is src/templates/ and templates are co-located there.
+const _fileDir = dirname(fileURLToPath(import.meta.url));
+const here = _fileDir.endsWith('/cli') ? join(_fileDir, '..', 'templates') : _fileDir;
+
+const _NAMES = [
+  'vitest-config.ts',
+  'playwright-config.ts',
+  'vitest-sample.story.test.ts',
+  'playwright-sample.story.spec.ts',
+  'tsconfig.json',
+] as const;
+export type TemplateName = (typeof _NAMES)[number];
+
+export async function renderTemplate(name: TemplateName): Promise<string> {
+  return readFile(join(here, `${name}.tmpl`), 'utf8');
+}

package/dist/templates/playwright-config.ts.tmpl

@@ -0,0 +1,13 @@
+import { createRequire } from 'node:module';
+import { defineConfig } from '@playwright/test';
+
+const require = createRequire(import.meta.url);
+const reporterPath = require.resolve('executable-stories-playwright/reporter');
+
+export default defineConfig({
+  testMatch: '**/*.story.spec.ts',
+  reporter: [
+    ['list'],
+    [reporterPath, { formats: ['markdown', 'html'], outputDir: 'reports' }],
+  ],
+});

package/dist/templates/playwright-sample.story.spec.ts.tmpl

@@ -0,0 +1,12 @@
+import { expect, test } from '@playwright/test';
+import { given, then, when } from 'executable-stories-playwright';
+
+test('Loads example.com', async ({ page }) => {
+  await given('a fresh browser context', async () => {});
+  await when('the user visits example.com', async () => {
+    await page.goto('https://example.com');
+  });
+  await then('the title contains Example', async () => {
+    await expect(page).toHaveTitle(/Example/);
+  });
+});

package/dist/templates/tsconfig.json.tmpl

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}

package/dist/templates/vitest-config.ts.tmpl

@@ -0,0 +1,20 @@
+import { createRequire } from 'node:module';
+import type { Reporter } from 'vitest/node';
+import { defineConfig } from 'vitest/config';
+
+const require = createRequire(import.meta.url);
+const { StoryReporter } = require('executable-stories-vitest/reporter');
+
+export default defineConfig({
+  test: {
+    reporters: [
+      'default',
+      new StoryReporter({
+        formats: ['markdown', 'html'],
+        outputDir: 'reports',
+        outputName: 'executable-stories',
+        rawRunPath: 'reports/raw-run.json',
+      }) as unknown as Reporter,
+    ],
+  },
+});

package/dist/templates/vitest-sample.story.test.ts.tmpl

@@ -0,0 +1,18 @@
+import { story } from 'executable-stories-vitest';
+import { describe, expect, it } from 'vitest';
+
+describe('Calculator', () => {
+  it('Adds two numbers', ({ task }) => {
+    story.init(task);
+
+    story.given('two numbers');
+    const a = 1;
+    const b = 2;
+
+    story.when('they are added');
+    const result = a + b;
+
+    story.then('the sum is 3');
+    expect(result).toBe(3);
+  });
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "executable-stories-init",
+  "version": "0.1.0",
+  "description": "Bootstrap executable-stories (Vitest + Playwright) into a TypeScript repo.",
+  "author": "Jag Reehal <jag@jagreehal.com>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "executable-stories-init": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.3.0",
+    "commander": "^14.0.0",
+    "fast-glob": "^3.3.3",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "eslint-config-executable-stories": "workspace:*",
+    "executable-stories-vitest": "workspace:*",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint .",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "quality": "pnpm type-check && pnpm test && pnpm lint"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jagreehal/executable-stories.git",
+    "directory": "packages/executable-stories-init"
+  }
+}