audit-tools 0.28.0

package/audit-code-wrapper-install-renderers.mjs

@@ -0,0 +1,58 @@
+/**
+ * Per-host asset render functions for audit-code install.
+ *
+ * Every host asset is derived from the ONE canonical loader prompt body via the
+ * shared `renderHostAsset` helper (`audit-tools/shared`). These functions are
+ * thin wrappers that pass the canonical body through with the right `kind` and
+ * `toolName`; they do NOT re-author per-host loader prose. That makes it
+ * impossible for a host asset to drift out of sync with the canonical body — to
+ * silently drop the next-step capability handshake (including `--host-models`) or
+ * to embed a wrong in-repo entrypoint. A no-drift guard test enforces this.
+ */
+
+import { renderHostAsset } from 'audit-tools/shared';
+
+export const INSTALLED_PROMPT_FILENAME = 'audit-code.import.md';
+
+const TOOL_NAME = 'audit-code';
+const ASSET_DESCRIPTION =
+  'Autonomous local-loop code auditing — loads one backend-rendered audit step at a time';
+
+/** Render the VS Code auditor agent markdown file from the canonical body. */
+export function renderVSCodeAgentFile(promptBody) {
+  return renderHostAsset('vscode-agent', {
+    promptBody,
+    toolName: TOOL_NAME,
+    description:
+      'Plan and orchestrate /audit-code through the next-step machine before making code changes.',
+  });
+}
+
+/** Render the Codex re-audit automation recipe markdown from the canonical body. */
+export function renderCodexAutomationRecipe(promptBody) {
+  return renderHostAsset('codex-recipe', {
+    promptBody,
+    toolName: TOOL_NAME,
+  });
+}
+
+/** Render the Antigravity planning-mode guide from the canonical body. */
+export function renderAntigravityPlanningGuide(promptBody) {
+  return renderHostAsset('antigravity-guide', {
+    promptBody,
+    toolName: TOOL_NAME,
+  });
+}
+
+/**
+ * Render the Gemini/Antigravity slash command TOML for a given prompt body.
+ * Escapes backslashes and double-quotes so the TOML multi-line basic string
+ * is valid regardless of prompt content.
+ */
+export function renderGeminiCommandToml(promptBody) {
+  return renderHostAsset('gemini-toml', {
+    promptBody,
+    toolName: TOOL_NAME,
+    description: ASSET_DESCRIPTION,
+  });
+}

package/audit-code-wrapper-io.mjs

@@ -0,0 +1,155 @@
+import { access, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname } from 'node:path';
+
+export async function fileExists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export 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 = `${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;
+}
+
+export async function readTextIfExists(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export async function readJson(path, description) {
+  const content = await readFile(path, 'utf8');
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(
+      `${description} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+export 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',
+  };
+}
+
+export async function writeGeneratedJson(targetPath, value) {
+  const existed = await fileExists(targetPath);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, JSON.stringify(value, null, 2) + '\n', 'utf8');
+  return {
+    path: targetPath,
+    mode: existed ? 'updated' : 'created',
+  };
+}
+
+async function readJsonObjectIfExists(targetPath, description) {
+  if (!(await fileExists(targetPath))) {
+    return {};
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(targetPath, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `${description} exists but is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${description} must be a JSON object when it already exists.`);
+  }
+
+  return parsed;
+}
+
+export async function writeMergedGeneratedJson(targetPath, description, buildValue) {
+  const existed = await fileExists(targetPath);
+  const existing = await readJsonObjectIfExists(targetPath, description);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(
+    targetPath,
+    JSON.stringify(buildValue(existing), null, 2) + '\n',
+    'utf8',
+  );
+  return {
+    path: targetPath,
+    mode: existed ? 'updated' : 'created',
+  };
+}
+
+export async function writeGeneratedBinary(targetPath, content) {
+  const existed = await fileExists(targetPath);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await writeFile(targetPath, content);
+  return {
+    path: targetPath,
+    mode: existed ? 'updated' : 'created',
+  };
+}
+
+const INSTALL_MARKER_START = '<!-- audit-code:begin -->';
+const INSTALL_MARKER_END = '<!-- audit-code:end -->';
+
+function normalizeNewlines(value) {
+  return value.replace(/\r\n/g, '\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`;
+}
+
+export 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',
+  };
+}

