ast-mcp-server 0.3.0

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("ast-mcp-server running over stdio.");
+}
+main().catch((error) => {
+    console.error("Fatal ast-mcp-server error:", error);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,28 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerApplyOperation } from "./tools/apply_operation.js";
+import { registerFindReferences } from "./tools/find_references.js";
+import { registerGetDiagnostics } from "./tools/get_diagnostics.js";
+import { registerGetOperationPreview } from "./tools/get_operation_preview.js";
+import { registerGetOutline } from "./tools/get_outline.js";
+import { registerGetSymbolSource } from "./tools/get_symbol_source.js";
+import { registerListFiles } from "./tools/list_files.js";
+import { registerRenameSymbol } from "./tools/rename_symbol.js";
+import { registerReplaceSymbolBody } from "./tools/replace_symbol_body.js";
+import { registerSearchSymbols } from "./tools/search_symbols.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "ast-mcp-server",
+        version: "0.3.0",
+    });
+    registerListFiles(server);
+    registerGetOutline(server);
+    registerGetSymbolSource(server);
+    registerSearchSymbols(server);
+    registerFindReferences(server);
+    registerGetDiagnostics(server);
+    registerRenameSymbol(server);
+    registerReplaceSymbolBody(server);
+    registerGetOperationPreview(server);
+    registerApplyOperation(server);
+    return server;
+}

package/dist/services/agent-setup.js

