@activate-core/test-forge 0.1.1 → 0.3.0

package/dist/core/env-template.js

@@ -11,15 +11,19 @@
  * 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 { readFileSync, writeFileSync, existsSync, readdirSync, } from 'node:fs';
+import { join } from 'node:path';
 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
+    // process.env.XXX  and  process.env["XXX"] / process.env['XXX']
     for (const m of text.matchAll(/process\.env\.([A-Z0-9_]+)/gi)) {
         vars.add(m[1]);
     }
+    for (const m of text.matchAll(/process\.env\[\s*['"]([A-Z0-9_]+)['"]\s*\]/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)) {
@@ -30,6 +34,69 @@ function extractEnvVars(text) {
     }
     return vars;
 }
+/** Directories we never want to scan for app env vars. */
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'coverage',
+    'docs',
+    'generated-tests',
+    '.testforge',
+]);
+const SOURCE_EXT = /\.(c|m)?[jt]sx?$/i;
+/**
+ * Scan the project's application SOURCE (not just the docs) for
+ * process.env references. Docs describe features; they routinely miss
+ * boot-critical vars (Sentry DSN, Twilio keys, feature flags) that the
+ * app reads directly at startup. Without those in the example file, the
+ * server won't even boot for a fresh clone. We walk the source tree,
+ * skipping vendored/build/test output, with a file cap so a huge repo
+ * can't stall the run.
+ */
+function scanSourceEnvVars(srcDir, maxFiles = 4000) {
+    const vars = new Set();
+    let seen = 0;
+    const walk = (dir) => {
+        if (seen >= maxFiles)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (seen >= maxFiles)
+                return;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                    continue;
+                walk(full);
+            }
+            else if (SOURCE_EXT.test(entry.name)) {
+                // Skip test files — we want app source, not existing tests.
+                if (/\.(test|spec)\./i.test(entry.name))
+                    continue;
+                seen++;
+                try {
+                    for (const v of extractEnvVars(readFileSync(full, 'utf-8'))) {
+                        vars.add(v);
+                    }
+                }
+                catch {
+                    // unreadable file — ignore
+                }
+            }
+        }
+    };
+    if (existsSync(srcDir))
+        walk(srcDir);
+    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).
@@ -41,7 +108,7 @@ function areaAndJourney(file) {
     // Fallback: flat file with no area folder.
     return { area: 'general', journey: noExt };
 }
