godpowers 1.6.24 → 2.1.0

package/lib/intent.js

@@ -10,6 +10,16 @@
 
 const fs = require('fs');
 const path = require('path');
+const asyncFs = require('./fs-async');
+
+/**
+ * @typedef {Object} IntentDocument
+ * @property {string} apiVersion Expected to be `godpowers/v1`.
+ * @property {string} kind Expected to be `Project`.
+ * @property {{ name: string, description?: string }} metadata Project metadata.
+ * @property {string} mode Project mode.
+ * @property {string} scale Project scale.
+ */
 
 function intentPath(projectRoot) {
   return path.join(projectRoot, '.godpowers', 'intent.yaml');
@@ -21,6 +31,9 @@ function intentPath(projectRoot) {
  * Minimal YAML parser: handles the subset our schema uses
  * (key: value, nested objects, arrays of strings, booleans).
  * For full YAML, agents should use a real parser.
+ *
+ * @param {string} projectRoot
+ * @returns {IntentDocument|null}
  */
 function read(projectRoot) {
   const file = intentPath(projectRoot);
@@ -29,6 +42,26 @@ function read(projectRoot) {
   return parseSimpleYaml(content);
 }
 
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<IntentDocument|null>}
+ */
+async function readAsync(projectRoot) {
+  const file = intentPath(projectRoot);
+  if (!(await asyncFs.exists(file))) return null;
+  const content = await asyncFs.fs.readFile(file, 'utf8');
+  return parseSimpleYaml(content);
+}
+
+/**
+ * Reject keys that would mutate the Object prototype chain. intent.yaml and
+ * extension manifests are untrusted input, so a key like `__proto__` must
+ * never be assigned during parsing.
+ */
+function isUnsafeKey(key) {
+  return key === '__proto__' || key === 'constructor' || key === 'prototype';
+}
+
 /**
  * Parse a simple YAML subset. Just enough for intent.yaml structure.
  * Real-world: replace with `yaml` npm package when we add deps.
@@ -41,17 +74,7 @@ function parseSimpleYaml(content) {
   for (let i = 0; i < lines.length; i++) {
     let line = lines[i];
     if (!line.trim() || line.trim().startsWith('#')) continue;
-    // Strip inline comments (but not # inside quotes)
-    const hashIdx = line.indexOf(' #');
-    if (hashIdx !== -1) {
-      // Make sure the # isn't inside a quoted string
-      const before = line.slice(0, hashIdx);
-      const dquoteCount = (before.match(/"/g) || []).length;
-      const squoteCount = (before.match(/'/g) || []).length;
-      if (dquoteCount % 2 === 0 && squoteCount % 2 === 0) {
-        line = before;
-      }
-    }
+    line = stripInlineComment(line);
 
     const indent = line.length - line.trimStart().length;
     const trimmed = line.trim();
@@ -66,7 +89,7 @@ function parseSimpleYaml(content) {
       const rest = trimmed.slice(2);
       // If the rest is a quoted string, treat as simple value (don't split on colon)
       const isQuotedSimple = /^"[^"]*"$|^'[^']*'$/.test(rest.trim());
-      const restColonIdx = isQuotedSimple ? -1 : rest.indexOf(':');
+      const restColonIdx = isQuotedSimple ? -1 : findUnquotedColon(rest);
 
       // Ensure parent is array
       if (!Array.isArray(parent.__items__)) {
@@ -79,6 +102,7 @@ function parseSimpleYaml(content) {
       } else {
         // List of objects: "- key: value"
         const itemKey = rest.slice(0, restColonIdx).trim();
+        if (isUnsafeKey(itemKey)) continue;
         const itemVal = rest.slice(restColonIdx + 1).trim();
         const newObj = {};
         if (itemVal) {
@@ -97,9 +121,10 @@ function parseSimpleYaml(content) {
       continue;
     }
 
-    const colonIdx = trimmed.indexOf(':');
+    const colonIdx = findUnquotedColon(trimmed);
     if (colonIdx === -1) continue;
     const key = trimmed.slice(0, colonIdx).trim();
+    if (isUnsafeKey(key)) continue;
     const valueStr = trimmed.slice(colonIdx + 1).trim();
 
     if (!valueStr) {
@@ -150,21 +175,91 @@ function readBlockScalar(lines, startIndex, parentIndent, folded) {
 }
 
 function parseValue(str) {
+  str = str.trim();
   if (str === 'true') return true;
   if (str === 'false') return false;
   if (str === 'null' || str === '~') return null;
   if (/^-?\d+$/.test(str)) return parseInt(str, 10);
   if (/^-?\d+\.\d+$/.test(str)) return parseFloat(str);
-  if (/^".*"$/.test(str) || /^'.*'$/.test(str)) return str.slice(1, -1);
+  if (/^".*"$/.test(str)) {
+    try {
+      return JSON.parse(str);
+    } catch (e) {
+      return str.slice(1, -1);
+    }
+  }
+  if (/^'.*'$/.test(str)) return str.slice(1, -1).replace(/''/g, "'");
   // Inline array: [/god-mode, /god-foo]
   if (/^\[.*\]$/.test(str)) {
     const inner = str.slice(1, -1).trim();
     if (!inner) return [];
-    return inner.split(',').map(s => parseValue(s.trim()));
+    return splitInlineArray(inner).map(s => parseValue(s.trim()));
   }
   return str;
 }
 
+function stripInlineComment(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (quote) {
+      if (ch === quote && line[i - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === '#' && (i === 0 || /\s/.test(line[i - 1]))) {
+      return line.slice(0, i).trimEnd();
+    }
+  }
+  return line;
+}
+
+function findUnquotedColon(text) {
+  let quote = null;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === quote && text[i - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === ':') return i;
+  }
+  return -1;
+}
+
+function splitInlineArray(text) {
+  const parts = [];
+  let quote = null;
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === quote && text[i - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === '[') depth++;
+    if (ch === ']') depth--;
+    if (ch === ',' && depth === 0) {
+      parts.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
 function cleanArrays(obj) {
   if (Array.isArray(obj)) return obj.map(cleanArrays);
   if (obj && typeof obj === 'object') {
@@ -206,4 +301,4 @@ function validate(intent) {
   return errors;
 }
 
-module.exports = { read, get, validate, intentPath, parseSimpleYaml };
+module.exports = { read, readAsync, get, validate, intentPath, parseSimpleYaml };

package/lib/quick-proof.js

@@ -0,0 +1,153 @@
+/**
+ * Quick proof runner.
+ *
+ * Renders a deterministic proof from a shipped fixture while detecting host
+ * guarantees from the caller's actual project and environment.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const dashboard = require('./dashboard');
+const hostCapabilities = require('./host-capabilities');
+
+const FIXTURE_ROOT = path.join(__dirname, '..', 'fixtures', 'quick-proof', 'project');
+const MANIFEST_PATH = path.join(__dirname, '..', 'fixtures', 'quick-proof', 'manifest.json');
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function relFixturePath(absPath) {
+  return path.relative(path.join(__dirname, '..'), absPath).split(path.sep).join('/');
+}
+
+function compute(projectRoot = process.cwd(), opts = {}) {
+  const fixtureRoot = opts.fixtureRoot || FIXTURE_ROOT;
+  const manifestPath = opts.manifestPath || MANIFEST_PATH;
+  const manifest = readJson(manifestPath);
+  const fixtureDashboard = dashboard.compute(fixtureRoot, { git: false });
+  const host = opts.hostReport || hostCapabilities.detect(projectRoot, opts.hostOptions || {});
+  const focusedActionBrief = {
+    recommended: fixtureDashboard.next && fixtureDashboard.next.command
+      ? fixtureDashboard.next.command
+      : 'describe the next intent',
+    reason: fixtureDashboard.next && fixtureDashboard.next.reason
+      ? fixtureDashboard.next.reason
+      : 'No route was computed.',
+    confidence: host.level === 'unknown' ? 'needs attention' : 'ready',
+    blockers: host.gaps && host.gaps.length > 0 ? [`Host: ${host.gaps[0]}`] : [],
+    overflow: host.gaps && host.gaps.length > 1 ? host.gaps.length - 1 : 0
+  };
+
+  const proof = {
+    source: 'quick-proof fixture',
+    manifest,
+    projectRoot: path.resolve(projectRoot),
+    fixtureRoot,
+    fixturePath: relFixturePath(fixtureRoot),
+    statePath: relFixturePath(path.join(fixtureRoot, '.godpowers', 'state.json')),
+    dashboard: {
+      state: fixtureDashboard.state,
+      progress: fixtureDashboard.progress,
+      planning: fixtureDashboard.planning,
+      next: fixtureDashboard.next,
+      actionBrief: focusedActionBrief
+    },
+    host,
+    commands: [
+      `npx godpowers quick-proof --project=${projectRoot}`,
+      `npx godpowers status --project=${fixtureRoot} --brief`,
+      `npx godpowers next --project=${fixtureRoot} --brief`,
+      `npx godpowers status --project=${projectRoot} --brief`
+    ],
+    evidence: [
+      {
+        label: 'State on disk',
+        value: relFixturePath(path.join(fixtureRoot, '.godpowers', 'state.json'))
+      },
+      {
+        label: 'Next action',
+        value: fixtureDashboard.next && fixtureDashboard.next.command
+          ? fixtureDashboard.next.command
+          : 'describe the next intent'
+      },
+      {
+        label: 'Missing artifact',
+        value: fixtureDashboard.planning.prd.status === 'missing'
+          ? '.godpowers/prd/PRD.md'
+          : 'none'
+      },
+      {
+        label: 'Host guarantees',
+        value: hostCapabilities.summary(host)
+      }
+    ]
+  };
+
+  return proof;
+}
+
+function render(proof, opts = {}) {
+  const brief = proof.dashboard.actionBrief || {};
+  const next = proof.dashboard.next || {};
+  const progress = proof.dashboard.progress || {};
+  const planning = proof.dashboard.planning || {};
+
+  if (opts.brief) {
+    return [
+      'Godpowers Quick Proof',
+      '',
+      'Action brief:',
+      `  Next: ${brief.recommended || next.command || 'describe the next intent'}`,
+      `  Why: ${brief.reason || next.reason || 'No route was computed.'}`,
+      `  Readiness: ${brief.confidence || 'unknown'}`,
+      `  Host guarantees: ${hostCapabilities.summary(proof.host)}`,
+      '',
+      'Evidence:',
+      `  State on disk: ${proof.statePath}`,
+      `  Fixture: ${proof.fixturePath}`,
+      `  PRD: ${planning.prd ? planning.prd.status : 'unknown'}`,
+      `  Roadmap: ${planning.roadmap ? planning.roadmap.status : 'unknown'}`
+    ].join('\n');
+  }
+
+  return [
+    'Godpowers Quick Proof',
+    '',
+    `Source: shipped fixture (${proof.fixturePath})`,
+    '',
+    'What this proves:',
+    '  1. Godpowers can read project state from disk.',
+    '  2. Godpowers can name missing artifacts instead of inventing completion.',
+    '  3. Godpowers can recommend the next command from state.',
+    '  4. Godpowers can report host guarantees separately from fixture state.',
+    '',
+    'Dashboard proof:',
+    `  State: ${proof.dashboard.state}`,
+    `  Progress: ${progress.percent || 0}% (${progress.completed || 0} of ${progress.total || 0} tracked steps complete)`,
+    `  PRD: ${planning.prd ? planning.prd.status : 'unknown'}`,
+    `  Roadmap: ${planning.roadmap ? planning.roadmap.status : 'unknown'}`,
+    `  Next: ${next.command || 'describe the next intent'}`,
+    `  Why: ${next.reason || 'No route was computed.'}`,
+    `  Host guarantees: ${hostCapabilities.summary(proof.host)}`,
+    '',
+    'Evidence:',
+    ...proof.evidence.map((item, index) => `  ${index + 1}. ${item.label}: ${item.value}`),
+    '',
+    'Try it on the fixture:',
+    `  npx godpowers status --project=${proof.fixtureRoot} --brief`,
+    `  npx godpowers next --project=${proof.fixtureRoot} --brief`,
+    '',
+    'Try it on your project:',
+    `  npx godpowers status --project=${proof.projectRoot} --brief`,
+    `  npx godpowers next --project=${proof.projectRoot} --brief`
+  ].join('\n');
+}
+
+module.exports = {
+  compute,
+  render,
+  FIXTURE_ROOT,
+  MANIFEST_PATH
+};

package/lib/release-surface-sync.js

@@ -51,6 +51,13 @@ function readJson(projectRoot, relPath) {
   }
 }
 
+function releaseGateText(projectRoot, pkg) {
+  return [
+    JSON.stringify((pkg && pkg.scripts) || {}),
+    read(projectRoot, 'scripts/run-tests.js')
+  ].join('\n');
+}
+
 function addCheck(checks, id, status, relPath, message, opts = {}) {
   checks.push({
     area: 'release-surface',
@@ -114,7 +121,7 @@ function detect(projectRoot) {
     );
   }
 
-  const scriptsText = JSON.stringify(pkg.scripts || {});
+  const scriptsText = releaseGateText(projectRoot, pkg);
   for (const required of REQUIRED_RELEASE_TESTS) {
     const ok = scriptsText.includes(required);
     addCheck(

package/lib/repo-surface-sync.js

@@ -88,6 +88,13 @@ function readJson(projectRoot, relPath) {
   }
 }
 
+function releaseGateText(projectRoot, pkg) {
+  return [
+    JSON.stringify((pkg && pkg.scripts) || {}),
+    read(projectRoot, 'scripts/run-tests.js')
+  ].join('\n');
+}
+
 function routeForSkill(skillPath) {
   const base = path.basename(skillPath, '.md');
   return `routing/${base}.yaml`;
@@ -364,7 +371,7 @@ function extensionChecks(projectRoot) {
 function suiteChecks(projectRoot) {
   const checks = [];
   const pkg = readJson(projectRoot, 'package.json') || {};
-  const scriptsText = JSON.stringify(pkg.scripts || {});
+  const scriptsText = releaseGateText(projectRoot, pkg);
   const roadmap = read(projectRoot, 'docs/ROADMAP.md');
   const suiteCommands = [
     'god-suite-init',
@@ -433,7 +440,7 @@ function suiteChecks(projectRoot) {
 function dogfoodChecks(projectRoot) {
   const checks = [];
   const pkg = readJson(projectRoot, 'package.json') || {};
-  const scriptsText = JSON.stringify(pkg.scripts || {});
+  const scriptsText = releaseGateText(projectRoot, pkg);
   const scenarios = [
     'fixtures/dogfood/half-migrated-gsd/manifest.json',
     'fixtures/dogfood/host-degraded/manifest.json',

package/lib/review-required.js

@@ -23,7 +23,7 @@ const fs = require('fs');
 const path = require('path');
 
 function filePath(projectRoot) {
-  return path.join(projectRoot, 'REVIEW-REQUIRED.md');
+  return path.join(projectRoot, '.godpowers', 'REVIEW-REQUIRED.md');
 }
 
 function rejectedPath(projectRoot) {
@@ -41,6 +41,7 @@ function rejectedPath(projectRoot) {
  */
 function appendBatch(projectRoot, batch) {
   const file = filePath(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
   const ts = new Date().toISOString();
   const id = `${ts.replace(/[:.]/g, '-')}-${batch.source}`;
 

package/lib/router.js

@@ -98,7 +98,9 @@ function evaluateCheck(check, projectRoot) {
   // file:path
   if (check.startsWith('file:')) {
     const filePath = check.slice(5).trim();
-    return fs.existsSync(path.join(projectRoot, filePath));
+    const resolved = resolveProjectRelative(projectRoot, filePath);
+    if (!resolved) return false;
+    return fs.existsSync(resolved);
   }
 
   // state:dotted.path == value
@@ -109,7 +111,10 @@ function evaluateCheck(check, projectRoot) {
     const [, dottedPath, expected] = match;
     const s = state.read(projectRoot);
     if (!s) return false;
-    const actual = dottedPath.split('.').reduce((acc, k) => (acc ? acc[k] : undefined), s.tiers || s);
+    const actual = dottedPath.split('.').reduce((acc, k) => {
+      if (!acc || k === '__proto__' || k === 'constructor' || k === 'prototype') return undefined;
+      return acc[k];
+    }, s.tiers || s);
     return actual === expected || actual === parseValue(expected);
   }
 
@@ -126,7 +131,11 @@ function evaluateCheck(check, projectRoot) {
     return !fs.existsSync(path.join(projectRoot, '.godpowers'));
   }
 
-  // unknown check: assume satisfied to not block legitimate work
+  // Unknown check predicate: log a warning but assume satisfied to avoid
+  // blocking legitimate work from an outdated or unrecognized routing file.
+  if (typeof process !== 'undefined' && process.env.GODPOWERS_DEBUG) {
+    console.warn(`[router] unknown check predicate, assuming satisfied: ${check}`);
+  }
   return true;
 }
 
@@ -139,6 +148,16 @@ function parseValue(s) {
   return s;
 }
 
+function resolveProjectRelative(projectRoot, relPath) {
+  if (!projectRoot || !relPath) return null;
+  if (path.isAbsolute(relPath) || relPath.includes('\0')) return null;
+
+  const root = path.resolve(projectRoot);
+  const resolved = path.resolve(root, relPath);
+  if (resolved === root || resolved.startsWith(root + path.sep)) return resolved;
+  return null;
+}
+
 /**
  * Get the recommended next command after a successful run.
  * If conditional-next is declared, evaluates each branch's condition
@@ -354,6 +373,7 @@ module.exports = {
   getSpawnedAgents,
   suggestNext,
   evaluateCheck,
+  resolveProjectRelative,
   detectSafeSyncBlocker,
   hasNoCriticalFindings,
   clearCache

package/lib/skill-surface.js

@@ -0,0 +1,42 @@
+const fs = require('fs');
+const path = require('path');
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) return {};
+  const end = text.indexOf('\n---', 4);
+  if (end === -1) return {};
+  const out = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    const match = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (match) out[match[1]] = match[2].replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+function listSkills(rootDir = path.join(__dirname, '..', 'skills')) {
+  return fs.readdirSync(rootDir)
+    .filter((file) => /^god.*\.md$/.test(file))
+    .sort()
+    .map((file) => {
+      const full = path.join(rootDir, file);
+      const text = fs.readFileSync(full, 'utf8');
+      const frontmatter = parseFrontmatter(text);
+      return {
+        file,
+        command: `/${path.basename(file, '.md')}`,
+        name: frontmatter.name || path.basename(file, '.md'),
+        description: frontmatter.description || '',
+        path: full
+      };
+    });
+}
+
+function commandNames(rootDir) {
+  return listSkills(rootDir).map((skill) => skill.command);
+}
+
+module.exports = {
+  parseFrontmatter,
+  listSkills,
+  commandNames
+};

package/lib/state-lock.js

@@ -27,6 +27,16 @@
  *   isStale(lock, nowMs?) -> bool
  *   reclaim(projectRoot, holder) -> { reclaimed: bool, previousHolder? }
  *   scopesConflict(a, b) -> bool
+ *
+ * Limitations:
+ *   This lock is COOPERATIVE and ADVISORY. acquire() performs a non-atomic
+ *   read-then-write of state.json, so two separate OS processes that race can
+ *   both observe "no lock" and both proceed. It reliably serializes
+ *   well-behaved in-process callers (the common single-developer case) but is
+ *   NOT a cross-process mutex, and withLock() therefore guarantees mutual
+ *   exclusion only within one process. If true multi-process exclusion is ever
+ *   required, replace the acquire step with an atomic primitive such as an
+ *   fs.mkdir lock directory or an O_EXCL (wx) lockfile.
  */
 
 const fs = require('fs');