@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/publish.mjs

@@ -3,7 +3,7 @@
  *
  * Single compound run: artifact release gate (default), detect tooling, export
  * markdown (pandoc-ext/diagram + Construct PDF template), optional VHS terminal
- * demo, optional Playwright dashboard demo. --strict requires toolchain and gate.
+ * demo, optional Playwright recording. --strict requires toolchain and gate.
  */
 
 import fs from 'node:fs';
@@ -11,7 +11,6 @@ import path from 'node:path';
 import { exportMarkdown, parsePublishFrontmatter, EXPORT_FORMATS } from './document-export.mjs';
 import { detectPublishPipeline } from './publish-tooling.mjs';
 import { runDemoRecord } from './demo.mjs';
-import { recordDashboardDemo } from './dashboard-demo.mjs';
 import { loadDemoRecording } from './demo-recording.mjs';
 import { recordPlaywrightDemo } from './playwright-demo.mjs';
 import { validateArtifactRelease } from './artifact-release-gate.mjs';
@@ -46,7 +45,6 @@ export function runPublish({
   format = 'pdf',
   outputPath,
   demos = [],
-  dashboardDemos = [],
   recordings = [],
   figures = true,
   strict = true,
@@ -62,27 +60,26 @@ export function runPublish({
     return { ok: false, message: `Input not found: ${resolvedIn}` };
   }
 
+  const explicitDemos = demos.length > 0;
+  const explicitRecordings = recordings.length > 0;
   let demoNames = demos;
-  let dashNames = dashboardDemos;
   let recordingNames = recordings;
-  if (!demoNames.length && !dashNames.length && !recordingNames.length) {
+  if (!demoNames.length && !recordingNames.length) {
     const fm = parsePublishFrontmatter(resolvedIn);
     if (fm?.demo) demoNames = [fm.demo];
-    if (fm?.dashboardDemo) dashNames = [fm.dashboardDemo];
     if (fm?.recording) recordingNames = [fm.recording];
   }
 
   const detection = detectPublishPipeline({
     format,
     includeFigures: figures,
-    includeTerminalDemo: demoNames.length > 0 && !sourceOnly,
-    includeDashboardDemo: (dashNames.length > 0 || recordingNames.length > 0) && !sourceOnly,
+    includeTerminalDemo: explicitDemos && demoNames.length > 0 && !sourceOnly,
     cwd,
     repoRoot,
     env,
   });
 
-  const ledger = { export: null, demos: [], dashboardDemos: [], recordings: [], detection, gate: null };
+  const ledger = { export: null, demos: [], recordings: [], detection, gate: null };
   const resolvedType = artifactType || inferArtifactTypeFromPath(resolvedIn, { rootDir: cwd });
 
   if (gate && !sourceOnly && resolvedType) {
@@ -131,40 +128,33 @@ export function runPublish({
   }
 
   for (const name of demoNames) {
+    const demoRequired = explicitDemos && strict && !sourceOnly;
     const demoResult = runDemoRecord(name, {
       cwd,
       format: 'mp4',
-      sourceOnly: sourceOnly || (!strict && !detection.steps?.terminalDemo?.present),
-      required: strict && !sourceOnly,
+      sourceOnly: sourceOnly || (!demoRequired && !detection.steps?.terminalDemo?.present),
+      required: demoRequired,
       surface: 'tape',
     });
     ledger.demos.push(demoResult);
-    if (strict && !sourceOnly && demoResult.required && !demoResult.ok) {
+    if (demoRequired && !demoResult.ok) {
       return { ok: false, strict: true, ledger, message: demoResult.message };
     }
   }
 
-  for (const name of dashNames) {
-    const dashResult = recordDashboardDemo(name, { cwd, repoRoot, env });
-    ledger.dashboardDemos.push(dashResult);
-    if (strict && !sourceOnly && !dashResult.ok) {
-      return { ok: false, strict: true, ledger, message: dashResult.message };
-    }
-  }
-
   for (const name of recordingNames) {
     const recording = loadDemoRecording(name, { cwd, repoRoot: repoRoot || cwd });
     if (!recording) {
       const miss = { ok: false, name, message: `Recording not found: ${name}` };
       ledger.recordings.push(miss);
-      if (strict && !sourceOnly) {
+      if (explicitRecordings && strict && !sourceOnly) {
         return { ok: false, strict: true, ledger, message: miss.message };
       }
       continue;
     }
     const recResult = recordPlaywrightDemo(recording, { cwd, repoRoot: repoRoot || cwd, env });
     ledger.recordings.push(recResult);
-    if (strict && !sourceOnly && !recResult.ok) {
+    if (explicitRecordings && strict && !sourceOnly && !recResult.ok) {
       return { ok: false, strict: true, ledger, message: recResult.message };
     }
   }
@@ -191,7 +181,6 @@ Options:
   --output=<path>         Output path (default: .cx/publish/<name>.<format>)
   --type=<doc-type>       Artifact type for release gate (inferred from path when omitted)
   --demo=<name>           Terminal VHS tape name (repeatable)
-  --dashboard-demo=<name> Playwright demo spec basename (repeatable)
   --recording=<name>      Playwright recording manifest (repeatable)
   --no-figures            Skip pandoc-ext/diagram filter
   --no-gate               Skip artifact release gate (maintainer escape hatch)
@@ -203,7 +192,6 @@ Options:
 Frontmatter (optional):
   publish:
     demo: resource-guard-rails
-    dashboardDemo: cockpit-tour
     recording: agentic-platforms-prd
 
 Examples:
@@ -218,7 +206,6 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     output: null,
     type: null,
     demos: [],
-    dashboardDemos: [],
     figures: true,
     strict: true,
     gate: true,
@@ -245,8 +232,6 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     if (arg.startsWith('--type=')) { options.type = arg.slice(7); continue; }
     if (arg === '--demo') { options.demos.push(argv[++i]); continue; }
     if (arg.startsWith('--demo=')) { options.demos.push(arg.slice(7)); continue; }
-    if (arg === '--dashboard-demo') { options.dashboardDemos.push(argv[++i]); continue; }
-    if (arg.startsWith('--dashboard-demo=')) { options.dashboardDemos.push(arg.slice(17)); continue; }
     if (!arg.startsWith('--')) options.input = arg;
   }
 
@@ -260,7 +245,6 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
       format: options.format,
       includeFigures: options.figures,
       includeTerminalDemo: options.demos.length > 0,
-      includeDashboardDemo: options.dashboardDemos.length > 0,
       cwd,
       repoRoot,
     });
@@ -278,7 +262,6 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     format: options.format,
     outputPath: options.output,
     demos: options.demos,
-    dashboardDemos: options.dashboardDemos,
     figures: options.figures,
     strict: options.strict,
     gate: options.gate,

package/lib/reconcile/mcp-entry-reconcile.mjs

@@ -18,6 +18,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -34,17 +35,21 @@ function escapeRegExp(value) {
 }
 
 function registryMcpServers() {
-  const installed = path.join(constructDir(), 'specialists', 'registry.json');
-  const bundled = fileURLToPath(new URL('../../specialists/registry.json', import.meta.url));
-  for (const src of [installed, bundled]) {
+  for (const rootDir of [constructDir(), fileURLToPath(new URL('../..', import.meta.url))]) {
     try {
-      const parsed = JSON.parse(fs.readFileSync(src, 'utf8'));
-      if (parsed && parsed.mcpServers) return parsed.mcpServers;
-    } catch {
-      continue;
-    }
+      const registry = loadRegistry({ rootDir, skipValidation: true });
+      if (registry?.mcpServers && Object.keys(registry.mcpServers).length > 0) {
+        return registry.mcpServers;
+      }
+    } catch { /* try next root */ }
+  }
+  try {
+    const templatePath = path.join(constructDir(), 'platforms', 'claude', 'settings.template.json');
+    const template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+    return template.mcpServers || {};
+  } catch {
+    return {};
   }
-  return {};
 }
 
 function hasMcpTable(text, id) {

package/lib/reflect.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/reflect.mjs — construct reflect command implementation.
  *
- * Captures improvement feedback from chat sessions and updates Construct core
+ * Captures improvement feedback from host sessions and updates Construct core
  * knowledge base with actionable insights for continuous self-improvement.
  */
 
@@ -259,4 +259,4 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
-}
+}

package/lib/registry/agent-manifest.mjs

@@ -0,0 +1,190 @@
+/**
+ * lib/registry/agent-manifest.mjs — load, regenerate, and verify the agent execution manifest.
+ *
+ * The manifest (registry/agent-manifest.json) declares the MCP-first tool surface
+ * agents should reach for and the OpenCode-first human entry. The structural
+ * facts must stay honest against live sources rather than drifting into
+ * hand-maintained copy:
+ *   - the CORE tool set, which is the CORE_TOOL_NAMES Set literal in
+ *     lib/mcp/server.mjs (that constant is not exported, so it is parsed from the
+ *     source text — the single authority for what the MCP ListTools front-loads);
+ *   - the long-tail dispatcher name `construct_call`;
+ *   - the OpenCode human conversation entry (the non-interactive CLI remains the admin/headless substrate);
+ *   - the MCP gap list, which is exactly the capabilities declaring surfaces.mcp.supported=false
+ *     in registry/capabilities.json, with the CLI fallback taken from surfaces.cli.command.
+ *
+ * generateAgentManifest reconciles those source-derived facts onto the curated prose
+ * (tool `use` strings, rationales, credential guidance, gap reasons) carried by the
+ * committed manifest and emits canonical JSON, so the human-owned copy round-trips while
+ * any drift in a live-source fact is caught by the --check path in registry:generate-docs.
+ * parseCoreToolNames reads the server source and returns the declared set so callers and
+ * tests verify the manifest against the server instead of re-stating the list.
+ * Read-only by default: generateAgentManifest writes only when asked.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadCapabilityRegistry } from './validate.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, '..', '..');
+
+export const MANIFEST_PATH = resolve(REPO_ROOT, 'registry', 'agent-manifest.json');
+export const MCP_SERVER_PATH = resolve(REPO_ROOT, 'lib', 'mcp', 'server.mjs');
+
+export const LONG_TAIL_DISPATCH_TOOL = 'call';
+
+export function loadAgentManifest(path = MANIFEST_PATH) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+// CORE_TOOL_NAMES is a `new Set([...])` literal of single-quoted tool names.
+// Capture the array body between the brackets, then pull each quoted token so the
+// parser tolerates reordering and reflow but fails loudly if the constant is gone.
+
+export function parseCoreToolNames(source) {
+  const block = source.match(/const\s+CORE_TOOL_NAMES\s*=\s*new\s+Set\(\[([\s\S]*?)\]\)/);
+  if (!block) {
+    throw new Error('CORE_TOOL_NAMES Set literal not found in MCP server source');
+  }
+  const names = [...block[1].matchAll(/'([^']+)'/g)].map((m) => m[1]);
+  if (names.length === 0) {
+    throw new Error('CORE_TOOL_NAMES literal parsed to an empty set');
+  }
+  return names;
+}
+
+export function readCoreToolNames(path = MCP_SERVER_PATH) {
+  return parseCoreToolNames(readFileSync(path, 'utf8'));
+}
+
+// Structural gate shared by the test and any future generator: the manifest must
+// front-load exactly the live CORE set, expose construct_call as the long-tail
+// door, name OpenCode as the primary human conversation entry, and never mention
+// the removed local-loop subcommand.
+
+export function verifyAgentManifest(manifest, { coreToolNames } = {}) {
+  const errors = [];
+  const core = coreToolNames ?? readCoreToolNames();
+
+  const tools = manifest?.toolSurface;
+  if (!tools || typeof tools !== 'object') {
+    errors.push('toolSurface object missing');
+  } else {
+    const declaredCore = Array.isArray(tools.core) ? tools.core.map((t) => t.name) : null;
+    if (!declaredCore) {
+      errors.push('toolSurface.core must be an array of tool entries');
+    } else {
+      const missing = core.filter((n) => !declaredCore.includes(n));
+      const extra = declaredCore.filter((n) => !core.includes(n));
+      if (missing.length) errors.push(`toolSurface.core missing CORE_TOOL_NAMES: ${missing.join(', ')}`);
+      if (extra.length) errors.push(`toolSurface.core lists non-core tools: ${extra.join(', ')}`);
+    }
+    if (tools.longTail?.tool !== LONG_TAIL_DISPATCH_TOOL) {
+      errors.push(`toolSurface.longTail.tool must be ${LONG_TAIL_DISPATCH_TOOL}`);
+    }
+  }
+
+  const entry = manifest?.humanEntry;
+  if (!entry || entry.surface !== 'opencode' || entry.command !== 'opencode') {
+    errors.push('humanEntry must name OpenCode as the primary human conversation surface');
+  }
+
+  const removedLocalLoopCommand = 'construct' + ' ' + 'c' + 'hat';
+  if (JSON.stringify(manifest).includes(removedLocalLoopCommand)) {
+    errors.push('manifest must not reference the removed local-loop subcommand');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// The MCP gap list is not editorial: it is exactly the capabilities that declare
+// surfaces.mcp.supported=false. Derive id/name/cliFallback from the registry so a
+// capability flipping its MCP support shows up as drift; keep the human-written reason.
+
+function deriveMcpGaps({ rootDir = REPO_ROOT, curatedGaps = [] } = {}) {
+  const { capabilities = [] } = loadCapabilityRegistry({ rootDir });
+  const reasonById = new Map(curatedGaps.map((g) => [g.id, g.reason]));
+  return capabilities
+    .filter((cap) => cap?.surfaces?.mcp?.supported === false)
+    .map((cap) => {
+      const reason = reasonById.get(cap.id);
+      if (!reason) {
+        throw new Error(`agent-manifest: MCP gap "${cap.id}" has no curated reason in registry/agent-manifest.json`);
+      }
+      return {
+        id: cap.id,
+        name: cap.name ?? cap.id,
+        mcp: 'unsupported',
+        cliFallback: cap.surfaces?.cli?.command ?? null,
+        reason,
+      };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+// Reconcile source-of-truth structure onto the curated prose: pull the CORE set from
+// the live server source (preserving each tool's curated `use` by name), pin the
+// long-tail dispatcher and the OpenCode human entry, and derive the MCP gap list from the
+// capability registry. The committed manifest supplies the prose; live sources supply
+// the facts. Emit canonical JSON so a correct file round-trips byte-for-byte.
+
+export function generateAgentManifest({ rootDir = REPO_ROOT, write = true } = {}) {
+  const manifestPath = resolve(rootDir, 'registry', 'agent-manifest.json');
+  const serverPath = resolve(rootDir, 'lib', 'mcp', 'server.mjs');
+  const current = loadAgentManifest(manifestPath);
+  const coreToolNames = readCoreToolNames(serverPath);
+
+  const useByName = new Map(
+    (current.toolSurface?.core ?? []).map((t) => [t.name, t.use]),
+  );
+  const core = coreToolNames.map((name) => {
+    const use = useByName.get(name);
+    if (!use) {
+      throw new Error(`agent-manifest: core tool "${name}" has no curated use string in registry/agent-manifest.json`);
+    }
+    return { name, use };
+  });
+
+  const next = {
+    $schema: current.$schema,
+    version: current.version,
+    kind: current.kind,
+    description: current.description,
+    sources: current.sources,
+    toolSurface: {
+      ...current.toolSurface,
+      core,
+      longTail: {
+        ...current.toolSurface?.longTail,
+        tool: LONG_TAIL_DISPATCH_TOOL,
+      },
+    },
+    humanEntry: {
+      ...current.humanEntry,
+      surface: 'opencode',
+      command: 'opencode',
+      subcommand: null,
+    },
+    credentials: current.credentials,
+    mcpGaps: {
+      ...current.mcpGaps,
+      gaps: deriveMcpGaps({ rootDir, curatedGaps: current.mcpGaps?.gaps ?? [] }),
+    },
+  };
+
+  const content = `${JSON.stringify(next, null, 2)}\n`;
+  if (!write) {
+    const existing = readFileSync(manifestPath, 'utf8');
+    return { path: manifestPath, content, drift: existing !== content };
+  }
+  writeFileSync(manifestPath, content);
+  return { path: manifestPath, content, drift: false };
+}
+
+export function checkAgentManifestDrift({ rootDir = REPO_ROOT } = {}) {
+  const { drift, content } = generateAgentManifest({ rootDir, write: false });
+  return { drift, contentLength: content.length };
+}

package/lib/registry/assemble.mjs

@@ -0,0 +1,133 @@
+/**
+ * lib/registry/assemble.mjs — Runtime merge of modular org files into registry v3.
+ *
+ * Walks specialists/org/{groups,teams,specialists,contracts,policies}, merges
+ * .cx/org overlay fragments, and returns the assembled object for validation.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function readJsonDir(dir) {
+  const out = {};
+  if (!fs.existsSync(dir)) return out;
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const id = name.replace(/\.json$/, '');
+    const raw = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+    const entityId = raw.id || id;
+    const { id: _drop, ...rest } = raw;
+    out[entityId] = { id: entityId, ...rest };
+  }
+  return out;
+}
+
+function mergeOverlaySection(base, overlaySection) {
+  if (!overlaySection) return;
+  for (const [id, value] of Object.entries(overlaySection)) {
+    base[id] = { ...base[id], ...value };
+  }
+}
+
+function mergeOrgOverlay(orgRoot, overlayRoot) {
+  if (!fs.existsSync(overlayRoot)) return;
+  const sections = ['groups', 'teams', 'specialists', 'contracts', 'policies'];
+  for (const section of sections) {
+    const overlayDir = path.join(overlayRoot, section);
+    if (!fs.existsSync(overlayDir)) continue;
+    const baseDir = path.join(orgRoot, section === 'groups' ? 'groups' : section);
+    const base = readJsonDir(baseDir);
+    for (const name of fs.readdirSync(overlayDir)) {
+      if (!name.endsWith('.json')) continue;
+      const raw = JSON.parse(fs.readFileSync(path.join(overlayDir, name), 'utf8'));
+      const entityId = raw.id || name.replace(/\.json$/, '');
+      const { id: _drop, ...rest } = raw;
+      base[entityId] = { ...(base[entityId] || {}), id: entityId, ...rest };
+    }
+    for (const [id, value] of Object.entries(base)) {
+      writeMerged(baseDir, id, value);
+    }
+  }
+}
+
+function writeMerged() {
+  // overlay merge is in-memory only; no disk write
+}
+
+export function orgDirMtime(rootDir) {
+  const orgRoot = path.join(rootDir, 'specialists', 'org');
+  if (!fs.existsSync(orgRoot)) return 0;
+  let max = 0;
+  const walk = (dir) => {
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, ent.name);
+      if (ent.isDirectory()) walk(p);
+      else if (ent.name.endsWith('.json')) max = Math.max(max, fs.statSync(p).mtimeMs);
+    }
+  };
+  walk(orgRoot);
+  const overlay = path.join(rootDir, '.cx', 'org');
+  if (fs.existsSync(overlay)) walk(overlay);
+  return max;
+}
+
+export function assembleRegistry(rootDir) {
+  const orgRoot = path.join(rootDir, 'specialists', 'org');
+  const overlayRoot = path.join(rootDir, '.cx', 'org');
+
+  if (!fs.existsSync(orgRoot)) {
+    throw new Error(`Modular org not found: ${orgRoot}. Run node scripts/migrate-org-modular.mjs`);
+  }
+
+  const groups = readJsonDir(path.join(orgRoot, 'groups'));
+  const squads = readJsonDir(path.join(orgRoot, 'teams'));
+  const specialists = readJsonDir(path.join(orgRoot, 'specialists'));
+  const contracts = readJsonDir(path.join(orgRoot, 'contracts'));
+  const policies = readJsonDir(path.join(orgRoot, 'policies'));
+
+  if (fs.existsSync(overlayRoot)) {
+    for (const [id, val] of Object.entries(readJsonDir(path.join(overlayRoot, 'groups')))) {
+      groups[id] = { ...groups[id], ...val };
+    }
+    for (const [id, val] of Object.entries(readJsonDir(path.join(overlayRoot, 'teams')))) {
+      squads[id] = { ...squads[id], ...val };
+    }
+    for (const [id, val] of Object.entries(readJsonDir(path.join(overlayRoot, 'specialists')))) {
+      specialists[id] = { ...specialists[id], ...val };
+    }
+    mergeOverlaySection(contracts, readJsonDir(path.join(overlayRoot, 'contracts')));
+    mergeOverlaySection(policies, readJsonDir(path.join(overlayRoot, 'policies')));
+  }
+
+  const teams = { ...groups, ...squads };
+
+  for (const [specId, spec] of Object.entries(specialists)) {
+    if (!spec.team && spec.teamId) spec.team = spec.teamId;
+    if (!spec.teamId && spec.team) spec.teamId = spec.team;
+    specialists[specId] = spec;
+  }
+
+  return {
+    version: 3,
+    teams,
+    specialists,
+    contracts,
+    policies,
+  };
+}
+
+export function listTeamsFromRegistry(registry, { kind } = {}) {
+  const entries = Object.entries(registry.teams || {}).map(([id, team]) => ({ id, ...team }));
+  if (kind === 'group') return entries.filter((t) => t.kind === 'group');
+  if (kind === 'squad') return entries.filter((t) => t.kind === 'squad');
+  return entries;
+}
+
+export function listGroupsHierarchical(registry) {
+  const groups = listTeamsFromRegistry(registry, { kind: 'group' });
+  const squads = listTeamsFromRegistry(registry, { kind: 'squad' });
+  return groups.map((group) => ({
+    ...group,
+    squads: squads.filter((s) => s.groupId === group.id),
+  }));
+}