godpowers 0.15.0

package/lib/drift-detector.js

@@ -0,0 +1,212 @@
+/**
+ * Drift Detector
+ *
+ * Detects divergence between artifact decisions and actual code.
+ * Uses the linkage map to know which files are linked to which artifacts.
+ *
+ * Drift types:
+ *   - DESIGN token drift: code uses a value that doesn't match the
+ *     declared token value
+ *   - DESIGN component drift: implementing file's actual styling differs
+ *     from component property declarations
+ *   - ARCH container drift: file is in container A but its imports
+ *     reach container B in a way ARCH says shouldn't happen
+ *   - STACK version drift: package.json has a version different from
+ *     what STACK/DECISION.md declares
+ *
+ * Public API:
+ *   detectAll(projectRoot) -> { findings, summary }
+ *   detectDesignTokenDrift(projectRoot, designContent) -> findings
+ *   detectStackVersionDrift(projectRoot, stackContent) -> findings
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const linkage = require('./linkage');
+const designSpec = require('./design-spec');
+
+/**
+ * Detect drift between DESIGN.md tokens and code that references them.
+ * If a file references a token that no longer exists in DESIGN.md, drift.
+ * If a file declares a token override (CSS var) with a different value, drift.
+ */
+function detectDesignTokenDrift(projectRoot, designContent) {
+  const findings = [];
+  if (!designContent) {
+    const designPath = path.join(projectRoot, 'DESIGN.md');
+    if (!fs.existsSync(designPath)) return findings;
+    designContent = fs.readFileSync(designPath, 'utf8');
+  }
+  const parsed = designSpec.parse(designContent);
+  if (!parsed.frontmatter) return findings;
+  const fm = parsed.frontmatter;
+
+  // Collect all valid token paths
+  const validTokens = new Set();
+  function walk(obj, prefix) {
+    for (const [k, v] of Object.entries(obj)) {
+      const here = prefix ? `${prefix}.${k}` : k;
+      if (typeof v === 'object' && v !== null && !Array.isArray(v)) {
+        walk(v, here);
+      } else {
+        validTokens.add(here);
+      }
+    }
+  }
+  walk(fm, '');
+
+  // Read reverse linkage to find files referencing tokens
+  const rev = linkage.readReverse(projectRoot);
+  for (const [filePath, ids] of Object.entries(rev)) {
+    for (const id of ids) {
+      if (linkage.classifyId(id) === 'token') {
+        // Check the token still exists
+        if (!validTokens.has(id) && !hasTokenInTree(fm, id)) {
+          findings.push({
+            kind: 'design-token-drift',
+            severity: 'error',
+            file: filePath,
+            artifactId: id,
+            message: `File references token "${id}" that no longer exists in DESIGN.md.`
+          });
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Detect drift between STACK/DECISION.md declared versions and actual
+ * package.json (or pyproject.toml etc.) versions.
+ */
+function detectStackVersionDrift(projectRoot, stackContent) {
+  const findings = [];
+  const stackPath = path.join(projectRoot, '.godpowers', 'stack', 'DECISION.md');
+  if (!stackContent && fs.existsSync(stackPath)) {
+    stackContent = fs.readFileSync(stackPath, 'utf8');
+  }
+  if (!stackContent) return findings;
+
+  // Extract declared deps from stack table: "| Foo | Choice | Lock-in |"
+  // and from "Selected Stack" rows. Heuristic: capture lines like
+  //   "Node 20 LTS" or "Next.js 15" or "Go 1.23"
+  const versionDeclared = {};
+  const tableLineRegex = /\|\s*[\w\s]+\s*\|\s*([\w.-]+)\s+(\d+(?:\.\d+)*(?:[\w-]*)?)\s*\|/g;
+  let m;
+  while ((m = tableLineRegex.exec(stackContent)) !== null) {
+    versionDeclared[m[1].toLowerCase()] = m[2];
+  }
+
+  // Read package.json
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      for (const [decl, expectedVer] of Object.entries(versionDeclared)) {
+        // Match against a dep name fragment
+        for (const [depName, actualSpec] of Object.entries(deps)) {
+          if (depName.toLowerCase().includes(decl) || decl.includes(depName.toLowerCase())) {
+            // Strip version specifier characters
+            const actualVer = String(actualSpec).replace(/^[\^~>=<]+/, '');
+            const majorActual = actualVer.split('.')[0];
+            const majorExpected = expectedVer.split('.')[0];
+            if (majorActual && majorExpected && majorActual !== majorExpected) {
+              findings.push({
+                kind: 'stack-version-drift',
+                severity: 'warning',
+                file: 'package.json',
+                artifactId: `S-${decl}`,
+                message: `STACK declares ${decl} ${expectedVer}; package.json has ${depName} ${actualSpec}.`
+              });
+            }
+          }
+        }
+      }
+    } catch (e) {
+      // ignore parse errors
+    }
+  }
+  return findings;
+}
+
+/**
+ * Check if a token path exists in the parsed frontmatter tree.
+ */
+function hasTokenInTree(fm, tokenPath) {
+  return tokenPath.split('.').reduce((acc, k) => (acc ? acc[k] : undefined), fm) !== undefined;
+}
+
+/**
+ * Detect ARCH container drift: cross-container imports that violate ARCH.
+ * Heuristic V1: if a file is linked to C-foo but imports from a path that
+ * looks like C-bar (e.g., src/bar/), flag.
+ */
+function detectArchContainerDrift(projectRoot) {
+  const findings = [];
+  const rev = linkage.readReverse(projectRoot);
+  for (const [filePath, ids] of Object.entries(rev)) {
+    const containerIds = ids.filter(id => linkage.classifyId(id) === 'container');
+    if (containerIds.length === 0) continue;
+    const fullPath = path.join(projectRoot, filePath);
+    if (!fs.existsSync(fullPath)) continue;
+    const ext = path.extname(filePath);
+    if (!['.js', '.jsx', '.ts', '.tsx', '.mjs'].includes(ext)) continue;
+
+    const content = fs.readFileSync(fullPath, 'utf8');
+    const importRegex = /(?:import\s+[^'"]*from\s+|require\s*\(\s*)['"]([^'"]+)['"]/g;
+    let m;
+    while ((m = importRegex.exec(content)) !== null) {
+      const importPath = m[1];
+      if (importPath.startsWith('.')) continue; // relative, same package
+      // Look for cross-container: something like "src/bar/" or "@/services/bar/"
+      const crossMatch = importPath.match(/(?:src|services?|lib|app)[\/\\]([\w-]+)/);
+      if (crossMatch) {
+        const otherSlug = crossMatch[1];
+        const otherContainerId = `C-${otherSlug}`;
+        if (otherContainerId !== containerIds[0] && containerIds.indexOf(otherContainerId) === -1) {
+          // It's a cross-container import. Whether this is drift depends on ARCH;
+          // V1 reports as info (suggestion to verify), not error.
+          findings.push({
+            kind: 'arch-container-cross-import',
+            severity: 'info',
+            file: filePath,
+            artifactId: containerIds[0],
+            message: `File in ${containerIds[0]} imports from ${otherContainerId} (verify ARCH allows this).`
+          });
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * Detect all known drift types.
+ */
+function detectAll(projectRoot) {
+  const findings = [
+    ...detectDesignTokenDrift(projectRoot),
+    ...detectStackVersionDrift(projectRoot),
+    ...detectArchContainerDrift(projectRoot)
+  ];
+  const summary = {
+    errors: findings.filter(f => f.severity === 'error').length,
+    warnings: findings.filter(f => f.severity === 'warning').length,
+    infos: findings.filter(f => f.severity === 'info').length,
+    byKind: {}
+  };
+  for (const f of findings) {
+    summary.byKind[f.kind] = (summary.byKind[f.kind] || 0) + 1;
+  }
+  return { findings, summary };
+}
+
+module.exports = {
+  detectAll,
+  detectDesignTokenDrift,
+  detectStackVersionDrift,
+  detectArchContainerDrift
+};

package/lib/event-reader.js

@@ -0,0 +1,174 @@
+/**
+ * Event Reader
+ *
+ * Reads events.jsonl files and produces three views:
+ *   - timeline(runId): chronological readable summary
+ *   - metrics(runId | runIds): per-tier durations, pauses, retries
+ *   - trace(runId, tier): deep dive on one tier's events
+ *
+ * Companion to lib/events.js which is the writer.
+ *
+ * Public API:
+ *   readAll(projectRoot, runId) -> Event[]
+ *   timeline(projectRoot, runId, opts) -> string (formatted) or rows array
+ *   metrics(projectRoot, runIds | null) -> { perTier, totals }
+ *   trace(projectRoot, runId, tier) -> Event[] (filtered)
+ *   summarize(events) -> { agentCount, pauseCount, errorCount, durationMs }
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const events = require('./events');
+
+function readAll(projectRoot, runId) {
+  return events.readRun(projectRoot, runId);
+}
+
+/**
+ * Render events as a readable timeline.
+ *
+ * opts: { limit, since (ISO), filter (event-name regex) }
+ *
+ * Returns an array of { ts, name, attrs, durationMs? } rows.
+ */
+function timeline(projectRoot, runId, opts = {}) {
+  const all = readAll(projectRoot, runId);
+  let rows = all;
+  if (opts.since) {
+    rows = rows.filter(e => e.ts >= opts.since);
+  }
+  if (opts.filter) {
+    const re = new RegExp(opts.filter);
+    rows = rows.filter(e => re.test(e.name));
+  }
+  if (opts.limit) rows = rows.slice(-opts.limit);
+
+  // Pair agent.start / agent.end to compute durations
+  const startMap = new Map();
+  const result = rows.map(e => {
+    const row = { ts: e.ts, name: e.name, attrs: e.attrs || {} };
+    if (e.name === 'agent.start') {
+      startMap.set(e.span_id, new Date(e.ts).getTime());
+    }
+    if (e.name === 'agent.end') {
+      const start = startMap.get(e.span_id);
+      if (start) row.durationMs = new Date(e.ts).getTime() - start;
+    }
+    return row;
+  });
+  return result;
+}
+
+/**
+ * Format a timeline as a human-readable string.
+ */
+function formatTimeline(rows) {
+  return rows.map(r => {
+    const dur = r.durationMs != null ? ` (${(r.durationMs / 1000).toFixed(2)}s)` : '';
+    const tier = r.attrs.tier ? ` [${r.attrs.tier}]` : '';
+    const agent = r.attrs.agent ? ` ${r.attrs.agent}` : '';
+    return `${r.ts} ${r.name}${tier}${agent}${dur}`;
+  }).join('\n');
+}
+
+/**
+ * Compute per-tier metrics across one or all runs.
+ *
+ * If runIds is null, walks every run in the project.
+ *
+ * Returns:
+ *   {
+ *     perTier: {
+ *       'tier-1': { count, totalMs, avgMs, pauseCount, errorCount },
+ *       ...
+ *     },
+ *     totals: { runs, agents, pauses, errors, totalMs }
+ *   }
+ */
+function metrics(projectRoot, runIds) {
+  if (!runIds) runIds = events.listRuns(projectRoot);
+  if (!Array.isArray(runIds)) runIds = [runIds];
+
+  const perTier = {};
+  const totals = { runs: runIds.length, agents: 0, pauses: 0, errors: 0, totalMs: 0 };
+
+  for (const runId of runIds) {
+    const all = readAll(projectRoot, runId);
+    const starts = new Map();
+    for (const e of all) {
+      const tier = (e.attrs && e.attrs.tier) || 'unknown';
+      if (!perTier[tier]) {
+        perTier[tier] = { count: 0, totalMs: 0, pauseCount: 0, errorCount: 0 };
+      }
+      if (e.name === 'agent.start') {
+        starts.set(e.span_id, { tier, ts: new Date(e.ts).getTime() });
+      }
+      if (e.name === 'agent.end') {
+        const s = starts.get(e.span_id);
+        if (s) {
+          const dur = new Date(e.ts).getTime() - s.ts;
+          perTier[s.tier].count += 1;
+          perTier[s.tier].totalMs += dur;
+          totals.agents += 1;
+          totals.totalMs += dur;
+        }
+      }
+      if (e.name === 'agent.pause') {
+        perTier[tier].pauseCount += 1;
+        totals.pauses += 1;
+      }
+      if (e.name === 'error') {
+        perTier[tier].errorCount += 1;
+        totals.errors += 1;
+      }
+    }
+  }
+
+  for (const t of Object.keys(perTier)) {
+    const p = perTier[t];
+    p.avgMs = p.count > 0 ? Math.round(p.totalMs / p.count) : 0;
+  }
+  return { perTier, totals };
+}
+
+/**
+ * Filter events for one tier across a run.
+ */
+function trace(projectRoot, runId, tier) {
+  return readAll(projectRoot, runId).filter(e =>
+    e.attrs && e.attrs.tier === tier
+  );
+}
+
+function summarize(eventList) {
+  const summary = { agentCount: 0, pauseCount: 0, errorCount: 0, durationMs: 0 };
+  const starts = new Map();
+  let firstTs = null, lastTs = null;
+  for (const e of eventList) {
+    if (!firstTs || e.ts < firstTs) firstTs = e.ts;
+    if (!lastTs || e.ts > lastTs) lastTs = e.ts;
+    if (e.name === 'agent.start') {
+      starts.set(e.span_id, new Date(e.ts).getTime());
+    }
+    if (e.name === 'agent.end') {
+      const s = starts.get(e.span_id);
+      if (s) summary.agentCount += 1;
+    }
+    if (e.name === 'agent.pause') summary.pauseCount += 1;
+    if (e.name === 'error') summary.errorCount += 1;
+  }
+  if (firstTs && lastTs) {
+    summary.durationMs = new Date(lastTs).getTime() - new Date(firstTs).getTime();
+  }
+  return summary;
+}
+
+module.exports = {
+  readAll,
+  timeline,
+  formatTimeline,
+  metrics,
+  trace,
+  summarize
+};

package/lib/events.js

@@ -0,0 +1,183 @@
+/**
+ * Events Manager
+ *
+ * Append OpenTelemetry-shape events to .godpowers/runs/<run-id>/events.jsonl.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const VALID_EVENT_NAMES = new Set([
+  'workflow.run', 'workflow.complete',
+  'agent.start', 'agent.end', 'agent.pause', 'agent.yolo-resolve',
+  'user.resolve',
+  'tool.call', 'tool.result',
+  'model.call',
+  'decision.route',
+  'artifact.created', 'artifact.updated', 'artifact.hash',
+  'have-nots.check',
+  'gate.fail', 'gate.pass',
+  'tier.skip',
+  'state.repair', 'state.rollback',
+  'extension.install', 'extension.activate',
+  // Cost / cache / budget (v0.14 token cost saver)
+  'cost.recorded', 'cache.hit', 'cache.miss', 'budget.exceeded',
+  'error', 'warn'
+]);
+
+function generateTraceId() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+function generateSpanId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+function eventsPath(projectRoot, runId) {
+  return path.join(projectRoot, '.godpowers', 'runs', runId, 'events.jsonl');
+}
+
+/**
+ * Start a new run. Returns a run handle with trace_id and write functions.
+ */
+function startRun(projectRoot, attrs = {}) {
+  const traceId = generateTraceId();
+  const runId = `${new Date().toISOString().replace(/[:.]/g, '-')}-${traceId.slice(0, 8)}`;
+  const spanId = generateSpanId();
+
+  const file = eventsPath(projectRoot, runId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  const handle = {
+    traceId,
+    runId,
+    rootSpanId: spanId,
+    file,
+    emit: (event) => emit(file, { trace_id: traceId, ...event }),
+    spawn: (parentSpanId) => spawnSpan(traceId, parentSpanId || spanId, file)
+  };
+
+  handle.emit({
+    span_id: spanId,
+    ts: new Date().toISOString(),
+    name: 'workflow.run',
+    attrs
+  });
+
+  return handle;
+}
+
+function spawnSpan(traceId, parentSpanId, file) {
+  const spanId = generateSpanId();
+  return {
+    traceId,
+    spanId,
+    parentSpanId,
+    emit: (event) =>
+      emit(file, {
+        trace_id: traceId,
+        span_id: spanId,
+        parent: parentSpanId,
+        ...event
+      })
+  };
+}
+
+/**
+ * Append a single event to the events.jsonl file. Includes a hash chain:
+ * each event carries `prev` = sha256 of the previous event line (or
+ * 'genesis' for the first). Any truncation, reordering, or tampering
+ * breaks the chain at that point and is detectable by
+ * verifyChain(file).
+ */
+function emit(file, event) {
+  if (!event.trace_id) throw new Error('event.trace_id required');
+  if (!event.span_id) throw new Error('event.span_id required');
+  if (!event.ts) event.ts = new Date().toISOString();
+  if (!event.name) throw new Error('event.name required');
+  if (!VALID_EVENT_NAMES.has(event.name)) {
+    throw new Error(`Invalid event name: ${event.name}`);
+  }
+
+  // Compute prev hash from the last line of the file, if any.
+  let prev = 'genesis';
+  if (fs.existsSync(file)) {
+    const stat = fs.statSync(file);
+    if (stat.size > 0) {
+      // Read just the last 4KB to find the last full line.
+      const fd = fs.openSync(file, 'r');
+      const chunkSize = Math.min(4096, stat.size);
+      const buf = Buffer.alloc(chunkSize);
+      fs.readSync(fd, buf, 0, chunkSize, stat.size - chunkSize);
+      fs.closeSync(fd);
+      const tail = buf.toString('utf8');
+      const lines = tail.split('\n').filter(l => l.trim());
+      if (lines.length > 0) {
+        prev = 'sha256:' + crypto.createHash('sha256')
+          .update(lines[lines.length - 1])
+          .digest('hex');
+      }
+    }
+  }
+  event.prev = prev;
+
+  fs.appendFileSync(file, JSON.stringify(event) + '\n');
+}
+
+/**
+ * Verify the hash chain in an events.jsonl file. Returns
+ * { valid: bool, breakAt: number | null, expected, actual }.
+ *
+ * The chain is broken if any event's `prev` doesn't match the sha256
+ * of the previous line's exact bytes. Genesis line must have
+ * prev === 'genesis'.
+ */
+function verifyChain(file) {
+  if (!fs.existsSync(file)) return { valid: true, lines: 0 };
+  const lines = fs.readFileSync(file, 'utf8').split('\n').filter(l => l.trim());
+  let prev = 'genesis';
+  for (let i = 0; i < lines.length; i++) {
+    let ev;
+    try { ev = JSON.parse(lines[i]); }
+    catch (e) { return { valid: false, breakAt: i, error: 'parse-error' }; }
+    if (ev.prev !== prev) {
+      return { valid: false, breakAt: i, expected: prev, actual: ev.prev };
+    }
+    prev = 'sha256:' + crypto.createHash('sha256').update(lines[i]).digest('hex');
+  }
+  return { valid: true, lines: lines.length };
+}
+
+/**
+ * Read all events for a run.
+ */
+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));
+}
+
+/**
+ * List all runs in a project.
+ */
+function listRuns(projectRoot) {
+  const runsDir = path.join(projectRoot, '.godpowers', 'runs');
+  if (!fs.existsSync(runsDir)) return [];
+  return fs.readdirSync(runsDir).sort();
+}
+
+module.exports = {
+  startRun,
+  emit,
+  readRun,
+  listRuns,
+  verifyChain,
+  generateTraceId,
+  generateSpanId,
+  eventsPath,
+  VALID_EVENT_NAMES
+};