@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/registry/docs-sync.mjs

@@ -0,0 +1,67 @@
+/**
+ * lib/registry/docs-sync.mjs — Sync narrative docs AUTO regions from the capability catalog.
+ *
+ * Generated regions are machine-owned; surrounding prose stays narrative.
+ * Drift is checked via `npm run docs:sync -- --check` in release:check.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadCapabilityRegistry } from './validate.mjs';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
+
+function replaceRegion(content, regionName, newBody) {
+  const open = `<!-- AUTO:${regionName} -->`;
+  const close = `<!-- /AUTO:${regionName} -->`;
+  const before = content.indexOf(open);
+  const after = content.indexOf(close);
+  if (before === -1 || after === -1) return null;
+  return `${content.slice(0, before + open.length)}\n${newBody}\n${content.slice(after)}`;
+}
+
+function buildCatalogDocsRegion(registry) {
+  const caps = (registry.capabilities ?? [])
+    .filter((cap) => cap.criticality === 'P0' || cap.criticality === 'P1')
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const lines = [
+    '## Capability catalog (generated)',
+    '',
+    '> Narrative docs index — this table is regenerated from `registry/capabilities.json`.',
+    '> Run `npm run docs:sync` after catalog changes. Do not hand-edit inside the AUTO markers.',
+    '',
+    `Catalog census: ${registry.catalog?.cliCommands?.length ?? 0} CLI commands, `
+      + `${registry.catalog?.npmScripts?.length ?? 0} npm scripts, `
+      + `${registry.catalog?.workflowTypes?.length ?? 0} embedded workflows.`,
+    '',
+    '| Capability | Criticality | CLI surface | Verification |',
+    '|---|---|---|---|',
+  ];
+
+  for (const cap of caps) {
+    const cli = cap.surfaces?.cli?.supported ? (cap.surfaces.cli.command || cap.edges?.cliCommands?.[0] || '—') : '—';
+    const ver = cap.verification?.functional || cap.verification?.hostEmulation || '—';
+    lines.push(`| \`${cap.id}\` | ${cap.criticality} | ${cli} | \`${ver}\` |`);
+  }
+
+  return lines.join('\n');
+}
+
+export function syncCatalogDocs({ rootDir = REPO_ROOT, check = false } = {}) {
+  const readmePath = path.join(rootDir, 'docs', 'README.md');
+  const registry = loadCapabilityRegistry({ rootDir });
+  const regionBody = buildCatalogDocsRegion(registry);
+  const existing = fs.readFileSync(readmePath, 'utf8');
+  const next = replaceRegion(existing, 'catalog-sync', regionBody);
+  if (!next) {
+    return { ok: false, changed: false, error: 'docs/README.md missing AUTO:catalog-sync region' };
+  }
+  if (next === existing) return { ok: true, changed: false, path: readmePath };
+  if (check) return { ok: false, changed: true, path: readmePath, error: 'docs/README.md catalog-sync region drift — run npm run docs:sync' };
+  fs.writeFileSync(readmePath, next, 'utf8');
+  return { ok: true, changed: true, path: readmePath };
+}

package/lib/registry/loader.mjs

@@ -0,0 +1,147 @@
+/**
+ * lib/registry/loader.mjs — Unified registry loader (modular org, runtime merge).
+ *
+ * Assembles specialists/org/** at load time, validates, caches by org dir mtime.
+ * Supports legacy .cx/unified-registry.json overlay for specialists/teams only.
+ *
+ * Export: loadRegistry, getTeam, getSpecialist, getContract, getPolicy,
+ *         listTeams, listSpecialists, listGroupsHierarchical, clearCache
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { validate } from './validator.mjs';
+import { assembleRegistry, orgDirMtime, listTeamsFromRegistry, listGroupsHierarchical } from './assemble.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = path.resolve(__dirname, '..', '..');
+
+let _registry = null;
+let _orgMtime = null;
+let _legacyOverlayMtime = null;
+
+function mergeLegacyOverlay(registry, overlay) {
+  if (overlay.teams) {
+    for (const [id, team] of Object.entries(overlay.teams)) {
+      registry.teams[id] = { ...registry.teams[id], ...team };
+    }
+  }
+  if (overlay.specialists) {
+    for (const [id, spec] of Object.entries(overlay.specialists)) {
+      registry.specialists[id] = { ...registry.specialists[id], ...spec };
+    }
+  }
+  if (overlay.contracts) {
+    for (const [id, contract] of Object.entries(overlay.contracts)) {
+      registry.contracts[id] = { ...registry.contracts[id], ...contract };
+    }
+  }
+  if (overlay.policies) {
+    for (const [id, policy] of Object.entries(overlay.policies)) {
+      registry.policies[id] = { ...registry.policies[id], ...policy };
+    }
+  }
+  for (const key of ['mcpServers', 'models', 'prefix', 'system', 'orchestrator']) {
+    if (overlay[key] !== undefined) registry[key] = overlay[key];
+  }
+}
+
+export function loadRegistry(opts = {}) {
+  const skipValidation = opts.skipValidation === true;
+  const rootDir = opts.rootDir ? path.resolve(opts.rootDir) : ROOT_DIR;
+
+  const orgMtime = orgDirMtime(rootDir);
+  const legacyOverlayPath = path.join(rootDir, '.cx', 'unified-registry.json');
+  let legacyOverlayMtime = null;
+  let legacyOverlay = null;
+  try {
+    legacyOverlayMtime = fs.statSync(legacyOverlayPath).mtimeMs;
+    legacyOverlay = JSON.parse(fs.readFileSync(legacyOverlayPath, 'utf8'));
+  } catch {
+    legacyOverlay = null;
+  }
+
+  if (_registry && _orgMtime === orgMtime && _legacyOverlayMtime === legacyOverlayMtime) {
+    return _registry;
+  }
+
+  const registry = assembleRegistry(rootDir);
+  if (legacyOverlay) {
+    mergeLegacyOverlay(registry, legacyOverlay);
+  }
+
+  if (!skipValidation) {
+    const result = validate(registry);
+    if (!result.ok) {
+      throw new Error(`Unified registry validation failed:\n${result.errors.map((e) => `  - ${e.id}: ${e.message}`).join('\n')}`);
+    }
+  }
+
+  _registry = registry;
+  _orgMtime = orgMtime;
+  _legacyOverlayMtime = legacyOverlayMtime;
+
+  return registry;
+}
+
+export function getTeam(id, opts = {}) {
+  const registry = loadRegistry(opts);
+  return registry.teams[id] || null;
+}
+
+export function getSpecialist(id, opts = {}) {
+  const registry = loadRegistry(opts);
+  const specId = id.startsWith('cx-') ? id : `cx-${id}`;
+  return registry.specialists[specId] || null;
+}
+
+export function getContract(producer, consumer, opts = {}) {
+  const registry = loadRegistry(opts);
+  for (const contract of Object.values(registry.contracts)) {
+    if (contract.producer === producer && contract.consumer === consumer) {
+      return contract;
+    }
+  }
+  return null;
+}
+
+export function getPolicy(id, opts = {}) {
+  const registry = loadRegistry(opts);
+  return registry.policies[id] || null;
+}
+
+export function listTeams(opts = {}) {
+  const registry = loadRegistry(opts);
+  return listTeamsFromRegistry(registry, { kind: opts.kind });
+}
+
+export { listGroupsHierarchical };
+
+export function listSpecialists(teamId, opts = {}) {
+  const registry = loadRegistry(opts);
+  const specs = Object.entries(registry.specialists).map(([id, spec]) => ({ id, ...spec }));
+  if (!teamId) return specs;
+  return specs.filter((spec) => spec.team === teamId || spec.teamId === teamId);
+}
+
+export function clearCache() {
+  _registry = null;
+  _orgMtime = null;
+  _legacyOverlayMtime = null;
+}
+
+export { assembleRegistry };
+
+export default {
+  loadRegistry,
+  getTeam,
+  getSpecialist,
+  getContract,
+  getPolicy,
+  listTeams,
+  listGroupsHierarchical,
+  listSpecialists,
+  clearCache,
+  assembleRegistry,
+};

package/lib/registry/org-io.mjs

@@ -0,0 +1,76 @@
+/**
+ * lib/registry/org-io.mjs — modular org filesystem helpers.
+ *
+ * Resolves entity JSON paths under specialists/org/** and assembles registry
+ * snapshots from a git ref for diff tooling.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+const ORG_SECTIONS = [
+  ['groups', 'teams'],
+  ['teams', 'teams'],
+  ['specialists', 'specialists'],
+  ['contracts', 'contracts'],
+  ['policies', 'policies'],
+];
+
+export function findOrgEntityFile(rootDir, section, id) {
+  const dir = path.join(rootDir, 'specialists', 'org', section);
+  if (!fs.existsSync(dir)) return null;
+  const direct = path.join(dir, `${id}.json`);
+  if (fs.existsSync(direct)) return direct;
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const filePath = path.join(dir, name);
+    try {
+      const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      if (raw.id === id || name.replace(/\.json$/, '') === id) return filePath;
+    } catch { /* skip malformed */ }
+  }
+  return null;
+}
+
+export function findTeamFile(rootDir, teamId) {
+  return findOrgEntityFile(rootDir, 'teams', teamId)
+    || findOrgEntityFile(rootDir, 'groups', teamId);
+}
+
+export function removeOrgEntityFile(rootDir, section, id) {
+  const filePath = findOrgEntityFile(rootDir, section, id);
+  if (!filePath) return false;
+  fs.unlinkSync(filePath);
+  return true;
+}
+
+export function assembleRegistryAtGitRef(rootDir, ref = 'HEAD') {
+  const assembled = { version: 3, teams: {}, specialists: {}, contracts: {}, policies: {} };
+  for (const [dirName, bucket] of ORG_SECTIONS) {
+    let files = [];
+    try {
+      const out = execSync(`git ls-tree -r --name-only ${ref} -- specialists/org/${dirName}`, {
+        cwd: rootDir,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'ignore'],
+      }).trim();
+      files = out ? out.split('\n').filter(Boolean) : [];
+    } catch { /* no org at ref */ }
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      try {
+        const content = execSync(`git show ${ref}:${file}`, {
+          cwd: rootDir,
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'ignore'],
+        });
+        const raw = JSON.parse(content);
+        const entityId = raw.id || path.basename(file, '.json');
+        const { id: _drop, ...rest } = raw;
+        assembled[bucket][entityId] = { id: entityId, ...rest };
+      } catch { /* skip unreadable */ }
+    }
+  }
+  return assembled;
+}

