@activate-core/test-forge 0.1.0

package/dist/core/discover.js

@@ -0,0 +1,103 @@
+/**
+ * testforge — journey discovery.
+ *
+ * Scans a project's source code using the local Claude CLI and asks
+ * it to identify user journeys (login, signup, checkout, etc.), then
+ * write a draft journey markdown file for each one into docs/.
+ *
+ * Important: discovery produces a DRAFT, not the final truth. The AI
+ * will miss some journeys and may guess wrong on others. A developer
+ * is expected to review and fix the generated markdown before relying
+ * on it (this matches the "human review" step of the workflow).
+ *
+ * We let the Claude CLI read the files itself (it has file-reading
+ * tools) rather than stuffing all source code into the prompt, which
+ * keeps this simple and works for projects of any size.
+ */
+import { execFileSync } from 'node:child_process';
+import { loadConfig, splitCommand } from './config.js';
+/** Build the discovery prompt. */
+export function buildDiscoverPrompt(srcDir, docsDir) {
+    return [
+        `You are a senior QA engineer creating per-journey documentation`,
+        `for a project, so a QA tool can generate tests from it.`,
+        ``,
+        `First, read the project map at "testforge.md" if it exists. It`,
+        `lists the project's journeys (grouped by area) and its data layer`,
+        `(database, models, key fields, enums). Use the map as your guide`,
+        `to what exists, so you do not have to re-scan the whole codebase`,
+        `from scratch. Read specific source files under "${srcDir}" only`,
+        `when you need detail for a particular journey.`,
+        ``,
+        `For EACH journey in the map, create one markdown file inside an`,
+        `area subfolder of "${docsDir}". The area is the journey's area from`,
+        `the map (for example "api", "web", "ops" — whatever areas the`,
+        `project has). Put the file at "${docsDir}/<area>/<journey>.md" using`,
+        `a short kebab-case journey name. For example:`,
+        `  "${docsDir}/api/payments.md"`,
+        `  "${docsDir}/web/sign-in.md"`,
+        `  "${docsDir}/ops/login.md"`,
+        `Do NOT put area in the file name (no "api-payments.md") — the area`,
+        `is the folder. Create the area subfolders as needed.`,
+        ``,
+        `Each file should be a RICH description of the journey. Start with`,
+        `this header (required):`,
+        ``,
+        `# Journey: <Name>`,
+        ``,
+        `Type: web        (use "web" for a page/UI, "api" for an endpoint)`,
+        `Route: <path>    (the URL path or endpoint, e.g. /login)`,
+        ``,
+        `Coverage:`,
+        `- functional`,
+        `- security`,
+        `  (add more if relevant: performance, accessibility, session,`,
+        `   race-condition, payment, webhook, data-integrity)`,
+        ``,
+        `Then include whichever of these sections actually apply (skip the`,
+        `ones that do not):`,
+        ``,
+        `Fields:           each input as: <name> (<type>, required|optional)`,
+        `Actions:          numbered steps the user/caller takes`,
+        `Expected:         what should happen on success`,
+        `Negative Cases:   things that should be rejected or fail safely`,
+        `Race Conditions:  concurrency risks (e.g. double-submit, duplicate charge)`,
+        `Webhooks:         any webhooks involved and what must hold (idempotency, signatures)`,
+        `Security Notes:   specific threats to test for this journey`,
+        `Data:             which models/collections this journey reads or writes,`,
+        `                  and the key fields/enum values a test would need to`,
+        `                  seed or verify (use the data layer from the map)`,
+        ``,
+        `Rules:`,
+        `- Base everything on real evidence in the code and the map. Do not`,
+        `  invent routes, fields, or behavior with false confidence.`,
+        `- Where you are unsure, add a line starting with "# TODO:"`,
+        `  describing what the developer must verify.`,
+        `- For the Data section, never include secrets — refer to env var`,
+        `  names only (as in the map).`,
+        `- Capture real risks you notice (e.g. a charge that could happen`,
+        `  twice, a missing webhook signature check, an unvalidated amount).`,
+        `- Create the docs directory if it does not exist.`,
+        `- After creating the files, print the list of journeys you documented`,
+        `  and remind the developer to review them.`,
+    ].join('\n');
+}
+/**
+ * Run discovery. This invokes the Claude CLI with permission to read
+ * and write files in the project. Returns the CLI's text output (the
+ * summary of what it created).
+ */
+export function runDiscover(srcDir, docsDir) {
+    const prompt = buildDiscoverPrompt(srcDir, docsDir);
+    // Use the configured AI command. Note: discovery needs the AI to
+    // read source files and write markdown files. The flags for that
+    // are tool-specific; for Claude we add acceptEdits. Other tools may
+    // need different setup (see README).
+    const { program, args } = splitCommand(loadConfig().aiCommand);
+    const output = execFileSync(program, [...args, '--permission-mode', 'acceptEdits'], {
+        input: prompt,
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return output.trim();
+}

package/dist/core/env-template.js

@@ -0,0 +1,107 @@
+/**
+ * testforge — env template builder.
+ *
+ * Scans the journey docs (and the project map) for environment variable
+ * NAMES that the journeys reference, and writes a single
+ * .env.testing.example. Variables are grouped by area (api / web / ops
+ * / ...) and each one is annotated with the journeys that use it, so a
+ * developer knows exactly which credentials they need for which feature
+ * — and can skip the ones for features they don't run.
+ *
+ * Only names are collected, never values. The developer fills in real
+ * values in their own .env.testing (which stays out of version control).
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { findMarkdownFiles } from './find-files.js';
+/** Pull env var names from a chunk of text. */
+function extractEnvVars(text) {
+    const vars = new Set();
+    // process.env.XXX
+    for (const m of text.matchAll(/process\.env\.([A-Z0-9_]+)/gi)) {
+        vars.add(m[1]);
+    }
+    // backtick-wrapped ALL_CAPS names in "env var" lines
+    for (const line of text.split('\n')) {
+        if (/env var|secret|credential/i.test(line)) {
+            for (const m of line.matchAll(/`([A-Z][A-Z0-9_]{2,})`/g)) {
+                vars.add(m[1]);
+            }
+        }
+    }
+    return vars;
+}
+/** Derive "area" and "journey" from a doc file name like web-payments.md */
+function areaAndJourney(file) {
+    // file is a relative path like "api/payments.md" (folder = area).
+    const noExt = file.replace(/\.md$/, '');
+    const parts = noExt.split('/');
+    if (parts.length >= 2) {
+        return { area: parts[0], journey: parts.slice(1).join('/') };
+    }
+    // Fallback: flat file with no area folder.
+    return { area: 'general', journey: noExt };
+}
+export function runEnvTemplate(docsDir, outPath) {
+    if (!existsSync(docsDir)) {
+        console.log(`No docs found at "${docsDir}". Run \`testforge setup\` first.`);
+        return;
+    }
+    const files = findMarkdownFiles(docsDir);
+    // area -> var -> set of journeys
+    const byArea = new Map();
+    for (const file of files) {
+        const { area, journey } = areaAndJourney(file);
+        const vars = extractEnvVars(readFileSync(`${docsDir}/${file}`, 'utf-8'));
+        if (vars.size === 0)
+            continue;
+        if (!byArea.has(area))
+            byArea.set(area, new Map());
+        const areaMap = byArea.get(area);
+        for (const v of vars) {
+            if (!areaMap.has(v))
+                areaMap.set(v, new Set());
+            areaMap.get(v).add(journey);
+        }
+    }
+    // Also include the project map's vars (no area — call it "shared").
+    if (existsSync('testforge.md')) {
+        const mapVars = extractEnvVars(readFileSync('testforge.md', 'utf-8'));
+        if (mapVars.size > 0) {
+            if (!byArea.has('shared'))
+                byArea.set('shared', new Map());
+            const shared = byArea.get('shared');
+            for (const v of mapVars) {
+                if (!shared.has(v))
+                    shared.set(v, new Set(['project map']));
+            }
+        }
+    }
+    if (byArea.size === 0) {
+        console.log('No environment variables found in the docs.');
+        return;
+    }
+    // Build the file.
+    const lines = [
+        '# .env.testing.example',
+        '#',
+        '# Test credentials the generated tests/seeds need, grouped by area.',
+        '# Copy this to .env.testing and fill in real values.',
+        '# Only variables for the features you actually run are required.',
+        '# Keep .env.testing OUT of version control.',
+        '',
+    ];
+    for (const area of [...byArea.keys()].sort()) {
+        lines.push(`# ${'='.repeat(40)}`);
+        lines.push(`# ${area.toUpperCase()}`);
+        lines.push(`# ${'='.repeat(40)}`);
+        const areaMap = byArea.get(area);
+        for (const v of [...areaMap.keys()].sort()) {
+            const journeys = [...areaMap.get(v)].sort().join(', ');
+            lines.push(`${v}=            # used by: ${journeys}`);
+        }
+        lines.push('');
+    }
+    writeFileSync(outPath, lines.join('\n'), 'utf-8');
+    console.log(`Env template written to ${outPath}`);
+    console.log('Copy it to .env.testing and fill in real values.');
+}

package/dist/core/find-files.js

@@ -0,0 +1,34 @@
+/**
+ * testforge — recursive markdown finder.
+ *
+ * Walks a docs directory and finds every .md file inside it, however
+ * deeply nested. For each file it returns the path relative to the
+ * docs root, so the same folder structure can be recreated in the
+ * output. For example, docs/api/create.md -> "api/create.md".
+ *
+ * This is what lets a project keep separate journeys for, say, an
+ * api/ folder and a webapp/ folder, and get matching test folders.
+ */
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+/**
+ * Return the relative paths of all .md files under rootDir.
+ * Example result: ["api/create.md", "webapp/sign-in.md"]
+ */
+export function findMarkdownFiles(rootDir) {
+    const results = [];
+    function walk(dir) {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full); // go deeper into sub-folders
+            }
+            else if (entry.name.endsWith('.md')) {
+                results.push(relative(rootDir, full));
+            }
+        }
+    }
+    walk(rootDir);
+    return results;
+}

