@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/plugins/pbr/scripts/graph-update.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse hook for Write|Edit: Incrementally updates the architecture graph
+ * when source files are written or edited.
+ *
+ * - Parses stdin JSON for tool_input.file_path (the file just written/edited)
+ * - Determines planningDir by walking up ancestors from the file path
+ * - Skips files inside .planning/ (avoid self-referential updates)
+ * - Skips non-source files (.md, .json, .txt, .log)
+ * - Calls isGraphEnabled() from graph.cjs; returns null if disabled
+ * - Calls loadGraph(); if missing, calls buildGraph() for initial build
+ * - Otherwise calls updateGraphIncremental() for incremental update
+ * - Logs to .planning/logs/hooks.jsonl with event type "graph_update"
+ * - Returns null (PostToolUse no-block)
+ *
+ * Exit codes:
+ *   0 = always (PostToolUse hook, advisory only)
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+// Source extensions to process
+const SOURCE_EXTENSIONS = new Set(['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx']);
+
+// ─── Helper: find .planning directory by walking up ──────────────────────────
+
+/**
+ * Walk up the directory tree from filePath to find the nearest .planning/ directory.
+ * @param {string} filePath - Absolute file path
+ * @returns {string|null} Absolute path to .planning/, or null if not found
+ */
+function findPlanningDir(filePath) {
+  let dir = path.isAbsolute(filePath) ? path.dirname(filePath) : path.dirname(path.resolve(filePath));
+  const root = path.parse(dir).root;
+
+  // Don't walk too deep (max 20 levels)
+  let depth = 0;
+  while (dir !== root && depth < 20) {
+    const candidate = path.join(dir, '.planning');
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+      return candidate;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // at root
+    dir = parent;
+    depth++;
+  }
+  return null;
+}
+
+// ─── Helper: check if a file is a source file we should process ──────────────
+
+/**
+ * Check if a file path represents a processable source file.
+ * @param {string} filePath - File path (relative or absolute)
+ * @returns {boolean}
+ */
+function isSourceFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return SOURCE_EXTENSIONS.has(ext);
+}
+
+// ─── Log helper: write directly to planningDir to avoid CWD dependency ───────
+
+const MAX_LOG_ENTRIES = 200;
+
+/**
+ * Write a graph_update log entry to .planning/logs/hooks.jsonl.
+ * Bypasses hook-logger's CWD dependency so tests with temp dirs work correctly.
+ * @param {string} planningDir
+ * @param {string} file - Changed file path
+ * @param {number} nodes - Node count
+ */
+function writeGraphUpdateLog(planningDir, file, nodes) {
+  try {
+    const logsDir = path.join(planningDir, 'logs');
+    if (!fs.existsSync(logsDir)) {
+      fs.mkdirSync(logsDir, { recursive: true });
+    }
+    const logPath = path.join(logsDir, 'hooks.jsonl');
+    const entry = {
+      ts: new Date().toISOString(),
+      hook: 'graph-update',
+      event: 'graph_update',
+      decision: 'graph_update',
+      file,
+      nodes
+    };
+
+    let lines = [];
+    if (fs.existsSync(logPath)) {
+      const content = fs.readFileSync(logPath, 'utf8').trim();
+      if (content) lines = content.split('\n');
+    }
+    lines.push(JSON.stringify(entry));
+    if (lines.length > MAX_LOG_ENTRIES) lines = lines.slice(lines.length - MAX_LOG_ENTRIES);
+    fs.writeFileSync(logPath, lines.join('\n') + '\n', 'utf8');
+  } catch (_e) {
+    // Best-effort — never fail the hook
+  }
+}
+
+// ─── Core update logic (exported for testing) ─────────────────────────────────
+
+/**
+ * Run the graph update for a changed file.
+ * @param {string} planningDir - Path to .planning directory
+ * @param {string} projectRoot - Path to project root
+ * @param {string} changedFile - Relative path of the changed file
+ * @returns {null} Always returns null (no block)
+ */
+function updateGraph(planningDir, projectRoot, changedFile) {
+  // Normalize changedFile to relative form
+  const normalizedFile = changedFile.replace(/\\/g, '/');
+
+  // Skip files inside .planning/
+  if (normalizedFile.includes('.planning/') || normalizedFile.startsWith('.planning')) {
+    try { logHook('graph-update', 'PostToolUse', 'skip', { reason: 'inside .planning', file: normalizedFile }); } catch (_e) { /* never crash */ }
+    return null;
+  }
+
+  // Skip non-source files
+  if (!isSourceFile(normalizedFile)) {
+    try { logHook('graph-update', 'PostToolUse', 'skip', { reason: 'non-source file', file: normalizedFile }); } catch (_e) { /* never crash */ }
+    return null;
+  }
+
+  // Load graph module
+  const graphModule = require(path.resolve(__dirname, '../../..', 'plan-build-run', 'bin', 'lib', 'graph.cjs'));
+
+  // Check if graph is enabled
+  if (!graphModule.isGraphEnabled(planningDir)) {
+    try { logHook('graph-update', 'PostToolUse', 'skip', { reason: 'graph disabled' }); } catch (_e) { /* never crash */ }
+    return null;
+  }
+
+  // Load existing graph or do a full build
+  let graph = graphModule.loadGraph(planningDir);
+  if (!graph) {
+    graph = graphModule.buildGraph(planningDir, projectRoot);
+  } else {
+    graph = graphModule.updateGraphIncremental(planningDir, projectRoot, normalizedFile);
+  }
+
+  // Log the update directly to the planningDir logs
+  const nodeCount = (graph && graph._meta && graph._meta.node_count) || 0;
+  writeGraphUpdateLog(planningDir, normalizedFile, nodeCount);
+
+  return null;
+}
+
+// ─── Main (stdin-based hook entry point) ─────────────────────────────────────
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      const filePath = (data.tool_input && data.tool_input.file_path) || '';
+
+      try { logHook('graph-update', 'PostToolUse', 'entry', { file: filePath }); } catch (_e) { /* never crash */ }
+
+      if (!filePath) {
+        try { logHook('graph-update', 'PostToolUse', 'skip', { reason: 'no file path' }); } catch (_e) { /* never crash */ }
+        process.exit(0);
+        return;
+      }
+
+      // Resolve absolute path for planning dir detection
+      const absFilePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+      const planningDir = findPlanningDir(absFilePath);
+      if (!planningDir) {
+        try { logHook('graph-update', 'PostToolUse', 'skip', { reason: 'no .planning dir', file: filePath }); } catch (_e) { /* never crash */ }
+        process.exit(0);
+        return;
+      }
+
+      const projectRoot = path.dirname(planningDir);
+      // Get relative file path from project root
+      let relFilePath = path.relative(projectRoot, absFilePath).replace(/\\/g, '/');
+
+      updateGraph(planningDir, projectRoot, relFilePath);
+      process.exit(0);
+    } catch (_e) {
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { updateGraph, findPlanningDir, isSourceFile };
+if (require.main === module || process.argv[1] === __filename) { main(); }

package/plugins/pbr/scripts/hook-logger.js

@@ -7,41 +7,94 @@
  *   const { logHook } = require('./hook-logger');
  *   logHook('validate-commit', 'PreToolUse', 'allow', { message: 'chore: ...' });
  *
- * Log file: .planning/logs/hooks.jsonl (in the project's .planning directory)
- * Format: One JSON line per entry (JSONL)
- * Rotation: Keeps last 200 entries max
+ * Log files: .planning/logs/hooks-YYYY-MM-DD.jsonl (one file per day, no size cap)
+ * Format: One JSON line per entry (JSONL), append-only
+ * Retention: Old daily files are cleaned up after MAX_DAYS days by session-cleanup.js
  */
 
 const fs = require('fs');
 const path = require('path');
+const { resolveProjectRoot } = require('./lib/resolve-root');
 
-const MAX_ENTRIES = 200;
+const MAX_DAYS = 30;
 
-function getLogPath() {
-  const cwd = process.cwd();
-  const planningDir = path.join(cwd, '.planning');
-  if (!fs.existsSync(planningDir)) return null;
+/** Return today's date string as YYYY-MM-DD (local time). */
+function getTodayDate() {
+  const d = new Date();
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+/** Return the log filename for a given date (defaults to today). */
+function getLogFilename(date) {
+  return `hooks-${date || getTodayDate()}.jsonl`;
+}
+
+/** Return the full path to the hooks log for a given date (defaults to today). */
+function getLogPath(date) {
+  const logDirOverride = process.env.PBR_LOG_DIR;
+  if (logDirOverride) {
+    if (!fs.existsSync(logDirOverride)) {
+      fs.mkdirSync(logDirOverride, { recursive: true });
+    }
+    return path.join(logDirOverride, getLogFilename(date));
+  }
 
-  const logsDir = path.join(planningDir, 'logs');
-  const newPath = path.join(logsDir, 'hooks.jsonl');
-  const oldPath = path.join(planningDir, '.hook-log');
+  const cwd = resolveProjectRoot();
+  const logsDir = path.join(cwd, '.planning', 'logs');
 
-  // Auto-create logs/ directory if it doesn't exist
+  // Auto-create .planning/logs/ if it doesn't exist.
   if (!fs.existsSync(logsDir)) {
     fs.mkdirSync(logsDir, { recursive: true });
   }
 
-  // One-time migration: move old .hook-log to new location
-  if (fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
-    fs.renameSync(oldPath, newPath);
+  // One-time migration: rename legacy hooks.jsonl to yesterday's dated file.
+  const legacyPath = path.join(logsDir, 'hooks.jsonl');
+  if (fs.existsSync(legacyPath)) {
+    const yesterday = new Date(Date.now() - 86400000);
+    const yDate = `${yesterday.getFullYear()}-${String(yesterday.getMonth() + 1).padStart(2, '0')}-${String(yesterday.getDate()).padStart(2, '0')}`;
+    const migratedPath = path.join(logsDir, `hooks-${yDate}.jsonl`);
+    // Only migrate if the dated file doesn't already exist (avoid overwriting)
+    if (!fs.existsSync(migratedPath)) {
+      try { fs.renameSync(legacyPath, migratedPath); } catch (_e) { /* best-effort */ }
+    } else {
+      try { fs.unlinkSync(legacyPath); } catch (_e) { /* best-effort */ }
+    }
+  }
+
+  // One-time migration: move very old .hook-log to dated file
+  const veryOldPath = path.join(cwd, '.planning', '.hook-log');
+  if (fs.existsSync(veryOldPath)) {
+    try { fs.unlinkSync(veryOldPath); } catch (_e) { /* best-effort */ }
   }
 
-  return newPath;
+  return path.join(logsDir, getLogFilename(date));
 }
 
-function logHook(hookName, eventType, decision, details = {}, startTime) {
+/**
+ * Delete hooks-*.jsonl files older than MAX_DAYS days.
+ * Called by session-cleanup.js at session end — not called on every log write.
+ */
+function cleanOldHookLogs(logsDir) {
+  try {
+    const cutoff = Date.now() - MAX_DAYS * 86400000;
+    const files = fs.readdirSync(logsDir);
+    for (const file of files) {
+      if (!/^hooks-\d{4}-\d{2}-\d{2}\.jsonl$/.test(file)) continue;
+      const filePath = path.join(logsDir, file);
+      const stat = fs.statSync(filePath);
+      if (stat.mtimeMs < cutoff) fs.unlinkSync(filePath);
+    }
+  } catch (_e) {
+    // Best-effort cleanup — never fail the caller
+  }
+}
+
+function logHook(hookName, eventType, decision, details = {}, startTime, source, sessionId) {
   const logPath = getLogPath();
-  if (!logPath) return; // Not a Plan-Build-Run project
+  if (!logPath) return;
 
   const entry = {
     ts: new Date().toISOString(),
@@ -51,30 +104,18 @@ function logHook(hookName, eventType, decision, details = {}, startTime) {
     ...details
   };
 
+  if (source) entry.source = source;
+  if (sessionId) entry.sid = sessionId;
+
   if (typeof startTime === 'number' && startTime > 0) {
     entry.duration_ms = Date.now() - startTime;
   }
 
   try {
-    let lines = [];
-    if (fs.existsSync(logPath)) {
-      const content = fs.readFileSync(logPath, 'utf8').trim();
-      if (content) {
-        lines = content.split('\n');
-      }
-    }
-
-    lines.push(JSON.stringify(entry));
-
-    // Keep only last MAX_ENTRIES
-    if (lines.length > MAX_ENTRIES) {
-      lines = lines.slice(lines.length - MAX_ENTRIES);
-    }
-
-    fs.writeFileSync(logPath, lines.join('\n') + '\n', 'utf8');
+    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
   } catch (_e) {
     // Best-effort logging — never fail the hook
   }
 }
 
-module.exports = { logHook };
+module.exports = { logHook, getLogPath, getLogFilename, cleanOldHookLogs, getTodayDate };

package/plugins/pbr/scripts/hook-server-client.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+
+/**
+ * hook-server-client.js — Thin HTTP client for the PBR hook server.
+ *
+ * Reads hook input from stdin (JSON), POSTs it to the local hook server,
+ * and relays the server response to stdout.
+ *
+ * Fail-open by design: if the server is not reachable or any error occurs,
+ * the client exits 0 (allowing the hook to pass through silently).
+ *
+ * Usage (called by hooks.json commands):
+ *   node hook-server-client.js <hook-name> [port]
+ *
+ * Arguments:
+ *   argv[2]  Hook name (e.g. "track-context-budget")
+ *   argv[3]  Server port (default: 19836)
+ */
+
+'use strict';
+
+const http = require('http');
+const net = require('net');
+const path = require('path');
+
+const DEFAULT_PORT = 19836;
+
+// ---------------------------------------------------------------------------
+// HOOK_EVENT_MAP: maps hook script names to { event, tool } pairs
+// ---------------------------------------------------------------------------
+
+const HOOK_EVENT_MAP = {
+  'track-context-budget': { event: 'PostToolUse',        tool: 'Read'  },
+  'context-bridge':       { event: 'PostToolUse',        tool: 'Write' },
+  'post-write-dispatch':  { event: 'PostToolUse',        tool: 'Write' },
+  'post-bash-triage':     { event: 'PostToolUse',        tool: 'Bash'  },
+  'check-subagent-output':{ event: 'PostToolUse',        tool: 'Task'  },
+  'log-tool-failure':     { event: 'PostToolUseFailure', tool: '*'     },
+  'log-subagent-start':   { event: 'SubagentStart',      tool: '*'     },
+  'log-subagent':         { event: 'SubagentStop',       tool: '*'     },
+  'event-handler':        { event: 'SubagentStop',       tool: '*'     },
+  'task-completed':       { event: 'TaskCompleted',      tool: '*'     },
+  'context-budget-check': { event: 'PreCompact',         tool: '*'     },
+  'instructions-loaded':  { event: 'InstructionsLoaded', tool: '*'     },
+  'check-config-change':  { event: 'ConfigChange',       tool: '*'     },
+  'session-cleanup':      { event: 'SessionEnd',         tool: '*'     },
+  'worktree-create':      { event: 'WorktreeCreate',     tool: '*'     },
+  'worktree-remove':      { event: 'WorktreeRemove',     tool: '*'     }
+};
+
+// ---------------------------------------------------------------------------
+// TCP probe — check if server port is open before committing to an HTTP call
+// ---------------------------------------------------------------------------
+
+/**
+ * Probe whether the given port is accepting connections on 127.0.0.1.
+ * @param {number} port
+ * @param {number} [timeoutMs=200]
+ * @returns {Promise<boolean>}
+ */
+function probePort(port, timeoutMs) {
+  timeoutMs = timeoutMs || 200;
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+
+    function done(result) {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(result);
+    }
+
+    socket.setTimeout(timeoutMs);
+    socket.connect(port, '127.0.0.1', () => done(true));
+    socket.on('error', () => done(false));
+    socket.on('timeout', () => done(false));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// HTTP POST to hook server
+// ---------------------------------------------------------------------------
+
+/**
+ * POST payload to http://127.0.0.1:{port}/hook
+ * @param {number} port
+ * @param {string} body - JSON string
+ * @param {number} [timeoutMs=200]
+ * @returns {Promise<string>} Response body text
+ */
+function postHook(port, body, timeoutMs) {
+  timeoutMs = timeoutMs || 200;
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: '127.0.0.1',
+      port,
+      path: '/hook',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body)
+      }
+    };
+
+    const req = http.request(options, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', chunk => { data += chunk; });
+      res.on('end', () => resolve(data));
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error('request timeout'));
+    });
+
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Direct fallback for lifecycle hooks when the server is unreachable
+// ---------------------------------------------------------------------------
+
+const DIRECT_FALLBACK_SCRIPTS = {
+  'worktree-create': 'worktree-create',
+  'worktree-remove': 'worktree-remove'
+};
+
+/**
+ * When the hook server is not running, lifecycle hooks like WorktreeCreate
+ * still need to produce valid output. Fall back to requiring the script
+ * directly and calling its handleHttp export.
+ */
+function tryDirectFallback(hookName, inputData) {
+  const scriptBase = DIRECT_FALLBACK_SCRIPTS[hookName];
+  if (!scriptBase) return null;
+
+  try {
+    const mod = require(path.join(__dirname, scriptBase + '.js'));
+    if (typeof mod.handleHttp === 'function') {
+      const mapping = HOOK_EVENT_MAP[hookName];
+      return mod.handleHttp({
+        event: mapping ? mapping.event : hookName,
+        tool: mapping ? mapping.tool : '*',
+        data: inputData
+      });
+    }
+  } catch (_e) {
+    // Fall through — return generic context so the hook still has output
+  }
+  return { additionalContext: `[Plan-Build-Run] ${hookName} completed (server offline).` };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const hookName = process.argv[2] || '';
+  const port = parseInt(process.argv[3], 10) || DEFAULT_PORT;
+
+  // Read stdin
+  let stdinData = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    stdinData += chunk;
+  }
+
+  // Parse stdin as JSON (fail-open on bad input)
+  let inputData;
+  try {
+    inputData = JSON.parse(stdinData);
+  } catch (_e) {
+    process.stdout.write('{}');
+    process.exit(0);
+    return;
+  }
+
+  // Resolve event/tool from hook name
+  const mapping = HOOK_EVENT_MAP[hookName];
+  if (!mapping) {
+    // Unknown hook — pass through silently
+    process.stdout.write('{}');
+    process.exit(0);
+    return;
+  }
+
+  // Probe port before attempting HTTP call
+  let reachable = false;
+  try {
+    reachable = await probePort(port, 200);
+  } catch (_e) {
+    reachable = false;
+  }
+
+  if (!reachable) {
+    // Server not running — try direct fallback for lifecycle hooks
+    const directFallback = tryDirectFallback(hookName, inputData);
+    if (directFallback) {
+      process.stdout.write(JSON.stringify(directFallback));
+    } else {
+      process.stdout.write('{}');
+    }
+    process.exit(0);
+    return;
+  }
+
+  // Build request payload
+  const payload = JSON.stringify({
+    event: mapping.event,
+    tool: mapping.tool,
+    data: inputData
+  });
+
+  // POST to hook server
+  let responseText = '';
+  try {
+    responseText = await postHook(port, payload, 200);
+  } catch (_e) {
+    process.stdout.write('{}');
+    process.exit(0);
+    return;
+  }
+
+  // Parse and relay response
+  let response;
+  try {
+    response = JSON.parse(responseText);
+  } catch (_e) {
+    process.stdout.write('{}');
+    process.exit(0);
+    return;
+  }
+
+  // Relay additionalContext or decision/reason to Claude Code via stdout
+  const out = {};
+  if (response.additionalContext) out.additionalContext = response.additionalContext;
+  if (response.decision !== undefined) {
+    out.decision = response.decision;
+    if (response.reason !== undefined) out.reason = response.reason;
+  }
+  // Always write JSON to stdout — WorktreeCreate hooks require output to confirm success
+  process.stdout.write(JSON.stringify(out));
+
+  process.exit(0);
+}
+
+main().catch(() => {
+  // Fail-open on any unhandled error — still produce output for hooks that require it
+  process.stdout.write('{}');
+  process.exit(0);
+});
+
+module.exports = { probePort, postHook, HOOK_EVENT_MAP, DEFAULT_PORT };