@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/features.mjs

@@ -1,15 +1,14 @@
 /**
- * lib/features.mjs — <one-line purpose>
+ * lib/features.mjs — Feature flag resolution for Construct capabilities.
  *
- * <2–6 line summary: what it does, who calls it, key side effects.>
+ * Reads ~/.cx/features.json and project-level .cx/features.json to determine
+ * which optional features are active. Provides isFlagEnabled() used throughout
+ * the codebase to gate experimental paths without modifying core logic.
  */
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, readdirSync } from 'fs';
 import { homedir } from 'os';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const CATALOG_PATH = join(__dirname, 'mcp-catalog.json');
+import { join } from 'path';
+import { loadPluginRegistry } from './plugin-registry.mjs';
 
 function getHomeDir(overrides = {}) {
   return overrides.homeDir ?? homedir();
@@ -94,58 +93,189 @@ function readJSON(p) {
   try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
 }
 
-// OpenCode uses 'cass' for what Claude Code calls 'memory'
-const OC_ID_MAP = { memory: 'cass' };
+function getHostSupport(mcp, host) {
+  const support = mcp?.hostSupport?.[host];
+  if (!support) return { mode: 'managed' };
+  if (typeof support === 'string') return { mode: support };
+  if (typeof support === 'object') return { mode: support.mode ?? 'managed', ...support };
+  return { mode: 'managed' };
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Build the set of IDs to match against host configs for a given MCP entry.
+ * Includes the canonical id, any declared aliases, and the OpenCode mapping.
+ */
+function getMcpMatchIds(mcp) {
+  const ids = new Set([mcp.id]);
+  for (const alias of mcp.aliases ?? []) {
+    ids.add(alias);
+  }
+  return ids;
+}
+
+/**
+ * Check whether any of the given IDs appear as keys in a config object.
+ */
+function configHasAny(config, ids) {
+  if (!config || typeof config !== 'object') return false;
+  for (const id of ids) {
+    if (id in config) return true;
+  }
+  return false;
+}
+
+/**
+ * Resolve all project-level .mcp.json paths to check.
+ * Claude Code supports .mcp.json at project root and in .claude/ directories.
+ */
+function getProjectMcpPaths(overrides = {}) {
+  if (overrides.projectMcpPaths) return overrides.projectMcpPaths;
+  const cwd = overrides.cwd ?? process.cwd();
+  return [
+    join(cwd, '.mcp.json'),
+    join(cwd, '.claude', 'mcp.json'),
+  ];
+}
+
+/**
+ * Load Claude.ai server-side managed MCP IDs.
+ * These are integrations connected through Claude.ai's web interface
+ * (e.g., Notion, Google Drive) that aren't discoverable from local config.
+ * Users declare them via ~/.construct/claude-ai-mcps.json: { "mcps": ["notion", "slack"] }
+ */
+function getClaudeAiManagedMcps(overrides = {}) {
+  const p = overrides.claudeAiMcpsPath ?? join(getHomeDir(overrides), '.construct', 'claude-ai-mcps.json');
+  if (!existsSync(p)) return [];
+  try {
+    const data = JSON.parse(readFileSync(p, 'utf8'));
+    return Array.isArray(data?.mcps) ? data.mcps : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve Claude marketplace plugin directories to scan for .mcp.json files.
+ */
+function getMarketplaceMcpPaths(overrides = {}) {
+  if (overrides.marketplaceMcpPaths) return overrides.marketplaceMcpPaths;
+  const home = getHomeDir(overrides);
+  const marketplaceRoot = join(home, '.claude', 'plugins', 'marketplaces');
+  if (!existsSync(marketplaceRoot)) return [];
 
-function getMcpPlatforms(serverId, overrides = {}) {
+  const paths = [];
+  try {
+    for (const marketplace of readdirSync(marketplaceRoot)) {
+      const extDir = join(marketplaceRoot, marketplace, 'external_plugins');
+      if (!existsSync(extDir)) continue;
+      try {
+        for (const plugin of readdirSync(extDir)) {
+          const mcpFile = join(extDir, plugin, '.mcp.json');
+          if (existsSync(mcpFile)) paths.push(mcpFile);
+        }
+      } catch { /* skip unreadable dirs */ }
+    }
+  } catch { /* skip unreadable marketplace root */ }
+  return paths;
+}
+
+function getMcpPlatforms(mcp, overrides = {}) {
   const platforms = [];
+  const matchIds = getMcpMatchIds(mcp);
+
+  // --- Claude.ai server-side managed MCPs ---
+  const cloudMcps = getClaudeAiManagedMcps(overrides);
+  if (cloudMcps.some((id) => matchIds.has(id))) {
+    platforms.push('Claude.ai');
+  }
 
+  // --- Claude Code: user settings (~/.claude/settings.json) ---
   const claudeSettings = readClaudeSettings(overrides);
-  if (claudeSettings?.mcpServers && serverId in claudeSettings.mcpServers) {
+  if (getHostSupport(mcp, 'claude').mode === 'managed' && configHasAny(claudeSettings?.mcpServers, matchIds)) {
     platforms.push('Claude Code');
   }
 
+  // --- Claude Code: project-level .mcp.json ---
+  if (!platforms.includes('Claude Code')) {
+    for (const p of getProjectMcpPaths(overrides)) {
+      if (!existsSync(p)) continue;
+      const projectMcp = readJSON(p);
+      if (configHasAny(projectMcp?.mcpServers, matchIds) || configHasAny(projectMcp, matchIds)) {
+        platforms.push('Claude Code');
+        break;
+      }
+    }
+  }
+
+  // --- Claude marketplace plugins (~/.claude/plugins/marketplaces/*/external_plugins/*/.mcp.json) ---
+  if (!platforms.includes('Claude Code')) {
+    for (const p of getMarketplaceMcpPaths(overrides)) {
+      const pluginMcp = readJSON(p);
+      if (configHasAny(pluginMcp, matchIds)) {
+        platforms.push('Claude Code');
+        break;
+      }
+    }
+  }
+
+  // --- OpenCode ---
   const ocConfig = readOpenCodeConfig(overrides);
-  const ocId = OC_ID_MAP[serverId] ?? serverId;
-  if (ocConfig?.mcp && ocId in ocConfig.mcp) {
+  const ocIds = new Set([...matchIds]);
+  if (getHostSupport(mcp, 'opencode').mode === 'managed' && configHasAny(ocConfig?.mcp, ocIds)) {
     platforms.push('OpenCode');
   }
 
+  // --- VS Code / Copilot ---
   for (const p of getVSCodeSettingsPaths(overrides)) {
     const settings = readJSON(p);
-    if (settings?.['github.copilot.mcpServers'] && serverId in settings['github.copilot.mcpServers']) {
+    if (configHasAny(settings?.['github.copilot.mcpServers'], matchIds)) {
       const label = p.includes('Insiders') ? 'VS Code Insiders' : 'VS Code';
       if (!platforms.includes(label)) platforms.push(label);
     }
   }
 
+  // --- Cursor ---
   const cursorMcpPath = overrides.cursorMcpPath ?? join(getHomeDir(overrides), '.cursor', 'mcp.json');
   if (existsSync(cursorMcpPath)) {
     const cursorConfig = readJSON(cursorMcpPath);
-    if (cursorConfig?.mcpServers && serverId in cursorConfig.mcpServers) {
+    if (configHasAny(cursorConfig?.mcpServers, matchIds)) {
       platforms.push('Cursor');
     }
   }
 
-  return platforms;
-}
-
-function readCatalog() {
-  if (!existsSync(CATALOG_PATH)) return { mcps: [] };
-  try {
-    return JSON.parse(readFileSync(CATALOG_PATH, 'utf8'));
-  } catch {
-    return { mcps: [] };
+  // --- Codex ---
+  const codexConfigPath = overrides.codexConfigPath ?? join(getHomeDir(overrides), '.codex', 'config.toml');
+  if (existsSync(codexConfigPath)) {
+    const codexConfig = readFileSync(codexConfigPath, 'utf8');
+    const codexSupport = getHostSupport(mcp, 'codex');
+    if (codexSupport.mode === 'plugin' && codexSupport.plugin) {
+      const pattern = new RegExp(`\\[plugins\\.${JSON.stringify(codexSupport.plugin)}\\]\\s*\\nenabled = true`, 'm');
+      if (pattern.test(codexConfig)) platforms.push(codexSupport.label ?? 'Codex Plugin');
+    } else if (codexSupport.mode === 'managed') {
+      const idAlts = [...matchIds].map(escapeRegExp).join('|');
+      const pattern = new RegExp(`^\\[mcp_servers\\.("?)(?:${idAlts})\\1\\]`, 'm');
+      if (pattern.test(codexConfig)) platforms.push('Codex');
+    }
   }
+
+  return platforms;
 }
 
 /**
- * Build features dynamically from mcp-catalog.json.
+ * Build features dynamically from the plugin registry.
  * Each MCP reports configured state when present in host configs and unavailable when missing.
  */
 function buildFeatures(overrides = {}) {
-  const catalog = readCatalog();
-  return catalog.mcps.map((mcp) => ({
+  const registry = loadPluginRegistry({
+    cwd: overrides.cwd ?? process.cwd(),
+    homeDir: getHomeDir(overrides),
+    env: overrides.env ?? process.env,
+  });
+  return registry.mcps.map((mcp) => ({
     id: mcp.id,
     name: mcp.name,
     category: mcp.category,
@@ -153,7 +283,7 @@ function buildFeatures(overrides = {}) {
     degradedMessage: mcp.degradedMessage,
     usedBy: mcp.usedBy ?? [],
     async check() {
-      const platforms = getMcpPlatforms(mcp.id, overrides);
+      const platforms = getMcpPlatforms(mcp, overrides);
       if (platforms.length > 0) {
         return { status: 'configured', message: `Configured in ${platforms.join(', ')}` };
       }

package/lib/gates-audit.mjs

@@ -0,0 +1,236 @@
+/**
+ * lib/gates-audit.mjs — Cross-surface enforcement audit.
+ *
+ * Verifies that every policy gate is consistently expressed across the four
+ * places enforcement can live: CI workflow jobs, the local pre-push hook,
+ * the local pre-commit hook (when `core.hooksPath` is wired), and GitHub
+ * branch protection (required status checks). Identifies gaps — checks that
+ * exist in one place but not another, or that are required-to-merge but
+ * absent from CI, or that are CI-only with no local mirror.
+ *
+ * The mapping between CI job names and local commands lives in the
+ * GATE_DEFINITIONS table below. When a new CI job is added, the mapping
+ * must be updated to declare what its local equivalent should be (or that
+ * none is expected). This is the same single-source-of-truth pattern the
+ * project already uses for CLI commands in lib/cli-commands.mjs.
+ *
+ * Exit code (in `construct gates:audit`): 0 if no critical gaps; 1 if any
+ * critical gap is found. Non-critical advisories never fail the command.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ROOT_DIR = join(MODULE_DIR, '..');
+
+// Authoritative gate mapping. Each entry declares a CI job name and its
+// expected local mirror. `critical: true` means this gate MUST be in CI and
+// SHOULD be in branch-protection required checks; absence is a hard gap.
+// `localMirror: 'ci-only'` flags gates that legitimately have no local
+// equivalent (e.g., dockerized integration tests).
+
+const GATE_DEFINITIONS = [
+  { ciJob: 'test (ubuntu-latest / node 22)', prePushLabel: 'tests', critical: true },
+  { ciJob: 'test (macos-latest / node 22)',  prePushLabel: 'tests', critical: true },
+  { ciJob: 'test (ubuntu-latest / node 20)', prePushLabel: 'tests', critical: true },
+  { ciJob: 'test (macos-latest / node 20)',  prePushLabel: 'tests', critical: true },
+  { ciJob: 'retrieval evals',                prePushLabel: 'evals', critical: true },
+  { ciJob: 'dependency CVE audit',           prePushLabel: 'audit', critical: true },
+  { ciJob: 'secret scanning',                prePushLabel: null,  preCommitCheck: 'ECC secret scan',               critical: true, note: 'pre-commit ECC scan covers a subset of gitleaks rules' },
+  { ciJob: 'postgres + pgvector integration', prePushLabel: null, preCommitCheck: null,                            critical: false, note: 'CI-only: requires Docker Postgres + pgvector container; not practical locally', localMirror: 'ci-only' },
+  { ciJob: 'docs drift check',               prePushLabel: 'docs', critical: true },
+  { ciJob: 'comment policy',                 prePushLabel: null,  preCommitCheck: 'Construct comment-lint (staged)', critical: true, note: 'pre-commit Construct policy section calls `lint:comments --staged`' },
+  { ciJob: 'template policy',                prePushLabel: null,  preCommitGhPrIntercept: true,                    critical: true, note: 'pre-push-gate intercepts `gh pr create` / `gh pr edit` and lints the body' },
+];
+
+function parseCIJobs(rootDir) {
+  const path = join(rootDir, '.github', 'workflows', 'ci.yml');
+  if (!existsSync(path)) return [];
+  const yml = readFileSync(path, 'utf8');
+  return [...yml.matchAll(/^    name:\s*(.+?)\s*$/gm)]
+    .map((m) => m[1].trim())
+    .map((n) => n.replace(/\$\{\{\s*matrix\.(\w+)\s*\}\}/g, (_, k) => `<${k}>`));
+}
+
+function parsePrePushJobs(rootDir) {
+  const path = join(rootDir, 'lib', 'hooks', 'pre-push-gate.mjs');
+  if (!existsSync(path)) return [];
+  const src = readFileSync(path, 'utf8');
+  return [...src.matchAll(/label:\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+}
+
+function parsePreCommitChecks(rootDir) {
+  const path = join(rootDir, '.beads', 'hooks', 'pre-commit');
+  if (!existsSync(path)) return [];
+  const src = readFileSync(path, 'utf8');
+  const checks = [];
+  if (src.includes('scan_added_lines')) checks.push('ECC secret scan');
+  if (src.includes('construct lint:comments --staged')) checks.push('Construct comment-lint (staged)');
+  if (src.includes('construct docs:verify --staged')) checks.push('Construct docs:verify (staged)');
+  if (src.includes('BEADS INTEGRATION')) checks.push('BEADS dispatcher');
+  return checks;
+}
+
+function getCoreHooksPath(rootDir) {
+  try {
+    return execSync('git config --get core.hooksPath', {
+      cwd: rootDir, stdio: 'pipe', encoding: 'utf8', timeout: 2000,
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function fetchBranchProtection(branch, { repo = 'geraldmaron/construct' } = {}) {
+  try {
+    const out = execSync(
+      `gh api repos/${repo}/branches/${branch}/protection/required_status_checks`,
+      { stdio: 'pipe', encoding: 'utf8', timeout: 5000 },
+    );
+    const data = JSON.parse(out);
+    return { protected: true, requiredContexts: data.contexts || [], status: 'fetched' };
+  } catch (err) {
+    const msg = err?.stderr?.toString() || err?.message || '';
+    if (/Branch not protected/i.test(msg)) {
+      return { protected: false, requiredContexts: [], status: 'unprotected' };
+    }
+    return { protected: false, requiredContexts: [], status: 'unfetchable' };
+  }
+}
+
+function ciHasJob(ciJobs, jobName) {
+  if (ciJobs.includes(jobName)) return true;
+  const stripped = jobName.replace(/\s*\([^)]*\)\s*/g, '').trim();
+  return ciJobs.some((j) => j.replace(/\s*\(.*?\)\s*/g, '').trim() === stripped);
+}
+
+function identifyGaps(state) {
+  const { ciJobs, prePushJobs, preCommitChecks, branchProtection, hooksPath, rootDir, inCI } = state;
+  const gaps = [];
+  const protectionVisible = branchProtection.status === 'fetched' || branchProtection.status === 'unprotected';
+
+  for (const def of GATE_DEFINITIONS) {
+    const inCi = ciHasJob(ciJobs, def.ciJob);
+    if (!inCi) {
+      gaps.push({ kind: 'missing-ci', gate: def.ciJob, critical: def.critical });
+      continue;
+    }
+
+    if (def.critical && protectionVisible) {
+      const required = branchProtection.requiredContexts.includes(def.ciJob);
+      if (!required) {
+        gaps.push({ kind: 'not-required-to-merge', gate: def.ciJob, critical: true });
+      }
+    }
+
+    const hasPrePush = def.prePushLabel ? prePushJobs.includes(def.prePushLabel) : false;
+    const hasPreCommit = def.preCommitCheck ? preCommitChecks.includes(def.preCommitCheck) : false;
+    const hasIntercept = !!def.preCommitGhPrIntercept;
+    const hasLocal = hasPrePush || hasPreCommit || hasIntercept || def.localMirror === 'ci-only';
+
+    if (def.critical && !hasLocal) {
+      gaps.push({ kind: 'no-local-mirror', gate: def.ciJob, note: def.note, critical: true });
+    }
+    if (!def.critical && !hasLocal && !def.note) {
+      gaps.push({ kind: 'no-local-mirror-advisory', gate: def.ciJob, critical: false });
+    }
+  }
+
+  if (protectionVisible) {
+    for (const ctx of branchProtection.requiredContexts) {
+      if (!ciHasJob(ciJobs, ctx)) {
+        gaps.push({ kind: 'required-but-not-in-ci', gate: ctx, critical: true });
+      }
+    }
+  }
+
+  if (!inCI && existsSync(join(rootDir, '.beads', 'hooks', 'pre-commit')) && hooksPath !== '.beads/hooks') {
+    gaps.push({
+      kind: 'hooks-unwired',
+      expected: '.beads/hooks',
+      actual: hooksPath || '(unset)',
+      critical: true,
+      note: 'pre-commit policy gates are inactive locally; fix with: git config core.hooksPath .beads/hooks',
+    });
+  }
+
+  return gaps;
+}
+
+export function auditGates({ rootDir = DEFAULT_ROOT_DIR, repo, branch = 'main' } = {}) {
+  const inCI = process.env.CI === 'true' || process.env.CI === '1';
+  const ciJobs = parseCIJobs(rootDir);
+  const prePushJobs = parsePrePushJobs(rootDir);
+  const preCommitChecks = parsePreCommitChecks(rootDir);
+  const hooksPath = getCoreHooksPath(rootDir);
+  const branchProtection = fetchBranchProtection(branch, repo ? { repo } : {});
+
+  const state = { ciJobs, prePushJobs, preCommitChecks, branchProtection, hooksPath, rootDir, inCI };
+  const gaps = identifyGaps(state);
+  const criticalGaps = gaps.filter((g) => g.critical);
+
+  return {
+    rootDir,
+    ciJobs,
+    prePushJobs,
+    preCommitChecks,
+    hooksPath,
+    branchProtection,
+    gaps,
+    criticalGaps,
+    inCI,
+    ok: criticalGaps.length === 0,
+  };
+}
+
+export function formatReport(report) {
+  const lines = [];
+  lines.push('Construct Gates Audit');
+  lines.push('═════════════════════');
+  lines.push('');
+
+  lines.push(`CI jobs (${report.ciJobs.length}):`);
+  for (const j of report.ciJobs) lines.push(`  • ${j}`);
+  lines.push('');
+
+  lines.push(`Local pre-push gate jobs (${report.prePushJobs.length}):`);
+  for (const j of report.prePushJobs) lines.push(`  • ${j}`);
+  lines.push('');
+
+  lines.push(`Local pre-commit checks (${report.preCommitChecks.length}):`);
+  for (const j of report.preCommitChecks) lines.push(`  • ${j}`);
+  lines.push('');
+
+  lines.push(`core.hooksPath: ${report.hooksPath || '(unset)'}`);
+  lines.push('');
+
+  if (report.branchProtection.status === 'fetched') {
+    lines.push(`Branch protection (main): ${report.branchProtection.requiredContexts.length} required contexts`);
+    for (const c of report.branchProtection.requiredContexts) lines.push(`  • ${c}`);
+  } else if (report.branchProtection.status === 'unprotected') {
+    lines.push('Branch protection (main): NOT PROTECTED — no gate enforces CI before merge');
+  } else {
+    lines.push('Branch protection (main): unfetchable (insufficient gh permissions) — protection-dependent gaps skipped');
+  }
+  lines.push('');
+
+  if (report.gaps.length === 0) {
+    lines.push('Gaps: none');
+  } else {
+    lines.push(`Gaps (${report.gaps.length}; ${report.criticalGaps.length} critical):`);
+    for (const g of report.gaps) {
+      const marker = g.critical ? '✗' : '⚠';
+      const detail = g.note ? ` — ${g.note}` : '';
+      const extra = g.kind === 'hooks-unwired' ? ` (expected ${g.expected}, actual ${g.actual})` : '';
+      lines.push(`  ${marker} ${g.kind}: ${g.gate || ''}${extra}${detail}`);
+    }
+  }
+  lines.push('');
+
+  lines.push(`Summary: ${report.ok ? 'OK ✓' : `${report.criticalGaps.length} critical gap(s) ✗`}`);
+
+  return lines.join('\n') + '\n';
+}

package/lib/git-hooks/prepare-commit-msg

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * lib/git-hooks/prepare-commit-msg
+ *
+ * Git hook that appends AI provenance trailers to every commit message.
+ * Follows the RFC 9562 / git-interpret-trailers convention.
+ *
+ * Trailers added (when env vars are present):
+ *   AI-Generator: construct/sync-agents
+ *   AI-Model:     claude-sonnet-4-6
+ *   AI-Session:   019dbb90-5885-...
+ *
+ * Install for a repo:
+ *   construct doc install-hooks
+ *
+ * Or manually:
+ *   cp node_modules/.bin/construct-prepare-commit-msg .git/hooks/prepare-commit-msg
+ *   chmod +x .git/hooks/prepare-commit-msg
+ *
+ * The hook reads env vars set by Construct sessions:
+ *   CONSTRUCT_MODEL       — active model name
+ *   CONSTRUCT_SESSION_ID  — UUIDv7 session id
+ *   CONSTRUCT_GENERATOR   — generator label (optional)
+ */
+
+import fs from 'node:fs';
+
+const msgFile = process.argv[2];
+const source  = process.argv[3]; // 'message', 'template', 'merge', 'squash', 'commit'
+
+// Only annotate regular commits and explicit message commits, not merges/squashes
+if (source === 'merge' || source === 'squash') process.exit(0);
+if (!msgFile) process.exit(0);
+
+const model     = process.env.CONSTRUCT_MODEL;
+const sessionId = process.env.CONSTRUCT_SESSION_ID;
+const generator = process.env.CONSTRUCT_GENERATOR;
+
+// Nothing to add if no Construct env vars are set
+if (!model && !sessionId && !generator) process.exit(0);
+
+const original = fs.readFileSync(msgFile, 'utf8');
+
+// Build trailers — only include fields that are populated
+const trailers = [];
+if (generator) trailers.push(`AI-Generator: ${generator}`);
+if (model)     trailers.push(`AI-Model: ${model}`);
+if (sessionId) trailers.push(`AI-Session: ${sessionId}`);
+
+if (!trailers.length) process.exit(0);
+
+// git-interpret-trailers convention: trailers follow a blank line after the body.
+// We append only if the trailers aren't already present (idempotent).
+const alreadyPresent = trailers.every(t => original.includes(t.split(':')[0] + ':'));
+if (alreadyPresent) process.exit(0);
+
+const separator = original.trimEnd().endsWith('\n\n') ? '' : '\n\n';
+fs.writeFileSync(msgFile, original.trimEnd() + separator + trailers.join('\n') + '\n');