forge-workflow 0.1.0-beta.7 → 0.1.0-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.8",
   "packageManager": "bun@1.4.2",
   "description": "Local runtime control plane for AI-assisted engineering workflows, gates, evidence, and all AI agents",
   "bin": {
@@ -23,7 +23,7 @@
     "prebuild": "node scripts/gen-command-manifest.js",
     "lint": "eslint . --max-warnings 0",
     "check": "node scripts/validate.js",
-    "prepare": "lefthook install || echo 'Note: lefthook not installed. Git hooks disabled. Run: bun add -d lefthook'",
+    "prepare": "node -e \"process.exit(process.env.npm_command === 'pack' ? 0 : 1)\" || lefthook install || echo 'Note: lefthook not installed. Git hooks disabled. Run: bun add -d lefthook'",
     "setup": "node ./bin/forge.js setup",
     "help": "node ./bin/forge.js --help",
     "gen:assets": "bun scripts/gen-embedded-assets.mjs",
@@ -52,6 +52,9 @@
     "@commitlint/cli": "^21.0.0",
     "@commitlint/config-conventional": "^21.0.0",
     "@eslint/js": "^10.0.1",
+    "@forge/contracts": "0.1.0-beta.6",
+    "@forge/flow": "0.1.0-beta.6",
+    "@forge/memory": "0.1.0-beta.6",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
     "@stryker-mutator/core": "^9.6.0",
     "c8": "^12.0.0",
@@ -89,6 +92,8 @@
   "files": [
     "bin/",
     "lib/",
+    "!lib/embedded-assets.generated.mjs",
+    "!lib/embedded-assets.generated-assets/",
     "rules/",
     "skills/",
     ".claude/rules/",
@@ -116,9 +121,6 @@
     ".mcp.json.example"
   ],
   "dependencies": {
-    "@forge/flow": "0.1.0-beta.6",
-    "@forge/memory": "0.1.0-beta.6",
-    "@forge/contracts": "0.1.0-beta.6",
     "@babel/parser": "^8.0.0",
     "cross-spawn": "^7.0.6",
     "fastest-levenshtein": "^1.0.16",

package/scripts/check-forge-token.js

@@ -1,97 +1,115 @@
 'use strict';
 
-const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
 const crypto = require('node:crypto');
+const fs = require('node:fs');
 const path = require('node:path');
+const { _pushProof } = require('../lib/validation-receipt');
+const { defaultGetProcessIdentity } = require('./process-tree');
 
-const TOKEN_FILENAME = '.forge-push-token';
-const MAX_AGE_MS = 30000; // 30 seconds
+const NONCE_ENV_VAR = 'FORGE_PUSH_NONCE';
+const NONCE_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
-/**
- * Get the absolute path to the token file.
- *
- * @param {string} projectRoot - Absolute path to project root
- * @returns {string} Token file path
- */
-function tokenPath(projectRoot) {
-  return path.join(projectRoot, TOKEN_FILENAME);
+function git(projectRoot, args, deps = {}) {
+  return (deps.execFileSync || execFileSync)('git', args, {
+    cwd: projectRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
 }
 
-/**
- * Write a one-time nonce token to disk.
- * Called by `forge push` right before `git push` so lefthook hooks
- * can detect that checks already passed and skip re-running them.
- *
- * @param {string} projectRoot - Absolute path to project root
- * @returns {{nonce: string, timestamp: number}} The written token data
- */
-function write(projectRoot) {
-  const data = {
-    nonce: crypto.randomUUID(),
-    timestamp: Date.now(),
-  };
-  fs.writeFileSync(tokenPath(projectRoot), JSON.stringify(data), 'utf-8');
-  return data;
+function resolveProofPath(projectRoot, nonce, deps = {}) {
+  if (!NONCE_PATTERN.test(nonce || '')) throw new Error('invalid push proof nonce');
+  if (deps.resolvePushProofPath) return path.resolve(deps.resolvePushProofPath(projectRoot, nonce));
+  const root = path.resolve(git(projectRoot, ['rev-parse', '--show-toplevel'], deps));
+  return path.resolve(root, git(root, ['rev-parse', '--git-path', `forge/push-tokens/${nonce}.json`], deps));
+}
+
+function writeAtomic(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporary = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, content, { flag: 'wx', mode: 0o600 });
+    fs.renameSync(temporary, filePath);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
 }
 
 /**
- * Check if a valid (fresh, well-formed) forge push token exists.
- * Does NOT delete the token — use `consume()` for one-time validation.
+ * Write signed authority for one active `forge push` invocation.
  *
- * @param {string} projectRoot - Absolute path to project root
- * @returns {boolean} True if a valid, fresh token exists
+ * @param {string} projectRoot
+ * @param {object} options
+ * @returns {{nonce: string}}
  */
-function isValid(projectRoot) {
+function write(projectRoot, options = {}) {
+  const nonce = (options.randomUUID || crypto.randomUUID)();
+  const ownerPid = options.processPid || process.pid;
+  const getProcessIdentity = options.getProcessIdentity || defaultGetProcessIdentity;
+  const ownerIdentity = getProcessIdentity(ownerPid);
+  if (!ownerIdentity) throw new Error('push proof owner identity unavailable');
+  const proof = _pushProof.create(projectRoot, options.snapshot, {
+    nonce,
+    mode: options.mode,
+    gates: options.gates,
+    owner: { pid: ownerPid, identity: ownerIdentity },
+    receiptIdentity: options.receiptIdentity,
+  }, options);
+  writeAtomic(resolveProofPath(projectRoot, nonce, options), JSON.stringify(proof));
+  return { nonce };
+}
+
+function validate(projectRoot, options = {}) {
   try {
-    const raw = fs.readFileSync(tokenPath(projectRoot), 'utf-8');
-    const content = JSON.parse(raw);
-    if (!content.nonce || typeof content.timestamp !== 'number') {
-      return false;
+    const env = options.env || process.env;
+    const nonce = env[NONCE_ENV_VAR];
+    if (!NONCE_PATTERN.test(nonce || '')) return { valid: false };
+    const proof = JSON.parse(fs.readFileSync(resolveProofPath(projectRoot, nonce, options), 'utf8'));
+    const verified = _pushProof.verify(projectRoot, proof, { nonce, env }, options);
+    if (!verified.valid) return verified;
+    const getProcessIdentity = options.getProcessIdentity || defaultGetProcessIdentity;
+    const owner = verified.payload.owner;
+    if (!owner || getProcessIdentity(owner.pid) !== owner.identity) {
+      return { valid: false, reason: 'owner' };
     }
-    const age = Date.now() - content.timestamp;
-    return age < MAX_AGE_MS;
-  } catch (_err) {
-    return false;
+    return verified;
+  } catch {
+    return { valid: false };
   }
 }
 
 /**
- * Validate and delete the token in one atomic operation (one-time use).
- * Always attempts to delete the file, even if the token is stale or invalid.
- *
- * @param {string} projectRoot - Absolute path to project root
- * @returns {boolean} True if the token was valid before deletion
+ * Check signed authority without consuming it so all three hook predicates can read it.
  */
-function consume(projectRoot) {
-  const tp = tokenPath(projectRoot);
-  try {
-    const raw = fs.readFileSync(tp, 'utf-8');
-    // Always delete after reading — whether valid or not
-    try { fs.unlinkSync(tp); } catch (_e) { /* already gone */ }
+function isValid(projectRoot, options = {}) {
+  return validate(projectRoot, options).valid === true;
+}
 
-    const content = JSON.parse(raw);
-    if (!content.nonce || typeof content.timestamp !== 'number') {
-      return false;
-    }
-    const age = Date.now() - content.timestamp;
-    return age < MAX_AGE_MS;
-  } catch (_err) {
-    // File doesn't exist or isn't readable — try cleanup anyway
-    try { fs.unlinkSync(tp); } catch (_e) { /* nothing to clean */ }
+/**
+ * Revoke only the proof named by this invocation's nonce.
+ */
+function consume(projectRoot, options = {}) {
+  try {
+    const nonce = options.nonce || (options.env || process.env)[NONCE_ENV_VAR];
+    fs.unlinkSync(resolveProofPath(projectRoot, nonce, options));
+    return true;
+  } catch {
     return false;
   }
 }
 
-module.exports = { write, isValid, consume };
+module.exports = {
+  write,
+  isValid,
+  consume,
+  _internal: { NONCE_ENV_VAR, resolveProofPath, validate },
+};
 
-// When run directly as a script (e.g., from lefthook skip check):
-// Exit 0 = token valid (skip hooks), Exit 1 = run hooks normally.
-// Uses isValid() (non-destructive) so multiple lefthook commands can
-// each check the same token. The token expires after 30s automatically.
 if (require.main === module) {
-  const projectRoot = process.cwd();
-  if (isValid(projectRoot)) {
-    console.log('forge push token valid — skipping pre-push hooks');
+  const result = validate(process.cwd());
+  if (result.valid) {
+    console.log(`forge push ${result.payload.mode} authorization valid — skipping pre-push hooks`);
     process.exit(0);
   }
   process.exit(1);

package/scripts/gen-embedded-assets.mjs

@@ -25,6 +25,8 @@ const { ASSET_ROOTS } = pkgRoot;
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..');
 const OUT_FILE = path.join(REPO_ROOT, 'lib', 'embedded-assets.generated.mjs');
+const STAGING_DIR_NAME = 'embedded-assets.generated-assets';
+const STAGING_DIR = path.join(REPO_ROOT, 'lib', STAGING_DIR_NAME);
 
 // Deterministic, locale-INDEPENDENT codepoint comparator. Locale-default sort would
 // diverge by machine locale and produce different embed bytes across the step-3
@@ -83,14 +85,37 @@ export function assetFingerprint(repoRoot = REPO_ROOT, files = collectAssetFiles
   return h.digest('hex');
 }
 
-function render(files, fingerprint) {
+/**
+ * Copy source assets to deterministic non-code paths before Bun imports them as
+ * raw files. This keeps a JavaScript source path from also becoming a raw asset
+ * module in the same compiled graph.
+ */
+export function stageAssetFiles(repoRoot, files, stagingDir = path.join(repoRoot, 'lib', STAGING_DIR_NAME)) {
+  const expectedDir = path.resolve(repoRoot, 'lib', STAGING_DIR_NAME);
+  const resolvedDir = path.resolve(stagingDir);
+  if (resolvedDir !== expectedDir) {
+    throw new Error(`Refusing to replace unexpected embedded-asset staging path: ${resolvedDir}`);
+  }
+  fs.rmSync(resolvedDir, { recursive: true, force: true });
+  fs.mkdirSync(resolvedDir, { recursive: true });
+  return files.map((rel, index) => {
+    const filename = `a${index}.asset`;
+    fs.copyFileSync(
+      path.join(repoRoot, ...rel.split('/')),
+      path.join(resolvedDir, filename),
+    );
+    return { rel, filename };
+  });
+}
+
+export function renderManifest(stagedFiles, fingerprint) {
   const imports = [];
   const entries = [];
   const execEntries = [];
-  files.forEach((rel, i) => {
+  stagedFiles.forEach(({ rel, filename }, i) => {
     const ident = `a${i}`;
-    // Specifier is relative to lib/embedded-assets.generated.mjs → prefix `../`.
-    const specifier = JSON.stringify(`../${rel}`);
+    // Specifier is relative to the generated manifest in lib/.
+    const specifier = JSON.stringify(`./${STAGING_DIR_NAME}/${filename}`);
     imports.push(`import ${ident} from ${specifier} with { type: "file" };`);
     entries.push(`  ${JSON.stringify(rel)}: ${ident},`);
     if (isExecutableAsset(rel)) execEntries.push(`  ${JSON.stringify(rel)},`);
@@ -116,8 +141,9 @@ function render(files, fingerprint) {
 function main() {
   const files = collectAssetFiles();
   const fingerprint = assetFingerprint(REPO_ROOT, files);
+  const stagedFiles = stageAssetFiles(REPO_ROOT, files, STAGING_DIR);
   fs.mkdirSync(path.dirname(OUT_FILE), { recursive: true });
-  fs.writeFileSync(OUT_FILE, render(files, fingerprint), 'utf8');
+  fs.writeFileSync(OUT_FILE, renderManifest(stagedFiles, fingerprint), 'utf8');
   const execCount = files.filter(isExecutableAsset).length;
   console.log(
     `Embedded ${files.length} asset file(s) (${execCount} executable), fingerprint ${fingerprint.slice(0, 16)} → ${path.relative(REPO_ROOT, OUT_FILE)}`

package/scripts/test-full-suite.js

@@ -64,13 +64,24 @@ function parseArgs(argv) {
     const next = argv[index + 1];
 
     if (current === '--label-prefix') args.labelPrefix = next;
-    if (current === '--shards') args.shards = Number.parseInt(next, 10);
+    if (current === '--shards') args.shards = parseResourceBudget(next);
     if (current === '--timeout') args.timeoutMs = parseTimeoutMs(next);
   }
 
   return args;
 }
 
+function parseResourceBudget(value) {
+  if (!/^[1-9]\d*$/.test(String(value ?? ''))) {
+    throw new Error('--shards must be a positive integer resource budget');
+  }
+  const budget = Number(value);
+  if (!Number.isSafeInteger(budget)) {
+    throw new Error('--shards must be a positive integer resource budget');
+  }
+  return budget;
+}
+
 function parseTimeoutMs(value) {
   const timeoutMs = Number(value);
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
@@ -479,12 +490,21 @@ function buildResourceLanePlan(allTests, shardTotal, durationMap = new Map(), op
 // A subprocess-lane worker owns two OS processes on Windows: the shard's own bun
 // runtime plus the bun.exe grandchild its tests spawn. Counting such a worker as
 // one budget unit oversubscribes small runners (3 workers is ~6 processes on 4
-// vCPU), so weight the grant by real process cost instead of by worker count.
+// vCPU), so weight the grant by the declared worker cost instead of worker count.
 function laneWorkerCost(laneName, platform = process.platform) {
   if (platform !== 'win32') return 1;
   return laneName === 'unit' ? 1 : 2;
 }
 
+function minimumResourceBudget(lanes, platform = process.platform) {
+  return lanes
+    .filter((lane) => lane.shards.length > 0)
+    .reduce(
+      (minimum, lane) => Math.max(minimum, laneWorkerCost(lane.name, platform)),
+      0,
+    );
+}
+
 function computeLaneGrants(lanes, options = {}) {
   const platform = options.platform || process.platform;
   const workerBudget = Number.isInteger(options.workerBudget) && options.workerBudget > 0
@@ -492,6 +512,7 @@ function computeLaneGrants(lanes, options = {}) {
     : null;
   const sharedLanes = lanes.filter((lane) => lane.name !== 'exclusive');
   const overlapsSubprocess = sharedLanes.some((lane) => lane.name === 'subprocess');
+  const deferWindowsUnitLane = platform === 'win32' && overlapsSubprocess;
   const grants = new Map();
   for (const lane of lanes) {
     grants.set(lane, {
@@ -503,13 +524,29 @@ function computeLaneGrants(lanes, options = {}) {
   }
   if (workerBudget === null) {
     for (const lane of sharedLanes) {
-      // One unit worker fills otherwise-idle CPU without recreating broad process pressure.
-      grants.get(lane).granted = overlapsSubprocess && lane.name === 'unit' ? 1 : lane.concurrency;
+      const entry = grants.get(lane);
+      if (deferWindowsUnitLane && lane.name === 'unit') {
+        entry.granted = 0;
+        entry.deferred = true;
+        entry.deferredConcurrency = lane.concurrency;
+      } else {
+        entry.granted = overlapsSubprocess && lane.name === 'unit' ? 1 : lane.concurrency;
+      }
     }
     return grants;
   }
-  // An explicit shard count is an operator-imposed cap on total concurrent
-  // children; reserve the budget for heavier subprocess workers first and
+  const minimumBudget = minimumResourceBudget(lanes, platform);
+  if (workerBudget < minimumBudget) {
+    throw new Error(
+      `Full suite resource budget: requested=${workerBudget} minimum=${minimumBudget} outcome=rejected`,
+    );
+  }
+  for (const lane of lanes.filter((candidate) => candidate.name === 'exclusive')) {
+    const entry = grants.get(lane);
+    entry.granted = Math.min(lane.concurrency, Math.floor(workerBudget / entry.cost));
+  }
+  // An explicit shard count is an operator-imposed weighted worker budget;
+  // reserve it for heavier subprocess workers first and
   // defer leftover lanes until capacity frees instead of exceeding it.
   const ordered = [...sharedLanes].sort(
     (left, right) => (left.name === 'subprocess' ? 0 : 1) - (right.name === 'subprocess' ? 0 : 1),
@@ -517,7 +554,9 @@ function computeLaneGrants(lanes, options = {}) {
   let reservedCost = 0;
   for (const [position, lane] of ordered.entries()) {
     const entry = grants.get(lane);
-    const want = overlapsSubprocess && lane.name === 'unit' ? 1 : lane.concurrency;
+    const want = overlapsSubprocess && lane.name === 'unit'
+      ? (deferWindowsUnitLane ? 0 : 1)
+      : lane.concurrency;
     const affordable = Math.floor(Math.max(0, workerBudget - reservedCost) / entry.cost);
     // The strongest lane always keeps one worker so the suite can never stall at zero.
     const granted = position === 0
@@ -587,7 +626,7 @@ async function runLaneSchedule(lanes, execute, cancel = () => {}, options = {})
   if (deferredFailure) throw deferredFailure.reason;
 
   for (const lane of lanes.filter((candidate) => candidate.name === 'exclusive')) {
-    resultsByLane.set(lane, await runLane(lane));
+    resultsByLane.set(lane, await runLane(lane, grants.get(lane).granted));
   }
   return lanes.flatMap((lane) => {
     const laneResults = resultsByLane.get(lane);
@@ -920,10 +959,11 @@ async function runFullSuiteInParallel(args = {}, deps = {}) {
 
   try {
     const allTests = deps.allTests || listAllFullSuiteTests();
-    const shardTotal = Number.isInteger(args.shards) && args.shards > 0
-      ? args.shards
-      : getDefaultShardCount(deps.cpuCount);
-    const subprocessShardTotal = Number.isInteger(args.shards) && args.shards > 0
+    const requestedResourceBudget = args.shards === null || args.shards === undefined
+      ? null
+      : parseResourceBudget(args.shards);
+    const shardTotal = requestedResourceBudget ?? getDefaultShardCount(deps.cpuCount);
+    const subprocessShardTotal = requestedResourceBudget !== null
       ? shardTotal
       : Math.max(6, shardTotal);
     const profile = deps.profile || readNewestProfile(reportDir);
@@ -940,6 +980,21 @@ async function runFullSuiteInParallel(args = {}, deps = {}) {
       subprocessShardTotal,
     });
     const shardSpecs = lanePlan.flatMap((lane) => lane.shards);
+    const minimumBudget = minimumResourceBudget(lanePlan, platform);
+    const effectiveResourceBudget = requestedResourceBudget === null
+      ? Math.max(shardTotal, minimumBudget)
+      : shardTotal;
+    if (requestedResourceBudget !== null && requestedResourceBudget < minimumBudget) {
+      console.log(
+        `Full suite resource budget: requested=${requestedResourceBudget} minimum=${minimumBudget} outcome=rejected`,
+      );
+    }
+    const laneGrants = computeLaneGrants(lanePlan, {
+      platform,
+      workerBudget: effectiveResourceBudget,
+    });
+
+    console.log(`Full suite resource budget: requested=${requestedResourceBudget ?? 'default'} effective=${effectiveResourceBudget}`);
 
     if (shardSpecs.length === 0) {
       const exitCode = signal ? signalExitCode(signal) : 1;
@@ -953,12 +1008,11 @@ async function runFullSuiteInParallel(args = {}, deps = {}) {
     const runReportDir = fs.mkdtempSync(path.join(reportDir, 'full-suite-'));
 
     console.log(`Running local full suite in ${shardSpecs.length} shard(s)`);
-    const laneGrants = computeLaneGrants(lanePlan, { platform, workerBudget: shardTotal });
     for (const lane of lanePlan) {
       const grant = laneGrants.get(lane);
       const granted = grant.deferred ? grant.deferredConcurrency : grant.granted;
       const files = lane.shards.reduce((total, shard) => total + shard.files.length, 0);
-      console.log(`Resource lane ${lane.name}: files=${files} shards=${lane.shards.length} concurrency=${granted} (nominal=${lane.concurrency} cost=${grant.cost} budget=${shardTotal}${grant.deferred ? ' deferred' : ''})`);
+      console.log(`Resource lane ${lane.name}: files=${files} shards=${lane.shards.length} concurrency=${granted} (nominal=${lane.concurrency} cost=${grant.cost} budget=${effectiveResourceBudget}${grant.deferred ? ' deferred' : ''})`);
     }
     const childEnv = stripFullSuiteChildEnv(
       typeof processTree.envFor === 'function' ? processTree.envFor(env) : env,
@@ -992,7 +1046,7 @@ async function runFullSuiteInParallel(args = {}, deps = {}) {
       }, {
         grants: laneGrants,
         platform,
-        workerBudget: shardTotal,
+        workerBudget: effectiveResourceBudget,
       });
     } catch (error) {
       console.error('Full suite shard execution failed:', error);

package/scripts/test.js

@@ -62,9 +62,17 @@ const KNOWN_TARGETABLE_FILES = new Set([
   'lib/kernel/schema.js',
   'lib/kernel/migrations.js',
   'lib/kernel/sqlite-driver.js',
+  'lib/test-workflow.js',
+  'lib/workflow-templates/test.yml',
   'lib/commands/shepherd.js',
   'lib/commands/github.js',
+  'bin/forge-gh-proxy.js',
+  'bin/forge-github-credential.js',
   'lib/github-context.js',
+  'lib/github-credential.js',
+  'lib/github-router.js',
+  'lib/gh-proxy.js',
+  'lib/native-gh.js',
   'lib/commands/_registry.js',
   'lib/commands/pr.js',
   'lib/commands/ship.js',
@@ -649,12 +657,14 @@ module.exports = {
   OBSERVED_FULL_SUITE_RUNTIME_MS,
   QUICK_LANE_ENV_VAR,
   QUICK_LANE_VALUE,
+  TIMEOUT_EXIT_CODE,
   buildTestExecutionPlan,
   classifyPushTests,
   detectPackageManager,
   isQuickPushLane,
   resolveCommandTimeoutMs,
   resolveFullSuiteTimeoutMs,
+  runCommand,
   runLocalValidationTests,
   runPrePushTests,
   runTestExecutionPlan,