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

package/dist/project-auth.js

@@ -0,0 +1,108 @@
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+function isInside(root, candidate) {
+    const path = relative(root, candidate);
+    return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+function assertInside(root, candidate) {
+    if (!isInside(root, candidate)) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "认证路径逃逸项目根");
+    }
+}
+/** 将任意项目相对位置安全地解析到给定项目根内。 */
+export function resolveProjectAuthPath(projectRoot, projectRelativePath) {
+    const root = resolve(projectRoot);
+    if (isAbsolute(projectRelativePath)) {
+        throw new AuthoringBridgeError("E_PATH_OUTSIDE_PROJECT", "认证路径必须是项目相对路径");
+    }
+    const candidate = resolve(root, projectRelativePath);
+    assertInside(root, candidate);
+    return candidate;
+}
+/** auth 与 WebView profile 固定在项目根，绝不退回到用户目录或共享 app data。 */
+export function resolveProjectAuthPaths(projectRoot) {
+    const root = resolve(projectRoot);
+    return {
+        project_root: root,
+        auth_directory: resolveProjectAuthPath(root, ".worldengine/auth"),
+        webview_data_directory: resolveProjectAuthPath(root, ".worldengine/webview"),
+    };
+}
+/**
+ * 项目级 broker。它不保存会话凭据：没有可用的外部 adapter 时只能保持 signed_out。
+ */
+export class ProjectAuthBroker {
+    identity;
+    paths;
+    #adapter;
+    #state = "signed_out";
+    #challenge;
+    constructor(identity, paths, adapter) {
+        if (!identity.windows_user_id || !identity.project_id) {
+            throw new AuthoringBridgeError("E_SCHEMA_INVALID", "broker identity 缺少 Windows user 或 project ID");
+        }
+        this.identity = Object.freeze({ ...identity });
+        this.paths = paths;
+        this.#adapter = adapter;
+    }
+    static async open(projectRoot, identity, adapter) {
+        const requested = resolveProjectAuthPaths(projectRoot);
+        const canonicalRoot = await realpath(requested.project_root);
+        await ensureSafeProjectDirectory(canonicalRoot, ".worldengine");
+        const authDirectory = await ensureSafeProjectDirectory(canonicalRoot, ".worldengine/auth");
+        const webviewDataDirectory = await ensureSafeProjectDirectory(canonicalRoot, ".worldengine/webview");
+        await safeProjectPath(canonicalRoot, ".worldengine/auth");
+        await safeProjectPath(canonicalRoot, ".worldengine/webview");
+        return new ProjectAuthBroker(identity, {
+            project_root: canonicalRoot,
+            auth_directory: authDirectory,
+            webview_data_directory: webviewDataDirectory,
+        }, adapter);
+    }
+    get state() {
+        return this.#state;
+    }
+    async beginLogin() {
+        if (this.#adapter === undefined) {
+            throw new AuthoringBridgeError("E_AUTH_REQUIRED", "此项目没有可用的外部认证 adapter");
+        }
+        const challenge = await this.#adapter.beginChallenge(this.identity, this.paths.webview_data_directory);
+        if (!challenge.challenge_id || !challenge.challenge || challenge.expires_at_ms <= Date.now()) {
+            throw new AuthoringBridgeError("E_VALIDATION_FAILED", "外部认证 adapter 返回无效 challenge");
+        }
+        this.#challenge = Object.freeze({ ...challenge });
+        this.#state = "challenge_pending";
+        return this.#challenge;
+    }
+    async completeLogin(challengeId) {
+        if (this.#adapter === undefined || this.#challenge === undefined || this.#state !== "challenge_pending") {
+            throw new AuthoringBridgeError("E_AUTH_REQUIRED", "项目没有待完成的外部认证 challenge");
+        }
+        if (challengeId !== this.#challenge.challenge_id || this.#challenge.expires_at_ms <= Date.now()) {
+            this.#challenge = undefined;
+            this.#state = "signed_out";
+            throw new AuthoringBridgeError("E_AUTH_REQUIRED", "认证 challenge 不匹配或已过期");
+        }
+        await this.#adapter.completeChallenge(this.identity, this.#challenge, this.paths.webview_data_directory);
+        this.#challenge = undefined;
+        this.#state = "signed_in";
+    }
+    async logout() {
+        if (this.#adapter !== undefined && this.#state === "signed_in") {
+            await this.#adapter.logout(this.identity, this.paths.webview_data_directory);
+        }
+        this.#challenge = undefined;
+        this.#state = "signed_out";
+    }
+    /** 可安全记录的诊断；故意不包含 challenge、cookie、token 或 WebView 内容。 */
+    diagnostic() {
+        return {
+            project_id: this.identity.project_id,
+            auth_state: this.#state,
+            auth_directory: this.paths.auth_directory,
+            webview_data_directory: this.paths.webview_data_directory,
+        };
+    }
+}

