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

package/LICENSE

@@ -0,0 +1,46 @@
+WorldEngine 官方作者工具许可证
+
+版权所有 (c) 2026 Nixdorfer。保留所有权利。
+
+本仓库的源代码、构建材料及附带资源（统称“本作品”）不是开源软件，
+不适用任何 OSI 认证的开源许可证。
+
+一、官方作者工具分发许可
+
+版权所有者可以通过其官方网站、npm registry、签名安装包或其他官方渠道，
+复制并分发由本作品构建的 WorldEngine 作者工具及其必要运行资源
+（统称“官方作者工具”）。仅版权所有者或其书面指定的发布者享有此分发权。
+
+二、作者用户许可
+
+从官方渠道取得官方作者工具的作者用户，可以：
+
+1. 安装和运行官方作者工具；
+2. 使用官方作者工具创作、编辑、预览、导入、导出和提交其有权处理的内容；
+3. 为上述使用目的制作合理必要的本地备份副本。
+
+三、未授予的权利
+
+除第二条明确允许的行为外，本许可证不授予作者用户或其他第三方以下权利：
+
+1. 修改、改编、反编译、反汇编或制作官方作者工具的派生作品；
+2. 复制、镜像、转发、再上传、出售、出租、再分发或再许可官方作者工具；
+3. 使用本作品的源代码、构建材料或任何部分开发、提供或训练其他产品或服务；
+4. 删除或规避版权、许可、签名、访问控制或其他权利管理信息。
+
+法律强制允许且合同不得排除的权利不受上述限制影响。
+
+四、源代码查看
+
+第三方可以在已获合法访问权限的范围内查看本作品，用于审查、安全研究或学习参考；
+查看不授予运行、复制、修改、分发、再许可或用于其他产品与服务的权利。
+
+五、无担保与责任限制
+
+本作品与官方作者工具均按“现状”提供，不附带任何明示或暗示的担保。
+在适用法律允许的最大范围内，版权所有者不对因访问或使用本作品或官方作者工具
+造成的任何损失承担责任。
+
+六、终止
+
+违反本许可证将立即终止相应的访问与使用权；终止不影响版权所有者已经产生的权利和救济。

package/dist/build-release-standalone-cmd.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+interface ReleaseStandaloneCmdReceiptV1 {
+    readonly schema_version: 1;
+    readonly release_identity: string;
+    readonly payload_root: string;
+    readonly command_file: string;
+    readonly command_sha256: string;
+    readonly node_version: string;
+    readonly payload_archive_sha256: string;
+    readonly package_source: string;
+}
+/**
+ * 将已经 fresh-pack 的 first-party tarball closure 变成可分发的 Windows 单 CMD。
+ * 它不执行 npm publish，也不运行 npm/npx；作者最终运行的是生成后的 CMD。
+ */
+export declare function buildReleaseStandaloneCmd(argv: readonly string[]): Promise<ReleaseStandaloneCmdReceiptV1>;
+export declare function runReleaseStandaloneCmdBuilder(argv: readonly string[]): Promise<number>;
+export {};

