spawnfile 0.1.14 → 0.1.18

package/dist/release/drainPhase.js

@@ -0,0 +1,161 @@
+import { readFile, rm } from "node:fs/promises";
+import { resolveDockerBaseArgs } from "../distribution/index.js";
+import { writeJsonAtomic } from "./ledger.js";
+import { DAIMON_CONTROL_TOKEN_ENV } from "./releaseTypes.js";
+import { ReleaseError } from "./types.js";
+export const RELEASE_DRAIN_MARKER_VERSION = "spawnfile.release-drain.v1";
+/** Same precedence `up` applies: a process value overrides the env file. */
+export const resolveControlToken = (request) => {
+    const fromProcess = process.env[DAIMON_CONTROL_TOKEN_ENV];
+    if (typeof fromProcess === "string" && fromProcess.length > 0)
+        return fromProcess;
+    const fromFile = request.envFileEnv[DAIMON_CONTROL_TOKEN_ENV];
+    return typeof fromFile === "string" && fromFile.length > 0 ? fromFile : null;
+};
+export const controlTargetFor = (request, containerRef, imageRef) => {
+    const token = resolveControlToken(request);
+    if (token === null) {
+        throw new ReleaseError("blocked", `${DAIMON_CONTROL_TOKEN_ENV} is not set in the env file or environment; a drained release needs the running deployment's control token`);
+    }
+    return {
+        containerRef,
+        dockerArgs: resolveDockerBaseArgs({ ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}), ...(request.dockerHost ? { dockerHost: request.dockerHost } : {}) }),
+        dockerCommand: request.dockerCommand,
+        imageRef,
+        token
+    };
+};
+/**
+ * Written BEFORE the drain request and removed only once admission is open
+ * again, so a release killed in between (a unit timeout, a reboot) leaves
+ * evidence that the organization may still be refusing work. Every later run
+ * resumes it first, even when it has nothing to release.
+ */
+const writeMarker = async (request, paths, unit) => {
+    const target = request.target;
+    if (target === undefined)
+        throw new ReleaseError("blocked", "the release has no pinned Docker target to record with its drain");
+    const marker = { container: unit.id, image: unit.imageId, since: new Date().toISOString(), target, version: RELEASE_DRAIN_MARKER_VERSION };
+    await writeJsonAtomic(paths.drainMarker, marker);
+};
+/** The same request, addressed at exactly this Docker daemon. */
+export const requestForTarget = (request, target) => {
+    const { dockerContext: _context, dockerHost: _host, ...rest } = request;
+    if (target.kind === "host")
+        return { ...rest, dockerHost: target.value, target };
+    return { ...rest, dockerContext: target.kind === "context" ? target.name : target.context, target };
+};
+export const clearDrainMarker = async (paths) => {
+    await rm(paths.drainMarker, { force: true });
+};
+export const recoverInterruptedDrain = async (request, deps, paths) => {
+    let marker;
+    try {
+        marker = JSON.parse(await readFile(paths.drainMarker, "utf8"));
+        if (typeof marker.container !== "string" || typeof marker.target?.kind !== "string")
+            throw new Error("shape");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw new ReleaseError("resume-failed", `the drain marker ${paths.drainMarker} is unreadable; the organization may still be drained`);
+    }
+    // Recovery talks to the Docker daemon the drain went out through, whatever this run was invoked with,
+    // and refuses (keeping the marker) when that name now resolves to a different endpoint.
+    const target = requestForTarget(request, marker.target);
+    let unit;
+    try {
+        await deps.verifyTarget(target, marker.target);
+        unit = await deps.inspectUnit(target, marker.container);
+    }
+    catch (error) {
+        throw new ReleaseError("resume-failed", `an earlier release may have left the organization drained and its container cannot be inspected: ${error.message}`);
+    }
+    if (unit === null || !unit.running) {
+        // A drain lives in the runtime process: a container that is gone or stopped admits again when it next starts.
+        await clearDrainMarker(paths);
+        return true;
+    }
+    try {
+        await deps.requestResume(controlTargetFor(target, unit.id, unit.imageId));
+    }
+    catch (error) {
+        throw new ReleaseError("resume-failed", `an earlier release left the organization drained and resuming it failed: ${error.message}`);
+    }
+    await clearDrainMarker(paths);
+    request.log("release: resumed admission left drained by an interrupted release");
+    return true;
+};
+/**
+ * Admission pauses, queued wakes stay queued, running turns finish. On a
+ * timeout or interruption the release is abandoned and admission resumed:
+ * nothing in this module, or anything it calls, stops a turn.
+ */
+export const drainForRelease = async (request, deps, paths, unit) => {
+    if (!request.drain) {
+        request.log("release: --no-drain: deploying without draining; in-flight turns will be killed");
+        return { drainMs: 0, kind: "skipped" };
+    }
+    if (unit === null || !unit.running) {
+        request.log("release: no running container, so no turn can be in flight; nothing to drain");
+        return { drainMs: 0, kind: "skipped" };
+    }
+    const target = controlTargetFor(request, unit.id, unit.imageId);
+    const started = Date.now();
+    await writeMarker(request, paths, unit);
+    try {
+        await deps.requestDrain(target);
+        request.log(`release: admission paused; waiting up to ${Math.round(request.drainTimeoutMs / 1000)}s for running turns to finish`);
+        const waited = await deps.waitForDrained(target, {
+            pollMs: request.drainPollMs,
+            ...(request.signal ? { signal: request.signal } : {}),
+            timeoutMs: request.drainTimeoutMs
+        });
+        if (waited.drained && !request.signal?.aborted) {
+            request.log(`release: drained after ${Math.round(waited.waitedMs / 1000)}s`);
+            return { drainMs: Date.now() - started, kind: "drained" };
+        }
+        await resumeOrThrow(request, deps, paths, target);
+        if (waited.drained || waited.reason === "interrupted")
+            throw new ReleaseError("interrupted", "the release was interrupted while waiting for running turns; admission resumed, nothing deployed");
+        return { drainMs: Date.now() - started, kind: "timeout" };
+    }
+    catch (error) {
+        if (error instanceof ReleaseError && (error.reason === "interrupted" || error.reason === "resume-failed"))
+            throw error;
+        await resumeOrThrow(request, deps, paths, target);
+        throw error instanceof ReleaseError ? error : new ReleaseError("drain-failed", error.message);
+    }
+};
+/** Resumes a container this release drained, keeping the marker if that fails. */
+export const resumeDrained = async (request, deps, paths, unit) => resumeOrThrow(request, deps, paths, controlTargetFor(request, unit.id, unit.imageId));
+const resumeOrThrow = async (request, deps, paths, target) => {
+    try {
+        await deps.requestResume(target);
+    }
+    catch (error) {
+        throw new ReleaseError("resume-failed", `admission could not be resumed after abandoning the release; the organization is refusing new work: ${error.message}`);
+    }
+    await clearDrainMarker(paths);
+    request.log("release: admission resumed");
+};
+/**
+ * After a failed deploy, whatever container now holds the name is either the
+ * restored previous one (restarted, so it admits) or the original, still
+ * drained because the deploy failed before touching it. Resume either way.
+ */
+export const resumeAfterFailedDeploy = async (request, deps, paths, containerName) => {
+    let unit;
+    try {
+        unit = await deps.inspectUnit(request, containerName);
+    }
+    catch (error) {
+        // Not "absent": the marker stays, so the next run resumes it.
+        throw new ReleaseError("resume-failed", `the deploy failed and the container cannot be inspected to resume admission: ${error.message}`);
+    }
+    if (unit === null || !unit.running) {
+        await clearDrainMarker(paths);
+        return;
+    }
+    await resumeOrThrow(request, deps, paths, controlTargetFor(request, unit.id, unit.imageId));
+};

