godpowers 2.4.1 → 2.4.3

package/bin/install.js

@@ -187,25 +187,20 @@ function runExtensionScaffoldCommand(opts) {
   }
 }
 
+const COMMAND_RUNNERS = {
+  status: runDashboardCommand,
+  next: runDashboardCommand,
+  'quick-proof': runQuickProofCommand,
+  'automation-status': runAutomationCommand,
+  'automation-setup': runAutomationCommand,
+  dogfood: runDogfoodCommand,
+  'extension-scaffold': runExtensionScaffoldCommand
+};
+
 function runCommand(opts) {
-  if (opts.command === 'status' || opts.command === 'next') {
-    runDashboardCommand(opts);
-    return true;
-  }
-  if (opts.command === 'quick-proof') {
-    runQuickProofCommand(opts);
-    return true;
-  }
-  if (opts.command === 'automation-status' || opts.command === 'automation-setup') {
-    runAutomationCommand(opts);
-    return true;
-  }
-  if (opts.command === 'dogfood') {
-    runDogfoodCommand(opts);
-    return true;
-  }
-  if (opts.command === 'extension-scaffold') {
-    runExtensionScaffoldCommand(opts);
+  const runner = COMMAND_RUNNERS[opts.command];
+  if (runner) {
+    runner(opts);
     return true;
   }
   return false;
@@ -299,11 +294,19 @@ function main() {
   }
 }
 
-main();
+if (require.main === module) {
+  main();
+}
 
 module.exports = {
   showHelp,
+  COMMAND_RUNNERS,
   runCommand,
+  runAutomationCommand,
+  runDashboardCommand,
+  runDogfoodCommand,
+  runQuickProofCommand,
+  runExtensionScaffoldCommand,
   applyDefaultRuntimeSelection,
   runInstall,
   runUninstall,

package/lib/README.md

@@ -11,6 +11,7 @@ package-level integrations.
 | `state.js` | Read, initialize, validate, and write `.godpowers/state.json`. |
 | `state-lock.js` | Coordinate state writes with a lock file. |
 | `intent.js` | Read and validate `intent.yaml` from project roots or `.godpowers/`. |
+| `frontmatter.js` | Parse shared markdown YAML frontmatter for skills, agents, Pillars, checkpoints, and design specs. |
 | `checkpoint.js` | Create and inspect resumable checkpoint artifacts. |
 | `feature-awareness.js` | Detect and refresh existing-project awareness after runtime upgrades. |
 | `code-intelligence.js` | Detect optional `ast-grep`, `sg`, and LSP tooling for structural search, rewrite, and diagnostics guidance. |

package/lib/agent-validator.js

@@ -18,6 +18,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const frontmatter = require('./frontmatter');
 
 const REQUIRED_FRONTMATTER = ['name', 'description'];
 const RECOMMENDED_FRONTMATTER = ['tools'];
@@ -37,33 +38,7 @@ function parseAgentFile(filePath) {
     raw
   };
 
-  // Frontmatter block: --- ... ---
-  if (raw.startsWith('---')) {
-    const end = raw.indexOf('\n---', 3);
-    if (end > 0) {
-      const fmBlock = raw.slice(3, end).trim();
-      // Parse simple YAML (key: value, key: |, etc.)
-      let currentMultiline = null;
-      for (const line of fmBlock.split('\n')) {
-        if (currentMultiline) {
-          if (line.startsWith(' ') || line.startsWith('\t')) {
-            result.frontmatter[currentMultiline] += '\n' + line.trim();
-            continue;
-          }
-          currentMultiline = null;
-        }
-        const m = line.match(/^([\w-]+):\s*(.*)$/);
-        if (m) {
-          if (m[2] === '|' || m[2] === '>') {
-            currentMultiline = m[1];
-            result.frontmatter[m[1]] = '';
-          } else {
-            result.frontmatter[m[1]] = m[2].trim();
-          }
-        }
-      }
-    }
-  }
+  result.frontmatter = frontmatter.parse(raw, { strict: true, source: filePath });
 
   // Sections: lines starting with # / ## / ###
   const lines = raw.split('\n');

package/lib/checkpoint.js

@@ -50,6 +50,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const atomic = require('./atomic-write');
+const frontmatterLib = require('./frontmatter');
 
 const MAX_ACTIONS = 20;
 const MAX_FACTS = 10;
@@ -74,25 +75,9 @@ function read(projectRoot) {
   if (!fs.existsSync(file)) return null;
   const raw = fs.readFileSync(file, 'utf8');
 
-  // Frontmatter parse
-  let frontmatter = {};
-  let body = raw;
-  if (raw.startsWith('---')) {
-    const end = raw.indexOf('\n---', 3);
-    if (end > 0) {
-      const fmText = raw.slice(3, end).trim();
-      body = raw.slice(end + 4).trim();
-      for (const line of fmText.split('\n')) {
-        const m = line.match(/^([\w-]+):\s*(.*)$/);
-        if (m) {
-          let v = m[2].trim();
-          if (v === 'true') v = true;
-          else if (v === 'false') v = false;
-          frontmatter[m[1]] = v;
-        }
-      }
-    }
-  }
+  const parsed = frontmatterLib.split(raw, { strict: true, source: file });
+  const frontmatter = parsed.frontmatter || {};
+  const body = parsed.body.trim();
 
   // Section parse for actions and facts
   const actions = parseList(body, 'Last actions');

package/lib/command-families.js

@@ -119,7 +119,6 @@ const COMMAND_FAMILIES = [
       '/god-upgrade',
       '/god-context',
       '/god-context-scan',
-      '/god-roadmap-check',
       '/god-roadmap-update'
     ]
   },
@@ -198,6 +197,15 @@ const COMMAND_FAMILIES = [
       '/god-help',
       '/god-version'
     ]
+  },
+  {
+    id: 'compatibility',
+    label: 'Compatibility',
+    purpose: 'Deprecated full-profile commands kept for backward compatibility.',
+    visibility: 'hidden',
+    commands: [
+      '/god-roadmap-check'
+    ]
   }
 ];
 
