@sienklogic/plan-build-run 2.21.0 → 2.21.2

package/plugins/pbr/scripts/lib/pid-lock.js

@@ -0,0 +1,156 @@
+'use strict';
+
+/**
+ * pid-lock.js — PID lockfile management for the PBR hook server.
+ *
+ * Provides cross-platform PID-based lock acquisition, release, and
+ * status checking. The lockfile lives at .planning/.hook-server.pid
+ * and contains JSON: { pid, port, startedAt }.
+ *
+ * All functions are synchronous — no async needed for fs ops and process.kill.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const LOCKFILE_NAME = '.hook-server.pid';
+
+/**
+ * Check if a process with the given PID is alive.
+ * Uses process.kill(pid, 0) which throws on dead/inaccessible processes.
+ */
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Acquire the PID lockfile for the hook server.
+ *
+ * @param {string} planningDir - Path to .planning directory
+ * @param {number} port - Port the server will listen on
+ * @returns {{ acquired: boolean, reason?: string, pid?: number }}
+ */
+function acquireLock(planningDir, port) {
+  const lockPath = path.join(planningDir, LOCKFILE_NAME);
+
+  // Check existing lockfile
+  try {
+    const content = fs.readFileSync(lockPath, 'utf8');
+    const lock = JSON.parse(content);
+
+    if (lock.pid && isPidAlive(lock.pid)) {
+      if (lock.port === port) {
+        // Existing server is alive on the same port — don't replace it
+        return { acquired: false, reason: 'server-running', pid: lock.pid };
+      }
+      // PID alive but different port — still running, don't clobber
+      return { acquired: false, reason: 'server-running', pid: lock.pid };
+    }
+
+    // PID is dead — stale lockfile, clean it up
+    // Best-effort: remove stale file. Even if this fails, the write attempt below
+    // determines the real outcome — a write failure returns acquired: false.
+    try {
+      fs.unlinkSync(lockPath);
+    } catch (_e) {
+      // Best-effort removal
+    }
+  } catch (_e) {
+    // No lockfile or unreadable — proceed to create
+  }
+
+  // Write new lockfile
+  try {
+    const lockData = {
+      pid: process.pid,
+      port: port,
+      startedAt: new Date().toISOString()
+    };
+    fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2) + '\n', 'utf8');
+    return { acquired: true };
+  } catch (_e) {
+    // Can't write lockfile — fail closed (do not start server without durable lock)
+    return { acquired: false, reason: 'write-error', error: _e.message };
+  }
+}
+
+/**
+ * Release the PID lockfile. Only deletes if the lockfile belongs to this process.
+ *
+ * @param {string} planningDir - Path to .planning directory
+ */
+function releaseLock(planningDir) {
+  const lockPath = path.join(planningDir, LOCKFILE_NAME);
+
+  try {
+    const content = fs.readFileSync(lockPath, 'utf8');
+    const lock = JSON.parse(content);
+
+    // Only delete our own lockfile
+    if (lock.pid === process.pid) {
+      fs.unlinkSync(lockPath);
+    }
+  } catch (_e) {
+    // File missing or unreadable — no-op (fail-safe)
+  }
+}
+
+/**
+ * Check if the hook server is currently running based on lockfile state.
+ *
+ * @param {string} planningDir - Path to .planning directory
+ * @returns {{ running: boolean, pid: number|null, port: number|null }}
+ */
+function isServerRunning(planningDir) {
+  const lockPath = path.join(planningDir, LOCKFILE_NAME);
+
+  try {
+    const content = fs.readFileSync(lockPath, 'utf8');
+    const lock = JSON.parse(content);
+
+    if (lock.pid && isPidAlive(lock.pid)) {
+      return { running: true, pid: lock.pid, port: lock.port || null };
+    }
+
+    // Stale lockfile present — caller should re-acquire to trigger cleanup
+    return { running: false, pid: null, port: null };
+  } catch (_e) {
+    // No lockfile or unreadable
+    return { running: false, pid: null, port: null };
+  }
+}
+
+/**
+ * Update the port recorded in an existing lockfile owned by this process.
+ * Used when the server had to bind to a different port than originally requested.
+ *
+ * @param {string} planningDir - Path to .planning directory
+ * @param {number} newPort - The new port to record
+ * @returns {{ updated: boolean, reason?: string }}
+ */
+function updateLockPort(planningDir, newPort) {
+  const lockPath = path.join(planningDir, LOCKFILE_NAME);
+
+  try {
+    const content = fs.readFileSync(lockPath, 'utf8');
+    const lock = JSON.parse(content);
+
+    // Only update our own lockfile
+    if (lock.pid !== process.pid) {
+      return { updated: false, reason: 'not-owner' };
+    }
+
+    lock.port = newPort;
+    fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf8');
+    return { updated: true };
+  } catch (_e) {
+    return { updated: false, reason: 'io-error' };
+  }
+}
+
+module.exports = { acquireLock, releaseLock, isServerRunning, updateLockPort };

