@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/plugins/pbr/scripts/lib/parse-args.js

@@ -0,0 +1,134 @@
+/**
+ * parse-args.js — CLI argument parsing and validation for PBR skills.
+ *
+ * Provides structured validation of user input before skills process it,
+ * replacing fragile prose-based guards with deterministic CLI checks.
+ */
+
+'use strict';
+
+/**
+ * Parse and validate arguments for /pbr:plan
+ *
+ * Valid patterns:
+ *   ""              → empty, skill will prompt
+ *   "3" or "03"     → bare phase number
+ *   "3 --gaps"      → phase number with flags
+ *   "3 --gaps --auto" → phase number with multiple flags
+ *
+ * Invalid:
+ *   "write me a function" → freeform text
+ *   "3 4 5"               → multiple numbers
+ *   "auth-module"         → non-numeric non-flag token
+ */
+function parsePlan(rawInput) {
+  const raw = (rawInput || '').trim();
+
+  // Empty input is valid — skill will prompt for phase number
+  if (!raw) {
+    return { valid: true, phase: null, flags: {}, raw: '' };
+  }
+
+  const tokens = raw.split(/\s+/);
+  const flags = { gaps: false, auto: false };
+  const knownFlags = new Set(['--gaps', '--auto']);
+  let phase = null;
+  const nonFlagTokens = [];
+
+  for (const token of tokens) {
+    if (token.startsWith('--')) {
+      if (knownFlags.has(token)) {
+        flags[token.slice(2)] = true;
+      } else {
+        return {
+          valid: false,
+          phase: null,
+          flags: {},
+          error: `Unknown flag: '${token}'. Expected: /pbr:plan <phase-number> [--gaps] [--auto]`,
+          raw
+        };
+      }
+    } else {
+      nonFlagTokens.push(token);
+    }
+  }
+
+  // Must have exactly 0 or 1 non-flag tokens
+  if (nonFlagTokens.length > 1) {
+    return {
+      valid: false,
+      phase: null,
+      flags: {},
+      error: `Invalid argument: '${raw}'. Expected: /pbr:plan <phase-number> [--gaps] [--auto]`,
+      raw
+    };
+  }
+
+  if (nonFlagTokens.length === 1) {
+    const candidate = nonFlagTokens[0];
+    // Must be a number (with optional leading zeros)
+    if (/^\d+$/.test(candidate)) {
+      phase = parseInt(candidate, 10);
+    } else {
+      return {
+        valid: false,
+        phase: null,
+        flags: {},
+        error: `Invalid argument: '${candidate}'. Expected: /pbr:plan <phase-number> [--gaps] [--auto]`,
+        raw
+      };
+    }
+  }
+
+  // Flags without a phase number are invalid (e.g. "--gaps" alone)
+  if (phase === null && (flags.gaps || flags.auto)) {
+    return {
+      valid: false,
+      phase: null,
+      flags: {},
+      error: `Flags require a phase number. Expected: /pbr:plan <phase-number> [--gaps] [--auto]`,
+      raw
+    };
+  }
+
+  return { valid: true, phase, flags, raw };
+}
+
+/**
+ * Parse and validate arguments for /pbr:quick
+ *
+ * Quick accepts freeform text as a task description. Always valid unless empty.
+ */
+function parseQuick(rawInput) {
+  const raw = (rawInput || '').trim();
+
+  if (!raw) {
+    return {
+      valid: false,
+      description: null,
+      error: 'Description required for /pbr:quick',
+      raw: ''
+    };
+  }
+
+  return { valid: true, description: raw, raw };
+}
+
+/**
+ * Dispatch parse-args by type
+ */
+function parseArgs(type, rawInput) {
+  switch (type) {
+    case 'plan':
+      return parsePlan(rawInput);
+    case 'quick':
+      return parseQuick(rawInput);
+    default:
+      return {
+        valid: false,
+        error: `Unknown parse-args type: '${type}'. Supported: plan, quick`
+      };
+  }
+}
+
+module.exports = { parseArgs, parsePlan, parseQuick };