package/audit-code-wrapper-legacy.mjs

@@ -0,0 +1,125 @@
+import { readdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readTextIfExists } from './audit-code-wrapper-io.mjs';
+
+function normalizeNewlines(value) {
+  return value.replace(/\r\n/g, '\n');
+}
+
+function looksLikeAuditCodeSkill(content) {
+  const normalized = normalizeNewlines(content);
+  return (
+    /^name:\s*audit-code\b/mu.test(normalized)
+    || normalized.includes('Conversation-first autonomous code auditing workflow for the /audit-code command.')
+    || normalized.includes('The canonical entrypoint is `/audit-code` in conversation.')
+  );
+}
+
+function looksLikeAuditCodePrompt(content) {
+  const normalized = normalizeNewlines(content);
+  return (
+    normalized.includes('# `/audit-code`')
+    && (
+      normalized.includes('audit-code orchestrator')
+      || normalized.includes('Autonomous local loop code auditing')
+      || normalized.includes('Conversation-first autonomous code auditing workflow')
+    )
+  );
+}
+
+function looksLikeAuditCodeInterfaceMetadata(content) {
+  const normalized = normalizeNewlines(content);
+  return (
+    normalized.includes('audit-code')
+    && (
+      normalized.includes('display_name:')
+      || normalized.includes('short_description:')
+      || normalized.includes('default_prompt:')
+    )
+    && (
+      normalized.includes('/audit-code')
+      || normalized.includes('Start /audit-code')
+    )
+  );
+}
+
+export async function buildLegacyAuditCodeSurfaceTargets(root) {
+  const targets = [
+    {
+      host: 'codex',
+      surface: 'skill',
+      path: join(root, '.codex', 'skills', 'audit-code', 'SKILL.md'),
+      matches: looksLikeAuditCodeSkill,
+    },
+    {
+      host: 'codex',
+      surface: 'prompt',
+      path: join(root, '.codex', 'skills', 'audit-code', 'audit-code.prompt.md'),
+      matches: looksLikeAuditCodePrompt,
+    },
+    {
+      host: 'opencode',
+      surface: 'command',
+      path: join(root, '.opencode', 'commands', 'audit-code.md'),
+      matches: looksLikeAuditCodePrompt,
+    },
+    {
+      host: 'opencode',
+      surface: 'skill',
+      path: join(root, '.opencode', 'skills', 'audit-code', 'SKILL.md'),
+      matches: looksLikeAuditCodeSkill,
+    },
+    {
+      host: 'opencode',
+      surface: 'prompt',
+      path: join(root, '.opencode', 'skills', 'audit-code', 'audit-code.prompt.md'),
+      matches: looksLikeAuditCodePrompt,
+    },
+    {
+      host: 'claude',
+      surface: 'command',
+      path: join(root, '.claude', 'commands', 'audit-code.md'),
+      matches: looksLikeAuditCodePrompt,
+    },
+  ];
+
+  const codexAgentDir = join(root, '.codex', 'skills', 'audit-code', 'agents');
+  const codexAgentEntries = await readdir(codexAgentDir).catch(() => []);
+  for (const entry of codexAgentEntries) {
+    targets.push({
+      host: 'codex',
+      surface: 'interface-metadata',
+      path: join(codexAgentDir, entry),
+      matches: looksLikeAuditCodeInterfaceMetadata,
+    });
+  }
+
+  return targets;
+}
+
+export async function findLegacyAuditCodeSurfaceFiles(root) {
+  const matches = [];
+  for (const target of await buildLegacyAuditCodeSurfaceTargets(root)) {
+    const existing = await readTextIfExists(target.path);
+    if (existing !== null && target.matches(existing)) {
+      matches.push(target.path);
+    }
+  }
+  return matches;
+}
+
+export async function removeLegacyAuditCodeSurfaceFiles(root) {
+  const removed = [];
+  for (const target of await buildLegacyAuditCodeSurfaceTargets(root)) {
+    const existing = await readTextIfExists(target.path);
+    if (existing === null || !target.matches(existing)) {
+      continue;
+    }
+    await unlink(target.path);
+    removed.push({
+      path: target.path,
+      mode: 'removed',
+    });
+  }
+  return removed;
+}

