UNPKG

comfyui-mcp

Version:

Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),

1,105 lines • 51.8 kB
import { execFileSync } from "node:child_process";
import { createHash, randomUUID } from "node:crypto";
import { existsSync } from "node:fs";
import { basename, isAbsolute, join, relative, resolve } from "node:path";
import { config, getComfyUIBaseUrl } from "../config.js";
import { comfyuiFetch } from "../comfyui/fetch.js";
import { progressEnabled, reportDownloadProgress } from "./download-progress.js";
import { assertComfyCliOk, runComfyCliSync } from "./comfy-cli.js";
import { ComfyUIError, ProcessControlError, ValidationError } from "../utils/errors.js";
import { logger } from "../utils/logger.js";
// ---------------------------------------------------------------------------
// Custom-node management — ports `comfy-cli node install|update|reinstall|fix|
// show|uv-sync` to MCP tools.
//
// Strategy (hybrid, confirmed with maintainer):
//   1. Prefer the ComfyUI-Manager HTTP API (works against remote instances).
//      TWO API GENERATIONS exist in the wild (issue #116), auto-detected per
//      target by detectManagerApi():
//        • v4 lineage (pip `comfyui_manager` ≥4.x, the `manager-v4` branch —
//          what the RunPod image bakes): unified queue — POST one task
//          envelope to /v2/manager/queue/task, then /v2/manager/queue/start,
//          then poll /v2/manager/queue/status until the queue drains.
//        • RELEASED Manager 3.x (`main`, the registry default): same queue
//          engine under /manager/queue/* with PER-OPERATION routes
//          (install/uninstall/update/fix/disable/install_model/update_all)
//          and different body shapes — see legacyTaskRequest().
//   2. Fall back to the cm-cli.py subprocess (against config.comfyuiPath) for
//      anything the HTTP API can't do, or when the user forces it (local
//      installs only — cm-cli needs the filesystem).
//
// API contract verified against the current Comfy-Org/ComfyUI-Manager (the
// `glob` server, codegen'd from openapi.yaml). Every operation now flows through
// ONE endpoint:
//   POST /v2/manager/queue/task   body: { ui_id, client_id, kind, params }
// where `kind` is an OperationType (install | uninstall | update | fix |
// enable | disable | update-comfyui | install-model) and `params` is the
// matching Pydantic model:
//   install  → InstallPackParams { id, version, selected_version, repository?,
//                                  pip?, mode, channel, skip_post_install? }
//              (do_install only reads `id` + `selected_version` → resolve_node_spec)
//   update   → UpdatePackParams  { node_name, node_ver? }
//   fix      → FixPackParams     { node_name, node_ver }
//   uninstall→ UninstallPackParams { node_name, is_unknown? }
//   disable  → DisablePackParams { node_name, is_unknown? }
//   enable   → EnablePackParams  { cnr_id }
// Dedicated (non-task) routes still exist for: /v2/manager/queue/update_all,
// /v2/manager/queue/start, /v2/manager/queue/status, /v2/customnode/installed.
// There is NO `reinstall` kind — reinstall is modeled as uninstall + install.
//
// NOTE: modern ComfyUI-Manager ships as the pip package `comfyui_manager`
// (site-packages), NOT a custom_nodes/ checkout, so it does not provide
// cm-cli.py. The cm-cli fallback therefore only works on legacy layouts; the
// HTTP API above covers every operation and is the primary path.
// ---------------------------------------------------------------------------
/** client_id reported to ComfyUI-Manager's task queue for our requests. */
const MANAGER_CLIENT_ID = "comfyui-mcp";
export class NodeManagementError extends ComfyUIError {
    constructor(message, details) {
        super(message, "NODE_MANAGEMENT_ERROR", details);
        this.name = "NodeManagementError";
    }
}
// ---------------------------------------------------------------------------
// Manager HTTP helper (local to this unit — do NOT extract to a shared client)
// ---------------------------------------------------------------------------
function managerBaseUrl() {
    return getComfyUIBaseUrl();
}
async function managerFetch(path, options = {}) {
    const { method = "GET", body, soft = false } = options;
    const url = `${managerBaseUrl()}${path}`;
    logger.debug("Manager API request", { url, method });
    const headers = {};
    if (body !== undefined)
        headers["Content-Type"] = "application/json";
    let res;
    try {
        res = await comfyuiFetch(url, {
            method,
            headers,
            body: body !== undefined ? JSON.stringify(body) : undefined,
        });
    }
    catch (err) {
        if (soft)
            return undefined;
        throw new NodeManagementError(`ComfyUI-Manager API unreachable at ${url}. Is ComfyUI running with ComfyUI-Manager installed? (${err instanceof Error ? err.message : String(err)})`);
    }
    if (!res.ok) {
        if (soft)
            return undefined;
        const text = await res.text().catch(() => "");
        throw new NodeManagementError(`ComfyUI-Manager API ${res.status} ${res.statusText} for ${path}`, { url, status: res.status, body: text });
    }
    // Some endpoints return empty bodies (e.g. queue ops). Parse defensively.
    const raw = await res.text();
    if (!raw)
        return undefined;
    try {
        return JSON.parse(raw);
    }
    catch {
        return raw;
    }
}
function sleep(ms) {
    return new Promise((resolve) => setTimeout(resolve, ms));
}
let managerApiCache = null;
/** @internal — test hook so suites can pin/clear the detected generation. */
export function resetManagerApiCacheForTests(api) {
    managerApiCache = api ? { base: managerBaseUrl(), api } : null;
}
/** A real queue/status payload — guards detection against servers that answer
 *  200 with HTML/junk for unknown GETs (SPA fallbacks, index catchalls). */
