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

package/dist/safe-project-path.js

@@ -0,0 +1,93 @@
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+function isInside(root, candidate) {
+    const path = relative(root, candidate);
+    return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+function assertInside(root, candidate) {
+    if (!isInside(root, candidate)) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", `路径逃逸项目根：${candidate}`);
+    }
+}
+function segments(projectRelativePath) {
+    if (typeof projectRelativePath !== "string" || projectRelativePath.trim() === "" || isAbsolute(projectRelativePath)) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "路径必须是非空项目相对路径");
+    }
+    const parts = projectRelativePath.split(/[\\/]+/).filter(Boolean);
+    if (parts.some((part) => part === "." || part === "..")) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "路径不能包含 . 或 ..");
+    }
+    return parts;
+}
+/** 只允许普通目录/文件；Windows junction 与 POSIX symlink 都由 lstat 的 symbolic link 标记拒绝。 */
+async function assertNoReparse(path) {
+    const info = await lstat(path);
+    if (info.isSymbolicLink()) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", `拒绝符号链接、junction 或 reparse point：${path}`);
+    }
+}
+/** 逐段验证已存在路径，随后 realpath 回读确认仍位于 canonical project root。 */
+export async function assertSafeExistingProjectPath(root, candidate) {
+    const canonicalRoot = await realpath(resolve(root));
+    const absolute = resolve(candidate);
+    assertInside(canonicalRoot, absolute);
+    const rel = relative(canonicalRoot, absolute);
+    let current = canonicalRoot;
+    await assertNoReparse(current);
+    for (const segment of rel === "" ? [] : rel.split(sep)) {
+        current = resolve(current, segment);
+        await assertNoReparse(current);
+    }
+    const canonical = await realpath(absolute);
+    assertInside(canonicalRoot, canonical);
+    return canonical;
+}
+/** 解析一个控制路径；所有已存在父段均须是普通目录，最终文件可尚未创建。 */
+export async function safeProjectPath(root, projectRelativePath) {
+    const canonicalRoot = await realpath(resolve(root));
+    const parts = segments(projectRelativePath);
+    let current = canonicalRoot;
+    await assertNoReparse(current);
+    for (const [index, segment] of parts.entries()) {
+        current = resolve(current, segment);
+        try {
+            await assertNoReparse(current);
+        }
+        catch (error) {
+            if (error.code === "ENOENT" && index === parts.length - 1)
+                break;
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+    assertInside(canonicalRoot, current);
+    return current;
+}
+/** 创建控制目录时逐段拒绝 reparse，并在每一次创建后 realpath 回读。 */
+export async function ensureSafeProjectDirectory(root, projectRelativePath) {
+    const canonicalRoot = await realpath(resolve(root));
+    let current = canonicalRoot;
+    await assertNoReparse(current);
+    for (const segment of segments(projectRelativePath)) {
+        current = resolve(current, segment);
+        try {
+            await assertNoReparse(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await mkdir(current);
+            await assertNoReparse(current);
+        }
+        const canonical = await realpath(current);
+        assertInside(canonicalRoot, canonical);
+    }
+    return current;
+}
+/** rename 前必须重新验证目标父目录，抵御检查与替换之间的链接交换。 */
+export async function assertSafeProjectParent(root, path) {
+    const parent = resolve(path, "..");
+    await assertSafeExistingProjectPath(root, parent);
+}

package/dist/scenario-writer.d.ts

@@ -0,0 +1,32 @@
+import { type AuthoringEffectIdentity, type AuthoringToolReceiptV1 } from "@world-engines/authoring-bridge";
+import { type ProjectWriterLeaseOwner } from "./project-writer-lease.js";
+export interface ScenarioSourceReadback {
+    readonly project_id: string;
+    readonly project_revision: number;
+    readonly source_sha256: string;
+    readonly source: Uint8Array;
+}
+export interface ScenarioWriteRequest extends AuthoringEffectIdentity {
+    /** 新 source.wes 的 WESP bytes；调用者不能提供未经校验的 projection。 */
+    readonly source: Uint8Array;
+    /** 可选的 source CAS，防止 GUI/CLI/MCP 从同一 revision 覆盖对方。 */
+    readonly expected_source_sha256?: string;
+}
+export interface ScenarioProjectionHydrator {
+    hydrate(readback: ScenarioSourceReadback): Promise<void> | void;
+}
+export type ScenarioWriteStage = "before_temp" | "after_temp" | "after_fsync" | "after_rename" | "after_manifest";
+/** 仅用于确定性崩溃恢复测试；生产调用不传入。 */
+export interface ScenarioWriterFaultInjector {
+    at(stage: ScenarioWriteStage): Promise<void> | void;
+}
+export declare function withProjectWriterLease<T>(root: string, operation: () => Promise<T>, owner?: ProjectWriterLeaseOwner): Promise<T>;
+export declare class ScenarioWriter {
+    #private;
+    private readonly root;
+    private readonly hydrateProjection;
+    private readonly faultInjector;
+    constructor(root: string, hydrateProjection: ScenarioProjectionHydrator | undefined, faultInjector: ScenarioWriterFaultInjector | undefined);
+    readSourceReadback(): Promise<ScenarioSourceReadback>;
+    write(request: ScenarioWriteRequest): Promise<AuthoringToolReceiptV1>;
+}

package/dist/scenario-writer.js

@@ -0,0 +1,191 @@
+import { open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { AuthoringBridgeError, validateAuthoringEffectIdentity, } from "@world-engines/authoring-bridge";
+import { computeCanonicalProjectDigest, decodeScenarioPartWesp, sha256Hex, validateLocalAuthorProjectManifest, } from "@world-engines/project-format";
+import { assertSafeExistingProjectPath, assertSafeProjectParent, ensureSafeProjectDirectory, safeProjectPath, } from "./safe-project-path.js";
+import { acquireProjectWriterLease } from "./project-writer-lease.js";
+export async function withProjectWriterLease(root, operation, owner = {}) {
+    const lease = await acquireProjectWriterLease(root, owner);
+    try {
+        return await operation();
+    }
+    finally {
+        await lease.release();
+    }
+}
+async function readManifest(root) {
+    const path = await safeProjectPath(root, "worldengine.project.json");
+    return validateLocalAuthorProjectManifest(JSON.parse(await readFile(await assertSafeExistingProjectPath(root, path), "utf8")));
+}
+async function atomicWriteJson(root, path, value) {
+    const staging = await ensureSafeProjectDirectory(root, ".worldengine/staging");
+    const bytes = new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`);
+    const temp = join(staging, `manifest-${await sha256Hex(bytes)}.tmp`);
+    await rm(temp, { force: true });
+    await assertSafeProjectParent(root, temp);
+    const handle = await open(temp, "wx");
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await assertSafeProjectParent(root, path);
+    await rename(temp, path);
+    await assertSafeExistingProjectPath(root, path);
+}
+function equalManifest(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export class ScenarioWriter {
+    root;
+    hydrateProjection;
+    faultInjector;
+    constructor(root, hydrateProjection, faultInjector) {
+        this.root = root;
+        this.hydrateProjection = hydrateProjection;
+        this.faultInjector = faultInjector;
+    }
+    async readSourceReadback() {
+        const manifest = await readManifest(this.root);
+        const sourcePath = await safeProjectPath(this.root, manifest.scenario.source_path);
+        const source = new Uint8Array(await readFile(await assertSafeExistingProjectPath(this.root, sourcePath)));
+        await decodeScenarioPartWesp(source);
+        const sourceSha256 = await sha256Hex(source);
+        if (sourceSha256 !== manifest.scenario.source_sha256) {
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "Scenario source 与 manifest digest 不一致");
+        }
+        return { project_id: manifest.project_id, project_revision: manifest.project_revision, source_sha256: sourceSha256, source };
+    }
+    async write(request) {
+        validateAuthoringEffectIdentity(request);
+        if (!(request.source instanceof Uint8Array)) {
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "scenario source 必须是 Uint8Array");
+        }
+        await decodeScenarioPartWesp(request.source);
+        const sourceSha256 = await sha256Hex(request.source);
+        const requestDigest = await sha256Hex(new TextEncoder().encode(JSON.stringify({
+            operation_id: request.operation_id,
+            expected_project_revision: request.expected_project_revision,
+            expected_source_sha256: request.expected_source_sha256,
+            source_sha256: sourceSha256,
+        })));
+        return withProjectWriterLease(this.root, async () => {
+            await ensureSafeProjectDirectory(this.root, ".worldengine/operations");
+            const ledgerPath = await safeProjectPath(this.root, `.worldengine/operations/scenario-${await sha256Hex(new TextEncoder().encode(request.operation_id))}.json`);
+            let ledger;
+            try {
+                ledger = JSON.parse(await readFile(await assertSafeExistingProjectPath(this.root, ledgerPath), "utf8"));
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            if (ledger !== undefined) {
+                if (ledger.request_digest !== requestDigest) {
+                    throw new AuthoringBridgeError("E_OPERATION_ID_CONFLICT", "同一 scenario operation_id 使用了不同请求");
+                }
+                return this.#recover(ledgerPath, ledger);
+            }
+            const current = await this.readSourceReadback();
+            if (current.project_revision !== request.expected_project_revision) {
+                throw new AuthoringBridgeError("E_STALE_PROJECT_REVISION", `期望 revision ${request.expected_project_revision}，当前 ${current.project_revision}`);
+            }
+            if (request.expected_source_sha256 !== undefined && request.expected_source_sha256 !== current.source_sha256) {
+                throw new AuthoringBridgeError("E_STALE_PROJECT_REVISION", "Scenario source CAS 不匹配");
+            }
+            const preimage = await readManifest(this.root);
+            const changed = current.source_sha256 !== sourceSha256;
+            const next = changed ? {
+                ...preimage,
+                project_revision: preimage.project_revision + 1,
+                updated_at_ms: Date.now(),
+                scenario: { ...preimage.scenario, source_sha256: sourceSha256 },
+                snapshot: { snapshot_id: "snapshot_pending", canonical_digest: "0".repeat(64), previous_snapshot_id: preimage.snapshot.snapshot_id },
+            } : preimage;
+            if (changed) {
+                next.snapshot.canonical_digest = await computeCanonicalProjectDigest(next);
+                next.snapshot.snapshot_id = `snapshot_${next.snapshot.canonical_digest.slice(0, 24)}`;
+            }
+            const receipt = {
+                schema_version: 1,
+                operation_id: request.operation_id,
+                project_id: next.project_id,
+                previous_project_revision: preimage.project_revision,
+                next_project_revision: next.project_revision,
+                changed_sections: changed ? ["scenario"] : [],
+                project_snapshot_digest: next.snapshot.canonical_digest,
+                readback_verified: true,
+            };
+            ledger = { schema_version: 1, request_digest: requestDigest, source_base64: Buffer.from(request.source).toString("base64"), source_sha256: sourceSha256, state: "prepared", preimage, next_manifest: next, receipt };
+            await writeFile(ledgerPath, `${JSON.stringify(ledger, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+            return this.#recover(ledgerPath, ledger);
+        }, { entrypoint: "scenario", operation_id: request.operation_id });
+    }
+    async #recover(ledgerPath, ledger) {
+        const manifest = await readManifest(this.root);
+        if (!equalManifest(manifest, ledger.preimage) && !equalManifest(manifest, ledger.next_manifest)) {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "scenario ledger 与当前 manifest 不一致");
+        }
+        const source = new Uint8Array(Buffer.from(ledger.source_base64, "base64"));
+        await decodeScenarioPartWesp(source);
+        if (await sha256Hex(source) !== ledger.source_sha256) {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "scenario ledger source digest 不一致");
+        }
+        const sourcePath = await safeProjectPath(this.root, "scenario/source.wes");
+        const tempPath = await safeProjectPath(this.root, "scenario/source.wes.tmp");
+        let currentBytes;
+        try {
+            currentBytes = new Uint8Array(await readFile(await assertSafeExistingProjectPath(this.root, sourcePath)));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (currentBytes === undefined || await sha256Hex(currentBytes) !== ledger.source_sha256) {
+            await this.faultInjector?.at("before_temp");
+            await rm(tempPath, { force: true });
+            await assertSafeProjectParent(this.root, tempPath);
+            const temp = await open(tempPath, "wx");
+            try {
+                await temp.writeFile(source);
+                await this.faultInjector?.at("after_temp");
+                await temp.sync();
+                await this.faultInjector?.at("after_fsync");
+            }
+            finally {
+                await temp.close();
+            }
+            await assertSafeProjectParent(this.root, sourcePath);
+            await rename(tempPath, sourcePath);
+            await this.faultInjector?.at("after_rename");
+            ledger = { ...ledger, state: "source_renamed" };
+            await atomicWriteJson(this.root, ledgerPath, ledger);
+        }
+        const afterSource = await this.readSourceReadback().catch(async (error) => {
+            // source 已替换、manifest 仍是 preimage 时的预期中间状态；只验证 WESP/digest，不能用它掩盖其他错误。
+            if (!equalManifest(await readManifest(this.root), ledger.preimage))
+                throw error;
+            const raw = new Uint8Array(await readFile(await assertSafeExistingProjectPath(this.root, sourcePath)));
+            await decodeScenarioPartWesp(raw);
+            return { project_id: ledger.next_manifest.project_id, project_revision: ledger.next_manifest.project_revision, source_sha256: await sha256Hex(raw), source: raw };
+        });
+        if (afterSource.source_sha256 !== ledger.source_sha256)
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "source rename readback 不一致");
+        if (!equalManifest(await readManifest(this.root), ledger.next_manifest)) {
+            await atomicWriteJson(this.root, join(this.root, "worldengine.project.json"), ledger.next_manifest);
+            await this.faultInjector?.at("after_manifest");
+            ledger = { ...ledger, state: "manifest_written" };
+            await atomicWriteJson(this.root, ledgerPath, ledger);
+        }
+        const readback = await this.readSourceReadback();
+        if (readback.project_revision !== ledger.next_manifest.project_revision || readback.source_sha256 !== ledger.source_sha256) {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "source/manifest readback 不一致");
+        }
+        await this.hydrateProjection?.hydrate(readback);
+        ledger = { ...ledger, state: "completed" };
+        await atomicWriteJson(this.root, ledgerPath, ledger);
+        return ledger.receipt;
+    }
+}

