spawnfile 0.1.17 → 0.1.18

package/dist/release/notify.d.ts

@@ -0,0 +1,58 @@
+import type { ReleaseFailureReason } from "./types.js";
+export declare const RELEASE_NOTIFICATION_VERSION: "spawnfile.release-notification.v1";
+export type NotifierConfig = {
+    kind: "command";
+    command: string;
+} | {
+    kind: "none";
+} | {
+    kind: "webhook";
+    urlEnv: string;
+};
+export interface ReleaseNotification {
+    at: string;
+    deployment: string;
+    host: string;
+    identity: string | null;
+    message: string;
+    reason: ReleaseFailureReason;
+    version: typeof RELEASE_NOTIFICATION_VERSION;
+}
+export interface NotifyResult {
+    channel: NotifierConfig["kind"];
+    delivered: boolean;
+    error?: string;
+}
+/**
+ * A notification says what broke, not where the box keeps things: anything
+ * path-shaped becomes `<path>` and the text is capped. The full detail stays
+ * in the release log on the host.
+ */
+export declare const shortReason: (message: string) => string;
+export declare const createNotification: (input: {
+    deployment: string;
+    identity: string | null;
+    message: string;
+    now?: Date;
+    reason: ReleaseFailureReason;
+}) => ReleaseNotification;
+/** Parses CLI declarations; at most one channel. */
+export declare const resolveNotifierConfig: (options: {
+    notifyCommand?: string;
+    notifyWebhookEnv?: string;
+}) => NotifierConfig;
+export declare const resolveWebhookUrl: (env: NodeJS.ProcessEnv, name: string) => URL;
+export interface NotifyDependencies {
+    attempts?: number;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    runCommand?: (command: string, input: string, env: NodeJS.ProcessEnv, timeoutMs: number) => Promise<number | null>;
+    sleep?: (ms: number) => Promise<void>;
+    timeoutMs?: number;
+}
+/**
+ * Never throws: a notifier that crashed the release reporting the failure
+ * would be worse than none. The caller records the result in the release log,
+ * so an undelivered notification still leaves its text on disk.
+ */
+export declare const sendNotification: (config: NotifierConfig, notification: ReleaseNotification, deps?: NotifyDependencies) => Promise<NotifyResult>;

package/dist/release/notify.js

