@world-engines/project-host 0.1.0-alpha.0

package/dist/desktop-sidecar.d.ts

@@ -0,0 +1,11 @@
+export declare const DESKTOP_PRIVATE_PROTOCOL: "worldengine.project-transfer.private.v1";
+export declare const DESKTOP_PRIVATE_MAX_REQUEST_BYTES: number;
+export interface DesktopPrivateRequest {
+    readonly namespace: typeof DESKTOP_PRIVATE_PROTOCOL;
+    readonly capability: "project_transfer";
+    readonly method: "upload.prepare" | "download.inspect" | "download.apply" | "download.restore";
+    readonly request_digest: string;
+    readonly payload: unknown;
+}
+/** 与 MCP tools/list 完全分离的版本化 Desktop RPC。 */
+export declare function handleDesktopPrivateRequest(root: string, request: DesktopPrivateRequest): Promise<unknown>;

package/dist/desktop-sidecar.js

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { assertSafeExistingProjectPath } from "./safe-project-path.js";
+import { DownloadReplaceCoordinator, decodeRemoteViewBundle, parseRemoteDownloadPlan } from "./transfer/download.js";
+import { captureUploadSnapshot } from "./transfer/upload.js";
+import { LocalProjectHost } from "./project-host.js";
+export const DESKTOP_PRIVATE_PROTOCOL = "worldengine.project-transfer.private.v1";
+export const DESKTOP_PRIVATE_MAX_REQUEST_BYTES = 8 * 1024 * 1024;
+const execFileAsync = promisify(execFile);
+function record(value, code) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", code);
+    return value;
+}
+function digest(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+function exactKeys(value, keys, code) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index]))
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", code);
+}
+function incomingObject(value, objectRef, expectedMediaType, code) {
+    const input = record(value, code);
+    exactKeys(input, ["content_base64", "sha256", "byte_length"], code);
+    if (typeof input.content_base64 !== "string" || input.sha256 !== objectRef.sha256 || input.byte_length !== objectRef.byteLength || objectRef.mediaType !== expectedMediaType)
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", code);
+    const bytes = new Uint8Array(Buffer.from(input.content_base64, "base64"));
+    if (bytes.length !== objectRef.byteLength || digest(bytes) !== objectRef.sha256)
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", code);
+    return bytes;
+}
+function downloadPlanFromGuiPayload(payload, operationId, expectedProjectRevision) {
+    const remotePayload = record(payload.remote_plan, "download remote_plan 无效");
+    const remote = parseRemoteDownloadPlan(remotePayload);
+    const objects = record(payload.objects, "download objects 无效");
+    exactKeys(objects, remote.parts, "download objects 与 frozen parts 不一致");
+    const scenario = remote.scenarioObject === undefined ? undefined : incomingObject(objects.scenario, remote.scenarioObject, "application/vnd.worldengine.wesp", "download scenario object 无效");
+    const view = remote.viewObject === undefined ? undefined : incomingObject(objects.view, remote.viewObject, "application/vnd.worldengine.svp", "download view object 无效");
+    return {
+        remote,
+        plan: {
+            schema_version: 1,
+            operation_id: operationId,
+            plan_digest: remote.planDigest,
+            expected_project_revision: expectedProjectRevision,
+            selection: remote.parts.length === 2 ? "both" : remote.parts[0],
+            ...(scenario === undefined ? {} : { scenario: { source_base64: Buffer.from(scenario).toString("base64"), sha256: digest(scenario) } }),
+            ...(view === undefined ? {} : { view: decodeRemoteViewBundle(view) }),
+        },
+    };
+}
+function validateEnvelope(request) {
+    if (request.namespace !== DESKTOP_PRIVATE_PROTOCOL || request.capability !== "project_transfer") {
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "private sidecar capability 无效");
+    }
+    const bytes = new TextEncoder().encode(JSON.stringify(request.payload));
+    if (bytes.length > DESKTOP_PRIVATE_MAX_REQUEST_BYTES)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "private sidecar 请求过大");
+    if (!/^[a-f0-9]{64}$/.test(request.request_digest) || digest(bytes) !== request.request_digest) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "private sidecar request digest 不匹配");
+    }
+    return record(request.payload, "private sidecar payload 无效");
+}
+/** 与 MCP tools/list 完全分离的版本化 Desktop RPC。 */
+export async function handleDesktopPrivateRequest(root, request) {
+    const canonicalRoot = await assertSafeExistingProjectPath(root, root);
+    const payload = validateEnvelope(request);
+    switch (request.method) {
+        case "upload.prepare": {
+            const operationId = payload.operation_id;
+            if (typeof operationId !== "string" || operationId.length === 0 || operationId.length > 256)
+                throw new AuthoringBridgeError("E_SCHEMA_INVALID", "upload operation_id 无效");
+            const captured = await captureUploadSnapshot(canonicalRoot);
+            return {
+                schema_version: 1,
+                operation_id: operationId,
+                snapshot: captured.snapshot,
+                objects: captured.objects.map(({ bytes, ...object }) => ({ ...object, content_base64: Buffer.from(bytes).toString("base64") })),
+            };
+        }
+        case "download.apply": {
+            exactKeys(payload, ["remote_plan", "objects", "inspection", "confirmation"], "download apply payload 无效");
+            const confirmation = record(payload.confirmation, "download confirmation 无效");
+            if (typeof confirmation.operation_id !== "string" || typeof confirmation.plan_digest !== "string")
+                throw new AuthoringBridgeError("E_SCHEMA_INVALID", "download confirmation 无效");
+            const inspection = record(payload.inspection, "download inspection 无效");
+            if (typeof inspection.expected_project_revision !== "number" || !Number.isSafeInteger(inspection.expected_project_revision) || inspection.expected_project_revision < 0)
+                throw new AuthoringBridgeError("E_SCHEMA_INVALID", "download inspection revision 无效");
+            if (confirmation.local_inspection_digest !== undefined && confirmation.local_inspection_digest !== inspection.local_inspection_digest)
+                throw new AuthoringBridgeError("E_VALIDATION_FAILED", "download confirmation inspection digest 不匹配");
+            const { plan } = downloadPlanFromGuiPayload(payload, confirmation.operation_id, inspection.expected_project_revision);
+            if (confirmation.plan_digest !== plan.plan_digest || inspection.remote_plan_digest !== plan.plan_digest)
+                throw new AuthoringBridgeError("E_VALIDATION_FAILED", "download confirmation 未绑定 frozen plan");
+            const coordinator = await DownloadReplaceCoordinator.open(canonicalRoot, {
+                installViewDependencies: async (stagingViewRoot) => {
+                    await execFileAsync(process.platform === "win32" ? "npm.cmd" : "npm", ["ci", "--ignore-scripts", "--no-audit", "--no-fund"], {
+                        cwd: stagingViewRoot,
+                        timeout: 5 * 60_000,
+                        windowsHide: true,
+                        maxBuffer: 1024 * 1024,
+                    });
+                },
+                readProjection: async (receipt) => {
+                    const host = await LocalProjectHost.open(canonicalRoot);
+                    try {
+                        const readback = await host.readTransferReadback();
+                        if (readback.project_revision !== receipt.next_project_revision || readback.snapshot_digest !== receipt.project_snapshot_digest || readback.scenario_sha256 !== receipt.scenario_sha256 || readback.view_source_tree_sha256 !== receipt.view_source_tree_sha256)
+                            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "download ProjectHost transfer readback 不匹配");
+                    }
+                    finally {
+                        await host.close();
+                    }
+                },
+            });
+            try {
+                const receipt = await coordinator.apply(plan, {
+                    operation_id: String(confirmation.operation_id ?? ""),
+                    plan_digest: String(confirmation.plan_digest ?? ""),
+                }, inspection);
+                return receipt;
+            }
+            catch (error) {
+                await coordinator.restore(String(confirmation.operation_id ?? "")).catch(() => undefined);
+                throw error;
+            }
+        }
+        case "download.inspect": {
+            exactKeys(payload, ["remote_plan", "objects"], "download inspect payload 无效");
+            const remote = parseRemoteDownloadPlan(record(payload.remote_plan, "download remote_plan 无效"));
+            const { plan } = downloadPlanFromGuiPayload(payload, `download.inspect.${remote.planId}`, 0);
+            return (await DownloadReplaceCoordinator.open(canonicalRoot)).inspect(plan, remote.planId);
+        }
+        case "download.restore": {
+            const operationId = payload.operation_id;
+            if (typeof operationId !== "string" || operationId.length === 0 || operationId.length > 256)
+                throw new AuthoringBridgeError("E_SCHEMA_INVALID", "restore operation_id 无效");
+            await (await DownloadReplaceCoordinator.open(canonicalRoot)).restore(operationId);
+            return { schema_version: 1, operation_id: operationId, restored: true };
+        }
+    }
+}

