taskmeld 0.1.1

package/dist/src/cli/server-runtime-client.js

@@ -0,0 +1,780 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPipelineRuntimeApiClient = exports.createServerLifecycleClient = void 0;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const ws_1 = __importDefault(require("ws"));
+const app_context_env_1 = require("../app/app-context-env");
+const data_dir_1 = require("../app/data-dir");
+const errors_1 = require("./errors");
+const STARTUP_LOCK_STALE_MS = 15_000;
+const STARTUP_LOCK_WAIT_MS = 250;
+const STARTUP_TIMEOUT_MS = 15_000;
+const STOP_TIMEOUT_MS = 10_000;
+const buildApiBaseUrl = () => {
+    const config = (0, app_context_env_1.resolveAppContextConfig)();
+    // CLI 访问本地常驻后端时固定走 loopback，避免 0.0.0.0 作为 client 目标地址不可直连。
+    return `http://127.0.0.1:${config.apiPort}`;
+};
+const buildWsBaseUrl = () => {
+    const config = (0, app_context_env_1.resolveAppContextConfig)();
+    return `ws://127.0.0.1:${config.apiPort}`;
+};
+const buildPipelineApiUrl = (pipelineId, suffix) => `${buildApiBaseUrl()}/api/pipelines/${encodeURIComponent(pipelineId)}${suffix}`;
+const buildPipelineApiUrlWithIdentity = (pipelineId, suffix, target) => {
+    const url = new URL(buildPipelineApiUrl(pipelineId, suffix));
+    if (typeof target?.runId === "string" && target.runId.trim()) {
+        url.searchParams.set("runId", target.runId.trim());
+    }
+    if (typeof target?.batchRunId === "string" && target.batchRunId.trim()) {
+        url.searchParams.set("batchRunId", target.batchRunId.trim());
+    }
+    return url.toString();
+};
+const resolveRuntimePipelineSelector = (selector) => {
+    if (typeof selector === "string" && selector.trim()) {
+        return { pipelineId: selector.trim() };
+    }
+    if (!selector || typeof selector === "string") {
+        throw new errors_1.CliError("Missing pipelineId for runtime API selector", {
+            code: "INVALID_ARGUMENT",
+            exitCode: 2,
+            details: {
+                runId: null,
+                batchRunId: null,
+            },
+        });
+    }
+    const pipelineId = typeof selector.pipelineId === "string" ? selector.pipelineId.trim() : "";
+    if (!pipelineId) {
+        // runtime API 的 status/stop 路由仍是 /api/pipelines/:pipelineId/*，runId/batchRunId 仅用于“精确命中当前 pipeline 运行”。
+        throw new errors_1.CliError("Missing pipelineId for runtime API selector", {
+            code: "INVALID_ARGUMENT",
+            exitCode: 2,
+            details: {
+                runId: selector?.runId ?? null,
+                batchRunId: selector?.batchRunId ?? null,
+            },
+        });
+    }
+    return {
+        pipelineId,
+        target: {
+            runId: selector?.runId,
+            batchRunId: selector?.batchRunId,
+        },
+    };
+};
+const waitForPipelineWatchSignal = async (selector, timeoutMs) => {
+    const wsUrl = `${buildWsBaseUrl()}/api/ws`;
+    const eventType = await new Promise((resolve, reject) => {
+        let settled = false;
+        let timeoutHandle = null;
+        const ws = new ws_1.default(wsUrl);
+        const finish = (error, payload) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            try {
+                ws.close();
+            }
+            catch {
+                // Ignore close failure; caller only cares about wake-up semantics.
+            }
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve(payload?.eventType ?? "pipeline.updated");
+        };
+        const matchesPipelineUpdated = (payload) => {
+            const eventPipelineId = typeof payload.pipelineId === "string" ? payload.pipelineId.trim() : "";
+            const eventRunId = typeof payload.runId === "string" ? payload.runId.trim() : "";
+            const runRecord = payload.run && typeof payload.run === "object" ? payload.run : null;
+            const runIdFromRun = typeof runRecord?.id === "string" ? runRecord.id.trim() : "";
+            if (selector.pipelineId && selector.pipelineId !== eventPipelineId)
+                return false;
+            if (selector.runId) {
+                return selector.runId === eventRunId || selector.runId === runIdFromRun;
+            }
+            // batchRunId 在 pipeline.updated 中没有稳定字段；这里把更新当作“状态可能变化”的唤醒信号，
+            // 实际终态判断仍由后续 status 请求完成，避免因为事件字段缺失误判终态。
+            if (selector.batchRunId)
+                return true;
+            return Boolean(selector.pipelineId);
+        };
+        const matchesBootstrap = (payload) => {
+            const pipelines = payload.pipelines && typeof payload.pipelines === "object"
+                ? payload.pipelines
+                : null;
+            if (!pipelines)
+                return false;
+            if (selector.pipelineId && pipelines[selector.pipelineId])
+                return true;
+            if (selector.runId) {
+                for (const item of Object.values(pipelines)) {
+                    if (!item || typeof item !== "object")
+                        continue;
+                    const runId = typeof item.runId === "string" ? String(item.runId) : "";
+                    if (runId && runId === selector.runId)
+                        return true;
+                }
+            }
+            return false;
+        };
+        ws.on("open", () => {
+            timeoutHandle = setTimeout(() => {
+                finish(new errors_1.CliError("Pipeline watch event-stream wait timed out", {
+                    code: "PIPELINE_WATCH_WS_TIMEOUT",
+                    exitCode: 4,
+                    details: {
+                        selector,
+                        timeoutMs,
+                        wsUrl,
+                    },
+                }));
+            }, timeoutMs);
+        });
+        ws.on("message", (event) => {
+            const raw = typeof event === "string" ? event : event.toString();
+            if (!raw)
+                return;
+            let parsed = null;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return;
+            }
+            if (!parsed || typeof parsed.type !== "string")
+                return;
+            const payload = parsed.payload && typeof parsed.payload === "object" ? parsed.payload : null;
+            if (!payload)
+                return;
+            if (parsed.type === "pipeline.updated" && matchesPipelineUpdated(payload)) {
+                finish(undefined, { eventType: "pipeline.updated" });
+                return;
+            }
+            if (parsed.type === "bootstrap" && matchesBootstrap(payload)) {
+                finish(undefined, { eventType: "bootstrap" });
+            }
+        });
+        ws.on("error", () => {
+            finish(new errors_1.CliError("Pipeline watch event-stream unavailable", {
+                code: "PIPELINE_WATCH_WS_UNAVAILABLE",
+                exitCode: 4,
+                details: {
+                    selector,
+                    wsUrl,
+                },
+            }));
+        });
+        ws.on("close", () => {
+            if (!settled) {
+                finish(new errors_1.CliError("Pipeline watch event-stream closed", {
+                    code: "PIPELINE_WATCH_WS_CLOSED",
+                    exitCode: 4,
+                    details: {
+                        selector,
+                        wsUrl,
+                    },
+                }));
+            }
+        });
+    });
+    return { ok: true, source: "ws", eventType };
+};
+const sleep = async (ms) => {
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+};
+const pathExists = async (filePath) => {
+    try {
+        await (0, promises_1.access)(filePath, node_fs_1.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const getWorkspaceRoot = () => {
+    let current = __dirname;
+    for (let depth = 0; depth < 8; depth += 1) {
+        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(current, "package.json"))) {
+            return current;
+        }
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return process.cwd();
+};
+const getServerRuntimeDir = () => {
+    const override = process.env.TASKMELD_SERVER_RUNTIME_DIR?.trim();
+    if (override)
+        return override;
+    return (0, data_dir_1.resolveTaskMeldDataPath)("server");
+};
+const getServerRuntimeMetadataPath = () => (0, node_path_1.join)(getServerRuntimeDir(), "runtime.json");
+const getServerStartupLockPath = () => (0, node_path_1.join)(getServerRuntimeDir(), "startup.lock");
+const normalizeOptionalString = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+const writeRuntimeMetadata = async (metadata) => {
+    await (0, promises_1.mkdir)(getServerRuntimeDir(), { recursive: true });
+    await (0, promises_1.writeFile)(getServerRuntimeMetadataPath(), JSON.stringify(metadata, null, 2), "utf8");
+};
+const readRuntimeMetadata = async () => {
+    try {
+        const raw = await (0, promises_1.readFile)(getServerRuntimeMetadataPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.pid !== "number" ||
+            !Number.isFinite(parsed.pid) ||
+            typeof parsed.port !== "number" ||
+            !Number.isFinite(parsed.port) ||
+            typeof parsed.endpoint !== "string" ||
+            !parsed.endpoint.trim() ||
+            typeof parsed.startedAt !== "string" ||
+            !parsed.startedAt.trim()) {
+            return null;
+        }
+        return {
+            serverId: normalizeOptionalString(parsed.serverId),
+            pid: Math.trunc(parsed.pid),
+            port: Math.trunc(parsed.port),
+            endpoint: parsed.endpoint.trim(),
+            startedAt: parsed.startedAt.trim(),
+        };
+    }
+    catch {
+        return null;
+    }
+};
+const readServerHealth = async () => {
+    try {
+        const response = await fetch(`${buildApiBaseUrl()}/api/health`);
+        if (!response.ok)
+            return null;
+        const payload = await response.json();
+        if (payload.ok !== true ||
+            typeof payload.pid !== "number" ||
+            !Number.isFinite(payload.pid) ||
+            typeof payload.port !== "number" ||
+            !Number.isFinite(payload.port) ||
+            typeof payload.endpoint !== "string" ||
+            !payload.endpoint.trim() ||
+            typeof payload.startedAt !== "string" ||
+            !payload.startedAt.trim()) {
+            return null;
+        }
+        return {
+            ok: true,
+            serverId: normalizeOptionalString(payload.serverId),
+            pid: Math.trunc(payload.pid),
+            port: Math.trunc(payload.port),
+            endpoint: payload.endpoint.trim(),
+            startedAt: payload.startedAt.trim(),
+        };
+    }
+    catch {
+        return null;
+    }
+};
+const metadataMatchesHealth = (metadata, health) => {
+    if (!metadata)
+        return false;
+    if (metadata.pid !== health.pid || metadata.port !== health.port || metadata.endpoint !== health.endpoint) {
+        return false;
+    }
+    if (metadata.serverId && health.serverId) {
+        return metadata.serverId === health.serverId;
+    }
+    // 兼容旧 metadata：早期 runtime.json 不含 serverId，此时退回 pid/port/endpoint 交叉校验。
+    return true;
+};
+const buildMetadataFromHealth = (health) => ({
+    serverId: health.serverId,
+    pid: health.pid,
+    port: health.port,
+    endpoint: health.endpoint,
+    startedAt: health.startedAt,
+});
+const getExpectedRuntimeOwner = () => {
+    const endpoint = buildApiBaseUrl();
+    const parsed = new URL(endpoint);
+    return {
+        endpoint,
+        port: Number(parsed.port),
+    };
+};
+const probeRuntimeOwnership = async () => {
+    const [metadata, health] = await Promise.all([readRuntimeMetadata(), readServerHealth()]);
+    const expected = getExpectedRuntimeOwner();
+    const pid = metadata?.pid ?? health?.pid ?? null;
+    const pidRunning = isPidRunning(pid);
+    const metadataMatchesExpected = Boolean(metadata && metadata.endpoint === expected.endpoint && metadata.port === expected.port);
+    const healthMatchesExpected = Boolean(health && health.endpoint === expected.endpoint && health.port === expected.port);
+    const metadataMatchesLiveOwner = health ? metadataMatchesHealth(metadata, health) : false;
+    const ownership = !metadata
+        ? "metadata_missing"
+        : metadataMatchesExpected && (!health || metadataMatchesLiveOwner) && (!health || healthMatchesExpected)
+            ? "matched"
+            : "metadata_mismatch";
+    const metadataStale = Boolean(metadata && !pidRunning && !health);
+    let lockStale = false;
+    try {
+        const lockStat = await (0, promises_1.stat)(getServerStartupLockPath());
+        lockStale = Date.now() - lockStat.mtimeMs > STARTUP_LOCK_STALE_MS;
+    }
+    catch {
+        lockStale = false;
+    }
+    return {
+        endpoint: expected.endpoint,
+        expectedPort: expected.port,
+        ready: health !== null,
+        metadataPresent: metadata !== null,
+        ownership,
+        ownershipMatched: ownership === "matched",
+        metadataStale,
+        lockStale,
+        pid,
+        pidRunning,
+        startedAt: metadata?.startedAt ?? health?.startedAt ?? null,
+        metadata,
+        health,
+    };
+};
+const cleanupStaleRuntimeArtifacts = async (probe) => {
+    if (probe.metadataStale) {
+        await (0, promises_1.rm)(getServerRuntimeMetadataPath(), { force: true });
+    }
+    // startup.lock 是“开始拉起”的互斥标记，不是 owner 证据；只有健康实例不存在且锁超时才允许清理。
+    if (!probe.ready && probe.lockStale) {
+        await (0, promises_1.rm)(getServerStartupLockPath(), { force: true });
+    }
+};
+const reconcileRuntimeMetadataWithHealth = async (probe) => {
+    if (!probe.health)
+        return probe.metadata;
+    const nextMetadata = buildMetadataFromHealth(probe.health);
+    if (!metadataMatchesHealth(probe.metadata, probe.health)) {
+        // health 请求已经命中了当前 CLI 期望的 endpoint；只要这份 owner 信息完整，就应该回填 metadata，
+        // 否则 metadata_missing / metadata_mismatch 会在后续 ensure/status/stop 中反复被误判为异常状态。
+        await writeRuntimeMetadata(nextMetadata);
+        return nextMetadata;
+    }
+    return nextMetadata;
+};
+const isPidRunning = (pid) => {
+    if (typeof pid !== "number" || !Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(Math.trunc(pid), 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const normalizeServerError = async (response) => {
+    let payload = null;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        payload = null;
+    }
+    const code = typeof payload?.error === "string" && payload.error.trim() ? payload.error.trim().toUpperCase() : "SERVER_REQUEST_FAILED";
+    const message = typeof payload?.error === "string" && payload.error.trim()
+        ? payload.error.trim()
+        : `server request failed: ${response.status}`;
+    throw new errors_1.CliError(message, {
+        code,
+        exitCode: response.status === 404 ? 3 : response.status === 400 ? 2 : 4,
+        details: {
+            status: response.status,
+            payload,
+        },
+    });
+};
+const requestJson = async (url, init) => {
+    let response;
+    try {
+        response = await fetch(url, init);
+    }
+    catch (error) {
+        throw new errors_1.CliError("Local API server is unavailable", {
+            code: "LOCAL_API_UNAVAILABLE",
+            exitCode: 5,
+            details: {
+                url,
+                detail: error instanceof Error ? error.message : "unknown_error",
+            },
+        });
+    }
+    if (!response.ok) {
+        await normalizeServerError(response);
+    }
+    return response.json();
+};
+const isServerHealthy = async () => {
+    return (await readServerHealth()) !== null;
+};
+const waitForHealth = async (timeoutMs) => {
+    const startAt = Date.now();
+    while (Date.now() - startAt <= timeoutMs) {
+        if (await isServerHealthy())
+            return;
+        await sleep(250);
+    }
+    throw new errors_1.CliError("Local API server failed to become healthy", {
+        code: "LOCAL_API_START_TIMEOUT",
+        exitCode: 5,
+        details: {
+            endpoint: buildApiBaseUrl(),
+            timeoutMs,
+        },
+    });
+};
+const resolveServerLaunchSpec = async () => {
+    const workspaceRoot = getWorkspaceRoot();
+    const distEntry = (0, node_path_1.join)(workspaceRoot, "dist", "src", "index.js");
+    if (await pathExists(distEntry)) {
+        return {
+            command: process.execPath,
+            args: [distEntry],
+            cwd: workspaceRoot,
+        };
+    }
+    const srcEntry = (0, node_path_1.join)(workspaceRoot, "src", "index.ts");
+    const tsxCmd = process.platform === "win32"
+        ? (0, node_path_1.join)(workspaceRoot, "node_modules", ".bin", "tsx.cmd")
+        : (0, node_path_1.join)(workspaceRoot, "node_modules", ".bin", "tsx");
+    if (await pathExists(srcEntry) && await pathExists(tsxCmd)) {
+        return {
+            command: tsxCmd,
+            args: [srcEntry],
+            cwd: workspaceRoot,
+        };
+    }
+    throw new errors_1.CliError("Unable to resolve local API server entry", {
+        code: "LOCAL_API_ENTRY_NOT_FOUND",
+        exitCode: 5,
+        details: {
+            workspaceRoot,
+            checked: [distEntry, srcEntry, tsxCmd],
+        },
+    });
+};
+const acquireStartupLock = async () => {
+    const lockPath = getServerStartupLockPath();
+    await (0, promises_1.mkdir)(getServerRuntimeDir(), { recursive: true });
+    const startAt = Date.now();
+    while (Date.now() - startAt <= STARTUP_TIMEOUT_MS) {
+        try {
+            const handle = await (0, promises_1.open)(lockPath, "wx");
+            return async () => {
+                await handle.close();
+                await (0, promises_1.rm)(lockPath, { force: true });
+            };
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code !== "EEXIST") {
+                throw new errors_1.CliError("Failed to acquire local API startup lock", {
+                    code: "LOCAL_API_LOCK_FAILED",
+                    exitCode: 5,
+                    details: {
+                        lockPath,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                });
+            }
+            if (await isServerHealthy()) {
+                const probe = await probeRuntimeOwnership();
+                await reconcileRuntimeMetadataWithHealth(probe);
+                return async () => { };
+            }
+            try {
+                const lockStat = await (0, promises_1.stat)(lockPath);
+                if (Date.now() - lockStat.mtimeMs > STARTUP_LOCK_STALE_MS) {
+                    await (0, promises_1.rm)(lockPath, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            await sleep(STARTUP_LOCK_WAIT_MS);
+        }
+    }
+    throw new errors_1.CliError("Timed out waiting for local API startup lock", {
+        code: "LOCAL_API_LOCK_TIMEOUT",
+        exitCode: 5,
+        details: {
+            lockPath,
+            timeoutMs: STARTUP_TIMEOUT_MS,
+        },
+    });
+};
+const startLocalApiServer = async () => {
+    const initialProbe = await probeRuntimeOwnership();
+    await cleanupStaleRuntimeArtifacts(initialProbe);
+    await reconcileRuntimeMetadataWithHealth(initialProbe);
+    if (initialProbe.ready) {
+        const verifiedProbe = await probeRuntimeOwnership();
+        return {
+            ok: true,
+            endpoint: buildApiBaseUrl(),
+            action: "already_running",
+            reused: true,
+            ownership: verifiedProbe.ownership,
+            metadataStale: verifiedProbe.metadataStale,
+            lockStale: verifiedProbe.lockStale,
+            pid: verifiedProbe.health?.pid ?? verifiedProbe.metadata?.pid ?? verifiedProbe.pid,
+            startedAt: verifiedProbe.health?.startedAt ?? verifiedProbe.metadata?.startedAt ?? verifiedProbe.startedAt,
+        };
+    }
+    const releaseLock = await acquireStartupLock();
+    try {
+        const lockedProbe = await probeRuntimeOwnership();
+        await cleanupStaleRuntimeArtifacts(lockedProbe);
+        await reconcileRuntimeMetadataWithHealth(lockedProbe);
+        if (lockedProbe.ready) {
+            const verifiedProbe = await probeRuntimeOwnership();
+            return {
+                ok: true,
+                endpoint: buildApiBaseUrl(),
+                action: "already_running",
+                reused: true,
+                ownership: verifiedProbe.ownership,
+                metadataStale: verifiedProbe.metadataStale,
+                lockStale: verifiedProbe.lockStale,
+                pid: verifiedProbe.health?.pid ?? verifiedProbe.metadata?.pid ?? verifiedProbe.pid,
+                startedAt: verifiedProbe.health?.startedAt ?? verifiedProbe.metadata?.startedAt ?? verifiedProbe.startedAt,
+            };
+        }
+        const launchSpec = await resolveServerLaunchSpec();
+        // 后台 daemon 必须脱离当前 CLI 生命周期运行，否则 watch/start 等命令一结束就会把宿主一并带死。
+        const child = (0, node_child_process_1.spawn)(launchSpec.command, launchSpec.args, {
+            cwd: launchSpec.cwd,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.unref();
+        await waitForHealth(STARTUP_TIMEOUT_MS);
+        const finalProbe = await probeRuntimeOwnership();
+        await reconcileRuntimeMetadataWithHealth(finalProbe);
+        const verifiedProbe = await probeRuntimeOwnership();
+        return {
+            ok: true,
+            endpoint: buildApiBaseUrl(),
+            action: "started",
+            reused: false,
+            ownership: verifiedProbe.ownership,
+            metadataStale: verifiedProbe.metadataStale,
+            lockStale: verifiedProbe.lockStale,
+            pid: verifiedProbe.health?.pid ?? verifiedProbe.metadata?.pid ?? child.pid ?? null,
+            startedAt: verifiedProbe.health?.startedAt ?? verifiedProbe.metadata?.startedAt ?? null,
+        };
+    }
+    finally {
+        await releaseLock();
+    }
+};
+const ensureServerReady = async () => {
+    const probe = await probeRuntimeOwnership();
+    await cleanupStaleRuntimeArtifacts(probe);
+    await reconcileRuntimeMetadataWithHealth(probe);
+    if (probe.ready) {
+        const verifiedProbe = await probeRuntimeOwnership();
+        return {
+            ok: true,
+            endpoint: buildApiBaseUrl(),
+            action: "ensured",
+            reused: true,
+            ownership: verifiedProbe.ownership,
+            metadataStale: verifiedProbe.metadataStale,
+            lockStale: verifiedProbe.lockStale,
+            pid: verifiedProbe.health?.pid ?? verifiedProbe.metadata?.pid ?? verifiedProbe.pid,
+            startedAt: verifiedProbe.health?.startedAt ?? verifiedProbe.metadata?.startedAt ?? verifiedProbe.startedAt,
+        };
+    }
+    const started = await startLocalApiServer();
+    return {
+        ...started,
+        action: started.action === "already_running" ? "ensured" : started.action,
+    };
+};
+const getServerStatus = async () => {
+    const probe = await probeRuntimeOwnership();
+    await cleanupStaleRuntimeArtifacts(probe);
+    await reconcileRuntimeMetadataWithHealth(probe);
+    const verifiedProbe = await probeRuntimeOwnership();
+    return {
+        ok: true,
+        endpoint: buildApiBaseUrl(),
+        ready: verifiedProbe.ready,
+        metadataPresent: verifiedProbe.metadataPresent,
+        ownership: verifiedProbe.ownership,
+        ownershipMatched: verifiedProbe.ownershipMatched,
+        metadataStale: verifiedProbe.metadataStale,
+        lockStale: verifiedProbe.lockStale,
+        pid: verifiedProbe.health?.pid ?? verifiedProbe.metadata?.pid ?? null,
+        pidRunning: isPidRunning(verifiedProbe.health?.pid ?? verifiedProbe.metadata?.pid ?? null),
+        startedAt: verifiedProbe.health?.startedAt ?? verifiedProbe.metadata?.startedAt ?? null,
+    };
+};
+const stopLocalApiServer = async () => {
+    const probe = await probeRuntimeOwnership();
+    await cleanupStaleRuntimeArtifacts(probe);
+    if (!probe.metadataPresent && !probe.health) {
+        return {
+            ok: true,
+            endpoint: buildApiBaseUrl(),
+            action: "not_running",
+            reused: false,
+            ownership: probe.ownership,
+            metadataStale: probe.metadataStale,
+            lockStale: probe.lockStale,
+            pid: null,
+            startedAt: null,
+        };
+    }
+    if (!probe.health) {
+        const pid = probe.metadata?.pid ?? null;
+        if (!isPidRunning(pid)) {
+            await (0, promises_1.rm)(getServerRuntimeMetadataPath(), { force: true });
+            return {
+                ok: true,
+                endpoint: buildApiBaseUrl(),
+                action: "not_running",
+                reused: false,
+                ownership: probe.ownership,
+                metadataStale: true,
+                lockStale: probe.lockStale,
+                pid: pid ?? null,
+                startedAt: probe.metadata?.startedAt ?? null,
+            };
+        }
+        throw new errors_1.CliError("Refusing to stop unverified local API owner", {
+            code: "LOCAL_API_OWNER_UNVERIFIED",
+            exitCode: 5,
+            details: {
+                pid,
+                endpoint: buildApiBaseUrl(),
+                ownership: probe.ownership,
+            },
+        });
+    }
+    const verifiedMetadata = await reconcileRuntimeMetadataWithHealth(probe);
+    if (!verifiedMetadata) {
+        throw new errors_1.CliError("Refusing to stop: healthy API owner metadata is unavailable", {
+            code: "LOCAL_API_OWNER_METADATA_MISSING",
+            exitCode: 5,
+            details: probe,
+        });
+    }
+    const pid = verifiedMetadata.pid;
+    if (!isPidRunning(pid)) {
+        await (0, promises_1.rm)(getServerRuntimeMetadataPath(), { force: true });
+        return {
+            ok: true,
+            endpoint: buildApiBaseUrl(),
+            action: "not_running",
+            reused: false,
+            ownership: probe.ownership,
+            metadataStale: true,
+            lockStale: probe.lockStale,
+            pid: pid ?? null,
+            startedAt: verifiedMetadata?.startedAt ?? probe.startedAt,
+        };
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (error) {
+        throw new errors_1.CliError("Failed to stop local API server", {
+            code: "LOCAL_API_STOP_FAILED",
+            exitCode: 5,
+            details: {
+                pid,
+                detail: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    const startAt = Date.now();
+    while (Date.now() - startAt <= STOP_TIMEOUT_MS) {
+        if (!isPidRunning(pid) && !await isServerHealthy()) {
+            await (0, promises_1.rm)(getServerRuntimeMetadataPath(), { force: true });
+            return {
+                ok: true,
+                endpoint: buildApiBaseUrl(),
+                action: "stopped",
+                reused: false,
+                ownership: probe.ownership,
+                metadataStale: false,
+                lockStale: false,
+                pid,
+                startedAt: verifiedMetadata?.startedAt ?? probe.startedAt,
+            };
+        }
+        await sleep(250);
+    }
+    throw new errors_1.CliError("Timed out stopping local API server", {
+        code: "LOCAL_API_STOP_TIMEOUT",
+        exitCode: 5,
+        details: {
+            pid,
+            endpoint: buildApiBaseUrl(),
+            timeoutMs: STOP_TIMEOUT_MS,
+        },
+    });
+};
+const createServerLifecycleClient = () => ({
+    ensureServerReady,
+    startServer: startLocalApiServer,
+    getServerStatus,
+    stopServer: stopLocalApiServer,
+});
+exports.createServerLifecycleClient = createServerLifecycleClient;
+const createPipelineRuntimeApiClient = () => ({
+    ensureServerReady,
+    startPipeline: async (pipelineId) => requestJson(buildPipelineApiUrl(pipelineId, "/run"), {
+        method: "POST",
+    }),
+    getPipelineStatus: async (selector) => {
+        const resolved = resolveRuntimePipelineSelector(selector);
+        return requestJson(buildPipelineApiUrlWithIdentity(resolved.pipelineId, "/status", resolved.target));
+    },
+    stopPipeline: async (selector) => {
+        const resolved = resolveRuntimePipelineSelector(selector);
+        return requestJson(buildPipelineApiUrlWithIdentity(resolved.pipelineId, "/stop", resolved.target), {
+            method: "POST",
+        });
+    },
+    waitForPipelineWatchSignal,
+    diagnoseNode: async (pipelineId, nodeId, itemKey) => {
+        const url = new URL(buildPipelineApiUrl(pipelineId, `/nodes/${encodeURIComponent(nodeId)}/diagnostics`));
+        if (itemKey)
+            url.searchParams.set("itemKey", itemKey);
+        return requestJson(url.toString());
+    },
+    getOutput: async (pipelineId, runId) => {
+        const url = new URL(buildPipelineApiUrl(pipelineId, "/outputs"));
+        if (runId)
+            url.searchParams.set("runId", runId);
+        return requestJson(url.toString());
+    },
+    listOutputs: async (pipelineId) => requestJson(buildPipelineApiUrl(pipelineId, "/outputs")),
+    listLinks: async () => requestJson("/api/pipeline-links"),
+    getQueue: async (pipelineId) => requestJson(buildPipelineApiUrl(pipelineId, "/queue")),
+});
+exports.createPipelineRuntimeApiClient = createPipelineRuntimeApiClient;