ast-mcp-server 0.7.1 → 0.8.0

package/dist/services/agent-setup.js

@@ -1,10 +1,15 @@
 import { spawn } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
 import { access, realpath, stat } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
-import { installBundledSkill, SkillConflictError, } from "./skill-installer.js";
-import { AGENT_IDS, getAgentTarget, MCP_SERVER_NAME, } from "./agent-targets.js";
+import { randomUUID } from "node:crypto";
+import { planBundledSkillInstallation, SkillConflictError, } from "./skill-installer.js";
+import { planManagedGuidance, } from "./managed-guidance.js";
+import { applyManagedFilePlan, createManagedFileApplyContext, ManagedFileApplyError, ManagedFileRollbackError, revalidateManagedFilePlan, verifyManagedFilePostimage, } from "./managed-file.js";
+import { AGENT_IDS, classifyAgentVersion, getAgentTarget, MCP_SERVER_NAME, } from "./agent-targets.js";
+import { applyOpenCodeConfigPlan, planOpenCodeConfig, resolveOpenCodeConfigPath, withIsolatedOpenCodeConfig, } from "./opencode-config.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
 export class AgentSetupError extends Error {
@@ -17,6 +22,87 @@ export class AgentSetupError extends Error {
         this.details = details;
     }
 }
+export async function applyManagedAssetPlans(skillPlan, guidancePlan, context = createManagedFileApplyContext(), hooks = {}) {
+    const physicalWrites = [];
+    const possiblyCommitted = [];
+    const rolledBack = [];
+    const rollbackFailed = [];
+    const authenticated = [];
+    let activePlan;
+    try {
+        for (const file of [...skillPlan.files, ...guidancePlan.files]) {
+            await revalidateManagedFilePlan(file);
+        }
+        const plans = [
+            ...skillPlan.files.map((file) => ({ file, asset: "skill" })),
+            ...guidancePlan.files.map((file) => ({ file, asset: "guidance" })),
+        ];
+        for (const { file, asset } of plans) {
+            activePlan = { file, asset };
+            for (const current of authenticated) {
+                await verifyManagedFilePostimage(current, context);
+            }
+            await applyManagedFilePlan(file, context, hooks);
+            authenticated.push(file);
+            if (file.status !== "unchanged") {
+                physicalWrites.push({ path: file.path, asset, status: file.status });
+            }
+            activePlan = undefined;
+        }
+        for (const current of authenticated) {
+            await verifyManagedFilePostimage(current, context);
+        }
+        return physicalWrites;
+    }
+    catch (error) {
+        if (activePlan !== undefined && activePlan.file.status !== "unchanged") {
+            const write = {
+                path: activePlan.file.path,
+                asset: activePlan.asset,
+                status: activePlan.file.status,
+            };
+            if (error instanceof ManagedFileRollbackError) {
+                rolledBack.push(write);
+            }
+            else if (error instanceof ManagedFileApplyError) {
+                if (error.commitState === "committed") {
+                    physicalWrites.push(write);
+                }
+                else {
+                    possiblyCommitted.push(write);
+                }
+                if (error.rollbackState === "failed") {
+                    rollbackFailed.push(write);
+                }
+            }
+        }
+        throw new AgentSetupError(error instanceof Error ? error.message : "Managed asset apply failed.", "AGENT_ASSET_APPLY_FAILED", {
+            completed_writes: physicalWrites,
+            possibly_committed: possiblyCommitted,
+            rolled_back: rolledBack,
+            rollback_failed: rollbackFailed,
+            pending: [
+                ...skillPlan.files
+                    .filter((file) => file.status !== "unchanged")
+                    .map((file) => ({ path: file.path, asset: "skill", status: file.status })),
+                ...guidancePlan.files
+                    .filter((file) => file.status !== "unchanged")
+                    .map((file) => ({ path: file.path, asset: "guidance", status: file.status })),
+            ].filter((pending) => !physicalWrites.some((completed) => completed.path === pending.path && completed.asset === pending.asset) &&
+                !possiblyCommitted.some((uncertain) => uncertain.path === pending.path && uncertain.asset === pending.asset)),
+        });
+    }
+}
+async function verifyManagedAssetPlans(skillPlan, guidancePlan, context) {
+    try {
+        for (const file of [...skillPlan.files, ...guidancePlan.files]) {
+            await verifyManagedFilePostimage(file, context);
+        }
+    }
+    catch (error) {
+        throw new AgentSetupError(error instanceof Error ? error.message : "Managed asset postimage verification failed.", "AGENT_ASSET_APPLY_FAILED", { cause: error instanceof Error ? error.message : String(error) });
+    }
+}
 function environmentPath(environment) {
     return environment.PATH ?? environment.Path ?? environment.path ?? "";
 }
