@geraldmaron/construct 1.3.1 → 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/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.1",
+  "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

@@ -1481,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));
@@ -1505,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;
@@ -1575,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));