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

package/dist/package-catalog.js

@@ -0,0 +1,33 @@
+import { readFileSync } from "node:fs";
+function loadPackageCatalog() {
+    const parsed = JSON.parse(readFileSync(new URL("./worldengine-package-catalog.json", import.meta.url), "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        throw new Error("worldengine_package_catalog_invalid");
+    const catalog = parsed;
+    if (catalog.schema_version !== 1 || !Array.isArray(catalog.packages) || catalog.packages.length === 0)
+        throw new Error("worldengine_package_catalog_invalid");
+    const names = new Set();
+    const directories = new Set();
+    for (const entry of catalog.packages) {
+        if (typeof entry?.name !== "string" || !/^@(?:chat|world-engines|worldengine)\/[a-z0-9-]+$/.test(entry.name))
+            throw new Error("worldengine_package_catalog_name_invalid");
+        if (typeof entry.directory !== "string" || !/^(?:packages|tools)\/[a-z0-9-]+$/.test(entry.directory))
+            throw new Error(`worldengine_package_catalog_directory_invalid:${entry.name}`);
+        if (entry.runtime !== undefined && entry.runtime !== "browser")
+            throw new Error(`worldengine_package_catalog_runtime_invalid:${entry.name}`);
+        if (entry.build_dependencies !== undefined && (!Array.isArray(entry.build_dependencies) || entry.build_dependencies.some((name) => typeof name !== "string")))
+            throw new Error(`worldengine_package_catalog_build_dependencies_invalid:${entry.name}`);
+        if (names.has(entry.name) || directories.has(entry.directory))
+            throw new Error(`worldengine_package_catalog_duplicate:${entry.name}`);
+        names.add(entry.name);
+        directories.add(entry.directory);
+    }
+    for (const entry of catalog.packages) {
+        for (const dependency of entry.build_dependencies ?? [])
+            if (!names.has(dependency) || dependency === entry.name)
+                throw new Error(`worldengine_package_catalog_build_dependency_invalid:${entry.name}:${dependency}`);
+    }
+    return catalog;
+}
+export const WORLDENGINE_NODE_PACKAGE_CATALOG = Object.freeze(loadPackageCatalog().packages.map((entry) => Object.freeze({ ...entry })));
+export const WORLDENGINE_NODE_PACKAGE_NAMES = Object.freeze(WORLDENGINE_NODE_PACKAGE_CATALOG.map(({ name }) => name));

package/dist/standalone-cmd.d.ts

@@ -0,0 +1,22 @@
+export interface StandaloneSetupCmdReceiptV1 {
+    readonly schema_version: 1;
+    readonly output_file: string;
+    readonly release_identity: string;
+    readonly node_version: string;
+    readonly payload_archive_sha256: string;
+    readonly payload_archive_size: number;
+    readonly test_only: boolean;
+}
+export declare function inspectGuiStartup(input: {
+    readonly processRunning: boolean;
+    readonly stdout: string;
+}): {
+    readonly ready: boolean;
+    readonly url?: string;
+};
+export declare function buildStandaloneSetupCmd({ payloadRoot, outputFile, testOnlySkipInstall, }: {
+    readonly payloadRoot: string;
+    readonly outputFile: string;
+    /** 只供隔离 fixture 验证 CMD 解包/执行链；生成的产物不得作为作者分发包。 */
+    readonly testOnlySkipInstall?: boolean;
+}): Promise<StandaloneSetupCmdReceiptV1>;

package/dist/standalone-cmd.js

@@ -0,0 +1,278 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir, writeFile } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import { deflateRawSync } from "node:zlib";
+import { inspectSetupPayload } from "./installer.js";
+const PAYLOAD_MARKER = "# __WORLDENGINE_PAYLOAD__";
+const POWERSHELL_MARKER = "# __WORLDENGINE_PS__";
+export function inspectGuiStartup(input) {
+    if (!input.processRunning)
+        return { ready: false };
+    const match = /\{\s*"status"\s*:\s*"listening"\s*,\s*"url"\s*:\s*"([^"]+)"\s*\}\s*$/s.exec(input.stdout);
+    return match?.[1] === "http://127.0.0.1:11451/" ? { ready: true, url: match[1] } : { ready: false };
+}
+const CRC_TABLE = Array.from({ length: 256 }, (_, value) => {
+    let crc = value;
+    for (let bit = 0; bit < 8; bit += 1)
+        crc = (crc & 1) === 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+    return crc >>> 0;
+});
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes)
+        crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+async function payloadFiles(root) {
+    const files = [];
+    async function visit(directory) {
+        const entries = (await readdir(directory, { withFileTypes: true }))
+            .sort((left, right) => left.name.localeCompare(right.name, "en"));
+        for (const entry of entries) {
+            const path = resolve(directory, entry.name);
+            const info = await lstat(path);
+            if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile())) {
+                throw new Error(`E_PAYLOAD_INVALID: 单文件 CMD payload 只允许普通文件和目录: ${path}`);
+            }
+            if (info.isDirectory()) {
+                await visit(path);
+            }
+            else {
+                files.push({ path: relative(root, path).replaceAll("\\", "/"), bytes: await readFile(path) });
+            }
+        }
+    }
+    await visit(root);
+    return files;
+}
+function zipPayload(files) {
+    const localParts = [];
+    const centralParts = [];
+    let offset = 0;
+    for (const file of files) {
+        const name = Buffer.from(file.path, "utf8");
+        const compressed = deflateRawSync(file.bytes, { level: 9 });
+        const crc = crc32(file.bytes);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6);
+        local.writeUInt16LE(8, 8);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(compressed.length, 18);
+        local.writeUInt32LE(file.bytes.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        localParts.push(local, name, compressed);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(0x0800, 8);
+        central.writeUInt16LE(8, 10);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(compressed.length, 20);
+        central.writeUInt32LE(file.bytes.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt32LE(offset, 42);
+        centralParts.push(central, name);
+        offset += local.length + name.length + compressed.length;
+    }
+    if (files.length > 0xffff || offset > 0xffffffff)
+        throw new Error("E_PAYLOAD_TOO_LARGE: CMD payload 超过 ZIP32 上限");
+    const central = Buffer.concat(centralParts);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(files.length, 8);
+    end.writeUInt16LE(files.length, 10);
+    end.writeUInt32LE(central.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...localParts, central, end]);
+}
+function powershellScript(releaseIdentity, nodeVersion, archiveSha256, testOnlySkipInstall) {
+    const release = JSON.stringify(releaseIdentity);
+    const version = JSON.stringify(nodeVersion);
+    const digest = JSON.stringify(archiveSha256);
+    return String.raw `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$cmdPath = [IO.Path]::GetFullPath($env:WORLDENGINE_SETUP_CMD)
+$target = [IO.Path]::GetFullPath($env:WORLDENGINE_SETUP_DIR)
+$targetRoot = [IO.Path]::GetPathRoot($target)
+if ($target.Length -gt $targetRoot.Length) { $target = $target.TrimEnd([IO.Path]::DirectorySeparatorChar) }
+$entries = @(Get-ChildItem -LiteralPath $target -Force)
+if ($entries.Count -ne 1 -or -not $entries[0].FullName.Equals($cmdPath, [StringComparison]::OrdinalIgnoreCase) -or $entries[0].PSIsContainer) {
+  throw 'E_TARGET_NOT_EMPTY: CMD 所在目录必须仅包含当前 CMD'
+}
+$targetParent = Split-Path -Parent $target
+$targetName = Split-Path -Leaf $target
+$temporaryIdentity = [guid]::NewGuid().ToString('N')
+$temporaryRoot = Join-Path $targetParent ('.' + $targetName + '.worldengine-standalone-' + $temporaryIdentity)
+New-Item -ItemType Directory -Path $temporaryRoot | Out-Null
+$temporaryOwner = Join-Path $temporaryRoot '.worldengine-cmd-owner'
+[IO.File]::WriteAllText($temporaryOwner, $temporaryIdentity, [Text.Encoding]::ASCII)
+try {
+  $source = [IO.File]::ReadAllText($cmdPath)
+  $marker = '${PAYLOAD_MARKER}' + [Environment]::NewLine
+  $markerIndex = $source.IndexOf($marker, [StringComparison]::Ordinal)
+  if ($markerIndex -lt 0) { throw 'E_PAYLOAD_INVALID: CMD 缺少 payload marker' }
+  $payloadBase64 = $source.Substring($markerIndex + $marker.Length) -replace '\s', ''
+  $archive = [Convert]::FromBase64String($payloadBase64)
+  $sha256 = [Security.Cryptography.SHA256]::Create()
+  try { $actualHash = ([BitConverter]::ToString($sha256.ComputeHash($archive))).Replace('-', '').ToLowerInvariant() } finally { $sha256.Dispose() }
+  if ($actualHash -ne ${digest}) { throw 'E_PAYLOAD_INVALID: CMD 内嵌 payload SHA-256 不匹配' }
+  $archivePath = Join-Path $temporaryRoot 'payload.zip'
+  $payloadRoot = Join-Path $temporaryRoot 'payload'
+  [IO.File]::WriteAllBytes($archivePath, $archive)
+  Add-Type -AssemblyName System.IO.Compression.FileSystem
+  [IO.Compression.ZipFile]::ExtractToDirectory($archivePath, $payloadRoot)
+  $manifest = Get-Content -LiteralPath (Join-Path $payloadRoot 'setup-payload-manifest.json') -Raw | ConvertFrom-Json
+  if ($manifest.release_identity -ne ${release} -or $manifest.node.version -ne ${version}) {
+    throw 'E_PAYLOAD_INVALID: payload release identity 或 Node version 不匹配'
+  }
+  $runner = Join-Path $temporaryRoot 'run-standalone.mjs'
+  $runnerSource = @'
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+const [payloadRoot, target, bootstrapFile] = process.argv.slice(2);
+const manifest = JSON.parse(await readFile(join(payloadRoot, "setup-payload-manifest.json"), "utf8"));
+function payloadPath(path) {
+  if (typeof path !== "string" || isAbsolute(path)) throw new Error("E_PAYLOAD_INVALID: 非法 payload path");
+  const value = resolve(payloadRoot, path);
+  const remainder = relative(payloadRoot, value);
+  if (remainder === ".." || remainder.startsWith("../") || remainder.startsWith("..\\")) throw new Error("E_PAYLOAD_INVALID: payload path escape");
+  return value;
+}
+const createProject = payloadPath("bootstrap/node_modules/@world-engines/create-project/dist/index.js");
+const { initializeLocalAuthorProject } = await import(pathToFileURL(createProject).href);
+const node = payloadPath(manifest.node.path);
+const receipt = await initializeLocalAuthorProject({
+  target,
+  bootstrap_file: bootstrapFile,
+  portable_runtime_directory: dirname(node),
+${testOnlySkipInstall ? "  install_dependencies: false,\n  verify: false,\n" : ""}  npm_executable: node,
+  npm_arguments_prefix: [join(dirname(node), "node_modules", "npm", "bin", "npm-cli.js")],
+  package_source: {
+    tarball_directory: payloadPath(manifest.package_source.path),
+    tarball_directory_sha256: manifest.package_source.sha256,
+  },
+});
+process.stdout.write(JSON.stringify(receipt) + "\\n");
+'@
+  [IO.File]::WriteAllText($runner, $runnerSource, [Text.UTF8Encoding]::new($false))
+  $payloadNode = [IO.Path]::GetFullPath((Join-Path $payloadRoot $manifest.node.path))
+  & $payloadNode $runner $payloadRoot $target $cmdPath
+  if ($LASTEXITCODE -ne 0) { throw "E_INITIALIZER_FAILED: initializer 退出码 $LASTEXITCODE" }
+  if ($env:WORLDENGINE_SETUP_NO_START -ne '1') {
+    $node = Join-Path $target '.worldengine\runtime\node\node.exe'
+    $hostCli = Join-Path $target 'node_modules\@world-engines\project-host\dist\cli.js'
+    if (-not (Test-Path -LiteralPath $hostCli -PathType Leaf)) { throw 'E_GUI_START_FAILED: 缺少已安装的 ProjectHost CLI' }
+    $guiArguments = @('"' + $hostCli + '"', 'gui')
+    if ($env:WORLDENGINE_SETUP_NO_OPEN -eq '1') { $guiArguments += '--no-open' }
+    $stdout = Join-Path $target '.worldengine\logs\gui-bootstrap.stdout.log'
+    $stderr = Join-Path $target '.worldengine\logs\gui-bootstrap.stderr.log'
+    try {
+      $process = Start-Process -FilePath $node -ArgumentList $guiArguments -WorkingDirectory $target -WindowStyle Hidden -RedirectStandardOutput $stdout -RedirectStandardError $stderr -PassThru
+    } catch {
+      throw 'E_GUI_START_FAILED: 无法启动项目 GUI 进程'
+    }
+    $deadline = [DateTime]::UtcNow.AddSeconds(20)
+    $readyUrl = $null
+    do {
+      $process.Refresh()
+      if ($process.HasExited) { break }
+      if (Test-Path -LiteralPath $stdout -PathType Leaf) {
+        $guiOutput = $null
+        try {
+          $stream = [IO.FileStream]::new($stdout, [IO.FileMode]::Open, [IO.FileAccess]::Read, [IO.FileShare]::ReadWrite)
+          try {
+            $reader = [IO.StreamReader]::new($stream)
+            try { $guiOutput = $reader.ReadToEnd() } finally { $reader.Dispose() }
+          } finally { $stream.Dispose() }
+        } catch [IO.IOException] {
+          $guiOutput = $null
+        }
+        if ($guiOutput -eq $null) { Start-Sleep -Milliseconds 200; continue }
+        $match = [regex]::Match($guiOutput, '(?s)\{\s*"status"\s*:\s*"listening"\s*,\s*"url"\s*:\s*"(?<url>[^"]+)"\s*\}\s*$')
+        if ($match.Success -and $match.Groups['url'].Value -eq 'http://127.0.0.1:11451/') {
+          $readyUrl = $match.Groups['url'].Value
+          break
+        }
+      }
+      Start-Sleep -Milliseconds 200
+    } while ([DateTime]::UtcNow -lt $deadline)
+    $process.Refresh()
+    if ($readyUrl -eq $null -or $process.HasExited) {
+      if (-not $process.HasExited) { Stop-Process -Id $process.Id -Force -ErrorAction SilentlyContinue }
+      throw 'E_GUI_START_FAILED: GUI 未在 20 秒内返回 project-bound listening receipt；已安装项目保持不变'
+    }
+    $guiReceipt = [ordered]@{ schema_version = 1; status = 'ready'; process_id = $process.Id; url = $readyUrl; no_open = ($env:WORLDENGINE_SETUP_NO_OPEN -eq '1') }
+    $guiReceipt | ConvertTo-Json | Set-Content -LiteralPath (Join-Path $target '.worldengine\operations\gui-bootstrap.json') -Encoding UTF8
+  }
+} finally {
+  if ((Test-Path -LiteralPath $temporaryOwner -PathType Leaf) -and
+      ([IO.File]::ReadAllText($temporaryOwner) -eq $temporaryIdentity) -and
+      ((Split-Path -Parent $temporaryRoot).Equals($targetParent, [StringComparison]::OrdinalIgnoreCase))) {
+    Remove-Item -LiteralPath $temporaryRoot -Recurse -Force -ErrorAction SilentlyContinue
+  }
+}
+`;
+}
+function batchHeader(powerShell) {
+    const loader = `$content=[IO.File]::ReadAllText($env:WORLDENGINE_SETUP_CMD);$psMarker='${POWERSHELL_MARKER}'+[Environment]::NewLine;$payloadMarker='${PAYLOAD_MARKER}'+[Environment]::NewLine;$start=$content.IndexOf($psMarker,[StringComparison]::Ordinal);$end=$content.IndexOf($payloadMarker,[StringComparison]::Ordinal);if($start -lt 0 -or $end -le $start){throw 'E_PAYLOAD_INVALID: CMD markers'};&([scriptblock]::Create($content.Substring($start+$psMarker.Length,$end-$start-$psMarker.Length)))`;
+    const encodedLoader = Buffer.from(loader, "utf16le").toString("base64");
+    return `@echo off
+setlocal EnableExtensions DisableDelayedExpansion
+set "WORLDENGINE_SETUP_CMD=%~f0"
+set "WORLDENGINE_SETUP_DIR=%~dp0"
+set "WORLDENGINE_SETUP_NO_START=0"
+set "WORLDENGINE_SETUP_NO_OPEN=0"
+if not "%~1"=="" (
+  if /I "%~1"=="--no-start" (
+    set "WORLDENGINE_SETUP_NO_START=1"
+  ) else if /I "%~1"=="--no-open" (
+    set "WORLDENGINE_SETUP_NO_OPEN=1"
+  ) else (
+    echo E_ARGUMENT_UNKNOWN: %~1 1>&2
+    exit /b 2
+  )
+)
+if not "%~2"=="" (
+  if /I "%~2"=="--no-start" (
+    set "WORLDENGINE_SETUP_NO_START=1"
+  ) else if /I "%~2"=="--no-open" (
+    set "WORLDENGINE_SETUP_NO_OPEN=1"
+  ) else (
+    echo E_ARGUMENT_UNKNOWN: %~2 1>&2
+    exit /b 2
+  )
+)
+if not "%~3"=="" (
+  echo E_ARGUMENT_UNKNOWN: %~3 1>&2
+  exit /b 2
+)
+:run
+powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encodedLoader}
+exit /b %ERRORLEVEL%
+${POWERSHELL_MARKER}
+${powerShell.trimStart()}`.replaceAll("\n", "\r\n");
+}
+export async function buildStandaloneSetupCmd({ payloadRoot, outputFile, testOnlySkipInstall = false, }) {
+    const root = resolve(payloadRoot);
+    const output = resolve(outputFile);
+    const manifest = await inspectSetupPayload(root);
+    const archive = zipPayload(await payloadFiles(root));
+    const archiveSha256 = createHash("sha256").update(archive).digest("hex");
+    const base64 = archive.toString("base64").match(/.{1,76}/g)?.join("\r\n") ?? "";
+    const command = `${batchHeader(powershellScript(manifest.release_identity, manifest.node.version, archiveSha256, testOnlySkipInstall))}\r\n${PAYLOAD_MARKER}\r\n${base64}\r\n`;
+    await writeFile(output, command, { encoding: "utf8", flag: "wx" });
+    return {
+        schema_version: 1,
+        output_file: output,
+        release_identity: manifest.release_identity,
+        node_version: manifest.node.version,
+        payload_archive_sha256: archiveSha256,
+        payload_archive_size: archive.length,
+        test_only: testOnlySkipInstall,
+    };
+}