@@ -76,7 +162,7 @@ async function runCommand(executable, args, options) {
         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 }));
+                finishWithError(new AgentSetupError(`Agent command exceeded ${MAX_COMMAND_OUTPUT_BYTES} output bytes.`, "AGENT_COMMAND_OUTPUT_LIMIT"));
                 return;
             }
             if (target === "stdout") {
@@ -87,15 +173,12 @@ async function runCommand(executable, args, options) {
             }
         };
         const timeout = setTimeout(() => {
-            finishWithError(new AgentSetupError(`Agent command timed out after ${options.timeoutMs}ms.`, "AGENT_COMMAND_TIMEOUT", { executable, args }));
+            finishWithError(new AgentSetupError(`Agent command timed out after ${options.timeoutMs}ms.`, "AGENT_COMMAND_TIMEOUT"));
         }, 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("error", () => {
+            finishWithError(new AgentSetupError("Failed to start the agent command.", "AGENT_COMMAND_START"));
         });
         child.on("close", (exitCode) => {
             if (settled) {
@@ -109,8 +192,7 @@ async function runCommand(executable, args, options) {
     });
 }
 function commandFailure(agent, operation, result) {
-    const output = `${result.stdout}\n${result.stderr}`.trim().slice(0, 4000);
-    return new AgentSetupError(`${getAgentTarget(agent).label} ${operation} failed with exit code ${result.exitCode}.`, "AGENT_COMMAND_FAILED", { agent, operation, output });
+    return new AgentSetupError(`${getAgentTarget(agent).label} ${operation} failed with exit code ${result.exitCode}.`, "AGENT_COMMAND_FAILED", { agent, operation, reason: `Command exited with code ${result.exitCode}.` });
 }
 function targetRuntime(detection, environment, timeoutMs) {
     return {
@@ -136,6 +218,33 @@ async function inspectMcp(agent, detection, serverEntryPath, nodeExecutable, env
         ...(inspection.detail ? { detail: inspection.detail } : {}),
     };
 }
+async function verifyOpenCode(detection, environment, timeoutMs, context) {
+    await withIsolatedOpenCodeConfig(environment, environment.HOME ?? os.homedir(), async (isolatedEnvironment) => {
+        const runtime = targetRuntime(detection, isolatedEnvironment, timeoutMs);
+        const resolved = await runtime.run(["debug", "config", "--pure"]);
+        if (resolved.exitCode !== 0)
+            throw commandFailure("opencode", "resolved configuration verification", resolved);
+        let config;
+        try {
+            config = JSON.parse(resolved.stdout);
+        }
+        catch {
+            throw new AgentSetupError("OpenCode resolved configuration output is unknown.", "AGENT_VERIFICATION_FAILED", { agent: "opencode" });
+        }
+        const command = config?.mcp?.ast?.command;
+        if (!Array.isArray(command) ||
+            command.length !== 2 ||
+            command[0] !== context.nodeExecutable ||
+            command[1] !== context.serverEntryPath) {
+            throw new AgentSetupError("OpenCode resolved configuration does not contain the expected ast server.", "AGENT_VERIFICATION_FAILED", { agent: "opencode" });
+        }
+        const listed = await runtime.run(["mcp", "list", "--pure"]);
+        const plainList = listed.stdout.replaceAll("\u001b", "");
+        if (listed.exitCode !== 0 || !/ast[\s\S]*connected/i.test(plainList)) {
+            throw new AgentSetupError("OpenCode did not report the ast server as connected.", "AGENT_VERIFICATION_FAILED", { agent: "opencode" });
+        }
+    });
+}
 async function configureMcp(agent, detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
     const target = getAgentTarget(agent);
     const added = await target.mcp.register(targetRuntime(detection, environment, timeoutMs), {
@@ -175,7 +284,12 @@ export async function detectInstalledAgents(options = {}) {
         const definition = getAgentTarget(id);
         const executable = await findExecutable(definition.command, environment);
         if (executable === undefined) {
-            return { id, label: definition.label, installed: false };
+            return {
+                id,
+                label: definition.label,
+                installed: false,
+                compatibility: { status: "unavailable", reason: "Not found in PATH." },
+            };
         }
         let version;
         try {
@@ -191,10 +305,17 @@ export async function detectInstalledAgents(options = {}) {
         catch {
             version = undefined;
         }
-        return { id, label: definition.label, installed: true, executable, version };
+        const compatibility = version === undefined
+            ? {
+                status: "incompatible",
+                reason: "Version command did not produce admitted evidence.",
+            }
+            : classifyAgentVersion(id, version);
+        return { id, label: definition.label, installed: true, executable, version, compatibility };
     }));
 }
 export async function runAgentSetup(options) {
+    const correlationId = randomUUID();
     const environment = options.environment ?? process.env;
     const nodeExecutable = options.nodeExecutable ?? process.execPath;
     const timeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
@@ -208,42 +329,137 @@ export async function runAgentSetup(options) {
         if (!detection?.installed || detection.executable === undefined) {
             throw new AgentSetupError(`${getAgentTarget(agent).label} is not installed or is not available in PATH.`, "AGENT_NOT_INSTALLED", { agent });
         }
+        if (detection.compatibility && detection.compatibility.status !== "compatible") {
+            throw new AgentSetupError(`${getAgentTarget(agent).label} is incompatible: ${detection.compatibility.reason}`, detection.compatibility.status === "blocked_untrusted_folder"
+                ? "AGENT_TRUST_REQUIRED"
+                : "AGENT_INCOMPATIBLE", { agent, correlation_id: correlationId });
+        }
     }
     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)));
+    let openCodePlan;
+    if (requested.includes("opencode")) {
+        openCodePlan = await planOpenCodeConfig({
+            filePath: resolveOpenCodeConfigPath(environment, environment.HOME ?? os.homedir()),
+            nodeExecutable,
+            serverEntryPath: options.serverEntryPath,
+        }).catch((error) => {
+            throw new AgentSetupError(error instanceof Error ? error.message : "OpenCode configuration preflight failed.", "AGENT_MCP_CONFLICT", { agent: "opencode", correlation_id: correlationId });
+        });
+        const effective = await withIsolatedOpenCodeConfig(environment, environment.HOME ?? os.homedir(), (isolatedEnvironment) => targetRuntime(detectionMap.get("opencode"), isolatedEnvironment, timeoutMs).run([
+            "debug",
+            "config",
+            "--pure",
+        ]));
+        if (effective.exitCode !== 0) {
+            throw new AgentSetupError(`OpenCode effective configuration preflight failed with exit code ${effective.exitCode}.`, "AGENT_MCP_CONFLICT", { agent: "opencode", correlation_id: correlationId });
+        }
+        let effectiveConfig;
+        try {
+            effectiveConfig = JSON.parse(effective.stdout);
+        }
+        catch {
+            throw new AgentSetupError("OpenCode effective configuration output is unknown.", "AGENT_MCP_CONFLICT", { agent: "opencode", correlation_id: correlationId });
+        }
+        const effectiveAst = effectiveConfig?.mcp?.ast;
+        const desiredAst = {
+            type: "local",
+            command: [nodeExecutable, options.serverEntryPath],
+            enabled: true,
+        };
+        if (effectiveAst !== undefined && JSON.stringify(effectiveAst) !== JSON.stringify(desiredAst)) {
+            throw new AgentSetupError("OpenCode effective configuration conflict at mcp.ast.", "AGENT_MCP_CONFLICT", { agent: "opencode", correlation_id: correlationId });
+        }
+        if (effectiveAst !== undefined && openCodePlan.status === "installed") {
+            openCodePlan = { ...openCodePlan, status: "unchanged" };
+        }
+    }
+    const inspections = await Promise.all(requested.map((agent) => agent === "opencode"
+        ? Promise.resolve({
+            agent,
+            status: openCodePlan?.status === "unchanged" ? "current" : "missing",
+        })
+        : 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 ${getAgentTarget(conflict.agent).label} MCP registration: ${conflict.detail}`, "AGENT_MCP_CONFLICT", { agent: conflict.agent });
     }
-    const skillTarget = requested.length === AGENT_IDS.length ? "all" : getAgentTarget(requested[0]).skillTarget;
-    const skillResult = await installBundledSkill({
-        target: skillTarget,
-        scope: "user",
-        force: options.forceSkill ?? false,
-        sourceSkillPath: options.sourceSkillPath,
-        environment,
-    }).catch((error) => {
+    const blocked = inspections.find((item) => item.status === "blocked_untrusted_folder");
+    if (blocked !== undefined) {
+        throw new AgentSetupError(`${getAgentTarget(blocked.agent).label} requires the working folder to be trusted before setup.`, "AGENT_TRUST_REQUIRED", { agent: blocked.agent, correlation_id: correlationId });
+    }
+    let skillPlan;
+    try {
+        skillPlan = await planBundledSkillInstallation({
+            target: requested,
+            scope: "user",
+            force: options.forceSkill ?? false,
+            sourceSkillPath: options.sourceSkillPath,
+            releaseManifestPath: options.releaseManifestPath,
+            environment,
+            homeDirectory: environment.HOME ?? os.homedir(),
+        });
+    }
+    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]));
+        throw new AgentSetupError(error instanceof Error ? error.message : "Skill preflight failed.", "SETUP_ASSET_INVALID", { asset: "skill", correlation_id: correlationId });
+    }
+    let guidancePlan;
+    try {
+        guidancePlan = await planManagedGuidance({
+            agents: requested,
+            sourceGuidancePath: options.sourceGuidancePath,
+            environment,
+            homeDirectory: environment.HOME ?? os.homedir(),
+        });
+    }
+    catch (error) {
+        throw new AgentSetupError(error instanceof Error ? error.message : "Managed guidance preflight failed.", "AGENT_GUIDANCE_CONFLICT", { asset: "guidance", correlation_id: correlationId });
+    }
+    const skillStatuses = new Map(skillPlan.installations.map((installation) => [installation.target, installation.status]));
+    const guidanceStatuses = new Map(guidancePlan.installations.map((installation) => [installation.agent, installation.status]));
+    const applyContext = createManagedFileApplyContext();
+    const physicalWrites = await applyManagedAssetPlans(skillPlan, guidancePlan, applyContext);
     const completed = [];
     for (const agent of requested) {
         const detection = detectionMap.get(agent);
         const inspection = inspections.find((item) => item.agent === agent);
         try {
+            await verifyManagedAssetPlans(skillPlan, guidancePlan, applyContext);
             if (inspection.status === "missing") {
-                await configureMcp(agent, detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
+                if (agent === "opencode") {
+                    await applyOpenCodeConfigPlan(openCodePlan);
+                    if (openCodePlan.status === "installed") {
+                        physicalWrites.push({
+                            path: openCodePlan.filePath,
+                            asset: "mcp_config",
+                            status: "installed",
+                        });
+                    }
+                    await verifyOpenCode(detection, environment, timeoutMs, {
+                        nodeExecutable,
+                        serverEntryPath: options.serverEntryPath,
+                    });
+                }
+                else
+                    await configureMcp(agent, detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
+            }
+            else if (agent === "opencode") {
+                await verifyOpenCode(detection, environment, timeoutMs, {
+                    nodeExecutable,
+                    serverEntryPath: options.serverEntryPath,
+                });
             }
+            await verifyManagedAssetPlans(skillPlan, guidancePlan, applyContext);
             completed.push({
                 agent,
                 executable: detection.executable,
                 version: detection.version,
                 mcp: inspection.status === "current" ? "unchanged" : "configured",
                 skill: skillStatuses.get(agent),
+                guidance: guidanceStatuses.get(agent),
             });
         }
         catch (error) {
@@ -251,16 +467,21 @@ export async function runAgentSetup(options) {
                 throw new AgentSetupError(error.message, error.code, {
                     cause: error.details,
                     completed,
-                    skills: skillResult.installations,
+                    skills: skillPlan.installations,
+                    guidance: guidancePlan.installations,
+                    completed_writes: physicalWrites,
                 });
             }
             throw error;
         }
     }
     return {
+        version: 2,
         status: "ok",
         command: "setup",
         server: { name: MCP_SERVER_NAME, command: nodeExecutable, args: [options.serverEntryPath] },
         agents: completed,
+        correlation_id: correlationId,
+        physical_writes: physicalWrites,
     };
 }