package/plugins/pbr/scripts/lib/pattern-routing.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+/**
+ * Pattern-based file routing module.
+ *
+ * Matches file writes against configurable patterns and returns
+ * context-appropriate advisory messages. Used as a lowest-priority
+ * fallback in post-write-dispatch.js.
+ *
+ * Pure function — no side effects, no file writes.
+ */
+
+/**
+ * Default pattern rules, ordered by priority (first match wins).
+ * Security patterns come first to catch auth-related test files correctly.
+ */
+const DEFAULT_PATTERNS = [
+  { pattern: /\.(env|secret|credential)/i, advisory: 'Security-sensitive file — consider /pbr:review for thorough review' },
+  { pattern: /\b(auth|permission|rbac|acl)\b/i, advisory: 'Security-sensitive file — consider /pbr:review for thorough review' },
+  { pattern: /\.(test|spec)\.(js|ts|jsx|tsx|cjs|mjs)$/i, advisory: 'Test file modified — ensure corresponding source file is updated' },
+  { pattern: /(schema|migration)\b/i, advisory: 'Schema change detected — check for required migrations' },
+  { pattern: /(config|tsconfig|jest\.config|vite\.config)\.(json|js|ts|cjs|mjs)$/i, advisory: 'Config change — verify downstream consumers' },
+  { pattern: /hooks[/\\].*\.js$/i, advisory: 'Hook script modified — run npm test to verify cross-platform' },
+];
+
+/**
+ * Check if a file path matches any defined pattern and return an advisory.
+ *
+ * @param {string} filePath - Path to the file being written
+ * @param {object} config - Loaded config object
+ * @returns {{ pattern: string, advisory: string } | null}
+ */
+function checkPatternRouting(filePath, config) {
+  // Feature gate
+  if (config && config.features && config.features.pattern_routing === false) {
+    return null;
+  }
+
+  // Normalize path: replace backslashes with forward slashes
+  const normalized = filePath.replace(/\\/g, '/');
+
+  // Iterate patterns in priority order, return first match
+  for (const rule of DEFAULT_PATTERNS) {
+    if (rule.pattern.test(normalized)) {
+      return {
+        pattern: rule.pattern.source,
+        advisory: rule.advisory
+      };
+    }
+  }
+
+  return null;
+}
+
+module.exports = { checkPatternRouting, DEFAULT_PATTERNS };

package/plugins/pbr/scripts/lib/patterns.js

