pi-session-mcp 0.0.0-stage → 0.6.2

package/dist/setup-process.js

@@ -0,0 +1,385 @@
+import { spawn } from "node:child_process";
+import { lstatSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const DEFAULT_TIMEOUT = 10_000;
+const DEFAULT_MAX = 65_536;
+const ABORT_GROUP_CLEANUP_TIMEOUT = 2_000;
+const GUARDIAN_START_TIMEOUT = 5_000;
+/** Kill a detached process and every descendant in its process group. */
+function terminateProcessGroup(child, signal) {
+    if (child.pid === undefined)
+        return;
+    if (process.platform !== "win32") {
+        try {
+            process.kill(-child.pid, signal);
+            return;
+        }
+        catch { /* already exited or no group */ }
+    }
+    try {
+        child.kill(signal);
+    }
+    catch { /* already exited */ }
+}
+function processGroupState(child) {
+    if (child.pid === undefined || process.platform !== "linux")
+        return "unknown";
+    const group = child.pid;
+    try {
+        for (const entry of readdirSync("/proc", { withFileTypes: true })) {
+            if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
+                continue;
+            try {
+                const stat = readProcStat(Number(entry.name));
+                if (stat.pgrp === group && stat.state !== "Z")
+                    return "alive";
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    return "unknown";
+            }
+        }
+    }
+    catch {
+        return "unknown";
+    }
+    return "gone";
+}
+function readProcStat(pid) {
+    const line = readFileSync(`/proc/${pid}/stat`, "utf8").trim();
+    const close = line.lastIndexOf(") ");
+    const state = line[close + 2];
+    if (close < 3 || !state || !/^[A-Za-z]$/.test(state) || line[close + 3] !== " ")
+        throw new Error("process_stat_invalid");
+    const fields = line.slice(close + 4).trim().split(/\s+/);
+    const pgrp = Number(fields[1]);
+    if (!Number.isSafeInteger(pgrp) || pgrp < 0)
+        throw new Error("process_group_invalid");
+    return { pgrp, state };
+}
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+/** Runs only an explicit executable/argv pair, with bounded output and termination. */
+export function createProcessRunner(options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT;
+    const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX;
+    return { run(command, args, signal) {
+            const effectiveSignal = options.signal && signal ? AbortSignal.any([options.signal, signal]) : options.signal ?? signal;
+            if (process.platform !== "linux")
+                return Promise.resolve({ exitCode: 126, stdout: "", stderr: "" });
+            return new Promise((resolve) => {
+                const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe"], env: options.env, detached: process.platform !== "win32" });
+                let stdout = "";
+                let stderr = "";
+                let overflow = false;
+                let aborted = false;
+                const collect = (part) => (chunk) => { const value = chunk.toString("utf8"); const current = part === "stdout" ? stdout : stderr; if (Buffer.byteLength(current + value, "utf8") > maxOutputBytes) {
+                    overflow = true;
+                    return;
+                } if (part === "stdout")
+                    stdout += value;
+                else
+                    stderr += value; };
+                child.stdout.on("data", collect("stdout"));
+                child.stderr.on("data", collect("stderr"));
+                let done = false;
+                let timedOut = false;
+                let killTimer;
+                let hardTimer;
+                let groupPoll;
+                let groupDeadline = 0;
+                const finish = (exitCode) => { if (done)
+                    return; done = true; effectiveSignal?.removeEventListener("abort", abort); clearTimeout(timer); if (!timedOut && killTimer)
+                    clearTimeout(killTimer); if (!timedOut && hardTimer)
+                    clearTimeout(hardTimer); if (groupPoll)
+                    clearTimeout(groupPoll); resolve({ exitCode, stdout: overflow ? Buffer.from(stdout).subarray(0, maxOutputBytes).toString("utf8") : stdout, stderr: overflow ? "output_limit" : stderr }); };
+                const finishAfterGroup = (successCode) => {
+                    if (done)
+                        return;
+                    if (processGroupState(child) === "gone") {
+                        finish(successCode);
+                        return;
+                    }
+                    if (Date.now() >= groupDeadline) {
+                        finish(126);
+                        return;
+                    }
+                    groupPoll = setTimeout(() => finishAfterGroup(successCode), 10);
+                };
+                const abort = () => { if (done)
+                    return; aborted = true; groupDeadline = Date.now() + ABORT_GROUP_CLEANUP_TIMEOUT; terminateProcessGroup(child, "SIGTERM"); killTimer = setTimeout(() => { terminateProcessGroup(child, "SIGKILL"); finishAfterGroup(125); }, 100); };
+                effectiveSignal?.addEventListener("abort", abort, { once: true });
+                if (effectiveSignal?.aborted)
+                    abort();
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    groupDeadline = Date.now() + ABORT_GROUP_CLEANUP_TIMEOUT;
+                    terminateProcessGroup(child, "SIGTERM");
+                    killTimer = setTimeout(() => {
+                        terminateProcessGroup(child, "SIGKILL");
+                        hardTimer = setTimeout(() => finishAfterGroup(124), 100);
+                    }, 100);
+                }, timeoutMs);
+                child.on("error", () => { if (!timedOut) {
+                    if (aborted)
+                        finishAfterGroup(125);
+                    else
+                        finish(127);
+                } });
+                child.on("close", (code) => { if (!timedOut) {
+                    if (aborted)
+                        finishAfterGroup(125);
+                    else
+                        finish(code ?? 1);
+                } });
+            });
+        } };
+}
+/** Starts the local MCP server with only the controlled configuration environment. */
+export function createMcpStdioLauncher(options) {
+    return async (signal) => {
+        const child = spawn(options.nodePath, [options.entryPath], { stdio: ["pipe", "pipe", "pipe"], env: { PI_SESSION_MCP_CONFIG: options.configPath }, detached: process.platform !== "win32" });
+        const max = options.maxFrameBytes ?? DEFAULT_MAX;
+        let buffer = "";
+        let closed = false;
+        let overflow = false;
+        child.stdout.on("data", (chunk) => { if (overflow)
+            return; buffer += chunk.toString("utf8"); if (Buffer.byteLength(buffer, "utf8") > max) {
+            overflow = true;
+            buffer = "";
+        } });
+        child.stderr.on("data", () => { });
+        child.on("error", () => { closed = true; });
+        child.on("close", () => { closed = true; });
+        const abort = () => { if (!closed)
+            terminateProcessGroup(child, "SIGTERM"); };
+        signal.addEventListener("abort", abort, { once: true });
+        const waitForClose = async (milliseconds) => {
+            if (closed)
+                return true;
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => resolve(closed), milliseconds);
+                child.once("close", () => { clearTimeout(timer); resolve(true); });
+            });
+        };
+        return {
+            write(frame) {
+                if (closed || overflow || Buffer.byteLength(frame, "utf8") > max)
+                    return Promise.reject(new Error("mcp_write_unavailable"));
+                return new Promise((resolve, reject) => child.stdin.write(frame, (error) => error ? reject(new Error("mcp_write_failed")) : resolve()));
+            },
+            async read() {
+                const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT);
+                while (!overflow && !closed && buffer.indexOf("\n") < 0 && Date.now() < deadline)
+                    await new Promise((resolve) => setTimeout(resolve, 5));
+                if (overflow)
+                    return null;
+                const newline = buffer.indexOf("\n");
+                if (newline >= 0) {
+                    const line = buffer.slice(0, newline + 1);
+                    buffer = buffer.slice(newline + 1);
+                    return line;
+                }
+                if (closed && buffer.length > 0) {
+                    const tail = buffer;
+                    buffer = "";
+                    return tail;
+                }
+                return null;
+            },
+            async kill() {
+                signal.removeEventListener("abort", abort);
+                if (!closed)
+                    child.stdin.end();
+                terminateProcessGroup(child, "SIGTERM");
+                await delay(100);
+                terminateProcessGroup(child, "SIGKILL");
+                const childClosed = await waitForClose(1_000);
+                const groupDeadline = Date.now() + 1_000;
+                while (processGroupState(child) === "alive" && Date.now() < groupDeadline)
+                    await delay(10);
+                if (!childClosed || processGroupState(child) !== "gone")
+                    throw new Error("mcp_process_cleanup_failed");
+            },
+        };
+    };
+}
+/**
+ * Acquires the Linux kernel fence and starts the transaction guardian. The
+ * guardian inherits the locked file description, so parent death cannot release
+ * the fence while a client mutation or descendant is still live.
+ */
+export async function acquireSetupGuardian(lockFd, timeoutMs, signal, validateFence) {
+    if (process.platform !== "linux")
+        throw new Error("platform_unsupported");
+    const flockPath = ["/usr/bin/flock", "/bin/flock"].find((candidate) => {
+        try {
+            const file = statSync(candidate);
+            return file.isFile() && file.uid === 0 && (file.mode & 0o022) === 0 && (file.mode & 0o111) !== 0;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!flockPath)
+        throw new Error("ownership_lock_unavailable");
+    const modulePath = fileURLToPath(import.meta.url);
+    const guardianPath = fileURLToPath(new URL(modulePath.endsWith(".ts") ? "./setup-command-guardian.ts" : "./setup-command-guardian.js", import.meta.url));
+    try {
+        if (!lstatSync(guardianPath).isFile())
+            throw new Error("guardian_invalid");
+    }
+    catch {
+        throw new Error("ownership_lock_unavailable");
+    }
+    const waitSeconds = String(Math.ceil(Math.max(1_000, Math.min(timeoutMs, 120_000)) / 1_000));
+    let locker;
+    try {
+        locker = spawn(flockPath, ["-E", "75", "-w", waitSeconds, "3"], {
+            stdio: ["ignore", "ignore", "ignore", lockFd],
+            detached: true,
+        });
+    }
+    catch {
+        throw new Error("ownership_lock_unavailable");
+    }
+    const stopAcquisition = () => { if (locker.pid !== undefined) {
+        try {
+            process.kill(-locker.pid, "SIGKILL");
+        }
+        catch { /* already gone */ }
+    } };
+    if (signal?.aborted)
+        stopAcquisition();
+    signal?.addEventListener("abort", stopAcquisition, { once: true });
+    try {
+        await new Promise((resolve, reject) => {
+            locker.once("error", () => reject(new Error("ownership_lock_unavailable")));
+            locker.once("close", (code) => code === 0 ? resolve() : reject(new Error(code === 75 ? "ownership_lock_busy" : signal?.aborted ? "operation_aborted" : "ownership_lock_unavailable")));
+        });
+    }
+    finally {
+        signal?.removeEventListener("abort", stopAcquisition);
+    }
+    if (signal?.aborted)
+        throw new Error("operation_aborted");
+    try {
+        await validateFence?.();
+    }
+    catch {
+        throw new Error("ownership_lock_unavailable");
+    }
+    let child;
+    try {
+        child = spawn(process.execPath, [guardianPath, String(process.pid)], { stdio: ["ignore", "ignore", "ignore", lockFd, "ipc"], detached: true });
+    }
+    catch {
+        throw new Error("ownership_lock_unavailable");
+    }
+    const stopGuardianStart = () => { if (child.pid !== undefined) {
+        try {
+            process.kill(-child.pid, "SIGKILL");
+        }
+        catch { /* already gone */ }
+    } };
+    signal?.addEventListener("abort", stopGuardianStart, { once: true });
+    try {
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => { stopGuardianStart(); settle(new Error("ownership_lock_unavailable")); }, GUARDIAN_START_TIMEOUT);
+            const settle = (error) => { if (settled)
+                return; settled = true; clearTimeout(timer); if (error)
+                reject(error);
+            else
+                resolve(); };
+            child.once("error", () => settle(new Error("ownership_lock_unavailable")));
+            child.once("close", () => settle(new Error(signal?.aborted ? "operation_aborted" : "ownership_lock_unavailable")));
+            child.on("message", (message) => { if (message && typeof message === "object" && message.type === "ready")
+                settle(); });
+        });
+    }
+    finally {
+        signal?.removeEventListener("abort", stopGuardianStart);
+    }
+    const compromised = new AbortController();
+    let nextId = 1;
+    let pending;
+    let released = false;
+    let unsafe = false;
+    const safeResult = (message) => {
+        if (!message || typeof message !== "object")
+            return undefined;
+        const value = message;
+        if (value.type !== "result" || !Number.isSafeInteger(value.id) || !Number.isSafeInteger(value.exitCode) || typeof value.stdout !== "string" || typeof value.stderr !== "string")
+            return undefined;
+        if (value.stdout.length > DEFAULT_MAX || value.stderr.length > DEFAULT_MAX)
+            return undefined;
+        return { exitCode: value.exitCode, stdout: value.stdout, stderr: value.stderr };
+    };
+    const failPending = () => {
+        if (!pending)
+            return;
+        pending.signal?.removeEventListener("abort", pending.abort);
+        const resolve = pending.resolve;
+        pending = undefined;
+        unsafe = true;
+        compromised.abort();
+        resolve({ exitCode: 126, stdout: "", stderr: "" });
+    };
+    child.on("message", (message) => {
+        const result = safeResult(message);
+        if (!result || !pending || message.id !== pending.id)
+            return;
+        pending.signal?.removeEventListener("abort", pending.abort);
+        const resolve = pending.resolve;
+        pending = undefined;
+        if (result.exitCode === 126) {
+            unsafe = true;
+            compromised.abort();
+        }
+        resolve(result);
+    });
+    child.once("error", failPending);
+    child.once("close", () => { if (!released) {
+        unsafe = true;
+        compromised.abort();
+        failPending();
+    } });
+    const runner = {
+        run(command, args, runSignal) {
+            if (released || unsafe || pending || runSignal?.aborted || !child.connected)
+                return Promise.resolve({ exitCode: 126, stdout: "", stderr: "" });
+            const id = nextId++;
+            return new Promise((resolve) => {
+                const abort = () => { if (child.connected)
+                    child.send({ type: "abort", id }, undefined, undefined, () => undefined); };
+                pending = { id, resolve, ...(runSignal ? { signal: runSignal } : {}), abort };
+                runSignal?.addEventListener("abort", abort, { once: true });
+                child.send({ type: "run", id, command, args: [...args], timeoutMs: DEFAULT_TIMEOUT, maxOutputBytes: DEFAULT_MAX }, undefined, undefined, (error) => { if (error)
+                    failPending(); });
+            });
+        },
+    };
+    return {
+        runner,
+        signal: compromised.signal,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            if (pending)
+                pending.abort();
+            if (!unsafe && child.connected) {
+                child.send({ type: "shutdown" }, undefined, undefined, () => undefined);
+                const closed = await new Promise((resolve) => {
+                    const timer = setTimeout(() => resolve(false), 5_000);
+                    child.once("close", () => { clearTimeout(timer); resolve(true); });
+                });
+                if (closed)
+                    return;
+            }
+            if (child.connected)
+                child.disconnect();
+            child.unref();
+        },
+    };
+}