package/dist/core/generator.js

@@ -0,0 +1,90 @@
+/**
+ * testforge — functional test case generator.
+ *
+ * Takes a parsed Journey and produces a list of test cases.
+ * For now this generates functional cases only (positive and
+ * negative) based on each field. Security, performance, and
+ * actual Playwright/Jest code come in later steps.
+ *
+ * The idea: a developer writes a few lines of markdown, and one
+ * field expands into several meaningful test cases automatically.
+ */
+import { SECURITY_PAYLOADS } from './security-payloads.js';
+/** Generate test cases for a single field. */
+function casesForField(journeyId, field) {
+    const cases = [];
+    // If the field is required, an empty value should fail.
+    if (field.required) {
+        cases.push({
+            journeyId,
+            title: `${field.name}: empty value should be rejected`,
+            expect: 'fail',
+        });
+    }
+    // Type-specific cases.
+    if (field.type === 'email') {
+        cases.push({
+            journeyId,
+            title: `${field.name}: valid email should be accepted`,
+            expect: 'pass',
+        });
+        cases.push({
+            journeyId,
+            title: `${field.name}: invalid email format should be rejected`,
+            expect: 'fail',
+        });
+    }
+    if (field.type === 'password') {
+        cases.push({
+            journeyId,
+            title: `${field.name}: valid password should be accepted`,
+            expect: 'pass',
+        });
+        cases.push({
+            journeyId,
+            title: `${field.name}: too short password should be rejected`,
+            expect: 'fail',
+        });
+    }
+    if (field.type === 'text' || field.type === 'number') {
+        cases.push({
+            journeyId,
+            title: `${field.name}: valid value should be accepted`,
+            expect: 'pass',
+        });
+    }
+    return cases;
+}
+/** Generate all functional test cases for a journey. */
+export function generateTestCases(journey) {
+    const cases = [];
+    // One happy-path case: everything filled correctly.
+    cases.push({
+        journeyId: journey.id,
+        title: `${journey.name}: successful flow with all valid inputs`,
+        expect: 'pass',
+    });
+    // Then per-field cases.
+    for (const field of journey.fields) {
+        cases.push(...casesForField(journey.id, field));
+    }
+    // Security cases — only if this journey asked for security coverage.
+    if (journey.coverage.includes('security')) {
+        for (const field of journey.fields) {
+            // Only attack text-like fields (skip numbers).
+            const textLike = field.type === 'text' ||
+                field.type === 'email' ||
+                field.type === 'password';
+            if (!textLike)
+                continue;
+            for (const attack of SECURITY_PAYLOADS) {
+                cases.push({
+                    journeyId: journey.id,
+                    title: `${field.name}: ${attack.name} should be rejected`,
+                    expect: 'fail',
+                });
+            }
+        }
+    }
+    return cases;
+}

