@geraldmaron/construct 1.0.6 → 1.0.8

package/lib/doctor/watchers/consistency.mjs

@@ -0,0 +1,360 @@
+/**
+ * lib/doctor/watchers/consistency.mjs — cross-surface drift watcher.
+ *
+ * Five drift checks bundled at one cadence:
+ *   1. Hook manifest ↔ files: every entry in platforms/claude/settings.template.json
+ *      points to a real .mjs file in lib/hooks/ that parses.
+ *   2. MCP registration ↔ impl: every `name === '<tool>'` branch in the MCP
+ *      dispatch resolves to an imported function, and every exported tool
+ *      function in lib/mcp/tools/*.mjs is wired into the dispatch.
+ *   3. Roles ↔ registry: every persona key in specialists/role-manifests.json
+ *      resolves to a persona or agent name in specialists/registry.json.
+ *   4. Persona promptFiles: every registry.personas[].promptFile and
+ *      registry.agents[].promptFile exists on disk.
+ *   5. Contracts ↔ schemas: specialists/contracts.json passes validateContractsFile
+ *      (cross-file refs, producer/consumer names, schema paths).
+ *
+ * Each violation produces an audit record. Blocking severity escalates to a
+ * role intake; advisory severity records only. Tick is cheap — reads JSON +
+ * directory listings, no network.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { record } from '../audit.mjs';
+import { escalate } from '../escalate.mjs';
+
+export const name = 'consistency';
+export const intervalMs = 15 * 60 * 1000;
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+export async function tick() {
+  const results = await runAllChecks({ repoRoot: REPO_ROOT });
+  const actions = [];
+  const escalations = [];
+
+  for (const finding of results.findings) {
+    record({
+      kind: finding.severity === 'blocking' ? 'escalation' : 'action',
+      watcher: name,
+      action: finding.category,
+      summary: finding.summary,
+      context: { details: finding.details },
+    });
+    actions.push({ type: finding.category, target: finding.target || null });
+    if (finding.severity === 'blocking') {
+      escalate({
+        watcher: name,
+        event: `consistency.${finding.category}`,
+        severity: 'high',
+        summary: finding.summary,
+        context: { details: finding.details },
+      });
+      escalations.push({ event: `consistency.${finding.category}`, severity: 'high' });
+    }
+  }
+
+  return { actions, escalations };
+}
+
+/**
+  * Run all six consistency checks. Returns { findings: [], passed: [] }.
+ * Pure function — no audit/escalate side effects. Surfaced separately so the
+ * `construct doctor consistency` CLI and the release-gate functional test can
+ * call it without spinning up the daemon.
+ */
+export async function runAllChecks({ repoRoot = REPO_ROOT } = {}) {
+  const findings = [];
+  const passed = [];
+
+  const hooks = checkHooksDrift({ repoRoot });
+  collect(hooks, findings, passed, 'hooks-drift');
+
+  const mcp = checkMcpDrift({ repoRoot });
+  collect(mcp, findings, passed, 'mcp-drift');
+
+  const roles = checkRolesDrift({ repoRoot });
+  collect(roles, findings, passed, 'roles-drift');
+
+  const prompts = checkPersonaPrompts({ repoRoot });
+  collect(prompts, findings, passed, 'prompt-files');
+
+  const contracts = await checkContractsDrift({ repoRoot });
+  collect(contracts, findings, passed, 'contracts-drift');
+
+  const hosts = checkHostSurfaces({ repoRoot });
+  collect(hosts, findings, passed, 'host-surfaces');
+
+  return { findings, passed };
+}
+
+function collect(result, findings, passed, defaultCategory) {
+  if (result.violations.length === 0) {
+    passed.push({ category: defaultCategory, summary: result.summary });
+    return;
+  }
+  for (const v of result.violations) {
+    findings.push({
+      category: v.category || defaultCategory,
+      severity: v.severity || 'warning',
+      summary: v.summary,
+      target: v.target || null,
+      details: v.details || null,
+    });
+  }
+}
+
+// ── Check 1: hook manifest ↔ files ─────────────────────────────────────────
+
+function checkHooksDrift({ repoRoot }) {
+  const violations = [];
+  const settingsPath = join(repoRoot, 'platforms', 'claude', 'settings.template.json');
+  const hooksDir = join(repoRoot, 'lib', 'hooks');
+
+  if (!existsSync(settingsPath)) {
+    return {
+      summary: 'settings template missing',
+      violations: [{ severity: 'blocking', summary: `settings template missing: ${settingsPath}` }],
+    };
+  }
+
+  let settings;
+  try { settings = JSON.parse(readFileSync(settingsPath, 'utf8')); }
+  catch (err) {
+    return {
+      summary: 'settings template parse error',
+      violations: [{ severity: 'blocking', summary: `settings template parse error: ${err.message}` }],
+    };
+  }
+
+  const referenced = new Set();
+  collectHookCommands(settings.hooks, referenced);
+
+  for (const hookPath of referenced) {
+    const resolvedPath = resolveHookPath(hookPath, hooksDir, repoRoot);
+    if (!resolvedPath || !existsSync(resolvedPath)) {
+      violations.push({
+        category: 'hooks-drift',
+        severity: 'blocking',
+        target: hookPath,
+        summary: `hook referenced by settings template does not exist on disk: ${hookPath}`,
+      });
+    }
+  }
+
+  return { summary: `hooks: ${referenced.size} referenced, ${violations.length} missing`, violations };
+}
+
+function collectHookCommands(node, out) {
+  if (!node) return;
+  if (Array.isArray(node)) { node.forEach((n) => collectHookCommands(n, out)); return; }
+  if (typeof node !== 'object') return;
+  if (typeof node.command === 'string' && /\.mjs/.test(node.command)) {
+    const match = node.command.match(/([\w./-]+\.mjs)/);
+    if (match) out.add(match[1]);
+  }
+  for (const v of Object.values(node)) collectHookCommands(v, out);
+}
+
+function resolveHookPath(reference, hooksDir, repoRoot) {
+  if (reference.startsWith('/')) return reference;
+  if (reference.startsWith('lib/hooks/')) return join(repoRoot, reference);
+  const bare = reference.split('/').pop();
+  return join(hooksDir, bare);
+}
+
+// ── Check 2: MCP registration ↔ impl ───────────────────────────────────────
+
+function checkMcpDrift({ repoRoot }) {
+  const violations = [];
+  const serverPath = join(repoRoot, 'lib', 'mcp', 'server.mjs');
+  const toolsDir = join(repoRoot, 'lib', 'mcp', 'tools');
+
+  if (!existsSync(serverPath) || !existsSync(toolsDir)) {
+    return { summary: 'mcp surface missing', violations: [] };
+  }
+
+  const serverSource = readFileSync(serverPath, 'utf8');
+  const dispatchedTools = new Set();
+  for (const m of serverSource.matchAll(/name === ['"]([a-z][a-z0-9_]*)['"]/g)) {
+    dispatchedTools.add(m[1]);
+  }
+
+  const exportedTools = new Set();
+  const entries = readdirSync(toolsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.mjs')) continue;
+    const src = readFileSync(join(toolsDir, entry.name), 'utf8');
+    for (const m of src.matchAll(/export (?:async )?function (\w+)/g)) {
+      exportedTools.add(camelToSnake(m[1]));
+    }
+  }
+
+  for (const tool of exportedTools) {
+    if (KNOWN_NON_DISPATCH_TOOLS.has(tool)) continue;
+    if (!dispatchedTools.has(tool)) {
+      violations.push({
+        category: 'mcp-drift',
+        severity: 'warning',
+        target: tool,
+        summary: `MCP tool exported but not dispatched: ${tool}`,
+      });
+    }
+  }
+
+  return { summary: `mcp: ${dispatchedTools.size} dispatched, ${exportedTools.size} exported, ${violations.length} drift`, violations };
+}
+
+const KNOWN_NON_DISPATCH_TOOLS = new Set([
+  // Internal helpers exported for tests but never wired through MCP.
+  'workflow_status_bound',
+  'create_needs_main_input_packet',
+]);
+
+function camelToSnake(s) {
+  return s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+}
+
+// ── Check 3: roles ↔ registry ──────────────────────────────────────────────
+
+function checkRolesDrift({ repoRoot }) {
+  const violations = [];
+  const manifestsPath = join(repoRoot, 'specialists', 'role-manifests.json');
+  const registryPath = join(repoRoot, 'specialists', 'registry.json');
+
+  if (!existsSync(manifestsPath) || !existsSync(registryPath)) {
+    return { summary: 'role manifests or registry missing', violations: [] };
+  }
+
+  const manifests = JSON.parse(readFileSync(manifestsPath, 'utf8'));
+  const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+
+  const known = new Set();
+  for (const s of registry.specialists || []) {
+    if (s?.name) { known.add(s.name); known.add(`cx-${s.name}`); }
+  }
+  if (registry.orchestrator?.name) {
+    known.add(registry.orchestrator.name);
+    known.add(`cx-${registry.orchestrator.name}`);
+  }
+
+  const personaKeys = Object.keys(manifests.personas || manifests || {});
+  for (const key of personaKeys) {
+    if (key === 'version' || key === 'description' || key === 'schemaVersion') continue;
+    if (!known.has(key) && !known.has(`cx-${key}`)) {
+      violations.push({
+        category: 'roles-drift',
+        severity: 'warning',
+        target: key,
+        summary: `role-manifests persona '${key}' does not resolve to a registry persona/agent`,
+      });
+    }
+  }
+
+  return { summary: `roles: ${personaKeys.length} manifest keys, ${violations.length} drift`, violations };
+}
+
+// ── Check 4: persona promptFile existence ──────────────────────────────────
+
+function checkPersonaPrompts({ repoRoot }) {
+  const violations = [];
+  const registryPath = join(repoRoot, 'specialists', 'registry.json');
+  if (!existsSync(registryPath)) return { summary: 'registry missing', violations: [] };
+
+  const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+  let checked = 0;
+
+  for (const list of [
+    registry.orchestrator ? [registry.orchestrator] : [],
+    registry.specialists || [],
+  ]) {
+    for (const entry of list) {
+      const ref = entry?.promptFile;
+      if (!ref) continue;
+      checked++;
+      const promptPath = ref.startsWith('/') ? ref : join(repoRoot, ref);
+      if (!existsSync(promptPath)) {
+        violations.push({
+          category: 'prompt-files',
+          severity: 'blocking',
+          target: ref,
+          summary: `registry entry '${entry.name}' references missing promptFile: ${ref}`,
+        });
+      }
+    }
+  }
+
+  return { summary: `prompt-files: ${checked} referenced, ${violations.length} missing`, violations };
+}
+
+// ── Check 5: contracts ↔ schemas ───────────────────────────────────────────
+
+async function checkContractsDrift({ repoRoot }) {
+  const violations = [];
+  try {
+    const { validateContractsFile } = await import('../../contracts/validate.mjs');
+    const result = validateContractsFile({ repoRoot });
+    if (!result.ok) {
+      for (const err of result.errors) {
+        violations.push({
+          category: 'contracts-drift',
+          severity: 'warning',
+          summary: err,
+        });
+      }
+    }
+  } catch (err) {
+    violations.push({
+      category: 'contracts-drift',
+      severity: 'warning',
+      summary: `contract validator unavailable: ${err.message}`,
+    });
+  }
+  return { summary: `contracts: ${violations.length} drift`, violations };
+}
+
+// ── Check 6: host surfaces ─────────────────────────────────────────────────
+
+function getVSCodeSettingsDir(homeDir) {
+  const platform = os.platform();
+  if (platform === 'darwin') return join(homeDir, 'Library', 'Application Support', 'Code', 'User');
+  if (platform === 'linux') return join(homeDir, '.config', 'Code', 'User');
+  const appData = process.env.APPDATA ?? join(homeDir, 'AppData', 'Roaming');
+  return join(appData, 'Code', 'User');
+}
+
+function checkHostSurfaces({ repoRoot }) {
+  const violations = [];
+  const homeDir = os.homedir();
+  const surfaces = [
+    { id: 'claude', label: 'Claude Code', check: () => existsSync(join(homeDir, '.claude', 'agents')) },
+    { id: 'opencode', label: 'OpenCode', check: () => existsSync(join(homeDir, '.config', 'opencode', 'opencode.json')) },
+    { id: 'codex', label: 'Codex', check: () => existsSync(join(homeDir, '.codex', 'agents')) },
+    { id: 'copilot', label: 'Copilot', check: () => existsSync(join(homeDir, '.github', 'prompts')) },
+    { id: 'vscode', label: 'VS Code', check: () => existsSync(join(getVSCodeSettingsDir(homeDir), 'settings.json')) },
+    { id: 'cursor', label: 'Cursor', check: () => existsSync(join(homeDir, '.cursor', 'mcp.json')) },
+  ];
+
+  const absent = surfaces.filter((s) => !s.check());
+  if (absent.length > 0) {
+    for (const s of absent) {
+      violations.push({
+        category: 'host-surfaces',
+        severity: 'advisory',
+        target: s.id,
+        summary: `Host surface '${s.label}' config not found — run \`construct sync\` to set up adapters`,
+      });
+    }
+    violations.push({
+      category: 'host-surfaces',
+      severity: 'advisory',
+      summary: `${absent.length}/${surfaces.length} host surfaces absent: ${absent.map((s) => s.id).join(', ')}`,
+    });
+  }
+
+  return { summary: `host-surfaces: ${surfaces.length - absent.length}/${surfaces.length} present`, violations };
+}

package/lib/doctor/watchers/mcp-protocol.mjs

@@ -0,0 +1,232 @@
+/**
+ * lib/doctor/watchers/mcp-protocol.mjs — MCP handshake health probe.
+ *
+ * Sweeps every MCP server configured in the active editor configs (Claude
+ * Code, OpenCode) and performs a real MCP handshake against each: send
+ * `initialize`, parse the response, send `tools/list`, report tool count.
+ * cass-memory v0.2.x (the original cause of construct-1qt) rejects the
+ * handshake outright; this watcher flags servers that fail the handshake so
+ * the dashboard surfaces a protocol problem rather than a port-up false
+ * positive.
+ *
+ * Severity defaults to warning. Set `CONSTRUCT_MCP_PROTOCOL_BLOCKING=1` to
+ * escalate via `service.down` when a configured server fails the handshake.
+ *
+ * Tick: 10 min. Cheap — most checks are skipped when no editor configs exist.
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { record } from '../audit.mjs';
+import { escalate } from '../escalate.mjs';
+
+export const name = 'mcp-protocol';
+export const intervalMs = 10 * 60 * 1000;
+
+const PROBE_TIMEOUT_MS = 5000;
+const HANDSHAKE_REQUEST_ID = 1;
+
+function readJson(file) {
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+}
+
+export function collectMcpServers({ home = homedir() } = {}) {
+  const servers = [];
+  const claudePath = join(home, '.claude', 'settings.json');
+  if (existsSync(claudePath)) {
+    const cfg = readJson(claudePath);
+    for (const [id, entry] of Object.entries(cfg?.mcpServers ?? {})) {
+      servers.push({ host: 'claude', id, entry });
+    }
+  }
+  const opencodePath = join(home, '.config', 'opencode', 'opencode.json');
+  if (existsSync(opencodePath)) {
+    const cfg = readJson(opencodePath);
+    for (const [id, entry] of Object.entries(cfg?.mcp ?? {})) {
+      servers.push({ host: 'opencode', id, entry });
+    }
+  }
+  return servers;
+}
+
+function classifyEntry(entry) {
+  if (!entry || typeof entry !== 'object') return { transport: 'unknown' };
+  if (entry.type === 'http' || entry.type === 'remote') {
+    return { transport: 'http', url: entry.url, headers: entry.headers ?? {} };
+  }
+  if (entry.type === 'local') {
+    const cmd = Array.isArray(entry.command) ? entry.command : [];
+    return { transport: 'stdio', command: cmd[0], args: cmd.slice(1), env: entry.environment ?? {} };
+  }
+  if (entry.command) {
+    return { transport: 'stdio', command: entry.command, args: entry.args ?? [], env: entry.env ?? {} };
+  }
+  return { transport: 'unknown' };
+}
+
+async function probeHttp({ url, headers }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+  try {
+    const body = {
+      jsonrpc: '2.0',
+      id: HANDSHAKE_REQUEST_ID,
+      method: 'initialize',
+      params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'construct-doctor', version: '1' } },
+    };
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', ...headers },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, reason: `HTTP ${res.status} on initialize` };
+    }
+    const text = await res.text();
+    let parsed;
+    try { parsed = JSON.parse(text); } catch {
+      return { ok: false, reason: 'initialize response was not JSON' };
+    }
+    if (parsed?.error) {
+      return { ok: false, reason: `initialize returned error: ${parsed.error.message ?? parsed.error.code}` };
+    }
+    if (/Unsupported method/i.test(text)) {
+      return { ok: false, reason: 'backend rejects initialize (Unsupported method)' };
+    }
+    return { ok: true, protocolVersion: parsed?.result?.protocolVersion };
+  } catch (err) {
+    const reason = err?.name === 'AbortError' ? 'timeout' : (err?.message || String(err));
+    return { ok: false, reason };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function spawnStdioServer({ command, args, env }) {
+  const child = spawn(command, args ?? [], {
+    env: { ...process.env, ...(env ?? {}) },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const frames = [];
+  let buffer = '';
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => {
+    buffer += chunk;
+    let idx;
+    while ((idx = buffer.indexOf('\n')) >= 0) {
+      const raw = buffer.slice(0, idx).trim();
+      buffer = buffer.slice(idx + 1);
+      if (!raw) continue;
+      try { frames.push(JSON.parse(raw)); } catch { /* skip junk */ }
+    }
+  });
+  child.stderr.on('data', () => { /* swallow */ });
+  return { child, frames };
+}
+
+async function waitFor(frames, predicate, deadline) {
+  while (Date.now() < deadline) {
+    const hit = frames.find(predicate);
+    if (hit) return hit;
+    await new Promise((r) => setTimeout(r, 25));
+  }
+  return null;
+}
+
+async function probeStdio(spec) {
+  if (!spec.command) return { ok: false, reason: 'stdio entry missing command' };
+  let session;
+  try {
+    session = spawnStdioServer(spec);
+  } catch (err) {
+    return { ok: false, reason: `spawn failed: ${err?.message || err}` };
+  }
+  const { child, frames } = session;
+  const deadline = Date.now() + PROBE_TIMEOUT_MS;
+
+  try {
+    child.stdin.write(JSON.stringify({
+      jsonrpc: '2.0',
+      id: HANDSHAKE_REQUEST_ID,
+      method: 'initialize',
+      params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'construct-doctor', version: '1' } },
+    }) + '\n');
+
+    const initFrame = await waitFor(frames, (f) => f.id === HANDSHAKE_REQUEST_ID, deadline);
+    if (!initFrame) return { ok: false, reason: 'no initialize response within timeout' };
+    if (initFrame.error) return { ok: false, reason: `initialize error: ${initFrame.error.message ?? initFrame.error.code}` };
+
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }) + '\n');
+
+    const toolsFrame = await waitFor(frames, (f) => f.id === 2, deadline);
+    if (!toolsFrame) return { ok: false, reason: 'no tools/list response within timeout' };
+    if (toolsFrame.error) return { ok: false, reason: `tools/list error: ${toolsFrame.error.message ?? toolsFrame.error.code}` };
+
+    const tools = toolsFrame.result?.tools ?? [];
+    return {
+      ok: true,
+      protocolVersion: initFrame.result?.protocolVersion,
+      toolCount: Array.isArray(tools) ? tools.length : 0,
+    };
+  } finally {
+    try { child.kill('SIGTERM'); } catch { /* already exited */ }
+  }
+}
+
+export async function probeServer({ host, id, entry }) {
+  const spec = classifyEntry(entry);
+  if (spec.transport === 'unknown') return { host, id, transport: 'unknown', ok: false, reason: 'unrecognized entry shape' };
+  const result = spec.transport === 'http' ? await probeHttp(spec) : await probeStdio(spec);
+  return { host, id, transport: spec.transport, ...result };
+}
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+  const samples = [];
+
+  const servers = collectMcpServers();
+  for (const server of servers) {
+    const result = await probeServer(server);
+    samples.push(result);
+
+    if (result.ok) {
+      record({
+        kind: 'sample',
+        watcher: name,
+        target: `${result.host}/${result.id}`,
+        result: 'ok',
+        summary: `${result.host}/${result.id} MCP handshake ok (transport=${result.transport})`,
+        context: { protocolVersion: result.protocolVersion, toolCount: result.toolCount },
+      });
+      continue;
+    }
+
+    record({
+      kind: 'sample',
+      watcher: name,
+      target: `${result.host}/${result.id}`,
+      result: 'warn',
+      summary: `${result.host}/${result.id} MCP handshake failed: ${result.reason}`,
+      context: { transport: result.transport, reason: result.reason },
+    });
+    actions.push({ type: 'protocol-warning', target: `${result.host}/${result.id}`, reason: result.reason });
+
+    if (process.env.CONSTRUCT_MCP_PROTOCOL_BLOCKING === '1') {
+      const r = await escalate({
+        watcher: name,
+        eventType: 'service.down',
+        summary: `MCP handshake failed for ${result.host}/${result.id}: ${result.reason}`,
+        context: { host: result.host, id: result.id, transport: result.transport, reason: result.reason },
+      });
+      escalations.push({ eventType: 'service.down', target: `${result.host}/${result.id}`, result: r });
+    }
+  }
+
+  return { actions, escalations, notes: samples };
+}