arkgate 4.8.23 → 4.8.25

package/bin/lib/orphan-modules.mjs

@@ -0,0 +1,251 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/orphanModules.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/orphan-modules.mjs). Zero Node I/O.
+ */
+
+const ARK_ORPHAN_MODULES_SCHEMA_VERSION = '1.0';
+/** Listed files per tier (agent-legible). The totals always carry the full count. */
+export const ORPHAN_LIST_CAP = 20;
+/** List cut when entry points were not recognised (ADR 0037 risk). */
+export const ORPHAN_UNRECOGNISED_LIST_CAP = 5;
+/** Share of governed files listed above which unrecognised entry points are assumed. */
+const UNRECOGNISED_SHARE = 0.25;
+/** A tiny tree with a few listed files is readable as is. */
+const UNRECOGNISED_MIN_FILES = 5;
+const TEST_ONLY_SAMPLE = 5;
+export const ORPHAN_MODULE_NEXT = 'Delete it through the write gate, or add it to .ark/entry-points.json if a framework loads it.';
+export const UNUSED_EXPORTS_COMMAND = 'arkgate-check --doctor --all';
+const CERTAINTY_ORDER = {
+    'no-importer': 0,
+    'maybe-unresolved': 1,
+    'maybe-dynamic': 2,
+};
+function byPath(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/** Last path segment without its extensions (`a/b/foo.test.ts` → `foo`). */
+export function moduleStem(rel) {
+    const segments = String(rel).replace(/\\/g, '/').split('/');
+    const last = segments[segments.length - 1] ?? '';
+    const dot = last.indexOf('.');
+    return dot > 0 ? last.slice(0, dot) : last;
+}
+function stemsFor(rel) {
+    const stem = moduleStem(rel);
+    if (stem !== 'index')
+        return [stem];
+    const segments = rel.split('/');
+    return segments.length > 1 ? [stem, segments[segments.length - 2] ?? stem] : [stem];
+}
+/** One human line per listed file. Shared by the terminal and the report. */
+export function orphanModuleLine(item) {
+    if (item.certainty === 'maybe-dynamic') {
+        const why = item.evidence[0] ?? 'a dynamic import may load it';
+        return `No static import reaches ${item.path}, but ${why}. It may still be loaded.`;
+    }
+    if (item.certainty === 'maybe-unresolved') {
+        return `Nothing imports ${item.path}, but an import that could not be followed has the same name. It may still be used.`;
+    }
+    return `Nothing imports ${item.path}, and no entry point covers it.`;
+}
+function unrecognisedFlood(listed, governed, frameworks) {
+    return (frameworks.length === 0 &&
+        listed >= UNRECOGNISED_MIN_FILES &&
+        governed > 0 &&
+        listed / governed > UNRECOGNISED_SHARE);
+}
+/**
+ * Tier 1: governed files with zero importers that no entry covers.
+ * Test-only and outside-only files are counted, never listed.
+ */
+export function findOrphanModules(input) {
+    const files = [...input.files];
+    const count = (index) => Number(input.importerCount[index] ?? 0) || 0;
+    let imported = 0;
+    let entries = 0;
+    const testOnly = [];
+    let outsideOnly = 0;
+    const listed = [];
+    for (let index = 0; index < files.length; index += 1) {
+        const path = files[index];
+        if (count(index) > 0) {
+            imported += 1;
+            continue;
+        }
+        if (input.entries.has(path)) {
+            entries += 1;
+            continue;
+        }
+        if ((input.testImporters.get(path) ?? 0) > 0) {
+            testOnly.push(path);
+            continue;
+        }
+        if ((input.outsideImporters.get(path) ?? 0) > 0) {
+            outsideOnly += 1;
+            continue;
+        }
+        const annotations = [...(input.annotations?.get(path) ?? [])];
+        const reach = input.dynamicReach.get(path);
+        if (reach) {
+            listed.push({
+                ruleId: 'ORPHAN_MODULE',
+                path,
+                certainty: 'maybe-dynamic',
+                evidence: [reach, ...annotations],
+            });
+            continue;
+        }
+        if (stemsFor(path).some((stem) => input.unresolvedStems.has(stem))) {
+            listed.push({
+                ruleId: 'ORPHAN_MODULE',
+                path,
+                certainty: 'maybe-unresolved',
+                evidence: ['an import that could not be followed has the same name', ...annotations],
+            });
+            continue;
+        }
+        listed.push({
+            ruleId: 'ORPHAN_MODULE',
+            path,
+            certainty: 'no-importer',
+            evidence: ['no governed file, test or project script imports it', ...annotations],
+        });
+    }
+    listed.sort((left, right) => CERTAINTY_ORDER[left.certainty] - CERTAINTY_ORDER[right.certainty] || byPath(left.path, right.path));
+    testOnly.sort(byPath);
+    const maybeDynamic = listed.filter((item) => item.certainty === 'maybe-dynamic').length;
+    const maybeUnresolved = listed.filter((item) => item.certainty === 'maybe-unresolved').length;
+    const honesty = [...input.partialReasons];
+    const flood = unrecognisedFlood(listed.length, files.length, input.frameworks);
+    if (flood) {
+        honesty.unshift(`${listed.length} of ${files.length} governed files have no importer and no framework was recognised. Entry points were probably not recognised, so the list may be wrong.`);
+    }
+    const partial = honesty.length > 0 || maybeDynamic > 0 || maybeUnresolved > 0;
+    const cap = flood ? ORPHAN_UNRECOGNISED_LIST_CAP : ORPHAN_LIST_CAP;
+    const shown = listed.slice(0, cap);
+    const headline = listed.length === 0
+        ? partial
+            ? 'No file without an importer was found, but some imports could not be followed.'
+            : 'Every governed file has an importer or an entry point.'
+        : flood
+            ? 'Entry points not recognised. The list of files nothing imports may be wrong.'
+            : `${listed.length} governed file${listed.length === 1 ? '' : 's'} nothing imports.`;
+    return {
+        schemaVersion: ARK_ORPHAN_MODULES_SCHEMA_VERSION,
+        advisory: true,
+        notAScore: true,
+        status: partial ? 'partial' : 'complete',
+        headline,
+        orphans: shown,
+        truncated: listed.length - shown.length,
+        testOnly: { count: testOnly.length, sample: testOnly.slice(0, TEST_ONLY_SAMPLE) },
+        totals: {
+            governed: files.length,
+            entries,
+            imported,
+            testOnly: testOnly.length,
+            outsideOnly,
+            listed: listed.length,
+            maybeDynamic,
+            maybeUnresolved,
+        },
+        entryEvidence: {
+            bySource: sortedRecord(input.entryEvidence.bySource),
+            unmapped: input.entryEvidence.unmapped,
+        },
+        frameworks: [...input.frameworks].sort(byPath),
+        honesty: [...honesty, ...(input.notes ?? [])],
+        ...(listed.length > 0 ? { next: ORPHAN_MODULE_NEXT } : {}),
+    };
+}
+function sortedRecord(record) {
+    const out = {};
+    for (const key of Object.keys(record).sort(byPath))
+        out[key] = record[key];
+    return out;
+}
+/** Doctor without an importer index (no TypeScript, or a caller without facts). */
+export function unavailableOrphanModules(reason) {
+    return {
+        schemaVersion: ARK_ORPHAN_MODULES_SCHEMA_VERSION,
+        advisory: true,
+        notAScore: true,
+        status: 'unavailable',
+        headline: 'Files nothing imports were not checked.',
+        orphans: [],
+        truncated: 0,
+        testOnly: { count: 0, sample: [] },
+        totals: {
+            governed: 0,
+            entries: 0,
+            imported: 0,
+            testOnly: 0,
+            outsideOnly: 0,
+            listed: 0,
+            maybeDynamic: 0,
+            maybeUnresolved: 0,
+        },
+        entryEvidence: { bySource: {}, unmapped: 0 },
+        frameworks: [],
+        honesty: [reason],
+    };
+}
+/** Tier 2 in the compact view: named, not run. */
+export function deferredUnusedExports() {
+    return {
+        schemaVersion: ARK_ORPHAN_MODULES_SCHEMA_VERSION,
+        notAScore: true,
+        status: 'deferred',
+        files: [],
+        truncated: 0,
+        totals: { filesChecked: 0, filesSkipped: 0, unusedExports: 0 },
+        honesty: ['Unused exports are listed in the details view only.'],
+        next: UNUSED_EXPORTS_COMMAND,
+    };
+}
+/**
+ * Tier 2: exports no governed file or test imports by name.
+ * Entry files are exempt. A file with no named use at all is tier 1, not here.
+ */
+export function findUnusedExports(input) {
+    const rows = [];
+    let filesChecked = 0;
+    let filesSkipped = 0;
+    const paths = [...input.exportsByFile.keys()].sort(byPath);
+    for (const path of paths) {
+        const exported = input.exportsByFile.get(path);
+        const used = input.namedUse.get(path);
+        if (input.entries.has(path) || used === undefined || used === '*' || exported == null) {
+            filesSkipped += 1;
+            continue;
+        }
+        filesChecked += 1;
+        const unused = [...new Set(exported)].filter((name) => !used.has(name)).sort(byPath);
+        if (unused.length > 0)
+            rows.push({ ruleId: 'UNUSED_EXPORT', path, exports: unused });
+    }
+    const shown = rows.slice(0, ORPHAN_LIST_CAP);
+    return {
+        schemaVersion: ARK_ORPHAN_MODULES_SCHEMA_VERSION,
+        notAScore: true,
+        status: input.partialReasons.length > 0 ? 'partial' : 'complete',
+        files: shown,
+        truncated: rows.length - shown.length,
+        totals: {
+            filesChecked,
+            filesSkipped,
+            unusedExports: rows.reduce((sum, row) => sum + row.exports.length, 0),
+        },
+        honesty: [...input.partialReasons],
+    };
+}
+/** One human line per file with unused exports. */
+export function unusedExportLine(row) {
+    const names = row.exports.join(', ');
+    return `${row.path} exports ${names}, and nothing imports ${row.exports.length === 1 ? 'it' : 'them'} by name.`;
+}

package/bin/lib/outside-importers.mjs

@@ -0,0 +1,197 @@
+/**
+ * Importers that live outside the governed graph — Tooling.
+ *
+ * Shared by files nothing imports (ADR 0037), which counts test and outside
+ * importers, and the invariant mutation probe (ADR 0039), which needs the
+ * test files that import a symbol file to pick covering tests. One walk, one
+ * test classifier, one lexical resolver, so the two never disagree on which
+ * test imports what.
+ *
+ * Bounded: at most 5000 non-governed files of 256 KB each, depth 8.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { namedModuleBindings } from './ast-scan.mjs';
+import { probeGoverned } from './entry-points-io.mjs';
+import { readTsconfigAliases, resolveSpecifierToRel } from './import-resolve.mjs';
+import { coverageOptionsFromConfig, matchSimpleGlob } from './invariant-coverage-io.mjs';
+
+export const MAX_EXTERNAL_IMPORTER_FILES = 5000;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_WALK_DEPTH = 8;
+const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
+const DECLARATION_FILE = /\.d\.[cm]?ts$/;
+const TEST_FILE = /\.(?:test|spec)(?:-d)?\.[cm]?[jt]sx?$|(?:^|\/)(?:tests?|__tests__|__mocks__|e2e)\//i;
+/** Data trees and build output: never importers of product source. */
+const SKIP_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  'fixture',
+  'fixtures',
+  '__fixtures__',
+  'testdata',
+  'docs',
+  'documentation',
+]);
+
+export function readSource(absolute) {
+  try {
+    const stat = fs.statSync(absolute);
+    if (!stat.isFile()) return { skip: true };
+    if (stat.size > MAX_FILE_BYTES) return { oversize: true };
+    return { text: fs.readFileSync(absolute, 'utf8') };
+  } catch {
+    return { skip: true };
+  }
+}
+
+export function dirOf(rel) {
+  const at = rel.lastIndexOf('/');
+  return at === -1 ? '' : rel.slice(0, at);
+}
+
+export function stripExt(rel) {
+  return rel.replace(DECLARATION_FILE, '').replace(SOURCE_FILE, '');
+}
+
+/** The default test-path heuristic plus the project's `coverage.testGlobs`. */
+export function testPathMatcher(config) {
+  const testGlobs = coverageOptionsFromConfig(config).testGlobs ?? [];
+  return (rel) => TEST_FILE.test(rel) || testGlobs.some((glob) => matchSimpleGlob(glob, rel));
+}
+
+/** Non-governed project files (tests and other source), sorted, bounded. */
+export function walkExternalSources(root, governed) {
+  const files = [];
+  let capped = 0;
+  const visit = (dirRel, depth) => {
+    if (depth > MAX_WALK_DEPTH) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dirRel ? path.join(root, dirRel) : root, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const rel = dirRel ? `${dirRel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) visit(rel, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || !SOURCE_FILE.test(entry.name) || DECLARATION_FILE.test(entry.name)) continue;
+      if (governed.has(rel)) continue;
+      if (files.length >= MAX_EXTERNAL_IMPORTER_FILES) capped += 1;
+      else files.push(rel);
+    }
+  };
+  visit('', 0);
+  return { files, capped };
+}
+
+/** Module specifiers of a file. With bindings, named imports keep their names. */
+export function fileImports(ts, rel, text, withBindings) {
+  const imports = [];
+  // Static declarations per specifier. preProcessFile also lists dynamic
+  // import() / require() sites: any occurrence past the static ones uses the
+  // whole module, so it counts as '*'.
+  const statics = new Map();
+  if (withBindings) {
+    const sourceFile = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, false);
+    for (const statement of sourceFile.statements) {
+      const specifier = statement.moduleSpecifier;
+      if (!specifier || !ts.isStringLiteralLike(specifier)) continue;
+      if (!ts.isImportDeclaration(statement) && !ts.isExportDeclaration(statement)) continue;
+      imports.push({ specifier: specifier.text, names: namedModuleBindings(ts, statement) ?? '*' });
+      statics.set(specifier.text, (statics.get(specifier.text) ?? 0) + 1);
+    }
+  }
+  const pre = ts.preProcessFile(text, true, true);
+  for (const item of [...pre.importedFiles, ...pre.referencedFiles]) {
+    const left = statics.get(item.fileName) ?? 0;
+    if (left > 0) statics.set(item.fileName, left - 1);
+    else imports.push({ specifier: item.fileName, names: '*' });
+  }
+  return imports;
+}
+
+/**
+ * Relative and tsconfig-alias specifiers → a governed file (same lexical
+ * resolver as the flat-parent graph and the write hook). Bare packages are
+ * never project files.
+ */
+export function createResolver(ts, root, governed) {
+  const aliases = readTsconfigAliases(ts, root);
+  const memo = new Map();
+  return (specifier, fromRel) => {
+    const key = `${dirOf(fromRel)}\0${specifier}`;
+    if (memo.has(key)) return memo.get(key);
+    let hit = null;
+    try {
+      const rel = resolveSpecifierToRel(specifier, fromRel, root, aliases);
+      hit = rel ? (governed.has(rel) ? rel : probeGoverned(stripExt(rel), governed)) : null;
+    } catch {
+      hit = null;
+    }
+    memo.set(key, hit);
+    return hit;
+  };
+}
+
+/** Governed files a barrel re-exports from (`export … from`), resolved. */
+function reExportTargets(ts, root, rel, resolve) {
+  const read = readSource(path.join(root, rel));
+  if (read.text == null) return [];
+  const sourceFile = ts.createSourceFile(rel, read.text, ts.ScriptTarget.Latest, false);
+  const out = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts.isExportDeclaration(statement)) continue;
+    const specifier = statement.moduleSpecifier;
+    if (!specifier || !ts.isStringLiteralLike(specifier)) continue;
+    const target = resolve(specifier.text, rel);
+    if (target) out.push(target);
+  }
+  return out;
+}
+
+/**
+ * Test files that import each target directly, or through one re-exporting
+ * barrel. Same walk, test classifier and resolver as the files-nothing-imports
+ * pass. Returns target → sorted test paths (targets nothing imports map to []).
+ *
+ * @param {{ root: string, ts: object, config?: object, governed: Set<string>, targets: string[] }} input
+ * @returns {{ byTarget: Map<string, string[]>, capped: number }}
+ */
+export function testImportersOf({ root, ts, config, governed, targets }) {
+  const byTarget = new Map(targets.map((target) => [target, new Set()]));
+  if (!ts || typeof ts.preProcessFile !== 'function' || targets.length === 0) {
+    return { byTarget: new Map(targets.map((target) => [target, []])), capped: 0 };
+  }
+  const isTest = testPathMatcher(config);
+  const resolve = createResolver(ts, root, governed);
+  const barrels = new Map();
+  const { files, capped } = walkExternalSources(root, governed);
+  for (const rel of files) {
+    if (!isTest(rel)) continue;
+    const read = readSource(path.join(root, rel));
+    if (read.text == null) continue;
+    for (const { specifier } of fileImports(ts, rel, read.text, false)) {
+      const hit = resolve(specifier, rel);
+      if (!hit) continue;
+      if (byTarget.has(hit)) {
+        byTarget.get(hit).add(rel);
+        continue;
+      }
+      if (!barrels.has(hit)) barrels.set(hit, reExportTargets(ts, root, hit, resolve));
+      for (const target of barrels.get(hit)) byTarget.get(target)?.add(rel);
+    }
+  }
+  return {
+    byTarget: new Map([...byTarget].map(([target, tests]) => [target, [...tests].sort()])),
+    capped,
+  };
+}

package/bin/lib/package-manager.mjs

@@ -83,9 +83,66 @@ const RUNNER_BY_PM = { pnpm: PNPM_EXEC, yarn: 'yarn', npm: 'npx' };
  * same detection.
  */
 export function execRunner(root) {
+  if (!arkgateIsProjectDependency(root)) return pinnedArkgateRunner();
   return RUNNER_BY_PM[detectPackageManager(root)];
 }
 
+/** The exact arkgate version that ships this CLI (the package.json next to bin/). */
+function shippedArkgateVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+    return typeof pkg.version === 'string' && pkg.version ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when the project resolves arkgate locally: a `dependencies` / `devDependencies` entry,
+ * an installed node_modules/arkgate, or the arkgate package itself (self-host). Only then
+ * does a bare `npx ark-check` / `pnpm exec` / `yarn` runner reach this package's bins.
+ */
+export function arkgateIsProjectDependency(root) {
+  // An installed copy (node_modules/arkgate) also resolves the local runner.
+  if (fs.existsSync(path.join(root, 'node_modules', 'arkgate', 'package.json'))) return true;
+  const pkg = readPackageJson(root);
+  if (!pkg || typeof pkg !== 'object') return false;
+  if (pkg.name === 'arkgate') return true;
+  return [pkg.dependencies, pkg.devDependencies].some(
+    (deps) => deps && typeof deps === 'object' && typeof deps.arkgate === 'string'
+  );
+}
+
+/** `arkgate@<exact shipped version>` — the package an unpinned project runs through npx. */
+function pinnedArkgateSpec(version = shippedArkgateVersion()) {
+  return version ? `arkgate@${version}` : 'arkgate';
+}
+
+/**
+ * Runner for a project that does not pin arkgate. Bare `npx ark-check` asks npm for a
+ * package named `ark-check` (404) or runs a stale global copy; `-p arkgate@<exact>` names the
+ * package that owns the bin, and `-y` keeps CI and host hooks from blocking on a prompt.
+ */
+export function pinnedArkgateRunner(version) {
+  return `npx -y -p ${pinnedArkgateSpec(version)}`;
+}
+
+/**
+ * Number of npx arguments before the bin: 0 for `npx <bin>`, more for the pinned form
+ * (`npx -y -p arkgate@x <bin>`, `--yes`, `--package arkgate@x`, `--package=arkgate@x`).
+ */
+export function npxArkgatePrefixLength(args) {
+  if (!Array.isArray(args)) return 0;
+  let index = 0;
+  if (args[index] === '-y' || args[index] === '--yes') index += 1;
+  const flag = args[index];
+  if ((flag === '-p' || flag === '--package') && /^arkgate(?:@\S+)?$/.test(args[index + 1] ?? '')) {
+    return index + 2;
+  }
+  if (typeof flag === 'string' && /^--package=arkgate(?:@\S+)?$/.test(flag)) return index + 1;
+  return 0;
+}
+
 /** Full runnable command string for an installed Ark binary, package-manager aware. */
 export function arkCommand(root, bin, argsStr = '') {
   return `${execRunner(root)} ${bin}${argsStr ? ` ${argsStr}` : ''}`;
@@ -116,7 +173,8 @@ export function execCommandParts(root, bin, binArgs = []) {
     };
   }
   if (runner === 'yarn') return { command: 'yarn', args: [bin, ...binArgs] };
-  return { command: 'npx', args: [bin, ...binArgs] };
+  // Pinned form (`npx -y -p arkgate@x`) keeps its prefix as real argv entries.
+  return { command: 'npx', args: [...runner.split(' ').slice(1), bin, ...binArgs] };
 }
 
 /**
@@ -141,7 +199,7 @@ export function isNpmYarnWorkspaceRoot(root) {
  * Normalize a version/range/spec into an installable package argument for arkgate.
  * Accepts `latest`, `^3.8.2`, `arkgate@latest`, or a full package name.
  */
-export function normalizeArkgateInstallSpec(versionSpec) {
+function normalizeArkgateInstallSpec(versionSpec) {
   const raw = typeof versionSpec === 'string' && versionSpec.trim() ? versionSpec.trim() : 'latest';
   if (raw.startsWith('arkgate@') || raw === 'arkgate') return raw === 'arkgate' ? 'arkgate@latest' : raw;
   if (raw.includes('/') || raw.startsWith('file:') || raw.startsWith('link:')) return raw;

package/bin/lib/parse-health.mjs

@@ -4,7 +4,7 @@
  * governed files to a partial analysis verdict.
  */
 
-export const PARSE_HEALTH_FILE_CAP = 12;
+const PARSE_HEALTH_FILE_CAP = 12;
 
 function unavailableParseHealth(scannedFiles = 0) {
   return {

package/bin/lib/passthrough-commands.mjs

@@ -0,0 +1,83 @@
+/**
+ * Subcommands of `arkgate` / `ark` that hand their own flags to a sibling bin untouched:
+ * `dashboard` (bin/ark-dashboard.mjs) and `mcp` (bin/ark-mcp.mjs).
+ *
+ * `mcp` exists because `npx arkgate@<version> <args>` always runs the bin named after the
+ * package (`arkgate`), never `arkgate-mcp`. The MCP Registry descriptor (`server.json`) is
+ * launched exactly that way, so `arkgate mcp --root .` must start the stdio MCP server.
+ * `arkgate-mcp` / `ark-mcp` are also accepted as the first argument, so a descriptor or host
+ * config that spells the bin name still reaches the server. That does not repair registry
+ * entries already published: each pins the arkgate version it was published with, and
+ * versions through 4.8.23 have no passthrough. Only a republished descriptor fixes those.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const arkDashboard = path.join(here, '..', 'ark-dashboard.mjs');
+const arkMcp = path.join(here, '..', 'ark-mcp.mjs');
+
+/** First positional arguments that start the MCP server (stdio JSON-RPC). */
+export const MCP_COMMANDS = Object.freeze(['mcp', 'arkgate-mcp', 'ark-mcp']);
+
+/** First positional arguments whose remaining argv belongs to another executable. */
+export function isPassthroughCommand(command) {
+  return command === 'dashboard' || command === 'report' || MCP_COMMANDS.includes(command);
+}
+
+export function isMcpCommand(command) {
+  return MCP_COMMANDS.includes(command);
+}
+
+export { DASHBOARD_HELP as dashboardHelp } from './dashboard-cli.mjs';
+
+export function withDashboardHelp(text, detailed) {
+  const extra = detailed
+    ? '  arkgate dashboard [--url <inspector-url>] [--interval <ms>] [--once]\n  arkgate mcp [--root <project>] [--config <path>]\n  arkgate report  [--root <project>] [--json] [--title <text>] [--finding <ref>] [--submit] [--i-confirm-submit]\n'
+    : '';
+  const extraDesc = detailed
+    ? '  dashboard  ANSI observability TUI (spawns ark-dashboard).\n  mcp        Stdio MCP server (same as arkgate-mcp; used by npx and the MCP Registry).\n  report     Draft an upstream GitHub issue for pedroknigge/arkgate. Create needs --submit plus confirm. --yes does not submit.\n'
+    : '';
+  if (detailed) {
+    return text
+      .replace('  arkgate agents-md [--root', `${extra}  arkgate agents-md [--root`)
+      .replace('  agents-md Version-matched', `${extraDesc}  agents-md Version-matched`);
+  }
+  return text.replace(
+    '  arkgate-check --doctor     status — one next step\n',
+    '  arkgate-check --doctor     status — one next step\n  arkgate dashboard         observability TUI (inspector)\n  arkgate report            draft an upstream GitHub issue\n'
+  );
+}
+
+export function runDashboard(passthroughArgs) {
+  const result = spawnSync(process.execPath, [arkDashboard, ...passthroughArgs], {
+    stdio: 'inherit',
+    encoding: 'utf8',
+  });
+  return result.status ?? 1;
+}
+
+/**
+ * Run bin/ark-mcp.mjs with the caller's stdio. Nothing is written to stdout here: stdout is
+ * the JSON-RPC channel. Termination signals are forwarded so the host can stop the server.
+ */
+export function runMcp(passthroughArgs) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [arkMcp, ...passthroughArgs], { stdio: 'inherit' });
+    const forward = (signal) => {
+      if (child.exitCode === null) child.kill(signal);
+    };
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    for (const signal of signals) process.on(signal, forward);
+    const done = (code) => {
+      for (const signal of signals) process.off(signal, forward);
+      resolve(code);
+    };
+    child.on('error', (error) => {
+      process.stderr.write(`arkgate mcp: ${error.message}\n`);
+      done(1);
+    });
+    child.on('exit', (code, signal) => done(code ?? (signal ? 1 : 0)));
+  });
+}