package/plugins/pbr/scripts/lib/post-hoc.js

@@ -0,0 +1,160 @@
+/**
+ * lib/post-hoc.cjs — Post-hoc SUMMARY.md generation from git history.
+ *
+ * Generates SUMMARY.md artifacts by analyzing git log and diff output
+ * after task execution, enabling zero-friction quick task workflows.
+ *
+ * Exports: generateSummary, parseGitLog, buildCommitGrep
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execGit, currentTimestamp } = require('./core');
+
+/**
+ * Parse git log --oneline output into structured commit data.
+ *
+ * @param {string} logOutput - Raw output from git log --oneline
+ * @returns {Array<{hash: string, type: string, scope: string, message: string}>}
+ */
+function parseGitLog(logOutput) {
+  if (!logOutput) return [];
+
+  const lines = logOutput.trim().split('\n').filter(Boolean);
+  const conventionalRe = /^(\S+)\s+(\w+)\(([^)]*)\):\s*(.+)$/;
+
+  return lines.map(line => {
+    const match = line.match(conventionalRe);
+    if (match) {
+      return { hash: match[1], type: match[2], scope: match[3], message: match[4] };
+    }
+    // Non-conventional: extract hash and rest as message
+    const parts = line.match(/^(\S+)\s+(.+)$/);
+    if (parts) {
+      return { hash: parts[1], type: 'unknown', scope: '', message: parts[2] };
+    }
+    return { hash: '', type: 'unknown', scope: '', message: line };
+  });
+}
+
+/**
+ * Build a grep pattern for matching commits by task ID.
+ *
+ * @param {string} taskId - Task identifier (e.g., 'quick-001', '03-01')
+ * @returns {string} Grep pattern string
+ */
+function buildCommitGrep(taskId) {
+  return taskId;
+}
+
+/**
+ * Generate a SUMMARY.md from git history for a completed task.
+ *
+ * @param {string} planningDir - Path to the .planning directory (or project root for git)
+ * @param {string} taskDir - Directory to write SUMMARY.md into
+ * @param {object} [options={}] - Generation options
+ * @param {string} [options.commitPattern] - Grep pattern to match commits (default: 'quick-\\d+')
+ * @param {string} [options.since] - ISO timestamp to limit git log range
+ * @param {string} [options.description] - Task description for the summary body
+ * @returns {{status: string, path: string, commitCount: number, keyFiles: string[]}}
+ */
+function generateSummary(planningDir, taskDir, options = {}) {
+  const summaryPath = path.join(taskDir, 'SUMMARY.md');
+  const grepPattern = options.commitPattern
+    ? buildCommitGrep(options.commitPattern)
+    : 'quick-\\d+';
+  const gitCwd = planningDir;
+
+  let commits = [];
+  let keyFiles = [];
+
+  try {
+    // Get matching commits
+    const logArgs = ['log', '--oneline', '--grep=' + grepPattern];
+    if (options.since) {
+      logArgs.push('--since=' + options.since);
+    }
+    const logOutput = execGit(gitCwd, logArgs);
+    commits = parseGitLog(logOutput);
+
+    // Get changed files if commits exist
+    if (commits.length > 0) {
+      try {
+        const diffOutput = execGit(gitCwd, ['diff', '--name-only', 'HEAD~' + commits.length + '..HEAD']);
+        keyFiles = diffOutput.trim().split('\n').filter(Boolean);
+      } catch (_e) {
+        // diff may fail for single-commit repos; fall back to show
+        try {
+          const showOutput = execGit(gitCwd, ['show', '--name-only', '--format=', commits[0].hash]);
+          keyFiles = showOutput.trim().split('\n').filter(Boolean);
+        } catch (_e2) {
+          // ignore
+        }
+      }
+    }
+  } catch (_e) {
+    // git commands failed entirely (empty repo, bad revision, etc.)
+  }
+
+  const status = commits.length > 0 ? 'complete' : 'failed';
+  const commitHashes = commits.map(c => c.hash);
+  const timestamp = currentTimestamp();
+
+  // Build SUMMARY.md content
+  const frontmatter = [
+    '---',
+    'status: "' + status + '"',
+    'requires: []',
+    'key_files:',
+    ...keyFiles.map(f => '  - "' + f + '"'),
+    'deferred: []',
+    'provides: []',
+    'key_decisions: []',
+    'patterns: []',
+    'generated: "post-hoc"',
+    'commits:',
+    ...commitHashes.map(h => '  - "' + h + '"'),
+    'timestamp: "' + timestamp + '"',
+    '---',
+  ].join('\n');
+
+  const description = options.description || 'Task completed.';
+
+  const changesSection = commits.length > 0
+    ? commits.map(c => '- ' + c.type + '(' + c.scope + '): ' + c.message + ' (`' + c.hash + '`)').join('\n')
+    : 'No commits found.';
+
+  const filesSection = keyFiles.length > 0
+    ? keyFiles.map(f => '- ' + f).join('\n')
+    : 'No files changed.';
+
+  const body = [
+    '',
+    '# Summary',
+    '',
+    description,
+    '',
+    '## Changes',
+    '',
+    changesSection,
+    '',
+    '## Files Modified',
+    '',
+    filesSection,
+    '',
+  ].join('\n');
+
+  const content = frontmatter + body;
+
+  // Ensure taskDir exists
+  fs.mkdirSync(taskDir, { recursive: true });
+  fs.writeFileSync(summaryPath, content, 'utf-8');
+
+  return { status, path: summaryPath, commitCount: commits.length, keyFiles };
+}
+
+module.exports = {
+  generateSummary,
+  parseGitLog,
+  buildCommitGrep,
+};

