ast-mcp-server 0.7.2 → 0.8.1

package/dist/services/managed-guidance.js

@@ -0,0 +1,229 @@
+import { readFile, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { applyManagedFilePlan, canonicalizeFuturePath, captureManagedFilePreimage, createManagedFileApplyContext, hashBytes, verifyManagedFilePostimage, } from "./managed-file.js";
+const BEGIN_MARKER = "<!-- ast-tool:structural-code-editing guidance v1 begin -->";
+const END_MARKER = "<!-- ast-tool:structural-code-editing guidance v1 end -->";
+const MARKER_NAMESPACE = "ast-tool:structural-code-editing guidance";
+function configured(value, fallback, cwd) {
+    return path.resolve(cwd, value ?? fallback);
+}
+async function regularFileSize(filePath) {
+    try {
+        const info = await stat(filePath);
+        if (!info.isFile())
+            throw new Error(`Guidance source is not a regular file: ${filePath}`);
+        return info.size;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+function openCodeConfigRoot(environment, home, cwd) {
+    if (environment.OPENCODE_CONFIG) {
+        return path.dirname(path.resolve(cwd, environment.OPENCODE_CONFIG));
+    }
+    if (environment.OPENCODE_CONFIG_DIR) {
+        return path.resolve(cwd, environment.OPENCODE_CONFIG_DIR);
+    }
+    return path.join(home, ".config", "opencode");
+}
+function safeGeminiContextFilename(value) {
+    const candidate = typeof value === "string"
+        ? value
+        : Array.isArray(value) && value.length === 1 && typeof value[0] === "string"
+            ? value[0]
+            : undefined;
+    if (candidate === undefined) {
+        throw new Error("Gemini context.fileName routing is ambiguous or unsupported.");
+    }
+    if (candidate.length === 0 ||
+        path.isAbsolute(candidate) ||
+        candidate !== path.basename(candidate) ||
+        candidate === "." ||
+        candidate === "..") {
+        throw new Error("Gemini context.fileName must be one safe filename.");
+    }
+    return candidate;
+}
+async function geminiGuidancePath(home) {
+    const root = path.join(home, ".gemini");
+    const settingsPath = path.join(root, "settings.json");
+    let settingsText;
+    try {
+        settingsText = await readFile(settingsPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return path.join(root, "GEMINI.md");
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(settingsText);
+    }
+    catch {
+        throw new Error("Gemini settings.json is not valid JSON.");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("Gemini settings.json must contain an object.");
+    }
+    const context = parsed.context;
+    if (context === undefined)
+        return path.join(root, "GEMINI.md");
+    if (typeof context !== "object" || context === null || Array.isArray(context)) {
+        throw new Error("Gemini context settings are unsupported.");
+    }
+    const fileName = context.fileName;
+    if (fileName === undefined)
+        return path.join(root, "GEMINI.md");
+    return path.join(root, safeGeminiContextFilename(fileName));
+}
+async function resolveDestinations(options) {
+    const environment = options.environment ?? process.env;
+    const home = options.homeDirectory ?? os.homedir();
+    const cwd = options.workingDirectory ?? process.cwd();
+    const selected = new Set(options.agents);
+    const claudePath = path.join(configured(environment.CLAUDE_CONFIG_DIR, path.join(home, ".claude"), cwd), "CLAUDE.md");
+    const result = [];
+    for (const agent of options.agents) {
+        if (agent === "hermes" || agent === "copilot") {
+            result.push({ agent });
+            continue;
+        }
+        if (agent === "claude") {
+            result.push({ agent, path: claudePath });
+            continue;
+        }
+        if (agent === "opencode") {
+            const nativePath = path.join(openCodeConfigRoot(environment, home, cwd), "AGENTS.md");
+            if ((await regularFileSize(nativePath)) !== undefined) {
+                result.push({ agent, path: nativePath });
+                continue;
+            }
+            const fallbackSize = await regularFileSize(claudePath);
+            if (fallbackSize !== undefined && selected.has("claude")) {
+                result.push({ agent, path: claudePath });
+            }
+            else if (fallbackSize !== undefined) {
+                result.push({ agent, path: nativePath, seed: await readFile(claudePath) });
+            }
+            else {
+                result.push({ agent, path: nativePath });
+            }
+            continue;
+        }
+        if (agent === "codex") {
+            const root = configured(environment.CODEX_HOME, path.join(home, ".codex"), cwd);
+            const override = path.join(root, "AGENTS.override.md");
+            result.push({
+                agent,
+                path: (await regularFileSize(override)) ? override : path.join(root, "AGENTS.md"),
+            });
+            continue;
+        }
+        result.push({ agent, path: await geminiGuidancePath(home) });
+    }
+    return Promise.all(result.map(async (item) => "path" in item ? { ...item, path: await canonicalizeFuturePath(item.path) } : item));
+}
+function decodeUtf8(content, destination) {
+    const bom = content.subarray(0, 3).equals(Buffer.from([0xef, 0xbb, 0xbf]))
+        ? content.subarray(0, 3)
+        : Buffer.alloc(0);
+    const body = content.subarray(bom.length);
+    if (body.includes(0))
+        throw new Error(`Guidance destination contains NUL bytes: ${destination}`);
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(body);
+    return { bom, text };
+}
+function newlineFor(text) {
+    return text.includes("\r\n") ? "\r\n" : "\n";
+}
+function canonicalBlock(guidance, newline) {
+    const normalized = guidance.replaceAll("\r\n", "\n").replaceAll("\r", "\n").trimEnd();
+    return [BEGIN_MARKER, normalized, END_MARKER].join(newline);
+}
+function postimageFor(content, guidance, destination) {
+    const { bom, text } = decodeUtf8(content, destination);
+    const newline = newlineFor(text);
+    const block = canonicalBlock(guidance, newline);
+    const namespaceCount = text.split(MARKER_NAMESPACE).length - 1;
+    const begins = text.split(BEGIN_MARKER).length - 1;
+    const ends = text.split(END_MARKER).length - 1;
+    if (namespaceCount === 0) {
+        const separator = text.length === 0 ? "" : text.endsWith(newline) ? newline : `${newline}${newline}`;
+        return Buffer.concat([bom, Buffer.from(`${text}${separator}${block}${newline}`, "utf8")]);
+    }
+    if (namespaceCount !== 2 || begins !== 1 || ends !== 1) {
+        throw new Error(`Guidance destination contains malformed or unsupported managed markers: ${destination}`);
+    }
+    const begin = text.indexOf(BEGIN_MARKER);
+    const end = text.indexOf(END_MARKER);
+    if (begin < 0 || end < begin) {
+        throw new Error(`Guidance destination contains malformed managed markers: ${destination}`);
+    }
+    const afterEnd = end + END_MARKER.length;
+    return Buffer.concat([
+        bom,
+        Buffer.from(`${text.slice(0, begin)}${block}${text.slice(afterEnd)}`, "utf8"),
+    ]);
+}
+export async function planManagedGuidance(options) {
+    const guidancePath = path.resolve(options.sourceGuidancePath);
+    if ((await regularFileSize(guidancePath)) === undefined) {
+        throw new Error(`Bundled guidance is missing: ${guidancePath}`);
+    }
+    const guidanceBuffer = await readFile(guidancePath);
+    const { text: guidance } = decodeUtf8(guidanceBuffer, guidancePath);
+    if (guidance.trim().length === 0 || guidance.includes(MARKER_NAMESPACE)) {
+        throw new Error("Bundled guidance must be non-empty and marker-free.");
+    }
+    const destinations = await resolveDestinations(options);
+    const filesByPath = new Map();
+    const installations = [];
+    for (const destination of destinations) {
+        if (!("path" in destination)) {
+            installations.push({ agent: destination.agent, status: "skill_only" });
+            continue;
+        }
+        let file = filesByPath.get(destination.path);
+        if (file === undefined) {
+            const captured = await captureManagedFilePreimage(destination.path);
+            const snapshot = captured.snapshot;
+            const preimage = snapshot.exists ? captured.content : (destination.seed ?? Buffer.alloc(0));
+            const postimage = postimageFor(preimage, guidance, destination.path);
+            const postimageSha256 = hashBytes(postimage);
+            const status = !snapshot.exists
+                ? "installed"
+                : snapshot.sha256 === postimageSha256
+                    ? "unchanged"
+                    : "updated";
+            file = { path: destination.path, snapshot, postimage, postimageSha256, status };
+            filesByPath.set(destination.path, file);
+        }
+        else if (destination.seed !== undefined) {
+            const seededPostimage = postimageFor(destination.seed, guidance, destination.path);
+            if (!seededPostimage.equals(file.postimage)) {
+                throw new Error(`Guidance aliases require incompatible postimages: ${destination.path}`);
+            }
+        }
+        installations.push({ agent: destination.agent, path: destination.path, status: file.status });
+    }
+    return { installations, files: [...filesByPath.values()] };
+}
+export async function applyManagedGuidancePlan(plan, onApplied, context = createManagedFileApplyContext(), hooks = {}) {
+    const authenticated = [];
+    for (const file of plan.files) {
+        for (const current of authenticated) {
+            await verifyManagedFilePostimage(current, context);
+        }
+        await applyManagedFilePlan(file, context, hooks);
+        authenticated.push(file);
+        await onApplied?.(file);
+    }
+    for (const current of authenticated) {
+        await verifyManagedFilePostimage(current, context);
+    }
+}

package/dist/services/opencode-config.js

@@ -0,0 +1,135 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { applyEdits, modify, parse } from "jsonc-parser";
+function hash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function resolveOpenCodeConfigPath(environment, homeDirectory) {
+    if (environment.OPENCODE_CONFIG)
+        return path.resolve(environment.OPENCODE_CONFIG);
+    if (environment.OPENCODE_CONFIG_DIR)
+        return path.resolve(environment.OPENCODE_CONFIG_DIR, "opencode.json");
+    return path.join(homeDirectory, ".config", "opencode", "opencode.json");
+}
+export async function withIsolatedOpenCodeConfig(environment, homeDirectory, operation) {
+    const selectedConfig = resolveOpenCodeConfigPath(environment, homeDirectory);
+    const routedDirectory = path.resolve(environment.OPENCODE_CONFIG_DIR ?? path.join(homeDirectory, ".config", "opencode"));
+    const routedConfig = path.join(routedDirectory, "opencode.json");
+    const readConfig = async (filePath) => {
+        try {
+            return await readFile(filePath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return "{}\n";
+            throw error;
+        }
+    };
+    const temporaryRoot = await mkdtemp(path.join(os.tmpdir(), "ast-opencode-preflight-"));
+    const temporaryRoutedDirectory = path.join(temporaryRoot, "config-dir");
+    const temporaryRoutedConfig = path.join(temporaryRoutedDirectory, "opencode.json");
+    const selectedAndRoutedAreSame = selectedConfig === routedConfig;
+    const temporarySelectedConfig = selectedAndRoutedAreSame
+        ? temporaryRoutedConfig
+        : path.join(temporaryRoot, "selected", path.basename(selectedConfig));
+    try {
+        await mkdir(path.dirname(temporarySelectedConfig), { recursive: true });
+        await mkdir(temporaryRoutedDirectory, { recursive: true });
+        await writeFile(temporarySelectedConfig, await readConfig(selectedConfig), {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        if (!selectedAndRoutedAreSame) {
+            await writeFile(temporaryRoutedConfig, await readConfig(routedConfig), {
+                encoding: "utf8",
+                flag: "wx",
+                mode: 0o600,
+            });
+        }
+        return await operation({
+            ...environment,
+            OPENCODE_CONFIG: temporarySelectedConfig,
+            OPENCODE_CONFIG_DIR: temporaryRoutedDirectory,
+        });
+    }
+    finally {
+        await rm(temporaryRoot, { recursive: true, force: true });
+    }
+}
+export async function planOpenCodeConfig(options) {
+    let before = "{}\n";
+    let beforeExists = true;
+    let mode = 0o600;
+    try {
+        before = await readFile(options.filePath, "utf8");
+        mode = (await stat(options.filePath)).mode & 0o777;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            beforeExists = false;
+        else
+            throw error;
+    }
+    const parseErrors = [];
+    const parsed = parse(before, parseErrors);
+    if (parseErrors.length > 0) {
+        throw new Error("OpenCode configuration is not parseable JSON/JSONC.");
+    }
+    if (!parsed || typeof parsed !== "object")
+        throw new Error("OpenCode configuration must contain an object.");
+    const desired = {
+        type: "local",
+        command: [options.nodeExecutable, options.serverEntryPath],
+        enabled: true,
+    };
+    if (parsed.mcp?.ast !== undefined && JSON.stringify(parsed.mcp.ast) !== JSON.stringify(desired))
+        throw new Error("OpenCode configuration conflict at mcp.ast.");
+    const content = parsed.mcp?.ast === undefined
+        ? applyEdits(before, modify(before, ["mcp", "ast"], desired, {
+            formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" },
+        }))
+        : before;
+    return {
+        filePath: options.filePath,
+        beforeHash: hash(beforeExists ? before : ""),
+        beforeExists,
+        mode,
+        content,
+        status: content === before ? "unchanged" : "installed",
+    };
+}
+export async function applyOpenCodeConfigPlan(plan) {
+    if (plan.status === "unchanged")
+        return;
+    let current = "";
+    let exists = true;
+    try {
+        current = await readFile(plan.filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            exists = false;
+        else
+            throw error;
+    }
+    if (exists !== plan.beforeExists || hash(current) !== plan.beforeHash)
+        throw new Error("OpenCode configuration changed concurrently; no file was replaced.");
+    const directory = path.dirname(plan.filePath);
+    await mkdir(directory, { recursive: true });
+    const temporary = path.join(directory, `.${path.basename(plan.filePath)}.${randomUUID()}.tmp`);
+    await writeFile(temporary, plan.content, { encoding: "utf8", flag: "wx", mode: plan.mode });
+    try {
+        if (!plan.beforeExists) {
+            await link(temporary, plan.filePath);
+            await rm(temporary);
+        }
+        else
+            await rename(temporary, plan.filePath);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/services/raw-tty.js

@@ -0,0 +1,75 @@
+import { createCheckboxState, reduceCheckboxState, } from "./checkbox-state.js";
+function render(state) {
+    const lines = state.choices.map((choice, index) => {
+        const focus = index === state.focus ? "❯" : " ";
+        const marker = choice.checked ? "◉" : "◯";
+        const reason = choice.enabled ? "" : ` — ${choice.reason ?? "unavailable"}`;
+        return `${focus} ${marker} ${choice.label}${reason}`;
+    });
+    return `\u001b[2J\u001b[HSelect agents (↑/↓ move, Space toggle, Enter continue, Esc cancel)\n${lines.join("\n")}${state.validation ? `\n${state.validation}` : ""}`;
+}
+function keyAction(bytes) {
+    const value = bytes.toString("utf8");
+    if (value === "\u001b[A")
+        return "up";
+    if (value === "\u001b[B")
+        return "down";
+    if (value === " ")
+        return "toggle";
+    if (value === "\r" || value === "\n")
+        return "submit";
+    if (value === "\u001b" || value === "\u0003")
+        return "cancel";
+    return undefined;
+}
+export function runRawCheckbox(options) {
+    return new Promise((resolve) => {
+        const signals = options.signals ?? process;
+        const initialRaw = options.input.isRaw === true;
+        let state = createCheckboxState(options.choices);
+        let settled = false;
+        const cleanup = () => {
+            if (settled)
+                return;
+            settled = true;
+            options.input.off("data", onData);
+            options.input.off("error", onError);
+            signals.off("SIGINT", onSignal);
+            signals.off("SIGTERM", onSignal);
+            options.input.setRawMode(initialRaw);
+            options.input.pause();
+            options.output.write("\u001b[?25h");
+        };
+        const finish = (selection) => {
+            cleanup();
+            resolve(selection);
+        };
+        const onSignal = () => finish([]);
+        const onError = () => finish([]);
+        const onData = (bytes) => {
+            const action = keyAction(bytes);
+            if (!action)
+                return;
+            state = reduceCheckboxState(state, action);
+            if (state.cancelled)
+                return finish([]);
+            if (state.submitted)
+                return finish(state.submitted);
+            options.output.write(render(state));
+        };
+        options.input.setRawMode(true);
+        options.input.resume();
+        options.input.on("data", onData);
+        options.input.on("error", onError);
+        signals.on("SIGINT", onSignal);
+        signals.on("SIGTERM", onSignal);
+        try {
+            options.output.write("\u001b[?25l");
+            options.output.write(render(state));
+        }
+        catch (error) {
+            cleanup();
+            throw error;
+        }
+    });
+}

package/dist/services/setup-wizard.js

@@ -1,110 +1,62 @@
-import { AGENT_IDS, getAgentTarget } from "./agent-targets.js";
+import { AGENT_IDS, getAgentTarget, } from "./agent-targets.js";
+import { runRawCheckbox } from "./raw-tty.js";
 export { AGENT_IDS } from "./agent-targets.js";
 function isAgentId(value) {
     return AGENT_IDS.includes(value);
 }
 export function parseAgentsArgument(value) {
     const normalized = value.trim().toLowerCase();
-    if (normalized === "") {
+    if (!normalized)
         throw new Error("The --agents value cannot be empty.");
-    }
-    if (normalized === "all") {
-        return [...AGENT_IDS];
-    }
+    if (normalized === "all")
+        return { mode: "all" };
     const requested = normalized
         .split(",")
         .map((item) => item.trim())
         .filter(Boolean);
-    if (requested.length === 0) {
-        throw new Error("The --agents value cannot be empty.");
-    }
     const unsupported = requested.find((item) => !isAgentId(item));
-    if (unsupported !== undefined) {
-        throw new Error(`Unsupported agent: ${unsupported}. Expected claude, hermes, or all.`);
-    }
+    if (unsupported)
+        throw new Error(`Unsupported agent: ${unsupported}. Expected ${AGENT_IDS.join(", ")}, or all.`);
     const selected = new Set(requested);
-    return AGENT_IDS.filter((agent) => selected.has(agent));
+    return AGENT_IDS.filter((id) => selected.has(id));
 }
-export function applyAgentDeselections(answer, detections) {
-    const installed = detections.filter((item) => item.installed);
-    const selected = new Set(installed.map((item) => item.id));
-    const normalized = answer.trim().toLowerCase();
-    if (normalized === "") {
-        return AGENT_IDS.filter((agent) => selected.has(agent));
-    }
-    if (normalized === "none") {
-        return [];
-    }
-    const tokens = normalized
-        .split(/[\s,]+/)
-        .map((item) => item.trim())
-        .filter(Boolean);
-    for (const token of tokens) {
-        let detection;
-        if (/^\d+$/.test(token)) {
-            detection = detections[Number(token) - 1];
-        }
-        else if (isAgentId(token)) {
-            detection = detections.find((item) => item.id === token);
-        }
-        if (detection === undefined) {
-            throw new Error(`Invalid selection: ${token}.`);
-        }
-        if (!detection.installed) {
-            throw new Error(`${detection.label} is not installed.`);
-        }
-        selected.delete(detection.id);
-    }
-    return AGENT_IDS.filter((agent) => selected.has(agent));
+function usability(detection) {
+    if (!detection.installed)
+        return {
+            usable: false,
+            reason: detection.compatibility?.status === "unavailable"
+                ? detection.compatibility.reason
+                : "Not found in PATH.",
+        };
+    if (!detection.compatibility || detection.compatibility.status === "compatible")
+        return { usable: true };
+    return { usable: false, reason: detection.compatibility.reason };
 }
-function renderSelectionQuestion(detections, validationMessage) {
-    const choices = detections
-        .map((item, index) => {
-        const marker = item.installed ? "x" : " ";
-        const detail = item.installed
-            ? [item.version, item.executable].filter(Boolean).join(" · ")
-            : "not installed";
-        return `  [${marker}] ${index + 1}. ${getAgentTarget(item.id).label} (${detail})`;
-    })
-        .join("\n");
-    const validation = validationMessage === undefined ? "" : `\n${validationMessage}\n`;
-    return `\nDetected agents (all installed agents are selected):\n${choices}\n${validation}\nEnter agents to deselect by number or name, 'none' to deselect all, or press Enter to keep all:\n> `;
+export function resolveAgentSelection(request, detections) {
+    const byId = new Map(detections.map((item) => [item.id, item]));
+    const ids = Array.isArray(request) ? request : AGENT_IDS.filter((id) => byId.get(id)?.installed);
+    for (const id of ids) {
+        const detection = byId.get(id);
+        const result = detection
+            ? usability(detection)
+            : { usable: false, reason: "Detection result is missing." };
+        if (!result.usable)
+            throw new Error(`${getAgentTarget(id).label}: ${result.reason}`);
+    }
+    return AGENT_IDS.filter((id) => ids.includes(id));
 }
-function renderConfirmation(agents, validationMessage) {
-    const labels = agents.map((agent) => getAgentTarget(agent).label).join(", ");
-    const validation = validationMessage === undefined ? "" : `\n${validationMessage}\n`;
-    return `${validation}\nSetup will install the MCP server and skill for: ${labels}.\nContinue? [Y/n] `;
-}
-export async function promptForAgentSelection(detections, ask) {
-    if (!detections.some((item) => item.installed)) {
-        throw new Error("No supported agents were detected in PATH.");
-    }
-    let selected;
-    let selectionError;
-    while (true) {
-        const answer = await ask(renderSelectionQuestion(detections, selectionError));
-        try {
-            selected = applyAgentDeselections(answer, detections);
-            break;
-        }
-        catch (error) {
-            selectionError = error instanceof Error ? error.message : String(error);
-        }
-    }
-    if (selected.length === 0) {
-        return [];
-    }
-    let confirmationError;
-    while (true) {
-        const answer = (await ask(renderConfirmation(selected, confirmationError)))
-            .trim()
-            .toLowerCase();
-        if (answer === "" || answer === "y" || answer === "yes") {
-            return selected;
-        }
-        if (answer === "n" || answer === "no") {
-            return [];
-        }
-        confirmationError = "Enter y or n.";
-    }
+export async function promptForAgentSelection(detections, options) {
+    return runRawCheckbox({
+        ...options,
+        choices: detections.map((item) => {
+            const result = usability(item);
+            return {
+                id: item.id,
+                label: item.label,
+                enabled: result.usable,
+                checked: result.usable,
+                ...(result.reason ? { reason: result.reason } : {}),
+            };
+        }),
+    });
 }