arkgate 2.12.0 → 2.13.0

package/bin/lib/install-migrate.mjs

@@ -14,6 +14,7 @@ import {
   codexPromptsDir,
   codexConfigPath,
   isTempOrUpgradeRoot,
+  usesDefaultCodexHome,
   wireCodexMcp,
 } from './codex-home.mjs';
 import {
@@ -40,9 +41,7 @@ import {
   checkArchitectureScriptSnippet,
 } from './ci-and-commands.mjs';
 import {
-  normalizeToolsList,
   resolveTools,
-  KNOWN_TOOLS,
   SKILL_TOOL_TARGETS,
   skillTemplates,
   stampSkill,
@@ -59,6 +58,11 @@ import {
   PREFERRED_CHECK_BIN,
   RUNNER_BEFORE_ARK,
 } from './mcp-adoption.mjs';
+import {
+  hasHardWriteHook,
+  validateHardWriteRequest,
+  validateSelectedTools,
+} from './enforcement-profiles.mjs';
 
 export function staleRunnerGateFiles(root) {
   const want = execRunner(root);
@@ -179,17 +183,35 @@ export function runInstallAgentGates(args) {
     return;
   }
   if (args.tools != null) {
-    const list = normalizeToolsList(args.tools);
-    args.tools = list;
-    const unknown = list.filter((tool) => !KNOWN_TOOLS.includes(tool));
-    if (list.length === 0 || unknown.length > 0) {
-      console.error(
-        `--tools expects a comma-separated subset of: ${KNOWN_TOOLS.join(', ')}` +
-          (unknown.length > 0 ? ` (unknown: ${unknown.join(', ')})` : '')
-      );
+    const selection = validateSelectedTools(args.tools);
+    if (!selection.ok) {
+      console.error(selection.error);
       process.exitCode = 2;
       return;
     }
+    args.tools = selection.tools;
+  }
+  const writeRequest = validateHardWriteRequest({
+    root,
+    host: args.requireWriteHook,
+    tools: args.tools,
+    force: args.force,
+  });
+  if (!writeRequest.ok) {
+    console.error(writeRequest.error);
+    process.exitCode = 2;
+    return;
+  }
+  if (writeRequest.host && args.tools == null) {
+    args.tools = writeRequest.tools;
+  }
+  if (writeRequest.host && args.skillsOnly && !hasHardWriteHook(root, writeRequest.host)) {
+    console.error(
+      `--skills-only cannot install the requested ${writeRequest.host} hard-write hook. ` +
+      'Remove --skills-only or omit --require-write-hook.'
+    );
+    process.exitCode = 2;
+    return;
   }
   const pm = packageManager(root);
   const hasCheckScript = hasCheckArchitectureScript(root);
@@ -370,16 +392,17 @@ export function runInstallAgentGates(args) {
   // without a manual copy step.
   //
   // Skip home-dir mutation when the project root is a temp/upgrade scratch *and*
-  // CODEX_HOME is the default (~/.codex). Fixtures must not rewrite the developer's
-  // real Codex config. When CODEX_HOME is redirected (unit tests set a temp home) or
-  // --codex-home is explicit, wire as usual.
+  // CODEX_HOME resolves to the default (~/.codex). Codex itself may export that exact
+  // path, so presence alone does not prove isolation. Fixtures must not rewrite the
+  // developer's real config. A genuinely redirected CODEX_HOME or explicit
+  // --codex-home still wires as requested.
   let codexMcp = null;
   const wantCodexWire = tools.has('codex') || args.codexHome;
   const skipHomeWire =
     wantCodexWire &&
     isTempOrUpgradeRoot(root) &&
     !args.codexHome &&
-    !process.env.CODEX_HOME;
+    usesDefaultCodexHome();
   if (wantCodexWire && !skipHomeWire) {
     codexMcp = wireCodexMcp(root, args.force);
     console.log('');
@@ -416,6 +439,14 @@ export function runInstallAgentGates(args) {
       `\nWarning: Codex home MCP registration failed (${codexMcp.message}). Repo gates were written; fix ~/.codex access or re-run with --tools codex --force.`
     );
   }
+  if (writeRequest.host) {
+    if (!hasHardWriteHook(root, writeRequest.host)) {
+      console.error(`\nFailed to verify the ${writeRequest.host} hard-write hook after install.`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`\nHard-write hook verified for ${writeRequest.host}.`);
+  }
   console.log('');
   console.log('Next steps:');
   console.log('  1. Review the generated files and commit the ones that match your tools.');

package/bin/lib/mcp-adoption.mjs

@@ -9,8 +9,9 @@ import { CORE_LAYER_NAMES } from './core-layers.mjs';
 import { falseGreenAdoptionGap } from './field-install.mjs';
 import { assessCodexHomeMcp, codexConfigPath } from './codex-home.mjs';
 import { detectWritePathCapabilities } from './write-path-detect.mjs';
-import { skillTemplateNames } from './skill-install.mjs';
+import { detectActiveAgentHost, skillTemplateNames } from './skill-install.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
+import { collectWeakestLinkGaps } from './weakest-link.mjs';
 
 export { detectDeployPathQuality };
 
@@ -195,10 +196,22 @@ export function collectAdoptionGaps(root, config, coverage) {
         scopedTable: assessed.scopedTable,
       };
       if (assessed.gap) {
+        // Temp/upgrade MCP roots stay urgent (fail-closed). Non-temp Codex-home debt
+        // is deferred only when the session host is known and is not Codex
+        // (Grok/Claude/Cursor…). Unknown host (CI/plain shell) keeps original severity.
+        const tempUrgent = Boolean(assessed.tempPath);
+        const activeHost = detectActiveAgentHost();
+        const deferred =
+          !tempUrgent && activeHost != null && activeHost !== 'codex';
+        const severity = deferred ? 'info' : assessed.gap.severity;
+        const message = deferred
+          ? `Deferred (fix when using Codex): ${assessed.gap.message}`
+          : assessed.gap.message;
         gaps.push({
           id: assessed.gap.id,
-          severity: assessed.gap.severity,
-          message: assessed.gap.message,
+          severity,
+          deferred,
+          message,
           fix: arkCommand(root, 'ark-check', assessed.gap.fixArgs),
         });
       }
@@ -403,6 +416,19 @@ export function collectAdoptionGaps(root, config, coverage) {
     }
   }
 
+  // --- Q3 weakest-link: CI / pre-commit / config drift (local FS; optional GH via ARK_DOCTOR_GITHUB=1) ---
+  const includeGithub =
+    process.env.ARK_DOCTOR_GITHUB === '1' ||
+    process.env.ARK_DOCTOR_GITHUB === 'true';
+  const weakest = collectWeakestLinkGaps(root, {
+    adopted,
+    isProducer,
+    includeGithub,
+  });
+  for (const g of weakest.gaps) {
+    gaps.push(g);
+  }
+
   return {
     gaps,
     hosts,
@@ -415,6 +441,12 @@ export function collectAdoptionGaps(root, config, coverage) {
     deployPath,
     contractFalseGreen,
     writePath,
+    enforcement: {
+      ci: weakest.ci,
+      preCommit: weakest.preCommit,
+      drift: weakest.drift,
+      github: weakest.github,
+    },
   };
 }
 

package/bin/lib/open-html.mjs

@@ -0,0 +1,75 @@
+/**
+ * Open a local HTML file in the default browser (macOS / Windows / Linux).
+ * Used after ark-check --report writes a showcase/beginner report.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Whether report generation should open the browser.
+ * Default: yes for interactive local TTY; never in CI/Vitest unless forced.
+ *
+ * @param {{ force?: boolean, noOpen?: boolean, env?: NodeJS.ProcessEnv, isTty?: boolean }} [opts]
+ */
+export function shouldOpenHtmlReport(opts = {}) {
+  const env = opts.env ?? process.env;
+  if (opts.noOpen) return false;
+  if (opts.force) return true;
+  const off = env.ARK_NO_OPEN_REPORT;
+  if (off === '1' || off === 'true' || off === 'yes') return false;
+  if (env.CI === 'true' || env.CI === '1') return false;
+  if (env.GITHUB_ACTIONS === 'true') return false;
+  if (env.VITEST) return false;
+  const tty = opts.isTty ?? Boolean(process.stdout.isTTY);
+  return tty;
+}
+
+/**
+ * Launch the OS default browser for a local file path (non-blocking).
+ * Errors are swallowed — report generation must not fail if the browser cannot open.
+ *
+ * @param {string} filePath
+ * @param {{ platform?: NodeJS.Platform, spawn?: typeof spawn }} [opts]
+ * @returns {{ ok: boolean, command?: string, reason?: string }}
+ */
+export function openHtmlInBrowser(filePath, opts = {}) {
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) {
+    return { ok: false, reason: 'missing-file' };
+  }
+  const platform = opts.platform ?? process.platform;
+  const spawnFn = opts.spawn ?? spawn;
+
+  /** @type {string} */
+  let command;
+  /** @type {string[]} */
+  let args;
+  if (platform === 'darwin') {
+    command = 'open';
+    args = [abs];
+  } else if (platform === 'win32') {
+    command = 'rundll32.exe';
+    args = ['url.dll,FileProtocolHandler', pathToFileURL(abs).href];
+  } else {
+    command = 'xdg-open';
+    args = [abs];
+  }
+
+  try {
+    const child = spawnFn(command, args, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      shell: false,
+    });
+    child.on('error', () => {
+      /* browser missing (e.g. headless Linux) — ignore */
+    });
+    child.unref();
+    return { ok: true, command };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+}

package/bin/lib/presets.mjs

@@ -8,6 +8,7 @@ import {
   DEFAULT_INTENT_PREFIXES,
   resolveIncludeRoots,
 } from '../ark-shared.mjs';
+import { withArkConfigMetadata } from './config-contract.mjs';
 
 export function denyUpward(names) {
   const rules = [];
@@ -49,8 +50,8 @@ export function peerIsolationEdges(layerNames, sliceFolders, message) {
 // (that carves out legitimate `src/shared/kernel/**` SharedKernel paths).
 export const FRAMEWORK_INTERNAL_EXCLUDE = ['src/kernel/**', '**/src/kernel/**'];
 export function presetWithOverlays(baseConfig, root) {
-  if (!root) return baseConfig;
-  return applyFrameworkLayoutOverlays(baseConfig, root);
+  const config = root ? applyFrameworkLayoutOverlays(baseConfig, root) : baseConfig;
+  return withArkConfigMetadata(config);
 }
 
 export const ARCHITECTURE_PRESETS = {

package/bin/lib/safety-diagnostics.mjs

@@ -146,15 +146,20 @@ export function collectSafetyDiagnostics(ts, root, config, files) {
         });
       }
 
-      if (ts.isCallExpression(node) && node.expression?.kind === ts.SyntaxKind.ImportKeyword) {
+      if (ts.isCallExpression(node)) {
+        const dynamicImport = node.expression?.kind === ts.SyntaxKind.ImportKeyword;
+        const directRequire =
+          ts.isIdentifier(node.expression) && node.expression.text === 'require';
         const argument = node.arguments[0];
-        if (!argument || !ts.isStringLiteralLike(argument)) {
-          if (!matchesAny(relFile, dynamicAllowlist)) {
-            report.nonLiteralDynamicImports.push({
-              file: relFile,
-              line: lineOf(sourceFile, node.getStart(sourceFile)),
-            });
-          }
+        const unresolved =
+          (dynamicImport || directRequire) &&
+          (!argument || !ts.isStringLiteralLike(argument));
+        if (unresolved && !matchesAny(relFile, dynamicAllowlist)) {
+          report.nonLiteralDynamicImports.push({
+            file: relFile,
+            line: lineOf(sourceFile, node.getStart(sourceFile)),
+            kind: directRequire ? 'require' : 'import',
+          });
         }
       }
 
@@ -216,13 +221,28 @@ export function collectSafetyDiagnostics(ts, root, config, files) {
   }
 
   const warnings = [];
-  if (report.nonLiteralDynamicImports.length > 0) {
-    const first = report.nonLiteralDynamicImports[0];
+  const nonLiteralImports = report.nonLiteralDynamicImports.filter(
+    (entry) => entry.kind !== 'require'
+  );
+  if (nonLiteralImports.length > 0) {
+    const first = nonLiteralImports[0];
     warnings.push({
       ruleId: 'DYNAMIC_IMPORT_NOT_ALLOWLISTED',
       file: first.file,
       line: first.line,
-      message: `${report.nonLiteralDynamicImports.length} non-literal dynamic import(s) cannot be resolved statically. Add only reviewed files to dynamicImportAllowlist.`,
+      message: `${nonLiteralImports.length} non-literal dynamic import(s) cannot be resolved statically. Add only reviewed files to dynamicImportAllowlist.`,
+    });
+  }
+  const nonLiteralRequires = report.nonLiteralDynamicImports.filter(
+    (entry) => entry.kind === 'require'
+  );
+  if (nonLiteralRequires.length > 0) {
+    const first = nonLiteralRequires[0];
+    warnings.push({
+      ruleId: 'DYNAMIC_REQUIRE_NOT_ALLOWLISTED',
+      file: first.file,
+      line: first.line,
+      message: `${nonLiteralRequires.length} non-literal require call(s) cannot be resolved statically. Add only reviewed files to dynamicImportAllowlist.`,
     });
   }
   if (report.tsSuppressions.length > maxTsSuppressions) {

package/bin/lib/skill-install.mjs

@@ -23,6 +23,70 @@ export function normalizeToolsList(tools) {
   return [];
 }
 
+function envTruthy(v) {
+  if (v == null || v === '') return false;
+  const s = String(v).trim().toLowerCase();
+  return s !== '0' && s !== 'false' && s !== 'no' && s !== 'off';
+}
+
+/**
+ * Best-effort active agent host for this process (session host).
+ * Prefer ARK_ACTIVE_HOST when set. Do NOT treat CODEX_HOME alone as Codex —
+ * that dir exists for anyone who installed Codex, even when running Grok/Claude.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null} tool id (claude|cursor|codex|grok|…) or null if unknown
+ */
+export function detectActiveAgentHost(env = process.env) {
+  const explicit = String(env.ARK_ACTIVE_HOST || '')
+    .trim()
+    .toLowerCase();
+  if (explicit) return explicit;
+
+  // Grok / xAI Build
+  if (
+    envTruthy(env.GROK_BUILD) ||
+    envTruthy(env.XAI_GROK) ||
+    env.GROK_WORKSPACE_ROOT ||
+    env.GROK_SESSION_ID
+  ) {
+    return 'grok';
+  }
+  // Claude Code
+  if (
+    env.CLAUDE_PROJECT_DIR ||
+    envTruthy(env.CLAUDE_CODE) ||
+    envTruthy(env.CLAUDECODE) ||
+    env.CLAUDE_CODE_ENTRYPOINT
+  ) {
+    return 'claude';
+  }
+  // Cursor agent
+  if (env.CURSOR_TRACE_ID || env.CURSOR_AGENT || envTruthy(env.CURSOR_AGENT_CLI)) {
+    return 'cursor';
+  }
+  // Codex session — never CODEX_HOME alone (see above)
+  if (
+    envTruthy(env.CODEX_SANDBOX) ||
+    env.CODEX_THREAD_ID ||
+    envTruthy(env.CODEX_CI) ||
+    env.CODEX_SESSION_ID
+  ) {
+    return 'codex';
+  }
+  return null;
+}
+
+/**
+ * True when Codex home / MCP / prompts should be treated as an urgent concern
+ * for this process. Non-Codex hosts (Grok, Claude, Cursor, …) defer Codex debt.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function codexConcernIsActive(env = process.env) {
+  return detectActiveAgentHost(env) === 'codex';
+}
+
 export function resolveTools(args) {
   const explicit = normalizeToolsList(args.tools);
   if (explicit.length > 0) {

package/bin/lib/ts-resolve.mjs

@@ -128,9 +128,10 @@ export function scanCacheKey(root, args) {
   // warm cache from an older Ark can't feed stale entries to new logic. v2: typeOnly on edges.
   // v3: per-file exportsOnlyTypes. v4: typeOnlyExportNames + namedBindings.
   // v5: hasTopLevelSideEffects. v6: non-exported impure inits + non-export class statics.
+  // v7: scope-aware forbidden globals + import-equals dependency edges.
   return crypto
     .createHash('sha1')
-    .update(`ark-check-cache-v6\0${read(configPath)}\0${manifestPath ? read(manifestPath) : ''}`)
+    .update(`ark-check-cache-v7\0${read(configPath)}\0${manifestPath ? read(manifestPath) : ''}`)
     .digest('hex');
 }