package/audit-code-wrapper-lib.mjs

@@ -0,0 +1,314 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ensureBuilt, shouldBuildDistForPaths, assertWorkspaceInstalled } from './audit-code-wrapper-build.mjs';
+import { fileExists } from './audit-code-wrapper-io.mjs';
+import {
+  installBootstrap,
+  verifyInstalledBootstrap,
+  ensureBootstrap,
+  installHostPrompt,
+  _INSTALL_HOST_ORDER,
+  _INSTALL_HOST_DEFINITIONS,
+  _getInstallHostKeys,
+  _getInstallProfile,
+  _renderGeminiCommandToml,
+} from './audit-code-wrapper-install-hosts.mjs';
+
+export { shouldBuildDistForPaths, assertWorkspaceInstalled };
+export { _INSTALL_HOST_ORDER, _INSTALL_HOST_DEFINITIONS, _getInstallHostKeys, _getInstallProfile, _renderGeminiCommandToml };
+
+const repoRoot = dirname(fileURLToPath(import.meta.url));
+const distEntry = join(repoRoot, 'dist', 'audit', 'index.js');
+const packageJsonPath = join(repoRoot, 'package.json');
+const promptAssetPath = join(repoRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
+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 nodeExecutable() {
+  return process.execPath;
+}
+
+// When the wrapper runs from a source checkout (its package dir is NOT inside a
+// node_modules tree), generated continuation commands should re-invoke THIS
+// wrapper via `node <path>` so a dogfooded monorepo run stays pinned to local
+// code instead of silently falling back to a globally-installed `audit-code`
+// bin. Installed copies leave the hint unset so the dist CLI keeps emitting the
+// `audit-code` bin. Returned as an env fragment scoped to the spawned child so
+// it never leaks into the parent process (e.g. the test runner).
+function selfInvocationEnv() {
+  if (process.env.AUDIT_CODE_INVOCATION) {
+    return { AUDIT_CODE_INVOCATION: process.env.AUDIT_CODE_INVOCATION };
+  }
+  if (/[\\/]node_modules[\\/]/.test(repoRoot)) {
+    return {};
+  }
+  return {
+    AUDIT_CODE_INVOCATION: JSON.stringify(['node', join(repoRoot, 'audit-code.mjs')]),
+  };
+}
+
+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: options.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}.`));
+    });
+  });
+}
+
+function printHelp({ usageName, preferredEntrypoint }) {
+  const lines = [
+    `Usage: node ${usageName} <command> [--root PATH] [--artifacts-dir PATH]`,
+    '',
+    'Primary usage (conversation-first):',
+    '- next-step advances deterministic audit state one bounded step and writes',
+    '  .audit-tools/audit/steps/current-step.json plus current-prompt.md; the host',
+    '  agent follows only the returned step prompt and calls next-step again',
+    '- advance-audit runs exactly one deterministic advance and prints the',
+    '  execution envelope (debugging / bounded-step testing)',
+    '',
+    'Helper commands:',
+    '- prompt-path prints the absolute path to the canonical /audit-code prompt asset',
+    '- ensure lazily bootstraps repo-local /audit-code assets when they are missing or stale',
+    '- install bootstraps /audit-code into supported repo-local host surfaces',
+    '- verify-install smoke-tests the generated host assets after install',
+    '- mcp starts the local stdio MCP server for repo-local IDE integrations',
+    '- 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',
+    '- validate-results --results FILE validates AuditResult payloads against the active task manifest without ingesting them',
+    '- explain-task <task_id> prints the resolved file coverage and current status for a task id',
+    '- prepare-dispatch --run-id <id> [--artifacts-dir <dir>] creates packet prompt files and a slim dispatch-plan.json for parallel subagent dispatch',
+    '- submit-packet --run-id <id> --packet-id <id> [--artifacts-dir <dir>] validates AuditResult[] from stdin and writes only backend-assigned result files',
+    '- merge-and-ingest --run-id <id> [--root <dir>] [--artifacts-dir <dir>] merges assigned packet results and ingests them into the coverage matrix',
+    '- validate-result --run-id <id> --task-id <id> [--artifacts-dir <dir>] validates a single task result against the schema and line counts',
+    '  generated packet prompts may use --run-id-b64, --task-id-b64, and --artifacts-dir-b64 to avoid shell-sensitive raw ids',
+    '',
+    'Defaults:',
+    '- --root .',
+    '- --artifacts-dir <root>/.audit-tools/audit',
+  ];
+
+  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));
+}
+
+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-tools', 'audit'));
+
+  setDefaultFlag(commandArgs, '--root', rootValue);
+  setDefaultFlag(commandArgs, '--artifacts-dir', artifactsDir);
+
+  if (ensureArtifactsDir) {
+    await mkdir(artifactsDir, { recursive: true });
+  }
+
+  await ensureBuilt();
+  await run(nodeExecutable(), [distEntry, commandName, ...commandArgs], {
+    env: { ...process.env, ...selfInvocationEnv() },
+  });
+}
+
+async function runDistCommandInline(commandName, argv) {
+  const commandArgs = [...argv];
+  const rootValue = resolve(getFlag(commandArgs, '--root') ?? '.');
+  const artifactsDir = resolve(getFlag(commandArgs, '--artifacts-dir') ?? join(rootValue, '.audit-tools', 'audit'));
+
+  setDefaultFlag(commandArgs, '--root', rootValue);
+  setDefaultFlag(commandArgs, '--artifacts-dir', artifactsDir);
+
+  await mkdir(artifactsDir, { recursive: true });
+  await ensureBuilt();
+
+  // Propagate the invocation hint into this (long-lived) server process so it
+  // and the wrapper subprocesses it spawns emit continuation commands that
+  // match how the backend was launched. Safe here: this path is only the `mcp`
+  // server, not a shared/test process.
+  Object.assign(process.env, selfInvocationEnv());
+
+  // Import the module that exports runCli (dist/cli.js). dist/index.js has no
+  // exports — it is the bare entrypoint that runs `runCli(process.argv)` as an
+  // import side effect — so importing it here both fails to provide runCli and
+  // double-starts the command from this process's argv.
+  const distCliEntry = join(repoRoot, 'dist', 'cli.js');
+  const distUrl = new URL(`file:///${distCliEntry.replace(/\\/g, '/')}`);
+  const cli = await import(distUrl.href);
+  await cli.runCli([process.execPath, distCliEntry, commandName, ...commandArgs]);
+}
+
+export async function runAuditCodeWrapper({
+  usageName,
+  argv = process.argv.slice(2),
+  preferredEntrypoint
+}) {
+  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] === 'ensure') {
+    await ensureBootstrap(argv.slice(1));
+    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] === 'verify-install') {
+    await verifyInstalledBootstrap(argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'validate') {
+    await runDistCommand('validate', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'validate-results') {
+    await runDistCommand('validate-results', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'explain-task') {
+    await runDistCommand('explain-task', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'mcp') {
+    await runDistCommandInline('mcp', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'next-step') {
+    await runDistCommand('next-step', argv.slice(1), { ensureArtifactsDir: true });
+    return;
+  }
+
+  if (argv[0] === 'prepare-dispatch') {
+    await runDistCommand('prepare-dispatch', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'validate-result') {
+    await runDistCommand('validate-result', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'quota') {
+    await runDistCommand('quota', argv.slice(1), { ensureArtifactsDir: true });
+    return;
+  }
+
+  if (argv[0] === 'submit-packet') {
+    await runDistCommand('submit-packet', argv.slice(1));
+    return;
+  }
+
+  if (argv[0] === 'merge-and-ingest') {
+    await runDistCommand('merge-and-ingest', argv.slice(1), { ensureArtifactsDir: true });
+    return;
+  }
+
+  if (argv[0] === 'advance-audit') {
+    await runDistCommand('advance-audit', argv.slice(1), { ensureArtifactsDir: true });
+    return;
+  }
+
+  // No implicit default command: the audit advances one bounded step per
+  // invocation via `next-step` (conversation-first). A bare invocation prints
+  // usage; an unrecognized command fails loudly instead of silently running
+  // something else.
+  if (argv.length === 0) {
+    printHelp({ usageName, preferredEntrypoint });
+    return;
+  }
+
+  printHelp({ usageName, preferredEntrypoint });
+  throw new Error(`Unknown command: ${argv[0]}`);
+}