@andwhy/e2e-pipeline 0.10.0

package/README.md

@@ -0,0 +1,106 @@
+# @andwhy/e2e-pipeline
+
+Scaffold customized Playwright test agents (Planner, Generator, Healer) into any project for **Claude Code**.
+
+## Quick start
+
+```bash
+pnpm dlx @andwhy/e2e-pipeline init
+```
+
+The CLI copies agent definitions, orchestration rules, and config templates into your project. The install is purely additive — it never creates or overwrites `CLAUDE.md`.
+
+**Setup and workflow docs:** [E2E Tests in Notion](https://app.notion.com/p/31ff837b6270805d8922c4a7c7beb6b0) (why-agency internal). These are maintained in one place rather than scaffolded into each project, so a workflow change is published once.
+
+## Options
+
+```
+pnpm dlx @andwhy/e2e-pipeline init [--format ts|mjs] [--force] [--reset-config]
+```
+
+| Flag             | Description                                                                                                  |
+| ---------------- | ------------------------------------------------------------------------------------------------------------ |
+| `--format`       | Config file format (`ts` or `mjs`). Use `mjs` if TS causes conflicts. Prompted if omitted.                   |
+| `--force`        | Update package-owned files. Never touches your configs, `CLAUDE.md`, or anything else you own.               |
+| `--reset-config` | Write a fresh `*.new.{ts,mjs}` next to each config so you can diff it. Your originals are left alone.         |
+
+Re-running `init --force` in an existing project is the way to pick up a new version.
+
+## What gets created
+
+**Package-owned** — regenerated by `--force`, so don't edit these by hand:
+
+- `.claude/agents/` — Planner, Generator, Healer agent definitions (3 agents, each defines its own MCP server)
+- `.claude/rules/playwright-workflow.md` — orchestration rules for the Plan → Generate → Heal pipeline, auto-loaded into the main session alongside any existing `CLAUDE.md`
+- `.claude/skills/playwright-test-pipeline/` — guided walkthrough skill; triggers when someone asks to create or fix tests and escorts them through setup check, Plan → Generate → Heal, preview validation, and deployment
+- `.mcp.json` — Playwright MCP server config (project root)
+- `playwright.mcp.config.{ts,mjs}` — config the MCP server loads: extends `playwright.config` and clears `testIgnore`, so the planner/generator can execute seeds that normal runs ignore
+
+**Seeded once** — starting points your project then owns. Written only when absent and never overwritten, `--force` included:
+
+- `playwright.config.{ts,mjs}` — Playwright config template with `BASE_URL` support, `testDir: "./tests/e2e"`, and `testIgnore` for seeds
+- `checkly.config.{ts,mjs}` — Checkly config template with placeholders
+- `tests/e2e/seed.spec.{ts,js}` — seed file for Playwright MCP `setup_page`
+- `tests/e2e/helpers/preview-consent-setup.{ts,js}` — `prepareVercelPreviewPage` (Vercel deployment-protection bypass); projects extend it with consent logic
+- `.github/workflows/pr-playwright-tests.yml` — runs the suite against the PR's Vercel preview and comments the result (plus `.github/scripts/playwright-pr-comment.mjs`)
+- `.github/workflows/checkly-deploy.yml` — deploys monitors on merge to `main`
+
+The workflows need repository secrets: `CHECKLY_API_KEY`, `CHECKLY_ACCOUNT_ID`,
+and `VERCEL_AUTOMATION_BYPASS_SECRET` (values in 1Password).
+
+E2E specs live under **`tests/e2e/`** so a repo can keep unit tests elsewhere under
+`tests/` without Playwright trying to run them. Seeds sit in the same tree and are
+kept out of test discovery by `testIgnore` rather than by living outside it.
+
+The agents treat this as a default, not a rule: if a repo already has specs
+somewhere else, they write there instead. See rule 6 in
+`.claude/rules/playwright-workflow.md`.
+
+`.gitignore` gains Playwright/test output and seed entries; existing lines are left in place.
+
+Scaffolded files are formatted with the project's own prettier when one is
+installed, so they match house style instead of this package's.
+
+## Agent customizations
+
+These agents extend the vanilla Playwright test agents with:
+
+- **Extra tools**: Generator gets `terminal`, `edit`, `read_file`; Healer gets `terminal`
+- **`data-testid` workflow**: Generator reads recommended attributes from the plan and adds them to source components before recording
+- **Vercel share auth**: every `test.describe` includes a `beforeEach` that authenticates with Vercel preview deployments
+- **Checkly verification**: both Generator and Healer run `pnpm exec checkly pw-test` after local tests pass
+- **Numbered step comments**: every logical step gets a comment (`// 1. Navigate to…`)
+- **Locale-awareness**: no hardcoded domains or locale-specific URL patterns
+- **Optional draft input**: Planner can validate a user-provided journey draft against the live page
+
+## Documentation
+
+The Installation and Usage guides live in `docs/notion/` and are the source of
+truth. Merging a change to `main` publishes them to their Notion pages, stamped
+with the package version they document. Edits made directly in Notion are
+overwritten on the next publish.
+
+Publishing needs a `NOTION_TOKEN` repository secret — a Notion PAT, or an
+internal integration token whose integration has been shared with both pages.
+Pull requests run `node scripts/publish-notion.mjs --dry-run`, which converts
+without writing, so malformed markdown fails before merge.
+
+The stamp shows the **latest version published to npm**, not the version in
+`package.json`. Docs describing an unreleased version send people looking for
+features they cannot install yet.
+
+## Releasing
+
+Bump `version` in `package.json`, add a `CHANGELOG.md` entry, merge to `main`.
+That's the whole release.
+
+`.github/workflows/release.yml` compares `package.json` against the version on
+npm. If they differ it publishes and tags the commit; if they match it exits
+quietly, so ordinary merges publish nothing. It needs an `NPM_TOKEN` repository
+secret with publish rights on the `@andwhy` scope.
+
+Published without npm provenance, which requires a public source repository.
+
+## License
+
+MIT

package/dist/bin/init.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/init.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findSpecsOutsideE2e, scaffold, } from "../utils/copy.js";
+import { formatFiles } from "../utils/format.js";
+import { installDeps } from "../utils/install.js";
+import { askFileFormat } from "../utils/prompt.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Setup and workflow docs are maintained in Notion (why-agency internal), not
+// scaffolded into projects, so a workflow change is published in one place.
+const DOCS_URL = "https://app.notion.com/p/31ff837b6270805d8922c4a7c7beb6b0";
+const parseArgs = (argv) => {
+    let format;
+    let force = false;
+    let resetConfig = false;
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "init")
+            continue;
+        if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--reset-config") {
+            resetConfig = true;
+        }
+        else if (arg === "--format" && argv[i + 1]) {
+            const val = argv[++i];
+            if (val === "ts" || val === "mjs") {
+                format = val;
+            }
+            else {
+                console.error(`Invalid --format value: ${val} (use "ts" or "mjs")`);
+                process.exit(1);
+            }
+        }
+        else if (arg.startsWith("--format=")) {
+            const val = arg.slice("--format=".length);
+            if (val === "ts" || val === "mjs") {
+                format = val;
+            }
+            else {
+                console.error(`Invalid --format value: ${val} (use "ts" or "mjs")`);
+                process.exit(1);
+            }
+        }
+    }
+    return { format, force, resetConfig };
+};
+const run = async () => {
+    const { format: formatArg, force, resetConfig } = parseArgs(process.argv);
+    const fileFormat = formatArg ?? (await askFileFormat());
+    const projectRoot = process.cwd();
+    const templatesRoot = path.resolve(__dirname, "..", "..", "templates");
+    console.log(`\nScaffolding Playwright test agents for Claude Code…\n`);
+    const result = await scaffold(templatesRoot, projectRoot, {
+        force,
+        fileFormat,
+        resetConfig,
+    });
+    if (result.created.length > 0) {
+        console.log("Created:");
+        for (const f of result.created) {
+            console.log(`  ${path.relative(projectRoot, f)}`);
+        }
+    }
+    if (result.skipped.length > 0) {
+        console.log("\nSkipped (already exist):");
+        for (const f of result.skipped) {
+            console.log(`  ${path.relative(projectRoot, f)}`);
+        }
+        if (!force) {
+            console.log("  Use --force to update package-owned files.");
+        }
+        console.log("  Your configs are never overwritten — use --reset-config for a fresh copy to diff against.");
+    }
+    if (result.regenerated.length > 0) {
+        console.log("\nWrote fresh configs alongside yours (diff, then delete):");
+        for (const f of result.regenerated) {
+            console.log(`  ${path.relative(projectRoot, f)}`);
+        }
+    }
+    const formatted = await formatFiles(projectRoot, [
+        ...result.created,
+        ...result.regenerated,
+    ]);
+    // "Ran over", not "formatted" — prettier skips anything the project's
+    // .prettierignore covers, and this count cannot see that.
+    if (formatted > 0) {
+        console.log(`\nRan the project's prettier over ${formatted} scaffolded file(s).`);
+    }
+    const outsideSpecs = await findSpecsOutsideE2e(projectRoot);
+    if (outsideSpecs.length > 0) {
+        console.log("\nExisting tests outside tests/e2e:");
+        for (const spec of outsideSpecs) {
+            console.log(`  ${spec}`);
+        }
+        console.log([
+            "  These stay outside the scaffolded testDir (./tests/e2e) and never run",
+            "  on Checkly — testCommand pins cloud runs to tests/e2e. To keep running",
+            "  them with Playwright, give them their own project with its own testDir",
+            "  in playwright.config. Do NOT widen testDir to ./tests: that runs them",
+            "  in every browser project and mixes the suites.",
+        ].join("\n"));
+    }
+    const createdWorkflow = result.created.some((f) => f.includes(`.github${path.sep}workflows`));
+    if (createdWorkflow) {
+        console.log([
+            "\nGitHub workflows created. They need repository secrets before they run",
+            "(values in 1Password):",
+            "  CHECKLY_API_KEY, CHECKLY_ACCOUNT_ID      — deploy monitors on merge",
+            "  VERCEL_AUTOMATION_BYPASS_SECRET          — PR tests through Vercel",
+            "                                             deployment protection",
+        ].join("\n"));
+    }
+    installDeps(projectRoot, fileFormat);
+    console.log("Next steps:");
+    let step = 1;
+    const ext = fileFormat === "mjs" ? "mjs" : "ts";
+    console.log(`  ${step++}. Edit checkly.config.${ext} with your project name and check suites`);
+    console.log(`  ${step++}. Run: npx checkly login`);
+    console.log(`  ${step++}. Setup and workflow docs: ${DOCS_URL}`);
+    console.log("\nPlaywright agent rules installed into .claude/rules/ — they load alongside any existing CLAUDE.md without conflict.");
+    console.log();
+};
+run().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/utils/copy.d.ts

