godpowers 0.15.0

package/lib/context-budget.js

@@ -0,0 +1,170 @@
+/**
+ * Context Budget - per-agent input budgeting to avoid kitchen-sink
+ * context that inflates token spend.
+ *
+ * The contract:
+ *   - Each agent declares `required-context` (must load) and
+ *     `optional-context` (load if budget allows) in its frontmatter.
+ *   - Project intent.yaml declares `budgets.default-max-tokens` and
+ *     optional per-agent overrides under `budgets.agents.<name>`.
+ *   - Orchestrator computes the loadout: all required files, then as
+ *     many optional files as fit under the budget.
+ *   - If required-context exceeds budget, emit `budget.exceeded` event
+ *     and proceed (load required anyway; users see the warning).
+ *
+ * Token estimation: bytes / 4 is a rough heuristic that matches
+ * empirical token-counts for typical English text well enough for
+ * budgeting. Not for billing.
+ *
+ * Public API:
+ *   estimateTokens(text | bytes) -> number
+ *   parseAgentBudget(agentPath) -> { required, optional, maxTokens? }
+ *   plan(budget, required, optional, perAgentMax) -> { loadout, dropped, used }
+ *   loadoutSize(files) -> { bytes, tokens }
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BYTES_PER_TOKEN = 4;            // rough English text heuristic
+const DEFAULT_MAX_TOKENS = 80_000;    // per-agent default; ~half of a 200K window
+
+function estimateTokens(input) {
+  if (typeof input === 'number') return Math.ceil(input / BYTES_PER_TOKEN);
+  if (typeof input === 'string') {
+    return Math.ceil(Buffer.byteLength(input, 'utf8') / BYTES_PER_TOKEN);
+  }
+  return 0;
+}
+
+/**
+ * Extract budget hints from an agent's frontmatter.
+ *
+ * Looks for lines like:
+ *   required-context: [path1, path2]
+ *   optional-context: [path3, path4]
+ *   max-tokens: 50000
+ *
+ * Returns defaults when missing.
+ */
+function parseAgentBudget(agentPath) {
+  if (!fs.existsSync(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 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;
+    }
+  }
+  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.
+ */
+function loadoutSize(files) {
+  let bytes = 0;
+  for (const f of files || []) {
+    if (!fs.existsSync(f)) continue;
+    bytes += fs.statSync(f).size;
+  }
+  return { bytes, tokens: estimateTokens(bytes) };
+}
+
+/**
+ * Plan a context loadout.
+ *
+ * budget: { defaultMaxTokens, perAgent: { agentName: max } }
+ * required, optional: arrays of file paths
+ * agentName: used to look up per-agent override
+ *
+ * Returns:
+ *   {
+ *     loadout: [paths in load order],
+ *     dropped: [paths skipped for budget],
+ *     used: { bytes, tokens },
+ *     budget: { tokens },
+ *     exceeded: bool
+ *   }
+ */
+function plan(budget, required, optional, agentName) {
+  const cap = (budget && budget.perAgent && budget.perAgent[agentName]) ||
+              (budget && budget.defaultMaxTokens) ||
+              DEFAULT_MAX_TOKENS;
+
+  const loadout = [];
+  let usedBytes = 0;
+
+  // Required first; always loaded regardless of budget.
+  let exceeded = false;
+  for (const f of required || []) {
+    if (!fs.existsSync(f)) continue;
+    loadout.push(f);
+    usedBytes += fs.statSync(f).size;
+  }
+  const requiredTokens = estimateTokens(usedBytes);
+  if (requiredTokens > cap) exceeded = true;
+
+  // Then optional, fit under cap.
+  const dropped = [];
+  for (const f of optional || []) {
+    if (!fs.existsSync(f)) continue;
+    const size = fs.statSync(f).size;
+    const projected = estimateTokens(usedBytes + size);
+    if (projected > cap) {
+      dropped.push(f);
+      continue;
+    }
+    loadout.push(f);
+    usedBytes += size;
+  }
+
+  return {
+    loadout,
+    dropped,
+    used: { bytes: usedBytes, tokens: estimateTokens(usedBytes) },
+    budget: { tokens: cap },
+    exceeded
+  };
+}
+
+module.exports = {
+  estimateTokens,
+  parseAgentBudget,
+  plan,
+  loadoutSize,
+  BYTES_PER_TOKEN,
+  DEFAULT_MAX_TOKENS
+};

package/lib/context-writer.js

@@ -0,0 +1,348 @@
+/**
+ * Context Writer
+ *
+ * Manages the fenced "Godpowers" section in project-level AI instruction
+ * files (AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/, .windsurfrules,
+ * .github/copilot-instructions.md, .clinerules).
+ *
+ * Rules:
+ *   - AGENTS.md is canonical; the others are 1-line pointers when their
+ *     tool's config dir is detected.
+ *   - Never blind-overwrite. Use a fenced section the user can recognize
+ *     and remove.
+ *   - Idempotent. Running twice produces the same file.
+ *   - Detect-then-write. Don't litter projects with files for tools the
+ *     user isn't using.
+ *
+ * Fence format:
+ *
+ *   <!-- godpowers:begin -->
+ *   ... managed content ...
+ *   <!-- godpowers:end -->
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const FENCE_BEGIN = '<!-- godpowers:begin -->';
+const FENCE_END = '<!-- godpowers:end -->';
+
+/**
+ * Detect which AI tools are configured in the project.
+ * Returns an array of platform descriptors.
+ */
+function detectInstalledTools(projectRoot) {
+  const detected = [];
+
+  const checks = [
+    { tool: 'claude-code', signal: '.claude', target: 'CLAUDE.md', kind: 'pointer' },
+    { tool: 'gemini', signal: '.gemini', target: 'GEMINI.md', kind: 'pointer' },
+    { tool: 'gemini', signal: 'GEMINI.md', target: 'GEMINI.md', kind: 'pointer' },
+    { tool: 'cursor', signal: '.cursor', target: '.cursor/rules/godpowers.mdc', kind: 'pointer' },
+    { tool: 'cursor', signal: '.cursorrules', target: '.cursorrules', kind: 'pointer' },
+    { tool: 'windsurf', signal: '.windsurf', target: '.windsurf/rules/godpowers.md', kind: 'pointer' },
+    { tool: 'windsurf', signal: '.windsurfrules', target: '.windsurfrules', kind: 'pointer' },
+    { tool: 'copilot', signal: '.github/copilot-instructions.md', target: '.github/copilot-instructions.md', kind: 'pointer' },
+    { tool: 'cline', signal: '.clinerules', target: '.clinerules', kind: 'pointer' },
+    { tool: 'roo', signal: '.roo', target: '.roo/rules/godpowers.md', kind: 'pointer' },
+    { tool: 'continue', signal: '.continue', target: '.continue/rules/godpowers.md', kind: 'pointer' },
+    // Pi (earendil-works/pi-coding-agent): reads AGENTS.md and CLAUDE.md
+    // as context files (already written via canonical AGENTS.md target),
+    // but also has its own project-local skills convention at .pi/skills/
+    { tool: 'pi', signal: '.pi', target: '.pi/skills/godpowers.md', kind: 'pointer' },
+    // .agents/skills/ is the cross-tool Agent Skills standard path used
+    // by Pi, Codex, and others; we write a pointer here when detected
+    { tool: 'agent-skills', signal: '.agents', target: '.agents/skills/godpowers.md', kind: 'pointer' }
+  ];
+
+  const seen = new Set();
+  for (const c of checks) {
+    if (seen.has(c.tool)) continue;
+    if (fs.existsSync(path.join(projectRoot, c.signal))) {
+      detected.push({ tool: c.tool, target: c.target, kind: c.kind });
+      seen.add(c.tool);
+    }
+  }
+  return detected;
+}
+
+/**
+ * Build the canonical Godpowers section content from project state.
+ * Keeps it short (the file is loaded into every AI prompt for some tools).
+ */
+function buildCanonicalContent(state, opts = {}) {
+  const lines = [];
+  lines.push('## Godpowers project');
+  lines.push('');
+  lines.push('This project uses Godpowers. The on-disk state is the source of truth;');
+  lines.push('conversation memory is not.');
+  lines.push('');
+
+  const projectName = (state && state.project && state.project.name) || opts.projectName || '(unnamed)';
+  const mode = (state && state.project && state.project.mode) || opts.mode || 'unknown';
+  const scale = (state && state.project && state.project.scale) || opts.scale || 'unknown';
+  lines.push(`- Project: ${projectName}`);
+  lines.push(`- Mode: ${mode}    Scale: ${scale}`);
+  lines.push('- State: `.godpowers/state.json` (machine) and `.godpowers/PROGRESS.md` (human)');
+  lines.push('');
+
+  lines.push('### Quarterback rule');
+  lines.push('');
+  lines.push('There is exactly one orchestrator: `god-orchestrator`. It owns all writes to');
+  lines.push('`state.json`, `PROGRESS.md`, `intent.yaml`, and `events.jsonl`. Skills like');
+  lines.push('`/god`, `/god-next`, `/god-status` read state without writing.');
+  lines.push('');
+
+  lines.push('### Useful commands');
+  lines.push('');
+  lines.push('- `/god-status` - re-derive state from disk');
+  lines.push('- `/god-next` - what to run next, with reason');
+  lines.push('- `/god <free text>` - match intent to a recipe');
+  lines.push('- `/god-mode` - run the full autonomous arc');
+  lines.push('- `/god-lint` - validate artifacts against have-nots');
+  lines.push('- `/god-scan` - rebuild linkage map from code');
+  lines.push('- `/god-review-changes` - walk REVIEW-REQUIRED.md');
+  lines.push('');
+
+  // Pointers to design and product files when present
+  const designExists = require('fs').existsSync(require('path').join(opts.projectRoot || process.cwd(), 'DESIGN.md'));
+  const productExists = require('fs').existsSync(require('path').join(opts.projectRoot || process.cwd(), 'PRODUCT.md'));
+  if (designExists || productExists) {
+    lines.push('### Design files');
+    lines.push('');
+    if (productExists) lines.push('- `PRODUCT.md` - strategic register, brand personality, anti-references');
+    if (designExists) lines.push('- `DESIGN.md` - visual tokens (Google Labs design.md format) + rationale');
+    lines.push('');
+  }
+
+  // Linkage status if known
+  if (state && state.linkage) {
+    const cov = (state.linkage['coverage-pct'] || 0) * 100;
+    if (cov > 0 || state.linkage['orphan-count'] > 0 || state.linkage['drift-count'] > 0) {
+      lines.push('### Linkage status');
+      lines.push('');
+      lines.push(`- Coverage: ${cov.toFixed(0)}%`);
+      if (state.linkage['orphan-count']) lines.push(`- Orphans: ${state.linkage['orphan-count']}`);
+      if (state.linkage['drift-count']) lines.push(`- Drift: ${state.linkage['drift-count']}`);
+      if (state.linkage['review-required-items']) lines.push(`- Pending reviews: ${state.linkage['review-required-items']}`);
+      lines.push('');
+    }
+  }
+
+  // Optional active artifacts list (filled in as tiers complete)
+  if (state && state.tiers) {
+    const active = [];
+    for (const tierKey of Object.keys(state.tiers)) {
+      const tier = state.tiers[tierKey];
+      for (const subKey of Object.keys(tier)) {
+        const sub = tier[subKey];
+        if (sub && sub.status === 'done' && sub.artifact) {
+          active.push(`${subKey}: \`${sub.artifact}\``);
+        }
+      }
+    }
+    if (active.length > 0) {
+      lines.push('### Active artifacts');
+      lines.push('');
+      for (const a of active) lines.push(`- ${a}`);
+      lines.push('');
+    }
+  }
+
+  lines.push('See `.godpowers/PROGRESS.md` for the live tier table.');
+  return lines.join('\n');
+}
+
+/**
+ * Build the pointer content for non-canonical files (CLAUDE.md, GEMINI.md, etc.).
+ * One line that defers to AGENTS.md.
+ */
+function buildPointerContent(canonicalRelPath = 'AGENTS.md') {
+  return `## Godpowers project\n\nThis project uses Godpowers. See \`${canonicalRelPath}\` for the project context.`;
+}
+
+/**
+ * Read a file, find the fenced section if present, return:
+ *   { exists, before, fenced, after }
+ *
+ * If no file exists, returns { exists: false, before: '', fenced: '', after: '' }.
+ * If file exists but has no fence, returns the whole file in `before`.
+ */
+function readFenced(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { exists: false, before: '', fenced: '', after: '' };
+  }
+  const content = fs.readFileSync(filePath, 'utf8');
+  const beginIdx = content.indexOf(FENCE_BEGIN);
+  const endIdx = content.indexOf(FENCE_END);
+  if (beginIdx === -1 || endIdx === -1 || endIdx < beginIdx) {
+    return { exists: true, before: content, fenced: '', after: '' };
+  }
+  return {
+    exists: true,
+    before: content.slice(0, beginIdx),
+    fenced: content.slice(beginIdx + FENCE_BEGIN.length, endIdx),
+    after: content.slice(endIdx + FENCE_END.length)
+  };
+}
+
+/**
+ * Write a fenced section to a file. Idempotent. Preserves user content
+ * outside the fence.
+ *
+ * Args:
+ *   filePath - absolute path to target file
+ *   sectionContent - markdown body to put inside the fence (no fence markers)
+ */
+function writeFenced(filePath, sectionContent) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const parsed = readFenced(filePath);
+  const fencedBlock = `${FENCE_BEGIN}\n${sectionContent}\n${FENCE_END}`;
+
+  let next;
+  if (!parsed.exists) {
+    next = `${fencedBlock}\n`;
+  } else if (parsed.fenced === '') {
+    // No fence yet. Append to end with a blank line separator.
+    const sep = parsed.before.endsWith('\n') ? '\n' : '\n\n';
+    next = `${parsed.before}${sep}${fencedBlock}\n`;
+  } else {
+    // Replace existing fence.
+    next = `${parsed.before}${fencedBlock}${parsed.after}`;
+  }
+  fs.writeFileSync(filePath, next);
+  return { written: filePath, hadFenceBefore: parsed.fenced !== '' };
+}
+
+/**
+ * Remove the Godpowers fence from a file. Leaves the rest untouched. If the
+ * file becomes empty (whitespace only), removes it.
+ */
+function removeFenced(filePath) {
+  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 === '') {
+    fs.unlinkSync(filePath);
+    return { removed: true, fileDeleted: true };
+  }
+  fs.writeFileSync(filePath, remaining + '\n');
+  return { removed: true, fileDeleted: false };
+}
+
+/**
+ * Detect existing fence in a file.
+ */
+function hasFence(filePath) {
+  return readFenced(filePath).fenced !== '';
+}
+
+/**
+ * Plan what would be written for a given project.
+ * Returns:
+ *   { canonical: { path, content }, pointers: [{ tool, path, content }] }
+ *
+ * Always plans AGENTS.md as canonical. Pointers are only planned for tools
+ * detected via `detectInstalledTools`.
+ */
+function plan(projectRoot, state, opts = {}) {
+  const canonicalPath = path.join(projectRoot, 'AGENTS.md');
+  const canonical = {
+    path: canonicalPath,
+    content: buildCanonicalContent(state, opts)
+  };
+
+  const pointers = [];
+  const detected = detectInstalledTools(projectRoot);
+  for (const d of detected) {
+    pointers.push({
+      tool: d.tool,
+      path: path.join(projectRoot, d.target),
+      content: buildPointerContent('AGENTS.md')
+    });
+  }
+  return { canonical, pointers };
+}
+
+/**
+ * Apply a plan: write AGENTS.md and any detected-tool pointers.
+ * Returns a list of write results.
+ */
+function apply(projectRoot, state, opts = {}) {
+  const p = plan(projectRoot, state, opts);
+  const results = [];
+  results.push(writeFenced(p.canonical.path, p.canonical.content));
+  for (const ptr of p.pointers) {
+    results.push({ ...writeFenced(ptr.path, ptr.content), tool: ptr.tool });
+  }
+  return results;
+}
+
+/**
+ * Remove all Godpowers fences from canonical + pointers (off-switch).
+ */
+function clearAll(projectRoot) {
+  const targets = [
+    path.join(projectRoot, 'AGENTS.md'),
+    path.join(projectRoot, 'CLAUDE.md'),
+    path.join(projectRoot, 'GEMINI.md'),
+    path.join(projectRoot, '.cursorrules'),
+    path.join(projectRoot, '.cursor', 'rules', 'godpowers.mdc'),
+    path.join(projectRoot, '.windsurfrules'),
+    path.join(projectRoot, '.windsurf', 'rules', 'godpowers.md'),
+    path.join(projectRoot, '.github', 'copilot-instructions.md'),
+    path.join(projectRoot, '.clinerules'),
+    path.join(projectRoot, '.roo', 'rules', 'godpowers.md'),
+    path.join(projectRoot, '.continue', 'rules', 'godpowers.md'),
+    path.join(projectRoot, '.pi', 'skills', 'godpowers.md'),
+    path.join(projectRoot, '.agents', 'skills', 'godpowers.md')
+  ];
+  const results = [];
+  for (const t of targets) {
+    const r = removeFenced(t);
+    if (r.removed) results.push({ path: t, ...r });
+  }
+  return results;
+}
+
+/**
+ * Status report: which targets have fences, which don't, what tools detected.
+ */
+function status(projectRoot) {
+  const canonicalPath = path.join(projectRoot, 'AGENTS.md');
+  const canonical = {
+    path: canonicalPath,
+    exists: fs.existsSync(canonicalPath),
+    hasFence: fs.existsSync(canonicalPath) ? hasFence(canonicalPath) : false
+  };
+  const detected = detectInstalledTools(projectRoot);
+  const pointers = detected.map(d => {
+    const p = path.join(projectRoot, d.target);
+    return {
+      tool: d.tool,
+      path: p,
+      exists: fs.existsSync(p),
+      hasFence: fs.existsSync(p) ? hasFence(p) : false
+    };
+  });
+  return { canonical, pointers, detected };
+}
+
+module.exports = {
+  FENCE_BEGIN,
+  FENCE_END,
+  detectInstalledTools,
+  buildCanonicalContent,
+  buildPointerContent,
+  readFenced,
+  writeFenced,
+  removeFenced,
+  hasFence,
+  plan,
+  apply,
+  clearAll,
+  status
+};