auditor-lambda 0.1.0

package/audit-code-wrapper-lib.mjs

@@ -0,0 +1,905 @@
+import { access, mkdir, open, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = dirname(fileURLToPath(import.meta.url));
+const distEntry = join(repoRoot, 'dist', 'index.js');
+const packageJsonPath = join(repoRoot, 'package.json');
+const promptAssetPath = join(repoRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
+const skillAssetPath = join(repoRoot, 'skills', 'audit-code', 'SKILL.md');
+const tsconfigPath = join(repoRoot, 'tsconfig.json');
+const sourceRoot = join(repoRoot, 'src');
+const buildLockPath = join(repoRoot, '.audit-code-build.lock');
+const BUILD_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const BUILD_LOCK_WAIT_TIMEOUT_MS = 2 * 60 * 1000;
+const BUILD_LOCK_WAIT_INTERVAL_MS = 200;
+const INSTALL_MARKER_START = '<!-- audit-code:begin -->';
+const INSTALL_MARKER_END = '<!-- audit-code:end -->';
+const INSTALL_GUIDE_FILENAME = 'GETTING-STARTED.md';
+const DEFAULT_INSTALL_HOST = 'all';
+const packageVersion = JSON.parse(await readFile(packageJsonPath, 'utf8')).version;
+
+function hasFlag(argv, name) {
+  return argv.includes(name);
+}
+
+function getFlag(argv, name) {
+  const index = argv.indexOf(name);
+  if (index < 0) return undefined;
+  return argv[index + 1];
+}
+
+function setDefaultFlag(argv, name, value) {
+  if (!hasFlag(argv, name)) {
+    argv.push(name, value);
+  }
+}
+
+function requireFlagValue(argv, name) {
+  const value = getFlag(argv, name);
+  if (!value) {
+    throw new Error(`${name} requires a value.`);
+  }
+  return value;
+}
+
+function npmExecutable() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function nodeExecutable() {
+  return process.execPath;
+}
+
+function quoteForCmd(arg) {
+  if (arg.length === 0) return '""';
+  if (!/[\s"]/u.test(arg)) return arg;
+  return `"${arg.replace(/"/g, '""')}"`;
+}
+
+function resolveSpawn(command, args) {
+  if (!(process.platform === 'win32' && /\.(cmd|bat)$/i.test(command))) {
+    return { command, args };
+  }
+
+  return {
+    command: process.env.ComSpec ?? 'cmd.exe',
+    args: ['/d', '/s', '/c', [command, ...args].map(quoteForCmd).join(' ')],
+  };
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const resolved = resolveSpawn(command, args);
+    const child = spawn(resolved.command, resolved.args, {
+      cwd: repoRoot,
+      stdio: options.capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      env: process.env
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    if (options.capture) {
+      child.stdout?.on('data', (chunk) => {
+        stdout += String(chunk);
+      });
+      child.stderr?.on('data', (chunk) => {
+        stderr += String(chunk);
+      });
+    }
+
+    child.on('error', rejectPromise);
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolvePromise({ stdout, stderr });
+        return;
+      }
+      rejectPromise(new Error(options.capture ? stderr || `Command failed with exit code ${code}.` : `Command failed with exit code ${code}.`));
+    });
+  });
+}
+
+async function sleep(ms) {
+  await new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
+async function fileExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function newestMtimeMs(path) {
+  const stats = await stat(path);
+  if (!stats.isDirectory()) {
+    return stats.mtimeMs;
+  }
+
+  let newest = stats.mtimeMs;
+  const entries = await readdir(path, { withFileTypes: true });
+  for (const entry of entries) {
+    const childPath = join(path, entry.name);
+    if (entry.isDirectory()) {
+      newest = Math.max(newest, await newestMtimeMs(childPath));
+      continue;
+    }
+    if (entry.isFile()) {
+      newest = Math.max(newest, (await stat(childPath)).mtimeMs);
+    }
+  }
+  return newest;
+}
+
+async function shouldBuildDist() {
+  if (!(await fileExists(distEntry))) {
+    if (!(await fileExists(sourceRoot)) || !(await fileExists(tsconfigPath))) {
+      throw new Error(
+        'Bundled dist is missing and source files are unavailable for rebuild.',
+      );
+    }
+    return true;
+  }
+
+  if (!(await fileExists(sourceRoot)) || !(await fileExists(tsconfigPath))) {
+    return false;
+  }
+
+  const distMtime = (await stat(distEntry)).mtimeMs;
+  const sourceMtime = await newestMtimeMs(sourceRoot);
+  const tsconfigMtime = (await stat(tsconfigPath)).mtimeMs;
+  const packageJsonMtime = (await stat(packageJsonPath)).mtimeMs;
+  const newestInput = Math.max(sourceMtime, tsconfigMtime, packageJsonMtime);
+  return distMtime < newestInput;
+}
+
+async function releaseBuildLock(handle) {
+  try {
+    await handle?.close();
+  } finally {
+    await unlink(buildLockPath).catch(() => {});
+  }
+}
+
+async function waitForPeerBuild() {
+  const start = Date.now();
+
+  while (true) {
+    if (!(await fileExists(buildLockPath))) {
+      return;
+    }
+
+    if (Date.now() - start > BUILD_LOCK_WAIT_TIMEOUT_MS) {
+      throw new Error(`Timed out waiting for build lock ${buildLockPath}.`);
+    }
+
+    await sleep(BUILD_LOCK_WAIT_INTERVAL_MS);
+  }
+}
+
+async function acquireBuildLock() {
+  while (true) {
+    try {
+      const handle = await open(buildLockPath, 'wx');
+      await handle.writeFile(JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() }));
+      return handle;
+    } catch (error) {
+      if (error && error.code === 'EEXIST') {
+        try {
+          const lockStats = await stat(buildLockPath);
+          if (Date.now() - lockStats.mtimeMs > BUILD_LOCK_MAX_AGE_MS) {
+            await unlink(buildLockPath).catch(() => {});
+            continue;
+          }
+        } catch {
+          continue;
+        }
+
+        await waitForPeerBuild();
+        if (!(await shouldBuildDist())) {
+          return null;
+        }
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+async function ensureBuilt() {
+  if (!(await shouldBuildDist())) {
+    return;
+  }
+
+  const lockHandle = await acquireBuildLock();
+  if (!lockHandle) {
+    return;
+  }
+
+  try {
+    if (!(await shouldBuildDist())) {
+      return;
+    }
+    await run(npmExecutable(), ['run', 'build']);
+  } finally {
+    await releaseBuildLock(lockHandle);
+  }
+}
+
+function printHelp({ usageName, preferredEntrypoint }) {
+  const lines = [
+    `Usage: node ${usageName} [--single-step] [--root PATH] [--artifacts-dir PATH] [--results FILE] [--updates FILE] [--external-analyzer-results FILE]`,
+    '',
+    'Helper commands:',
+    '- prompt-path prints the absolute path to the canonical /audit-code prompt asset',
+    '- install bootstraps /audit-code into supported repo-local host surfaces',
+    '- install-host --host copilot keeps the narrower Copilot-focused install path available',
+    '- validate checks the current artifact bundle plus session-config/provider readiness and exits non-zero when issues exist',
+    '',
+    'Primary usage:',
+    '- from the repository root, run the wrapper with no arguments',
+    '- default behavior advances the audit automatically until it completes or no further automatic progress is possible',
+    '- each wrapper response refreshes operator-handoff.json and operator-handoff.md under the artifacts directory',
+    '- use --single-step only for debugging or bounded-step testing',
+    '',
+    'Defaults:',
+    '- --root .',
+    '- --artifacts-dir <root>/.audit-artifacts',
+    '',
+    'Completion signals:',
+    '- done: audit_state.status is complete',
+    '- blocked/no further automatic progress: progress_made is false and next_likely_step is null'
+  ];
+
+  if (preferredEntrypoint && preferredEntrypoint !== usageName) {
+    lines.push('', `Preferred entrypoint: node ${preferredEntrypoint}`);
+  }
+
+  console.log(lines.join('\n'));
+}
+
+async function printPromptPath() {
+  if (!(await fileExists(promptAssetPath))) {
+    throw new Error(`Canonical prompt asset is missing: ${promptAssetPath}`);
+  }
+
+  console.log(resolve(promptAssetPath));
+}
+
+function normalizeNewlines(value) {
+  return value.replace(/\r\n/g, '\n');
+}
+
+function splitFrontmatter(markdown) {
+  const normalized = normalizeNewlines(markdown);
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?/u);
+  if (!match) {
+    return { frontmatter: null, body: normalized };
+  }
+
+  return {
+    frontmatter: match[1],
+    body: normalized.slice(match[0].length),
+  };
+}
+
+function renderFrontmatter(fields) {
+  const entries = Object.entries(fields).filter(([, value]) => {
+    if (value === undefined || value === null) {
+      return false;
+    }
+
+    if (typeof value === 'string') {
+      return value.length > 0;
+    }
+
+    return true;
+  });
+  if (entries.length === 0) {
+    return '';
+  }
+
+  return [
+    '---',
+    ...entries.map(([key, value]) => `${key}: ${value}`),
+    '---',
+    '',
+  ].join('\n');
+}
+
+function renderPromptFile(fields, body) {
+  return `${renderFrontmatter(fields)}${body.trimStart()}`;
+}
+
+function toRepoRelativePath(root, targetPath) {
+  const value = relative(root, targetPath).replace(/\\/g, '/');
+  return value.length > 0 ? value : '.';
+}
+
+function buildInstallDirective(relativePromptPath) {
+  return [
+    INSTALL_MARKER_START,
+    '## /audit-code',
+    'When the user enters `/audit-code`, treat it as this repository\'s autonomous audit workflow.',
+    `If your host does not automatically register the installed slash command file, load and follow [the repo-local audit directive](${relativePromptPath.replace(/\\/g, '/')}).`,
+    'Normal usage should stay conversation-first and avoid manual `--root`, provider flags, or model-selection arguments.',
+    INSTALL_MARKER_END,
+  ].join('\n');
+}
+
+function buildInstallHostGuidance({
+  installedPromptPath,
+  slashCommandSurfaces,
+  instructionSurfaces,
+}) {
+  const guidance = [];
+
+  if (slashCommandSurfaces.vscode_prompt) {
+    guidance.push({
+      host: 'vscode',
+      label: 'VS Code',
+      support_level: 'supported',
+      setup_kind: 'repo-local-slash-command',
+      summary:
+        'Use the generated VS Code / Copilot prompt surface, then invoke `/audit-code` in chat.',
+      primary_path: slashCommandSurfaces.vscode_prompt,
+      supporting_paths: [
+        instructionSurfaces.copilot_instructions,
+        instructionSurfaces.agents,
+      ].filter(Boolean),
+      steps: [
+        'Open this repository in VS Code or GitHub Copilot Chat.',
+        'Invoke `/audit-code` in chat.',
+        'Use the integrated terminal and run `audit-code` only when you intentionally need the repo-local backend fallback.',
+      ],
+    });
+  }
+
+  if (slashCommandSurfaces.opencode_command) {
+    guidance.push({
+      host: 'opencode',
+      label: 'OpenCode',
+      support_level: 'supported',
+      setup_kind: 'repo-local-slash-command',
+      summary:
+        'Use the generated OpenCode command surface so `/audit-code` is available without extra provider flags.',
+      primary_path: slashCommandSurfaces.opencode_command,
+      supporting_paths: [instructionSurfaces.agents].filter(Boolean),
+      steps: [
+        'Open this repository in OpenCode.',
+        'Invoke `/audit-code` from the OpenCode command surface.',
+        'Use the repo-local backend wrapper only when you intentionally need the fallback automation path.',
+      ],
+    });
+  }
+
+  if (slashCommandSurfaces.claude_code_command) {
+    guidance.push({
+      host: 'claude-code',
+      label: 'Claude Code',
+      support_level: 'supported',
+      setup_kind: 'repo-local-slash-command',
+      summary:
+        'Use the generated Claude Code command surface so `/audit-code` is available inside the repository without extra provider wiring.',
+      primary_path: slashCommandSurfaces.claude_code_command,
+      supporting_paths: [instructionSurfaces.claude].filter(Boolean),
+      steps: [
+        'Open this repository in Claude Code.',
+        'Invoke `/audit-code` from the Claude Code project command surface.',
+        'Use the terminal fallback and run `audit-code` only when you intentionally need the repo-local backend wrapper.',
+      ],
+    });
+  }
+
+  guidance.push({
+    host: 'claude-desktop',
+    label: 'Claude Desktop',
+    support_level: 'manual-import',
+    setup_kind: 'prompt-import',
+    summary:
+      'No verified project-local slash-command surface is shipped for Claude Desktop, so use the installed prompt asset as the primary path.',
+    primary_path: installedPromptPath,
+    supporting_paths: [instructionSurfaces.claude].filter(Boolean),
+    steps: [
+      'Import the installed prompt asset into Claude Desktop\'s prompt or instruction surface.',
+      'Invoke `/audit-code` conversationally inside Claude Desktop after the prompt is available.',
+      'If you intentionally need the repo-local backend fallback instead, run `audit-code` from the repository root.',
+    ],
+  });
+
+  guidance.push({
+    host: 'antigravity',
+    label: 'Antigravity',
+    support_level: 'manual-import',
+    setup_kind: 'prompt-import-or-terminal',
+    summary:
+      'No verified repo-local slash-command surface is shipped for Antigravity, so start from the installed prompt asset or an Antigravity-managed terminal.',
+    primary_path: installedPromptPath,
+    supporting_paths: [instructionSurfaces.agents].filter(Boolean),
+    steps: [
+      'Import the installed prompt asset into Antigravity\'s prompt or instruction surface when that surface is available.',
+      'Invoke `/audit-code` conversationally inside Antigravity.',
+      'If you prefer the backend fallback, run `audit-code` from an Antigravity-managed terminal with `local-subprocess` first.',
+    ],
+  });
+
+  return guidance;
+}
+
+function renderInstallHostSection(root, guide) {
+  const lines = [
+    `## ${guide.label}`,
+    '',
+    `Support level: ${guide.support_level}`,
+    `Setup kind: ${guide.setup_kind}`,
+    '',
+    guide.summary,
+    '',
+    'Primary repo-local path:',
+    `- \`${toRepoRelativePath(root, guide.primary_path)}\``,
+  ];
+
+  if (guide.supporting_paths.length > 0) {
+    lines.push('', 'Supporting repo-local paths:');
+    for (const targetPath of guide.supporting_paths) {
+      lines.push(`- \`${toRepoRelativePath(root, targetPath)}\``);
+    }
+  }
+
+  lines.push('', 'Recommended steps:');
+  for (const step of guide.steps) {
+    lines.push(`- ${step}`);
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function renderInstallGuide({
+  root,
+  host,
+  installedPromptPath,
+  installedSkillPath,
+  slashCommandSurfaces,
+  instructionSurfaces,
+  unsupportedHosts,
+  hostGuidance,
+}) {
+  const slashCommandPaths = Object.values(slashCommandSurfaces).filter(Boolean);
+  const instructionPaths = Object.values(instructionSurfaces).filter(Boolean);
+  const lines = [
+    '# audit-code bootstrap guide',
+    '',
+    'The canonical product route is `/audit-code` in conversation.',
+    '',
+    'Canonical installed assets:',
+    `- prompt asset: \`${toRepoRelativePath(root, installedPromptPath)}\``,
+    `- skill asset: \`${toRepoRelativePath(root, installedSkillPath)}\``,
+  ];
+
+  if (slashCommandPaths.length > 0) {
+    lines.push('', 'Repo-local slash-command surfaces:');
+    for (const targetPath of slashCommandPaths) {
+      lines.push(`- \`${toRepoRelativePath(root, targetPath)}\``);
+    }
+  }
+
+  if (instructionPaths.length > 0) {
+    lines.push('', 'Compatibility instruction surfaces:');
+    for (const targetPath of instructionPaths) {
+      lines.push(`- \`${toRepoRelativePath(root, targetPath)}\``);
+    }
+  }
+
+  lines.push('', 'Host-specific quick starts:');
+  for (const guide of hostGuidance) {
+    lines.push(`- ${guide.label}: ${guide.summary}`);
+  }
+
+  for (const guide of hostGuidance) {
+    lines.push('', renderInstallHostSection(root, guide).trimEnd());
+  }
+
+  lines.push(
+    '',
+    'Backend fallback:',
+    '- from the repository root, run `audit-code` only when you intentionally need the repo-local backend wrapper',
+  );
+
+  if (unsupportedHosts.length > 0) {
+    lines.push('', 'Hosts still requiring extra handling today:');
+    for (const item of unsupportedHosts) {
+      lines.push(`- ${item.host}: ${item.reason}`);
+    }
+  }
+
+  if (host !== 'all') {
+    lines.push(
+      '',
+      `This install was scoped to \`${host}\`, so some repo-local surfaces may be intentionally omitted.`,
+    );
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+function upsertManagedBlock(existingContent, blockContent) {
+  const normalized = normalizeNewlines(existingContent);
+  const blockPattern = new RegExp(
+    `${INSTALL_MARKER_START}[\\s\\S]*?${INSTALL_MARKER_END}`,
+    'u',
+  );
+
+  if (blockPattern.test(normalized)) {
+    return normalized.replace(blockPattern, blockContent);
+  }
+
+  if (normalized.trim().length === 0) {
+    return `${blockContent}\n`;
+  }
+
+  return `${normalized.replace(/\s+$/u, '')}\n\n${blockContent}\n`;
+}
+
+async function writeManagedMarkdown(targetPath, blockContent) {
+  const existed = await fileExists(targetPath);
+  const existingContent = existed ? await readFile(targetPath, 'utf8') : '';
+  const nextContent = upsertManagedBlock(existingContent, blockContent);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, nextContent, 'utf8');
+  return {
+    path: targetPath,
+    mode: existed ? 'updated' : 'created',
+  };
+}
+
+async function writeGeneratedMarkdown(targetPath, content) {
+  const existed = await fileExists(targetPath);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, content, 'utf8');
+  return {
+    path: targetPath,
+    mode: existed ? 'updated' : 'created',
+  };
+}
+
+function getInstallProfile(host) {
+  switch (host) {
+    case 'all':
+      return {
+        writeVSCodePrompt: true,
+        writeCopilotInstructions: true,
+        writeAgents: true,
+        writeClaudeMemory: true,
+        writeOpenCodeCommand: true,
+        writeClaudeCommand: true,
+        writeCompatibilitySkills: true,
+      };
+    case 'copilot':
+      return {
+        writeVSCodePrompt: true,
+        writeCopilotInstructions: true,
+        writeAgents: false,
+        writeClaudeMemory: false,
+        writeOpenCodeCommand: false,
+        writeClaudeCommand: false,
+        writeCompatibilitySkills: false,
+      };
+    case 'vscode':
+      return {
+        writeVSCodePrompt: true,
+        writeCopilotInstructions: true,
+        writeAgents: true,
+        writeClaudeMemory: true,
+        writeOpenCodeCommand: false,
+        writeClaudeCommand: false,
+        writeCompatibilitySkills: false,
+      };
+    case 'opencode':
+      return {
+        writeVSCodePrompt: false,
+        writeCopilotInstructions: false,
+        writeAgents: true,
+        writeClaudeMemory: false,
+        writeOpenCodeCommand: true,
+        writeClaudeCommand: false,
+        writeCompatibilitySkills: true,
+      };
+    case 'claude-code':
+      return {
+        writeVSCodePrompt: false,
+        writeCopilotInstructions: false,
+        writeAgents: false,
+        writeClaudeMemory: true,
+        writeOpenCodeCommand: false,
+        writeClaudeCommand: true,
+        writeCompatibilitySkills: true,
+      };
+    default:
+      throw new Error(
+        `Unsupported host "${host}". Supported hosts: all, copilot, vscode, opencode, claude-code.`,
+      );
+  }
+}
+
+async function assertDirectoryExists(path, description) {
+  let stats;
+  try {
+    stats = await stat(path);
+  } catch {
+    throw new Error(`${description} does not exist: ${path}`);
+  }
+
+  if (!stats.isDirectory()) {
+    throw new Error(`${description} is not a directory: ${path}`);
+  }
+}
+
+async function installBootstrap(argv) {
+  const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
+  const root = resolve(getFlag(argv, '--root') ?? '.');
+  await assertDirectoryExists(root, 'Target repository root');
+  const profile = getInstallProfile(host);
+  const promptSource = await readFile(promptAssetPath, 'utf8');
+  const skillSource = await readFile(skillAssetPath, 'utf8');
+  const { body: promptBody } = splitFrontmatter(promptSource);
+  const installedPromptPath = join(root, '.audit-code', 'install', 'audit-code.prompt.md');
+  const installedSkillPath = join(root, '.audit-code', 'install', 'SKILL.md');
+  const installGuidePath = join(root, '.audit-code', 'install', INSTALL_GUIDE_FILENAME);
+  const slashCommandSurfaces = {
+    vscode_prompt: profile.writeVSCodePrompt
+      ? join(root, '.github', 'prompts', 'audit-code.prompt.md')
+      : null,
+    opencode_command: profile.writeOpenCodeCommand
+      ? join(root, '.opencode', 'commands', 'audit-code.md')
+      : null,
+    claude_code_command: profile.writeClaudeCommand
+      ? join(root, '.claude', 'commands', 'audit-code.md')
+      : null,
+  };
+  const instructionSurfaces = {
+    copilot_instructions: profile.writeCopilotInstructions
+      ? join(root, '.github', 'copilot-instructions.md')
+      : null,
+    agents: profile.writeAgents ? join(root, 'AGENTS.md') : null,
+    claude: profile.writeClaudeMemory ? join(root, 'CLAUDE.md') : null,
+  };
+  const unsupportedHosts = host === 'all'
+    ? [
+        {
+          host: 'claude-desktop',
+          reason:
+            'No verified project-local slash-command installation surface is currently shipped for Claude Desktop.',
+        },
+        {
+          host: 'antigravity',
+          reason:
+            'No verified repo-local slash-command installation surface is currently shipped for Antigravity.',
+        },
+      ]
+    : [];
+  const hostGuidance = buildInstallHostGuidance({
+    installedPromptPath,
+    slashCommandSurfaces,
+    instructionSurfaces,
+  });
+
+  const results = [];
+  results.push(
+    await writeGeneratedMarkdown(
+      installedPromptPath,
+      promptSource,
+    ),
+  );
+  results.push(await writeGeneratedMarkdown(installedSkillPath, skillSource));
+
+  if (profile.writeVSCodePrompt) {
+    results.push(
+      await writeGeneratedMarkdown(
+        join(root, '.github', 'prompts', 'audit-code.prompt.md'),
+        renderPromptFile(
+          {
+            name: 'audit-code',
+            description: 'Autonomous local loop code auditing',
+            agent: 'agent',
+          },
+          promptBody,
+        ),
+      ),
+    );
+  }
+
+  if (profile.writeOpenCodeCommand) {
+    results.push(
+      await writeGeneratedMarkdown(
+        join(root, '.opencode', 'commands', 'audit-code.md'),
+        renderPromptFile(
+          {
+            description: 'Autonomous local loop code auditing',
+            agent: 'build',
+            subtask: false,
+          },
+          promptBody,
+        ),
+      ),
+    );
+  }
+
+  if (profile.writeClaudeCommand) {
+    results.push(
+      await writeGeneratedMarkdown(
+        join(root, '.claude', 'commands', 'audit-code.md'),
+        renderPromptFile(
+          {
+            description: 'Autonomous local loop code auditing',
+          },
+          promptBody,
+        ),
+      ),
+    );
+  }
+
+  const compatibilityBlockTargets = Object.values(instructionSurfaces).filter(Boolean);
+
+  for (const targetPath of compatibilityBlockTargets) {
+    results.push(
+      await writeManagedMarkdown(
+        targetPath,
+        buildInstallDirective(
+          relative(dirname(targetPath), installedPromptPath) || './.audit-code/install/audit-code.prompt.md',
+        ),
+      ),
+    );
+  }
+
+  if (profile.writeCompatibilitySkills) {
+    const skillTargets = [
+      join(root, '.opencode', 'skills', 'audit-code'),
+      join(root, '.claude', 'skills', 'audit-code'),
+      join(root, '.agents', 'skills', 'audit-code'),
+    ];
+
+    for (const targetDir of skillTargets) {
+      results.push(
+        await writeGeneratedMarkdown(join(targetDir, 'SKILL.md'), skillSource),
+      );
+      results.push(
+        await writeGeneratedMarkdown(
+          join(targetDir, 'audit-code.prompt.md'),
+          promptSource,
+        ),
+      );
+    }
+  }
+
+  results.push(
+    await writeGeneratedMarkdown(
+      installGuidePath,
+      renderInstallGuide({
+        root,
+        host,
+        installedPromptPath,
+        installedSkillPath,
+        slashCommandSurfaces,
+        instructionSurfaces,
+        unsupportedHosts,
+        hostGuidance,
+      }),
+    ),
+  );
+
+  console.log(
+    JSON.stringify(
+      {
+        host,
+        repo_root: root,
+        installed_prompt_path: installedPromptPath,
+        installed_skill_path: installedSkillPath,
+        install_guide_path: installGuidePath,
+        source_prompt_path: resolve(promptAssetPath),
+        files: results,
+        slash_command_surfaces: slashCommandSurfaces,
+        instruction_surfaces: instructionSurfaces,
+        host_guidance: hostGuidance,
+        unsupported_hosts: unsupportedHosts,
+        next_steps: [
+          'Open the repository in your preferred host and follow the matching host_guidance entry.',
+          `Open ${installGuidePath} for repo-local quick-start steps for VS Code, OpenCode, Claude Code, Claude Desktop, and Antigravity.`,
+          'If a host does not auto-discover slash commands, use the installed prompt asset or the listed compatibility instruction surfaces.',
+        ],
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+async function installHostPrompt(argv) {
+  const host = requireFlagValue(argv, '--host').toLowerCase();
+
+  if (host !== 'copilot') {
+    throw new Error(
+      `install-host currently supports only "copilot". Use "install --host ${host}" for the broader bootstrap flow.`,
+    );
+  }
+
+  await installBootstrap(argv);
+}
+
+async function runDistCommand(commandName, argv, { ensureArtifactsDir = false } = {}) {
+  const commandArgs = [...argv];
+  const rootValue = resolve(getFlag(commandArgs, '--root') ?? '.');
+  const artifactsDir = resolve(getFlag(commandArgs, '--artifacts-dir') ?? join(rootValue, '.audit-artifacts'));
+
+  setDefaultFlag(commandArgs, '--root', rootValue);
+  setDefaultFlag(commandArgs, '--artifacts-dir', artifactsDir);
+
+  if (ensureArtifactsDir) {
+    await mkdir(artifactsDir, { recursive: true });
+  }
+
+  await ensureBuilt();
+  await run(nodeExecutable(), [distEntry, commandName, ...commandArgs]);
+}
+
+export async function runAuditCodeWrapper({
+  usageName,
+  argv = process.argv.slice(2),
+  ensureArtifactsDir = true,
+  preferredEntrypoint,
+  defaultSingleStep = false
+}) {
+  if (hasFlag(argv, '--help') || hasFlag(argv, '-h')) {
+    printHelp({ usageName, preferredEntrypoint });
+    return;
+  }
+
+  if (hasFlag(argv, '--version') || hasFlag(argv, '-v')) {
+    console.log(packageVersion);
+    return;
+  }
+
+  if (argv[0] === 'prompt-path') {
+    await printPromptPath();
+    return;
+  }
+
+  if (argv[0] === 'install') {
+    await installBootstrap(argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'install-host') {
+    await installHostPrompt(argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'validate') {
+    await runDistCommand('validate', argv.slice(1));
+    return;
+  }
+
+  const wrapperArgs = [...argv];
+  if (defaultSingleStep && !hasFlag(wrapperArgs, '--single-step')) {
+    wrapperArgs.push('--single-step');
+  }
+  const rootValue = resolve(getFlag(wrapperArgs, '--root') ?? '.');
+  const artifactsDir = resolve(getFlag(wrapperArgs, '--artifacts-dir') ?? join(rootValue, '.audit-artifacts'));
+
+  setDefaultFlag(wrapperArgs, '--root', rootValue);
+  setDefaultFlag(wrapperArgs, '--artifacts-dir', artifactsDir);
+
+  if (ensureArtifactsDir) {
+    await mkdir(artifactsDir, { recursive: true });
+  }
+
+  await ensureBuilt();
+  const command = hasFlag(wrapperArgs, '--single-step') ? 'advance-audit' : 'run-to-completion';
+  await run(nodeExecutable(), [distEntry, command, ...wrapperArgs]);
+}