@activate-core/test-forge 0.12.1 → 0.13.1

package/dist/cli/index.js

@@ -24,6 +24,7 @@ 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 { dirname } from 'node:path';
 const command = process.argv[2];
 const useBasic = process.argv.includes('--basic');
@@ -78,6 +79,7 @@ function printUsage() {
     console.log('  testforge update            Re-check and update only what changed');
     console.log('  testforge env               Write .env.testing.example from docs');
     console.log('  testforge run [--area a] [--journey j]  Run the generated tests (Jest/Playwright)');
+    console.log('  testforge run --env-file <file>       Run against another server (e.g. .env.dev / .env.staging)');
 }
 async function main() {
     if (command === 'update') {
@@ -114,6 +116,7 @@ async function main() {
         const code = runTests({
             area: flagValue('--area'),
             journey: flagValue('--journey'),
+            envFile: flagValue('--env-file'),
         });
         process.exitCode = code;
     }
@@ -165,6 +168,50 @@ async function main() {
             runEnvTemplate('docs', '.env.testing.example', '.', generatedScanDirs());
         }
     }
+    else if (command === 'report') {
+        // Publish a test run to the TestForge dashboard. Public by design — the only
+        // secret is the per-project API key (TESTFORGE_KEY), issued by the dashboard.
+        loadDotenv(); // pick up TESTFORGE_KEY from a gitignored .testforge.env if present
+        const cfg = loadReportConfig();
+        const resultsPath = flagValue('--results');
+        const project = flagValue('--project') || cfg.project;
+        const dashboardUrl = flagValue('--dashboard') || cfg.dashboardUrl || process.env.TESTFORGE_DASHBOARD_URL;
+        const apiKey = process.env.TESTFORGE_KEY;
+        const category = flagValue('--category') || 'api';
+        // --inventory: register the FULL generated test inventory (all suites) so the
+        // dashboard shows the total test-case count before/independent of any run.
+        if (process.argv.includes('--inventory')) {
+            if (!dashboardUrl || !apiKey) {
+                console.error('Usage: testforge report --inventory [--dashboard <url>]   (TESTFORGE_KEY env required)');
+                process.exit(1);
+            }
+            console.log('Counting test cases (playwright --list expands parameterized tests; may take a moment)...');
+            const suites = scanInventory(process.cwd(), cfg.testOutput || {}, cfg.testExtension || '.test.js', cfg.framework || {});
+            const cases = suites.reduce((a, s) => a + s.total, 0);
+            const ir = await publishInventory({ suites, dashboardUrl, apiKey });
+            if (ir.status >= 200 && ir.status < 300)
+                console.log(`✓ Registered inventory: ${suites.length} suites, ${cases} test cases`);
+            else {
+                console.error(`✗ Inventory publish failed (${ir.status}): ${ir.text}`);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        if (!resultsPath || !project || !dashboardUrl || !apiKey) {
+            console.error('Usage: testforge report --results <jest-json> [--project <slug>] [--dashboard <url>] [--category api|web]');
+            console.error('  project / dashboard may also come from testforge.config.json.');
+            console.error('  TESTFORGE_KEY must be set in the environment (the key the dashboard gave you).');
+            process.exit(1);
+        }
+        const r = await publishReport({ resultsPath, project, dashboardUrl, apiKey, category });
+        if (r.status >= 200 && r.status < 300) {
+            console.log(`✓ Published "${project}" run to ${dashboardUrl}`);
+        }
+        else {
+            console.error(`✗ Publish failed (${r.status}): ${r.text}`);
+            process.exitCode = 1;
+        }
+    }
     else {
         printUsage();
     }

package/dist/core/ai-generator.js

@@ -83,21 +83,9 @@ export function buildPrompt(journey, map, testPath, focus, harnessPath, transpor
         : 'TypeScript';
     return [
         `You are a senior QA engineer. Generate a complete ${framework}`,
-        `for the user journey described below.`,
+        `for the user journey described below. (The specific file to write is`,
+        `stated at the very end, after the journey — read all the context first.)`,
         ``,
-        ...(focus
-            ? [
-                `SCOPE — this is ONE file in a larger suite for this journey.`,
-                `Cover ONLY this concern in this file:`,
-                `  ${focus.title}`,
-                `  ${focus.covers}`,
-                `Do NOT test the journey's other concerns here — separate files`,
-                `cover those. Go DEEP on this one concern (happy path + its own`,
-                `edge/negative/security cases) rather than broad-but-shallow.`,
-                `Use this exact describe() title: "${focus.title}".`,
-                ``,
-            ]
-            : []),
         `Think like an experienced tester whose goal is to break the`,
         `application. Cover, where relevant: happy path, missing/empty`,
         `required fields, invalid formats and boundary values (very long,`,
@@ -241,17 +229,6 @@ export function buildPrompt(journey, map, testPath, focus, harnessPath, transpor
                 `module (aliased as apiRequest above).`,
             ].join('\n'),
         ``,
-        ...(testPath
-            ? [
-                `This test file will be saved at EXACTLY this path:`,
-                `  ${testPath}`,
-                `Compute every require()/import path (to app source, helpers, the`,
-                `seed file, etc.) RELATIVE TO THAT EXACT location — count the`,
-                `directory depth from that path, do not assume a conventional`,
-                `depth. Getting the relative depth wrong breaks the whole file.`,
-                ``,
-            ]
-            : []),
         ...(transport
             ? [transport, `Do NOT import any library that is not already a dependency of this project.`, ``]
             : []),
@@ -298,6 +275,36 @@ export function buildPrompt(journey, map, testPath, focus, harnessPath, transpor
         `Data section. Use ALL of it. Respect any "# TODO:" notes.`,
         ``,
         journey.rawMarkdown,
+        // ---- PER-FILE TASK (kept LAST so the big context above stays a stable,
+        // cache-reusable prefix across every file in this journey, and so the
+        // concrete task is the most recent thing the model reads) ----
+        ``,
+        ...(focus
+            ? [
+                `--- THIS FILE (the one to write now) ---`,
+                `This is ONE file in a larger suite for this journey.`,
+                `Cover ONLY this concern here:`,
+                `  ${focus.title}`,
+                `  ${focus.covers}`,
+                `Do NOT test the journey's other concerns here — separate files`,
+                `cover those. Go DEEP on this one concern (happy path + its own`,
+                `edge/negative/security cases) rather than broad-but-shallow.`,
+                `Use this exact describe() title: "${focus.title}".`,
+            ]
+            : []),
+        ...(testPath
+            ? [
+                ``,
+                `Save this file at EXACTLY: ${testPath}`,
+                `Compute every require()/import path (app source, helpers, the seed`,
+                `file, etc.) RELATIVE TO THAT EXACT location — count the directory`,
+                `depth from that path; do not assume a conventional depth. Getting`,
+                `the relative depth wrong breaks the whole file.`,
+            ]
+            : []),
+        ``,
+        `Now output ONLY the raw ${isJs ? 'JavaScript' : 'TypeScript'} test code`,
+        `for THIS file — the first character must be the first line of code.`,
     ].join('\n');
 }
 /**

package/dist/core/cache.js

@@ -12,6 +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';
 /** Make a short fingerprint of a file's content. */
 export function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
@@ -63,7 +64,8 @@ const SKIP_DIRS = new Set([
     'coverage',
     '.next',
     'docs',
-    '.testforge',
+    STATE_DIR,
+    LEGACY_STATE_DIR,
     'generated-tests',
 ]);
 export function hashProjectSource(rootDir) {

package/dist/core/env-template.js

@@ -14,6 +14,7 @@
 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';
 /** Pull env var names from a chunk of text. */
 function extractEnvVars(text) {
     const vars = new Set();
@@ -43,7 +44,8 @@ const SKIP_DIRS = new Set([
     'coverage',
     'docs',
     'generated-tests',
-    '.testforge',
+    STATE_DIR,
+    LEGACY_STATE_DIR,
 ]);
 const SOURCE_EXT = /\.(c|m)?[jt]sx?$/i;
 /**
@@ -256,6 +258,12 @@ export function runEnvTemplate(docsDir, outPath, srcDir = '.', testDirs = []) {
         '# Only variables for the features you actually run are required.',
         '# Keep .env.testing OUT of version control.',
         '',
+        `# ${'='.repeat(40)}`,
+        '# TESTFORGE DASHBOARD (auto-publish each run)',
+        `# ${'='.repeat(40)}`,
+        'TESTFORGE_KEY=    # from the TestForge dashboard (Integration tab) — the per-project key',
+        'TESTFORGE_ENV=local # environment youre testing = the DB/target you connect to (local/dev/stage/production). Set it in the SAME env-file that points tests at that DB. Not from git branch.',
+        '',
     ];
     if (suiteVars.length > 0) {
         lines.push(`# ${'='.repeat(40)}`);

package/dist/core/harness.js

@@ -273,7 +273,7 @@ export function generateHarnessAsync(harnessPath, framework) {
  * dir, treats *.test.js as specs, and runs the testkit's setup() once via
  * globalSetup (mints/populates tokens before any worker starts).
  */
-export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage) {
+export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage, category = 'web') {
     return [
         `// @generated by testforge`,
         `// Minimal Playwright config so testforge's generated specs run.`,
@@ -285,14 +285,71 @@ export function playwrightConfig(testDirRelToPackage, globalSetupRelToPackage) {
         `  testMatch: /.*\\.(test|spec)\\.[jt]s$/,`,
         `  globalSetup: require.resolve('${globalSetupRelToPackage}'),`,
         `  timeout: 60000,`,
+        `  // Console line output. The last reporter auto-publishes the run to the`,
+        `  // TestForge dashboard (needs TESTFORGE_KEY in env + project/dashboardUrl`,
+        `  // in testforge.config.json).`,
+        `  reporter: [['line'], [require.resolve('@activate-core/test-forge/reporters/playwright-reporter.cjs'), { category: ${JSON.stringify(category)} }]],`,
         `  use: {`,
         `    baseURL: process.env.BASE_URL || 'http://localhost:3000',`,
         `    trace: 'on-first-retry',`,
+        `    screenshot: 'only-on-failure',`,
         `  },`,
         `});`,
         ``,
     ].join('\n');
 }
+/**
+ * Jest config for a backend (jest) area — self-contained so `npm test` / a bare
+ * `npx jest` runs with no shell setup.
+ *   - testEnvironment 'node': the default Node test environment
+ *   - setupFiles: loads .env.testing + NODE_ENV + the reset opt-in before any
+ *     test file imports the app
+ *   - serial (maxWorkers 1): suites share one test DB and reset between tests
+ */
+export function jestConfig(testDirRelToPackage, setupRelToPackage, category = 'api') {
+    return [
+        `// @generated by testforge`,
+        `// Install once:  npm i -D jest`,
+        `module.exports = {`,
+        `  testEnvironment: 'node',`,
+        `  setupFiles: ['<rootDir>/${setupRelToPackage}'],`,
+        `  testMatch: ['<rootDir>/${testDirRelToPackage}/**/*.test.js'],`,
+        `  // Serial: the suites share ONE test DB and reset it between tests.`,
+        `  maxWorkers: 1,`,
+        `  forceExit: true,`,
+        `  // 'default' keeps console output; the second reporter auto-publishes the`,
+        `  // run to the TestForge dashboard (needs TESTFORGE_KEY in env +`,
+        `  // project/dashboardUrl in testforge.config.json).`,
+        `  reporters: ['default', [require.resolve('@activate-core/test-forge/reporters/jest-reporter.cjs'), { category: ${JSON.stringify(category)} }]],`,
+        `};`,
+        ``,
+    ].join('\n');
+}
+/**
+ * Jest setup file (runs before each test file): loads the env so the suite is
+ * self-contained. Mirrors what a Playwright globalSetup + config does for web.
+ */
+export function jestSetupContent() {
+    return [
+        `// @generated by testforge`,
+        `'use strict';`,
+        `// Auto-loads test env so \`npm test\` / \`npx jest\` "just works" (no shell setup):`,
+        `//   .env.testing, NODE_ENV=testing, and opt-in to the destructive test reset.`,
+        `const fs = require('fs');`,
+        `const path = require('path');`,
+        `let dotenv; try { dotenv = require('dotenv'); } catch (_) { dotenv = null; }`,
+        ``,
+        `if (!process.env.NODE_ENV || process.env.NODE_ENV === 'test') {`,
+        `  process.env.NODE_ENV = 'testing';`,
+        `}`,
+        `const envFile = path.resolve(__dirname, '../.env.testing');`,
+        `if (dotenv && fs.existsSync(envFile)) dotenv.config({ path: envFile });`,
+        `if (process.env.TESTFORGE_ALLOW_RESET === undefined) {`,
+        `  process.env.TESTFORGE_ALLOW_RESET = 'true';`,
+        `}`,
+        ``,
+    ].join('\n');
+}
 /**
  * Playwright globalSetup file: runs the testkit's one-call setup() once
  * before the suite (connect + seed + mint/populate tokens). Sits next to

package/dist/core/init.js

@@ -44,6 +44,10 @@ export function buildInitPrompt() {
         `  tests use, or the project's language (TypeScript vs JavaScript).`,
         `- aiCommand: keep it as "claude -p" unless there is a clear reason`,
         `  to change it.`,
+        `- project: a short slug for this repo (kebab-case, e.g. the repo folder`,
+        `  name lower-cased). Identifies the project on the TestForge dashboard.`,
+        `- dashboardUrl: leave as an empty string "". The developer fills in the`,
+        `  TestForge dashboard URL when they connect the project.`,
         ``,
         `Write valid JSON only, in this shape:`,
         ``,
@@ -52,7 +56,9 @@ export function buildInitPrompt() {
         `  "testOutput": { "<area>": "<path>" },`,
         `  "framework": { "<area>": "<jest|playwright|...>" },`,
         `  "seedOutput": "<path>",`,
-        `  "testExtension": ".test.ts"`,
+        `  "testExtension": ".test.ts",`,
+        `  "project": "<repo-slug>",`,
+        `  "dashboardUrl": ""`,
         `}`,
         ``,
         `Base every path on real evidence in the project (existing test`,

package/dist/core/paths.js

@@ -0,0 +1,19 @@
+import { join } from 'node:path';
+/**
+ * Single source of truth for TestForge's per-project state directory and the
+ * files/sub-dirs inside it. Everything the tool persists between runs lives
+ * here (like `.git` for git): the doc-hash cache, the source-of-truth choice,
+ * the coverage manifest, and the per-journey generation plans.
+ *
+ * Rename in ONE place and every command — setup, discover, generate, update,
+ * coverage — follows automatically, so no path can drift out of sync.
+ */
+export const STATE_DIR = 'test-artifacts';
+/** Legacy state-dir name kept only so source-hash skip-lists still ignore a
+ *  pre-migration folder if one is lying around. Not written to. */
+export const LEGACY_STATE_DIR = '.testforge';
+export const CACHE_PATH = join(STATE_DIR, 'cache.json');
+export const SOURCE_PATH = join(STATE_DIR, 'source.json');
+export const COVERAGE_PATH = join(STATE_DIR, 'coverage.json');
+/** Per-journey generation plans, organised per area: <PLANS_DIR>/<area>/<id>.json */
+export const PLANS_DIR = join(STATE_DIR, 'test-plans');

package/dist/core/report.js

@@ -0,0 +1,269 @@
+/**
+ * report — TestForge's built-in, public "publish results to the dashboard" step.
+ *
+ * The tool itself needs no auth to run this; authentication is the per-project
+ * API key (issued by the dashboard) supplied via the TESTFORGE_KEY env var.
+ * Project + dashboard URL come from flags or a committed testforge.config.json.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+/**
+ * Load TESTFORGE_KEY (and any other vars) from a gitignored `.testforge.env`
+ * (then `.env`) at the project root, so a developer can keep the key in a file
+ * instead of exporting it every time. Never overrides vars already in the
+ * environment (a real `export` still wins). Add `.testforge.env` to .gitignore.
+ */
+export function loadDotenv(cwd = process.cwd()) {
+    for (const file of ['.testforge.env', '.env']) {
+        const p = path.join(cwd, file);
+        if (!fs.existsSync(p))
+            continue;
+        for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+            const s = line.trim();
+            if (!s || s.startsWith('#'))
+                continue;
+            const i = s.indexOf('=');
+            if (i === -1)
+                continue;
+            const k = s.slice(0, i).trim();
+            let v = s.slice(i + 1).trim();
+            if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))
+                v = v.slice(1, -1);
+            if (k && process.env[k] === undefined)
+                process.env[k] = v;
+        }
+    }
+}
+/** Read testforge.config.json (project, dashboardUrl) from the project root. */
+export function loadReportConfig(cwd = process.cwd()) {
+    const p = path.join(cwd, 'testforge.config.json');
+    if (fs.existsSync(p)) {
+        try {
+            return JSON.parse(fs.readFileSync(p, 'utf8'));
+        }
+        catch {
+            /* ignore malformed config */
+        }
+    }
+    return {};
+}
+const strip = (s) => (s || '').replace(/\x1b\[[0-9;]*m/g, '');
+/** Bucket a failure message into a root-cause signature the dashboard clusters on. */
+function signature(msg) {
+    const m = strip(msg || '').replace(/\n/g, ' ');
+    if (/403|whoami|invalid_grant|refresh token/i.test(m))
+        return 'IM auth (403)';
+    if (/\$gt|\$exists|injection/i.test(m))
+        return 'NoSQL injection accepted';
+    if (/timeout|timed out|ETIMEDOUT/i.test(m))
+        return 'Timeout';
+    if (/\b500\b|Internal Server/i.test(m))
+        return 'Server 500';
+    if (/expect|toBe|toEqual|Received|Expected/i.test(m))
+        return 'Assertion mismatch';
+    return 'Uncategorised';
+}
+/** Map a Jest `--json` report to the dashboard run contract. */
+export function mapJest(json, category = 'api') {
+    const suites = {};
+    for (const f of json.testResults || []) {
+        const name = String(f.name || f.testFilePath || 'suite')
+            .split('/').pop()
+            .replace(/\.(test|spec)\.[jt]s$/, '');
+        const su = (suites[name] ||= { name, category, tests: [] });
+        for (const a of f.assertionResults || []) {
+            const status = a.status === 'passed' ? 'passed' : a.status === 'failed' ? 'failed' : 'skipped';
+            const raw = a.failureMessages && a.failureMessages[0];
+            const err = strip(raw || '').split('\n').find((l) => l.trim()) || '';
+            su.tests.push({
+                name: a.title,
+                status,
+                error: status === 'failed' ? err.slice(0, 200) : undefined,
+                sig: status === 'failed' ? signature(raw) : undefined,
+            });
+        }
+    }
+    const durationSec = Math.round((json.testResults || []).reduce((a, f) => a + ((f.endTime || 0) - (f.startTime || 0)), 0) / 1000);
+    return { suites: Object.values(suites), durationSec };
+}
+export async function publishReport(opts) {
+    const json = JSON.parse(fs.readFileSync(opts.resultsPath, 'utf8'));
+    const { suites, durationSec } = mapJest(json, opts.category || 'api');
+    const body = { project: opts.project, env: opts.env || 'dev', durationSec, suites };
+    const res = await fetch(opts.dashboardUrl.replace(/\/$/, '') + '/api/v1/runs', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${opts.apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    return { status: res.status, text: await res.text() };
+}
+function walk(dir, ext, out) {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            walk(full, ext, out);
+        else if (e.name.endsWith(ext))
+            out.push(full);
+    }
+}
+const suiteName = (file) => path.basename(file).replace(/\.(test|spec)\.[jt]sx?$/, '');
+const staticCount = (file) => (fs.readFileSync(file, 'utf8').match(/\b(it|test)\s*\(/g) || []).length;
+/** Static fallback: count `it(`/`test(` occurrences per file (undercounts parameterized tests). */
+function jestStatic(dir, ext, category, out) {
+    const files = [];
+    walk(dir, ext, files);
+    for (const f of files)
+        out.push({ name: suiteName(f), category, total: staticCount(f) });
+}
+// setupFilesAfterEnv shim: runs after jest installs the test globals, replaces
+// every test BODY and before/after hook with a no-op. Collection still runs
+// (describe bodies, for-loops, .each all execute → real count), but nothing
+// slow does — no DB, no assertions. Applied via a temp config that extends the
+// project's own jest config, so env/mocks/moduleNameMapper/transforms are live.
+const COLLECT_PATCH = `
+const noop = () => {};
+['it','test','fit','xit','xtest'].forEach((name) => {
+  const orig = global[name];
+  if (typeof orig !== 'function') return;
+  const wrap = (t,_fn,to) => orig(t, noop, to);
+  if (orig.each) wrap.each = (...a) => { const r = orig.each(...a); return (t,_fn,to) => r(t, noop, to); };
+  wrap.only = wrap; wrap.concurrent = wrap; wrap.failing = wrap;
+  wrap.skip = orig.skip ? ((t,_fn,to) => orig.skip(t, noop, to)) : wrap;
+  wrap.todo = orig.todo ? orig.todo.bind(orig) : ((t) => orig(t, noop));
+  global[name] = wrap;
+});
+global.beforeAll = noop; global.beforeEach = noop; global.afterAll = noop; global.afterEach = noop;
+`;
+const COLLECT_CONFIG = `
+const fs = require('fs'), path = require('path');
+let base = {};
+for (const f of ['jest.config.js','jest.config.cjs','jest.config.json']) {
+  if (fs.existsSync(path.join(__dirname, f))) { base = require('./' + f); break; }
+}
+if (!Object.keys(base).length && fs.existsSync(path.join(__dirname,'package.json'))) base = require('./package.json').jest || {};
+module.exports = {
+  ...base,
+  testEnvironment: 'node', // plain node env for a count-only run
+  setupFilesAfterEnv: [...(base.setupFilesAfterEnv || []), path.resolve(__dirname, '.tf-collect-patch.cjs')],
+};
+`;
+/**
+ * Accurate for Jest: run the project's OWN jest with a temp config that no-ops
+ * test bodies + hooks. Files load exactly as under jest (setupFiles load
+ * .env.testing, jest.mock + transforms apply), so parameterized tests expand and
+ * nothing throws at import — but no bodies/DB run, so it's far faster than a real
+ * run. `numTotalTests` / per-file assertionResults give the true counts.
+ */
+function jestCount(dir, ext, category, out) {
+    const pkgDir = path.dirname(dir); // testOutput is <pkg>/tests → jest config lives in <pkg>
+    const patch = path.join(pkgDir, '.tf-collect-patch.cjs');
+    const cfg = path.join(pkgDir, '.tf-collect.config.cjs');
+    const outJson = path.join(os.tmpdir(), `tf-inv-${category}-${process.pid}.json`);
+    const files = [];
+    walk(dir, ext, files);
+    try {
+        fs.writeFileSync(patch, COLLECT_PATCH);
+        fs.writeFileSync(cfg, COLLECT_CONFIG);
+        try {
+            execSync('npx jest --config .tf-collect.config.cjs --json --outputFile=' + JSON.stringify(outJson) + ' --silent', {
+                cwd: pkgDir, stdio: ['ignore', 'ignore', 'ignore'], timeout: 300000,
+                env: { ...process.env, NODE_ENV: process.env.NODE_ENV || 'testing' },
+            });
+        }
+        catch { /* jest exits non-zero if a file errors at load; the --json is still written */ }
+        if (fs.existsSync(outJson)) {
+            const j = JSON.parse(fs.readFileSync(outJson, 'utf8'));
+            const seen = new Set();
+            for (const f of j.testResults || []) {
+                const n = suiteName(String(f.name || f.testFilePath || 'suite'));
+                seen.add(n);
+                out.push({ name: n, category, total: (f.assertionResults || []).length });
+            }
+            // any file jest couldn't even load → static, and say so loudly
+            for (const f of files) {
+                const n = suiteName(f);
+                if (seen.has(n))
+                    continue;
+                const total = staticCount(f);
+                console.warn(`  ! couldn't collect ${n} — static estimate (${total})`);
+                out.push({ name: n, category, total });
+            }
+            return;
+        }
+        console.warn(`  ! jest collect produced no output for "${category}" — static estimate for all suites`);
+        jestStatic(dir, ext, category, out);
+    }
+    finally {
+        for (const p of [patch, cfg, outJson]) {
+            try {
+                if (fs.existsSync(p))
+                    fs.unlinkSync(p);
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+/**
+ * Accurate for Playwright: `playwright test --list` does a collect pass that
+ * EXPANDS parameterized tests (loops / .each), so we get the real case count
+ * per file. Returns false if it couldn't run (caller falls back to static).
+ */
+function playwrightList(pkgDir, category, out) {
+    try {
+        const res = execSync('npx playwright test --list', {
+            cwd: pkgDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 180000,
+        });
+        const counts = {};
+        for (const line of res.split('\n')) {
+            const m = line.match(/([^\s›»]+\.(?:test|spec)\.[jt]sx?):\d+:\d+/);
+            if (m) {
+                const n = suiteName(m[1]);
+                counts[n] = (counts[n] || 0) + 1;
+            }
+        }
+        const names = Object.keys(counts);
+        if (!names.length)
+            return false;
+        for (const n of names)
+            out.push({ name: n, category, total: counts[n] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the per-suite inventory. Uses the framework's own enumeration where it
+ * exists (Playwright `--list` → real counts incl. parameterized), and a static
+ * estimate for Jest (whose true count is refined from actual runs on the dashboard).
+ */
+export function scanInventory(cwd, testOutput, ext, framework = {}) {
+    const suites = [];
+    for (const [category, rel] of Object.entries(testOutput || {})) {
+        const dir = path.join(cwd, rel);
+        if (!fs.existsSync(dir))
+            continue;
+        if (framework[category] === 'playwright') {
+            // package root (holds playwright.config) is the parent of the tests dir
+            if (playwrightList(path.dirname(dir), category, suites))
+                continue;
+            console.warn(`  ! playwright --list failed for "${category}" — using static estimate`);
+            jestStatic(dir, ext, category, suites);
+        }
+        else {
+            // jest (and ops/lambda, also jest-based) — accurate collect-only counter
+            jestCount(dir, ext, category, suites);
+        }
+    }
+    return suites;
+}
+export async function publishInventory(opts) {
+    const res = await fetch(opts.dashboardUrl.replace(/\/$/, '') + '/api/v1/inventory', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${opts.apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ suites: opts.suites }),
+    });
+    return { status: res.status, text: await res.text() };
+}

package/dist/core/run-generate.js

@@ -18,6 +18,7 @@
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { CACHE_PATH, COVERAGE_PATH, PLANS_DIR, STATE_DIR } from './paths.js';
 import { parseJourney } from './parser.js';
 import { generateTestCases } from './generator.js';
 import { writeDeferredStub } from './playwright-writer.js';
@@ -26,11 +27,10 @@ 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 { harnessInfo, generateHarnessAsync, generateHarness, playwrightConfig, globalSetupContent, fixturesDoc, } from './harness.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';
-const CACHE_PATH = '.testforge/cache.json';
 /** How many times to re-ask the AI when output won't parse. */
 const MAX_GEN_ATTEMPTS = 2;
 /** How many focused files to generate concurrently within a journey. */
@@ -176,22 +176,16 @@ export async function runHarness(only) {
         mkdirSync(dirname(info.path), { recursive: true });
         writeFileSync(info.path, kit, 'utf-8');
         writeFileSync(join(info.dir, 'FIXTURES.md'), fixturesDoc(), 'utf-8');
-        if (framework === 'playwright') {
-            const gsPath = join(info.dir, 'global-setup.js');
-            writeFileSync(gsPath, globalSetupContent(), 'utf-8');
-            const pkgRoot = dirname(areaDir);
-            const cfg = join(pkgRoot, 'playwright.config.js');
-            if (!existsSync(cfg)) {
-                const rel = areaDir.slice(pkgRoot.length + 1) || '.';
-                const gsRel = gsPath.slice(pkgRoot.length + 1);
-                writeFileSync(cfg, playwrightConfig(`./${rel}`, `./${gsRel}`), 'utf-8');
-            }
-        }
+        writeHarnessConfigs(framework, areaDir, info.dir, area);
         written.push(info.path);
     }
     return written;
 }
-const PLAN_DIR = '.testforge/plans';
+/** 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';
@@ -245,7 +239,7 @@ function hasDeferredStubs(testDir, ext) {
 }
 /** Slugs recorded in a journey's existing plan cache (the previous run). */
 function readPlanSlugs(journey) {
-    const p = join(PLAN_DIR, `${journey.area}__${journey.id}.json`);
+    const p = planPath(journey);
     try {
         const c = JSON.parse(readFileSync(p, 'utf-8'));
         if (Array.isArray(c.files)) {
@@ -290,7 +284,7 @@ function cleanStaleFiles(testDir, journeyId, ext, flat, keepSlugs, dropSlugs) {
  * the doc changes, the hash changes and we re-plan.
  */
 function loadOrPlan(journey, docHash) {
-    const p = join(PLAN_DIR, `${journey.area}__${journey.id}.json`);
+    const p = planPath(journey);
     if (existsSync(p)) {
         try {
             const cached = JSON.parse(readFileSync(p, 'utf-8'));
@@ -304,7 +298,7 @@ function loadOrPlan(journey, docHash) {
     }
     const files = planSuite(journey);
     try {
-        mkdirSync(PLAN_DIR, { recursive: true });
+        mkdirSync(dirname(p), { recursive: true });
         writeFileSync(p, JSON.stringify({ hash: docHash, files }, null, 2), 'utf-8');
     }
     catch {
@@ -361,19 +355,9 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
         mkdirSync(dirname(info.path), { recursive: true });
         writeFileSync(info.path, kit, 'utf-8');
         writeFileSync(join(info.dir, 'FIXTURES.md'), fixturesDoc(), 'utf-8');
-        // Playwright areas need a config + globalSetup so the specs can run
-        // AND get their tokens minted once before the suite.
-        if (framework === 'playwright') {
-            const gsPath = join(info.dir, 'global-setup.js');
-            writeFileSync(gsPath, globalSetupContent(), 'utf-8');
-            const pkgRoot = dirname(areaDir);
-            const cfg = join(pkgRoot, 'playwright.config.js');
-            if (!existsSync(cfg)) {
-                const rel = areaDir.slice(pkgRoot.length + 1) || '.';
-                const gsRel = gsPath.slice(pkgRoot.length + 1);
-                writeFileSync(cfg, playwrightConfig(`./${rel}`, `./${gsRel}`), 'utf-8');
-            }
-        }
+        // Config + globalSetup (playwright) / config + setup (jest) so the specs run
+        // AND get their tokens minted once, plus the runner config scaffolding.
+        writeHarnessConfigs(framework, areaDir, info.dir, area);
         harnessByArea.set(area, info.path);
         return info.path;
     }
@@ -392,16 +376,15 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
         // --journey <x>: generate just the one matching journey.
         if (only && !matchesJourney(file, journey.id, only))
             continue;
-        // Layout depends on the framework's test runner:
-        //  - Playwright (web/ops) recurses, so each journey gets its own
-        //    FOLDER of focused specs (testDir/<journey>/<slug>).
-        //  - Jest is often pointed at a flat glob (e.g. the-seam's
-        //    `**/service/*.test.js`, which does NOT recurse), so api/lambda
-        //    files stay FLAT in the test dir, journey-prefixed to stay unique
-        //    (testDir/<journey>-<slug>). Otherwise they'd silently not run.
+        // EVERY area gets its own per-journey FOLDER of focused files
+        // (testDir/<journey>/<slug>), for both Playwright and Jest. The folder
+        // namespaces the files, so the on-disk name is just the clean <slug>
+        // (no journey prefix) — which is also what the dashboard shows as the
+        // suite name. testforge's generated jest.config uses a recursive
+        // `tests/**/*.test.js` glob, so foldered jest files are still discovered.
         const areaDir = testDirForType(config, journey.area);
         const framework = resolveFramework(config, journey.area, journey.type);
-        const flat = framework === 'jest';
+        const flat = false; // foldered layout for all runners (clean, categorised)
         const testDir = flat ? areaDir : join(areaDir, journey.id);
         const seedPath = join(seedDir, `${journey.id}${seedExt}`);
         // Dependency-aware guardrails (F1): what this area may import, and how
@@ -529,8 +512,14 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
             }
             // Write IMMEDIATELY (not batched at the end of the journey), so an
             // interruption preserves every file generated so far.
-            mkdirSync(dirname(filePath), { recursive: true });
-            writeFileSync(filePath, content, 'utf-8');
+            // keepDeferredStubs:false (config) — do NOT write a DEFERRED stub file;
+            // it still counts as deferred in the coverage report (analyzeFile's catch
+            // treats the missing file as real:false), so nothing is hidden — we just
+            // don't litter the tree with placeholder error files.
+            if (!(status === 'basic' && config.keepDeferredStubs === false)) {
+                mkdirSync(dirname(filePath), { recursive: true });
+                writeFileSync(filePath, content, 'utf-8');
+            }
             return { slug: pf.slug, path: filePath, status };
         });
         const testFiles = generated.map((g) => ({
@@ -601,7 +590,7 @@ export async function runGenerate(docsDir, useAI = true, force = false, only, ar
  * 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
- * .testforge/coverage.json and summarised to the console.
+ * test-artifacts/coverage.json and summarised to the console.
  */
 function writeCoverageManifest(results) {
     const journeys = results
@@ -629,14 +618,43 @@ function writeCoverageManifest(results) {
     const totalReal = journeys.reduce((n, j) => n + j.real, 0);
     const totalDeferred = journeys.reduce((n, j) => n + j.deferred, 0);
     try {
-        mkdirSync('.testforge', { recursive: true });
-        writeFileSync(join('.testforge', 'coverage.json'), JSON.stringify({ real: totalReal, deferred: totalDeferred, journeys }, null, 2), 'utf-8');
+        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 .testforge/coverage.json`);
+    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
+ *  - jest:       helpers/jest.setup.js + jest.config.js
+ * Config files are written only if absent, so a project's hand-tuned config is
+ * never clobbered. `harnessDir` is the area's helpers dir (where setup lives).
+ */
+function writeHarnessConfigs(framework, areaDir, harnessDir, area) {
+    const pkgRoot = dirname(areaDir);
+    const rel = areaDir.slice(pkgRoot.length + 1) || '.';
+    if (framework === 'playwright') {
+        const gsPath = join(harnessDir, 'global-setup.js');
+        writeFileSync(gsPath, globalSetupContent(), 'utf-8');
+        const cfg = join(pkgRoot, 'playwright.config.js');
+        if (!existsSync(cfg)) {
+            const gsRel = gsPath.slice(pkgRoot.length + 1);
+            writeFileSync(cfg, playwrightConfig(`./${rel}`, `./${gsRel}`, area), 'utf-8');
+        }
+    }
+    else if (framework === 'jest') {
+        const setupPath = join(harnessDir, 'jest.setup.js');
+        writeFileSync(setupPath, jestSetupContent(), 'utf-8');
+        const cfg = join(pkgRoot, 'jest.config.js');
+        if (!existsSync(cfg)) {
+            const setupRel = setupPath.slice(pkgRoot.length + 1);
+            writeFileSync(cfg, jestConfig(rel, setupRel, area), 'utf-8');
+        }
+    }
+}

package/dist/core/run-tests.js

@@ -30,7 +30,7 @@ function packageRoot(dir) {
 }
 export function runTests(opts = {}) {
     const config = loadConfig();
-    const envFile = config.envFile ?? '.env.testing';
+    const envFile = opts.envFile ?? config.envFile ?? '.env.testing';
     const envVars = loadEnvFile(envFile);
     if (Object.keys(envVars).length > 0) {
         console.log(`Loaded env from ${envFile} (${Object.keys(envVars).length} vars).`);

package/dist/core/setup.js

@@ -12,6 +12,7 @@
  */
 import { existsSync } from 'node:fs';
 import { hashProjectSource, loadCache, saveCache } from './cache.js';
+import { CACHE_PATH } from './paths.js';
 import { runInit } from './init.js';
 import { runMap } from './map.js';
 import { runDiscover } from './discover.js';
@@ -55,9 +56,9 @@ export async function runSetup(srcDir, opts = {}) {
     await runDiscover(srcDir, 'docs', opts);
     console.log('  done — docs/\n');
     // Remember the source state so the first `update` can detect "no change".
-    const cache = loadCache('.testforge/cache.json');
+    const cache = loadCache(CACHE_PATH);
     cache['__source__'] = hashProjectSource(srcDir);
-    saveCache('.testforge/cache.json', cache);
+    saveCache(CACHE_PATH, cache);
     // Build an env template so the developer knows which credentials each
     // area/journey needs for running the tests.
     console.log('Building env template...');

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

@@ -9,7 +9,7 @@
  *   2. An external reference — a spec/doc/PDF in the repo, a website, or
  *      a Notion page capturing the human/client EXPECTED behavior.
  *
- * The choice is remembered in .testforge/source.json so later refreshes
+ * The choice is remembered in test-artifacts/source.json so later refreshes
  * (`update`) keep using the same source without asking again — otherwise
  * an update would silently regenerate reference-based docs from the code.
  *
@@ -22,7 +22,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { isInteractive, promptChoice, promptLine } from './prompt.js';
-const SOURCE_PATH = '.testforge/source.json';
+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/suite-planner.js

@@ -44,7 +44,13 @@ function buildPlanPrompt(journey, map) {
         `Output ONLY a JSON array (no prose, no markdown fences) of objects:`,
         `  [{ "slug": "<short-kebab-name>", "title": "<describe title>",`,
         `     "covers": "<one or two sentences: exactly what this file tests>" }]`,
-        `slug: lowercase, words joined by "-", no path and no file extension.`,
+        `slug: lowercase kebab-case, no path, no extension — and SHORT: name the`,
+        `  one concern in 2–4 words (4 max), the way a human names a file. Do NOT`,
+        `  restate the journey name and do NOT pile on qualifiers.`,
+        `  Good: "amount-validation", "3ds-challenge", "zero-amount", "rate-limit".`,
+        `  Bad:  "charge-amount-sanity-negative-nonnumeric-oversized",`,
+        `        "otp-session-otp-send-rate-limit".`,
+        `title: human-readable and specific, e.g. "Payment — Amount validation".`,
         `The very first character of your response must be "[".`,
         ``,
         `--- PROJECT MAP (data layer) ---`,
@@ -71,14 +77,16 @@ function extractJsonArray(text) {
         return [];
     }
 }
-/** Normalise a raw slug into a safe kebab-case file stem. */
+/** Normalise a raw slug into a safe, SHORT kebab-case file stem. */
 function safeSlug(raw) {
-    return String(raw ?? '')
+    const kebab = String(raw ?? '')
         .trim()
         .toLowerCase()
         .replace(/\.(spec|test)\.[jt]sx?$/, '') // drop any extension the AI added
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-|-$/g, '');
+    // Hard cap: keep names short & human — at most 4 words, whatever the AI returns.
+    return kebab.split('-').filter(Boolean).slice(0, 4).join('-');
 }
 /**
  * Plan the suite for one journey: returns the list of focused files to

package/dist/core/update.js

@@ -14,7 +14,7 @@ import { runDiscover } from './discover.js';
 import { runGenerate } from './run-generate.js';
 import { hashProjectSource, loadCache, saveCache } from './cache.js';
 import { runEnvTemplate } from './env-template.js';
-const CACHE_PATH = '.testforge/cache.json';
+import { CACHE_PATH } from './paths.js';
 const SOURCE_KEY = '__source__';
 export async function runUpdate(srcDir) {
     if (!existsSync('testforge.md') || !existsSync('testforge.config.json')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activate-core/test-forge",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "AI-powered QA automation. Scans a project, drafts journey docs, and generates seeded Jest/Playwright tests. Works in any project, with any AI CLI.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "main": "./dist/core/index.js",
   "files": [
     "dist",
+    "reporters",
     "README.md"
   ],
   "scripts": {

package/reporters/_shared.cjs

@@ -0,0 +1,153 @@
+// Shared helpers for the TestForge auto-publish reporters (plain CJS so jest &
+// playwright can require() them directly). No build step — runtime files.
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Walk up from cwd to the repo root (where testforge.config.json lives) so the
+// reporter works even when the framework runs from a package subdir (monorepo).
+function findRoot(cwd) {
+  let d = cwd;
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(d, 'testforge.config.json'))) return d;
+    const up = path.dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return cwd;
+}
+
+// Load TESTFORGE_KEY from a gitignored .testforge.env / .env (never overrides a real env var).
+function loadEnv(root) {
+  for (const f of ['.testforge.env', '.env']) {
+    const p = path.join(root, f);
+    if (!fs.existsSync(p)) continue;
+    for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+      const s = line.trim();
+      if (!s || s.startsWith('#')) continue;
+      const i = s.indexOf('=');
+      if (i === -1) continue;
+      const k = s.slice(0, i).trim();
+      let v = s.slice(i + 1).trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+      if (k && process.env[k] === undefined) process.env[k] = v;
+    }
+  }
+}
+
+function loadConfig(root) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, 'testforge.config.json'), 'utf8')); }
+  catch { return {}; }
+}
+
+const strip = (s) => (s || '').replace(/\x1b\[[0-9;]*m/g, '');
+
+// jest's raw matcher line (`expect(received).toBeGreaterThanOrEqual(expected)`) reads
+// backwards to a human. Translate the matcher into a plain, direction-correct sentence
+// so an engineer sees intent, not jest internals.
+const MATCHER = {
+  toBe: 'equal', toEqual: 'equal', toStrictEqual: 'equal',
+  toBeGreaterThanOrEqual: 'be at least', toBeGreaterThan: 'be greater than',
+  toBeLessThanOrEqual: 'be at most', toBeLessThan: 'be less than',
+  toContain: 'contain', toContainEqual: 'contain', toMatch: 'match',
+  toHaveLength: 'have length', toHaveProperty: 'have property', toBeCloseTo: 'be about',
+};
+function humanize(body) {
+  const m = body.match(/\.(\w+)\((?:expected|n|value|substring|sample|element)?\)/) || body.match(/expect\([^)]*\)\.(\w+)/);
+  const phrase = m && MATCHER[m[1]];
+  if (!phrase) return null;
+  const exp = (body.match(/Expected:?\s*(.+)/) || [])[1];
+  const rec = (body.match(/Received:?\s*(.+)/) || [])[1];
+  const ce = (exp || '').replace(/^[><=!~\s]+/, '').trim();
+  const cr = (rec || '').trim();
+  if (!ce || !cr) return null;
+  return `The check expected the result to ${phrase} ${ce}, but it was ${cr}.`;
+}
+
+// A readable failure detail for an engineer: a plain-language lead (what the check
+// wanted vs what it got) + the Expected/Received values + any custom message. Drops
+// jest's cryptic matcher line and the noisy stack frames / internal paths. Capped so
+// it stays a summary, not a full dump.
+function cleanError(raw) {
+  const s = strip(raw || '');
+  if (!s) return '';
+  const kept = s.split('\n').filter((l) => {
+    const t = l.trim();
+    if (!t) return true; // keep blank lines for readability (collapsed below)
+    if (/^at\s/.test(t)) return false;                       // stack frame
+    if (/node_modules|node:internal|\/dist\//.test(t)) return false; // library/internal noise
+    return true;
+  });
+  const body = kept.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+  const lead = humanize(body);
+  if (!lead) return body.slice(0, 700);
+  // The plain lead replaces jest's `expect(received)…` matcher line — drop it, keep the rest.
+  const rest = body.split('\n').filter((l) => !/^(Error:\s*)?expect\(/.test(l.trim())).join('\n').replace(/\n{3,}/g, '\n\n').trim();
+  return (lead + (rest ? '\n\n' + rest : '')).slice(0, 700);
+}
+
+function sh(cmd, cwd) {
+  try { return (execSync(cmd, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim()) || undefined; }
+  catch { return undefined; }
+}
+
+// Where did the tests run? branch + sha + ci build — from CI env vars first, else git.
+function gitInfo(root) {
+  let branch = process.env.TESTFORGE_BRANCH
+    || process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME
+    || process.env.CIRCLE_BRANCH || process.env.CI_COMMIT_REF_NAME
+    || process.env.GIT_BRANCH || process.env.BRANCH_NAME
+    || sh('git rev-parse --abbrev-ref HEAD', root);
+  if (branch) branch = branch.replace(/^refs\/heads\//, '').replace(/^origin\//, '');
+  if (branch === 'HEAD') branch = undefined; // detached checkout
+  const sha = process.env.GITHUB_SHA || process.env.CIRCLE_SHA1
+    || process.env.CI_COMMIT_SHA || process.env.GIT_COMMIT
+    || sh('git rev-parse --short HEAD', root);
+  const ciBuild = process.env.GITHUB_RUN_ID || process.env.CIRCLE_BUILD_NUM || process.env.BUILD_NUMBER;
+  return { branch: branch || undefined, sha: sha || undefined, ciBuild: ciBuild || undefined };
+}
+
+// Which environment does this run represent? The env is the TARGET you tested (which DB/host),
+// NOT the git branch — a reporter can't sniff the DB, so it's set explicitly via TESTFORGE_ENV
+// in the same env-file that points the tests at that DB (stage DB config → TESTFORGE_ENV=stage).
+// Bare local run with nothing set ⇒ "local". Branch/sha are recorded separately as identity only.
+function resolveEnv() {
+  return process.env.TESTFORGE_ENV || 'local';
+}
+
+function sig(msg) {
+  const m = strip(msg || '').replace(/\n/g, ' ');
+  if (/403|whoami|invalid_grant|refresh token/i.test(m)) return 'IM auth (403)';
+  if (/\$gt|\$exists|injection/i.test(m)) return 'NoSQL injection accepted';
+  if (/timeout|timed out|ETIMEDOUT/i.test(m)) return 'Timeout';
+  if (/\b500\b|Internal Server/i.test(m)) return 'Server 500';
+  if (/expect|toBe|toEqual|Received|Expected/i.test(m)) return 'Assertion mismatch';
+  return 'Uncategorised';
+}
+
+// POST the run to the dashboard. Never throws — a publish problem must not fail the test run.
+async function publish(category, suites, durationSec) {
+  const root = findRoot(process.cwd());
+  loadEnv(root);
+  const cfg = loadConfig(root);
+  const project = cfg.project, dashboardUrl = cfg.dashboardUrl, key = process.env.TESTFORGE_KEY;
+  if (!project || !dashboardUrl || !key) {
+    console.warn('[testforge] skipped publish — need "project" + "dashboardUrl" in testforge.config.json and TESTFORGE_KEY in .testforge.env');
+    return;
+  }
+  const { branch, sha, ciBuild } = gitInfo(root);
+  const env = resolveEnv();
+  try {
+    const res = await fetch(dashboardUrl.replace(/\/$/, '') + '/api/v1/runs', {
+      method: 'POST',
+      headers: { Authorization: 'Bearer ' + key, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ project, env, branch, sha, ciBuild, durationSec, suites }),
+    });
+    if (res.ok) console.log(`[testforge] ✓ published ${category} run (env: ${env}${branch ? ` · ${branch}` : ''}) → ${dashboardUrl}`);
+    else console.warn(`[testforge] publish failed (${res.status}): ${(await res.text()).slice(0, 200)}`);
+  } catch (e) {
+    console.warn('[testforge] publish error: ' + (e && e.message));
+  }
+}
+
+module.exports = { strip, cleanError, sig, publish, gitInfo, resolveEnv };

package/reporters/jest-reporter.cjs

@@ -0,0 +1,32 @@
+// TestForge Jest reporter — auto-publishes the run to the dashboard on completion.
+// Add to jest.config.js:
+//   reporters: ['default', ['<abs>/reporters/jest-reporter.cjs', { category: 'api' }]]
+const { cleanError, sig, publish } = require('./_shared.cjs');
+
+module.exports = class TestForgeJestReporter {
+  constructor(_globalConfig, options) {
+    this.category = (options && options.category) || 'api';
+  }
+  async onRunComplete(_contexts, results) {
+    const suites = {};
+    for (const f of results.testResults || []) {
+      const name = String(f.testFilePath || f.name || 'suite').split('/').pop().replace(/\.(test|spec)\.[jt]s$/, '');
+      const su = suites[name] || (suites[name] = { name, category: this.category, tests: [] });
+      for (const a of (f.testResults || f.assertionResults || [])) {
+        const status = a.status === 'passed' ? 'passed' : a.status === 'failed' ? 'failed' : 'skipped';
+        const raw = (a.failureMessages || [])[0];
+        su.tests.push({
+          name: a.fullName || a.title,
+          status,
+          error: status === 'failed' ? cleanError(raw) : undefined,
+          sig: status === 'failed' ? sig(raw) : undefined,
+          note: status === 'skipped'
+            ? (a.status === 'todo' ? 'Marked to-do — this scenario isn’t implemented yet' : 'Skipped — not run in this execution')
+            : undefined,
+        });
+      }
+    }
+    const durationSec = Math.round((results.startTime ? Date.now() - results.startTime : 0) / 1000);
+    await publish(this.category, Object.values(suites), durationSec);
+  }
+};

package/reporters/playwright-reporter.cjs

@@ -0,0 +1,31 @@
+// TestForge Playwright reporter — auto-publishes the run to the dashboard on completion.
+// Add to playwright.config.js reporter array:
+//   ['<abs>/reporters/playwright-reporter.cjs', { category: 'web' }]
+const { cleanError, sig, publish } = require('./_shared.cjs');
+
+module.exports = class TestForgePlaywrightReporter {
+  constructor(options) {
+    this.category = (options && options.category) || 'web';
+    this.suites = {};
+    this.start = Date.now();
+  }
+  onTestEnd(test, result) {
+    const file = (test.location && test.location.file) || 'suite';
+    const name = String(file).split('/').pop().replace(/\.(test|spec)\.[jt]s$/, '');
+    const su = this.suites[name] || (this.suites[name] = { name, category: this.category, tests: [] });
+    const status = result.status === 'passed' ? 'passed' : result.status === 'skipped' ? 'skipped' : 'failed';
+    const raw = result.error && result.error.message;
+    const skipAnno = (test.annotations || []).find((x) => x.type === 'skip' || x.type === 'fixme');
+    su.tests.push({
+      name: test.title,
+      status,
+      error: status === 'failed' ? cleanError(raw) : undefined,
+      sig: status === 'failed' ? sig(raw) : undefined,
+      note: status === 'skipped' ? ((skipAnno && skipAnno.description) || 'Skipped — not run in this execution') : undefined,
+    });
+  }
+  async onEnd(result) {
+    const durationSec = Math.round(((result && result.duration) || (Date.now() - this.start)) / 1000);
+    await publish(this.category, Object.values(this.suites), durationSec);
+  }
+};