audit-tools 0.28.0

package/README.audit.md

@@ -0,0 +1,223 @@
+# auditor-lambda
+
+Skill-first audit orchestration backend for the `/audit-code` product surface.
+
+## Canonical Product Route
+
+The primary product is `/audit-code` in conversation.
+
+Normal product usage should:
+
+- use the active conversation model by default
+- use project files and attached repository context by default
+- avoid manual paths, provider flags, and model-selection arguments
+- keep semantic review with the active conversation agent by default
+- advance the audit automatically until it completes or no further automatic progress is possible
+
+## Conversation Setup
+
+The canonical asset for editor and conversation integrations is:
+
+`skills/audit-code/audit-code.prompt.md`
+
+Packaged installs and repository checkouts both ship that prompt asset.
+
+The intended user install is one global tool install:
+
+```bash
+npm install -g auditor-lambda
+```
+
+That makes `audit-code` available on `PATH`. During package install, the package
+also writes user-level command/skill assets for hosts we can seed safely, including
+the Claude command file, the global Codex skill bundle with `audit-code` display
+metadata, and the global OpenCode slash command entry in
+`~/.config/opencode/opencode.json`.
+
+After that, invoke `/audit-code` in a supported host. The prompt self-bootstraps
+the current repository by running:
+
+```bash
+audit-code ensure --quiet
+```
+
+That command writes or refreshes the repo-local assets only when they are missing
+or stale, then normal audit execution continues without manual paths, provider
+flags, or model-selection arguments.
+
+The explicit repair and compatibility setup path remains:
+
+```bash
+audit-code install
+```
+
+That bootstraps repo-local supporting surfaces for the hosts we can automate today, including:
+
+- Codex `AGENTS.md` fallback guidance for the global skill surface
+- Claude Desktop local MCP bundle artifacts and project template guidance
+- OpenCode `opencode.json` with auditor agent and permission wiring; the `/audit-code` command stays in the global npm-installed OpenCode config
+- VS Code prompt, custom agent, Copilot instructions, and `.vscode/mcp.json`
+- Antigravity planning-mode guidance plus the shared repo-local MCP launcher
+
+`audit-code ensure` refreshes those files automatically when the packaged prompt
+or skill changes. Use `audit-code install` or `audit-code ensure --force` when
+you intentionally want to rewrite every generated host surface on demand.
+
+After bootstrap, you can smoke-test the generated host assets and launcher from the repository root:
+
+```bash
+audit-code verify-install
+```
+
+After that, open a supported conversation surface in the repository and invoke `/audit-code`.
+
+If a host still needs manual prompt import after bootstrap, open:
+
+```text
+.audit-code/install/GETTING-STARTED.md
+```
+
+That repo-local guide now includes dedicated quick-start sections for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity, plus the installed canonical prompt asset path for prompt-import fallback flows.
+
+For narrower compatibility, `audit-code install-host --host copilot` still exists.
+
+For hosts that still need manual import after bootstrap, or for environments with no repo-local install surface, after installing the package or checking out the repository, use:
+
+```bash
+audit-code prompt-path
+```
+
+Import the reported file into your editor or conversation environment's custom prompt configuration, then invoke `/audit-code` in conversation.
+
+Typical examples include custom instructions, `.cursorrules`, prompt libraries, or comparable editor-specific prompt surfaces.
+
+## Repo-Local Backend Fallback
+
+The CLI in this repository is backend infrastructure and a repo-local fallback surface.
+
+The conversation step engine used by `/audit-code` — the single execution loop —
+runs from the target repository root:
+
+```bash
+audit-code next-step
+```
+
+Repository-local equivalent:
+
+```bash
+node /path/to/auditor-lambda/audit-code.mjs next-step
+```
+
+This advances deterministic audit state one bounded step, writes
+`.audit-tools/audit/steps/current-step.json` and
+`.audit-tools/audit/steps/current-prompt.md`, auto-builds `dist/` if it is
+missing, and creates the artifacts directory automatically. Hosts follow only
+the returned step prompt, then call `next-step` again. A bare `audit-code`
+invocation prints usage; there is no implicit batch loop.
+
+Explicit root override still exists for callers running from outside the target repository:
+
+```bash
+audit-code next-step --root /path/to/repo
+```
+
+For one bounded debug advance that prints the execution envelope
+(`contract_version: "audit-code/v1alpha1"`) instead of a step contract:
+
+```bash
+audit-code advance-audit
+```
+
+For an operator-side artifact consistency check:
+
+```bash
+audit-code validate
+```
+
+That check now covers the artifact bundle plus `session-config.json` and explicit provider readiness.
+
+For native batch ingestion of multiple result files during a debug advance:
+
+```bash
+audit-code advance-audit --batch-results /path/to/audit-results-dir
+```
+
+For task-to-coverage inspection without reverse-engineering multiple artifacts:
+
+```bash
+audit-code explain-task <task_id>
+```
+
+To remove a leftover `.audit-artifacts/` directory from an interrupted or
+crashed audit:
+
+```bash
+audit-code cleanup
+audit-code cleanup --dry-run   # preview without deleting
+audit-code cleanup --force     # delete even if state is unknown
+```
+
+Refuses to delete if the audit state is `active` or `blocked` (resumable).
+Pass `--force` when `audit_state.json` is missing (crashed run).
+
+The backend wrapper response schema is `schemas/audit-code-v1alpha1.schema.json`.
+
+## Backend Provider Modes
+
+If `provider` is omitted, the backend defaults to the safest mode:
+
+```json
+{
+  "provider": "local-subprocess"
+}
+```
+
+If you want best-effort cross-editor or provider routing, opt into:
+
+```json
+{
+  "provider": "auto",
+  "ui_mode": "visible"
+}
+```
+
+Optional backend config:
+
+`.audit-artifacts/session-config.json`
+
+## Practical Guidance
+
+- use `/audit-code` in conversation as the canonical product surface
+- install once with `npm install -g auditor-lambda`, then let `/audit-code` run `audit-code ensure --quiet` in each repository
+- use `audit-code install` when you want to repair or force-refresh repo-local host assets
+- use `audit-code prompt-path` to locate the packaged prompt asset
+- use `audit-code` from the repository root only when you need the repo-local backend fallback
+- use omitted provider or `local-subprocess` for the safest deterministic fallback behavior
+- use `provider: "auto"` only when you want best-effort routing across installed backends
+- treat explicit provider bridges as compatibility fallback, not as the intended owner of semantic review
+
+## Build And Test
+
+```bash
+npm install
+npm run test:single -- tests/next-step.test.mjs
+npm run verify:release
+npm run release:patch
+npm run release:patch:publish
+```
+
+When developing from a fresh clone or git worktree, run repo-root `npm install`
+before package checks. Missing workspace links can look like stale
+`@audit-tools/shared` export or type errors.
+
+For GitHub Actions publication and npm Trusted Publishing setup, see `docs/release.md`.
+
+## Key Docs
+
+- `docs/product.md`
+- `docs/operator-guide.md`
+- `docs/contracts.md`
+- `docs/release.md`
+- `docs/development.md`
+- `docs/history.md`
+- `skills/audit-code/SKILL.md`