package/dist/project-git-capture-recovery.d.ts

@@ -0,0 +1,16 @@
+export type GitCaptureRepositoryKind = "map" | "database" | "view";
+/** 仅供崩溃注入测试使用；生产调用不传入该参数。 */
+export interface GitCaptureRecoveryDependencies {
+    /** 仅测试：返回 crash 模拟宿主在该 filesystem 原子操作后消失。 */
+    readonly fault?: (phase: "after_old_entry" | "after_old_moved" | "after_new_entry" | "after_new_moved") => "crash" | void | Promise<"crash" | void>;
+    readonly isPidLive?: (pid: number) => boolean;
+}
+/**
+ * 恢复未完成的仓根替换。只移动 journal 中记录、且内容摘要仍匹配的条目；任何旁路编辑均 fail closed。
+ */
+export declare function recoverGitSourceTree(root: string, kindValue: GitCaptureRepositoryKind, dependencies?: GitCaptureRecoveryDependencies): Promise<void>;
+/**
+ * 将 capture source 原子地换入固定的三仓根，同时把旧 source 留在受控 backup 中。
+ * .git 从不移动。错误时尝试立即恢复；测试可模拟进程崩溃留下 journal。
+ */
+export declare function replaceGitSourceTree(root: string, repositoryPath: string, stagingPath: string, kindValue: GitCaptureRepositoryKind, dependencies?: GitCaptureRecoveryDependencies): Promise<void>;

package/dist/project-git-capture-recovery.js