package/plugins/pbr/scripts/lib/pre-commit-checks.js

@@ -0,0 +1,220 @@
+'use strict';
+
+/**
+ * Pre-commit quality gate checks.
+ *
+ * Three advisory check functions that inspect staged files for common issues.
+ * Each returns null (no issues) or { warnings: string[] }.
+ * These never throw — all errors are caught and logged.
+ *
+ * Usage:
+ *   const { checkRequirePaths, checkMirrorSync, checkLintErrors } = require('./lib/pre-commit-checks');
+ *   const result = checkRequirePaths(data);
+ *   if (result) console.log(result.warnings);
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { logHook } = require('../hook-logger');
+
+/**
+ * Get list of staged files from git.
+ * @returns {string[]} Array of staged file paths (relative to repo root)
+ */
+function getStagedFiles() {
+  try {
+    const output = execSync('git diff --cached --name-only', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    return output.trim().split('\n').filter(Boolean);
+  } catch (_e) {
+    return [];
+  }
+}
+
+/**
+ * Check staged JS/CJS files under hooks/ and plan-build-run/bin/ for broken
+ * relative require() paths.
+ *
+ * @param {object} _data - Hook input data (unused, kept for interface consistency)
+ * @returns {null|{warnings: string[]}}
+ */
+function checkRequirePaths(_data) {
+  try {
+    const staged = getStagedFiles();
+    const jsFiles = staged.filter(f => {
+      const ext = path.extname(f);
+      return (ext === '.js' || ext === '.cjs') &&
+        (f.startsWith(path.join('hooks', '')) || f.startsWith('hooks/') ||
+         f.startsWith(path.join('plan-build-run', 'bin', '')) || f.startsWith('plan-build-run/bin/'));
+    });
+
+    if (jsFiles.length === 0) return null;
+
+    const warnings = [];
+
+    for (const file of jsFiles) {
+      let content;
+      try {
+        content = fs.readFileSync(file, 'utf8');
+      } catch (_e) {
+        continue; // File may not exist on disk yet (deleted in staging)
+      }
+
+      // Match require('...') calls with relative paths
+      const requireRegex = /require\(\s*['"](\.[^'"]+)['"]\s*\)/g;
+      let match;
+      while ((match = requireRegex.exec(content)) !== null) {
+        const reqPath = match[1];
+
+        // Skip dynamic expressions (template literals, concatenation)
+        if (reqPath.includes('${') || reqPath.includes('+')) continue;
+
+        const fileDir = path.dirname(file);
+        const resolved = path.resolve(fileDir, reqPath);
+
+        // Try the path as-is, then with common extensions
+        const candidates = [
+          resolved,
+          resolved + '.js',
+          resolved + '.cjs',
+          path.join(resolved, 'index.js'),
+          path.join(resolved, 'index.cjs')
+        ];
+
+        const exists = candidates.some(c => fs.existsSync(c));
+        if (!exists) {
+          warnings.push(`Broken require path in ${file}: require('${reqPath}') — resolved to ${resolved}`);
+        }
+      }
+    }
+
+    if (warnings.length === 0) return null;
+
+    logHook('pre-commit-checks', 'PreToolUse', 'warn-require-paths', { count: warnings.length });
+    return { warnings };
+  } catch (e) {
+    logHook('pre-commit-checks', 'PreToolUse', 'error', { fn: 'checkRequirePaths', error: e.message });
+    return null;
+  }
+}
+
+/**
+ * Mirror pair definitions: source -> mirror.
+ * When a file in source dir is staged, its counterpart in mirror dir should also be staged.
+ */
+const MIRROR_PAIRS = {
+  // Root commands/ directory removed — no mirror pairs needed
+};
+
+/**
+ * Check that mirrored files are staged together.
+ * Detects drift when one side of a mirror pair is modified but the other is not.
+ *
+ * @param {object} _data - Hook input data (unused)
+ * @returns {null|{warnings: string[]}}
+ */
+function checkMirrorSync(_data) {
+  try {
+    const staged = getStagedFiles();
+    if (staged.length === 0) return null;
+
+    const warnings = [];
+    const stagedSet = new Set(staged);
+
+    for (const [sourceDir, mirrorDir] of Object.entries(MIRROR_PAIRS)) {
+      // Normalize to forward slashes for comparison
+      const srcNorm = sourceDir.replace(/\\/g, '/');
+      const mirNorm = mirrorDir.replace(/\\/g, '/');
+
+      for (const file of staged) {
+        const fileNorm = file.replace(/\\/g, '/');
+        let counterpart = null;
+
+        if (fileNorm.startsWith(srcNorm)) {
+          const relative = fileNorm.slice(srcNorm.length);
+          counterpart = mirNorm + relative;
+        } else if (fileNorm.startsWith(mirNorm)) {
+          const relative = fileNorm.slice(mirNorm.length);
+          counterpart = srcNorm + relative;
+        }
+
+        if (!counterpart) continue;
+
+        // Check if counterpart is also staged
+        if (stagedSet.has(counterpart) || stagedSet.has(counterpart.replace(/\//g, path.sep))) {
+          continue; // Both sides staged — OK
+        }
+
+        // Check if counterpart exists on disk and has different content
+        const counterpartOnDisk = counterpart.replace(/\//g, path.sep);
+        if (!fs.existsSync(file) || !fs.existsSync(counterpartOnDisk)) continue;
+
+        try {
+          const srcContent = fs.readFileSync(file, 'utf8');
+          const mirContent = fs.readFileSync(counterpartOnDisk, 'utf8');
+          if (srcContent !== mirContent) {
+            warnings.push(`Mirror drift: ${file} was modified but ${counterpart} was not staged`);
+          }
+        } catch (_e) {
+          // Can't read one of the files — skip
+        }
+      }
+    }
+
+    if (warnings.length === 0) return null;
+
+    logHook('pre-commit-checks', 'PreToolUse', 'warn-mirror-sync', { count: warnings.length });
+    return { warnings };
+  } catch (e) {
+    logHook('pre-commit-checks', 'PreToolUse', 'error', { fn: 'checkMirrorSync', error: e.message });
+    return null;
+  }
+}
+
+/**
+ * Run eslint on staged JS/CJS files and report any errors.
+ *
+ * @param {object} _data - Hook input data (unused)
+ * @returns {null|{warnings: string[]}}
+ */
+function checkLintErrors(_data) {
+  try {
+    const staged = getStagedFiles();
+    const jsFiles = staged.filter(f => {
+      const ext = path.extname(f);
+      return ext === '.js' || ext === '.cjs';
+    });
+
+    if (jsFiles.length === 0) return null;
+
+    try {
+      const fileList = jsFiles.join(' ');
+      execSync(`npx eslint --quiet ${fileList}`, {
+        encoding: 'utf8',
+        timeout: 5000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+      // eslint exited 0 — no errors
+      return null;
+    } catch (lintErr) {
+      // eslint exited non-zero — lint errors found
+      if (lintErr.code === 'ENOENT') {
+        // eslint not available
+        return null;
+      }
+
+      const output = (lintErr.stdout || '') + (lintErr.stderr || '');
+      const errorCountMatch = output.match(/(\d+)\s+errors?/i);
+      const errorCount = errorCountMatch ? errorCountMatch[1] : 'unknown';
+
+      const warnings = [`Lint errors found in staged files (${errorCount} errors). Run 'npm run lint' for details.`];
+      logHook('pre-commit-checks', 'PreToolUse', 'warn-lint', { errorCount, fileCount: jsFiles.length });
+      return { warnings };
+    }
+  } catch (e) {
+    logHook('pre-commit-checks', 'PreToolUse', 'error', { fn: 'checkLintErrors', error: e.message });
+    return null;
+  }
+}
+
+module.exports = { checkRequirePaths, checkMirrorSync, checkLintErrors };

package/plugins/pbr/scripts/lib/pre-research.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+/**
+ * Pre-research trigger module.
+ *
+ * At 70%+ phase completion during SessionStart, emits a background
+ * research signal for the next phase. Uses idempotent signal files
+ * (.planning/.pre-research-{NN}) to ensure the advisory fires once.
+ *
+ * Pure advisory — no blocking, no side effects beyond signal file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { extractFrontmatter } = require('./frontmatter');
+
+/**
+ * Parse STATE.md frontmatter for current phase, progress, and status.
+ * Delegates to canonical extractFrontmatter and adapts return shape.
+ * @param {string} content - STATE.md content
+ * @returns {{ current_phase: number, progress_percent: number, status: string }}
+ */
+const parseStateFrontmatter = (content) => {
+  const fm = extractFrontmatter(content);
+  return {
+    current_phase: parseInt(fm.current_phase, 10) || 0,
+    progress_percent: parseInt(fm.progress_percent, 10) || 0,
+    status: fm.status || ''
+  };
+};
+
+/**
+ * Find the name of a phase from ROADMAP.md checklist.
+ * Looks for: - [ ] Phase N: Name  or  ### Phase N: Name
+ * @param {string} content - ROADMAP.md content
+ * @param {number} phaseNum - Phase number to find
+ * @returns {string|null} Phase name or null
+ */
+function findPhaseName(content, phaseNum) {
+  // Try checklist format first: - [ ] Phase N: Name
+  const checkRegex = new RegExp(`- \\[[ x]\\] Phase ${phaseNum}:\\s*(.+)`, 'i');
+  const checkMatch = content.match(checkRegex);
+  if (checkMatch) return checkMatch[1].trim();
+
+  // Try heading format: ### Phase N: Name
+  const headingRegex = new RegExp(`### Phase ${phaseNum}:\\s*(.+)`, 'i');
+  const headingMatch = content.match(headingRegex);
+  if (headingMatch) return headingMatch[1].trim();
+
+  return null;
+}
+
+/**
+ * Check if the current phase is far enough along to trigger pre-research
+ * for the next phase. Returns an advisory object or null.
+ *
+ * @param {string} planningDir - Absolute path to .planning/ directory
+ * @param {object} config - Loaded config object
+ * @returns {{ nextPhase: number, name: string, command: string } | null}
+ */
+function checkPreResearch(planningDir, config) {
+  // Feature gate
+  if (config && config.features && config.features.pre_research === false) {
+    return null;
+  }
+
+  // Read STATE.md
+  const statePath = path.join(planningDir, 'STATE.md');
+  let stateContent;
+  try {
+    stateContent = fs.readFileSync(statePath, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+
+  const state = parseStateFrontmatter(stateContent);
+
+  // Skip if phase is already verified/complete
+  if (state.status === 'verified' || state.status === 'complete') {
+    return null;
+  }
+
+  // Skip if progress below threshold
+  if (state.progress_percent < 70) {
+    return null;
+  }
+
+  // Compute next phase number
+  const nextPhase = state.current_phase + 1;
+
+  // Check signal file for idempotency
+  const paddedNext = String(nextPhase).padStart(2, '0');
+  const signalPath = path.join(planningDir, `.pre-research-${paddedNext}`);
+  if (fs.existsSync(signalPath)) {
+    return null;
+  }
+
+  // Read ROADMAP.md to check if next phase exists
+  const roadmapPath = path.join(planningDir, 'ROADMAP.md');
+  let roadmapContent;
+  try {
+    roadmapContent = fs.readFileSync(roadmapPath, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+
+  const phaseName = findPhaseName(roadmapContent, nextPhase);
+  if (!phaseName) {
+    return null;
+  }
+
+  // Write signal file to prevent re-triggering
+  try {
+    fs.writeFileSync(signalPath, new Date().toISOString(), 'utf8');
+  } catch (_e) {
+    // Non-fatal — advisory still works, just won't be idempotent
+  }
+
+  return {
+    nextPhase,
+    name: phaseName,
+    command: `/pbr:explore ${nextPhase}`
+  };
+}
+
+module.exports = { checkPreResearch };