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

package/dist/cli/dump.d.ts

@@ -0,0 +1,32 @@
+import type { LocalProjectHost } from "../project-host.js";
+export type DocumentDumpInvocation = Readonly<{
+    documentId: string;
+    outputDirectory: string;
+}>;
+export declare function parseDocumentDumpInvocation(args: readonly string[]): DocumentDumpInvocation;
+/** 文件先 fsync，再通过 hardlink 原子发布；目标已存在时绝不替换，manifest 最后提交。 */
+export declare function writeDocumentPlainTextDump(host: LocalProjectHost, invocation: DocumentDumpInvocation): Promise<{
+    schemaVersion: number;
+    documentId: string;
+    outputDirectory: string;
+    files: Readonly<{
+        name: string;
+        path: string;
+        byteLength: number;
+        sha256: string;
+    }>[];
+    integrity: "incomplete" | "verified";
+    source: {
+        integrityStatus: "verified";
+        byteLength: number;
+        sha256: string;
+        utf16Length: number;
+        unicodeCodePoints: number;
+        hanCharacters: number;
+    };
+    counts: {
+        nodes: number;
+        edges: number;
+        chunks: number;
+    };
+}>;

package/dist/cli/dump.js

@@ -0,0 +1,91 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, open, readFile, unlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { createDocumentPlainTextDump } from "../document-dump.js";
+import { assertSafeExistingProjectPath, ensureSafeProjectDirectory, safeProjectPath } from "../safe-project-path.js";
+export function parseDocumentDumpInvocation(args) {
+    const [documentId, outputDirectory] = args;
+    if (args.length !== 2 || documentId === undefined || documentId.length === 0 || documentId.trim() !== documentId
+        || /[\u0000-\u001f\u007f]/u.test(documentId) || outputDirectory === undefined) {
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "dump 需要 document-id 和项目内新目录");
+    }
+    const parts = outputDirectory.split(/[\\/]/u);
+    if (isAbsolute(outputDirectory) || parts.some((part) => part.length === 0 || part === "." || part === ".."
+        || part.trim() !== part || /[<>:"|?*\u0000-\u001f\u007f]/u.test(part) || /[. ]$/u.test(part))) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "dump 只接受项目内新目录");
+    }
+    return { documentId, outputDirectory: parts.join("/") };
+}
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** 文件先 fsync，再通过 hardlink 原子发布；目标已存在时绝不替换，manifest 最后提交。 */
+export async function writeDocumentPlainTextDump(host, invocation) {
+    const requested = parseDocumentDumpInvocation([invocation.documentId, invocation.outputDirectory]);
+    const parentRelative = dirname(requested.outputDirectory);
+    // safeProjectPath 会提前拒绝已存在的 junction；不得把它作为递归 mkdir 的替代。
+    await safeProjectPath(host.root, requested.outputDirectory);
+    const dump = await createDocumentPlainTextDump(host, { documentId: requested.documentId });
+    if (parentRelative !== ".")
+        await ensureSafeProjectDirectory(host.root, parentRelative);
+    const directory = await safeProjectPath(host.root, requested.outputDirectory);
+    await assertSafeExistingProjectPath(host.root, dirname(directory));
+    try {
+        await mkdir(directory);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "dump 目标目录已存在；拒绝覆盖");
+        throw error;
+    }
+    await assertSafeExistingProjectPath(host.root, directory);
+    const identity = await lstat(directory);
+    const assertOwnedDirectory = async () => {
+        await assertSafeExistingProjectPath(host.root, directory);
+        const current = await lstat(directory);
+        if (!current.isDirectory() || current.dev !== identity.dev || current.ino !== identity.ino) {
+            throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "dump 输出目录 identity 已改变");
+        }
+    };
+    const encoder = new TextEncoder();
+    const artifacts = [
+        { name: "source.txt", bytes: dump.sourceBytes },
+        { name: "graph.txt", bytes: encoder.encode(dump.graphText) },
+        { name: "review.txt", bytes: encoder.encode(dump.reviewText) },
+        { name: "manifest.json", bytes: encoder.encode(`${JSON.stringify(dump.manifest, null, 2)}\n`) },
+    ];
+    const files = [];
+    for (const artifact of artifacts) {
+        await assertOwnedDirectory();
+        const temporary = join(directory, `.${artifact.name}.${randomUUID()}.tmp`);
+        const target = join(directory, artifact.name);
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(artifact.bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await assertOwnedDirectory();
+        await assertSafeExistingProjectPath(host.root, temporary);
+        await link(temporary, target);
+        await assertOwnedDirectory();
+        await assertSafeExistingProjectPath(host.root, target);
+        const written = await readFile(target);
+        if (written.byteLength !== artifact.bytes.byteLength || digest(written) !== digest(artifact.bytes)) {
+            throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", "dump 文件读回不一致");
+        }
+        await assertSafeExistingProjectPath(host.root, temporary);
+        await unlink(temporary);
+        files.push({ name: artifact.name, path: relative(host.root, target).split(sep).join("/"), byteLength: written.byteLength, sha256: digest(written) });
+    }
+    return {
+        schemaVersion: 1,
+        documentId: requested.documentId,
+        outputDirectory: requested.outputDirectory,
+        files,
+        integrity: dump.manifest.integrity.status,
+        source: dump.manifest.source,
+        counts: { nodes: dump.manifest.graph.nodeCount, edges: dump.manifest.graph.edgeCount, chunks: dump.manifest.chunks.count },
+    };
+}

