@ebay-dt/bonfire-node 0.2.0-alpha.0 → 0.2.0-alpha.11

package/dist/lifecycle/local-prototype-lifecycle.js

@@ -1,9 +1,11 @@
 import { constants } from "node:fs";
+import { execFile as execFileCallback } from "node:child_process";
 import { lstat, open, rename, rm, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
+import { promisify } from "node:util";
 import { join, relative, sep } from "node:path";
 import { definePrototypeRef, getPrototypeUrl, LifecycleInputError, lifecycleFailure, lifecycleSuccess, parseCreatePrototypeInput, parseDuplicatePrototypeInput, parseEditPrototypeInput, parseBonfireIdentity, parsePrototypeCommandInput, parsePrototypeMetadata, slugifyPrototypeTitle, PrototypeRefError, parseGitModeSetting, } from "@ebay-dt/bonfire-core";
-import { commitPath, discardPath, GitRepositoryError, pushBranch, } from "../git-repository.js";
+import { commitPath, GitRepositoryError, pushBranch, pushCommitToBranch, remoteBranchCommit, } from "../git-repository.js";
 import { duplicatePrototype, PrototypeDuplicateError } from "../duplicate.js";
 import { PrototypeCatalog, } from "../prototype-catalog.js";
 import { PrototypeScaffoldError, scaffoldPrototype } from "../scaffold.js";
@@ -13,10 +15,19 @@ import { RepositoryBusyError, withRepositoryOperation, } from "./operation-gate.
 import { DeploymentProviderError, } from "../deployment-provider.js";
 import { assertIdentityBranchReady, synchronizeIdentityBranch, } from "./repository-synchronization.js";
 import { getRepositorySummary } from "./repository-summary.js";
+import { DeploymentWorktreeError, publishDeploymentSource, reportDeploymentIssue, } from "./deployment-worktree.js";
+import { commitPrototypePath, deletePrototypePath, discardPrototypePath, } from "./prototype-path-policy.js";
+import { clearPreparationMarker, readPreparationMarker, writePreparationMarker, } from "./preparation-marker.js";
+const execFile = promisify(execFileCallback);
 function repositoryRelativePath(runtime, ref) {
     const absolutePath = join(runtime.prototypeRoot, ref.login, ref.slug);
     return relative(runtime.repositoryRoot, absolutePath).split(sep).join("/");
 }
+function namespaceRelativePath(runtime, login) {
+    return relative(runtime.repositoryRoot, join(runtime.prototypeRoot, login))
+        .split(sep)
+        .join("/");
+}
 function destinationRef(identity, title) {
     const slug = slugifyPrototypeTitle(title);
     if (slug === null)
@@ -31,21 +42,72 @@ class PrototypeMetadataFileError extends Error {
 }
 class DeploymentUnavailableError extends Error {
 }
+class DeploymentSourcePushError extends Error {
+}
+class DeploymentNotAcceptedError extends Error {
+}
+const pendingPublications = new Map();
+function pendingPublicationKey(repositoryRoot, login) {
+    return `${repositoryRoot}\0${login}`;
+}
 function metadataPath(runtime, ref) {
     return join(runtime.prototypeRoot, ref.login, ref.slug, "metadata.json");
 }
-async function assertPrototypeDirectory(runtime, ref) {
-    const paths = [
+function prototypeDirectoryPaths(runtime, ref) {
+    return [
         runtime.prototypeRoot,
         join(runtime.prototypeRoot, ref.login),
         join(runtime.prototypeRoot, ref.login, ref.slug),
     ];
-    try {
-        for (const path of paths) {
+}
+async function capturePrototypeDirectory(runtime, ref) {
+    const entries = [];
+    for (const path of prototypeDirectoryPaths(runtime, ref)) {
+        try {
             const stats = await lstat(path);
-            if (stats.isSymbolicLink() || !stats.isDirectory()) {
-                throw new PrototypeMetadataFileError();
+            entries.push({
+                path,
+                kind: stats.isSymbolicLink()
+                    ? "symlink"
+                    : stats.isDirectory()
+                        ? "directory"
+                        : "other",
+                dev: stats.dev,
+                ino: stats.ino,
+            });
+        }
+        catch (error) {
+            if (error &&
+                typeof error === "object" &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                entries.push({ path, kind: "missing" });
+                continue;
             }
+            throw new PrototypeMetadataFileError();
+        }
+    }
+    return entries;
+}
+function samePrototypeDirectorySnapshot(expected, actual) {
+    return expected.every((entry, index) => {
+        const current = actual[index];
+        return (current !== undefined &&
+            current.path === entry.path &&
+            current.kind === entry.kind &&
+            current.dev === entry.dev &&
+            current.ino === entry.ino);
+    });
+}
+async function assertPrototypeDirectory(runtime, ref, expected) {
+    try {
+        const actual = await capturePrototypeDirectory(runtime, ref);
+        if (expected !== undefined &&
+            !samePrototypeDirectorySnapshot(expected, actual)) {
+            throw new PrototypeMetadataFileError();
+        }
+        if (actual.some((entry) => entry.kind !== "directory")) {
+            throw new PrototypeMetadataFileError();
         }
     }
     catch (error) {
@@ -79,18 +141,6 @@ async function readMetadataDocument(runtime, ref, themeRegistry) {
         throw new PrototypeMetadataFileError();
     }
 }
-async function removePrototypeDirectory(runtime, ref) {
-    await assertPrototypeDirectory(runtime, ref);
-    try {
-        await rm(join(runtime.prototypeRoot, ref.login, ref.slug), {
-            force: false,
-            recursive: true,
-        });
-    }
-    catch {
-        throw new PrototypeMetadataFileError();
-    }
-}
 async function writeMetadataDocument(runtime, ref, document) {
     const path = metadataPath(runtime, ref);
     const temporaryPath = `${path}.${randomUUID()}.tmp`;
@@ -114,26 +164,6 @@ async function writeMetadataDocument(runtime, ref, document) {
         await rm(temporaryPath, { force: true }).catch(() => undefined);
     }
 }
-async function mergeIdentityBranchToPrimary(repository, options) {
-    if (options.branch === options.primaryBranch)
-        return;
-    const hasRemote = (await repository.remotes()).some((remote) => remote.name === options.remote);
-    if (!hasRemote)
-        return;
-    await repository.checkout([options.primaryBranch]);
-    try {
-        await repository.merge([
-            options.branch,
-            "--no-ff",
-            "-m",
-            `merge: ${options.branch}`,
-        ]);
-        await repository.push(options.remote, options.primaryBranch);
-    }
-    finally {
-        await repository.checkout([options.branch]);
-    }
-}
 function mapError(error) {
     if (error instanceof PrototypeNotFoundError)
         return "not-found";
@@ -175,6 +205,11 @@ function mapError(error) {
     if (error instanceof DeploymentUnavailableError) {
         return "deployment-unavailable";
     }
+    if (error instanceof DeploymentSourcePushError ||
+        error instanceof DeploymentNotAcceptedError ||
+        error instanceof DeploymentWorktreeError) {
+        return "deployment-failure";
+    }
     if (error instanceof DeploymentProviderError) {
         return error.kind === "timeout" ? "timeout" : "deployment-failure";
     }
@@ -185,6 +220,15 @@ function resultFrom(operation) {
         .then(lifecycleSuccess)
         .catch((error) => lifecycleFailure(mapError(error)));
 }
+async function diagnoseMetadataStep(step, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        reportDeploymentIssue("publication", step, error);
+        throw error;
+    }
+}
 export class LocalPrototypeLifecycle {
     #runtime;
     gitMode;
@@ -194,9 +238,14 @@ export class LocalPrototypeLifecycle {
     #deploymentProvider;
     #applicationId;
     #themeRegistry;
+    #publishDeploymentSource;
+    #installDependencies;
+    #restartRequired = false;
+    #preparationAttention = new Map();
     constructor(options) {
         const internalOptions = options;
-        const runtime = internalOptions.runtime ?? createPrototypeLifecycleRuntime(internalOptions);
+        const runtime = internalOptions.runtime ??
+            createPrototypeLifecycleRuntime(internalOptions);
         this.#runtime = {
             ...runtime,
             gitMode: parseGitModeSetting(runtime.gitMode),
@@ -214,6 +263,11 @@ export class LocalPrototypeLifecycle {
             internalOptions.preparePrototypeFiles ?? (() => undefined);
         this.#deploymentProvider = internalOptions.deploymentProvider;
         this.#applicationId = internalOptions.applicationId;
+        this.#publishDeploymentSource =
+            internalOptions.publishDeploymentSource === null
+                ? null
+                : (internalOptions.publishDeploymentSource ?? publishDeploymentSource);
+        this.#installDependencies = options.installDependencies;
         if (this.#deploymentProvider &&
             (typeof this.#applicationId !== "string" ||
                 this.#applicationId.length === 0)) {
@@ -230,22 +284,27 @@ export class LocalPrototypeLifecycle {
         }
         return branch;
     }
-    async #ownedPrototype(identity, input) {
+    async #authorizedPrototype(identity, input) {
         const verifiedIdentity = await this.#verifiedIdentity(identity);
         const normalizedInput = parsePrototypeCommandInput(input);
         if (normalizedInput.ref.login !== verifiedIdentity.login) {
             throw new PrototypeOwnershipError();
         }
-        const summary = await this.#catalog.getSummary(normalizedInput.ref);
-        if (!summary) {
-            throw new PrototypeNotFoundError();
-        }
+        const directorySnapshot = await capturePrototypeDirectory(this.#runtime, normalizedInput.ref);
         return {
             ref: normalizedInput.ref,
             path: repositoryRelativePath(this.#runtime, normalizedInput.ref),
-            summary,
+            directorySnapshot,
         };
     }
+    async #ownedPrototype(identity, input) {
+        const authorized = await this.#authorizedPrototype(identity, input);
+        const summary = await this.#catalog.getSummary(authorized.ref);
+        if (!summary) {
+            throw new PrototypeNotFoundError();
+        }
+        return { ...authorized, summary };
+    }
     async #prepareMutationBranch(login) {
         await assertIdentityBranchReady(this.#repository, login);
         return login;
@@ -280,26 +339,160 @@ export class LocalPrototypeLifecycle {
                 if (this.#runtime.gitMode === "manual" ||
                     this.#runtime.automaticBranchSwitch === "disabled") {
                     await this.#currentBranch();
-                    return { status: "disabled" };
+                    const disabled = {
+                        status: "disabled",
+                        effects: {
+                            changed: false,
+                            pushed: false,
+                            reconciledPaths: [],
+                            restartRequired: false,
+                        },
+                    };
+                    this.#preparationAttention.set(verifiedIdentity.login, disabled);
+                    return disabled;
                 }
                 const synchronization = await synchronizeIdentityBranch(this.#repository, {
                     identityBranch: verifiedIdentity.login,
                     primaryBranch: this.#runtime.primaryBranch,
                     remote: this.#runtime.remote,
+                    prototypeRoot: relative(this.#runtime.repositoryRoot, this.#runtime.prototypeRoot)
+                        .split(sep)
+                        .join("/"),
                 });
-                if (synchronization.status !== "synchronized") {
-                    return {
-                        status: synchronization.status,
+                const reconciledPaths = synchronization.status === "synchronized" &&
+                    synchronization.platformPaths.length === 0
+                    ? synchronization.affectedPaths.filter((path) => this.#runtime.managedRepositoryPaths.includes(path))
+                    : synchronization.platformPaths;
+                const effects = {
+                    changed: synchronization.changed,
+                    pushed: synchronization.pushed,
+                    reconciledPaths,
+                    restartRequired: synchronization.status === "synchronized" &&
+                        synchronization.platformPaths.length === 0
+                        ? reconciledPaths.length > 0
+                        : synchronization.restartRequired,
+                    ...(synchronization.platformPaths.length > 0
+                        ? { platformPaths: synchronization.platformPaths }
+                        : {}),
+                    ...(synchronization.dependencyPaths.length > 0
+                        ? { dependencyPaths: synchronization.dependencyPaths }
+                        : {}),
+                    ...(synchronization.preparationRequired
+                        ? { preparationRequired: true }
+                        : {}),
+                };
+                if (effects.restartRequired)
+                    this.#restartRequired = true;
+                if (effects.preparationRequired) {
+                    await writePreparationMarker(this.#repository, this.#runtime.repositoryRoot, effects.dependencyPaths ?? []);
+                }
+                if (synchronization.status === "deferred") {
+                    const attention = {
+                        status: "deferred",
+                        reason: synchronization.reason,
+                        effects,
+                        ...(synchronization.affectedPaths.length > 0
+                            ? { affectedPaths: synchronization.affectedPaths }
+                            : {}),
+                    };
+                    this.#preparationAttention.set(verifiedIdentity.login, attention);
+                    return attention;
+                }
+                if (synchronization.status === "unsafe") {
+                    const attention = {
+                        status: "unsafe",
                         reason: synchronization.reason,
+                        effects,
                         ...(synchronization.affectedPaths.length > 0
                             ? { affectedPaths: synchronization.affectedPaths }
                             : {}),
                     };
+                    this.#preparationAttention.set(verifiedIdentity.login, attention);
+                    return attention;
                 }
-                return { status: "ready" };
+                const ready = {
+                    status: "ready",
+                    effects,
+                    ...(synchronization.affectedPaths.length > 0
+                        ? { affectedPaths: synchronization.affectedPaths }
+                        : {}),
+                };
+                this.#preparationAttention.delete(verifiedIdentity.login);
+                return ready;
             });
         });
     }
+    async prepareDependencies(dependencyPaths = [], installer) {
+        return resultFrom(async () => withRepositoryOperation(this.#runtime.repositoryRealPath, async () => {
+            let pending = null;
+            try {
+                pending = await readPreparationMarker(this.#repository, this.#runtime.repositoryRoot);
+            }
+            catch {
+                // A retained/corrupt marker is recovery truth. Restricted modes must
+                // preserve it without attempting installation; managed mode must
+                // report not-ready rather than guessing what to install.
+                if (this.#runtime.gitMode === "manual" ||
+                    this.#runtime.automaticBranchSwitch === "disabled") {
+                    return {
+                        status: "skipped",
+                        dependencyPaths: [...dependencyPaths],
+                        pending: true,
+                        restartRequired: false,
+                    };
+                }
+                return {
+                    status: "failed",
+                    dependencyPaths: [...dependencyPaths],
+                    pending: true,
+                    restartRequired: true,
+                };
+            }
+            const paths = [...new Set([...(pending ?? []), ...dependencyPaths])];
+            if (this.#runtime.gitMode === "manual" ||
+                this.#runtime.automaticBranchSwitch === "disabled") {
+                return {
+                    status: "skipped",
+                    dependencyPaths: paths,
+                    pending: pending !== null,
+                    restartRequired: false,
+                };
+            }
+            // An empty path list is still an obligation when the marker exists.
+            // Do not reinterpret a retained marker as "not required".
+            if (paths.length === 0 && pending === null) {
+                return {
+                    status: "not-required",
+                    dependencyPaths: [],
+                    pending: false,
+                    restartRequired: false,
+                };
+            }
+            await writePreparationMarker(this.#repository, this.#runtime.repositoryRoot, paths);
+            try {
+                await (installer ??
+                    this.#installDependencies ??
+                    (async (root) => {
+                        await execFile("pnpm", ["install"], { cwd: root });
+                    }))(this.#runtime.repositoryRoot);
+            }
+            catch {
+                return {
+                    status: "failed",
+                    dependencyPaths: paths,
+                    pending: true,
+                    restartRequired: true,
+                };
+            }
+            await clearPreparationMarker(this.#repository, this.#runtime.repositoryRoot);
+            return {
+                status: "prepared",
+                dependencyPaths: paths,
+                pending: false,
+                restartRequired: true,
+            };
+        }));
+    }
     async create(identity, input) {
         return resultFrom(async () => {
             const verifiedIdentity = await this.#verifiedIdentity(identity);
@@ -339,11 +532,13 @@ export class LocalPrototypeLifecycle {
                     };
                 }
                 await commitPath(this.#repository, repositoryRelativePath(this.#runtime, ref), `init: ${ref.slug}`);
-                const push = await pushBranch(this.#repository, this.#runtime.remote, branch);
+                const sourceSha = await this.#headCommit();
+                const outcome = await this.#publishOrdinaryNamespace(verifiedIdentity, "create", ref, repositoryRelativePath(this.#runtime, ref), sourceSha);
                 return {
                     ref,
                     url: getPrototypeUrl(ref),
-                    remoteStatus: push.remoteStatus,
+                    remoteStatus: "local-only",
+                    outcome,
                 };
             });
         });
@@ -389,16 +584,34 @@ export class LocalPrototypeLifecycle {
             const verifiedIdentity = await this.#verifiedIdentity(identity);
             const normalizedInput = parsePrototypeCommandInput(input);
             return withRepositoryOperation(this.#runtime.repositoryRealPath, async () => {
-                const { ref, path } = await this.#ownedPrototype(verifiedIdentity, normalizedInput);
+                const { ref, path, directorySnapshot } = await this.#authorizedPrototype(verifiedIdentity, normalizedInput);
+                if (directorySnapshot.at(-1)?.kind === "missing") {
+                    throw new PrototypeNotFoundError();
+                }
                 const branch = this.#runtime.gitMode === "managed"
                     ? await this.#prepareMutationBranch(verifiedIdentity.login)
                     : undefined;
-                await removePrototypeDirectory(this.#runtime, ref);
+                await assertPrototypeDirectory(this.#runtime, ref, directorySnapshot);
+                await deletePrototypePath(this.#repository, path, branch === undefined ? undefined : `delete: ${ref.slug}`);
                 if (branch !== undefined) {
-                    await commitPath(this.#repository, path, `delete: ${ref.slug}`);
-                    await pushBranch(this.#repository, this.#runtime.remote, branch);
+                    const sourceSha = await this.#headCommit();
+                    const outcome = await this.#publishOrdinaryNamespace(verifiedIdentity, "delete", ref, path, sourceSha);
+                    return {
+                        deleted: true,
+                        ref,
+                        outcome,
+                    };
                 }
-                return { deleted: true, ref };
+                return {
+                    deleted: true,
+                    ref,
+                    outcome: {
+                        local: { status: "completed" },
+                        upload: { status: "not-attempted" },
+                        preview: { status: "not-attempted" },
+                        publication: { status: "not-attempted" },
+                    },
+                };
             });
         });
     }
@@ -417,7 +630,7 @@ export class LocalPrototypeLifecycle {
     async getRepositorySummary(identity) {
         return resultFrom(async () => {
             const verifiedIdentity = await this.#verifiedIdentity(identity);
-            return getRepositorySummary({
+            return withRepositoryOperation(this.#runtime.repositoryRealPath, async () => getRepositorySummary({
                 repository: this.#repository,
                 catalog: this.#catalog,
                 repositoryRoot: this.#runtime.repositoryRoot,
@@ -426,13 +639,16 @@ export class LocalPrototypeLifecycle {
                 mode: this.#runtime.gitMode,
                 remote: this.#runtime.remote,
                 primaryBranch: this.#runtime.primaryBranch,
-            });
+                restartRequired: this.#restartRequired,
+                preparationAttention: this.#preparationAttention.get(verifiedIdentity.login),
+                preparationPending: (await readPreparationMarker(this.#repository, this.#runtime.repositoryRoot)) !== null,
+            }));
         });
     }
     async checkRepositorySummary(identity) {
         return resultFrom(async () => {
             const verifiedIdentity = await this.#verifiedIdentity(identity);
-            return getRepositorySummary({
+            return withRepositoryOperation(this.#runtime.repositoryRealPath, async () => getRepositorySummary({
                 repository: this.#repository,
                 catalog: this.#catalog,
                 repositoryRoot: this.#runtime.repositoryRoot,
@@ -441,10 +657,149 @@ export class LocalPrototypeLifecycle {
                 mode: this.#runtime.gitMode,
                 remote: this.#runtime.remote,
                 primaryBranch: this.#runtime.primaryBranch,
+                restartRequired: this.#restartRequired,
+                preparationAttention: this.#preparationAttention.get(verifiedIdentity.login),
+                preparationPending: (await readPreparationMarker(this.#repository, this.#runtime.repositoryRoot)) !== null,
                 refresh: true,
-            });
+            }));
         });
     }
+    async #headCommit() {
+        const commit = (await this.#repository.raw(["rev-parse", "HEAD"])).trim();
+        if (!/^[0-9a-f]{40,64}$/iu.test(commit)) {
+            throw new GitRepositoryError("malformed-output", "head-commit");
+        }
+        return commit.toLowerCase();
+    }
+    #workspaceRuntime(workspacePath, workspaceRepository) {
+        return {
+            ...this.#runtime,
+            repositoryRoot: workspacePath,
+            repositoryRealPath: workspacePath,
+            prototypeRoot: join(workspacePath, relative(this.#runtime.repositoryRoot, this.#runtime.prototypeRoot)),
+            gitRepository: workspaceRepository,
+        };
+    }
+    #pendingKey(login) {
+        return pendingPublicationKey(this.#runtime.repositoryRoot, login);
+    }
+    #rememberPending(pending) {
+        pendingPublications.set(this.#pendingKey(pending.identity.login), pending);
+    }
+    #clearPending(login) {
+        pendingPublications.delete(this.#pendingKey(login));
+    }
+    #recoveryValue(pending, outcome) {
+        return {
+            recoveryId: pending.recoveryId,
+            operation: pending.operation,
+            kind: pending.kind,
+            ref: pending.ref,
+            sourceSha: pending.sourceSha,
+            ...(pending.previewUrl === undefined
+                ? {}
+                : { previewUrl: pending.previewUrl }),
+            ...(pending.deploymentId === undefined
+                ? {}
+                : { deploymentId: pending.deploymentId }),
+            ...(pending.readyState === undefined
+                ? {}
+                : { readyState: pending.readyState }),
+            ...(pending.acceptedAt === undefined
+                ? {}
+                : { acceptedAt: pending.acceptedAt }),
+            outcome,
+        };
+    }
+    async #publishCommittedNamespace(identity, sourceSha) {
+        if (this.#publishDeploymentSource === null) {
+            throw new DeploymentUnavailableError();
+        }
+        return this.#publishDeploymentSource(this.#repository, {
+            remote: this.#runtime.remote,
+            primaryBranch: this.#runtime.primaryBranch,
+            sourceSha,
+            namespacePath: namespaceRelativePath(this.#runtime, identity.login),
+            commitIdentity: this.#runtime.commitIdentity,
+        }, async () => undefined);
+    }
+    async #publishOrdinaryNamespace(identity, operation, ref, path, sourceSha) {
+        const baseOutcome = {
+            local: { status: "completed", checkpointSha: sourceSha },
+            upload: { status: "not-attempted", sourceSha },
+            preview: { status: "not-attempted" },
+            publication: {
+                status: this.#publishDeploymentSource === null ? "not-attempted" : "pending",
+            },
+        };
+        if (this.#publishDeploymentSource === null)
+            return baseOutcome;
+        try {
+            const publication = await this.#publishCommittedNamespace(identity, sourceSha);
+            this.#clearPending(identity.login);
+            return {
+                ...baseOutcome,
+                publication: {
+                    status: "confirmed",
+                    revision: publication.publicationSha,
+                },
+            };
+        }
+        catch {
+            const pending = {
+                recoveryId: randomUUID(),
+                operation,
+                kind: "ordinary-publication",
+                identity,
+                ref,
+                path,
+                sourceSha,
+            };
+            this.#rememberPending(pending);
+            return {
+                ...baseOutcome,
+                publication: {
+                    status: "failed",
+                    recoveryId: pending.recoveryId,
+                },
+            };
+        }
+    }
+    async #publishDeploymentMetadata(pending) {
+        if (this.#publishDeploymentSource === null) {
+            throw new DeploymentUnavailableError();
+        }
+        return this.#publishDeploymentSource(this.#repository, {
+            remote: this.#runtime.remote,
+            primaryBranch: this.#runtime.primaryBranch,
+            sourceSha: pending.sourceSha,
+            namespacePath: namespaceRelativePath(this.#runtime, pending.identity.login),
+            commitIdentity: this.#runtime.commitIdentity,
+        }, async ({ path, repository }) => {
+            const workspaceRuntime = this.#workspaceRuntime(path, repository);
+            const mergedDocument = await diagnoseMetadataStep("metadata-read", () => readMetadataDocument(workspaceRuntime, pending.ref, this.#themeRegistry));
+            await diagnoseMetadataStep("metadata-write", () => writeMetadataDocument(workspaceRuntime, pending.ref, {
+                ...mergedDocument,
+                previewUrl: pending.previewUrl,
+                updatedAt: pending.acceptedAt,
+            }));
+            await diagnoseMetadataStep("metadata-commit", () => commitPath(repository, pending.path, `deploy: ${pending.ref.slug} (metadata)`));
+        });
+    }
+    async #deploymentValue(pending, publicationWarnings = [], outcome) {
+        const warnings = [...publicationWarnings];
+        return {
+            deployed: true,
+            ref: pending.ref,
+            previewUrl: pending.previewUrl,
+            deploymentId: pending.deploymentId,
+            sourceSha: pending.sourceSha,
+            readyState: pending.readyState,
+            ...(outcome === undefined ? {} : { outcome }),
+            warning: publicationWarnings[0],
+            ...(warnings.length === 0 ? {} : { warnings }),
+        };
+    }
     async deploy(identity, input) {
         if (this.#runtime.gitMode === "manual") {
             return lifecycleFailure("forbidden");
@@ -457,7 +812,7 @@ export class LocalPrototypeLifecycle {
             }
             return withRepositoryOperation(this.#runtime.repositoryRealPath, async () => {
                 const { ref, path } = await this.#ownedPrototype(verifiedIdentity, normalizedInput);
-                const branch = await this.#prepareMutationBranch(verifiedIdentity.login);
+                await assertIdentityBranchReady(this.#repository, verifiedIdentity.login);
                 await assertPrototypeDirectory(this.#runtime, ref);
                 const document = await readMetadataDocument(this.#runtime, ref, this.#themeRegistry);
                 const metadata = parsePrototypeMetadata(document, {
@@ -466,60 +821,344 @@ export class LocalPrototypeLifecycle {
                 if (metadata.authorLogin !== ref.login) {
                     throw new PrototypeNotFoundError();
                 }
-                await commitPath(this.#repository, path, `deploy: ${ref.slug}`);
-                await pushBranch(this.#repository, this.#runtime.remote, branch);
-                const deployment = await this.#deploymentProvider.deploy({
-                    applicationId: this.#applicationId,
-                    login: verifiedIdentity.login,
-                });
-                const previewUrl = new URL(getPrototypeUrl(ref).slice(1), `${deployment.url.replace(/\/+$/, "")}/`).toString();
-                let warning;
+                await commitPrototypePath(this.#repository, path, `deploy: ${ref.slug}`);
+                const sourceSha = await this.#headCommit();
+                let sourcePush;
                 try {
-                    await writeMetadataDocument(this.#runtime, ref, {
-                        ...document,
-                        previewUrl,
-                        updatedAt: new Date().toISOString(),
-                    });
-                    await commitPath(this.#repository, path, `deploy: ${ref.slug} (metadata)`);
-                    await pushBranch(this.#repository, this.#runtime.remote, branch);
-                }
-                catch {
-                    warning = "metadata-persistence-failed";
+                    sourcePush = await pushCommitToBranch(this.#repository, this.#runtime.remote, sourceSha, verifiedIdentity.login, true);
                 }
-                if (warning === undefined) {
-                    try {
-                        await mergeIdentityBranchToPrimary(this.#repository, {
-                            branch,
-                            primaryBranch: this.#runtime.primaryBranch,
-                            remote: this.#runtime.remote,
-                        });
+                catch (error) {
+                    if (error instanceof GitRepositoryError) {
+                        const pending = {
+                            recoveryId: randomUUID(),
+                            operation: "deploy",
+                            kind: "deployment-upload",
+                            identity: verifiedIdentity,
+                            ref,
+                            path,
+                            sourceSha,
+                        };
+                        this.#rememberPending(pending);
+                        return {
+                            deployed: false,
+                            ref,
+                            sourceSha,
+                            warning: "upload-unconfirmed",
+                            outcome: {
+                                local: { status: "completed", checkpointSha: sourceSha },
+                                upload: {
+                                    status: "unconfirmed",
+                                    sourceSha,
+                                },
+                                preview: { status: "not-attempted" },
+                                publication: {
+                                    status: "pending",
+                                    recoveryId: pending.recoveryId,
+                                },
+                            },
+                        };
                     }
-                    catch {
-                        warning = "primary-merge-failed";
+                    throw error;
+                }
+                if (sourcePush.remoteStatus !== "pushed") {
+                    throw new DeploymentSourcePushError();
+                }
+                let deployment;
+                try {
+                    deployment = await this.#deploymentProvider.deploy({
+                        applicationId: this.#applicationId,
+                        login: verifiedIdentity.login,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof DeploymentProviderError &&
+                        [
+                            "timeout",
+                            "transport-failure",
+                            "invalid-response",
+                            "invalid-url",
+                        ].includes(error.kind)) {
+                        const pending = {
+                            recoveryId: randomUUID(),
+                            operation: "deploy",
+                            kind: "deployment-preview-unconfirmed",
+                            identity: verifiedIdentity,
+                            ref,
+                            path,
+                            sourceSha,
+                        };
+                        this.#rememberPending(pending);
+                        return {
+                            deployed: false,
+                            ref,
+                            sourceSha,
+                            warning: "preview-unconfirmed",
+                            outcome: {
+                                local: { status: "completed", checkpointSha: sourceSha },
+                                upload: { status: "confirmed", sourceSha },
+                                preview: { status: "unconfirmed" },
+                                publication: { status: "not-attempted" },
+                            },
+                        };
                     }
+                    throw error;
                 }
-                return {
-                    deployed: true,
+                if (deployment.commitSha.toLowerCase() !== sourceSha ||
+                    !["READY", "QUEUED", "INITIALIZING", "BUILDING"].includes(deployment.readyState)) {
+                    throw new DeploymentNotAcceptedError();
+                }
+                const previewUrl = new URL(getPrototypeUrl(ref).slice(1), `${deployment.url.replace(/\/+$/, "")}/`).toString();
+                const pending = {
+                    recoveryId: randomUUID(),
+                    operation: "deploy",
+                    kind: "deployment-publication",
+                    identity: verifiedIdentity,
                     ref,
+                    path,
                     previewUrl,
                     deploymentId: deployment.deploymentId,
+                    sourceSha,
+                    acceptedAt: new Date().toISOString(),
                     readyState: deployment.readyState,
-                    warning,
                 };
+                const acceptedOutcome = {
+                    local: { status: "completed", checkpointSha: sourceSha },
+                    upload: { status: "confirmed", sourceSha },
+                    preview: {
+                        status: "accepted",
+                        previewUrl,
+                        deploymentId: deployment.deploymentId,
+                    },
+                    publication: { status: "pending" },
+                };
+                try {
+                    const publication = await this.#publishDeploymentMetadata(pending);
+                    this.#clearPending(verifiedIdentity.login);
+                    return this.#deploymentValue(pending, publication.cleanupFailed ? ["publication-cleanup-failed"] : [], {
+                        ...acceptedOutcome,
+                        publication: {
+                            status: "confirmed",
+                            revision: publication.publicationSha,
+                        },
+                    });
+                }
+                catch (error) {
+                    // Keep the accepted deployment retryable for every publication
+                    // failure, including metadata preparation failures.
+                    this.#rememberPending(pending);
+                    return this.#deploymentValue(pending, [
+                        error instanceof DeploymentWorktreeError &&
+                            error.kind !== "cleanup-failure" &&
+                            error.kind !== "metadata-failure"
+                            ? "primary-merge-failed"
+                            : "metadata-persistence-failed",
+                        ...(error instanceof DeploymentWorktreeError &&
+                            error.cleanupFailed
+                            ? ["publication-cleanup-failed"]
+                            : []),
+                    ], {
+                        ...acceptedOutcome,
+                        publication: {
+                            status: "failed",
+                            recoveryId: pending.recoveryId,
+                        },
+                    });
+                }
+            });
+        });
+    }
+    async getPendingRecovery(identity) {
+        return resultFrom(async () => {
+            const verifiedIdentity = await this.#verifiedIdentity(identity);
+            const pending = pendingPublications.get(this.#pendingKey(verifiedIdentity.login));
+            if (pending === undefined)
+                return null;
+            return this.#recoveryValue(pending, {
+                local: { status: "completed", checkpointSha: pending.sourceSha },
+                upload: {
+                    status: pending.kind === "deployment-upload" ? "unconfirmed" : "confirmed",
+                    sourceSha: pending.sourceSha,
+                },
+                preview: pending.kind === "deployment-publication"
+                    ? {
+                        status: "accepted",
+                        previewUrl: pending.previewUrl,
+                        deploymentId: pending.deploymentId,
+                    }
+                    : pending.kind === "deployment-preview-unconfirmed"
+                        ? { status: "unconfirmed" }
+                        : { status: "not-attempted" },
+                publication: {
+                    status: pending.kind === "deployment-upload"
+                        ? "pending"
+                        : pending.kind === "deployment-preview-unconfirmed"
+                            ? "not-attempted"
+                            : "failed",
+                    ...(pending.kind === "deployment-preview-unconfirmed"
+                        ? {}
+                        : { recoveryId: pending.recoveryId }),
+                },
             });
         });
     }
+    async retryPendingPublication(identity, recoveryId) {
+        if (this.#runtime.gitMode === "manual") {
+            return lifecycleFailure("forbidden");
+        }
+        return resultFrom(async () => {
+            const verifiedIdentity = await this.#verifiedIdentity(identity);
+            const pending = pendingPublications.get(this.#pendingKey(verifiedIdentity.login));
+            if (pending === undefined || pending.recoveryId !== recoveryId) {
+                throw new DeploymentUnavailableError();
+            }
+            return withRepositoryOperation(this.#runtime.repositoryRealPath, async () => {
+                await assertIdentityBranchReady(this.#repository, verifiedIdentity.login);
+                if (pending.kind === "deployment-preview-unconfirmed") {
+                    throw new DeploymentUnavailableError();
+                }
+                let deploymentPending = pending;
+                if (pending.kind === "ordinary-publication") {
+                    deploymentPending = {
+                        ...pending,
+                        sourceSha: await this.#headCommit(),
+                    };
+                    this.#rememberPending(deploymentPending);
+                }
+                if (pending.kind === "deployment-upload") {
+                    const remoteSource = await remoteBranchCommit(this.#repository, this.#runtime.remote, verifiedIdentity.login);
+                    if (remoteSource !== pending.sourceSha) {
+                        const upload = await pushCommitToBranch(this.#repository, this.#runtime.remote, pending.sourceSha, verifiedIdentity.login, true);
+                        if (upload.remoteStatus !== "pushed") {
+                            throw new DeploymentSourcePushError();
+                        }
+                    }
+                    if (!this.#deploymentProvider) {
+                        throw new DeploymentUnavailableError();
+                    }
+                    let deployment;
+                    try {
+                        deployment = await this.#deploymentProvider.deploy({
+                            applicationId: this.#applicationId,
+                            login: verifiedIdentity.login,
+                        });
+                    }
+                    catch (error) {
+                        if (error instanceof DeploymentProviderError &&
+                            [
+                                "timeout",
+                                "transport-failure",
+                                "invalid-response",
+                                "invalid-url",
+                            ].includes(error.kind)) {
+                            const uncertain = {
+                                ...pending,
+                                kind: "deployment-preview-unconfirmed",
+                            };
+                            this.#rememberPending(uncertain);
+                            return this.#recoveryValue(uncertain, {
+                                local: {
+                                    status: "completed",
+                                    checkpointSha: pending.sourceSha,
+                                },
+                                upload: {
+                                    status: "confirmed",
+                                    sourceSha: pending.sourceSha,
+                                },
+                                preview: { status: "unconfirmed" },
+                                publication: { status: "not-attempted" },
+                            });
+                        }
+                        throw error;
+                    }
+                    if (deployment.commitSha.toLowerCase() !== pending.sourceSha ||
+                        !["READY", "QUEUED", "INITIALIZING", "BUILDING"].includes(deployment.readyState)) {
+                        throw new DeploymentNotAcceptedError();
+                    }
+                    deploymentPending = {
+                        ...pending,
+                        kind: "deployment-publication",
+                        previewUrl: new URL(getPrototypeUrl(pending.ref).slice(1), `${deployment.url.replace(/\/+$/, "")}/`).toString(),
+                        deploymentId: deployment.deploymentId,
+                        acceptedAt: new Date().toISOString(),
+                        readyState: deployment.readyState,
+                    };
+                    this.#rememberPending(deploymentPending);
+                }
+                const publication = deploymentPending.kind === "deployment-publication"
+                    ? await this.#publishDeploymentMetadata(deploymentPending)
+                    : await this.#publishCommittedNamespace(verifiedIdentity, deploymentPending.sourceSha);
+                this.#clearPending(verifiedIdentity.login);
+                return this.#recoveryValue(deploymentPending, {
+                    local: {
+                        status: "completed",
+                        checkpointSha: deploymentPending.sourceSha,
+                    },
+                    upload: {
+                        status: "confirmed",
+                        sourceSha: deploymentPending.sourceSha,
+                    },
+                    preview: deploymentPending.kind === "deployment-publication"
+                        ? {
+                            status: "accepted",
+                            previewUrl: deploymentPending.previewUrl,
+                            deploymentId: deploymentPending.deploymentId,
+                        }
+                        : { status: "not-attempted" },
+                    publication: {
+                        status: "confirmed",
+                        revision: publication.publicationSha,
+                    },
+                });
+            });
+        });
+    }
+    /** Compatibility wrapper; recovery-ID retry is the implementation. */
+    async retryPublish(identity, input) {
+        if (this.#runtime.gitMode === "manual") {
+            return lifecycleFailure("forbidden");
+        }
+        let normalizedInput;
+        try {
+            normalizedInput = parsePrototypeCommandInput(input);
+        }
+        catch {
+            return lifecycleFailure("invalid-input");
+        }
+        const pending = pendingPublications.get(this.#pendingKey(identity.login));
+        if (pending === undefined ||
+            pending.kind !== "deployment-publication" ||
+            pending.ref.login !== normalizedInput.ref.login ||
+            pending.ref.slug !== normalizedInput.ref.slug) {
+            return lifecycleFailure("deployment-unavailable");
+        }
+        const result = await this.retryPendingPublication(identity, pending.recoveryId);
+        if (!result.ok)
+            return result;
+        const current = pendingPublications.get(this.#pendingKey(identity.login));
+        const completed = {
+            ...pending,
+            ...(current ?? {}),
+            sourceSha: result.value.sourceSha,
+            ...(result.value.previewUrl === undefined
+                ? {}
+                : { previewUrl: result.value.previewUrl }),
+            ...(result.value.deploymentId === undefined
+                ? {}
+                : { deploymentId: result.value.deploymentId }),
+        };
+        return lifecycleSuccess(await this.#deploymentValue(completed, [], result.value.outcome));
+    }
     async save(identity, input) {
         if (this.#runtime.gitMode === "manual") {
             return lifecycleFailure("forbidden");
         }
         return resultFrom(async () => {
             const verifiedIdentity = await this.#verifiedIdentity(identity);
-            const { ref, path } = await this.#ownedPrototype(verifiedIdentity, input);
             return withRepositoryOperation(this.#runtime.repositoryRealPath, async () => {
                 await this.#prepareMutationBranch(verifiedIdentity.login);
-                await commitPath(this.#repository, path, `save: ${ref.slug}`);
-                await pushBranch(this.#repository, this.#runtime.remote, verifiedIdentity.login);
+                const { ref, path, directorySnapshot } = await this.#authorizedPrototype(verifiedIdentity, input);
+                await assertPrototypeDirectory(this.#runtime, ref, directorySnapshot);
+                await commitPrototypePath(this.#repository, path, `save: ${ref.slug}`);
                 return { saved: true };
             });
         });
@@ -530,10 +1169,11 @@ export class LocalPrototypeLifecycle {
         }
         return resultFrom(async () => {
             const verifiedIdentity = await this.#verifiedIdentity(identity);
-            const { path } = await this.#ownedPrototype(verifiedIdentity, input);
             return withRepositoryOperation(this.#runtime.repositoryRealPath, async () => {
                 await this.#prepareMutationBranch(verifiedIdentity.login);
-                await discardPath(this.#repository, path);
+                const { ref, path, directorySnapshot } = await this.#authorizedPrototype(verifiedIdentity, input);
+                await assertPrototypeDirectory(this.#runtime, ref, directorySnapshot);
+                await discardPrototypePath(this.#repository, path);
                 return { discarded: true };
             });
         });