package/dist/document-dump.d.ts

@@ -0,0 +1,113 @@
+import type { ScenarioSourceReadback } from "./scenario-writer.js";
+import { type LadybugGraphSnapshot } from "./ladybug-runtime.js";
+type Span = {
+    startOffset: number;
+    endOffset: number;
+};
+export interface DocumentDumpExtractionStatus {
+    graphStatus: "partial" | "complete" | "not_recorded";
+    processedWindows: number | null;
+    authorityMarkerId: string | null;
+}
+export interface DocumentDumpProjectionVerification {
+    status: "verified" | "mismatch" | "not_checked";
+    sourceSha256: string | null;
+    projectRevision: number | null;
+    counts: {
+        expectedNodes: number;
+        actualNodes: number | null;
+        expectedEdges: number;
+        actualEdges: number | null;
+    };
+    missing: {
+        nodeIds: string[];
+        edgeIds: string[];
+    };
+    extra: {
+        nodeIds: string[];
+        edgeIds: string[];
+    };
+    mismatch: {
+        nodeIds: string[];
+        edgeIds: string[];
+    };
+}
+export interface DocumentPlainTextDumpHost {
+    readSourceReadback(): Promise<ScenarioSourceReadback>;
+    readGraphProjectionReadback?(request: {
+        scopeId?: string;
+    }): Promise<{
+        project_revision: number;
+        source_sha256: string;
+        graph: LadybugGraphSnapshot;
+    }>;
+}
+export interface DocumentPlainTextDumpManifest {
+    schemaVersion: 1;
+    documentId: string;
+    projectRevision: number;
+    scopeId: string;
+    sourceId: string;
+    sourceRevision: string;
+    authority: {
+        projectId: string;
+        wespSha256: string;
+        enumeration: "complete_logical_graph";
+    };
+    integrity: {
+        status: "verified" | "incomplete";
+        warnings: string[];
+    };
+    source: {
+        integrityStatus: "verified";
+        byteLength: number;
+        sha256: string;
+        utf16Length: number;
+        unicodeCodePoints: number;
+        hanCharacters: number;
+    };
+    extraction: DocumentDumpExtractionStatus;
+    projection: DocumentDumpProjectionVerification;
+    chunks: {
+        count: number;
+        reconstructedSha256: string;
+        coverageRatio: number;
+        gaps: Span[];
+        overlaps: Span[];
+        invalidCount: number;
+    };
+    graph: {
+        nodeCount: number;
+        edgeCount: number;
+        semanticEntityCount: number;
+        sourceChunkCount: number;
+        statementAssertionCount: number;
+        edgeAssertionCount: number;
+        structuralEdgeCount: number;
+        semanticEdgeCount: number;
+        unknownEdgeCount: number;
+        nodesByKind: Record<string, number>;
+        edgesByKind: Record<string, number>;
+        uniqueAssertionCount: number;
+        assertionBodyUtf16Length: number;
+        externalReferenceCount: number;
+    };
+    evidence: {
+        uniqueSpanCount: number;
+        coveredUtf16Length: number;
+        coverageRatio: number;
+        invalidCount: number;
+    };
+    interpretation: string[];
+}
+export interface DocumentPlainTextDump {
+    sourceBytes: Uint8Array;
+    graphText: string;
+    reviewText: string;
+    manifest: DocumentPlainTextDumpManifest;
+}
+/** 原文与枚举只消费一次 WESP authority；真实 Ladybug 只作同版本投影校验，不成为第二 authority。 */
+export declare function createDocumentPlainTextDump(host: DocumentPlainTextDumpHost, request: {
+    documentId: string;
+}): Promise<DocumentPlainTextDump>;
+export {};