package/dist/release/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./drainControl.js";
+export * from "./drainPhase.js";
+export * from "./ledger.js";
+export * from "./notify.js";
+export * from "./pending.js";
+export * from "./postDeploy.js";
+export * from "./releaseDefaults.js";
+export * from "./releaseDocker.js";
+export * from "./releaseTypes.js";
+export * from "./runRelease.js";
+export * from "./types.js";

package/dist/release/index.js

@@ -0,0 +1,11 @@
+export * from "./drainControl.js";
+export * from "./drainPhase.js";
+export * from "./ledger.js";
+export * from "./notify.js";
+export * from "./pending.js";
+export * from "./postDeploy.js";
+export * from "./releaseDefaults.js";
+export * from "./releaseDocker.js";
+export * from "./releaseTypes.js";
+export * from "./runRelease.js";
+export * from "./types.js";

package/dist/release/ledger.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { type PidLockHooks } from "../deployment/index.js";
+export declare const RELEASE_LEDGER_VERSION: "spawnfile.release-ledger.v1";
+export declare const RELEASE_LOG_VERSION: "spawnfile.release-log.v1";
+declare const timings: z.ZodObject<{
+    build_ms: z.ZodNullable<z.ZodNumber>;
+    compile_ms: z.ZodNumber;
+    deploy_ms: z.ZodNullable<z.ZodNumber>;
+    drain_ms: z.ZodNullable<z.ZodNumber>;
+    total_ms: z.ZodNumber;
+}, z.core.$strict>;
+/** What is running, as the last successful release recorded it. */
+export declare const releaseLedgerSchema: z.ZodObject<{
+    compile_fingerprint: z.ZodString;
+    deployment: z.ZodString;
+    identity: z.ZodString;
+    image_id: z.ZodString;
+    image_tag: z.ZodString;
+    previous_image_tag: z.ZodNullable<z.ZodString>;
+    released_at: z.ZodString;
+    timings: z.ZodObject<{
+        build_ms: z.ZodNullable<z.ZodNumber>;
+        compile_ms: z.ZodNumber;
+        deploy_ms: z.ZodNullable<z.ZodNumber>;
+        drain_ms: z.ZodNullable<z.ZodNumber>;
+        total_ms: z.ZodNumber;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.release-ledger.v1">;
+}, z.core.$strict>;
+export type ReleaseLedger = z.infer<typeof releaseLedgerSchema>;
+export interface ReleaseLogEntry {
+    at: string;
+    deployment: string;
+    identity: string | null;
+    image_tag?: string;
+    message?: string;
+    notified?: {
+        channel: "command" | "webhook" | "none";
+        delivered: boolean;
+        error?: string;
+    };
+    outcome: "deferred" | "failed" | "notified" | "released";
+    reason?: string;
+    timings?: z.infer<typeof timings>;
+    version: typeof RELEASE_LOG_VERSION;
+}
+export interface ReleasePaths {
+    directory: string;
+    drainMarker: string;
+    ledger: string;
+    lock: string;
+    log: string;
+    pending: string;
+    /** Present from just before a post-deploy command runs until the ledger records its success. */
+    postDeploy: string;
+}
+export declare const resolveReleasePaths: (deployment: string, root?: string) => ReleasePaths;
+export declare const ensureReleaseDirectory: (paths: ReleasePaths) => Promise<void>;
+/**
+ * A missing ledger means nothing has been released into this deployment yet,
+ * which is a full release. A ledger that exists and cannot be read means this
+ * command does not know what is running, and it must not deploy: it could not
+ * write the record the next run depends on either. Unreadable is a refusal,
+ * never an assumed-stale.
+ */
+export declare const readReleaseLedger: (file: string) => Promise<ReleaseLedger | null>;
+/** Anything but "definitely absent" counts as present: an unknown marker never reads as done. */
+export declare const postDeployPending: (file: string) => Promise<boolean>;
+/** Same-directory temp file + rename, so a reader sees the old record or the new one. */
+export declare const writeJsonAtomic: (file: string, value: unknown) => Promise<void>;
+export declare const writeReleaseLedger: (file: string, ledger: ReleaseLedger) => Promise<void>;
+export declare const appendReleaseLog: (file: string, entry: Omit<ReleaseLogEntry, "version">) => Promise<void>;
+/** One release per deployment at a time; see `acquirePidLock` for the guarantees and the residual. */
+export declare const acquireReleaseLock: (paths: ReleasePaths, hooks?: PidLockHooks) => Promise<() => Promise<void>>;
+export {};

package/dist/release/ledger.js

@@ -0,0 +1,111 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { acquirePidLock, normalizeDeploymentName, PidLockBusyError } from "../deployment/index.js";
+import { ReleaseError } from "./types.js";
+export const RELEASE_LEDGER_VERSION = "spawnfile.release-ledger.v1";
+export const RELEASE_LOG_VERSION = "spawnfile.release-log.v1";
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+const timings = z.object({
+    build_ms: z.number().nonnegative().nullable(),
+    compile_ms: z.number().nonnegative(),
+    deploy_ms: z.number().nonnegative().nullable(),
+    drain_ms: z.number().nonnegative().nullable(),
+    total_ms: z.number().nonnegative()
+}).strict();
+/** What is running, as the last successful release recorded it. */
+export const releaseLedgerSchema = z.object({
+    compile_fingerprint: z.string().min(1),
+    deployment: z.string().min(1),
+    identity: digest,
+    image_id: z.string().min(1),
+    image_tag: z.string().min(1),
+    previous_image_tag: z.string().min(1).nullable(),
+    released_at: z.string().min(1),
+    timings,
+    version: z.literal(RELEASE_LEDGER_VERSION)
+}).strict();
+export const resolveReleasePaths = (deployment, root) => {
+    const directory = path.join(root ?? path.join(resolveSpawnfileHome(), "releases"), normalizeDeploymentName(deployment));
+    return {
+        directory,
+        drainMarker: path.join(directory, "drain.json"),
+        ledger: path.join(directory, "ledger.json"),
+        lock: path.join(directory, ".lock"),
+        log: path.join(directory, "log.jsonl"),
+        pending: path.join(directory, "pending.json"),
+        postDeploy: path.join(directory, "post-deploy.json")
+    };
+};
+export const ensureReleaseDirectory = async (paths) => {
+    await mkdir(paths.directory, { mode: 0o700, recursive: true });
+    await chmod(paths.directory, 0o700);
+};
+/**
+ * A missing ledger means nothing has been released into this deployment yet,
+ * which is a full release. A ledger that exists and cannot be read means this
+ * command does not know what is running, and it must not deploy: it could not
+ * write the record the next run depends on either. Unreadable is a refusal,
+ * never an assumed-stale.
+ */
+export const readReleaseLedger = async (file) => {
+    let source;
+    try {
+        source = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new ReleaseError("blocked", `cannot read the release ledger ${file}: ${error.message}`);
+    }
+    try {
+        return releaseLedgerSchema.parse(JSON.parse(source));
+    }
+    catch {
+        throw new ReleaseError("blocked", `the release ledger ${file} is not a ${RELEASE_LEDGER_VERSION} record; refusing to release against a ledger this command cannot read`);
+    }
+};
+/** Anything but "definitely absent" counts as present: an unknown marker never reads as done. */
+export const postDeployPending = async (file) => {
+    try {
+        await stat(file);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ENOENT";
+    }
+};
+/** Same-directory temp file + rename, so a reader sees the old record or the new one. */
+export const writeJsonAtomic = async (file, value) => {
+    const scratch = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(scratch, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        await rename(scratch, file);
+    }
+    catch (error) {
+        await rm(scratch, { force: true }).catch(() => undefined);
+        throw error;
+    }
+};
+export const writeReleaseLedger = async (file, ledger) => {
+    await writeJsonAtomic(file, releaseLedgerSchema.parse(ledger));
+};
+export const appendReleaseLog = async (file, entry) => {
+    await appendFile(file, `${JSON.stringify({ ...entry, version: RELEASE_LOG_VERSION })}\n`, { encoding: "utf8", mode: 0o600 });
+};
+/** One release per deployment at a time; see `acquirePidLock` for the guarantees and the residual. */
+export const acquireReleaseLock = async (paths, hooks = {}) => {
+    try {
+        return await acquirePidLock(paths.lock, hooks);
+    }
+    catch (error) {
+        if (error instanceof PidLockBusyError) {
+            throw new ReleaseError("blocked", error.ownerPid === null
+                ? "another release of this deployment took the lock first"
+                : `another release of this deployment is running (pid ${error.ownerPid})`);
+        }
+        throw error;
+    }
+};

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 });
+};