arkgate 2.10.0 → 2.12.0

package/bin/lib/scan-files.mjs

@@ -32,24 +32,62 @@ export function isSkippedSourceDir(name) {
   );
 }
 
-export function walk(dir, files = []) {
-  const stat = fs.statSync(dir, { throwIfNoEntry: false });
+function isInsideRoot(root, target) {
+  const rel = path.relative(root, target);
+  return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+/**
+ * Walk source files while treating symlinks explicitly.
+ *
+ * When `root` is provided, every resolved file/directory must stay inside it.
+ * Internal symlink directories are followed once (TypeScript follows them too),
+ * while escaping links fail closed instead of reading arbitrary filesystem paths.
+ */
+export function walk(dir, files = [], options = {}) {
+  const state = options.state ?? {
+    root: options.root ? fs.realpathSync(options.root) : undefined,
+    visitedDirectories: new Set(),
+    visitedFiles: new Set(),
+  };
+  const lstat = fs.lstatSync(dir, { throwIfNoEntry: false });
+  if (!lstat) return files;
+  const resolved = fs.realpathSync(dir);
+  if (state.root && !isInsideRoot(state.root, resolved)) {
+    throw new Error(
+      `Refusing to scan symlink outside project root: ${dir} -> ${resolved}`
+    );
+  }
+  const stat = lstat.isSymbolicLink()
+    ? fs.statSync(dir, { throwIfNoEntry: false })
+    : lstat;
   if (!stat) return files;
   // An `include` entry may be a single file (e.g. a root-level "middleware.ts"),
   // not just a directory — govern it directly instead of trying to scandir it
   // (which threw ENOTDIR). The extension filter still applies.
   if (stat.isFile()) {
-    if (isGovernableSourceFile(path.basename(dir))) files.push(dir);
+    if (
+      isGovernableSourceFile(path.basename(dir)) &&
+      !state.visitedFiles.has(resolved)
+    ) {
+      state.visitedFiles.add(resolved);
+      files.push(dir);
+    }
     return files;
   }
   if (!stat.isDirectory()) return files;
+  if (state.visitedDirectories.has(resolved)) return files;
+  state.visitedDirectories.add(resolved);
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (isSkippedSourceDir(entry.name)) continue;
-      walk(full, files);
+      walk(full, files, { state });
+    } else if (entry.isSymbolicLink()) {
+      if (isSkippedSourceDir(entry.name)) continue;
+      walk(full, files, { state });
     } else if (isGovernableSourceFile(entry.name)) {
-      files.push(full);
+      walk(full, files, { state });
     }
   }
   return files;
@@ -57,7 +95,14 @@ export function walk(dir, files = []) {
 
 /** Walk include roots then drop codegen / config.exclude (universal scan filter). */
 export function collectGovernedFiles(root, config) {
-  const raw = (config.include ?? []).flatMap((entry) => walk(path.join(root, entry)));
+  const state = {
+    root: fs.realpathSync(root),
+    visitedDirectories: new Set(),
+    visitedFiles: new Set(),
+  };
+  const raw = (config.include ?? []).flatMap((entry) =>
+    walk(path.join(root, entry), [], { state })
+  );
   return raw.filter((abs) => {
     const rel = normalize(path.relative(root, abs));
     return !isScanExcludedRelative(rel, config);

package/bin/lib/skill-install.mjs

@@ -0,0 +1,259 @@
+/**
+ * Tool detection, skill templates, stamping, and skill freshness gaps.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { codexPromptsDir } from './codex-home.mjs';
+import { __packageRoot, readJson } from './gate-files.mjs';
+
+export function normalizeToolsList(tools) {
+  if (tools == null) return [];
+  if (Array.isArray(tools)) {
+    return tools
+      .flatMap((t) => String(t).split(','))
+      .map((t) => t.trim().toLowerCase())
+      .filter(Boolean);
+  }
+  if (typeof tools === 'string') {
+    return tools
+      .split(',')
+      .map((t) => t.trim().toLowerCase())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+export function resolveTools(args) {
+  const explicit = normalizeToolsList(args.tools);
+  if (explicit.length > 0) {
+    return { tools: new Set(explicit), source: 'explicit' };
+  }
+  const root = args.root;
+  const detected = new Set();
+  if (fs.existsSync(path.join(root, '.claude'))) detected.add('claude');
+  if (fs.existsSync(path.join(root, '.cursor'))) detected.add('cursor');
+  if (fs.existsSync(path.join(root, '.codex'))) detected.add('codex');
+  if (fs.existsSync(path.join(root, '.grok'))) detected.add('grok');
+  if (fs.existsSync(path.join(root, '.windsurf'))) detected.add('windsurf');
+  // .clinerules can also be a single FILE (older Cline convention); only a directory
+  // can receive .clinerules/ark.md, so a file must not trigger detection.
+  if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
+    detected.add('cline');
+  }
+  if (fs.existsSync(path.join(root, '.kiro'))) detected.add('kiro');
+  if (fs.existsSync(path.join(root, '.roo'))) detected.add('roo');
+  if (fs.existsSync(path.join(root, '.continue'))) detected.add('continue');
+  if (fs.existsSync(path.join(root, '.gemini'))) detected.add('gemini');
+  // copilot has no reliable directory signal (.github exists in most repos),
+  // so it is explicit-only via --tools.
+  // Host signals: Grok Build / xAI agents often have no project `.grok/` yet but
+  // set an env marker (or run with GROK_*). Include Grok so skills install there.
+  if (
+    process.env.GROK_BUILD === '1' ||
+    process.env.GROK_BUILD === 'true' ||
+    process.env.XAI_GROK === '1' ||
+    process.env.XAI_GROK === 'true'
+  ) {
+    detected.add('grok');
+  }
+  // No signal at all: fall back to a complete starter set including Grok (field
+  // log: default claude+cursor+codex silently omitted Grok skills for Grok hosts).
+  if (detected.size === 0) {
+    return { tools: new Set(['claude', 'cursor', 'codex', 'grok']), source: 'default' };
+  }
+  return { tools: detected, source: 'detected' };
+}
+
+export const KNOWN_TOOLS = [
+  'claude',
+  'cursor',
+  'codex',
+  'grok',
+  'windsurf',
+  'cline',
+  'copilot',
+  'kiro',
+  'roo',
+  'continue',
+  'gemini',
+];
+
+// One canonical markdown per skill (templates/skills/*.md, shipped in the npm
+// package); installed into each tool's slash-command location. The YAML
+// frontmatter (name/description) is understood or harmlessly ignored by every
+// host. Kiro has no command mechanism — its steering rule file is the only gate.
+export const SKILL_TOOL_TARGETS = {
+  claude: (name) => `.claude/skills/${name}/SKILL.md`,
+  cursor: (name) => `.cursor/commands/${name}.md`,
+  codex: (name) => `.codex/prompts/${name}.md`,
+  // Grok Build: project skills at .grok/skills/<name>/SKILL.md (slash-invocable).
+  grok: (name) => `.grok/skills/${name}/SKILL.md`,
+  windsurf: (name) => `.windsurf/workflows/${name}.md`,
+  cline: (name) => `.clinerules/workflows/${name}.md`,
+  copilot: (name) => `.github/prompts/${name}.prompt.md`,
+};
+
+// The version of the arkgate package these bins ship with. Used to
+// stamp installed skills so a normal ark-check can tell "outdated skill from an
+// older Ark" apart from "user-customized skill" — the stamp moves with the
+// package, editing the body doesn't.
+export function arkPackageVersion() {
+  try {
+    const pkg = readJson(path.join(__packageRoot, 'package.json'));
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+// Insert `arkVersion: <v>` into a skill's YAML frontmatter (before its closing
+// `---`). No frontmatter → returned unchanged. Idempotent for a given version.
+export function stampSkill(content, version) {
+  if (!version) return content;
+  const lines = content.split('\n');
+  if (lines[0] !== '---') return content;
+  const closeIdx = lines.indexOf('---', 1);
+  if (closeIdx === -1) return content;
+  const existing = lines.findIndex(
+    (line, i) => i > 0 && i < closeIdx && /^arkVersion:/.test(line)
+  );
+  if (existing !== -1) {
+    lines[existing] = `arkVersion: ${version}`;
+  } else {
+    lines.splice(closeIdx, 0, `arkVersion: ${version}`);
+  }
+  return lines.join('\n');
+}
+
+// Read the `arkVersion:` stamp from an installed skill file. Returns null when
+// the file is absent or has no stamp (installed by a pre-stamp Ark, or hand-authored).
+export function installedSkillVersion(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  const match = content.match(/^arkVersion:\s*(.+)$/m);
+  return match ? match[1].trim() : null;
+}
+
+// Numeric-tuple compare of dotted versions; true when `a` is strictly older than
+// `b`. Non-numeric/absent segments compare as 0, so "1.7" < "1.7.5".
+export function isVersionOlder(a, b) {
+  const parse = (v) => String(v).split('.').map((n) => Number.parseInt(n, 10) || 0);
+  const av = parse(a);
+  const bv = parse(b);
+  const len = Math.max(av.length, bv.length);
+  for (let i = 0; i < len; i += 1) {
+    const x = av[i] ?? 0;
+    const y = bv[i] ?? 0;
+    if (x !== y) return x < y;
+  }
+  return false;
+}
+
+export function skillTemplates() {
+  const dir = path.join(__packageRoot, 'templates', 'skills');
+  // A missing/mispackaged templates dir would otherwise install zero skills with
+  // exit 0 — warn so a packaging regression (e.g. "templates" dropped from the
+  // package.json files array) is visible instead of a silent no-op.
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    console.error(
+      `Warning: skill templates directory not found (${dir}); no /ark-* skills installed.`
+    );
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isFile() && /^[a-z0-9-]+\.md$/.test(entry.name))
+    .map((entry) => entry.name)
+    .sort()
+    .map((name) => [path.basename(name, '.md'), fs.readFileSync(path.join(dir, name), 'utf8')]);
+}
+
+// Skill names only, silent on a missing templates dir — for the freshness
+// advisory below, which must not print packaging warnings on every check run.
+export function skillTemplateNames() {
+  const dir = path.join(__packageRoot, 'templates', 'skills');
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isFile() && /^[a-z0-9-]+\.md$/.test(entry.name))
+    .map((entry) => path.basename(entry.name, '.md'));
+}
+
+// A normal ark-check run is the reliable discovery point for new /ark-* skills.
+// Ark ships no install lifecycle script (a postinstall banner would be blocked by
+// modern package managers' script-approval policy anyway, so careful users never
+// saw it — and it broke hardened installs). When a project has adopted Ark agent
+// gates (AGENTS.md present) but a detected tool is missing
+// skills this version ships, surface it here so agents and CI actually notice.
+// Advisory only — never affects the exit code. Copilot has no reliable directory
+// signal, so it is not auto-detected (explicit --tools only), matching resolveTools.
+export function detectCodexHomeGap(root) {
+  if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return null;
+  if (fs.existsSync(path.join(root, 'templates', 'skills'))) return null;
+  const skillNames = skillTemplateNames();
+  if (skillNames.length === 0) return null;
+  const dir = codexPromptsDir();
+  if (!fs.existsSync(dir)) return null;
+  const present = skillNames.filter((name) => fs.existsSync(path.join(dir, `${name}.md`)));
+  if (present.length === 0) return null; // Codex home never set up for Ark — don't nag.
+  const version = arkPackageVersion();
+  const missing = skillNames.length - present.length;
+  let stale = 0;
+  if (version) {
+    for (const name of present) {
+      const installed = installedSkillVersion(path.join(dir, `${name}.md`));
+      if (installed === null || isVersionOlder(installed, version)) stale += 1;
+    }
+  }
+  return missing > 0 || stale > 0 ? { missing, stale } : null;
+}
+
+export function detectSkillGaps(root) {
+  if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return [];
+  // The Ark source tree keeps the skill templates at templates/skills/ — it's the
+  // producer, not a consumer, so it must not nag itself to "install" its own skills.
+  if (fs.existsSync(path.join(root, 'templates', 'skills'))) return [];
+  const skillNames = skillTemplateNames();
+  if (skillNames.length === 0) return [];
+  const detected = [];
+  if (fs.existsSync(path.join(root, '.claude'))) detected.push('claude');
+  if (fs.existsSync(path.join(root, '.cursor'))) detected.push('cursor');
+  if (fs.existsSync(path.join(root, '.codex'))) detected.push('codex');
+  if (fs.existsSync(path.join(root, '.grok'))) detected.push('grok');
+  if (fs.existsSync(path.join(root, '.windsurf'))) detected.push('windsurf');
+  if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
+    detected.push('cline');
+  }
+  const version = arkPackageVersion();
+  const gaps = [];
+  for (const tool of detected) {
+    const target = SKILL_TOOL_TARGETS[tool];
+    if (!target) continue;
+    let missing = 0;
+    let stale = 0;
+    for (const name of skillNames) {
+      const file = path.join(root, target(name));
+      if (!fs.existsSync(file)) {
+        missing += 1;
+      } else if (version) {
+        // An installed skill with no stamp predates stamping (older Ark), or one
+        // stamped behind the current version is left over from an older install.
+        // Either way the shipped skill has moved on — offer a --force refresh.
+        const installed = installedSkillVersion(file);
+        if (installed === null || isVersionOlder(installed, version)) stale += 1;
+      }
+    }
+    if (missing > 0 || stale > 0) gaps.push({ tool, missing, stale });
+  }
+  return gaps;
+}

package/bin/lib/typescript-host.mjs

@@ -0,0 +1,88 @@
+/**
+ * TypeScript host resolution for architecture scan (API-compatible loader).
+ */
+import path from 'node:path';
+import { usableTypescript, typescriptUsabilityHint } from '../ark-shared.mjs';
+import { __arkCheckCli } from './gate-files.mjs';
+
+export async function loadTypeScript(root) {
+  const { createRequire } = await import('node:module');
+  const loaders = [];
+  try {
+    const req = createRequire(path.join(root, 'package.json'));
+    loaders.push({
+      label: 'project',
+      load: () => req('typescript'),
+      resolvePath: () => {
+        try {
+          return req.resolve('typescript');
+        } catch {
+          return null;
+        }
+      },
+    });
+  } catch {
+    /* project has no package.json resolvable tree */
+  }
+  // Nested under arkgate (production dependency) — must work when project has only TS7.
+  try {
+    const req = createRequire(__arkCheckCli);
+    loaders.push({
+      label: 'arkgate',
+      load: () => req('typescript'),
+      resolvePath: () => {
+        try {
+          return req.resolve('typescript');
+        } catch {
+          return null;
+        }
+      },
+    });
+  } catch {
+    /* ark install tree unavailable */
+  }
+  loaders.push({
+    label: 'import',
+    load: async () => {
+      const m = await import('typescript');
+      return m;
+    },
+    resolvePath: () => null,
+  });
+
+  let projectRejected = null;
+  const triedPaths = new Set();
+  for (const { label, load, resolvePath } of loaders) {
+    try {
+      const resolved = typeof resolvePath === 'function' ? resolvePath() : null;
+      if (resolved && triedPaths.has(resolved)) {
+        // Same physical package already rejected (e.g. project === hoisted arkgate path).
+        continue;
+      }
+      if (resolved) triedPaths.add(resolved);
+
+      const mod = await load();
+      const ts = usableTypescript(mod);
+      if (ts) {
+        const version =
+          typeof ts.version === 'string'
+            ? ts.version
+            : typeof mod?.version === 'string'
+              ? mod.version
+              : undefined;
+        return {
+          ts,
+          source: label,
+          version,
+          ...(projectRejected ? { fallbackReason: projectRejected } : {}),
+        };
+      }
+      if (label === 'project' && mod) {
+        projectRejected = `project typescript is not API-compatible (${typescriptUsabilityHint(mod)}); using ArkGate's JS-API TypeScript fallback (TypeScript 7.0 main export is version-only). See docs/typescript-support.md.`;
+      }
+    } catch {
+      /* try next loader */
+    }
+  }
+  return null;
+}

package/bin/lib/violations.mjs

@@ -11,8 +11,8 @@ const color = {
 };
 
 /** Canonical: src/domain/baselineKey.ts → bin/lib/baseline-key.mjs (R4). */
-import { baselineKey } from './baseline-key.mjs';
-export { baselineKey };
+import { baselineKey, baselineOccurrenceKeys } from './baseline-key.mjs';
+export { baselineKey, baselineOccurrenceKeys };
 
 export function readBaseline(root, baselinePath) {
   const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
@@ -23,7 +23,7 @@ export function readBaseline(root, baselinePath) {
 
 export function writeBaseline(root, baselinePath, violations) {
   const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
-  const keys = [...new Set(violations.map(baselineKey))].sort();
+  const keys = baselineOccurrenceKeys(violations).sort();
   fs.writeFileSync(
     fullPath,
     `${JSON.stringify({ version: 1, note: 'Frozen ark-check violations. Only NEW violations fail --baseline runs. Regenerate with: ark-check --update-baseline', violations: keys }, null, 2)}\n`

package/bin/lib/write-path-detect.mjs

@@ -0,0 +1,138 @@
+/**
+ * W5 — Write-path capability surface for doctor (stable additive JSON).
+ * Extracted from agent-gates so install orchestration stays scannable.
+ *
+ * Detects whether installed agent gates expose:
+ *   - MCP prepare-write / validate_code (autoPatch) tools
+ *   - PreToolUse hook in reject-only vs repair mode (--hook-repair / ARK_HOOK_REPAIR)
+ *
+ * Never claims silent apply; "repair" means host can re-inject a patch after hard deny.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { arkCommand } from '../ark-shared.mjs';
+
+/**
+ * @returns {{
+ *   mode: 'repair' | 'reject-only' | 'mcp-only' | 'none',
+ *   prepareWrite: boolean,
+ *   autoPatch: boolean,
+ *   hookPresent: boolean,
+ *   hookRepair: boolean,
+ *   mcpPresent: boolean,
+ *   evidence: string[],
+ *   gap: null | { id: string, severity: string, message: string, fix: string },
+ * }}
+ */
+export function detectWritePathCapabilities(root) {
+  const evidence = [];
+  let hookPresent = false;
+  let hookRepair = false;
+
+  const hookFiles = [
+    '.claude/settings.json',
+    '.grok/hooks/ark-write-gate.json',
+  ];
+  for (const rel of hookFiles) {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs)) continue;
+    let text = '';
+    try {
+      text = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    // PreToolUse / write-gate command referencing ark(-gate)?-mcp --hook
+    if (
+      /--hook\b/.test(text) ||
+      /\b(ark|arkgate)-mcp\b[\s\S]{0,80}--hook\b/.test(text) ||
+      /\b--hook\b[\s\S]{0,80}\b(ark|arkgate)-mcp\b/.test(text)
+    ) {
+      hookPresent = true;
+      evidence.push(rel);
+    }
+    if (
+      /--hook-repair\b/.test(text) ||
+      /ARK_HOOK_REPAIR\s*=\s*['"]?(1|true|yes|on)/i.test(text)
+    ) {
+      hookRepair = true;
+      if (!evidence.includes(rel)) evidence.push(rel);
+    }
+  }
+
+  let mcpPresent = false;
+  const mcpFiles = ['.mcp.json', '.cursor/mcp.json', '.grok/config.toml'];
+  for (const rel of mcpFiles) {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs)) continue;
+    let text = '';
+    try {
+      text = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    if (
+      /\b(ark|arkgate)-mcp\b/.test(text) ||
+      /mcp_servers\.ark\b/.test(text) ||
+      /"ark"\s*:\s*\{/.test(text) ||
+      /mcpServers[\s\S]*\bark\b/.test(text)
+    ) {
+      mcpPresent = true;
+      evidence.push(rel);
+    }
+  }
+
+  // Package tools when MCP is wired: ark_prepare_write + validate_code(autoPatch).
+  // Hook repair emits machine-readable autoPatch without silent write.
+  const prepareWrite = mcpPresent;
+  const autoPatch = mcpPresent || hookRepair;
+
+  /** @type {'repair' | 'reject-only' | 'mcp-only' | 'none'} */
+  let mode = 'none';
+  if (hookPresent && hookRepair) mode = 'repair';
+  else if (hookPresent && !hookRepair) mode = 'reject-only';
+  else if (mcpPresent) mode = 'mcp-only';
+
+  let gap = null;
+  if (mode === 'none') {
+    gap = {
+      id: 'write-path-none',
+      severity: 'warn',
+      message:
+        'Write path is not installed — no PreToolUse hook and no Ark MCP. Agents write without architecture gate or prepare-write.',
+      fix: arkCommand(root, 'ark-check', '--install-agent-gates'),
+    };
+  } else if (mode === 'reject-only') {
+    gap = {
+      id: 'write-path-reject-only',
+      severity: 'info',
+      message: mcpPresent
+        ? 'PreToolUse hook is reject-only (hard block, no ARK_REPAIR_JSON). MCP still exposes prepare-write/autoPatch — enable --hook-repair so the write boundary itself can re-inject patches.'
+        : 'Write path is reject-only (hard block with prose; no repair payload). Enable --hook-repair or ARK_HOOK_REPAIR=1 so hosts can re-inject patches without full re-draft.',
+      fix: arkCommand(
+        root,
+        'ark-check',
+        '--install-agent-gates --tools claude,grok --force'
+      ),
+    };
+  } else if (mode === 'mcp-only') {
+    gap = {
+      id: 'write-path-mcp-only',
+      severity: 'info',
+      message:
+        'MCP exposes prepare-write / autoPatch tools, but no PreToolUse write hook is installed — enforcement is advisory unless the agent calls tools.',
+      fix: arkCommand(root, 'ark-check', '--install-agent-gates --tools claude,grok'),
+    };
+  }
+
+  return {
+    mode,
+    prepareWrite,
+    autoPatch,
+    hookPresent,
+    hookRepair,
+    mcpPresent,
+    evidence: [...new Set(evidence)],
+    gap,
+  };
+}