package/dist/setup-result.d.ts

@@ -0,0 +1,22 @@
+/** Public, deliberately path-free setup result model. */
+export type SetupOperation = "dry-run" | "apply" | "verify" | "rollback" | "remove";
+export type SetupStatus = "ok" | "planned" | "unchanged" | "absent" | "divergent" | "unsupported" | "failed";
+export type RegistrationState = "absent" | "equivalent" | "divergent" | "unsupported";
+export interface SetupTarget {
+    readonly client: string;
+    readonly scope: string;
+    readonly alias: string;
+}
+export interface SetupFinding {
+    readonly target: SetupTarget;
+    readonly status: SetupStatus;
+    readonly code: string;
+}
+export interface SetupResult {
+    readonly schemaVersion: 1;
+    readonly operation: SetupOperation;
+    readonly status: SetupStatus;
+    readonly findings: readonly SetupFinding[];
+    readonly exitCode: 0 | 1 | 64 | 130 | 143;
+}
+export declare function result(operation: SetupOperation, findings: readonly SetupFinding[], status?: SetupStatus, exitCode?: 0 | 1 | 64 | 130 | 143): SetupResult;

package/dist/setup-result.js

@@ -0,0 +1,8 @@
+export function result(operation, findings, status = findings.some((finding) => finding.status === "failed" || finding.status === "divergent" || finding.status === "unsupported") ? "failed" : "ok", exitCode = status === "failed" ? 1 : 0) {
+    const normalized = findings.map((finding) => Object.freeze({
+        target: Object.freeze({ ...finding.target }),
+        status: finding.status,
+        code: /^[a-z][a-z0-9_]{0,63}$/.test(finding.code) ? finding.code : "operation_failed",
+    }));
+    return Object.freeze({ schemaVersion: 1, operation, status, findings: Object.freeze(normalized), exitCode });
+}

