auditor-lambda 0.2.5 → 0.2.8

package/dist/mcp/server.js

@@ -0,0 +1,579 @@
+import { readFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadArtifactBundle } from "../io/artifacts.js";
+import { readOptionalTextFile } from "../io/json.js";
+import { deriveAuditState } from "../orchestrator/state.js";
+import { decideNextStep } from "../orchestrator/nextStep.js";
+import { buildAuditCodeHandoff, } from "../supervisor/operatorHandoff.js";
+import { readSessionConfigFile } from "../supervisor/sessionConfig.js";
+import { resolveFreshSessionProviderName } from "../providers/index.js";
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(moduleDir, "..", "..");
+const wrapperPath = join(packageRoot, "audit-code.mjs");
+const packageJsonPath = join(packageRoot, "package.json");
+const PROTOCOL_VERSION = "2025-06-18";
+function getFlag(argv, name) {
+    const index = argv.indexOf(name);
+    if (index < 0)
+        return undefined;
+    return argv[index + 1];
+}
+function hasValue(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function parseServerOptions(argv) {
+    const root = resolve(getFlag(argv, "--root") ?? ".");
+    const artifactsDir = resolve(getFlag(argv, "--artifacts-dir") ?? join(root, ".audit-artifacts"));
+    return { root, artifactsDir };
+}
+function parseObject(value) {
+    return value && typeof value === "object"
+        ? value
+        : {};
+}
+function getToolContext(params, defaults) {
+    const root = hasValue(params?.root)
+        ? resolve(params.root)
+        : defaults.root;
+    const artifactsDir = hasValue(params?.artifacts_dir)
+        ? resolve(params.artifacts_dir)
+        : hasValue(params?.artifactsDir)
+            ? resolve(params.artifactsDir)
+            : defaults.artifactsDir;
+    return { root, artifactsDir };
+}
+async function packageVersion() {
+    const parsed = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    return parsed.version ?? "0.0.0";
+}
+function writeMessage(payload) {
+    const body = Buffer.from(JSON.stringify(payload), "utf8");
+    const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "utf8");
+    process.stdout.write(header);
+    process.stdout.write(body);
+}
+function success(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function failure(id, code, message, data) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code,
+            message,
+            data,
+        },
+    };
+}
+async function runWrapperCommand(args, options) {
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [
+            wrapperPath,
+            ...args,
+            "--root",
+            options.root,
+            "--artifacts-dir",
+            options.artifactsDir,
+        ], {
+            cwd: options.root,
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", rejectPromise);
+        child.on("exit", (code) => {
+            resolvePromise({
+                code: code ?? 1,
+                stdout,
+                stderr,
+            });
+        });
+    });
+}
+async function parseCliJson(args, options, allowNonZero = false) {
+    const result = await runWrapperCommand(args, options);
+    const combined = result.stdout.trim() || result.stderr.trim();
+    if (!allowNonZero && result.code !== 0) {
+        throw new Error(combined || `Command failed with exit code ${result.code}.`);
+    }
+    if (combined.length === 0) {
+        throw new Error("Command completed without JSON output.");
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        try {
+            return JSON.parse(result.stderr);
+        }
+        catch {
+            throw new Error(combined);
+        }
+    }
+}
+async function getStatusPayload(context) {
+    const bundle = await loadArtifactBundle(context.artifactsDir);
+    const decision = decideNextStep(bundle);
+    const auditState = bundle.audit_state ?? deriveAuditState(bundle);
+    const rawSessionConfig = await readSessionConfigFile(context.artifactsDir);
+    const providerName = rawSessionConfig && typeof rawSessionConfig === "object"
+        ? resolveFreshSessionProviderName(undefined, rawSessionConfig)
+        : null;
+    const handoff = buildAuditCodeHandoff({
+        root: context.root,
+        artifactsDir: context.artifactsDir,
+        state: auditState,
+        bundle,
+        providerName,
+        progressSummary: "Current artifact and handoff status.",
+    });
+    return {
+        repo_root: context.root,
+        artifacts_dir: context.artifactsDir,
+        audit_state: auditState,
+        selected_obligation: decision.selected_obligation,
+        selected_executor: decision.selected_executor,
+        next_likely_step: auditState.status === "complete" ? null : decision.selected_obligation,
+        handoff,
+    };
+}
+function asTextContent(value) {
+    return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+}
+function toolResult(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: asTextContent(value),
+            },
+        ],
+        structuredContent: value && typeof value === "object" ? value : { value },
+    };
+}
+async function readResource(uri, context) {
+    switch (uri) {
+        case "audit-code://artifacts/current": {
+            const bundle = await loadArtifactBundle(context.artifactsDir);
+            return {
+                mimeType: "application/json",
+                text: JSON.stringify(bundle, null, 2),
+            };
+        }
+        case "audit-code://handoff/current": {
+            const status = (await getStatusPayload(context)).handoff;
+            return {
+                mimeType: "application/json",
+                text: JSON.stringify(status, null, 2),
+            };
+        }
+        case "audit-code://install/guide": {
+            const path = join(context.root, ".audit-code", "install", "GETTING-STARTED.md");
+            const guide = (await readOptionalTextFile(path)) ??
+                "Run `audit-code install` from the repository root to generate the repo-local setup guide.";
+            return {
+                mimeType: "text/markdown",
+                text: guide,
+            };
+        }
+        case "audit-code://report/current": {
+            const report = (await readOptionalTextFile(join(context.artifactsDir, "audit-report.md"))) ??
+                (await readOptionalTextFile(join(context.root, "audit-report.md"))) ??
+                "The audit report has not been rendered yet.";
+            return {
+                mimeType: "text/markdown",
+                text: report,
+            };
+        }
+        default:
+            throw new Error(`Unknown resource URI: ${uri}`);
+    }
+}
+function promptDefinitions() {
+    return [
+        {
+            name: "audit-code",
+            description: "Start or continue the autonomous audit loop through the auditor MCP tools.",
+            arguments: [],
+        },
+        {
+            name: "review-task",
+            description: "Inspect one audit task with explain_task and the current artifacts before reviewing code.",
+            arguments: [
+                {
+                    name: "task_id",
+                    required: true,
+                    description: "Audit task id to inspect.",
+                },
+            ],
+        },
+        {
+            name: "synthesize-report",
+            description: "Read the current audit report resource and summarize the highest-signal findings.",
+            arguments: [],
+        },
+    ];
+}
+function renderPrompt(name, args) {
+    switch (name) {
+        case "audit-code":
+            return [
+                "Use the auditor MCP tools as the primary interface to the backend wrapper.",
+                "1. Call `start_audit`.",
+                "2. If the audit is blocked, inspect `audit-code://handoff/current` and `audit-code://artifacts/current`.",
+                "3. When the user provides additional evidence, call `import_results` or `import_runtime_updates`.",
+                "4. Call `continue_audit` until the status is complete or explicitly blocked for operator input.",
+            ].join("\n");
+        case "review-task":
+            return [
+                `Use \`explain_task\` for task \`${String(args?.task_id ?? "")}\` before you inspect code manually.`,
+                "Then read `audit-code://artifacts/current` and use the task scope to review the relevant files.",
+            ].join("\n");
+        case "synthesize-report":
+            return [
+                "Read `audit-code://report/current`.",
+                "Summarize the final audit report as work blocks first, then highlight the most important risks and remediation priorities.",
+            ].join("\n");
+        default:
+            throw new Error(`Unknown prompt: ${name}`);
+    }
+}
+async function handleToolCall(name, params, defaults) {
+    const context = getToolContext(params, defaults);
+    switch (name) {
+        case "start_audit":
+            return toolResult(await parseCliJson([], context));
+        case "continue_audit":
+            return toolResult(await parseCliJson([], context));
+        case "get_status":
+            return toolResult(await getStatusPayload(context));
+        case "explain_task": {
+            if (!hasValue(params?.task_id) && !hasValue(params?.taskId)) {
+                throw new Error("explain_task requires task_id.");
+            }
+            const taskId = hasValue(params?.task_id)
+                ? params.task_id
+                : params?.taskId;
+            return toolResult(await parseCliJson(["explain-task", taskId], context));
+        }
+        case "validate_artifacts":
+            return toolResult(await parseCliJson(["validate"], context, true));
+        case "import_results": {
+            if (!hasValue(params?.results_path) && !hasValue(params?.resultsPath)) {
+                throw new Error("import_results requires results_path.");
+            }
+            const resultsPath = hasValue(params?.results_path)
+                ? params.results_path
+                : params?.resultsPath;
+            return toolResult(await parseCliJson(["--results", resolve(resultsPath)], context));
+        }
+        case "import_runtime_updates": {
+            if (!hasValue(params?.updates_path) && !hasValue(params?.updatesPath)) {
+                throw new Error("import_runtime_updates requires updates_path.");
+            }
+            const updatesPath = hasValue(params?.updates_path)
+                ? params.updates_path
+                : params?.updatesPath;
+            return toolResult(await parseCliJson(["--updates", resolve(updatesPath)], context));
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+function toolDefinitions() {
+    return [
+        {
+            name: "start_audit",
+            description: "Start the audit wrapper and advance until completion or blocked operator handoff.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    root: { type: "string", description: "Repository root override." },
+                    artifacts_dir: {
+                        type: "string",
+                        description: "Artifacts directory override.",
+                    },
+                },
+            },
+        },
+        {
+            name: "get_status",
+            description: "Inspect the current artifact bundle and operator handoff without mutating state.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    root: { type: "string", description: "Repository root override." },
+                    artifacts_dir: {
+                        type: "string",
+                        description: "Artifacts directory override.",
+                    },
+                },
+            },
+        },
+        {
+            name: "continue_audit",
+            description: "Continue the audit wrapper from the current artifacts directory.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    root: { type: "string", description: "Repository root override." },
+                    artifacts_dir: {
+                        type: "string",
+                        description: "Artifacts directory override.",
+                    },
+                },
+            },
+        },
+        {
+            name: "explain_task",
+            description: "Resolve a task id into coverage scope, matching findings, and pending work.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: {
+                        type: "string",
+                        description: "Task id to explain.",
+                    },
+                    root: { type: "string", description: "Repository root override." },
+                    artifacts_dir: {
+                        type: "string",
+                        description: "Artifacts directory override.",
+                    },
+                },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "validate_artifacts",
+            description: "Validate the current artifact bundle plus provider/session-config readiness.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    root: { type: "string", description: "Repository root override." },
+                    artifacts_dir: {
+                        type: "string",
+                        description: "Artifacts directory override.",
+                    },
+                },
+            },
+        },
+        {
+            name: "import_results",
+            description: "Import structured audit results into the same backend wrapper flow.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    results_path: {
+                        type: "string",
+                        description: "Path to an AuditResult JSON payload.",
+                    },
+                    root: { type: "string", description: "Repository root override." },
+                    artifacts_dir: {
+                        type: "string",
+                        description: "Artifacts directory override.",
+                    },
+                },
+                required: ["results_path"],
+            },
+        },
+        {
+            name: "import_runtime_updates",
+            description: "Import runtime validation evidence updates into the backend wrapper flow.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    updates_path: {
+                        type: "string",
+                        description: "Path to a runtime validation update JSON payload.",
+                    },
+                    root: { type: "string", description: "Repository root override." },
+                    artifacts_dir: {
+                        type: "string",
+                        description: "Artifacts directory override.",
+                    },
+                },
+                required: ["updates_path"],
+            },
+        },
+    ];
+}
+export async function runAuditCodeMcpServer(argv) {
+    const defaults = parseServerOptions(argv);
+    const version = await packageVersion();
+    let shutdownRequested = false;
+    let buffer = Buffer.alloc(0);
+    process.stdin.on("data", async (chunk) => {
+        buffer = Buffer.concat([buffer, chunk]);
+        while (true) {
+            const separator = buffer.indexOf("\r\n\r\n");
+            if (separator < 0) {
+                return;
+            }
+            const headerBlock = buffer.slice(0, separator).toString("utf8");
+            const headers = headerBlock.split("\r\n");
+            const contentLengthHeader = headers.find((header) => header.toLowerCase().startsWith("content-length:"));
+            if (!contentLengthHeader) {
+                buffer = Buffer.alloc(0);
+                writeMessage(failure(null, -32700, "Invalid MCP framing: missing Content-Length."));
+                return;
+            }
+            const contentLength = Number(contentLengthHeader.split(":")[1]?.trim());
+            const frameLength = separator + 4 + contentLength;
+            if (!Number.isFinite(contentLength) || contentLength < 0) {
+                buffer = Buffer.alloc(0);
+                writeMessage(failure(null, -32700, "Invalid MCP framing: bad Content-Length."));
+                return;
+            }
+            if (buffer.length < frameLength) {
+                return;
+            }
+            const body = buffer
+                .slice(separator + 4, frameLength)
+                .toString("utf8");
+            buffer = buffer.slice(frameLength);
+            let request;
+            try {
+                request = JSON.parse(body);
+            }
+            catch (error) {
+                writeMessage(failure(null, -32700, "Invalid JSON-RPC payload.", error instanceof Error ? error.message : String(error)));
+                continue;
+            }
+            if (!request.method) {
+                writeMessage(failure(request.id ?? null, -32600, "Missing method."));
+                continue;
+            }
+            try {
+                switch (request.method) {
+                    case "initialize":
+                        writeMessage(success(request.id ?? null, {
+                            protocolVersion: PROTOCOL_VERSION,
+                            serverInfo: {
+                                name: "audit-code",
+                                version,
+                            },
+                            instructions: "Use the audit-code MCP tools as the primary interface to the backend wrapper. Prefer start_audit, get_status, continue_audit, and the audit-code resources over ad hoc shell commands.",
+                            capabilities: {
+                                tools: { listChanged: false },
+                                resources: { subscribe: false, listChanged: false },
+                                prompts: { listChanged: false },
+                            },
+                        }));
+                        break;
+                    case "notifications/initialized":
+                        break;
+                    case "ping":
+                        if (request.id !== undefined) {
+                            writeMessage(success(request.id, {}));
+                        }
+                        break;
+                    case "tools/list":
+                        writeMessage(success(request.id ?? null, { tools: toolDefinitions() }));
+                        break;
+                    case "tools/call": {
+                        const params = parseObject(request.params);
+                        const toolName = params.name;
+                        if (!hasValue(toolName)) {
+                            throw new Error("tools/call requires a tool name.");
+                        }
+                        writeMessage(success(request.id ?? null, await handleToolCall(toolName, parseObject(params.arguments), defaults)));
+                        break;
+                    }
+                    case "resources/list":
+                        writeMessage(success(request.id ?? null, {
+                            resources: [
+                                {
+                                    uri: "audit-code://artifacts/current",
+                                    name: "current_artifacts",
+                                    description: "Current artifact bundle as JSON.",
+                                    mimeType: "application/json",
+                                },
+                                {
+                                    uri: "audit-code://handoff/current",
+                                    name: "operator_handoff",
+                                    description: "Current operator handoff payload as JSON.",
+                                    mimeType: "application/json",
+                                },
+                                {
+                                    uri: "audit-code://install/guide",
+                                    name: "install_guide",
+                                    description: "Repo-local install guide for supported IDE hosts.",
+                                    mimeType: "text/markdown",
+                                },
+                                {
+                                    uri: "audit-code://report/current",
+                                    name: "audit_report",
+                                    description: "Current deterministic audit report if available.",
+                                    mimeType: "text/markdown",
+                                },
+                            ],
+                        }));
+                        break;
+                    case "resources/read": {
+                        const params = parseObject(request.params);
+                        if (!hasValue(params.uri)) {
+                            throw new Error("resources/read requires uri.");
+                        }
+                        const resource = await readResource(params.uri, defaults);
+                        writeMessage(success(request.id ?? null, {
+                            contents: [
+                                {
+                                    uri: params.uri,
+                                    mimeType: resource.mimeType,
+                                    text: resource.text,
+                                },
+                            ],
+                        }));
+                        break;
+                    }
+                    case "prompts/list":
+                        writeMessage(success(request.id ?? null, {
+                            prompts: promptDefinitions(),
+                        }));
+                        break;
+                    case "prompts/get": {
+                        const params = parseObject(request.params);
+                        if (!hasValue(params.name)) {
+                            throw new Error("prompts/get requires name.");
+                        }
+                        writeMessage(success(request.id ?? null, {
+                            description: promptDefinitions().find((prompt) => prompt.name === params.name)?.description,
+                            messages: [
+                                {
+                                    role: "user",
+                                    content: {
+                                        type: "text",
+                                        text: renderPrompt(params.name, parseObject(params.arguments)),
+                                    },
+                                },
+                            ],
+                        }));
+                        break;
+                    }
+                    case "shutdown":
+                        shutdownRequested = true;
+                        writeMessage(success(request.id ?? null, {}));
+                        break;
+                    case "exit":
+                        process.exit(shutdownRequested ? 0 : 1);
+                        break;
+                    default:
+                        writeMessage(failure(request.id ?? null, -32601, `Unknown method: ${request.method}`));
+                }
+            }
+            catch (error) {
+                writeMessage(failure(request.id ?? null, -32000, error instanceof Error ? error.message : String(error)));
+            }
+        }
+    });
+}

