arkgate 2.6.1 → 2.8.0

package/bin/lib/codex-home.mjs

@@ -0,0 +1,320 @@
+/**
+ * Codex home config ($CODEX_HOME/config.toml) — paths, multi-project wire, adoption assess.
+ * Extracted from agent-gates so install/doctor stay orchestration-only (R7 review).
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execCommandParts } from '../ark-shared.mjs';
+
+export const PREFERRED_CODEX_MCP_BIN = 'arkgate-mcp';
+
+/** Where Codex loads slash-command prompts ($CODEX_HOME/prompts). */
+export function codexPromptsDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'prompts');
+}
+
+/** Where Codex loads MCP servers ($CODEX_HOME/config.toml) — global, not project-local. */
+export function codexConfigPath() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'config.toml');
+}
+
+/** Temp / upgrade sandbox roots must never remain as Codex MCP --root. */
+export function isTempOrUpgradeRoot(p) {
+  if (!p || typeof p !== 'string') return false;
+  const n = p.replace(/\\/g, '/');
+  return (
+    /\/var\/folders\//i.test(n) ||
+    /\/tmp\//i.test(n) ||
+    /\/Temp\//i.test(n) ||
+    /ark-upgrade/i.test(n) ||
+    /\/T\/(?:ark-|grok-)/i.test(n) ||
+    /[\\/]AppData[\\/]Local[\\/]Temp[\\/]/i.test(n)
+  );
+}
+
+/**
+ * Stable secondary table name: basename + short path hash so two projects named
+ * `app` do not collide on `mcp_servers.ark_app`.
+ */
+export function codexProjectSlug(absRoot) {
+  const abs = path.resolve(absRoot);
+  const base =
+    path
+      .basename(abs)
+      .replace(/[^a-zA-Z0-9_-]/g, '_')
+      .slice(0, 40) || 'project';
+  const hash = crypto.createHash('sha1').update(abs).digest('hex').slice(0, 8);
+  return `${base}_${hash}`;
+}
+
+/** Extract `--root` from one TOML mcp_servers table body. */
+export function extractCodexRootFromBlock(block) {
+  if (!block || typeof block !== 'string') return null;
+  const m = block.match(/"--root"\s*,\s*"([^"]+)"/);
+  return m ? m[1] : null;
+}
+
+/**
+ * All Ark MCP server tables in a Codex config.toml.
+ * @returns {Array<{ table: string, root: string|null, block: string, start: number, end: number }>}
+ */
+export function listCodexArkServerTables(tomlText) {
+  if (!tomlText || typeof tomlText !== 'string') return [];
+  const out = [];
+  const headerRe = /\[mcp_servers\.(ark(?:_[a-zA-Z0-9_-]*)?)\]/g;
+  const headers = [];
+  let hm;
+  while ((hm = headerRe.exec(tomlText)) !== null) {
+    headers.push({ table: hm[1], index: hm.index });
+  }
+  for (let i = 0; i < headers.length; i++) {
+    const start = headers[i].index;
+    let end = i + 1 < headers.length ? headers[i + 1].index : tomlText.length;
+    if (i + 1 >= headers.length) {
+      const rest = tomlText.slice(start + 1);
+      const other = rest.search(/\n\[/);
+      if (other >= 0) end = start + 1 + other;
+    }
+    const block = tomlText.slice(start, end).replace(/\s+$/, '\n');
+    out.push({
+      table: headers[i].table,
+      root: extractCodexRootFromBlock(block),
+      block,
+      start,
+      end,
+    });
+  }
+  return out;
+}
+
+/**
+ * Replace an existing `[mcp_servers.<table>]` block or append a new one.
+ * `block` should include the header line; trailing whitespace is normalized.
+ */
+export function upsertCodexMcpTable(tomlText, tableName, block) {
+  const existing = tomlText || '';
+  const normalized = `${String(block).replace(/\s+$/, '')}\n`;
+  const tables = listCodexArkServerTables(existing);
+  const hit = tables.find((t) => t.table === tableName);
+  if (hit) {
+    return `${existing.slice(0, hit.start)}${normalized}${existing.slice(hit.end).replace(/^\n+/, '\n')}`;
+  }
+  if (existing.length === 0) return normalized;
+  const sep = existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
+  return `${existing}${sep}${normalized}`;
+}
+
+/** Primary table entry or null. */
+export function codexPrimaryTable(tomlText) {
+  return listCodexArkServerTables(tomlText).find((t) => t.table === 'ark') ?? null;
+}
+
+/** Secondary (non-primary) table whose --root is this project, if any. */
+export function codexScopedTableForRoot(tomlText, absRoot) {
+  const abs = path.resolve(absRoot);
+  for (const entry of listCodexArkServerTables(tomlText)) {
+    if (entry.table === 'ark') continue;
+    if (!entry.root) continue;
+    try {
+      if (path.resolve(entry.root) === abs) return entry.table;
+    } catch {
+      /* ignore */
+    }
+  }
+  return null;
+}
+
+/** Extract --root from primary [mcp_servers.ark]. */
+export function extractCodexArkRootFromToml(tomlText) {
+  return codexPrimaryTable(tomlText)?.root ?? null;
+}
+
+export function codexArkBlockHasPreferredBin(tomlText) {
+  const primary = codexPrimaryTable(tomlText);
+  if (!primary) return false;
+  const bins = [...primary.block.matchAll(/"(arkgate-mcp|ark-mcp)"/g)].map((m) => m[1]);
+  if (bins.length > 1) return false;
+  return bins.length === 1 && bins[0] === PREFERRED_CODEX_MCP_BIN;
+}
+
+/**
+ * True when primary is broken (temp root / dual bin) and should rewrite fail-closed.
+ * Permanent different project roots are NOT broken — multi-project uses a secondary table.
+ */
+export function codexArkBlockNeedsRewrite(tomlText, absRoot) {
+  if (!tomlText || !tomlText.includes('[mcp_servers.ark]')) return true;
+  const rootArg = extractCodexArkRootFromToml(tomlText);
+  if (!rootArg || isTempOrUpgradeRoot(rootArg)) return true;
+  try {
+    if (path.resolve(rootArg) !== path.resolve(absRoot)) {
+      if (!isTempOrUpgradeRoot(rootArg)) return false;
+      return true;
+    }
+  } catch {
+    return true;
+  }
+  if (!codexArkBlockHasPreferredBin(tomlText)) return true;
+  return false;
+}
+
+/**
+ * Assess Codex home MCP vs this project. Pure (no I/O).
+ * @returns {{
+ *   root: string|null,
+ *   tempPath: boolean,
+ *   wrongRoot: boolean,
+ *   preferredBin: boolean,
+ *   needsRewrite: boolean,
+ *   multiProject: boolean,
+ *   scopedTable: string|null,
+ *   gap: null | { id: string, severity: string, message: string, fixArgs: string }
+ * }}
+ */
+export function assessCodexHomeMcp(tomlText, absRoot) {
+  const resolvedRoot = path.resolve(absRoot);
+  if (!tomlText || !tomlText.includes('[mcp_servers.ark]')) {
+    return {
+      root: null,
+      tempPath: false,
+      wrongRoot: false,
+      preferredBin: false,
+      needsRewrite: false,
+      multiProject: false,
+      scopedTable: null,
+      gap: null,
+    };
+  }
+  const rootArg = extractCodexArkRootFromToml(tomlText);
+  const temp = isTempOrUpgradeRoot(rootArg);
+  let wrongRoot = false;
+  try {
+    wrongRoot = rootArg ? path.resolve(rootArg) !== resolvedRoot : true;
+  } catch {
+    wrongRoot = true;
+  }
+  const preferredBin = codexArkBlockHasPreferredBin(tomlText);
+  const needsRewrite = codexArkBlockNeedsRewrite(tomlText, resolvedRoot);
+  const scopedTable = wrongRoot && !temp ? codexScopedTableForRoot(tomlText, resolvedRoot) : null;
+  const multiProject = Boolean(wrongRoot && !temp && !needsRewrite);
+
+  let gap = null;
+  if (needsRewrite) {
+    gap = {
+      id: 'codex-home-mcp',
+      severity: temp || wrongRoot ? 'warn' : 'info',
+      message: temp
+        ? `Codex home MCP --root points at a temp/upgrade path (${rootArg})`
+        : wrongRoot
+          ? `Codex home MCP --root is not this project (${rootArg || 'missing'} ≠ ${resolvedRoot})`
+          : `Codex home MCP should use a single ${PREFERRED_CODEX_MCP_BIN} bin with absolute project paths`,
+      fixArgs: '--install-agent-gates --codex-home --force',
+    };
+  } else if (multiProject) {
+    gap = {
+      id: 'codex-home-multi-project',
+      severity: scopedTable ? 'info' : 'warn',
+      message: scopedTable
+        ? `Codex primary [mcp_servers.ark] is bound to another project (${rootArg}); ` +
+          `this project is registered as [mcp_servers.${scopedTable}]. ` +
+          `Codex may still prefer the primary binding for ark://manifest — rebind if this repo should own it.`
+        : `Codex home primary MCP --root is another permanent project ` +
+          `(${rootArg || 'missing'} ≠ ${resolvedRoot}). ` +
+          `Install without --force adds a scoped [mcp_servers.ark_<slug>] table and leaves primary unchanged; ` +
+          `--force rebinds primary to this project.`,
+      fixArgs: scopedTable
+        ? '--install-agent-gates --tools codex --force'
+        : '--install-agent-gates --tools codex',
+    };
+  }
+
+  return {
+    root: rootArg,
+    tempPath: temp,
+    wrongRoot,
+    preferredBin,
+    needsRewrite,
+    multiProject,
+    scopedTable,
+    gap,
+  };
+}
+
+/**
+ * Merge [mcp_servers.ark] (or scoped secondary) into Codex home config.toml.
+ * Without --force, permanent other-project primary is left alone; this project gets
+ * [mcp_servers.ark_<slug>]. Temp/stale roots rewrite fail-closed.
+ *
+ * All mutations go through upsertCodexMcpTable (single table model).
+ */
+export function wireCodexMcp(root, force) {
+  const file = codexConfigPath();
+  const esc = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const absRoot = path.resolve(root);
+  const absConfig = path.join(absRoot, 'ark.config.json');
+  const { command, args } = execCommandParts(root, PREFERRED_CODEX_MCP_BIN, [
+    '--root',
+    esc(absRoot),
+    '--config',
+    esc(absConfig),
+  ]);
+  const argsToml = args.map((value) => `"${value}"`).join(', ');
+  const makeBlock = (table) =>
+    `[mcp_servers.${table}]
+command = "${command}"
+args = [${argsToml}]`;
+
+  let existing = '';
+  try {
+    if (fs.existsSync(file)) existing = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    return { status: 'failed', file, message: error.message };
+  }
+
+  const primary = codexPrimaryTable(existing);
+  const hasPrimary = Boolean(primary);
+  const existingRoot = primary?.root ?? null;
+  let differentProject = false;
+  try {
+    differentProject = Boolean(existingRoot && path.resolve(existingRoot) !== absRoot);
+  } catch {
+    differentProject = Boolean(existingRoot);
+  }
+  const mustRewrite = hasPrimary && codexArkBlockNeedsRewrite(existing, absRoot);
+
+  const writeToml = (next) => {
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, next);
+      return null;
+    } catch (error) {
+      return { status: 'failed', file, message: error.message };
+    }
+  };
+
+  // Multi-project: leave primary alone; upsert scoped secondary for this root.
+  if (hasPrimary && differentProject && !force && !mustRewrite) {
+    const existingScoped = codexScopedTableForRoot(existing, absRoot);
+    const table = existingScoped || `ark_${codexProjectSlug(absRoot)}`;
+    const next = upsertCodexMcpTable(existing, table, makeBlock(table));
+    const err = writeToml(next);
+    if (err) return err;
+    return { status: 'written-multi', file, table, primaryUnchanged: true };
+  }
+
+  if (hasPrimary && !force && !mustRewrite) {
+    return { status: 'skipped', file };
+  }
+
+  const next = upsertCodexMcpTable(existing, 'ark', makeBlock('ark'));
+  const err = writeToml(next);
+  if (err) return err;
+  return {
+    status: hasPrimary ? 'updated' : 'written',
+    file,
+    ...(mustRewrite && !force ? { reason: 'temp-or-stale-root' } : {}),
+  };
+}