@@ -0,0 +1,23 @@
+interface CopyResult {
+    created: string[];
+    skipped: string[];
+    regenerated: string[];
+}
+/**
+ * Specs already living under tests/ but outside tests/e2e — a unit or a11y
+ * suite that predates the scaffold. They need calling out at install time:
+ * left alone they are simply outside testDir, but the tempting "fix" of
+ * widening testDir to ./tests runs them in every browser project and mixes
+ * the suites.
+ */
+export declare const findSpecsOutsideE2e: (projectRoot: string) => Promise<string[]>;
+export type FileFormat = "ts" | "mjs";
+export interface ScaffoldOptions {
+    /** Overwrite package-owned files. Never applies to seeded files. */
+    force?: boolean;
+    fileFormat?: FileFormat;
+    /** Write a fresh copy of each config alongside the existing one, as `.new`. */
+    resetConfig?: boolean;
+}
+export declare const scaffold: (templatesRoot: string, projectRoot: string, { force, fileFormat, resetConfig }?: ScaffoldOptions) => Promise<CopyResult>;
+export {};

package/dist/utils/copy.js

@@ -0,0 +1,249 @@
+import path from "node:path";
+import fs from "fs-extra";
+const copyTemplateDir = async (srcDir, destDir, force, result, destRename) => {
+    const entries = await fs.readdir(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(srcDir, entry.name);
+        const relPath = destRename ? destRename(entry.name) : entry.name;
+        const destPath = path.join(destDir, relPath);
+        if (entry.isDirectory()) {
+            await copyTemplateDir(srcPath, destPath, force, result);
+        }
+        else {
+            if (!force && (await fs.pathExists(destPath))) {
+                result.skipped.push(destPath);
+            }
+            else {
+                await fs.ensureDir(path.dirname(destPath));
+                await fs.copy(srcPath, destPath);
+                result.created.push(destPath);
+            }
+        }
+    }
+};
+const ROBUSTNESS_MARKER = "<!-- ROBUSTNESS_CORE -->";
+// Copies agent definition files, inlining the shared robustness core partial in
+// place of the ROBUSTNESS_CORE marker. Subagents run in isolated context and
+// cannot read the partial (or any rules file), so the content must be embedded
+// in each agent body at scaffold time. The partials/ directory is never copied.
+const copyAgentsDir = async (agentsSrc, agentsDest, robustnessCore, force, result) => {
+    const entries = await fs.readdir(agentsSrc, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const srcPath = path.join(agentsSrc, entry.name);
+        const destPath = path.join(agentsDest, entry.name);
+        if (!force && (await fs.pathExists(destPath))) {
+            result.skipped.push(destPath);
+            continue;
+        }
+        const content = await fs.readFile(srcPath, "utf-8");
+        const inlined = content.split(ROBUSTNESS_MARKER).join(robustnessCore);
+        await fs.ensureDir(path.dirname(destPath));
+        await fs.writeFile(destPath, inlined);
+        result.created.push(destPath);
+    }
+};
+const readProjectName = async (projectRoot) => {
+    const pkgPath = path.join(projectRoot, "package.json");
+    if (await fs.pathExists(pkgPath)) {
+        const pkg = await fs.readJson(pkgPath);
+        const name = pkg.name ?? "";
+        return name.replace(/^@[^/]+\//, "");
+    }
+    return path.basename(projectRoot);
+};
+const buildMcpConfig = (configPath) => {
+    const server = {
+        command: "pnpm",
+        args: ["playwright", "run-test-mcp-server", "-c", configPath],
+    };
+    return (JSON.stringify({ mcpServers: { "playwright-test": server } }, null, 2) +
+        "\n");
+};
+const writeMcpConfig = async (destPath, configPath, force, result) => {
+    if (!force && (await fs.pathExists(destPath))) {
+        result.skipped.push(destPath);
+        return;
+    }
+    await fs.ensureDir(path.dirname(destPath));
+    await fs.writeFile(destPath, buildMcpConfig(configPath));
+    result.created.push(destPath);
+};
+const GITIGNORE_LINES = [
+    "# Playwright",
+    "test-results/",
+    "playwright-report/",
+    // Session artifacts (traces, snapshots) the Playwright MCP server writes
+    // while the planner/generator drive the browser.
+    ".playwright-mcp/",
+];
+// Lines earlier scaffold versions added and this one must take back: seeds
+// were once regenerable root-level scaffolding, but since 0.5.0 the planner
+// writes real per-feature setup into them and the convention is to commit
+// seeds alongside specs and plans — a bare "seed.spec.ts" entry ignores every
+// seed at any depth. Removed only as exact-line matches, so a project's own
+// deliberate patterns are never touched.
+const GITIGNORE_STALE_LINES = ["seed.spec.ts", "seed.spec.js"];
+const appendGitignore = async (projectRoot, result) => {
+    const gitignorePath = path.join(projectRoot, ".gitignore");
+    let existing = (await fs.pathExists(gitignorePath))
+        ? await fs.readFile(gitignorePath, "utf-8")
+        : "";
+    const lines = existing.split("\n");
+    const cleaned = lines.filter((line) => !GITIGNORE_STALE_LINES.includes(line.trim()));
+    const removedStale = cleaned.length !== lines.length;
+    if (removedStale) {
+        existing = cleaned.join("\n");
+        await fs.writeFile(gitignorePath, existing);
+    }
+    const missing = GITIGNORE_LINES.filter((line) => !existing.includes(line));
+    if (missing.length === 0) {
+        if (removedStale)
+            result.created.push(gitignorePath);
+        return;
+    }
+    const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await fs.appendFile(gitignorePath, `${separator}\n${missing.join("\n")}\n`);
+    result.created.push(gitignorePath);
+};
+const writeSeed = async (srcPath, destPath, srcName, projectName) => {
+    await fs.ensureDir(path.dirname(destPath));
+    await fs.copy(srcPath, destPath);
+    if (srcName.startsWith("checkly.config.template")) {
+        const content = await fs.readFile(destPath, "utf-8");
+        await fs.writeFile(destPath, content.replace(/my-app/g, projectName));
+    }
+};
+/**
+ * Specs already living under tests/ but outside tests/e2e — a unit or a11y
+ * suite that predates the scaffold. They need calling out at install time:
+ * left alone they are simply outside testDir, but the tempting "fix" of
+ * widening testDir to ./tests runs them in every browser project and mixes
+ * the suites.
+ */
+export const findSpecsOutsideE2e = async (projectRoot) => {
+    const testsRoot = path.join(projectRoot, "tests");
+    if (!(await fs.pathExists(testsRoot)))
+        return [];
+    const found = new Set();
+    const walk = async (dir) => {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (dir === testsRoot && entry.name === "e2e")
+                    continue;
+                await walk(entryPath);
+            }
+            else if (/\.(spec|test)\.[cm]?[jt]sx?$/.test(entry.name)) {
+                const rel = path.relative(projectRoot, entryPath);
+                const parts = rel.split(path.sep);
+                found.add(parts.length > 2 ? parts.slice(0, 2).join("/") : rel);
+            }
+        }
+    };
+    await walk(testsRoot);
+    return [...found].sort();
+};
+export const scaffold = async (templatesRoot, projectRoot, { force = false, fileFormat = "ts", resetConfig = false } = {}) => {
+    const result = { created: [], skipped: [], regenerated: [] };
+    const configExt = fileFormat === "mjs" ? "mjs" : "ts";
+    const seedExt = fileFormat === "mjs" ? "js" : "ts";
+    // The MCP server gets its own config: it must discover seeds that the main
+    // config's testIgnore hides from local, CI, and Checkly runs. Package-owned,
+    // like .mcp.json which points at it.
+    const mcpConfigPath = `./playwright.mcp.config.${configExt}`;
+    const claudeSrc = path.join(templatesRoot, "claude");
+    const robustnessCore = (await fs.readFile(path.join(claudeSrc, "partials", "_robustness-core.md"), "utf-8")).trimEnd();
+    await copyAgentsDir(path.join(claudeSrc, "agents"), path.join(projectRoot, ".claude", "agents"), robustnessCore, force, result);
+    await copyTemplateDir(path.join(claudeSrc, "rules"), path.join(projectRoot, ".claude", "rules"), force, result);
+    await copyTemplateDir(path.join(claudeSrc, "skills"), path.join(projectRoot, ".claude", "skills"), force, result);
+    await writeMcpConfig(path.join(projectRoot, ".mcp.json"), mcpConfigPath, force, result);
+    {
+        const src = path.join(templatesRoot, "shared", `playwright.mcp.config.template.${configExt}`);
+        const dest = path.join(projectRoot, `playwright.mcp.config.${configExt}`);
+        if (!force && (await fs.pathExists(dest))) {
+            result.skipped.push(dest);
+        }
+        else {
+            await fs.copy(src, dest);
+            result.created.push(dest);
+        }
+    }
+    const projectName = await readProjectName(projectRoot);
+    const sharedSrc = path.join(templatesRoot, "shared");
+    const sharedMappings = [
+        [
+            `playwright.config.template.${configExt}`,
+            `playwright.config.${configExt}`,
+        ],
+        [`checkly.config.template.${configExt}`, `checkly.config.${configExt}`],
+        // Inside testDir, alongside the specs it seeds. Safe there because the
+        // config's testIgnore keeps seeds out of test discovery.
+        [`seed.spec.${seedExt}`, path.join("tests", "e2e", `seed.spec.${seedExt}`)],
+        // The preview helper every spec's beforeEach calls (rules file, rule 3).
+        // Seeded once: projects extend it with their own consent logic.
+        [
+            `preview-consent-setup.template.${seedExt}`,
+            path.join("tests", "e2e", "helpers", `preview-consent-setup.${seedExt}`),
+        ],
+    ];
+    // Seeded files are starting points the project then owns — a Checkly config
+    // grows domains, alert policies and environment variables that no template can
+    // reproduce. They are written when absent and never overwritten, --force
+    // included. Use resetConfig to get a fresh copy to diff against by hand.
+    for (const [src, dest] of sharedMappings) {
+        const srcPath = path.join(sharedSrc, src);
+        const destPath = path.join(projectRoot, dest);
+        const exists = await fs.pathExists(destPath);
+        if (exists && resetConfig && src.endsWith(`.config.template.${configExt}`)) {
+            // checkly.config.new.ts, not checkly.config.ts.new — keeping the real
+            // extension means prettier can format it and the editor highlights it,
+            // so the diff against your config shows content rather than style.
+            const ext = path.extname(destPath);
+            const newPath = `${destPath.slice(0, -ext.length)}.new${ext}`;
+            await writeSeed(srcPath, newPath, src, projectName);
+            result.regenerated.push(newPath);
+            continue;
+        }
+        if (exists) {
+            result.skipped.push(destPath);
+            continue;
+        }
+        await writeSeed(srcPath, destPath, src, projectName);
+        result.created.push(destPath);
+    }
+    // GitHub workflows: seeded once, like the configs. Repos customize their
+    // workflows (path filters, retry posture), and --force must never clobber
+    // that. Both need repository secrets the scaffold cannot create — the CLI
+    // says which below, the skill walks the user through adding them.
+    const githubSrc = path.join(templatesRoot, "github");
+    const githubMappings = [
+        [
+            path.join("workflows", "checkly-deploy.yml"),
+            path.join(".github", "workflows", "checkly-deploy.yml"),
+        ],
+        [
+            path.join("workflows", "pr-playwright-tests.yml"),
+            path.join(".github", "workflows", "pr-playwright-tests.yml"),
+        ],
+        [
+            path.join("scripts", "playwright-pr-comment.mjs"),
+            path.join(".github", "scripts", "playwright-pr-comment.mjs"),
+        ],
+    ];
+    for (const [src, dest] of githubMappings) {
+        const destPath = path.join(projectRoot, dest);
+        if (await fs.pathExists(destPath)) {
+            result.skipped.push(destPath);
+        }
+        else {
+            await fs.ensureDir(path.dirname(destPath));
+            await fs.copy(path.join(githubSrc, src), destPath);
+            result.created.push(destPath);
+        }
+    }
+    await appendGitignore(projectRoot, result);
+    return result;
+};

