arkgate 4.6.6 → 4.7.0

package/bin/ark-mcp-runtime.mjs

@@ -76,6 +76,13 @@ import { detectWritePathCapabilities } from './lib/write-path-detect.mjs';
 import { collectGovernedFiles, isGovernableSourceFile } from './lib/scan-files.mjs';
 import { classifyChangeSet, evaluateTeamGate } from './lib/team-parliament.mjs';
 import { contractSessionFrom } from './lib/team-parliament-io.mjs';
+import {
+  normalizeHookPayload,
+  codexPatchWrites,
+  proposedSource,
+  emitHostAllow,
+  formatWriteGateDeny,
+} from './lib/mcp-hook-payload.mjs';
 import {
   canonicalizeCandidateChanges,
   resolvedCompilerInputPaths,
@@ -293,269 +300,48 @@ function isResolvedAnalysisInput(relativePath, args, compilerInputs = new Set())
   return /(?:^|\/)configs?\/[^/]+\.jsonc?$/i.test(relative);
 }
 
-/**
- * Map Google Antigravity write tools (PascalCase args) onto Claude Write/Edit/MultiEdit.
- * @returns {{ toolName: string, toolInput: object }|null}
- */
-function mapAntigravityToolCall(toolCall) {
-  if (!toolCall || typeof toolCall !== 'object') return null;
-  const name = toolCall.name ?? '';
-  const args = toolCall.args && typeof toolCall.args === 'object' ? toolCall.args : {};
-  const filePath = args.TargetFile ?? args.targetFile ?? args.file_path ?? args.path;
-  if (name === 'write_to_file') {
-    return {
-      toolName: 'Write',
-      toolInput: {
-        file_path: filePath,
-        content: args.CodeContent ?? args.codeContent ?? args.content ?? '',
-      },
-      operation: 'write_to_file',
-    };
-  }
-  if (name === 'replace_file_content') {
-    return {
-      toolName: 'Edit',
-      toolInput: {
-        file_path: filePath,
-        old_string: args.TargetContent ?? args.targetContent ?? args.old_string ?? '',
-        new_string: args.ReplacementContent ?? args.replacementContent ?? args.new_string ?? '',
-        replace_all: Boolean(args.AllowMultiple ?? args.allowMultiple),
-      },
-      operation: 'replace_file_content',
-    };
-  }
-  if (name === 'multi_replace_file_content') {
-    const chunks = Array.isArray(args.ReplacementChunks)
-      ? args.ReplacementChunks
-      : Array.isArray(args.replacementChunks)
-        ? args.replacementChunks
-        : [];
-    return {
-      toolName: 'MultiEdit',
-      toolInput: {
-        file_path: filePath,
-        edits: chunks.map((chunk) => ({
-          old_string: chunk?.TargetContent ?? chunk?.targetContent ?? chunk?.old_string ?? '',
-          new_string:
-            chunk?.ReplacementContent ?? chunk?.replacementContent ?? chunk?.new_string ?? '',
-          replace_all: Boolean(chunk?.AllowMultiple ?? chunk?.allowMultiple),
-        })),
-      },
-      operation: 'multi_replace_file_content',
-    };
-  }
-  return {
-    toolName: name,
-    toolInput: { ...args, file_path: filePath },
-    operation: name,
-  };
+function hookEnforcement(root, host, operation, completePatch = false) {
+  return detectWritePathCapabilities(root, host, {
+    boundary: 'pre-tool',
+    operation,
+    completePatch,
+  }).enforcementLadder;
 }
 
-/**
- * Normalize agent PreToolUse payloads.
- * Claude Code: { tool_name, tool_input: { file_path, content | old_string/new_string } }
- * Grok Build:  { toolName, toolInput:  { file_path, content | old_string/new_string } }
- *              (aliases Write/Edit/MultiEdit → write/search_replace; matcher keeps both)
- * Antigravity: { toolCall: { name, args: { TargetFile, CodeContent, … } } }
- * Cursor:      { tool_name, tool_input, hook_event_name?, workspace_roots? }
- *              Write uses `contents`; StrReplace maps to Edit (path/old_string/new_string).
- * Codex:       { tool_name: "apply_patch", tool_input: { command: "*** Begin Patch..." } }
- */
-function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_HOOK_EVENT)) {
-  const antigravityStyle =
-    payload != null && typeof payload === 'object' && 'toolCall' in payload;
-  if (antigravityStyle) {
-    const mapped = mapAntigravityToolCall(payload.toolCall);
-    const filePath =
-      mapped?.toolInput?.file_path ??
-      mapped?.toolInput?.filePath ??
-      mapped?.toolInput?.path ??
-      mapped?.toolInput?.target_file;
-    return {
-      toolName: mapped?.toolName ?? '',
-      toolInput: { ...(mapped?.toolInput ?? {}), file_path: filePath },
-      grokStyle: true, // decision JSON on stdout (deny)
-      antigravityStyle: true,
-      cursorStyle: false,
-      operation: mapped?.operation ?? mapped?.toolName ?? null,
-    };
+function extraMergeTeethClassification(root, config) {
+  const files = collectGovernedFiles(root, config);
+  const layers = config.layers ?? [];
+  let classified = 0;
+  const populated = new Set();
+  for (const abs of files) {
+    const layer = layerForFile(root, abs, layers);
+    if (layer) {
+      classified += 1;
+      populated.add(layer);
+    }
   }
-
-  const rawName = payload?.tool_name ?? payload?.toolName ?? '';
-  const toolInputRaw = payload?.tool_input ?? payload?.toolInput ?? {};
-  const toolInput =
-    toolInputRaw && typeof toolInputRaw === 'object' ? { ...toolInputRaw } : {};
-  // Cursor Write uses `contents`; Claude/Grok use `content`.
-  if (toolInput.content == null && typeof toolInput.contents === 'string') {
-    toolInput.content = toolInput.contents;
-  }
-  const nameMap = {
-    Write: 'Write',
-    write: 'Write',
-    Edit: 'Edit',
-    search_replace: 'Edit',
-    StrReplace: 'Edit',
-    MultiEdit: 'MultiEdit',
-    ApplyPatch: 'ApplyPatch',
-    apply_patch: 'ApplyPatch',
-    write_to_file: 'Write',
-    replace_file_content: 'Edit',
-    multi_replace_file_content: 'MultiEdit',
-  };
-  const toolName = nameMap[rawName] ?? rawName;
-  const filePath =
-    toolInput.file_path ?? toolInput.filePath ?? toolInput.path ?? toolInput.target_file;
-  const cursorStyle =
-    Boolean(process.env.CURSOR_PROJECT_DIR) ||
-    Boolean(process.env.CURSOR_VERSION) ||
-    (payload != null &&
-      typeof payload === 'object' &&
-      (payload.hook_event_name === 'preToolUse' ||
-        Array.isArray(payload.workspace_roots) ||
-        rawName === 'StrReplace' ||
-        (rawName === 'Write' && typeof toolInputRaw?.contents === 'string')));
   return {
-    toolName,
-    toolInput: { ...toolInput, file_path: filePath },
-    // Grok-style camelCase (or GROK_HOOK_EVENT) → also emit deny JSON on stdout.
-    grokStyle:
-      grokHookEvent ||
-      (payload != null && typeof payload === 'object' && 'toolName' in payload),
-    antigravityStyle: false,
-    cursorStyle,
-    operation: rawName === 'StrReplace' ? 'StrReplace' : null,
+    governedPercent: files.length > 0 ? Math.round((classified / files.length) * 100) : 0,
+    populatedLayerCount: populated.size,
   };
 }
 
-function applyCodexUpdatePatch(current, lines) {
-  let source = current.split('\n');
-  let cursor = 0;
-  const hunks = [];
-  let hunk = null;
-  for (const line of lines) {
-    if (line.startsWith('@@')) {
-      if (hunk) hunks.push(hunk);
-      hunk = { anchor: line.slice(2).trim(), entries: [] };
-    } else if (/^[ +\-]/.test(line)) {
-      if (!hunk) return null;
-      hunk.entries.push(line);
-    }
-  }
-  if (hunk) hunks.push(hunk);
-  for (const { anchor, entries } of hunks) {
-    if (anchor) {
-      const anchorAt = source.findIndex((line, index) => index >= cursor && line === anchor);
-      if (anchorAt < 0) return null;
-      cursor = anchorAt + 1;
-    }
-    const oldLines = entries.filter((line) => !line.startsWith('+')).map((line) => line.slice(1));
-    const newLines = entries.filter((line) => !line.startsWith('-')).map((line) => line.slice(1));
-    let found = -1;
-    for (let at = cursor; at <= source.length - oldLines.length; at += 1) {
-      if (oldLines.every((line, index) => source[at + index] === line)) {
-        found = at;
-        break;
-      }
-    }
-    if (found < 0) return null;
-    source.splice(found, oldLines.length, ...newLines);
-    cursor = found + newLines.length;
-  }
-  return source.join('\n');
-}
-
-function codexPatchWrites(patch, root) {
-  if (typeof patch !== 'string') {
-    return { writes: [], complete: false };
-  }
-  const lines = patch.split('\n');
-  const begin = lines.indexOf('*** Begin Patch');
-  const end = lines.indexOf('*** End Patch', begin + 1);
-  if (begin < 0 || end <= begin) return { writes: [], complete: false };
-  const writes = [];
-  const seenPaths = new Set();
-  let complete = [
-    ...lines.slice(0, begin),
-    ...lines.slice(end + 1),
-  ].every((line) => line.trim() === '');
-  let sawFileDirective = false;
-  for (let index = begin + 1; index < end; index += 1) {
-    const match = lines[index].match(/^\*\*\* (Add|Update|Delete) File: (.+)$/);
-    if (!match) {
-      if (lines[index].trim() !== '') complete = false;
-      continue;
-    }
-    sawFileDirective = true;
-    const [, action, relativePath] = match;
-    const body = [];
-    for (index += 1; index < end && !lines[index].startsWith('*** '); index += 1) {
-      body.push(lines[index]);
-    }
-    index -= 1;
-    const filePath = path.resolve(root, relativePath);
-    const rel = path.relative(root, filePath);
-    if (
-      seenPaths.has(filePath) ||
-      rel.startsWith(`..${path.sep}`) ||
-      rel === '..' ||
-      path.isAbsolute(rel)
-    ) {
-      complete = false;
-      continue;
-    }
-    seenPaths.add(filePath);
-    const canonicalRelativePath = rel.split(path.sep).join('/');
-    if (action === 'Delete') {
-      if (body.some((line) => line.trim() !== '') || !fs.existsSync(filePath)) {
-        complete = false;
-        continue;
-      }
-      writes.push({ path: canonicalRelativePath, filePath, delete: true });
-      continue;
-    }
-    let content;
-    if (action === 'Add') {
-      if (
-        body.length === 0 ||
-        fs.existsSync(filePath) ||
-        body.some((line) => !line.startsWith('+'))
-      ) {
-        complete = false;
-        continue;
-      }
-      content = body.filter((line) => line.startsWith('+')).map((line) => line.slice(1)).join('\n');
-      if (body.some((line) => line.startsWith('+'))) content += '\n';
-    } else {
-      if (
-        !body.some((line) => line.startsWith('@@')) ||
-        body.some((line) => !line.startsWith('@@') && !/^[ +\-]/.test(line))
-      ) {
-        complete = false;
-        continue;
-      }
-      let current;
-      try {
-        current = fs.readFileSync(filePath, 'utf8');
-      } catch {
-        complete = false;
-        continue;
-      }
-      content = applyCodexUpdatePatch(current, body);
-      if (content === null) complete = false;
-    }
-    if (typeof content === 'string') {
-      writes.push({ path: canonicalRelativePath, filePath, content });
-    }
-  }
-  return { writes, complete: complete && sawFileDirective };
-}
-
-function hookEnforcement(root, host, operation, completePatch = false) {
-  return detectWritePathCapabilities(root, host, {
-    boundary: 'pre-tool',
-    operation,
-    completePatch,
-  }).enforcementLadder;
+function arkRunSnippetContext({ root, config, filePath, layer, relFile, classification }) {
+  const extra = config?.arkRun;
+  if (!extra) return { layer, filePath };
+  const relative =
+    relFile ||
+    (typeof filePath === 'string'
+      ? path.relative(root, path.resolve(root, filePath)).split(path.sep).join('/')
+      : undefined);
+  return {
+    layer,
+    filePath,
+    relFile: relative,
+    arkRun: extra,
+    layers: config.layers ?? [],
+    classification: classification ?? extraMergeTeethClassification(root, config),
+  };
 }
 
 function designDeltaViolations(delta) {
@@ -571,36 +357,6 @@ function designDeltaViolations(delta) {
   }));
 }
 
-/**
- * Compute the file content a Write/Edit/MultiEdit is about to produce. Edits are applied
- * to the CURRENT on-disk file so the gate judges the real post-edit state, not the edit
- * snippet out of context. Replacement uses a function argument so `$&`-style sequences in
- * generated code are inserted literally, never interpreted as replacement patterns.
- */
-function proposedSource(toolName, toolInput) {
-  if (toolName === 'Write') return toolInput.content ?? toolInput.contents;
-
-  let text = '';
-  try {
-    text = fs.readFileSync(toolInput.file_path, 'utf8');
-  } catch {
-    // New file created via Edit: fall through with an empty base.
-  }
-  const edits = toolName === 'MultiEdit' ? toolInput.edits ?? [] : [toolInput];
-  for (const edit of edits) {
-    const from = edit.old_string ?? '';
-    const to = edit.new_string ?? '';
-    if (from === '') {
-      text = to;
-    } else if (edit.replace_all) {
-      text = text.split(from).join(to);
-    } else {
-      text = text.replace(from, () => to);
-    }
-  }
-  return text;
-}
-
 /**
  * One-shot PreToolUse gate (Claude Code + Grok Build hook contracts): payload on stdin,
  * exit 2 + violations on stderr to block, exit 0 to allow. Grok also receives a deny
@@ -628,42 +384,6 @@ function processHookOutput() {
   };
 }
 
-/** Antigravity PreToolUse requires stdout `decision` on every response (allow included). */
-function emitAntigravityAllow(output, antigravityStyle) {
-  if (!antigravityStyle) return;
-  output.stdout(`${JSON.stringify({ decision: 'allow' })}\n`);
-}
-
-/** Cursor preToolUse accepts explicit allow; exit 0 alone also works. */
-function emitCursorAllow(output, cursorStyle) {
-  if (!cursorStyle) return;
-  output.stdout(`${JSON.stringify({ permission: 'allow' })}\n`);
-}
-
-function emitHostAllow(output, { antigravityStyle, cursorStyle }) {
-  emitAntigravityAllow(output, antigravityStyle);
-  emitCursorAllow(output, cursorStyle);
-}
-
-/**
- * Socket-style write-gate deny: two lines first. Pass/fail, no score.
- * Rule id stays on a following line, not the first sentence.
- */
-function formatWriteGateDeny({ file, reason, ruleId, nextAction, extraLines = [] }) {
-  const target = file || 'this write';
-  const why = String(reason || 'this change breaks the architecture layers').replace(/\s+/g, ' ').trim();
-  const next =
-    nextAction && /place|move|import|port/i.test(nextAction)
-      ? nextAction
-      : 'Move the import or run /ark-place. Do not weaken ark.config.json.';
-  const lines = [`blocked ${target} — ${why}`, `Next: ${next}`];
-  if (ruleId) lines.push(`[${ruleId}]`);
-  for (const extra of extraLines) {
-    if (extra) lines.push(extra);
-  }
-  return lines.join('\n');
-}
-
 function runHookPayload(payload, gate, config, args, ts, attemptContext, output = processHookOutput()) {
   const { toolName, toolInput, grokStyle, antigravityStyle, cursorStyle, operation } =
     normalizeHookPayload(
@@ -881,7 +601,18 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
 
   const layer = inferLayer(filePath, config, args.root);
   const validateOnce = (src) =>
-    validateSnippetAnalysis({ gate, ts, source: src, context: { layer, filePath } });
+    validateSnippetAnalysis({
+      gate,
+      ts,
+      source: src,
+      context: arkRunSnippetContext({
+        root: args.root,
+        config,
+        filePath,
+        layer,
+        relFile: normalizedRel,
+      }),
+    });
   // W1: one validation pass (+ optional autoPatch). Original write still blocked when
   // invalid; hosts must apply autoPatch explicitly (never silent write).
   const result = ts
@@ -2452,7 +2183,17 @@ export async function runArkMcp({ hookInput } = {}) {
     const filePath = params.arguments.filePath;
     const layer = params.arguments.layer ?? inferLayer(filePath, config, args.root);
     const validateOnce = (src) =>
-      validateSnippetAnalysis({ gate, ts, source: src, context: { layer, filePath } });
+      validateSnippetAnalysis({
+        gate,
+        ts,
+        source: src,
+        context: arkRunSnippetContext({
+          root: args.root,
+          config,
+          filePath,
+          layer,
+        }),
+      });
     // W1: attempt mechanical-safe single-file autoPatch (import type), re-validate or discard.
     const result = validateWithAutoPatch({
       source,
@@ -2745,7 +2486,12 @@ export async function runArkMcp({ hookInput } = {}) {
         gate,
         ts,
         source: src,
-        context: { layer, filePath: placement.filePath },
+        context: arkRunSnippetContext({
+          root: args.root,
+          config,
+          filePath: placement.filePath,
+          layer,
+        }),
       });
     const result = composePrepareWrite({
       source,

package/bin/ark-shared.mjs

@@ -11,6 +11,18 @@ import {
   looksLikeArkIntent,
   resolveIntentLayer as resolveConfiguredIntentLayer,
 } from './lib/source-policy.mjs';
+import {
+  presentLockfiles,
+  detectPackageManager,
+  execRunner,
+  arkCommand,
+  execCommandParts,
+  isPnpmWorkspaceRoot,
+  isNpmYarnWorkspaceRoot,
+  normalizeArkgateInstallSpec,
+  packageInstallArgv,
+  installDevHint,
+} from './lib/package-manager.mjs';
 
 /**
  * Default intent-prefix map shared by both CLIs and the ark-mcp write-path gate. The rule
@@ -575,152 +587,18 @@ export function typescriptUsabilityHint(mod) {
   return 'unknown shape incompatibility';
 }
 
-/** The three package managers Ark emits commands for. */
-const LOCKFILES = { pnpm: 'pnpm-lock.yaml', yarn: 'yarn.lock', npm: 'package-lock.json' };
-
-/**
- * The Corepack `packageManager` field (and the newer `devEngines.packageManager`) is the
- * project's OWN authoritative statement of its package manager. When present it wins over any
- * lockfile guess. Returns 'pnpm' | 'yarn' | 'npm' | undefined.
- */
-function declaredPackageManager(root) {
-  let pkg;
-  try {
-    pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
-  } catch {
-    return undefined;
-  }
-  const raw =
-    (typeof pkg.packageManager === 'string' ? pkg.packageManager.split('@')[0] : undefined) ??
-    (typeof pkg.devEngines?.packageManager?.name === 'string'
-      ? pkg.devEngines.packageManager.name
-      : undefined);
-  const name = raw?.trim().toLowerCase();
-  return name === 'pnpm' || name === 'yarn' || name === 'npm' ? name : undefined;
-}
-
-/** Lockfiles present in the project root, in { pnpm, yarn, npm } key order. */
-export function presentLockfiles(root) {
-  return Object.entries(LOCKFILES)
-    .filter(([, file]) => fs.existsSync(path.join(root, file)))
-    .map(([pm]) => pm);
-}
-
-/**
- * Detect the project's package manager: 'pnpm' | 'yarn' | 'npm'.
- *
- * Priority: (1) the `packageManager` / `devEngines` field (the project's own declaration);
- * (2) a single lockfile; (3) on CONFLICT (more than one lockfile and no declaration) prefer
- * npm whenever a package-lock.json is present. Rationale: `npx` runs fine inside a pnpm/yarn
- * repo, but `pnpm exec` / `yarn` in an npm repo BREAKS (frozen-lockfile / no-TTY / a spurious
- * pnpm-lock). So a stray pnpm-lock.yaml left in an npm project must NOT hijack it into pnpm —
- * package-lock.json wins the tie, and the field is the escape hatch for a genuine pnpm repo
- * that still carries a package-lock.json. Falls back to npm when nothing is detectable.
- */
-export function detectPackageManager(root) {
-  const declared = declaredPackageManager(root);
-  if (declared) return declared;
-  const locks = presentLockfiles(root);
-  if (locks.length <= 1) return locks[0] ?? 'npm';
-  if (locks.includes('npm')) return 'npm';
-  return locks[0]; // pnpm over yarn when only those two collide
-}
-
-// pnpm 10+ `pnpm exec` runs a deps-status pre-check that fails with ERR_PNPM_IGNORED_BUILDS
-// when the repo has un-approved native build scripts (sharp, esbuild, tailwind oxide, …) —
-// the common state of real pnpm apps. Skip that gate so Ark's emitted commands still run.
-const PNPM_EXEC = 'pnpm --config.verify-deps-before-run=false exec';
-const RUNNER_BY_PM = { pnpm: PNPM_EXEC, yarn: 'yarn', npm: 'npx' };
-
-/**
- * The command prefix that runs an INSTALLED package binary, matched to the project's
- * package manager. `npx` is used for npm and as the safe fallback.
- *
- * This is the single source of truth that makes every command Ark EMITS — the AGENTS.md
- * contract, .mcp.json, the Claude/Codex hooks, the check:architecture script, the
- * SessionStart summary and every console hint — respect a pnpm-only or yarn repo instead
- * of hardcoding `npx`. (A "pnpm only, never npx" repo treats an emitted `npx` as a policy
- * violation.) `packageManager()` in ark-check.mjs builds the CI-workflow variant on the
- * same detection.
- */
-export function execRunner(root) {
-  return RUNNER_BY_PM[detectPackageManager(root)];
-}
-
-/** Full runnable command string for an installed Ark binary, package-manager aware. */
-export function arkCommand(root, bin, argsStr = '') {
-  return `${execRunner(root)} ${bin}${argsStr ? ` ${argsStr}` : ''}`;
-}
-
-/**
- * Split { command, args } form for JSON/TOML configs (.mcp.json, config.toml) that spawn
- * the binary directly. `pnpm exec ark-mcp` becomes command "pnpm" + args ["exec","ark-mcp",…]
- * so the runner is a real argv[0], not a space-joined string a shell would mis-split.
- */
-export function execCommandParts(root, bin, binArgs = []) {
-  const runner = execRunner(root);
-  if (runner === PNPM_EXEC || runner.startsWith('pnpm ')) {
-    return {
-      command: 'pnpm',
-      args: ['--config.verify-deps-before-run=false', 'exec', bin, ...binArgs],
-    };
-  }
-  if (runner === 'yarn') return { command: 'yarn', args: [bin, ...binArgs] };
-  return { command: 'npx', args: [bin, ...binArgs] };
-}
-
-/**
- * True when this directory is a pnpm workspace root (needs `pnpm add -w` for root deps).
- * Nested packages under the workspace are not roots.
- */
-export function isPnpmWorkspaceRoot(root) {
-  return fs.existsSync(path.join(root, 'pnpm-workspace.yaml'));
-}
-
-/**
- * True when package.json declares npm/yarn workspaces (yarn classic needs `-W` at root).
- */
-export function isNpmYarnWorkspaceRoot(root) {
-  const pkg = readPackageJson(root);
-  if (!pkg) return false;
-  const ws = pkg.workspaces;
-  return Array.isArray(ws) || (ws && typeof ws === 'object' && Array.isArray(ws.packages));
-}
-
-/**
- * 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) {
-  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;
-  return `arkgate@${raw}`;
-}
-
-/**
- * Package-manager argv to add a dev dependency (e.g. arkgate@latest).
- * pnpm workspace roots get `-w`; yarn classic workspaces get `-W`.
- *
- * @param {string} root
- * @param {string} [versionSpec]  package name or name@version (default arkgate@latest)
- * @returns {[string, string[]]}
- */
-export function packageInstallArgv(root, versionSpec = 'latest') {
-  const pkgSpec = normalizeArkgateInstallSpec(versionSpec);
-  const pm = detectPackageManager(root);
-  if (pm === 'pnpm') {
-    const args = ['add', '-D', pkgSpec];
-    if (isPnpmWorkspaceRoot(root)) args.push('-w');
-    return ['pnpm', args];
-  }
-  if (pm === 'yarn') {
-    const args = ['add', '-D', pkgSpec];
-    if (isNpmYarnWorkspaceRoot(root)) args.push('-W');
-    return ['yarn', args];
-  }
-  return ['npm', ['install', '-D', pkgSpec]];
-}
+export {
+  presentLockfiles,
+  detectPackageManager,
+  execRunner,
+  arkCommand,
+  execCommandParts,
+  isPnpmWorkspaceRoot,
+  isNpmYarnWorkspaceRoot,
+  normalizeArkgateInstallSpec,
+  packageInstallArgv,
+  installDevHint,
+};
 
 // FX01–FX02: registry-aware skip lives in upgrade-package-decision (injectable probe).
 export {
@@ -731,18 +609,6 @@ export {
   probeRegistryArkgateLatest,
 } from './lib/upgrade-package-decision.mjs';
 
-/** Package-manager aware "install a dev dependency" hint (e.g. for a missing typescript). */
-export function installDevHint(root, pkg) {
-  const pm = detectPackageManager(root);
-  if (pm === 'pnpm') {
-    return isPnpmWorkspaceRoot(root) ? `pnpm add -D ${pkg} -w` : `pnpm add -D ${pkg}`;
-  }
-  if (pm === 'yarn') {
-    return isNpmYarnWorkspaceRoot(root) ? `yarn add -D ${pkg} -W` : `yarn add -D ${pkg}`;
-  }
-  return `npm install -D ${pkg}`;
-}
-
 export const ARCHETYPE_IDS = [
   'crud-product',
   'api-backend',