@geraldmaron/construct 1.3.0 → 1.3.2

package/lib/certification/artifact-gates.mjs

@@ -53,11 +53,16 @@ export function validateAllGoldenArtifactGates({ rootDir } = {}) {
   return { pass: errors.length === 0, results, errors, matrix: artifactGateMatrix({ rootDir: root }) };
 }
 
+// The committed gate matrix is a deterministic projection of the rootDir; no
+// wall-clock field, so regenerating it (the artifact-gates test writes it on every
+// run) yields a byte-identical file instead of a timestamp-only diff on a tracked
+// artifact. The matrix content is the signal; when it changes, the diff is real.
+
 export function writeArtifactGateMatrixDoc({ rootDir } = {}) {
   const root = findConstructRoot(rootDir);
   const out = path.join(root, 'tests', 'certification', 'artifacts', 'gate-matrix.json');
   fs.mkdirSync(path.dirname(out), { recursive: true });
-  const payload = { generatedAt: new Date().toISOString(), matrix: artifactGateMatrix({ rootDir: root }) };
+  const payload = { matrix: artifactGateMatrix({ rootDir: root }) };
   fs.writeFileSync(out, `${JSON.stringify(payload, null, 2)}\n`);
   return out;
 }

package/lib/doctor/cli.mjs

@@ -101,16 +101,26 @@ export async function runCli(args) {
   }
 
   if (sub === 'consistency') {
+    const strict = args.some((a) => a === '--strict' || a === '--all' || a === '--debug');
     const { runAllChecks } = await import('./watchers/consistency.mjs');
     const result = await runAllChecks();
     const blocking = result.findings.filter((f) => f.severity === 'blocking');
     const warnings = result.findings.filter((f) => f.severity === 'warning');
 
+    // Default output carries only user-actionable signal; package/maintainer drift
+    // (tier 'internal') is gated behind --strict so a clean install reads clean.
+
+    const visibleWarnings = strict ? warnings : warnings.filter((f) => f.tier !== 'internal');
+    const internalWarnings = warnings.filter((f) => f.tier === 'internal');
+
     for (const p of result.passed) console.log(`  ✓  ${p.category.padEnd(18)} ${p.summary}`);
-    for (const w of warnings) console.log(`  ⚠  ${w.category.padEnd(18)} ${w.summary}`);
+    for (const w of visibleWarnings) console.log(`  ⚠  ${w.category.padEnd(18)} ${w.summary}`);
     for (const b of blocking) console.log(`  ✗  ${b.category.padEnd(18)} ${b.summary}`);
 
-    console.log(`\n${result.passed.length} category(s) clean, ${warnings.length} warning(s), ${blocking.length} blocking finding(s)`);
+    console.log(`\n${result.passed.length} category(s) clean, ${visibleWarnings.length} warning(s), ${blocking.length} blocking finding(s)`);
+    if (!strict && internalWarnings.length > 0) {
+      console.log(`  (+${internalWarnings.length} package-internal diagnostic(s) — run \`construct doctor consistency --strict\` to view)`);
+    }
     return blocking.length > 0 ? 1 : 0;
   }
 

package/lib/doctor/watchers/consistency.mjs

@@ -19,7 +19,7 @@
  * directory listings, no network.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { loadRegistry } from '../../registry/loader.mjs';
 import { join, dirname, resolve } from 'node:path';
 import os from 'node:os';
@@ -97,15 +97,32 @@ export async function runAllChecks({ repoRoot = REPO_ROOT } = {}) {
   return { findings, passed };
 }
 