package/dist/utils/format.d.ts

@@ -0,0 +1 @@
+export declare const formatFiles: (projectRoot: string, files: string[]) => Promise<number>;

package/dist/utils/format.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import fs from "fs-extra";
+/**
+ * Scaffolded files carry this package's style, which is rarely the host
+ * project's — quotes, semicolons, print width all differ. Left alone, every
+ * install produces a diff of pure formatting noise and fights the project's
+ * pre-commit hook.
+ *
+ * Running the project's own prettier over the files we wrote fixes that without
+ * guessing at conventions: prettier resolves the project's config itself.
+ * Resolved from node_modules/.bin rather than through a package manager so
+ * nothing gets downloaded and no pnpm/npm/yarn detection is needed.
+ *
+ * Everything written gets formatted, `.claude/**` included. Those files are
+ * committed and reviewed like any other, and a repo that formats on commit
+ * (lint-staged over `**\/*`) would reformat them at the next commit anyway —
+ * skipping them here only defers the diff to a more surprising moment.
+ *
+ * A project that wants them left alone says so in its own `.prettierignore`,
+ * which prettier honours even for explicitly passed paths. That keeps the
+ * policy with the project rather than baked in here.
+ */
+const resolvePrettier = async (projectRoot) => {
+    const binDir = path.join(projectRoot, "node_modules", ".bin");
+    for (const name of ["prettier", "prettier.cmd"]) {
+        const candidate = path.join(binDir, name);
+        if (await fs.pathExists(candidate))
+            return candidate;
+    }
+    return null;
+};
+export const formatFiles = async (projectRoot, files) => {
+    if (files.length === 0)
+        return 0;
+    const prettier = await resolvePrettier(projectRoot);
+    if (!prettier)
+        return 0;
+    // --ignore-unknown skips files prettier has no parser for (.gitignore), and
+    // .prettierignore is honoured automatically.
+    const result = spawnSync(prettier, ["--write", "--ignore-unknown", "--log-level", "warn", ...files], { cwd: projectRoot, stdio: "pipe", encoding: "utf-8" });
+    // Formatting is a nicety — a prettier failure must not fail the install.
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.error?.message || "").trim();
+        console.warn(`\nCould not format scaffolded files with the project's prettier${detail ? `: ${detail}` : "."}`);
+        return 0;
+    }
+    return files.length;
+};

