@activate-core/test-forge 0.19.3 → 1.0.1

package/dist/core/docs/discover.js

@@ -23,6 +23,7 @@ import { DEEP_DOC_GUIDANCE } from './doc-guidance.js';
 import { promptConfirm } from '../prompt.js';
 import { loadSourceChoice, resolveDocsSource, saveJourneyReferences, saveSourceChoice, } from './source-of-truth.js';
 import { analyzeReference, draftDocsFromReference, DIFF_PATH, } from './reference.js';
+import { reviewDocs } from './review.js';
 /** Scope line: one journey, or all of them. */
 function scopeLines(journey) {
     return journey
@@ -180,7 +181,7 @@ export async function runDiscover(srcDir, docsDir, opts = {}, journey) {
             if (!ok) {
                 console.log('Basing docs on testforge.md instead.\n');
                 saveSourceChoice({ mode: 'map' });
-                return runCodeDiscover(srcDir, docsDir, journey);
+                return discoverFromCode(srcDir, docsDir, journey);
             }
         }
         // Is this the product's specification, or one feature's? A ticket's PDF
@@ -246,6 +247,10 @@ export async function runDiscover(srcDir, docsDir, opts = {}, journey) {
         for (const path of restored) {
             writeFileSync(join(docsDir, path), before.get(path), 'utf-8');
         }
+        // Second, focused pass per written doc: the drafting pass covers every
+        // journey at once and drops the small scenarios.
+        const written = [...added, ...rewritten.filter((p) => !restored.includes(p))];
+        await reviewDocs(docsDir, written, srcDir, source.reference);
         if (wholeProject) {
             saveSourceChoice({ mode: 'reference', reference: source.reference });
             if (added.length)
@@ -270,5 +275,15 @@ export async function runDiscover(srcDir, docsDir, opts = {}, journey) {
         return out;
     }
     saveSourceChoice({ mode: 'map' });
-    return runCodeDiscover(srcDir, docsDir, journey);
+    return discoverFromCode(srcDir, docsDir, journey);
+}
+/** Draft from the code, then review every doc the draft wrote or changed. */
+async function discoverFromCode(srcDir, docsDir, journey) {
+    const before = snapshotDocs(docsDir);
+    const out = runCodeDiscover(srcDir, docsDir, journey);
+    const changed = [...snapshotDocs(docsDir)]
+        .filter(([path, text]) => before.get(path) !== text && !notAJourneyDoc(path, text))
+        .map(([path]) => path);
+    await reviewDocs(docsDir, changed, srcDir);
+    return out;
 }

package/dist/core/docs/doc-guidance.js

@@ -81,6 +81,36 @@ export const DEEP_DOC_GUIDANCE = [
     `  failure is an inconsistency, not a spec defect. Never use [observed]`,
     `  to override or soften a [spec] criterion.`,
     ``,
+    `METHOD. Work through these steps for every journey, in order:`,
+    `1. CONTROLS. Start the doc with a "## Controls" table listing EVERY`,
+    `   interactive element and where it appears: each input, button, link,`,
+    `   checkbox, code box, dropdown, pop-up, menu item, and the page itself.`,
+    `   Secondary controls count as much as the main form: Resend, Back,`,
+    `   show/hide, close, apply, sign-out, provider buttons. Apply every`,
+    `   [baseline] item that fits to EACH row, not just to the main form.`,
+    `2. COMBINATIONS. When the source states a rule across alternatives and`,
+    `   conditions ("for login and sign-up, also on a slow connection and on`,
+    `   a retry"), write one criterion per combination (login × slow, login ×`,
+    `   retry, sign-up × slow, sign-up × retry), never just one of them.`,
+    `3. CODE BRANCHES. Read the code the journey runs — screens, components,`,
+    `   client API calls, and the server handlers they reach (related repos`,
+    `   included) — and walk EVERY validation rule, error response and`,
+    `   conditional branch: account states (unverified, banned, deleted,`,
+    `   other roles), limits and expiry, empty and failure states, refresh`,
+    `   and deep links, what is stored in the browser and when it is`,
+    `   cleared, input handling (paste, clearing after an error). Each branch`,
+    `   becomes an [observed] criterion, or a Question when only product can`,
+    `   say what it should do. A skipped branch is the commonest gap.`,
+    `4. QUOTE [spec]. End every [spec] criterion with the source sentence it`,
+    `   rests on, quoted: (source: "..."). A criterion you cannot quote is`,
+    `   NOT [spec] — make it [baseline] or [observed], or a Question.`,
+    `5. SHARED RULES. A rule shared by several journeys (password, redirects,`,
+    `   attack payloads, accepted formats) uses the same cases and values in`,
+    `   every doc.`,
+    `6. COVERAGE. After the numbered sections, add "## Coverage": one row per`,
+    `   control from step 1, naming the section that covers each [baseline]`,
+    `   item that fits it. A blank cell is a gap — fill it before finishing.`,
+    ``,
     `TEST DATA. Tests fill data themselves. Never ask for an exact value:`,
     `valid data comes from the stated or [observed] rules; invalid data`,
     `breaks one rule at a time; a choice control is filled with an option`,
@@ -100,6 +130,7 @@ export const DEEP_DOC_GUIDANCE = [
     `Organise the body with numbered "## N. <Section>" headings, ONE`,
     `concern per section, because each section later becomes its own`,
     `focused test file — so the richer and better-separated the sections,`,
-    `the better the test suite. Put "## Test setup" and "## Questions for`,
-    `product (not asserted)" last, without numbers.`,
+    `the better the test suite. "## Controls" comes first; "## Coverage",`,
+    `"## Test setup" and "## Questions for product (not asserted)" come`,
+    `last. None of these four is numbered.`,
 ].join('\n');

package/dist/core/docs/review.js

@@ -0,0 +1,81 @@
+/**
+ * testforge — journey doc gap review.
+ *
+ * One drafting pass writes every journey at once, and it reliably runs out
+ * of attention before the small things: a Resend button with no failure
+ * cases, a code box nobody pasted into, one combination of the four the
+ * source asked for, a server branch never read. So each freshly written doc
+ * gets a second, focused pass of its own: re-run the method from
+ * DEEP_DOC_GUIDANCE against that one journey, fill what is missing, and fix
+ * tiers that claim more than their source says. The reviewer edits the file
+ * in place and never deletes a sound criterion.
+ */
+import { join } from 'node:path';
+import { loadConfig, splitCommand, withEditTools, withReferenceTools } from '../project/config.js';
+import { runWithStdin } from '../generate/ai-generator.js';
+import { pool } from '../generate/run-generate.js';
+import { DEEP_DOC_GUIDANCE } from './doc-guidance.js';
+/** Build the prompt that reviews and completes ONE journey doc. */
+export function buildReviewPrompt(docPath, srcDir, reference) {
+    const source = reference
+        ? `The source of truth is the reference: ${reference}. Read it fully; [spec]` +
+            ` criteria come only from it, and the code under "${srcDir}" (and any` +
+            ` related repos) supplies technical detail and [observed] rules.`
+        : `The source of truth is the code under "${srcDir}" (and any related repos).`;
+    return [
+        `You are a senior QA engineer reviewing ONE journey doc that a first`,
+        `pass drafted: "${docPath}". Your job is to make it COMPLETE, so that`,
+        `no scenario a careful QA engineer would test is missing.`,
+        ``,
+        source,
+        ``,
+        `The doc must follow this guidance:`,
+        DEEP_DOC_GUIDANCE,
+        ``,
+        `Review it step by step against the METHOD above and fix what you find:`,
+        `- Controls: is every interactive element of this journey in the table,`,
+        `  secondary controls included? Add the missing ones.`,
+        `- Baseline: does every control have every [baseline] item that fits`,
+        `  it? Add the missing criteria to the right section.`,
+        `- Combinations: is every combination the source states written out?`,
+        `- Code branches: read the code this journey runs, client and server.`,
+        `  Is every validation, error response and conditional branch an`,
+        `  [observed] criterion or a Question? Add the missing ones.`,
+        `- Tiers: does every [spec] criterion quote a real source sentence?`,
+        `  Re-tag any that does not. Does any criterion contradict the code`,
+        `  with nothing to test (a rule the screen has no way to break)? Turn`,
+        `  it into a "Likely defect" note or a Question.`,
+        `- Shared rules: read the other docs in the same folder and make shared`,
+        `  cases (password, redirects, payloads, formats) identical.`,
+        `- Coverage: rebuild the "## Coverage" table; no blank cell may remain.`,
+        ``,
+        `Rules: edit "${docPath}" in place and touch no other file. Keep every`,
+        `sound criterion. Keep the header, the section numbering style and the`,
+        `last sections (Coverage, Test setup, Questions for product). Never`,
+        `write "# TODO". When done, print ONE line: what you added or fixed,`,
+        `with counts.`,
+    ].join('\n');
+}
+/**
+ * Review each doc (paths relative to docsDir) in its own AI pass, a few at
+ * a time. A failed review leaves that doc as drafted and is reported, never
+ * fatal: the draft is still a valid doc.
+ */
+export async function reviewDocs(docsDir, docs, srcDir, reference) {
+    if (!docs.length)
+        return;
+    const config = loadConfig();
+    const base = splitCommand(config.aiCommand);
+    const { program, args } = reference ? withReferenceTools(base) : withEditTools(base);
+    console.log(`\nReviewing ${docs.length} journey doc(s) for missing scenarios...`);
+    await pool(docs, Math.max(1, config.aiConcurrency ?? 4), async (doc) => {
+        const path = join(docsDir, doc);
+        try {
+            const out = await runWithStdin(program, args, buildReviewPrompt(path, srcDir, reference), config.aiTimeoutMs);
+            console.log(`  ${doc}: ${out.trim().split('\n').pop() ?? 'reviewed'}`);
+        }
+        catch (err) {
+            console.log(`  ${doc}: review failed, kept as drafted (${err.message.split('\n')[0]})`);
+        }
+    });
+}

package/dist/core/docs/source-of-truth.js

@@ -22,7 +22,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { isInteractive, promptChoice, promptLine } from '../prompt.js';
-import { SOURCE_PATH } from '../paths.js';
+import { SOURCE_PATH, ensureStateDirIgnored } from '../paths.js';
 /** Read the remembered source choice, or null if none/invalid. */
 export function loadSourceChoice() {
     if (!existsSync(SOURCE_PATH))
@@ -58,6 +58,7 @@ export function saveSourceChoice(choice) {
     if (journeys && Object.keys(journeys).length)
         next.journeys = journeys;
     mkdirSync(dirname(SOURCE_PATH), { recursive: true });
+    ensureStateDirIgnored();
     writeFileSync(SOURCE_PATH, JSON.stringify(next, null, 2), 'utf-8');
 }
 /**

package/dist/core/gates/lint.js

@@ -17,7 +17,7 @@
  */
 import { spawnSync } from 'node:child_process';
 import { resolve } from 'node:path';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 /** Walk up from a file to the nearest package that has ESLint installed. */
 function eslintFor(file) {
@@ -77,7 +77,9 @@ export function lintGenerated(files) {
             encoding: 'utf-8',
             timeout: 120_000,
         });
-        const after = readProblems(g.bin, cwd, g.files);
+        let after = readProblems(g.bin, cwd, g.files);
+        if (relaxTypingRules(after.typingRules))
+            after = readProblems(g.bin, cwd, g.files);
         checked += g.files.length;
         fixed += Math.max(0, before - after.count);
         remaining.push(...after.lines);
@@ -87,6 +89,32 @@ export function lintGenerated(files) {
 function countProblems(bin, cwd, files) {
     return readProblems(bin, cwd, files).count;
 }
+/**
+ * Strictness rules a house config applies to app code that say nothing about
+ * whether a generated TEST is right: `any` in a fixture, `require` in a
+ * CommonJS helper. Left in place they fail `npm run lint` in CI on files no
+ * one hand-edits, so a generated file gets a header turning off exactly the
+ * ones it trips — every other rule stays on.
+ */
+const TYPING_RULES = new Set([
+    '@typescript-eslint/no-explicit-any',
+    '@typescript-eslint/no-require-imports',
+    '@typescript-eslint/no-var-requires',
+    '@typescript-eslint/ban-ts-comment',
+]);
+/** Add the header to each file; true when any file changed. */
+function relaxTypingRules(byFile) {
+    let changed = false;
+    for (const [file, rules] of byFile) {
+        if (!rules.size)
+            continue;
+        const text = readFileSync(file, 'utf-8');
+        const header = `/* eslint-disable ${[...rules].sort().join(', ')} -- generated by testforge */\n`;
+        writeFileSync(file, header + text, 'utf-8');
+        changed = true;
+    }
+    return changed;
+}
 function readProblems(bin, cwd, files) {
     const res = spawnSync(bin, ['-f', 'json', '--no-error-on-unmatched-pattern', ...files], {
         cwd,
@@ -99,14 +127,20 @@ function readProblems(bin, cwd, files) {
         parsed = JSON.parse(res.stdout || '[]');
     }
     catch {
-        return { count: 0, lines: [] }; // linter unavailable or output unusable
+        return { count: 0, lines: [], typingRules: new Map() }; // linter unavailable or output unusable
     }
     const lines = [];
+    const typingRules = new Map();
     let count = 0;
     for (const file of parsed) {
         for (const m of file.messages) {
             if (m.severity !== 2)
                 continue; // warnings do not fail a build
+            if (m.ruleId && TYPING_RULES.has(m.ruleId)) {
+                const set = typingRules.get(file.filePath) ?? new Set();
+                set.add(m.ruleId);
+                typingRules.set(file.filePath, set);
+            }
             count += 1;
             if (lines.length < 20) {
                 const rel = file.filePath.replace(cwd + '/', '');
@@ -114,5 +148,5 @@ function readProblems(bin, cwd, files) {
             }
         }
     }
-    return { count, lines };
+    return { count, lines, typingRules };
 }

package/dist/core/generate/ai-generator.js

@@ -18,7 +18,7 @@ const MAP_PATH = 'testforge.md';
  * Spawn a command, feed `input` on stdin, resolve with its stdout.
  * Async (unlike execFileSync) so many calls can run concurrently.
  */
-function runWithStdin(program, args, input, timeoutMs = 300_000) {
+export function runWithStdin(program, args, input, timeoutMs = 300_000) {
     return new Promise((resolve, reject) => {
         const child = spawn(program, args, {
             stdio: ['pipe', 'pipe', 'pipe'],

package/dist/core/generate/harness.js

@@ -303,7 +303,7 @@ export function generateHarnessAsync(harnessPath, framework) {
  * dir, treats *.test.js as specs, and runs the testkit's setup() once via
  * globalSetup (mints/populates tokens before any worker starts).
  */
-export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage, category = 'web') {
+export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage, category = 'web', outputDirRelToPackage = 'test-results') {
     return [
         `// @generated by testforge`,
         `// Minimal Playwright config so testforge's generated specs run.`,
@@ -315,6 +315,9 @@ export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage, c
         `  testMatch: /.*\\.(test|spec)\\.[jt]s$/,`,
         `  globalSetup: require.resolve('${globalSetupRelToPackage}'),`,
         `  timeout: 60000,`,
+        `  // Run output (failure reports, traces) stays with testforge's local state,`,
+        `  // which is not committed.`,
+        `  outputDir: '${outputDirRelToPackage}',`,
         `  // Serial, like the Jest config: these suites share ONE test database`,
         `  // and seed/reset it, so parallel workers race on the same rows and the`,
         `  // same run gives different answers twice. It also keeps --headed to a`,

package/dist/core/generate/run-generate.js

@@ -17,8 +17,8 @@
  * generated-tests/ when not configured.
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync, } from 'node:fs';
-import { join, dirname, basename, extname } from 'node:path';
-import { CACHE_PATH } from '../paths.js';
+import { join, dirname, basename, extname, relative, resolve, sep } from 'node:path';
+import { CACHE_PATH, RESULTS_DIR, ensureStateDirIgnored } from '../paths.js';
 import { lintGenerated } from '../gates/lint.js';
 import { parseJourney, notAJourneyDoc } from '../docs/parser.js';
 import { writeCoverageManifest } from '../gates/coverage.js';
@@ -27,7 +27,8 @@ import { aiFailureNote, aiUnavailableReason, confirmAiAlive, lastAiFailureWasPro
 import { generateTestCases } from './generator.js';
 import { writeDeferredStub } from './playwright-writer.js';
 import { generateWithAI, generateWithAIAsync, repairWithAIAsync, } from './ai-generator.js';
-import { verifyFiles } from './verify.js';
+import { verifyFiles, browserPreflight } from './verify.js';
+import { packageRoot } from '../run/run-tests.js';
 import { groundJourney } from '../docs/grounding.js';
 import { generateSeed } from './seed-generator.js';
 import { isSyntaxValid, checkTestGates } from '../gates/validate.js';
@@ -45,7 +46,7 @@ const GEN_CONCURRENCY = 4;
  * the results. Keeps a heavy fan-out (15 AI calls) from spawning 15
  * processes at once while still finishing in a few waves, not serially.
  */
-async function pool(items, limit, fn) {
+export async function pool(items, limit, fn) {
     const results = new Array(items.length);
     let next = 0;
     async function worker() {
@@ -183,6 +184,20 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
     const ext = config.testExtension ?? '.test.ts';
     const seedDir = config.seedOutput ?? 'generated-tests/seed';
     const seedExt = ext.endsWith('.js') ? '.seed.js' : '.seed.ts';
+    // A browser that cannot start fails every verify, and each failure would be
+    // sent for repair. Find out once, before any AI call is spent.
+    if (useAI && verifyOn) {
+        for (const area of Object.keys(config.testOutput ?? {})) {
+            if (resolveFramework(config, area, area) !== 'playwright')
+                continue;
+            const problem = browserPreflight(packageRoot(testDirForType(config, area)));
+            if (problem) {
+                throw new Error(`Cannot verify "${area}" tests: ${problem}.\n` +
+                    'Fix that and re-run, or pass --no-verify to write tests without running them.');
+            }
+        }
+    }
+    ensureStateDirIgnored();
     const cache = loadCache(CACHE_PATH);
     const results = [];
     resetAiSession();
@@ -559,6 +574,10 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
         const lintTargets = [
             ...testFiles.map((t) => (typeof t === 'string' ? t : t.path)),
             ...(seedPath ? [seedPath] : []),
+            // The shared harness and the runner config are generated too, and CI
+            // lints them like any other file.
+            // Only files testforge generated: a project's own config is never edited.
+            ...[harnessPath, join(dirname(testDir), 'playwright.config.js')].filter((f) => !!f && existsSync(f) && readFileSync(f, 'utf-8').includes(GEN_MARKER)),
         ];
         const lint = lintGenerated(lintTargets);
         if (lint.fixed > 0) {
@@ -578,6 +597,13 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
         if (useAI && verifyOn && targets.length) {
             for (let attempt = 0; attempt <= verifyAttempts; attempt += 1) {
                 const outcome = verifyFiles(config, journey.area, targets);
+                if (outcome.infra) {
+                    // Not the tests' fault, so no repair; and not verified, so the
+                    // journey stays uncached and the next run checks it again.
+                    verified = false;
+                    warnings.push(`verify: not run — ${outcome.reason}`);
+                    break;
+                }
                 if (!outcome.ran) {
                     // Say WHY once. The reason is a property of the project (no env
                     // file, no runner), not of this journey, so repeating it per
@@ -689,25 +715,39 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
  * Config files are written only if absent, so a project's hand-tuned config is
  * never clobbered. `harnessDir` is the area's helpers dir (where setup lives).
  */
-function writeHarnessConfigs(framework, areaDir, harnessDir, area) {
-    const pkgRoot = dirname(areaDir);
-    const rel = areaDir.slice(pkgRoot.length + 1) || '.';
+export function writeHarnessConfigs(framework, areaDir, harnessDir, area) {
+    const posix = (from, to) => relative(from, resolve(to)).split(sep).join('/') || '.';
     if (framework === 'playwright') {
         const gsPath = join(harnessDir, 'global-setup.js');
         writeFileSync(gsPath, globalSetupContent(), 'utf-8');
-        const cfg = join(pkgRoot, 'playwright.config.js');
+        const home = configHome(areaDir, 'playwright.config.js');
+        const cfg = join(home, 'playwright.config.js');
         if (!existsSync(cfg)) {
-            const gsRel = gsPath.slice(pkgRoot.length + 1);
-            writeFileSync(cfg, playwrightConfig(`./${rel}`, `./${gsRel}`, area), 'utf-8');
+            writeFileSync(cfg, playwrightConfig(`./${posix(home, areaDir)}`, `./${posix(home, gsPath)}`, area, posix(home, RESULTS_DIR)), 'utf-8');
         }
     }
     else if (framework === 'jest') {
         const setupPath = join(harnessDir, 'jest.setup.js');
         writeFileSync(setupPath, jestSetupContent(), 'utf-8');
-        const cfg = join(pkgRoot, 'jest.config.js');
+        const home = configHome(areaDir, 'jest.config.js');
+        const cfg = join(home, 'jest.config.js');
         if (!existsSync(cfg)) {
-            const setupRel = setupPath.slice(pkgRoot.length + 1);
-            writeFileSync(cfg, jestConfig(rel, setupRel, area), 'utf-8');
+            writeFileSync(cfg, jestConfig(posix(home, areaDir), posix(home, setupPath), area), 'utf-8');
         }
     }
 }
+/**
+ * Where a runner config goes: the package root, where `npx playwright test`
+ * and `npx jest` look for it by themselves — so CI, a teammate or a custom
+ * testCommand finds it with no --config flag. Tests can sit any depth below
+ * (tests/e2e, not just tests/). Only when the project already has its own
+ * config there do we fall back to the test folder's parent, never touching
+ * the project's file.
+ */
+function configHome(areaDir, name) {
+    const root = packageRoot(areaDir);
+    const existing = join(root, name);
+    if (!existsSync(existing) || readFileSync(existing, 'utf-8').includes(GEN_MARKER))
+        return root;
+    return resolve(dirname(areaDir));
+}

package/dist/core/generate/suite-planner.js

@@ -40,9 +40,9 @@ function buildPlanPrompt(journey, map) {
         `  refunds) may need many. Do not pad, do not over-split, do not force`,
         `  a fixed number.`,
         `- Each file covers ONE concern and must be independently meaningful.`,
-        `- "## Test setup" is what every file needs to run, not a behaviour, and`,
-        `  "## Questions for product (not asserted)" is not tested: plan no file`,
-        `  for either.`,
+        `- "## Controls" and "## Coverage" are indexes, "## Test setup" is what`,
+        `  every file needs to run, and "## Questions for product (not`,
+        `  asserted)" is not tested: plan no file for any of them.`,
         ``,
         `Output ONLY a JSON array (no prose, no markdown fences) of objects:`,
         `  [{ "slug": "<short-kebab-name>", "title": "<describe title>",`,

package/dist/core/generate/verify.js

@@ -44,6 +44,35 @@ function countsFrom(output) {
         return null;
     return { passed: passed ?? 0, skipped: skipped ?? 0 };
 }
+/**
+ * Failures no test edit can fix. Sending one to the repair prompt burns AI
+ * calls rewriting correct tests against an error they cannot cause (one
+ * night: 877 failures, every one a missing browser).
+ */
+const INFRA_FAILURES = [
+    [
+        /Executable doesn't exist at|browserType\.launch:|Host system is missing dependencies|does not support (chromium|firefox|webkit) on/i,
+        'the test browser cannot start — install the one this Playwright version needs (`npx playwright install chromium`), or pin a Playwright version your OS supports',
+    ],
+    [
+        /net::ERR_CONNECTION_REFUSED|ECONNREFUSED/i,
+        'the app (or a service it needs) is not reachable — start it and check BASE_URL / the DB settings in the env file',
+    ],
+];
+export function infraFailure(output) {
+    return INFRA_FAILURES.find(([re]) => re.test(output))?.[1] ?? null;
+}
+/**
+ * Can the test browser start? Asked once before generation spends anything,
+ * so a missing browser stops the run instead of failing every verify.
+ */
+export function browserPreflight(root) {
+    const res = spawnSync(process.execPath, ['-e', "require('@playwright/test').chromium.launch().then((b) => b.close())"], { cwd: root, encoding: 'utf-8', timeout: 120_000 });
+    if (res.status === 0)
+        return null;
+    const output = `${res.stdout ?? ''}\n${res.stderr ?? ''}`;
+    return infraFailure(output) ?? (output.trim().split('\n').find((l) => l.trim()) || 'the test browser could not start');
+}
 /**
  * Run exactly the given generated files. Never throws: a verify step that
  * breaks generation would be worse than no verify step at all.
@@ -90,6 +119,9 @@ export function verifyFiles(config, area, files) {
     if (/command not found|Cannot find module '@playwright|is not recognized/i.test(output)) {
         return { ran: false, ok: false, output, reason: 'test runner is not installed' };
     }
+    const infra = infraFailure(output);
+    if (infra)
+        return { ran: false, infra: true, ok: false, output, reason: infra };
     if (res.status !== 0)
         return { ran: true, ok: false, output };
     // A suite where every test skipped ALSO exits 0. Treating that as verified

package/dist/core/paths.js

@@ -1,3 +1,4 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 /**
  * Single source of truth for TestForge's per-project state directory and the
@@ -17,3 +18,17 @@ export const SOURCE_PATH = join(STATE_DIR, 'source.json');
 export const COVERAGE_PATH = join(STATE_DIR, 'coverage.json');
 /** Per-journey generation plans, organised per area: <PLANS_DIR>/<area>/<id>.json */
 export const PLANS_DIR = join(STATE_DIR, 'test-plans');
+/** Where Playwright writes its per-run output (failure reports, traces). */
+export const RESULTS_DIR = join(STATE_DIR, 'playwright-results');
+/**
+ * Keep the state dir out of git without touching the project's own
+ * .gitignore: caches, plans and run output are local and regenerated, only
+ * the source-of-truth choice is worth sharing with the team.
+ */
+export function ensureStateDirIgnored() {
+    const file = join(STATE_DIR, '.gitignore');
+    if (existsSync(file))
+        return;
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(file, '# testforge local state: regenerated as needed, so not committed.\n*\n!.gitignore\n!source.json\n', 'utf-8');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activate-core/test-forge",
-  "version": "0.19.3",
+  "version": "1.0.1",
   "description": "AI-powered QA automation. Scans a project, drafts journey docs, and generates seeded Jest/Playwright tests. Works in any project, with any AI CLI.",
   "type": "module",
   "bin": {