arkgate 2.10.0 → 2.12.0

package/bin/lib/deploy-path.mjs

@@ -0,0 +1,205 @@
+/**
+ * Production deploy-path quality signals (install modularization).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readPackageJson, packageScriptsHaveTypecheck } from './gate-files.mjs';
+
+/**
+ * Production deploy path quality (universal — any consumer repo).
+ * Detects when the production build host runs ESLint / typecheck as part of
+ * `build` (e.g. Next.js "Linting and checking validity of types") so failures
+ * surface first on Vercel/Netlify/etc. unless CI/pre-merge runs the same checks.
+ * Framework signals only (deps + scripts + config) — never project-specific.
+ *
+ * @returns {{
+ *   embedsLintInBuild: boolean,
+ *   embedsTypecheckInBuild: boolean,
+ *   engines: string[],
+ *   hasLintScript: boolean,
+ *   hasTypecheckScript: boolean,
+ *   ciRunsLint: boolean,
+ *   ciRunsTypecheck: boolean,
+ *   eslintIgnoreDuringBuilds: boolean,
+ * }}
+ */
+export function detectDeployPathQuality(root) {
+  const pkg = readPackageJson(root) || {};
+  const deps = {
+    ...(pkg.dependencies && typeof pkg.dependencies === 'object' ? pkg.dependencies : {}),
+    ...(pkg.devDependencies && typeof pkg.devDependencies === 'object' ? pkg.devDependencies : {}),
+    ...(pkg.peerDependencies && typeof pkg.peerDependencies === 'object' ? pkg.peerDependencies : {}),
+  };
+  const scripts =
+    pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+  const buildScript = typeof scripts.build === 'string' ? scripts.build : '';
+
+  const engines = [];
+  // Next.js production build runs ESLint + typecheck by default (unless opted out).
+  if (deps.next || /\bnext\s+build\b/.test(buildScript)) engines.push('next');
+  // Nuxt 3+ can lint via modules; only flag when build clearly invokes nuxt build + eslint tooling present.
+  if ((deps.nuxt || deps['nuxt3'] || /\bnuxt\s+build\b/.test(buildScript)) && (deps.eslint || hasEslintConfig(root))) {
+    engines.push('nuxt');
+  }
+  // Create React App historically failed build on ESLint errors.
+  if (deps['react-scripts'] || /\breact-scripts\s+build\b/.test(buildScript)) engines.push('cra');
+
+  const eslintIgnoreDuringBuilds = engines.includes('next') && nextIgnoresEslintDuringBuilds(root);
+  const embedsLintInBuild = engines.length > 0 && !eslintIgnoreDuringBuilds;
+  // Next still typechecks during build even when eslint.ignoreDuringBuilds is true.
+  const embedsTypecheckInBuild = engines.includes('next') || engines.includes('nuxt');
+
+  const scriptHasLint = (s) =>
+    Boolean(
+      s &&
+        ((typeof s.lint === 'string' && s.lint.trim()) ||
+          (typeof s.eslint === 'string' && s.eslint.trim()) ||
+          (typeof s['lint:ci'] === 'string' && s['lint:ci'].trim()) ||
+          (typeof s['check:lint'] === 'string' && s['check:lint'].trim()))
+    );
+
+  let hasLintScript = scriptHasLint(scripts);
+  let hasTypecheckScript = packageScriptsHaveTypecheck(scripts);
+  const packageLintScripts = [];
+  // Monorepo: package-level scripts count (apps/web, packages/ui, …).
+  try {
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const candidates = [path.join(root, entry.name)];
+      // one more level: packages/foo
+      try {
+        for (const child of fs.readdirSync(path.join(root, entry.name), { withFileTypes: true })) {
+          if (child.isDirectory() && !child.name.startsWith('.')) {
+            candidates.push(path.join(root, entry.name, child.name));
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+      for (const dir of candidates) {
+        const pj = path.join(dir, 'package.json');
+        if (!fs.existsSync(pj)) continue;
+        try {
+          const nested = JSON.parse(fs.readFileSync(pj, 'utf8'));
+          const ns = nested.scripts && typeof nested.scripts === 'object' ? nested.scripts : {};
+          if (scriptHasLint(ns)) {
+            hasLintScript = true;
+            packageLintScripts.push(path.relative(root, dir).split(path.sep).join('/'));
+          }
+          if (packageScriptsHaveTypecheck(ns)) hasTypecheckScript = true;
+          const nd = {
+            ...(nested.dependencies || {}),
+            ...(nested.devDependencies || {}),
+          };
+          if (nd.next && !engines.includes('next')) engines.push('next');
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+
+  const ciTexts = collectCiWorkflowTexts(root);
+  const ciJoined = ciTexts.join('\n');
+  const ciRunsLint =
+    ciTexts.length > 0 &&
+    (/\bnpm\s+run\s+lint\b/i.test(ciJoined) ||
+      /\bpnpm\s+(?:run\s+)?lint\b/i.test(ciJoined) ||
+      /\byarn\s+(?:run\s+)?lint\b/i.test(ciJoined) ||
+      /\bbun\s+run\s+lint\b/i.test(ciJoined) ||
+      /\beslint\b/i.test(ciJoined) ||
+      /\blint:ci\b/i.test(ciJoined) ||
+      /\bcheck:lint\b/i.test(ciJoined) ||
+      // package-level: working-directory + lint, or path/filter lint
+      (packageLintScripts.length > 0 &&
+        packageLintScripts.some((p) => ciJoined.includes(p) && /lint/i.test(ciJoined))));
+  const ciRunsTypecheck =
+    ciTexts.length > 0 &&
+    (/\btypecheck\b/i.test(ciJoined) ||
+      /\btype-check\b/i.test(ciJoined) ||
+      /\bcheck:types\b/i.test(ciJoined) ||
+      /\btsc\s+--noEmit\b/i.test(ciJoined));
+
+  return {
+    embedsLintInBuild,
+    embedsTypecheckInBuild,
+    engines,
+    hasLintScript,
+    hasTypecheckScript,
+    ciRunsLint,
+    ciRunsTypecheck,
+    eslintIgnoreDuringBuilds,
+    hasCiWorkflows: ciTexts.length > 0,
+    packageLintScripts,
+  };
+}
+
+function hasEslintConfig(root) {
+  return [
+    'eslint.config.mjs',
+    'eslint.config.js',
+    'eslint.config.cjs',
+    'eslint.config.ts',
+    '.eslintrc.json',
+    '.eslintrc.cjs',
+    '.eslintrc.js',
+    '.eslintrc.yml',
+    '.eslintrc.yaml',
+  ].some((f) => fs.existsSync(path.join(root, f)));
+}
+
+/** next.config.* eslint.ignoreDuringBuilds: true → production build will not fail on ESLint. */
+function nextIgnoresEslintDuringBuilds(root) {
+  const names = [
+    'next.config.ts',
+    'next.config.mts',
+    'next.config.js',
+    'next.config.mjs',
+    'next.config.cjs',
+  ];
+  for (const name of names) {
+    const file = path.join(root, name);
+    if (!fs.existsSync(file)) continue;
+    try {
+      const text = fs.readFileSync(file, 'utf8');
+      // Common patterns: ignoreDuringBuilds: true | ignoreDuringBuilds: true,
+      if (/ignoreDuringBuilds\s*:\s*true/.test(text)) return true;
+    } catch {
+      /* ignore */
+    }
+  }
+  return false;
+}
+
+function collectCiWorkflowTexts(root) {
+  const texts = [];
+  const pushFile = (rel) => {
+    try {
+      const full = path.join(root, rel);
+      if (fs.existsSync(full) && fs.statSync(full).isFile()) {
+        texts.push(fs.readFileSync(full, 'utf8'));
+      }
+    } catch {
+      /* ignore */
+    }
+  };
+  pushFile('.gitlab-ci.yml');
+  pushFile('bitbucket-pipelines.yml');
+  pushFile('azure-pipelines.yml');
+  pushFile('.circleci/config.yml');
+  const wfDir = path.join(root, '.github', 'workflows');
+  try {
+    if (fs.existsSync(wfDir)) {
+      for (const f of fs.readdirSync(wfDir)) {
+        if (!/\.ya?ml$/i.test(f)) continue;
+        pushFile(path.join('.github', 'workflows', f));
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return texts;
+}
+

package/bin/lib/doctor-plan.mjs

@@ -19,7 +19,7 @@ import {
   staleRunnerGateFiles,
 } from './agent-gates.mjs';
 import {
-  baselineKey,
+  baselineOccurrenceKeys,
   readBaseline,
   summarizeViolations,
   violationEdge,
@@ -272,9 +272,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   // Prefer writePath from adoption (same detector); recompute only if missing (tests/stubs).
   const writePath = adoption.writePath ?? detectWritePathCapabilities(root);
   const baseline = readBaseline(root, '.ark-baseline.json');
-  const currentKeys = new Set(violations.map(baselineKey));
+  const occurrenceKeys = baselineOccurrenceKeys(violations);
+  const currentKeys = new Set(occurrenceKeys);
   const suppressed = baseline.exists
-    ? violations.filter((v) => baseline.keys.has(baselineKey(v))).length
+    ? occurrenceKeys.filter((key) => baseline.keys.has(key)).length
     : 0;
   const staleBaseline = baseline.exists
     ? [...baseline.keys].filter((key) => !currentKeys.has(key)).length
@@ -347,6 +348,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
                 : { gap: null }),
             },
             adoption,
+            safety: options.safety,
             newHere: showNewHere
               ? {
                   show: true,
@@ -592,11 +594,33 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     line(ok, 'Origin architecture snapshot present (.ark/reports/origin.json)');
   }
 
+  console.log('');
+  console.log(color.bold('Safety / bypass resistance'));
+  const safety = options.safety;
+  if (!safety) {
+    line(warn, 'Safety diagnostics unavailable');
+  } else {
+    const rows = [
+      ['Non-literal dynamic imports', safety.nonLiteralDynamicImports],
+      ['@ts-ignore / @ts-nocheck', safety.tsSuppressions],
+      ['Explicit any casts', safety.anyCasts],
+      ['InMemory stores in production source', safety.inMemoryProductionStores],
+      ['Rules with peerIsolation: false', safety.disabledPeerIsolationRules],
+    ];
+    for (const [label, entries] of rows) {
+      line(entries.length === 0 ? ok : warn, `${label}: ${entries.length}`);
+    }
+    if (rows.some(([, entries]) => entries.length > 0)) {
+      actions.push('resolve strict safety diagnostics before treating CI as enforcement');
+    }
+  }
+
   console.log('');
   if (actions.length === 0) {
     console.log(color.green('✔ Healthy — nothing to do.'));
   } else {
-    console.log(color.bold(`Top actions (${actions.length}):`));
-    actions.forEach((action, index) => console.log(`  ${index + 1}. ${action}`));
+    const uniqueActions = [...new Set(actions.filter(Boolean))];
+    console.log(color.bold(`Top actions (${uniqueActions.length}):`));
+    uniqueActions.forEach((action, index) => console.log(`  ${index + 1}. ${action}`));
   }
 }

package/bin/lib/gate-files.mjs

@@ -0,0 +1,223 @@
+/**
+ * Gate file IO: package.json helpers, template writes, required gates.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const __packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const __arkCheckCli = path.join(__packageRoot, 'bin', 'ark-check.mjs');
+
+export function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+export function readPackageJson(root) {
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) return null;
+  return readJson(file);
+}
+
+export function hasCheckArchitectureScript(root) {
+  const pkg = readPackageJson(root);
+  return Boolean(pkg?.scripts?.['check:architecture']);
+}
+
+/**
+ * Whether package.json scripts already expose a typecheck-like command.
+ * Shared by deploy-path quality + typecheck bootstrap (single definition).
+ * @param {Record<string, unknown>|null|undefined} scripts
+ */
+export function packageScriptsHaveTypecheck(scripts) {
+  if (!scripts || typeof scripts !== 'object') return false;
+  return Boolean(
+    (typeof scripts.typecheck === 'string' && scripts.typecheck.trim()) ||
+      (typeof scripts['type-check'] === 'string' && scripts['type-check'].trim()) ||
+      (typeof scripts['check:types'] === 'string' && scripts['check:types'].trim()) ||
+      (typeof scripts.tsc === 'string' && /\btsc\b/.test(scripts.tsc))
+  );
+}
+
+/**
+ * Root package (and shallow nested packages) already have a typecheck script.
+ * Does not scan CI or framework configs — only package.json scripts.
+ * @param {string} root
+ */
+export function treeHasTypecheckScript(root) {
+  const pkg = readPackageJson(root);
+  if (packageScriptsHaveTypecheck(pkg?.scripts)) return true;
+  try {
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const candidates = [path.join(root, entry.name)];
+      try {
+        for (const child of fs.readdirSync(path.join(root, entry.name), { withFileTypes: true })) {
+          if (child.isDirectory() && !child.name.startsWith('.')) {
+            candidates.push(path.join(root, entry.name, child.name));
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+      for (const dir of candidates) {
+        const pj = path.join(dir, 'package.json');
+        if (!fs.existsSync(pj)) continue;
+        try {
+          const nested = JSON.parse(fs.readFileSync(pj, 'utf8'));
+          if (packageScriptsHaveTypecheck(nested.scripts)) return true;
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return false;
+}
+
+/**
+ * Add a conservative `typecheck` script when the host has a TS/JS project config
+ * but no typecheck-like script yet. Never overwrites an existing script.
+ *
+ * @param {string} root
+ * @param {{ write?: boolean }} [opts]
+ * @returns {{
+ *   changed: boolean,
+ *   reason: 'added' | 'already' | 'no-tsconfig' | 'no-package-json',
+ *   script?: string,
+ * }}
+ */
+export function ensureTypecheckScript(root, opts = {}) {
+  const write = opts.write !== false;
+  const hasTsconfig =
+    fs.existsSync(path.join(root, 'tsconfig.json')) ||
+    fs.existsSync(path.join(root, 'jsconfig.json'));
+  if (!hasTsconfig) return { changed: false, reason: 'no-tsconfig' };
+
+  const pkgPath = path.join(root, 'package.json');
+  if (!fs.existsSync(pkgPath)) return { changed: false, reason: 'no-package-json' };
+
+  if (treeHasTypecheckScript(root)) {
+    return { changed: false, reason: 'already' };
+  }
+
+  const pkg = readPackageJson(root) || {};
+  const scripts =
+    pkg.scripts && typeof pkg.scripts === 'object' ? { ...pkg.scripts } : {};
+  const script = 'tsc --noEmit';
+  scripts.typecheck = script;
+  if (write) {
+    const next = { ...pkg, scripts };
+    fs.writeFileSync(pkgPath, `${JSON.stringify(next, null, 2)}\n`);
+  }
+  return { changed: true, reason: 'added', script };
+}
+
+export const REQUIRED_GATE_FILES = [
+  'AGENTS.md',
+  '.mcp.json',
+];
+const REQUIRED_GATE_WORKFLOW = '.github/workflows/*.yml running ark-check';
+
+export function hasArkWorkflow(root) {
+  const workflowsDir = path.join(root, '.github', 'workflows');
+  if (!fs.existsSync(workflowsDir)) return false;
+  return fs
+    .readdirSync(workflowsDir)
+    .filter((file) => /\.ya?ml$/i.test(file))
+    .some((file) => {
+      try {
+        const content = fs.readFileSync(path.join(workflowsDir, file), 'utf8');
+        return (
+          /\bark-check\b/.test(content) ||
+          /\bcheck:architecture\b/.test(content) ||
+          /\buses\s*:\s*['"]?[^'"\s#]+\/arkgate@/i.test(content)
+        );
+      } catch {
+        return false;
+      }
+    });
+}
+
+export function missingGates(root) {
+  const missing = REQUIRED_GATE_FILES.filter(
+    (relativePath) => !fs.existsSync(path.join(root, relativePath))
+  );
+  if (!hasArkWorkflow(root)) missing.push(REQUIRED_GATE_WORKFLOW);
+  return missing;
+}
+
+export function ensureDirForFile(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+}
+
+/**
+ * True when AGENTS.md is wholly Ark-owned (header is Ark Enforcement).
+ * Project guides that merely append an Ark section must remain non-Ark so --force
+ * never wipes them.
+ */
+export function isArkAgentsContent(text) {
+  if (typeof text !== 'string' || !text.trim()) return false;
+  const head = text.trimStart().slice(0, 120);
+  return /^#\s*Ark(Gate)?\s+Enforcement\b/.test(head);
+}
+
+/**
+ * True when AGENTS.md is the **library mother-repo** self-hosted guide (Identity block).
+ * Never replace with the consumer install template — even under `--force`.
+ */
+export function isSelfHostedLibraryAgents(text) {
+  if (typeof text !== 'string' || !text.trim()) return false;
+  return (
+    /##\s*Identity\s*[—\-–-]\s*read this first/i.test(text) ||
+    /mother\s*\/\s*canonical development repository/i.test(text) ||
+    /Git\s*\/\s*clone only/i.test(text)
+  );
+}
+
+export function writeTemplate(root, relativePath, content, force) {
+  const fullPath = path.join(root, relativePath);
+  if (relativePath === 'AGENTS.md' && fs.existsSync(fullPath)) {
+    let existing = '';
+    try {
+      existing = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      existing = '';
+    }
+    // Library authoring tree: keep Identity + 4-layer dogfood contract forever.
+    if (existing && isSelfHostedLibraryAgents(existing)) {
+      return { relativePath, status: 'skipped-self-hosted' };
+    }
+    if (existing && !isArkAgentsContent(existing)) {
+      // Never clobber a project-owned AGENTS.md — even with --force.
+      // If Ark section not present yet, merge once; subsequent runs leave it alone.
+      const hasArkSection =
+        /#\s*Ark(Gate)?\s+Enforcement\b/.test(existing) ||
+        /ark\.config\.json is authoritative/i.test(existing);
+      if (force && isArkAgentsContent(content) && !hasArkSection) {
+        try {
+          const merged = `${existing.replace(/\s*$/, '')}\n\n---\n\n${content}`;
+          ensureDirForFile(fullPath);
+          fs.writeFileSync(fullPath, merged);
+          return { relativePath, status: 'merged' };
+        } catch {
+          return { relativePath, status: 'failed' };
+        }
+      }
+      return { relativePath, status: 'skipped-non-ark' };
+    }
+    if (!force && isArkAgentsContent(existing)) {
+      return { relativePath, status: 'skipped' };
+    }
+  } else if (fs.existsSync(fullPath) && !force) {
+    return { relativePath, status: 'skipped' };
+  }
+  try {
+    ensureDirForFile(fullPath);
+    fs.writeFileSync(fullPath, content);
+    return { relativePath, status: 'written' };
+  } catch {
+    return { relativePath, status: 'failed' };
+  }
+}

package/bin/lib/hook-templates.mjs

@@ -0,0 +1,99 @@
+/**
+ * Host hook / MCP project templates for agent-gate install (Claude, Grok).
+ * Kept out of agent-gates.mjs so install orchestration stays scannable (explore gap #5).
+ */
+import { execCommandParts, execRunner } from '../ark-shared.mjs';
+
+/** Preferred MCP binary name for generated hooks (package dual-bin). */
+export const PREFERRED_MCP_BIN = 'arkgate-mcp';
+
+export function claudeSettings(root) {
+  const runner = execRunner(root);
+  return `${JSON.stringify({
+    hooks: {
+      // Inject the contract at session start so the agent knows the architecture from
+      // the first token. Project-scoped by design; --session-context is also a silent
+      // no-op when no ark.config.json exists, so it can never leak into other projects.
+      SessionStart: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command: `${runner} ${PREFERRED_MCP_BIN} --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
+            },
+          ],
+        },
+      ],
+      PreToolUse: [
+        {
+          matcher: 'Write|Edit|MultiEdit',
+          hooks: [
+            {
+              type: 'command',
+              // W4: --hook-repair emits ARK_REPAIR_JSON / ARK_AUTOPATCH_JSON on deny
+              // (still exit 2 — never silent write). Omit --hook-repair for reject-only prose.
+              command: `${runner} ${PREFERRED_MCP_BIN} --hook --hook-repair --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
+            },
+          ],
+        },
+      ],
+    },
+  }, null, 2)}\n`;
+}
+
+// Grok Build project config: MCP registration (commit-friendly relative paths — unlike
+// Codex's global config.toml, Grok loads .grok/config.toml from the project).
+export function grokProjectConfig(root) {
+  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
+    '--root',
+    '.',
+    '--config',
+    'ark.config.json',
+  ]);
+  const argsToml = args.map((value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).join(', ');
+  return `# Generated by ark-check --install-agent-gates (Grok Build project scope).
+# Restart Grok (or /mcps → refresh) after changes. Also loads repo-root .mcp.json.
+[mcp_servers.ark]
+command = "${command.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"
+args = [${argsToml}]
+`;
+}
+
+// Grok Build hooks: same arkgate-mcp contracts as Claude. Grok sets both
+// GROK_WORKSPACE_ROOT and CLAUDE_PROJECT_DIR (Claude-compatible alias). Prefer
+// GROK_* with fallback so hooks still work if only one is present.
+// Matcher keeps Claude names (Write|Edit|MultiEdit) and Grok natives
+// (write|search_replace) — Grok aliases both directions.
+export function grokHooks(root) {
+  const runner = execRunner(root);
+  // Nested defaults: Grok native → Claude alias → project cwd (hook cwd is the workspace).
+  const grokRoot = '${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}';
+  return `${JSON.stringify({
+    hooks: {
+      SessionStart: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              timeout: 30,
+              command: `${runner} ${PREFERRED_MCP_BIN} --session-context --root "${grokRoot}" --config ark.config.json`,
+            },
+          ],
+        },
+      ],
+      PreToolUse: [
+        {
+          matcher: 'Write|Edit|MultiEdit|write|search_replace',
+          hooks: [
+            {
+              type: 'command',
+              timeout: 30,
+              // W4: --hook-repair → structured autoPatch on deny (hard block still).
+              command: `${runner} ${PREFERRED_MCP_BIN} --hook --hook-repair --root "${grokRoot}" --config ark.config.json`,
+            },
+          ],
+        },
+      ],
+    },
+  }, null, 2)}\n`;
+}