@@ -0,0 +1,126 @@
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import path from "node:path";
+export const RELEASE_NOTIFICATION_VERSION = "spawnfile.release-notification.v1";
+const MAX_MESSAGE_CHARS = 500;
+const PATHLIKE = /(?:\/[A-Za-z0-9._@-]+){2,}\/?/gu;
+/**
+ * A notification says what broke, not where the box keeps things: anything
+ * path-shaped becomes `<path>` and the text is capped. The full detail stays
+ * in the release log on the host.
+ */
+export const shortReason = (message) => {
+    const scrubbed = message.replace(PATHLIKE, "<path>").replace(/\s+/gu, " ").trim();
+    return scrubbed.length > MAX_MESSAGE_CHARS ? `${scrubbed.slice(0, MAX_MESSAGE_CHARS - 1)}…` : scrubbed;
+};
+export const createNotification = (input) => ({
+    at: (input.now ?? new Date()).toISOString(),
+    deployment: input.deployment,
+    host: hostname(),
+    identity: input.identity,
+    message: shortReason(input.message),
+    reason: input.reason,
+    version: RELEASE_NOTIFICATION_VERSION
+});
+/** Parses CLI declarations; at most one channel. */
+export const resolveNotifierConfig = (options) => {
+    if (options.notifyCommand !== undefined && options.notifyWebhookEnv !== undefined) {
+        throw new Error("declare one notifier: --notify-command or --notify-webhook-env, not both");
+    }
+    if (options.notifyCommand !== undefined) {
+        if (!path.isAbsolute(options.notifyCommand))
+            throw new Error("--notify-command must be an absolute path to an executable");
+        return { command: options.notifyCommand, kind: "command" };
+    }
+    if (options.notifyWebhookEnv !== undefined) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(options.notifyWebhookEnv))
+            throw new Error("--notify-webhook-env must name an environment variable");
+        return { kind: "webhook", urlEnv: options.notifyWebhookEnv };
+    }
+    return { kind: "none" };
+};
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "[::1]"]);
+export const resolveWebhookUrl = (env, name) => {
+    const raw = env[name];
+    if (!raw)
+        throw new Error(`${name} is not set, so the webhook notifier has no URL`);
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`${name} is not a URL`);
+    }
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
+        throw new Error(`${name} must be an https URL (plain http only for loopback)`);
+    }
+    return url;
+};
+const runNotifierCommand = (command, input, env, timeoutMs) => new Promise((resolve, reject) => {
+    const child = spawn(command, [], { env, stdio: ["pipe", "ignore", "ignore"] });
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+    child.once("error", (error) => { clearTimeout(timer); reject(error); });
+    child.once("close", (code) => { clearTimeout(timer); resolve(code); });
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(input);
+});
+const notifyCommand = async (command, notification, deps) => {
+    const env = {
+        ...(deps.env ?? process.env),
+        SPAWNFILE_RELEASE_DEPLOYMENT: notification.deployment,
+        SPAWNFILE_RELEASE_IDENTITY: notification.identity ?? "",
+        SPAWNFILE_RELEASE_MESSAGE: notification.message,
+        SPAWNFILE_RELEASE_REASON: notification.reason
+    };
+    try {
+        const code = await (deps.runCommand ?? runNotifierCommand)(command, `${JSON.stringify(notification)}\n`, env, deps.timeoutMs ?? 60_000);
+        return code === 0 ? { channel: "command", delivered: true } : { channel: "command", delivered: false, error: `notifier exited ${code ?? "by signal"}` };
+    }
+    catch (error) {
+        return { channel: "command", delivered: false, error: `notifier could not run: ${error.message}` };
+    }
+};
+const notifyWebhook = async (urlEnv, notification, deps) => {
+    let url;
+    try {
+        url = resolveWebhookUrl(deps.env ?? process.env, urlEnv);
+    }
+    catch (error) {
+        return { channel: "webhook", delivered: false, error: error.message };
+    }
+    const attempts = deps.attempts ?? 3;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const errors = [];
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            const response = await (deps.fetchImpl ?? fetch)(url, {
+                body: JSON.stringify(notification),
+                headers: { "content-type": "application/json" },
+                method: "POST",
+                redirect: "error",
+                signal: AbortSignal.timeout(deps.timeoutMs ?? 15_000)
+            });
+            if (response.ok)
+                return { channel: "webhook", delivered: true };
+            errors.push(`HTTP ${response.status}`);
+        }
+        catch (error) {
+            errors.push(error.name === "TimeoutError" ? "timed out" : "request failed");
+        }
+        if (attempt < attempts)
+            await sleep(attempt * 2_000);
+    }
+    return { channel: "webhook", delivered: false, error: errors.join("; ") };
+};
+/**
+ * Never throws: a notifier that crashed the release reporting the failure
+ * would be worse than none. The caller records the result in the release log,
+ * so an undelivered notification still leaves its text on disk.
+ */
+export const sendNotification = async (config, notification, deps = {}) => {
+    if (config.kind === "command")
+        return notifyCommand(config.command, notification, deps);
+    if (config.kind === "webhook")
+        return notifyWebhook(config.urlEnv, notification, deps);
+    return { channel: "none", delivered: false, error: "no notifier declared" };
+};

package/dist/release/pending.d.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+export declare const RELEASE_PENDING_VERSION: "spawnfile.release-pending.v1";
+declare const pendingSchema: z.ZodObject<{
+    identity: z.ZodString;
+    notified_at: z.ZodNullable<z.ZodString>;
+    since: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.release-pending.v1">;
+}, z.core.$strict>;
+export type ReleasePending = z.infer<typeof pendingSchema>;
+export interface DeferralDecision {
+    ageMs: number;
+    /** True exactly once per pending identity after the threshold, or whenever tracking is broken. */
+    notify: boolean;
+    pending: ReleasePending;
+    /** Set when the record that holds "waiting since" could not be read or written. */
+    trackingBroken: string | null;
+}
+/**
+ * A drain that times out is "not yet", not "broken": on a timer that runs
+ * hourly, notifying on every busy hour teaches whoever receives it to ignore
+ * the channel. It must not hide forever either, so the instant this identity
+ * first deferred is kept beside the ledger and a person hears about it once
+ * it has waited longer than `notifyAfterMs`.
+ *
+ * The record is the only thing that turns "forever" into one notification,
+ * so a record that cannot be read or written is itself notified immediately,
+ * never silently restarted.
+ */
+export declare const recordDeferral: (file: string, identity: string, options: {
+    notifyAfterMs: number;
+    now?: Date;
+}) => Promise<DeferralDecision>;
+export declare const markDeferralNotified: (file: string, pending: ReleasePending, now?: Date) => Promise<void>;
+export declare const clearDeferral: (file: string) => Promise<void>;
+export {};