package/README.md

@@ -0,0 +1,42 @@
+# audit-tools
+
+Portable, hybrid code **auditing** + **remediation** orchestrators for arbitrary repositories,
+shipped as one package exposing two CLIs / slash workflows:
+
+- **`audit-code`** (`/audit-code`) — audits a codebase one bounded, backend-rendered step at a time
+  and produces a findings report (`audit-findings.json` + `audit-report.md`).
+- **`remediate-code`** (`/remediate-code`) — consumes that report (or free-form feedback) and applies
+  fixes step by step, emitting `remediation-outcomes.json` + `remediation-report.md`.
+
+Both are **conversation-first**: the product is the slash workflow inside a host agent; the CLI is the
+backend/fallback. Each `next-step` call returns one prompt contract (JSON + markdown); the host agent
+executes it and calls back for the next. State persists to an artifact directory, so runs are resumable.
+
+## Install
+
+```bash
+npm install -g audit-tools
+```
+
+This installs both the `audit-code` and `remediate-code` bins and deploys the host slash-command assets
+(Claude Code, Codex, OpenCode, Antigravity) via the package postinstall.
+
+## Usage
+
+```bash
+audit-code next-step        # advance the audit one step
+remediate-code next-step    # advance a remediation one step
+```
+
+In a host agent, drive the workflow with `/audit-code` then `/remediate-code`.
+
+## Concepts
+
+One pipeline, two halves: audit → findings contract; remediate → consumes + fixes. The JSON contract is
+the source of truth; the markdown is its human render. Neither tool runs to completion in a single call —
+each derives state, does one bounded unit of work, persists, and returns. See `CLAUDE.md` for the full
+design concepts and standing decisions.
+
+## License
+
+ISC

package/README.remediate.md

