@datumos/datum-cli 0.0.0-stage → 0.588.0

package/cli/selfUpdate.js

@@ -0,0 +1,779 @@
+/**
+ * Self-update of the `datum` CLI (#1512, docs/cli.md "Updates").
+ *
+ * The shape is the one Claude Code, bun and rustup use: a new version is
+ * installed NEXT TO the running one and a pointer is switched atomically, so
+ * the next start runs it — the running process is never overwritten in
+ * place (a root-owned global npm prefix answers EACCES, and Windows refuses
+ * to replace files a process holds open).
+ *
+ *   <data dir>/versions/<v>/      one extracted CLI bundle (package + node_modules)
+ *   <data dir>/current            the version the launcher runs (rename = atomic)
+ *   <data dir>/update-state.json  last check, the server's answer, the opt-out
+ *
+ * The package installed with `npm i -g @datumos/datum-cli` stays the launcher:
+ * before main() it runs `preflight()`, which hands the process over to the
+ * newest installed version (never an OLDER one — an `npm i -g` of a newer
+ * release wins over a stale pointer) and, at most every
+ * UPDATE_CHECK_INTERVAL_MS, starts a detached `datum update --background`
+ * that asks the SERVER — not the npm registry, which a machine may not
+ * reach — for the release it runs (`GET /api/cli/latest`). The
+ * server serves the bundle built from its own commit, so a CLI follows the
+ * platform it talks to. Below the server's `minVersion` the update runs in
+ * the foreground before the command: an old CLI must not fail a command the
+ * API already changed under it (#758).
+ *
+ * Modes (DATUM_AUTOUPDATE): `on` (default), `off`, `min-only` (update ONLY
+ * when below the server's minimum — the AgentCore runtime image, whose CLI
+ * is otherwise pinned and smoke-tested). DATUM_NO_AUTOUPDATE=1, CI=true and
+ * `datum update --auto off` turn it off. A CLI running from the repository
+ * (tsx, server/dist in the app image) is never updated — only the published
+ * package is.
+ *
+ * Every failure here is swallowed into state + at most one stderr line: an
+ * updater that breaks the command it wraps is worse than no updater.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { BundleSignatureError, ENV_REQUIRE_SIGNED_UPDATE, checkBundleSignature, signatureRequired, } from "./bundleSignature.js";
+import { isLoopbackHost } from "./secureOrigin.js";
+/** The public package (npmjs.org, #2613) — what a bundle is built and signed as. */
+export const CLI_PACKAGE_NAME = "@datumos/datum-cli";
+/**
+ * The name the same package carried in a private registry before it went
+ * public. Still published there as an alias, and still the launcher of every
+ * install made before the switch — those keep updating themselves from the
+ * server's bundle, which is why both names count wherever one is checked.
+ */
+export const LEGACY_CLI_PACKAGE_NAME = "@datum/datum-cli";
+export const CLI_PACKAGE_NAMES = [CLI_PACKAGE_NAME, LEGACY_CLI_PACKAGE_NAME];
+/** How often the background check may ask the server. */
+export const UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/**
+ * A newer release the last check already KNOWS of (a `datum update --check`,
+ * a background check that failed to install) is retried this often — not
+ * after the full check interval, which would leave a known update idle.
+ */
+export const UPDATE_RETRY_INTERVAL_MS = 15 * 60 * 1000;
+/**
+ * After an install of the SAME bundle (version + integrity) failed, the next
+ * automatic attempt waits this long — by the number of failures in a row,
+ * the last value repeating (#3325). A deterministic failure (a bundle this
+ * machine cannot extract) must not come back with every command; a newer
+ * release, a rebuilt bundle or an explicit `datum update` tries at once.
+ */
+export const UPDATE_FAILURE_BACKOFF_MS = [15 * 60 * 1000, 6 * 60 * 60 * 1000, 24 * 60 * 60 * 1000];
+/** A lock older than this belongs to a dead updater and is broken. */
+export const UPDATE_LOCK_STALE_MS = 10 * 60 * 1000;
+/** Installed versions kept besides the current one (rollback targets). */
+export const KEEP_PREVIOUS_VERSIONS = 2;
+/** The server route the check asks (routes/cliRelease.ts). */
+export const CLI_LATEST_PATH = "/api/cli/latest";
+export const ENV_AUTOUPDATE = "DATUM_AUTOUPDATE";
+export const ENV_NO_AUTOUPDATE = "DATUM_NO_AUTOUPDATE";
+/** Set on the process the launcher hands over to — it must not hand over again. */
+export const ENV_DELEGATED = "DATUM_CLI_DELEGATED";
+/** The npm-installed launcher's own version, told to the process it hands over to. */
+export const ENV_LAUNCHER_VERSION = "DATUM_CLI_LAUNCHER_VERSION";
+/** Overrides the data directory (tests, unusual homes). */
+export const ENV_DATA_DIR = "DATUM_DATA_DIR";
+export const AUTOUPDATE_ON = "on";
+export const AUTOUPDATE_OFF = "off";
+export const AUTOUPDATE_MIN_ONLY = "min-only";
+const MODES = [AUTOUPDATE_ON, AUTOUPDATE_OFF, AUTOUPDATE_MIN_ONLY];
+export function parseVersion(text) {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(String(text ?? "").trim());
+    if (!m)
+        return null;
+    return { core: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null };
+}
+/** Semver order, enough of it: numeric core, a prerelease sorts below its release. */
+export function compareVersions(a, b) {
+    const x = parseVersion(a);
+    const y = parseVersion(b);
+    if (!x || !y)
+        throw new Error(`not a version: ${x ? b : a}`);
+    for (let i = 0; i < 3; i++) {
+        const d = x.core[i] - y.core[i];
+        if (d !== 0)
+            return d;
+    }
+    if (x.pre === y.pre)
+        return 0;
+    if (x.pre === null)
+        return 1;
+    if (y.pre === null)
+        return -1;
+    return comparePrerelease(x.pre, y.pre);
+}
+/** SemVer §11: dot-separated identifiers, numeric ones numerically and below
+ * alphanumeric ones, a shorter equal prefix lower (`alpha` < `alpha.1`). */
+function comparePrerelease(a, b) {
+    const xs = a.split(".");
+    const ys = b.split(".");
+    for (let i = 0; i < Math.max(xs.length, ys.length); i++) {
+        const x = xs[i];
+        const y = ys[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xn = /^\d+$/.test(x);
+        const yn = /^\d+$/.test(y);
+        if (xn && yn) {
+            const d = Number(x) - Number(y);
+            if (d !== 0)
+                return d;
+        }
+        else if (xn !== yn) {
+            return xn ? -1 : 1;
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}
+function newest(versions) {
+    let best = null;
+    for (const v of versions) {
+        if (!v || !parseVersion(v))
+            continue;
+        if (best === null || compareVersions(v, best) > 0)
+            best = v;
+    }
+    return best;
+}
+// ─── where things live ───────────────────────────────────────────────────
+export function updatePaths(env = process.env, platform = process.platform) {
+    const override = env[ENV_DATA_DIR]?.trim();
+    let root;
+    if (override) {
+        root = override;
+    }
+    else if (platform === "win32") {
+        root = path.join(env.LOCALAPPDATA?.trim() || path.join(homedir(), "AppData", "Local"), "datum");
+    }
+    else {
+        root = path.join(env.XDG_DATA_HOME?.trim() || path.join(homedir(), ".local", "share"), "datum");
+    }
+    return {
+        root,
+        versionsDir: path.join(root, "versions"),
+        currentFile: path.join(root, "current"),
+        stateFile: path.join(root, "update-state.json"),
+        lockDir: path.join(root, "update.lock"),
+        claimDir: path.join(root, "background.claim"),
+    };
+}
+/** The entry point of an installed version (the bundle is the package root). */
+export function entryFor(paths, version) {
+    return path.join(paths.versionsDir, version, "cli", "datum.js");
+}
+/**
+ * Is `entryDir` (the directory of the running datum.js) the PUBLISHED
+ * package — or a repository build? Only the former updates itself: the app
+ * image's `datum` runs server/dist from the commit it was built from, and a
+ * developer's tsx run is whatever they checked out.
+ */
+export function isPackagedInstall(entryDir) {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(entryDir, "..", "package.json"), "utf8"));
+        return typeof pkg.name === "string" && CLI_PACKAGE_NAMES.includes(pkg.name);
+    }
+    catch {
+        return false;
+    }
+}
+function readPackageName(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"));
+        return typeof pkg.name === "string" ? pkg.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readCurrent(paths) {
+    try {
+        const v = readFileSync(paths.currentFile, "utf8").trim();
+        return parseVersion(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Installed versions whose entry file is there, newest first. */
+export function installedVersions(paths) {
+    let names;
+    try {
+        names = readdirSync(paths.versionsDir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((n) => parseVersion(n) && existsSync(entryFor(paths, n)))
+        .sort((a, b) => compareVersions(b, a));
+}
+export function readState(paths) {
+    try {
+        const parsed = JSON.parse(readFileSync(paths.stateFile, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Write-then-rename: a reader never sees half a file. */
+function writeAtomic(file, text) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, text);
+    renameSync(tmp, file);
+}
+export function writeState(paths, patch) {
+    const next = { ...readState(paths), ...patch };
+    writeAtomic(paths.stateFile, `${JSON.stringify(next, null, 2)}\n`);
+    return next;
+}
+/** The note an install left (UpdateState.notice), cleared as it is taken — shown once. */
+export function takeNotice(paths) {
+    const { notice } = readState(paths);
+    if (!notice)
+        return null;
+    try {
+        writeState(paths, { notice: undefined });
+    }
+    catch {
+        return null; // an unwritable home would repeat it forever — say nothing instead
+    }
+    return notice;
+}
+// ─── policy ──────────────────────────────────────────────────────────────
+const truthy = (v) => !!v && !/^(0|false|no|off)$/i.test(v.trim());
+export function autoUpdateMode(env, state) {
+    if (truthy(env[ENV_NO_AUTOUPDATE]))
+        return AUTOUPDATE_OFF;
+    const explicit = env[ENV_AUTOUPDATE]?.trim().toLowerCase();
+    if (explicit && MODES.includes(explicit))
+        return explicit;
+    if (state.autoUpdate === false)
+        return AUTOUPDATE_OFF;
+    // A CI job wants the CLI it pinned, not one that changes between steps.
+    if (truthy(env.CI))
+        return AUTOUPDATE_OFF;
+    return AUTOUPDATE_ON;
+}
+/**
+ * The version the launcher should hand over to: the pointer, when it names
+ * an installed version NEWER than the one running. Never an older one.
+ */
+export function pickDelegate(ownVersion, paths, env) {
+    if (env[ENV_DELEGATED])
+        return null;
+    const current = readCurrent(paths);
+    if (!current || !parseVersion(ownVersion))
+        return null;
+    if (compareVersions(current, ownVersion) <= 0)
+        return null;
+    const entry = entryFor(paths, current);
+    return existsSync(entry) ? entry : null;
+}
+/** The version this machine effectively runs: the newer of the package and the pointer. */
+export function effectiveVersion(ownVersion, paths) {
+    return newest([ownVersion, readCurrent(paths)]) ?? ownVersion;
+}
+const elapsed = (iso, now, ms) => {
+    const t = iso ? Date.parse(iso) : NaN;
+    return !Number.isFinite(t) || now - t >= ms;
+};
+export function checkIsDue(state, now) {
+    return elapsed(state.lastCheckAt, now, UPDATE_CHECK_INTERVAL_MS);
+}
+/** One line of an error that tar (or anything else) answered in several — for the state, `--check` and stderr. */
+export function oneLine(message) {
+    return message.trim().replace(/\s*\n\s*/g, "; ");
+}
+/** `2026-11-13T22:34:14Z (in 5 h 58 min)` — when a deferred attempt runs, said for a person. */
+export function describeWhen(at, now) {
+    const iso = new Date(at).toISOString().replace(/\.\d{3}Z$/, "Z");
+    const minutes = Math.max(0, Math.ceil((at - now) / 60_000));
+    const h = Math.floor(minutes / 60);
+    const m = minutes % 60;
+    return `${iso} (in ${h ? `${h} h ` : ""}${m} min)`;
+}
+export function failureBackoffMs(count) {
+    const steps = UPDATE_FAILURE_BACKOFF_MS;
+    return steps[Math.min(Math.max(count, 1), steps.length) - 1];
+}
+/**
+ * When may the automatic update try to install `latest` again? Null when
+ * nothing holds it back — no failure recorded, or the failure was another
+ * bundle (a newer release, a rebuilt one: other integrity).
+ */
+export function installDeferredUntil(state, latest, now) {
+    const failed = state.failedInstall;
+    if (!failed || !latest?.package)
+        return null;
+    if (failed.version !== latest.version || failed.integrity !== latest.package.integrity)
+        return null;
+    const at = Date.parse(failed.at);
+    if (!Number.isFinite(at))
+        return null;
+    const until = at + failureBackoffMs(failed.count);
+    return now < until ? until : null;
+}
+/** Record a failed install of `latest` — one more in a row when it is the same bundle. */
+function recordFailedInstall(paths, latest, message, now) {
+    if (!latest.package)
+        return;
+    const error = oneLine(message);
+    const prev = readState(paths).failedInstall;
+    const same = prev?.version === latest.version && prev.integrity === latest.package.integrity;
+    writeState(paths, {
+        lastError: error,
+        failedInstall: {
+            version: latest.version,
+            integrity: latest.package.integrity,
+            count: same ? prev.count + 1 : 1,
+            at: new Date(now).toISOString(),
+            error,
+        },
+    });
+}
+/**
+ * Should the launcher start a background update now? When a check is due —
+ * or when the last answer already names a newer installable release than
+ * the one running (retried every UPDATE_RETRY_INTERVAL_MS, not every command,
+ * and not before the backoff of a failed install of that bundle has passed).
+ */
+export function backgroundIsDue(state, running, now) {
+    if (!elapsed(state.lastAttemptAt, now, UPDATE_RETRY_INTERVAL_MS))
+        return false;
+    if (checkIsDue(state, now))
+        return true;
+    const known = state.latest;
+    if (installDeferredUntil(state, known, now) !== null)
+        return false;
+    return !!known?.package && !!parseVersion(known.version) && compareVersions(known.version, running) > 0;
+}
+// ─── talking to the server ───────────────────────────────────────────────
+/**
+ * Code is only ever installed from a server reached over TLS: the integrity
+ * the CLI checks comes from the SAME server as the bundle, so over plain
+ * HTTP anybody on the path could hand over both. The one exception is a
+ * loopback host — the local dev stack, where the path is this machine.
+ */
+export function isTrustedUpdateSource(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol === "https:")
+        return true;
+    return url.protocol === "http:" && isLoopbackHost(url.hostname);
+}
+export class UntrustedUpdateSourceError extends Error {
+    constructor(baseUrl) {
+        super(`refusing to update from ${baseUrl} — the CLI installs code only from an https:// server (or a loopback http:// one)`);
+    }
+}
+function isCliLatest(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    if (!parseVersion(o.version) || !parseVersion(o.minVersion))
+        return false;
+    if (o.package === null)
+        return true;
+    const p = o.package;
+    return !!p && typeof p.url === "string" && typeof p.integrity === "string";
+}
+export async function fetchLatest(baseUrl, fetchImpl, timeoutMs) {
+    // No redirects, here or for the bundle: a redirect could land either
+    // request on another origin, and the same-origin rule would be moot.
+    const res = await fetchImpl(new URL(CLI_LATEST_PATH, baseUrl).toString(), {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { accept: "application/json" },
+        redirect: "error",
+    });
+    if (!res.ok)
+        throw new Error(`${CLI_LATEST_PATH} answered HTTP ${res.status}`);
+    const body = await res.json();
+    if (!isCliLatest(body))
+        throw new Error(`${CLI_LATEST_PATH} answered an unexpected shape`);
+    return body;
+}
+/** `sha512-<base64>` — the npm/SRI spelling the server sends. */
+export function sriSha512(bytes) {
+    return `sha512-${createHash("sha512").update(bytes).digest("base64")}`;
+}
+export const runProcess = (cmd, args, opts = {}) => new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+        ...(opts.cwd ? { cwd: opts.cwd } : {}),
+        env: { ...process.env, ...opts.env },
+        stdio: ["ignore", "pipe", "pipe"],
+        // Windows: tar.exe and the smoke `node --version` are console programs —
+        // without this each pops up its own console window (#3325).
+        windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d.toString()));
+    child.stderr.on("data", (d) => (stderr += d.toString()));
+    child.on("error", (err) => resolve({ code: 127, stdout, stderr: stderr + err.message }));
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+});
+export class UpdateLockedError extends Error {
+}
+const LOCK_OWNER_FILE = "owner";
+/**
+ * Take the install lock; returns the owner token that releases it. `mkdir`
+ * is atomic; a stale lock (its holder long gone) is taken over by an atomic
+ * RENAME away first — of two processes seeing the same stale lock only one
+ * rename succeeds, so a fresh lock is never removed by a second taker.
+ */
+function acquireLock(paths, now) {
+    mkdirSync(paths.root, { recursive: true });
+    const token = `${process.pid}-${now}-${Math.random().toString(36).slice(2)}`;
+    const take = () => {
+        try {
+            mkdirSync(paths.lockDir);
+        }
+        catch {
+            return false;
+        }
+        writeFileSync(path.join(paths.lockDir, LOCK_OWNER_FILE), token);
+        return true;
+    };
+    if (take())
+        return token;
+    try {
+        if (now - statSync(paths.lockDir).mtimeMs >= UPDATE_LOCK_STALE_MS) {
+            const stale = `${paths.lockDir}.stale-${token}`;
+            renameSync(paths.lockDir, stale);
+            rmSync(stale, { recursive: true, force: true });
+            if (take())
+                return token;
+        }
+    }
+    catch {
+        // lost the takeover race, or the lock vanished under us
+    }
+    throw new UpdateLockedError("another datum update is running");
+}
+/** Release ONLY a lock this process holds — never one somebody took over. */
+function releaseLock(paths, token) {
+    try {
+        if (readFileSync(path.join(paths.lockDir, LOCK_OWNER_FILE), "utf8") !== token)
+            return;
+        const released = `${paths.lockDir}.released-${token}`;
+        renameSync(paths.lockDir, released);
+        rmSync(released, { recursive: true, force: true });
+    }
+    catch {
+        // already gone
+    }
+}
+/**
+ * The tar that extracts the bundle. On Windows it is the system's own
+ * `%SystemRoot%\System32\tar.exe` (bsdtar, Windows 10+), named by its path:
+ * a GNU tar earlier on PATH (Git for Windows' Unix tools, MSYS) reads
+ * `C:\…\x.tgz` as a remote `host:file` and fails (#3325).
+ */
+export function tarCommand(platform = process.platform, env = process.env) {
+    if (platform !== "win32")
+        return "tar";
+    const systemTar = path.join(env.SystemRoot?.trim() || env.windir?.trim() || "C:\\Windows", "System32", "tar.exe");
+    return existsSync(systemTar) ? systemTar : "tar";
+}
+/** Keep the current version plus KEEP_PREVIOUS_VERSIONS older ones. */
+function prune(paths, current) {
+    const keep = new Set([current, ...installedVersions(paths).filter((v) => v !== current).slice(0, KEEP_PREVIOUS_VERSIONS)]);
+    let names = [];
+    try {
+        names = readdirSync(paths.versionsDir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!keep.has(name))
+            rmSync(path.join(paths.versionsDir, name), { recursive: true, force: true });
+    }
+}
+/**
+ * Download → verify sha512 → extract into a staging directory → smoke
+ * (`--version` must name the version) → rename into versions/<v> → switch
+ * the pointer. Any step failing leaves the previous version in charge.
+ */
+export async function installVersion(latest, baseUrl, paths, deps) {
+    if (!latest.package)
+        throw new Error("the server carries no CLI bundle to install");
+    if (!isTrustedUpdateSource(baseUrl))
+        throw new UntrustedUpdateSourceError(baseUrl);
+    // The bundle must come from the server that announced it, never a URL it names elsewhere.
+    const bundleUrl = new URL(latest.package.url, baseUrl);
+    if (bundleUrl.origin !== new URL(baseUrl).origin) {
+        throw new Error(`the server announced a CLI bundle on another origin (${bundleUrl.origin}) — not installed`);
+    }
+    const version = latest.version;
+    const lockToken = acquireLock(paths, deps.now());
+    const staging = path.join(paths.versionsDir, `.staging-${version}-${process.pid}`);
+    try {
+        const res = await deps.fetch(bundleUrl.toString(), {
+            signal: AbortSignal.timeout(120_000),
+            redirect: "error",
+        });
+        if (!res.ok)
+            throw new Error(`the CLI bundle download answered HTTP ${res.status}`);
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        const integrity = sriSha512(bytes);
+        if (integrity !== latest.package.integrity) {
+            throw new Error("the CLI bundle does not match the integrity the server announced — not installed");
+        }
+        // The integrity came from the same server as the bytes; the signature
+        // ties them to Datum's CI instead (#2612) — a hostile host cannot forge it.
+        const signature = checkBundleSignature({ version, integrity, signature: latest.package.signature }, { rootKeys: deps.rootKeys, packageNames: CLI_PACKAGE_NAMES });
+        if (!signature.signed) {
+            const required = deps.requireSigned ?? signatureRequired(process.env, isLoopbackHost(bundleUrl.hostname));
+            if (required)
+                throw new BundleSignatureError(`the CLI bundle is not signed by Datum (${signature.reason}) — not installed`);
+        }
+        rmSync(staging, { recursive: true, force: true });
+        mkdirSync(staging, { recursive: true });
+        const archive = path.join(staging, "..", `.staging-${version}-${process.pid}.tgz`);
+        writeFileSync(archive, bytes);
+        try {
+            // bsdtar/GNU tar: macOS, Linux and Windows 10+ all ship one.
+            const tar = await deps.run(tarCommand(), ["-xzf", archive, "-C", staging]);
+            if (tar.code !== 0)
+                throw new Error(`extracting the CLI bundle failed: ${tar.stderr.trim() || `tar exit ${tar.code}`}`);
+        }
+        finally {
+            rmSync(archive, { force: true });
+        }
+        const entry = path.join(staging, "cli", "datum.js");
+        if (!existsSync(entry))
+            throw new Error("the CLI bundle has no cli/datum.js");
+        if (signature.signed && readPackageName(staging) !== signature.name) {
+            throw new BundleSignatureError(`the CLI bundle is not the ${signature.name} package it is signed as — not installed`);
+        }
+        const smoke = await deps.run(deps.nodePath, [entry, "--version"], {
+            env: { [ENV_DELEGATED]: "1", [ENV_AUTOUPDATE]: AUTOUPDATE_OFF },
+        });
+        if (smoke.code !== 0 || !smoke.stdout.includes(`datum ${version} `)) {
+            throw new Error(`the new CLI does not start (\`--version\` → ${smoke.stdout.trim() || smoke.stderr.trim() || smoke.code})`);
+        }
+        const target = path.join(paths.versionsDir, version);
+        rmSync(target, { recursive: true, force: true });
+        renameSync(staging, target);
+        writeAtomic(paths.currentFile, `${version}\n`);
+        if (!signature.signed) {
+            // Recorded, not printed: most installs run in the detached background
+            // check, whose stderr goes nowhere — the next foreground run shows it.
+            // Only once it IS installed: a failed attempt must not claim it was (#3325).
+            writeState(paths, {
+                notice: `datum: ${version} was installed from an UNSIGNED bundle served by ${bundleUrl.origin} (${signature.reason}) — set ${ENV_REQUIRE_SIGNED_UPDATE}=1 to refuse those\n`,
+            });
+        }
+        prune(paths, version);
+        return version;
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+        releaseLock(paths, lockToken);
+    }
+}
+/**
+ * Ask the server; install when it runs a newer release than this machine.
+ * `onlyBelowMin`: install ONLY when below the server's minimum (min-only).
+ */
+export async function checkForUpdate(opts) {
+    const { baseUrl, ownVersion, paths, deps } = opts;
+    if (!isTrustedUpdateSource(baseUrl))
+        throw new UntrustedUpdateSourceError(baseUrl);
+    let latest;
+    try {
+        latest = await fetchLatest(baseUrl, deps.fetch, opts.timeoutMs ?? 10_000);
+    }
+    catch (err) {
+        writeState(paths, { lastCheckAt: new Date(deps.now()).toISOString(), lastError: err.message });
+        throw err;
+    }
+    writeState(paths, { lastCheckAt: new Date(deps.now()).toISOString(), latest, lastError: undefined });
+    const running = effectiveVersion(ownVersion, paths);
+    const wanted = opts.onlyBelowMin
+        ? compareVersions(running, latest.minVersion) < 0
+        : compareVersions(latest.version, running) > 0;
+    if (!wanted || !latest.package)
+        return { latest, installed: null, running };
+    // An installed copy of that version (a rollback, say) only needs the pointer.
+    if (existsSync(entryFor(paths, latest.version))) {
+        writeAtomic(paths.currentFile, `${latest.version}\n`);
+        return { latest, installed: latest.version, running: latest.version };
+    }
+    const deferredUntil = opts.ignoreBackoff ? null : installDeferredUntil(readState(paths), latest, deps.now());
+    if (deferredUntil !== null)
+        return { latest, installed: null, running, deferredUntil };
+    try {
+        const installed = await installVersion(latest, baseUrl, paths, deps);
+        writeState(paths, { failedInstall: undefined });
+        return { latest, installed, running: installed };
+    }
+    catch (err) {
+        // Another updater at work is not a failure of the bundle.
+        if (err instanceof UpdateLockedError)
+            writeState(paths, { lastError: err.message });
+        else
+            recordFailedInstall(paths, latest, err.message, deps.now());
+        throw err;
+    }
+}
+/** Point `current` at an installed version — `datum update --to <v>` (rollback). */
+export function switchTo(paths, version) {
+    if (!existsSync(entryFor(paths, version))) {
+        const have = installedVersions(paths);
+        throw new Error(`version ${version} is not installed here${have.length ? ` (installed: ${have.join(", ")})` : ""}`);
+    }
+    writeAtomic(paths.currentFile, `${version}\n`);
+}
+/** `datum update --to package`: drop the pointer, run the npm-installed package again. */
+export function clearCurrent(paths) {
+    rmSync(paths.currentFile, { force: true });
+}
+/** `datum update …` itself must not recurse into another check. */
+function isUpdateCommand(argv) {
+    return argv.find((a) => !a.startsWith("-")) === "update";
+}
+/**
+ * The ONE launcher allowed to start a background update in this retry
+ * window: `mkdir` is atomic, so of N concurrent commands exactly one gets
+ * the claim; a claim older than the window is taken over by renaming it
+ * away first (rename is atomic too — two launchers cannot both win it).
+ */
+export function claimBackground(paths, now) {
+    mkdirSync(paths.root, { recursive: true });
+    try {
+        mkdirSync(paths.claimDir);
+        return true;
+    }
+    catch {
+        // held — take it over only when its window has passed
+    }
+    try {
+        if (now - statSync(paths.claimDir).mtimeMs < UPDATE_RETRY_INTERVAL_MS)
+            return false;
+        const stale = `${paths.claimDir}.stale-${process.pid}-${now}`;
+        renameSync(paths.claimDir, stale);
+        rmSync(stale, { recursive: true, force: true });
+        mkdirSync(paths.claimDir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const spawnBackgroundCheck = (entryFile, env) => {
+    const child = spawn(process.execPath, [entryFile, "update", "--background"], {
+        detached: true,
+        stdio: "ignore",
+        // Windows: a detached child gets its own console window unless hidden (#3325).
+        windowsHide: true,
+        env: { ...process.env, ...env, [ENV_DELEGATED]: "1" },
+    });
+    child.on("error", () => { });
+    child.unref();
+};
+export async function preflight(ctx) {
+    const none = { delegate: null, backgroundStarted: false };
+    if (ctx.env[ENV_DELEGATED] || !isPackagedInstall(ctx.entryDir))
+        return none;
+    const notice = takeNotice(ctx.paths);
+    if (notice)
+        ctx.err.write(notice);
+    const state = readState(ctx.paths);
+    const mode = autoUpdateMode(ctx.env, state);
+    const updating = isUpdateCommand(ctx.argv);
+    // An untrusted source (plain http to a remote host) is skipped silently:
+    // `datum update` explains it, a normal command must not nag.
+    const source = ctx.baseUrl && isTrustedUpdateSource(ctx.baseUrl) ? ctx.baseUrl : null;
+    if (mode !== AUTOUPDATE_OFF && source && !updating) {
+        try {
+            let known = state.latest;
+            // Ask in the foreground, briefly: min-only once per interval (it has no
+            // background check, and a fresh container has no state at all); `on`
+            // only on the very first run — a freshly installed CLI below the
+            // minimum must not fail its first command waiting for a background answer.
+            const foregroundCheck = mode === AUTOUPDATE_MIN_ONLY ? checkIsDue(state, ctx.deps.now()) : !state.lastCheckAt;
+            if (foregroundCheck) {
+                try {
+                    known = await fetchLatest(source, ctx.deps.fetch, 3_000);
+                    writeState(ctx.paths, { lastCheckAt: new Date(ctx.deps.now()).toISOString(), latest: known, lastError: undefined });
+                }
+                catch (err) {
+                    writeState(ctx.paths, { lastCheckAt: new Date(ctx.deps.now()).toISOString(), lastError: err.message });
+                }
+            }
+            const running = effectiveVersion(ctx.ownVersion, ctx.paths);
+            const deferredUntil = installDeferredUntil(readState(ctx.paths), known, ctx.deps.now());
+            if (known && known.package && compareVersions(running, known.minVersion) < 0 && deferredUntil !== null) {
+                // Below the minimum, yet the same bundle failed moments ago: say so, do not retry it on every command.
+                ctx.err.write(`datum: this CLI (${running}) is older than the server's minimum (${known.minVersion}); installing ${known.version} failed — next automatic attempt after ${describeWhen(deferredUntil, ctx.deps.now())}, \`datum update\` retries now\n`);
+            }
+            else if (known && known.package && compareVersions(running, known.minVersion) < 0) {
+                ctx.err.write(`datum: this CLI (${running}) is older than the server's minimum (${known.minVersion}) — updating to ${known.version} first…\n`);
+                try {
+                    const out = await checkForUpdate({
+                        baseUrl: source,
+                        ownVersion: ctx.ownVersion,
+                        paths: ctx.paths,
+                        deps: ctx.deps,
+                        onlyBelowMin: mode === AUTOUPDATE_MIN_ONLY,
+                    });
+                    if (out.installed)
+                        ctx.err.write(`datum: updated to ${out.installed}\n${takeNotice(ctx.paths) ?? ""}`);
+                }
+                catch (err) {
+                    ctx.err.write(`datum: the update failed (${oneLine(err.message)}) — continuing with ${running}\n`);
+                }
+            }
+        }
+        catch {
+            // never let the updater break the command
+        }
+    }
+    const delegate = pickDelegate(ctx.ownVersion, ctx.paths, ctx.env);
+    let backgroundStarted = false;
+    const now = ctx.deps.now();
+    if (mode === AUTOUPDATE_ON &&
+        source &&
+        !updating &&
+        backgroundIsDue(readState(ctx.paths), effectiveVersion(ctx.ownVersion, ctx.paths), now)) {
+        try {
+            // A burst of commands starts one child, not ten: only the launcher that
+            // wins the claim spawns — and it re-reads the state under the claim.
+            if (!claimBackground(ctx.paths, now))
+                return { delegate, backgroundStarted };
+            if (!backgroundIsDue(readState(ctx.paths), effectiveVersion(ctx.ownVersion, ctx.paths), now)) {
+                return { delegate, backgroundStarted };
+            }
+            writeState(ctx.paths, { lastAttemptAt: new Date(now).toISOString() });
+            // The child resolves no flags: hand it the server this command resolved.
+            (ctx.spawnBackground ?? spawnBackgroundCheck)(delegate ?? ctx.entryFile, { ...ctx.env, DATUM_BASE_URL: source });
+            backgroundStarted = true;
+        }
+        catch {
+            // an unwritable home just means no background check
+        }
+    }
+    return { delegate, backgroundStarted };
+}
+//# sourceMappingURL=selfUpdate.js.map