package/dist/orchestrator/advance.js

@@ -1,7 +1,7 @@
 import { decideNextStep } from "./nextStep.js";
 import { deriveAuditState } from "./state.js";
 import { computeArtifactMetadata } from "./artifactMetadata.js";
-import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationUpdateExecutor, runSynthesisExecutor, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
+import { runIntakeExecutor, runStructureExecutor, runPlanningExecutor, runResultIngestionExecutor, runRuntimeValidationExecutor, runRuntimeValidationUpdateExecutor, runSynthesisExecutor, runExternalAnalyzerImportExecutor, } from "./internalExecutors.js";
 import { runAutoFixExecutor } from "./autoFixExecutor.js";
 import { runSyntaxResolutionExecutor } from "./syntaxResolutionExecutor.js";
 export async function advanceAudit(bundle, options = {}) {
@@ -37,11 +37,18 @@ export async function advanceAudit(bundle, options = {}) {
             run = runStructureExecutor(bundle);
             break;
         case "planning_executor":
-            run = runPlanningExecutor(bundle, options.lineIndex ?? {});
+            if (!options.root)
+                throw new Error("advanceAudit planning_executor requires root");
+            run = await runPlanningExecutor(bundle, options.root, options.lineIndex ?? {});
             break;
         case "result_ingestion_executor":
             run = runResultIngestionExecutor(bundle, options.auditResults ?? bundle.audit_results ?? []);
             break;
+        case "runtime_validation_executor":
+            if (!options.root)
+                throw new Error("advanceAudit runtime_validation_executor requires root");
+            run = await runRuntimeValidationExecutor(bundle, options.root);
+            break;
         case "synthesis_executor":
             run = runSynthesisExecutor(bundle, options.auditResults);
             break;

package/dist/orchestrator/dependencyMap.js

@@ -12,7 +12,7 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
-        "synthesis_report.json",
+        "audit-report.md",
     ],
     "file_disposition.json": [
         "unit_manifest.json",
@@ -26,7 +26,7 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
-        "synthesis_report.json",
+        "audit-report.md",
     ],
     "unit_manifest.json": [
         "risk_register.json",
@@ -34,13 +34,13 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "audit_tasks.json",
         "runtime_validation_tasks.json",
         "requeue_tasks.json",
-        "synthesis_report.json",
+        "audit-report.md",
     ],
     "surface_manifest.json": [
         "critical_flows.json",
         "risk_register.json",
         "runtime_validation_tasks.json",
-        "synthesis_report.json",
+        "audit-report.md",
     ],
     "critical_flows.json": [
         "flow_coverage.json",
@@ -49,7 +49,7 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
-        "synthesis_report.json",
+        "audit-report.md",
     ],
     "audit_results.jsonl": [
         "coverage_matrix.json",
@@ -57,26 +57,22 @@ export const ARTIFACT_DEPENDENCY_MAP = {
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
-        "merged_findings.json",
-        "root_cause_clusters.json",
-        "synthesis_report.json",
+        "audit-report.md",
     ],
     "coverage_matrix.json": [
         "flow_coverage.json",
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
-        "synthesis_report.json",
+        "audit-report.md",
     ],
     "flow_coverage.json": [
         "requeue_tasks.json",
         "runtime_validation_tasks.json",
         "runtime_validation_report.json",
-        "synthesis_report.json",
+        "audit-report.md",
     ],
     "runtime_validation_report.json": [
-        "merged_findings.json",
-        "root_cause_clusters.json",
-        "synthesis_report.json",
+        "audit-report.md",
     ],
 };