function looksLikeQueueStatus(s) {
    return (!!s &&
        typeof s === "object" &&
        (typeof s.total_count === "number" ||
            typeof s.is_processing === "boolean"));
}
async function detectManagerApi() {
    const base = managerBaseUrl();
    if (managerApiCache?.base === base)
        return managerApiCache.api;
    const v2 = await managerFetch("/v2/manager/queue/status", { soft: true });
    if (looksLikeQueueStatus(v2)) {
        // Same /v2 surface, two servers: the pip package in legacy-UI mode swaps
        // in its bundled 3.x server (no task route). Both register
        // GET /v2/manager/is_legacy_manager_ui and answer truthfully; a missing
        // route (older pip) means the normal v4 server → task dialect.
        const legacyUi = await managerFetch("/v2/manager/is_legacy_manager_ui", { soft: true });
        const api = legacyUi && typeof legacyUi === "object" && legacyUi.is_legacy_manager_ui === true
            ? "v2-batch"
            : "v2";
        managerApiCache = { base, api };
        return api;
    }
    const legacy = await managerFetch("/manager/queue/status", { soft: true });
    if (looksLikeQueueStatus(legacy)) {
        managerApiCache = { base, api: "legacy" };
        return "legacy";
    }
    throw new NodeManagementError("ComfyUI-Manager's queue API is not reachable (neither /v2/manager/queue/status " +
        "nor /manager/queue/status answered with a queue status). Is ComfyUI-Manager " +
        "installed and enabled on the connected ComfyUI? The pip comfyui_manager " +
        "package only activates when ComfyUI is started with --enable-manager.");
}
/** Queue route prefix for the detected generation ("v2-batch" serves
 *  status/start under the /v2 prefix too — only the mutation routes differ). */
async function managerQueuePrefix() {
    return (await detectManagerApi()) === "legacy" ? "/manager/queue" : "/v2/manager/queue";
}
/** Appended to every legacy-Manager operation failure so users know they're on
 *  the partial feature set and how to get off it. */
const MANAGER_UPGRADE_HINT = "NOTE: this ComfyUI runs the LEGACY ComfyUI-Manager 3.x. comfyui-mcp is optimized " +
    "for Manager v4+ — on 3.x some operations degrade or are unavailable (notably " +
    "arbitrary-URL model downloads, which 3.x whitelist-gates). Recommend upgrading: " +
    "`pip install -U comfyui_manager` in the ComfyUI python env, then disable the old " +
    "custom_nodes/ComfyUI-Manager clone and restart. " +
    "See https://comfyui-mcp.artokun.io/docs/troubleshooting";
/** Appended to v2-batch (pip Manager in legacy-UI mode) failures. */
const MANAGER_LEGACY_UI_HINT = "NOTE: this ComfyUI runs Manager v4 (pip comfyui_manager) in LEGACY-UI mode " +
    "(--enable-manager-legacy-ui), which serves the older 3.x API — some operations " +
    "degrade (notably arbitrary-URL model downloads, which the 3.x code whitelist-gates). " +
    "For the full v4 API, start ComfyUI without --enable-manager-legacy-ui (for " +
    "yanwk/comfyui-boot images that flag is hardcoded in the entrypoint). " +
    "See https://comfyui-mcp.artokun.io/docs/troubleshooting";
/** Wrap a legacy-Manager failure with the upgrade guidance (keeps details). */
function annotateLegacyError(err, kind, hint = MANAGER_UPGRADE_HINT) {
    const base = err instanceof Error ? err.message : String(err);
    const extra = kind === "install-model"
        ? " Arbitrary-URL model installs REQUIRE Manager v4+ (3.x only accepts whitelisted catalog models)."
        : "";
    return new NodeManagementError(`${base}${extra}\n${hint}`, err instanceof NodeManagementError ? err.details : undefined);
}
/**
 * Translate one unified-task call into the legacy per-operation route + body.
 * Body shapes verified against ComfyUI-Manager 3.41 glob/manager_server.py:
 * install/uninstall/update/fix/disable key on `version` ('unknown' → treat
 * `files[0]` as a git URL / folder name), and install (unlike v4) accepts a
 * REAL git URL natively via { version:'unknown', files:[url] }.
 */
function legacyTaskRequest(kind, params, uiId) {
    const nodeName = (params.node_name ?? params.id);
    const version = params.node_ver || params.selected_version || "latest";
    switch (kind) {
        case "install":
            return {
                path: "/manager/queue/install",
                body: {
                    ui_id: uiId,
                    id: params.id,
                    version: params.version ?? version,
                    selected_version: params.selected_version ?? version,
                    ...(params.files ? { files: params.files } : {}),
                    ...(params.repository ? { repository: params.repository } : {}),
                    ...(params.pip ? { pip: params.pip } : {}),
                    channel: params.channel ?? "default",
                    mode: params.mode ?? "cache",
                    ...(params.skip_post_install !== undefined
                        ? { skip_post_install: params.skip_post_install }
                        : {}),
                },
            };
        case "enable":
            // Legacy has no enable route — the UI re-installs with skip_post_install.
            return {
                path: "/manager/queue/install",
                body: {
                    ui_id: uiId,
                    id: nodeName,
                    version,
                    selected_version: version,
                    skip_post_install: true,
                    channel: "default",
                    mode: "cache",
                },
            };
        case "uninstall":
            return {
                path: "/manager/queue/uninstall",
                body: { ui_id: uiId, id: nodeName, version },
            };
        case "update":
            return {
                path: "/manager/queue/update",
                body: { ui_id: uiId, id: nodeName, version },
            };
        case "fix":
            return {
                path: "/manager/queue/fix",
                body: { ui_id: uiId, id: nodeName, version },
            };
        case "disable":
            return {
                path: "/manager/queue/disable",
                body: { ui_id: uiId, id: nodeName, version },
            };
        case "install-model":
            // Same model-item body — but 3.x validates it against the model-list
            // whitelist, so arbitrary-URL installs are rejected (v4-only feature).
            return { path: "/manager/queue/install_model", body: { ...params, ui_id: uiId } };
    }
}
/**
 * Tunable timing for queue polling. Defaults are production values; tests
 * shrink these via setQueueTimingForTests to keep the suite fast.
 */
const queueTiming = {
    pollIntervalMs: 1500,
    // The worker thread is spawned asynchronously by /manager/queue/start, so a
    // poll taken immediately afterward can read is_processing=false /
    // in_progress_count=0 while the queued item is still pending (total_count
    // counts queued items). Give the worker a grace window to spin up before
    // treating an idle-looking status as "done".
    startupGraceMs: 8000,
    timeoutMs: 600_000,
};
/** @internal — test hook to shrink polling timings; not part of the tool API. */
export function setQueueTimingForTests(overrides) {
    Object.assign(queueTiming, overrides);
}
/**
 * Kick off the Manager queue worker and poll until it drains.
 * Returns the final queue status.
 */
