@activate-core/test-forge 0.3.1 → 0.5.0

package/dist/cli/index.js

@@ -49,7 +49,10 @@ function printUsage() {
     console.log('  testforge generate           Generate tests from the journey docs');
     console.log('  testforge generate --basic   Use the basic generator only');
     console.log('  testforge generate --force   Regenerate everything');
+    console.log('  testforge generate --journey <name>  Generate just ONE journey');
     console.log('  testforge discover          Draft journey docs (asks: map or reference)');
+    console.log('  testforge discover --journey <name>  Draft just ONE journey doc');
+    console.log('  testforge discover --reference <file|url>  Base docs on a reference');
     console.log('  testforge map               Scan project, write journey + data map');
     console.log('  testforge init              Inspect project and write config');
     console.log('  testforge update            Re-check and update only what changed');
@@ -78,7 +81,7 @@ async function main() {
     else if (command === 'discover') {
         console.log('Drafting journey files with AI...');
         console.log('This writes drafts into docs/ from your chosen source.\n');
-        const output = await runDiscover('.', 'docs', sourceOptions());
+        const output = await runDiscover('.', 'docs', sourceOptions(), flagValue('--journey'));
         console.log(output);
         console.log('\nDraft journeys written to docs/. Please review and edit them,');
         console.log('then run `testforge generate`.');
@@ -91,7 +94,7 @@ async function main() {
         console.log(useAI
             ? 'Generating tests with AI for changed journeys...\n'
             : 'Generating tests with the basic generator...\n');
-        const results = runGenerate('docs', useAI, force);
+        const results = await runGenerate('docs', useAI, force, flagValue('--journey'));
         if (results.length === 0) {
             console.log('No journey files found in docs/. Add a .md file and try again.');
         }
@@ -102,8 +105,11 @@ async function main() {
                 }
                 else {
                     const tag = r.status === 'ai' ? '[AI]' : '[basic]';
-                    console.log(`  ${tag} ${r.journeyName}`);
-                    console.log(`         test: ${r.testPath}`);
+                    console.log(`  ${tag} ${r.journeyName} — ${r.testFiles.length} test file(s)`);
+                    console.log(`         dir: ${r.testDir}/`);
+                    for (const tf of r.testFiles) {
+                        console.log(`           - ${tf.slug}`);
+                    }
                     if (r.status === 'ai') {
                         if (r.seedStatus === 'ok') {
                             console.log(`         seed: ${r.seedPath}`);

package/dist/core/ai-generator.js

@@ -10,20 +10,49 @@
  * We call it in print mode (`claude -p`) and feed the prompt via
  * stdin so long prompts and special characters are handled safely.
  */
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
-import { loadConfig, splitCommand, withTextOnlyTools } from './config.js';
+import { loadConfig, splitCommand, withReadOnlyTools } from './config.js';
 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) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(program, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let out = '';
+        let err = '';
+        child.stdout.setEncoding('utf-8');
+        child.stdout.on('data', (d) => (out += d));
+        child.stderr.on('data', (d) => (err += d));
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(`${program} exited ${code}: ${err.slice(0, 500)}`));
+        });
+        child.stdin.end(input);
+    });
+}
 /** Build the prompt we send to the AI for one journey. */
-export function buildPrompt(journey, map, testPath) {
+export function buildPrompt(journey, map, testPath, focus) {
     const config = loadConfig();
-    const fw = config.framework?.[journey.type];
-    const isApi = journey.type === 'api' || fw === 'jest' || fw === 'supertest';
-    const framework = fw
-        ? `${fw} for a "${journey.type}" test`
-        : isApi
-            ? 'Jest (with supertest for HTTP) for an API/backend test'
-            : 'an appropriate test framework for this kind of journey';
+    // Opinionated: testforge only generates Jest (api/backend) or Playwright
+    // (web/UI) tests. We look the framework up by AREA, but clamp anything
+    // that is not jest/supertest/playwright (e.g. a project's cypress setup)
+    // to the sensible default for the journey's Type — so no other framework
+    // ever leaks into generated output.
+    const configured = (config.framework?.[journey.area] ?? '').toLowerCase();
+    const isApi = configured === 'jest' ||
+        configured === 'supertest' ||
+        (configured !== 'playwright' && journey.type === 'api');
+    const framework = isApi
+        ? 'Jest (with supertest for HTTP) for an API/backend test'
+        : 'Playwright for a web/UI test';
     const ext = config.testExtension ?? '.test.ts';
     const isJs = ext.endsWith('.js');
     const language = isJs
@@ -33,6 +62,19 @@ export function buildPrompt(journey, map, testPath) {
         `You are a senior QA engineer. Generate a complete ${framework}`,
         `for the user journey described below.`,
         ``,
+        ...(focus
+            ? [
+                `SCOPE — this is ONE file in a larger suite for this journey.`,
+                `Cover ONLY this concern in this file:`,
+                `  ${focus.title}`,
+                `  ${focus.covers}`,
+                `Do NOT test the journey's other concerns here — separate files`,
+                `cover those. Go DEEP on this one concern (happy path + its own`,
+                `edge/negative/security cases) rather than broad-but-shallow.`,
+                `Use this exact describe() title: "${focus.title}".`,
+                ``,
+            ]
+            : []),
         `Think like an experienced tester whose goal is to break the`,
         `application. Cover, where relevant: happy path, missing/empty`,
         `required fields, invalid formats and boundary values (very long,`,
@@ -52,6 +94,19 @@ export function buildPrompt(journey, map, testPath) {
         `guard is missing and produce a failing test that falsely brands the`,
         `product as vulnerable.`,
         ``,
+        `GROUND EVERYTHING IN THE REAL SOURCE. You are running inside the`,
+        `project's repository and have read-only tools (Read, Grep, Glob, LS).`,
+        `BEFORE writing tests, look up the actual code for this journey — use`,
+        `the route/endpoint named below to grep for the router, then read the`,
+        `route file, its controller/handler, the service it calls, and the`,
+        `models it touches. Confirm the REAL endpoint paths, HTTP methods,`,
+        `request/response shapes, status codes, auth requirements, and function`,
+        `signatures from the code. Base every assertion on what the code`,
+        `actually does. Only fall back to "// TODO:" or test.todo/it.skip when`,
+        `the behavior genuinely cannot be determined from the source — do not`,
+        `leave something as a TODO that a quick read of the code would answer.`,
+        `Do NOT write or edit any file; output only the test code to stdout.`,
+        ``,
         isApi
             ? [
                 `Because this is an API journey, write Jest tests that call the`,
@@ -117,12 +172,13 @@ export function buildPrompt(journey, map, testPath) {
  * journey. Reads the project map (testforge.md) for data-layer
  * context. Returns the test file content.
  */
-export function generateWithAI(journey, testPath) {
+export function generateWithAI(journey, testPath, focus) {
     const map = existsSync(MAP_PATH) ? readFileSync(MAP_PATH, 'utf-8') : '';
-    const prompt = buildPrompt(journey, map, testPath);
-    // Generation is pure text — run with NO tools so the model just
-    // prints code instead of trying to write files.
-    const { program, args } = withTextOnlyTools(splitCommand(loadConfig().aiCommand));
+    const prompt = buildPrompt(journey, map, testPath, focus);
+    // Allow read-only exploration so the model grounds the test in the
+    // real source (routes/controllers/models); Write stays denied, so it
+    // still can't create files — it reads, then prints the code.
+    const { program, args } = withReadOnlyTools(splitCommand(loadConfig().aiCommand));
     const output = execFileSync(program, args, {
         input: prompt,
         encoding: 'utf-8',
@@ -130,6 +186,18 @@ export function generateWithAI(journey, testPath) {
     });
     return cleanOutput(output);
 }
+/**
+ * Async twin of generateWithAI, so multiple focused files in one
+ * journey's suite can be generated concurrently (each spawns its own
+ * `claude` process). Same prompt, same read-only exploration.
+ */
+export async function generateWithAIAsync(journey, testPath, focus) {
+    const map = existsSync(MAP_PATH) ? readFileSync(MAP_PATH, 'utf-8') : '';
+    const prompt = buildPrompt(journey, map, testPath, focus);
+    const { program, args } = withReadOnlyTools(splitCommand(loadConfig().aiCommand));
+    const stdout = await runWithStdin(program, args, prompt);
+    return cleanOutput(stdout);
+}
 /** Does this line look like the start (or body) of real code? */
 function looksLikeCode(line) {
     const t = line.trim();

package/dist/core/config.js

@@ -115,6 +115,27 @@ export function withTextOnlyTools(cmd) {
         return cmd;
     return { program: cmd.program, args: [...cmd.args, '--allowedTools', ''] };
 }
+/**
+ * Args for a generation call that should EXPLORE the real source before
+ * writing — read-only tools (Read/Grep/Glob/LS) are allowed so the model
+ * can confirm actual endpoint paths, request/response shapes, and model
+ * schemas from the code, but Write/Edit/Bash stay OUT of the allowlist so
+ * it still can't create files or run commands. The model reads, then
+ * prints the test/seed code to stdout.
+ *
+ * This is the key to tests grounded in the real code instead of
+ * assumptions: without source access the model leaves "endpoint shape
+ * unconfirmed" TODOs; with it, those become real assertions.
+ */
+export function withReadOnlyTools(cmd) {
+    if (!isClaude(cmd.program))
+        return cmd;
+    return {
+        program: cmd.program,
+        // Space-separated allowlist; Write/Edit/Bash deliberately excluded.
+        args: [...cmd.args, '--allowedTools', 'Read Grep Glob LS'],
+    };
+}
 /**
  * Args for a phase where the model must read/write files (init, map,
  * discover). Mirrors withTextOnlyTools but grants edit permission.

package/dist/core/discover.js

@@ -16,15 +16,30 @@
  */
 import { execFileSync } from 'node:child_process';
 import { loadConfig, splitCommand, withEditTools } from './config.js';
+import { DEEP_DOC_GUIDANCE } from './doc-guidance.js';
 import { promptConfirm } from './prompt.js';
 import { resolveDocsSource, saveSourceChoice, } from './source-of-truth.js';
 import { analyzeReference, draftDocsFromReference, DIFF_PATH, } from './reference.js';
-/** Build the discovery prompt. */
-export function buildDiscoverPrompt(srcDir, docsDir) {
+/** Scope line: one journey, or all of them. */
+function scopeLines(journey) {
+    return journey
+        ? [
+            `SCOPE: document ONLY the single journey matching "${journey}"`,
+            `(match by name, or by "area/name"). Create just that ONE file and`,
+            `ignore every other journey.`,
+            ``,
+        ]
+        : [`Document EVERY journey in the map (one file each).`, ``];
+}
+/** Build the discovery prompt. Optionally scoped to one journey. */
+export function buildDiscoverPrompt(srcDir, docsDir, journey) {
     return [
         `You are a senior QA engineer creating per-journey documentation`,
         `for a project, so a QA tool can generate tests from it.`,
         ``,
+        ...scopeLines(journey),
+        DEEP_DOC_GUIDANCE,
+        ``,
         `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`,
@@ -89,8 +104,8 @@ export function buildDiscoverPrompt(srcDir, docsDir) {
  * Draft the docs from the project's own code (the default). Invokes the
  * AI CLI with permission to read source and write markdown files.
  */
-function runCodeDiscover(srcDir, docsDir) {
-    const prompt = buildDiscoverPrompt(srcDir, docsDir);
+function runCodeDiscover(srcDir, docsDir, journey) {
+    const prompt = buildDiscoverPrompt(srcDir, docsDir, journey);
     // 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
@@ -113,7 +128,7 @@ function runCodeDiscover(srcDir, docsDir) {
  * Async because the source-of-truth barrier may prompt the developer.
  * Returns the AI's text summary of what it created.
  */
-export async function runDiscover(srcDir, docsDir, opts = {}) {
+export async function runDiscover(srcDir, docsDir, opts = {}, journey) {
     const source = await resolveDocsSource(opts);
     if (source.mode === 'reference' && source.reference) {
         console.log(`\nComparing the reference against testforge.md: ${source.reference}`);
@@ -128,14 +143,14 @@ export async function runDiscover(srcDir, docsDir, opts = {}) {
             if (!ok) {
                 console.log('Basing docs on testforge.md instead.\n');
                 saveSourceChoice({ mode: 'map' });
-                return runCodeDiscover(srcDir, docsDir);
+                return runCodeDiscover(srcDir, docsDir, journey);
             }
         }
         console.log('\nDrafting docs from the reference...\n');
-        const out = draftDocsFromReference(srcDir, docsDir, source.reference);
+        const out = draftDocsFromReference(srcDir, docsDir, source.reference, journey);
         saveSourceChoice({ mode: 'reference', reference: source.reference });
         return out;
     }
     saveSourceChoice({ mode: 'map' });
-    return runCodeDiscover(srcDir, docsDir);
+    return runCodeDiscover(srcDir, docsDir, journey);
 }

package/dist/core/doc-guidance.js

@@ -0,0 +1,27 @@
+/**
+ * testforge — shared doc-generation guidance.
+ *
+ * The journey doc is the source of truth for the generated tests, so its
+ * depth is the ceiling on test quality. This wording is shared by both
+ * discover prompts (code-based and reference-based) so a doc is deep and
+ * well-sectioned regardless of where it is drafted from.
+ */
+export const DEEP_DOC_GUIDANCE = [
+    `Make each doc DEEP and exhaustive — the generated tests can only be as`,
+    `good as this doc, so do NOT stop at a thin outline. For the journey,`,
+    `document, where they apply:`,
+    `- every distinct sub-flow and lifecycle STATE it can be in, and the`,
+    `  transitions between them (not just the happy path);`,
+    `- each endpoint/screen involved, with real inputs, outputs, status`,
+    `  codes, and side effects;`,
+    `- edge cases, race conditions, idempotency, retries, webhooks and`,
+    `  signature checks, refunds/reversals, permissions/auth, and any`,
+    `  money/amount CALCULATIONS — with the actual rules and formulas, not`,
+    `  vague mentions;`,
+    `- concrete acceptance criteria per case (exactly what must hold).`,
+    `Aim for the depth of a spec a new engineer could implement from.`,
+    `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.`,
+].join('\n');

package/dist/core/index.js

@@ -4,4 +4,4 @@
  * Currently exposes the package version only.
  * Model, parser, and engines will be added in upcoming steps.
  */
-export const VERSION = '0.3.1';
+export const VERSION = '0.4.0';

package/dist/core/init.js

@@ -29,10 +29,17 @@ export function buildInitPrompt() {
         `  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").`,
+        `  For UI areas, use a plain tests folder (e.g. ".../tests" or`,
+        `  ".../tests/e2e") — do NOT point them at a Cypress folder such as`,
+        `  "cypress/integration", because testforge does not generate Cypress.`,
+        `- framework: an object mapping each area to its test framework.`,
+        `  testforge ONLY generates two kinds of tests, so each value MUST be`,
+        `  exactly "jest" or "playwright" — never "cypress", "mocha", "vitest",`,
+        `  or anything else, EVEN IF the project currently uses one of those.`,
+        `  Choose the closest fit: backend / API / serverless / lambda / worker`,
+        `  areas -> "jest"; UI / web / browser / admin-panel areas ->`,
+        `  "playwright". Example: { "api": "jest", "web": "playwright", "ops":`,
+        `  "playwright", "lambda": "jest" }.`,
         `- 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`,

package/dist/core/parser.js

@@ -65,8 +65,14 @@ function parseField(line) {
     const required = parts.includes('required');
     return { name, type, required };
 }
-/** Parse a full markdown string into a Journey object. */
-export function parseJourney(markdown) {
+/**
+ * Parse a full markdown string into a Journey object.
+ *
+ * `area` is the journey's docs subfolder (e.g. "api", "ops"), which drives
+ * output location and framework. When omitted (a journey read outside an
+ * area folder), it falls back to the parsed `Type:`.
+ */
+export function parseJourney(markdown, area) {
     const lines = markdown.split('\n').map((l) => l.trim());
     let name = '';
     let type = 'web';
@@ -112,6 +118,7 @@ export function parseJourney(markdown) {
     return {
         id: toId(name),
         name,
+        area: area ?? type,
         type,
         route,
         coverage,

package/dist/core/reference.js

@@ -23,6 +23,7 @@
  */
 import { execFileSync } from 'node:child_process';
 import { loadConfig, splitCommand, withReferenceTools } from './config.js';
+import { DEEP_DOC_GUIDANCE } from './doc-guidance.js';
 /** Where the comparison report is written. */
 export const DIFF_PATH = 'testforge.diff.md';
 const MAP_PATH = 'testforge.md';
@@ -87,7 +88,15 @@ export function buildAnalyzePrompt(reference, docsDir) {
  * treating it as the source of truth for behavior. Mirrors the code-based
  * discover format so the docs are interchangeable downstream.
  */
-export function buildReferenceDiscoverPrompt(srcDir, docsDir, reference) {
+export function buildReferenceDiscoverPrompt(srcDir, docsDir, reference, journey) {
+    const scope = journey
+        ? [
+            `SCOPE: document ONLY the single journey matching "${journey}"`,
+            `(match by name, or by "area/name"). Create just that ONE file and`,
+            `ignore every other journey the reference describes.`,
+            ``,
+        ]
+        : [`Document EVERY journey the reference describes (one file each).`, ``];
     return [
         `You are a senior QA engineer creating per-journey documentation so a`,
         `QA tool can generate tests from it. The developer has chosen an`,
@@ -96,9 +105,14 @@ export function buildReferenceDiscoverPrompt(srcDir, docsDir, reference) {
         `does something different, document the reference's expected behavior`,
         `(the code may be buggy — that is exactly what these tests must catch).`,
         ``,
+        ...scope,
+        DEEP_DOC_GUIDANCE,
+        ``,
         `Reference: ${reference}`,
-        `Read it with your available tools (read the file, fetch the URL/page).`,
-        `The comparison you need is already in "${DIFF_PATH}" — use it.`,
+        `Read it FULLY with your available tools (read the file, fetch the`,
+        `URL/page — follow sub-pages/links the reference points to). Do not`,
+        `summarise shallowly; pull out every flow, rule, state and edge case`,
+        `it describes. The comparison you need is already in "${DIFF_PATH}".`,
         ``,
         `Use the project map at "${MAP_PATH}" and the source under "${srcDir}"`,
         `ONLY for TECHNICAL detail the reference does not spell out: routes,`,
@@ -157,6 +171,6 @@ export function analyzeReference(reference, docsDir) {
  * Draft the journey docs from the reference. Returns the AI's summary of
  * the journeys it documented.
  */
-export function draftDocsFromReference(srcDir, docsDir, reference) {
-    return runAI(buildReferenceDiscoverPrompt(srcDir, docsDir, reference));
+export function draftDocsFromReference(srcDir, docsDir, reference, journey) {
+    return runAI(buildReferenceDiscoverPrompt(srcDir, docsDir, reference, journey));
 }

package/dist/core/run-generate.js

@@ -21,8 +21,9 @@ import { join, dirname } from 'node:path';
 import { parseJourney } from './parser.js';
 import { generateTestCases } from './generator.js';
 import { writePlaywrightFile } from './playwright-writer.js';
-import { generateWithAI } from './ai-generator.js';
+import { generateWithAI, generateWithAIAsync } from './ai-generator.js';
 import { generateSeed } from './seed-generator.js';
+import { planSuite } from './suite-planner.js';
 import { isSyntaxValid } from './validate.js';
 import { hashContent, loadCache, saveCache } from './cache.js';
 import { findMarkdownFiles } from './find-files.js';
@@ -30,6 +31,43 @@ import { loadConfig, testDirForType } from './config.js';
 const CACHE_PATH = '.testforge/cache.json';
 /** How many times to re-ask the AI when output won't parse. */
 const MAX_GEN_ATTEMPTS = 2;
+/** How many focused files to generate concurrently within a journey. */
+const GEN_CONCURRENCY = 4;
+/**
+ * Run async tasks with a bounded concurrency, preserving input order in
+ * 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) {
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    const n = Math.max(1, Math.min(limit, items.length));
+    await Promise.all(Array.from({ length: n }, () => worker()));
+    return results;
+}
+/** Async version of generateValidated (for concurrent per-file gen). */
+async function generateValidatedAsync(generate, ext) {
+    let content = '';
+    for (let attempt = 0; attempt < MAX_GEN_ATTEMPTS; attempt++) {
+        try {
+            content = await generate();
+        }
+        catch {
+            continue;
+        }
+        if (isSyntaxValid(content, ext))
+            return content;
+    }
+    return null;
+}
 /**
  * Run an AI generator, cleaning + syntax-gating its output, retrying a
  * couple of times on malformed results. Returns the valid content, or
@@ -56,10 +94,9 @@ function generateValidated(generate, ext) {
  * syntax gate + retry) and falls back to the deterministic basic
  * generator if AI output can't be made valid.
  */
-function buildTest(markdown, useAI, ext, testPath) {
-    const journey = parseJourney(markdown);
+function buildTest(journey, useAI, ext, testPath, focus) {
     if (useAI) {
-        const ai = generateValidated(() => generateWithAI(journey, testPath), ext);
+        const ai = generateValidated(() => generateWithAI(journey, testPath, focus), ext);
         if (ai !== null) {
             return { content: ai, status: 'ai' };
         }
@@ -102,7 +139,17 @@ function collisionWarning(testDir, id, ext) {
         return null;
     return `an existing test with different naming already covers this journey: ${clashes.join(', ')} — new file may duplicate it`;
 }
-export function runGenerate(docsDir, useAI = true, force = false) {
+/** Does this doc file / journey match a --journey selector? */
+function matchesJourney(file, journeyId, sel) {
+    const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    const n = norm(sel);
+    const stem = file.replace(/\.md$/, '');
+    return (journeyId === n ||
+        norm(stem) === n ||
+        norm(stem).endsWith(`-${n}`) ||
+        norm(stem).split('/').pop() === n);
+}
+export async function runGenerate(docsDir, useAI = true, force = false, only) {
     const files = findMarkdownFiles(docsDir);
     if (files.length === 0) {
         return [];
@@ -116,16 +163,25 @@ export function runGenerate(docsDir, useAI = true, force = false) {
     for (const file of files) {
         const markdown = readFileSync(join(docsDir, file), 'utf-8');
         const hash = hashContent(markdown);
-        const journey = parseJourney(markdown);
-        // Where this journey's test and seed go.
-        const testDir = testDirForType(config, journey.type);
-        const testPath = join(testDir, `${journey.id}${ext}`);
+        // The area is the doc's top-level folder (api/web/ops/lambda/...). It
+        // decides where the test goes and which framework is used — NOT the
+        // "Type:" line, which only says UI-vs-endpoint. This keeps ops/lambda
+        // journeys in their own package instead of leaking into web/api.
+        const area = file.split(/[\\/]/)[0] || undefined;
+        const journey = parseJourney(markdown, area);
+        // --journey <x>: generate just the one matching journey.
+        if (only && !matchesJourney(file, journey.id, only))
+            continue;
+        // Deep mode: each journey becomes a FOLDER of focused test files.
+        const areaDir = testDirForType(config, journey.area);
+        const testDir = join(areaDir, journey.id);
         const seedPath = join(seedDir, `${journey.id}${seedExt}`);
         // Skip if unchanged.
         if (!force && cache[file] === hash) {
             results.push({
                 journeyName: journey.name,
-                testPath,
+                testDir,
+                testFiles: [],
                 seedPath,
                 status: 'skipped',
                 seedStatus: 'none',
@@ -133,13 +189,52 @@ export function runGenerate(docsDir, useAI = true, force = false) {
             continue;
         }
         const warnings = [];
-        const collision = collisionWarning(testDir, journey.id, ext);
+        const collision = collisionWarning(areaDir, journey.id, ext);
         if (collision)
             warnings.push(collision);
-        // 1. Test file (syntax-gated before writing).
-        const { content, status } = buildTest(markdown, useAI, ext, testPath);
-        mkdirSync(dirname(testPath), { recursive: true });
-        writeFileSync(testPath, content, 'utf-8');
+        // 1. Plan the suite (deep mode), then generate one focused file per
+        //    concern. In basic mode there is no AI planner — one file only.
+        const planned = useAI
+            ? planSuite(journey)
+            : [{ slug: journey.id, title: journey.name, covers: '' }];
+        // Generate all focused files CONCURRENTLY (bounded pool). Each AI
+        // call is independent, so a 15-file journey finishes in ~4 waves
+        // instead of 15 serial calls.
+        const generated = await pool(planned, GEN_CONCURRENCY, async (pf) => {
+            const filePath = join(testDir, `${pf.slug}${ext}`);
+            let content;
+            let status;
+            if (useAI) {
+                const ai = await generateValidatedAsync(() => generateWithAIAsync(journey, filePath, {
+                    title: pf.title,
+                    covers: pf.covers,
+                }), ext);
+                if (ai !== null) {
+                    content = ai;
+                    status = 'ai';
+                }
+                else {
+                    const built = buildTest(journey, false, ext, filePath);
+                    content = built.content;
+                    status = 'basic';
+                }
+            }
+            else {
+                const built = buildTest(journey, false, ext, filePath);
+                content = built.content;
+                status = 'basic';
+            }
+            return { slug: pf.slug, path: filePath, content, status };
+        });
+        const testFiles = [];
+        for (const g of generated) {
+            mkdirSync(dirname(g.path), { recursive: true });
+            writeFileSync(g.path, g.content, 'utf-8');
+            testFiles.push({ slug: g.slug, path: g.path, status: g.status });
+        }
+        const anyAI = testFiles.some((t) => t.status === 'ai');
+        const anyBasic = testFiles.some((t) => t.status === 'basic');
+        const status = anyAI || !anyBasic ? 'ai' : 'basic';
         // 2. Seed file (only when using AI — basic mode has no seed concept).
         let seedStatus = 'none';
         if (useAI) {
@@ -159,7 +254,8 @@ export function runGenerate(docsDir, useAI = true, force = false) {
         cache[file] = hash;
         results.push({
             journeyName: journey.name,
-            testPath,
+            testDir,
+            testFiles,
             seedPath,
             status,
             seedStatus,

package/dist/core/seed-generator.js

@@ -16,7 +16,7 @@
  */
 import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
-import { loadConfig, splitCommand, withTextOnlyTools } from './config.js';
+import { loadConfig, splitCommand, withReadOnlyTools } from './config.js';
 import { cleanOutput } from './ai-generator.js';
 const MAP_PATH = 'testforge.md';
 /** Build the seed-generation prompt for one journey. */
@@ -31,11 +31,15 @@ export function buildSeedPrompt(journeyDoc, seedPath) {
         `You are a senior SDET writing a TEST DATA SEED for one feature,`,
         `so its tests have a known, valid starting state in the database.`,
         ``,
-        `Use the project map below to understand the data layer — the`,
-        `database type, the models/collections, their key fields, and the`,
-        `allowed enum values. Build records that are VALID against that`,
-        `schema (right collection/table, right fields, right enum values,`,
-        `correct relationships between records).`,
+        `Use the project map below to understand the data layer. You are`,
+        `running inside the repository with read-only tools (Read, Grep, Glob,`,
+        `LS): READ THE ACTUAL MODEL/SCHEMA FILES for the collections this`,
+        `feature uses (grep for the model names) and build records that are`,
+        `VALID against the real schema — right collection/table, right field`,
+        `names and types, real required fields, real enum values, and correct`,
+        `relationships between records. Do not guess a field that a quick read`,
+        `of the model would confirm. Do NOT write or edit any file; output only`,
+        `the seed code to stdout.`,
         ``,
         `Requirements for the seed you write:`,
         `- Connect using the env var named in the map (e.g.`,
@@ -78,9 +82,9 @@ export function buildSeedPrompt(journeyDoc, seedPath) {
 /** Generate a seed file's content for one journey doc, via the AI. */
 export function generateSeed(journeyDoc, seedPath) {
     const prompt = buildSeedPrompt(journeyDoc, seedPath);
-    // Pure text — no tools, so the model prints the seed instead of
-    // attempting to write it (which leaks approval prose into the output).
-    const { program, args } = withTextOnlyTools(splitCommand(loadConfig().aiCommand));
+    // Allow read-only exploration so the seed matches the REAL schema
+    // (models/collections/enums) read from the code; Write stays denied.
+    const { program, args } = withReadOnlyTools(splitCommand(loadConfig().aiCommand));
     const output = execFileSync(program, args, {
         input: prompt,
         encoding: 'utf-8',

package/dist/core/suite-planner.js

@@ -0,0 +1,130 @@
+/**
+ * testforge — suite planner (deep mode).
+ *
+ * Instead of one monolithic test file per journey, we first ask the AI
+ * to DECOMPOSE a journey into a set of focused test files — one concern
+ * each — exactly like a human-authored suite (e.g. a payment flow splits
+ * into success / failures / discount / 3ds / zero-amount / ... files).
+ *
+ * The split is driven by the journey doc's own sections and the REAL
+ * endpoints/behaviours the AI reads from the source (read-only tools).
+ * Depth scales with the doc: a thin journey yields 1–2 files, a rich
+ * one yields many. We never force a fixed count.
+ *
+ * The planner returns structured data (a list of files), NOT code — the
+ * per-file generator turns each entry into an actual focused test.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { loadConfig, splitCommand, withReadOnlyTools } from './config.js';
+const MAP_PATH = 'testforge.md';
+/** Build the planning prompt for one journey. */
+function buildPlanPrompt(journey, map) {
+    return [
+        `You are a senior test architect. Plan how to split ONE user journey`,
+        `into a set of FOCUSED test files — one concern per file — the way a`,
+        `careful human would (e.g. a payment flow becomes separate files for`,
+        `success, failures, discount, 3D-Secure, zero-amount, price summary,`,
+        `and so on). Do NOT plan a single monolithic file.`,
+        ``,
+        `You are inside the project's repository with read-only tools (Read,`,
+        `Grep, Glob, LS). READ the real source for this journey — routes,`,
+        `controllers, services, models — and combine it with the journey doc`,
+        `to decide the split. Every file must map to a real behaviour that`,
+        `exists in the code or is explicitly described in the doc.`,
+        ``,
+        `Rules:`,
+        `- Let the doc's sections and the real endpoints drive the split.`,
+        `- Depth SCALES with the journey: a small/simple journey may need just`,
+        `  1–2 files; a rich one (many endpoints, edge cases, webhooks, cron,`,
+        `  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.`,
+        ``,
+        `Output ONLY a JSON array (no prose, no markdown fences) of objects:`,
+        `  [{ "slug": "<short-kebab-name>", "title": "<describe title>",`,
+        `     "covers": "<one or two sentences: exactly what this file tests>" }]`,
+        `slug: lowercase, words joined by "-", no path and no file extension.`,
+        `The very first character of your response must be "[".`,
+        ``,
+        `--- PROJECT MAP (data layer) ---`,
+        map,
+        ``,
+        `--- JOURNEY ---`,
+        journey.rawMarkdown,
+    ].join('\n');
+}
+/**
+ * Pull a JSON array out of the AI's reply, tolerating stray prose or
+ * code fences around it. Returns [] if nothing parseable is found.
+ */
+function extractJsonArray(text) {
+    const start = text.indexOf('[');
+    const end = text.lastIndexOf(']');
+    if (start === -1 || end === -1 || end < start)
+        return [];
+    try {
+        const parsed = JSON.parse(text.slice(start, end + 1));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Normalise a raw slug into a safe kebab-case file stem. */
+function safeSlug(raw) {
+    return String(raw ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/\.(spec|test)\.[jt]sx?$/, '') // drop any extension the AI added
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Plan the suite for one journey: returns the list of focused files to
+ * generate. Falls back to a single whole-journey file when the planner
+ * produces nothing usable, so generation never silently yields zero
+ * files.
+ */
+export function planSuite(journey) {
+    const map = existsSync(MAP_PATH) ? readFileSync(MAP_PATH, 'utf-8') : '';
+    const prompt = buildPlanPrompt(journey, map);
+    const { program, args } = withReadOnlyTools(splitCommand(loadConfig().aiCommand));
+    let raw = '';
+    try {
+        raw = execFileSync(program, args, {
+            input: prompt,
+            encoding: 'utf-8',
+            maxBuffer: 10 * 1024 * 1024,
+        });
+    }
+    catch {
+        raw = '';
+    }
+    const seen = new Set();
+    const files = [];
+    for (const entry of extractJsonArray(raw)) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const e = entry;
+        const slug = safeSlug(e.slug ?? e.title);
+        if (!slug || seen.has(slug))
+            continue;
+        seen.add(slug);
+        files.push({
+            slug,
+            title: String(e.title ?? journey.name).trim() || journey.name,
+            covers: String(e.covers ?? '').trim(),
+        });
+    }
+    if (files.length === 0) {
+        // Planner failed or returned junk — degrade to a single file for the
+        // whole journey rather than generating nothing.
+        files.push({
+            slug: journey.id,
+            title: journey.name,
+            covers: 'The entire journey as described in the doc.',
+        });
+    }
+    return files;
+}

package/dist/core/update.js

@@ -41,7 +41,7 @@ export async function runUpdate(srcDir) {
     await runDiscover(srcDir, 'docs', { noPrompt: true });
     console.log('  done — docs/\n');
     console.log('Regenerating tests for changed journeys...');
-    const results = runGenerate('docs', true, false);
+    const results = await runGenerate('docs', true, false);
     const made = results.filter((r) => r.status !== 'skipped').length;
     const skipped = results.filter((r) => r.status === 'skipped').length;
     console.log(`  done — ${made} updated, ${skipped} unchanged.\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activate-core/test-forge",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "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": {