@evandu/super-pi 0.0.0-stage → 0.1.1

package/dist/server/types.js

@@ -0,0 +1,11 @@
+/**
+ * The nine methods Pi's `RpcExtensionUIRequest` union defines (rpc-types.ts:252-287), split by whether
+ * Pi waits for a reply. `blocking` is the only field the transport needs in order to decide, and it
+ * is derived here rather than at each call site so the two halves can never drift apart.
+ */
+export const EXTENSION_UI_METHODS = [
+    "select", "confirm", "input", "editor",
+    "notify", "setStatus", "setWidget", "setTitle", "set_editor_text",
+];
+/** Pi registers exactly these four in `pendingExtensionRequests`; the other five are fire-and-forget. */
+export const BLOCKING_UI_METHODS = new Set(["select", "confirm", "input", "editor"]);

package/dist/server/upload.d.ts

@@ -0,0 +1,37 @@
+import type { MessageImage } from "./types.js";
+/** 5MB maximum decoded image payload, matching the source-file size ceiling in files.ts. */
+export declare const MAX_UPLOAD_BYTES: number;
+/** 10MB maximum HTTP request body to safely handle base64 overhead before JSON parsing. */
+export declare const MAX_UPLOAD_BODY_BYTES: number;
+/**
+ * Strict image MIME type allowlist.
+ * SVGs are explicitly excluded because rendered SVGs can execute arbitrary JavaScript (XSS).
+ */
+export declare const ALLOWED_IMAGE_MIMES: Set<string>;
+export declare function extForMime(mime: string): string;
+export declare function mimeForExt(ext: string): string;
+/**
+ * Sniffs magic bytes to verify that buffer contents match the declared image MIME type.
+ * This prevents masquerading non-image files or dangerous content under image extensions.
+ */
+export declare function validateImageMagic(buffer: Buffer, mimeType: string): boolean;
+export type UploadRecord = {
+    id: string;
+    conversationId: string;
+    name: string;
+    mimeType: string;
+    bytes: number;
+    url: string;
+};
+export declare function saveUpload(uploadsDir: string, conversationId: string, clientName: string | undefined, mimeType: string, base64Data: string): Promise<UploadRecord>;
+export declare function findUploadFile(uploadsDir: string, conversationId: string | undefined, filenameOrId: string): Promise<{
+    filePath: string;
+    mimeType: string;
+    size: number;
+} | null>;
+export declare function deleteConversationUploads(uploadsDir: string, conversationId: string): Promise<void>;
+export declare function loadConversationImages(uploadsDir: string, conversationId: string, images: MessageImage[]): Promise<Array<{
+    type: "image";
+    data: string;
+    mimeType: string;
+}>>;

package/dist/server/upload.js

