deepflow 0.1.103 → 0.1.105

package/bin/install.test.js

@@ -909,3 +909,208 @@ describe('copyDir logic', () => {
     assert.ok(fs.existsSync(path.join(newDest, 'a.md')));
   });
 });
+
+// ---------------------------------------------------------------------------
+// 6. copyDir security hardening — symlink rejection & path traversal guard
+// ---------------------------------------------------------------------------
+
+describe('copyDir security hardening (symlink & path traversal)', () => {
+  let tmpSrc;
+  let tmpDest;
+
+  /**
+   * Reproduces the hardened copyDir from install.js (commit f3b7f47).
+   * Includes isSymbolicLink() check and path traversal guard.
+   */
+  function copyDir(src, dest) {
+    if (!fs.existsSync(src)) return;
+
+    const resolvedSrcRoot = path.resolve(src);
+    const resolvedDestRoot = path.resolve(dest);
+
+    fs.mkdirSync(dest, { recursive: true });
+
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+
+      // Reject symlinks to prevent symlink attacks
+      if (entry.isSymbolicLink()) {
+        process.stderr.write(`[deepflow] skipping symlink: ${srcPath}\n`);
+        continue;
+      }
+
+      // Guard against path traversal — resolved paths must stay under their roots
+      const resolvedSrc = path.resolve(srcPath);
+      const resolvedDest = path.resolve(destPath);
+      if (!resolvedSrc.startsWith(resolvedSrcRoot + path.sep) && resolvedSrc !== resolvedSrcRoot) {
+        process.stderr.write(`[deepflow] skipping path traversal attempt (src): ${srcPath}\n`);
+        continue;
+      }
+      if (!resolvedDest.startsWith(resolvedDestRoot + path.sep) && resolvedDest !== resolvedDestRoot) {
+        process.stderr.write(`[deepflow] skipping path traversal attempt (dest): ${destPath}\n`);
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+
+  beforeEach(() => {
+    tmpSrc = makeTmpDir();
+    tmpDest = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmrf(tmpSrc);
+    rmrf(tmpDest);
+  });
+
+  // -- Symlink rejection --
+
+  test('skips symlinked files and does not copy them to dest', () => {
+    // Create a real file outside the src tree
+    const outsideFile = path.join(os.tmpdir(), `df-symlink-target-${Date.now()}.txt`);
+    fs.writeFileSync(outsideFile, 'secret content');
+
+    // Create a symlink inside the src dir pointing to the outside file
+    fs.symlinkSync(outsideFile, path.join(tmpSrc, 'link-to-secret.txt'));
+
+    // Also create a normal file to ensure it IS copied
+    fs.writeFileSync(path.join(tmpSrc, 'normal.md'), '# normal');
+
+    copyDir(tmpSrc, tmpDest);
+
+    // The symlink should NOT have been copied
+    assert.ok(
+      !fs.existsSync(path.join(tmpDest, 'link-to-secret.txt')),
+      'Symlinked file should be skipped and not appear in dest'
+    );
+    // The normal file should still be copied
+    assert.ok(
+      fs.existsSync(path.join(tmpDest, 'normal.md')),
+      'Normal files should still be copied alongside skipped symlinks'
+    );
+
+    // Cleanup
+    fs.unlinkSync(outsideFile);
+  });
+
+  test('skips symlinked directories and does not copy them to dest', () => {
+    // Create a real directory outside src
+    const outsideDir = makeTmpDir();
+    fs.writeFileSync(path.join(outsideDir, 'inside.txt'), 'hidden');
+
+    // Create a directory symlink inside src
+    fs.symlinkSync(outsideDir, path.join(tmpSrc, 'link-to-dir'));
+
+    // Normal subdir to verify it copies
+    fs.mkdirSync(path.join(tmpSrc, 'real-sub'));
+    fs.writeFileSync(path.join(tmpSrc, 'real-sub', 'file.md'), '# real');
+
+    copyDir(tmpSrc, tmpDest);
+
+    assert.ok(
+      !fs.existsSync(path.join(tmpDest, 'link-to-dir')),
+      'Symlinked directory should be skipped'
+    );
+    assert.ok(
+      fs.existsSync(path.join(tmpDest, 'real-sub', 'file.md')),
+      'Real subdirectories should still be copied'
+    );
+
+    rmrf(outsideDir);
+  });
+
+  test('skips relative symlinks within the source tree', () => {
+    // Create a real file and a relative symlink to it
+    fs.writeFileSync(path.join(tmpSrc, 'real.md'), '# real');
+    fs.symlinkSync('real.md', path.join(tmpSrc, 'relative-link.md'));
+
+    copyDir(tmpSrc, tmpDest);
+
+    assert.ok(
+      fs.existsSync(path.join(tmpDest, 'real.md')),
+      'Real file should be copied'
+    );
+    assert.ok(
+      !fs.existsSync(path.join(tmpDest, 'relative-link.md')),
+      'Even relative symlinks should be skipped'
+    );
+  });
+
+  // -- Normal files continue to copy correctly --
+
+  test('copies normal files correctly when no symlinks or traversal present', () => {
+    fs.writeFileSync(path.join(tmpSrc, 'a.md'), '# a');
+    fs.writeFileSync(path.join(tmpSrc, 'b.txt'), 'content b');
+    fs.mkdirSync(path.join(tmpSrc, 'sub'));
+    fs.writeFileSync(path.join(tmpSrc, 'sub', 'c.md'), '# c');
+
+    copyDir(tmpSrc, tmpDest);
+
+    assert.equal(fs.readFileSync(path.join(tmpDest, 'a.md'), 'utf8'), '# a');
+    assert.equal(fs.readFileSync(path.join(tmpDest, 'b.txt'), 'utf8'), 'content b');
+    assert.equal(fs.readFileSync(path.join(tmpDest, 'sub', 'c.md'), 'utf8'), '# c');
+  });
+
+  test('copies deeply nested directories correctly', () => {
+    fs.mkdirSync(path.join(tmpSrc, 'l1', 'l2', 'l3'), { recursive: true });
+    fs.writeFileSync(path.join(tmpSrc, 'l1', 'l2', 'l3', 'deep.md'), '# deep');
+
+    copyDir(tmpSrc, tmpDest);
+
+    assert.ok(fs.existsSync(path.join(tmpDest, 'l1', 'l2', 'l3', 'deep.md')));
+    assert.equal(
+      fs.readFileSync(path.join(tmpDest, 'l1', 'l2', 'l3', 'deep.md'), 'utf8'),
+      '# deep'
+    );
+  });
+
+  // -- Source-level verification that the guards exist in install.js --
+
+  test('install.js copyDir checks isSymbolicLink()', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    assert.ok(
+      src.includes('entry.isSymbolicLink()'),
+      'copyDir should check entry.isSymbolicLink() to reject symlinks'
+    );
+  });
+
+  test('install.js copyDir has path traversal guard using startsWith', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    // The guard resolves src/dest and checks they stay under their root
+    assert.ok(
+      src.includes('resolvedSrc.startsWith(resolvedSrcRoot + path.sep)'),
+      'copyDir should guard source paths against traversal using startsWith'
+    );
+    assert.ok(
+      src.includes('resolvedDest.startsWith(resolvedDestRoot + path.sep)'),
+      'copyDir should guard dest paths against traversal using startsWith'
+    );
+  });
+
+  test('install.js copyDir logs stderr warning for skipped symlinks', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    assert.ok(
+      src.includes('[deepflow] skipping symlink:'),
+      'copyDir should log a warning to stderr when skipping a symlink'
+    );
+  });
+
+  test('install.js copyDir logs stderr warning for path traversal attempts', () => {
+    const src = fs.readFileSync(path.resolve(__dirname, 'install.js'), 'utf8');
+    assert.ok(
+      src.includes('[deepflow] skipping path traversal attempt (src):'),
+      'copyDir should log a warning for source path traversal'
+    );
+    assert.ok(
+      src.includes('[deepflow] skipping path traversal attempt (dest):'),
+      'copyDir should log a warning for dest path traversal'
+    );
+  });
+});