package/bin/lib/config-warnings.mjs

@@ -0,0 +1,228 @@
+/**
+ * Config validation warnings + intent layer helpers for ark-check.
+ * Extracted from ark-check entry (R3).
+ */
+import path from 'node:path';
+import {
+  DEFAULT_INTENT_PREFIXES,
+  globToRegExp,
+  layerForFile,
+  patternSpecificity,
+  resolveIntentLayer,
+} from '../ark-shared.mjs';
+import { normalize } from './scan-files.mjs';
+
+export function intentLayersFromManifest(manifest) {
+  const layers = manifest?.architecture?.layers;
+  if (!Array.isArray(layers)) return undefined;
+  return layers
+    .filter((layer) => Array.isArray(layer.prefixes) && layer.prefixes.length > 0)
+    .map((layer) => ({ name: layer.name, prefixes: layer.prefixes }));
+}
+
+export function layerForIntent(intent, layers, manifestIntentLayers) {
+  // Use only layers that declare intent prefixes; fall back to the built-in defaults when
+  // none do (mirrors the write-gate). resolveIntentLayer applies the library's exact
+  // longest-prefix + trailing-dot semantics so CI and the MCP gate classify identically.
+  const configured =
+    manifestIntentLayers ??
+    layers
+      .filter((layer) => (layer.intentPrefixes ?? []).length > 0)
+      .map((layer) => ({ name: layer.name, prefixes: layer.intentPrefixes }));
+  const source =
+    configured.length > 0
+      ? configured
+      : DEFAULT_INTENT_PREFIXES.map((entry) => ({ name: entry.layer, prefixes: entry.prefixes }));
+  return resolveIntentLayer(intent, source);
+}
+
+export function isBlocked(rules, from, to) {
+  return rules.find((rule) => !rule.allowed && rule.from === from && rule.to === to);
+}
+
+export function configWarning(ruleId, message, extra = {}) {
+  return { ruleId, message, ...extra };
+}
+
+export function collectConfigWarnings(root, config, files, rules, manifest) {
+  const warnings = [];
+  const layers = Array.isArray(config.layers) ? config.layers : [];
+  const manifestLayers = Array.isArray(manifest?.architecture?.layers)
+    ? manifest.architecture.layers
+    : [];
+  const knownLayers = new Set([
+    ...layers.map((layer) => layer.name).filter(Boolean),
+    ...manifestLayers.map((layer) => layer.name).filter(Boolean),
+  ]);
+
+  if (layers.length === 0) {
+    warnings.push(
+      configWarning(
+        'CONFIG_NO_LAYERS',
+        'No file layers are configured; ark-check cannot classify files for import-boundary enforcement.'
+      )
+    );
+  }
+
+  const seenLayers = new Set();
+  const duplicateLayers = new Set();
+  for (const layer of layers) {
+    if (!layer.name) {
+      warnings.push(
+        configWarning('CONFIG_LAYER_WITHOUT_NAME', 'A configured layer is missing a name.')
+      );
+      continue;
+    }
+    if (seenLayers.has(layer.name)) duplicateLayers.add(layer.name);
+    seenLayers.add(layer.name);
+
+    if (
+      layer.forbiddenGlobals !== undefined &&
+      (!Array.isArray(layer.forbiddenGlobals) ||
+        layer.forbiddenGlobals.some((entry) => typeof entry !== 'string'))
+    ) {
+      warnings.push(
+        configWarning(
+          'CONFIG_INVALID_FORBIDDEN_GLOBALS',
+          `Layer "${layer.name}" has an invalid forbiddenGlobals value; expected an array of strings (e.g. ["fetch", "Date.now"]). The entry is ignored.`,
+          { layer: layer.name }
+        )
+      );
+    }
+
+    const patterns = Array.isArray(layer.patterns) ? layer.patterns : [];
+    if (patterns.length === 0) {
+      warnings.push(
+        configWarning(
+          'CONFIG_LAYER_WITHOUT_PATTERNS',
+          `Layer "${layer.name}" has no file patterns and will never classify files.`,
+          { layer: layer.name }
+        )
+      );
+      continue;
+    }
+
+    for (const pattern of patterns) {
+      let re;
+      try {
+        re = globToRegExp(pattern);
+      } catch (err) {
+        warnings.push(
+          configWarning(
+            'CONFIG_INVALID_LAYER_PATTERN',
+            `Layer "${layer.name}" has an invalid pattern "${pattern}": ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+            { layer: layer.name, pattern }
+          )
+        );
+        continue;
+      }
+
+      const matched = files.some((file) => {
+        const rel = normalize(path.relative(root, file));
+        return re.test(rel);
+      });
+      if (!matched && !layer.optional) {
+        // Advisory only under --strict-config: monorepo/Next presets ship many optional-looking
+        // globs (e.g. src/layouts/**, app/**) that never match when include is ["frontend"].
+        // Failing the release gate on dead preset globs caused false CI red while architecture
+        // edges were clean (deer-flow host validation). Real safety is import violations +
+        // CONFIG_UNCLASSIFIED_FILES / invalid patterns.
+        warnings.push(
+          configWarning(
+            'CONFIG_LAYER_PATTERN_NO_MATCHES',
+            `Layer "${layer.name}" pattern "${pattern}" matched no included files.`,
+            { layer: layer.name, pattern, failsStrict: false }
+          )
+        );
+      }
+    }
+  }
+
+  for (const name of duplicateLayers) {
+    warnings.push(
+      configWarning(
+        'CONFIG_DUPLICATE_LAYER',
+        `Layer "${name}" is configured more than once.`,
+        { layer: name }
+      )
+    );
+  }
+
+  if (knownLayers.size > 0) {
+    for (const rule of rules ?? []) {
+      if (rule.from && !knownLayers.has(rule.from)) {
+        warnings.push(
+          configWarning(
+            'CONFIG_RULE_UNKNOWN_FROM_LAYER',
+            `Rule references unknown source layer "${rule.from}".`,
+            { fromLayer: rule.from, toLayer: rule.to }
+          )
+        );
+      }
+      if (rule.to && !knownLayers.has(rule.to)) {
+        warnings.push(
+          configWarning(
+            'CONFIG_RULE_UNKNOWN_TO_LAYER',
+            `Rule references unknown target layer "${rule.to}".`,
+            { fromLayer: rule.from, toLayer: rule.to }
+          )
+        );
+      }
+    }
+  }
+
+  // Ambiguous overlap: a file matched by two different layers at the SAME top specificity.
+  // layerForFile breaks the tie by declaration order, but the config is genuinely undecided
+  // (unlike a facade split, where the surface pattern is strictly more specific and wins
+  // cleanly). Surface the layer pairs so the author disambiguates instead of relying on order.
+  const ambiguousPairs = new Set();
+  if (layers.length > 1) {
+    for (const file of files) {
+      const rel = normalize(path.relative(root, file));
+      let topScore = -1;
+      let topLayers = [];
+      for (const layer of layers) {
+        for (const pattern of layer.patterns ?? []) {
+          if (!globToRegExp(pattern).test(rel)) continue;
+          const score = patternSpecificity(pattern);
+          if (score > topScore) {
+            topScore = score;
+            topLayers = [layer.name];
+          } else if (score === topScore && !topLayers.includes(layer.name)) {
+            topLayers.push(layer.name);
+          }
+        }
+      }
+      if (topLayers.length > 1) {
+        ambiguousPairs.add([...topLayers].sort().join(' + '));
+      }
+    }
+  }
+  if (ambiguousPairs.size > 0) {
+    warnings.push(
+      configWarning(
+        'CONFIG_AMBIGUOUS_LAYERS',
+        `Some files match multiple layers at equal specificity; classification falls back to declaration order. Disambiguate the overlapping patterns: ${[...ambiguousPairs].join(', ')}.`,
+        { pairs: [...ambiguousPairs] }
+      )
+    );
+  }
+
+  const unclassified = files.filter((file) => !layerForFile(root, file, layers));
+  if (unclassified.length > 0) {
+    warnings.push(
+      configWarning(
+        'CONFIG_UNCLASSIFIED_FILES',
+        `${unclassified.length} included source file(s) are not matched by any configured layer; ark-check will not enforce import rules for those source files.`,
+        {
+          count: unclassified.length,
+          samples: unclassified.slice(0, 5).map((file) => normalize(path.relative(root, file))),
+        }
+      )
+    );
+  }
+
+  return warnings;
+}

package/bin/lib/doctor-plan.mjs

@@ -162,6 +162,8 @@ export function buildRemediationPlan(root, activeViolations, governedPercent = n
       ...(v.typeOnly ? { typeOnly: true } : {}),
       ...(v.targetTypeOnlyExports ? { targetTypeOnlyExports: true } : {}),
       ...(v.sourcePureTypeModule ? { sourcePureTypeModule: true } : {}),
+      ...(v.namedBindingsTypeOnly ? { namedBindingsTypeOnly: true } : {}),
+      ...(v.edgeKind ? { edgeKind: v.edgeKind } : {}),
       ...(verdict.remediationKind ? { remediationKind: verdict.remediationKind } : {}),
     };
   });

package/bin/lib/graph-cycles.mjs

@@ -0,0 +1,56 @@
+/**
+ * Import-graph cycle detection (Tarjan) for ark-check.
+ * Extracted from ark-check entry (R3).
+ */
+export function detectCycles(graph) {
+  let index = 0;
+  const indices = new Map();
+  const low = new Map();
+  const onStack = new Set();
+  const stack = [];
+  const components = [];
+
+  // ponytail: recursive Tarjan; make it iterative only if a real repo blows the stack.
+  const strongconnect = (v) => {
+    indices.set(v, index);
+    low.set(v, index);
+    index += 1;
+    stack.push(v);
+    onStack.add(v);
+    for (const w of [...(graph.get(v) ?? [])].sort()) {
+      if (!graph.has(w)) continue;
+      if (!indices.has(w)) {
+        strongconnect(w);
+        low.set(v, Math.min(low.get(v), low.get(w)));
+      } else if (onStack.has(w)) {
+        low.set(v, Math.min(low.get(v), indices.get(w)));
+      }
+    }
+    if (low.get(v) === indices.get(v)) {
+      const comp = [];
+      let w;
+      do {
+        w = stack.pop();
+        onStack.delete(w);
+        comp.push(w);
+      } while (w !== v);
+      if (comp.length > 1) components.push(comp.sort());
+    }
+  };
+
+  for (const v of [...graph.keys()].sort()) {
+    if (!indices.has(v)) strongconnect(v);
+  }
+
+  return components
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map((members) => ({
+      ruleId: 'CIRCULAR_DEPENDENCY',
+      file: members[0],
+      line: 1,
+      target: members.join(' → '),
+      message: `Circular dependency among ${members.length} files: ${members.join(' → ')} → ${members[0]}.`,
+      // Graph is value/runtime edges only (type-only imports omitted).
+      cycleKind: 'value',
+    }));
+}