deepflow 0.1.104 → 0.1.106

package/hooks/df-tool-usage-spike.js

@@ -11,31 +11,20 @@
 'use strict';
 
 const fs = require('fs');
+const { readStdinIfMain } = require('./lib/hook-stdin');
 
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => { raw += chunk; });
-process.stdin.on('end', () => {
-  try {
-    // Write raw payload for inspection
-    fs.writeFileSync('/tmp/df-posttooluse-payload.json', raw);
-
-    // Also append a minimal summary line for quick review
-    const data = JSON.parse(raw);
-    const summary = {
-      hook_event_name: data.hook_event_name,
-      tool_name: data.tool_name,
-      tool_use_id: data.tool_use_id,
-      session_id: data.session_id,
-      cwd: data.cwd,
-      permission_mode: data.permission_mode,
-      tool_input_keys: data.tool_input ? Object.keys(data.tool_input) : [],
-      tool_response_keys: data.tool_response ? Object.keys(data.tool_response) : [],
-      transcript_path: data.transcript_path,
-    };
-    fs.appendFileSync('/tmp/df-posttooluse-summary.jsonl', JSON.stringify(summary) + '\n');
-  } catch (_e) {
-    // Fail silently — never break tool execution
-  }
-  process.exit(0);
+readStdinIfMain(module, (data) => {
+  // Also append a minimal summary line for quick review
+  const summary = {
+    hook_event_name: data.hook_event_name,
+    tool_name: data.tool_name,
+    tool_use_id: data.tool_use_id,
+    session_id: data.session_id,
+    cwd: data.cwd,
+    permission_mode: data.permission_mode,
+    tool_input_keys: data.tool_input ? Object.keys(data.tool_input) : [],
+    tool_response_keys: data.tool_response ? Object.keys(data.tool_response) : [],
+    transcript_path: data.transcript_path,
+  };
+  fs.appendFileSync('/tmp/df-posttooluse-summary.jsonl', JSON.stringify(summary) + '\n');
 });

package/hooks/df-tool-usage.js

@@ -15,6 +15,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { readStdinIfMain } = require('./lib/hook-stdin');
 
 const TOOL_USAGE_LOG = path.join(os.homedir(), '.claude', 'tool-usage.jsonl');
 
@@ -49,56 +50,45 @@ function extractTaskId(cwd) {
   return taskMatch ? taskMatch[1].toUpperCase() : null;
 }
 
-// Read all stdin, then process
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => { raw += chunk; });
-process.stdin.on('end', () => {
-  try {
-    const data = JSON.parse(raw);
-
-    const toolName = data.tool_name || null;
-    const toolResponse = data.tool_response;
-    const cwd = data.cwd || '';
-
-    let activeCommand = null;
-    try {
-      const markerPath = path.join(cwd || process.cwd(), '.deepflow', 'active-command.json');
-      const markerRaw = fs.readFileSync(markerPath, 'utf8');
-      activeCommand = JSON.parse(markerRaw).command || null;
-    } catch (_e) { /* no marker or unreadable — null */ }
+readStdinIfMain(module, (data) => {
+  const toolName = data.tool_name || null;
+  const toolResponse = data.tool_response;
+  const cwd = data.cwd || '';
 
-    // Extract a compact tool_input summary per tool type
-    const ti = data.tool_input || {};
-    let inputSummary = null;
-    if (toolName === 'Bash') inputSummary = ti.command || null;
-    else if (toolName === 'LSP') inputSummary = `${ti.operation || '?'}:${(ti.filePath || '').split('/').pop()}:${ti.line || '?'}`;
-    else if (toolName === 'Read') inputSummary = (ti.file_path || '').split('/').pop() + (ti.offset ? `:${ti.offset}-${ti.offset + (ti.limit || 0)}` : '');
-    else if (toolName === 'Grep') inputSummary = ti.pattern || null;
-    else if (toolName === 'Glob') inputSummary = ti.pattern || null;
-    else if (toolName === 'Agent') inputSummary = `${ti.subagent_type || '?'}/${ti.model || '?'}`;
-    else if (toolName === 'Edit' || toolName === 'Write') inputSummary = (ti.file_path || '').split('/').pop();
+  let activeCommand = null;
+  try {
+    const markerPath = path.join(cwd || process.cwd(), '.deepflow', 'active-command.json');
+    const markerRaw = fs.readFileSync(markerPath, 'utf8');
+    activeCommand = JSON.parse(markerRaw).command || null;
+  } catch (_e) { /* no marker or unreadable — null */ }
 
-    const record = {
-      timestamp: new Date().toISOString(),
-      session_id: data.session_id || null,
-      tool_name: toolName,
-      input: inputSummary,
-      output_size_est_tokens: Math.ceil(JSON.stringify(toolResponse).length / 4),
-      project: cwd ? path.basename(cwd) : null,
-      phase: inferPhase(cwd),
-      task_id: extractTaskId(cwd),
-      active_command: activeCommand,
-    };
+  // Extract a compact tool_input summary per tool type
+  const ti = data.tool_input || {};
+  let inputSummary = null;
+  if (toolName === 'Bash') inputSummary = ti.command || null;
+  else if (toolName === 'LSP') inputSummary = `${ti.operation || '?'}:${(ti.filePath || '').split('/').pop()}:${ti.line || '?'}`;
+  else if (toolName === 'Read') inputSummary = (ti.file_path || '').split('/').pop() + (ti.offset ? `:${ti.offset}-${ti.offset + (ti.limit || 0)}` : '');
+  else if (toolName === 'Grep') inputSummary = ti.pattern || null;
+  else if (toolName === 'Glob') inputSummary = ti.pattern || null;
+  else if (toolName === 'Agent') inputSummary = `${ti.subagent_type || '?'}/${ti.model || '?'}`;
+  else if (toolName === 'Edit' || toolName === 'Write') inputSummary = (ti.file_path || '').split('/').pop();
 
-    const logDir = path.dirname(TOOL_USAGE_LOG);
-    if (!fs.existsSync(logDir)) {
-      fs.mkdirSync(logDir, { recursive: true });
-    }
+  const record = {
+    timestamp: new Date().toISOString(),
+    session_id: data.session_id || null,
+    tool_name: toolName,
+    input: inputSummary,
+    output_size_est_tokens: Math.ceil(JSON.stringify(toolResponse).length / 4),
+    project: cwd ? path.basename(cwd) : null,
+    phase: inferPhase(cwd),
+    task_id: extractTaskId(cwd),
+    active_command: activeCommand,
+  };
 
-    fs.appendFileSync(TOOL_USAGE_LOG, JSON.stringify(record) + '\n');
-  } catch (_e) {
-    // Fail silently — never break tool execution
+  const logDir = path.dirname(TOOL_USAGE_LOG);
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
   }
-  process.exit(0);
+
+  fs.appendFileSync(TOOL_USAGE_LOG, JSON.stringify(record) + '\n');
 });

package/hooks/df-worktree-guard.js

@@ -19,6 +19,7 @@
 'use strict';
 
 const { execFileSync } = require('child_process');
+const { readStdinIfMain } = require('./lib/hook-stdin');
 
 // Paths that are always allowed regardless of worktree state
 const ALLOWLIST = [
@@ -56,47 +57,38 @@ function dfWorktreeExists(cwd) {
   }
 }
 
-let raw = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', chunk => { raw += chunk; });
-process.stdin.on('end', () => {
-  try {
-    const data = JSON.parse(raw);
-    const toolName = data.tool_name || '';
-
-    // Only guard Write and Edit
-    if (toolName !== 'Write' && toolName !== 'Edit') {
-      process.exit(0);
-    }
+readStdinIfMain(module, (data) => {
+  const toolName = data.tool_name || '';
 
-    const filePath = (data.tool_input && data.tool_input.file_path) || '';
-    const cwd = data.cwd || process.cwd();
+  // Only guard Write and Edit
+  if (toolName !== 'Write' && toolName !== 'Edit') {
+    return;
+  }
 
-    // Allowlisted paths always pass
-    if (isAllowlisted(filePath)) {
-      process.exit(0);
-    }
+  const filePath = (data.tool_input && data.tool_input.file_path) || '';
+  const cwd = data.cwd || process.cwd();
 
-    const branch = currentBranch(cwd);
+  // Allowlisted paths always pass
+  if (isAllowlisted(filePath)) {
+    return;
+  }
 
-    // Only guard when on main/master
-    if (branch !== 'main' && branch !== 'master') {
-      process.exit(0);
-    }
+  const branch = currentBranch(cwd);
 
-    // Block only when a df/* worktree branch exists
-    if (!dfWorktreeExists(cwd)) {
-      process.exit(0);
-    }
+  // Only guard when on main/master
+  if (branch !== 'main' && branch !== 'master') {
+    return;
+  }
 
-    // All conditions met — block the write
-    console.error(
-      `[df-worktree-guard] Blocked ${toolName} to "${filePath}" on main branch ` +
-      `while df/* worktree exists. Make changes inside the worktree branch instead.`
-    );
-    process.exit(1);
-  } catch (_e) {
-    // Parse or unexpected error — fail open so we never break non-deepflow projects
-    process.exit(0);
+  // Block only when a df/* worktree branch exists
+  if (!dfWorktreeExists(cwd)) {
+    return;
   }
+
+  // All conditions met — block the write
+  console.error(
+    `[df-worktree-guard] Blocked ${toolName} to "${filePath}" on main branch ` +
+    `while df/* worktree exists. Make changes inside the worktree branch instead.`
+  );
+  process.exit(1);
 });

package/hooks/lib/hook-stdin.js

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * Shared stdin helper for deepflow hooks.
+ *
+ * Usage in a hook file:
+ *   const { readStdinIfMain } = require('./lib/hook-stdin');
+ *   readStdinIfMain(module, (data) => { ... });
+ *
+ * The helper checks if the CALLING hook is the main module (i.e. run directly,
+ * not required by a test). This prevents test files from hanging on stdin.
+ */
+
+/**
+ * readStdinIfMain(callerModule, callback)
+ *
+ * @param {NodeModule} callerModule  Pass `module` from the calling hook file.
+ * @param {function(Object): void} callback  Called with the parsed JSON payload.
+ *   If stdin is not valid JSON the process exits 0 without calling callback.
+ */
+function readStdinIfMain(callerModule, callback) {
+  if (require.main !== callerModule) {
+    // Being required (e.g. by a test) — do not read stdin.
+    return;
+  }
+
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { raw += chunk; });
+  process.stdin.on('end', () => {
+    let payload;
+    try {
+      payload = JSON.parse(raw);
+    } catch (_e) {
+      // Invalid JSON — exit 0 to avoid breaking Claude Code.
+      process.exit(0);
+    }
+    try {
+      callback(payload);
+    } catch (_e) {
+      // Never break Claude Code on hook errors.
+    }
+    process.exit(0);
+  });
+}
+
+module.exports = { readStdinIfMain };

package/hooks/lib/hook-stdin.test.js

@@ -0,0 +1,200 @@
+'use strict';
+
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { readStdinIfMain } = require('./hook-stdin');
+
+// ---------------------------------------------------------------------------
+// 1. Guard: skips stdin when callerModule is NOT require.main
+// ---------------------------------------------------------------------------
+
+describe('readStdinIfMain', () => {
+  test('returns immediately when callerModule is not require.main', () => {
+    const fakeModule = { id: 'not-main' };
+    const callback = () => { throw new Error('should not be called'); };
+
+    // Should return undefined without hanging or calling callback
+    const result = readStdinIfMain(fakeModule, callback);
+    assert.equal(result, undefined);
+  });
+
+  test('does not set encoding on stdin when callerModule is not require.main', () => {
+    const fakeModule = { id: 'not-main' };
+    let encodingSet = false;
+    const originalSetEncoding = process.stdin.setEncoding;
+    process.stdin.setEncoding = () => { encodingSet = true; };
+
+    try {
+      readStdinIfMain(fakeModule, () => {});
+      assert.equal(encodingSet, false, 'should not touch stdin when not main');
+    } finally {
+      process.stdin.setEncoding = originalSetEncoding;
+    }
+  });
+
+  test('does not attach data listeners when callerModule is not require.main', () => {
+    const fakeModule = { id: 'not-main' };
+    const listenersBefore = process.stdin.listenerCount('data');
+
+    readStdinIfMain(fakeModule, () => {});
+
+    const listenersAfter = process.stdin.listenerCount('data');
+    assert.equal(listenersAfter, listenersBefore, 'should not add data listeners');
+  });
+
+  test('callback is never invoked when callerModule is not require.main', () => {
+    const fakeModule = { id: 'not-main' };
+    let callbackInvoked = false;
+
+    readStdinIfMain(fakeModule, () => { callbackInvoked = true; });
+    assert.equal(callbackInvoked, false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Module exports
+// ---------------------------------------------------------------------------
+
+describe('hook-stdin exports', () => {
+  test('exports readStdinIfMain as a function', () => {
+    assert.equal(typeof readStdinIfMain, 'function');
+  });
+
+  test('readStdinIfMain expects two parameters', () => {
+    assert.equal(readStdinIfMain.length, 2);
+  });
+
+  test('module exports only readStdinIfMain', () => {
+    const exports = require('./hook-stdin');
+    const keys = Object.keys(exports);
+    assert.deepEqual(keys, ['readStdinIfMain']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Integration via subprocess — tests the stdin-reading path
+//    Spawns hook-stdin-test-harness as a child process so require.main matches.
+// ---------------------------------------------------------------------------
+
+const { execFileSync, spawn } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+// We create a tiny harness script that uses readStdinIfMain with itself as main
+const HARNESS_PATH = path.join(__dirname, '_test-harness-stdin.js');
+
+describe('readStdinIfMain when callerModule IS require.main (subprocess)', () => {
+  beforeEach(() => {
+    // Write a small harness that exercises readStdinIfMain as main module
+    fs.writeFileSync(HARNESS_PATH, `
+'use strict';
+const { readStdinIfMain } = require('./hook-stdin');
+readStdinIfMain(module, (data) => {
+  // Write parsed payload to stdout so the test can verify
+  process.stdout.write(JSON.stringify(data));
+});
+`);
+  });
+
+  afterEach(() => {
+    try { fs.unlinkSync(HARNESS_PATH); } catch (_e) { /* ignore */ }
+  });
+
+  test('parses valid JSON from stdin and passes to callback', () => {
+    const input = JSON.stringify({ event: 'test', foo: 42 });
+    const result = execFileSync(process.execPath, [HARNESS_PATH], {
+      input,
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    const parsed = JSON.parse(result);
+    assert.deepEqual(parsed, { event: 'test', foo: 42 });
+  });
+
+  test('handles empty object from stdin', () => {
+    const input = JSON.stringify({});
+    const result = execFileSync(process.execPath, [HARNESS_PATH], {
+      input,
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    assert.deepEqual(JSON.parse(result), {});
+  });
+
+  test('handles array payload from stdin', () => {
+    const input = JSON.stringify([1, 2, 3]);
+    const result = execFileSync(process.execPath, [HARNESS_PATH], {
+      input,
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    assert.deepEqual(JSON.parse(result), [1, 2, 3]);
+  });
+
+  test('exits 0 on invalid JSON without calling callback', () => {
+    // Invalid JSON should cause process.exit(0) before callback
+    const result = execFileSync(process.execPath, [HARNESS_PATH], {
+      input: 'not valid json {{{',
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    // Callback writes to stdout; if not called, stdout should be empty
+    assert.equal(result, '');
+  });
+
+  test('exits 0 on empty stdin without calling callback', () => {
+    const result = execFileSync(process.execPath, [HARNESS_PATH], {
+      input: '',
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    assert.equal(result, '');
+  });
+
+  test('exits 0 even when callback throws', () => {
+    // Write a harness where the callback throws
+    const throwHarness = path.join(__dirname, '_test-harness-throw.js');
+    fs.writeFileSync(throwHarness, `
+'use strict';
+const { readStdinIfMain } = require('./hook-stdin');
+readStdinIfMain(module, (data) => {
+  throw new Error('callback error');
+});
+`);
+    try {
+      // Should not throw — the error is caught internally
+      execFileSync(process.execPath, [throwHarness], {
+        input: JSON.stringify({ ok: true }),
+        encoding: 'utf8',
+        timeout: 5000,
+      });
+    } finally {
+      try { fs.unlinkSync(throwHarness); } catch (_e) { /* ignore */ }
+    }
+  });
+
+  test('handles large JSON payload', () => {
+    const largeObj = { data: 'x'.repeat(10000), nested: { a: 1 } };
+    const input = JSON.stringify(largeObj);
+    const result = execFileSync(process.execPath, [HARNESS_PATH], {
+      input,
+      encoding: 'utf8',
+      timeout: 10000,
+      maxBuffer: 1024 * 1024,
+    });
+    const parsed = JSON.parse(result);
+    assert.equal(parsed.data.length, 10000);
+    assert.equal(parsed.nested.a, 1);
+  });
+
+  test('handles JSON with unicode characters', () => {
+    const input = JSON.stringify({ msg: '日本語テスト 🎉' });
+    const result = execFileSync(process.execPath, [HARNESS_PATH], {
+      input,
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    assert.deepEqual(JSON.parse(result), { msg: '日本語テスト 🎉' });
+  });
+});

package/hooks/lib/lint-no-bare-stdin.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * lint-no-bare-stdin.js
+ *
+ * Guards against bare `process.stdin.on` calls being (re-)introduced in
+ * hooks/df-*.js files. Hooks that need stdin must use readStdinIfMain()
+ * from hooks/lib/hook-stdin.js instead.
+ *
+ * Excluded hooks (use alternative stdin strategies — documented below):
+ *   df-check-update.js    — spawns detached background process; never reads stdin
+ *   df-dashboard-push.js  — reads stdin synchronously via readFileSync('/dev/stdin')
+ *   df-quota-logger.js    — spawns detached background process; never reads stdin
+ *   df-spec-lint.js       — CLI tool (takes a filepath arg); never reads stdin
+ *
+ * Usage:
+ *   node hooks/lib/lint-no-bare-stdin.js          # exits 0 (clean) or 1 (violations)
+ *
+ * Integration:
+ *   Add to your CI / pre-commit as:
+ *     node hooks/lib/lint-no-bare-stdin.js
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const HOOKS_DIR = path.resolve(__dirname, '..');
+const PATTERN = /process\.stdin\.on\s*\(/;
+
+function run() {
+  // Collect hooks/df-*.js (not inside hooks/lib/)
+  const entries = fs.readdirSync(HOOKS_DIR);
+  const hookFiles = entries
+    .filter((f) => f.startsWith('df-') && f.endsWith('.js') && !f.endsWith('.test.js'))
+    .map((f) => path.join(HOOKS_DIR, f));
+
+  const violations = [];
+
+  for (const filePath of hookFiles) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    lines.forEach((line, idx) => {
+      if (PATTERN.test(line)) {
+        violations.push({
+          file: path.relative(path.resolve(__dirname, '..', '..'), filePath),
+          line: idx + 1,
+          text: line.trim(),
+        });
+      }
+    });
+  }
+
+  if (violations.length === 0) {
+    console.log('lint-no-bare-stdin: OK — no bare process.stdin.on calls found in hooks/df-*.js');
+    process.exit(0);
+  }
+
+  console.error('lint-no-bare-stdin: FAIL — bare process.stdin.on calls detected:');
+  for (const v of violations) {
+    console.error(`  ${v.file}:${v.line}  ${v.text}`);
+  }
+  console.error('');
+  console.error('Fix: use readStdinIfMain() from hooks/lib/hook-stdin.js instead of inline stdin listeners.');
+  process.exit(1);
+}
+
+run();

package/hooks/lib/lint-no-bare-stdin.test.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const { test, describe, after } = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+after(() => { process.stdin.destroy(); });
+
+const LINT_SCRIPT = path.join(__dirname, 'lint-no-bare-stdin.js');
+const HOOKS_DIR = path.resolve(__dirname, '..');
+
+describe('lint-no-bare-stdin', () => {
+  test('is a valid Node.js script (can be parsed without syntax errors)', () => {
+    // --check parses without executing
+    execFileSync(process.execPath, ['--check', LINT_SCRIPT], {
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    assert.ok(true, 'script parsed without syntax errors');
+  });
+
+  test('exits 0 when run against current hooks directory (codebase is clean)', () => {
+    const result = execFileSync(process.execPath, [LINT_SCRIPT], {
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    assert.match(result, /OK/, 'should report OK when no violations found');
+  });
+
+  test('scans hooks/df-*.js files (not lib/ or test files)', () => {
+    // Verify the script's target pattern by checking that hook files exist
+    const entries = fs.readdirSync(HOOKS_DIR);
+    const hookFiles = entries.filter(
+      (f) => f.startsWith('df-') && f.endsWith('.js') && !f.endsWith('.test.js')
+    );
+    assert.ok(hookFiles.length > 0, 'should find at least one hooks/df-*.js file to lint');
+  });
+
+  test('detects bare process.stdin.on and exits 1', () => {
+    // Create a temporary hook file with a violation
+    const tempHook = path.join(HOOKS_DIR, 'df-_test-lint-violation.js');
+    fs.writeFileSync(tempHook, `'use strict';\nprocess.stdin.on('data', () => {});\n`);
+    try {
+      execFileSync(process.execPath, [LINT_SCRIPT], {
+        encoding: 'utf8',
+        timeout: 5000,
+      });
+      assert.fail('should have exited with code 1');
+    } catch (err) {
+      assert.equal(err.status, 1, 'should exit 1 when violations found');
+      assert.match(
+        err.stderr.toString(),
+        /FAIL/,
+        'should report FAIL in stderr'
+      );
+      assert.match(
+        err.stderr.toString(),
+        /df-_test-lint-violation\.js/,
+        'should name the violating file'
+      );
+    } finally {
+      try { fs.unlinkSync(tempHook); } catch (_e) { /* ignore */ }
+    }
+  });
+
+  test('ignores .test.js files when scanning', () => {
+    // Create a test file with a violation — should NOT be flagged
+    const tempTest = path.join(HOOKS_DIR, 'df-_test-lint-fake.test.js');
+    fs.writeFileSync(tempTest, `'use strict';\nprocess.stdin.on('data', () => {});\n`);
+    try {
+      const result = execFileSync(process.execPath, [LINT_SCRIPT], {
+        encoding: 'utf8',
+        timeout: 5000,
+      });
+      assert.match(result, /OK/, 'test files should be excluded from scanning');
+    } finally {
+      try { fs.unlinkSync(tempTest); } catch (_e) { /* ignore */ }
+    }
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepflow",
-  "version": "0.1.104",
+  "version": "0.1.106",
   "description": "Doing reveals what thinking can't predict — spec-driven iterative development for Claude Code",
   "keywords": [
     "claude",