@@ -0,0 +1,169 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { extname, join } from "node:path";
+/** 5MB maximum decoded image payload, matching the source-file size ceiling in files.ts. */
+export const MAX_UPLOAD_BYTES = 5 * 1024 * 1024;
+/** 10MB maximum HTTP request body to safely handle base64 overhead before JSON parsing. */
+export const MAX_UPLOAD_BODY_BYTES = 10 * 1024 * 1024;
+/**
+ * Strict image MIME type allowlist.
+ * SVGs are explicitly excluded because rendered SVGs can execute arbitrary JavaScript (XSS).
+ */
+export const ALLOWED_IMAGE_MIMES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+]);
+export function extForMime(mime) {
+    switch (mime) {
+        case "image/png": return ".png";
+        case "image/jpeg": return ".jpg";
+        case "image/gif": return ".gif";
+        case "image/webp": return ".webp";
+        default: return "";
+    }
+}
+export function mimeForExt(ext) {
+    switch (ext.toLowerCase()) {
+        case ".png": return "image/png";
+        case ".jpg":
+        case ".jpeg": return "image/jpeg";
+        case ".gif": return "image/gif";
+        case ".webp": return "image/webp";
+        default: return "application/octet-stream";
+    }
+}
+/**
+ * Sniffs magic bytes to verify that buffer contents match the declared image MIME type.
+ * This prevents masquerading non-image files or dangerous content under image extensions.
+ */
+export function validateImageMagic(buffer, mimeType) {
+    if (buffer.length < 8)
+        return false;
+    switch (mimeType) {
+        case "image/png":
+            return buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47 &&
+                buffer[4] === 0x0d && buffer[5] === 0x0a && buffer[6] === 0x1a && buffer[7] === 0x0a;
+        case "image/jpeg":
+            return buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+        case "image/gif":
+            return buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38 &&
+                (buffer[4] === 0x37 || buffer[4] === 0x39) && buffer[5] === 0x61;
+        case "image/webp":
+            return buffer.length >= 12 &&
+                buffer.toString("ascii", 0, 4) === "RIFF" &&
+                buffer.toString("ascii", 8, 12) === "WEBP";
+        default:
+            return false;
+    }
+}
+export async function saveUpload(uploadsDir, conversationId, clientName, mimeType, base64Data) {
+    if (!ALLOWED_IMAGE_MIMES.has(mimeType)) {
+        throw new Error(`不支持的图片格式: ${mimeType}。仅支持 PNG、JPEG、GIF 和 WebP`);
+    }
+    const buffer = Buffer.from(base64Data, "base64");
+    if (buffer.length === 0) {
+        throw new Error("上传的图片数据为空");
+    }
+    if (buffer.length > MAX_UPLOAD_BYTES) {
+        throw new Error(`图片大小（${(buffer.length / 1024 / 1024).toFixed(1)}MB）超过 5MB 上限`);
+    }
+    if (!validateImageMagic(buffer, mimeType)) {
+        throw new Error("图片数据与声明的 MIME 类型不符或文件损坏");
+    }
+    const id = crypto.randomUUID();
+    const ext = extForMime(mimeType);
+    const filename = `${id}${ext}`;
+    const conversationDir = join(uploadsDir, conversationId);
+    await mkdir(conversationDir, { recursive: true });
+    const targetPath = join(conversationDir, filename);
+    await writeFile(targetPath, buffer);
+    const cleanName = (clientName?.trim() || filename).slice(0, 120);
+    const meta = {
+        id,
+        conversationId,
+        name: cleanName,
+        mimeType,
+        bytes: buffer.length,
+        createdAt: new Date().toISOString(),
+    };
+    await writeFile(join(conversationDir, `${id}.meta.json`), JSON.stringify(meta), "utf8");
+    return {
+        id,
+        conversationId,
+        name: cleanName,
+        mimeType,
+        bytes: buffer.length,
+        url: `/api/upload/${conversationId}/${filename}`,
+    };
+}
+export async function findUploadFile(uploadsDir, conversationId, filenameOrId) {
+    if (!existsSync(uploadsDir))
+        return null;
+    // Syntactic safety check: reject path traversal
+    if (filenameOrId.includes("..") || filenameOrId.includes("/") || filenameOrId.includes("\\"))
+        return null;
+    if (conversationId) {
+        if (conversationId.includes("..") || conversationId.includes("/") || conversationId.includes("\\"))
+            return null;
+        const directPath = join(uploadsDir, conversationId, filenameOrId);
+        if (existsSync(directPath)) {
+            const s = await stat(directPath);
+            if (s.isFile()) {
+                const mime = mimeForExt(extname(directPath));
+                return { filePath: directPath, mimeType: mime, size: s.size };
+            }
+        }
+        const dir = join(uploadsDir, conversationId);
+        if (existsSync(dir)) {
+            const entries = await readdir(dir).catch(() => []);
+            for (const entry of entries) {
+                if (!entry.endsWith(".meta.json") && (entry === filenameOrId || entry.startsWith(`${filenameOrId}.`))) {
+                    const fp = join(dir, entry);
+                    const s = await stat(fp);
+                    if (s.isFile()) {
+                        return { filePath: fp, mimeType: mimeForExt(extname(fp)), size: s.size };
+                    }
+                }
+            }
+        }
+    }
+    // Fallback: search across all conversation upload directories
+    const convDirs = await readdir(uploadsDir).catch(() => []);
+    for (const conv of convDirs) {
+        const dir = join(uploadsDir, conv);
+        const entries = await readdir(dir).catch(() => []);
+        for (const entry of entries) {
+            if (!entry.endsWith(".meta.json") && (entry === filenameOrId || entry.startsWith(`${filenameOrId}.`))) {
+                const fp = join(dir, entry);
+                const s = await stat(fp);
+                if (s.isFile()) {
+                    return { filePath: fp, mimeType: mimeForExt(extname(fp)), size: s.size };
+                }
+            }
+        }
+    }
+    return null;
+}
+export async function deleteConversationUploads(uploadsDir, conversationId) {
+    if (conversationId.includes("..") || conversationId.includes("/") || conversationId.includes("\\"))
+        return;
+    const dir = join(uploadsDir, conversationId);
+    await rm(dir, { recursive: true, force: true }).catch(() => { });
+}
+export async function loadConversationImages(uploadsDir, conversationId, images) {
+    const result = [];
+    for (const img of images) {
+        const found = await findUploadFile(uploadsDir, conversationId, img.id);
+        if (found) {
+            const buf = await readFile(found.filePath);
+            result.push({
+                type: "image",
+                data: buf.toString("base64"),
+                mimeType: img.mimeType || found.mimeType,
+            });
+        }
+    }
+    return result;
+}