async function runManagerQueue() {
    const prefix = await managerQueuePrefix();
    // queue/start returns 200 (worker started) or 201 (already running) — both
    // are 2xx, so managerFetch accepts either. Same on both generations.
    await managerFetch(`${prefix}/start`, { method: "POST" });
    const start = Date.now();
    let lastStatus;
    while (Date.now() - start < queueTiming.timeoutMs) {
        await sleep(queueTiming.pollIntervalMs);
        const status = await managerFetch(`${prefix}/status`, {
            soft: true,
        });
        if (status) {
            lastStatus = status;
            // Manager defines total_count = done + in_progress + queued. The queue
            // is fully drained only once nothing is processing AND every item that
            // was ever queued has completed (done_count >= total_count, which also
            // implies in_progress_count === 0 and no queued items remain).
            const drained = !status.is_processing && status.done_count >= status.total_count;
            if (drained && Date.now() - start >= queueTiming.startupGraceMs) {
                return status;
            }
        }
    }
    throw new NodeManagementError(`ComfyUI-Manager queue did not finish within ${queueTiming.timeoutMs / 1000}s`, lastStatus);
}
/**
 * Enqueue one operation on ComfyUI-Manager's unified task queue and drain it.
 * Wraps the caller's per-kind `params` in the QueueTaskItem envelope the v2
 * endpoint validates ({ ui_id, client_id, kind, params }) and returns the final
 * queue status. `ui_id` is also threaded into params (Manager's models carry an
 * optional ui_id for correlation).
 */
async function queueManagerTask(kind, params) {
    const uiId = randomUUID();
    const api = await detectManagerApi();
    if (api === "legacy") {
        // Released Manager 3.x: per-operation routes + different body shapes
        // (issue #116 — the unified /v2 task route 405s there).
        const { path, body } = legacyTaskRequest(kind, params, uiId);
        try {
            await managerFetch(path, { method: "POST", body });
        }
        catch (err) {
            throw annotateLegacyError(err, kind);
        }
        return runManagerQueue();
    }
    if (api === "v2-batch") {
        // pip Manager in legacy-UI mode (issue #235): the /v2 prefix serves the
        // BUNDLED 3.x server — no task route (POST there 405s via the frontend
        // catchall). Mutations take 3.x body shapes, wrapped in the batch
        // envelope {<op>: [body, ...]}; the batch runs its items synchronously
        // and reports failures as {failed: [id, ...]}. install-model keeps its
        // dedicated route (same path as v4, 3.x whitelist semantics).
        const { path, body } = legacyTaskRequest(kind, params, uiId);
        try {
            if (kind === "install-model") {
                await managerFetch("/v2/manager/queue/install_model", { method: "POST", body });
            }
            else {
                // legacyTaskRequest's path is "/manager/queue/<op>"; the batch key is
                // that trailing op ("enable" maps to an install body → key "install").
                const op = path.split("/").pop();
                const res = await managerFetch("/v2/manager/queue/batch", {
                    method: "POST",
                    body: { [op]: [body] },
                });
                const failed = Array.isArray(res?.failed) ? res.failed : [];
                if (failed.length && (body.id === undefined || failed.includes(body.id))) {
                    throw new NodeManagementError(`ComfyUI-Manager batch reported the ${op} of "${String(body.id ?? "?")}" as failed ` +
                        "(check the ComfyUI server log for the underlying error — security_level " +
                        "gating is a common cause).");
                }
            }
        }
        catch (err) {
            throw annotateLegacyError(err, kind, MANAGER_LEGACY_UI_HINT);
        }
        return runManagerQueue();
    }
    await managerFetch("/v2/manager/queue/task", {
        method: "POST",
        body: {
            ui_id: uiId,
            client_id: MANAGER_CLIENT_ID,
            kind,
            params: { ...params, ui_id: uiId },
        },
    });
    return runManagerQueue();
}
// ---------------------------------------------------------------------------
// Official comfy-cli subprocess helper
// ---------------------------------------------------------------------------
const COMFY_CLI_TIMEOUT = 600_000;
// A real custom-node repo clones well under this; with prompts disabled a
// missing/private repo fails in ~1s rather than blocking the whole timeout.
const GIT_CLONE_TIMEOUT = 180_000;
/** Env for git network ops that must NEVER block on an interactive credential
 *  prompt. Without this, `git clone`/`fetch` of a missing or private repo waits
 *  on a stdin username/password prompt and hangs until the timeout (observed as a
 *  multi-minute "thinking" stall on a bad URL). GIT_ASKPASS=echo + the prompt
 *  flags make git fail fast instead. GITHUB_TOKEN is passed through when set. */
export function nonInteractiveGitEnv() {
    return {
        ...process.env,
        GIT_TERMINAL_PROMPT: "0",
        GIT_ASKPASS: "echo",
        GCM_INTERACTIVE: "never",
        ...(config.githubToken ? { GITHUB_TOKEN: config.githubToken } : {}),
    };
}
/**
 * Run an official `comfy node` subcommand. Returns normalized JSON data.
 * Throws ProcessControlError if comfyuiPath is undefined (remote mode).
 */
function runCmCli(args) {
    if (!config.comfyuiPath) {
        throw new ProcessControlError("This operation requires a local ComfyUI install. Set COMFYUI_PATH or use the Manager HTTP API.");
    }
    logger.info("Running comfy-cli", { args: ["node", ...args].join(" ") });
    try {
        const envelope = assertComfyCliOk(runComfyCliSync(["node", ...args], {
            workspace: config.comfyuiPath,
            timeoutMs: COMFY_CLI_TIMEOUT,
            env: config.githubToken ? { GITHUB_TOKEN: config.githubToken } : undefined,
        }));
        return JSON.stringify(envelope.data ?? {}, null, 2);
    }
    catch (error) {
        const processError = error;
        if (processError.code === "ENOENT") {
            throw new ProcessControlError("The comfy-cli executable could not be started. Check COMFY_CLI_PATH and PATH.");
        }
        throw new NodeManagementError(`comfy-cli node ${args[0]} failed: ${processError.message}`, {
            stdout: processError.stdout?.toString() ?? "",
            stderr: processError.stderr?.toString() ?? "",
        });
    }
}
// ---------------------------------------------------------------------------
// Parsing helpers
// ---------------------------------------------------------------------------
/**
 * Normalize the /customnode/installed response into InstalledNode[].
 * Manager returns an object keyed by module name (see manager_core
 * get_installed_node_packs), each value carrying { ver, cnr_id, aux_id, enabled }.
 * Older/variant builds may return an array; handle both.
 */