@@ -0,0 +1,346 @@
+import { spawn } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { installBundledSkill, SkillConflictError, } from "./skill-installer.js";
+import { AGENT_IDS } from "./setup-wizard.js";
+const MCP_SERVER_NAME = "ast";
+const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
+const EXPECTED_HERMES_TOOLS = [
+    "ast_list_files",
+    "ast_get_outline",
+    "ast_get_symbol_source",
+    "ast_search_symbols",
+    "ast_find_references",
+    "ast_get_diagnostics",
+    "ast_rename_symbol",
+    "ast_replace_symbol_body",
+    "ast_get_operation_preview",
+    "ast_apply_operation",
+];
+const AGENT_DEFINITIONS = {
+    claude: { label: "Claude Code", command: "claude" },
+    hermes: { label: "Hermes", command: "hermes" },
+};
+export class AgentSetupError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.name = "AgentSetupError";
+        this.code = code;
+        this.details = details;
+    }
+}
+function environmentPath(environment) {
+    return environment.PATH ?? environment.Path ?? environment.path ?? "";
+}
+async function isExecutableFile(candidate) {
+    try {
+        const candidateStat = await stat(candidate);
+        if (!candidateStat.isFile()) {
+            return false;
+        }
+        if (process.platform !== "win32") {
+            await access(candidate, fsConstants.X_OK);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findExecutable(command, environment) {
+    const extensions = process.platform === "win32"
+        ? (environment.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)
+        : [""];
+    for (const directory of environmentPath(environment).split(path.delimiter)) {
+        if (directory === "") {
+            continue;
+        }
+        for (const extension of extensions) {
+            const candidate = path.resolve(directory, `${command}${extension}`);
+            if (await isExecutableFile(candidate)) {
+                return realpath(candidate);
+            }
+        }
+    }
+    return undefined;
+}
+async function runCommand(executable, args, options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, args, {
+            env: options.environment,
+            shell: false,
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let outputBytes = 0;
+        let settled = false;
+        const finishWithError = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            child.kill("SIGKILL");
+            reject(error);
+        };
+        const appendOutput = (target, chunk) => {
+            outputBytes += chunk.byteLength;
+            if (outputBytes > MAX_COMMAND_OUTPUT_BYTES) {
+                finishWithError(new AgentSetupError(`Agent command exceeded ${MAX_COMMAND_OUTPUT_BYTES} output bytes.`, "AGENT_COMMAND_OUTPUT_LIMIT", { executable, args }));
+                return;
+            }
+            if (target === "stdout") {
+                stdout += chunk.toString("utf8");
+            }
+            else {
+                stderr += chunk.toString("utf8");
+            }
+        };
+        const timeout = setTimeout(() => {
+            finishWithError(new AgentSetupError(`Agent command timed out after ${options.timeoutMs}ms.`, "AGENT_COMMAND_TIMEOUT", { executable, args }));
+        }, options.timeoutMs);
+        child.stdout.on("data", (chunk) => appendOutput("stdout", chunk));
+        child.stderr.on("data", (chunk) => appendOutput("stderr", chunk));
+        child.on("error", (error) => {
+            finishWithError(new AgentSetupError(`Failed to start ${executable}: ${error.message}`, "AGENT_COMMAND_START", {
+                executable,
+                args,
+            }));
+        });
+        child.on("close", (exitCode) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            resolve({ exitCode: exitCode ?? 1, stdout, stderr });
+        });
+        child.stdin.end(options.input);
+    });
+}
+function commandFailure(agent, operation, result) {
+    const output = `${result.stdout}\n${result.stderr}`.trim().slice(0, 4000);
+    return new AgentSetupError(`${AGENT_DEFINITIONS[agent].label} ${operation} failed with exit code ${result.exitCode}.`, "AGENT_COMMAND_FAILED", { agent, operation, output });
+}
+function isMissingClaudeMcp(output) {
+    return (/\bno\s+mcp\s+server\b/i.test(output) &&
+        /(?:\bfound\b|\bnamed?\b)/i.test(output) &&
+        /\bast\b/i.test(output));
+}
+async function inspectClaudeMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
+    const result = await runCommand(detection.executable, ["mcp", "get", MCP_SERVER_NAME], {
+        environment,
+        timeoutMs,
+    });
+    const output = `${result.stdout}\n${result.stderr}`;
+    if (result.exitCode !== 0) {
+        if (isMissingClaudeMcp(output)) {
+            return { agent: "claude", status: "missing" };
+        }
+        throw commandFailure("claude", "MCP inspection", result);
+    }
+    const fields = new Map();
+    for (const line of result.stdout.split(/\r?\n/)) {
+        const match = line.match(/^\s*(Status|Type|Command|Args):\s*(.*)$/i);
+        if (match !== null) {
+            fields.set(match[1].toLowerCase(), match[2].trim());
+        }
+    }
+    const current = /connected/i.test(fields.get("status") ?? "") &&
+        fields.get("type")?.toLowerCase() === "stdio" &&
+        fields.get("command") === nodeExecutable &&
+        fields.get("args") === serverEntryPath;
+    return current
+        ? { agent: "claude", status: "current" }
+        : {
+            agent: "claude",
+            status: "conflict",
+            detail: "The existing user-scoped 'ast' registration does not match this package.",
+        };
+}
+async function inspectHermesMcp(detection, environment, timeoutMs) {
+    const listed = await runCommand(detection.executable, ["mcp", "list"], {
+        environment,
+        timeoutMs,
+    });
+    if (listed.exitCode !== 0) {
+        throw commandFailure("hermes", "MCP list", listed);
+    }
+    if (!/^\s*ast(?:\s|$)/im.test(listed.stdout)) {
+        return { agent: "hermes", status: "missing" };
+    }
+    const tested = await runCommand(detection.executable, ["mcp", "test", MCP_SERVER_NAME], {
+        environment,
+        timeoutMs,
+    });
+    const current = tested.exitCode === 0 && EXPECTED_HERMES_TOOLS.every((tool) => tested.stdout.includes(tool));
+    return current
+        ? { agent: "hermes", status: "current" }
+        : {
+            agent: "hermes",
+            status: "conflict",
+            detail: "The existing 'ast' registration does not expose the expected structural tools.",
+        };
+}
+async function inspectMcp(agent, detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
+    return agent === "claude"
+        ? inspectClaudeMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs)
+        : inspectHermesMcp(detection, environment, timeoutMs);
+}
+async function configureClaudeMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
+    const added = await runCommand(detection.executable, [
+        "mcp",
+        "add",
+        "--scope",
+        "user",
+        "--transport",
+        "stdio",
+        MCP_SERVER_NAME,
+        "--",
+        nodeExecutable,
+        serverEntryPath,
+    ], { environment, timeoutMs });
+    if (added.exitCode !== 0) {
+        throw commandFailure("claude", "MCP registration", added);
+    }
+    const verified = await inspectClaudeMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs);
+    if (verified.status !== "current") {
+        throw new AgentSetupError("Claude Code saved the MCP registration but verification did not match.", "AGENT_VERIFICATION_FAILED", { agent: "claude", inspection: verified });
+    }
+}
+async function configureHermesMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
+    const added = await runCommand(detection.executable, ["mcp", "add", MCP_SERVER_NAME, "--command", nodeExecutable, "--args", serverEntryPath], { environment, timeoutMs, input: "\n" });
+    if (added.exitCode !== 0 || !/saved\s+'ast'/i.test(added.stdout)) {
+        throw commandFailure("hermes", "MCP registration", added);
+    }
+    const verified = await inspectHermesMcp(detection, environment, timeoutMs);
+    if (verified.status !== "current") {
+        throw new AgentSetupError("Hermes saved the MCP registration but verification did not expose the expected tools.", "AGENT_VERIFICATION_FAILED", { agent: "hermes", inspection: verified });
+    }
+}
+async function assertRegularFile(filePath, label) {
+    let fileStat;
+    try {
+        fileStat = await stat(filePath);
+    }
+    catch (error) {
+        throw new AgentSetupError(`${label} does not exist: ${filePath}`, "SETUP_ARTIFACT_MISSING", {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (!fileStat.isFile()) {
+        throw new AgentSetupError(`${label} is not a regular file: ${filePath}`, "SETUP_ARTIFACT_INVALID");
+    }
+}
+export async function resolveServerEntryPath(cliExecutablePath) {
+    const resolvedCli = await realpath(cliExecutablePath);
+    return path.join(path.dirname(resolvedCli), "index.js");
+}
+export async function detectInstalledAgents(options = {}) {
+    const environment = options.environment ?? process.env;
+    const timeoutMs = options.commandTimeoutMs ?? 5000;
+    return Promise.all(AGENT_IDS.map(async (id) => {
+        const definition = AGENT_DEFINITIONS[id];
+        const executable = await findExecutable(definition.command, environment);
+        if (executable === undefined) {
+            return { id, label: definition.label, installed: false };
+        }
+        let version;
+        try {
+            const result = await runCommand(executable, ["--version"], {
+                environment,
+                timeoutMs,
+            });
+            version = `${result.stdout}\n${result.stderr}`
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .find(Boolean);
+        }
+        catch {
+            version = undefined;
+        }
+        return { id, label: definition.label, installed: true, executable, version };
+    }));
+}
+export async function runAgentSetup(options) {
+    const environment = options.environment ?? process.env;
+    const nodeExecutable = options.nodeExecutable ?? process.execPath;
+    const timeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+    const requested = AGENT_IDS.filter((agent) => options.agents.includes(agent));
+    if (requested.length === 0) {
+        throw new AgentSetupError("At least one agent must be selected.", "SETUP_NO_AGENTS");
+    }
+    const detectionMap = new Map(options.detections.map((item) => [item.id, item]));
+    for (const agent of requested) {
+        const detection = detectionMap.get(agent);
+        if (!detection?.installed || detection.executable === undefined) {
+            throw new AgentSetupError(`${AGENT_DEFINITIONS[agent].label} is not installed or is not available in PATH.`, "AGENT_NOT_INSTALLED", { agent });
+        }
+    }
+    await assertRegularFile(options.serverEntryPath, "MCP server entrypoint");
+    await assertRegularFile(options.sourceSkillPath, "Bundled skill");
+    const inspections = await Promise.all(requested.map((agent) => inspectMcp(agent, detectionMap.get(agent), options.serverEntryPath, nodeExecutable, environment, timeoutMs)));
+    const conflict = inspections.find((item) => item.status === "conflict");
+    if (conflict !== undefined) {
+        throw new AgentSetupError(`Conflicting ${AGENT_DEFINITIONS[conflict.agent].label} MCP registration: ${conflict.detail}`, "AGENT_MCP_CONFLICT", { agent: conflict.agent });
+    }
+    const skillTarget = requested.length === 2 ? "all" : requested[0];
+    const skillResult = await installBundledSkill({
+        target: skillTarget,
+        scope: "user",
+        force: options.forceSkill ?? false,
+        sourceSkillPath: options.sourceSkillPath,
+        environment,
+    }).catch((error) => {
+        if (error instanceof SkillConflictError) {
+            throw new AgentSetupError(`Skill already exists with different content at ${error.destination}; pass --force-skill to replace it.`, "AGENT_SKILL_CONFLICT", { path: error.destination });
+        }
+        throw error;
+    });
+    const skillStatuses = new Map(skillResult.installations.map((installation) => [installation.target, installation.status]));
+    const completed = [];
+    for (const agent of requested) {
+        const detection = detectionMap.get(agent);
+        const inspection = inspections.find((item) => item.agent === agent);
+        try {
+            if (inspection.status === "missing") {
+                if (agent === "claude") {
+                    await configureClaudeMcp(detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
+                }
+                else {
+                    await configureHermesMcp(detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
+                }
+            }
+            completed.push({
+                agent,
+                executable: detection.executable,
+                version: detection.version,
+                mcp: inspection.status === "current" ? "unchanged" : "configured",
+                skill: skillStatuses.get(agent),
+            });
+        }
+        catch (error) {
+            if (error instanceof AgentSetupError) {
+                throw new AgentSetupError(error.message, error.code, {
+                    cause: error.details,
+                    completed,
+                    skills: skillResult.installations,
+                });
+            }
+            throw error;
+        }
+    }
+    return {
+        status: "ok",
+        command: "setup",
+        server: { name: MCP_SERVER_NAME, command: nodeExecutable, args: [options.serverEntryPath] },
+        agents: completed,
+    };
+}

package/dist/services/diagnostics.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { DiagnosticCategory, ts } from "ts-morph";
+export function normalizeDiagnostic(diagnostic, projectRoot) {
+    const sourceFile = diagnostic.getSourceFile();
+    const start = diagnostic.getStart();
+    const location = sourceFile && start !== undefined ? sourceFile.getLineAndColumnAtPos(start) : undefined;
+    return {
+        code: diagnostic.getCode(),
+        category: DiagnosticCategory[diagnostic.getCategory()] ?? String(diagnostic.getCategory()),
+        file: sourceFile ? path.relative(projectRoot, sourceFile.getFilePath()) : null,
+        line: location?.line ?? null,
+        column: location?.column ?? null,
+        message: ts.flattenDiagnosticMessageText(diagnostic.compilerObject.messageText, "\n"),
+    };
+}
+function identity(diagnostic) {
+    return JSON.stringify([
+        diagnostic.code,
+        diagnostic.category,
+        diagnostic.file,
+        diagnostic.message,
+    ]);
+}
+function subtract(candidates, baseline) {
+    const counts = new Map();
+    for (const diagnostic of baseline) {
+        const key = identity(diagnostic);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const difference = [];
+    for (const diagnostic of candidates) {
+        const key = identity(diagnostic);
+        const remaining = counts.get(key) ?? 0;
+        if (remaining > 0) {
+            counts.set(key, remaining - 1);
+        }
+        else {
+            difference.push(diagnostic);
+        }
+    }
+    return difference;
+}
+export function compareDiagnostics(before, after) {
+    const added = subtract(after, before);
+    const removed = subtract(before, after);
+    return {
+        added,
+        removed,
+        addedErrors: added.filter((diagnostic) => diagnostic.category === "Error"),
+    };
+}

package/dist/services/operation-plan-file.js

@@ -0,0 +1,191 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, open, realpath, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { applyOperation, configureOperationApply, exportOperationRecord, importOperationRecord, } from "./operations.js";
+import { ensurePrivateDirectory, resolveRuntimeStateDirectory, } from "./runtime-state.js";
+export const PLAN_SCHEMA_VERSION = 1;
+export const MAX_PLAN_BYTES = 50 * 1024 * 1024;
+const HashSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const IsoDateSchema = z.string().datetime({ offset: true });
+const DiagnosticSchema = z
+    .object({
+    code: z.number().int(),
+    category: z.string(),
+    file: z.string().nullable(),
+    line: z.number().int().positive().nullable(),
+    column: z.number().int().positive().nullable(),
+    message: z.string(),
+})
+    .strict();
+const DiagnosticDeltaSchema = z
+    .object({
+    added: z.array(DiagnosticSchema),
+    removed: z.array(DiagnosticSchema),
+    addedErrors: z.array(DiagnosticSchema),
+})
+    .strict();
+const AffectedFileSchema = z
+    .object({
+    file: z.string().min(1),
+    original_hash: HashSchema,
+    updated_hash: HashSchema,
+})
+    .strict();
+const PersistedFileSchema = AffectedFileSchema.extend({
+    original_bytes_base64: z.string(),
+    updated_bytes_base64: z.string(),
+    mode: z.number().int().nonnegative(),
+}).strict();
+const PersistedOperationSchema = z
+    .object({
+    operation_id: z.string().uuid(),
+    plan_hash: HashSchema,
+    kind: z.enum(["rename_symbol", "replace_symbol_body"]),
+    status: z.enum(["prepared", "applied"]),
+    project_root: z.string().min(1),
+    created_at: IsoDateSchema,
+    expires_at: IsoDateSchema,
+    affected_files: z.array(AffectedFileSchema).min(1),
+    reference_count: z.number().int().nonnegative(),
+    workspace_hash: HashSchema,
+    post_workspace_hash: HashSchema,
+    workspace_file_count: z.number().int().positive(),
+    diagnostics: DiagnosticDeltaSchema,
+    allow_new_errors: z.boolean(),
+    blocked: z.boolean(),
+    block_reason: z.string().nullable(),
+    preview: z.string().nullable(),
+    preview_truncated: z.boolean(),
+    applied_at: IsoDateSchema.optional(),
+    files: z.array(PersistedFileSchema).min(1),
+})
+    .strict();
+const PlanEnvelopeSchema = z
+    .object({
+    schema_version: z.literal(PLAN_SCHEMA_VERSION),
+    operation: PersistedOperationSchema,
+})
+    .strict();
+function stateDirectory(options) {
+    return resolveRuntimeStateDirectory(options);
+}
+async function syncDirectory(directory) {
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function atomicWritePlan(planFile, envelope) {
+    const directory = path.dirname(planFile);
+    await ensurePrivateDirectory(directory);
+    const serialized = `${JSON.stringify(envelope)}\n`;
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes > MAX_PLAN_BYTES) {
+        throw new Error(`Persisted plan is ${bytes} bytes; maximum is ${MAX_PLAN_BYTES}.`);
+    }
+    const temporaryPath = path.join(directory, `.${path.basename(planFile)}.${randomUUID()}.tmp`);
+    const handle = await open(temporaryPath, "wx", 0o600);
+    try {
+        await handle.writeFile(serialized, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporaryPath, planFile);
+        if (process.platform !== "win32")
+            await chmod(planFile, 0o600);
+        await syncDirectory(directory);
+    }
+    catch (error) {
+        await unlink(temporaryPath).catch(() => undefined);
+        throw error;
+    }
+}
+async function readPlanEnvelope(planFileInput) {
+    const planFile = path.resolve(planFileInput);
+    const flags = process.platform === "win32" ? constants.O_RDONLY : constants.O_RDONLY | constants.O_NOFOLLOW;
+    const handle = await open(planFile, flags);
+    try {
+        const fileStat = await handle.stat();
+        if (!fileStat.isFile())
+            throw new Error(`Plan path is not a regular file: ${planFile}`);
+        const canonicalPlanFile = await realpath(planFile);
+        const samePath = process.platform === "win32"
+            ? canonicalPlanFile.toLowerCase() === planFile.toLowerCase()
+            : canonicalPlanFile === planFile;
+        if (!samePath) {
+            throw new Error(`Plan path must not traverse symbolic links: ${planFile}`);
+        }
+        if (process.platform !== "win32" && fileStat.nlink !== 1) {
+            throw new Error(`Plan file must have exactly one hard link: ${planFile}`);
+        }
+        const uid = process.getuid?.();
+        if (uid !== undefined && fileStat.uid !== uid) {
+            throw new Error(`Plan file is not owned by the current user: ${planFile}`);
+        }
+        if (fileStat.size > MAX_PLAN_BYTES) {
+            throw new Error(`Persisted plan is ${fileStat.size} bytes; maximum is ${MAX_PLAN_BYTES}.`);
+        }
+        if (process.platform !== "win32" && (fileStat.mode & 0o077) !== 0) {
+            throw new Error(`Plan file permissions are too broad; expected 0600: ${planFile}`);
+        }
+        const serialized = await handle.readFile({ encoding: "utf8" });
+        const parsed = PlanEnvelopeSchema.parse(JSON.parse(serialized));
+        return { planFile, envelope: parsed };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function persistOperationPlan(operationId, options = {}) {
+    const plansDirectory = path.join(stateDirectory(options), "plans");
+    const planFile = path.join(plansDirectory, `${operationId}.astplan`);
+    await atomicWritePlan(planFile, {
+        schema_version: PLAN_SCHEMA_VERSION,
+        operation: exportOperationRecord(operationId),
+    });
+    return planFile;
+}
+export async function applyPersistedOperation(planFileInput, planHash, options = {}) {
+    if (!/^[a-f0-9]{64}$/.test(planHash)) {
+        throw new Error("plan_hash must be a 64-character lowercase SHA-256 digest.");
+    }
+    const current = await readPlanEnvelope(planFileInput);
+    const operationId = current.envelope.operation.operation_id;
+    importOperationRecord(current.envelope.operation, planHash);
+    configureOperationApply(operationId, {
+        stateDirectory: options.stateDirectory,
+        receiptWriter: async () => {
+            await atomicWritePlan(current.planFile, {
+                schema_version: PLAN_SCHEMA_VERSION,
+                operation: exportOperationRecord(operationId),
+            });
+        },
+    });
+    return applyOperation(operationId, planHash);
+}
+export async function inspectPersistedPlan(planFileInput) {
+    const { envelope } = await readPlanEnvelope(planFileInput);
+    const operation = envelope.operation;
+    return {
+        schema_version: PLAN_SCHEMA_VERSION,
+        operation_id: operation.operation_id,
+        plan_hash: operation.plan_hash,
+        status: operation.status,
+        project_root: operation.project_root,
+        created_at: operation.created_at,
+        expires_at: operation.expires_at,
+        affected_files: operation.affected_files,
+        blocked: operation.blocked,
+        block_reason: operation.block_reason,
+        preview: operation.preview,
+        preview_truncated: operation.preview_truncated,
+    };
+}