@activate-core/test-forge 0.1.1 → 0.2.0

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/reconcile.js

@@ -0,0 +1,157 @@
+/**
+ * testforge — reconcile docs against an external reference.
+ *
+ * By default testforge's source of truth is what the AI derived from the
+ * project's own code (testforge.md + the journey docs under docs/). That
+ * is convenient, but it inherits any bugs or wrong assumptions in the
+ * code: if the code mishandles a scenario, the AI documents the wrong
+ * behavior, and every test then locks that wrong behavior in.
+ *
+ * This module lets a human point testforge at an AUTHORITATIVE reference
+ * of the expected behavior — a spec file in the repo, a document/PDF, a
+ * website, or a Notion page — and:
+ *
+ *   1. analyzeReference() — compares the reference against the current
+ *      testforge.md/docs, writes a comparison report to testforge.diff.md,
+ *      and prints a short summary. It changes nothing else.
+ *
+ *   2. applyReconciliation() — once the human confirms, rewrites the
+ *      journey docs so they reflect the reference as the source of truth
+ *      (fixing wrong expectations, adding missing journeys/cases).
+ *
+ * Both steps drive the configured AI CLI with file-read/write (and, for
+ * URLs/Notion, web) access. As with discover/map, this is tool-specific;
+ * it is tuned for the Claude CLI and other CLIs may need their own setup.
+ */
+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();
+}
+/**
+ * The journey-doc format, kept in sync with discover.ts so newly created
+ * docs match the ones setup produced. Referenced from the apply prompt.
+ */
+const DOC_FORMAT = [
+    `# 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 sections apply: Fields, Actions, Expected, Negative`,
+    `Cases, Race Conditions, Webhooks, Security Notes, Data.`,
+].join('\n');
+/** 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. This reference comes from a human/client, NOT from the code,`,
+        `so where it disagrees with the current docs the reference is right`,
+        `and the docs (which were derived from possibly-buggy code) are wrong.`,
+        ``,
+        `In THIS step you only COMPARE. Do not change the 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 (read the file, fetch the URL/page). If`,
+        `you cannot access it at all, print a line starting with "ERROR:"`,
+        `explaining why, and stop.`,
+        ``,
+        `Then read:`,
+        `  - the project map at "${MAP_PATH}" (if it exists)`,
+        `  - every journey doc under "${docsDir}/"`,
+        ``,
+        `Compare what the reference specifies against what the map and docs`,
+        `currently say, focusing on things that matter for testing:`,
+        `  - journeys/flows the reference describes that are MISSING from docs`,
+        `  - expected results / acceptance criteria that DIFFER`,
+        `  - fields, routes, validation, or error cases the reference requires`,
+        `    that the docs omit or get wrong`,
+        `  - anything the docs assert 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: docs say X vs reference says Y,`,
+        `                       and which should win)`,
+        `  ## Missing in docs  (journeys/cases only in the reference)`,
+        `  ## Docs-only        (in the docs but not the reference — may be`,
+        `                       code-derived assumptions to double-check)`,
+        ``,
+        `Do NOT modify "${MAP_PATH}" or anything 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 for the apply (reconcile) step. */
+export function buildApplyPrompt(reference, docsDir) {
+    return [
+        `You are a senior QA engineer. The developer has CONFIRMED that the`,
+        `reference below is the SOURCE OF TRUTH for tests, overriding what was`,
+        `previously derived from the code.`,
+        ``,
+        `Reference: ${reference}`,
+        `The comparison has already been computed — read "${DIFF_PATH}" for the`,
+        `differences you must resolve.`,
+        ``,
+        `Update the journey docs under "${docsDir}/" so they reflect the`,
+        `reference as the source of truth:`,
+        `  - Fix expected results / acceptance criteria to match the reference`,
+        `    wherever they differ.`,
+        `  - Add sections or cases the reference requires that are missing.`,
+        `  - For a journey the reference describes that has NO doc yet, create`,
+        `    "${docsDir}/<area>/<journey>.md" (area = folder, short kebab-case`,
+        `    journey name) using this format:`,
+        ``,
+        DOC_FORMAT,
+        ``,
+        `  - Where a doc made an assumption from the code that the reference`,
+        `    does not mention, KEEP it, but if it conflicts with the reference`,
+        `    add a line starting with "# TODO:" describing the conflict.`,
+        `  - If the reference reveals models/fields the map missed, update`,
+        `    "${MAP_PATH}" too.`,
+        ``,
+        `Never include secrets — refer to env var names only. Preserve the`,
+        `existing doc format. When done, print a SHORT summary listing which`,
+        `docs you created or changed.`,
+    ].join('\n');
+}
+/**
+ * Compare-only step. Reads the reference and the current docs/map, writes
+ * testforge.diff.md, and returns the AI's short summary. Changes nothing
+ * else. 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;
+}
+/**
+ * Apply step. Rewrites the docs (and map if needed) so they reflect the
+ * reference. Returns the AI's short summary of what it changed.
+ */
+export function applyReconciliation(reference, docsDir) {
+    return runAI(buildApplyPrompt(reference, docsDir));
+}

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);
 }

package/dist/core/setup.js