package/dist/toolchain-manifest.d.ts

@@ -0,0 +1,43 @@
+import { type WorldEngineNodePackageName } from "./package-catalog.js";
+/**
+ * payload 中唯一的 first-party package 闭包。这里是 release-stage 的输入边界，
+ * 不是 workspace package.json 的第二份依赖权威。
+ */
+export declare const TOOLCHAIN_FIRST_PARTY_PACKAGES: readonly string[];
+export type ToolchainFirstPartyPackage = WorldEngineNodePackageName;
+export declare const TOOLCHAIN_MANIFEST_FILE = "toolchain-manifest.json";
+export interface ToolchainPackageV1 {
+    readonly name: ToolchainFirstPartyPackage;
+    readonly version: string;
+    readonly archive: string;
+    readonly sha256: string;
+    readonly license_sha256: string;
+    /** build 前后读回一致的 package source postimage。 */
+    readonly source_sha256: string;
+}
+export interface ToolchainManifestV1 {
+    readonly schema_version: 1;
+    /** 所有 tarball（first-party 与其锁定的第三方）数量；payload 以此拒绝 closure 漂移。 */
+    readonly tarball_count: number;
+    readonly packages: readonly ToolchainPackageV1[];
+}
+export interface PackToolchainInput {
+    readonly output_directory: string;
+    readonly license_file: string;
+    readonly package_directories: Readonly<Record<ToolchainFirstPartyPackage, string>>;
+    readonly source_sha256_by_package: Readonly<Record<ToolchainFirstPartyPackage, string>>;
+    readonly catalog: Readonly<Record<string, string>>;
+    readonly npm_executable?: string;
+}
+/** 只读取 npm tarball 中的具名文件，避免把 archive 解到工作区。 */
+export declare function readPackedFile(archive: Uint8Array, expectedPath: string): Uint8Array;
+/** 只解析 npm tarball 中的 package/package.json，避免把 archive 解到工作区。 */
+export declare function readPackedPackageManifest(archive: Uint8Array): Record<string, unknown>;
+export declare function createToolchainManifest(sourceDirectory: string): Promise<ToolchainManifestV1>;
+export declare function writeToolchainManifest(sourceDirectory: string): Promise<ToolchainManifestV1>;
+export declare function readToolchainManifest(sourceDirectory: string): Promise<ToolchainManifestV1>;
+/**
+ * 在隔离副本中投影 workspace/catalog，随后用 npm pack 生成可被非 pnpm 客户端消费的包。
+ * 这里不修改源码 package.json；catalog 仍只由根 pnpm-workspace.yaml 定义。
+ */
+export declare function packFirstPartyToolchain(input: PackToolchainInput): Promise<ToolchainManifestV1>;