package/dist/server/ws-server.d.ts

@@ -0,0 +1,45 @@
+import type { Server as NodeHttpServer } from "node:http";
+import { WebSocket } from "ws";
+import type { AppState, ServerEvent } from "./types.js";
+import type { EventBroadcaster } from "./server-context.js";
+import type { CommandHandler } from "./command-handler.js";
+import type { CatalogService } from "./application/catalog-service.js";
+/**
+ * Concrete implementation of EventBroadcaster delivering server events
+ * across active WebSocket connections.
+ */
+export declare class WsBroadcaster implements EventBroadcaster {
+    private readonly getState;
+    private readonly sockets;
+    constructor(getState: () => AppState);
+    register(socket: WebSocket): void;
+    unregister(socket: WebSocket): void;
+    getSockets(): Set<WebSocket>;
+    broadcast(event: ServerEvent): void;
+    broadcastState(): void;
+    getStateSnapshot(): AppState;
+}
+export interface WsServerOptions {
+    httpServer: NodeHttpServer;
+    broadcaster: WsBroadcaster;
+    commandHandler: CommandHandler;
+    catalogService: CatalogService;
+    accessToken?: string;
+}
+/**
+ * WebSocket transport manager handling upgrade, connection lifecycles, and command dispatch.
+ */
+export declare class WsServer {
+    private readonly websocketServer;
+    private readonly broadcaster;
+    private readonly commandHandler;
+    private readonly catalogService;
+    private readonly accessToken?;
+    constructor(options: WsServerOptions);
+    private setupUpgrade;
+    private setupConnectionHandling;
+    /**
+     * Gracefully closes all active WebSocket connections and terminates the server.
+     */
+    close(): void;
+}

package/dist/server/ws-server.js

