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

package/lib/commands/serve.js

@@ -31,6 +31,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawn } = require('node:child_process');
+const { githubWorkerEnvironment } = require('../pr-monitor/watch-lifecycle');
 
 // Shared-machine hardening (single-instance lock, owner-only perms + audit,
 // hash-chained mutation journal). No dependency on serve.js, so a top-level
@@ -237,12 +238,21 @@ async function routeMutation(verb, args, projectRoot, deps = {}) {
 // Snapshot (GET /data.json) — regenerate on demand, debounced.
 // ---------------------------------------------------------------------------
 
-function defaultGenerate(projectRoot, dashboardDir) {
+function defaultGenerate(projectRoot, dashboardDir, deps = {}) {
   return new Promise((resolve, reject) => {
     const script = path.join(dashboardDir, 'generate-snapshot.mjs');
-    const child = spawn(process.execPath, [script], { cwd: projectRoot, stdio: 'ignore', windowsHide: true });
+    const env = githubWorkerEnvironment(projectRoot, deps);
+    let child;
+    try {
+      child = (deps.spawn || spawn)(process.execPath, [script], {
+        cwd: projectRoot, stdio: 'ignore', windowsHide: true, ...(env ? { env } : {}),
+      });
+    } catch {
+      reject(new Error('snapshot generation failed'));
+      return;
+    }
     const timer = setTimeout(() => { child.kill(); reject(new Error('snapshot generation timed out')); }, GEN_TIMEOUT_MS);
-    child.on('error', (err) => { clearTimeout(timer); reject(err); });
+    child.on('error', () => { clearTimeout(timer); reject(new Error('snapshot generation failed')); });
     child.on('exit', (code) => {
       clearTimeout(timer);
       if (code === 0) resolve();
@@ -409,7 +419,7 @@ function buildContext(projectRoot, dashboardDir, token, deps = {}) {
       buffer: null,
       lastGen: 0,
       inFlight: null,
-      generate: deps.generate || defaultGenerate,
+      generate: deps.generate || ((root, dir) => defaultGenerate(root, dir, deps)),
     },
   };
 }
@@ -438,13 +448,16 @@ function browserOpener() {
   return { file: '/usr/bin/xdg-open', args: [] };
 }
 
-function openBrowser(url) {
+function openBrowser(url, projectRoot = process.cwd(), deps = {}) {
   try {
     const { file, args } = browserOpener();
+    const env = githubWorkerEnvironment(projectRoot, deps);
     // windowsHide keeps this detached opener from flashing a console window on
     // Windows (Node defaults windowsHide to false); background/detached spawns
     // must stay silent (issue 931e7924).
-    const child = spawn(file, [...args, url], { detached: true, stdio: 'ignore', windowsHide: true });
+    const child = (deps.spawn || spawn)(file, [...args, url], {
+      detached: true, stdio: 'ignore', windowsHide: true, ...(env ? { env } : {}),
+    });
     // spawn() failures (e.g. the opener binary is missing) surface ASYNChronously
     // as an 'error' event, NOT via the try/catch — an unhandled one would crash
     // `forge serve`. Opening a browser is best-effort; swallow it (URL is printed).
@@ -480,7 +493,7 @@ function announceServe(server, token, options, resolve) {
     `\nforge serve — interactive dashboard (loopback only)\n  ${url}\n`
     + '  Token dies with this process. Press Ctrl-C to stop.\n\n',
   );
-  if (options.open) openBrowser(url);
+  if (options.open) openBrowser(url, options.projectRoot, options.deps);
   installServeShutdown(server, resolve, options.onClose);
 }
 
@@ -535,7 +548,7 @@ function verifyJournalAtStartup(projectRoot, warn = (m) => process.stderr.write(
   return result;
 }
 
-async function handler(args, flags = {}, projectRoot = process.cwd(), _opts = {}) {
+async function handler(args, flags = {}, projectRoot = process.cwd(), opts = {}) {
   const { port, open } = parseServeArgs(args, flags);
   const dashboardDir = path.join(projectRoot, 'web', 'dashboard');
   if (!fs.existsSync(path.join(dashboardDir, 'index.html'))) {
@@ -558,10 +571,12 @@ async function handler(args, flags = {}, projectRoot = process.cwd(), _opts = {}
   verifyJournalAtStartup(projectRoot);
 
   const token = mintToken();
-  const ctx = buildContext(projectRoot, dashboardDir, token);
+  const ctx = buildContext(projectRoot, dashboardDir, token, opts);
   const server = createServeServer(ctx);
   return startListening(server, port, token, {
     open,
+    projectRoot,
+    deps: opts,
     onClose: () => security.releaseLock(projectRoot),
   });
 }
@@ -575,6 +590,8 @@ module.exports = {
   routeMutation,
   parseServeArgs,
   buildContext,
+  defaultGenerate,
+  openBrowser,
   createServeServer,
   verifyToken,
   isLoopbackRequest,

package/lib/commands/setup.js

@@ -13,7 +13,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
-const { execSync } = require('node:child_process');
+const { execFileSync, execSync } = require('node:child_process');
 
 // Compute packageDir relative to this file (lib/commands/setup.js -> project root).
 // packageDir stays a runtime value for asset copying; requires use static
@@ -91,6 +91,10 @@ const initCommand = require('./init');
 const fileUtils = require('../file-utils');
 const detectionUtils = require('../detection-utils');
 const { detectHusky, migrateHusky } = require('../husky-migration');
+const {
+  issueGeneratedHarnessClaudeAuthorization,
+  completeGeneratedHarnessClaudeAuthorization,
+} = require('../protected-state-authority');
 
 // --- Module-level state (deferred from ForgeContext migration) ---
 // Follow-up tracked in forge-vi7v: migrate setup state to a ForgeContext instance passed via handler args.
@@ -163,6 +167,92 @@ function safeExec(cmd, opts = {}) {
   }
 }
 
+/**
+ * Resolve the current source revision without passing Git arguments through a shell.
+ * @param {string} cwd - Repository working directory
+ * @param {Function} commandRunner - execFileSync-compatible runner for tests
+ * @returns {string} Full source HEAD, or empty when Git cannot resolve it
+ */
+function resolveCurrentSourceHead(cwd = projectRoot, commandRunner = execFileSync) {
+  try {
+    return commandRunner('git', ['rev-parse', '--verify', 'HEAD^{commit}'], {
+      cwd,
+      stdio: 'pipe',
+    }).toString().trim();
+  } catch (_e) { // NOSONAR — fail closed when the source revision is unavailable
+    return '';
+  }
+}
+
+/**
+ * Normalize Git's Windows checkout line endings before authorizing the exact
+ * root CLAUDE.md pointer bytes.
+ * @param {Buffer|string} content - Existing CLAUDE.md bytes
+ * @returns {Buffer} LF-normalized content
+ */
+function normalizeClaudePointerContent(content) {
+  return Buffer.from(String(content || '').replace(/\r\n/g, '\n'));
+}
+
+function readCleanClaudePointerWorktreeContent(cwd, commandRunner) {
+	const tempIndexDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-claude-index-'));
+	const tempIndex = path.join(tempIndexDir, 'index');
+	const env = { ...process.env, GIT_INDEX_FILE: tempIndex };
+	try {
+		commandRunner('git', ['read-tree', 'HEAD'], {
+			cwd,
+			env,
+			stdio: 'pipe',
+		});
+		commandRunner('git', ['add', '--', 'CLAUDE.md'], {
+			cwd,
+			env,
+			stdio: 'pipe',
+		});
+		return commandRunner('git', ['show', ':CLAUDE.md'], {
+			cwd,
+			env,
+			encoding: null,
+			stdio: 'pipe',
+		});
+	} finally {
+		fs.rmSync(tempIndexDir, { recursive: true, force: true });
+	}
+}
+
+/**
+ * Read the exact staged CLAUDE.md bytes that the protected-state hook will hash.
+ * @param {string} cwd - Repository working directory
+ * @param {Function} commandRunner - execFileSync-compatible runner for tests
+ * @returns {Buffer} Staged bytes, or the worktree bytes when the file is untracked
+ */
+function readStagedClaudePointerContent(cwd = projectRoot, commandRunner = execFileSync) {
+	try {
+		const stagedContent = commandRunner('git', ['show', ':CLAUDE.md'], {
+			cwd,
+			encoding: null,
+			stdio: 'pipe',
+		});
+		try {
+			return readCleanClaudePointerWorktreeContent(cwd, commandRunner);
+		} catch (_worktreeError) {
+			return stagedContent;
+		}
+	} catch (showError) {
+		try {
+			commandRunner('git', ['ls-files', '--error-unmatch', '--', 'CLAUDE.md'], {
+				cwd,
+				encoding: 'utf8',
+				stdio: 'pipe',
+			});
+			throw showError;
+		} catch (trackedError) {
+			if (trackedError?.status !== 1) throw showError;
+		}
+		return readCleanClaudePointerWorktreeContent(cwd, commandRunner);
+	}
+}
+
 /**
  * Detect package manager
  */
@@ -1649,6 +1739,13 @@ function ensureDirWithNote(dir, purpose) { // eslint-disable-line no-unused-vars
 
 // Setup core documentation and directories
 function setupCoreDocs() {
+  // Review skills reference this root contract in every installed repository.
+  // It is a consumer-owned extension point after creation, so setup never overwrites it.
+  const codingStandardsDest = path.join(projectRoot, 'CODING_STANDARDS.md');
+  if (!fs.existsSync(codingStandardsDest)) {
+    copyFile(path.join(getPackageRoot(packageDir), 'CODING_STANDARDS.md'), 'CODING_STANDARDS.md');
+  }
+
   // docs/planning/ and docs/research/ are created lazily on first use
   // by /plan Phase 1 and Phase 2 respectively, via ensureDirWithNote().
   // TEMPLATE.md and PROGRESS.md are also deferred to first use.
@@ -2053,7 +2150,7 @@ function setupCursorHooksConfig() {
 
 // Helper: Create agent link file
 // When symlinkOnly is true (--symlink flag), skip copy fallback
-function createAgentLinkFile(agent, symlinkOnly = false) {
+async function createAgentLinkFile(agent, symlinkOnly = false) {
   if (!shouldLinkAgentsMd(agent)) return;
 
   const result = createSymlinkOrCopy('AGENTS.md', agent.linkFile, { symlinkOnly });
@@ -2061,6 +2158,33 @@ function createAgentLinkFile(agent, symlinkOnly = false) {
     const action = result === 'linked' ? 'Linked' : result === 'copied' ? 'Copied' : 'Preserved import';
     console.log(`  ${action}: ${agent.linkFile}`);
   }
+  if (agent.linkFile !== 'CLAUDE.md' || result !== 'existing-import') return;
+
+  try {
+    const sourceHead = resolveCurrentSourceHead();
+    const content = readStagedClaudePointerContent();
+    const actor = process.env.FORGE_PROTECTED_STATE_ACTOR || process.env.FORGE_ACTOR || process.env.USER || process.env.USERNAME || 'unknown';
+    const authorization = await issueGeneratedHarnessClaudeAuthorization(projectRoot, {
+      actor,
+      content,
+      sourceHead,
+    });
+    if (!authorization.success) {
+      console.warn(`  Warning: Could not authorize existing CLAUDE.md import: ${authorization.error}`);
+      return;
+    }
+    const completion = await completeGeneratedHarnessClaudeAuthorization(projectRoot, {
+      actor,
+      capabilityId: authorization.capabilityId,
+      content,
+      sourceHead,
+    });
+    if (!completion.success) {
+      console.warn(`  Warning: Could not complete CLAUDE.md import authorization: ${completion.error}`);
+    }
+  } catch (error) {
+    console.warn(`  Warning: Could not record CLAUDE.md import authorization: ${error.message}`);
+  }
 }
 
 // Setup specific agent
@@ -2117,7 +2241,7 @@ async function setupAgent(agentKey, skipFiles = {}, options = {}) {
   }
 
   // Create link file (SYMLINK_ONLY = --symlink flag disables copy fallback)
-  createAgentLinkFile(agent, SYMLINK_ONLY);
+  await createAgentLinkFile(agent, SYMLINK_ONLY);
 }
 
 
@@ -3927,8 +4051,9 @@ function dryRunSetup(agents, options = {}) { // NOSONAR — Extracted as-is from
     }
   }
 
-  // AGENTS.md
+  // Root policy files
   addFileAction('AGENTS.md', 'Copy workflow documentation');
+  addFileAction('CODING_STANDARDS.md', 'Install Forge coding standards');
 
   // Per-agent planned actions
   for (const agentKey of agents) {
@@ -4526,6 +4651,9 @@ module.exports = {
   repairRuntimeReadiness,
   _showBanner: showBanner,
   backupAndRemoveLegacyCursorRules,
+  resolveCurrentSourceHead,
+  normalizeClaudePointerContent,
+  readStagedClaudePointerContent,
 
   // State accessors for testing
   _getState: () => ({ projectRoot, FORCE_MODE, VERBOSE_MODE, NON_INTERACTIVE, SYMLINK_ONLY, PKG_MANAGER }),