@@ -0,0 +1,347 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, open, readFile, readdir, rename, rm } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { assertSafeExistingProjectPath, ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+const CONTROL = ".worldengine/project-git";
+const KINDS = new Set(["map", "database", "view"]);
+const TOP_LEVEL_NAME = /^(?!\.git$)(?!\.worldengine$)[^\\/\0]+$/u;
+class InjectedCrash extends Error {
+}
+function fail(message) {
+    throw new AuthoringBridgeError("E_OPERATION_UNCERTAIN", message);
+}
+function assertKind(kind) {
+    if (!KINDS.has(kind))
+        fail("Git capture recovery repository kind 无效");
+}
+function assertEntryName(name) {
+    if (typeof name !== "string" || !TOP_LEVEL_NAME.test(name) || name === "." || name === "..") {
+        fail("Git capture recovery 检测到不安全的仓库根条目");
+    }
+}
+function recoveryHint(root, kind) {
+    return `${join(root, CONTROL, `${kind}-capture-journal.json`)}；请保留 ${join(root, CONTROL)} 下的 capture/source-backup 目录后恢复`;
+}
+function treeEntryMap(entries) {
+    return new Map(entries.map((entry) => [entry.name, entry.digest]));
+}
+function sameTree(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const expected = treeEntryMap(left);
+    return right.every((entry) => expected.get(entry.name) === entry.digest);
+}
+async function digestEntry(path) {
+    const info = await lstat(path);
+    if (info.isSymbolicLink())
+        fail(`Git capture recovery 拒绝符号链接：${path}`);
+    const hash = createHash("sha256");
+    if (info.isFile()) {
+        hash.update("file\0");
+        hash.update(await readFile(path));
+        return hash.digest("hex");
+    }
+    if (!info.isDirectory())
+        fail(`Git capture recovery 只允许普通文件或目录：${path}`);
+    hash.update("directory\0");
+    const entries = await readdir(path, { withFileTypes: true });
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (entry.name === ".git")
+            fail(`Git capture recovery 不允许嵌套 Git 控制目录：${path}`);
+        const child = join(path, entry.name);
+        const childInfo = await lstat(child);
+        if (childInfo.isSymbolicLink())
+            fail(`Git capture recovery 拒绝符号链接：${child}`);
+        hash.update(entry.name, "utf8");
+        hash.update("\0");
+        hash.update(await digestEntry(child));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+async function listTree(path, allowGitControl = false) {
+    const output = [];
+    for (const entry of (await readdir(path, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name))) {
+        if (allowGitControl && entry.name === ".git")
+            continue;
+        assertEntryName(entry.name);
+        const absolute = join(path, entry.name);
+        output.push({ name: entry.name, digest: await digestEntry(absolute) });
+    }
+    return output;
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function isLivePid(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function canonicalPaths(root, kind, repositoryPath, stagingPath) {
+    const control = await ensureSafeProjectDirectory(root, CONTROL);
+    const repository = await assertSafeExistingProjectPath(root, join(control, "repositories", kind));
+    const expectedRepository = resolve(control, "repositories", kind);
+    if (repository !== expectedRepository)
+        fail("Git capture recovery 仓库路径不在固定 project-git repositories 目录");
+    if (repositoryPath !== undefined && resolve(repositoryPath) !== repository)
+        fail("Git capture recovery 拒绝非固定仓库根");
+    if (stagingPath === undefined)
+        return { control, repository };
+    const staging = await assertSafeExistingProjectPath(root, stagingPath);
+    const stagedRelative = relative(control, staging);
+    if (stagedRelative === "" || stagedRelative.startsWith(`..${sep}`) || stagedRelative === ".." || !/^capture-[A-Za-z0-9-]+$/u.test(stagedRelative)) {
+        fail("Git capture recovery 暂存目录必须是 project-git/capture-* 控制目录");
+    }
+    return { control, repository, staging };
+}
+function journalRelative(kind) { return `${CONTROL}/${kind}-capture-journal.json`; }
+async function writeJournal(root, journal) {
+    const control = await ensureSafeProjectDirectory(root, CONTROL);
+    const target = await safeProjectPath(root, journalRelative(journal.kind));
+    const temporary = join(control, `.capture-journal-${randomUUID()}.tmp`);
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(journal)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, target);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+function parseEntries(value, field) {
+    if (!Array.isArray(value))
+        fail(`Git capture journal ${field} 无效`);
+    const seen = new Set();
+    return value.map((entry) => {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            fail(`Git capture journal ${field} 条目无效`);
+        const record = entry;
+        if (Object.keys(record).length !== 2 || typeof record.name !== "string" || typeof record.digest !== "string")
+            fail(`Git capture journal ${field} 条目字段无效`);
+        assertEntryName(record.name);
+        if (!/^[a-f0-9]{64}$/u.test(record.digest) || seen.has(record.name))
+            fail(`Git capture journal ${field} 条目无效`);
+        seen.add(record.name);
+        return { name: record.name, digest: record.digest };
+    }).sort((left, right) => left.name.localeCompare(right.name));
+}
+function parseJournal(value, kind) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail("Git capture journal 无效");
+    const record = value;
+    const keys = ["schema_version", "kind", "pid", "repository_relative", "staging_relative", "backup_relative", "phase", "old_entries", "new_entries"];
+    if (Object.keys(record).length !== keys.length || Object.keys(record).some((key) => !keys.includes(key)))
+        fail("Git capture journal 字段无效");
+    if (record.schema_version !== 1 || record.kind !== kind || !Number.isSafeInteger(record.pid) || (typeof record.repository_relative !== "string") || typeof record.staging_relative !== "string" || typeof record.backup_relative !== "string" || !["prepared", "old_moved", "new_moving", "complete"].includes(String(record.phase))) {
+        fail("Git capture journal identity 无效");
+    }
+    const expectedRepository = `${CONTROL}/repositories/${kind}`;
+    if (record.repository_relative !== expectedRepository || !/^\.worldengine\/project-git\/capture-[A-Za-z0-9-]+$/u.test(record.staging_relative) || !/^\.worldengine\/project-git\/source-backup-[A-Za-z0-9-]+$/u.test(record.backup_relative)) {
+        fail("Git capture journal 路径无效");
+    }
+    return {
+        schema_version: 1, kind, pid: record.pid, repository_relative: record.repository_relative,
+        staging_relative: record.staging_relative, backup_relative: record.backup_relative,
+        phase: record.phase, old_entries: parseEntries(record.old_entries, "old_entries"), new_entries: parseEntries(record.new_entries, "new_entries"),
+    };
+}
+async function readJournal(root, kind) {
+    const path = await safeProjectPath(root, journalRelative(kind));
+    try {
+        return parseJournal(JSON.parse(await readFile(path, "utf8")), kind);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        if (error instanceof AuthoringBridgeError)
+            throw error;
+        fail("Git capture journal JSON 无效");
+    }
+}
+async function entryDigestIfPresent(path) {
+    if (!(await exists(path)))
+        return undefined;
+    return digestEntry(path);
+}
+async function assertExpectedSubset(path, expected, allowGitControl, hint) {
+    const allowed = new Map();
+    for (const entry of expected) {
+        const digests = allowed.get(entry.name) ?? new Set();
+        digests.add(entry.digest);
+        allowed.set(entry.name, digests);
+    }
+    for (const actual of await listTree(path, allowGitControl)) {
+        if (!allowed.get(actual.name)?.has(actual.digest))
+            fail(`Git capture recovery 发现未知或被编辑的字节，拒绝覆盖；恢复材料：${hint}`);
+    }
+}
+async function moveExpected(from, to, entry, hint) {
+    const source = join(from, entry.name);
+    const destination = join(to, entry.name);
+    const sourceDigest = await entryDigestIfPresent(source);
+    const destinationDigest = await entryDigestIfPresent(destination);
+    if (sourceDigest === undefined) {
+        if (destinationDigest === entry.digest)
+            return;
+        fail(`Git capture recovery 缺少可验证的 ${entry.name}；恢复材料：${hint}`);
+    }
+    if (sourceDigest !== entry.digest || destinationDigest !== undefined) {
+        fail(`Git capture recovery ${entry.name} 与 journal 摘要不匹配；恢复材料：${hint}`);
+    }
+    await rename(source, destination);
+}
+async function removeJournal(root, kind) {
+    await rm(await safeProjectPath(root, journalRelative(kind)), { force: true });
+}
+async function rollback(root, journal, paths) {
+    const hint = recoveryHint(root, journal.kind);
+    await assertExpectedSubset(paths.repository, [...journal.old_entries, ...journal.new_entries], true, hint);
+    await assertExpectedSubset(paths.staging, journal.new_entries, false, hint);
+    await assertExpectedSubset(paths.backup, journal.old_entries, false, hint);
+    const oldByName = treeEntryMap(journal.old_entries);
+    for (const entry of journal.new_entries) {
+        const repositoryDigest = await entryDigestIfPresent(join(paths.repository, entry.name));
+        const stagingDigest = await entryDigestIfPresent(join(paths.staging, entry.name));
+        if (repositoryDigest === entry.digest) {
+            if (stagingDigest === undefined)
+                await moveExpected(paths.repository, paths.staging, entry, hint);
+            else if (stagingDigest !== entry.digest || oldByName.get(entry.name) !== entry.digest)
+                fail(`Git capture recovery ${entry.name} 出现双份新树；恢复材料：${hint}`);
+        }
+        else if (repositoryDigest === undefined || repositoryDigest === oldByName.get(entry.name)) {
+            if (stagingDigest !== entry.digest)
+                fail(`Git capture recovery ${entry.name} 新树位置不一致；恢复材料：${hint}`);
+        }
+        else {
+            fail(`Git capture recovery ${entry.name} 仓根摘要不匹配；恢复材料：${hint}`);
+        }
+    }
+    for (const entry of journal.old_entries) {
+        const backupDigest = await entryDigestIfPresent(join(paths.backup, entry.name));
+        const repositoryDigest = await entryDigestIfPresent(join(paths.repository, entry.name));
+        if (backupDigest === entry.digest) {
+            if (repositoryDigest === undefined)
+                await moveExpected(paths.backup, paths.repository, entry, hint);
+            else if (repositoryDigest !== entry.digest)
+                fail(`Git capture recovery ${entry.name} 旧树目标被占用；恢复材料：${hint}`);
+        }
+        else if (repositoryDigest !== entry.digest) {
+            fail(`Git capture recovery 缺少可验证的旧树 ${entry.name}；恢复材料：${hint}`);
+        }
+    }
+    if (!sameTree(journal.old_entries, await listTree(paths.repository, true)) || !sameTree(journal.new_entries, await listTree(paths.staging))) {
+        fail(`Git capture recovery 回滚后摘要不匹配；恢复材料：${hint}`);
+    }
+    await removeJournal(root, journal.kind);
+}
+/**
+ * 恢复未完成的仓根替换。只移动 journal 中记录、且内容摘要仍匹配的条目；任何旁路编辑均 fail closed。
+ */
+export async function recoverGitSourceTree(root, kindValue, dependencies = {}) {
+    assertKind(kindValue);
+    const journal = await readJournal(root, kindValue);
+    if (journal === undefined)
+        return;
+    if ((dependencies.isPidLive ?? isLivePid)(journal.pid))
+        fail(`Git capture recovery 正由 pid ${journal.pid} 执行；恢复材料：${recoveryHint(root, kindValue)}`);
+    const base = await canonicalPaths(root, kindValue);
+    const staging = await assertSafeExistingProjectPath(root, join(root, journal.staging_relative));
+    const backup = await assertSafeExistingProjectPath(root, join(root, journal.backup_relative));
+    const paths = { repository: base.repository, staging, backup };
+    const hint = recoveryHint(root, kindValue);
+    // 进程在写入 complete 后崩溃时，目标树已经是新 source；不得回滚它。
+    if (journal.phase === "complete" || (journal.phase === "new_moving"
+        && sameTree(journal.new_entries, await listTree(paths.repository, true))
+        && sameTree(journal.old_entries, await listTree(paths.backup)))) {
+        if (!sameTree(journal.new_entries, await listTree(paths.repository, true))
+            || !sameTree(journal.old_entries, await listTree(paths.backup))
+            || (await listTree(paths.staging)).length !== 0)
+            fail(`Git capture recovery 完成态材料已变化；恢复材料：${hint}`);
+        await removeJournal(root, kindValue);
+        return;
+    }
+    await rollback(root, journal, paths);
+}
+/**
+ * 将 capture source 原子地换入固定的三仓根，同时把旧 source 留在受控 backup 中。
+ * .git 从不移动。错误时尝试立即恢复；测试可模拟进程崩溃留下 journal。
+ */
+export async function replaceGitSourceTree(root, repositoryPath, stagingPath, kindValue, dependencies = {}) {
+    assertKind(kindValue);
+    await recoverGitSourceTree(root, kindValue, dependencies);
+    const paths = await canonicalPaths(root, kindValue, repositoryPath, stagingPath);
+    const repository = paths.repository;
+    const staging = paths.staging;
+    if (!(await exists(join(repository, ".git"))))
+        fail("Git capture recovery 固定仓库根缺少 .git");
+    const backupRelative = `${CONTROL}/source-backup-${randomUUID()}`;
+    const backup = await ensureSafeProjectDirectory(root, backupRelative);
+    const journal = {
+        schema_version: 1, kind: kindValue, pid: process.pid,
+        repository_relative: `${CONTROL}/repositories/${kindValue}`,
+        staging_relative: relative(root, staging).split(sep).join("/"), backup_relative: backupRelative,
+        phase: "prepared", old_entries: await listTree(repository, true), new_entries: await listTree(staging),
+    };
+    await writeJournal(root, journal);
+    const hint = recoveryHint(root, kindValue);
+    try {
+        for (const entry of journal.old_entries) {
+            await moveExpected(repository, backup, entry, hint);
+            if (await dependencies.fault?.("after_old_entry") === "crash")
+                throw new InjectedCrash("simulated capture crash");
+        }
+        const oldMoved = { ...journal, phase: "old_moved" };
+        await writeJournal(root, oldMoved);
+        if (await dependencies.fault?.("after_old_moved") === "crash")
+            throw new InjectedCrash("simulated capture crash");
+        const newMoving = { ...oldMoved, phase: "new_moving" };
+        await writeJournal(root, newMoving);
+        for (const entry of journal.new_entries) {
+            await moveExpected(staging, repository, entry, hint);
+            if (await dependencies.fault?.("after_new_entry") === "crash")
+                throw new InjectedCrash("simulated capture crash");
+        }
+        if (await dependencies.fault?.("after_new_moved") === "crash")
+            throw new InjectedCrash("simulated capture crash");
+        await writeJournal(root, { ...newMoving, phase: "complete" });
+        await removeJournal(root, kindValue);
+    }
+    catch (error) {
+        if (error instanceof InjectedCrash)
+            throw error;
+        try {
+            const current = await readJournal(root, kindValue);
+            if (current !== undefined) {
+                const liveBypass = { isPidLive: (pid) => pid !== process.pid && (dependencies.isPidLive ?? isLivePid)(pid) };
+                await recoverGitSourceTree(root, kindValue, liveBypass);
+            }
+        }
+        catch (recoveryError) {
+            // rollback 无法证明安全时必须返回带恢复路径的 fail-closed 错误。
+            throw recoveryError;
+        }
+        throw error;
+    }
+}

package/dist/project-git-cli.d.ts

@@ -0,0 +1,5 @@
+import type { ProjectTransferTransport } from "./transfer/transport.js";
+export interface ProjectGitCliIo {
+    readonly stdout: (text: string) => void;
+}
+export declare function runProjectGitCli(args: readonly string[], projectRoot: string, transport: ProjectTransferTransport | undefined, io: ProjectGitCliIo): Promise<number>;

package/dist/project-git-cli.js

@@ -0,0 +1,40 @@
+import { ProjectGitClient, projectGitTransport } from "./project-git.js";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+function writeJson(io, value) {
+    io.stdout(`${JSON.stringify(value, null, 2)}\n`);
+}
+export async function runProjectGitCli(args, projectRoot, transport, io) {
+    const [command, operand, ...rest] = args;
+    if (command === undefined || command === "help" || command === "--help") {
+        io.stdout("worldengine git manifest pull|push | git clone|fetch|push|capture|prepare-apply|apply map|database|view\n导出：capture → 在固定旁仓 git add/commit → push；应用：prepare-apply → fetch → 检查/合并提交 → apply。不会自动 stage、merge 或覆盖本地漂移。\n");
+        return 0;
+    }
+    if (rest.length !== 0)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "git 参数无效");
+    const client = await ProjectGitClient.open(projectRoot, transport === undefined ? undefined : projectGitTransport(transport));
+    if (command === "manifest" && operand === "pull") {
+        writeJson(io, await client.pullManifest());
+        return 0;
+    }
+    if (command === "manifest" && operand === "push") {
+        writeJson(io, await client.pushManifest());
+        return 0;
+    }
+    if (command === "clone" && operand !== undefined)
+        writeJson(io, await client.clone(operand));
+    else if (command === "fetch" && operand !== undefined)
+        writeJson(io, await client.fetch(operand));
+    else if (command === "push" && operand !== undefined)
+        writeJson(io, await client.push(operand));
+    else if (command === "capture" && operand !== undefined)
+        writeJson(io, await client.capture(operand));
+    else if (command === "prepare-apply" && operand !== undefined)
+        writeJson(io, await client.prepareApply(operand));
+    else if (command === "apply" && operand !== undefined)
+        writeJson(io, await client.apply(operand));
+    else if (command === "inspect" && operand !== undefined)
+        writeJson(io, await client.inspect(operand));
+    else
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "git 命令无效");
+    return 0;
+}

package/dist/project-git-scenario-source.d.ts

@@ -0,0 +1,10 @@
+export type ScenarioGitSourceKind = "map" | "database";
+export interface ScenarioGitCapture {
+    readonly files: Readonly<Record<string, Uint8Array>>;
+    /** 选定 Git tree 的 canonical SHA-256，而非整个 Local Author Project。 */
+    readonly digest: string;
+    readonly project_revision: number;
+    readonly source_sha256: string;
+}
+export declare function captureScenarioGitSource(root: string, kind: ScenarioGitSourceKind): Promise<ScenarioGitCapture>;
+export declare function applyScenarioGitSource(root: string, kind: ScenarioGitSourceKind, files: Readonly<Record<string, Uint8Array>>, expected: ScenarioGitCapture): Promise<void>;