package/dist/core/index.js

@@ -0,0 +1,7 @@
+/**
+ * testforge — core library entry point.
+ *
+ * Currently exposes the package version only.
+ * Model, parser, and engines will be added in upcoming steps.
+ */
+export const VERSION = '0.1.0';

package/dist/core/init.js

@@ -0,0 +1,67 @@
+/**
+ * testforge — init command.
+ *
+ * Scans the project with the AI and writes a testforge.config.json
+ * tailored to the project's layout: where api vs web tests should go,
+ * where seed files belong, and the test file extension the project
+ * uses. The goal is that a user never hand-writes this config — init
+ * figures it out from the existing structure.
+ *
+ * Nothing is hardcoded for a specific framework or layout; the AI
+ * infers it from what the project actually looks like.
+ */
+import { execFileSync } from 'node:child_process';
+import { loadConfig, splitCommand } from './config.js';
+/** Build the prompt that asks the AI to write testforge.config.json. */
+export function buildInitPrompt() {
+    return [
+        `You are setting up the QA tool "testforge" in this project. Inspect`,
+        `the project's structure and write a configuration file named`,
+        `"testforge.config.json" at the project root.`,
+        ``,
+        `Look at how the project is organised and where tests already live`,
+        `(or should live), so generated tests land in the right place and`,
+        `match the project's conventions. Determine:`,
+        ``,
+        `- testOutput: an object mapping each AREA of the project to a`,
+        `  folder. Areas are not a fixed list — use whatever this project`,
+        `  actually has (e.g. "api", "web", "ops", "lambda", "worker").`,
+        `  Point each to where that area's tests belong (e.g. in a monorepo,`,
+        `  api -> "packages/api/test", web -> "packages/webapp/tests", ops ->`,
+        `  "packages/ops/tests"; in a simple app, one area mapping to "tests").`,
+        `- framework: an object mapping each area to its test framework`,
+        `  (e.g. { "api": "jest", "web": "playwright", "ops": "playwright" }),`,
+        `  based on what the project already uses for that area.`,
+        `  the api tests, e.g. "packages/api/test/helpers/seed").`,
+        `- testExtension: ".test.ts" or ".test.js" — match what existing`,
+        `  tests use, or the project's language (TypeScript vs JavaScript).`,
+        `- aiCommand: keep it as "claude -p" unless there is a clear reason`,
+        `  to change it.`,
+        ``,
+        `Write valid JSON only, in this shape:`,
+        ``,
+        `{`,
+        `  "aiCommand": "claude -p",`,
+        `  "testOutput": { "<area>": "<path>" },`,
+        `  "framework": { "<area>": "<jest|playwright|...>" },`,
+        `  "seedOutput": "<path>",`,
+        `  "testExtension": ".test.ts"`,
+        `}`,
+        ``,
+        `Base every path on real evidence in the project (existing test`,
+        `folders, package layout, tsconfig presence). Create the file.`,
+        `After writing it, print a short summary of the choices you made and`,
+        `why, so the developer can confirm or adjust.`,
+    ].join('\n');
+}
+/** Run init via the configured AI command. */
+export function runInit() {
+    const prompt = buildInitPrompt();
+    const { program, args } = splitCommand(loadConfig().aiCommand);
+    const output = execFileSync(program, [...args, '--permission-mode', 'acceptEdits'], {
+        input: prompt,
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return output.trim();
+}

package/dist/core/map.js

@@ -0,0 +1,90 @@
+/**
+ * testforge — project map builder.
+ *
+ * Scans the project once with the AI and writes a short, high-level
+ * map to testforge.md at the project root (similar to CLAUDE.md).
+ *
+ * The map has two parts:
+ *   1. Journeys — a short list of features/areas, one line each.
+ *   2. Data layer — how the project stores data (db type, models,
+ *      key fields, enums), so tests can later seed and verify data.
+ *
+ * Purpose: the AI reads this small map to understand the project
+ * instead of re-reading the whole codebase every time. Refreshed
+ * only when the code changes.
+ *
+ * Nothing about any specific database is hardcoded — the AI detects
+ * whatever the project actually uses. Secrets are never captured;
+ * only env var names.
+ */
+import { execFileSync } from 'node:child_process';
+import { loadConfig, splitCommand } from './config.js';
+/** Build the prompt that asks the AI to produce the project map. */
+export function buildMapPrompt(srcDir) {
+    return [
+        `You are a senior engineer mapping a codebase so a QA tool can`,
+        `plan tests and seed test data. Read the source code under`,
+        `"${srcDir}" and produce a SHORT, high-level map of the project.`,
+        ``,
+        `The map has two parts: journeys and the data layer.`,
+        ``,
+        `PART 1 — Journeys.`,
+        `Group journeys by area based on the folder structure (for example`,
+        `"api" and "webapp"). Under each area, list each journey as a single`,
+        `line: a short name and a brief one-line description.`,
+        ``,
+        `PART 2 — Data layer.`,
+        `Figure out, from the code, how this project stores data, so tests`,
+        `can later seed and verify it. Capture:`,
+        `- Database type (e.g. MongoDB, MySQL, PostgreSQL) — only what you`,
+        `  find real evidence for.`,
+        `- The models / collections / tables, with their key fields.`,
+        `- Important enum-like values a field can take (e.g. a status field`,
+        `  that is "unpaid" or "paid").`,
+        `- Any relationships that matter (e.g. an order references a user id).`,
+        `- The env var(s) used for the connection, by NAME only (e.g.`,
+        `  DATABASE_URL). Never copy actual connection strings or secrets.`,
+        `If the project has no database, say "No database detected" and skip`,
+        `this part.`,
+        ``,
+        `Write the map to the file "testforge.md" using this format:`,
+        ``,
+        `# Project Map`,
+        ``,
+        `## Journeys`,
+        ``,
+        `### api`,
+        `- project — create and manage projects`,
+        `- login — user authentication`,
+        ``,
+        `### webapp`,
+        `- dashboard — overview of the user's projects`,
+        ``,
+        `## Data Layer`,
+        ``,
+        `- Database: <type>, connection from env var <NAME>`,
+        `- Models / collections:`,
+        `  - <name>: <key fields>; <important enums or relations>`,
+        ``,
+        `Rules:`,
+        `- Keep journeys SHORT — one line each. Detailed fields/steps belong`,
+        `  in per-journey docs, not here.`,
+        `- For the data layer, capture enough that a test could build a valid`,
+        `  record (right collection/table, right key fields, right enum`,
+        `  values), but stay concise — no full schemas dumped verbatim.`,
+        `- Base everything on real evidence in the code. Do not invent.`,
+        `- Never include secrets or real connection strings — env var names only.`,
+        `- After writing the file, print a short summary of what you found.`,
+    ].join('\n');
+}
+/** Run the map builder via the configured AI command. */
+export function runMap(srcDir) {
+    const prompt = buildMapPrompt(srcDir);
+    const { program, args } = splitCommand(loadConfig().aiCommand);
+    const output = execFileSync(program, [...args, '--permission-mode', 'acceptEdits'], {
+        input: prompt,
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return output.trim();
+}

package/dist/core/model.js

@@ -0,0 +1,9 @@
+/**
+ * testforge — core data model.
+ *
+ * These types describe what a "user journey" looks like internally.
+ * Markdown files are parsed into a Journey, and test generators read
+ * from a Journey to produce test cases. This is the single shared
+ * shape that every part of the framework depends on.
+ */
+export {};

package/dist/core/parser.js

@@ -0,0 +1,121 @@
+/**
+ * testforge — markdown journey parser.
+ *
+ * Reads a journey markdown file line by line and builds a Journey
+ * object from it. The expected markdown format is:
+ *
+ *   # Journey: Sign In
+ *
+ *   Type: web
+ *   Route: /login
+ *
+ *   Coverage:
+ *   - functional
+ *   - security
+ *
+ *   Fields:
+ *   - email (email, required)
+ *   - password (password, required)
+ */
+/**
+ * Turn a journey name into a safe file-name id.
+ * "Sign In" -> "sign-in"
+ * "Resume Builder (Create / Edit Resume)" -> "resume-builder-create-edit-resume"
+ *
+ * We keep only letters, numbers, and spaces, then turn spaces into
+ * dashes. This removes brackets, slashes, and other characters that
+ * are not safe in file names.
+ */
+function toId(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '') // drop anything that is not a letter, number, space, or dash
+        .replace(/\s+/g, '-') // spaces -> dashes
+        .replace(/-+/g, '-') // collapse multiple dashes into one
+        .replace(/^-|-$/g, ''); // trim leading/trailing dashes
+}
+/**
+ * Parse a single field line like "email (email, required)".
+ *
+ * Returns null if the line does not match the simple field shape.
+ * Rich journey files often have comments, extra notes, or formats
+ * the basic parser does not understand — we skip those here rather
+ * than failing, because the full markdown is still passed to the AI
+ * via rawMarkdown. The parsed fields are only used by the basic
+ * fallback generator.
+ */
+function parseField(line) {
+    // Ignore comment lines (starting with #) and anything without brackets.
+    const text = line.replace(/^-\s*/, '').trim();
+    if (text.startsWith('#')) {
+        return null;
+    }
+    const match = text.match(/^(\w+)\s*\(([^)]*)\)/);
+    if (!match) {
+        return null;
+    }
+    const name = match[1];
+    const parts = match[2].split(',').map((p) => p.trim());
+    // Only accept known field types; otherwise skip this line.
+    const known = ['text', 'email', 'password', 'number'];
+    const type = known.includes(parts[0])
+        ? parts[0]
+        : 'text'; // default unknown types to text
+    const required = parts.includes('required');
+    return { name, type, required };
+}
+/** Parse a full markdown string into a Journey object. */
+export function parseJourney(markdown) {
+    const lines = markdown.split('\n').map((l) => l.trim());
+    let name = '';
+    let type = 'web';
+    let route = '';
+    const coverage = [];
+    const fields = [];
+    // Track which list we are currently reading ("coverage" or "fields").
+    let section = null;
+    for (const line of lines) {
+        if (line === '')
+            continue;
+        if (line.startsWith('# Journey:')) {
+            name = line.replace('# Journey:', '').trim();
+            section = null;
+        }
+        else if (line.startsWith('Type:')) {
+            type = line.replace('Type:', '').trim();
+            section = null;
+        }
+        else if (line.startsWith('Route:')) {
+            route = line.replace('Route:', '').trim();
+            section = null;
+        }
+        else if (line.startsWith('Coverage:')) {
+            section = 'coverage';
+        }
+        else if (line.startsWith('Fields:')) {
+            section = 'fields';
+        }
+        else if (line.startsWith('-')) {
+            // A list item. Where it goes depends on the current section.
+            if (section === 'coverage') {
+                coverage.push(line.replace(/^-\s*/, '').trim());
+            }
+            else if (section === 'fields') {
+                const field = parseField(line);
+                if (field) {
+                    fields.push(field);
+                }
+            }
+        }
+    }
+    return {
+        id: toId(name),
+        name,
+        type,
+        route,
+        coverage,
+        fields,
+        rawMarkdown: markdown,
+    };
+}

package/dist/core/playwright-writer.js

@@ -0,0 +1,47 @@
+/**
+ * testforge — Playwright test file writer.
+ *
+ * Takes a Journey and its generated test cases and produces the
+ * text of a runnable Playwright test file (.test.ts). It does not
+ * write to disk itself; it returns the file content as a string so
+ * the caller decides where to save it.
+ *
+ * The generated tests use placeholder selectors and values, marked
+ * with TODO comments, because testforge cannot know the real page
+ * structure. A developer fills those in. Every test is tagged
+ * @generated so it is easy to spot auto-created tests.
+ */
+/** Build the import header and describe block opening. */
+function header(journey) {
+    return [
+        `import { test, expect } from "@playwright/test";`,
+        ``,
+        `// @generated by testforge — review before relying on these tests.`,
+        `test.describe("${journey.name}", () => {`,
+        ``,
+    ].join('\n');
+}
+/** Build a single Playwright test block from one test case. */
+function testBlock(journey, testCase) {
+    const lines = [];
+    lines.push(`  // @generated`);
+    lines.push(`  test("${testCase.title}", async ({ page }) => {`);
+    lines.push(`    await page.goto("${journey.route}");`);
+    lines.push(``);
+    lines.push(`    // TODO: fill in the steps for this test.`);
+    if (testCase.expect === 'pass') {
+        lines.push(`    // This case is expected to succeed.`);
+        lines.push(`    // TODO: assert the success outcome (e.g. redirect or success message).`);
+    }
+    else {
+        lines.push(`    // This case is expected to fail / be rejected.`);
+        lines.push(`    // TODO: assert the error outcome (e.g. validation message shown).`);
+    }
+    lines.push(`  });`);
+    return lines.join('\n');
+}
+/** Build the full Playwright test file content for a journey. */
+export function writePlaywrightFile(journey, cases) {
+    const blocks = cases.map((c) => testBlock(journey, c)).join('\n\n');
+    return header(journey) + blocks + `\n\n});\n`;
+}