-export function runEnvTemplate(docsDir, outPath) {
+export function runEnvTemplate(docsDir, outPath, srcDir = '.') {
     if (!existsSync(docsDir)) {
         console.log(`No docs found at "${docsDir}". Run \`testforge setup\` first.`);
         return;
@@ -76,8 +143,18 @@ export function runEnvTemplate(docsDir, outPath) {
             }
         }
     }
-    if (byArea.size === 0) {
-        console.log('No environment variables found in the docs.');
+    // Vars the app reads directly from source but that no doc/map mentioned.
+    // These are the ones that silently break `boot` when missing, so they get
+    // their own clearly-flagged section.
+    const knownFromDocs = new Set();
+    for (const areaMap of byArea.values()) {
+        for (const v of areaMap.keys())
+            knownFromDocs.add(v);
+    }
+    const sourceVars = scanSourceEnvVars(srcDir);
+    const bootVars = [...sourceVars].filter((v) => !knownFromDocs.has(v)).sort();
+    if (byArea.size === 0 && bootVars.length === 0) {
+        console.log('No environment variables found in the docs or source.');
         return;
     }
     // Build the file.
@@ -90,6 +167,15 @@ export function runEnvTemplate(docsDir, outPath) {
         '# Keep .env.testing OUT of version control.',
         '',
     ];
+    if (bootVars.length > 0) {
+        lines.push(`# ${'='.repeat(40)}`);
+        lines.push('# APP (read directly from source — REQUIRED to boot)');
+        lines.push(`# ${'='.repeat(40)}`);
+        for (const v of bootVars) {
+            lines.push(`${v}=            # used by: app source`);
+        }
+        lines.push('');
+    }
     for (const area of [...byArea.keys()].sort()) {
         lines.push(`# ${'='.repeat(40)}`);
         lines.push(`# ${area.toUpperCase()}`);

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.1.0';
+export const VERSION = '0.3.0';

package/dist/core/init.js

@@ -11,7 +11,7 @@
  * infers it from what the project actually looks like.
  */
 import { execFileSync } from 'node:child_process';
-import { loadConfig, splitCommand } from './config.js';
+import { loadConfig, splitCommand, withEditTools } from './config.js';
 /** Build the prompt that asks the AI to write testforge.config.json. */
 export function buildInitPrompt() {
     return [
@@ -57,8 +57,8 @@ export function buildInitPrompt() {
 /** 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'], {
+    const { program, args } = withEditTools(splitCommand(loadConfig().aiCommand));
+    const output = execFileSync(program, args, {
         input: prompt,
         encoding: 'utf-8',
         maxBuffer: 10 * 1024 * 1024,

package/dist/core/map.js

@@ -18,7 +18,7 @@
  * only env var names.
  */
 import { execFileSync } from 'node:child_process';
-import { loadConfig, splitCommand } from './config.js';
+import { loadConfig, splitCommand, withEditTools } from './config.js';
 /** Build the prompt that asks the AI to produce the project map. */
 export function buildMapPrompt(srcDir) {
     return [
@@ -80,8 +80,8 @@ export function buildMapPrompt(srcDir) {
 /** 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'], {
+    const { program, args } = withEditTools(splitCommand(loadConfig().aiCommand));
+    const output = execFileSync(program, args, {
         input: prompt,
         encoding: 'utf-8',
         maxBuffer: 10 * 1024 * 1024,

package/dist/core/prompt.js

@@ -0,0 +1,70 @@
+/**
+ * testforge — small interactive prompt helpers.
+ *
+ * The rest of the CLI is non-interactive: it feeds prompts to the AI on
+ * a child process's stdin and never reads from the terminal. The
+ * source-of-truth barrier (see source-of-truth.ts) is the one place we
+ * genuinely need to ask the human a question, so these helpers read from
+ * the parent process's own stdin (the TTY) using node:readline.
+ *
+ * They are careful about two things:
+ *   - Non-interactive runs (CI, piped stdin): callers should check
+ *     isInteractive() first and fall back to a safe default instead of
+ *     blocking forever waiting for input that will never come.
+ *   - The child-process AI calls use a separate pipe for their prompt
+ *     (execFileSync `input`), so reading the TTY here does not clash
+ *     with them — they never touch process.stdin.
+ */
+import { createInterface } from 'node:readline/promises';
+/**
+ * Is the process attached to an interactive terminal on BOTH stdin and
+ * stdout? If not (piped input, CI, cron), we must not block on a prompt.
+ */
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** Ask a free-text question and return the trimmed answer. */
+export async function promptLine(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(question);
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Ask a yes/no question. Returns true only for an explicit yes.
+ * `defaultYes` controls what an empty answer (just Enter) means.
+ */
+export async function promptConfirm(question, defaultYes = false) {
+    const hint = defaultYes ? '[Y/n]' : '[y/N]';
+    const answer = (await promptLine(`${question} ${hint} `)).toLowerCase();
+    if (answer === '')
+        return defaultYes;
+    return answer === 'y' || answer === 'yes';
+}
+/**
+ * Present a numbered list of choices and return the 1-based index the
+ * user picked. Re-asks until a valid number is entered. `defaultIndex`
+ * (1-based) is used when the user just presses Enter.
+ */
+export async function promptChoice(title, options, defaultIndex = 1) {
+    console.log(title);
+    options.forEach((opt, i) => {
+        const marker = i + 1 === defaultIndex ? ' (default)' : '';
+        console.log(`  [${i + 1}] ${opt}${marker}`);
+    });
+    // Loop until we get a valid selection.
+    for (;;) {
+        const raw = await promptLine(`Choose [1-${options.length}]: `);
+        if (raw === '')
+            return defaultIndex;
+        const n = Number(raw);
+        if (Number.isInteger(n) && n >= 1 && n <= options.length) {
+            return n;
+        }
+        console.log(`Please enter a number between 1 and ${options.length}.`);
+    }
+}

package/dist/core/reference.js

@@ -0,0 +1,162 @@
+/**
+ * testforge — external reference support for doc generation.
+ *
+ * The journey docs are the source of truth for the tests: `generate`
+ * reads the docs and nothing else. So WHERE the docs come from decides
+ * everything. By default they are derived from the project's own code
+ * (via testforge.md), which bakes in any bugs the code has.
+ *
+ * This module lets the docs be drafted from an AUTHORITATIVE reference
+ * instead — a spec/requirements doc in the repo, a PDF, a website, or a
+ * Notion page that captures the human/client EXPECTED behavior:
+ *
+ *   - analyzeReference()   compares the reference against the current
+ *                          map (testforge.md) and any existing docs, and
+ *                          writes a comparison to testforge.diff.md.
+ *   - draftDocsFromReference() drafts the journey docs with the reference
+ *                          as the source of truth for behavior, using the
+ *                          map/code only for technical detail.
+ *
+ * Both drive the configured AI CLI with file-read/write (and, for
+ * URLs/Notion, web) access. As with discover/map this is tool-specific
+ * and tuned for the Claude CLI.
+ */
+import { execFileSync } from 'node:child_process';
+import { loadConfig, splitCommand, withEditTools } from './config.js';
+/** Where the comparison report is written. */
+export const DIFF_PATH = 'testforge.diff.md';
+const MAP_PATH = 'testforge.md';
+/** Run the configured AI command with read/write/web access. */
+function runAI(prompt) {
+    const { program, args } = withEditTools(splitCommand(loadConfig().aiCommand));
+    const output = execFileSync(program, args, {
+        input: prompt,
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return output.trim();
+}
+/** Build the prompt for the compare-only (analyze) step. */
+export function buildAnalyzePrompt(reference, docsDir) {
+    return [
+        `You are a senior QA engineer. The developer has given you an`,
+        `AUTHORITATIVE reference describing how this product is EXPECTED to`,
+        `behave. It comes from a human/client, NOT from the code, so where it`,
+        `disagrees with what the code implies, the reference is right.`,
+        ``,
+        `In THIS step you only COMPARE — you do not write any journey docs.`,
+        ``,
+        `Reference provided by the developer:`,
+        `  ${reference}`,
+        ``,
+        `This may be a path to a file in this project, a path to a document`,
+        `(e.g. a PDF), a URL to a website, or a link to a Notion page. Read`,
+        `it with your available tools. If you cannot access it at all, print`,
+        `a single line starting with "ERROR:" explaining why, and stop.`,
+        ``,
+        `Then read the project map at "${MAP_PATH}" (the AI's code-derived view`,
+        `of the journeys and data layer) and any existing docs under`,
+        `"${docsDir}/".`,
+        ``,
+        `Compare what the reference specifies against what the map/docs imply,`,
+        `focusing on things that matter for testing:`,
+        `  - journeys/flows the reference describes that the map is missing`,
+        `  - expected results / acceptance criteria that DIFFER`,
+        `  - fields, routes, validation, or error cases the reference requires`,
+        `    that the code-derived view omits or gets wrong`,
+        `  - anything the code-derived view asserts that the reference contradicts`,
+        ``,
+        `Write a comparison report to "${DIFF_PATH}" at the project root with`,
+        `these sections:`,
+        `  # Source-of-truth comparison`,
+        `  ## Reference        (what you read, and where from)`,
+        `  ## Summary          (a few bullet lines)`,
+        `  ## Differences      (per journey: the code implies X vs the`,
+        `                       reference says Y, and which should win)`,
+        `  ## Missing          (journeys/cases only in the reference)`,
+        `  ## Code-only        (in the code-derived view but not the reference —`,
+        `                       likely assumptions to double-check)`,
+        ``,
+        `Do NOT write any files under "${docsDir}/" in this step — only write`,
+        `"${DIFF_PATH}". When done, print a SHORT plain-text summary (about`,
+        `5-10 lines) of the key differences.`,
+    ].join('\n');
+}
+/**
+ * Build the prompt that drafts the journey docs FROM the reference,
+ * 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) {
+    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`,
+        `AUTHORITATIVE reference as the SOURCE OF TRUTH for how the product is`,
+        `EXPECTED to behave. The reference wins over the code: where the code`,
+        `does something different, document the reference's expected behavior`,
+        `(the code may be buggy — that is exactly what these tests must catch).`,
+        ``,
+        `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.`,
+        ``,
+        `Use the project map at "${MAP_PATH}" and the source under "${srcDir}"`,
+        `ONLY for TECHNICAL detail the reference does not spell out: routes,`,
+        `field names, models/collections, enums, and env var names. NEVER take`,
+        `expected behavior, acceptance criteria, or negative cases from the`,
+        `code — those come from the reference.`,
+        ``,
+        `For EACH journey the reference describes, create one markdown file at`,
+        `"${docsDir}/<area>/<journey>.md" (area = folder such as api/web/ops,`,
+        `short kebab-case journey name; do NOT put the area in the file name).`,
+        `Also create a doc for any journey that exists in the map but NOT in`,
+        `the reference, drafted from the map, and add a line`,
+        `"# TODO: not covered by the reference — confirm expected behavior"`,
+        `at its top so it is clearly flagged.`,
+        ``,
+        `Each file starts 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, ...)`,
+        ``,
+        `Then whichever of these sections apply: Fields, Actions, Expected,`,
+        `Negative Cases, Race Conditions, Webhooks, Security Notes, Data. The`,
+        `Expected / Negative Cases / acceptance criteria MUST reflect the`,
+        `reference. For the Data section use the map's data layer.`,
+        ``,
+        `Rules:`,
+        `- Base behavior on the reference and technical detail on real code;`,
+        `  do not invent either with false confidence.`,
+        `- Where the reference is silent on a needed detail, add a "# TODO:"`,
+        `  line describing what the developer must verify.`,
+        `- Never include secrets — refer to env var names only.`,
+        `- Create the area subfolders as needed.`,
+        `- After creating the files, print the list of journeys you documented`,
+        `  and remind the developer to review them.`,
+    ].join('\n');
+}
+/**
+ * Compare-only step. Reads the reference and the current map/docs, writes
+ * testforge.diff.md, and returns the AI's short summary. Throws if the AI
+ * reports it could not read the reference.
+ */
+export function analyzeReference(reference, docsDir) {
+    const summary = runAI(buildAnalyzePrompt(reference, docsDir));
+    if (/^ERROR:/m.test(summary)) {
+        throw new Error(`Could not read the reference "${reference}":\n${summary}`);
+    }
+    return summary;
+}
+/**
+ * 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));
+}

package/dist/core/run-generate.js

@@ -7,35 +7,101 @@
  *     falling back to the basic generator if AI fails
  *   - generates a SEED file for the journey's test data via AI
  *
+ * Everything generated by AI passes a syntax gate BEFORE it is written
+ * (see validate.ts). If a generation is malformed we regenerate a
+ * couple of times; if it still won't parse we skip writing it and
+ * report that clearly rather than dropping junk on disk.
+ *
  * Output locations come from config (testOutput per type, seedOutput),
  * so tests/seeds land where the project expects them. Defaults to
  * generated-tests/ when not configured.
  */
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, } from 'node:fs';
 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 { generateSeed } from './seed-generator.js';
+import { isSyntaxValid } from './validate.js';
 import { hashContent, loadCache, saveCache } from './cache.js';
 import { findMarkdownFiles } from './find-files.js';
 import { loadConfig, testDirForType } from './config.js';
 const CACHE_PATH = '.testforge/cache.json';
-/** Produce the test file content for one journey. */
-function buildTest(markdown, useAI) {
-    const journey = parseJourney(markdown);
-    if (useAI) {
+/** How many times to re-ask the AI when output won't parse. */
+const MAX_GEN_ATTEMPTS = 2;
+/**
+ * Run an AI generator, cleaning + syntax-gating its output, retrying a
+ * couple of times on malformed results. Returns the valid content, or
+ * null if every attempt failed to produce parseable code.
+ */
+function generateValidated(generate, ext) {
+    let content = '';
+    for (let attempt = 0; attempt < MAX_GEN_ATTEMPTS; attempt++) {
         try {
-            return { content: generateWithAI(journey), status: 'ai' };
+            content = generate();
         }
         catch {
-            // fall through to basic
+            // generation (or output cleaning) threw — retry
+            continue;
+        }
+        if (isSyntaxValid(content, ext)) {
+            return content;
+        }
+    }
+    return null;
+}
+/**
+ * Produce the test file content for one journey. Uses the AI (with a
+ * 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);
+    if (useAI) {
+        const ai = generateValidated(() => generateWithAI(journey, testPath), ext);
+        if (ai !== null) {
+            return { content: ai, status: 'ai' };
         }
+        // fall through to the basic generator
     }
     const cases = generateTestCases(journey);
     return { content: writePlaywrightFile(journey, cases), status: 'basic' };
 }
+/**
+ * Turn a journey id into the alternate naming conventions we might
+ * collide with (kebab <-> camel). Used to spot a pre-existing test for
+ * the same journey written under a different filename style.
+ */
+function alternateIds(id) {
+    const kebab = id
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/_/g, '-')
+        .toLowerCase();
+    const camel = id.replace(/[-_]([a-zA-Z0-9])/g, (_, c) => c.toUpperCase());
+    return [...new Set([kebab, camel])].filter((x) => x !== id);
+}
+/**
+ * Warn if a test for this same journey already exists under a different
+ * naming convention (e.g. urlShortener.test.js vs url-shortener.test.js),
+ * which would silently create a duplicate.
+ */
+function collisionWarning(testDir, id, ext) {
+    if (!existsSync(testDir))
+        return null;
+    const alts = new Set(alternateIds(id).map((a) => `${a}${ext}`));
+    let existing;
+    try {
+        existing = readdirSync(testDir);
+    }
+    catch {
+        return null;
+    }
+    const clashes = existing.filter((f) => alts.has(f));
+    if (clashes.length === 0)
+        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) {
     const files = findMarkdownFiles(docsDir);
     if (files.length === 0) {
@@ -44,6 +110,7 @@ export function runGenerate(docsDir, useAI = true, force = false) {
     const config = loadConfig();
     const ext = config.testExtension ?? '.test.ts';
     const seedDir = config.seedOutput ?? 'generated-tests/seed';
+    const seedExt = ext.endsWith('.js') ? '.seed.js' : '.seed.ts';
     const cache = loadCache(CACHE_PATH);
     const results = [];
     for (const file of files) {
@@ -53,9 +120,6 @@ export function runGenerate(docsDir, useAI = true, force = false) {
         // Where this journey's test and seed go.
         const testDir = testDirForType(config, journey.type);
         const testPath = join(testDir, `${journey.id}${ext}`);
-        const seedExt = (config.testExtension ?? '.test.ts').endsWith('.js')
-            ? '.seed.js'
-            : '.seed.ts';
         const seedPath = join(seedDir, `${journey.id}${seedExt}`);
         // Skip if unchanged.
         if (!force && cache[file] === hash) {
@@ -64,26 +128,43 @@ export function runGenerate(docsDir, useAI = true, force = false) {
                 testPath,
                 seedPath,
                 status: 'skipped',
+                seedStatus: 'none',
             });
             continue;
         }
-        // 1. Test file.
-        const { content, status } = buildTest(markdown, useAI);
+        const warnings = [];
+        const collision = collisionWarning(testDir, 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');
         // 2. Seed file (only when using AI — basic mode has no seed concept).
+        let seedStatus = 'none';
         if (useAI) {
-            try {
-                const seed = generateSeed(markdown);
+            const seed = generateValidated(() => generateSeed(markdown, seedPath), seedExt);
+            if (seed !== null) {
                 mkdirSync(dirname(seedPath), { recursive: true });
                 writeFileSync(seedPath, seed, 'utf-8');
+                seedStatus = 'ok';
             }
-            catch {
-                // seed generation failed — leave a note but don't fail the run
+            else {
+                // Do NOT write a broken seed. Report it so the user sees which
+                // seeds were not produced.
+                seedStatus = 'failed';
+                warnings.push(`seed generation failed after ${MAX_GEN_ATTEMPTS} attempts — no seed written`);
             }
         }
         cache[file] = hash;
-        results.push({ journeyName: journey.name, testPath, seedPath, status });
+        results.push({
+            journeyName: journey.name,
+            testPath,
+            seedPath,
+            status,
+            seedStatus,
+            warnings: warnings.length ? warnings : undefined,
+        });
     }
     saveCache(CACHE_PATH, cache);
     return results;

package/dist/core/seed-generator.js

@@ -16,10 +16,11 @@
  */
 import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
-import { loadConfig, splitCommand } from './config.js';
+import { loadConfig, splitCommand, withTextOnlyTools } from './config.js';
+import { cleanOutput } from './ai-generator.js';
 const MAP_PATH = 'testforge.md';
 /** Build the seed-generation prompt for one journey. */
-export function buildSeedPrompt(journeyDoc) {
+export function buildSeedPrompt(journeyDoc, seedPath) {
     const map = existsSync(MAP_PATH) ? readFileSync(MAP_PATH, 'utf-8') : '';
     const ext = loadConfig().testExtension ?? '.test.ts';
     const isJs = ext.endsWith('.js');
@@ -50,6 +51,17 @@ export function buildSeedPrompt(journeyDoc) {
         `- Use the database driver/ORM the project already uses (infer from`,
         `  the map / schema style).`,
         ``,
+        ...(seedPath
+            ? [
+                `This seed file will be saved at EXACTLY this path:`,
+                `  ${seedPath}`,
+                `Compute every require()/import path (to app source, models, config,`,
+                `etc.) RELATIVE TO THAT EXACT location — count the directory depth`,
+                `from that path, do not assume a conventional depth. A wrong`,
+                `relative depth makes the seed fail to load.`,
+                ``,
+            ]
+            : []),
         `Write the seed in ${language}.`,
         `Output ONLY the seed code. No explanation, no markdown code fences.`,
         `The very first characters must be code (a comment or import/require).`,
@@ -64,17 +76,18 @@ export function buildSeedPrompt(journeyDoc) {
     ].join('\n');
 }
 /** Generate a seed file's content for one journey doc, via the AI. */
-export function generateSeed(journeyDoc) {
-    const prompt = buildSeedPrompt(journeyDoc);
-    const { program, args } = splitCommand(loadConfig().aiCommand);
+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));
     const output = execFileSync(program, args, {
         input: prompt,
         encoding: 'utf-8',
         maxBuffer: 10 * 1024 * 1024,
     });
-    // Strip code fences if the AI added them despite instructions.
-    return output
-        .replace(/^```[a-zA-Z]*\n/, '')
-        .replace(/\n```\s*$/, '')
-        .trim();
+    // Share the test generator's robust cleaning: strips leading AND
+    // trailing prose, and throws if no code is found (so the caller can
+    // retry or skip rather than writing junk to disk).
+    return cleanOutput(output);
 }