+// Drift categories split into two operator tiers. `actionable` findings are
+// project state a user can fix and surface by default. `internal` findings are
+// package/maintainer diagnostics about Construct's own registry and MCP wiring —
+// never user-actionable in a consumer project (this watcher resolves REPO_ROOT to
+// the installed package), so they stay behind `doctor consistency --strict`.
+
+const CATEGORY_TIERS = {
+  'mcp-drift': 'internal',
+  'roles-drift': 'internal',
+};
+
+function tierFor(category) {
+  return CATEGORY_TIERS[category] || 'actionable';
+}
+
 function collect(result, findings, passed, defaultCategory) {
   if (result.violations.length === 0) {
-    passed.push({ category: defaultCategory, summary: result.summary });
+    passed.push({ category: defaultCategory, summary: result.summary, tier: tierFor(defaultCategory) });
     return;
   }
   for (const v of result.violations) {
+    const category = v.category || defaultCategory;
     findings.push({
-      category: v.category || defaultCategory,
+      category,
       severity: v.severity || 'warning',
+      tier: v.tier || tierFor(category),
       summary: v.summary,
       target: v.target || null,
       details: v.details || null,
@@ -184,38 +201,51 @@ function checkMcpDrift({ repoRoot }) {
   }
 
   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]));
+  // Candidate tool handlers are exactly the identifiers server.mjs imports from
+  // ./tools/*.mjs. Tool modules also export private helpers (exec, readJson) that
+  // are never MCP tools; scanning every `export function` swept those into the
+  // signal. Scoping to the server's own imports is the real contract surface.
+
+  const importedHandlers = new Set();
+  for (const m of serverSource.matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]\.\/tools\/[^'"]+['"]/g)) {
+    for (const ident of m[1].split(',')) {
+      const local = ident.trim().split(/\s+as\s+/).pop().trim();
+      if (local) importedHandlers.add(local);
     }
   }
 
-  for (const tool of exportedTools) {
-    if (KNOWN_NON_DISPATCH_TOOLS.has(tool)) continue;
-    if (!dispatchedTools.has(tool)) {
+  // A handler is wired when the dispatcher invokes it, regardless of the
+  // registered tool name. Handlers follow xxxTool→'xxx' and construct_xxx naming
+  // conventions, so matching exported names against `name === '<tool>'` strings is
+  // unreliable; matching the invoked identifier is convention-agnostic.
+
+  const invoked = new Set();
+  for (const m of serverSource.matchAll(/\b([A-Za-z_$][\w$]*)\s*\(/g)) {
+    invoked.add(m[1]);
+  }
+
+  for (const handler of importedHandlers) {
+    const snake = camelToSnake(handler);
+    if (KNOWN_NON_DISPATCH_TOOLS.has(handler) || KNOWN_NON_DISPATCH_TOOLS.has(snake)) continue;
+    if (!invoked.has(handler)) {
       violations.push({
         category: 'mcp-drift',
         severity: 'warning',
-        target: tool,
-        summary: `MCP tool exported but not dispatched: ${tool}`,
+        tier: 'internal',
+        target: snake,
+        summary: `MCP tool handler imported but never dispatched: ${handler}`,
       });
     }
   }
 
-  return { summary: `mcp: ${dispatchedTools.size} dispatched, ${exportedTools.size} exported, ${violations.length} drift`, violations };
+  return { summary: `mcp: ${importedHandlers.size} handlers, ${violations.length} drift`, violations };
 }
 
+// Handlers the server may import for re-export or test surface but intentionally
+// never dispatches. Matched by camelCase identifier or snake_case form.
+
 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',
 ]);
@@ -263,21 +293,28 @@ function personaOwnersFromRegistry(registry) {
     owners.get(personaId).add(owner);
   }
 
+  // One registry entity owns a persona once. A specialist's id and its own name
+  // normalize to the same persona by design (cx-architect / architect), so they
+  // must share a single owner token keyed on the entity — otherwise every
+  // specialist self-collides and reports a spurious "ambiguous" drift. Genuine
+  // ambiguity (two distinct specialists, or a specialist and the orchestrator,
+  // normalizing to the same persona) still yields owners.size > 1.
+
   for (const [specId, spec] of Object.entries(registry?.specialists || {})) {
     addOwner(specId, `specialist:${specId}`);
-    addOwner(spec?.name, `specialist:${specId}:name`);
+    addOwner(spec?.name, `specialist:${specId}`);
   }
 
   if (Array.isArray(registry?.specialists)) {
     for (const spec of registry.specialists) {
       const owner = `specialist:${spec?.id || spec?.name || 'unknown'}`;
       addOwner(spec?.id, owner);
-      addOwner(spec?.name, `${owner}:name`);
+      addOwner(spec?.name, owner);
     }
   }
 
-  addOwner(registry?.orchestrator?.id, 'orchestrator:id');
-  addOwner(registry?.orchestrator?.name, 'orchestrator:name');
+  addOwner(registry?.orchestrator?.id, 'orchestrator');
+  addOwner(registry?.orchestrator?.name, 'orchestrator');
   return owners;
 }
 