@@ -60,7 +60,7 @@ export function runSetup(srcDir) {
     // Build an env template so the developer knows which credentials each
     // area/journey needs for running the tests.
     console.log('Building env template...');
-    runEnvTemplate('docs', '.env.testing.example');
+    runEnvTemplate('docs', '.env.testing.example', srcDir);
     console.log('');
     console.log('Setup complete.');
     console.log('Review the drafts in docs/, fix anything the AI got wrong,');

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

@@ -0,0 +1,95 @@
+/**
+ * testforge — the "source of truth" barrier for `generate`.
+ *
+ * Before generating tests, testforge asks the developer WHAT the tests
+ * should be based on. Two answers are possible:
+ *
+ *   1. testforge.md + docs/  — what the AI derived from the project's own
+ *      code. Fast, but only as correct as the code it read.
+ *
+ *   2. An external reference — a spec/doc/PDF in the repo, a website, or
+ *      a Notion page — that captures the HUMAN/CLIENT expected behavior.
+ *      testforge compares it against the current docs (writing a diff for
+ *      the developer to inspect), and, on confirmation, reconciles the
+ *      docs so the reference wins. Tests are then generated from those
+ *      reconciled docs.
+ *
+ * This keeps the generate pipeline itself unchanged (it still reads
+ * docs/) — the barrier just decides whether the docs get reconciled
+ * against a reference first.
+ *
+ * Non-interactive callers (CI, cron, piped stdin) must not be blocked on
+ * a prompt, so:
+ *   - `source: 'docs'`        → skip the barrier, use docs as-is.
+ *   - `reference: <locator>`  → use that reference, analyze + apply with
+ *                               no prompts (implicit confirmation).
+ *   - neither, and no TTY     → fall back to docs with a printed note.
+ */
+import { isInteractive, promptChoice, promptConfirm, promptLine, } from './prompt.js';
+import { analyzeReference, applyReconciliation, DIFF_PATH } from './reconcile.js';
+/** Run the analyze step and reconcile the docs against the reference. */
+function reconcileToReference(reference, docsDir) {
+    console.log(`\nAnalyzing reference against current docs: ${reference}`);
+    console.log('(reading the reference, the map and docs/ — this may take a moment)\n');
+    const summary = analyzeReference(reference, docsDir);
+    console.log(summary);
+    console.log(`\nFull comparison written to ${DIFF_PATH}.`);
+    console.log('\nReconciling docs so the reference is the source of truth...\n');
+    const applied = applyReconciliation(reference, docsDir);
+    console.log(applied);
+    console.log('\nDocs updated. Generating tests from the reconciled docs.\n');
+}
+/**
+ * Resolve the source of truth before generation. May reconcile the docs
+ * in place (when a reference is chosen). Returns once docs/ reflects the
+ * chosen source; the caller then runs the normal generate pipeline.
+ */
+export async function resolveSourceOfTruth(opts) {
+    const { docsDir } = opts;
+    // Explicit "use the docs" — nothing to do.
+    if (opts.source === 'docs')
+        return;
+    // Explicit reference via flag: non-interactive analyze + apply.
+    if (opts.reference) {
+        reconcileToReference(opts.reference, docsDir);
+        return;
+    }
+    // No explicit choice and no terminal to ask on — do the safe,
+    // non-blocking thing: use the docs as they are.
+    if (!isInteractive()) {
+        console.log('Using testforge.md + docs/ as the source of truth ' +
+            '(non-interactive; pass --reference <file|url> to use an external reference).');
+        return;
+    }
+    // Interactive: ask what to base the tests on.
+    const choice = await promptChoice('What should the tests be based on?', [
+        'testforge.md + docs/ (what the AI derived from your code)',
+        'An external reference (a file/PDF in scope, a website, or a Notion link)',
+    ], 1);
+    if (choice === 1) {
+        console.log('Using testforge.md + docs/ as the source of truth.\n');
+        return;
+    }
+    const reference = await promptLine('\nProvide the reference (a file path, a URL, or a Notion link): ');
+    if (!reference) {
+        console.log('No reference given — falling back to testforge.md + docs/.\n');
+        return;
+    }
+    // Analyze first so the developer can see the differences, then confirm
+    // before we rewrite any docs.
+    console.log(`\nAnalyzing reference against current docs: ${reference}`);
+    console.log('(reading the reference, the map and docs/ — this may take a moment)\n');
+    const summary = analyzeReference(reference, docsDir);
+    console.log(summary);
+    console.log(`\nFull comparison written to ${DIFF_PATH}.`);
+    const apply = await promptConfirm('\nApply these changes to docs/ (make the reference the source of truth)?', false);
+    if (!apply) {
+        console.log(`\nKeeping the current docs. The comparison is saved in ${DIFF_PATH} ` +
+            'for you to review. Generating tests from the existing docs.\n');
+        return;
+    }
+    console.log('\nReconciling docs so the reference is the source of truth...\n');
+    const applied = applyReconciliation(reference, docsDir);
+    console.log(applied);
+    console.log('\nDocs updated. Generating tests from the reconciled docs.\n');
+}

package/dist/core/update.js

@@ -46,7 +46,7 @@ export function runUpdate(srcDir) {
     cache[SOURCE_KEY] = newHash;
     saveCache(CACHE_PATH, cache);
     console.log('Refreshing env template...');
-    runEnvTemplate('docs', '.env.testing.example');
+    runEnvTemplate('docs', '.env.testing.example', srcDir);
     console.log('');
     console.log('Update complete.');
 }