@evandu/super-pi 0.0.0-stage → 0.1.1

package/dist/server/http-server.js

@@ -0,0 +1,313 @@
+import { createReadStream, existsSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { describe as describeFilesError, fileMeta, listDirectory, MAX_FILE_BYTES, readWorkspaceFile, resolveInsideRoot, searchByName, toRelative, writeWorkspaceFile, } from "./files.js";
+import { findUploadFile, MAX_UPLOAD_BODY_BYTES, saveUpload } from "./upload.js";
+const MIME_TYPES = {
+    ".css": "text/css; charset=utf-8",
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".json": "application/json; charset=utf-8",
+    ".ico": "image/x-icon",
+};
+/**
+ * Checks if the remote address is a local loopback interface.
+ */
+export function isLoopbackAddress(remoteAddress) {
+    if (!remoteAddress)
+        return false;
+    return ["127.0.0.1", "::1", "::ffff:127.0.0.1"].includes(remoteAddress);
+}
+/**
+ * Checks whether an incoming HTTP request satisfies access token authorization.
+ */
+export function isAuthorized(request, accessToken) {
+    return !accessToken || request.headers.authorization === `Bearer ${accessToken}`;
+}
+/**
+ * Creates the HTTP server providing static client assets and all `/api/*` endpoints.
+ */
+export function createHttpServer(options) {
+    const { context, onShutdown } = options;
+    const { store, paths, accessToken, broadcaster, runService, catalogService } = context;
+    const { uploadsDir, clientDir, rootDir } = paths;
+    return createServer(async (request, response) => {
+        if (!isAuthorized(request, accessToken)) {
+            response.writeHead(401, { "www-authenticate": "Bearer" }).end("Authentication required");
+            return;
+        }
+        const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+        const remote = request.socket.remoteAddress ?? "";
+        if (url.pathname === "/api/shutdown") {
+            if (request.method !== "POST" || !isLoopbackAddress(remote)) {
+                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Shutdown requires a loopback POST");
+                return;
+            }
+            response.writeHead(202, { "content-type": "application/json; charset=utf-8" })
+                .end(JSON.stringify({ status: "shutting_down", message: "Server is stopping" }));
+            setTimeout(() => onShutdown("api-shutdown"), 50);
+            return;
+        }
+        if (url.pathname === "/api/health") {
+            response.writeHead(200, { "content-type": "application/json; charset=utf-8" })
+                .end(JSON.stringify({ status: "ok", service: "super-pi" }));
+            return;
+        }
+        if (url.pathname === "/api/subagent/dispatch") {
+            if (request.method !== "POST" || !isLoopbackAddress(remote)) {
+                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Sub-agent dispatch requires a loopback POST");
+                return;
+            }
+            let raw = "";
+            for await (const chunk of request)
+                raw += chunk;
+            const json = (status, body) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+            };
+            try {
+                const body = JSON.parse(raw);
+                const result = await runService.dispatchTask(body);
+                json(result.status, result.body);
+            }
+            catch (error) {
+                json(400, { error: error instanceof Error ? error.message : "task dispatch failed" });
+            }
+            return;
+        }
+        if (url.pathname === "/api/todos") {
+            if (request.method !== "POST" || !isLoopbackAddress(remote)) {
+                response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Todo writes require a loopback POST");
+                return;
+            }
+            let raw = "";
+            for await (const chunk of request)
+                raw += chunk;
+            const json = (status, body) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+            };
+            try {
+                const body = JSON.parse(raw);
+                const conversationId = body.conversationId?.trim();
+                if (!conversationId)
+                    throw new Error("todowrite requires conversationId");
+                const { todos, dropped } = await store.setTodos(body.todos);
+                broadcaster.broadcastState();
+                json(200, { todos, dropped, conversationId });
+            }
+            catch (error) {
+                json(400, { error: error instanceof Error ? error.message : "todo write failed" });
+            }
+            return;
+        }
+        if (url.pathname === "/api/files" || url.pathname === "/api/file") {
+            const json = (status, body) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+            };
+            try {
+                const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
+                if (!workspaceId || !workspace) {
+                    json(404, { error: `Workspace ${workspaceId ?? "(missing)"} not found`, code: "no_workspace" });
+                    return;
+                }
+                const root = workspace.path;
+                if (url.pathname === "/api/files") {
+                    if (request.method !== "GET") {
+                        json(405, { error: "Directory listing requires GET", code: "method" });
+                        return;
+                    }
+                    const query = url.searchParams.get("q");
+                    if (query !== null && query.trim() !== "") {
+                        const result = await searchByName(root, query);
+                        json(200, { mode: "search", query: query.trim(), ...result, maxResults: 500, maxDepth: 12 });
+                        return;
+                    }
+                    const listing = await listDirectory(root, url.searchParams.get("path"));
+                    json(200, { mode: "list", ...listing, maxEntries: 2000 });
+                    return;
+                }
+                if (request.method === "GET") {
+                    const rel = url.searchParams.get("path") ?? "";
+                    if (url.searchParams.get("meta") === "1") {
+                        const resolved = await resolveInsideRoot(root, rel);
+                        json(200, { path: toRelative(root, resolved), ...(await fileMeta(resolved)) });
+                        return;
+                    }
+                    const file = await readWorkspaceFile(root, rel);
+                    json(200, { path: file.path, content: file.content, eol: file.eol, meta: file.meta, maxBytes: MAX_FILE_BYTES });
+                    return;
+                }
+                if (request.method === "PUT") {
+                    const remoteAddr = request.socket.remoteAddress ?? "";
+                    if (!isLoopbackAddress(remoteAddr)) {
+                        json(403, { error: "File writes require a loopback connection", code: "not_loopback" });
+                        return;
+                    }
+                    let raw = "";
+                    for await (const chunk of request)
+                        raw += chunk;
+                    const declared = Number(request.headers["content-length"] ?? "0");
+                    if (Number.isFinite(declared) && declared > MAX_FILE_BYTES * 2) {
+                        json(413, { error: "请求体过大", code: "too_large" });
+                        return;
+                    }
+                    const parsed = JSON.parse(raw);
+                    if (typeof parsed.path !== "string" || typeof parsed.content !== "string") {
+                        json(400, { error: "写入需要 path 与 content 两个字符串字段", code: "bad_request" });
+                        return;
+                    }
+                    const outcome = await writeWorkspaceFile(root, parsed.path, parsed.content, parsed.baseEtag);
+                    json(200, outcome);
+                    return;
+                }
+                json(405, { error: `${request.method} is not supported on /api/file`, code: "method" });
+            }
+            catch (error) {
+                const described = describeFilesError(error);
+                json(described.status, described.body);
+            }
+            return;
+        }
+        if (url.pathname === "/api/fs/dirs") {
+            const fail = (status, message) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: message }));
+            };
+            try {
+                const target = resolve(url.searchParams.get("path")?.trim() || rootDir);
+                const info = await stat(target).catch((error) => {
+                    if (error?.code === "ENOENT" || error?.code === "ENOTDIR")
+                        return undefined;
+                    throw error;
+                });
+                if (!info) {
+                    fail(404, `Directory does not exist: ${target}`);
+                    return;
+                }
+                if (!info.isDirectory()) {
+                    fail(400, `Not a directory: ${target}`);
+                    return;
+                }
+                const dirents = await readdir(target, { withFileTypes: true });
+                const entries = dirents
+                    .filter((item) => item.isDirectory())
+                    .map((item) => ({ name: item.name, path: join(target, item.name) }))
+                    .sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" }));
+                const truncated = entries.length > 2000;
+                const parent = dirname(target);
+                response.writeHead(200, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({
+                    path: target,
+                    parent: parent === target ? null : parent,
+                    suggestedName: basename(target) || target,
+                    entries: truncated ? entries.slice(0, 2000) : entries,
+                    truncated,
+                }));
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === "EACCES" || code === "EPERM")
+                    fail(403, `Permission denied: ${url.searchParams.get("path") ?? rootDir}`);
+                else
+                    fail(500, `Failed to list directories: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+            return;
+        }
+        if (url.pathname === "/api/upload") {
+            if (request.method !== "POST" || !isLoopbackAddress(remote)) {
+                response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "Upload requires a loopback POST" }));
+                return;
+            }
+            const json = (status, body) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+            };
+            try {
+                let totalBytes = 0;
+                const chunks = [];
+                for await (const chunk of request) {
+                    totalBytes += chunk.length;
+                    if (totalBytes > MAX_UPLOAD_BODY_BYTES) {
+                        json(413, { error: "Upload payload exceeds size limit" });
+                        request.destroy();
+                        return;
+                    }
+                    chunks.push(chunk);
+                }
+                const raw = Buffer.concat(chunks).toString("utf8");
+                const body = JSON.parse(raw);
+                const conversationId = body.conversationId?.trim();
+                if (!conversationId) {
+                    json(400, { error: "conversationId is required" });
+                    return;
+                }
+                const conversation = store.snapshot().conversations.find((c) => c.id === conversationId);
+                if (!conversation) {
+                    json(404, { error: `Conversation not found: ${conversationId}` });
+                    return;
+                }
+                if (!body.mimeType || typeof body.mimeType !== "string") {
+                    json(400, { error: "mimeType is required" });
+                    return;
+                }
+                if (!body.data || typeof body.data !== "string") {
+                    json(400, { error: "data (base64) is required" });
+                    return;
+                }
+                const catalog = await catalogService.getCatalog(conversation.model);
+                const currentModel = catalog.models.find((m) => m.provider === conversation.model?.provider && m.modelId === conversation.model?.modelId)
+                    ?? catalog.models.find((m) => m.provider === catalog.defaultModel?.provider && m.modelId === catalog.defaultModel?.modelId);
+                if (currentModel && !currentModel.imageInput) {
+                    json(400, { error: `当前模型「${currentModel.label || currentModel.modelId}」不支持图片输入` });
+                    return;
+                }
+                const record = await saveUpload(uploadsDir, conversationId, body.name, body.mimeType, body.data);
+                json(200, record);
+            }
+            catch (error) {
+                json(400, { error: error instanceof Error ? error.message : "Upload failed" });
+            }
+            return;
+        }
+        if (url.pathname.startsWith("/api/upload/")) {
+            if (request.method !== "GET" || !isLoopbackAddress(remote)) {
+                response.writeHead(403, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "Upload access requires a loopback GET" }));
+                return;
+            }
+            const pathParts = url.pathname.slice("/api/upload/".length).split("/").filter(Boolean);
+            if (!pathParts.length || pathParts.length > 2) {
+                response.writeHead(400, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "Invalid upload path" }));
+                return;
+            }
+            const convId = pathParts.length === 2 ? pathParts[0] : undefined;
+            const fileOrId = pathParts.length === 2 ? pathParts[1] : pathParts[0];
+            const found = await findUploadFile(uploadsDir, convId, fileOrId);
+            if (!found) {
+                response.writeHead(404, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "Image not found" }));
+                return;
+            }
+            response.writeHead(200, {
+                "content-type": found.mimeType,
+                "x-content-type-options": "nosniff",
+                "cache-control": "public, max-age=31536000, immutable",
+                "content-length": found.size,
+            });
+            createReadStream(found.filePath).pipe(response);
+            return;
+        }
+        // Static client asset handling
+        const requested = url.pathname === "/" ? "index.html" : url.pathname.slice(1);
+        const requestedPath = resolve(clientDir, requested);
+        const safe = !relative(clientDir, requestedPath).startsWith("..") && !relative(clientDir, requestedPath).includes(":");
+        if (!safe) {
+            response.writeHead(403).end();
+            return;
+        }
+        const candidate = existsSync(requestedPath) ? requestedPath : join(clientDir, "index.html");
+        if (!existsSync(candidate)) {
+            response.writeHead(503, { "content-type": "text/plain; charset=utf-8" }).end("Super Pi client has not been built. Run npm run build.");
+            return;
+        }
+        response.writeHead(200, { "content-type": MIME_TYPES[extname(candidate)] ?? "application/octet-stream" });
+        createReadStream(candidate).pipe(response);
+    });
+}

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/index.js

@@ -0,0 +1,103 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { defaultStorePath, Store } from "./store.js";
+import { PiRpcRuntime, WelcomeRuntime } from "./runtime.js";
+import { SubagentSupervisor } from "./subagents.js";
+import { SubagentRunRecorder } from "./subagent-runs.js";
+import { ExtensionUiService } from "./application/extension-ui-service.js";
+import { CatalogService } from "./application/catalog-service.js";
+import { RunService } from "./application/run-service.js";
+import { ConversationService } from "./application/conversation-service.js";
+import { WorkspaceService } from "./application/workspace-service.js";
+import { CommandHandler } from "./command-handler.js";
+import { createHttpServer } from "./http-server.js";
+import { WsBroadcaster, WsServer } from "./ws-server.js";
+// ------------------------------------------------------------- Environment & paths
+const rootDir = resolve(import.meta.dirname, "../..");
+const port = Number.parseInt(process.env.SUPER_PI_PORT ?? "3080", 10);
+const host = process.env.SUPER_PI_HOST ?? "127.0.0.1";
+const defaultDataDir = !rootDir.includes("node_modules") && existsSync(join(rootDir, ".super-pi"))
+    ? join(rootDir, ".super-pi")
+    : join(homedir(), ".super-pi");
+const dataDir = resolve(process.env.SUPER_PI_DATA_DIR ?? defaultDataDir);
+const agentsDir = resolve(process.env.SUPER_PI_AGENTS_DIR ?? join(rootDir, "agents"));
+const agentPromptDir = join(dataDir, "agent-prompts");
+const clientDir = join(rootDir, "dist", "client");
+const accessToken = process.env.SUPER_PI_ACCESS_TOKEN;
+const uploadsDir = join(dataDir, "uploads");
+await mkdir(uploadsDir, { recursive: true }).catch(() => { });
+const taskEndpoint = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/api/subagent/dispatch`;
+const todoEndpoint = `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${port}/api/todos`;
+const paths = {
+    dataDir,
+    rootDir,
+    agentsDir,
+    agentPromptDir,
+    uploadsDir,
+    clientDir,
+};
+// ------------------------------------------------------------- Core singletons
+const store = await Store.open(defaultStorePath(dataDir));
+const runtime = process.env.SUPER_PI_RUNTIME === "welcome"
+    ? new WelcomeRuntime()
+    : new PiRpcRuntime(join(dataDir, "pi-sessions"), undefined, { dir: agentsDir, promptDir: agentPromptDir }, { endpoint: taskEndpoint, todoEndpoint, uploadsDir });
+const broadcaster = new WsBroadcaster(() => store.snapshot());
+const extensionUiService = new ExtensionUiService(broadcaster);
+const supervisor = new SubagentSupervisor(join(dataDir, "pi-sessions"), undefined, {
+    dir: agentsDir,
+    promptDir: agentPromptDir,
+});
+const subagents = new SubagentRunRecorder(supervisor, {
+    store,
+    broadcast: (event) => {
+        broadcaster.broadcast(event);
+        if (event.type === "subagent.event")
+            broadcaster.broadcastState();
+    },
+    host: (conversationId, runId) => extensionUiService.createHost(conversationId, runId),
+});
+// ------------------------------------------------------------- Application services
+const catalogService = new CatalogService(runtime, broadcaster, agentsDir);
+const runService = new RunService(store, runtime, subagents, broadcaster, extensionUiService);
+const conversationService = new ConversationService(store, runtime, subagents, broadcaster, catalogService, runService, extensionUiService, agentsDir);
+const workspaceService = new WorkspaceService(store, runtime, broadcaster, catalogService, runService, extensionUiService, uploadsDir, agentsDir);
+const serverContext = {
+    paths,
+    store,
+    runtime,
+    subagents,
+    broadcaster,
+    accessToken,
+    workspaceService,
+    conversationService,
+    runService,
+    extensionUiService,
+    catalogService,
+};
+const commandHandler = new CommandHandler(workspaceService, conversationService, runService, extensionUiService, catalogService);
+// ------------------------------------------------------------- Lifecycle & shutdown
+let shuttingDown = false;
+function shutdown(reason) {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    console.log(`Super Pi is shutting down (${reason}).`);
+    runService.abortAll();
+    for (const c of store.snapshot().conversations) {
+        extensionUiService.cancelPendingUi(c.id, "aborted");
+    }
+    wsServer.close();
+    httpServer.close(() => process.exit(0));
+    httpServer.closeAllConnections();
+    setTimeout(() => process.exit(0), 3000).unref();
+}
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+// ------------------------------------------------------------- Transports & startup
+const httpServer = createHttpServer({ context: serverContext, onShutdown: shutdown });
+const wsServer = new WsServer({ httpServer, broadcaster, commandHandler, catalogService, accessToken });
+httpServer.listen(port, host, () => {
+    console.log(`Super Pi is running at http://${host}:${port}`);
+});

package/dist/server/pi-command.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Where Pi is, or a plain statement that it is not here.
+ *
+ * WHY THIS IS NOT `process.env.SUPER_PI_PI_COMMAND ?? "pi.cmd"`. npm installs global CLIs into a
+ * directory that is NOT on many shells' PATH - on Windows `%APPDATA%\npm` is missing from a cron or
+ * service shell by default - so a bare `pi.cmd` spawn fails there while succeeding in an interactive
+ * shell. Same commit, same machine, opposite `npm run check` verdicts, and the failing line was
+ * cmd.exe's own message in the console's code page (`'pi.cmd' 不是内部或外部命令`), which reads as an
+ * encoding bug instead of a PATH one. Both the production spawn and the real-Pi probe resolve through
+ * this one function so the test cannot verify a resolution production does not use.
+ *
+ * "Not installed" and "installed but disagreeing" are DIFFERENT facts with different verdicts: the
+ * first is the environment, the second is the product. `found: false` is the first, and callers report
+ * it as a skip with a reason rather than as a product failure.
+ */
+export type PiCommandResolution = {
+    found: true;
+    command: string;
+    via: string;
+} | {
+    found: false;
+    reason: string;
+    searched: string[];
+};
+/** Overridable so the resolution can be exercised for both platforms and both outcomes without a Pi install. */
+export interface PiCommandOptions {
+    /** An explicit command (the runtime constructor's second argument). Wins over the environment. */
+    command?: string | undefined;
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    exists?: (path: string) => boolean;
+}
+/**
+ * Resolves the command that starts Pi: the explicit override, then PATH, then npm's global bin
+ * directories, and only then a report of every place it looked.
+ *
+ * An explicit override that does not exist is REPORTED rather than handed to the spawn, because a
+ * silent fallback would make a typo in `SUPER_PI_PI_COMMAND` look like a working Pi somewhere else.
+ */
+export declare function resolvePiCommand(options?: PiCommandOptions): PiCommandResolution;
+/**
+ * Decodes a child process's output, falling back to the console code page when it is not UTF-8.
+ *
+ * A Windows `.cmd` shim runs under cmd.exe, which writes its own diagnostics in the console's code
+ * page - GBK on a Chinese Windows - so `chunk.toString()` renders `'pi.cmd' 不是内部或外部命令` as
+ * `'pi.cmd' ??????`. Reading those bytes as UTF-8 fatal first and retrying as GBK is what keeps the
+ * message readable, and therefore what keeps the next reader from mistaking a PATH problem for an
+ * encoding one.
+ */
+export declare function decodeProcessOutput(chunks: Iterable<Buffer>, fallbackCodePage?: string): string;
+/**
+ * True when the text says the command itself was not found, which is a PATH or install problem rather
+ * than a rejection by Pi - the two are indistinguishable once the output is garbled, so the diagnosis
+ * is made on the decoded text rather than guessed from an exit code.
+ */
+export declare function looksLikeCommandNotFound(text: string): boolean;
+/**
+ * Quotes a resolved command for `shell: true` spawns on Windows.
+ *
+ * npm's global bin directory can sit under a path with spaces (`C:\Program Files\nodejs`), and node
+ * joins a shell command out of argv WITHOUT quoting it, so an unquoted resolved path fails to launch
+ * on exactly the machine where PATH lookup did not already find Pi. A command with no spaces - the
+ * common case, and every fake launcher the tests use - is returned untouched.
+ */
+export declare function shellQuote(command: string, platform?: NodeJS.Platform): string;

package/dist/server/pi-command.js

@@ -0,0 +1,183 @@
+import { accessSync, constants, existsSync } from "node:fs";
+import { posix, win32 } from "node:path";
+/** npm's launcher names, most specific first: `.cmd` is what `shell: true` can actually start on Windows. */
+const launcherNames = (platform) => platform === "win32" ? ["pi.cmd", "pi.exe", "pi.bat", "pi"] : ["pi", "pi.exe"];
+/**
+ * Turns one PATH entry into a path this platform can stat.
+ *
+ * Git Bash and MSYS hand a native program a POSIX-looking PATH (`/c/Users/...`), and Windows cannot
+ * stat that: `existsSync("/c/Users/...")` resolves against the current drive root and says no. So the
+ * drive-letter form is rewritten, which is what makes PATH scanning work in exactly the shells this
+ * bug appeared in.
+ */
+function nativeEntry(entry, platform) {
+    const trimmed = entry.trim().replace(/^"(.*)"$/, "$1");
+    if (!trimmed)
+        return undefined;
+    if (platform !== "win32")
+        return trimmed;
+    const drive = /^\/([a-zA-Z])(\/.*)?$/.exec(trimmed);
+    return drive ? `${drive[1].toUpperCase()}:${(drive[2] ?? "/").replace(/\//g, "\\")}` : trimmed;
+}
+/**
+ * Splits PATH the way the platform that handed it to us actually wrote it.
+ *
+ * Windows uses `;`, but a Git Bash / MSYS PATH arrives colon-separated with drive-letter prefixes, and a
+ * `C:` in an ordinary Windows entry means the drive, never a separator. So `;` always wins when present;
+ * otherwise `:` is treated as a separator only if the string has no drive-letter prefix at all.
+ */
+const splitPath = (value, platform) => {
+    if (platform !== "win32")
+        return value.split(":");
+    if (value.includes(";"))
+        return value.split(";");
+    return /(^|[;,])[a-zA-Z]:[\\/]/.test(value) ? [value] : value.split(":");
+};
+const pathDirectories = (env, platform) => splitPath(env.PATH ?? env.Path ?? "", platform).map((entry) => nativeEntry(entry, platform)).filter((entry) => Boolean(entry));
+/** Joins with the target platform's separator, so a POSIX expectation stays comparable on Windows. */
+const joinFor = (platform) => (platform === "win32" ? win32.join : posix.join);
+/**
+ * The directories npm installs global CLIs into, beyond PATH.
+ *
+ * `npm_config_prefix` is npm's own answer when it is set; the rest are the defaults per platform. The
+ * home directory is read from the ENVIRONMENT only - `os.homedir()` is never consulted - so a
+ * deliberately isolated environment (empty PATH, no HOME) really is isolated instead of quietly
+ * finding the developer's own install through the OS.
+ */
+function globalBinDirectories(env, platform) {
+    const home = env.HOME?.trim() || env.USERPROFILE?.trim();
+    const at = joinFor(platform);
+    const directories = [];
+    const prefix = env.npm_config_prefix?.trim();
+    if (prefix)
+        directories.push(platform === "win32" ? nativeEntry(prefix, platform) ?? prefix : at(prefix, "bin"));
+    if (platform === "win32") {
+        if (env.APPDATA?.trim())
+            directories.push(at(env.APPDATA.trim(), "npm"));
+        if (env.LOCALAPPDATA?.trim())
+            directories.push(at(env.LOCALAPPDATA.trim(), "npm"));
+        if (env.ProgramFiles?.trim())
+            directories.push(at(env.ProgramFiles.trim(), "npm"));
+    }
+    else {
+        if (home)
+            directories.push(at(home, ".local", "bin"), at(home, ".npm-global", "bin"), at(home, "bin"));
+        directories.push("/usr/local/bin", "/opt/homebrew/bin");
+    }
+    return [...new Set(directories.filter(Boolean))];
+}
+/** On POSIX a file that is not executable is not runnable; on Windows that bit does not exist. */
+const defaultExists = (platform) => (path) => {
+    if (!existsSync(path))
+        return false;
+    if (platform === "win32")
+        return true;
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const firstHit = (names, directories, exists, platform) => {
+    const at = joinFor(platform);
+    for (const dir of directories)
+        for (const name of names) {
+            const candidate = at(dir, name);
+            if (exists(candidate))
+                return { command: candidate, dir };
+        }
+    return undefined;
+};
+/**
+ * Resolves the command that starts Pi: the explicit override, then PATH, then npm's global bin
+ * directories, and only then a report of every place it looked.
+ *
+ * An explicit override that does not exist is REPORTED rather than handed to the spawn, because a
+ * silent fallback would make a typo in `SUPER_PI_PI_COMMAND` look like a working Pi somewhere else.
+ */
+export function resolvePiCommand(options = {}) {
+    const { command, env = process.env, platform = process.platform } = options;
+    const exists = options.exists ?? defaultExists(platform);
+    const names = launcherNames(platform);
+    const explicit = (command ?? env.SUPER_PI_PI_COMMAND ?? "").trim();
+    const onPath = pathDirectories(env, platform);
+    const globalDirs = globalBinDirectories(env, platform);
+    if (explicit) {
+        const label = command ? "the command given to the runtime" : "SUPER_PI_PI_COMMAND";
+        if (/[\\/]/.test(explicit)) {
+            const full = nativeEntry(explicit, platform) ?? explicit;
+            if (exists(full))
+                return { found: true, command: full, via: label };
+            return {
+                found: false,
+                reason: `${label} points at ${full}, and no such file exists. Fix ${command ? "that argument" : "SUPER_PI_PI_COMMAND"} or unset it to fall back to PATH and npm's global bin directory. This is an environment problem, not a defect in the agent mechanism.`,
+                searched: [full],
+            };
+        }
+        const hit = firstHit([explicit], [...onPath, ...globalDirs], exists, platform);
+        if (hit)
+            return { found: true, command: hit.command, via: `${label} (${hit.dir})` };
+        return {
+            found: false,
+            reason: `${label} names ${explicit}, which is on no PATH entry and in none of npm's global bin directories. This is an environment problem, not a defect in the agent mechanism.`,
+            searched: [...onPath, ...globalDirs],
+        };
+    }
+    const namesFound = firstHit(names, onPath, exists, platform);
+    if (namesFound)
+        return { found: true, command: namesFound.command, via: `PATH (${namesFound.dir})` };
+    const globalFound = firstHit(names, globalDirs, exists, platform);
+    if (globalFound)
+        return { found: true, command: globalFound.command, via: `npm's global bin directory (${globalFound.dir})` };
+    const searched = [...new Set([...onPath, ...globalDirs])];
+    return {
+        found: false,
+        reason: `Pi was not found: no ${names.map((name) => `"${name}"`).join(" or ")} in ${searched.length} directory(ies) on PATH or in npm's global bin location (${searched.join(", ") || "none known"}). Install it with "npm i -g pi" or set SUPER_PI_PI_COMMAND to its full path. This is an environment fact, NOT evidence that the agent mechanism is broken - only a Pi that IS present and disagrees can say that.`,
+        searched,
+    };
+}
+/**
+ * Decodes a child process's output, falling back to the console code page when it is not UTF-8.
+ *
+ * A Windows `.cmd` shim runs under cmd.exe, which writes its own diagnostics in the console's code
+ * page - GBK on a Chinese Windows - so `chunk.toString()` renders `'pi.cmd' 不是内部或外部命令` as
+ * `'pi.cmd' ??????`. Reading those bytes as UTF-8 fatal first and retrying as GBK is what keeps the
+ * message readable, and therefore what keeps the next reader from mistaking a PATH problem for an
+ * encoding one.
+ */
+export function decodeProcessOutput(chunks, fallbackCodePage = "gbk") {
+    const buffer = Buffer.concat([...chunks]);
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+    }
+    catch { /* not UTF-8 - fall through to the code page below */ }
+    try {
+        return new TextDecoder(fallbackCodePage).decode(buffer);
+    }
+    catch {
+        return buffer.toString("latin1");
+    }
+}
+/**
+ * True when the text says the command itself was not found, which is a PATH or install problem rather
+ * than a rejection by Pi - the two are indistinguishable once the output is garbled, so the diagnosis
+ * is made on the decoded text rather than guessed from an exit code.
+ */
+export function looksLikeCommandNotFound(text) {
+    return /不是内部或外部命令|不是可识别的内部或外部命令|not recognized as an internal or external command|command not found|No such file or directory/i.test(text);
+}
+/**
+ * Quotes a resolved command for `shell: true` spawns on Windows.
+ *
+ * npm's global bin directory can sit under a path with spaces (`C:\Program Files\nodejs`), and node
+ * joins a shell command out of argv WITHOUT quoting it, so an unquoted resolved path fails to launch
+ * on exactly the machine where PATH lookup did not already find Pi. A command with no spaces - the
+ * common case, and every fake launcher the tests use - is returned untouched.
+ */
+export function shellQuote(command, platform = process.platform) {
+    if (platform !== "win32" || !/\s/.test(command) || command.includes("\""))
+        return command;
+    return `"${command}"`;
+}