package/dist/cli/ingest.d.ts

@@ -0,0 +1,49 @@
+import type { NaturalLanguageSource } from "@world-engines/tmw/natural-language-ingestion";
+/** 原文会以 base64 进入 durable staging；在读取前限制单文件，避免无界占用 Host 内存与 journal。 */
+export declare const MAX_DOCUMENT_SOURCE_BYTES: number;
+export type ProjectDocumentIngestInvocation = Readonly<{
+    sourcePath: string;
+    scopeId: string;
+    sourceId: string;
+    sourceRevision: string;
+}>;
+export type ProjectDocumentOperationInvocation = Readonly<{
+    kind: "status" | "resume";
+    operationId: string;
+}>;
+export type ResolvedPathOnlyProjectDocumentIngest = Readonly<{
+    /** 稳定的单路径 identity：以项目隔离，绝不使用时间戳或随机值。 */
+    invocation: ProjectDocumentIngestInvocation;
+    source: LoadedProjectDocumentBytes;
+}>;
+/** status/resume 只消费 durable operation ID，不接受文件、凭据或新的 source identity。 */
+export declare function parseProjectDocumentOperationInvocation(args: readonly string[]): ProjectDocumentOperationInvocation;
+export type LoadedProjectDocumentBytes = Readonly<{
+    bytes: Uint8Array;
+    /** 稳定逻辑来源；外部来源不暴露绝对路径，也不随 content revision 改变。 */
+    sourcePath: string;
+    /** 外部来源的项目内逐字节副本；项目内来源省略。 */
+    sourceStoragePath?: string;
+    scopeId: string;
+    sourceId: string;
+    sourceRevision: string;
+    mediaType: "text/plain" | "text/markdown";
+}>;
+/** CLI route owner 消费的稳定 positional contract：ingest <path> <scope-id> <source-id> <source-revision>。 */
+export declare function parseProjectDocumentIngestInvocation(args: readonly string[]): ProjectDocumentIngestInvocation;
+/**
+ * `ingest <path>` is deliberately a preparation-only convenience entrypoint.
+ * The project manifest isolates the scope, the logical path identifies a source,
+ * and the original byte digest is its revision.  It neither invokes a model nor
+ * accepts/commits a harness candidate.
+ */
+export declare function resolvePathOnlyProjectDocumentIngest(cwd: string, sourcePath: string): Promise<ResolvedPathOnlyProjectDocumentIngest>;
+export declare function loadProjectDocumentSource(cwd: string, invocation: ProjectDocumentIngestInvocation): Promise<NaturalLanguageSource>;
+export declare function projectDocumentBytesToSource(loaded: LoadedProjectDocumentBytes): NaturalLanguageSource;
+/** D4F 默认入口保留原始 bytes；fatal UTF-8 只验证，不做 NFC 或换行重写。 */
+export declare function loadProjectDocumentBytes(cwd: string, invocation: ProjectDocumentIngestInvocation): Promise<LoadedProjectDocumentBytes>;
+/**
+ * 用户可从项目外选择最终原文；Host 把 bytes 原样导入项目内 content-addressed 路径，
+ * 不覆盖、移动或修改外部文件。discussion/废案不会调用本函数。
+ */
+export declare function stageProjectDocumentBytes(cwd: string, invocation: ProjectDocumentIngestInvocation): Promise<LoadedProjectDocumentBytes>;