package/dist/release/pending.js

@@ -0,0 +1,60 @@
+import { readFile, rm } from "node:fs/promises";
+import { z } from "zod";
+import { writeJsonAtomic } from "./ledger.js";
+export const RELEASE_PENDING_VERSION = "spawnfile.release-pending.v1";
+const pendingSchema = z.object({
+    identity: z.string().min(1),
+    notified_at: z.string().min(1).nullable(),
+    since: z.string().min(1),
+    version: z.literal(RELEASE_PENDING_VERSION)
+}).strict();
+/**
+ * A drain that times out is "not yet", not "broken": on a timer that runs
+ * hourly, notifying on every busy hour teaches whoever receives it to ignore
+ * the channel. It must not hide forever either, so the instant this identity
+ * first deferred is kept beside the ledger and a person hears about it once
+ * it has waited longer than `notifyAfterMs`.
+ *
+ * The record is the only thing that turns "forever" into one notification,
+ * so a record that cannot be read or written is itself notified immediately,
+ * never silently restarted.
+ */
+export const recordDeferral = async (file, identity, options) => {
+    const now = options.now ?? new Date();
+    let previous = null;
+    let trackingBroken = null;
+    try {
+        previous = pendingSchema.parse(JSON.parse(await readFile(file, "utf8")));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            trackingBroken = `the pending-release record ${file} cannot be read`;
+        }
+    }
+    const pending = previous?.identity === identity
+        ? { ...previous }
+        : { identity, notified_at: null, since: now.toISOString(), version: RELEASE_PENDING_VERSION };
+    const since = Date.parse(pending.since);
+    const notifiedAt = pending.notified_at === null ? 0 : Date.parse(pending.notified_at);
+    if (!Number.isFinite(since) || !Number.isFinite(notifiedAt)) {
+        // A record that parses but holds no usable instant is as broken as one that does not parse.
+        trackingBroken = `the pending-release record ${file} holds an unreadable timestamp`;
+    }
+    const ageMs = Number.isFinite(since) ? Math.max(0, now.getTime() - since) : 0;
+    // `notified_at` is set only once a notification was actually delivered
+    // (markDeferralNotified), so a failed or crashed delivery is retried next run.
+    const escalate = ageMs >= options.notifyAfterMs && pending.notified_at === null;
+    try {
+        await writeJsonAtomic(file, pending);
+    }
+    catch {
+        trackingBroken = `the pending-release record ${file} could not be written`;
+    }
+    return { ageMs, notify: escalate || trackingBroken !== null, pending, trackingBroken };
+};
+export const markDeferralNotified = async (file, pending, now = new Date()) => {
+    await writeJsonAtomic(file, { ...pending, notified_at: now.toISOString() });
+};
+export const clearDeferral = async (file) => {
+    await rm(file, { force: true });
+};

