@izkac/forgekit 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {

package/src/e2e-cli.test.mjs

@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const E2E = path.join(path.dirname(fileURLToPath(import.meta.url)), 'e2e.mjs');
+
+function tmp(prefix) {
+  return fs.mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+function run(cwd, args) {
+  return execFileSync(process.execPath, [E2E, ...args], {
+    cwd,
+    env: { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('e2e-fleet-'), 's') },
+  }).toString();
+}
+
+/** .forge fixture with an active session tracking a specs change. */
+function makeFixture(root) {
+  const sessionDir = path.join(root, '.forge', 'sessions', 's1');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    `${JSON.stringify({ id: 's1', slug: 'fixture', planType: 'specs', openspecChange: 'my-change' })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(root, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  fs.mkdirSync(path.join(root, 'specs', 'changes', 'my-change'), { recursive: true });
+}
+
+test('e2e harness: record → show → surfaced by init; config keys preserved', () => {
+  const root = tmp('e2e-harness-');
+  makeFixture(root);
+  // Pre-existing config keys must survive the harness merge-write.
+  fs.writeFileSync(
+    path.join(root, '.forge', 'config.json'),
+    `${JSON.stringify({ plan: { engine: 'specs', dir: 'specs' } }, null, 2)}\n`,
+    'utf8',
+  );
+
+  assert.match(run(root, ['harness']), /No harness recorded/);
+
+  run(root, [
+    'harness',
+    '--set',
+    'compose test stack: server + scratch mongo on isolated ports',
+    '--start',
+    'npm run e2e:stack',
+    '--dir',
+    'scripts/e2e',
+  ]);
+
+  const cfg = JSON.parse(fs.readFileSync(path.join(root, '.forge', 'config.json'), 'utf8'));
+  assert.equal(cfg.plan.engine, 'specs');
+  assert.equal(cfg.e2e.harness.start, 'npm run e2e:stack');
+  assert.match(cfg.e2e.harness.description, /compose test stack/);
+
+  assert.match(run(root, ['harness']), /REUSE it — do not build/);
+  assert.match(run(root, ['init']), /REUSE it — do not build/);
+  assert.equal(JSON.parse(run(root, ['status'])).harness.dir, 'scripts/e2e');
+});
+
+test('e2e harness --set requires a description', () => {
+  const root = tmp('e2e-harness-req-');
+  makeFixture(root);
+  assert.throws(() => run(root, ['harness', '--set']), /Usage: forge e2e harness --set/);
+});

package/src/e2e.mjs

@@ -7,6 +7,8 @@
  *   forge e2e init [--force]          # scaffold e2e.json for the active change
  *   forge e2e run                     # execute steps, write e2e-results.json (session dir)
  *   forge e2e check                   # gate check: green + current results; exit 1 with problems
+ *   forge e2e harness                 # show recorded project harness (reuse it!)
+ *   forge e2e harness --set "<desc>" [--start "<cmd>"] [--dir <path>]
  *   [--session <id>]
  *
  * e2e.json lives next to spine.json (change dir, falling back to the session
@@ -17,6 +19,7 @@
 
 import fs from 'node:fs';
 import { loadSession, readActive, readJson } from './lib.mjs';
+import { loadProjectConfig, saveProjectConfig } from './config.mjs';
 import {
   checkE2eGate,
   e2ePath,
@@ -34,11 +37,57 @@ const sub = args[0] && !args[0].startsWith('--') ? args[0] : 'status';
 
 if (args[0] === '--help' || sub === 'help') {
   process.stdout.write(
-    'Usage: forge e2e [init [--force] | run | check | status] [--session <id>]\n',
+    'Usage: forge e2e [init [--force] | run | check | status | harness [--set <desc> --start <cmd> --dir <path>]] [--session <id>]\n',
   );
   process.exit(0);
 }
 
+/** Recorded project harness (committed in .forge/config.json → e2e.harness). */
+function loadHarness() {
+  const cfg = loadProjectConfig(process.cwd());
+  const h = cfg?.e2e?.harness;
+  return h && typeof h === 'object' ? h : null;
+}
+
+function harnessLines(h) {
+  const lines = [`Existing e2e harness (REUSE it — do not build or ask for a new one):`];
+  lines.push(`  ${h.description}`);
+  if (h.start) lines.push(`  Start: ${h.start}`);
+  if (h.dir) lines.push(`  Location: ${h.dir}`);
+  return lines.join('\n');
+}
+
+// Project-level, no session needed.
+if (sub === 'harness') {
+  const si = args.indexOf('--set');
+  if (si >= 0) {
+    const description = args[si + 1];
+    if (!description || description.startsWith('--')) {
+      process.stderr.write('Usage: forge e2e harness --set "<description>" [--start "<cmd>"] [--dir <path>]\n');
+      process.exit(1);
+    }
+    const harness = { description, recordedAt: new Date().toISOString() };
+    const st = args.indexOf('--start');
+    if (st >= 0 && args[st + 1]) harness.start = args[st + 1];
+    const di = args.indexOf('--dir');
+    if (di >= 0 && args[di + 1]) harness.dir = args[di + 1];
+    saveProjectConfig(process.cwd(), { e2e: { harness } }, { mergeKeys: ['adr', 'plan', 'e2e'] });
+    process.stdout.write(
+      `Recorded harness in .forge/config.json (commit it). Future sessions will see it on forge e2e init.\n`,
+    );
+    process.exit(0);
+  }
+  const h = loadHarness();
+  if (!h) {
+    process.stdout.write(
+      'No harness recorded. After building one (with operator approval), record it:\n  forge e2e harness --set "<what/where>" --start "<command>" [--dir <path>]\n',
+    );
+    process.exit(0);
+  }
+  process.stdout.write(`${harnessLines(h)}\n`);
+  process.exit(0);
+}
+
 let sessionId = null;
 let force = false;
 for (let i = 0; i < args.length; i += 1) {
@@ -74,6 +123,8 @@ if (sub === 'init') {
   process.stdout.write(
     `Scaffolded ${file}\nAuthor the product-loop steps (produce → consume → assert domain side effects).\nSteps that would pass against a stubbed handler are invalid.\nRun with: forge e2e run\n`,
   );
+  const harness = loadHarness();
+  if (harness) process.stdout.write(`\n${harnessLines(harness)}\n`);
   process.exit(0);
 }
 
@@ -133,7 +184,7 @@ if (sub === 'check') {
 
 if (sub === 'status') {
   if (!fs.existsSync(file)) {
-    process.stdout.write(JSON.stringify({ file, exists: false }, null, 2));
+    process.stdout.write(JSON.stringify({ file, exists: false, harness: loadHarness() }, null, 2));
     process.stdout.write('\n');
     process.exit(0);
   }
@@ -153,6 +204,7 @@ if (sub === 'status') {
         exists: true,
         ok: valid.ok,
         problems: valid.problems,
+        harness: loadHarness(),
         results: results
           ? {
               file: e2eResultsPath(dir),

package/vendor/skills/forge/references/runtime-integrity.md

@@ -87,11 +87,29 @@ a loop is complex exactly when the feature has many wiring seams, which is
 when wiring silently breaks. Never skip the loop for complexity; control its
 cost instead:
 
-- **Ask before building new harness infrastructure, not before testing.** If
-  a harness already exists (test server, isolated ports, scratch DB), the loop
-  is cheap — author it. If the loop would require building a harness from
-  scratch or driving a third-party service, stop and ask the user: that is a
-  project, not a test.
+- **Ask before building complex harness infrastructure — and only then.**
+  The ask-line is infrastructure: a rig built from scratch, new
+  servers/containers/services, third-party accounts or sandboxes (e.g. real
+  payment checkout), device farms. That is a project, not a test — stop and
+  ask the user. **Everything below that line never needs permission**: if a
+  harness already exists (test server, isolated ports, scratch DB), author
+  the loop; writing fixtures, seed data, helper scripts, or extra steps
+  inside the existing rig is normal test work — just do it. Asking for
+  fixture-level work is over-asking; skipping the loop because the rig is
+  missing is under-testing — the ask is exactly the moment the operator can
+  say "build it once" and make every future loop on the project cheap.
+- **A built harness is permanent project infrastructure — record it, reuse
+  it.** When the operator approves building one: build it as committed
+  project code (never session scratch), then record it:
+
+  ```bash
+  forge e2e harness --set "<what it is / where>" --start "<start command>" [--dir <path>]
+  ```
+
+  This lands in `.forge/config.json` (committed), and every later session
+  sees it — `forge e2e init` and `forge e2e status` print the recorded
+  harness. Check `forge e2e harness` before proposing to build or asking the
+  operator; proposing a new rig while one is recorded is a REJECT.
 - **One executed loop per capability, not per assertion.** Push edge cases
   into unit tests; e2e proves the wiring exists.
 - **Set `timeoutMs` from the step count up front.** A 10-step loop is never a