@@ -0,0 +1,272 @@
+'use strict';
+
+/**
+ * patterns.cjs -- Cross-project pattern library for Plan-Build-Run.
+ *
+ * Storage: JSON files in ~/.claude/patterns/
+ * Schema: id, name, source_project, type, tags, description, files,
+ *         template_content, confidence, created_at
+ *
+ * Usage (library):
+ *   const { patternExtract, patternQuery, patternList } = require('./patterns');
+ *
+ * Usage (CLI via pbr-tools.js):
+ *   node pbr-tools.js patterns extract <json-file>
+ *   node pbr-tools.js patterns query [--tags X,Y] [--type T] [--stack S]
+ *   node pbr-tools.js patterns list
+ */
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// --- Constants ---
+
+const PATTERNS_DIR = path.join(os.homedir(), '.claude', 'patterns');
+
+const PATTERN_TYPES = [
+  'architecture',
+  'testing',
+  'auth',
+  'crud',
+  'deployment',
+  'error-handling',
+  'api-design',
+  'data-model',
+];
+
+// --- Shared I/O helpers ---
+
+/**
+ * Read all JSON files from a directory, returning parsed objects.
+ * Skips malformed files.
+ * @param {string} dir
+ * @returns {object[]}
+ */
+function readJsonDir(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter(f => f.endsWith('.json'))
+    .reduce((acc, f) => {
+      try {
+        acc.push(JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')));
+      } catch (_e) {
+        // Skip malformed files
+      }
+      return acc;
+    }, []);
+}
+
+/**
+ * Write a JSON object to a file, creating parent dirs as needed.
+ * @param {string} filePath
+ * @param {object} data
+ */
+function writeJsonFile(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+/**
+ * Append a JSONL entry to an audit log file.
+ * @param {string} logDir
+ * @param {object} entry
+ */
+function appendAuditLog(logDir, entry) {
+  if (!logDir) return;
+  try {
+    fs.mkdirSync(logDir, { recursive: true });
+    const logPath = path.join(logDir, 'cross-project.jsonl');
+    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf8');
+  } catch (_e) {
+    // Non-fatal: audit log failures must not break operations
+  }
+}
+
+/**
+ * Sanitize a name for use as a filename.
+ * Replaces non-alphanumeric characters with hyphens.
+ * @param {string} name
+ * @returns {string}
+ */
+function sanitizeName(name) {
+  return name.replace(/[^a-zA-Z0-9]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+
+// --- Core functions ---
+
+/**
+ * Extract a pattern and store it in basePath.
+ * Deduplicates by name+source_project: updates existing if found.
+ *
+ * @param {object} entry - Pattern entry to store
+ * @param {{ basePath?: string, configFeatures?: object, logDir?: string }} [options]
+ * @returns {{ action: 'created'|'updated', pattern: object } | { enabled: false }}
+ */
+function patternExtract(entry, options = {}) {
+  const configFeatures = options.configFeatures || {};
+  if (configFeatures.cross_project_patterns === false) {
+    return { enabled: false };
+  }
+
+  const basePath = options.basePath || PATTERNS_DIR;
+  const logDir = options.logDir;
+
+  // Validate required fields
+  const required = ['name', 'source_project', 'type', 'tags', 'description'];
+  const missing = required.filter(f => entry[f] === undefined || entry[f] === null);
+  if (missing.length > 0) {
+    throw new Error(`Missing required pattern fields: ${missing.join(', ')}`);
+  }
+
+  // Build full pattern object
+  const pattern = Object.assign({}, entry);
+  if (!pattern.id) {
+    try {
+      pattern.id = crypto.randomUUID();
+    } catch (_e) {
+      pattern.id = Date.now().toString(36) + Math.random().toString(36).slice(2);
+    }
+  }
+  if (!pattern.created_at) {
+    pattern.created_at = new Date().toISOString();
+  }
+
+  const sanitized = sanitizeName(pattern.name);
+  const filePath = path.join(basePath, `${sanitized}.json`);
+
+  // Check for existing entry with same name (dedup)
+  let action = 'created';
+  if (fs.existsSync(filePath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      if (existing.name === pattern.name && existing.source_project === pattern.source_project) {
+        // Merge: union tags, bump confidence
+        const mergedTags = Array.from(new Set([...(existing.tags || []), ...(pattern.tags || [])]));
+        const merged = Object.assign({}, existing, pattern, {
+          tags: mergedTags,
+          updated_at: new Date().toISOString(),
+        });
+        writeJsonFile(filePath, merged);
+        appendAuditLog(logDir, {
+          timestamp: new Date().toISOString(),
+          operation: 'pattern-extract',
+          feature: 'cross_project_patterns',
+          detail: { name: pattern.name, tags: mergedTags },
+        });
+        return { action: 'updated', pattern: merged };
+      }
+    } catch (_e) {
+      // File unreadable — overwrite
+    }
+  }
+
+  writeJsonFile(filePath, pattern);
+  appendAuditLog(logDir, {
+    timestamp: new Date().toISOString(),
+    operation: 'pattern-extract',
+    feature: 'cross_project_patterns',
+    detail: { name: pattern.name, tags: pattern.tags },
+  });
+
+  return { action, pattern };
+}
+
+/**
+ * Query patterns with optional filters.
+ *
+ * @param {{ tags?: string[], type?: string, stack?: string, minConfidence?: number }} [filters]
+ * @param {{ basePath?: string, configFeatures?: object, logDir?: string }} [options]
+ * @returns {object[] | { enabled: false }}
+ */
+function patternQuery(filters = {}, options = {}) {
+  const configFeatures = options.configFeatures || {};
+  if (configFeatures.cross_project_patterns === false) {
+    return { enabled: false };
+  }
+
+  const basePath = options.basePath || PATTERNS_DIR;
+  const logDir = options.logDir;
+
+  let patterns = readJsonDir(basePath);
+
+  // Filter by tags (ALL must be present)
+  if (filters.tags && filters.tags.length > 0) {
+    patterns = patterns.filter(p => {
+      const pTags = p.tags || [];
+      return filters.tags.every(t => pTags.includes(t));
+    });
+  }
+
+  // Filter by type (exact match)
+  if (filters.type) {
+    patterns = patterns.filter(p => p.type === filters.type);
+  }
+
+  // Filter by stack (tag prefix "stack:")
+  if (filters.stack) {
+    const stackTag = `stack:${filters.stack}`;
+    patterns = patterns.filter(p => {
+      const pTags = p.tags || [];
+      return pTags.includes(stackTag);
+    });
+  }
+
+  // Filter by minConfidence
+  if (filters.minConfidence !== undefined) {
+    patterns = patterns.filter(p => (p.confidence || 0) >= filters.minConfidence);
+  }
+
+  // Sort by confidence descending, then created_at descending
+  patterns.sort((a, b) => {
+    const confDiff = (b.confidence || 0) - (a.confidence || 0);
+    if (confDiff !== 0) return confDiff;
+    return (b.created_at || '') > (a.created_at || '') ? 1 : -1;
+  });
+
+  appendAuditLog(logDir, {
+    timestamp: new Date().toISOString(),
+    operation: 'pattern-query',
+    feature: 'cross_project_patterns',
+    detail: { tags: filters.tags, type: filters.type },
+  });
+
+  return patterns;
+}
+
+/**
+ * List all patterns (summary fields only).
+ *
+ * @param {{ basePath?: string, configFeatures?: object }} [options]
+ * @returns {Array<{ name, type, tags, source_project, confidence }> | { enabled: false }}
+ */
+function patternList(options = {}) {
+  const configFeatures = options.configFeatures || {};
+  if (configFeatures.cross_project_patterns === false) {
+    return { enabled: false };
+  }
+
+  const basePath = options.basePath || PATTERNS_DIR;
+  const patterns = readJsonDir(basePath);
+
+  return patterns.map(p => ({
+    name: p.name,
+    type: p.type,
+    tags: p.tags,
+    source_project: p.source_project,
+    confidence: p.confidence,
+  }));
+}
+
+// --- Exports ---
+
+module.exports = {
+  PATTERNS_DIR,
+  PATTERN_TYPES,
+  patternExtract,
+  patternQuery,
+  patternList,
+  // Shared helpers (used by templates.cjs)
+  appendAuditLog,
+};

package/plugins/pbr/scripts/lib/perf.js

@@ -0,0 +1,190 @@
+'use strict';
+
+/**
+ * lib/perf.js — Performance metric utilities for Plan-Build-Run hooks.
+ *
+ * Provides percentile calculation, hook performance summarization,
+ * and formatted table output with regression detection.
+ */
+
+/**
+ * Compute a percentile value from a pre-sorted ascending numeric array.
+ * Uses the nearest-rank method.
+ *
+ * @param {number[]} sortedArr - Numeric array sorted ascending
+ * @param {number} p - Percentile (0-100)
+ * @returns {number|null} The percentile value, or null if array is empty
+ */
+function percentile(sortedArr, p) {
+  if (!sortedArr || sortedArr.length === 0) return null;
+  const idx = Math.max(0, Math.min(Math.ceil(p / 100 * sortedArr.length) - 1, sortedArr.length - 1));
+  return sortedArr[idx];
+}
+
+/**
+ * Compute stats (count, p50, p95, p99, min, max) for a sorted array of durations.
+ * @param {number[]} sorted
+ * @returns {{ count: number, p50: number|null, p95: number|null, p99: number|null, min: number, max: number }}
+ */
+function computeStats(sorted) {
+  return {
+    count: sorted.length,
+    p50: percentile(sorted, 50),
+    p95: percentile(sorted, 95),
+    p99: percentile(sorted, 99),
+    min: sorted[0],
+    max: sorted[sorted.length - 1]
+  };
+}
+
+/**
+ * Summarize hook performance from JSONL event entries.
+ *
+ * @param {object[]} entries - Array of parsed JSONL event objects
+ * @returns {{ byHook: object, byEvent: object }} Grouped performance stats
+ */
+function summarizeHookPerf(entries) {
+  const withDuration = (entries || []).filter(e => typeof e.duration_ms === 'number');
+
+  const byHookMap = {};
+  const byEventMap = {};
+
+  for (const entry of withDuration) {
+    const hookKey = entry.hook || '(unknown)';
+    const eventKey = entry.event || '(unknown)';
+
+    if (!byHookMap[hookKey]) byHookMap[hookKey] = [];
+    byHookMap[hookKey].push(entry.duration_ms);
+
+    if (!byEventMap[eventKey]) byEventMap[eventKey] = [];
+    byEventMap[eventKey].push(entry.duration_ms);
+  }
+
+  const byHook = {};
+  for (const [key, durations] of Object.entries(byHookMap)) {
+    durations.sort((a, b) => a - b);
+    byHook[key] = computeStats(durations);
+  }
+
+  const byEvent = {};
+  for (const [key, durations] of Object.entries(byEventMap)) {
+    durations.sort((a, b) => a - b);
+    byEvent[key] = computeStats(durations);
+  }
+
+  return { byHook, byEvent };
+}
+
+/**
+ * Format a performance summary as a plain-text table.
+ *
+ * @param {{ byHook: object, byEvent: object }} summary - Output of summarizeHookPerf()
+ * @returns {string} Plain-text table (no ANSI codes)
+ */
+function formatPerfTable(summary) {
+  const pad = (str, width) => String(str).padEnd(width);
+  const rpad = (val, width) => String(val === null ? '-' : val).padStart(width);
+
+  function buildTable(title, data) {
+    const lines = [];
+    lines.push(title);
+    lines.push(pad('Name', 30) + rpad('Count', 7) + rpad('P50', 7) + rpad('P95', 7) + rpad('P99', 7) + rpad('Max', 7));
+    lines.push('-'.repeat(65));
+
+    const keys = Object.keys(data).sort();
+    for (const key of keys) {
+      const s = data[key];
+      let row = pad(key.length > 29 ? key.slice(0, 29) : key, 30)
+        + rpad(s.count, 7)
+        + rpad(s.p50, 7)
+        + rpad(s.p95, 7)
+        + rpad(s.p99, 7)
+        + rpad(s.max, 7);
+      if (s.max >= 100) {
+        row += ' *** ALERT';
+      }
+      lines.push(row);
+    }
+
+    return lines.join('\n');
+  }
+
+  const hookTable = buildTable('== By Hook ==', summary.byHook || {});
+  const eventTable = buildTable('== By Event ==', summary.byEvent || {});
+
+  return hookTable + '\n\n' + eventTable;
+}
+
+/**
+ * Load performance entries from hooks JSONL log files.
+ *
+ * @param {string} planningDir - Path to the .planning/ directory
+ * @param {{ last?: number }} [opts] - Options: last = max days of log files to include
+ * @returns {object[]} Flat array of matching entry objects with duration_ms and transport === 'http'
+ */
+function loadPerfEntries(planningDir, opts) {
+  const fs = require('fs');
+  const path = require('path');
+  const logsDir = path.join(planningDir, 'logs');
+  const entries = [];
+
+  // Determine cutoff date if --last N is specified
+  let cutoffDate = null;
+  if (opts && typeof opts.last === 'number' && opts.last > 0) {
+    const d = new Date();
+    d.setDate(d.getDate() - opts.last);
+    cutoffDate = d.toISOString().slice(0, 10); // YYYY-MM-DD
+  }
+
+  // Collect files to read
+  const files = [];
+
+  // Read hooks-*.jsonl from logs dir
+  try {
+    const dirEntries = fs.readdirSync(logsDir);
+    for (const fname of dirEntries) {
+      const match = fname.match(/^hooks-(\d{4}-\d{2}-\d{2})\.jsonl$/);
+      if (match) {
+        if (cutoffDate && match[1] < cutoffDate) continue;
+        files.push(path.join(logsDir, fname));
+      }
+    }
+  } catch (_e) {
+    // logsDir may not exist — skip silently
+  }
+
+  // Also read .hook-events.jsonl in planningDir if it exists
+  const eventsFile = path.join(planningDir, '.hook-events.jsonl');
+  try {
+    fs.accessSync(eventsFile, fs.constants.R_OK);
+    files.push(eventsFile);
+  } catch (_e) {
+    // File doesn't exist — skip
+  }
+
+  // Parse each file
+  for (const filePath of files) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const lines = content.split('\n');
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          const entry = JSON.parse(trimmed);
+          if (typeof entry.duration_ms === 'number' && entry.transport === 'http') {
+            entries.push(entry);
+          }
+        } catch (_e) {
+          // Skip malformed lines
+        }
+      }
+    } catch (_e) {
+      // Skip unreadable files silently
+    }
+  }
+
+  return entries;
+}
+
+module.exports = { percentile, summarizeHookPerf, formatPerfTable, loadPerfEntries };