package/dist/release/postDeploy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A caller-declared step that must succeed on the new container before the
+ * release counts as done (for example installing a credential the image
+ * cannot carry). Executed without a shell; it must be idempotent, because a
+ * failure leaves the release unrecorded and the next run deploys and runs it
+ * again.
+ */
+export interface PostDeployHook {
+    args: string[];
+    command: string;
+    timeoutMs: number;
+}
+export interface PostDeployContext {
+    containerName: string;
+    deployment: string;
+    identity: string;
+    imageId: string;
+    imageTag: string;
+}
+export interface PostDeployResult {
+    /** Null when the process ended by signal (including the timeout). */
+    exitCode: number | null;
+    output: string;
+    timedOut: boolean;
+}
+export declare const resolvePostDeployHook: (options: {
+    postDeployArg?: string[];
+    postDeployCommand?: string;
+    timeoutMs: number;
+}) => PostDeployHook | null;
+export declare const postDeployEnvironment: (context: PostDeployContext, env?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+export declare const runPostDeployCommand: (hook: PostDeployHook, context: PostDeployContext, signal?: AbortSignal) => Promise<PostDeployResult>;

package/dist/release/postDeploy.js

@@ -0,0 +1,62 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+const MAX_OUTPUT_CHARS = 4_000;
+const MAX_TIMEOUT_MS = 24 * 3_600_000;
+export const resolvePostDeployHook = (options) => {
+    if (options.postDeployCommand === undefined) {
+        if (options.postDeployArg?.length)
+            throw new Error("--post-deploy-arg needs --post-deploy-command");
+        return null;
+    }
+    if (!path.isAbsolute(options.postDeployCommand))
+        throw new Error("--post-deploy-command must be an absolute path to an executable");
+    if (options.timeoutMs > MAX_TIMEOUT_MS)
+        throw new Error("--post-deploy-timeout must be at most 24h");
+    return { args: options.postDeployArg ?? [], command: options.postDeployCommand, timeoutMs: options.timeoutMs };
+};
+export const postDeployEnvironment = (context, env = process.env) => ({
+    ...env,
+    SPAWNFILE_RELEASE_CONTAINER: context.containerName,
+    SPAWNFILE_RELEASE_DEPLOYMENT: context.deployment,
+    SPAWNFILE_RELEASE_IDENTITY: context.identity,
+    SPAWNFILE_RELEASE_IMAGE: context.imageTag,
+    SPAWNFILE_RELEASE_IMAGE_ID: context.imageId
+});
+/** Keeps the tail: the end of a failing script's output is where it says why. */
+const appendBounded = (current, chunk) => {
+    const next = current + chunk;
+    return next.length > MAX_OUTPUT_CHARS ? next.slice(next.length - MAX_OUTPUT_CHARS) : next;
+};
+/** Kills the hook's whole process group: a descendant holding its pipes must not outlive it. */
+const killGroup = (pid) => {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch { /* already gone */ }
+};
+export const runPostDeployCommand = (hook, context, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(new Error("aborted before the post-deploy command started"));
+        return;
+    }
+    let output = "";
+    let timedOut = false;
+    // Its own process group, so a timeout or abort reaches every descendant.
+    const child = spawn(hook.command, hook.args, { detached: true, env: postDeployEnvironment(context), stdio: ["ignore", "pipe", "pipe"] });
+    const kill = () => { killGroup(child.pid); };
+    const timer = setTimeout(() => { timedOut = true; kill(); }, hook.timeoutMs);
+    signal?.addEventListener("abort", kill, { once: true });
+    const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", kill);
+    };
+    const collect = (chunk) => { output = appendBounded(output, chunk.toString("utf8")); };
+    child.stdout.on("data", collect);
+    child.stderr.on("data", collect);
+    child.once("error", (error) => { done(); reject(error); });
+    // Leftover descendants would hold the pipes open and delay `close` forever.
+    child.once("exit", () => { killGroup(child.pid); });
+    child.once("close", (code) => { done(); resolve({ exitCode: code, output, timedOut }); });
+});

package/dist/release/releaseDefaults.d.ts

@@ -0,0 +1,9 @@
+import type { ReleaseDependencies } from "./releaseTypes.js";
+/**
+ * The production effects. The identity is the Docker build-context digest the
+ * build cache already keys on: a function of everything the image is built
+ * from (compiled workspaces, bundles, runtime installs, target architecture),
+ * so a change that does not reach the image does not release, and one that
+ * does always does.
+ */
+export declare const createDefaultReleaseDependencies: () => ReleaseDependencies;

package/dist/release/releaseDefaults.js