@@ -0,0 +1,116 @@
+import { WebSocket, WebSocketServer } from "ws";
+import { isAuthorized } from "./http-server.js";
+/**
+ * Concrete implementation of EventBroadcaster delivering server events
+ * across active WebSocket connections.
+ */
+export class WsBroadcaster {
+    getState;
+    sockets = new Set();
+    constructor(getState) {
+        this.getState = getState;
+    }
+    register(socket) {
+        this.sockets.add(socket);
+    }
+    unregister(socket) {
+        this.sockets.delete(socket);
+    }
+    getSockets() {
+        return this.sockets;
+    }
+    broadcast(event) {
+        const payload = JSON.stringify(event);
+        for (const socket of this.sockets) {
+            if (socket.readyState === WebSocket.OPEN) {
+                socket.send(payload);
+            }
+        }
+    }
+    broadcastState() {
+        this.broadcast({ type: "state", state: this.getState() });
+    }
+    getStateSnapshot() {
+        return this.getState();
+    }
+}
+/**
+ * WebSocket transport manager handling upgrade, connection lifecycles, and command dispatch.
+ */
+export class WsServer {
+    websocketServer;
+    broadcaster;
+    commandHandler;
+    catalogService;
+    accessToken;
+    constructor(options) {
+        this.broadcaster = options.broadcaster;
+        this.commandHandler = options.commandHandler;
+        this.catalogService = options.catalogService;
+        this.accessToken = options.accessToken;
+        this.websocketServer = new WebSocketServer({ noServer: true });
+        this.setupUpgrade(options.httpServer);
+        this.setupConnectionHandling();
+    }
+    setupUpgrade(httpServer) {
+        httpServer.on("upgrade", (request, socket, head) => {
+            if (!isAuthorized(request, this.accessToken) || new URL(request.url ?? "/", "http://localhost").pathname !== "/ws") {
+                socket.destroy();
+                return;
+            }
+            this.websocketServer.handleUpgrade(request, socket, head, (ws) => {
+                this.websocketServer.emit("connection", ws, request);
+            });
+        });
+    }
+    setupConnectionHandling() {
+        this.websocketServer.on("connection", (socket) => {
+            this.broadcaster.register(socket);
+            socket.send(JSON.stringify({ type: "state", state: this.broadcaster.getStateSnapshot() }));
+            void this.catalogService.agentCatalog().then((catalog) => {
+                if (socket.readyState === WebSocket.OPEN) {
+                    socket.send(JSON.stringify({ type: "agent.catalog", catalog }));
+                }
+            }).catch((error) => console.warn(`Super Pi: agent catalog for a new connection failed: ${error instanceof Error ? error.message : "unknown error"}`));
+            void this.catalogService.subagentCatalog().then((catalog) => {
+                if (socket.readyState === WebSocket.OPEN) {
+                    socket.send(JSON.stringify({ type: "subagent.catalog", catalog }));
+                }
+            }).catch((error) => console.warn(`Super Pi: sub-agent catalog for a new connection failed: ${error instanceof Error ? error.message : "unknown error"}`));
+            const heartbeat = setInterval(() => {
+                if (socket.readyState === WebSocket.OPEN) {
+                    socket.ping();
+                }
+            }, 30_000);
+            socket.on("close", () => {
+                clearInterval(heartbeat);
+                this.broadcaster.unregister(socket);
+            });
+            socket.on("message", async (raw) => {
+                try {
+                    const command = JSON.parse(raw.toString());
+                    await this.commandHandler.handleCommand(command, (event) => {
+                        if (socket.readyState === WebSocket.OPEN) {
+                            socket.send(JSON.stringify(event));
+                        }
+                    });
+                }
+                catch (error) {
+                    socket.send(JSON.stringify({
+                        type: "error",
+                        message: error instanceof Error ? error.message : "command failed",
+                    }));
+                }
+            });
+        });
+    }
+    /**
+     * Gracefully closes all active WebSocket connections and terminates the server.
+     */
+    close() {
+        for (const socket of this.broadcaster.getSockets()) {
+            socket.close(1001, "server-shutdown");
+        }
+        this.websocketServer.close();
+    }
+}

package/package.json

