arkgate 2.11.0 → 2.13.0

package/bin/lib/enforcement-profiles.mjs

@@ -0,0 +1,97 @@
+/**
+ * Static host support plus preflight validation for requested write guarantees.
+ * Installed evidence remains authoritative in write-path-capabilities.mjs.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectWritePathCapabilities } from './write-path-detect.mjs';
+import {
+  HOST_SUPPORT_HOSTS,
+  HOST_SUPPORT_MATRIX,
+} from './host-support-matrix.mjs';
+import { KNOWN_TOOLS, normalizeToolsList } from './skill-install.mjs';
+
+export const HOST_ENFORCEMENT_SUPPORT = Object.freeze(
+  Object.fromEntries(
+    HOST_SUPPORT_HOSTS.map((host) => {
+      const profile = HOST_SUPPORT_MATRIX[host];
+      return [
+        host,
+        Object.freeze({
+          hardWrite: profile.capabilities['hard-write'],
+          advisoryWrite: profile.capabilities['advisory-write'],
+          hookPath: profile.hookPath,
+        }),
+      ];
+    })
+  )
+);
+
+export const WRITE_PROFILE_HOSTS = HOST_SUPPORT_HOSTS;
+
+export function validateSelectedTools(tools) {
+  if (tools == null) return { ok: true, tools: null };
+  const selected = normalizeToolsList(tools);
+  const unknown = selected.filter((tool) => !KNOWN_TOOLS.includes(tool));
+  if (selected.length === 0 || unknown.length > 0) {
+    return {
+      ok: false,
+      error:
+        `--tools expects a comma-separated subset of: ${KNOWN_TOOLS.join(', ')}` +
+        (unknown.length > 0 ? ` (unknown: ${unknown.join(', ')})` : ''),
+    };
+  }
+  return { ok: true, tools: selected };
+}
+
+export function hasHardWriteHook(root, host) {
+  return detectWritePathCapabilities(root, host).capabilities['hard-write'];
+}
+
+export function validateHardWriteRequest({ root, host, tools, force = false }) {
+  const toolSelection = validateSelectedTools(tools);
+  if (!toolSelection.ok) return toolSelection;
+  if (host == null) return { ok: true, host: null, tools: toolSelection.tools };
+
+  const normalizedHost = String(host).trim().toLowerCase();
+  const support = HOST_ENFORCEMENT_SUPPORT[normalizedHost];
+  if (!support) {
+    return {
+      ok: false,
+      error: `Unknown write host "${normalizedHost}". Expected: ${WRITE_PROFILE_HOSTS.join(', ')}.`,
+    };
+  }
+  if (!support.hardWrite) {
+    return {
+      ok: false,
+      error:
+        `${normalizedHost} supports advisory-write plus the shared CI check, not a hard local write hook. ` +
+        'Omit --require-write-hook, keep --strict-merge in CI, and require that status to block merges.',
+    };
+  }
+
+  const selectedTools = toolSelection.tools ?? [normalizedHost];
+  if (!selectedTools.includes(normalizedHost)) {
+    return {
+      ok: false,
+      error: `--require-write-hook ${normalizedHost} requires --tools to include ${normalizedHost}.`,
+    };
+  }
+
+  const hookFile = path.join(root, support.hookPath);
+  if (fs.existsSync(hookFile) && !force && !hasHardWriteHook(root, normalizedHost)) {
+    return {
+      ok: false,
+      error:
+        `${support.hookPath} already exists without an Ark hard-write hook and would be preserved. ` +
+        'Use --force to replace that host file, or omit --require-write-hook for merge-only enforcement.',
+    };
+  }
+
+  return {
+    ok: true,
+    host: normalizedHost,
+    tools: selectedTools,
+    support,
+  };
+}

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`;
+}

package/bin/lib/host-support-matrix.mjs

@@ -0,0 +1,77 @@
+/**
+ * Canonical host support promises.
+ *
+ * These records describe what ArkGate can install for each supported host.
+ * Installed evidence remains authoritative for a specific repository and is
+ * reported separately by write-path-capabilities.mjs.
+ */
+
+function hostProfile(label, hookPath, hookSurface, hardWrite, repairPayload) {
+  return Object.freeze({
+    label,
+    hookPath,
+    hookSurface,
+    capabilities: Object.freeze({
+      'hard-write': hardWrite,
+      'advisory-write': true,
+      'merge-gate': true,
+      'repair-payload': repairPayload,
+    }),
+  });
+}
+
+export const HOST_SUPPORT_MATRIX = Object.freeze({
+  claude: hostProfile(
+    'Claude Code',
+    '.claude/settings.json',
+    'PreToolUse `Write` / `Edit` / `MultiEdit`',
+    true,
+    true
+  ),
+  grok: hostProfile(
+    'Grok Build',
+    '.grok/hooks/ark-write-gate.json',
+    'PreToolUse `write` / `search_replace` (plus aliases)',
+    true,
+    true
+  ),
+  cursor: hostProfile('Cursor', null, null, false, false),
+  codex: hostProfile('OpenAI Codex', null, null, false, false),
+});
+
+export const HOST_SUPPORT_HOSTS = Object.freeze(Object.keys(HOST_SUPPORT_MATRIX));
+
+export function getHostSupportProfile(host) {
+  const normalized = typeof host === 'string' ? host.trim().toLowerCase() : '';
+  return HOST_SUPPORT_MATRIX[normalized] ?? null;
+}
+
+export function formatHostSupportSummary(profile) {
+  if (!profile) return 'unknown host; no local write guarantee';
+  const capabilities = profile.capabilities;
+  const write = capabilities['hard-write']
+    ? 'hard local write boundary'
+    : 'no hard local write boundary';
+  const repair = capabilities['repair-payload'] ? 'repair payload' : 'no hard-boundary repair';
+  return `${write} + advisory MCP + CI check + ${repair}`;
+}
+
+export function renderHostSupportMatrixMarkdown() {
+  const rows = HOST_SUPPORT_HOSTS.map((host) => {
+    const profile = HOST_SUPPORT_MATRIX[host];
+    const capabilities = profile.capabilities;
+    const local = capabilities['hard-write']
+      ? `Hard block for ${profile.hookSurface}`
+      : 'No hard hook; MCP/rules are advisory';
+    const repair = capabilities['repair-payload']
+      ? 'Emitted on hook deny; host must re-inject'
+      : 'No hard-boundary payload';
+    return `| ${profile.label} | ${local} | Advisory; the agent must call it | Available \`arkgate-check --strict-merge\` check | ${repair} |`;
+  }).join('\n');
+
+  return `| Host | Local write boundary | MCP validation | CI / merge path | Repair payload |
+|------|----------------------|----------------|-----------------|----------------|
+${rows}
+
+This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair payloads never write code silently: the host must re-inject the candidate and ArkGate revalidates it. Run \`arkgate-check --doctor\` for the evidence actually detected in the current repository.`;
+}