package/dist/setup.d.ts

@@ -0,0 +1,55 @@
+import type { CommandExecution, CommandRunner, RegistrationIntent, RegistrationState } from "./client-adapters/types.js";
+import { type OwnershipStore } from "./setup-ownership.js";
+import { type SetupOperation, type SetupResult, type SetupTarget } from "./setup-result.js";
+export interface SetupClientAdapter {
+    readonly name: string;
+    readonly supportedScopes: readonly string[];
+    inspect(target: SetupTarget, fingerprint: string): Promise<{
+        state: RegistrationState;
+        fingerprint?: string;
+    }>;
+    apply(target: SetupTarget, execution?: CommandExecution): Promise<void>;
+    remove(target: SetupTarget, execution?: CommandExecution): Promise<void>;
+    verify(target: SetupTarget): Promise<{
+        ok: boolean;
+        code: string;
+    }>;
+}
+export interface SetupDoctor {
+    check(): Promise<{
+        ok: boolean;
+        code: string;
+    }>;
+}
+export interface SetupDependencies {
+    readonly adapters?: readonly SetupClientAdapter[];
+    readonly doctor?: SetupDoctor;
+    readonly ownership?: OwnershipStore;
+    readonly intendedFingerprint: string;
+}
+export interface SetupRequest {
+    readonly operation?: SetupOperation;
+    readonly targets: readonly SetupTarget[];
+}
+export declare const isSupportedTarget: (target: SetupTarget) => boolean;
+export declare class SetupOrchestrator {
+    private readonly dependencies;
+    private readonly ownership;
+    constructor(dependencies: SetupDependencies);
+    run(request: SetupRequest): Promise<SetupResult>;
+    private adapter;
+    private assertOwnershipHealthy;
+    private signal;
+    private execution;
+    private plan;
+    private apply;
+    private verify;
+    private restore;
+    private safe;
+}
+export declare function registrationFingerprint(intent: RegistrationIntent, releaseBinding?: string): string;
+/** Bind setup ownership to the exact package manifests and built runtime tree. */
+export declare function immutableReleaseBinding(packageRoot: string): Promise<string>;
+export declare function createProductionSetup(runner: CommandRunner, packageRoot: string, configPath: string, ownershipPath?: string, signal?: AbortSignal): Promise<SetupOrchestrator>;
+export { result } from "./setup-result.js";
+export type { SetupFinding, SetupOperation, SetupResult, SetupStatus, SetupTarget } from "./setup-result.js";