godpowers 2.0.0 → 2.1.1

package/extensions/launch-pack/README.md

@@ -11,7 +11,7 @@ Channel-specific launch strategists for Godpowers.
 | `/god-indie-hackers` | god-indie-hackers-strategist | Numbers-first, mistakes, real questions |
 | `/god-oss-release` | god-oss-release-strategist | README, SemVer, examples that run |
 
-Plus 4 workflows and 22 channel-specific have-nots.
+Plus 4 workflows and 23 channel-specific have-nots.
 
 ## When to use
 

package/lib/README.md

@@ -22,6 +22,7 @@ package-level integrations.
 | `dogfood-runner.js` | Run deterministic messy-repo scenarios against migration, host, extension, and suite release behavior. |
 | `budget.js` | Read and enforce configured budget controls. |
 | `cost-tracker.js` | Track token and cost estimates from event streams. |
+| `fs-async.js` | Promise-based file read/write helpers for non-blocking runtime paths. |
 
 ## Events and observability
 
@@ -43,6 +44,8 @@ package-level integrations.
 | `workflow-runner.js` | Execute workflow steps with validation hooks. |
 | `agent-cache.js` | Cache agent metadata for faster routing. |
 | `agent-validator.js` | Validate agent frontmatter and contracts. |
+| `agent-refs.js` | Validate workflow agent references and scan skill/agent prose for phantom references. |
+| `skill-surface.js` | Derive slash-command metadata from the individual `skills/` files. |
 
 ## Artifact quality
 
@@ -71,6 +74,7 @@ package-level integrations.
 | `impeccable-bridge.js` | Bridge runtime checks into impeccable quality workflows. |
 | `extensions.js` | Load and validate extension packs. |
 | `extension-authoring.js` | Scaffold publishable extension packs with manifest, package, README, skill, agent, and workflow files. |
+| `pillars.js` | Manage the Pillars project-context layer (`AGENTS.md` plus routed `agents/*.md`). |
 
 ## Repository and graph helpers
 
@@ -87,5 +91,17 @@ package-level integrations.
 | `review-required.js` | Decide when review gates should block progress. |
 | `suite-state.js` | Manage state across registered project suites. |
 
+## Installer, dashboard, and CLI helpers
+
+| Module | Purpose |
+|--------|---------|
+| `installer-core.js` | Install and uninstall the Godpowers surface for each runtime. |
+| `installer-files.js` | File-copy helpers shared by the installer and its tests. |
+| `installer-args.js` | Parse `bin/install.js` arguments and subcommands. |
+| `installer-runtimes.js` | Map supported runtimes to their config directories. |
+| `automation-providers.js` | Detect and configure host-native automation providers. |
+| `dashboard.js` | Compute the next-step action brief and host guarantee line. |
+| `quick-proof.js` | Render the shipped proof fixture for `godpowers quick-proof`. |
+
 See `../ARCHITECTURE.md` for system design and `../docs/ROADMAP.md` for planned
 runtime work.

package/lib/agent-browser-driver.js