function parseInstalled(raw) {
    if (!raw || typeof raw !== "object")
        return [];
    const toNode = (module, v) => ({
        module,
        cnrId: typeof v.cnr_id === "string" && v.cnr_id.length > 0 ? v.cnr_id : undefined,
        auxId: typeof v.aux_id === "string" && v.aux_id.length > 0 ? v.aux_id : undefined,
        version: typeof v.ver === "string" ? v.ver : undefined,
        // `enabled` may be absent on some builds; treat missing as enabled,
        // but honor an explicit is_disabled flag if present.
        enabled: typeof v.enabled === "boolean"
            ? v.enabled
            : v.is_disabled === true
                ? false
                : true,
    });
    if (Array.isArray(raw)) {
        return raw
            .filter((entry) => Boolean(entry && typeof entry === "object"))
            .map((entry) => {
            const module = (typeof entry.title === "string" && entry.title) ||
                (typeof entry.module === "string" && entry.module) ||
                (typeof entry.cnr_id === "string" && entry.cnr_id) ||
                "unknown";
            return toNode(module, entry);
        });
    }
    return Object.entries(raw)
        .filter(([, v]) => Boolean(v && typeof v === "object"))
        .map(([module, v]) => toNode(module, v));
}
function stripUrlSuffix(value) {
    return value.replace(/[?#].*$/, "").replace(/\/+$/, "");
}
function validateGitRef(ref) {
    if (ref.length === 0) {
        throw new ValidationError("Git ref must be a non-empty string.");
    }
    if (ref.startsWith("-")) {
        throw new ValidationError("Git ref cannot start with '-'.");
    }
    if (/[\x00-\x1F\x7F]/.test(ref)) {
        throw new ValidationError("Git ref cannot contain ASCII control characters.");
    }
    if (/\s/.test(ref)) {
        throw new ValidationError("Git ref cannot contain whitespace.");
    }
    if (/[~^:?*[\\]/.test(ref)) {
        throw new ValidationError("Git ref contains characters that are not valid in git refs.");
    }
    if (ref.startsWith("/") ||
        ref.endsWith("/") ||
        ref.includes("//") ||
        ref.includes("..") ||
        ref.includes("@{") ||
        ref === "@" ||
        ref.endsWith(".") ||
        ref.endsWith(".lock")) {
        throw new ValidationError("Git ref is not a valid git ref name.");
    }
    return ref;
}
function stripGitUrlRef(value, patterns) {
    const normalized = stripUrlSuffix(value);
    for (const pattern of patterns) {
        const match = normalized.match(pattern.re);
        if (match) {
            const ref = decodeURIComponent(match[2]);
            if (pattern.rejectSlashRef && ref.includes("/")) {
                throw new ValidationError("Ambiguous git tree URL contains a path after the ref. Pass the repository URL and explicit `ref` instead.");
            }
            return { baseUrl: match[1], ref: validateGitRef(ref) };
        }
    }
    return undefined;
}
export function parseGitUrl(url) {
    const input = url.trim();
    const withoutSuffix = stripUrlSuffix(input);
    // npm/pip style: repo@ref or repo.git@ref. Avoid treating the user part of
    // scp-like SSH URLs (git@github.com:owner/repo.git) as a ref.
    const atRef = withoutSuffix.match(/^(.+)@([^@/]+)$/);
    if (atRef && (!/^[^@]+@[^/:]+:/.test(withoutSuffix) || atRef[1].includes("@"))) {
        return { baseUrl: atRef[1], ref: validateGitRef(decodeURIComponent(atRef[2])) };
    }
    const matched = stripGitUrlRef(withoutSuffix, [
        { re: /^(.+?)\/-\/tree\/(.+)$/, rejectSlashRef: true },
        { re: /^(.+?)\/-\/commit\/(.+)$/ },
        { re: /^(.+?)\/tree\/(.+)$/, rejectSlashRef: true },
        { re: /^(.+?)\/commit\/(.+)$/ },
        { re: /^(.+?)\/releases\/tag\/(.+)$/ },
        { re: /^(.+?)\/src\/([^/]+)(?:\/.*)?$/ },
        { re: /^(.+?)\/commits\/(.+)$/ },
    ]);
    if (matched)
        return matched;
    return { baseUrl: input, ref: null };
}
function looksLikeGitUrl(id) {
    return /^(https?:\/\/|git@|git\+)/i.test(id) || id.endsWith(".git");
}
function gitCheckoutDir(baseUrl) {
    const pathPart = baseUrl.includes(":") && !baseUrl.includes("://")
        ? baseUrl.slice(baseUrl.lastIndexOf(":") + 1)
        : baseUrl;
    const clean = stripUrlSuffix(pathPart);
    return basename(clean).replace(/\.git$/i, "");
}
function runGitCheckout(baseUrl, ref) {
    if (!config.comfyuiPath) {
        throw new ProcessControlError("Checking out a custom-node git ref requires a local ComfyUI install, " +
            "but config.comfyuiPath is not set.");
    }
    // SECURITY: this is also reached by the forced-cm-cli git path, NOT just the
    // clone fallback, so validate here too before baseUrl / the derived dir reach
    // git or the filesystem (option injection + path traversal). Mirrors
    // cloneCustomNodeFallback's checks.
    assertSafeGitUrl(baseUrl);
    const repoName = gitCheckoutDir(baseUrl);
    assertSafeRepoName(repoName);
    const customNodesRoot = resolve(config.comfyuiPath, "custom_nodes");
    const nodeDir = resolve(customNodesRoot, repoName);
    const rel = relative(customNodesRoot, nodeDir);
    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
        throw new ValidationError(`Refusing to check out: resolved path "${nodeDir}" escapes ${customNodesRoot}.`);
    }
    logger.info("Checking out custom-node git ref", {
        repository: baseUrl,
        ref,
        nodeDir,
    });
    try {
        execFileSync("git", ["-C", nodeDir, "fetch", "--all", "--tags"], {
            cwd: config.comfyuiPath,
            encoding: "utf-8",
            timeout: GIT_CLONE_TIMEOUT,
            env: nonInteractiveGitEnv(),
        });
        execFileSync("git", ["-C", nodeDir, "checkout", "--detach", "--end-of-options", ref], {
            cwd: config.comfyuiPath,
            encoding: "utf-8",
            timeout: GIT_CLONE_TIMEOUT,
            env: nonInteractiveGitEnv(),
        });
    }
    catch (err) {
        const e = err;
        throw new NodeManagementError(`Failed to check out git ref "${ref}" for custom node "${baseUrl}": ${e.message}`, {
            stdout: e.stdout ? e.stdout.toString() : "",
            stderr: e.stderr ? e.stderr.toString() : "",
        });
    }
}
/**
 * Does an installed node match the wanted id/url? Mirrors manifest.ts's private
 * nodeAlreadyInstalled, but kept local to this unit. Normalizes (lowercase) and
 * matches an installed node's module/cnrId/auxId (and the basename of each — aux
 * ids are typically "owner/repo") against the wanted value and, when the wanted
 * value is a git URL, its derived repo name. This is how we VERIFY a Manager
 * install actually landed on disk (Manager marks the queue "done" even when it
 * resolved nothing).
 */
function nodeInstalledMatches(idOrUrl, installed) {
    const wanted = idOrUrl.trim().toLowerCase();
    const repoName = looksLikeGitUrl(idOrUrl)
        ? gitCheckoutDir(parseGitUrl(idOrUrl).baseUrl).toLowerCase()
        : wanted;
    return installed.some((node) => {
        const candidates = [];
        for (const v of [node.module, node.cnrId, node.auxId]) {
            if (!v)
                continue;
            const norm = v.trim().toLowerCase();
            candidates.push(norm);
            candidates.push(basename(norm));
        }
        return candidates.includes(wanted) || candidates.includes(repoName);
    });
}
/**
 * Resolve the ComfyUI venv python for installing a cloned node's deps. Prefers
 * the install's own `.venv` (Windows Scripts/ or POSIX bin/), falling back to a
 * bare "python" on PATH.
 */
function resolveVenvPython() {
    if (config.comfyuiPath) {
        const winPy = join(config.comfyuiPath, ".venv", "Scripts", "python.exe");
        if (existsSync(winPy))
            return winPy;
        const posixPy = join(config.comfyuiPath, ".venv", "bin", "python");
        if (existsSync(posixPy))
            return posixPy;
    }
    return "python";
}
/**
 * Validate a git URL before it is handed to `git clone` as an argument.
 * Rejects an arg-injection vector (a URL parsed as a git option) and anything
 * that isn't a recognized git URL shape.
 */
function assertSafeGitUrl(gitId) {
    if (gitId.startsWith("-")) {
        throw new ValidationError(`Refusing to clone git URL "${gitId}": it starts with '-' and would be ` +
            `interpreted as a git option.`);
    }
    if (/[\x00-\x1F\x7F]/.test(gitId)) {
        throw new ValidationError("Git URL cannot contain ASCII control characters.");
    }
    if (!looksLikeGitUrl(gitId)) {
        throw new ValidationError(`Refusing to clone "${gitId}": not a recognized git URL (expected ` +
            `https://, ssh://, git@…, git+…, or a .git URL).`);
    }
}
/**
 * Validate the repo name derived from a git URL before it is used as a
 * filesystem path segment under custom_nodes. Rejects empty, '.'/'..', names
 * starting with '-', and names containing path separators or control chars —
 * any of which could escape custom_nodes or be parsed as a git option.
 */
export function assertSafeRepoName(repoName) {
    if (repoName.length === 0 ||
        repoName === "." ||
        repoName === ".." ||
        repoName.startsWith("-") ||
        /[/\\]/.test(repoName) ||
        /[\x00-\x1F\x7F]/.test(repoName)) {
        throw new ValidationError(`Refusing to use "${repoName}" as a custom_nodes directory name (empty, ` +
            `'.'/'..', starts with '-', or contains a path separator/control char).`);
    }
}
/**
 * Direct-clone fallback for an unregistered git repo the Manager can't resolve.
 * Clones into custom_nodes/<repoName>, checks out a ref if given, then makes a
 * best-effort attempt at installing python deps (requirements.txt + install.py).
 * Dep failures DON'T fail the install (clone succeeded) — they're surfaced as
 * warnings. A clone failure throws NodeManagementError.
 */
function cloneCustomNodeFallback(gitId, repoName, gitRef, managerStatus) {
    if (!config.comfyuiPath) {
        throw new ProcessControlError(`"${repoName}" is not in the ComfyUI-Manager registry and cloning it ` +
            `requires a local ComfyUI install, but config.comfyuiPath is not set ` +
            `(running in remote --comfyui-url mode). Install it on the ComfyUI host, ` +
            `or pass a registered pack id.`);
    }
    // SECURITY: validate before either value becomes a `git clone` arg or a path
    // segment. gitId is checked for option-injection; repoName for path traversal.
    assertSafeGitUrl(gitId);
    assertSafeRepoName(repoName);
    // Resolve the target and ASSERT it stays inside <comfyuiPath>/custom_nodes,
    // mirroring manifest.ts's isWithinRoot containment check (defense in depth on
    // top of the repoName validation above).
    const customNodesRoot = resolve(config.comfyuiPath, "custom_nodes");
    const nodeDir = resolve(customNodesRoot, repoName);
    const rel = relative(customNodesRoot, nodeDir);
    if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
        throw new ValidationError(`Refusing to clone: resolved path "${nodeDir}" escapes ${customNodesRoot}.`);
    }
    const warnings = [];
    const alreadyPresent = existsSync(nodeDir);
    if (!alreadyPresent) {
        // A concrete ref needs the full history reachable; otherwise shallow-clone.
        // `--end-of-options` ensures gitId/nodeDir are never parsed as git options.
        const cloneArgs = gitRef
            ? ["clone", "--end-of-options", gitId, nodeDir]
            : ["clone", "--depth", "1", "--end-of-options", gitId, nodeDir];
        logger.info("Cloning unregistered custom node", { gitId, nodeDir, gitRef });
        try {
            execFileSync("git", cloneArgs, {
                cwd: config.comfyuiPath,
                encoding: "utf-8",
                timeout: GIT_CLONE_TIMEOUT,
                env: nonInteractiveGitEnv(),
            });
        }
        catch (err) {
            const e = err;
            throw new NodeManagementError(`Failed to clone "${gitId}" into custom_nodes/${repoName}: ${e.message}`, {
                stdout: e.stdout ? e.stdout.toString() : "",
                stderr: e.stderr ? e.stderr.toString() : "",
            });
        }
        if (gitRef)
            runGitCheckout(gitId, gitRef);
    }
    // VERIFY the clone landed before attempting deps.
    if (!existsSync(nodeDir)) {
        throw new NodeManagementError(`Clone of "${gitId}" reported success but ${nodeDir} is missing.`);
    }
    // Best-effort python deps. Don't fail the install if these don't.
    const requirements = join(nodeDir, "requirements.txt");
    const installScript = join(nodeDir, "install.py");
    if (existsSync(requirements) || existsSync(installScript)) {
        const python = resolveVenvPython();
        if (existsSync(requirements)) {
            try {
                execFileSync(python, ["-m", "pip", "install", "-r", requirements], {
                    cwd: nodeDir,
                    encoding: "utf-8",
                    timeout: COMFY_CLI_TIMEOUT,
                });
            }
            catch (err) {
                const e = err;
                warnings.push(`Python dependencies (requirements.txt) failed to install (${e.message}); install them manually with "${python} -m pip install -r requirements.txt".`);
            }
        }
        if (existsSync(installScript)) {
            try {
                execFileSync(python, [installScript], {
                    cwd: nodeDir,
                    encoding: "utf-8",
                    timeout: COMFY_CLI_TIMEOUT,
                });
            }
            catch (err) {
                const e = err;
                warnings.push(`install.py failed to run (${e.message}); the node may need manual setup.`);
            }
        }
    }
    const base = alreadyPresent
        ? `"${repoName}" already exists in custom_nodes (${repoName}) — left it in place.`
        : `"${repoName}" is not in the ComfyUI-Manager registry — cloned it directly into custom_nodes (${repoName}).`;
    const warn = warnings.length ? ` ${warnings.join(" ")}` : "";
    return {
        mechanism: "git-clone",
        message: `${base}${warn} RESTART ComfyUI to load it.`,
        details: { nodeDir, warnings, managerStatus },
    };
}
export async function installCustomNode(opts) {
    const { id, version, mode = "remote", channel = "default" } = opts;
    const parsedGit = parseGitUrl(id);
    const gitId = parsedGit.baseUrl;
    const gitRefCandidate = opts.ref ?? parsedGit.ref ?? version;
    const source = opts.source && opts.source !== "auto"
        ? opts.source
        : looksLikeGitUrl(gitId)
            ? "git"
            : "registry";
    const gitRef = source === "git" && gitRefCandidate
        ? validateGitRef(gitRefCandidate)
        : gitRefCandidate;
    // SECURITY: validate a git URL ONCE, up front, before it can reach ANY install
    // path — cm-cli (`cm-cli install <url>`), the Manager queue, or the clone
    // fallback. Rejects option-injection (leading "-") / non-git / control chars.
    // The repo-name + custom_nodes-containment checks live where the on-disk dir is
    // actually used (runGitCheckout, cloneCustomNodeFallback).
    if (source === "git")
        assertSafeGitUrl(gitId);
    if (opts.useCmCli) {
        // cm-cli install accepts registry ids and git urls alike.
        const installId = source === "git" ? gitId : id;
        const out = runCmCli(["install", installId, "--mode", mode, "--channel", channel]);
        if (source === "git" && gitRef) {
            runGitCheckout(gitId, gitRef);
        }
        return {
            mechanism: "comfy-cli",
            message: `Installed "${id}" via official comfy-cli.`,
            details: out.trim(),
        };
    }
    if (source === "git") {
        const repoName = gitCheckoutDir(gitId);
        let status;
        if ((await detectManagerApi()) !== "v2") {
            // 3.x SEMANTICS (both the custom-node Manager AND pip Manager in
            // legacy-UI mode, whose /v2 batch runs the same 3.x handlers — codex
            // review on #235): a REAL git URL installs natively via
            // { version:'unknown', files:[url] }, cloning it as an unregistered
            // pack. (Gated server-side by security_level + allow_git_url_install
            // config — a rejection surfaces as a 403/404 from the queue route.)
            status = await queueManagerTask("install", {
                id: repoName,
                version: "unknown",
                selected_version: "unknown",
                files: [gitId],
                channel: opts.channel ?? "default",
                mode: opts.mode ?? "cache",
            });
        }
        else {
            // Manager v4: REGISTRY-FIRST, CLONE FALLBACK. The v4 backend resolves an
            // install by the pack's REPO NAME / CNR id — NOT a full git URL
            // (do_install splits `${id}@${selected_version}` and looks the result up
            // in its DB; a full URL matches nothing and the queue silently marks the
            // task "done"). So we mirror the frontend UI: id = repo name,
            // selected_version = ref or "nightly" (the git-HEAD channel for unclaimed
            // packs), channel "dev", mode "cache".
            const selected = gitRef ?? "nightly";
            status = await queueManagerTask("install", {
                id: repoName,
                version: selected,
                selected_version: selected,
                channel: opts.channel ?? "dev",
                mode: opts.mode ?? "cache",
            });
        }
        // VERIFY: /v2/customnode/installed reflects on-disk custom_nodes, so a
        // freshly-cloned pack shows up even before a reboot. If the Manager actually
        // installed it, we're done; otherwise it's unregistered → clone it directly.
        const installed = await listInstalledNodes().catch(() => []);
        if (nodeInstalledMatches(gitId, installed)) {
            return {
                mechanism: "manager-http",
                message: `Installed "${repoName}" via ComfyUI-Manager. Restart may be required to load new nodes.`,
                details: status,
            };
        }
        return cloneCustomNodeFallback(gitId, repoName, gitRef, status);
    }
    // Registry (plain CNR id). Keep the prior defaults channel "default" /
    // mode "remote" (overridable via opts) — forcing "dev"/"cache" risks resolving
    // a different build or failing for default-only packs. The UI-style
    // "dev"/"cache" is used ONLY for the git registry-first lookup above. Then
    // VERIFY the pack actually landed — a non-URL id can't be cloned, so an absent
    // pack is a hard error rather than a silent no-op.
    const status = await queueManagerTask("install", {
        id,
        version: version ?? "latest",
        selected_version: version ?? "latest",
        channel,
        mode,
    });
    const installed = await listInstalledNodes().catch(() => []);
    if (!nodeInstalledMatches(id, installed)) {
        throw new NodeManagementError(`"${id}" was queued but is not present afterward — it was not found in the ` +
            `ComfyUI-Manager registry. Check the pack id, or pass a git URL to clone ` +
            `it directly.`, status);
    }
    return {
        mechanism: "manager-http",
        message: `Installed "${id}" via ComfyUI-Manager. Restart may be required to load new nodes.`,
        details: status,
    };
}
export async function updateCustomNode(opts) {
    const { id, mode = "remote", channel = "default" } = opts;
    const all = id.trim().toLowerCase() === "all";
    if (opts.useCmCli) {
        const out = runCmCli(["update", id, "--mode", mode, "--channel", channel]);
        return {
            mechanism: "comfy-cli",
            message: all
                ? "Updated all installed node packs via official comfy-cli."
                : `Updated "${id}" via official comfy-cli.`,
            details: out.trim(),
        };
    }
    let status;
    if (all) {
        // update_all keeps its own dedicated route. The backend reads
        // UpdateAllQueryParams from the QUERY STRING (manager_server.py), NOT the
        // JSON body — a body-only request leaves mode defaulting to 'remote' and
        // drops client_id/ui_id. Send them as URL query params.
        const uiId = randomUUID();
        if ((await detectManagerApi()) === "legacy") {
            // 3.x reads {mode} from the JSON BODY (and ignores client_id/ui_id).
            await managerFetch("/manager/queue/update_all", {
                method: "POST",
                body: { mode, ui_id: uiId },
            });
        }
        else {
            const query = new URLSearchParams({
                mode,
                client_id: MANAGER_CLIENT_ID,
                ui_id: uiId,
            }).toString();
            await managerFetch(`/v2/manager/queue/update_all?${query}`, {
                method: "POST",
            });
        }
        status = await runManagerQueue();
    }
    else {
        // Single-pack update → unified task; UpdatePackParams uses node_name/node_ver.
        status = await queueManagerTask("update", { node_name: id });
    }
    return {
        mechanism: "manager-http",
        message: all
            ? "Queued + updated all installed node packs via ComfyUI-Manager."
            : `Queued + updated "${id}" via ComfyUI-Manager.`,
        details: status,
    };
}
export async function reinstallCustomNode(opts) {
    const { id, version, mode = "remote", channel = "default" } = opts;
    if (opts.useCmCli) {
        const out = runCmCli(["reinstall", id, "--mode", mode, "--channel", channel]);
        return {
            mechanism: "comfy-cli",
            message: `Reinstalled "${id}" via official comfy-cli.`,
            details: out.trim(),
        };
    }
    // The unified queue has no `reinstall` kind, so model it as uninstall + a
    // fresh install of the same target. Each is its own drained queue cycle.
    await queueManagerTask("uninstall", { node_name: id });
    const status = await queueManagerTask("install", {
        id,
        version: version ?? "latest",
        selected_version: version ?? "latest",
        channel,
        mode,
    });
    return {
        mechanism: "manager-http",
        message: `Queued + reinstalled "${id}" (uninstall + install) via ComfyUI-Manager. A restart may be required.`,
        details: status,
    };
}
export async function fixCustomNode(opts) {
    const { id, mode = "remote", channel = "default" } = opts;
    const all = id.trim().toLowerCase() === "all";
    // The HTTP API has no "fix all"; cm-cli supports it. Route accordingly.
    if (opts.useCmCli || all) {
        const out = runCmCli(["fix", id, "--mode", mode, "--channel", channel]);
        return {
            mechanism: "comfy-cli",
            message: all
                ? "Repaired all installed node packs via official comfy-cli."
                : `Repaired "${id}" via official comfy-cli.`,
            details: out.trim(),
        };
    }
    // FixPackParams requires node_ver; "" lets Manager resolve the installed
    // version (do_fix looks the pack up by name).
    const status = await queueManagerTask("fix", { node_name: id, node_ver: "" });
    return {
        mechanism: "manager-http",
        message: `Queued + repaired "${id}" via ComfyUI-Manager.`,
        details: status,
    };
}
export async function listInstalledNodes(opts = {}) {
    const { mode = "default" } = opts;
    if (opts.useCmCli) {
        // cm-cli `show installed` prints a formatted table — return raw lines as
        // pseudo-nodes since structured data is HTTP-only.
        const out = runCmCli(["show", "installed"]);
        const lines = out
            .split("\n")
            .map((l) => l.trim())
            .filter((l) => l.length > 0 && !l.startsWith("#"));
        return lines.map((line) => ({
            module: line,
            enabled: true,
            version: undefined,
        }));
    }
    // Both pip-Manager modes serve /v2/customnode/installed (the legacy-UI
    // module registers it too); only the 3.x custom-node Manager lacks /v2.
    const prefix = (await detectManagerApi()) === "legacy" ? "" : "/v2";
    const raw = await managerFetch(`${prefix}/customnode/installed?mode=${encodeURIComponent(mode)}`);
    return parseInstalled(raw);
}
/**
 * Reconcile installed-node Python dependencies. comfy-cli exposes this as
 * `node uv-sync`, but ComfyUI-Manager has no `uv-sync` subcommand or HTTP
 * endpoint; the equivalent reconciliation is cm-cli `restore-dependencies`,
 * which reinstalls each installed pack's requirements. Subprocess-only.
 */
export async function syncNodeDependencies() {
    const out = runCmCli(["restore-dependencies"]);
    return {
        mechanism: "comfy-cli",
        message: "Reconciled installed-node Python dependencies via official comfy-cli node restore-dependencies.",
        details: out.trim(),
    };
}
// Remote (Manager-dispatched) downloads run server-side: the queue reports
// "done" at dispatch/aria2-handoff while the host still streams gigabytes, so
// tray progress can't come from bytes we never see (issue #143). Instead, poll
// the server's /models/<category> listing — verified live: an in-progress file
// is NOT listed; it appears when the download completes.
const REMOTE_LANDING_POLL_MS = 5_000;
const REMOTE_LANDING_TIMEOUT_MS = 4 * 60 * 60 * 1000; // generous: multi-GB on slow links
/**
 * Background tray reporter for a server-side model download. Writes an
 * indeterminate "downloading" row immediately (and as a heartbeat, so the
 * orchestrator's 60s dead-writer sweep doesn't prune long downloads), then a
 * terminal "done" when the filename appears in /models/<category>, or "error"
 * if it never shows within the timeout. Fire-and-forget: the tool call returns
 * at dispatch; this keeps the tray honest afterwards. No-op outside the panel
 * (progress channel disabled).
 */
export function watchRemoteModelLanding(category, filename, url) {
    if (!progressEnabled())
        return;
    const id = createHash("sha256").update(url).digest("hex").slice(0, 16);
    const row = { id, name: filename, downloaded: 0, total: 0, bytes_per_sec: 0 };
    reportDownloadProgress({ ...row, status: "downloading" }, true);
    const started = Date.now();
    const timer = setInterval(() => {
        void (async () => {
            let listed = false;
            try {
                const res = await comfyuiFetch(`${getComfyUIBaseUrl()}/models/${encodeURIComponent(category)}`);
                if (res.ok) {
                    const names = (await res.json());
                    // Entries are relative paths ("file.safetensors" or "sub/file.safetensors").
                    listed =
                        Array.isArray(names) &&
                            names.some((n) => typeof n === "string" &&
                                (n === filename || n.endsWith(`/${filename}`) || n.endsWith(`\\${filename}`)));
                }
            }
            catch {
                // Server briefly unreachable (e.g. mid-reboot) — keep waiting.
            }
            if (listed) {
                clearInterval(timer);
                reportDownloadProgress({ ...row, status: "done" }, true);
            }
            else if (Date.now() - started > REMOTE_LANDING_TIMEOUT_MS) {
                clearInterval(timer);
                reportDownloadProgress({ ...row, status: "error" }, true);
            }
            else {
                reportDownloadProgress({ ...row, status: "downloading" }, true);
            }
        })();
    }, REMOTE_LANDING_POLL_MS);
    timer.unref?.();
}
/**
 * Install a model on the connected ComfyUI host via ComfyUI-Manager's unified
 * task queue (`install-model` kind). Wraps the same queue task + drain
 * (start → poll status) flow that custom-node installs use, so it works against
 * a REMOTE ComfyUI where the MCP has no local filesystem. The Manager backend
 * fetches `url` server-side into the target model directory.
 */
export async function installModelViaManager(params) {
    // Build the ModelMetadata params exactly as Manager 4.2.2 expects. ALL of
    // name/type/url/filename/save_path are load-bearing (verified live against a
    // RunPod pod): `name` and `save_path` were the two missing fields that made
    // the task dispatch but silently install nothing.
    const name = params.name && params.name.trim().length > 0 ? params.name : params.filename;
    const save_path = params.save_path && params.save_path.trim().length > 0
        ? params.save_path
        : "default";
    const taskParams = {
        name,
        url: params.url,
        filename: params.filename,
        type: params.type,
        save_path,
    };
    const status = await queueManagerTask("install-model", taskParams);
    // NOTE: the Manager queue reports the task "done" once it DRAINS, even when
    // the underlying OperationResult failed (e.g. a 404 download, or Manager's
    // security gate rejecting a network fetch) — and with an aria2 sidecar
    // (COMFYUI_MANAGER_ARIA2_SERVER) it drains at HANDOFF, while the host is
    // still streaming gigabytes. The v2 queue/status endpoint only exposes
    // aggregate counts (no per-task result), so a clean drain here does NOT
    // prove the file landed — phrase the result as "dispatched", not
    // "installed", and leave final verification to a list on the pod.
    //
    // DEPLOYMENT: remote model install requires the pod's ComfyUI-Manager to be
    // in network_mode=personal_cloud (or loopback) with permissive security; a
    // stricter security_level rejects the server-side download.
    if (params.trayCategory) {
        watchRemoteModelLanding(params.trayCategory, params.filename, params.url);
    }
    return {
        mechanism: "manager-http",
        message: `Dispatched model "${name}" (${params.filename}) to install into ` +
            `${params.type} on the connected ComfyUI via ComfyUI-Manager. The queue ` +
            `drained, but that only means the download was HANDED OFF (with an aria2 ` +
            `sidecar the host keeps streaming after the queue drains), and Manager ` +
            `reports tasks "done" even on failure with no per-task result — so ` +
            `success is NOT guaranteed. The file appears in the server's ` +
            `/models/<category> listing only once the download COMPLETES (in-progress ` +
            `files are hidden), and Manager may store it under its own type dir ` +
            `(e.g. unet/, clip/) which ComfyUI aliases to diffusion_models/` +
            `text_encoders — an empty canonical folder mid-download is NORMAL, not a ` +
            `failure. Wait and re-check before re-dispatching (duplicates waste ` +
            `bandwidth); a restart may be required for loaders to see the file. If ` +
            `nothing ever lands, confirm Manager runs with ` +
            `network_mode=personal_cloud (or loopback) and a permissive security ` +
            `level so server-side downloads aren't blocked.`,
        details: status,
    };
}
//# sourceMappingURL=node-management.js.map