@activate-core/test-forge 0.18.8 → 0.18.10

package/dist/cli/index.js

@@ -19,16 +19,16 @@
  *                                      (an auth-gated page can move unseen).
  */
 import { VERSION } from '../core/index.js';
-import { runGenerate } from '../core/run-generate.js';
-import { runTests } from '../core/run-tests.js';
-import { runDiscover } from '../core/discover.js';
-import { runMap } from '../core/map.js';
-import { runInit } from '../core/init.js';
-import { runSetup } from '../core/setup.js';
-import { runUpdate } from '../core/update.js';
-import { runEnvTemplate } from '../core/env-template.js';
-import { loadConfig } from '../core/config.js';
-import { publishReport, loadReportConfig, loadDotenv, scanInventory, publishInventory } from '../core/report.js';
+import { runGenerate } from '../core/generate/run-generate.js';
+import { runTests } from '../core/run/run-tests.js';
+import { runDiscover } from '../core/docs/discover.js';
+import { runMap } from '../core/project/map.js';
+import { runInit } from '../core/project/init.js';
+import { runSetup } from '../core/project/setup.js';
+import { runUpdate } from '../core/project/update.js';
+import { runEnvTemplate } from '../core/project/env-template.js';
+import { loadConfig } from '../core/project/config.js';
+import { publishReport, loadReportConfig, loadDotenv, scanInventory, publishInventory } from '../core/run/report.js';
 import { dirname } from 'node:path';
 const command = process.argv[2];
 const useBasic = process.argv.includes('--basic');

package/dist/core/{cache.js → docs/cache.js}

@@ -12,7 +12,7 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, } from 'node:fs';
 import { dirname, join, extname } from 'node:path';
-import { STATE_DIR, LEGACY_STATE_DIR } from './paths.js';
+import { STATE_DIR, LEGACY_STATE_DIR } from '../paths.js';
 /** Make a short fingerprint of a file's content. */
 export function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');

package/dist/core/{discover.js → docs/discover.js}

@@ -18,9 +18,9 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, } from 'node:fs';
 import { join, relative, sep, basename } from 'node:path';
 import { notAJourneyDoc } from './parser.js';
-import { loadConfig, splitCommand, withEditTools } from './config.js';
+import { loadConfig, splitCommand, withEditTools } from '../project/config.js';
 import { DEEP_DOC_GUIDANCE } from './doc-guidance.js';
-import { promptConfirm } from './prompt.js';
+import { promptConfirm } from '../prompt.js';
 import { loadSourceChoice, resolveDocsSource, saveJourneyReferences, saveSourceChoice, } from './source-of-truth.js';
 import { analyzeReference, draftDocsFromReference, DIFF_PATH, } from './reference.js';
 /** Scope line: one journey, or all of them. */

package/dist/core/{grounding.js → docs/grounding.js}

@@ -20,9 +20,9 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { loadConfig, splitCommand, withReadOnlyTools } from './config.js';
+import { loadConfig, splitCommand, withReadOnlyTools } from '../project/config.js';
 import { hashProjectSource } from './cache.js';