@@ -30,7 +30,7 @@
  *   isInstalled() -> bool
  */
 
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const path = require('path');
 
 /**
@@ -38,14 +38,14 @@ const path = require('path');
  */
 function isInstalled() {
   try {
-    execSync('agent-browser --version', {
+    execFileSync('agent-browser', ['--version'], {
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 5000
     });
     return true;
   } catch (e1) {
     try {
-      execSync('npx --no-install agent-browser --version', {
+      execFileSync('npx', ['--no-install', 'agent-browser', '--version'], {
         stdio: ['ignore', 'pipe', 'pipe'],
         timeout: 5000
       });
@@ -59,21 +59,21 @@ function isInstalled() {
 /**
  * Run an agent-browser CLI command and return stdout.
  * Throws on non-zero exit. Times out after 30s default.
+ *
+ * Arguments are passed as an argv array with the shell disabled. URLs,
+ * selectors, and eval expressions can originate from project content
+ * (PRD/DESIGN acceptance criteria, CLI flags), so they must never be
+ * concatenated into a shell command string where metacharacters like
+ * `;`, `&&`, `$()`, or backticks could trigger command injection.
  */
 function run(args, opts = {}) {
-  const cmd = Array.isArray(args) ? args : [args];
-  // Quote arguments containing spaces (best-effort)
-  const argString = cmd.map(a => {
-    const s = String(a);
-    if (/\s/.test(s) && !s.startsWith('"')) return `"${s.replace(/"/g, '\\"')}"`;
-    return s;
-  }).join(' ');
-  const fullCmd = `agent-browser ${argString}`;
-  return execSync(fullCmd, {
+  const cmd = (Array.isArray(args) ? args : [args]).map(String);
+  return execFileSync('agent-browser', cmd, {
     stdio: ['ignore', 'pipe', 'pipe'],
     timeout: opts.timeout || 30000,
     cwd: opts.cwd || process.cwd(),
-    encoding: 'utf8'
+    encoding: 'utf8',
+    shell: false
   });
 }
 

package/lib/agent-cache.js

@@ -139,7 +139,14 @@ function clear(projectRoot, opts = {}) {
       const fpath = path.join(shardPath, fname);
       let entry;
       try { entry = JSON.parse(fs.readFileSync(fpath, 'utf8')); }
-      catch (e) { fs.unlinkSync(fpath); removed++; continue; }
+      catch (e) {
+        // Corrupt or non-JSON entry: prune it only on an explicit full clear.
+        // A narrow clear (by agent, expiry, or age) must not delete unrelated
+        // unparseable files it was never asked to touch.
+        if (opts.all) { fs.unlinkSync(fpath); removed++; }
+        else { kept++; }
+        continue;
+      }
       let shouldRemove = false;
       if (opts.all) shouldRemove = true;
       else if (opts.agent && entry.agent === opts.agent) shouldRemove = true;

package/lib/agent-refs.js

@@ -0,0 +1,161 @@
+const fs = require('fs');
+const path = require('path');
+const { isCompatible, parseManifest } = require('./extensions');
+
+const AGENT_CONTRACT_VERSION = '1.0.0';
+
+/**
+ * @typedef {Object} AgentRef
+ * @property {string|null} agent Agent name without the range suffix.
+ * @property {string|null} range SemVer range declared after the final at sign.
+ * @property {string} raw Original workflow `uses` value.
+ */
+
+/**
+ * @typedef {AgentRef & { contractVersion: string, valid: boolean, errors: string[] }} AgentRefValidation
+ */
+
+/**
+ * @param {string} ref
+ * @returns {AgentRef}
+ */
+function parseAgentRef(ref) {
+  if (!ref) return { agent: null, range: null, raw: ref };
+  const raw = String(ref).trim();
+  const at = raw.lastIndexOf('@');
+  if (at <= 0) {
+    return { agent: raw, range: null, raw };
+  }
+  return {
+    agent: raw.slice(0, at),
+    range: raw.slice(at + 1),
+    raw
+  };
+}
+
+/**
+ * @param {string} ref
+ * @param {string} [contractVersion]
+ * @returns {AgentRefValidation}
+ */
+function validateAgentRef(ref, contractVersion = AGENT_CONTRACT_VERSION) {
+  const parsed = parseAgentRef(ref);
+  const errors = [];
+
+  if (!parsed.agent || !/^[a-z][a-z0-9-]*$/.test(parsed.agent)) {
+    errors.push(`invalid agent name in uses: ${ref}`);
+  }
+  if (!parsed.range) {
+    errors.push(`agent ref must include a semver range: ${ref}`);
+  } else if (!isCompatible(parsed.range, contractVersion)) {
+    errors.push(`agent ref ${ref} does not satisfy agent contract ${contractVersion}`);
+  }
+
+  return { ...parsed, contractVersion, valid: errors.length === 0, errors };
+}
+
+/**
+ * @param {string} ref
+ * @param {string} [contractVersion]
+ * @returns {AgentRefValidation}
+ */
+function assertAgentRef(ref, contractVersion = AGENT_CONTRACT_VERSION) {
+  const result = validateAgentRef(ref, contractVersion);
+  if (!result.valid) {
+    throw new Error(result.errors.join('; '));
+  }
+  return result;
+}
+
+/**
+ * @typedef {Object} ProseRef
+ * @property {string} token Unresolved god-* token (leading slash stripped).
+ * @property {string} file Repo-relative path where the token was found.
+ * @property {number} count Occurrences of that token in that file.
+ */
+
+const PROSE_TOKEN = /(?<![A-Za-z0-9_])\/?god-[a-z0-9]+(?:-[a-z0-9]+)*/g;
+
+/**
+ * Collect the set of every god-* command/agent name that legitimately exists:
+ * core skills, core agents, and the skills/agents provided by first-party
+ * extension packs. {god, godpowers} are always valid (front door + binary).
+ *
+ * @param {string} rootDir Repository root.
+ * @returns {Set<string>}
+ */
+function knownGodNames(rootDir) {
+  const valid = new Set(['god', 'godpowers']);
+
+  for (const f of fs.readdirSync(path.join(rootDir, 'skills'))) {
+    if (f.endsWith('.md')) valid.add(f.replace(/\.md$/, ''));
+  }
+  for (const f of fs.readdirSync(path.join(rootDir, 'agents'))) {
+    if (/^god-.*\.md$/.test(f)) valid.add(f.replace(/\.md$/, ''));
+  }
+
+  const extDir = path.join(rootDir, 'extensions');
+  if (fs.existsSync(extDir)) {
+    for (const pack of fs.readdirSync(extDir)) {
+      const manifestPath = path.join(extDir, pack, 'manifest.yaml');
+      if (!fs.existsSync(manifestPath)) continue;
+      let provides = {};
+      try {
+        const parsed = parseManifest(fs.readFileSync(manifestPath, 'utf8'));
+        provides = (parsed && parsed.manifest && parsed.manifest.provides) || {};
+      } catch (e) {
+        continue;
+      }
+      for (const list of [provides.skills, provides.agents]) {
+        if (Array.isArray(list)) {
+          for (const name of list) valid.add(String(name).trim());
+        }
+      }
+    }
+  }
+
+  return valid;
+}
+
+/**
+ * Scan skill and agent prose for `god-*` references that do not resolve to a
+ * real core skill, core agent, or extension-provided skill/agent. Catches
+ * phantom references that the workflow `uses:` validator cannot see because
+ * they live in markdown bodies rather than YAML.
+ *
+ * @param {string} rootDir Repository root.
+ * @returns {ProseRef[]} Unresolved references (empty when everything resolves).
+ */
+function findUnresolvedProseRefs(rootDir) {
+  const valid = knownGodNames(rootDir);
+  const unresolved = [];
+
+  for (const dir of ['skills', 'agents']) {
+    const dirPath = path.join(rootDir, dir);
+    for (const f of fs.readdirSync(dirPath)) {
+      if (!f.endsWith('.md')) continue;
+      const text = fs.readFileSync(path.join(dirPath, f), 'utf8');
+      const counts = new Map();
+      let m;
+      while ((m = PROSE_TOKEN.exec(text)) !== null) {
+        const token = m[0].replace(/^\//, '');
+        if (valid.has(token)) continue;
+        counts.set(token, (counts.get(token) || 0) + 1);
+      }
+      for (const [token, count] of counts) {
+        unresolved.push({ token, file: `${dir}/${f}`, count });
+      }
+    }
+  }
+
+  return unresolved;
+}
+
+module.exports = {
+  AGENT_CONTRACT_VERSION,
+  parseAgentRef,
+  validateAgentRef,
+  assertAgentRef,
+  knownGodNames,
+  findUnresolvedProseRefs
+};

package/lib/budget.js

@@ -75,19 +75,32 @@ function writeBlock(projectRoot, newBudgets) {
  */
 function stripBudgets(raw) {
   const lines = raw.split('\n');
-  const out = [];
-  let inBudgets = false;
-  for (const line of lines) {
-    if (/^budgets\s*:/.test(line)) { inBudgets = true; continue; }
-    if (inBudgets) {
-      // End of block when we hit a non-indented non-empty line
-      if (/^\S/.test(line)) { inBudgets = false; out.push(line); continue; }
-      // Skip block lines
-      continue;
+  const range = findTopLevelBlock(lines, 'budgets');
+  if (!range) return raw;
+  const out = lines.slice(0, range.start).concat(lines.slice(range.end));
+  return out.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+
+function findTopLevelBlock(lines, key) {
+  const header = new RegExp(`^${key}\\s*:(?:\\s*(?:#.*)?)?$`);
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (header.test(lines[i])) {
+      start = i;
+      break;
     }
-    out.push(line);
   }
-  return out.join('\n').replace(/\n{3,}/g, '\n\n');
+  if (start === -1) return null;
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (!lines[i].trim()) continue;
+    if (/^\S/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return { start, end };
 }
 
 /**
@@ -211,5 +224,6 @@ module.exports = {
   writeBlock,
   stripBudgets,
   renderBudgets,
+  findTopLevelBlock,
   DEFAULTS
 };

package/lib/context-writer.js

@@ -216,15 +216,21 @@ function writeFenced(filePath, sectionContent) {
 }
 
 /**
- * Remove the Godpowers fence from a file. Leaves the rest untouched. If the
- * file becomes empty (whitespace only), removes it.
+ * Remove the Godpowers fence from a file. Leaves the rest untouched. If only
+ * the fence remained, an auto-generated pointer file is deleted; with
+ * { preserveFile: true } the file is emptied instead of deleted (used for the
+ * canonical AGENTS.md so the off-switch never removes the user's primary file).
  */
-function removeFenced(filePath) {
+function removeFenced(filePath, opts = {}) {
   if (!fs.existsSync(filePath)) return { removed: false, reason: 'missing' };
   const parsed = readFenced(filePath);
   if (parsed.fenced === '') return { removed: false, reason: 'no-fence' };
   let remaining = `${parsed.before}${parsed.after}`.replace(/\n{3,}/g, '\n\n').trim();
   if (remaining === '') {
+    if (opts.preserveFile) {
+      fs.writeFileSync(filePath, '');
+      return { removed: true, fileDeleted: false, emptied: true };
+    }
     fs.unlinkSync(filePath);
     return { removed: true, fileDeleted: true };
   }
@@ -284,8 +290,11 @@ function apply(projectRoot, state, opts = {}) {
  * Remove all Godpowers fences from canonical + pointers (off-switch).
  */
 function clearAll(projectRoot) {
-  const targets = [
-    path.join(projectRoot, 'AGENTS.md'),
+  // The canonical AGENTS.md is the user's primary context file: empty it rather
+  // than delete it. The remaining targets are auto-generated pointer files that
+  // Godpowers owns outright, so they are deleted when only the fence remains.
+  const canonical = path.join(projectRoot, 'AGENTS.md');
+  const pointers = [
     path.join(projectRoot, 'CLAUDE.md'),
     path.join(projectRoot, 'GEMINI.md'),
     path.join(projectRoot, '.cursorrules'),
@@ -300,7 +309,9 @@ function clearAll(projectRoot) {
     path.join(projectRoot, '.agents', 'skills', 'godpowers.md')
   ];
   const results = [];
-  for (const t of targets) {
+  const rc = removeFenced(canonical, { preserveFile: true });
+  if (rc.removed) results.push({ path: canonical, ...rc });
+  for (const t of pointers) {
     const r = removeFenced(t);
     if (r.removed) results.push({ path: t, ...r });
   }

package/lib/events.js

@@ -161,10 +161,17 @@ function verifyChain(file) {
 function readRun(projectRoot, runId) {
   const file = eventsPath(projectRoot, runId);
   if (!fs.existsSync(file)) return [];
-  return fs.readFileSync(file, 'utf8')
-    .split('\n')
-    .filter(Boolean)
-    .map(line => JSON.parse(line));
+  const out = [];
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    if (!line) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch (e) {
+      // Skip a torn or partial line (e.g. the process was killed mid-append).
+      // Hash-chain integrity is verified separately by verifyChain.
+    }
+  }
+  return out;
 }
 
 /**

package/lib/extension-authoring.js

@@ -26,6 +26,24 @@ function packageFolderName(name) {
   return name.replace(/^@/, '').replace(/\//g, '-');
 }
 
+function assertSafePackageName(value) {
+  if (!/^@?[a-z0-9][a-z0-9-]*(\/[a-z0-9][a-z0-9-]*)?$/.test(value)) {
+    throw new Error(
+      `Invalid extension name "${value}": expected a package name like ` +
+      `"@scope/pack" or "pack" using lowercase letters, digits, and dashes.`
+    );
+  }
+}
+
+function assertSafeSegment(value, label) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(value)) {
+    throw new Error(
+      `Invalid ${label} "${value}": use lowercase letters, digits, and dashes ` +
+      `only. Slashes, dots, and ".." are rejected to prevent path traversal.`
+    );
+  }
+}
+
 function scaffold(outputRoot, opts = {}) {
   const name = opts.name || '@godpowers/custom-pack';
   const version = opts.version || '0.1.0';
@@ -34,6 +52,15 @@ function scaffold(outputRoot, opts = {}) {
   const workflow = opts.workflow || null;
   const range = opts.godpowersRange || '>=1.6.0';
   const folder = opts.folder || packageFolderName(name);
+
+  // Validate all user-supplied names before they reach a filesystem path, so a
+  // value like "../../escape" can never write outside the output folder.
+  assertSafePackageName(name);
+  assertSafeSegment(skill, 'skill');
+  if (agent) assertSafeSegment(agent, 'agent');
+  if (workflow) assertSafeSegment(workflow, 'workflow');
+  assertSafeSegment(folder, 'folder');
+
   const root = path.join(outputRoot, folder);
   const written = [];
 

package/lib/feature-awareness.js

@@ -89,6 +89,24 @@ const FEATURES = [
     commands: ['godpowers quick-proof'],
     description: 'Render a shipped proof fixture with computed next action and host guarantees.'
   },
+  {
+    id: 'request-trace-review',
+    since: '2.0.1',
+    commands: ['/god-build', '/god-review', '/god-feature', '/god-refactor'],
+    description: 'Keep implementation diffs narrow by requiring request-trace evidence and reviewer checks for scope, simplicity, and surgicality.'
+  },
+  {
+    id: 'release-hardening',
+    since: '2.0.2',
+    commands: ['npm test', 'npm run lint', 'npm run release:check'],
+    description: 'Maintain release validation through a delegated test runner, static checks, parser coverage, and hardened package and runtime checks.'
+  },
+  {
+    id: 'maintenance-hardening',
+    since: '2.0.3',
+    commands: ['npm test', 'npm run lint', 'npm run release:check'],
+    description: 'Track installer decomposition, shared test harness adoption, executable agent refs, skill metadata sync, God Mode runbook delegation, and async runtime APIs.'
+  },
   {
     id: 'extension-authoring',
     since: '1.6.22',

package/lib/fs-async.js

@@ -0,0 +1,28 @@
+const fs = require('fs/promises');
+const path = require('path');
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+async function readJson(filePath) {
+  return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+
+async function writeJson(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(value, null, 2) + '\n');
+  return value;
+}
+
+module.exports = {
+  exists,
+  readJson,
+  writeJson,
+  fs
+};

package/lib/installer-args.js

@@ -0,0 +1,99 @@
+const path = require('path');
+const { RUNTIMES } = require('./installer-runtimes');
+
+const COMMANDS = new Set([
+  'status',
+  'next',
+  'quick-proof',
+  'automation-status',
+  'automation-setup',
+  'dogfood',
+  'extension-scaffold'
+]);
+
+function parseArgs(argv, cwd = process.cwd()) {
+  const args = argv.slice(2);
+  const opts = {
+    command: null,
+    project: cwd,
+    json: false,
+    brief: false,
+    extensionName: null,
+    extensionOutput: cwd,
+    extensionSkill: null,
+    extensionAgent: null,
+    extensionWorkflow: null,
+    runtimes: [],
+    global: false,
+    local: false,
+    all: false,
+    help: false,
+    uninstall: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (COMMANDS.has(arg)) {
+      opts.command = arg;
+      continue;
+    }
+
+    switch (arg) {
+      case '--json':
+        opts.json = true;
+        break;
+      case '--brief':
+        opts.brief = true;
+        break;
+      case '--project':
+        if (args[i + 1]) {
+          opts.project = path.resolve(args[i + 1]);
+          i++;
+        }
+        break;
+      case '-g':
+      case '--global':
+        opts.global = true;
+        break;
+      case '-l':
+      case '--local':
+        opts.local = true;
+        break;
+      case '--all':
+        opts.all = true;
+        break;
+      case '-h':
+      case '--help':
+        opts.help = true;
+        break;
+      case '-u':
+      case '--uninstall':
+        opts.uninstall = true;
+        break;
+      default:
+        if (arg.startsWith('--project=')) {
+          opts.project = path.resolve(arg.slice('--project='.length));
+        } else if (arg.startsWith('--name=')) {
+          opts.extensionName = arg.slice('--name='.length);
+        } else if (arg.startsWith('--output=')) {
+          opts.extensionOutput = path.resolve(arg.slice('--output='.length));
+        } else if (arg.startsWith('--skill=')) {
+          opts.extensionSkill = arg.slice('--skill='.length);
+        } else if (arg.startsWith('--agent=')) {
+          opts.extensionAgent = arg.slice('--agent='.length);
+        } else if (arg.startsWith('--workflow=')) {
+          opts.extensionWorkflow = arg.slice('--workflow='.length);
+        } else if (arg.startsWith('--') && RUNTIMES[arg.slice(2)]) {
+          opts.runtimes.push(arg.slice(2));
+        }
+        break;
+    }
+  }
+
+  return opts;
+}
+
+module.exports = {
+  COMMANDS,
+  parseArgs
+};