ast-mcp-server 0.3.0

package/dist/batch/runner.js

@@ -0,0 +1,228 @@
+import { performance } from "node:perf_hooks";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { createServer } from "../server.js";
+import { MAX_BATCH_CONTEXT_BYTES, MAX_BATCH_INVOCATIONS, MAX_BATCH_OUTPUT_BYTES, MAX_FOREACH_ITEMS, isItemTemplate, isPrepareBatchTool, isReadBatchTool, isReferenceTemplate, parseBatchDocument as parseDocument, } from "./schema.js";
+export { parseDocument as parseBatchDocument };
+export class BatchExecutionError extends Error {
+    code;
+    stepId;
+    constructor(message, code, stepId, options) {
+        super(message, options);
+        this.code = code;
+        this.stepId = stepId;
+        this.name = "BatchExecutionError";
+    }
+}
+function decodePointerSegment(segment) {
+    if (/~(?![01])/.test(segment)) {
+        throw new BatchExecutionError(`Invalid JSON Pointer escape in segment "${segment}".`, "INVALID_REFERENCE");
+    }
+    return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+function resolvePointer(root, pointer, label) {
+    const fragment = pointer.startsWith("#") ? pointer.slice(1) : pointer;
+    if (fragment === "")
+        return root;
+    if (!fragment.startsWith("/")) {
+        throw new BatchExecutionError(`${label} must be empty or start with "/".`, "INVALID_REFERENCE");
+    }
+    let current = root;
+    for (const encodedSegment of fragment.slice(1).split("/")) {
+        const segment = decodePointerSegment(encodedSegment);
+        if (segment === "__proto__" || segment === "prototype" || segment === "constructor") {
+            throw new BatchExecutionError(`${label} contains a forbidden segment.`, "INVALID_REFERENCE");
+        }
+        if ((typeof current !== "object" || current === null) && !Array.isArray(current)) {
+            throw new BatchExecutionError(`${label} does not resolve to an object value.`, "MISSING_REFERENCE");
+        }
+        if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+            throw new BatchExecutionError(`${label} does not contain segment "${segment}".`, "MISSING_REFERENCE");
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function resolveTemplate(value, context, item) {
+    if (isReferenceTemplate(value)) {
+        return resolvePointer(context, value.$ref, `$ref ${value.$ref}`);
+    }
+    if (isItemTemplate(value)) {
+        if (item === undefined) {
+            throw new BatchExecutionError("$item is unavailable outside foreach.", "INVALID_ITEM_REFERENCE");
+        }
+        return resolvePointer(item, value.$item, `$item ${value.$item}`);
+    }
+    if (Array.isArray(value))
+        return value.map((child) => resolveTemplate(child, context, item));
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, resolveTemplate(child, context, item)]));
+    }
+    return value;
+}
+function injectProjectRoot(resolved, projectRoot, step) {
+    if (typeof resolved !== "object" || resolved === null || Array.isArray(resolved)) {
+        throw new BatchExecutionError(`Step "${step.id}" input must resolve to an object.`, "INVALID_STEP_INPUT", step.id);
+    }
+    const input = resolved;
+    if (Object.prototype.hasOwnProperty.call(input, "project_root") &&
+        input.project_root !== projectRoot) {
+        throw new BatchExecutionError(`Step "${step.id}" resolves a conflicting project_root.`, "PROJECT_ROOT_CONFLICT", step.id);
+    }
+    return { ...input, project_root: projectRoot };
+}
+async function connectBatchClient() {
+    const server = createServer();
+    const client = new Client({ name: "ast-tool-batch", version: "0.3.0" });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    return { client, server };
+}
+function toolErrorMessage(result) {
+    const content = typeof result === "object" && result !== null
+        ? result.content
+        : undefined;
+    const blocks = Array.isArray(content) ? content : [];
+    const text = blocks
+        .flatMap((block) => {
+        if (typeof block === "object" &&
+            block !== null &&
+            block.type === "text" &&
+            typeof block.text === "string") {
+            return [block.text];
+        }
+        return [];
+    })
+        .join("\n");
+    return text || "Tool returned an unspecified error.";
+}
+async function callStructuredTool(client, step, input) {
+    const result = await client.callTool({ name: step.tool, arguments: input });
+    if (result.isError) {
+        throw new BatchExecutionError(`Step "${step.id}" failed: ${toolErrorMessage(result)}`, "TOOL_ERROR", step.id);
+    }
+    if (typeof result.structuredContent !== "object" ||
+        result.structuredContent === null ||
+        Array.isArray(result.structuredContent)) {
+        throw new BatchExecutionError(`Step "${step.id}" returned no structured object result.`, "INVALID_TOOL_RESULT", step.id);
+    }
+    return result.structuredContent;
+}
+async function mapLimit(items, concurrency, callback) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+        while (nextIndex < items.length) {
+            const index = nextIndex++;
+            results[index] = await callback(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+export async function runBatchDocument(document, options = {}) {
+    const startedAt = performance.now();
+    const context = { steps: Object.create(null) };
+    let invocationCount = 0;
+    let retainedContextBytes = 0;
+    const connection = options.invokeTool ? undefined : await connectBatchClient();
+    const invoke = async (step, input) => {
+        if (!options.invokeTool)
+            return callStructuredTool(connection.client, step, input);
+        const result = await options.invokeTool(step.tool, input);
+        if (!result || typeof result !== "object" || Array.isArray(result)) {
+            throw new BatchExecutionError(`Step "${step.id}" returned no structured object result.`, "INVALID_TOOL_RESULT", step.id);
+        }
+        return result;
+    };
+    const reserveInvocations = (count, step) => {
+        if (invocationCount + count > MAX_BATCH_INVOCATIONS) {
+            throw new BatchExecutionError(`Step "${step.id}" would exceed the ${MAX_BATCH_INVOCATIONS}-invocation batch limit.`, "INVOCATION_LIMIT", step.id);
+        }
+        invocationCount += count;
+    };
+    const retainResult = (result, step) => {
+        let bytes;
+        try {
+            bytes = Buffer.byteLength(JSON.stringify(result));
+        }
+        catch (error) {
+            throw new BatchExecutionError(`Step "${step.id}" returned a result that cannot be serialized as JSON.`, "INVALID_TOOL_RESULT", step.id, { cause: error });
+        }
+        if (bytes > MAX_BATCH_OUTPUT_BYTES) {
+            throw new BatchExecutionError(`Step "${step.id}" returned ${bytes} bytes; maximum per result is ${MAX_BATCH_OUTPUT_BYTES}.`, "RESULT_LIMIT", step.id);
+        }
+        retainedContextBytes += bytes;
+        if (retainedContextBytes > MAX_BATCH_CONTEXT_BYTES) {
+            throw new BatchExecutionError(`Batch retained context exceeds ${MAX_BATCH_CONTEXT_BYTES} bytes.`, "CONTEXT_LIMIT", step.id);
+        }
+    };
+    try {
+        for (const step of document.steps) {
+            if (step.foreach) {
+                if (!isReadBatchTool(step.tool)) {
+                    throw new BatchExecutionError(`Step "${step.id}" cannot expand non-read tool "${step.tool}".`, "FORBIDDEN_FOREACH_TOOL", step.id);
+                }
+                const items = resolveTemplate(step.foreach, context);
+                if (!Array.isArray(items)) {
+                    throw new BatchExecutionError(`Step "${step.id}" foreach must resolve to an array.`, "INVALID_FOREACH", step.id);
+                }
+                if (items.length > MAX_FOREACH_ITEMS) {
+                    throw new BatchExecutionError(`Step "${step.id}" expands to ${items.length} items; maximum is ${MAX_FOREACH_ITEMS}.`, "FOREACH_LIMIT", step.id);
+                }
+                reserveInvocations(items.length, step);
+                const results = await mapLimit(items, document.limits.concurrency, async (item) => {
+                    const resolved = resolveTemplate(step.input, context, item);
+                    return invoke(step, injectProjectRoot(resolved, document.project_root, step));
+                });
+                retainResult(results, step);
+                context.steps[step.id] = results;
+            }
+            else {
+                reserveInvocations(1, step);
+                const resolved = resolveTemplate(step.input, context);
+                const result = await invoke(step, injectProjectRoot(resolved, document.project_root, step));
+                if (isPrepareBatchTool(step.tool) && options.persistPreparedOperation) {
+                    const operationId = result.operation_id;
+                    if (typeof operationId !== "string") {
+                        throw new BatchExecutionError(`Prepare step "${step.id}" returned no operation_id.`, "INVALID_TOOL_RESULT", step.id);
+                    }
+                    result.plan_file = await options.persistPreparedOperation(operationId);
+                }
+                retainResult(result, step);
+                context.steps[step.id] = result;
+            }
+        }
+        const finalStep = document.steps.at(-1);
+        const projected = document.emit === undefined
+            ? context.steps[finalStep.id]
+            : resolveTemplate(document.emit, context);
+        const output = {
+            version: 1,
+            status: "ok",
+            duration_ms: performance.now() - startedAt,
+            step_count: document.steps.length,
+            invocation_count: invocationCount,
+            result: projected,
+        };
+        if (isPrepareBatchTool(finalStep.tool)) {
+            const prepared = context.steps[finalStep.id];
+            if (typeof prepared.operation_id === "string" &&
+                typeof prepared.plan_hash === "string" &&
+                typeof prepared.plan_file === "string") {
+                output.operation_id = prepared.operation_id;
+                output.plan_hash = prepared.plan_hash;
+                output.plan_file = prepared.plan_file;
+            }
+        }
+        const outputBytes = Buffer.byteLength(JSON.stringify(output));
+        if (outputBytes > MAX_BATCH_OUTPUT_BYTES) {
+            throw new BatchExecutionError(`Batch output is ${outputBytes} bytes; maximum is ${MAX_BATCH_OUTPUT_BYTES}. Narrow emit or pagination.`, "OUTPUT_LIMIT");
+        }
+        return output;
+    }
+    finally {
+        if (connection)
+            await Promise.allSettled([connection.client.close(), connection.server.close()]);
+    }
+}

package/dist/batch/schema.js

@@ -0,0 +1,159 @@
+import { z } from "zod";
+export const BATCH_SCHEMA_VERSION = 1;
+export const MAX_BATCH_STEPS = 50;
+export const MAX_BATCH_INVOCATIONS = 500;
+export const MAX_FOREACH_ITEMS = 200;
+export const DEFAULT_BATCH_CONCURRENCY = 4;
+export const MAX_BATCH_CONCURRENCY = 16;
+export const MAX_BATCH_INPUT_BYTES = 1024 * 1024;
+export const MAX_BATCH_OUTPUT_BYTES = 10 * 1024 * 1024;
+export const MAX_BATCH_CONTEXT_BYTES = 50 * 1024 * 1024;
+export const READ_BATCH_TOOLS = [
+    "ast_list_files",
+    "ast_get_outline",
+    "ast_get_symbol_source",
+    "ast_search_symbols",
+    "ast_find_references",
+    "ast_get_diagnostics",
+];
+export const PREPARE_BATCH_TOOLS = ["ast_rename_symbol", "ast_replace_symbol_body"];
+export const BATCH_TOOLS = [...READ_BATCH_TOOLS, ...PREPARE_BATCH_TOOLS];
+const BatchToolSchema = z.enum(BATCH_TOOLS);
+const BatchStepSchema = z
+    .object({
+    id: z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/),
+    tool: BatchToolSchema,
+    input: z.record(z.unknown()).default({}),
+    foreach: z
+        .object({ $ref: z.string().min(1) })
+        .strict()
+        .optional(),
+})
+    .strict();
+const BatchDocumentSchema = z
+    .object({
+    version: z.literal(BATCH_SCHEMA_VERSION),
+    project_root: z.string().min(1),
+    limits: z
+        .object({
+        concurrency: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_BATCH_CONCURRENCY)
+            .default(DEFAULT_BATCH_CONCURRENCY),
+    })
+        .strict()
+        .default({ concurrency: DEFAULT_BATCH_CONCURRENCY }),
+    steps: z.array(BatchStepSchema).min(1).max(MAX_BATCH_STEPS),
+    emit: z.unknown().optional(),
+})
+    .strict();
+function isTemplateObject(value, key) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length === 1 &&
+        typeof value[key] === "string");
+}
+function decodePointerSegment(segment) {
+    if (/~(?![01])/u.test(segment)) {
+        throw new Error(`Invalid JSON Pointer escape in segment "${segment}".`);
+    }
+    return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+function referencedStepId(pointer) {
+    if (!pointer.startsWith("#/steps/")) {
+        throw new Error(`Batch $ref must start with "#/steps/": ${pointer}`);
+    }
+    const remainder = pointer.slice("#/steps/".length);
+    const encodedId = remainder.split("/", 1)[0];
+    if (!encodedId)
+        throw new Error(`Batch $ref is missing a step id: ${pointer}`);
+    return decodePointerSegment(encodedId);
+}
+function visitTemplate(value, options) {
+    if (isTemplateObject(value, "$ref")) {
+        const id = referencedStepId(value.$ref);
+        if (!options.availableSteps.has(id)) {
+            throw new Error(`${options.location} references step "${id}" before it is available; only prior steps may be referenced.`);
+        }
+        return;
+    }
+    if (isTemplateObject(value, "$item")) {
+        if (!options.allowItem) {
+            throw new Error(`${options.location} uses $item outside a foreach step.`);
+        }
+        if (value.$item !== "" && !value.$item.startsWith("/")) {
+            throw new Error(`${options.location} $item must be an empty pointer or start with "/".`);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => visitTemplate(item, { ...options, location: `${options.location}/${index}` }));
+        return;
+    }
+    if (typeof value === "object" && value !== null) {
+        for (const [key, child] of Object.entries(value)) {
+            visitTemplate(child, { ...options, location: `${options.location}/${key}` });
+        }
+    }
+}
+export function isPrepareBatchTool(tool) {
+    return PREPARE_BATCH_TOOLS.includes(tool);
+}
+export function isReadBatchTool(tool) {
+    return READ_BATCH_TOOLS.includes(tool);
+}
+export function parseBatchDocument(input) {
+    const parsed = BatchDocumentSchema.parse(input);
+    const ids = new Set();
+    const prepareIndexes = [];
+    for (const [index, step] of parsed.steps.entries()) {
+        if (ids.has(step.id))
+            throw new Error(`Duplicate batch step id "${step.id}".`);
+        if (Object.hasOwn(step.input, "project_root")) {
+            if (step.input.project_root !== parsed.project_root) {
+                throw new Error(`Step "${step.id}" project_root conflicts with the pipeline project_root.`);
+            }
+            delete step.input.project_root;
+        }
+        if (isPrepareBatchTool(step.tool)) {
+            prepareIndexes.push(index);
+            if (step.foreach)
+                throw new Error(`Prepare step "${step.id}" cannot use foreach.`);
+        }
+        if (step.foreach) {
+            visitTemplate(step.foreach, {
+                availableSteps: ids,
+                allowItem: false,
+                location: `step "${step.id}" foreach`,
+            });
+        }
+        visitTemplate(step.input, {
+            availableSteps: ids,
+            allowItem: Boolean(step.foreach),
+            location: `step "${step.id}" input`,
+        });
+        ids.add(step.id);
+    }
+    if (prepareIndexes.length > 1)
+        throw new Error("A batch may contain at most one prepare step.");
+    if (prepareIndexes.length === 1 && prepareIndexes[0] !== parsed.steps.length - 1) {
+        throw new Error("A prepare step must be the final batch step.");
+    }
+    if (parsed.emit !== undefined) {
+        visitTemplate(parsed.emit, {
+            availableSteps: ids,
+            allowItem: false,
+            location: "emit",
+        });
+    }
+    return parsed;
+}
+export function isReferenceTemplate(value) {
+    return isTemplateObject(value, "$ref");
+}
+export function isItemTemplate(value) {
+    return isTemplateObject(value, "$item");
+}

package/dist/cli.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import process from "node:process";
+import { createInterface } from "node:readline/promises";
+import { ZodError } from "zod";
+import { BatchExecutionError, parseBatchDocument, runBatchDocument } from "./batch/runner.js";
+import { MAX_BATCH_INPUT_BYTES } from "./batch/schema.js";
+import { applyPersistedOperation, persistOperationPlan } from "./services/operation-plan-file.js";
+import { AgentSetupError, detectInstalledAgents, resolveServerEntryPath, runAgentSetup, } from "./services/agent-setup.js";
+import { installBundledSkill, resolveBundledSkillPath, } from "./services/skill-installer.js";
+import { parseAgentsArgument, promptForAgentSelection, } from "./services/setup-wizard.js";
+class CliError extends Error {
+    code;
+    exitCode;
+    command;
+    stepId;
+    details;
+    constructor(message, code, exitCode, command, stepId, options, details) {
+        super(message, options);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.command = command;
+        this.stepId = stepId;
+        this.details = details;
+        this.name = "CliError";
+    }
+}
+function usage() {
+    return [
+        "Usage:",
+        "  ast-tool run <pipeline.json|->",
+        "  ast-tool validate <pipeline.json|->",
+        "  ast-tool apply <plan.astplan> --plan-hash <sha256>",
+        "  ast-tool install-skill [claude|hermes|all] [--scope user|project] [--project-root <path>] [--force]",
+        "  ast-tool setup [--agents claude,hermes|all --yes] [--force-skill]",
+    ].join("\n");
+}
+async function readStdinBounded() {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > MAX_BATCH_INPUT_BYTES) {
+            throw new CliError(`Batch input exceeds ${MAX_BATCH_INPUT_BYTES} bytes.`, "INPUT_LIMIT", 2, null);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks);
+}
+async function readBatchInput(source) {
+    const bytes = source === "-" ? await readStdinBounded() : await readFile(source);
+    if (bytes.length > MAX_BATCH_INPUT_BYTES) {
+        throw new CliError(`Batch input is ${bytes.length} bytes; maximum is ${MAX_BATCH_INPUT_BYTES}.`, "INPUT_LIMIT", 2, null);
+    }
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch (error) {
+        throw new CliError("Batch input is not valid JSON.", "INVALID_JSON", 2, null, undefined, {
+            cause: error,
+        });
+    }
+}
+function parseApplyArgs(args) {
+    if (args.length !== 3 || args[1] !== "--plan-hash" || !args[0] || !args[2]) {
+        throw new CliError(usage(), "USAGE", 2, "apply");
+    }
+    return { planFile: args[0], planHash: args[2] };
+}
+function parseInstallSkillArgs(args) {
+    let target = "all";
+    let targetSeen = false;
+    let scope = "user";
+    let scopeSeen = false;
+    let projectRoot;
+    let force = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--force") {
+            if (force)
+                throw new CliError(usage(), "USAGE", 2, "install-skill");
+            force = true;
+            continue;
+        }
+        if (argument === "--scope") {
+            const value = args[index + 1];
+            if (scopeSeen || (value !== "user" && value !== "project")) {
+                throw new CliError(usage(), "USAGE", 2, "install-skill");
+            }
+            scope = value;
+            scopeSeen = true;
+            index += 1;
+            continue;
+        }
+        if (argument === "--project-root") {
+            const value = args[index + 1];
+            if (projectRoot !== undefined || !value || value.startsWith("--")) {
+                throw new CliError(usage(), "USAGE", 2, "install-skill");
+            }
+            projectRoot = value;
+            index += 1;
+            continue;
+        }
+        if (!targetSeen && (argument === "claude" || argument === "hermes" || argument === "all")) {
+            target = argument;
+            targetSeen = true;
+            continue;
+        }
+        throw new CliError(usage(), "USAGE", 2, "install-skill");
+    }
+    if (projectRoot !== undefined && scope !== "project") {
+        throw new CliError(usage(), "USAGE", 2, "install-skill");
+    }
+    return { target, scope, ...(projectRoot ? { projectRoot } : {}), force };
+}
+function parseSetupArgs(args) {
+    let agents;
+    let yes = false;
+    let forceSkill = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--agents") {
+            const value = args[index + 1];
+            if (agents !== undefined || !value || value.startsWith("--")) {
+                throw new CliError(usage(), "USAGE", 2, "setup");
+            }
+            try {
+                agents = parseAgentsArgument(value);
+            }
+            catch (error) {
+                throw new CliError(error instanceof Error ? error.message : String(error), "USAGE", 2, "setup", undefined, { cause: error });
+            }
+            index += 1;
+            continue;
+        }
+        if (argument === "--yes") {
+            if (yes)
+                throw new CliError(usage(), "USAGE", 2, "setup");
+            yes = true;
+            continue;
+        }
+        if (argument === "--force-skill") {
+            if (forceSkill)
+                throw new CliError(usage(), "USAGE", 2, "setup");
+            forceSkill = true;
+            continue;
+        }
+        throw new CliError(usage(), "USAGE", 2, "setup");
+    }
+    if ((agents === undefined) === yes) {
+        throw new CliError("Non-interactive setup requires both --agents and --yes; interactive setup accepts neither.", "USAGE", 2, "setup");
+    }
+    return { ...(agents === undefined ? {} : { agents }), yes, forceSkill };
+}
+async function parseDocumentForCommand(source, command) {
+    try {
+        return parseBatchDocument(await readBatchInput(source));
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            throw new CliError(error.message, error.code, 2, command, error.stepId, { cause: error });
+        }
+        const message = error instanceof ZodError ? error.issues.map((issue) => issue.message).join("; ") : error;
+        throw new CliError(message instanceof Error ? message.message : String(message), "INVALID_BATCH", 2, command, undefined, { cause: error });
+    }
+}
+export async function runCli(args) {
+    const [command, ...commandArgs] = args;
+    if (command === "run" || command === "validate") {
+        if (commandArgs.length !== 1 || !commandArgs[0]) {
+            throw new CliError(usage(), "USAGE", 2, command);
+        }
+        const document = await parseDocumentForCommand(commandArgs[0], command);
+        if (command === "validate") {
+            return {
+                version: 1,
+                status: "valid",
+                step_count: document.steps.length,
+            };
+        }
+        try {
+            return await runBatchDocument(document, {
+                persistPreparedOperation: (operationId) => persistOperationPlan(operationId),
+            });
+        }
+        catch (error) {
+            if (error instanceof BatchExecutionError) {
+                throw new CliError(error.message, error.code, 1, command, error.stepId, {
+                    cause: error,
+                });
+            }
+            throw new CliError(error instanceof Error ? error.message : String(error), "EXECUTION_ERROR", 1, command, undefined, { cause: error });
+        }
+    }
+    if (command === "apply") {
+        const { planFile, planHash } = parseApplyArgs(commandArgs);
+        try {
+            return await applyPersistedOperation(planFile, planHash);
+        }
+        catch (error) {
+            throw new CliError(error instanceof Error ? error.message : String(error), "APPLY_ERROR", 1, command, undefined, { cause: error });
+        }
+    }
+    if (command === "setup") {
+        const options = parseSetupArgs(commandArgs);
+        try {
+            const detections = await detectInstalledAgents();
+            let agents = options.agents;
+            if (agents === undefined) {
+                if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
+                    throw new CliError("Interactive setup requires a TTY. Use --agents claude,hermes --yes for automation.", "USAGE", 2, command);
+                }
+                const prompt = createInterface({ input: process.stdin, output: process.stderr });
+                try {
+                    agents = await promptForAgentSelection(detections, (question) => prompt.question(question));
+                }
+                finally {
+                    prompt.close();
+                }
+                if (agents.length === 0) {
+                    return { status: "cancelled", command: "setup", agents: [] };
+                }
+            }
+            const executablePath = process.argv[1];
+            if (!executablePath) {
+                throw new Error("Cannot resolve the ast-tool executable path.");
+            }
+            return await runAgentSetup({
+                agents,
+                detections,
+                sourceSkillPath: await resolveBundledSkillPath(executablePath),
+                serverEntryPath: await resolveServerEntryPath(executablePath),
+                forceSkill: options.forceSkill,
+            });
+        }
+        catch (error) {
+            if (error instanceof CliError) {
+                throw error;
+            }
+            if (error instanceof AgentSetupError) {
+                throw new CliError(error.message, error.code, 1, command, undefined, { cause: error }, error.details);
+            }
+            throw new CliError(error instanceof Error ? error.message : String(error), "SETUP_ERROR", 1, command, undefined, { cause: error });
+        }
+    }
+    if (command === "install-skill") {
+        const options = parseInstallSkillArgs(commandArgs);
+        try {
+            const executablePath = process.argv[1];
+            if (!executablePath) {
+                throw new Error("Cannot resolve the ast-tool executable path.");
+            }
+            return await installBundledSkill({
+                ...options,
+                sourceSkillPath: await resolveBundledSkillPath(executablePath),
+            });
+        }
+        catch (error) {
+            throw new CliError(error instanceof Error ? error.message : String(error), "SKILL_INSTALL_ERROR", 1, command, undefined, { cause: error });
+        }
+    }
+    throw new CliError(usage(), "USAGE", 2, command ?? null);
+}
+function failure(error) {
+    if (error instanceof CliError) {
+        return {
+            value: {
+                status: "error",
+                command: error.command,
+                code: error.code,
+                ...(error.stepId ? { step_id: error.stepId } : {}),
+                message: error.message,
+                ...(error.details === undefined ? {} : { details: error.details }),
+            },
+            exitCode: error.exitCode,
+        };
+    }
+    return {
+        value: {
+            status: "error",
+            command: null,
+            code: "INTERNAL_ERROR",
+            message: error instanceof Error ? error.message : String(error),
+        },
+        exitCode: 1,
+    };
+}
+async function main() {
+    try {
+        const result = await runCli(process.argv.slice(2));
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    catch (error) {
+        const failed = failure(error);
+        process.stderr.write(`${JSON.stringify(failed.value)}\n`);
+        process.exitCode = failed.exitCode;
+    }
+}
+await main();