@cjhyy/code-shell-server 0.9.7 → 0.9.9

package/dist/panels/storage-store.d.ts

@@ -0,0 +1,9 @@
+/** Matches the existing Desktop namespace, so its remote Web shares saved panel state. */
+export declare function panelAppStoragePath(dataDir: string, appId: string, projectPath: string): string;
+export declare const DEFAULT_PANEL_APP_STORAGE_QUOTA_BYTES: number;
+export type PanelAppStorage = Record<string, unknown>;
+export declare function panelAppStorageQuotaBytes(requested?: number): number;
+export declare function panelAppStorageKey(params: unknown): string;
+export declare function preparePanelAppStorage(file: string): Promise<void>;
+export declare function readPanelAppStorage(file: string, quotaBytes: number): Promise<PanelAppStorage>;
+export declare function writePanelAppStorage(file: string, storage: PanelAppStorage, quotaBytes: number, beforeCommit?: () => Promise<void>): Promise<void>;

package/dist/panels/storage-store.js

@@ -0,0 +1,154 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/** Matches the existing Desktop namespace, so its remote Web shares saved panel state. */
+export function panelAppStoragePath(dataDir, appId, projectPath) {
+    const namespace = createHash("sha256")
+        .update("codeshell-panel-app-storage-v2")
+        .update("\0")
+        .update(appId)
+        .update("\0")
+        .update(projectPath)
+        .digest("hex");
+    return join(dataDir, "panel-app-storage", `${namespace}.json`);
+}
+export const DEFAULT_PANEL_APP_STORAGE_QUOTA_BYTES = 256 * 1024;
+const MAX_PANEL_APP_STORAGE_QUOTA_BYTES = 16 * 1024 * 1024;
+const MAX_PANEL_APP_STORAGE_KEYS = 10_000;
+const STORAGE_KEY_PATTERN = /^[a-zA-Z0-9._-]{1,80}$/;
+export function panelAppStorageQuotaBytes(requested) {
+    if (requested === undefined)
+        return DEFAULT_PANEL_APP_STORAGE_QUOTA_BYTES;
+    if (!Number.isSafeInteger(requested) || requested <= 0) {
+        throw new Error("Panel App storage quota must be a positive safe integer");
+    }
+    return Math.min(requested, MAX_PANEL_APP_STORAGE_QUOTA_BYTES);
+}
+export function panelAppStorageKey(params) {
+    const key = params?.key;
+    if (typeof key !== "string" || !STORAGE_KEY_PATTERN.test(key)) {
+        throw new Error("storage key must match [a-zA-Z0-9._-]{1,80}");
+    }
+    return key;
+}
+function emptyStorage() {
+    // A null prototype is important here: valid app keys include names such as
+    // `__proto__`, `constructor`, and `toString`. They must remain data keys and
+    // never read or mutate JavaScript's object prototype.
+    return Object.create(null);
+}
+async function assertRealStorageParent(file, create) {
+    const parent = dirname(file);
+    if (create)
+        await mkdir(parent, { recursive: true, mode: 0o700 });
+    const metadata = await lstat(parent);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+        throw new Error("Panel App storage parent must be a real directory");
+    }
+}
+async function storageFileMetadata(file) {
+    try {
+        return await lstat(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export async function preparePanelAppStorage(file) {
+    await assertRealStorageParent(file, true);
+    const metadata = await storageFileMetadata(file);
+    if (metadata && (metadata.isSymbolicLink() || !metadata.isFile())) {
+        throw new Error("Panel App storage target must be a regular file");
+    }
+    if (!metadata) {
+        // Materialize an empty store so the caller can take a PER-FILE lock on it.
+        // Locking this path (rather than the shared parent directory) is what keeps
+        // one panel app's storage write from stalling every other app; the lock
+        // library needs the target to exist. `wx` keeps this a no-op under a race.
+        try {
+            await writeFile(file, "{}\n", { encoding: "utf8", mode: 0o600, flag: "wx" });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+}
+export async function readPanelAppStorage(file, quotaBytes) {
+    const quota = panelAppStorageQuotaBytes(quotaBytes);
+    let handle;
+    try {
+        await assertRealStorageParent(file, false);
+        const metadata = await storageFileMetadata(file);
+        if (!metadata)
+            return emptyStorage();
+        if (metadata.isSymbolicLink() || !metadata.isFile() || metadata.size > quota) {
+            throw new Error("Panel App storage must be a bounded regular file");
+        }
+        handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.size > quota) {
+            throw new Error("Panel App storage must be a bounded regular file");
+        }
+        const parsed = JSON.parse(await handle.readFile("utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("Panel App storage root must be an object");
+        }
+        const entries = Object.entries(parsed);
+        if (entries.length > MAX_PANEL_APP_STORAGE_KEYS) {
+            throw new Error("Panel App storage contains too many keys");
+        }
+        const storage = emptyStorage();
+        for (const [key, value] of entries) {
+            if (!STORAGE_KEY_PATTERN.test(key))
+                throw new Error("Panel App storage contains an invalid key");
+            storage[key] = value;
+        }
+        return storage;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return emptyStorage();
+        throw error;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+export async function writePanelAppStorage(file, storage, quotaBytes, beforeCommit) {
+    const quota = panelAppStorageQuotaBytes(quotaBytes);
+    const entries = Object.entries(storage);
+    if (entries.length > MAX_PANEL_APP_STORAGE_KEYS) {
+        throw new Error("Panel App storage contains too many keys");
+    }
+    for (const [key] of entries) {
+        if (!STORAGE_KEY_PATTERN.test(key))
+            throw new Error("Panel App storage contains an invalid key");
+    }
+    const serialized = `${JSON.stringify(storage)}\n`;
+    if (Buffer.byteLength(serialized, "utf8") > quota) {
+        throw new Error("Panel App storage quota exceeded");
+    }
+    await preparePanelAppStorage(file);
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, serialized, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        // A remote owner can disconnect or lose its binding while staging bytes.
+        // Recheck both authorization and the target after staging, before publishing.
+        await beforeCommit?.();
+        await preparePanelAppStorage(file);
+        await rename(temporary, file);
+        if (process.platform !== "win32")
+            await chmod(file, 0o600);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}

package/dist/panels/types.d.ts

@@ -0,0 +1,52 @@
+import type { GitPanelAppDiscoveryCandidate, GitPanelAppDiscoveryIssue, PanelAppPreview } from "@cjhyy/code-shell-core";
+export interface PanelCompatibility {
+    supported: boolean;
+    reasons: string[];
+}
+export interface PanelGitSource {
+    kind: "git";
+    url: string;
+    /** The original branch/tag, retained separately from the pinned archive commit. */
+    ref: string;
+    subdir?: string;
+    commit: string;
+}
+export interface ManagedPanel extends Omit<PanelAppPreview, "reviewToken" | "alreadyInstalled" | "warnings" | "source"> {
+    revision: string;
+    bound: boolean;
+    enabled: boolean;
+    globalDisabled: boolean;
+    updatable: boolean;
+    source: {
+        kind: "git" | "local";
+        label: string;
+        url?: string;
+        ref?: string;
+        commit?: string;
+        subdir?: string;
+    };
+    compatibility: PanelCompatibility;
+}
+export interface PanelSnapshot {
+    panels: ManagedPanel[];
+    workspace: string;
+    hasProject: boolean;
+}
+export interface PanelDiscovery {
+    panels: GitPanelAppDiscoveryCandidate[];
+    issues: GitPanelAppDiscoveryIssue[];
+    source: PanelGitSource;
+}
+export interface PanelReview {
+    reviewToken: string;
+    expiresAt: number;
+    kind: "install" | "update";
+    preview: Omit<PanelAppPreview, "reviewToken">;
+    source: PanelGitSource;
+    expectedRevision: string | null;
+    compatibility: PanelCompatibility;
+}
+export interface PanelOperationContext {
+    ownerId: string;
+    authorize: () => boolean | Promise<boolean>;
+}

package/dist/panels/types.js

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

package/dist/project-runtime/control-server.d.ts

@@ -0,0 +1,19 @@
+import type { ProjectRuntimeProvider } from "./types.js";
+export interface ProjectControlServerOptions {
+    host: string;
+    port: number;
+    dataDir: string;
+    publicOrigin?: string;
+    staticRootDir?: string;
+    runtimeImage?: string;
+    /** Dependency injection for lifecycle/transport integration tests. */
+    provider?: ProjectRuntimeProvider;
+}
+/** A small account/project gateway. It never creates a worker, executes tools or mounts cwd. */
+export declare function startProjectControlServer(options: ProjectControlServerOptions): Promise<{
+    url: string;
+    port: number;
+    bootstrapToken: string | undefined;
+    generatedPasscode: undefined;
+    close(): Promise<void>;
+}>;

package/dist/project-runtime/control-server.js

@@ -0,0 +1,300 @@
+import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { createHubAuth } from "../hub/auth-http.js";
+import { resolveSafe } from "../mobile-remote/mobile-static.js";
+import { contentTypeFor } from "../static-files.js";
+import { createDockerProjectProvider } from "./docker-provider.js";
+import { ProjectManager } from "./manager.js";
+import { createProjectRuntimeProxy } from "./proxy.js";
+import { ProjectRegistry, ProjectRegistryError } from "./registry.js";
+function json(response, status, value) {
+    if (response.destroyed || response.writableEnded)
+        return;
+    response.writeHead(status, {
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
+    });
+    response.end(JSON.stringify(value));
+}
+async function readBody(request) {
+    if (!/^application\/json(?:\s*;|$)/i.test(request.headers["content-type"] ?? ""))
+        throw new ProjectRegistryError(415, "请使用 JSON 提交。");
+    let size = 0;
+    const chunks = [];
+    await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            request.off("data", onData);
+            request.off("end", onEnd);
+            request.off("error", onError);
+            request.off("aborted", onAborted);
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onAborted = () => onError(new ProjectRegistryError(400, "请求已中断。"));
+        const onEnd = () => {
+            cleanup();
+            resolve();
+        };
+        const onData = (chunk) => {
+            size += chunk.length;
+            if (size > 8192) {
+                cleanup();
+                request.resume();
+                reject(new ProjectRegistryError(413, "请求过大。"));
+            }
+            else
+                chunks.push(Buffer.from(chunk));
+        };
+        request.on("data", onData);
+        request.once("end", onEnd);
+        request.once("error", onError);
+        request.once("aborted", onAborted);
+    });
+    try {
+        const value = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        if (value && typeof value === "object" && !Array.isArray(value))
+            return value;
+    }
+    catch {
+        /* Invalid JSON is a client error. */
+    }
+    throw new ProjectRegistryError(400, "请求格式无效。");
+}
+/** A small account/project gateway. It never creates a worker, executes tools or mounts cwd. */
+export async function startProjectControlServer(options) {
+    const registry = new ProjectRegistry(options.dataDir);
+    let proxy;
+    let manager;
+    let provider;
+    let server;
+    let shuttingDown = false;
+    try {
+        const auth = await createHubAuth({
+            dataDir: options.dataDir,
+            publicOrigin: options.publicOrigin,
+            onRevoke: (sessionId) => {
+                if (shuttingDown)
+                    return;
+                void proxy?.revokeOwner(sessionId).catch(async () => {
+                    if (shuttingDown)
+                        return;
+                    // The revoked browser's transports are already closed. If its inner
+                    // session cannot be revoked, stop the single administrator's runtimes.
+                    try {
+                        await manager?.stopAll();
+                    }
+                    catch {
+                        console.error("[project-control] could not confirm project termination after session revocation.");
+                    }
+                });
+            },
+        });
+        let listeningOrigin = "";
+        const publicOrigin = () => options.publicOrigin ?? listeningOrigin;
+        provider =
+            options.provider ??
+                createDockerProjectProvider({
+                    installationId: registry.installationId,
+                    dataDir: options.dataDir,
+                    image: options.runtimeImage,
+                });
+        manager = new ProjectManager({
+            registry,
+            provider,
+            publicOrigin,
+            isSessionActive: (session) => auth.store
+                .listSessions()
+                .some((item) => item.id === session.id && item.username === session.username),
+            revokeProject: async (id) => {
+                await proxy?.revokeProject(id);
+            },
+        });
+        const projects = manager;
+        proxy = createProjectRuntimeProxy({
+            auth,
+            publicOrigin,
+            resolveTarget: (id, session) => projects.resolveTarget(session, id),
+            onRevocationFailure: (id) => {
+                // Ordered shutdown below owns termination of every runtime. Do not
+                // launch background cleanup that could outlive registry ownership.
+                if (shuttingDown)
+                    return;
+                void projects.stopAfterRevocationFailure(id).catch(() => {
+                    console.error("[project-control] could not confirm project termination after runtime revocation failed.");
+                });
+            },
+        });
+        const transport = proxy;
+        await projects.reconcile();
+        const handle = async (request, response) => {
+            if (shuttingDown)
+                throw new ProjectRegistryError(503, "项目服务正在关闭。");
+            response.setHeader("X-Content-Type-Options", "nosniff");
+            response.setHeader("Referrer-Policy", "no-referrer");
+            const url = new URL(request.url ?? "/", "http://localhost");
+            const pathname = url.pathname;
+            if (pathname === "/health" && request.method === "GET") {
+                json(response, 200, { status: "ok", mode: "project-sandbox", runtime: "docker" });
+                return;
+            }
+            if (await auth.handle(request, response))
+                return;
+            if (await transport.handle(request, response))
+                return;
+            if (pathname === "/api/v1/projects" || pathname.startsWith("/api/v1/projects/")) {
+                if (!auth.isOriginAllowed(request))
+                    throw new ProjectRegistryError(403, "请求来源无效。");
+                const session = await auth.authenticate(request);
+                if (!session)
+                    throw new ProjectRegistryError(401, "请先登录。");
+                if (url.search)
+                    throw new ProjectRegistryError(400, "项目请求参数无效。");
+                if (pathname === "/api/v1/projects" && request.method === "GET") {
+                    const availability = await provider.availability();
+                    json(response, 200, {
+                        runtime: "docker",
+                        ...availability,
+                        projects: projects.list(session),
+                    });
+                    return;
+                }
+                if (pathname === "/api/v1/projects" && request.method === "POST") {
+                    const body = await readBody(request);
+                    if (Object.keys(body).some((key) => key !== "name"))
+                        throw new ProjectRegistryError(400, "仅支持设置项目名称。");
+                    json(response, 201, { project: projects.create(session, body.name) });
+                    return;
+                }
+                const match = /^\/api\/v1\/projects\/([a-f0-9-]{36})(?:\/(start|stop))?$/.exec(pathname);
+                if (match && request.method === "GET" && !match[2]) {
+                    json(response, 200, { project: projects.get(session, match[1]) });
+                    return;
+                }
+                if (match?.[2] && request.method === "POST") {
+                    const body = await readBody(request);
+                    if (Object.keys(body).length)
+                        throw new ProjectRegistryError(400, "启动和停止不接受额外参数。");
+                    const project = match[2] === "start"
+                        ? await projects.start(session, match[1])
+                        : await projects.stop(session, match[1]);
+                    json(response, 200, { project });
+                    return;
+                }
+                throw new ProjectRegistryError(404, "找不到项目接口。");
+            }
+            if (pathname.startsWith("/api/") || pathname.startsWith("/p/") || pathname === "/ws") {
+                throw new ProjectRegistryError(404, "请先选择并启动项目。");
+            }
+            if (request.method !== "GET" && request.method !== "HEAD")
+                throw new ProjectRegistryError(405, "仅支持读取网页。");
+            const root = options.staticRootDir;
+            if (!root)
+                throw new ProjectRegistryError(404, "请先构建 Web 应用。");
+            let decoded;
+            try {
+                decoded = decodeURIComponent(pathname);
+            }
+            catch {
+                throw new ProjectRegistryError(400, "地址无效。");
+            }
+            let file = resolveSafe(root, decoded.replace(/^\//, ""));
+            if (!file && request.headers.accept?.includes("text/html"))
+                file = resolveSafe(root, "index.html");
+            if (!file)
+                throw new ProjectRegistryError(404, "找不到网页资源。");
+            const bytes = readFileSync(file);
+            response.writeHead(200, {
+                "Content-Type": contentTypeFor(extname(file)),
+                "Content-Length": bytes.length,
+                "Cache-Control": "no-cache",
+            });
+            response.end(request.method === "HEAD" ? undefined : bytes);
+        };
+        server = createServer((request, response) => {
+            void handle(request, response).catch((error) => {
+                if (response.headersSent) {
+                    response.destroy();
+                    return;
+                }
+                json(response, error instanceof ProjectRegistryError ? error.status : 503, {
+                    error: error instanceof ProjectRegistryError
+                        ? error.message
+                        : "项目服务暂不可用，请稍后重试。",
+                });
+            });
+        });
+        server.requestTimeout = 180000;
+        server.headersTimeout = 10000;
+        server.on("upgrade", (request, socket, head) => {
+            if (shuttingDown) {
+                socket.destroy();
+                return;
+            }
+            void transport
+                .handleUpgrade(request, socket, head)
+                .then((handled) => {
+                if (!handled)
+                    socket.destroy();
+            })
+                .catch(() => socket.destroy());
+        });
+        const listener = server;
+        await new Promise((resolve, reject) => {
+            listener.once("error", reject);
+            listener.listen(options.port, options.host, () => {
+                listener.off("error", reject);
+                resolve();
+            });
+        });
+        const address = listener.address();
+        if (!address || typeof address === "string")
+            throw new Error("Missing project listener address");
+        const host = ["0.0.0.0", "::"].includes(options.host) ? "127.0.0.1" : options.host;
+        listeningOrigin = `http://${host.includes(":") ? `[${host}]` : host}:${address.port}`;
+        let closing;
+        return {
+            url: listeningOrigin,
+            port: address.port,
+            bootstrapToken: auth.bootstrapToken,
+            generatedPasscode: undefined,
+            close() {
+                return (closing ??= (async () => {
+                    shuttingDown = true;
+                    const stopped = new Promise((resolve) => listener.close(() => resolve()));
+                    try {
+                        // Revoke streams and inner sessions before stopping their servers.
+                        // If logout is unreachable, confirmed runtime termination is the
+                        // fallback; a real stop failure must still reject close().
+                        await transport.close().catch(() => { });
+                        await projects.close();
+                    }
+                    finally {
+                        listener.closeAllConnections();
+                        try {
+                            await stopped;
+                        }
+                        finally {
+                            registry.close();
+                        }
+                    }
+                })());
+            },
+        };
+    }
+    catch (error) {
+        shuttingDown = true;
+        server?.close();
+        server?.closeAllConnections();
+        try {
+            await proxy?.close().catch(() => { });
+            await (manager ? manager.close() : provider?.close())?.catch(() => { });
+        }
+        finally {
+            registry.close();
+        }
+        throw error;
+    }
+}

package/dist/project-runtime/docker-provider.d.ts

@@ -0,0 +1,33 @@
+import type { ProjectRuntimeProvider, ProjectRuntimeRecord } from "./types.js";
+export declare const DEFAULT_PROJECT_RUNTIME_IMAGE = "codeshell-project-runtime:local";
+export declare const PROJECT_RUNTIME_SECRET_PATH = "/run/codeshell-project.json";
+export declare const PROJECT_RUNTIME_LABEL = "io.codeshell.project-runtime";
+export interface DockerCommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface DockerProjectProviderOptions {
+    installationId: string;
+    dataDir: string;
+    image?: string;
+    limits?: {
+        memoryMb?: number;
+        cpus?: number;
+        pids?: number;
+    };
+    commandTimeoutMs?: number;
+    startupTimeoutMs?: number;
+    /** Test seam; production always invokes Docker directly, without a shell. */
+    command?: (args: string[], options: {
+        signal: AbortSignal;
+    }) => Promise<DockerCommandResult>;
+    healthCheck?: (url: string, signal: AbortSignal) => Promise<boolean>;
+}
+export declare class ProjectRuntimeError extends Error {
+    constructor(message: string);
+}
+export declare function validateProjectRuntimeRecord(project: ProjectRuntimeRecord): void;
+export declare function validateProjectPublicOrigin(value: string): string;
+/** An administrator-owned Docker control client. Project tasks never receive this client. */
+export declare function createDockerProjectProvider(options: DockerProjectProviderOptions): ProjectRuntimeProvider;