@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/overrides/resolver.mjs

@@ -0,0 +1,207 @@
+/**
+ * lib/overrides/resolver.mjs — single override + backup helper for every
+ * user-customizable Construct primitive (personas, skills, rules,
+ * contracts, role manifests).
+ *
+ * Convention:
+ *   - Original lives in the install (`personas/<n>.md`, `skills/.../<n>.md`, …)
+ *   - User override lives at `.cx/<category>/<n>.<ext>` — gitignored
+ *   - Each edit snapshots the prior content to
+ *     `.cx/backups/<category>/<n>.<iso>.<ext>` — gitignored, 60-day
+ *     auto-prune
+ *
+ * Override semantics: full file replacement (decided 2026-05-14). No
+ * section-merge. Means sync() reads the override file verbatim if
+ * present; otherwise reads the original.
+ *
+ * Backups: each call to `applyEdit` writes the prior content (if any)
+ * to `.cx/backups/<category>/<n>.<iso>.<ext>` before the new content
+ * lands. `restoreFromBackup` is the inverse.
+ *
+ * `pruneBackups(maxDays=60)` deletes backup files older than the cap.
+ * Idempotent — safe to call from a cron, post-merge hook, or doctor
+ * --fix.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_BACKUP_MAX_DAYS = 60;
+
+export const SUPPORTED_CATEGORIES = Object.freeze([
+  'personas',
+  'agents',
+  'skills',
+  'rules',
+  'contracts',
+  'role-manifests',
+]);
+
+const CATEGORY_RULES = {
+  personas: { originalDir: 'personas', defaultExt: '.md' },
+  agents: { originalDir: 'agents/prompts', defaultExt: '.md' },
+  skills: { originalDir: 'skills', defaultExt: '.md' },
+  rules: { originalDir: 'rules', defaultExt: '.md' },
+  contracts: { originalDir: 'agents', defaultExt: '.json', singleFile: 'contracts.json' },
+  'role-manifests': { originalDir: 'agents', defaultExt: '.json', singleFile: 'role-manifests.json' },
+};
+
+function categoryRule(category) {
+  const rule = CATEGORY_RULES[category];
+  if (!rule) throw new Error(`unknown override category: ${category}`);
+  return rule;
+}
+
+function isoStamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function ensureCxIgnore(projectRoot) {
+  const cxDir = path.join(projectRoot, '.cx');
+  fs.mkdirSync(cxDir, { recursive: true });
+  const gitignorePath = path.join(cxDir, '.gitignore');
+  const want = 'backups/\n';
+  let existing = '';
+  try { existing = fs.readFileSync(gitignorePath, 'utf8'); } catch { /* fresh */ }
+  if (!existing.split(/\r?\n/).map((l) => l.trim()).includes('backups/')) {
+    fs.writeFileSync(gitignorePath, existing + (existing.endsWith('\n') || !existing ? '' : '\n') + want);
+  }
+}
+
+function originalPath(projectRoot, category, name) {
+  const rule = categoryRule(category);
+  if (rule.singleFile) {
+    return path.join(projectRoot, rule.originalDir, rule.singleFile);
+  }
+  const ext = name.includes('.') ? '' : rule.defaultExt;
+  return path.join(projectRoot, rule.originalDir, `${name}${ext}`);
+}
+
+function overridePath(projectRoot, category, name) {
+  const rule = categoryRule(category);
+  if (rule.singleFile) {
+    return path.join(projectRoot, '.cx', category, rule.singleFile);
+  }
+  const ext = name.includes('.') ? '' : rule.defaultExt;
+  return path.join(projectRoot, '.cx', category, `${name}${ext}`);
+}
+
+function backupDir(projectRoot, category) {
+  return path.join(projectRoot, '.cx', 'backups', category);
+}
+
+function backupName(name, ext) {
+  return `${name}.${isoStamp()}${ext}`;
+}
+
+function readIfExists(filePath) {
+  try { return fs.readFileSync(filePath, 'utf8'); } catch { return null; }
+}
+
+export function resolveOverride(projectRoot, category, name) {
+  const orig = originalPath(projectRoot, category, name);
+  const over = overridePath(projectRoot, category, name);
+  if (fs.existsSync(over)) {
+    return { path: over, source: 'override', overrideExists: true, originalPath: orig };
+  }
+  if (fs.existsSync(orig)) {
+    return { path: orig, source: 'original', overrideExists: false, originalPath: orig };
+  }
+  return { path: null, source: 'missing', overrideExists: false, originalPath: orig };
+}
+
+export function readResolved(projectRoot, category, name) {
+  const r = resolveOverride(projectRoot, category, name);
+  if (!r.path) return { content: null, source: 'missing' };
+  return { content: readIfExists(r.path), source: r.source };
+}
+
+export function applyEdit(projectRoot, category, name, newContent) {
+  if (typeof newContent !== 'string') throw new Error('newContent must be a string');
+  const over = overridePath(projectRoot, category, name);
+  const rule = categoryRule(category);
+  const ext = name.includes('.') ? path.extname(name) : rule.defaultExt;
+  ensureCxIgnore(projectRoot);
+  fs.mkdirSync(path.dirname(over), { recursive: true });
+
+  const priorContent = fs.existsSync(over)
+    ? readIfExists(over)
+    : readIfExists(originalPath(projectRoot, category, name));
+
+  let backupPath = null;
+  if (priorContent !== null && priorContent !== newContent) {
+    const dir = backupDir(projectRoot, category);
+    fs.mkdirSync(dir, { recursive: true });
+    backupPath = path.join(dir, backupName(name, ext));
+    fs.writeFileSync(backupPath, priorContent);
+  }
+
+  fs.writeFileSync(over, newContent);
+  return { overridePath: over, backupPath, wrote: newContent.length };
+}
+
+export function listBackups(projectRoot, category, name) {
+  const dir = backupDir(projectRoot, category);
+  if (!fs.existsSync(dir)) return [];
+  const prefix = `${name}.`;
+  const entries = fs.readdirSync(dir)
+    .filter((f) => f.startsWith(prefix))
+    .map((f) => {
+      const full = path.join(dir, f);
+      const stat = fs.statSync(full);
+      return { filename: f, path: full, mtimeMs: stat.mtimeMs, size: stat.size };
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return entries;
+}
+
+export function restoreFromBackup(projectRoot, category, name, backupFilename) {
+  const dir = backupDir(projectRoot, category);
+  const src = path.join(dir, backupFilename);
+  if (!fs.existsSync(src)) throw new Error(`backup not found: ${src}`);
+  const content = fs.readFileSync(src, 'utf8');
+  return applyEdit(projectRoot, category, name, content);
+}
+
+export function pruneBackups(projectRoot, { maxDays = DEFAULT_BACKUP_MAX_DAYS, now = Date.now() } = {}) {
+  const root = path.join(projectRoot, '.cx', 'backups');
+  if (!fs.existsSync(root)) return { pruned: [], kept: 0 };
+  const cutoff = now - maxDays * 24 * 60 * 60 * 1000;
+  const pruned = [];
+  let kept = 0;
+  for (const category of fs.readdirSync(root)) {
+    const dir = path.join(root, category);
+    if (!fs.statSync(dir).isDirectory()) continue;
+    for (const entry of fs.readdirSync(dir)) {
+      const full = path.join(dir, entry);
+      const stat = fs.statSync(full);
+      if (stat.mtimeMs < cutoff) {
+        fs.unlinkSync(full);
+        pruned.push(full);
+      } else {
+        kept += 1;
+      }
+    }
+  }
+  return { pruned, kept };
+}
+
+export function describeOverrides(projectRoot) {
+  const summary = {};
+  for (const category of SUPPORTED_CATEGORIES) {
+    const dir = path.join(projectRoot, '.cx', category);
+    if (!fs.existsSync(dir)) { summary[category] = []; continue; }
+    const entries = [];
+    const walk = (rel = '') => {
+      const cur = path.join(dir, rel);
+      for (const name of fs.readdirSync(cur)) {
+        const full = path.join(cur, name);
+        const relPath = path.join(rel, name);
+        if (fs.statSync(full).isDirectory()) { walk(relPath); continue; }
+        entries.push(relPath);
+      }
+    };
+    walk();
+    summary[category] = entries;
+  }
+  return summary;
+}

package/lib/parity.mjs

@@ -0,0 +1,147 @@
+/**
+ * lib/parity.mjs — Cross-surface parity verifier.
+ *
+ * After `construct sync` writes adapters to multiple surfaces (Claude Code,
+ * OpenCode, Codex), the module diffs each surface's actual state against the
+ * canonical `agents/registry.json`. Backs `construct doctor` for surfacing
+ * silent divergence — for instance, an agent added to the registry that
+ * never made it to OpenCode because of a sync regression.
+ *
+ * Each surface check is independent. A surface that is not installed (no
+ * config dir, no agents dir) reports `status: 'absent'` rather than
+ * generating a false-negative parity error. Surfaces explicitly opt out per
+ * entry via `entry.platforms` (an allowlist, when present); entries without
+ * the field are mirrored everywhere.
+ *
+ * Surfaces checked:
+ *   claude   ~/.claude/agents/*.md
+ *   opencode ~/.config/opencode/opencode.json (agent table)
+ *   codex    ~/.codex/agents/*.toml
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = path.resolve(MODULE_DIR, '..');
+
+function loadRegistry(rootDir = ROOT_DIR) {
+  const file = path.join(rootDir, 'agents', 'registry.json');
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function adapterName(entry, prefix) {
+  return entry.isPersona ? entry.name : `${prefix}-${entry.name}`;
+}
+
+function entriesForSurface(registry, surface) {
+  const prefix = registry.prefix || 'cx';
+  const entries = [
+    ...(registry.personas || []).map((p) => ({ ...p, isPersona: true })),
+    ...(registry.agents || []).map((a) => ({ ...a, isPersona: false })),
+  ];
+
+  return entries
+    .filter((e) => {
+      if (!Array.isArray(e.platforms)) return true;
+      return e.platforms.includes(surface);
+    })
+    .map((e) => adapterName(e, prefix));
+}
+
+function diffSets(expected, actual) {
+  const expectedSet = new Set(expected);
+  const actualSet = new Set(actual);
+  const missing = expected.filter((n) => !actualSet.has(n));
+  const extra = actual.filter((n) => !expectedSet.has(n));
+  return { missing, extra };
+}
+
+function checkClaude(registry, { homeDir = os.homedir() } = {}) {
+  const dir = path.join(homeDir, '.claude', 'agents');
+  if (!fs.existsSync(dir)) return { surface: 'claude', status: 'absent', dir };
+  const expected = entriesForSurface(registry, 'claude');
+  const actual = fs.readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .map((name) => name.replace(/\.md$/, ''));
+  const { missing, extra } = diffSets(expected, actual);
+  return {
+    surface: 'claude',
+    status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
+    dir,
+    expectedCount: expected.length,
+    actualCount: actual.length,
+    missing,
+    extra,
+  };
+}
+
+function checkOpenCode(registry, { homeDir = os.homedir() } = {}) {
+  const file = path.join(homeDir, '.config', 'opencode', 'opencode.json');
+  if (!fs.existsSync(file)) return { surface: 'opencode', status: 'absent', file };
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    return { surface: 'opencode', status: 'unreadable', file, error: err.message };
+  }
+  const expected = entriesForSurface(registry, 'opencode');
+  const actual = Object.keys(config.agent || config.agents || {});
+  const { missing, extra } = diffSets(expected, actual);
+  return {
+    surface: 'opencode',
+    status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
+    file,
+    expectedCount: expected.length,
+    actualCount: actual.length,
+    missing,
+    extra,
+  };
+}
+
+function checkCodex(registry, { homeDir = os.homedir() } = {}) {
+  const dir = path.join(homeDir, '.codex', 'agents');
+  if (!fs.existsSync(dir)) return { surface: 'codex', status: 'absent', dir };
+  const expected = entriesForSurface(registry, 'codex');
+  const actual = fs.readdirSync(dir)
+    .filter((name) => name.endsWith('.toml'))
+    .map((name) => name.replace(/\.toml$/, ''));
+  const { missing, extra } = diffSets(expected, actual);
+  return {
+    surface: 'codex',
+    status: missing.length === 0 && extra.length === 0 ? 'ok' : 'drift',
+    dir,
+    expectedCount: expected.length,
+    actualCount: actual.length,
+    missing,
+    extra,
+  };
+}
+
+/**
+ * Run parity checks across every supported surface. Never throws — returns a
+ * structured report so callers can render it however they like.
+ */
+export function checkParity({ rootDir = ROOT_DIR, homeDir = os.homedir() } = {}) {
+  const registry = loadRegistry(rootDir);
+  const surfaces = [
+    checkClaude(registry, { homeDir }),
+    checkOpenCode(registry, { homeDir }),
+    checkCodex(registry, { homeDir }),
+  ];
+
+  const ok = surfaces.every((s) => s.status === 'ok' || s.status === 'absent');
+  const summary = surfaces.map((s) => {
+    if (s.status === 'absent') return `${s.surface}: not installed`;
+    if (s.status === 'unreadable') return `${s.surface}: unreadable (${s.error})`;
+    if (s.status === 'ok') return `${s.surface}: ok (${s.actualCount}/${s.expectedCount})`;
+    const parts = [];
+    if (s.missing.length) parts.push(`missing: ${s.missing.join(', ')}`);
+    if (s.extra.length) parts.push(`extra: ${s.extra.join(', ')}`);
+    return `${s.surface}: drift — ${parts.join(' · ')}`;
+  });
+
+  return { ok, surfaces, summary };
+}

package/lib/paths.mjs

@@ -0,0 +1,33 @@
+/**
+ * lib/paths.mjs — cross-platform resolution for Construct's home-relative directories.
+ *
+ * The codebase historically scattered `process.env.HOME + '/.cx'` and similar
+ * patterns. Those break on Windows where `HOME` is unset and `USERPROFILE`
+ * holds the home path. Use `homeDir()`, `cxDir()`, and `constructDir()`
+ * instead — they consult `os.homedir()` (which respects every OS's user
+ * directory convention) and join with `path.join` so separators work on any
+ * platform.
+ *
+ * The `--toolkit-dir` style env override (`CX_TOOLKIT_DIR`) takes precedence
+ * over `~/.construct/` so operators with non-default install layouts can
+ * point Construct at the right tree.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+
+export function homeDir() {
+  return process.env.CX_HOME_OVERRIDE || os.homedir() || process.env.HOME || process.env.USERPROFILE || '';
+}
+
+export function cxDir() {
+  return path.join(homeDir(), '.cx');
+}
+
+export function constructDir() {
+  return process.env.CX_TOOLKIT_DIR || path.join(homeDir(), '.construct');
+}
+
+export function hookPath(name) {
+  return path.join(constructDir(), 'lib', 'hooks', `${name}.mjs`);
+}

package/lib/performance/generate.mjs

@@ -0,0 +1,212 @@
+/**
+ * lib/performance/generate.mjs — end-of-session performance review writer.
+ *
+ * Reads two sources for the trailing 7-day window:
+ *
+ *   1. `~/.cx/session-cost.jsonl` — appended by the Stop hook.
+ *      Per-call entries with model, tokens, cost, agent.
+ *   2. Telemetry `/api/public/observations?type=GENERATION` — generation
+ *      observations with latency, completionStartTime, errors,
+ *      metadata.agent. Optional — review degrades when telemetry
+ *      isn't reachable.
+ *
+ * Aggregates per agent: invocations, avgScore (placeholder = 1 -
+ * failureRate until telemetry scores are wired), failureRate, p50/p95
+ * latency, totalCostUsd, trend (compares this window to the prior
+ * 7-day window — 'improving' / 'stable' / 'declining' / 'unknown'),
+ * status ('healthy' if failureRate < 5% and avgScore >= 0.6;
+ * 'needs_attention' if failureRate 5–20% or avgScore 0.4–0.6;
+ * 'failing' if worse).
+ *
+ * Writes the result to
+ * `~/.cx/performance-reviews/review-<iso>.json` (no test- prefix,
+ * no -mock suffix, so the dashboard surfaces it as a real review).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const WINDOW_DAYS = 7;
+const REVIEW_DIR = path.join(os.homedir(), '.cx', 'performance-reviews');
+const COST_LEDGER = path.join(os.homedir(), '.cx', 'session-cost.jsonl');
+
+function quantile(values, q) {
+  if (!values.length) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const pos = (sorted.length - 1) * q;
+  const base = Math.floor(pos);
+  const rest = pos - base;
+  return sorted[base + 1] !== undefined ? sorted[base] + rest * (sorted[base + 1] - sorted[base]) : sorted[base];
+}
+
+function readLedger(cutoffMs) {
+  if (!fs.existsSync(COST_LEDGER)) return [];
+  const raw = fs.readFileSync(COST_LEDGER, 'utf8');
+  const entries = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line);
+      const ts = Date.parse(entry.ts);
+      if (Number.isFinite(ts) && ts >= cutoffMs) entries.push({ ...entry, _ts: ts });
+    } catch { /* skip malformed */ }
+  }
+  return entries;
+}
+
+async function fetchTelemetryGenerations(env, { sinceMs, limit = 500 } = {}) {
+  const key = env.CONSTRUCT_TELEMETRY_PUBLIC_KEY;
+  const secret = env.CONSTRUCT_TELEMETRY_SECRET_KEY;
+  if (!key || !secret) return null;
+  const baseUrl = (env.CONSTRUCT_TELEMETRY_URL ?? '').replace(/\/$/, '');
+  const auth = `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 8000);
+  try {
+    let res = await fetch(
+      `${baseUrl}/api/public/observations?type=GENERATION&fromStartTime=${encodeURIComponent(new Date(sinceMs).toISOString())}&limit=${limit}`,
+      { headers: { Authorization: auth }, signal: controller.signal },
+    );
+    if (res.status === 400 || res.status === 422) {
+      res = await fetch(
+        `${baseUrl}/api/public/observations?type=GENERATION&limit=${limit}`,
+        { headers: { Authorization: auth }, signal: controller.signal },
+      );
+    }
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const json = await res.json();
+    return Array.isArray(json.data) ? json.data : [];
+  } catch {
+    clearTimeout(timer);
+    return null;
+  }
+}
+
+function classifyStatus(avgScore, failureRate) {
+  if (failureRate >= 0.2 || avgScore < 0.4) return 'failing';
+  if (failureRate >= 0.05 || avgScore < 0.6) return 'needs_attention';
+  return 'healthy';
+}
+
+function classifyTrend(currentScore, priorScore) {
+  if (priorScore == null) return 'unknown';
+  if (currentScore > priorScore + 0.05) return 'improving';
+  if (currentScore < priorScore - 0.05) return 'declining';
+  return 'stable';
+}
+
+function aggregateAgentStats(ledger, generations) {
+  const byAgent = new Map();
+  for (const entry of ledger) {
+    const agent = entry.agent || 'orchestrator';
+    const stat = byAgent.get(agent) || {
+      name: agent,
+      invocations: 0,
+      totalCostUsd: 0,
+      latencies: [],
+      errors: 0,
+      models: new Set(),
+    };
+    stat.invocations += 1;
+    stat.totalCostUsd += Number(entry.cost_usd) || 0;
+    if (entry.model) stat.models.add(entry.model);
+    byAgent.set(agent, stat);
+  }
+  if (Array.isArray(generations)) {
+    for (const g of generations) {
+      const agent =
+        g.metadata?.agent ||
+        (typeof g.name === 'string' && g.name.startsWith('llm.') ? g.name.slice(4) : null);
+      if (!agent || agent === 'chat') continue;
+      const stat = byAgent.get(agent) || {
+        name: agent,
+        invocations: 0,
+        totalCostUsd: 0,
+        latencies: [],
+        errors: 0,
+        models: new Set(),
+      };
+      const start = g.startTime ? Date.parse(g.startTime) : null;
+      const end = g.endTime ? Date.parse(g.endTime) : null;
+      if (start && end && end > start) stat.latencies.push(end - start);
+      if ((g.level || '').toLowerCase() === 'error') stat.errors += 1;
+      if (g.model) stat.models.add(g.model);
+      byAgent.set(agent, stat);
+    }
+  }
+  return byAgent;
+}
+
+export async function generatePerformanceReview({
+  windowDays = WINDOW_DAYS,
+  now = Date.now(),
+  env = process.env,
+} = {}) {
+  const cutoff = now - windowDays * 24 * 60 * 60 * 1000;
+  const priorCutoff = now - windowDays * 2 * 24 * 60 * 60 * 1000;
+  const ledger = readLedger(cutoff);
+  const priorLedger = readLedger(priorCutoff).filter((e) => e._ts < cutoff);
+  const generations = await fetchTelemetryGenerations(env, { sinceMs: cutoff });
+  const currentByAgent = aggregateAgentStats(ledger, generations || []);
+  const priorByAgent = aggregateAgentStats(priorLedger, []);
+  const agentStats = [];
+  for (const [name, s] of currentByAgent) {
+    const failureRate = s.invocations > 0 ? s.errors / s.invocations : 0;
+    const avgScore = Math.max(0, Math.min(1, 1 - failureRate));
+    const priorStats = priorByAgent.get(name);
+    const priorScore = priorStats && priorStats.invocations > 0
+      ? Math.max(0, Math.min(1, 1 - priorStats.errors / priorStats.invocations))
+      : null;
+    const status = classifyStatus(avgScore, failureRate);
+    const trend = classifyTrend(avgScore, priorScore);
+    agentStats.push({
+      name,
+      invocations: s.invocations,
+      scoredInvocations: s.invocations,
+      avgScore: Number(avgScore.toFixed(2)),
+      failureRate: Number(failureRate.toFixed(3)),
+      status,
+      trend,
+      totalCostUsd: Number(s.totalCostUsd.toFixed(4)),
+      latencyMs: s.latencies.length
+        ? { p50: Math.round(quantile(s.latencies, 0.5)), p95: Math.round(quantile(s.latencies, 0.95)) }
+        : null,
+      models: [...s.models],
+      reasoning: failureRate > 0
+        ? `${s.errors}/${s.invocations} calls errored over the window`
+        : `${s.invocations} calls, no errors detected`,
+    });
+  }
+  agentStats.sort((a, b) => b.invocations - a.invocations);
+  const generatedAt = new Date(now).toISOString();
+  return {
+    generated: generatedAt,
+    period: {
+      from: new Date(cutoff).toISOString(),
+      to: generatedAt,
+      days: windowDays,
+    },
+    sources: {
+      costLedgerEntries: ledger.length,
+      telemetryGenerations: Array.isArray(generations) ? generations.length : null,
+      telemetryReachable: generations !== null,
+    },
+    agentStats,
+  };
+}
+
+export function writeReview(report, { dir = REVIEW_DIR, now = Date.now() } = {}) {
+  fs.mkdirSync(dir, { recursive: true });
+  const stamp = new Date(now).toISOString().replace(/[:.]/g, '-');
+  const filename = `review-${stamp}.json`;
+  const full = path.join(dir, filename);
+  fs.writeFileSync(full, JSON.stringify(report, null, 2));
+  return { filename, path: full };
+}
+
+export async function runGenerator({ env = process.env, now = Date.now() } = {}) {
+  const report = await generatePerformanceReview({ env, now });
+  const written = writeReview(report, { now });
+  return { ...written, agentCount: report.agentStats.length };
+}