@@ -0,0 +1,113 @@
+# remediator-lambda
+
+Conversation-first remediation orchestrator for arbitrary repositories. It
+accepts the auditor's `audit-findings.json` (the deterministic machine contract)
+from [auditor-lambda](https://github.com/OhOkThisIsFine/auditor-lambda), an
+`audit-report.md` or other feedback document (LLM-extracted), or conversational
+feedback — then advances through one backend-rendered step prompt at a time.
+
+## Primary Usage
+
+```bash
+npm install -g remediator-lambda
+```
+
+Then start from a conversation:
+
+```text
+/remediate-code path/to/audit-findings.json
+```
+
+You can also start with free-form feedback:
+
+```text
+/remediate-code clean up the auth flow and make the session refresh behavior easier to test
+```
+
+The global loader runs `remediate-code ensure --quiet`, then
+`remediate-code next-step`, reads only the returned `prompt_path`, and follows
+that one prompt. Each prompt carries its own allowed commands and stop
+condition.
+
+If the starting point is not already a structured auditor report, the backend
+first creates an intake brief from the supplied document(s) or conversational
+feedback. It asks for clarification when the goals, non-goals, affected areas,
+or success criteria are ambiguous. The normal remediation workflow starts only
+after that brief is clear enough to convert into bounded findings.
+
+## Runtime Artifacts
+
+Active runs use `.remediation-artifacts/` in the target repository. The current
+state is `.remediation-artifacts/state.json`, and the current step contract is
+written to:
+
+- `.remediation-artifacts/steps/current-step.json`
+- `.remediation-artifacts/steps/current-prompt.md`
+
+After close, the durable outputs are written at the repo root:
+
+- `remediation-report.md`
+- `remediation-report.json`
+- `remediation-closing-result.json`
+
+## Development From Source
+
+The global `npm install -g remediator-lambda` path is for users. For repository
+development in a fresh clone or git worktree, run `npm install` at the repo root
+before build, check, test, or package-scoped workflows so workspace links point
+at the current `@audit-tools/shared` sources instead of stale compiled output.
+
+## CLI
+
+| Command | Description |
+| --- | --- |
+| `remediate-code next-step [--input <path>] [--host-can-dispatch-subagents]` | Decide and render exactly one next action |
+| `remediate-code prepare-implement-dispatch --run-id <id>` | Write bounded implementation prompts |
+| `remediate-code merge-implement-results --run-id <id>` | Validate implementation results and update item state |
+| `remediate-code validate-artifacts` | Validate runtime artifacts |
+| `remediate-code install` | Deprecated alias that repairs global assets and writes no repo-local host files |
+| `remediate-code ensure [--quiet]` | Repair/check global Claude, Codex, and OpenCode assets |
+
+`next-step` is the single canonical execution path. Hosts and IDEs should call
+it repeatedly, read the returned `prompt_path`, follow that one prompt, and then
+call `next-step` again only when the prompt says to continue.
+
+## Auditor Compatibility
+
+The auditor's canonical `audit-findings.json` is parsed **deterministically** —
+findings, work-block assignments, and synthesis themes are adopted verbatim, with
+no LLM involved. A Markdown `audit-report.md` (or any other free-form or partial
+document) is instead routed through intake synthesis and bounded LLM finding
+extraction, so it cannot silently produce a zero-finding plan. The deterministic
+contract is locked by `tests/fixtures/auditor-contract-audit-findings.json`,
+regenerated with `npm run fixtures:auditor-contract` from auditor-lambda's
+findings renderer.
+
+## Intake
+
+The remediator can start from any of these inputs:
+
+- a structured auditor report
+- one or more feedback or planning documents
+- conversational feedback typed directly after `/remediate-code`
+- a mix of documents and conversation
+
+Runtime intake artifacts live under `.remediation-artifacts/intake/`:
+
+- `source-manifest.json`
+- `conversation-start.md`
+- `intake-summary.json`
+- `intake-clarifications.json`
+- `remediation-brief.md`
+
+Structured auditor reports skip intake and go directly to planning. All other
+starting points go through synthesis first, and ambiguous requests pause for a
+single batched clarification before findings are extracted.
+
+## Closing
+
+The default closing action is `none`. Actions such as `commit`, `push`,
+`open-pr`, `publish`, `tag`, and `custom` record command exit codes and captured
+output in `remediation-closing-result.json`; reports only claim success after
+the command succeeds. Closing is advanced by a generated `next-step` finalization
+command, not the broad compatibility `run` loop.

package/audit-code-wrapper-build.mjs

@@ -0,0 +1,185 @@
+import { open, stat, unlink } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fileExists, newestMtimeMs } from './audit-code-wrapper-io.mjs';
+
+const repoRoot = dirname(fileURLToPath(import.meta.url));
+const distEntry = join(repoRoot, 'dist', 'audit', 'index.js');
+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;
+
+function npmExecutable() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+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((arg) => {
+      if (arg.length === 0) return '""';
+      if (!/[\s"]/u.test(arg)) return arg;
+      return `"${arg.replace(/"/g, '""')}"`;
+    }).join(' ')],
+  };
+}
+
+function runBuild(command, args) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const resolved = resolveSpawn(command, args);
+    const child = spawn(resolved.command, resolved.args, {
+      cwd: repoRoot,
+      // Auto-rebuild output is diagnostic — route both child streams to the
+      // parent's stderr (fd 2) so npm's `> auditor-lambda@… build` banner can
+      // never pollute the wrapper's stdout JSON channel when a caller captures it.
+      stdio: ['ignore', 2, 2],
+      env: process.env,
+    });
+    child.on('error', rejectPromise);
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolvePromise();
+        return;
+      }
+      rejectPromise(new Error(`Command failed with exit code ${code}.`));
+    });
+  });
+}
+
+export async function shouldBuildDistForPaths({
+  distEntryPath,
+  sourceRootPath,
+  tsconfigPath: tsconfigPathValue,
+}) {
+  if (!(await fileExists(distEntryPath))) {
+    if (!(await fileExists(sourceRootPath)) || !(await fileExists(tsconfigPathValue))) {
+      throw new Error(
+        'Bundled dist is missing and source files are unavailable for rebuild.',
+      );
+    }
+    return true;
+  }
+
+  if (!(await fileExists(sourceRootPath)) || !(await fileExists(tsconfigPathValue))) {
+    return false;
+  }
+
+  const distMtime = (await stat(distEntryPath)).mtimeMs;
+  const sourceMtime = await newestMtimeMs(sourceRootPath);
+  const tsconfigMtime = (await stat(tsconfigPathValue)).mtimeMs;
+  const newestInput = Math.max(sourceMtime, tsconfigMtime);
+  return distMtime < newestInput;
+}
+
+async function shouldBuildDist() {
+  return await shouldBuildDistForPaths({
+    distEntryPath: distEntry,
+    sourceRootPath: sourceRoot,
+    tsconfigPath,
+  });
+}
+
+async function releaseBuildLock(handle) {
+  try {
+    await handle?.close();
+  } finally {
+    await unlink(buildLockPath).catch(() => {});
+    process.stderr.write(JSON.stringify({ event: "build_lock_released", pid: process.pid, lock: buildLockPath, released_at: new Date().toISOString() }) + '\n');
+  }
+}
+
+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 new Promise((r) => setTimeout(r, BUILD_LOCK_WAIT_INTERVAL_MS));
+  }
+}
+
+async function acquireBuildLock() {
+  while (true) {
+    try {
+      const handle = await open(buildLockPath, 'wx');
+      const acquiredAt = new Date().toISOString();
+      await handle.writeFile(JSON.stringify({ pid: process.pid, acquired_at: acquiredAt }));
+      process.stderr.write(JSON.stringify({ event: "build_lock_acquired", pid: process.pid, lock: buildLockPath, acquired_at: acquiredAt }) + '\n');
+      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;
+    }
+  }
+}
+
+export function assertWorkspaceInstalled({ checkoutRoot, sharedManifestPath }) {
+  if (!sharedManifestPath) {
+    throw new Error(
+      'Dependencies are not installed for this checkout. Run `npm install` from ' +
+        'the repository root, then retry — building from source needs node_modules ' +
+        '(including the audit-tools/shared workspace link).',
+    );
+  }
+
+  const relToCheckout = relative(checkoutRoot, sharedManifestPath);
+  if (relToCheckout.startsWith('..') || isAbsolute(relToCheckout)) {
+    throw new Error(
+      `audit-tools/shared resolved to ${sharedManifestPath}, outside this ` +
+        `checkout (${checkoutRoot}). node_modules was never installed here — ` +
+        'common in a fresh git worktree — so building would typecheck against ' +
+        "another checkout's stale dist and report phantom \"missing export\" " +
+        "errors. Run `npm install` from this checkout's root.",
+    );
+  }
+}
+
+export async function ensureBuilt() {
+  if (!(await shouldBuildDist())) {
+    return;
+  }
+
+  const lockHandle = await acquireBuildLock();
+  if (!lockHandle) {
+    return;
+  }
+
+  try {
+    if (!(await shouldBuildDist())) {
+      return;
+    }
+    await runBuild(npmExecutable(), ['run', 'build']);
+  } finally {
+    await releaseBuildLock(lockHandle);
+  }
+}