@sienklogic/plan-build-run 2.0.2 → 2.1.1

package/plan-build-run/bin/lib/skill-section.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * skill-section.cjs -- Targeted SKILL.md section extraction for Plan-Build-Run.
+ *
+ * Enables surgical extraction of specific sections from skill files (SKILL.md),
+ * reducing token usage by fetching only the needed section on demand.
+ *
+ * Exported functions:
+ *   skillSection(skillName, sectionQuery, pluginRoot)  -- Main entry point
+ *   resolveSkillPath(skillName, pluginRoot)            -- Resolve skill name to file path
+ *   listAvailableSkills(pluginRoot)                    -- List all available skill names
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { extractSection, listHeadings } = require('./reference.cjs');
+
+/**
+ * Resolve a skill name to its SKILL.md file path.
+ *
+ * @param {string} skillName - Skill name (e.g., "build", "plan")
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {string | null} - Full path to SKILL.md, or null if not found
+ */
+function resolveSkillPath(skillName, pluginRoot) {
+  const skillPath = path.join(pluginRoot, 'skills', skillName, 'SKILL.md');
+  if (!fs.existsSync(skillPath)) return null;
+  return skillPath;
+}
+
+/**
+ * List all available skill names from the skills/ directory.
+ *
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {string[]} - Array of skill names (directory names)
+ */
+function listAvailableSkills(pluginRoot) {
+  const skillsDir = path.join(pluginRoot, 'skills');
+  try {
+    return fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name);
+  } catch (_e) {
+    return [];
+  }
+}
+
+/**
+ * Extract a specific section from a skill's SKILL.md.
+ *
+ * @param {string} skillName - Skill name (e.g., "build", "plan")
+ * @param {string} sectionQuery - Section heading query (fuzzy matched)
+ * @param {string} pluginRoot - Plugin root directory
+ * @returns {object} - { skill, section, heading, content, char_count } or { error, available? }
+ */
+function skillSection(skillName, sectionQuery, pluginRoot) {
+  // Validate section query
+  if (!sectionQuery || !sectionQuery.trim()) {
+    return { error: 'Section query required' };
+  }
+
+  // Resolve skill path
+  const skillPath = resolveSkillPath(skillName, pluginRoot);
+  if (!skillPath) {
+    return {
+      error: `Skill not found: ${skillName}`,
+      available: listAvailableSkills(pluginRoot)
+    };
+  }
+
+  // Read skill content
+  let content;
+  try {
+    content = fs.readFileSync(skillPath, 'utf8');
+  } catch (e) {
+    return { error: `Cannot read skill file: ${e.message}` };
+  }
+
+  // Normalize query: replace hyphens with spaces for better fuzzy matching
+  const normalizedQuery = sectionQuery.replace(/-/g, ' ');
+
+  // Extract the requested section (try normalized first, then original)
+  let result = extractSection(content, normalizedQuery);
+  if (!result && normalizedQuery !== sectionQuery) {
+    result = extractSection(content, sectionQuery);
+  }
+  if (!result) {
+    return {
+      error: `Section '${sectionQuery}' not found in skill '${skillName}'`,
+      available: listHeadings(content)
+    };
+  }
+
+  return { skill: skillName, section: sectionQuery, ...result };
+}
+
+module.exports = { skillSection, resolveSkillPath, listAvailableSkills };

package/plan-build-run/bin/lib/spot-check.cjs

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * lib/spot-check.cjs -- Machine-enforced wave gate spot check.
+ *
+ * Verifies that a completed plan's SUMMARY file exists, lists real key_files
+ * that exist on disk, and has a non-empty commits field.
+ *
+ * Used by pbr-tools.cjs `spot-check <phaseSlug> <planId>` subcommand.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseYamlFrontmatter } = require('./core.cjs');
+
+/**
+ * Perform a spot-check on a completed plan's SUMMARY artifact.
+ *
+ * @param {string} planningDir  - Absolute path to the .planning/ directory
+ * @param {string} phaseSlug    - Phase directory name (e.g. "49-build-workflow-hardening")
+ * @param {string} planId       - Plan identifier (e.g. "49-01")
+ * @returns {{
+ *   ok: boolean,
+ *   summary_exists: boolean,
+ *   key_files_checked: Array<{path: string, exists: boolean}>,
+ *   commits_present: boolean,
+ *   detail: string
+ * }}
+ */
+function spotCheck(planningDir, phaseSlug, planId) {
+  const summaryPath = path.join(planningDir, 'phases', phaseSlug, 'SUMMARY-' + planId + '.md');
+
+  // Check 1: SUMMARY file must exist
+  if (!fs.existsSync(summaryPath)) {
+    return {
+      ok: false,
+      summary_exists: false,
+      key_files_checked: [],
+      commits_present: false,
+      detail: 'SUMMARY-' + planId + '.md not found'
+    };
+  }
+
+  // Read and parse SUMMARY frontmatter
+  let content;
+  try {
+    content = fs.readFileSync(summaryPath, 'utf8');
+  } catch (e) {
+    return {
+      ok: false,
+      summary_exists: true,
+      key_files_checked: [],
+      commits_present: false,
+      detail: 'Failed to read SUMMARY: ' + e.message
+    };
+  }
+
+  const fm = parseYamlFrontmatter(content);
+  const failures = [];
+
+  // Check 2: key_files -- check first 2 entries for existence on disk
+  const repoRoot = path.resolve(path.join(planningDir, '..'));
+  const rawKeyFiles = Array.isArray(fm.key_files) ? fm.key_files : [];
+  const toCheck = rawKeyFiles.slice(0, 2);
+
+  const key_files_checked = toCheck.map(kf => {
+    const absPath = path.resolve(repoRoot, kf);
+    const exists = fs.existsSync(absPath);
+    return { path: kf, exists };
+  });
+
+  const missingFiles = key_files_checked.filter(kf => !kf.exists);
+  if (missingFiles.length > 0) {
+    failures.push('missing key_files: ' + missingFiles.map(kf => kf.path).join(', '));
+  }
+
+  // Check 3: commits field must be non-empty
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  let commits_present = false;
+
+  if (fmMatch) {
+    const fmBlock = fmMatch[1];
+    const commitsMatch = fmBlock.match(/commits:\s*(\[.*?\]|.*)/);
+    if (commitsMatch) {
+      const commitsVal = commitsMatch[1].trim();
+      // Treat these as empty: [], '', ~, null
+      commits_present = !(
+        commitsVal === '[]' ||
+        commitsVal === '' ||
+        commitsVal === '~' ||
+        commitsVal === 'null' ||
+        commitsVal === '""'
+      );
+    }
+  } else {
+    // No frontmatter found at all
+    failures.push('no frontmatter found in SUMMARY');
+  }
+
+  if (!commits_present) {
+    failures.push('commits field is empty or missing');
+  }
+
+  const ok = missingFiles.length === 0 && commits_present && (fmMatch !== null);
+  const detail = failures.length === 0 ? 'all checks passed' : failures.join('; ');
+
+  return {
+    ok,
+    summary_exists: true,
+    key_files_checked,
+    commits_present,
+    detail
+  };
+}
+
+module.exports = { spotCheck };