package/bin/lineage-ingest.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Scans specs/*.md for derives-from frontmatter and writes .deepflow/lineage.jsonl
+ *
+ * Each line: { "child": "fix-auth", "parent": "done-auth", "child_status": "doing", "scanned_at": "ISO" }
+ *
+ * Usage: node bin/lineage-ingest.js [--specs-dir specs/] [--out .deepflow/lineage.jsonl]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter } = require('../hooks/df-spec-lint.js');
+
+function main() {
+  const args = process.argv.slice(2);
+  const specsDir = getArg(args, '--specs-dir') || 'specs';
+  const outFile = getArg(args, '--out') || path.join('.deepflow', 'lineage.jsonl');
+
+  if (!fs.existsSync(specsDir)) {
+    process.stderr.write(`lineage-ingest: specs dir not found: ${specsDir}\n`);
+    process.exit(1);
+  }
+
+  const files = fs.readdirSync(specsDir).filter(f => f.endsWith('.md'));
+  const entries = [];
+  const now = new Date().toISOString();
+
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(specsDir, file), 'utf8');
+    const { frontmatter } = parseFrontmatter(content);
+    const derivesFrom = frontmatter['derives-from'];
+
+    if (!derivesFrom) continue;
+
+    const specName = file.replace(/\.md$/, '');
+    let childStatus = 'planned';
+    if (specName.startsWith('doing-')) childStatus = 'doing';
+    else if (specName.startsWith('done-')) childStatus = 'done';
+
+    entries.push({
+      child: specName,
+      parent: derivesFrom,
+      child_status: childStatus,
+      scanned_at: now
+    });
+  }
+
+  // Ensure output dir exists
+  const outDir = path.dirname(outFile);
+  if (outDir && !fs.existsSync(outDir)) {
+    fs.mkdirSync(outDir, { recursive: true });
+  }
+
+  // Overwrite — full scan each time, no append
+  const lines = entries.map(e => JSON.stringify(e)).join('\n');
+  fs.writeFileSync(outFile, lines ? lines + '\n' : '');
+
+  process.stdout.write(`lineage-ingest: ${entries.length} lineage entries written to ${outFile}\n`);
+}
+
+function getArg(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+module.exports = { main };
+
+if (require.main === module) {
+  main();
+}

package/hooks/df-check-update.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @hook-event: SessionStart
 /**
  * deepflow update checker
  * Runs in background, checks npm for newer versions

package/hooks/df-command-usage.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @hook-event: PreToolUse, PostToolUse, SessionEnd
 /**
  * deepflow command usage tracker
  * Tracks df:* command invocations with token deltas and tool call counts.
@@ -6,6 +7,7 @@
  * Events:
  *   PreToolUse  — detect Skill calls matching df:*, close previous command, open new marker
  *   PostToolUse — increment tool_calls_count on the active marker
+ *   SessionStart — close orphaned marker on /clear or /compact (context reset)
  *   SessionEnd  — close any open marker so the last command gets a record
  *
  * Marker: .deepflow/active-command.json
@@ -45,6 +47,8 @@ function main() {
     handlePreToolUse(deepflowDir, markerPath, usagePath, tokenHistoryPath);
   } else if (event === 'PostToolUse') {
     handlePostToolUse(markerPath);
+  } else if (event === 'SessionStart') {
+    handleSessionStart(markerPath, usagePath, tokenHistoryPath);
   } else if (event === 'SessionEnd') {
     handleSessionEnd(deepflowDir, markerPath, usagePath, tokenHistoryPath);
   }
@@ -111,6 +115,20 @@ function handlePostToolUse(markerPath) {
   }
 }
 
+/**
+ * On /clear or /compact, context resets — close any orphaned marker.
+ * Only fires for source=clear|compact (not startup/resume).
+ */
+function handleSessionStart(markerPath, usagePath, tokenHistoryPath) {
+  if (!safeExists(markerPath)) return;
+  let payload;
+  try { payload = JSON.parse(raw); } catch { return; }
+  const source = payload.source || '';
+  if (source === 'clear' || source === 'compact') {
+    closeCommand(markerPath, usagePath, tokenHistoryPath);
+  }
+}
+
 function handleSessionEnd(deepflowDir, markerPath, usagePath, tokenHistoryPath) {
   if (!safeExists(markerPath)) return;
   closeCommand(markerPath, usagePath, tokenHistoryPath);

package/hooks/df-dashboard-push.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @hook-event: SessionEnd
 /**
  * deepflow dashboard push — SessionEnd hook
  * Collects session summary (tokens, duration, tool calls, model), gets
@@ -40,9 +41,9 @@ function getStdinSync() {
   }
 }
 
-/** Read .deepflow/config.yaml and extract dashboard_url (no yaml dep — regex parse). */
-function getDashboardUrl(cwd) {
-  const configPath = path.join(cwd, '.deepflow', 'config.yaml');
+/** Read ~/.deepflow/config.yaml and extract dashboard_url (no yaml dep — regex parse). */
+function getDashboardUrl() {
+  const configPath = path.join(os.homedir(), '.deepflow', 'config.yaml');
   if (!fs.existsSync(configPath)) return null;
   try {
     const content = fs.readFileSync(configPath, 'utf8');
@@ -111,7 +112,7 @@ function postJson(url, payload) {
 async function main() {
   try {
     const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-    const dashboardUrl = getDashboardUrl(cwd);
+    const dashboardUrl = getDashboardUrl();
 
     // Silently skip if not configured
     if (!dashboardUrl) process.exit(0);

package/hooks/df-dashboard-push.test.js

@@ -0,0 +1,256 @@
+/**
+ * Tests for hooks/df-dashboard-push.js (security-hardening, T2)
+ *
+ * Validates that the dashboard push hook reads dashboard_url from
+ * ~/.deepflow/config.yaml (home directory) rather than the project
+ * directory, and silently skips when not configured.
+ *
+ * Uses Node.js built-in node:test to avoid adding dependencies.
+ */
+
+'use strict';
+
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('os');
+const { execFileSync } = require('node:child_process');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const HOOK_PATH = path.resolve(__dirname, 'df-dashboard-push.js');
+
+function makeTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'df-dashboard-push-test-'));
+}
+
+function rmrf(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Run the dashboard push hook in --background mode as a child process.
+ * Overrides HOME so getDashboardUrl reads from our fake home dir.
+ * Returns { stdout, stderr, code }.
+ */
+function runHook({ home, cwd, hookInput } = {}) {
+  const env = { ...process.env };
+  if (home) env.HOME = home;
+  if (hookInput !== undefined) env._DF_HOOK_INPUT = hookInput;
+  // Ensure CLAUDE_PROJECT_DIR points to cwd so main() uses it
+  if (cwd) env.CLAUDE_PROJECT_DIR = cwd;
+
+  try {
+    const stdout = execFileSync(
+      process.execPath,
+      [HOOK_PATH, '--background'],
+      {
+        cwd: cwd || os.tmpdir(),
+        encoding: 'utf8',
+        timeout: 10000,
+        env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }
+    );
+    return { stdout, stderr: '', code: 0 };
+  } catch (err) {
+    return {
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      code: err.status ?? 1,
+    };
+  }
+}
+
+/**
+ * Write a config.yaml into {dir}/.deepflow/config.yaml with given content.
+ */
+function writeConfig(dir, content) {
+  const configDir = path.join(dir, '.deepflow');
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(path.join(configDir, 'config.yaml'), content, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('df-dashboard-push hook', () => {
+  let fakeHome;
+  let fakeCwd;
+
+  beforeEach(() => {
+    fakeHome = makeTmpDir();
+    fakeCwd = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmrf(fakeHome);
+    rmrf(fakeCwd);
+  });
+
+  // -------------------------------------------------------------------------
+  // Config resolution: reads from HOME, not CWD
+  // -------------------------------------------------------------------------
+
+  describe('config resolution', () => {
+    test('exits 0 when no config file exists at HOME', () => {
+      const result = runHook({ home: fakeHome, cwd: fakeCwd });
+      assert.equal(result.code, 0);
+    });
+
+    test('exits 0 when config exists at HOME but has no dashboard_url key', () => {
+      writeConfig(fakeHome, 'build_command: "npm run build"\ntest_command: "npm test"\n');
+      const result = runHook({ home: fakeHome, cwd: fakeCwd });
+      assert.equal(result.code, 0);
+    });
+
+    test('exits 0 when dashboard_url is empty string', () => {
+      writeConfig(fakeHome, 'dashboard_url: ""\n');
+      const result = runHook({ home: fakeHome, cwd: fakeCwd });
+      assert.equal(result.code, 0);
+    });
+
+    test('exits 0 when dashboard_url is bare empty (no quotes)', () => {
+      writeConfig(fakeHome, 'dashboard_url: \n');
+      const result = runHook({ home: fakeHome, cwd: fakeCwd });
+      assert.equal(result.code, 0);
+    });
+
+    test('ignores dashboard_url in project cwd config (reads from HOME only)', () => {
+      // Put a valid URL in the project config, but NOT in home config
+      writeConfig(fakeCwd, 'dashboard_url: "http://localhost:9999"\n');
+      // Home has no config at all
+      const result = runHook({ home: fakeHome, cwd: fakeCwd });
+      // Should exit 0 without attempting POST because HOME has no config
+      assert.equal(result.code, 0);
+    });
+
+    test('reads dashboard_url from HOME config even when project has none', () => {
+      // Home has a dashboard_url pointing to an unreachable port
+      writeConfig(fakeHome, 'dashboard_url: "http://127.0.0.1:19999"\n');
+      // Project has no config
+      // Hook should attempt POST, fail silently, exit 0
+      const result = runHook({ home: fakeHome, cwd: fakeCwd, hookInput: '{}' });
+      assert.equal(result.code, 0);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // YAML parsing edge cases
+  // -------------------------------------------------------------------------
+
+  describe('dashboard_url parsing', () => {
+    test('extracts unquoted URL', () => {
+      writeConfig(fakeHome, 'dashboard_url: http://127.0.0.1:19999\n');
+      const result = runHook({ home: fakeHome, cwd: fakeCwd, hookInput: '{}' });
+      // Attempts POST, fails silently on unreachable port, exits 0
+      assert.equal(result.code, 0);
+    });
+
+    test('extracts single-quoted URL', () => {
+      writeConfig(fakeHome, "dashboard_url: 'http://127.0.0.1:19999'\n");
+      const result = runHook({ home: fakeHome, cwd: fakeCwd, hookInput: '{}' });
+      assert.equal(result.code, 0);
+    });
+
+    test('extracts double-quoted URL', () => {
+      writeConfig(fakeHome, 'dashboard_url: "http://127.0.0.1:19999"\n');
+      const result = runHook({ home: fakeHome, cwd: fakeCwd, hookInput: '{}' });
+      assert.equal(result.code, 0);
+    });
+
+    test('handles dashboard_url with leading spaces (indented)', () => {
+      writeConfig(fakeHome, '  dashboard_url: http://127.0.0.1:19999\n');
+      const result = runHook({ home: fakeHome, cwd: fakeCwd, hookInput: '{}' });
+      assert.equal(result.code, 0);
+    });
+
+    test('ignores commented-out dashboard_url', () => {
+      writeConfig(fakeHome, '# dashboard_url: http://127.0.0.1:19999\n');
+      const result = runHook({ home: fakeHome, cwd: fakeCwd });
+      // The regex uses ^ so a comment line should not match
+      assert.equal(result.code, 0);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error handling / resilience
+  // -------------------------------------------------------------------------
+
+  describe('error handling', () => {
+    test('exits 0 when config file is unreadable (permissions)', () => {
+      writeConfig(fakeHome, 'dashboard_url: http://localhost:9999\n');
+      const configPath = path.join(fakeHome, '.deepflow', 'config.yaml');
+      fs.chmodSync(configPath, 0o000);
+      const result = runHook({ home: fakeHome, cwd: fakeCwd });
+      assert.equal(result.code, 0);
+      // Restore permissions for cleanup
+      fs.chmodSync(configPath, 0o644);
+    });
+
+    test('exits 0 when hook input is invalid JSON', () => {
+      writeConfig(fakeHome, 'dashboard_url: http://127.0.0.1:19999\n');
+      const result = runHook({
+        home: fakeHome,
+        cwd: fakeCwd,
+        hookInput: '{not valid json',
+      });
+      assert.equal(result.code, 0);
+    });
+
+    test('exits 0 when hook input is empty', () => {
+      writeConfig(fakeHome, 'dashboard_url: http://127.0.0.1:19999\n');
+      const result = runHook({
+        home: fakeHome,
+        cwd: fakeCwd,
+        hookInput: '',
+      });
+      assert.equal(result.code, 0);
+    });
+
+    test('exits 0 when dashboard_url has invalid URL format', () => {
+      writeConfig(fakeHome, 'dashboard_url: not-a-url\n');
+      const result = runHook({
+        home: fakeHome,
+        cwd: fakeCwd,
+        hookInput: '{}',
+      });
+      // postJson should handle invalid URL gracefully
+      assert.equal(result.code, 0);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Foreground mode (spawns background and exits immediately)
+  // -------------------------------------------------------------------------
+
+  describe('foreground mode', () => {
+    test('exits 0 immediately without --background flag', () => {
+      const env = { ...process.env, HOME: fakeHome };
+      try {
+        const stdout = execFileSync(
+          process.execPath,
+          [HOOK_PATH],
+          {
+            cwd: fakeCwd,
+            encoding: 'utf8',
+            timeout: 5000,
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            input: '{}',
+          }
+        );
+        assert.equal(typeof stdout, 'string');
+      } catch (err) {
+        // Even if it errors, check code is 0 (fire-and-forget exit)
+        assert.equal(err.status, 0, 'foreground mode should exit 0');
+      }
+    });
+  });
+});

package/hooks/df-execution-history.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// @hook-event: PostToolUse
 /**
  * deepflow execution history recorder
  * PostToolUse hook: fires when the Agent tool completes.