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

package/dist/project-git.js

@@ -0,0 +1,656 @@
+import { execFile } from "node:child_process";
+import { createServer } from "node:http";
+import { lstat, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { validateLocalAuthorProjectManifest } from "@world-engines/project-format";
+import { assertSafeExistingProjectPath, ensureSafeProjectDirectory, safeProjectPath } from "./safe-project-path.js";
+import { readFrozenReviewTargetBinding } from "./frozen-review-local-pipeline.js";
+import { captureScenarioGitSource, applyScenarioGitSource } from "./project-git-scenario-source.js";
+import { captureViewGitSource, applyViewGitSource } from "./project-git-view-source.js";
+import { recoverGitSourceTree, replaceGitSourceTree } from "./project-git-capture-recovery.js";
+import { acquireProjectWriterLease } from "./project-writer-lease.js";
+const execFileAsync = promisify(execFile);
+const PROJECT_GIT_CONTROL_DIRECTORY = ".worldengine/project-git";
+export const PROJECT_GIT_MANIFEST_PATH = `${PROJECT_GIT_CONTROL_DIRECTORY}/manifest.json`;
+const PROJECT_GIT_HTTP_MAX_BODY_BYTES = 96 * 1024 * 1024;
+const STRICT_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
+const GIT_OBJECT_ID = /^[a-f0-9]{40,64}$/;
+export const PROJECT_GIT_REPOSITORY_KINDS = ["map", "database", "view"];
+function fail(code, message) {
+    throw new AuthoringBridgeError(code, message);
+}
+function exactObject(value, keys, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail("E_SCHEMA_INVALID", `${field} 无效`);
+    const actual = Object.keys(value);
+    if (actual.length !== keys.length || actual.some((key) => !keys.includes(key)))
+        fail("E_SCHEMA_INVALID", `${field} 字段无效`);
+}
+function strictSegment(value, field) {
+    if (typeof value !== "string" || !STRICT_SEGMENT.test(value))
+        fail("E_SCHEMA_INVALID", `${field} 无效`);
+}
+function expectedRemotePath(scenarioId, kind) {
+    return `/v1/project-git/${scenarioId}/${kind}.git`;
+}
+export function validateProjectGitManifest(value, expected) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail("E_SCHEMA_INVALID", "project git manifest response 无效");
+    const response = value;
+    if (!Number.isSafeInteger(response.revision) || response.revision < 0)
+        fail("E_SCHEMA_INVALID", "project git manifest revision 无效");
+    strictSegment(response.scenario_id, "scenario_id");
+    if (typeof response.manifest !== "object" || response.manifest === null || Array.isArray(response.manifest))
+        fail("E_SCHEMA_INVALID", "project git manifest body 无效");
+    const manifest = response.manifest;
+    exactObject(manifest, ["schema_version", "scenario_id", "metadata", "repositories"], "project git manifest body");
+    if (manifest.schema_version !== 1 || manifest.scenario_id !== response.scenario_id)
+        fail("E_SCHEMA_INVALID", "project git manifest identity 无效");
+    strictSegment(manifest.scenario_id, "manifest.scenario_id");
+    exactObject(manifest.metadata, ["title", "description"], "manifest.metadata");
+    if (typeof manifest.metadata.title !== "string" || typeof manifest.metadata.description !== "string")
+        fail("E_SCHEMA_INVALID", "manifest.metadata 无效");
+    exactObject(manifest.repositories, PROJECT_GIT_REPOSITORY_KINDS, "manifest.repositories");
+    for (const kind of PROJECT_GIT_REPOSITORY_KINDS) {
+        const repository = manifest.repositories[kind];
+        exactObject(repository, ["kind", "remote_path", "commit"], `manifest.repositories.${kind}`);
+        if (repository.kind !== kind || repository.remote_path !== expectedRemotePath(String(response.scenario_id), kind)
+            || (repository.commit !== null && (typeof repository.commit !== "string" || !/^[a-f0-9]{40}$/.test(repository.commit)))) {
+            fail("E_SCHEMA_INVALID", `manifest.repositories.${kind} 无效`);
+        }
+    }
+    const parsed = value;
+    if (expected !== undefined && parsed.scenario_id !== expected.scenario_id) {
+        fail("E_REMOTE_FORBIDDEN", "远端 manifest identity 与当前作者项目不匹配");
+    }
+    return parsed;
+}
+function validateProjectGitAccess(value, expected) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail("E_SCHEMA_INVALID", "project git collaboration response 无效");
+    const access = value.access;
+    if (typeof access !== "object" || access === null || Array.isArray(access))
+        fail("E_SCHEMA_INVALID", "project git access 无效");
+    const record = access;
+    if (record.scenario_id !== expected.scenario_id || typeof record.is_member !== "boolean" || typeof record.manifest_read !== "boolean" || typeof record.view_source_available !== "boolean")
+        fail("E_REMOTE_FORBIDDEN", "project git access identity 无效");
+    if (typeof record.permissions !== "object" || record.permissions === null || Array.isArray(record.permissions))
+        fail("E_SCHEMA_INVALID", "project git permissions 无效");
+    const permissions = record.permissions;
+    const fields = ["map_read", "map_write", "database_read", "database_write", "view_read", "view_write", "metadata_write"];
+    if (!fields.every((field) => typeof permissions[field] === "boolean"))
+        fail("E_SCHEMA_INVALID", "project git permissions 无效");
+    return record;
+}
+export function projectGitTransport(transport) {
+    return {
+        async request(request) {
+            const bodyBytes = request.body instanceof Uint8Array
+                ? request.body
+                : request.body === undefined
+                    ? undefined
+                    : Buffer.from(JSON.stringify(request.body), "utf8");
+            return await transport.request({
+                project_id: request.project_id,
+                method: request.method,
+                path: request.path,
+                ...(request.content_type === undefined ? {} : { content_type: request.content_type }),
+                ...(request.body === undefined ? {} : { body: request.body }),
+                ...(bodyBytes === undefined ? {} : {
+                    body_digest: createHash("sha256").update(bodyBytes).digest("hex"),
+                    body_size: bodyBytes.byteLength,
+                }),
+            });
+        },
+    };
+}
+async function readProjectIdentity(projectRoot) {
+    const path = await assertSafeExistingProjectPath(projectRoot, join(projectRoot, "worldengine.project.json"));
+    let manifest;
+    try {
+        manifest = validateLocalAuthorProjectManifest(JSON.parse(await readFile(path, "utf8")));
+    }
+    catch {
+        fail("E_SCHEMA_INVALID", "本地 author project manifest 无效");
+    }
+    strictSegment(manifest.project_id, "project_id");
+    const binding = await readFrozenReviewTargetBinding(projectRoot, manifest.project_id);
+    strictSegment(binding.scenario_id, "review-target.scenario_id");
+    return { project_id: manifest.project_id, scenario_id: binding.scenario_id };
+}
+function remoteManifestPath(scenarioId) {
+    return `/v1/creator/scenarios/${encodeURIComponent(scenarioId)}/project-manifest`;
+}
+function remoteAccessPath(scenarioId) {
+    return `/v1/creator/scenarios/${encodeURIComponent(scenarioId)}/collaboration`;
+}
+function remoteGitPath(scenarioId, kind, suffix) {
+    return `/v1/project-git/${encodeURIComponent(scenarioId)}/${kind}.git${suffix}`;
+}
+function bodyObject(response) {
+    if (response.status === 401)
+        fail("E_AUTH_REQUIRED", "project git 需要当前项目登录");
+    if (response.status === 403)
+        fail("E_REMOTE_FORBIDDEN", "project git ACL 拒绝当前操作");
+    if (response.status < 200 || response.status >= 300)
+        fail("E_OPERATION_UNCERTAIN", `project git 远端返回 ${response.status}`);
+    return response.body;
+}
+function assertKind(value) {
+    if (!PROJECT_GIT_REPOSITORY_KINDS.includes(value))
+        fail("E_SCHEMA_INVALID", "repository kind 仅允许 map/database/view");
+    return value;
+}
+function assertSourceFilePath(path) {
+    if (path.length === 0 || /[\\:\x00-\x1f<>"|?*]/.test(path)
+        || path.split("/").some((part) => !part || part === "." || part === ".." || [".git", ".worldengine"].includes(part.toLowerCase()) || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i.test(part))) {
+        fail("E_PATH_OUTSIDE_PROJECT", "Git source 文件路径无效");
+    }
+}
+function checkGrant(access, kind, operation) {
+    if (!access.is_member || !access.manifest_read)
+        fail("E_REMOTE_FORBIDDEN", "当前身份不是项目成员或无 manifest 读取权限");
+    if (kind === "view" && !access.view_source_available)
+        fail("E_REMOTE_FORBIDDEN", "购买或外部 view 只提供运行包，禁止取得卖家源码");
+    const canRead = access.permissions[`${kind}_read`];
+    const canWrite = access.permissions[`${kind}_write`];
+    if ((operation === "read" && !canRead) || (operation === "write" && (!canRead || !canWrite))) {
+        fail("E_REMOTE_FORBIDDEN", `project git ${operation} ACL 拒绝当前操作`);
+    }
+}
+async function collectRequestBody(request) {
+    if (request.method === "GET" || request.method === "HEAD")
+        return undefined;
+    const length = Number(request.headers["content-length"] ?? 0);
+    if (!Number.isSafeInteger(length) || length < 0 || length > PROJECT_GIT_HTTP_MAX_BODY_BYTES)
+        fail("E_VALIDATION_FAILED", "git HTTP 请求过大");
+    const chunks = [];
+    let total = 0;
+    for await (const raw of request) {
+        const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+        total += chunk.byteLength;
+        if (total > PROJECT_GIT_HTTP_MAX_BODY_BYTES)
+            fail("E_VALIDATION_FAILED", "git HTTP 请求过大");
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+function relayRoute(url, relayPath) {
+    if (url === undefined || url.includes("#"))
+        fail("E_VALIDATION_FAILED", "git HTTP route 无效");
+    const parsed = new URL(url, "http://127.0.0.1");
+    if (parsed.pathname === `${relayPath}/info/refs`) {
+        const service = parsed.searchParams.get("service");
+        if (parsed.searchParams.size !== 1 || (service !== "git-upload-pack" && service !== "git-receive-pack"))
+            fail("E_VALIDATION_FAILED", "git smart HTTP service 无效");
+        return { suffix: `/info/refs?service=${service}`, contentType: undefined };
+    }
+    if (parsed.search !== "" || ![`${relayPath}/git-upload-pack`, `${relayPath}/git-receive-pack`].includes(parsed.pathname)) {
+        fail("E_VALIDATION_FAILED", "仅允许 git smart HTTP endpoint");
+    }
+    return { suffix: parsed.pathname.slice(relayPath.length), contentType: undefined };
+}
+function decodeGitEnvelope(value) {
+    exactObject(value, ["schema_version", "content_type", "body_base64", ...(typeof value?.cache_control === "string" ? ["cache_control"] : [])], "project git HTTP response");
+    if (value.schema_version !== 1 || typeof value.content_type !== "string" || !/^application\/x-git-(?:upload|receive)-pack-(?:advertisement|result)$/.test(value.content_type) || typeof value.body_base64 !== "string") {
+        fail("E_VALIDATION_FAILED", "project git HTTP response 无效");
+    }
+    if (value.cache_control !== undefined && (typeof value.cache_control !== "string" || value.cache_control.length > 256 || /[\r\n]/.test(value.cache_control))) {
+        fail("E_VALIDATION_FAILED", "project git HTTP cache_control 无效");
+    }
+    const bytes = Buffer.from(value.body_base64, "base64");
+    if (bytes.byteLength > PROJECT_GIT_HTTP_MAX_BODY_BYTES || bytes.toString("base64").replace(/=+$/, "") !== value.body_base64.replace(/=+$/, "")) {
+        fail("E_VALIDATION_FAILED", "project git HTTP body_base64 无效");
+    }
+    return { ...value, bytes };
+}
+async function sendRelayResponse(response, request, transportResponse) {
+    if (transportResponse.status < 200 || transportResponse.status >= 300) {
+        response.writeHead(transportResponse.status, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+        response.end("project git request rejected\n");
+        return;
+    }
+    const envelope = decodeGitEnvelope(transportResponse.body);
+    response.writeHead(transportResponse.status, {
+        "content-type": envelope.content_type,
+        "content-length": String(envelope.bytes.byteLength),
+        "cache-control": envelope.cache_control ?? "no-cache",
+        "x-content-type-options": "nosniff",
+        connection: "close",
+    });
+    if (request.method === "HEAD")
+        response.end();
+    else
+        response.end(envelope.bytes);
+}
+async function closeServer(server) {
+    await new Promise((resolvePromise, rejectPromise) => server.close((error) => error === undefined ? resolvePromise() : rejectPromise(error)));
+}
+async function startGitRelay(identity, kind, transport) {
+    // loopback relay 是一次 Git 操作的短期能力；随机路径避免同机其他进程仅凭端口复用 broker 出口。
+    const relayPath = `/project-git-${randomUUID()}/repository.git`;
+    const server = createServer(async (request, response) => {
+        try {
+            if (request.headers.authorization !== undefined || request.headers.cookie !== undefined)
+                fail("E_AUTH_REQUIRED", "loopback git 不接受客户端凭据");
+            if (request.method !== "GET" && request.method !== "POST" && request.method !== "HEAD")
+                fail("E_VALIDATION_FAILED", "git smart HTTP method 无效");
+            const route = relayRoute(request.url, relayPath);
+            const expectedContentType = route.suffix === "/git-upload-pack"
+                ? "application/x-git-upload-pack-request"
+                : route.suffix === "/git-receive-pack"
+                    ? "application/x-git-receive-pack-request"
+                    : undefined;
+            const receivedContentType = request.headers["content-type"]?.split(";", 1)[0]?.trim().toLowerCase();
+            if (expectedContentType !== receivedContentType) {
+                if (expectedContentType !== undefined || receivedContentType !== undefined)
+                    fail("E_VALIDATION_FAILED", "git smart HTTP content-type 无效");
+            }
+            const body = await collectRequestBody(request);
+            await sendRelayResponse(response, request, await transport.request({
+                project_id: identity.project_id,
+                method: request.method === "HEAD" ? "GET" : request.method,
+                path: remoteGitPath(identity.scenario_id, kind, route.suffix),
+                ...(expectedContentType === undefined ? {} : { content_type: expectedContentType }),
+                ...(body === undefined ? {} : { body }),
+            }));
+        }
+        catch {
+            if (!response.headersSent)
+                response.writeHead(502, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+            response.end("project git relay failed\n");
+        }
+    });
+    await new Promise((resolvePromise, rejectPromise) => {
+        server.once("error", rejectPromise);
+        server.listen(0, "127.0.0.1", resolvePromise);
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        await closeServer(server);
+        fail("E_OPERATION_UNCERTAIN", "project git loopback relay 无法启动");
+    }
+    return Object.freeze({ url: `http://127.0.0.1:${address.port}${relayPath}`, close: () => closeServer(server) });
+}
+async function runGit(args, cwd) {
+    try {
+        const environment = { ...process.env };
+        for (const name of [
+            "WORLDENGINE_PROJECT_TRANSFER_PIPE",
+            "WORLDENGINE_PROJECT_TRANSFER_CHALLENGE_ID",
+            "WORLDENGINE_PROJECT_TRANSFER_CHALLENGE",
+            "WORLDENGINE_PROJECT_TRANSFER_EXPIRES_AT_MS",
+        ])
+            delete environment[name];
+        const { stdout } = await execFileAsync("git", [...args], {
+            ...(cwd === undefined ? {} : { cwd }),
+            windowsHide: true,
+            timeout: 5 * 60_000,
+            maxBuffer: 8 * 1024 * 1024,
+            env: {
+                ...environment,
+                GIT_TERMINAL_PROMPT: "0",
+                GCM_INTERACTIVE: "Never",
+                NO_PROXY: [process.env.NO_PROXY, "127.0.0.1", "localhost"].filter(Boolean).join(","),
+            },
+        });
+        return stdout.trim();
+    }
+    catch {
+        fail("E_OPERATION_UNCERTAIN", "系统 git 执行失败");
+    }
+}
+function gitBaseArgs(hooksDirectory) {
+    return ["-c", "credential.helper=", "-c", "http.extraHeader=", "-c", "http.proxy=", "-c", "http.followRedirects=false", "-c", `core.hooksPath=${hooksDirectory}`];
+}
+/** 在启动网络命令前解析 Git URL rewrite，拒绝任何配置把出口改到 relay 之外。 */
+async function assertRelayTarget(url, cwd, push = false) {
+    const resolved = await runGit(["ls-remote", "--get-url", url], cwd);
+    if (resolved !== url) {
+        fail("E_REMOTE_FORBIDDEN", "Git URL rewrite 不能更改受控 relay 目标");
+    }
+    if (push) {
+        let rules;
+        try {
+            rules = (await execFileAsync("git", ["config", "--null", "--get-regexp", "^url\\..*\\.pushinsteadof$"], { cwd, windowsHide: true, timeout: 10_000, maxBuffer: 1024 * 1024 })).stdout;
+        }
+        catch (error) {
+            if (error.code === 1)
+                return;
+            fail("E_OPERATION_UNCERTAIN", "无法验证 Git push URL rewrite");
+        }
+        for (const rule of rules.split("\0")) {
+            const separator = rule.indexOf("\n");
+            if (separator >= 0 && url.startsWith(rule.slice(separator + 1))) {
+                fail("E_REMOTE_FORBIDDEN", "Git URL rewrite 不能更改受控 relay 目标");
+            }
+        }
+    }
+}
+function semanticRemote(identity, kind) {
+    return `worldengine://${identity.scenario_id}/${kind}`;
+}
+async function existingRepository(projectRoot, target) {
+    const canonical = await assertSafeExistingProjectPath(projectRoot, target);
+    const dotGit = await assertSafeExistingProjectPath(projectRoot, join(canonical, ".git"));
+    if (!(await lstat(dotGit)).isDirectory())
+        fail("E_VALIDATION_FAILED", "只允许独立仓库，拒绝父仓或 worktree .git");
+    const top = await runGit(["-C", canonical, "rev-parse", "--show-toplevel"]);
+    const canonicalTop = await realpath(top);
+    if (process.platform === "win32" ? canonicalTop.toLowerCase() !== canonical.toLowerCase() : canonicalTop !== canonical) {
+        fail("E_VALIDATION_FAILED", "仓库根与固定 project git 子目录不一致");
+    }
+    return canonical;
+}
+export class ProjectGitClient {
+    projectRoot;
+    identity;
+    transport;
+    constructor(projectRoot, identity, transport) {
+        this.projectRoot = projectRoot;
+        this.identity = identity;
+        this.transport = transport;
+    }
+    static async open(projectRoot, transport) {
+        if (transport === undefined)
+            fail("E_AUTH_REQUIRED", "project git 需要 ProjectAuthBroker");
+        const canonicalRoot = await realpath(resolve(projectRoot));
+        return new ProjectGitClient(canonicalRoot, await readProjectIdentity(canonicalRoot), transport);
+    }
+    async readManifest() {
+        const response = await this.transport.request({ project_id: this.identity.project_id, method: "GET", path: remoteManifestPath(this.identity.scenario_id) });
+        return validateProjectGitManifest(bodyObject(response), this.identity);
+    }
+    async readAccess() {
+        const response = await this.transport.request({ project_id: this.identity.project_id, method: "GET", path: remoteAccessPath(this.identity.scenario_id) });
+        return validateProjectGitAccess(bodyObject(response), this.identity);
+    }
+    captureSource(kind) {
+        return kind === "view" ? captureViewGitSource(this.projectRoot) : captureScenarioGitSource(this.projectRoot, kind);
+    }
+    /** Native 在命令后只读核对同一实际作者源，避免复制 map/database/view 摘要算法。 */
+    async inspect(kindValue) {
+        const kind = assertKind(kindValue);
+        checkGrant(await this.readAccess(), kind, "read");
+        return this.sourceResult("source_inspected", kind, await this.captureSource(kind));
+    }
+    async withSourceLease(kind, work) {
+        // 旁仓单独的 lease，不嵌套占用真实作者源 writer；Windows helper 随宿主管道
+        // 关闭按 file identity 清理，避免自制 PID/rename stale-lock 竞争误删后来者。
+        const scope = await ensureSafeProjectDirectory(this.projectRoot, `${PROJECT_GIT_CONTROL_DIRECTORY}/source-leases/${kind}`);
+        const lock = await acquireProjectWriterLease(scope, { operation: "project_git_source", repository: kind });
+        try {
+            await recoverGitSourceTree(this.projectRoot, kind);
+            return await work();
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    async assertCleanRepository(target) {
+        // 包括 ignored 文件，避免导出替换 source 目录时带走未知本地字节。
+        if (await runGit(["-C", target, "status", "--porcelain=v1", "--untracked-files=all", "--ignored"])) {
+            fail("E_VALIDATION_FAILED", "Git 仓库有未提交或忽略文件；请先保存、提交或自行处理，系统不会覆盖");
+        }
+    }
+    async saveSourcePreimage(kind, capture) {
+        const control = await ensureSafeProjectDirectory(this.projectRoot, PROJECT_GIT_CONTROL_DIRECTORY);
+        const target = await safeProjectPath(this.projectRoot, `${PROJECT_GIT_CONTROL_DIRECTORY}/${kind}-source-preimage.json`);
+        const temporary = join(control, `.source-preimage-${randomUUID()}.tmp`);
+        await writeFile(temporary, JSON.stringify({ schema_version: 1, project_id: this.identity.project_id, scenario_id: this.identity.scenario_id, repository: kind,
+            digest: capture.digest, project_revision: capture.project_revision, source_sha256: capture.source_sha256,
+            files: Object.fromEntries(Object.entries(capture.files).map(([path, bytes]) => [path, Buffer.from(bytes).toString("base64")])) }), { flag: "wx", mode: 0o600 });
+        await rename(temporary, target);
+    }
+    /** 导出真实作者源，不触碰 index；作者仍使用原始 Git add/commit/merge。 */
+    async capture(kindValue) {
+        const kind = assertKind(kindValue);
+        checkGrant(await this.readAccess(), kind, "write");
+        return this.withSourceLease(kind, async () => {
+            const repoRelative = `${PROJECT_GIT_CONTROL_DIRECTORY}/repositories/${kind}`;
+            await ensureSafeProjectDirectory(this.projectRoot, `${PROJECT_GIT_CONTROL_DIRECTORY}/repositories`);
+            const repoPath = await safeProjectPath(this.projectRoot, repoRelative);
+            try {
+                await lstat(repoPath);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                await ensureSafeProjectDirectory(this.projectRoot, repoRelative);
+                const hooks = await ensureSafeProjectDirectory(this.projectRoot, `${PROJECT_GIT_CONTROL_DIRECTORY}/hooks-disabled`);
+                await runGit([...gitBaseArgs(hooks), "init", "--initial-branch=main", "--", repoPath]);
+                await runGit(["-C", repoPath, "remote", "add", "origin", semanticRemote(this.identity, kind)]);
+            }
+            const target = await existingRepository(this.projectRoot, repoPath);
+            await this.assertCleanRepository(target);
+            const capture = await this.captureSource(kind);
+            const stageRelative = `${PROJECT_GIT_CONTROL_DIRECTORY}/capture-${randomUUID()}`;
+            const stage = await ensureSafeProjectDirectory(this.projectRoot, stageRelative);
+            for (const [path, bytes] of Object.entries(capture.files)) {
+                assertSourceFilePath(path);
+                await ensureSafeProjectDirectory(this.projectRoot, `${stageRelative}/${dirname(path) === "." ? "" : dirname(path)}`);
+                await writeFile(join(stage, path), bytes, { flag: "wx" });
+            }
+            const current = await this.captureSource(kind);
+            if (current.project_revision !== capture.project_revision || current.source_sha256 !== capture.source_sha256 || current.digest !== capture.digest)
+                fail("E_VALIDATION_FAILED", "导出期间作者源变化，请重试；暂存预影已保留");
+            await this.assertCleanRepository(target);
+            // Web 与 npm 共用仓根布局；持久 journal 保留崩溃后的精确恢复预影。
+            await replaceGitSourceTree(this.projectRoot, target, stage, kind);
+            await this.saveSourcePreimage(kind, capture);
+            return this.sourceResult("captured", kind, capture);
+        });
+    }
+    /** 在 fetch/merge 之前固定本地预影；后续本地编辑必须导致 apply 拒绝。 */
+    async prepareApply(kindValue) {
+        const kind = assertKind(kindValue);
+        checkGrant(await this.readAccess(), kind, "read");
+        return this.withSourceLease(kind, async () => {
+            const target = await existingRepository(this.projectRoot, join(this.projectRoot, PROJECT_GIT_CONTROL_DIRECTORY, "repositories", kind));
+            await this.assertCleanRepository(target);
+            const capture = await this.captureSource(kind);
+            await this.saveSourcePreimage(kind, capture);
+            return this.sourceResult("apply_prepared", kind, capture);
+        });
+    }
+    async apply(kindValue) {
+        const kind = assertKind(kindValue);
+        checkGrant(await this.readAccess(), kind, "read");
+        return this.withSourceLease(kind, async () => {
+            const target = await existingRepository(this.projectRoot, join(this.projectRoot, PROJECT_GIT_CONTROL_DIRECTORY, "repositories", kind));
+            await this.assertCleanRepository(target);
+            const path = await assertSafeExistingProjectPath(this.projectRoot, join(this.projectRoot, PROJECT_GIT_CONTROL_DIRECTORY, `${kind}-source-preimage.json`));
+            const raw = await readFile(path);
+            if (raw.length > PROJECT_GIT_HTTP_MAX_BODY_BYTES)
+                fail("E_SCHEMA_INVALID", "Git source 预影过大");
+            const saved = JSON.parse(raw.toString("utf8"));
+            if (saved.schema_version !== 1 || saved.project_id !== this.identity.project_id || saved.scenario_id !== this.identity.scenario_id || saved.repository !== kind
+                || !Number.isSafeInteger(saved.project_revision) || saved.project_revision < 0 || !/^[a-f0-9]{64}$/.test(saved.digest) || !/^[a-f0-9]{64}$/.test(saved.source_sha256)
+                || typeof saved.files !== "object" || saved.files === null || Array.isArray(saved.files))
+                fail("E_SCHEMA_INVALID", "Git source 预影 identity 无效");
+            const expected = { ...saved, files: Object.fromEntries(Object.entries(saved.files).map(([name, value]) => {
+                    assertSourceFilePath(name);
+                    if (typeof value !== "string" || Buffer.from(value, "base64").toString("base64") !== value)
+                        fail("E_SCHEMA_INVALID", "Git source 预影 bytes 无效");
+                    return [name, new Uint8Array(Buffer.from(value, "base64"))];
+                })) };
+            const head = await runGit(["-C", target, "rev-parse", "HEAD"]);
+            if (!GIT_OBJECT_ID.test(head))
+                fail("E_VALIDATION_FAILED", "Git HEAD 无效");
+            const tree = await runGit(["-C", target, "ls-tree", "-rz", head]);
+            const files = Object.create(null);
+            const caseFoldedPaths = new Set();
+            let size = 0;
+            for (const entry of tree.split("\0").filter(Boolean)) {
+                const match = /^(100644|100755) blob ([a-f0-9]{40,64})\t(.+)$/s.exec(entry);
+                if (!match)
+                    fail("E_VALIDATION_FAILED", "Git source 只允许普通 blob，禁止 symlink/submodule");
+                const name = match[3];
+                assertSourceFilePath(name);
+                const folded = name.toLowerCase();
+                if (caseFoldedPaths.has(folded))
+                    fail("E_PATH_OUTSIDE_PROJECT", "Git source 包含大小写冲突路径");
+                caseFoldedPaths.add(folded);
+                const { stdout } = await execFileAsync("git", ["-C", target, "cat-file", "blob", match[2]], { encoding: "buffer", windowsHide: true, timeout: 10_000, maxBuffer: PROJECT_GIT_HTTP_MAX_BODY_BYTES });
+                size += stdout.length;
+                if (size > PROJECT_GIT_HTTP_MAX_BODY_BYTES)
+                    fail("E_VALIDATION_FAILED", "Git source tree 过大");
+                files[name] = new Uint8Array(stdout);
+            }
+            if (Object.keys(files).length === 0)
+                fail("E_VALIDATION_FAILED", "Git 提交缺少作者源文件");
+            await this.assertCleanRepository(target);
+            if (await runGit(["-C", target, "rev-parse", "HEAD"]) !== head)
+                fail("E_VALIDATION_FAILED", "Git HEAD 在应用期间变化");
+            if (kind === "view")
+                await applyViewGitSource(this.projectRoot, files, expected);
+            else
+                await applyScenarioGitSource(this.projectRoot, kind, files, expected);
+            const current = await this.captureSource(kind);
+            await this.saveSourcePreimage(kind, current);
+            return this.sourceResult("applied", kind, current);
+        });
+    }
+    sourceResult(status, kind, capture) {
+        return { status, repository: kind, local_path: `${PROJECT_GIT_CONTROL_DIRECTORY}/repositories/${kind}`, project_revision: capture.project_revision, source_digest: capture.digest };
+    }
+    async pullManifest() {
+        const manifest = await this.readManifest();
+        const control = await ensureSafeProjectDirectory(this.projectRoot, PROJECT_GIT_CONTROL_DIRECTORY);
+        const target = await safeProjectPath(this.projectRoot, PROJECT_GIT_MANIFEST_PATH);
+        const temporary = join(control, `.manifest-${randomUUID()}.tmp`);
+        try {
+            await writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            await rename(temporary, target);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+        return manifest;
+    }
+    async pushManifest() {
+        const path = await assertSafeExistingProjectPath(this.projectRoot, join(this.projectRoot, PROJECT_GIT_MANIFEST_PATH));
+        if (!(await lstat(path)).isFile())
+            fail("E_SCHEMA_INVALID", "project git manifest cache 不是普通文件");
+        const bytes = await readFile(path);
+        if (bytes.byteLength > 256 * 1024)
+            fail("E_SCHEMA_INVALID", "project git manifest 过大");
+        let candidate;
+        try {
+            candidate = validateProjectGitManifest(JSON.parse(bytes.toString("utf8")), this.identity);
+        }
+        catch (error) {
+            if (error instanceof AuthoringBridgeError)
+                throw error;
+            fail("E_SCHEMA_INVALID", "project git manifest JSON 无效");
+        }
+        const [current, access] = await Promise.all([this.readManifest(), this.readAccess()]);
+        if (!access.permissions.metadata_write)
+            fail("E_REMOTE_FORBIDDEN", "当前 ACL 没有 manifest 写权限");
+        if (current.revision !== candidate.revision)
+            fail("E_VALIDATION_FAILED", "manifest revision 已变化，请先 pull");
+        const response = await this.transport.request({
+            project_id: this.identity.project_id,
+            method: "PUT",
+            path: remoteManifestPath(this.identity.scenario_id),
+            body: { expected_revision: current.revision, manifest: candidate.manifest },
+        });
+        const written = validateProjectGitManifest(bodyObject(response), this.identity);
+        if (written.revision <= current.revision)
+            fail("E_VALIDATION_FAILED", "manifest 写入未返回递增 revision");
+        return this.pullManifestFromValue(written);
+    }
+    async pullManifestFromValue(manifest) {
+        const control = await ensureSafeProjectDirectory(this.projectRoot, PROJECT_GIT_CONTROL_DIRECTORY);
+        const target = await safeProjectPath(this.projectRoot, PROJECT_GIT_MANIFEST_PATH);
+        const temporary = join(control, `.manifest-${randomUUID()}.tmp`);
+        try {
+            await writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            await rename(temporary, target);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+        return manifest;
+    }
+    async clone(kindValue) {
+        const kind = assertKind(kindValue);
+        const [manifest, access] = await Promise.all([this.readManifest(), this.readAccess()]);
+        checkGrant(access, kind, "read");
+        if (manifest.manifest.repositories[kind].remote_path !== expectedRemotePath(this.identity.scenario_id, kind))
+            fail("E_REMOTE_FORBIDDEN", "manifest remote path 与当前仓不一致");
+        const repositoriesRoot = await ensureSafeProjectDirectory(this.projectRoot, `${PROJECT_GIT_CONTROL_DIRECTORY}/repositories`);
+        const hooks = await ensureSafeProjectDirectory(this.projectRoot, `${PROJECT_GIT_CONTROL_DIRECTORY}/hooks-disabled`);
+        const target = await safeProjectPath(this.projectRoot, `${PROJECT_GIT_CONTROL_DIRECTORY}/repositories/${kind}`);
+        try {
+            await lstat(target);
+            fail("E_VALIDATION_FAILED", `${kind} 仓库已存在`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const rel = relative(this.projectRoot, target);
+        if (rel === "" || rel === ".git" || rel.startsWith(`..${sep}`))
+            fail("E_PATH_OUTSIDE_PROJECT", "project git clone target 无效");
+        const relay = await startGitRelay(this.identity, kind, this.transport);
+        try {
+            await assertRelayTarget(relay.url, repositoriesRoot);
+            await runGit([...gitBaseArgs(hooks), "clone", "--origin", "origin", "--", relay.url, target], repositoriesRoot);
+            await runGit([...gitBaseArgs(hooks), "-C", target, "remote", "set-url", "origin", semanticRemote(this.identity, kind)]);
+        }
+        finally {
+            await relay.close();
+        }
+        return this.result("cloned", kind, await existingRepository(this.projectRoot, target));
+    }
+    async fetch(kindValue) {
+        const kind = assertKind(kindValue);
+        const [manifest, access] = await Promise.all([this.readManifest(), this.readAccess()]);
+        checkGrant(access, kind, "read");
+        if (manifest.manifest.repositories[kind].remote_path !== expectedRemotePath(this.identity.scenario_id, kind))
+            fail("E_REMOTE_FORBIDDEN", "manifest remote path 与当前仓不一致");
+        const hooks = await ensureSafeProjectDirectory(this.projectRoot, `${PROJECT_GIT_CONTROL_DIRECTORY}/hooks-disabled`);
+        const target = await existingRepository(this.projectRoot, join(this.projectRoot, PROJECT_GIT_CONTROL_DIRECTORY, "repositories", kind));
+        const relay = await startGitRelay(this.identity, kind, this.transport);
+        try {
+            await assertRelayTarget(relay.url, target);
+            await runGit([...gitBaseArgs(hooks), "-C", target, "fetch", "--prune", "--", relay.url, "+refs/heads/*:refs/remotes/origin/*"]);
+        }
+        finally {
+            await relay.close();
+        }
+        return this.result("fetched", kind, target);
+    }
+    async push(kindValue) {
+        const kind = assertKind(kindValue);
+        const [manifest, access] = await Promise.all([this.readManifest(), this.readAccess()]);
+        checkGrant(access, kind, "write");
+        if (manifest.manifest.repositories[kind].remote_path !== expectedRemotePath(this.identity.scenario_id, kind))
+            fail("E_REMOTE_FORBIDDEN", "manifest remote path 与当前仓不一致");
+        const hooks = await ensureSafeProjectDirectory(this.projectRoot, `${PROJECT_GIT_CONTROL_DIRECTORY}/hooks-disabled`);
+        const target = await existingRepository(this.projectRoot, join(this.projectRoot, PROJECT_GIT_CONTROL_DIRECTORY, "repositories", kind));
+        const branch = await runGit(["-C", target, "symbolic-ref", "--short", "HEAD"]);
+        if (!/^[A-Za-z0-9][A-Za-z0-9._/-]{0,254}$/.test(branch) || branch.includes("..") || branch.endsWith(".") || branch.endsWith("/"))
+            fail("E_VALIDATION_FAILED", "当前 Git branch 无效或 detached");
+        const relay = await startGitRelay(this.identity, kind, this.transport);
+        try {
+            await assertRelayTarget(relay.url, target, true);
+            await runGit([...gitBaseArgs(hooks), "-c", "push.recurseSubmodules=no", "-C", target, "push", "--", relay.url, `HEAD:refs/heads/${branch}`]);
+        }
+        finally {
+            await relay.close();
+        }
+        return this.result("pushed", kind, target);
+    }
+    async result(status, kind, target) {
+        const head = await runGit(["-C", target, "rev-parse", "HEAD"]);
+        if (!GIT_OBJECT_ID.test(head))
+            fail("E_VALIDATION_FAILED", "Git HEAD identity 无效");
+        return { status, repository: kind, local_path: `${PROJECT_GIT_CONTROL_DIRECTORY}/repositories/${kind}`, head };
+    }
+}