@@ -0,0 +1,115 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { promisify } from "node:util";
+import { buildCompiledProject, createDefaultImageTag, resolveDockerBuildArchitecture, resolveImageTagRoot } from "../compiler/buildProject.js";
+import { compileProject } from "../compiler/compileProject.js";
+import { createDockerBuildContextDigest } from "../compiler/dockerBuildContext.js";
+import { inspectDockerImage } from "../compiler/dockerBuildSkip.js";
+import { requireAuthProfile } from "../auth/index.js";
+import { readRunEnvFile } from "../compiler/runProjectAuth.js";
+import { acquireHomeDeploymentLock, resolveDockerDeploymentTarget, verifyDockerDeploymentTarget } from "../deployment/index.js";
+import { consumeImageUp, createConsumerDockerRunner, extractImageReport, resolveDockerBaseArgs } from "../distribution/index.js";
+import { helperControlCall, requestDrain, requestResume, waitForDrained } from "./drainControl.js";
+import { sendNotification } from "./notify.js";
+import { runPostDeployCommand } from "./postDeploy.js";
+import { inspectUnit, pruneReleaseImages, settleUnit } from "./releaseDocker.js";
+const execFile = promisify(execFileCallback);
+const dockerFor = (request) => createConsumerDockerRunner(request.dockerCommand, resolveDockerBaseArgs({
+    ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}),
+    ...(request.dockerHost ? { dockerHost: request.dockerHost } : {})
+}));
+/**
+ * The production effects. The identity is the Docker build-context digest the
+ * build cache already keys on: a function of everything the image is built
+ * from (compiled workspaces, bundles, runtime installs, target architecture),
+ * so a change that does not reach the image does not release, and one that
+ * does always does.
+ */
+export const createDefaultReleaseDependencies = () => ({
+    async build(request, compiled, imageTag) {
+        const result = await buildCompiledProject(request.inputPath, compiled.compileResult, {
+            contextDigest: compiled.identity,
+            dockerCommand: request.dockerCommand,
+            ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}),
+            imageTag
+        });
+        const image = await inspectDockerImage({ dockerCommand: request.dockerCommand, dockerContext: request.dockerContext ?? null, imageTag });
+        if (image === null)
+            throw new Error(`built image ${imageTag} cannot be inspected`);
+        return { buildMs: result.imageBuild?.buildMs ?? null, imageId: image.id, imageTag, skipped: result.imageBuild?.skipped ?? false };
+    },
+    async compile(request) {
+        const started = performance.now();
+        const containerArchitecture = await resolveDockerBuildArchitecture({
+            dockerCommand: request.dockerCommand,
+            ...(request.dockerContext ? { dockerContext: request.dockerContext } : {})
+        });
+        const compileResult = await compileProject(request.inputPath, {
+            bundleIdentity: request.bundleIdentity,
+            ...(containerArchitecture ? { containerArchitecture } : {}),
+            ...(request.outputDirectory ? { outputDirectory: request.outputDirectory } : {})
+        });
+        const identity = await createDockerBuildContextDigest(compileResult.outputDirectory);
+        return {
+            compileMs: performance.now() - started,
+            compileResult,
+            identity,
+            repository: request.imageRepository ?? createDefaultImageTag(resolveImageTagRoot(request.inputPath))
+        };
+    },
+    async deploy(request, imageTag) {
+        const started = performance.now();
+        const result = await consumeImageUp(imageTag, {
+            authProfile: request.authProfile ?? null,
+            authProfileName: request.authProfileName ?? null,
+            authValues: request.authProfile?.env ?? {},
+            deploymentLockHeld: true,
+            deploymentName: request.deployment,
+            dockerCommand: request.dockerCommand,
+            ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}),
+            ...(request.dockerHost ? { dockerHost: request.dockerHost } : {}),
+            envFileEnv: request.envFileEnv,
+            envFilePath: request.envFilePath ?? null,
+            now: request.now
+        });
+        return { containerName: result.containerName, deployMs: performance.now() - started };
+    },
+    inspectUnit: (request, containerRef) => inspectUnit(dockerFor(request), containerRef),
+    notify: (config, notification) => sendNotification(config, notification),
+    prune: (request, repository, keep) => pruneReleaseImages(dockerFor(request), repository, keep),
+    lockDeployment: (deployment) => acquireHomeDeploymentLock(deployment),
+    async prepare(request) {
+        return {
+            authProfile: request.authProfileName ? await requireAuthProfile(request.authProfileName) : null,
+            envFileEnv: await readRunEnvFile(request.envFilePath)
+        };
+    },
+    async runtimesOf(request, imageId) {
+        const inspection = await extractImageReport(imageId, {
+            dockerCommand: request.dockerCommand,
+            ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}),
+            ...(request.dockerHost ? { dockerHost: request.dockerHost } : {})
+        });
+        return inspection.report.runtime_instances.map((instance) => instance.runtime);
+    },
+    requestDrain: (target) => requestDrain(target, helperControlCall),
+    async pinTarget(request) {
+        // Not the deployment record's target: image-mode `up` runs Docker against
+        // the explicit context or the CLI's own default and only records a target,
+        // so the record can name a daemon the deployment does not live on.
+        if (request.dockerContext)
+            return resolveDockerDeploymentTarget({ context: request.dockerContext, dockerCommand: request.dockerCommand });
+        if (process.env.DOCKER_HOST?.trim())
+            return resolveDockerDeploymentTarget({ dockerCommand: request.dockerCommand });
+        // What a bare `docker` command would use: DOCKER_CONTEXT, else the selected context.
+        const { stdout } = await execFile(request.dockerCommand, ["context", "show"], { timeout: 10_000 });
+        return resolveDockerDeploymentTarget({ context: stdout.trim() || "default", dockerCommand: request.dockerCommand });
+    },
+    async verifyTarget(request, target) {
+        await verifyDockerDeploymentTarget(target, { dockerCommand: request.dockerCommand });
+    },
+    requestResume: (target) => requestResume(target, helperControlCall),
+    runPostDeploy: (request, hook, context) => runPostDeployCommand(hook, context, request.signal),
+    settle: (request, containerRef) => settleUnit(dockerFor(request), containerRef, request.settle),
+    waitForDrained: (target, options) => waitForDrained(target, { call: helperControlCall, ...options })
+});