package/dist/cli/ingest.js

@@ -0,0 +1,225 @@
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, open, readFile, realpath, rm, stat } from "node:fs/promises";
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
+import { validateLocalAuthorProjectManifest } from "@world-engines/project-format";
+import { assertSafeExistingProjectPath, ensureSafeProjectDirectory, safeProjectPath } from "../safe-project-path.js";
+/** 原文会以 base64 进入 durable staging；在读取前限制单文件，避免无界占用 Host 内存与 journal。 */
+export const MAX_DOCUMENT_SOURCE_BYTES = 64 * 1024 * 1024;
+/** status/resume 只消费 durable operation ID，不接受文件、凭据或新的 source identity。 */
+export function parseProjectDocumentOperationInvocation(args) {
+    const [kind, operationId] = args;
+    if (args.length !== 2 || (kind !== "status" && kind !== "resume") || operationId === undefined
+        || operationId.length === 0 || operationId.length > 512 || operationId.trim() !== operationId
+        || operationId.normalize("NFC") !== operationId || /[\u0000-\u001f\u007f]/u.test(operationId)) {
+        throw new Error("ingest_operation_args_invalid");
+    }
+    return Object.freeze({ kind, operationId });
+}
+/** CLI route owner 消费的稳定 positional contract：ingest <path> <scope-id> <source-id> <source-revision>。 */
+export function parseProjectDocumentIngestInvocation(args) {
+    if (args.length !== 4 || args.some((value) => value.length === 0 || value.trim() !== value || value.normalize("NFC") !== value)) {
+        throw new Error("ingest_args_invalid");
+    }
+    return Object.freeze({ sourcePath: args[0], scopeId: args[1], sourceId: args[2], sourceRevision: args[3] });
+}
+/**
+ * `ingest <path>` is deliberately a preparation-only convenience entrypoint.
+ * The project manifest isolates the scope, the logical path identifies a source,
+ * and the original byte digest is its revision.  It neither invokes a model nor
+ * accepts/commits a harness candidate.
+ */
+export async function resolvePathOnlyProjectDocumentIngest(cwd, sourcePath) {
+    if (sourcePath.length === 0 || sourcePath.trim() !== sourcePath || sourcePath.normalize("NFC") !== sourcePath) {
+        throw new Error("ingest_path_only_args_invalid");
+    }
+    const projectRoot = await realpath(resolve(cwd));
+    const manifestPath = await assertSafeExistingProjectPath(projectRoot, resolve(projectRoot, "worldengine.project.json"));
+    const manifest = validateLocalAuthorProjectManifest(JSON.parse(await readFile(manifestPath, "utf8")));
+    // staging 独占带守卫的单次读取。这些临时 identity 不会持久化；读取后替换可避免第二次读文件。
+    const staged = await stageProjectDocumentBytes(projectRoot, {
+        sourcePath,
+        scopeId: "path-only-staging",
+        sourceId: "path-only-staging",
+        sourceRevision: "path-only-staging",
+    });
+    const projectIdentity = sha256Text(manifest.project_id);
+    const pathIdentity = sha256Text(staged.sourcePath);
+    const contentIdentity = createHash("sha256").update(staged.bytes).digest("hex");
+    const invocation = Object.freeze({
+        sourcePath,
+        scopeId: `project:${projectIdentity}`,
+        sourceId: `document:${pathIdentity}`,
+        sourceRevision: `bytes:${contentIdentity}`,
+    });
+    return Object.freeze({
+        invocation,
+        source: Object.freeze({ ...staged, ...invocation, sourcePath: staged.sourcePath }),
+    });
+}
+export async function loadProjectDocumentSource(cwd, invocation) {
+    const loaded = await loadProjectDocumentBytes(cwd, invocation);
+    return projectDocumentBytesToSource(loaded);
+}
+export function projectDocumentBytesToSource(loaded) {
+    return Object.freeze({
+        scopeId: loaded.scopeId,
+        sourceId: loaded.sourceId,
+        sourceRevision: loaded.sourceRevision,
+        sourcePath: loaded.sourcePath,
+        text: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(loaded.bytes),
+        mediaType: loaded.mediaType,
+    });
+}
+/** D4F 默认入口保留原始 bytes；fatal UTF-8 只验证，不做 NFC 或换行重写。 */
+export async function loadProjectDocumentBytes(cwd, invocation) {
+    const projectRoot = await realpath(resolve(cwd));
+    const sourcePath = await assertSafeExistingProjectPath(projectRoot, resolve(projectRoot, invocation.sourcePath));
+    const extension = extname(sourcePath).toLowerCase();
+    if (extension !== ".md" && extension !== ".markdown" && extension !== ".txt")
+        throw new Error("ingest_media_type_invalid");
+    const sourceInfo = await lstat(sourcePath);
+    if (!sourceInfo.isFile() || sourceInfo.isSymbolicLink())
+        throw new Error("ingest_source_file_invalid");
+    const handle = await open(sourcePath, "r");
+    let bytes;
+    try {
+        const before = await handle.stat();
+        if (before.size > MAX_DOCUMENT_SOURCE_BYTES)
+            throw new Error("ingest_source_too_large");
+        bytes = new Uint8Array(await handle.readFile());
+        const after = await handle.stat();
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs
+            || bytes.byteLength !== after.size || after.size > MAX_DOCUMENT_SOURCE_BYTES)
+            throw new Error("ingest_source_changed_during_read");
+    }
+    finally {
+        await handle.close();
+    }
+    assertTextDocumentBytes(bytes);
+    return Object.freeze({
+        bytes,
+        scopeId: invocation.scopeId,
+        sourceId: invocation.sourceId,
+        sourceRevision: invocation.sourceRevision,
+        sourcePath: invocation.sourcePath.replaceAll("\\", "/"),
+        mediaType: extension === ".txt" ? "text/plain" : "text/markdown",
+    });
+}
+function sameBytes(left, right) {
+    return left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index]);
+}
+/**
+ * 用户可从项目外选择最终原文；Host 把 bytes 原样导入项目内 content-addressed 路径，
+ * 不覆盖、移动或修改外部文件。discussion/废案不会调用本函数。
+ */
+export async function stageProjectDocumentBytes(cwd, invocation) {
+    const projectRoot = await realpath(resolve(cwd));
+    const requestedSource = resolve(projectRoot, invocation.sourcePath);
+    const relativeSource = relative(projectRoot, requestedSource);
+    const insideProject = relativeSource !== "" && relativeSource !== ".." && !relativeSource.startsWith(`..${sep}`)
+        && !isAbsolute(relativeSource);
+    let openedPath = insideProject
+        ? await assertSafeExistingProjectPath(projectRoot, requestedSource)
+        : requestedSource;
+    let externalInfo;
+    if (!insideProject) {
+        const sourceInfo = await lstat(openedPath);
+        if (!sourceInfo.isFile() || sourceInfo.isSymbolicLink())
+            throw new Error("ingest_source_file_invalid");
+        // 固定在已经解析的普通文件上读取。即使调用方路径在随后被替换，也不能借由 path TOCTOU
+        // 改变本次导入的对象或转向链接目标。
+        openedPath = await realpath(openedPath);
+        externalInfo = await lstat(openedPath);
+        if (!externalInfo.isFile() || externalInfo.isSymbolicLink()
+            || externalInfo.dev !== sourceInfo.dev || externalInfo.ino !== sourceInfo.ino) {
+            throw new Error("ingest_source_identity_changed");
+        }
+    }
+    const extension = extname(openedPath).toLowerCase();
+    if (extension !== ".md" && extension !== ".markdown" && extension !== ".txt")
+        throw new Error("ingest_media_type_invalid");
+    const sourceHandle = await open(openedPath, "r");
+    let bytes;
+    try {
+        const before = await sourceHandle.stat();
+        if (!before.isFile())
+            throw new Error("ingest_source_file_invalid");
+        if (before.size > MAX_DOCUMENT_SOURCE_BYTES)
+            throw new Error("ingest_source_too_large");
+        if (externalInfo !== undefined && (before.dev !== externalInfo.dev || before.ino !== externalInfo.ino)) {
+            throw new Error("ingest_source_identity_changed");
+        }
+        if (insideProject) {
+            const revalidated = await assertSafeExistingProjectPath(projectRoot, requestedSource);
+            const pathInfo = await stat(revalidated);
+            if (before.dev !== pathInfo.dev || before.ino !== pathInfo.ino)
+                throw new Error("ingest_source_identity_changed");
+        }
+        bytes = new Uint8Array(await sourceHandle.readFile());
+        const after = await sourceHandle.stat();
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs
+            || bytes.byteLength !== after.size || after.size > MAX_DOCUMENT_SOURCE_BYTES)
+            throw new Error("ingest_source_changed_during_read");
+    }
+    finally {
+        await sourceHandle.close();
+    }
+    assertTextDocumentBytes(bytes);
+    const loaded = Object.freeze({ bytes,
+        sourcePath: insideProject ? relativeSource.split(sep).join("/") : `external-source/${sha256Path(requestedSource)}${extension}`,
+        scopeId: invocation.scopeId, sourceId: invocation.sourceId, sourceRevision: invocation.sourceRevision,
+        mediaType: extension === ".txt" ? "text/plain" : "text/markdown" });
+    if (insideProject) {
+        return loaded;
+    }
+    const digest = createHash("sha256").update(loaded.bytes).digest("hex");
+    await ensureSafeProjectDirectory(projectRoot, ".worldengine/imported-sources");
+    const destination = await safeProjectPath(projectRoot, `.worldengine/imported-sources/${digest}${extension}`);
+    const temporary = await safeProjectPath(projectRoot, `.worldengine/imported-sources/.${digest}.${randomUUID()}.tmp`);
+    const stagingHandle = await open(temporary, "wx");
+    try {
+        await stagingHandle.writeFile(loaded.bytes);
+        await stagingHandle.sync();
+    }
+    catch (error) {
+        await stagingHandle.close();
+        await rm(temporary, { force: true });
+        throw error;
+    }
+    await stagingHandle.close();
+    try {
+        try {
+            await link(temporary, destination);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        await assertSafeExistingProjectPath(projectRoot, destination);
+        const readback = new Uint8Array(await readFile(destination));
+        if (!sameBytes(readback, loaded.bytes))
+            throw new Error("ingest_staged_source_identity_mismatch");
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return Object.freeze({ ...loaded, sourceStoragePath: relative(projectRoot, destination).split(sep).join("/") });
+}
+/** UTF-8 通过不等于可作为原文文本；NUL 是二进制输入的明确拒绝信号。 */
+function assertTextDocumentBytes(bytes) {
+    if (bytes.includes(0))
+        throw new Error("ingest_source_binary");
+    try {
+        new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new Error("ingest_utf8_invalid");
+    }
+}
+function sha256Path(path) {
+    const normalized = path.normalize("NFC").replaceAll("\\", "/");
+    return createHash("sha256").update(process.platform === "win32" ? normalized.toLocaleLowerCase("en-US") : normalized).digest("hex");
+}
+function sha256Text(value) {
+    return createHash("sha256").update(value.normalize("NFC"), "utf8").digest("hex");
+}

package/dist/cli/review.d.ts

@@ -0,0 +1,10 @@
+export type ReviewCliInvocation = Readonly<{
+    kind: "prepare" | "submit";
+    operation_key: string;
+    review_note?: string;
+    release_at?: number;
+}> | Readonly<{
+    kind: "status";
+    operation_key: string;
+}>;
+export declare function parseReviewInvocation(args: readonly string[]): ReviewCliInvocation;

package/dist/cli/review.js

@@ -0,0 +1,44 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+function invalid(message) {
+    throw new AuthoringBridgeError("E_SCHEMA_INVALID", message);
+}
+export function parseReviewInvocation(args) {
+    const [kind, operationKey, ...options] = args;
+    if (kind === "status") {
+        if (operationKey === undefined || options.length !== 0) {
+            invalid("review status <operation-key>");
+        }
+        return Object.freeze({ kind, operation_key: operationKey });
+    }
+    if (kind !== "prepare" && kind !== "submit") {
+        invalid("review 只接受 prepare、submit 或 status");
+    }
+    if (operationKey === undefined) {
+        invalid(`review ${kind} <operation-key> [--review-note <text>] [--release-at-ms <timestamp>]`);
+    }
+    let reviewNote;
+    let releaseAt;
+    for (let index = 0; index < options.length; index += 2) {
+        const flag = options[index];
+        const value = options[index + 1];
+        if (value === undefined)
+            invalid(`review ${kind} 选项缺少值`);
+        if (flag === "--review-note" && reviewNote === undefined && value.trim() === value && value.length > 0) {
+            reviewNote = value;
+            continue;
+        }
+        if (flag === "--release-at-ms" && releaseAt === undefined && /^[1-9][0-9]*$/u.test(value)) {
+            releaseAt = Number(value);
+            if (!Number.isSafeInteger(releaseAt))
+                invalid("--release-at-ms 超过安全整数");
+            continue;
+        }
+        invalid(`review ${kind} 包含未知、重复或无效选项`);
+    }
+    return Object.freeze({
+        kind,
+        operation_key: operationKey,
+        ...(reviewNote === undefined ? {} : { review_note: reviewNote }),
+        ...(releaseAt === undefined ? {} : { release_at: releaseAt }),
+    });
+}

package/dist/cli/upload.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Upload CLI 的纯确认边界。真正的 plan/execute/reconcile 由已注入的 coordinator 完成，
+ * 因此此模块不含 HTTP、认证态或远端 fallback。
+ */
+export interface UploadCliPlan {
+    readonly operation_id: string;
+    readonly plan_digest: string;
+    readonly expires_at: string;
+    readonly target_count: number;
+    readonly part_names: readonly string[];
+}
+export type UploadCliConfirmation = {
+    readonly mode: "interactive";
+} | {
+    readonly mode: "confirm_plan";
+    readonly plan_digest: string;
+};
+export interface UploadCliPublicPlan {
+    readonly operation_id: string;
+    readonly plan_digest: string;
+    readonly expires_at: string;
+    readonly target_count: number;
+    readonly parts: readonly string[];
+}
+export interface UploadCliInvocation {
+    readonly kind: "plan" | "confirm" | "operation" | "reconcile" | "retry" | "undo" | "bind-review-target";
+    readonly operation_id?: string;
+    readonly expires_at_ms?: number;
+    readonly expected_project_revision?: number;
+    readonly targets?: readonly unknown[];
+    readonly plan?: Record<string, unknown>;
+    readonly plan_digest?: string;
+    readonly client_target_key?: string;
+}
+export declare class UploadCliArgumentError extends Error {
+    readonly code = "E_SCHEMA_INVALID";
+}
+export declare class UploadCliConfirmationError extends Error {
+    readonly code = "E_CONFIRMATION_REQUIRED";
+}
+/**
+ * CLI 传回的 frozen plan 必须在进入 coordinator 前完整校验，不能把任意 JSON
+ * 断言成 RemoteUploadPlan。这里保留 wire 原字段，后续由 coordinator 再做 identity
+ * 与 expiry gate。
+ */
+export declare function parseUploadFrozenPlan(value: string | undefined): Record<string, unknown>;
+/** 不带参数表示交互确认；非交互模式只能固定当前 plan digest。 */
+export declare function parseUploadConfirmation(args: readonly string[]): UploadCliConfirmation;
+export declare function toUploadCliPublicPlan(plan: UploadCliPlan): UploadCliPublicPlan;
+/** 在调用 coordinator 前执行 digest/expiry 防护；interactive 回调必须逐目标询问。 */
+export declare function requireUploadConfirmation(plan: UploadCliPlan, confirmation: UploadCliConfirmation, confirmEachTarget: ((plan: UploadCliPublicPlan) => Promise<boolean>) | undefined, now?: Date): Promise<{
+    readonly operation_id: string;
+    readonly plan_digest: string;
+    readonly confirmation: "force_overwrite";
+}>;
+/** upload 的非交互确认仅接受一个已输出并冻结的完整计划。 */
+export declare function parseUploadInvocation(args: readonly string[]): UploadCliInvocation;

package/dist/cli/upload.js

@@ -0,0 +1,112 @@
+export class UploadCliArgumentError extends Error {
+    code = "E_SCHEMA_INVALID";
+}
+export class UploadCliConfirmationError extends Error {
+    code = "E_CONFIRMATION_REQUIRED";
+}
+/**
+ * CLI 传回的 frozen plan 必须在进入 coordinator 前完整校验，不能把任意 JSON
+ * 断言成 RemoteUploadPlan。这里保留 wire 原字段，后续由 coordinator 再做 identity
+ * 与 expiry gate。
+ */
+export function parseUploadFrozenPlan(value) {
+    const plan = parseJson(value, "--plan-json 必须是 JSON frozen plan");
+    const requiredStrings = ["operation_id", "plan_id", "plan_digest", "snapshot_id", "snapshot_digest"];
+    if (requiredStrings.some((key) => typeof plan[key] !== "string" || plan[key].trim() === "")
+        || typeof plan.expires_at_ms !== "number" || !Number.isSafeInteger(plan.expires_at_ms)
+        || !Array.isArray(plan.targets) || !Array.isArray(plan.objects)) {
+        invalid("--plan-json 不是完整 frozen upload plan");
+    }
+    return plan;
+}
+function invalid(message) {
+    throw new UploadCliArgumentError(message);
+}
+/** 不带参数表示交互确认；非交互模式只能固定当前 plan digest。 */
+export function parseUploadConfirmation(args) {
+    if (args.length === 0)
+        return { mode: "interactive" };
+    if (args.length === 2 && args[0] === "--confirm-plan" && args[1].trim() !== "") {
+        return { mode: "confirm_plan", plan_digest: args[1] };
+    }
+    if (args.includes("--force") || args.includes("--yes")) {
+        invalid("upload 不接受裸 --force 或 --yes；请交互确认或使用 --confirm-plan <digest>");
+    }
+    invalid("upload 确认只接受交互模式或 --confirm-plan <digest>");
+}
+export function toUploadCliPublicPlan(plan) {
+    return {
+        operation_id: plan.operation_id,
+        plan_digest: plan.plan_digest,
+        expires_at: plan.expires_at,
+        target_count: plan.target_count,
+        parts: [...plan.part_names],
+    };
+}
+/** 在调用 coordinator 前执行 digest/expiry 防护；interactive 回调必须逐目标询问。 */
+export async function requireUploadConfirmation(plan, confirmation, confirmEachTarget, now = new Date()) {
+    if (!Number.isFinite(Date.parse(plan.expires_at)) || Date.parse(plan.expires_at) <= now.getTime()) {
+        throw new UploadCliConfirmationError("upload plan 已过期；请重新生成计划");
+    }
+    if (confirmation.mode === "confirm_plan") {
+        if (confirmation.plan_digest !== plan.plan_digest)
+            throw new UploadCliConfirmationError("--confirm-plan 与当前 upload plan digest 不匹配");
+    }
+    else {
+        if (confirmEachTarget === undefined || !(await confirmEachTarget(toUploadCliPublicPlan(plan)))) {
+            throw new UploadCliConfirmationError("upload 未获得逐目标明确确认");
+        }
+    }
+    return { operation_id: plan.operation_id, plan_digest: plan.plan_digest, confirmation: "force_overwrite" };
+}
+function parseJson(value, message) {
+    if (value === undefined)
+        invalid(message);
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            invalid(message);
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof UploadCliArgumentError)
+            throw error;
+        invalid(message);
+    }
+}
+/** upload 的非交互确认仅接受一个已输出并冻结的完整计划。 */
+export function parseUploadInvocation(args) {
+    const [command, ...rest] = args;
+    if (command === "plan") {
+        const [operationId, expectedProjectRevision, expiresAtMs, flag, targetsJson, ...extra] = rest;
+        if (!operationId || !/^\d+$/.test(expectedProjectRevision ?? "") || !/^\d+$/.test(expiresAtMs ?? "") || flag !== "--targets-json" || extra.length !== 0)
+            invalid("upload plan <operation-id> <expected-project-revision> <expires-at-ms> --targets-json <targets-json>");
+        const raw = parseJson(targetsJson, "--targets-json 必须是 JSON object {targets:[]}");
+        if (!Array.isArray(raw.targets))
+            invalid("--targets-json 必须含 targets 数组");
+        return { kind: "plan", operation_id: operationId, expected_project_revision: Number(expectedProjectRevision), expires_at_ms: Number(expiresAtMs), targets: raw.targets };
+    }
+    if (command === "confirm") {
+        const [planFlag, planJson, confirmFlag, digest, ...extra] = rest;
+        if (planFlag !== "--plan-json" || extra.length !== 0)
+            invalid("upload confirm --plan-json <frozen-plan-json> [--confirm-plan <digest>]");
+        if (confirmFlag === undefined)
+            return { kind: "confirm", plan: parseUploadFrozenPlan(planJson) };
+        if (confirmFlag !== "--confirm-plan" || !digest)
+            invalid("upload confirm --plan-json <frozen-plan-json> [--confirm-plan <digest>]");
+        return { kind: "confirm", plan: parseUploadFrozenPlan(planJson), plan_digest: digest };
+    }
+    if (command === "operation" || command === "reconcile" || command === "retry" || command === "undo") {
+        if (rest.length !== 1 || !rest[0])
+            invalid(`upload ${command} <operation-id>`);
+        return { kind: command, operation_id: rest[0] };
+    }
+    if (command === "bind-review-target") {
+        const [operationId, flag, clientTargetKey, ...extra] = rest;
+        if (!operationId || extra.length !== 0 || (flag !== undefined && (flag !== "--target" || !clientTargetKey))) {
+            invalid("upload bind-review-target <operation-id> [--target <client-target-key>]");
+        }
+        return { kind: command, operation_id: operationId, ...(clientTargetKey === undefined ? {} : { client_target_key: clientTargetKey }) };
+    }
+    invalid("upload 只接受 plan、confirm、operation、reconcile、retry、undo 或 bind-review-target");
+}