package/dist/transfer/download.d.ts

@@ -0,0 +1,159 @@
+import type { ProjectTransferTransport } from "./transport.js";
+export type DownloadReplaceSelection = "scenario" | "view" | "both";
+export interface DownloadReplaceFile {
+    readonly path: string;
+    readonly content_base64: string;
+    readonly sha256: string;
+}
+/** T015 的远端 wire 冻结前，GUI/CLI 只能消费这个本地已冻结的计划。 */
+export interface DownloadReplacePlan {
+    readonly schema_version: 1;
+    readonly operation_id: string;
+    readonly plan_digest: string;
+    readonly expected_project_revision: number;
+    readonly selection: DownloadReplaceSelection;
+    readonly scenario?: {
+        readonly source_base64: string;
+        readonly sha256: string;
+    };
+    readonly view?: {
+        readonly files: readonly DownloadReplaceFile[];
+        readonly install_dependencies: boolean;
+    };
+    /**
+     * 原生 Git 等“本地 checkout 必须精确 CAS”调用方可选择开启。
+     * 旧 download 保持确认后覆盖、以最新 preimage 恢复的既有语义。
+     */
+    readonly strict_source_cas?: Readonly<{
+        readonly schema_version: 1;
+        readonly expected_source_sha256: string;
+        readonly expected_view_source_tree_sha256: string;
+    }>;
+}
+export interface DownloadReplaceConfirmation {
+    readonly operation_id: string;
+    readonly plan_digest: string;
+}
+/**
+ * 确认前由 ProjectHost 本地生成的只读事实。renderer 可以展示它，但不能自报
+ * summary/diff；apply 会在 writer lease 内重新读取同一组事实并保留最新 preimage。
+ */
+export interface DownloadLocalInspection {
+    readonly schema_version: 1;
+    readonly project_id: string;
+    readonly remote_plan_id: string;
+    readonly remote_plan_digest: string;
+    readonly expected_project_revision: number;
+    readonly parts: readonly ("scenario" | "view")[];
+    readonly object_digests: Readonly<Record<string, string>>;
+    readonly local_overwrite_summary: Readonly<{
+        scenario_file_count: string;
+        scenario_bytes: string;
+        view_file_count: string;
+        view_bytes: string;
+        current_snapshot_digest: string;
+    }>;
+    readonly dependency_diff: Readonly<{
+        added: readonly string[];
+        removed: readonly string[];
+        changed: readonly string[];
+        lockfile_changes: boolean;
+    }>;
+    readonly local_inspection_digest: string;
+}
+export interface DownloadReplaceReceipt {
+    readonly operation_id: string;
+    readonly previous_project_revision: number;
+    readonly next_project_revision: number;
+    readonly selection: DownloadReplaceSelection;
+    readonly readback_verified: true;
+    readonly restored: boolean;
+    readonly scenario_sha256: string;
+    readonly view_source_tree_sha256: string;
+    readonly project_snapshot_digest: string;
+    readonly inspection_changed_since_confirmation?: boolean;
+    readonly local_inspection_digest?: string;
+    readonly local_overwrite_summary?: DownloadLocalInspection["local_overwrite_summary"];
+}
+export interface DownloadReplaceDependencies {
+    /** 仅在 staging/view 内执行；不得在 writer lease 内安装依赖。 */
+    readonly installViewDependencies?: (stagingViewRoot: string) => Promise<void>;
+    /** 写入后由实际投影 owner 读回；未注入时不能伪造远端/GUI 投影成功。 */
+    readonly readProjection?: (receipt: DownloadReplaceReceipt) => Promise<void>;
+    /** 仅用于 crash-recovery 测试。 */
+    readonly fault?: (stage: "after_scenario_rename" | "after_view_rename") => Promise<void>;
+    readonly now?: () => number;
+}
+/**
+ * 认证 broker 的受控 HTTP 出口。调用者只能交给它已经摘要过的请求体；实现不得把
+ * cookie、token 或 WebView profile 返回给 CLI。
+ */
+export type { ProjectTransferTransport } from "./transport.js";
+export interface RemoteDownloadObject {
+    readonly key: string;
+    readonly sha256: string;
+    readonly byteLength: number;
+    readonly mediaType: string;
+}
+export interface RemoteDownloadPlan {
+    readonly planId: string;
+    readonly planDigest: string;
+    readonly expiresAtMs: number;
+    readonly frozenRemote: Readonly<{
+        scenarioId: string;
+        scenarioHead: string;
+        viewId: string;
+        viewDigest: string;
+        bindingRevision: number;
+    }>;
+    readonly parts: readonly ("scenario" | "view")[];
+    readonly scenarioObject?: RemoteDownloadObject;
+    readonly viewObject?: RemoteDownloadObject;
+}
+export interface RemoteDownloadOperation {
+    readonly operationId: string;
+    readonly planId: string;
+    readonly planDigest: string;
+    readonly state: string;
+}
+export interface DownloadRemoteRequest {
+    readonly project_id: string;
+    readonly target_pair_id: string;
+    readonly parts: readonly ("scenario" | "view")[];
+}
+/** Windows checkout 与 strict Git source CAS 共用的大小写无关过滤定义。 */
+export declare function isProjectGitViewExcludedName(name: string): boolean;
+export declare function parseRemoteDownloadPlan(value: unknown, now?: number): RemoteDownloadPlan;
+export declare function parseRemoteDownloadOperation(value: unknown, expected?: Readonly<{
+    operationId?: string;
+    planId: string;
+    planDigest: string;
+}>): RemoteDownloadOperation;
+export declare class DownloadReplaceCoordinator {
+    #private;
+    readonly root: string;
+    private constructor();
+    static open(root: string, dependencies?: DownloadReplaceDependencies): Promise<DownloadReplaceCoordinator>;
+    /** 深模块 seam：调用方只提交冻结内容，所有本地树、依赖与 digest 由 host 自己读取。 */
+    inspect(plan: DownloadReplacePlan, remotePlanId?: string): Promise<DownloadLocalInspection>;
+    prepare(plan: DownloadReplacePlan): Promise<void>;
+    apply(plan: DownloadReplacePlan, confirmation: DownloadReplaceConfirmation | undefined, inspection?: DownloadLocalInspection): Promise<DownloadReplaceReceipt>;
+    restore(operationId: string): Promise<void>;
+    setHistoryPinned(operationId: string, pinned: boolean): Promise<void>;
+    pruneHistory(now?: number): Promise<void>;
+}
+/**
+ * 将稳定远端路由收敛成可重放的单 target 下载：先由远端冻结对象，再在本地验证
+ * staging 内容；本地失败不会新建 operation，而是让同一 operation 走 reconcile。
+ */
+export declare class RemoteDownloadCoordinator {
+    #private;
+    private constructor();
+    static open(root: string, projectId: string, transport: ProjectTransferTransport | undefined, dependencies?: DownloadReplaceDependencies): Promise<RemoteDownloadCoordinator>;
+    plan(request: DownloadRemoteRequest): Promise<RemoteDownloadPlan>;
+    confirm(plan: RemoteDownloadPlan, confirmPlanDigest: string): Promise<RemoteDownloadOperation>;
+    operation(operationId: string, reconcile?: boolean): Promise<RemoteDownloadOperation>;
+    apply(plan: RemoteDownloadPlan, operation: RemoteDownloadOperation): Promise<DownloadReplaceReceipt>;
+    restore(operationId: string): Promise<void>;
+}
+export declare function decodeRemoteViewBundle(bytes: Uint8Array): NonNullable<DownloadReplacePlan["view"]>;