package/dist/release/releaseDocker.d.ts

@@ -0,0 +1,38 @@
+import type { DockerCommandRunner } from "../distribution/dockerRunner.js";
+/** Release images are `<repository>:r-<first 12 hex of the identity>`. */
+export declare const RELEASE_TAG_PREFIX = "r-";
+export declare const releaseImageTag: (repository: string, identity: string) => string;
+export interface RunningUnit {
+    health: string;
+    id: string;
+    imageId: string;
+    restartCount: number;
+    running: boolean;
+}
+/** Null when the container does not exist; a container that exists but cannot be parsed is an error. */
+export declare const inspectUnit: (runDocker: DockerCommandRunner, containerRef: string) => Promise<RunningUnit | null>;
+export interface SettleOptions {
+    pollMs: number;
+    polls: number;
+    sleep?: (ms: number) => Promise<void>;
+    stablePolls: number;
+}
+/**
+ * Started is not working. A container that is "running (health: starting)"
+ * has proved nothing, and a crash-looping one reports `running` between
+ * restarts, so this waits until the same healthy observation, restart count
+ * included, holds for `stablePolls` consecutive polls.
+ */
+export declare const settleUnit: (runDocker: DockerCommandRunner, containerRef: string, options: SettleOptions) => Promise<RunningUnit>;
+export interface PruneResult {
+    kept: string[];
+    removed: string[];
+    skipped: string[];
+}
+/**
+ * Bounded disk: keeps the running image and one rollback, removes every other
+ * release tag of this repository. Only ever touches `<repository>:r-*` tags a
+ * release created, never an image any container (running or stopped, any
+ * deployment) still uses, never a volume, never build cache, never `prune`.
+ */
+export declare const pruneReleaseImages: (runDocker: DockerCommandRunner, repository: string, keepTags: readonly (string | null | undefined)[]) => Promise<PruneResult>;

package/dist/release/releaseDocker.js