@@ -279,7 +287,7 @@ function familyForCommand(command) {
   return COMMAND_FAMILIES.find((family) => family.commands.includes(command)) || null;
 }
 
-function renderFamilyCards(families = COMMAND_FAMILIES) {
+function renderFamilyCards(families = COMMAND_FAMILIES.filter((family) => family.visibility !== 'hidden')) {
   return families.map((family) => (
     `${family.label}: ${family.purpose} (${family.commands.join(', ')})`
   ));

package/lib/context-budget.js

@@ -25,6 +25,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const frontmatter = require('./frontmatter');
 
 const BYTES_PER_TOKEN = 4;            // rough English text heuristic
 const DEFAULT_MAX_TOKENS = 80_000;    // per-agent default; ~half of a 200K window
@@ -52,44 +53,14 @@ function parseAgentBudget(agentPath) {
     return { required: [], optional: [], maxTokens: null };
   }
   const raw = fs.readFileSync(agentPath, 'utf8');
-  let fmText = '';
-  if (raw.startsWith('---')) {
-    const end = raw.indexOf('\n---', 3);
-    if (end > 0) fmText = raw.slice(3, end);
-  }
-
+  const metadata = frontmatter.parse(raw, { strict: true, source: agentPath });
   const out = { required: [], optional: [], maxTokens: null };
-  // very loose YAML-ish parse, just for our subset
-  const lines = fmText.split('\n');
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i].trim();
-    if (line.startsWith('required-context:')) {
-      out.required = parseListInline(line.slice('required-context:'.length), lines, i);
-    } else if (line.startsWith('optional-context:')) {
-      out.optional = parseListInline(line.slice('optional-context:'.length), lines, i);
-    } else if (line.startsWith('max-tokens:')) {
-      const n = parseInt(line.slice('max-tokens:'.length).trim(), 10);
-      if (Number.isFinite(n)) out.maxTokens = n;
-    }
-  }
+  if (Array.isArray(metadata['required-context'])) out.required = metadata['required-context'];
+  if (Array.isArray(metadata['optional-context'])) out.optional = metadata['optional-context'];
+  if (Number.isFinite(metadata['max-tokens'])) out.maxTokens = metadata['max-tokens'];
   return out;
 }
 
