deepflow 0.1.111 → 0.1.113

package/bin/install.js

@@ -9,6 +9,18 @@ const path = require('path');
 const os = require('os');
 const readline = require('readline');
 const { execFileSync } = require('child_process');
+const { scanHookEvents, removeDeepflowHooks } = require('../hooks/lib/installer-utils');
+
+function atomicWriteFileSync(targetPath, data) {
+  const tmpPath = targetPath + '.tmp';
+  try {
+    fs.writeFileSync(tmpPath, data);
+    fs.renameSync(tmpPath, targetPath);
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    throw err;
+  }
+}
 
 // Legacy subcommand: `deepflow auto` is now `/df:auto` inside Claude Code
 if (process.argv[2] === 'auto') {
@@ -35,23 +47,6 @@ const GLOBAL_DIR = path.join(os.homedir(), '.claude');
 const PROJECT_DIR = path.join(process.cwd(), '.claude');
 const PACKAGE_DIR = path.resolve(__dirname, '..');
 
-/**
- * Atomically write data to targetPath using a write-to-temp + rename pattern.
- * If the write fails, the original file is left untouched and the temp file is
- * cleaned up. Temp file is created in the same directory as the target so the
- * rename is within the same filesystem (atomic on POSIX).
- */
-function atomicWriteFileSync(targetPath, data) {
-  const tmpPath = targetPath + '.tmp';
-  try {
-    fs.writeFileSync(tmpPath, data);
-    fs.renameSync(tmpPath, targetPath);
-  } catch (err) {
-    try { fs.unlinkSync(tmpPath); } catch (_) {}
-    throw err;
-  }
-}
-
 function updateGlobalPackage() {
   const currentVersion = require(path.join(PACKAGE_DIR, 'package.json')).version;
   try {
@@ -297,77 +292,46 @@ function copyDir(src, dest) {
   }
 }
 
-// Valid hook events (settings.hooks keys + special "statusLine")
-const VALID_HOOK_EVENTS = new Set([
-  'SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse', 'SubagentStop', 'statusLine'
-]);
-
 /**
- * Scan hook source files for @hook-event tags. Returns:
- *   { eventMap: Map<event, [filename, ...]>, untagged: [filename, ...] }
+ * Returns true if settings.json contains any hook commands that reference a
+ * dashboard-owned hook file (identified by @hook-owner: dashboard in its source).
+ * Checks both settings.hooks.* entries and settings.statusLine.
  */
-function scanHookEvents(hooksSourceDir) {
-  const eventMap = new Map();  // event → [filenames]
-  const untagged = [];
+function detectDashboardHooks(settings, claudeDir) {
+  const hooksInstallDir = path.join(claudeDir, 'hooks');
+  if (!fs.existsSync(hooksInstallDir)) return false;
 
-  if (!fs.existsSync(hooksSourceDir)) return { eventMap, untagged };
-
-  for (const file of fs.readdirSync(hooksSourceDir)) {
-    if (!file.endsWith('.js') || file.endsWith('.test.js')) continue;
-
-    const content = fs.readFileSync(path.join(hooksSourceDir, file), 'utf8');
-    const firstLines = content.split('\n').slice(0, 10).join('\n');
-    const match = firstLines.match(/\/\/\s*@hook-event:\s*(.+)/);
-
-    if (!match) {
-      untagged.push(file);
-      continue;
-    }
-
-    const events = match[1].split(',').map(e => e.trim()).filter(Boolean);
-    let hasValidEvent = false;
-
-    for (const event of events) {
-      if (!VALID_HOOK_EVENTS.has(event)) {
-        console.log(`  ${c.yellow}!${c.reset} Warning: unknown event "${event}" in ${file} — skipped`);
-        continue;
+  // Collect all command strings currently wired in settings
+  const wiredCommands = [];
+  if (settings.hooks) {
+    for (const entries of Object.values(settings.hooks)) {
+      for (const hook of entries) {
+        const cmd = hook.hooks?.[0]?.command;
+        if (cmd) wiredCommands.push(cmd);
       }
-      hasValidEvent = true;
-      if (!eventMap.has(event)) eventMap.set(event, []);
-      eventMap.get(event).push(file);
-    }
-
-    if (!hasValidEvent) {
-      untagged.push(file);
     }
   }
-
-  return { eventMap, untagged };
-}
-
-/**
- * Remove all deepflow hook entries (commands containing /hooks/df-) from settings.
- * Preserves non-deepflow hooks.
- */
-function removeDeepflowHooks(settings) {
-  const isDeepflow = (hook) => {
-    const cmd = hook.hooks?.[0]?.command || '';
-    return cmd.includes('/hooks/df-');
-  };
-
-  // Clean settings.hooks.*
-  if (settings.hooks) {
-    for (const event of Object.keys(settings.hooks)) {
-      settings.hooks[event] = settings.hooks[event].filter(h => !isDeepflow(h));
-      if (settings.hooks[event].length === 0) delete settings.hooks[event];
-    }
-    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  if (settings.statusLine?.command) {
+    wiredCommands.push(settings.statusLine.command);
   }
 
-  // Clean settings.statusLine if it's a deepflow hook
-  if (settings.statusLine?.command && settings.statusLine.command.includes('/hooks/df-')) {
-    delete settings.statusLine;
+  // For each wired command, resolve the hook filename and check its @hook-owner
+  for (const cmd of wiredCommands) {
+    // Commands look like: node "/path/to/.claude/hooks/df-foo.js"
+    const match = cmd.match(/["']?([^"'\s]+\.js)["']?\s*$/);
+    if (!match) continue;
+    const hookPath = match[1];
+    if (!fs.existsSync(hookPath)) continue;
+    try {
+      const content = fs.readFileSync(hookPath, 'utf8');
+      const firstLines = content.split('\n').slice(0, 10).join('\n');
+      const ownerMatch = firstLines.match(/\/\/\s*@hook-owner:\s*(.+)/);
+      if (ownerMatch && ownerMatch[1].trim() === 'dashboard') return true;
+    } catch (_) {
+      // Skip unreadable files
+    }
   }
+  return false;
 }
 
 async function configureHooks(claudeDir) {
@@ -393,8 +357,8 @@ async function configureHooks(claudeDir) {
   configurePermissions(settings);
   log('Agent permissions configured');
 
-  // Scan hook files for @hook-event tags
-  const { eventMap, untagged } = scanHookEvents(hooksSourceDir);
+  // Scan hook files for @hook-event tags — only deepflow-owned hooks
+  const { eventMap, untagged } = scanHookEvents(hooksSourceDir, 'deepflow');
 
   // Remember if there was a pre-existing non-deepflow statusLine
   const hadExternalStatusLine = settings.statusLine &&
@@ -403,6 +367,15 @@ async function configureHooks(claudeDir) {
   // Remove all existing deepflow hooks (orphan cleanup + idempotency)
   removeDeepflowHooks(settings);
 
+  // Migration warning: detect dashboard-owned hooks already wired in settings.json
+  // (they were installed by an older deepflow version that didn't distinguish owners)
+  const hasDashboardHooks = detectDashboardHooks(settings, claudeDir);
+  if (hasDashboardHooks) {
+    console.log('');
+    console.log(`  ${c.yellow}!${c.reset} Dashboard hooks detected — run \`npx deepflow-dashboard install\` to manage them separately.`);
+    console.log('');
+  }
+
   // Wire hooks by event
   if (!settings.hooks) settings.hooks = {};
 
@@ -636,12 +609,23 @@ async function uninstall() {
   ];
 
   if (level === 'global') {
-    // Dynamically find all df-*.js hook files to remove
+    // Dynamically find deepflow-owned hook files to remove.
+    // Check @hook-owner tag from the installed file; skip dashboard-owned hooks.
     const hooksDir = path.join(CLAUDE_DIR, 'hooks');
     if (fs.existsSync(hooksDir)) {
       for (const file of fs.readdirSync(hooksDir)) {
-        if (file.startsWith('df-') && file.endsWith('.js')) {
-          toRemove.push(`hooks/${file}`);
+        if (!file.startsWith('df-') || !file.endsWith('.js') || file.endsWith('.test.js')) continue;
+        const filePath = path.join(hooksDir, file);
+        try {
+          const content = fs.readFileSync(filePath, 'utf8');
+          const firstLines = content.split('\n').slice(0, 10).join('\n');
+          const ownerMatch = firstLines.match(/\/\/\s*@hook-owner:\s*(.+)/);
+          if (ownerMatch && ownerMatch[1].trim() === 'deepflow') {
+            toRemove.push(`hooks/${file}`);
+          }
+          // dashboard-owned hooks are intentionally left in place
+        } catch (_) {
+          // Skip unreadable files
         }
       }
     }

package/bin/install.test.js

@@ -333,6 +333,7 @@ describe('Uninstaller — file removal and settings cleanup', () => {
       'df-dashboard-push.js',
       'df-execution-history.js',
       'df-worktree-guard.js',
+      'df-harness-score.js',
     ]) {
       fs.writeFileSync(path.join(hookDir, hook), '// hook');
     }

package/bin/ratchet.js

@@ -273,10 +273,157 @@ function autoRevert(cwd) {
 // Health-check stages in order
 // ---------------------------------------------------------------------------
 
-const STAGE_ORDER = ['build', 'test', 'typecheck', 'lint'];
+const STAGE_ORDER = ['build', 'test', 'typecheck', 'lint', 'contract'];
 
 // Stages where failure is SALVAGEABLE (not FAIL)
-const SALVAGEABLE_STAGES = new Set(['lint']);
+const SALVAGEABLE_STAGES = new Set(['lint', 'contract']);
+
+// ---------------------------------------------------------------------------
+// REQ-1 + REQ-8: Contract stage
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse `Produces: path::Symbol` entries from PLAN.md.
+ * Returns array of { file, symbol } entries.
+ */
+function parseProducesFromPlan(planPath) {
+  if (!fs.existsSync(planPath)) return [];
+  const text = fs.readFileSync(planPath, 'utf8');
+  const entries = [];
+  // Match: Produces: <path>::<Symbol>   (tolerant to leading whitespace & markdown bullets)
+  const re = /Produces:\s*([^\s:`]+)::([A-Za-z_$][A-Za-z0-9_$]*)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    entries.push({ file: m[1].trim(), symbol: m[2].trim() });
+  }
+  return entries;
+}
+
+/**
+ * Verify that a symbol exists in a file.
+ * Tries LSP documentSymbols first (if available); falls back to regex grep.
+ * Returns true if found, false otherwise.
+ */
+async function verifySymbolExists(absFilePath, symbol, projectRoot) {
+  // LSP-first — try to use queryLsp from df-invariant-check if present
+  try {
+    const invariantPath = path.join(projectRoot, 'hooks', 'df-invariant-check.js');
+    if (fs.existsSync(invariantPath)) {
+      // eslint-disable-next-line global-require
+      const inv = require(invariantPath);
+      if (typeof inv.queryLsp === 'function' && typeof inv.detectLanguageServer === 'function') {
+        const detected = inv.detectLanguageServer(projectRoot, [absFilePath]);
+        if (detected && detected.binary) {
+          const fileUri = 'file://' + absFilePath;
+          const res = await inv.queryLsp(
+            detected.binary,
+            projectRoot,
+            fileUri,
+            'textDocument/documentSymbol',
+            { textDocument: { uri: fileUri } }
+          );
+          if (res && res.ok && Array.isArray(res.result)) {
+            const names = flattenSymbolNames(res.result);
+            if (names.includes(symbol)) return true;
+            // LSP gave a definitive (empty/non-matching) result — do NOT fall
+            // back to regex when we have an authoritative answer. But if
+            // the list is empty, treat as inconclusive → fallback.
+            if (names.length > 0) return false;
+          }
+        }
+      }
+    }
+  } catch (_) {
+    // LSP unavailable — fall back
+  }
+
+  // Regex fallback: scan file for \bsymbol\b
+  try {
+    if (!fs.existsSync(absFilePath)) return false;
+    const src = fs.readFileSync(absFilePath, 'utf8');
+    const safe = escapeRegExp(symbol);
+    return new RegExp(`\\b${safe}\\b`).test(src);
+  } catch (_) {
+    return false;
+  }
+}
+
+function flattenSymbolNames(symbols) {
+  const names = [];
+  const walk = (arr) => {
+    for (const s of arr || []) {
+      if (s && typeof s.name === 'string') names.push(s.name);
+      if (s && Array.isArray(s.children)) walk(s.children);
+    }
+  };
+  walk(symbols);
+  return names;
+}
+
+/**
+ * Count AC-N references across snapshot test files.
+ */
+function countAcRefsInSnapshot(snapshotFiles) {
+  let count = 0;
+  const pattern = /\bAC-\d+\b/g;
+  for (const f of snapshotFiles) {
+    try {
+      const src = fs.readFileSync(f, 'utf8');
+      const matches = src.match(pattern);
+      if (matches) count += matches.length;
+    } catch (_) {
+      // skip unreadable
+    }
+  }
+  return count;
+}
+
+/**
+ * Run the contract stage.
+ * @returns {Promise<{ ok: boolean, salvageable?: boolean, log: string }>}
+ *   - ok:true → PASS (continue / exit success)
+ *   - ok:false, salvageable:true → SALVAGEABLE (exit 2, no revert)
+ *   - ok:false → FAIL
+ *   - If no Produces: entries at all, returns ok:true (no-op).
+ */
+async function runContractStage(repoRoot, cwd, snapshotFiles) {
+  // Locate PLAN.md — prefer worktree cwd, fall back to repo root
+  let planPath = path.join(cwd, 'PLAN.md');
+  if (!fs.existsSync(planPath)) planPath = path.join(repoRoot, 'PLAN.md');
+
+  const entries = parseProducesFromPlan(planPath);
+  if (entries.length === 0) {
+    return { ok: true, log: 'contract: no Produces: entries — skipped' };
+  }
+
+  // Verify each declared symbol exists
+  const missing = [];
+  for (const { file, symbol } of entries) {
+    const absPath = path.isAbsolute(file) ? file : path.join(cwd, file);
+    const found = await verifySymbolExists(absPath, symbol, repoRoot);
+    if (!found) missing.push(`${file}::${symbol}`);
+  }
+
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      salvageable: true,
+      log: `contract: declared symbols not found: ${missing.join(', ')}`,
+    };
+  }
+
+  // Ratchet PASS + zero AC test references in snapshot → SALVAGEABLE
+  const acRefs = countAcRefsInSnapshot(snapshotFiles);
+  if (acRefs === 0) {
+    return {
+      ok: false,
+      salvageable: true,
+      log: 'contract: zero AC-N references found in ratchet snapshot test files',
+    };
+  }
+
+  return { ok: true, log: `contract: ${entries.length} symbols verified, ${acRefs} AC refs` };
+}
 
 // ---------------------------------------------------------------------------
 // CLI argument parser
@@ -287,7 +434,7 @@ function escapeRegExp(value) {
 }
 
 function parseArgs(argv) {
-  const args = { task: null, worktree: null, snapshot: null };
+  const args = { task: null, worktree: null, snapshot: null, stage: null };
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--task' && argv[i + 1]) {
       args.task = argv[++i];
@@ -295,6 +442,8 @@ function parseArgs(argv) {
       args.worktree = argv[++i];
     } else if (argv[i] === '--snapshot' && argv[i + 1]) {
       args.snapshot = argv[++i];
+    } else if (argv[i] === '--stage' && argv[i + 1]) {
+      args.stage = argv[++i];
     }
   }
   return args;
@@ -338,26 +487,51 @@ function updatePlanMd(repoRoot, taskId, cwd) {
 // Main
 // ---------------------------------------------------------------------------
 
-function main() {
+async function main() {
   const cliArgs = parseArgs(process.argv.slice(2));
   const cwd = cliArgs.worktree || process.cwd();
   const repoRoot = mainRepoRoot(cwd);
 
   const cfg = loadConfig(repoRoot);
   const projectType = detectProjectType(repoRoot);
-  const snapshotFiles = loadSnapshotFiles(repoRoot, cwd);
+  let snapshotFiles = loadSnapshotFiles(repoRoot, cwd);
   const cmds = buildCommands(repoRoot, projectType, snapshotFiles, cfg);
   // --snapshot flag overrides the snapshot-derived test command
   if (cliArgs.snapshot && fs.existsSync(cliArgs.snapshot)) {
     const snapFiles = fs.readFileSync(cliArgs.snapshot, 'utf8')
       .split('\n').map(l => l.trim()).filter(l => l.length > 0)
       .map(rel => path.isAbsolute(rel) ? rel : path.join(cwd, rel));
-    if (snapFiles.length > 0 && projectType === 'node' && !cfg.test_command) {
-      cmds.test = ['node', '--test', ...snapFiles];
+    if (snapFiles.length > 0) {
+      snapshotFiles = snapFiles;
+      if (projectType === 'node' && !cfg.test_command) {
+        cmds.test = ['node', '--test', ...snapFiles];
+      }
     }
   }
 
+  // --stage filter: run only the specified stage
+  const stageFilter = cliArgs.stage;
+  if (stageFilter && !STAGE_ORDER.includes(stageFilter)) {
+    process.stdout.write(JSON.stringify({ result: 'FAIL', stage: stageFilter, log: `unknown stage: ${stageFilter}` }) + '\n');
+    process.exit(1);
+  }
+
   for (const stage of STAGE_ORDER) {
+    if (stageFilter && stage !== stageFilter) continue;
+
+    // Contract stage is implemented in-process (no external command)
+    if (stage === 'contract') {
+      const res = await runContractStage(repoRoot, cwd, snapshotFiles);
+      if (res.ok) continue;
+      if (res.salvageable) {
+        process.stdout.write(JSON.stringify({ result: 'SALVAGEABLE', stage, log: res.log }) + '\n');
+        process.exit(2);
+      }
+      autoRevert(cwd);
+      process.stdout.write(JSON.stringify({ result: 'FAIL', stage, log: res.log }) + '\n');
+      process.exit(1);
+    }
+
     const cmd = cmds[stage];
     if (!cmd) continue; // stage not applicable
 
@@ -394,4 +568,7 @@ function main() {
   process.exit(0);
 }
 
-main();
+main().catch((err) => {
+  process.stdout.write(JSON.stringify({ result: 'FAIL', stage: 'internal', log: String(err && err.stack || err) }) + '\n');
+  process.exit(1);
+});

package/bin/ratchet.test.js

@@ -570,19 +570,19 @@ describe('buildCommands — unknown project type', () => {
 // 7. Health check stage ordering — source assertions
 // ---------------------------------------------------------------------------
 
-describe('STAGE_ORDER — build, test, typecheck, lint', () => {
+describe('STAGE_ORDER — build, test, typecheck, lint, contract', () => {
   test('source defines stages in correct order', () => {
     const match = RATCHET_SRC.match(/STAGE_ORDER\s*=\s*\[([^\]]+)\]/);
     assert.ok(match, 'STAGE_ORDER constant should exist in source');
     const stages = match[1].replace(/['"]/g, '').split(',').map(s => s.trim());
-    assert.deepEqual(stages, ['build', 'test', 'typecheck', 'lint']);
+    assert.deepEqual(stages, ['build', 'test', 'typecheck', 'lint', 'contract']);
   });
 
-  test('only lint is SALVAGEABLE', () => {
+  test('lint and contract are SALVAGEABLE', () => {
     const match = RATCHET_SRC.match(/SALVAGEABLE_STAGES\s*=\s*new Set\(\[([^\]]+)\]\)/);
     assert.ok(match, 'SALVAGEABLE_STAGES constant should exist in source');
     const stages = match[1].replace(/['"]/g, '').split(',').map(s => s.trim());
-    assert.deepEqual(stages, ['lint']);
+    assert.deepEqual(stages, ['lint', 'contract']);
   });
 });