package/dist/build-release-standalone-cmd.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { access, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { buildSetupPayload, prepareInitializerBootstrap } from "./installer.js";
+import { buildStandaloneSetupCmd } from "./standalone-cmd.js";
+const execFileAsync = promisify(execFile);
+function value(argv, name) {
+    const index = argv.indexOf(name);
+    const candidate = index < 0 ? undefined : argv[index + 1];
+    if (candidate === undefined || candidate.startsWith("--")) {
+        throw new Error(`E_ARGUMENT_INVALID: ${name} 需要绝对路径或 release identity`);
+    }
+    return candidate;
+}
+function absolute(value, name) {
+    const path = resolve(value);
+    if (path !== value && !/^[a-zA-Z]:[\\/]/.test(value)) {
+        throw new Error(`E_ARGUMENT_INVALID: ${name} 必须是绝对路径`);
+    }
+    return path;
+}
+async function existingDirectory(path, label) {
+    await access(path).catch(() => {
+        throw new Error(`E_INPUT_MISSING: ${label} 不存在: ${path}`);
+    });
+}
+/**
+ * 将已经 fresh-pack 的 first-party tarball closure 变成可分发的 Windows 单 CMD。
+ * 它不执行 npm publish，也不运行 npm/npx；作者最终运行的是生成后的 CMD。
+ */
+export async function buildReleaseStandaloneCmd(argv) {
+    const allowed = new Set([
+        "--repository-root",
+        "--package-source",
+        "--runtime-directory",
+        "--payload-root",
+        "--output",
+        "--release-identity",
+    ]);
+    if (argv.length !== allowed.size * 2 || argv.some((item, index) => index % 2 === 0 && !allowed.has(item))) {
+        throw new Error("E_ARGUMENT_INVALID: 需要 repository-root、package-source、runtime-directory、payload-root、output、release-identity");
+    }
+    const repositoryRoot = absolute(value(argv, "--repository-root"), "--repository-root");
+    const packageSource = absolute(value(argv, "--package-source"), "--package-source");
+    const runtimeDirectory = absolute(value(argv, "--runtime-directory"), "--runtime-directory");
+    const payloadRoot = absolute(value(argv, "--payload-root"), "--payload-root");
+    const outputFile = absolute(value(argv, "--output"), "--output");
+    const releaseIdentity = value(argv, "--release-identity");
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(releaseIdentity)) {
+        throw new Error("E_ARGUMENT_INVALID: release identity 只能包含字母、数字、点、下划线和连字符");
+    }
+    await Promise.all([
+        existingDirectory(repositoryRoot, "repository root"),
+        existingDirectory(packageSource, "package source"),
+        existingDirectory(runtimeDirectory, "portable Node runtime"),
+    ]);
+    await access(dirname(outputFile)).catch(() => {
+        throw new Error(`E_OUTPUT_PARENT_MISSING: CMD 输出目录不存在: ${dirname(outputFile)}`);
+    });
+    const projectSetup = join(repositoryRoot, "tools", "worldengine-project-setup");
+    const createProject = join(repositoryRoot, "packages", "worldengine-create-project");
+    const projectFormat = join(repositoryRoot, "packages", "worldengine-project-format");
+    const agentKit = join(repositoryRoot, "packages", "worldengine-agent-kit");
+    await Promise.all([
+        existingDirectory(projectSetup, "project-setup package"),
+        existingDirectory(createProject, "create-project package"),
+        existingDirectory(projectFormat, "project-format package"),
+        existingDirectory(agentKit, "agent-kit package"),
+    ]);
+    const nodeExecutable = join(runtimeDirectory, "node.exe");
+    const { stdout } = await execFileAsync(nodeExecutable, ["--version"], { windowsHide: true });
+    const nodeVersion = stdout.trim();
+    if (!/^v\d+\.\d+\.\d+$/.test(nodeVersion)) {
+        throw new Error(`E_RUNTIME_INVALID: node.exe 未返回语义版本: ${nodeVersion}`);
+    }
+    const bootstrapDirectory = `${payloadRoot}.bootstrap`;
+    let bootstrapCreated = false;
+    try {
+        await prepareInitializerBootstrap({
+            outputDirectory: bootstrapDirectory,
+            projectSetupDirectory: projectSetup,
+            createProjectDirectory: createProject,
+            projectFormatDirectory: projectFormat,
+            agentKitDirectory: agentKit,
+        });
+        bootstrapCreated = true;
+        const payload = await buildSetupPayload({
+            outputRoot: payloadRoot,
+            runtimeDirectory,
+            bootstrapDirectory,
+            packageSource,
+            releaseIdentity,
+            nodeVersion,
+        });
+        const command = await buildStandaloneSetupCmd({ payloadRoot, outputFile });
+        const commandSha256 = createHash("sha256").update(await (await import("node:fs/promises")).readFile(outputFile)).digest("hex");
+        return {
+            schema_version: 1,
+            release_identity: releaseIdentity,
+            payload_root: payloadRoot,
+            command_file: outputFile,
+            command_sha256: commandSha256,
+            node_version: payload.node.version,
+            payload_archive_sha256: command.payload_archive_sha256,
+            package_source: packageSource,
+        };
+    }
+    finally {
+        if (bootstrapCreated)
+            await rm(bootstrapDirectory, { recursive: true, force: true });
+    }
+}
+export async function runReleaseStandaloneCmdBuilder(argv) {
+    try {
+        process.stdout.write(`${JSON.stringify(await buildReleaseStandaloneCmd(argv), null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+const invokedPath = process.argv[1];
+if (invokedPath !== undefined && resolve(invokedPath).toLocaleLowerCase("en-US") === resolve(fileURLToPath(import.meta.url)).toLocaleLowerCase("en-US")) {
+    void runReleaseStandaloneCmdBuilder(process.argv.slice(2)).then((exitCode) => {
+        process.exitCode = exitCode;
+    });
+}

package/dist/build-standalone-cmd.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runStandaloneCmdBuilder(argv: readonly string[]): Promise<number>;

package/dist/build-standalone-cmd.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildStandaloneSetupCmd } from "./standalone-cmd.js";
+function value(argv, name) {
+    const index = argv.indexOf(name);
+    const candidate = index < 0 ? undefined : argv[index + 1];
+    if (candidate === undefined || candidate.startsWith("--"))
+        throw new Error(`E_ARGUMENT_INVALID: ${name} 需要路径`);
+    return candidate;
+}
+export async function runStandaloneCmdBuilder(argv) {
+    try {
+        const allowed = new Set(["--payload-root", "--output"]);
+        for (let index = 0; index < argv.length; index += 2) {
+            const name = argv[index];
+            if (name === undefined || !allowed.has(name))
+                throw new Error(`E_ARGUMENT_INVALID: 未知参数 ${name ?? ""}`);
+        }
+        const receipt = await buildStandaloneSetupCmd({
+            payloadRoot: value(argv, "--payload-root"),
+            outputFile: value(argv, "--output"),
+        });
+        process.stdout.write(`${JSON.stringify(receipt, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+const invokedPath = process.argv[1];
+if (invokedPath !== undefined && resolve(invokedPath).toLocaleLowerCase("en-US") === resolve(fileURLToPath(import.meta.url)).toLocaleLowerCase("en-US")) {
+    void runStandaloneCmdBuilder(process.argv.slice(2)).then((exitCode) => {
+        process.exitCode = exitCode;
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./installer.js";
+export * from "./toolchain-manifest.js";
+export * from "./standalone-cmd.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./installer.js";
+export * from "./toolchain-manifest.js";
+export * from "./standalone-cmd.js";

package/dist/installer.d.ts

@@ -0,0 +1,97 @@
+export declare const SETUP_PAYLOAD_SCHEMA_VERSION = 1;
+export declare class ProjectSetupError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface SetupPayloadManifestV1 {
+    readonly schema_version: 1;
+    readonly release_identity: string;
+    readonly node: {
+        readonly path: string;
+        readonly sha256: string;
+        readonly runtime_sha256: string;
+        readonly version: string;
+    };
+    readonly create_project_tgz: {
+        readonly path: string;
+        readonly sha256: string;
+    };
+    readonly package_source: {
+        readonly path: string;
+        readonly sha256: string;
+    };
+    /** package source 的 first-party identity 与完整 tarball 数量。 */
+    readonly toolchain_manifest: {
+        readonly path: string;
+        readonly sha256: string;
+    };
+    readonly bootstrap: {
+        readonly path: string;
+        readonly sha256: string;
+    };
+}
+export interface SetupPreflightV1 {
+    readonly schema_version: 1;
+    readonly target: string;
+    readonly payload_identity: string;
+    readonly directory: {
+        readonly status: "ready";
+        readonly target_exists: boolean;
+    };
+    readonly network: {
+        readonly status: "ready" | "unavailable";
+        readonly required_for_dependency_install: boolean;
+    };
+    readonly disk: {
+        readonly status: "ready";
+        readonly required_bytes: number;
+        readonly available_bytes: number | null;
+    };
+}
+export interface SetupInstallationReceiptV1 {
+    readonly schema_version: 1;
+    readonly operation_id: string;
+    readonly status: "ready" | "recoverable_failure";
+    readonly payload_identity: string;
+    readonly target: string;
+    readonly progress: readonly string[];
+    readonly initializer_receipt?: unknown;
+    readonly recovery_path: string;
+}
+export declare function inspectSetupPayload(payloadRoot: string): Promise<SetupPayloadManifestV1>;
+export declare function preflightSetup({ payloadRoot, target, requiredBytes, networkProbe }: {
+    payloadRoot: string;
+    target: string;
+    requiredBytes?: number;
+    networkProbe?: () => Promise<boolean>;
+}): Promise<SetupPreflightV1>;
+export declare function installProjectFromSetup({ payloadRoot, target, networkProbe }: {
+    payloadRoot: string;
+    target: string;
+    networkProbe?: () => Promise<boolean>;
+}): Promise<SetupInstallationReceiptV1>;
+export declare function recoverProjectSetup({ payloadRoot, target, networkProbe }: {
+    payloadRoot: string;
+    target: string;
+    networkProbe?: () => Promise<boolean>;
+}): Promise<SetupInstallationReceiptV1>;
+/**
+ * 将已经编译的唯一 initializer 及其运行时依赖放入 payload bootstrap。
+ * 这里不重写或复制 initializeLocalAuthorProject；run-initializer 只负责把
+ * 固定 Node/npm 与已验证 tarball source 传给该 public API。
+ */
+export declare function prepareInitializerBootstrap({ outputDirectory, projectSetupDirectory, createProjectDirectory, projectFormatDirectory, agentKitDirectory }: {
+    outputDirectory: string;
+    projectSetupDirectory: string;
+    createProjectDirectory: string;
+    projectFormatDirectory: string;
+    agentKitDirectory: string;
+}): Promise<string>;
+export declare function buildSetupPayload({ outputRoot, runtimeDirectory, bootstrapDirectory, packageSource, releaseIdentity, nodeVersion }: {
+    outputRoot: string;
+    runtimeDirectory: string;
+    bootstrapDirectory: string;
+    packageSource: string;
+    releaseIdentity: string;
+    nodeVersion: string;
+}): Promise<SetupPayloadManifestV1>;

package/dist/installer.js

@@ -0,0 +1,265 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { copyFile, cp, lstat, mkdir, readFile, readdir, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { TOOLCHAIN_MANIFEST_FILE, readToolchainManifest } from "./toolchain-manifest.js";
+export const SETUP_PAYLOAD_SCHEMA_VERSION = 1;
+const SHA256 = /^[a-f0-9]{64}$/;
+export class ProjectSetupError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+    }
+}
+function fail(code, message) { throw new ProjectSetupError(code, message); }
+function hash(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+function isWithin(path, root) { const result = relative(root, path); return result === "" || (!result.startsWith("..\\") && result !== ".." && !result.startsWith("../")); }
+async function regularFile(path, label) {
+    const canonical = await realpath(path).catch(() => fail("E_PAYLOAD_INVALID", `${label} 不存在: ${path}`));
+    const info = await lstat(canonical);
+    if (!info.isFile() || info.isSymbolicLink())
+        fail("E_PAYLOAD_INVALID", `${label} 必须是常规文件`);
+    return canonical;
+}
+async function regularDirectory(path, label) {
+    const canonical = await realpath(path).catch(() => fail("E_PAYLOAD_INVALID", `${label} 不存在: ${path}`));
+    const info = await lstat(canonical);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        fail("E_PAYLOAD_INVALID", `${label} 必须是非 reparse 目录`);
+    return canonical;
+}
+async function canonicalDirectoryDigest(directory) {
+    const root = await regularDirectory(directory, "目录");
+    const entries = [];
+    async function walk(current) {
+        for (const entry of (await readdir(current, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name, "en"))) {
+            const candidate = join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(candidate);
+                continue;
+            }
+            if (!entry.isFile() || entry.isSymbolicLink())
+                fail("E_PAYLOAD_INVALID", `payload 含非普通文件: ${candidate}`);
+            const bytes = await readFile(candidate);
+            entries.push({ path: relative(root, candidate).replaceAll("\\", "/"), sha256: hash(bytes), size_bytes: bytes.length });
+        }
+    }
+    await walk(root);
+    return hash(Buffer.from(JSON.stringify(entries)));
+}
+// 与 @world-engines/project-format 的 computeCanonicalFileTreeDigest 保持逐字节一致；
+// package source 是 create-project 的公开输入合同，不能另造一个近似 hash 算法。
+async function canonicalPackageSourceDigest(directory) {
+    const root = await regularDirectory(directory, "package source");
+    const entries = [];
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isFile() || entry.isSymbolicLink())
+            fail("E_PAYLOAD_INVALID", "package source 只能含普通 .tgz 文件与 ToolchainManifest");
+        if (entry.name === TOOLCHAIN_MANIFEST_FILE)
+            continue;
+        if (!entry.name.endsWith(".tgz"))
+            fail("E_PAYLOAD_INVALID", "package source 只能含普通 .tgz 文件与 ToolchainManifest");
+        entries.push({ path: entry.name, bytes: new Uint8Array(await readFile(join(root, entry.name))) });
+    }
+    entries.sort((left, right) => Buffer.compare(Buffer.from(left.path, "utf8"), Buffer.from(right.path, "utf8")));
+    const encoder = new TextEncoder();
+    const length = entries.reduce((total, entry) => total + 4 + encoder.encode(entry.path).byteLength + 8 + entry.bytes.byteLength, 0);
+    const canonical = new Uint8Array(length);
+    const view = new DataView(canonical.buffer);
+    let offset = 0;
+    for (const entry of entries) {
+        const pathBytes = encoder.encode(entry.path);
+        view.setUint32(offset, pathBytes.byteLength);
+        offset += 4;
+        canonical.set(pathBytes, offset);
+        offset += pathBytes.byteLength;
+        view.setBigUint64(offset, BigInt(entry.bytes.byteLength));
+        offset += 8;
+        canonical.set(entry.bytes, offset);
+        offset += entry.bytes.byteLength;
+    }
+    return hash(canonical);
+}
+async function readManifest(payloadRoot) {
+    const raw = await readFile(join(payloadRoot, "setup-payload-manifest.json"), "utf8").catch(() => fail("E_PAYLOAD_INVALID", "缺少 setup-payload-manifest.json"));
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        fail("E_PAYLOAD_INVALID", "payload manifest 不是 JSON");
+    }
+    const manifest = parsed;
+    if (manifest?.schema_version !== SETUP_PAYLOAD_SCHEMA_VERSION || typeof manifest.release_identity !== "string" || manifest.release_identity.length === 0)
+        fail("E_PAYLOAD_INVALID", "payload identity 无效");
+    return manifest;
+}
+export async function inspectSetupPayload(payloadRoot) {
+    const root = await regularDirectory(payloadRoot, "setup payload 根");
+    const manifest = await readManifest(root);
+    for (const [label, item] of Object.entries({ node: manifest.node, create_project_tgz: manifest.create_project_tgz, bootstrap: manifest.bootstrap })) {
+        if (!item || typeof item.path !== "string" || !SHA256.test(item.sha256))
+            fail("E_PAYLOAD_INVALID", `${label} manifest 项无效`);
+        const candidate = resolve(root, item.path);
+        if (!isWithin(candidate, root))
+            fail("E_PAYLOAD_INVALID", `${label} 路径逃离 payload`);
+        if (label === "bootstrap") {
+            if (await canonicalDirectoryDigest(candidate) !== item.sha256)
+                fail("E_PAYLOAD_INVALID", "bootstrap SHA-256 不匹配");
+        }
+        else if (hash(await readFile(await regularFile(candidate, label))) !== item.sha256)
+            fail("E_PAYLOAD_INVALID", `${label} SHA-256 不匹配`);
+    }
+    if (!SHA256.test(manifest.node.runtime_sha256) || await canonicalDirectoryDigest(resolve(root, "runtime")) !== manifest.node.runtime_sha256)
+        fail("E_PAYLOAD_INVALID", "固定 Node runtime SHA-256 不匹配");
+    await regularFile(resolve(root, "runtime", "node_modules", "npm", "bin", "npm-cli.js"), "固定 Node npm CLI");
+    if (!manifest.package_source || typeof manifest.package_source.path !== "string" || !SHA256.test(manifest.package_source.sha256))
+        fail("E_PAYLOAD_INVALID", "package_source manifest 项无效");
+    const source = resolve(root, manifest.package_source.path);
+    if (!isWithin(source, root) || await canonicalPackageSourceDigest(source) !== manifest.package_source.sha256)
+        fail("E_PAYLOAD_INVALID", "package_source SHA-256 不匹配");
+    if (!manifest.toolchain_manifest || typeof manifest.toolchain_manifest.path !== "string" || !SHA256.test(manifest.toolchain_manifest.sha256))
+        fail("E_PAYLOAD_INVALID", "toolchain_manifest manifest 项无效");
+    const toolchainPath = resolve(root, manifest.toolchain_manifest.path);
+    if (!isWithin(toolchainPath, source) || basename(toolchainPath) !== TOOLCHAIN_MANIFEST_FILE || hash(await readFile(await regularFile(toolchainPath, "toolchain_manifest"))) !== manifest.toolchain_manifest.sha256)
+        fail("E_PAYLOAD_INVALID", "toolchain_manifest SHA-256 不匹配");
+    try {
+        await readToolchainManifest(source);
+    }
+    catch (error) {
+        fail("E_PAYLOAD_INVALID", `toolchain_manifest 无效: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return manifest;
+}
+export async function preflightSetup({ payloadRoot, target, requiredBytes = 128 * 1024 * 1024, networkProbe }) {
+    const manifest = await inspectSetupPayload(payloadRoot);
+    const canonicalTarget = resolve(target);
+    let targetExists = false;
+    try {
+        const info = await stat(canonicalTarget);
+        if (!info.isDirectory())
+            fail("E_TARGET_INVALID", "目标必须是目录或不存在的目录");
+        if ((await readdir(canonicalTarget)).length !== 0)
+            fail("E_TARGET_NOT_EMPTY", "目标目录非空");
+        targetExists = true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const online = networkProbe === undefined ? true : await networkProbe().catch(() => false);
+    return { schema_version: 1, target: canonicalTarget, payload_identity: manifest.release_identity, directory: { status: "ready", target_exists: targetExists }, network: { status: online ? "ready" : "unavailable", required_for_dependency_install: true }, disk: { status: "ready", required_bytes: requiredBytes, available_bytes: null } };
+}
+async function writeRecovery(path, receipt) { await writeFile(path, `${JSON.stringify(receipt, null, 2)}\n`, "utf8"); }
+async function runNode(node, args, cwd) {
+    const result = await new Promise((resolvePromise, reject) => {
+        const child = spawn(node, args, { cwd, windowsHide: true, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => { stdout += chunk; });
+        child.stderr.on("data", (chunk) => { stderr += chunk; });
+        child.once("error", reject);
+        child.once("close", (code) => code === 0 ? resolvePromise(stdout) : reject(new ProjectSetupError("E_INITIALIZER_FAILED", `${stderr.trim() || `initializer 退出码 ${code}`}`)));
+    });
+    // npm 会由唯一 initializer 继承 stdout 输出进度；最后一行才是它的 receipt。
+    const receiptLine = result.trim().split(/\r?\n/).filter(Boolean).at(-1);
+    try {
+        return JSON.parse(receiptLine ?? "");
+    }
+    catch {
+        fail("E_INITIALIZER_FAILED", "initializer 未返回 JSON receipt");
+    }
+}
+export async function installProjectFromSetup({ payloadRoot, target, networkProbe }) {
+    const preflight = await preflightSetup(networkProbe === undefined ? { payloadRoot, target } : { payloadRoot, target, networkProbe });
+    if (preflight.network.status !== "ready")
+        fail("E_NETWORK_UNAVAILABLE", "依赖安装需要网络；恢复时请重新运行 setup recover");
+    const root = await regularDirectory(payloadRoot, "setup payload 根");
+    const manifest = await inspectSetupPayload(root);
+    const recoveryPath = join(dirname(preflight.target), `.${resolve(preflight.target).split(/[\\/]/).pop()}.worldengine-setup-recovery.json`);
+    const progress = ["preflight:directory", "preflight:network", "preflight:disk", "initializer:starting"];
+    const receiptBase = { schema_version: 1, operation_id: `setup_${randomUUID().replaceAll("-", "")}`, payload_identity: manifest.release_identity, target: preflight.target, recovery_path: recoveryPath };
+    try {
+        const initializerReceipt = await runNode(resolve(root, manifest.node.path), [join(resolve(root, manifest.bootstrap.path), "run-initializer.mjs"), "--target", preflight.target, "--node", resolve(root, manifest.node.path), "--package-source", resolve(root, manifest.package_source.path), "--package-source-sha256", manifest.package_source.sha256], root);
+        const receipt = { ...receiptBase, status: "ready", progress: [...progress, "initializer:ready"], initializer_receipt: initializerReceipt };
+        await mkdir(join(preflight.target, ".worldengine", "operations"), { recursive: true });
+        await writeRecovery(join(preflight.target, ".worldengine", "operations", "windows-setup.json"), receipt);
+        return receipt;
+    }
+    catch (error) {
+        const receipt = { ...receiptBase, status: "recoverable_failure", progress: [...progress, "initializer:recoverable_failure"] };
+        await writeRecovery(recoveryPath, receipt);
+        throw error;
+    }
+}
+export async function recoverProjectSetup({ payloadRoot, target, networkProbe }) {
+    const receipt = await installProjectFromSetup(networkProbe === undefined ? { payloadRoot, target } : { payloadRoot, target, networkProbe });
+    await rm(receipt.recovery_path, { force: true });
+    return receipt;
+}
+/**
+ * 将已经编译的唯一 initializer 及其运行时依赖放入 payload bootstrap。
+ * 这里不重写或复制 initializeLocalAuthorProject；run-initializer 只负责把
+ * 固定 Node/npm 与已验证 tarball source 传给该 public API。
+ */
+export async function prepareInitializerBootstrap({ outputDirectory, projectSetupDirectory, createProjectDirectory, projectFormatDirectory, agentKitDirectory }) {
+    const output = resolve(outputDirectory);
+    await mkdir(output, { recursive: true });
+    if ((await readdir(output)).length !== 0)
+        fail("E_OUTPUT_NOT_EMPTY", "bootstrap 输出目录必须为空");
+    const packages = [
+        ["project-setup", projectSetupDirectory],
+        ["create-project", createProjectDirectory],
+        ["project-format", projectFormatDirectory],
+        ["agent-kit", agentKitDirectory],
+    ];
+    for (const [name, directory] of packages) {
+        const source = await regularDirectory(directory, `bootstrap ${name}`);
+        await regularFile(join(source, "dist", "index.js"), `bootstrap ${name} dist`);
+        const destination = join(output, "node_modules", "@world-engines", name);
+        await mkdir(destination, { recursive: true });
+        await copyFile(join(source, "package.json"), join(destination, "package.json"));
+        await cp(join(source, "dist"), join(destination, "dist"), { recursive: true, force: false });
+        try {
+            await copyFile(join(source, "LICENSE"), join(destination, "LICENSE"));
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (name === "agent-kit") {
+            await cp(join(source, "assets"), join(destination, "assets"), { recursive: true, force: false });
+        }
+    }
+    const runner = `import { initializeLocalAuthorProject } from "@world-engines/create-project";\nimport { dirname, join } from "node:path";\nconst read = (name) => { const index = process.argv.indexOf(name); const value = index < 0 ? undefined : process.argv[index + 1]; if (!value || value.startsWith("--")) throw new Error(name + " is required"); return value; };\nconst node = read("--node");\nconst receipt = await initializeLocalAuthorProject({ target: read("--target"), npm_executable: node, npm_arguments_prefix: [join(dirname(node), "node_modules", "npm", "bin", "npm-cli.js")], package_source: { tarball_directory: read("--package-source"), tarball_directory_sha256: read("--package-source-sha256") } });\nprocess.stdout.write(JSON.stringify(receipt));\n`;
+    await writeFile(join(output, "run-initializer.mjs"), runner, { flag: "wx" });
+    const setupRunner = `import { installProjectFromSetup } from "@world-engines/project-setup";\nconst read = (name) => { const index = process.argv.indexOf(name); const value = index < 0 ? undefined : process.argv[index + 1]; if (!value || value.startsWith("--")) throw new Error(name + " is required"); return value; };\nconst receipt = await installProjectFromSetup({ payloadRoot: read("--payload-root"), target: read("--target") });\nprocess.stdout.write(JSON.stringify(receipt));\n`;
+    await writeFile(join(output, "run-setup.mjs"), setupRunner, { flag: "wx" });
+    return output;
+}
+export async function buildSetupPayload({ outputRoot, runtimeDirectory, bootstrapDirectory, packageSource, releaseIdentity, nodeVersion }) {
+    const destination = resolve(outputRoot);
+    await mkdir(destination, { recursive: true });
+    if ((await readdir(destination)).length !== 0)
+        fail("E_OUTPUT_NOT_EMPTY", "setup payload 输出目录必须为空");
+    const runtime = await regularDirectory(runtimeDirectory, "固定 Node runtime");
+    await regularFile(join(runtime, "node.exe"), "固定 Node executable");
+    await regularFile(join(runtime, "node_modules", "npm", "bin", "npm-cli.js"), "固定 Node npm CLI");
+    const source = await regularDirectory(packageSource, "package source");
+    const toolchain = await readToolchainManifest(source).catch((error) => fail("E_PAYLOAD_INVALID", `toolchain_manifest 无效: ${error instanceof Error ? error.message : String(error)}`));
+    const bootstrapSource = await regularDirectory(bootstrapDirectory, "initializer bootstrap");
+    await regularFile(join(bootstrapSource, "run-initializer.mjs"), "initializer bootstrap entry");
+    await mkdir(join(destination, "runtime"));
+    await mkdir(join(destination, "packages"));
+    await cp(runtime, join(destination, "runtime"), { recursive: true, force: false });
+    await cp(source, join(destination, "packages"), { recursive: true, force: false });
+    await cp(bootstrapSource, join(destination, "bootstrap"), { recursive: true, force: false });
+    const createProject = toolchain.packages.find((item) => item.name === "@world-engines/create-project");
+    if (createProject === undefined)
+        fail("E_PAYLOAD_INVALID", "toolchain manifest 缺少 create-project.tgz");
+    const manifest = { schema_version: 1, release_identity: releaseIdentity, node: { path: "runtime/node.exe", sha256: hash(await readFile(join(destination, "runtime", "node.exe"))), runtime_sha256: await canonicalDirectoryDigest(join(destination, "runtime")), version: nodeVersion }, create_project_tgz: { path: `packages/${createProject.archive}`, sha256: createProject.sha256 }, package_source: { path: "packages", sha256: await canonicalPackageSourceDigest(join(destination, "packages")) }, toolchain_manifest: { path: `packages/${TOOLCHAIN_MANIFEST_FILE}`, sha256: hash(await readFile(join(destination, "packages", TOOLCHAIN_MANIFEST_FILE))) }, bootstrap: { path: "bootstrap", sha256: await canonicalDirectoryDigest(join(destination, "bootstrap")) } };
+    await writeFile(join(destination, "setup-payload-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+    await inspectSetupPayload(destination);
+    return manifest;
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { initializeLocalAuthorProject } from "@world-engines/create-project";
+import { dirname, join } from "node:path";
+function option(name) {
+    const index = process.argv.indexOf(name);
+    const value = index < 0 ? undefined : process.argv[index + 1];
+    if (value === undefined || value.startsWith("--"))
+        throw new Error(`${name} is required`);
+    return value;
+}
+const target = option("--target");
+const node = option("--node");
+const source = option("--package-source");
+const sourceHash = option("--package-source-sha256");
+const npmCli = join(dirname(node), "node_modules", "npm", "bin", "npm-cli.js");
+initializeLocalAuthorProject({
+    target,
+    npm_executable: node,
+    npm_arguments_prefix: [npmCli],
+    package_source: { tarball_directory: source, tarball_directory_sha256: sourceHash },
+}).then((receipt) => process.stdout.write(`${JSON.stringify(receipt)}\n`));

package/dist/package-catalog.d.ts

@@ -0,0 +1,16 @@
+export interface WorldEngineNodePackage {
+    readonly name: string;
+    readonly directory: string;
+    /** 未指定时是原生 Node 入口；browser 必须通过隔离 Vite consumer 构建。 */
+    readonly runtime?: "browser";
+    /** 只约束 release build 顺序，不进入公开 runtime dependency。 */
+    readonly build_dependencies?: readonly string[];
+}
+export declare const WORLDENGINE_NODE_PACKAGE_CATALOG: readonly Readonly<{
+    name: string;
+    directory: string;
+    runtime?: "browser";
+    build_dependencies?: readonly string[];
+}>[];
+export declare const WORLDENGINE_NODE_PACKAGE_NAMES: readonly string[];
+export type WorldEngineNodePackageName = string;