-function parseListInline(rest, lines, idx) {
-  const r = rest.trim();
-  if (r.startsWith('[') && r.endsWith(']')) {
-    return r.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
-  }
-  // Block list: subsequent lines starting with '- '
-  const items = [];
-  for (let j = idx + 1; j < lines.length; j++) {
-    const l = lines[j];
-    if (!l.startsWith('  - ')) break;
-    items.push(l.slice(4).trim().replace(/^["']|["']$/g, ''));
-  }
-  return items;
-}
-
 /**
  * Compute total bytes + estimated tokens for a list of file paths.
  * Missing files contribute 0; not an error.

package/lib/design-spec.js

@@ -15,7 +15,7 @@
  *   lint(content) -> { findings, valid }   // run all checks
  */
 
-const intent = require('./intent');
+const frontmatter = require('./frontmatter');
 
 const VALID_SECTIONS = [
   'Overview', 'Brand & Style',
@@ -48,23 +48,21 @@ const COMPONENT_PROPS = [
  * Parse a DESIGN.md file: separate YAML frontmatter from markdown body.
  */
 function parse(content) {
-  const errors = [];
   if (!content.startsWith('---')) {
     return { frontmatter: null, body: content, errors: ['Missing YAML frontmatter (file must start with `---`).'] };
   }
-  const end = content.indexOf('\n---', 3);
-  if (end === -1) {
+  const parsed = frontmatter.split(content, { strict: true, source: 'DESIGN.md' });
+  if (!parsed.frontmatter) {
     return { frontmatter: null, body: content, errors: ['Frontmatter not closed (missing closing `---`).'] };
   }
-  const yamlBlock = content.slice(3, end).trim();
-  const body = content.slice(end + 4).trim();
-  let frontmatter = null;
-  try {
-    frontmatter = intent.parseSimpleYaml(yamlBlock);
-  } catch (e) {
-    errors.push(`Frontmatter YAML parse error: ${e.message}`);
-  }
-  return { frontmatter, body, errors };
+  const errors = parsed.diagnostics.map((diagnostic) =>
+    `Frontmatter YAML warning: ${diagnostic.message} on line ${diagnostic.line}`
+  );
+  return {
+    frontmatter: errors.length > 0 ? null : parsed.frontmatter,
+    body: parsed.body.trim(),
+    errors
+  };
 }
 
 /**

package/lib/extensions.js

@@ -41,8 +41,18 @@ function parseManifest(yamlText) {
     return { manifest: null, errors: ['empty manifest'] };
   }
   try {
-    const manifest = intentLib.parseSimpleYaml(yamlText);
-    return { manifest, errors: [] };
+    const parsed = intentLib.parseSimpleYamlWithDiagnostics(yamlText, {
+      strict: true,
+      source: 'manifest.yaml',
+      unsafeKeySeverity: 'error'
+    });
+    if (parsed.diagnostics.length > 0) {
+      return {
+        manifest: null,
+        errors: parsed.diagnostics.map(intentLib.formatDiagnostic)
+      };
+    }
+    return { manifest: parsed.data, errors: [] };
   } catch (e) {
     return { manifest: null, errors: ['parse error: ' + e.message] };
   }

package/lib/frontmatter.js

@@ -0,0 +1,74 @@
+/**
+ * Shared YAML frontmatter helpers for markdown-backed Godpowers contracts.
+ *
+ * Frontmatter uses the same dependency-free YAML subset as intent, routing,
+ * recipes, workflows, and extension manifests.
+ */
+
+const { parseSimpleYamlWithDiagnostics } = require('./intent');
+
+function hasOpeningFence(text) {
+  return typeof text === 'string' && text.startsWith('---');
+}
+
+function split(text, opts = {}) {
+  const source = opts.source || null;
+  if (!hasOpeningFence(text)) {
+    return {
+      frontmatter: null,
+      body: text,
+      rawFrontmatter: '',
+      diagnostics: opts.require ? [{
+        severity: 'warning',
+        line: 1,
+        source,
+        message: 'Missing YAML frontmatter fence'
+      }] : []
+    };
+  }
+
+  const end = text.indexOf('\n---', 3);
+  if (end === -1) {
+    return {
+      frontmatter: null,
+      body: text,
+      rawFrontmatter: '',
+      diagnostics: [{
+        severity: 'warning',
+        line: 1,
+        source,
+        message: 'YAML frontmatter fence is not closed'
+      }]
+    };
+  }
+
+  const rawFrontmatter = text.slice(3, end).trim();
+  const parsed = parseSimpleYamlWithDiagnostics(rawFrontmatter, {
+    strict: opts.strict === true,
+    source,
+    unsafeKeySeverity: opts.unsafeKeySeverity || 'warning',
+    onDiagnostic: opts.onDiagnostic
+  });
+
+  return {
+    frontmatter: parsed.data,
+    body: text.slice(end + 4).trimStart(),
+    rawFrontmatter,
+    diagnostics: parsed.diagnostics
+  };
+}
+
+function parse(text, opts = {}) {
+  const result = split(text, opts);
+  return result.frontmatter || {};
+}
+
+function strip(text) {
+  return split(text).body.trim();
+}
+
+module.exports = {
+  split,
+  parse,
+  strip
+};

package/lib/installer-core.js

@@ -5,6 +5,7 @@ const { ensureDir, copyRecursive, copyRuntimeBundle } = require('./installer-fil
 const { resolveRuntime } = require('./installer-runtimes');
 const { selectedSkillNames, normalizeProfiles } = require('./install-profiles');
 const identity = require('./package-identity');
+const frontmatter = require('./frontmatter');
 
 const VERSION = identity.PACKAGE_VERSION;
 
@@ -46,52 +47,6 @@ function installSkillFile(srcFile, skillsDest, runtimeKey, targetName = null) {
   fs.copyFileSync(srcFile, path.join(skillsDest, `${baseName}.md`));
 }
 
-function parseAgentFrontmatter(content) {
-  const fallback = { name: null, description: null };
-  if (!content.startsWith('---\n')) return fallback;
-
-  const end = content.indexOf('\n---', 4);
-  if (end === -1) return fallback;
-
-  const lines = content.slice(4, end).split('\n');
-  const parsed = { ...fallback };
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const nameMatch = line.match(/^name:\s*(.+)\s*$/);
-    if (nameMatch) {
-      parsed.name = nameMatch[1].replace(/^["']|["']$/g, '');
-      continue;
-    }
-
-    if (line === 'description: |') {
-      const desc = [];
-      i++;
-      while (i < lines.length && /^ {2}/.test(lines[i])) {
-        desc.push(lines[i].slice(2));
-        i++;
-      }
-      i--;
-      parsed.description = desc.join('\n').trim();
-      continue;
-    }
-
-    const descMatch = line.match(/^description:\s*(.+)\s*$/);
-    if (descMatch) {
-      parsed.description = descMatch[1].replace(/^["']|["']$/g, '');
-    }
-  }
-
-  return parsed;
-}
-
-function stripFrontmatter(content) {
-  if (!content.startsWith('---\n')) return content.trim();
-  const end = content.indexOf('\n---', 4);
-  if (end === -1) return content.trim();
-  return content.slice(end + 4).trim();
-}
-
 function tomlString(value) {
   return JSON.stringify(value || '');
 }
@@ -102,10 +57,10 @@ function tomlLiteral(value) {
 
 function writeCodexAgentToml(srcFile, agentsDest) {
   const content = fs.readFileSync(srcFile, 'utf8');
-  const frontmatter = parseAgentFrontmatter(content);
-  const name = frontmatter.name || path.basename(srcFile, '.md');
-  const description = frontmatter.description || `Godpowers specialist agent: ${name}.`;
-  const instructions = stripFrontmatter(content);
+  const metadata = frontmatter.parse(content, { strict: true, source: srcFile });
+  const name = metadata.name || path.basename(srcFile, '.md');
+  const description = metadata.description || `Godpowers specialist agent: ${name}.`;
+  const instructions = frontmatter.strip(content);
   const toml = [
     `name = ${tomlString(name)}`,
     `description = ${tomlString(description)}`,
@@ -371,8 +326,8 @@ module.exports = {
   uninstallForRuntime,
   countInstalledSurface: countProfileSurface,
   installSkillFile,
-  parseAgentFrontmatter,
-  stripFrontmatter,
+  parseAgentFrontmatter: frontmatter.parse,
+  stripFrontmatter: frontmatter.strip,
   writeCodexAgentToml,
   removeSkillEntry,
   pruneGodpowersSkills,

package/lib/intent.js

@@ -5,6 +5,7 @@
  *
  * Note: this is a minimal YAML reader, intentionally avoiding a YAML
  * dependency. Handles the subset of YAML our intent files use.
+ * Strict callers can collect diagnostics for skipped lines and unsafe keys.
  * For complex YAML, agents read the file directly.
  */
 
@@ -66,15 +67,59 @@ function isUnsafeKey(key) {
  * Parse a simple YAML subset. Just enough for intent.yaml structure.
  * Real-world: replace with `yaml` npm package when we add deps.
  */
-function parseSimpleYaml(content) {
+function createDiagnostic(severity, line, message, source) {
+  return {
+    severity,
+    line,
+    source: source || null,
+    message
+  };
+}
+
+function formatDiagnostic(diagnostic) {
+  const source = diagnostic.source ? `${diagnostic.source}:` : '';
+  return `${source}${diagnostic.line}: ${diagnostic.message}`;
+}
+
+function diagnosticsError(diagnostics, label = 'YAML diagnostics') {
+  const error = new Error(`${label}:\n  - ${diagnostics.map(formatDiagnostic).join('\n  - ')}`);
+  error.diagnostics = diagnostics;
+  return error;
+}
+
+function parseSimpleYaml(content, opts = {}) {
+  const result = parseSimpleYamlWithDiagnostics(content, opts);
+  if (opts.throwOnDiagnostics && result.diagnostics.length > 0) {
+    throw diagnosticsError(result.diagnostics, opts.errorLabel);
+  }
+  return result.data;
+}
+
+function parseSimpleYamlWithDiagnostics(content, opts = {}) {
   const lines = content.split('\n');
   const result = {};
   const stack = [{ obj: result, indent: -1, key: null, isArray: false, parent: null }];
+  const diagnostics = [];
+  const strict = opts.strict === true;
+  const source = opts.source || null;
+  const unsafeKeySeverity = opts.unsafeKeySeverity || 'warning';
+
+  function record(severity, lineNumber, message) {
+    const diagnostic = createDiagnostic(severity, lineNumber, message, source);
+    diagnostics.push(diagnostic);
+    if (typeof opts.onDiagnostic === 'function') opts.onDiagnostic(diagnostic);
+  }
+
+  function recordSkipped(lineNumber, rawLine, reason) {
+    if (!strict) return;
+    record('warning', lineNumber, `${reason}: ${rawLine.trim()}`);
+  }
 
   for (let i = 0; i < lines.length; i++) {
     let line = lines[i];
     if (!line.trim() || line.trim().startsWith('#')) continue;
     line = stripInlineComment(line);
+    if (!line.trim()) continue;
 
     const indent = line.length - line.trimStart().length;
     const trimmed = line.trim();
@@ -84,6 +129,16 @@ function parseSimpleYaml(content) {
       stack.pop();
     }
     const parent = stack[stack.length - 1].obj;
+
+    if (trimmed === '[]') {
+      const current = stack[stack.length - 1];
+      if (current.parent && current.key && Object.keys(current.obj).length === 0) {
+        current.parent[current.key] = [];
+        stack.pop();
+        continue;
+      }
+    }
+
     // List item: "- key: value" or "- value"
     if (trimmed.startsWith('- ')) {
       const rest = trimmed.slice(2);
@@ -102,7 +157,14 @@ function parseSimpleYaml(content) {
       } else {
         // List of objects: "- key: value"
         const itemKey = rest.slice(0, restColonIdx).trim();
-        if (isUnsafeKey(itemKey)) continue;
+        if (!itemKey) {
+          recordSkipped(i + 1, lines[i], 'Missing list item key');
+          continue;
+        }
+        if (isUnsafeKey(itemKey)) {
+          record(unsafeKeySeverity, i + 1, `Unsafe YAML key rejected: ${itemKey}`);
+          continue;
+        }
         const itemVal = rest.slice(restColonIdx + 1).trim();
         const newObj = {};
         if (itemVal) {
@@ -122,9 +184,19 @@ function parseSimpleYaml(content) {
     }
 
     const colonIdx = findUnquotedColon(trimmed);
-    if (colonIdx === -1) continue;
+    if (colonIdx === -1) {
+      recordSkipped(i + 1, lines[i], 'Unparseable YAML line skipped');
+      continue;
+    }
     const key = trimmed.slice(0, colonIdx).trim();
-    if (isUnsafeKey(key)) continue;
+    if (!key) {
+      recordSkipped(i + 1, lines[i], 'Missing YAML key');
+      continue;
+    }
+    if (isUnsafeKey(key)) {
+      record(unsafeKeySeverity, i + 1, `Unsafe YAML key rejected: ${key}`);
+      continue;
+    }
     const valueStr = trimmed.slice(colonIdx + 1).trim();
 
     if (!valueStr) {
@@ -140,7 +212,7 @@ function parseSimpleYaml(content) {
     }
   }
 
-  return cleanArrays(result);
+  return { data: cleanArrays(result), diagnostics };
 }
 
 function readBlockScalar(lines, startIndex, parentIndent, folded) {
@@ -301,4 +373,14 @@ function validate(intent) {
   return errors;
 }
 
-module.exports = { read, readAsync, get, validate, intentPath, parseSimpleYaml };
+module.exports = {
+  read,
+  readAsync,
+  get,
+  validate,
+  intentPath,
+  parseSimpleYaml,
+  parseSimpleYamlWithDiagnostics,
+  diagnosticsError,
+  formatDiagnostic
+};

package/lib/pillars.js

@@ -8,6 +8,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const frontmatterLib = require('./frontmatter');
 
 const PILLARS_FENCE_BEGIN = '<!-- pillars:begin -->';
 const PILLARS_FENCE_END = '<!-- pillars:end -->';
@@ -119,47 +120,7 @@ function stripQuotes(value) {
   return String(value).trim().replace(/^['"]|['"]$/g, '');
 }
 
-function parseInlineList(value) {
-  const trimmed = value.trim();
-  if (trimmed === '[]') return [];
-  if (!trimmed.startsWith('[') || !trimmed.endsWith(']')) return null;
-  const body = trimmed.slice(1, -1).trim();
-  if (!body) return [];
-  return body.split(',').map(part => stripQuotes(part)).filter(Boolean);
-}
-
-function parseScalar(value) {
-  const trimmed = value.trim();
-  if (trimmed === 'true') return true;
-  if (trimmed === 'false') return false;
-  const list = parseInlineList(trimmed);
-  if (list) return list;
-  return stripQuotes(trimmed);
-}
-
-function parseFrontmatter(raw) {
-  if (!raw.startsWith('---\n')) return null;
-  const end = raw.indexOf('\n---', 4);
-  if (end === -1) return null;
-
-  const frontmatter = {};
-  const lines = raw.slice(4, end).split('\n');
-  let currentKey = null;
-  for (const line of lines) {
-    const match = line.match(/^([\w-]+):\s*(.*)$/);
-    if (match) {
-      currentKey = match[1];
-      frontmatter[currentKey] = parseScalar(match[2]);
-      continue;
-    }
-    const itemMatch = line.match(/^\s*-\s*(.+)$/);
-    if (currentKey && itemMatch) {
-      if (!Array.isArray(frontmatter[currentKey])) frontmatter[currentKey] = [];
-      frontmatter[currentKey].push(stripQuotes(itemMatch[1]));
-    }
-  }
-  return frontmatter;
-}
+const parseFrontmatter = (raw) => frontmatterLib.parse(raw, { strict: true });
 
 function walkMarkdown(dir) {
   if (!fs.existsSync(dir)) return [];