-import { STATE_DIR } from './paths.js';
+import { STATE_DIR } from '../paths.js';
 const MAP_PATH = 'testforge.md';
 /** Where a journey's grounded facts live, mirroring the plan cache layout. */
 function groundingPath(journey) {

package/dist/core/{reference.js → docs/reference.js}

@@ -22,7 +22,7 @@
  * and tuned for the Claude CLI.
  */
 import { execFileSync } from 'node:child_process';
-import { loadConfig, splitCommand, withReferenceTools } from './config.js';
+import { loadConfig, splitCommand, withReferenceTools } from '../project/config.js';
 import { DEEP_DOC_GUIDANCE } from './doc-guidance.js';
 /** Where the comparison report is written. */
 export const DIFF_PATH = 'testforge.diff.md';

package/dist/core/{source-of-truth.js → docs/source-of-truth.js}

@@ -21,8 +21,8 @@
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { isInteractive, promptChoice, promptLine } from './prompt.js';
-import { SOURCE_PATH } from './paths.js';
+import { isInteractive, promptChoice, promptLine } from '../prompt.js';
+import { SOURCE_PATH } from '../paths.js';
 /** Read the remembered source choice, or null if none/invalid. */
 export function loadSourceChoice() {
     if (!existsSync(SOURCE_PATH))

package/dist/core/gates/coverage.js

@@ -0,0 +1,54 @@
+/**
+ * testforge — the coverage manifest.
+ *
+ * A green run is only meaningful if the count behind it is honest, so this
+ * records REAL files (they assert something) apart from DEFERRED ones (they
+ * are pending placeholders). Without the split, a suite of placeholders reads
+ * as full coverage.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { analyzeFile } from './validate.js';
+import { COVERAGE_PATH, STATE_DIR } from '../paths.js';
+/**
+ * F8 — write an honest coverage manifest. For every generated file it
+ * records real (has assertions) vs deferred (pending only), so a "green"
+ * run is never mistaken for full coverage. Written to
+ * test-artifacts/coverage.json and summarised to the console.
+ */
+export function writeCoverageManifest(results) {
+    const journeys = results
+        .filter((r) => r.testFiles.length)
+        .map((r) => {
+        const files = r.testFiles.map((t) => {
+            let a = { activeTests: 0, pending: 0, assertions: 0, real: false };
+            try {
+                a = analyzeFile(readFileSync(t.path, 'utf-8'));
+            }
+            catch {
+                /* file unreadable — count as empty */
+            }
+            return { file: t.path, status: t.status, ...a };
+        });
+        return {
+            journey: r.journeyName,
+            real: files.filter((f) => f.real).length,
+            deferred: files.filter((f) => !f.real).length,
+            files,
+        };
+    });
+    if (!journeys.length)
+        return;
+    const totalReal = journeys.reduce((n, j) => n + j.real, 0);
+    const totalDeferred = journeys.reduce((n, j) => n + j.deferred, 0);
+    try {
+        mkdirSync(STATE_DIR, { recursive: true });
+        writeFileSync(COVERAGE_PATH, JSON.stringify({ real: totalReal, deferred: totalDeferred, journeys }, null, 2), 'utf-8');
+    }
+    catch {
+        /* best-effort */
+    }
+    console.log(`\nCoverage: ${totalReal} real test file(s), ${totalDeferred} deferred/placeholder — see ${COVERAGE_PATH}`);
+    if (totalDeferred) {
+        console.log(`  (deferred files are pending, NOT real coverage — regenerate or implement them.)`);
+    }
+}

package/dist/core/{ai-generator.js → generate/ai-generator.js}

@@ -12,7 +12,7 @@
  */
 import { execFileSync, spawn } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
-import { loadConfig, splitCommand, withReadOnlyTools, resolveFramework, } from './config.js';
+import { loadConfig, splitCommand, withReadOnlyTools, resolveFramework, } from '../project/config.js';
 const MAP_PATH = 'testforge.md';
 /**
  * Spawn a command, feed `input` on stdin, resolve with its stdout.

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

@@ -0,0 +1,120 @@
+/**
+ * testforge — is the AI answering, and if not, why.
+ *
+ * One place owns the answer, because every caller needs the same one: the
+ * per-file generator, the seed generator and the harness builder all ask the
+ * same CLI, and a limit that stops one has stopped them all. Keeping the
+ * state here is what lets a run say "AI unavailable: <reason>" once and wait,
+ * instead of each caller failing on its own with no explanation.
+ *
+ * Nothing here decides what to DO about it — run-generate owns that. This
+ * module only reports.
+ */
+import { pingAi } from './ai-generator.js';
+// WHY the last AI attempt failed, and whether the AI is gone for the whole run.
+//
+// Both validators used to swallow the error and retry, so when the AI CLI was
+// unavailable — usage limit reached mid-run, not logged in, not installed —
+// the operator saw "could not be generated with AI" forty-three times and no
+// reason, while every remaining journey was burned into a deferred stub and
+// every seed retried against a dead CLI. Record the reason, put it in the
+// warning, and once the failure is clearly "AI unavailable" stop starting new
+// journeys: the deferred stubs are re-attempted automatically on the next run.
+let lastAiFailure = null;
+let aiUnavailable = null;
+// Process failures in a row with no success between them. The CLI does not
+// always SAY it is out — on wagonex it exited 1 with empty stderr for every
+// call and the message-matching below saw nothing to match, so thirteen
+// journeys were burned before anyone noticed. Two silent failures in a row
+// earn a ping; if the ping fails too, the AI is unavailable, message or not.
+let consecutiveAiFailures = 0;
+const AI_UNAVAILABLE = /usage limit|spend limit|limit will reset|rate limit|\b429\b|not logged in|please log ?in|unauthori[sz]ed|invalid api key|credit balance|quota|spawn \S+ ENOENT/i;
+export function noteAiFailure(e) {
+    // execFileSync attaches what the process said; node's own message is just
+    // "Command failed: <cmd>", which explains nothing.
+    const x = e;
+    const said = [x.stderr, x.stdout].map((v) => String(v ?? '').trim()).find(Boolean);
+    let msg = (x.message ?? String(e)).replace(/\s+/g, ' ').trim();
+    if (said && !msg.includes(said.slice(0, 40)))
+        msg += `: ${said}`;
+    if (x.signal === 'SIGKILL' && !/timed out/.test(msg))
+        msg += ' (killed — hit aiTimeoutMs)';
+    lastAiFailure = msg.slice(0, 300);
+    consecutiveAiFailures += 1;
+    if (AI_UNAVAILABLE.test(msg))
+        aiUnavailable = lastAiFailure;
+}
+export function noteAiRejected(why) {
+    // The AI answered, but with something we will not write. Not a sign it is
+    // gone — do not count it towards unavailability — but the operator still
+    // deserves to know why the file is a stub.
+    lastAiFailure = `AI output rejected: ${why}`.slice(0, 300);
+}
+export function noteAiSuccess() {
+    consecutiveAiFailures = 0;
+}
+/**
+ * Two silent failures in a row: ask the CLI directly whether it is alive.
+ * Returns true when it was failing but answers now — the caller then redoes
+ * the journey those failures degraded, exactly as after a wait.
+ */
+export async function confirmAiAlive() {
+    if (aiUnavailable || consecutiveAiFailures < 2)
+        return false;
+    if (!(await pingAi(60_000))) {
+        aiUnavailable = lastAiFailure ?? 'the AI CLI is not answering';
+        return false;
+    }
+    consecutiveAiFailures = 0;
+    return true;
+}
+export function aiFailureNote() {
+    return lastAiFailure ? ` — last AI error: ${lastAiFailure}` : '';
+}
+/**
+ * Wait for the AI CLI to answer again after a usage limit. Polls with a
+ * one-line question every `aiWaitPollMs` for up to `aiWaitMaxMs`; true when
+ * it is back (and the failure state is cleared), false when the cap is hit.
+ * Progress goes to the console because a run that sits silent for hours
+ * looks hung.
+ */
+export async function waitForAi(config) {
+    const poll = config.aiWaitPollMs ?? 20 * 60_000;
+    const max = config.aiWaitMaxMs ?? 8 * 3_600_000;
+    const mins = (ms) => `${Math.max(1, Math.round(ms / 60_000))} min`;
+    console.log(`\nAI unavailable: ${aiUnavailable}\n` +
+        `Waiting for it to come back — checking every ${mins(poll)}, for up to ${mins(max)}. ` +
+        `Ctrl-C is safe: re-running later resumes from exactly here.`);
+    const started = Date.now();
+    while (Date.now() - started < max) {
+        await new Promise((r) => setTimeout(r, poll));
+        if (await pingAi(60_000)) {
+            console.log(`AI is back (${new Date().toLocaleTimeString()}) — resuming.`);
+            aiUnavailable = null;
+            lastAiFailure = null;
+            return true;
+        }
+        console.log(`${new Date().toLocaleTimeString()} still unavailable — next check in ${mins(poll)}`);
+    }
+    console.log(`Gave up waiting after ${mins(max)}.`);
+    return false;
+}
+/** The reason the AI is unavailable, or null while it is answering. */
+export function aiUnavailableReason() {
+    return aiUnavailable;
+}
+/** Forget everything — called once at the start of a run. */
+export function resetAiSession() {
+    lastAiFailure = null;
+    aiUnavailable = null;
+    consecutiveAiFailures = 0;
+}
+/**
+ * True while the last thing that went wrong was the AI PROCESS failing (as
+ * opposed to it answering with output we refused). run-generate uses this to
+ * tell "the outage is over, redo what it broke" from "that file was simply
+ * rejected", which needs no redo.
+ */
+export function lastAiFailureWasProcess() {
+    return consecutiveAiFailures > 0;
+}

package/dist/core/{harness.js → generate/harness.js}

@@ -13,7 +13,7 @@
  */
 import { execFileSync, spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { loadConfig, splitCommand, withReadOnlyTools } from './config.js';
+import { loadConfig, splitCommand, withReadOnlyTools } from '../project/config.js';
 import { cleanOutput } from './ai-generator.js';
 const MAP_PATH = 'testforge.md';
 /**

package/dist/core/generate/plan-cache.js

@@ -0,0 +1,181 @@
+/**
+ * testforge — the per-journey suite plan, and what is already on disk.
+ *
+ * A journey is split into focused files, one per concern, and that split is
+ * cached so a re-run does not re-ask the AI for a plan it already has. The
+ * rest of this module answers the questions a resume needs: which files the
+ * plan expects, which of those are real and which are placeholders, and which
+ * files from an older plan are now stale.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { planSuite } from './suite-planner.js';
+import { PLANS_DIR } from '../paths.js';
+/** The line every generated file carries, so cleanup never touches a hand-written one. */
+export const GEN_MARKER = '@generated by testforge';
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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`;
+}
+/** Plan cache path for a journey, organised per area:
+ *  `<PLANS_DIR>/<area>/<id>.json` (e.g. test-artifacts/test-plans/api/payment-api.json). */
+export function planPath(journey) {
+    return join(PLANS_DIR, journey.area, `${journey.id}.json`);
+}
+/**
+ * F9 — a journey doc that is still an unconfirmed stub. Deep-generating
+ * confident assertions from it produces UNVALIDATED tests, so we skip it
+ * and tell the user to confirm the spec first.
+ */
+export function isStubDoc(markdown) {
+    // The doc's FIRST heading is its premise. A confirmed journey opens with a
+    // real title (e.g. "# Journey: ..."); a genuine stub opens by declaring
+    // itself uncovered ("# TODO: not covered by the reference ...").
+    //
+    // We deliberately look ONLY at the opening heading. Partial "reference
+    // SILENT" annotations on individual SECTIONS of an otherwise-complete doc,
+    // and trailing "developer verification checklist" sections, are healthy —
+    // the previous whole-document scan wrongly skipped confirmed journeys that
+    // merely carried such notes.
+    const firstHeading = (markdown.match(/^#{1,6}\s+.+$/m) || [''])[0];
+    return /\btodo\b|not covered by the reference|reference[-\s]silent|unconfirmed/i.test(firstHeading);
+}
+/**
+ * True if a generated file is a testforge DEFERRED stub — a placeholder
+ * written when AI generation was unavailable. It is NOT real coverage, so
+ * per-file resume must RE-ATTEMPT it (unlike a real file, which is kept).
+ */
+export function isDeferredStub(content) {
+    return content.includes('DEFERRED stub');
+}
+/** True if the journey's output dir already holds any deferred stub. */
+export function hasDeferredStubs(testDir, ext) {
+    let files;
+    try {
+        files = readdirSync(testDir);
+    }
+    catch {
+        return false;
+    }
+    for (const f of files) {
+        if (!f.endsWith(ext))
+            continue;
+        try {
+            if (isDeferredStub(readFileSync(join(testDir, f), 'utf-8')))
+                return true;
+        }
+        catch {
+            /* ignore unreadable */
+        }
+    }
+    return false;
+}
+/** Slugs recorded in a journey's existing plan cache (the previous run). */
+export function readPlanSlugs(journey) {
+    const p = planPath(journey);
+    try {
+        const c = JSON.parse(readFileSync(p, 'utf-8'));
+        if (Array.isArray(c.files)) {
+            return c.files.map((f) => f.slug).filter((s) => !!s);
+        }
+    }
+    catch {
+        /* no previous plan */
+    }
+    return [];
+}
+/**
+ * F6 — replace, don't duplicate. When a journey is (re)generated and its
+ * plan changed, the files for slugs that no longer exist are stale. Delete
+ * them — but ONLY files that carry our marker, so we never touch a
+ * developer's own tests. Prevents the twin-suite accumulation.
+ */
+export function cleanStaleFiles(testDir, journeyId, ext, flat, keepSlugs, dropSlugs) {
+    const removed = [];
+    const keep = new Set(keepSlugs);
+    for (const slug of dropSlugs) {
+        if (keep.has(slug))
+            continue;
+        const base = flat ? `${journeyId}-${slug}` : slug;
+        const f = join(testDir, `${base}${ext}`);
+        try {
+            if (existsSync(f) && readFileSync(f, 'utf-8').includes(GEN_MARKER)) {
+                rmSync(f);
+                removed.push(`${base}${ext}`);
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return removed;
+}
+/**
+ * Get a journey's file plan, cached by doc hash. Caching the plan keeps
+ * the file slugs STABLE across runs, so per-file resume (skip-existing)
+ * actually matches — and it saves the planner AI call on a resume. When
+ * the doc changes, the hash changes and we re-plan.
+ */
+export function loadOrPlan(journey, docHash) {
+    const p = planPath(journey);
+    if (existsSync(p)) {
+        try {
+            const cached = JSON.parse(readFileSync(p, 'utf-8'));
+            if (cached.hash === docHash && Array.isArray(cached.files) && cached.files.length) {
+                return cached.files;
+            }
+        }
+        catch {
+            // corrupt plan cache — re-plan
+        }
+    }
+    const files = planSuite(journey);
+    try {
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, JSON.stringify({ hash: docHash, files }, null, 2), 'utf-8');
+    }
+    catch {
+        // best-effort cache
+    }
+    return files;
+}
+/** Does this doc file / journey match a --journey selector? */
+export 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);
+}

package/dist/core/{run-generate.js → generate/run-generate.js}

@@ -16,23 +16,25 @@
  * so tests/seeds land where the project expects them. Defaults to
  * generated-tests/ when not configured.
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, } from 'node:fs';
 import { join, dirname, basename, extname } from 'node:path';
-import { CACHE_PATH, COVERAGE_PATH, PLANS_DIR, STATE_DIR } from './paths.js';
-import { lintGenerated } from './lint.js';
-import { parseJourney, notAJourneyDoc } from './parser.js';
+import { CACHE_PATH } from '../paths.js';
+import { lintGenerated } from '../gates/lint.js';
+import { parseJourney, notAJourneyDoc } from '../docs/parser.js';
+import { writeCoverageManifest } from '../gates/coverage.js';
+import { cleanStaleFiles, collisionWarning, hasDeferredStubs, isDeferredStub, isStubDoc, loadOrPlan, readPlanSlugs, GEN_MARKER, matchesJourney, } from './plan-cache.js';
+import { aiFailureNote, aiUnavailableReason, confirmAiAlive, lastAiFailureWasProcess, noteAiFailure, noteAiRejected, noteAiSuccess, resetAiSession, waitForAi, } from './ai-session.js';
 import { generateTestCases } from './generator.js';
 import { writeDeferredStub } from './playwright-writer.js';
-import { generateWithAI, generateWithAIAsync, pingAi, } from './ai-generator.js';
-import { groundJourney } from './grounding.js';
+import { generateWithAI, generateWithAIAsync, } from './ai-generator.js';
+import { groundJourney } from '../docs/grounding.js';
 import { generateSeed } from './seed-generator.js';
-import { planSuite } from './suite-planner.js';
-import { isSyntaxValid, checkTestGates, analyzeFile } from './validate.js';
-import { installedModules, transportHint, projectSelectors } from './detect.js';
+import { isSyntaxValid, checkTestGates } from '../gates/validate.js';
+import { installedModules, transportHint, projectSelectors } from '../project/detect.js';
 import { harnessInfo, generateHarnessAsync, generateHarness, playwrightConfig, globalSetupContent, fixturesDoc, jestConfig, jestSetupContent, } from './harness.js';
-import { hashContent, loadCache, saveCache } from './cache.js';
-import { findMarkdownFiles } from './find-files.js';
-import { loadConfig, testDirForType, resolveFramework } from './config.js';
+import { hashContent, loadCache, saveCache } from '../docs/cache.js';
+import { findMarkdownFiles } from '../find-files.js';
+import { loadConfig, testDirForType, resolveFramework } from '../project/config.js';
 /** 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. */
@@ -57,99 +59,11 @@ async function pool(items, limit, fn) {
     await Promise.all(Array.from({ length: n }, () => worker()));
     return results;
 }
-// WHY the last AI attempt failed, and whether the AI is gone for the whole run.
-//
-// Both validators used to swallow the error and retry, so when the AI CLI was
-// unavailable — usage limit reached mid-run, not logged in, not installed —
-// the operator saw "could not be generated with AI" forty-three times and no
-// reason, while every remaining journey was burned into a deferred stub and
-// every seed retried against a dead CLI. Record the reason, put it in the
-// warning, and once the failure is clearly "AI unavailable" stop starting new
-// journeys: the deferred stubs are re-attempted automatically on the next run.
-let lastAiFailure = null;
-let aiUnavailable = null;
-// Process failures in a row with no success between them. The CLI does not
-// always SAY it is out — on wagonex it exited 1 with empty stderr for every
-// call and the message-matching below saw nothing to match, so thirteen
-// journeys were burned before anyone noticed. Two silent failures in a row
-// earn a ping; if the ping fails too, the AI is unavailable, message or not.
-let consecutiveAiFailures = 0;
-const AI_UNAVAILABLE = /usage limit|spend limit|limit will reset|rate limit|\b429\b|not logged in|please log ?in|unauthori[sz]ed|invalid api key|credit balance|quota|spawn \S+ ENOENT/i;
-function noteAiFailure(e) {
-    // execFileSync attaches what the process said; node's own message is just
-    // "Command failed: <cmd>", which explains nothing.
-    const x = e;
-    const said = [x.stderr, x.stdout].map((v) => String(v ?? '').trim()).find(Boolean);
-    let msg = (x.message ?? String(e)).replace(/\s+/g, ' ').trim();
-    if (said && !msg.includes(said.slice(0, 40)))
-        msg += `: ${said}`;
-    if (x.signal === 'SIGKILL' && !/timed out/.test(msg))
-        msg += ' (killed — hit aiTimeoutMs)';
-    lastAiFailure = msg.slice(0, 300);
-    consecutiveAiFailures += 1;
-    if (AI_UNAVAILABLE.test(msg))
-        aiUnavailable = lastAiFailure;
-}
-function noteAiRejected(why) {
-    // The AI answered, but with something we will not write. Not a sign it is
-    // gone — do not count it towards unavailability — but the operator still
-    // deserves to know why the file is a stub.
-    lastAiFailure = `AI output rejected: ${why}`.slice(0, 300);
-}
-function noteAiSuccess() {
-    consecutiveAiFailures = 0;
-}
-/**
- * Two silent failures in a row: ask the CLI directly whether it is alive.
- * Returns true when it was failing but answers now — the caller then redoes
- * the journey those failures degraded, exactly as after a wait.
- */
-async function confirmAiAlive() {
-    if (aiUnavailable || consecutiveAiFailures < 2)
-        return false;
-    if (!(await pingAi(60_000))) {
-        aiUnavailable = lastAiFailure ?? 'the AI CLI is not answering';
-        return false;
-    }
-    consecutiveAiFailures = 0;
-    return true;
-}
-function aiFailureNote() {
-    return lastAiFailure ? ` — last AI error: ${lastAiFailure}` : '';
-}
-/**
- * Wait for the AI CLI to answer again after a usage limit. Polls with a
- * one-line question every `aiWaitPollMs` for up to `aiWaitMaxMs`; true when
- * it is back (and the failure state is cleared), false when the cap is hit.
- * Progress goes to the console because a run that sits silent for hours
- * looks hung.
- */
-async function waitForAi(config) {
-    const poll = config.aiWaitPollMs ?? 20 * 60_000;
-    const max = config.aiWaitMaxMs ?? 8 * 3_600_000;
-    const mins = (ms) => `${Math.max(1, Math.round(ms / 60_000))} min`;
-    console.log(`\nAI unavailable: ${aiUnavailable}\n` +
-        `Waiting for it to come back — checking every ${mins(poll)}, for up to ${mins(max)}. ` +
-        `Ctrl-C is safe: re-running later resumes from exactly here.`);
-    const started = Date.now();
-    while (Date.now() - started < max) {
-        await new Promise((r) => setTimeout(r, poll));
-        if (await pingAi(60_000)) {
-            console.log(`AI is back (${new Date().toLocaleTimeString()}) — resuming.`);
-            aiUnavailable = null;
-            lastAiFailure = null;
-            return true;
-        }
-        console.log(`${new Date().toLocaleTimeString()} still unavailable — next check in ${mins(poll)}`);
-    }
-    console.log(`Gave up waiting after ${mins(max)}.`);
-    return false;
-}
 /** Async version of generateValidated (for concurrent per-file gen). */
 async function generateValidatedAsync(generate, ext, gate) {
     let content = '';
     for (let attempt = 0; attempt < MAX_GEN_ATTEMPTS; attempt++) {
-        if (aiUnavailable)
+        if (aiUnavailableReason())
             return null; // retrying a dead CLI only burns time
         try {
             content = await generate();
@@ -174,7 +88,7 @@ async function generateValidatedAsync(generate, ext, gate) {
 function generateValidated(generate, ext, gate) {
     let content = '';
     for (let attempt = 0; attempt < MAX_GEN_ATTEMPTS; attempt++) {
-        if (aiUnavailable)
+        if (aiUnavailableReason())
             return null; // retrying a dead CLI only burns time
         try {
             content = generate();
@@ -213,40 +127,6 @@ function buildTest(journey, useAI, ext, testPath, framework, focus, grounding) {
     const cases = generateTestCases(journey);
     return { content: writeDeferredStub(journey, cases, framework), 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`;
-}
 /**
  * (Re)generate ONLY the shared harness for one or all areas — without
  * touching any test file. Use this after upgrading the harness (e.g. to
@@ -285,141 +165,8 @@ export async function runHarness(only) {
     }
     return written;
 }
-/** Plan cache path for a journey, organised per area:
- *  `<PLANS_DIR>/<area>/<id>.json` (e.g. test-artifacts/test-plans/api/payment-api.json). */
-function planPath(journey) {
-    return join(PLANS_DIR, journey.area, `${journey.id}.json`);
-}
 /** Marker every testforge-written test carries, so stale-file cleanup
  * (F6) only ever removes OUR files, never hand-authored ones. */
-const GEN_MARKER = '@generated by testforge';
-/**
- * F9 — a journey doc that is still an unconfirmed stub. Deep-generating
- * confident assertions from it produces UNVALIDATED tests, so we skip it
- * and tell the user to confirm the spec first.
- */
-function isStubDoc(markdown) {
-    // The doc's FIRST heading is its premise. A confirmed journey opens with a
-    // real title (e.g. "# Journey: ..."); a genuine stub opens by declaring
-    // itself uncovered ("# TODO: not covered by the reference ...").
-    //
-    // We deliberately look ONLY at the opening heading. Partial "reference
-    // SILENT" annotations on individual SECTIONS of an otherwise-complete doc,
-    // and trailing "developer verification checklist" sections, are healthy —
-    // the previous whole-document scan wrongly skipped confirmed journeys that
-    // merely carried such notes.
-    const firstHeading = (markdown.match(/^#{1,6}\s+.+$/m) || [''])[0];
-    return /\btodo\b|not covered by the reference|reference[-\s]silent|unconfirmed/i.test(firstHeading);
-}
-/**
- * True if a generated file is a testforge DEFERRED stub — a placeholder
- * written when AI generation was unavailable. It is NOT real coverage, so
- * per-file resume must RE-ATTEMPT it (unlike a real file, which is kept).
- */
-function isDeferredStub(content) {
-    return content.includes('DEFERRED stub');
-}
-/** True if the journey's output dir already holds any deferred stub. */
-function hasDeferredStubs(testDir, ext) {
-    let files;
-    try {
-        files = readdirSync(testDir);
-    }
-    catch {
-        return false;
-    }
-    for (const f of files) {
-        if (!f.endsWith(ext))
-            continue;
-        try {
-            if (isDeferredStub(readFileSync(join(testDir, f), 'utf-8')))
-                return true;
-        }
-        catch {
-            /* ignore unreadable */
-        }
-    }
-    return false;
-}
-/** Slugs recorded in a journey's existing plan cache (the previous run). */
-function readPlanSlugs(journey) {
-    const p = planPath(journey);
-    try {
-        const c = JSON.parse(readFileSync(p, 'utf-8'));
-        if (Array.isArray(c.files)) {
-            return c.files.map((f) => f.slug).filter((s) => !!s);
-        }
-    }
-    catch {
-        /* no previous plan */
-    }
-    return [];
-}
-/**
- * F6 — replace, don't duplicate. When a journey is (re)generated and its
- * plan changed, the files for slugs that no longer exist are stale. Delete
- * them — but ONLY files that carry our marker, so we never touch a
- * developer's own tests. Prevents the twin-suite accumulation.
- */
-function cleanStaleFiles(testDir, journeyId, ext, flat, keepSlugs, dropSlugs) {
-    const removed = [];
-    const keep = new Set(keepSlugs);
-    for (const slug of dropSlugs) {
-        if (keep.has(slug))
-            continue;
-        const base = flat ? `${journeyId}-${slug}` : slug;
-        const f = join(testDir, `${base}${ext}`);
-        try {
-            if (existsSync(f) && readFileSync(f, 'utf-8').includes(GEN_MARKER)) {
-                rmSync(f);
-                removed.push(`${base}${ext}`);
-            }
-        }
-        catch {
-            /* best-effort */
-        }
-    }
-    return removed;
-}
-/**
- * Get a journey's file plan, cached by doc hash. Caching the plan keeps
- * the file slugs STABLE across runs, so per-file resume (skip-existing)
- * actually matches — and it saves the planner AI call on a resume. When
- * the doc changes, the hash changes and we re-plan.
- */
-function loadOrPlan(journey, docHash) {
-    const p = planPath(journey);
-    if (existsSync(p)) {
-        try {
-            const cached = JSON.parse(readFileSync(p, 'utf-8'));
-            if (cached.hash === docHash && Array.isArray(cached.files) && cached.files.length) {
-                return cached.files;
-            }
-        }
-        catch {
-            // corrupt plan cache — re-plan
-        }
-    }
-    const files = planSuite(journey);
-    try {
-        mkdirSync(dirname(p), { recursive: true });
-        writeFileSync(p, JSON.stringify({ hash: docHash, files }, null, 2), 'utf-8');
-    }
-    catch {
-        // best-effort cache
-    }
-    return files;
-}
-/** 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, areaOnly, opts = {}) {
     const allFiles = findMarkdownFiles(docsDir);
     if (allFiles.length === 0) {
@@ -431,9 +178,7 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
     const seedExt = ext.endsWith('.js') ? '.seed.js' : '.seed.ts';
     const cache = loadCache(CACHE_PATH);
     const results = [];
-    lastAiFailure = null;
-    aiUnavailable = null;
-    consecutiveAiFailures = 0;
+    resetAiSession();
     // Only journey docs are generated from. A file at the docs root, under a
     // "_reference/" folder, or without a "# Journey:" heading is reference
     // material — report it once and leave it alone rather than inventing a
@@ -542,8 +287,8 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
         if (useAI && (await confirmAiAlive()) && redoPrevious())
             continue;
         if (useAI &&
-            !aiUnavailable &&
-            consecutiveAiFailures === 0 &&
+            !aiUnavailableReason() &&
+            !lastAiFailureWasProcess() &&
             i > 0 &&
             stubbed.has(files[i - 1]) &&
             redoPrevious()) {
@@ -553,7 +298,7 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
         // journey would only become deferred stubs. Either wait for it to come back
         // (--wait-for-limit) or stop here; either way the stubs already written are
         // re-attempted automatically on the next run.
-        if (aiUnavailable && useAI) {
+        if (aiUnavailableReason() && useAI) {
             if (waitForLimit && (await waitForAi(config))) {
                 if (redoPrevious())
                     continue;
@@ -857,7 +602,8 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
             ],
         });
     }
-    if (notAttempted > 0 && aiUnavailable) {
+    const unavailable = aiUnavailableReason();
+    if (notAttempted > 0 && unavailable) {
         // One line, not one per journey: the operator needs the reason and the
         // count, then to re-run once the CLI is back.
         results.push({
@@ -868,7 +614,7 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
             status: 'skipped',
             seedStatus: 'none',
             warnings: [
-                `${aiUnavailable}. Nothing was written for these; re-run \`testforge generate\` when the AI CLI is back — deferred stubs from this run are re-attempted automatically.`,
+                `${unavailable}. Nothing was written for these; re-run \`testforge generate\` when the AI CLI is back — deferred stubs from this run are re-attempted automatically.`,
             ],
         });
     }
@@ -876,49 +622,6 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
     writeCoverageManifest(results);
     return results;
 }
-/**
- * F8 — write an honest coverage manifest. For every generated file it
- * records real (has assertions) vs deferred (pending only), so a "green"
- * run is never mistaken for full coverage. Written to
- * test-artifacts/coverage.json and summarised to the console.
- */
-function writeCoverageManifest(results) {
-    const journeys = results
-        .filter((r) => r.testFiles.length)
-        .map((r) => {
-        const files = r.testFiles.map((t) => {
-            let a = { activeTests: 0, pending: 0, assertions: 0, real: false };
-            try {
-                a = analyzeFile(readFileSync(t.path, 'utf-8'));
-            }
-            catch {
-                /* file unreadable — count as empty */
-            }
-            return { file: t.path, status: t.status, ...a };
-        });
-        return {
-            journey: r.journeyName,
-            real: files.filter((f) => f.real).length,
-            deferred: files.filter((f) => !f.real).length,
-            files,
-        };
-    });
-    if (!journeys.length)
-        return;
-    const totalReal = journeys.reduce((n, j) => n + j.real, 0);
-    const totalDeferred = journeys.reduce((n, j) => n + j.deferred, 0);
-    try {
-        mkdirSync(STATE_DIR, { recursive: true });
-        writeFileSync(COVERAGE_PATH, JSON.stringify({ real: totalReal, deferred: totalDeferred, journeys }, null, 2), 'utf-8');
-    }
-    catch {
-        /* best-effort */
-    }
-    console.log(`\nCoverage: ${totalReal} real test file(s), ${totalDeferred} deferred/placeholder — see ${COVERAGE_PATH}`);
-    if (totalDeferred) {
-        console.log(`  (deferred files are pending, NOT real coverage — regenerate or implement them.)`);
-    }
-}
 /**
  * Write the per-area runner config.
  *  - playwright: global-setup.js + playwright.config.js

package/dist/core/{seed-generator.js → generate/seed-generator.js}

@@ -16,7 +16,7 @@
  */
 import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
-import { loadConfig, splitCommand, withReadOnlyTools } from './config.js';
+import { loadConfig, splitCommand, withReadOnlyTools } from '../project/config.js';
 import { cleanOutput } from './ai-generator.js';
 const MAP_PATH = 'testforge.md';
 /** Build the seed-generation prompt for one journey. */

package/dist/core/{suite-planner.js → generate/suite-planner.js}

@@ -16,7 +16,7 @@
  */
 import { execFileSync } from 'node:child_process';
 import { readFileSync, existsSync } from 'node:fs';
-import { loadConfig, splitCommand, withReadOnlyTools } from './config.js';
+import { loadConfig, splitCommand, withReadOnlyTools } from '../project/config.js';
 const MAP_PATH = 'testforge.md';
 /** Build the planning prompt for one journey. */
 function buildPlanPrompt(journey, map) {

package/dist/core/{env-template.js → project/env-template.js}

@@ -13,8 +13,8 @@
  */
 import { readFileSync, writeFileSync, existsSync, readdirSync, } from 'node:fs';
 import { join } from 'node:path';
-import { findMarkdownFiles } from './find-files.js';
-import { STATE_DIR, LEGACY_STATE_DIR } from './paths.js';
+import { findMarkdownFiles } from '../find-files.js';
+import { STATE_DIR, LEGACY_STATE_DIR } from '../paths.js';
 /** Pull env var names from a chunk of text. */
 function extractEnvVars(text) {
     const vars = new Set();

package/dist/core/{setup.js → project/setup.js}

@@ -11,11 +11,11 @@
  * single stage; setup just chains them for a smooth first run.
  */
 import { existsSync } from 'node:fs';
-import { hashProjectSource, loadCache, saveCache } from './cache.js';
-import { CACHE_PATH } from './paths.js';
+import { hashProjectSource, loadCache, saveCache } from '../docs/cache.js';
+import { CACHE_PATH } from '../paths.js';
 import { runInit } from './init.js';
 import { runMap } from './map.js';
-import { runDiscover } from './discover.js';
+import { runDiscover } from '../docs/discover.js';
 import { runEnvTemplate } from './env-template.js';
 export async function runSetup(srcDir, opts = {}) {
     // If the project already looks set up, don't redo it — point the user

package/dist/core/{update.js → project/update.js}

@@ -10,12 +10,12 @@
  */
 import { existsSync } from 'node:fs';
 import { runMap } from './map.js';
-import { runDiscover } from './discover.js';
-import { runGenerate } from './run-generate.js';
-import { hashProjectSource, hashReference, loadCache, saveCache } from './cache.js';
-import { loadSourceChoice } from './source-of-truth.js';
+import { runDiscover } from '../docs/discover.js';
+import { runGenerate } from '../generate/run-generate.js';
+import { hashProjectSource, hashReference, loadCache, saveCache } from '../docs/cache.js';
+import { loadSourceChoice } from '../docs/source-of-truth.js';
 import { runEnvTemplate } from './env-template.js';
-import { CACHE_PATH } from './paths.js';
+import { CACHE_PATH } from '../paths.js';
 const SOURCE_KEY = '__source__';
 const REFERENCE_KEY = '__reference__';
 export async function runUpdate(srcDir, opts = {}) {

package/dist/core/{run-tests.js → run/run-tests.js}

@@ -15,7 +15,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join, dirname, resolve, relative } from 'node:path';
-import { loadConfig, loadEnvFile, testDirForType, resolveFramework, } from './config.js';
+import { loadConfig, loadEnvFile, testDirForType, resolveFramework, } from '../project/config.js';
 /** Nearest ancestor dir containing a package.json (the runner's cwd). */
 function packageRoot(dir) {
     let d = resolve(dir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activate-core/test-forge",
-  "version": "0.18.8",
+  "version": "0.18.10",
   "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": {
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "rm -rf dist && tsc",
     "dev": "tsc --watch"
   },
   "license": "MIT",