package/lib/registry/retired-paths.mjs

@@ -0,0 +1,71 @@
+/**
+ * lib/registry/retired-paths.mjs — retired registry path needles for lint gates.
+ *
+ * specialists/registry.json and specialists/unified-registry.json were removed
+ * in favor of modular specialists/org/** assembled by loadRegistry().
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const RETIRED_REGISTRY_PATHS = Object.freeze([
+  'specialists/registry.json',
+  'specialists/unified-registry.json',
+]);
+
+export const RETIRED_REGISTRY_PATH_ALLOWLIST = Object.freeze([
+  'CHANGELOG.md',
+  'docs/decisions/adr/0037-specialist-prompt-format.md',
+  'docs/decisions/adr/0031-browser-automation-is-opt-in.md',
+  'docs/decisions/adr/0033-platform-capability-registry.md',
+  'docs/decisions/adr/0046-modular-org-runtime-merge.md',
+  'docs/decisions/rfc/0004-team-orchestration-integration.md',
+  'docs/guides/concepts/teams.md',
+  'lib/migrations/v2-unified-registry.mjs',
+  'scripts/migrate-org-modular.mjs',
+  'scripts/migrate-unified-registry.mjs',
+  'scripts/migrate-specialist-prompt-frontmatter.mjs',
+  'scripts/patch-registry-readers.mjs',
+  'scripts/patch-registry-readers-v2.mjs',
+  'tests/no-monolithic-registry.test.mjs',
+  'tests/migration-round-trip.test.mjs',
+]);
+
+export function isRetiredRegistryPathAllowed(relPath) {
+  if (RETIRED_REGISTRY_PATH_ALLOWLIST.includes(relPath)) return true;
+  if (relPath.startsWith('docs/operations/audit/')) return true;
+  if (relPath.startsWith('docs/notes/research/')) return true;
+  if (relPath.startsWith('docs/specs/')) return true;
+  if (relPath.startsWith('docs/decisions/')) return true;
+  if (relPath.startsWith('lib/migrations/')) return true;
+  if (relPath.endsWith('.bak')) return true;
+  return false;
+}
+
+export function scanRetiredRegistryPathReferences(rootDir) {
+  const root = path.resolve(rootDir);
+  const hits = [];
+  const SKIP_DIRS = new Set(['.git', 'node_modules', '.cx', 'dist', 'coverage', '.next', '.claude', '.codex', '.cursor', '.github', '.opencode']);
+  const SKIP_FILES = new Set(['lib/registry/retired-paths.mjs']);
+  const SKIP_PREFIXES = ['apps/docs/.claude/', 'apps/docs/.codex/', 'apps/docs/.opencode/'];
+  const EXT = new Set(['.mjs', '.js', '.md', '.mdx', '.json']);
+  const walk = (dir) => {
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (SKIP_DIRS.has(ent.name)) continue;
+      const abs = path.join(dir, ent.name);
+      const rel = path.relative(root, abs).split(path.sep).join('/');
+      if (ent.isDirectory()) walk(abs);
+      else if (EXT.has(path.extname(ent.name)) && !SKIP_FILES.has(rel) && !SKIP_PREFIXES.some((p) => rel.startsWith(p)) && !isRetiredRegistryPathAllowed(rel)) {
+        const content = fs.readFileSync(abs, 'utf8');
+        for (const needle of RETIRED_REGISTRY_PATHS) {
+          if (content.includes(needle)) {
+            hits.push({ file: rel, needle });
+            break;
+          }
+        }
+      }
+    }
+  };
+  if (fs.existsSync(root)) walk(root);
+  return hits;
+}

package/lib/registry/surface-map.mjs

@@ -8,18 +8,16 @@
  *   agent-mcp — MCP tool canonical; CLI --json twin
  *   thin-cli  — human types this at a prompt
  *   tui       — interactive loop emphasized
- *   dashboard — visual/telemetry emphasized
  *   internal  — CI/harness only
  */
 
-export const SURFACE_TIERS = ['agent-mcp', 'thin-cli', 'tui', 'dashboard', 'internal'];
+export const SURFACE_TIERS = ['agent-mcp', 'thin-cli', 'tui', 'internal'];
 
 /** @type {Record<string, string>} */
 export const COMMAND_SURFACE = {
   install: 'thin-cli',
   init: 'thin-cli',
   dev: 'thin-cli',
-  dashboard: 'thin-cli',
   stop: 'thin-cli',
   status: 'thin-cli',
   doctor: 'thin-cli',
@@ -41,10 +39,10 @@ export const COMMAND_SURFACE = {
   models: 'agent-mcp',
   profile: 'tui',
   sandbox: 'tui',
-  review: 'dashboard',
-  telemetry: 'dashboard',
-  evals: 'dashboard',
-  improvement: 'dashboard',
+  review: 'thin-cli',
+  telemetry: 'thin-cli',
+  evals: 'thin-cli',
+  improvement: 'thin-cli',
   ci: 'thin-cli',
   docs: 'thin-cli',
   export: 'agent-mcp',