@@ -0,0 +1,94 @@
+import { ReleaseError } from "./types.js";
+/** Release images are `<repository>:r-<first 12 hex of the identity>`. */
+export const RELEASE_TAG_PREFIX = "r-";
+export const releaseImageTag = (repository, identity) => `${repository}:${RELEASE_TAG_PREFIX}${identity.replace(/^sha256:/u, "").slice(0, 12)}`;
+// `.State.Health` is absent (not null) without a healthcheck, and Go templates
+// fail on a missing map key, so the whole State object is read and parsed here.
+const INSPECT_FORMAT = "{{json .Id}}\t{{json .Image}}\t{{json .State}}\t{{json .RestartCount}}";
+/** Null when the container does not exist; a container that exists but cannot be parsed is an error. */
+export const inspectUnit = async (runDocker, containerRef) => {
+    let raw;
+    try {
+        raw = (await runDocker(["container", "inspect", "--format", INSPECT_FORMAT, containerRef], { timeoutMs: 15_000 })).toString("utf8").trim();
+    }
+    catch (error) {
+        if (/no such (container|object)/iu.test(error.message))
+            return null;
+        throw new ReleaseError("blocked", `cannot inspect container ${containerRef}: ${error.message.slice(0, 200)}`);
+    }
+    try {
+        const [id, imageId, state, restarts] = raw.split("\t").map((field) => JSON.parse(field));
+        const { Health: health, Running: running } = (state ?? {});
+        const status = health === undefined || health === null ? "none" : health.Status;
+        if (typeof id !== "string" || typeof imageId !== "string" || typeof running !== "boolean" || typeof status !== "string" || typeof restarts !== "number")
+            throw new Error();
+        return { health: status, id, imageId, restartCount: restarts, running };
+    }
+    catch {
+        throw new ReleaseError("blocked", `container ${containerRef} returned an unreadable inspection`);
+    }
+};
+/**
+ * Started is not working. A container that is "running (health: starting)"
+ * has proved nothing, and a crash-looping one reports `running` between
+ * restarts, so this waits until the same healthy observation, restart count
+ * included, holds for `stablePolls` consecutive polls.
+ */
+export const settleUnit = async (runDocker, containerRef, options) => {
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let last = null;
+    let stable = 0;
+    let observed = null;
+    for (let poll = 0; poll < options.polls; poll += 1) {
+        let failure = null;
+        observed = await inspectUnit(runDocker, containerRef).catch((error) => { failure = error.message.slice(0, 160); return null; });
+        const healthy = observed !== null && observed.running && (observed.health === "healthy" || observed.health === "none");
+        const key = observed ? `${observed.id} ${observed.running} ${observed.health} ${observed.restartCount}` : failure ?? "missing";
+        stable = healthy && key === last ? stable + 1 : healthy ? 1 : 0;
+        last = key;
+        if (stable >= options.stablePolls)
+            return observed;
+        if (poll + 1 < options.polls)
+            await sleep(options.pollMs);
+    }
+    throw new ReleaseError("health-failed", `the deployed container never settled healthy; last observed: ${last ?? "nothing"}`);
+};
+const inUseImageIds = async (runDocker) => {
+    const ids = (await runDocker(["ps", "-a", "-q", "--no-trunc"])).toString("utf8").split("\n").map((line) => line.trim()).filter(Boolean);
+    if (ids.length === 0)
+        return new Set();
+    const images = (await runDocker(["container", "inspect", "--format", "{{.Image}}", ...ids])).toString("utf8");
+    return new Set(images.split("\n").map((line) => line.trim()).filter(Boolean));
+};
+/**
+ * Bounded disk: keeps the running image and one rollback, removes every other
+ * release tag of this repository. Only ever touches `<repository>:r-*` tags a
+ * release created, never an image any container (running or stopped, any
+ * deployment) still uses, never a volume, never build cache, never `prune`.
+ */
+export const pruneReleaseImages = async (runDocker, repository, keepTags) => {
+    const keep = new Set(keepTags.filter((tag) => typeof tag === "string"));
+    const listed = (await runDocker(["image", "ls", repository, "--no-trunc", "--format", "{{.Tag}}\t{{.ID}}"])).toString("utf8")
+        .split("\n").map((line) => line.trim().split("\t")).filter((row) => row.length === 2 && row[0].startsWith(RELEASE_TAG_PREFIX));
+    const used = await inUseImageIds(runDocker);
+    const result = { kept: [], removed: [], skipped: [] };
+    for (const [tag, id] of listed) {
+        const ref = `${repository}:${tag}`;
+        if (keep.has(ref)) {
+            result.kept.push(ref);
+            continue;
+        }
+        if (used.has(id)) {
+            result.skipped.push(ref);
+            continue;
+        }
+        try {
+            await runDocker(["image", "rm", ref]);
+            result.removed.push(ref);
+        }
+        catch {
+            result.skipped.push(ref);
+        }
+    }
+    return result;
+};