package/dist/utils/install.d.ts

@@ -0,0 +1,2 @@
+import type { FileFormat } from "./copy.js";
+export declare const installDeps: (projectRoot: string, fileFormat?: FileFormat) => void;

package/dist/utils/install.js

@@ -0,0 +1,54 @@
+import { execSync } from "node:child_process";
+import fs from "fs-extra";
+import path from "node:path";
+const LOCK_FILE_TO_PACKAGE_MANAGER = {
+    "pnpm-lock.yaml": "pnpm",
+    "package-lock.json": "npm",
+};
+const findWorkspaceInfo = (startDir) => {
+    let currentDir = path.resolve(startDir);
+    const { root } = path.parse(currentDir);
+    while (true) {
+        for (const [lockFile, pm] of Object.entries(LOCK_FILE_TO_PACKAGE_MANAGER)) {
+            if (fs.existsSync(path.join(currentDir, lockFile))) {
+                return {
+                    packageManager: pm,
+                    workspaceRoot: currentDir,
+                    isMonorepo: currentDir !== path.resolve(startDir),
+                };
+            }
+        }
+        if (currentDir === root)
+            break;
+        currentDir = path.dirname(currentDir);
+    }
+    return {
+        packageManager: "npm",
+        workspaceRoot: path.resolve(startDir),
+        isMonorepo: false,
+    };
+};
+const getAddCommand = (packageManager) => {
+    if (packageManager === "pnpm")
+        return "pnpm add -D";
+    return "npm install -D";
+};
+const BASE_DEV_DEPS = ["@playwright/test", "checkly"];
+export const installDeps = (projectRoot, fileFormat = "ts") => {
+    const { packageManager, workspaceRoot, isMonorepo } = findWorkspaceInfo(projectRoot);
+    const addCmd = getAddCommand(packageManager);
+    const devDeps = fileFormat === "ts" ? [...BASE_DEV_DEPS, "jiti"] : BASE_DEV_DEPS;
+    const cmd = `${addCmd} ${devDeps.join(" ")}`;
+    if (isMonorepo) {
+        const relativeRoot = path.relative(projectRoot, workspaceRoot) || workspaceRoot;
+        console.log(`Detected ${packageManager} workspace at ${relativeRoot} (root lockfile)`);
+    }
+    console.log(`Installing dependencies with ${packageManager}…`);
+    console.log(`  ${cmd}\n`);
+    execSync(cmd, { cwd: projectRoot, stdio: "inherit" });
+    console.log("\nInstalling Chromium browser…\n");
+    execSync("npx playwright install chromium", {
+        cwd: projectRoot,
+        stdio: "inherit",
+    });
+};

package/dist/utils/prompt.d.ts

@@ -0,0 +1,2 @@
+import type { FileFormat } from "./copy.js";
+export declare const askFileFormat: () => Promise<FileFormat>;

package/dist/utils/prompt.js

@@ -0,0 +1,17 @@
+import prompts from "prompts";
+export const askFileFormat = async () => {
+    const { format } = await prompts({
+        type: "select",
+        name: "format",
+        message: "Config file format (use .mjs if TypeScript causes conflicts)?",
+        choices: [
+            { title: "TypeScript (.ts)", value: "ts" },
+            { title: "JavaScript (.mjs)", value: "mjs" },
+        ],
+        initial: 0,
+    });
+    if (!format) {
+        process.exit(0);
+    }
+    return format;
+};