package/lib/mcp/server.mjs

@@ -38,7 +38,7 @@ import {
 } from './tools/storage.mjs';
 import {
   listSkills, getSkill, searchSkills, getTemplate, listTemplates,
-  agentContract, brokerCheck, orchestrationPolicy, workerRun, listTeams, getTeam, suggestSkillsTool,
+  agentContract, brokerCheck, orchestrationPolicy, workerRun, listTeams, suggestSkillsTool,
 } from './tools/skills.mjs';
 import {
   workflowInit, workflowAddTask, workflowUpdateTask,

package/lib/mcp-manager.mjs

@@ -339,35 +339,33 @@ export async function cmdMcpAdd(id) {
     }
   }
 
-  // GitHub: source token from gh CLI, env, or prompt (--token flag)
-  if (id === 'github') {
+  // GitHub's hosted remote server uses one-click OAuth by default: the host runs
+  // the browser flow and stores the token in its own secure store, so we wire the
+  // URL only and keep no credential. `--token`/`--pat` opts into the PAT fallback
+  // (headless/CI), sourced from gh CLI or env and emitted as an env reference.
+  let authMode = id === 'github' ? 'oauth' : 'pat';
+  if (id === 'github' && (flags.token || flags.pat)) {
+    authMode = 'pat';
     const envToken = process.env.GITHUB_TOKEN || process.env.GITHUB_PERSONAL_ACCESS_TOKEN;
-    const forceToken = flags.token;
-
     let ghCliToken = '';
     try {
       execSync('gh auth status -h github.com', { stdio: 'ignore' });
       ghCliToken = execSync('gh auth token -h github.com 2>/dev/null', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
     } catch { /* gh not installed or not authed */ }
 
-    if (forceToken) {
+    const best = envToken || ghCliToken;
+    if (process.stdin.isTTY && typeof flags.token !== 'string') {
       const rl = createInterface({ input: process.stdin, output: process.stdout });
-      const best = envToken || ghCliToken;
       const hint = best ? ' [press Enter to use detected token]' : '';
       const value = await prompt(rl, `\n   > GITHUB_TOKEN${hint}: `);
       rl.close();
       envValues.GITHUB_TOKEN = value.trim() || best || '';
-    } else if (ghCliToken) {
-      console.log('\n   ✓ GitHub token sourced from gh CLI (gh auth login).');
-      envValues.GITHUB_TOKEN = ghCliToken;
-    } else if (envToken) {
-      console.log('\n   ✓ GitHub token detected in environment.');
-      envValues.GITHUB_TOKEN = envToken;
     } else {
-      console.log('\n   ✗ No GitHub token found.');
-      console.log('   Run: gh auth login -h github.com    (opens browser, stores token automatically)');
-      console.log('   Then re-run: construct mcp add github');
-      console.log('   Or provide a PAT: construct mcp add github --token');
+      envValues.GITHUB_TOKEN = (typeof flags.token === 'string' ? flags.token : '') || best || '';
+    }
+    if (!envValues.GITHUB_TOKEN) {
+      console.log('\n   ✗ --token requested but no PAT found (gh CLI / env / prompt).');
+      console.log('   Run `gh auth login -h github.com`, or omit --token to use OAuth.');
       process.exit(1);
     }
   }
@@ -418,7 +416,7 @@ export async function cmdMcpAdd(id) {
   const settings = loadSettings();
   if (!settings.mcpServers) settings.mcpServers = {};
   if (isManagedOnHost(mcp, 'claude')) {
-    settings.mcpServers[id] = buildClaudeMcpEntry(id, mcp, resolvedValues);
+    settings.mcpServers[id] = buildClaudeMcpEntry(id, mcp, resolvedValues, { auth: authMode });
   } else {
     delete settings.mcpServers[id];
   }
@@ -431,7 +429,7 @@ export async function cmdMcpAdd(id) {
   delete oc.mcp[id];
   if (id === 'memory') delete oc.mcp.cass;
   if (isManagedOnHost(mcp, 'opencode')) {
-    oc.mcp[openCodeId] = buildOpenCodeMcpEntry(id, mcp, resolvedValues).entry;
+    oc.mcp[openCodeId] = buildOpenCodeMcpEntry(id, mcp, resolvedValues, { auth: authMode }).entry;
   } else {
     delete oc.mcp[openCodeId];
   }
@@ -451,8 +449,15 @@ export async function cmdMcpAdd(id) {
 
   console.log(`\n✓ ${mcp.name} successfully wired into Claude Code, OpenCode, and Codex.`);
   console.log(`✓ Setup mode: ${setupMode}`);
+  console.log(`✓ Auth: ${id === 'github' ? authMode : 'managed'}`);
   console.log(`✓ Services synchronized.`);
   console.log(`\nNext: Restart OpenCode, Claude Code, or Codex to activate the new tools.`);
+  if (id === 'github' && authMode === 'oauth') {
+    console.log(`\nAuthenticate (one-click OAuth, no token stored on disk):`);
+    console.log(`   Claude Code: \`claude mcp login github\`   ·   OpenCode: \`opencode mcp auth github\``);
+    console.log(`   VS Code / Cursor: approve the sign-in prompt on first use.`);
+    console.log(`   PAT fallback (headless/CI): \`construct mcp add github --token\``);
+  }
   for (const host of ['claude', 'opencode', 'codex']) {
     const support = getHostSupport(mcp, host);
     const hostLabel = host === 'claude' ? 'Claude Code' : host === 'opencode' ? 'OpenCode' : 'Codex';

package/lib/mcp-platform-config.mjs

@@ -40,14 +40,24 @@ function resolveArgs(args, resolvedValues) {
   );
 }
 
+// Remote MCP header values carry secrets (e.g. `Authorization: Bearer __GITHUB_TOKEN__`).
+// Emit a host-resolved env reference rather than the literal token value, so a live
+// credential never lands in a config file on disk. Each host expands a different
+// reference syntax; the secret stays in one place (config.env / the shell env) and the
+// host resolves it at launch.
+
+const SECRET_REF = {
+  claude: (name) => `\${${name}}`,
+  vscode: (name) => `\${env:${name}}`,
+  opencode: (name) => `{env:${name}}`,
+};
+
 function buildLocalEnvironment(mcpDef, resolvedValues) {
   return stripUnresolvedValues(resolveTemplateObject(mcpDef.env ?? {}, resolvedValues));
 }
 
-function buildRemoteHeaders(mcpDef, resolvedValues) {
-  return stripUnresolvedValues(
-    resolveTemplateObject(mcpDef.headers ?? {}, resolvedValues, (name) => `{env:${name}}`),
-  );
+function buildRemoteHeaders(mcpDef, secretRef) {
+  return resolveTemplateObject(mcpDef.headers ?? {}, {}, secretRef);
 }
 
 function withMemoryDefaults(id, values) {
@@ -56,11 +66,18 @@ function withMemoryDefaults(id, values) {
   return { ...values, MEMORY_PORT: "8765" };
 }
 
-export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}) {
+// auth defaults to "oauth": remote MCP servers (e.g. GitHub's hosted server) are
+// configured by URL only, and the host runs the browser OAuth flow and stores the
+// token in its own secure store — nothing secret touches the config file. "pat"
+// is the opt-in fallback for non-OAuth contexts (headless/CI), emitting an env
+// reference for the credential, never the literal value.
+
+export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}, { host = "claude", auth = "oauth" } = {}) {
   const values = withMemoryDefaults(id, { CX_TOOLKIT_DIR: ROOT_DIR, ...resolvedValues });
+  const secretRef = SECRET_REF[host] ?? SECRET_REF.claude;
 
   if (mcpDef.type === "url") {
-    const headers = buildRemoteHeaders(mcpDef, values);
+    const headers = auth === "pat" ? buildRemoteHeaders(mcpDef, secretRef) : {};
     const url =
       id === "memory" && values.MEMORY_PORT
         ? `http://127.0.0.1:${values.MEMORY_PORT}/`
@@ -80,7 +97,7 @@ export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}) {
   };
 }
 
-export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}) {
+export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}, { auth = "oauth" } = {}) {
   const runtimeValues = withMemoryDefaults(id, {
     CX_TOOLKIT_DIR: ROOT_DIR,
     ...resolvedValues,
@@ -92,12 +109,13 @@ export function buildOpenCodeMcpEntry(id, mcpDef, resolvedValues = {}) {
       id === "memory" && runtimeValues.MEMORY_PORT
         ? `http://127.0.0.1:${runtimeValues.MEMORY_PORT}/`
         : resolveTemplateString(mcpDef.url, runtimeValues);
+    const headers = auth === "pat" ? buildRemoteHeaders(mcpDef, SECRET_REF.opencode) : {};
     return {
       id: openCodeId,
       entry: {
         type: "remote",
         url,
-        ...(Object.keys(buildRemoteHeaders(mcpDef, runtimeValues)).length > 0 ? { headers: buildRemoteHeaders(mcpDef, runtimeValues) } : {}),
+        ...(Object.keys(headers).length > 0 ? { headers } : {}),
       },
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",

package/scripts/sync-specialists.mjs

@@ -1002,13 +1002,20 @@ ${buildPrompt(entry, allEntries, "claude")}
  * Rewrite the home-mode hook command pattern
  *   node "$HOME/.config/construct/lib/hooks/<name>.mjs"
  * into the project-portable form
- *   node .construct/run.mjs hook <name>
+ *   node "${CLAUDE_PROJECT_DIR:-.}/.construct/run.mjs" hook <name>
  * so the resulting settings.json works on any clone where the project ships
  * the .construct/ launcher (committed by `npm install`'s postinstall or by
  * `construct init`). The launcher resolves Construct via node_modules → npx
  * → globally-installed CLI → cached binary → docker, in that order, so it
  * works for non-Node ecosystems too. Other commands (inline node -e
  * snippets, npx block-no-verify@…) are left untouched.
+ *
+ * The `${CLAUDE_PROJECT_DIR:-.}` anchor matters: Claude Code invokes hooks with
+ * a working directory that is not guaranteed to be the project root (observed:
+ * $HOME), and a bare relative `.construct/run.mjs` then fails with MODULE_NOT_FOUND
+ * at node:internal/modules/cjs/loader. CLAUDE_PROJECT_DIR is the project root Claude
+ * Code exports to every hook (same var lib/hooks/*.mjs already read); the `:-.`
+ * fallback preserves the prior relative behavior wherever the var is unset.
  */
 function makeHooksPortable(hooksJson) {
   // Operate on the in-memory object so we don't fight JSON string escaping.
@@ -1017,7 +1024,7 @@ function makeHooksPortable(hooksJson) {
     const m = cmd.match(/^node\s+"?\$HOME\/\.config\/construct\/lib\/hooks\/([a-z0-9-]+)\.mjs"?\s*(.*)$/);
     if (!m) return cmd;
     const [, name, rest] = m;
-    return `node .construct/run.mjs hook ${name}${rest ? ' ' + rest.trim() : ''}`;
+    return `node "\${CLAUDE_PROJECT_DIR:-.}/.construct/run.mjs" hook ${name}${rest ? ' ' + rest.trim() : ''}`;
   };
 
   const walk = (node) => {
@@ -1474,7 +1481,7 @@ function syncVSCode(targetDir = null, wants = true) {
       const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
       const transportMismatch = registryWantsCommand && existingIsRemote;
       if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
-      config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+      config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
     }
     if (!DRY_RUN) {
       mkdirp(path.dirname(mcpPath));
@@ -1498,7 +1505,7 @@ function syncVSCode(targetDir = null, wants = true) {
         const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
         const transportMismatch = registryWantsCommand && existingIsRemote;
         if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
-        config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+        config.servers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
       }
       if (!DRY_RUN) fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
       synced = true;
@@ -1568,7 +1575,7 @@ function syncCursor(targetDir = null, wants = true) {
     const existingIsRemote = existingEntry && (existingEntry.type === 'http' || existingEntry.type === 'remote');
     const transportMismatch = registryWantsCommand && existingIsRemote;
     if (existingEntry && !hasPlaceholder && !transportMismatch) continue;
-    config.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env);
+    config.mcpServers[id] = buildClaudeMcpEntry(id, mcpDef, process.env, { host: "vscode" });
   }
   if (!DRY_RUN) {
     mkdirp(path.dirname(cursorMcpPath));