package/dist/toolchain-manifest.js

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { copyFile, cp, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { gunzipSync } from "node:zlib";
+import { WORLDENGINE_NODE_PACKAGE_NAMES } from "./package-catalog.js";
+const execFileAsync = promisify(execFile);
+/**
+ * payload 中唯一的 first-party package 闭包。这里是 release-stage 的输入边界，
+ * 不是 workspace package.json 的第二份依赖权威。
+ */
+export const TOOLCHAIN_FIRST_PARTY_PACKAGES = WORLDENGINE_NODE_PACKAGE_NAMES;
+export const TOOLCHAIN_MANIFEST_FILE = "toolchain-manifest.json";
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function packageSlug(name) {
+    return name.replace(/^@/, "").replaceAll("/", "-");
+}
+function assertProjectedSpecifier(specifier, dependency) {
+    if (typeof specifier !== "string" || specifier.length === 0) {
+        throw new Error(`toolchain_dependency_specifier_invalid:${dependency}`);
+    }
+    if (/^(?:workspace:|catalog:|file:|link:)/.test(specifier)) {
+        throw new Error(`toolchain_dependency_specifier_unprojected:${dependency}`);
+    }
+}
+function projectSpecifier(specifier, dependency, catalog, packageVersions) {
+    if (specifier === "catalog:") {
+        const resolved = catalog[dependency];
+        if (resolved === undefined)
+            throw new Error(`toolchain_catalog_dependency_missing:${dependency}`);
+        return resolved;
+    }
+    if (specifier === "workspace:*") {
+        const resolved = packageVersions[dependency];
+        if (resolved === undefined)
+            throw new Error(`toolchain_workspace_dependency_missing:${dependency}`);
+        return resolved;
+    }
+    if (typeof specifier === "string" && specifier.startsWith("workspace:")) {
+        const resolved = specifier.slice("workspace:".length);
+        if (/^(?:\^|~)?\d/.test(resolved))
+            return resolved;
+        throw new Error(`toolchain_workspace_dependency_invalid:${dependency}`);
+    }
+    assertProjectedSpecifier(specifier, dependency);
+    return specifier;
+}
+function projectDependencyBlock(value, catalog, packageVersions) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("toolchain_dependency_block_invalid");
+    return Object.fromEntries(Object.entries(value).map(([name, specifier]) => [name, projectSpecifier(specifier, name, catalog, packageVersions)]));
+}
+function projectPackageManifest(value, catalog, packageVersions) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("toolchain_package_json_invalid");
+    const manifest = { ...value };
+    for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+        const projected = projectDependencyBlock(manifest[field], catalog, packageVersions);
+        if (projected !== undefined)
+            manifest[field] = projected;
+    }
+    return manifest;
+}
+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, "");
+}
+/** 只读取 npm tarball 中的具名文件，避免把 archive 解到工作区。 */
+export function readPackedFile(archive, expectedPath) {
+    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 === expectedPath)
+            return new Uint8Array(tar.subarray(contentStart, contentStart + size));
+        offset = contentStart + Math.ceil(size / 512) * 512;
+    }
+    throw new Error(`toolchain_packed_file_missing:${expectedPath}`);
+}
+/** 只解析 npm tarball 中的 package/package.json，避免把 archive 解到工作区。 */
+export function readPackedPackageManifest(archive) {
+    const parsed = JSON.parse(new TextDecoder().decode(readPackedFile(archive, "package/package.json")));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        throw new Error("toolchain_packed_package_json_invalid");
+    return parsed;
+}
+function packageIdentity(manifest, archive, bytes) {
+    const name = manifest.name;
+    const version = manifest.version;
+    if (!TOOLCHAIN_FIRST_PARTY_PACKAGES.includes(name)) {
+        if (typeof name === "string" && /^@(?:chat|world-engines|worldengine)\//.test(name))
+            throw new Error(`toolchain_first_party_package_unexpected:${name}`);
+        return undefined;
+    }
+    if (manifest.private === true)
+        throw new Error(`toolchain_first_party_package_private:${String(name)}`);
+    if (typeof version !== "string" || version.length === 0)
+        throw new Error(`toolchain_package_version_invalid:${String(name)}`);
+    const sourceSha256 = manifest.worldengine_source_sha256;
+    if (typeof sourceSha256 !== "string" || !/^[a-f0-9]{64}$/.test(sourceSha256))
+        throw new Error(`toolchain_package_source_sha256_invalid:${String(name)}`);
+    for (const field of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+        const block = manifest[field];
+        if (block === undefined)
+            continue;
+        if (typeof block !== "object" || block === null || Array.isArray(block))
+            throw new Error(`toolchain_dependency_block_invalid:${String(name)}:${field}`);
+        for (const [dependency, specifier] of Object.entries(block)) {
+            assertProjectedSpecifier(specifier, `${String(name)}:${dependency}`);
+            if (/^@(?:chat|world-engines|worldengine)\//.test(dependency) && !TOOLCHAIN_FIRST_PARTY_PACKAGES.includes(dependency)) {
+                throw new Error(`toolchain_first_party_dependency_missing:${String(name)}:${dependency}`);
+            }
+        }
+    }
+    const licenseBytes = readPackedFile(bytes, "package/LICENSE");
+    return { name: name, version, archive, sha256: sha256(bytes), license_sha256: sha256(licenseBytes), source_sha256: sourceSha256 };
+}
+export async function createToolchainManifest(sourceDirectory) {
+    const source = resolve(sourceDirectory);
+    const entries = await readdir(source, { withFileTypes: true });
+    const archives = entries.filter((entry) => entry.isFile() && entry.name.endsWith(".tgz")).sort((left, right) => left.name.localeCompare(right.name, "en"));
+    if (archives.length === 0)
+        throw new Error("toolchain_tarball_closure_empty");
+    const inspected = await Promise.all(archives.map(async (entry) => {
+        const bytes = new Uint8Array(await readFile(join(source, entry.name)));
+        const packed = readPackedPackageManifest(bytes);
+        return packageIdentity(packed, entry.name, bytes);
+    }));
+    const packages = inspected.filter((item) => item !== undefined);
+    const names = new Set(packages.map(({ name }) => name));
+    for (const name of TOOLCHAIN_FIRST_PARTY_PACKAGES) {
+        if (!names.has(name))
+            throw new Error(`toolchain_first_party_package_missing:${name}`);
+    }
+    if (packages.length !== names.size)
+        throw new Error("toolchain_first_party_package_duplicate");
+    if (new Set(packages.map(({ license_sha256 }) => license_sha256)).size !== 1)
+        throw new Error("toolchain_package_license_drift");
+    return { schema_version: 1, tarball_count: archives.length, packages: packages.sort((left, right) => left.name.localeCompare(right.name, "en")) };
+}
+export async function writeToolchainManifest(sourceDirectory) {
+    const source = resolve(sourceDirectory);
+    const manifest = await createToolchainManifest(source);
+    await writeFile(join(source, TOOLCHAIN_MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+    return manifest;
+}
+export async function readToolchainManifest(sourceDirectory) {
+    const source = resolve(sourceDirectory);
+    const raw = JSON.parse(await readFile(join(source, TOOLCHAIN_MANIFEST_FILE), "utf8"));
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("toolchain_manifest_invalid");
+    const manifest = raw;
+    if (manifest.schema_version !== 1 || !Number.isSafeInteger(manifest.tarball_count) || manifest.tarball_count < TOOLCHAIN_FIRST_PARTY_PACKAGES.length || !Array.isArray(manifest.packages))
+        throw new Error("toolchain_manifest_invalid");
+    const actual = await createToolchainManifest(source);
+    if (JSON.stringify(actual) !== JSON.stringify(manifest))
+        throw new Error("toolchain_manifest_drift");
+    return manifest;
+}
+/**
+ * 在隔离副本中投影 workspace/catalog，随后用 npm pack 生成可被非 pnpm 客户端消费的包。
+ * 这里不修改源码 package.json；catalog 仍只由根 pnpm-workspace.yaml 定义。
+ */
+export async function packFirstPartyToolchain(input) {
+    const output = resolve(input.output_directory);
+    await mkdir(output, { recursive: true });
+    if ((await readdir(output)).length !== 0)
+        throw new Error("toolchain_output_not_empty");
+    const suppliedNames = Object.keys(input.package_directories);
+    if (suppliedNames.length !== TOOLCHAIN_FIRST_PARTY_PACKAGES.length || TOOLCHAIN_FIRST_PARTY_PACKAGES.some((name) => !suppliedNames.includes(name))) {
+        throw new Error("toolchain_package_directories_incomplete");
+    }
+    if (Object.keys(input.source_sha256_by_package).length !== TOOLCHAIN_FIRST_PARTY_PACKAGES.length || TOOLCHAIN_FIRST_PARTY_PACKAGES.some((name) => !/^[a-f0-9]{64}$/.test(input.source_sha256_by_package[name] ?? ""))) {
+        throw new Error("toolchain_source_postimage_incomplete");
+    }
+    const packageVersions = {};
+    for (const [name, directory] of Object.entries(input.package_directories)) {
+        const source = JSON.parse(await readFile(join(resolve(directory), "package.json"), "utf8"));
+        if (source.name !== name || typeof source.version !== "string")
+            throw new Error(`toolchain_source_package_invalid:${name}`);
+        packageVersions[name] = source.version;
+    }
+    const staging = join(output, ".staging");
+    await mkdir(staging);
+    try {
+        for (const [name, directory] of Object.entries(input.package_directories)) {
+            const source = resolve(directory);
+            const projected = join(staging, packageSlug(name));
+            await cp(source, projected, { recursive: true, force: false, filter: (entry) => !relative(source, entry).split(/[/\\]/).includes("node_modules") });
+            const packageJson = projectPackageManifest(JSON.parse(await readFile(join(source, "package.json"), "utf8")), input.catalog, packageVersions);
+            if (packageJson.license !== "SEE LICENSE IN LICENSE")
+                throw new Error(`toolchain_package_license_invalid:${name}`);
+            packageJson.worldengine_source_sha256 = input.source_sha256_by_package[name];
+            await writeFile(join(projected, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
+            await copyFile(resolve(input.license_file), join(projected, "LICENSE"));
+            const executable = resolve(input.npm_executable ?? process.execPath);
+            const npmCli = join(dirname(executable), "node_modules", "npm", "bin", "npm-cli.js");
+            await execFileAsync(executable, [npmCli, "pack", "--ignore-scripts", "--pack-destination", output], { cwd: projected, windowsHide: true });
+            const generated = (await readdir(output)).filter((entry) => entry.endsWith(".tgz")).find((entry) => entry.startsWith(packageSlug(name)));
+            if (generated === undefined)
+                throw new Error(`toolchain_pack_missing:${name}`);
+            const archive = new Uint8Array(await readFile(join(output, generated)));
+            const destination = `${packageSlug(name)}-sha256-${sha256(archive)}.tgz`;
+            await rename(join(output, generated), join(output, destination));
+        }
+        return await writeToolchainManifest(output);
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}

package/dist/worldengine-package-catalog.json

@@ -0,0 +1,23 @@
+{
+  "schema_version": 1,
+  "packages": [
+    { "name": "@world-engines/blocks-editor", "directory": "packages/blocks-editor", "runtime": "browser" },
+    { "name": "@world-engines/ladybug-bridge", "directory": "packages/ladybug-bridge" },
+    { "name": "@world-engines/monaco-host", "directory": "packages/monaco-host", "runtime": "browser" },
+    { "name": "@world-engines/protocol-ts", "directory": "packages/protocol-ts" },
+    { "name": "@world-engines/scenario-author-source", "directory": "packages/scenario-author-source" },
+    { "name": "@world-engines/scenario-review-snapshot", "directory": "packages/scenario-review-snapshot" },
+    { "name": "@world-engines/tmw", "directory": "packages/tmw" },
+    { "name": "@world-engines/view-exposure", "directory": "packages/view-exposure" },
+    { "name": "@world-engines/chatplay-vite-plugin", "directory": "packages/chatplay-vite-plugin" },
+    { "name": "@world-engines/agent-kit", "directory": "packages/worldengine-agent-kit", "build_dependencies": ["@world-engines/authoring-bridge"] },
+    { "name": "@world-engines/authoring-bridge", "directory": "packages/worldengine-authoring-bridge" },
+    { "name": "@world-engines/authoring-ui", "directory": "packages/worldengine-authoring-ui", "runtime": "browser" },
+    { "name": "@world-engines/create-project", "directory": "packages/worldengine-create-project" },
+    { "name": "@world-engines/project-format", "directory": "packages/worldengine-project-format" },
+    { "name": "@world-engines/project-host", "directory": "packages/worldengine-project-host", "build_dependencies": ["@world-engines/authoring-ui"] },
+    { "name": "@world-engines/project-setup", "directory": "tools/worldengine-project-setup" },
+    { "name": "@world-engines/spatial-authoring", "directory": "packages/worldengine-spatial-authoring" },
+    { "name": "@world-engines/view-sdk", "directory": "packages/worldengine-view-sdk" }
+  ]
+}