@@ -1,6 +1,117 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Web control plane and companion for Pi",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "super-pi": "bin/super-pi.js"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extension.js"
+    ]
+  },
+  "files": [
+    "dist",
+    "agents",
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "prepack": "npm run build",
+    "dev": "concurrently --kill-others-on-fail \"npm:dev:server\" \"npm:dev:client\"",
+    "dev:client": "vite --host 0.0.0.0",
+    "dev:server": "tsx watch src/server/index.ts",
+    "build": "tsc -b && vite build",
+    "start": "node dist/server/index.js",
+    "restart:server": "node scripts/restart-server.mjs",
+    "smoke": "npm run build && node scripts/smoke.mjs",
+    "check": "node scripts/run-check.mjs"
+  },
+  "check:logic": [
+    "scripts/dispatch-ancestry.test.mjs",
+    "scripts/dispatch-endpoint.test.mjs",
+    "scripts/dispatched-by.test.mjs",
+    "scripts/verify-source-text.test.mjs",
+    "scripts/runtime-extension-ui.test.mjs",
+    "scripts/agent-mechanism.test.mjs",
+    "scripts/agent-wiring.test.mjs",
+    "scripts/message-timestamps.test.mjs",
+    "scripts/pi-resolution.test.mjs",
+    "scripts/agent-real-pi.test.mjs",
+    "scripts/image-input-real-pi.test.mjs",
+    "scripts/image-upload.test.mjs",
+    "scripts/extension-ui-e2e.test.mjs",
+    "scripts/session-picker.test.mjs",
+    "scripts/workspace-cwd.test.mjs",
+    "scripts/subagents.test.mjs",
+    "scripts/subagent-noise.test.mjs",
+    "scripts/subagent-runs.test.mjs",
+    "scripts/conversation-reconcile.test.mjs",
+    "scripts/subagent-dispatch.test.mjs",
+    "scripts/agent-vis-records.test.mjs",
+    "scripts/queue-store.test.mjs",
+    "scripts/followup.test.mjs",
+    "scripts/md-render.test.mjs",
+    "scripts/revert-session-format.test.mjs",
+    "scripts/revert-session-file.test.mjs",
+    "scripts/revert-real-pi.test.mjs",
+    "scripts/bg-task.test.mjs",
+    "scripts/todo-tool.test.mjs",
+    "scripts/tool-calls.test.mjs",
+    "scripts/files-api.test.mjs",
+    "scripts/files-missing-path.test.mjs",
+    "scripts/task-tool.test.mjs",
+    "scripts/fork-server.test.mjs",
+    "scripts/styles-no-dangling.test.mjs",
+    "scripts/theme-no-hardcoded-colours.test.mjs"
+  ],
+  "check:browser": [
+    "scripts/extension-ui-browser.test.mjs",
+    "scripts/inline-rename-blur.test.mjs",
+    "scripts/message-timestamps-browser.test.mjs",
+    "scripts/session-picker-browser.test.mjs",
+    "scripts/workspace-settings-browser.test.mjs",
+    "scripts/subagent-card-browser.test.mjs",
+    "scripts/conversation-reconcile-browser.test.mjs",
+    "scripts/visual-defects-browser.test.mjs",
+    "scripts/agent-vis-card-browser.test.mjs",
+    "scripts/queue-dock.test.mjs",
+    "scripts/md-render-browser.test.mjs",
+    "scripts/right-sidebar-browser.test.mjs",
+    "scripts/sidebar-tools-browser.test.mjs",
+    "scripts/tool-call-blocks-browser.test.mjs",
+    "scripts/files-tab-browser.test.mjs",
+    "scripts/msg-tabs-browser.test.mjs",
+    "scripts/tabs-on-top-browser.test.mjs",
+    "scripts/subagent-source.test.mjs",
+    "scripts/fork-resize-browser.test.mjs",
+    "scripts/msg-bubbles.test.mjs",
+    "scripts/narrow-layout.test.mjs",
+    "scripts/scrollbar-style.test.mjs",
+    "scripts/theme-contrast.test.mjs",
+    "scripts/theme-switch-state.test.mjs",
+    "scripts/settings-window-structure.test.mjs",
+    "scripts/file-tab-selected-contrast.test.mjs"
+  ],
+  "dependencies": {
+    "ws": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "@types/react": "latest",
+    "@types/react-dom": "latest",
+    "@types/ws": "latest",
+    "@vitejs/plugin-react": "latest",
+    "concurrently": "latest",
+    "react": "latest",
+    "react-dom": "latest",
+    "tsx": "latest",
+    "typescript": "latest",
+    "vite": "latest"
+  }
+}