@gentbajko/slopify 1.5.1 → 2.0.0

package/dist/edge/docker-projects/engine.js

@@ -0,0 +1,384 @@
+import { lstat, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { containerSchema, digestSchema, } from "./state.js";
+import { contains } from "./tree.js";
+export function dockerEngine(runner, signal, env) {
+    const run = (args, localSignal = signal) => runner.exec("docker", args, localSignal);
+    async function command(args, localSignal = signal) {
+        const r = await run(args, localSignal);
+        if (r.code !== 0)
+            throw new Error(`Docker ${args[0] ?? "command"} failed; recovery material is retained.`);
+        return r.stdout.trim();
+    }
+    const mount = (type, source, target, readonly = false) => [
+        "--mount",
+        `type=${type},source=${source},target=${target}${readonly ? ",readonly" : ""}${type === "volume" ? ",volume-nocopy" : ""}`,
+    ];
+    const source = (volume, bind) => [
+        ...mount("volume", volume, "/source", true),
+        ...(bind === null ? [] : mount("bind", bind, "/source/projects", true)),
+    ];
+    const helper = async (image, args, operation, user = "0:0") => JSON.parse(await command([
+        "run",
+        "--rm",
+        "--network",
+        "none",
+        "--read-only",
+        "--user",
+        operation === "probe" ? user : "0:0",
+        ...(args.some((a) => a.includes("target=/data,")) ? [] : ["--tmpfs", "/data"]),
+        ...args,
+        "--entrypoint",
+        "node",
+        image,
+        "/opt/slopify/packages/app/dist/edge/docker-projects/volume.js",
+        operation,
+        user,
+    ]));
+    async function inspect(name) {
+        const present = await run([
+            "container",
+            "ls",
+            "-a",
+            "--filter",
+            `name=^/${name}$`,
+            "--format",
+            "{{.ID}}",
+        ]);
+        if (present.code !== 0)
+            throw new Error("Docker container inventory failed.");
+        if (!present.stdout.trim() && !/^[a-f0-9]{12,64}$/.test(name))
+            return null;
+        const result = await run(["inspect", name]);
+        if (result.code !== 0) {
+            if (!present.stdout.trim())
+                return null;
+            throw new Error("Docker inspect failed.");
+        }
+        const schema = z.array(z.object({
+            Id: z.string(),
+            Name: z.string(),
+            Image: z.string(),
+            Config: z.object({ User: z.string(), Labels: z.record(z.string(), z.string()).nullable() }),
+            State: z.object({ Running: z.boolean() }),
+            HostConfig: z.object({
+                RestartPolicy: z.object({ Name: z.string(), MaximumRetryCount: z.number() }),
+            }),
+            Mounts: z.array(z.object({
+                Type: z.string(),
+                Name: z.string().optional(),
+                Source: z.string(),
+                Destination: z.string(),
+                RW: z.boolean(),
+            })),
+            NetworkSettings: z.object({
+                Ports: z.record(z.string(), z.array(z.object({ HostIp: z.string(), HostPort: z.string() })).nullable()),
+            }),
+        }));
+        const raw = schema.parse(JSON.parse(result.stdout))[0];
+        if (!raw)
+            throw new Error("Missing inspected container.");
+        const port = raw.NetworkSettings.Ports["6969/tcp"]?.[0];
+        return containerSchema.parse({
+            id: raw.Id,
+            name: raw.Name.replace(/^\//, ""),
+            image: raw.Image,
+            user: raw.Config.User,
+            running: raw.State.Running,
+            restart: raw.HostConfig.RestartPolicy,
+            signature: raw.Config.Labels?.["io.slopify.launcher"] ?? null,
+            installation: raw.Config.Labels?.["io.slopify.installation"] ?? null,
+            mounts: raw.Mounts.map((m) => ({
+                type: m.Type,
+                name: m.Name ?? "",
+                source: m.Source,
+                destination: m.Destination,
+                rw: m.RW,
+            })),
+            port: port ? `${port.HostIp}:${port.HostPort}` : null,
+        });
+    }
+    async function claims(volume, permitted, spared = () => false) {
+        const ids = (await command(["container", "ls", "-a", "-q"])).split(/\s+/).filter(Boolean);
+        for (const id of ids) {
+            const c = await inspect(id);
+            if (!c)
+                throw new Error("Cannot verify volume claims; an inventoried container is missing.");
+            if (!permitted.includes(c.id) &&
+                !spared(c) &&
+                c.mounts.some((m) => m.type === "volume" && m.name === volume))
+                throw new Error(`Another container claims installation volume ${volume}: ${c.name}.`);
+        }
+    }
+    async function writers(volume, paths, permitted) {
+        const ids = (await command(["container", "ls", "-q"])).split(/\s+/).filter(Boolean);
+        for (const id of ids) {
+            const c = await inspect(id);
+            if (!c || permitted.includes(c.id))
+                continue;
+            if (c.mounts.some((m) => m.rw &&
+                (m.name === volume ||
+                    (m.type === "bind" &&
+                        paths.some((p) => contains(p, m.source) || contains(m.source, p))))))
+                throw new Error(`Another running container writes installation storage: ${c.name}. Stop it before retrying.`);
+        }
+    }
+    async function recoveryLabel(j) {
+        const label = await command([
+            "volume",
+            "inspect",
+            "--format",
+            '{{index .Labels "io.slopify.transaction"}}',
+            j.backup,
+        ]);
+        if (label !== j.id)
+            throw new Error("Recovery volume identity conflict.");
+    }
+    return {
+        command,
+        inspect,
+        claims,
+        writers,
+        context: async (uid, gid) => {
+            let endpoint = env.DOCKER_HOST;
+            if (env.DOCKER_CONTEXT || !endpoint) {
+                const raw = JSON.parse(await command([
+                    "context",
+                    "inspect",
+                    ...(env.DOCKER_CONTEXT ? [env.DOCKER_CONTEXT] : []),
+                ]));
+                endpoint = z
+                    .array(z.object({ Endpoints: z.object({ docker: z.object({ Host: z.string() }) }) }))
+                    .parse(raw)[0]?.Endpoints.docker.Host;
+            }
+            if (!endpoint?.startsWith("unix://"))
+                throw new Error("Managed folders require a local Linux Docker unix socket; remote daemons are unsupported.");
+            const info = z
+                .object({
+                ID: z.string(),
+                OSType: z.literal("linux"),
+                OperatingSystem: z.string(),
+                SecurityOptions: z.array(z.string()),
+            })
+                .parse(JSON.parse(await command(["info", "--format", "{{json .}}"])));
+            if (/docker desktop/i.test(info.OperatingSystem))
+                throw new Error("Docker Desktop is unsupported by managed project folders. Use a native Linux Docker daemon or native Slopify.");
+            const rootless = info.SecurityOptions.includes("name=rootless");
+            if (!rootless && info.SecurityOptions.some((s) => s.startsWith("name=userns")))
+                throw new Error("Docker userns-remap is unsupported by managed project folders. Use a supported rootless daemon or native Slopify; do not disable isolation.");
+            return { daemon: info.ID, user: rootless ? "0:0" : `${uid}:${gid}` };
+        },
+        image: async (ref) => {
+            if (ref === "ghcr.io/gentbajko/slopify:latest") {
+                await command(["pull", ref]);
+                return command(["image", "inspect", "--format", "{{.Id}}", ref]);
+            }
+            const found = await run(["image", "inspect", "--format", "{{.Id}}", ref]);
+            if (found.code !== 0)
+                await command(["pull", ref]);
+            return command(["image", "inspect", "--format", "{{.Id}}", ref]);
+        },
+        version: async (image) => z
+            .string()
+            .regex(/^\d+\.\d+\.\d+$/)
+            .parse(await command([
+            "run",
+            "--rm",
+            "--network",
+            "none",
+            "--read-only",
+            "--tmpfs",
+            "/data",
+            "--entrypoint",
+            "node",
+            image,
+            "-p",
+            "require('/opt/slopify/packages/app/package.json').version",
+        ])),
+        ensureVolume: async (volume) => {
+            await command(["volume", "create", volume]);
+        },
+        volume: async (name) => {
+            const names = (await command(["volume", "ls", "--format", "{{.Name}}"])).split(/\s+/);
+            if (!names.includes(name))
+                return null;
+            const v = z
+                .object({
+                Name: z.string(),
+                CreatedAt: z.string(),
+                Driver: z.literal("local"),
+                Scope: z.literal("local"),
+                Options: z.record(z.string(), z.string()).nullable(),
+            })
+                .parse(JSON.parse(await command(["volume", "inspect", "--format", "{{json .}}", name])));
+            if (v.Name !== name || (v.Options && Object.keys(v.Options).length > 0))
+                throw new Error("Managed projects require an ordinary local named volume; remote/custom volume drivers are unsupported.");
+            return JSON.stringify([v.Name, v.CreatedAt, v.Driver]);
+        },
+        probe: async (c, image, user, destination) => {
+            const probe = await mkdtemp(join(dirname(destination), ".slopify-probe-"));
+            try {
+                await writeFile(join(probe, "host"), "host", { mode: 0o600 });
+                await helper(image, mount("bind", probe, "/probe"), "probe", user);
+                const s = await lstat(join(probe, "container"));
+                if (!s.isFile() ||
+                    s.uid !== c.uid ||
+                    s.gid !== c.gid ||
+                    (s.mode & 0o077) !== 0 ||
+                    (await readFile(join(probe, "container"), "utf8")) !== "slopify ownership probe")
+                    throw new Error("Docker cannot create private files as this host user; ownership mapping is unsupported.");
+                await writeFile(join(probe, "container"), "host can write", { flag: "a" });
+            }
+            finally {
+                await rm(probe, { recursive: true, force: true });
+            }
+        },
+        projects: async (image, volume, bind) => {
+            const value = z
+                .discriminatedUnion("exists", [
+                z.object({ exists: z.literal(false) }),
+                z.object({ exists: z.literal(true), digest: digestSchema }),
+            ])
+                .parse(await helper(image, source(volume, bind), "projects"));
+            return value.exists ? value.digest : null;
+        },
+        copy: async (image, volume, bind, destination, id) => {
+            const name = `slopify-reader-${id}`;
+            const reader = await command([
+                "create",
+                "--name",
+                name,
+                "--label",
+                `io.slopify.reader=${id}`,
+                "--network",
+                "none",
+                "--read-only",
+                "--tmpfs",
+                "/data",
+                ...source(volume, bind),
+                "--entrypoint",
+                "true",
+                image,
+            ]);
+            try {
+                await command(["cp", `${reader}:/source/projects/.`, destination]);
+            }
+            finally {
+                await command(["rm", reader], AbortSignal.timeout(10_000));
+            }
+        },
+        snapshot: async (j) => {
+            const all = (await command(["volume", "ls", "--format", "{{.Name}}"])).split(/\s+/);
+            if (all.includes(j.backup))
+                throw new Error("Recovery volume already exists; reconcile the journal before retrying.");
+            await command(["volume", "create", "--label", `io.slopify.transaction=${j.id}`, j.backup]);
+            return digestSchema.parse(await helper(j.image, [...source(j.volume, null), ...mount("volume", j.backup, "/backup")], "snapshot"));
+        },
+        restore: async (j) => {
+            if (!j.backupDigest)
+                throw new Error("No verified private snapshot; automatic restore is unsafe.");
+            await recoveryLabel(j);
+            const found = digestSchema.parse(await helper(j.image, source(j.backup, null), "private"));
+            if (found.hash !== j.backupDigest.hash)
+                throw new Error("Recovery snapshot changed; automatic restore refused.");
+            const result = digestSchema.parse(await helper(j.image, [...source(j.backup, null), ...mount("volume", j.volume, "/data")], "restore"));
+            if (result.hash !== j.backupDigest.hash)
+                throw new Error("Restored private data differs from its snapshot.");
+        },
+        own: async (j) => {
+            await helper(j.image, mount("volume", j.volume, "/data"), "own", j.user);
+        },
+        stop: async (c) => {
+            await command(["update", "--restart=no", c.id]);
+            await command(["stop", c.id]);
+        },
+        restart: async (c) => {
+            const current = await inspect(c.id);
+            if (!current)
+                throw new Error("Previous container is missing; use the retained recovery volume.");
+            if (current.name !== c.name)
+                await command(["rename", c.id, c.name]);
+            const restart = c.restart.Name === "on-failure" && c.restart.MaximumRetryCount > 0
+                ? `on-failure:${c.restart.MaximumRetryCount}`
+                : c.restart.Name;
+            await command(["update", `--restart=${restart}`, c.id]);
+            if (c.running)
+                await command(["start", c.id]);
+        },
+        start: async (c, j, transactionDirectory) => {
+            const port = c.port === 0 ? "" : String(c.port);
+            return command([
+                "run",
+                "-d",
+                "--name",
+                c.name,
+                "--restart",
+                "no",
+                "--user",
+                j.user,
+                "--label",
+                `io.slopify.launcher=${j.signature}`,
+                "--label",
+                `io.slopify.installation=${j.installation}`,
+                "--label",
+                `io.slopify.transaction=${j.id}`,
+                "-p",
+                `127.0.0.1:${port}:6969`,
+                ...mount("volume", c.volume, "/data"),
+                ...mount("bind", j.destination, "/data/projects"),
+                ...mount("bind", transactionDirectory, "/opt/slopify-install", true),
+                ...(c.bridge
+                    ? [
+                        ...mount("bind", c.bridge, "/opt/slopify-host", true),
+                        "--env",
+                        "SLOPIFY_HOST_CLI_DIR=/opt/slopify-host",
+                    ]
+                    : []),
+                "--env",
+                `SLOPIFY_DOCKER_PROJECTS_DIR=${j.destination}`,
+                "--env",
+                "SLOPIFY_DOCKER_INSTALL_STATE=/opt/slopify-install/activation.json",
+                "--env",
+                `SLOPIFY_UPDATE_TOKEN=${j.token}`,
+                "--env",
+                "SLOPIFY_UPDATE_PENDING=1",
+                j.image,
+            ]);
+        },
+        health: async (id, token, expectedVersion) => {
+            const deadline = Date.now() + 120_000;
+            while (Date.now() < deadline) {
+                signal.throwIfAborted();
+                const remaining = deadline - Date.now();
+                const probe = AbortSignal.any([
+                    signal,
+                    AbortSignal.timeout(Math.max(1, Math.min(2000, remaining))),
+                ]);
+                try {
+                    const result = await run([
+                        "exec",
+                        id,
+                        "node",
+                        "-e",
+                        "const [token,expected]=process.argv.slice(1); Promise.all([fetch('http://127.0.0.1:6969/api/health'),fetch('http://127.0.0.1:6969/api/update/ready',{headers:{'X-Slopify-Update-Token':token}})]).then(async rs=>{for(const r of rs){const b=await r.json();if(!r.ok||b.status!=='ok'||b.version!==expected)process.exit(1)}}).catch(()=>process.exit(1))",
+                        token,
+                        expectedVersion,
+                    ], probe);
+                    if (result.code === 0) {
+                        const running = await run(["inspect", "--format", "{{.State.Running}}", id], probe);
+                        if (running.code === 0 && running.stdout.trim() === "true")
+                            return;
+                    }
+                }
+                catch (error) {
+                    if (signal.aborted || !probe.aborted)
+                        throw error;
+                }
+                await delay(Math.min(250, Math.max(0, deadline - Date.now())), undefined, { signal });
+            }
+            throw new Error("Replacement did not become healthy within 120 seconds.");
+        },
+    };
+}

package/dist/edge/docker-projects/install.js

@@ -0,0 +1,246 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { lstat, mkdir, readdir, rename } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readVersion } from "../../kernel/version.js";
+import { assertVolumeClaims } from "./claims.js";
+import { readCommittedJournal } from "./committed.js";
+import { assertSourceIdentity, recoverInstallation } from "./recover.js";
+import { journalSchema, privateDirectory, readState, receiptSchema, selectProjects, writeState, } from "./state.js";
+import { assertIdentity, assertWritableTree, identity, isMissing, privateTree, safePath, syncDirectory, treeDigest, } from "./tree.js";
+export async function installProjects(c, e, recovery) {
+    await privateDirectory(c.directory, c.uid);
+    const receiptPath = join(c.directory, "receipt.json");
+    const journalPath = join(c.directory, "journal.json");
+    let receipt = await readState(receiptPath, receiptSchema, c.uid);
+    let previousJournal = await readState(journalPath, journalSchema, c.uid);
+    const context = await e.context(c.uid, c.gid);
+    const currentVolume = await e.volume(c.volume);
+    if ((receipt && receipt.volumeIdentity !== currentVolume) ||
+        (previousJournal?.volumeIdentity && previousJournal.volumeIdentity !== currentVolume))
+        throw new Error("Remembered data volume is missing or was replaced; restore the original volume before retrying.");
+    if ((receipt && receipt.daemon !== context.daemon) ||
+        (previousJournal && previousJournal.daemon !== context.daemon))
+        throw new Error("Docker daemon differs from saved installation; select the original daemon.");
+    await assertVolumeClaims(c, e, context.daemon, currentVolume, await e.inspect(c.name));
+    if (previousJournal && previousJournal.phase !== "rolled-back")
+        previousJournal = await recoverInstallation(c, previousJournal, receipt, recovery());
+    if (previousJournal?.phase === "rolled-back")
+        await assertSourceIdentity(previousJournal);
+    receipt = await readState(receiptPath, receiptSchema, c.uid);
+    const old = await e.inspect(c.name);
+    if (!receipt &&
+        previousJournal?.sourceBind &&
+        (old?.id !== previousJournal.previous?.id ||
+            old?.mounts.find((m) => m.destination === "/data/projects")?.source !==
+                previousJournal.sourceBind))
+        throw new Error(`Original bound container is missing or changed. Restore the recorded original container using ${previousJournal.sourceBind}; the hidden volume projects are not authoritative.`);
+    for (const name of await readdir(c.root)) {
+        if (name === c.name || name === "setup.lock")
+            continue;
+        const s = await lstat(join(c.root, name));
+        if (!s.isDirectory() || s.isSymbolicLink())
+            continue;
+        const other = await readState(join(c.root, name, "receipt.json"), receiptSchema, c.uid);
+        if (other?.daemon === context.daemon && other.volume === c.volume)
+            throw new Error(`Named volume belongs to installation ${other.name}; select a separate volume.`);
+    }
+    let reuse = null;
+    if (previousJournal?.phase === "rolled-back" &&
+        previousJournal.sourceBind !== previousJournal.destination &&
+        previousJournal.publishedIdentity &&
+        previousJournal.sourceDigest &&
+        (c.projectsOverride === null || c.projectsOverride === previousJournal.destination)) {
+        await assertIdentity(previousJournal.destination, previousJournal.publishedIdentity);
+        if ((await treeDigest(previousJournal.destination)).hash !== previousJournal.sourceDigest.hash)
+            throw new Error(`Published retry folder changed; preserve it for inspection: ${previousJournal.destination}`);
+        reuse = previousJournal;
+    }
+    const base = await selectProjects(c, receipt, old, reuse);
+    const projects = reuse?.destination ?? base;
+    await safePath(projects, c.home, c.root, true);
+    const bind = receipt?.projects ??
+        old?.mounts.find((m) => m.destination === "/data/projects")?.source ??
+        null;
+    if (bind !== null)
+        await assertWritableTree(bind, c.uid);
+    const image = await e.image(c.image);
+    const expectedVersion = await e.version(image);
+    if (expectedVersion !== readVersion())
+        throw new Error("Docker image and installed launcher versions differ. Refresh the default release image or select the matching custom image before retrying; the existing container is unchanged.");
+    const signature = createHash("sha256")
+        .update(JSON.stringify([image, c.volume, c.port, c.bridge, projects, context.user]))
+        .digest("hex");
+    await e.writers(c.volume, [projects, ...(bind ? [bind] : [])], old ? [old.id] : []);
+    await e.probe(c, image, context.user, projects);
+    if (receipt &&
+        old &&
+        old.signature === signature &&
+        old.image === image &&
+        old.user === context.user &&
+        old.mounts.find((m) => m.destination === "/data/projects")?.source === projects &&
+        old.mounts.find((m) => m.destination === "/data")?.name === c.volume &&
+        old.mounts.find((m) => m.destination === "/data")?.rw === true &&
+        old.mounts.find((m) => m.destination === "/opt/slopify-install")?.source ===
+            join(c.directory, receipt.transaction) &&
+        old.mounts.find((m) => m.destination === "/opt/slopify-install")?.rw === false &&
+        old.restart.Name === "always" &&
+        old.port?.startsWith("127.0.0.1:") &&
+        (c.port === 0 || old.port === `127.0.0.1:${c.port}`) &&
+        (old.mounts.find((m) => m.destination === "/opt/slopify-host")?.source ?? null) === c.bridge) {
+        const j = await readCommittedJournal(c, receipt, old);
+        if (!old.running)
+            await e.command(["start", old.id]);
+        await e.health(old.id, j.token, expectedVersion);
+        return { url: `http://${old.port}`, projects, recovery: j.backup };
+    }
+    const id = randomUUID();
+    const directory = join(c.directory, id);
+    await privateDirectory(directory, c.uid);
+    const destinationBefore = await identity(projects).catch((error) => {
+        if (isMissing(error))
+            return null;
+        throw error;
+    });
+    let j = {
+        version: 1,
+        id,
+        installation: receipt?.installation ?? randomUUID(),
+        daemon: context.daemon,
+        name: c.name,
+        volume: c.volume,
+        volumeIdentity: currentVolume,
+        image,
+        user: context.user,
+        signature,
+        phase: "prepared",
+        previous: old,
+        previousReceipt: receipt,
+        sourceBind: bind,
+        sourceIdentity: bind === null ? null : (receipt?.directoryIdentity ?? (await identity(bind))),
+        destination: projects,
+        destinationBefore,
+        staging: join(dirname(projects), `.slopify-projects-${id}`),
+        stagingIdentity: null,
+        publishedIdentity: reuse?.publishedIdentity ?? null,
+        sourceDigest: reuse?.sourceDigest ?? null,
+        sourceAbsent: reuse?.sourceAbsent ?? false,
+        backup: `${c.volume}-recovery-${id}`,
+        backupDigest: null,
+        candidate: null,
+        token: randomBytes(32).toString("hex"),
+    };
+    async function save(change) {
+        j = journalSchema.parse({ ...j, ...change });
+        await writeState(join(directory, "journal.json"), j);
+        await writeState(journalPath, j);
+    }
+    await save({});
+    await writeState(join(directory, "activation.json"), {
+        version: 1,
+        token: j.token,
+        committed: false,
+    });
+    try {
+        await save({ phase: "stopping" });
+        if (old)
+            await e.stop(old);
+        await e.writers(c.volume, [projects, ...(bind ? [bind] : [])], []);
+        await assertSourceIdentity(j);
+        await save({ phase: "stopped" });
+        await e.ensureVolume(c.volume);
+        await save({ volumeIdentity: await e.volume(c.volume) });
+        const source = await e.projects(image, c.volume, bind);
+        if (reuse && (reuse.sourceAbsent ? source !== null : source?.hash !== reuse.sourceDigest?.hash))
+            throw new Error(`Stale migration baseline. Retain ${projects} and ${reuse.staging}; select a new empty --projects-dir for a fresh verified copy.`);
+        await save({
+            sourceDigest: source ?? reuse?.sourceDigest ?? null,
+            sourceAbsent: source === null,
+        });
+        const backupDigest = await e.snapshot(j);
+        await save({ phase: "snapshot", backupDigest });
+        if (projects !== bind && reuse === null) {
+            await mkdir(j.staging, { mode: 0o700 });
+            await save({ phase: "copying", stagingIdentity: await identity(j.staging) });
+            if (source !== null)
+                await e.copy(image, c.volume, bind, j.staging, j.id);
+            await privateTree(j.staging, c.uid, c.gid);
+            const copied = await treeDigest(j.staging);
+            const after = await e.projects(image, c.volume, bind);
+            if ((source === null && copied.files !== 0) ||
+                (source !== null && (copied.hash !== source.hash || after?.hash !== source.hash)))
+                throw new Error("Project copy verification failed; source and staging are retained.");
+            await save({ phase: "verified", sourceDigest: source ?? copied });
+            await safePath(projects, c.home, c.root, false);
+            if (j.destinationBefore) {
+                await assertIdentity(projects, j.destinationBefore);
+                if ((await readdir(projects)).length !== 0)
+                    throw new Error("Destination became populated before publication.");
+            }
+            else {
+                const exists = await lstat(projects).catch((error) => {
+                    if (isMissing(error))
+                        return null;
+                    throw error;
+                });
+                if (exists !== null)
+                    throw new Error("Destination appeared before publication.");
+            }
+            if (!j.stagingIdentity)
+                throw new Error("Missing staging identity.");
+            await assertIdentity(j.staging, j.stagingIdentity);
+            await rename(j.staging, projects);
+            await syncDirectory(dirname(projects));
+        }
+        await save({ phase: "published", publishedIdentity: await identity(projects) });
+        await assertSourceIdentity(j);
+        await e.writers(c.volume, [projects, ...(bind ? [bind] : [])], []);
+        await e.own(j);
+        if (old)
+            await e.command(["rename", old.id, `${c.name}-previous-${j.id}`]);
+        await save({ phase: "starting" });
+        const candidate = await e.start(c, j, directory);
+        await save({ candidate });
+        await e.health(candidate, j.token, expectedVersion);
+        await save({ phase: "healthy" });
+        if (!j.publishedIdentity || !j.volumeIdentity)
+            throw new Error("Missing published storage identity.");
+        const next = {
+            version: 1,
+            installation: j.installation,
+            daemon: j.daemon,
+            name: c.name,
+            volume: c.volume,
+            volumeIdentity: j.volumeIdentity,
+            projects,
+            directoryIdentity: j.publishedIdentity,
+            user: j.user,
+            image,
+            signature,
+            transaction: j.id,
+        };
+        await writeState(receiptPath, next);
+        await e.command(["update", "--restart=always", candidate]);
+        await writeState(join(directory, "activation.json"), {
+            version: 1,
+            token: j.token,
+            committed: true,
+        });
+        await save({ phase: "committed" });
+        const ready = await e.inspect(candidate);
+        if (!ready?.port)
+            throw new Error("Committed container has no localhost port; rerun the launcher.");
+        return { url: `http://${ready.port}`, projects, recovery: j.backup };
+    }
+    catch (cause) {
+        const current = await readState(receiptPath, receiptSchema, c.uid);
+        if (current?.transaction === j.id)
+            throw new Error(`Installation committed at ${projects}; rerun the launcher to finish activation. Recovery volume: ${j.backup}`, { cause });
+        try {
+            await recoverInstallation(c, j, current, recovery());
+        }
+        catch (failure) {
+            throw new Error(`Recovery incomplete. Leave container/data stopped; recovery volume ${j.backup}, journal ${journalPath}, project folder ${projects}. ${failure instanceof Error ? failure.message : "Recovery operation failed."}`, { cause });
+        }
+        throw new Error(`Previous installation restored${old?.running ? " and restarted" : " without starting it"}. Recovery: ${j.backup}; project copy: ${projects}. ${cause instanceof Error ? cause.message : "Installation failed."}`, { cause });
+    }
+}