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

package/dist/initialize.js

@@ -0,0 +1,776 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { npmChildEnvironment } from "./npm-environment.js";
+import { copyFile, cp, link, lstat, mkdir, readFile, readlink, readdir, realpath, rename, rm, stat, symlink, writeFile, } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { computeCanonicalProjectDigest, computeCanonicalFileTreeDigest, createEmptyScenarioPartWesp, sha256Hex, LOCAL_AUTHOR_GALLERY_PATHS, } from "@world-engines/project-format";
+import { AGENT_KIT_ROOT_LINKS, materializeAgentKit } from "@world-engines/agent-kit";
+import { ProjectInitializationError } from "./errors.js";
+import { PROJECT_TEMPLATE_FILES } from "./template.js";
+const TOOLCHAIN_VERSION = "0.1.0-alpha.0";
+const EMPTY_DIGEST = "0".repeat(64);
+const TOOLCHAIN_MANIFEST_FILE = "toolchain-manifest.json";
+const PROJECT_DIRECTORIES = [
+    LOCAL_AUTHOR_GALLERY_PATHS.scenario,
+    LOCAL_AUTHOR_GALLERY_PATHS.view,
+    ".agents",
+    ".codex",
+    ".claude",
+    ".worldengine/lock",
+    ".worldengine/auth",
+    ".worldengine/webview",
+    ".worldengine/projections/ladybug",
+    ".worldengine/projections/trigger",
+    ".worldengine/projections/spatial",
+    ".worldengine/snapshots",
+    ".worldengine/history",
+    ".worldengine/staging",
+    ".worldengine/operations",
+    ".worldengine/cache",
+    ".worldengine/logs",
+    ".worldengine/tmp",
+    ".worldengine/bin",
+    "docs/authoring",
+];
+function generatedId(prefix) {
+    return `${prefix}_${randomUUID().replaceAll("-", "")}`;
+}
+function initializationIds(input) {
+    return input.ids ?? {
+        project_id: generatedId("project"),
+        local_scenario_id: generatedId("scenario"),
+        local_view_id: generatedId("view"),
+        snapshot_id: generatedId("snapshot"),
+        operation_id: generatedId("operation"),
+    };
+}
+async function inspectBootstrapFile(target, bootstrapFile) {
+    const path = resolve(bootstrapFile);
+    if (dirname(path).toLocaleLowerCase("en-US") !== target.toLocaleLowerCase("en-US")) {
+        throw new ProjectInitializationError("E_TARGET_INVALID", "启动 CMD 必须是初始化目标的直接子文件");
+    }
+    const info = await lstat(path).catch(() => {
+        throw new ProjectInitializationError("E_TARGET_INVALID", "声明的启动 CMD 不存在");
+    });
+    if (!info.isFile() || info.isSymbolicLink()) {
+        throw new ProjectInitializationError("E_TARGET_INVALID", "启动 CMD 必须是非链接普通文件");
+    }
+    return {
+        path,
+        name: basename(path),
+        sha256: await sha256Hex(new Uint8Array(await readFile(path))),
+    };
+}
+async function inspectTarget(target, bootstrapFile) {
+    try {
+        const targetStat = await stat(target);
+        if (!targetStat.isDirectory()) {
+            throw new ProjectInitializationError("E_TARGET_INVALID", "初始化目标必须是目录");
+        }
+        const entries = await readdir(target);
+        if (entries.length > 0) {
+            if (bootstrapFile !== undefined && entries.length === 1) {
+                const file = await inspectBootstrapFile(target, bootstrapFile);
+                if (entries[0]?.toLocaleLowerCase("en-US") === file.name.toLocaleLowerCase("en-US")) {
+                    return { kind: "bootstrap", file };
+                }
+            }
+            throw new ProjectInitializationError("E_TARGET_NOT_EMPTY", "初始化目标目录非空");
+        }
+        if (bootstrapFile !== undefined) {
+            throw new ProjectInitializationError("E_TARGET_INVALID", "声明的启动 CMD 不在初始化目标中");
+        }
+        return { kind: "empty" };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            if (bootstrapFile !== undefined) {
+                throw new ProjectInitializationError("E_TARGET_INVALID", "声明的启动 CMD 不存在");
+            }
+            return { kind: "missing" };
+        }
+        throw error;
+    }
+}
+async function writeTemplate(root) {
+    for (const directory of PROJECT_DIRECTORIES) {
+        await mkdir(join(root, directory), { recursive: true });
+    }
+    for (const file of PROJECT_TEMPLATE_FILES) {
+        const output = join(root, ...file.path.split("/"));
+        await mkdir(dirname(output), { recursive: true });
+        await writeFile(output, file.content, { encoding: "utf8", flag: "wx" });
+    }
+    const agentKit = await materializeAgentKit();
+    const manifestFile = agentKit.find(({ path }) => path === "manifest.json");
+    if (manifestFile === undefined) {
+        throw new ProjectInitializationError("E_INITIALIZATION_VERIFY_FAILED", "AgentKit 缺少 manifest.json");
+    }
+    const manifest = JSON.parse(manifestFile.content);
+    const internalSkillNames = new Set(manifest.skills
+        .filter(({ source }) => source === "worldengine-chat-internal")
+        .map(({ name }) => name));
+    const authorManifest = {
+        ...manifest,
+        skills: manifest.skills.filter(({ source }) => source !== "worldengine-chat-internal"),
+    };
+    for (const file of agentKit) {
+        if (file.path !== "manifest.json" &&
+            [...internalSkillNames].some((name) => file.path.startsWith(`skills-disabled/${name}/`)))
+            continue;
+        const output = join(root, "docs", "authoring", ...file.path.split("/"));
+        await mkdir(dirname(output), { recursive: true });
+        const content = file.path === "manifest.json"
+            ? `${JSON.stringify(authorManifest, null, 2)}\n`
+            : file.content;
+        await writeFile(output, content, { encoding: "utf8", flag: "wx" });
+    }
+}
+async function materializePortableRuntime(staging, sourceDirectory) {
+    const source = resolve(sourceDirectory);
+    const sourceInfo = await lstat(source).catch(() => {
+        throw new ProjectInitializationError("E_TARGET_INVALID", "便携 Node runtime 不存在");
+    });
+    if (!sourceInfo.isDirectory() || sourceInfo.isSymbolicLink()) {
+        throw new ProjectInitializationError("E_TARGET_INVALID", "便携 Node runtime 必须是非链接目录");
+    }
+    const node = join(source, "node.exe");
+    const npmCli = join(source, "node_modules", "npm", "bin", "npm-cli.js");
+    for (const [path, label] of [[node, "node.exe"], [npmCli, "npm CLI"]]) {
+        const info = await lstat(path).catch(() => {
+            throw new ProjectInitializationError("E_TARGET_INVALID", `便携 Node runtime 缺少 ${label}`);
+        });
+        if (!info.isFile() || info.isSymbolicLink()) {
+            throw new ProjectInitializationError("E_TARGET_INVALID", `便携 Node runtime ${label} 必须是普通文件`);
+        }
+    }
+    const destination = join(staging, ".worldengine", "runtime", "node");
+    await mkdir(destination, { recursive: true });
+    await cp(source, destination, { recursive: true, force: false, verbatimSymlinks: true });
+}
+function tarOctal(bytes) {
+    const text = new TextDecoder().decode(bytes).replaceAll("\0", "").trim();
+    return text.length === 0 ? 0 : Number.parseInt(text, 8);
+}
+function tarString(bytes) {
+    return new TextDecoder().decode(bytes).replace(/\0.*$/s, "");
+}
+function readPackedPackageManifest(archive) {
+    const tar = gunzipSync(archive);
+    for (let offset = 0; offset + 512 <= tar.length;) {
+        const header = tar.subarray(offset, offset + 512);
+        const name = tarString(header.subarray(0, 100));
+        const prefix = tarString(header.subarray(345, 500));
+        const path = prefix.length === 0 ? name : `${prefix}/${name}`;
+        const size = tarOctal(header.subarray(124, 136));
+        const contentStart = offset + 512;
+        if (path === "package/package.json") {
+            const parsed = JSON.parse(new TextDecoder().decode(tar.subarray(contentStart, contentStart + size)));
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                throw new Error("package.json 不是对象");
+            }
+            return parsed;
+        }
+        offset = contentStart + Math.ceil(size / 512) * 512;
+    }
+    throw new Error("tarball 缺少 package/package.json");
+}
+function packageDependencies(manifest) {
+    const dependencies = new Set();
+    for (const field of ["dependencies", "optionalDependencies", "peerDependencies"]) {
+        const block = manifest[field];
+        if (block === undefined)
+            continue;
+        if (typeof block !== "object" || block === null || Array.isArray(block)) {
+            throw new Error(`${field} 不是对象`);
+        }
+        for (const name of Object.keys(block))
+            dependencies.add(name);
+    }
+    return [...dependencies].sort((left, right) => left.localeCompare(right, "en"));
+}
+function packageArchiveName(name, sha256) {
+    return `${name.replace(/^@/, "").replaceAll("/", "-")}-sha256-${sha256}.tgz`;
+}
+async function verifyPackageSource(source) {
+    const directory = resolve(source.tarball_directory);
+    if (!/^[a-f0-9]{64}$/.test(source.tarball_directory_sha256)) {
+        throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", "tarball 目录 SHA-256 格式无效");
+    }
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", `无法读取 tarball 目录：${message}`);
+    }
+    if (entries.some((entry) => !entry.isFile() || (extname(entry.name) !== ".tgz" && entry.name !== TOOLCHAIN_MANIFEST_FILE))) {
+        throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", "tarball 目录只能包含 .tgz 常规文件与 ToolchainManifest");
+    }
+    const tarballs = entries.filter((entry) => extname(entry.name) === ".tgz");
+    const files = await Promise.all(tarballs.map(async (entry) => ({
+        path: entry.name,
+        bytes: new Uint8Array(await readFile(join(directory, entry.name))),
+    })));
+    const digest = await computeCanonicalFileTreeDigest(files);
+    if (digest !== source.tarball_directory_sha256) {
+        throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", "tarball 目录 SHA-256 不匹配");
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(join(directory, TOOLCHAIN_MANIFEST_FILE), "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", `ToolchainManifest 无法读取：${message}`);
+    }
+    if (manifest.schema_version !== 1 ||
+        manifest.tarball_count !== tarballs.length ||
+        !Array.isArray(manifest.packages) ||
+        manifest.packages.length === 0) {
+        throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", "ToolchainManifest schema 或 tarball_count 无效");
+    }
+    const tarballNames = new Set(tarballs.map(({ name }) => name));
+    const fileNameByPackage = new Map();
+    const versionByPackage = new Map();
+    const dependenciesByPackage = new Map();
+    for (const rawPackage of manifest.packages) {
+        const item = rawPackage;
+        if (typeof item.name !== "string" ||
+            !/^@(?:chat|world-engines|worldengine)\/[a-z0-9-]+$/.test(item.name) ||
+            typeof item.version !== "string" ||
+            item.version.length === 0 ||
+            typeof item.archive !== "string" ||
+            typeof item.sha256 !== "string" ||
+            !/^[a-f0-9]{64}$/.test(item.sha256) ||
+            item.archive !== packageArchiveName(item.name, item.sha256) ||
+            !tarballNames.has(item.archive) ||
+            fileNameByPackage.has(item.name)) {
+            throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", "ToolchainManifest package identity 无效或重复");
+        }
+        const bytes = new Uint8Array(await readFile(join(directory, item.archive)));
+        if (await sha256Hex(bytes) !== item.sha256) {
+            throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", `${item.name} tarball 内容 SHA-256 不匹配`);
+        }
+        let packed;
+        try {
+            packed = readPackedPackageManifest(bytes);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", `${item.name} tarball 无效：${message}`);
+        }
+        if (packed.name !== item.name || packed.version !== item.version || packed.private === true) {
+            throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", `${item.name} tarball package identity 不匹配`);
+        }
+        fileNameByPackage.set(item.name, item.archive);
+        versionByPackage.set(item.name, item.version);
+        try {
+            dependenciesByPackage.set(item.name, packageDependencies(packed));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", `${item.name} dependencies 无效：${message}`);
+        }
+    }
+    for (const [name, dependencies] of dependenciesByPackage) {
+        for (const dependency of dependencies) {
+            if (/^@(?:chat|world-engines|worldengine)\//.test(dependency) && !fileNameByPackage.has(dependency)) {
+                throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", `ToolchainManifest 缺少 ${name} 的 first-party 依赖 ${dependency}`);
+            }
+        }
+    }
+    return {
+        fileNameByPackage,
+        versionByPackage,
+        dependenciesByPackage,
+        tarballFileNames: [...tarballNames].sort((left, right) => left.localeCompare(right, "en")),
+    };
+}
+function packageClosure(directDependencies, verified) {
+    const closure = new Set();
+    const pending = directDependencies.filter((name) => verified.fileNameByPackage.has(name));
+    while (pending.length > 0) {
+        const name = pending.pop();
+        if (name === undefined || closure.has(name))
+            continue;
+        closure.add(name);
+        for (const dependency of verified.dependenciesByPackage.get(name) ?? []) {
+            if (verified.fileNameByPackage.has(dependency) && !closure.has(dependency))
+                pending.push(dependency);
+        }
+    }
+    return [...closure].sort((left, right) => left.localeCompare(right, "en"));
+}
+async function materializePackageSource(root, source) {
+    const verified = await verifyPackageSource(source);
+    const outputDirectory = join(root, ".worldengine", "package-source");
+    await mkdir(outputDirectory, { recursive: true });
+    for (const fileName of verified.tarballFileNames) {
+        await copyFile(join(resolve(source.tarball_directory), fileName), join(outputDirectory, fileName));
+    }
+    await copyFile(join(resolve(source.tarball_directory), TOOLCHAIN_MANIFEST_FILE), join(outputDirectory, TOOLCHAIN_MANIFEST_FILE));
+    const rootPackagePath = join(root, "package.json");
+    const rootPackage = JSON.parse(await readFile(rootPackagePath, "utf8"));
+    const rootDependencyBlocks = [rootPackage.dependencies, rootPackage.optionalDependencies ?? {}];
+    for (const block of rootDependencyBlocks) {
+        for (const name of Object.keys(block)) {
+            if (!/^@(?:chat|world-engines|worldengine)\//.test(name))
+                continue;
+            const fileName = verified.fileNameByPackage.get(name);
+            if (fileName === undefined) {
+                throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", `ToolchainManifest 缺少 root 依赖 ${name}`);
+            }
+            block[name] = `file:.worldengine/package-source/${fileName}`;
+        }
+    }
+    await writeFile(rootPackagePath, `${JSON.stringify(rootPackage, null, 2)}\n`, "utf8");
+    const viewPackagePath = join(root, "view", "package.json");
+    const viewPackage = JSON.parse(await readFile(viewPackagePath, "utf8"));
+    for (const name of Object.keys(viewPackage.dependencies)) {
+        if (!/^@(?:chat|world-engines|worldengine)\//.test(name))
+            continue;
+        const fileName = verified.fileNameByPackage.get(name);
+        if (fileName === undefined) {
+            throw new ProjectInitializationError("E_PACKAGE_SOURCE_INVALID", `ToolchainManifest 缺少 view 依赖 ${name}`);
+        }
+        viewPackage.dependencies[name] = `file:../.worldengine/package-source/${fileName}`;
+    }
+    await writeFile(viewPackagePath, `${JSON.stringify(viewPackage, null, 2)}\n`, "utf8");
+    return {
+        rootArchives: packageClosure(rootDependencyBlocks.flatMap((block) => Object.keys(block)), verified).map((name) => join(outputDirectory, verified.fileNameByPackage.get(name))),
+        viewArchives: packageClosure(Object.keys(viewPackage.dependencies), verified).map((name) => join(outputDirectory, verified.fileNameByPackage.get(name))),
+    };
+}
+async function assertLinkTargetMissing(output, displayPath) {
+    try {
+        await lstat(output);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    throw new ProjectInitializationError("E_INITIALIZATION_VERIFY_FAILED", `拒绝覆盖未知 AgentKit 入口：${displayPath}`);
+}
+async function createAgentSkillJunctions(root, previousRoot) {
+    for (const rootLink of AGENT_KIT_ROOT_LINKS.filter(({ kind }) => kind === "junction")) {
+        const output = join(root, ...rootLink.path.split("/"));
+        const target = join(root, ...rootLink.target.split("/"));
+        if (previousRoot === undefined) {
+            await assertLinkTargetMissing(output, rootLink.path);
+        }
+        else {
+            const entry = await lstat(output);
+            const previousTarget = resolve(previousRoot, ...rootLink.target.split("/"));
+            const actualTarget = resolve(dirname(output), await readlink(output));
+            if (!entry.isSymbolicLink() || actualTarget !== previousTarget) {
+                throw new ProjectInitializationError("E_INITIALIZATION_VERIFY_FAILED", `拒绝重定向未知 AgentKit 入口：${rootLink.path}`);
+            }
+            await rm(output, { recursive: true, force: false });
+        }
+        await symlink(target, output, "junction");
+    }
+}
+async function verifyAgentKitLinks(root) {
+    for (const rootLink of AGENT_KIT_ROOT_LINKS.filter(({ kind }) => kind === "hardlink")) {
+        const output = join(root, ...rootLink.path.split("/"));
+        const target = join(root, ...rootLink.target.split("/"));
+        if ((await stat(output)).ino !== (await stat(target)).ino) {
+            throw new ProjectInitializationError("E_INITIALIZATION_VERIFY_FAILED", `${rootLink.path} 未链接至 AgentKit 单真相源`);
+        }
+    }
+    for (const rootLink of AGENT_KIT_ROOT_LINKS.filter(({ kind }) => kind === "junction")) {
+        const output = join(root, ...rootLink.path.split("/"));
+        const target = await realpath(join(root, ...rootLink.target.split("/")));
+        if (!(await lstat(output)).isSymbolicLink() || (await realpath(output)) !== target) {
+            throw new ProjectInitializationError("E_INITIALIZATION_VERIFY_FAILED", `${rootLink.path} 未链接至 AgentKit 单真相源`);
+        }
+    }
+}
+async function createAgentKitLinks(root) {
+    for (const rootLink of AGENT_KIT_ROOT_LINKS.filter(({ kind }) => kind === "hardlink")) {
+        const output = join(root, ...rootLink.path.split("/"));
+        await mkdir(dirname(output), { recursive: true });
+        await assertLinkTargetMissing(output, rootLink.path);
+        await link(join(root, ...rootLink.target.split("/")), output);
+    }
+    // Windows junction 会把 target 固化为绝对路径。先指向 staging 通过验证，promote 后再重建到最终根目录。
+    await createAgentSkillJunctions(root);
+    await verifyAgentKitLinks(root);
+}
+async function runCommand(command, args, cwd, errorCode) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        // 始终通过 node.exe + npm-cli.js（或明确的 node 可执行文件）和参数数组调用，
+        // 不经 shell，项目路径与 tarball 名称不会被解释成 shell 语法。
+        const child = spawn(command, [...args], {
+            cwd, stdio: "inherit", windowsHide: true, shell: false,
+            env: npmChildEnvironment(command === "npm" ? process.execPath : command),
+        });
+        child.once("error", (error) => rejectPromise(new ProjectInitializationError(errorCode, error.message)));
+        child.once("exit", (code) => {
+            if (code === 0)
+                resolvePromise();
+            else
+                rejectPromise(new ProjectInitializationError(errorCode, `${command} ${args.join(" ")} 退出码 ${String(code)}`));
+        });
+    });
+}
+async function resolveNpmInvocation(input) {
+    if (input.npm_executable !== undefined) {
+        if (input.npm_executable.toLowerCase().endsWith(".cmd")) {
+            const npmCli = join(dirname(resolve(input.npm_executable)), "node_modules", "npm", "bin", "npm-cli.js");
+            try {
+                await stat(npmCli);
+            }
+            catch {
+                throw new ProjectInitializationError("E_DEPENDENCY_INSTALL_FAILED", `无法从 npm.cmd 定位 npm CLI：${npmCli}`);
+            }
+            return { command: process.execPath, argumentsPrefix: [npmCli, ...(input.npm_arguments_prefix ?? [])] };
+        }
+        const executable = resolve(input.npm_executable);
+        if (!/^node(?:\.exe)?$/i.test(basename(executable))) {
+            throw new ProjectInitializationError("E_DEPENDENCY_INSTALL_FAILED", "npm_executable 必须是 node.exe 或 npm.cmd，避免通过任意命令执行安装");
+        }
+        return { command: executable, argumentsPrefix: input.npm_arguments_prefix ?? [] };
+    }
+    if (process.platform === "win32") {
+        const npmCli = join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js");
+        try {
+            await stat(npmCli);
+        }
+        catch {
+            throw new ProjectInitializationError("E_DEPENDENCY_INSTALL_FAILED", `Node 安装不含可执行 npm CLI：${npmCli}`);
+        }
+        return { command: process.execPath, argumentsPrefix: [npmCli] };
+    }
+    return { command: "npm", argumentsPrefix: [] };
+}
+async function requireInstalledNodeModules(root) {
+    try {
+        if (!(await stat(join(root, "node_modules"))).isDirectory()) {
+            throw new Error("node_modules 不是目录");
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ProjectInitializationError("E_DEPENDENCY_INSTALL_FAILED", `依赖安装未生成 node_modules：${message}`);
+    }
+}
+async function requireRegularInstalledFile(path, label) {
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink())
+            throw new Error("不是普通文件");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ProjectInitializationError("E_DEPENDENCY_INSTALL_FAILED", `${label} 无效：${message}`);
+    }
+}
+async function verifyInstalledProjectHostGui(root) {
+    const packageRoot = join(root, "node_modules", "@world-engines", "project-host");
+    const manifestPath = join(packageRoot, "package.json");
+    await requireRegularInstalledFile(manifestPath, "@world-engines/project-host manifest");
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new ProjectInitializationError("E_DEPENDENCY_INSTALL_FAILED", `@world-engines/project-host manifest 无法读取：${message}`);
+    }
+    if (manifest.name !== "@world-engines/project-host" ||
+        typeof manifest.bin !== "object" || manifest.bin === null || Array.isArray(manifest.bin) ||
+        manifest.bin.worldengine !== "dist/cli.js") {
+        throw new ProjectInitializationError("E_DEPENDENCY_INSTALL_FAILED", "@world-engines/project-host manifest identity/bin 不匹配");
+    }
+    await requireRegularInstalledFile(join(packageRoot, "dist", "cli.js"), "@world-engines/project-host CLI");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "index.html"), "@world-engines/project-host GUI HTML");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "app.js"), "@world-engines/project-host GUI JavaScript");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "local-preview-bridge.js"), "@world-engines/project-host GUI Preview Bridge");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "styles.css"), "@world-engines/project-host GUI CSS");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "WELogo-title.svg"), "@world-engines/project-host GUI Logo");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "workspace-status.css"), "@world-engines/project-host Workspace Status CSS");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "workspace-status.js"), "@world-engines/project-host Workspace Status JavaScript");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "world-map-globe.js"), "@world-engines/project-host World Map Globe JavaScript");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "world-map-worker.js"), "@world-engines/project-host World Map Worker JavaScript");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "world-map.css"), "@world-engines/project-host World Map CSS");
+    await requireRegularInstalledFile(join(packageRoot, "assets", "gui", "world-map.js"), "@world-engines/project-host World Map JavaScript");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "graph.js"), "@world-engines/project-host Graph GUI JavaScript");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "graph.css"), "@world-engines/project-host Graph GUI CSS");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "score.js"), "@world-engines/project-host Score GUI JavaScript");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "score.css"), "@world-engines/project-host Score GUI CSS");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "trigger.js"), "@world-engines/project-host Trigger GUI JavaScript");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "trigger.css"), "@world-engines/project-host Trigger GUI CSS");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "graph-layout-worker.js"), "@world-engines/project-host Graph Layout Worker");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "graph-layout.wasm"), "@world-engines/project-host Graph Layout WASM");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "plane-generator.js"), "@world-engines/project-host Plane Generator JavaScript");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "plane-generator_bg.wasm"), "@world-engines/project-host Plane Generator WASM");
+    await requireRegularInstalledFile(join(packageRoot, "dist", "gui", "plane-generation.js"), "@world-engines/project-host Plane Generation JavaScript");
+}
+async function listViewSourceFiles(root, directory = "view") {
+    const absolute = join(root, ...directory.split("/"));
+    const entries = await readdir(absolute, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (["node_modules", "dist", ".vite"].includes(entry.name))
+            continue;
+        const child = `${directory}/${entry.name}`;
+        if (entry.isDirectory())
+            files.push(...(await listViewSourceFiles(root, child)));
+        else if (entry.isFile())
+            files.push(child);
+    }
+    return files.sort((left, right) => left.localeCompare(right, "en"));
+}
+async function computeViewTreeDigest(root) {
+    return computeCanonicalFileTreeDigest(await Promise.all((await listViewSourceFiles(root)).map(async (path) => ({
+        path: path.slice("view/".length),
+        bytes: new Uint8Array(await readFile(join(root, ...path.split("/")))),
+    }))));
+}
+async function digestFileOrEmpty(path) {
+    try {
+        return sha256Hex(new Uint8Array(await readFile(path)));
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return sha256Hex(new Uint8Array(0));
+        }
+        throw error;
+    }
+}
+async function readSnapshotDigest(root) {
+    const manifest = JSON.parse(await readFile(join(root, "worldengine.project.json"), "utf8"));
+    const digest = manifest.snapshot?.canonical_digest;
+    if (typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest)) {
+        throw new ProjectInitializationError("E_INITIALIZATION_VERIFY_FAILED", "snapshot 后 manifest digest 无效");
+    }
+    return digest;
+}
+async function buildManifest(root, ids, nowMs) {
+    const scenarioBytes = new Uint8Array(await readFile(join(root, "scenario", "source.wes")));
+    const manifest = {
+        schema_version: 2,
+        project_id: ids.project_id,
+        project_revision: 0,
+        created_at_ms: nowMs,
+        updated_at_ms: nowMs,
+        scenario: {
+            local_scenario_id: ids.local_scenario_id,
+            source_path: "scenario/source.wes",
+            source_sha256: await sha256Hex(scenarioBytes),
+            assets_digest: await sha256Hex(new Uint8Array(0)),
+        },
+        view: {
+            local_view_id: ids.local_view_id,
+            root_path: "view",
+            source_tree_sha256: await computeViewTreeDigest(root),
+            package_lock_sha256: await digestFileOrEmpty(join(root, "view", "package-lock.json")),
+        },
+        gallery: {
+            root_path: LOCAL_AUTHOR_GALLERY_PATHS.root,
+            scenario_root_path: LOCAL_AUTHOR_GALLERY_PATHS.scenario,
+            view_root_path: LOCAL_AUTHOR_GALLERY_PATHS.view,
+            content_tree_sha256: await computeCanonicalFileTreeDigest([]),
+        },
+        snapshot: {
+            snapshot_id: ids.snapshot_id,
+            canonical_digest: EMPTY_DIGEST,
+            previous_snapshot_id: null,
+        },
+        toolchain: {
+            template_version: TOOLCHAIN_VERSION,
+            project_host_version: TOOLCHAIN_VERSION,
+            authoring_bridge_version: TOOLCHAIN_VERSION,
+            desktop_package_version: TOOLCHAIN_VERSION,
+            agent_kit_version: TOOLCHAIN_VERSION,
+        },
+    };
+    manifest.snapshot.canonical_digest = await computeCanonicalProjectDigest(manifest);
+    return manifest;
+}
+async function assertBootstrapUnchanged(target, file) {
+    const entries = await readdir(target);
+    if (entries.length !== 1 || entries[0]?.toLocaleLowerCase("en-US") !== file.name.toLocaleLowerCase("en-US")) {
+        throw new ProjectInitializationError("E_TARGET_NOT_EMPTY", "验证期间目标目录发生变化");
+    }
+    const current = await inspectBootstrapFile(target, file.path);
+    if (current.sha256 !== file.sha256) {
+        throw new ProjectInitializationError("E_TARGET_INVALID", "验证期间启动 CMD 内容发生变化");
+    }
+}
+async function promoteProjectRoot(staging, target, targetState, operationId) {
+    if (targetState.kind === "missing") {
+        await rename(staging, target);
+        return { kind: "renamed", backup: undefined };
+    }
+    if (targetState.kind === "bootstrap") {
+        await assertBootstrapUnchanged(target, targetState.file);
+        const movedEntries = [];
+        try {
+            for (const entry of await readdir(staging)) {
+                await rename(join(staging, entry), join(target, entry));
+                movedEntries.push(entry);
+            }
+            return { kind: "merged", movedEntries, staging };
+        }
+        catch (error) {
+            for (const entry of movedEntries.reverse()) {
+                await rename(join(target, entry), join(staging, entry));
+            }
+            throw error;
+        }
+    }
+    const backup = join(dirname(target), `.${basename(target)}.worldengine-preimage-${operationId}`);
+    await rename(target, backup);
+    try {
+        await rename(staging, target);
+    }
+    catch (error) {
+        await rename(backup, target);
+        throw error;
+    }
+    return { kind: "renamed", backup };
+}
+async function rollbackPromotion(target, promotion) {
+    if (promotion.kind === "merged") {
+        for (const entry of promotion.movedEntries) {
+            await rm(join(target, entry), { recursive: true, force: true });
+        }
+        await rm(promotion.staging, { recursive: true, force: true });
+        return;
+    }
+    await rm(target, { recursive: true, force: true });
+    if (promotion.backup !== undefined)
+        await rename(promotion.backup, target);
+}
+export async function initializeLocalAuthorProject(input) {
+    if (typeof input.target !== "string" || input.target.trim().length === 0) {
+        throw new ProjectInitializationError("E_TARGET_INVALID", "初始化目标不能为空");
+    }
+    const target = resolve(input.target);
+    const targetState = await inspectTarget(target, input.bootstrap_file);
+    const ids = initializationIds(input);
+    const nowMs = input.now_ms ?? Date.now();
+    const installDependencies = input.install_dependencies ?? true;
+    const verify = input.verify ?? installDependencies;
+    const npm = await resolveNpmInvocation(input);
+    const staging = join(dirname(target), `.${basename(target)}.worldengine-staging-${ids.operation_id}`);
+    let promotion;
+    let packageInstallationPlan;
+    await mkdir(staging, { recursive: false });
+    try {
+        await writeTemplate(staging);
+        if (input.portable_runtime_directory !== undefined) {
+            await materializePortableRuntime(staging, input.portable_runtime_directory);
+        }
+        if (input.fault_injection === "disk_write") {
+            const error = new Error("受控磁盘写入失败");
+            Object.assign(error, { code: "ENOSPC" });
+            throw error;
+        }
+        if (input.package_source !== undefined) {
+            packageInstallationPlan = await materializePackageSource(staging, input.package_source);
+        }
+        await writeFile(join(staging, "scenario", "source.wes"), await createEmptyScenarioPartWesp(), {
+            flag: "wx",
+        });
+        await createAgentKitLinks(staging);
+        if (installDependencies) {
+            await runCommand(npm.command, [
+                ...npm.argumentsPrefix,
+                "install",
+                "--workspaces=false",
+                ...(packageInstallationPlan === undefined ? [] : ["--no-save", ...packageInstallationPlan.rootArchives]),
+            ], staging, "E_DEPENDENCY_INSTALL_FAILED");
+            await requireInstalledNodeModules(staging);
+            await verifyInstalledProjectHostGui(staging);
+            if (packageInstallationPlan !== undefined) {
+                // --no-save 保留根 manifest 的四个公开入口；安装后的 lock-only 读取同一闭包，
+                // 将实际解析版本固定为可复现且可 npm audit 的 root package-lock。
+                await runCommand(npm.command, [
+                    ...npm.argumentsPrefix,
+                    "install",
+                    "--workspaces=false",
+                    "--package-lock-only",
+                    "--ignore-scripts",
+                ], staging, "E_DEPENDENCY_INSTALL_FAILED");
+                await requireRegularInstalledFile(join(staging, "package-lock.json"), "root package-lock");
+            }
+            await runCommand(npm.command, [
+                ...npm.argumentsPrefix,
+                "install",
+                "--workspaces=false",
+                "--prefix",
+                "view",
+                ...(packageInstallationPlan === undefined ? [] : ["--no-save", ...packageInstallationPlan.viewArchives]),
+            ], staging, "E_DEPENDENCY_INSTALL_FAILED");
+            await requireInstalledNodeModules(join(staging, "view"));
+            if (packageInstallationPlan !== undefined) {
+                await runCommand(npm.command, [
+                    ...npm.argumentsPrefix,
+                    "install",
+                    "--workspaces=false",
+                    "--prefix",
+                    "view",
+                    "--package-lock-only",
+                    "--ignore-scripts",
+                ], staging, "E_DEPENDENCY_INSTALL_FAILED");
+                await requireRegularInstalledFile(join(staging, "view", "package-lock.json"), "view package-lock");
+            }
+        }
+        const manifest = await buildManifest(staging, ids, nowMs);
+        await writeFile(join(staging, "worldengine.project.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+        await writeFile(join(staging, ".worldengine", "runtime.json"), `${JSON.stringify({ schema_version: 1, project_id: ids.project_id, project_host_version: TOOLCHAIN_VERSION }, null, 2)}\n`, "utf8");
+        if (verify) {
+            await runCommand(npm.command, [...npm.argumentsPrefix, "run", "gui:check"], staging, "E_INITIALIZATION_VERIFY_FAILED");
+            await runCommand(npm.command, [...npm.argumentsPrefix, "run", "snapshot"], staging, "E_INITIALIZATION_VERIFY_FAILED");
+            await runCommand(npm.command, [...npm.argumentsPrefix, "run", "doctor"], staging, "E_INITIALIZATION_VERIFY_FAILED");
+            await runCommand(npm.command, [...npm.argumentsPrefix, "run", "typecheck"], staging, "E_INITIALIZATION_VERIFY_FAILED");
+            await runCommand(npm.command, [...npm.argumentsPrefix, "run", "build"], staging, "E_INITIALIZATION_VERIFY_FAILED");
+        }
+        // 所有安装和 doctor/typecheck/build 都已在 target 外完成后，才替换空目标。
+        promotion = await promoteProjectRoot(staging, target, targetState, ids.operation_id);
+        if (input.fault_injection === "agent_link_post_promote") {
+            throw new ProjectInitializationError("E_INITIALIZATION_VERIFY_FAILED", "受控 promote 后 skills 重建失败");
+        }
+        await createAgentSkillJunctions(target, staging);
+        await verifyAgentKitLinks(target);
+        const receipt = {
+            schema_version: 1,
+            operation_id: ids.operation_id,
+            project_id: ids.project_id,
+            status: "ready",
+            initialized_at_ms: nowMs,
+            root_dependencies_installed: installDependencies,
+            view_dependencies_installed: installDependencies,
+            dependency_installation: {
+                root: { status: installDependencies ? "completed" : "skipped", working_directory: "." },
+                view: { status: installDependencies ? "completed" : "skipped", working_directory: "view" },
+            },
+            verification_completed: verify,
+            snapshot_digest: verify ? await readSnapshotDigest(target) : manifest.snapshot.canonical_digest,
+        };
+        await writeFile(join(target, ".worldengine", "operations", "initialization.json"), `${JSON.stringify(receipt, null, 2)}\n`, "utf8");
+        if (promotion.kind === "renamed" && promotion.backup !== undefined) {
+            await rm(promotion.backup, { recursive: true, force: true });
+        }
+        else if (promotion.kind === "merged") {
+            await rm(promotion.staging, { recursive: true, force: true });
+        }
+        return receipt;
+    }
+    catch (error) {
+        if (promotion !== undefined) {
+            await rollbackPromotion(target, promotion);
+        }
+        else {
+            await rm(staging, { recursive: true, force: true });
+        }
+        throw error;
+    }
+}