@catalyst-cloud/cli 0.16.30 → 0.16.32

package/dist/update-replica.js

@@ -0,0 +1,120 @@
+// update-replica.ts — a running local replica comes back on the approved CLI with its data
+// (CTC-6708). A detached writer keeps the code it started with, so after the CLI moves, a release
+// check stops the writer it can identify, waits until that process has exited and released the
+// writer lock, then starts a new writer through the person's own `catalyst` command (which runs the
+// selected version) on the same database file. Nothing here deletes, moves or reseeds the database:
+// the new writer resumes from the rows and cursor the old one left.
+//
+// It never starts a second writer: when the old one does not exit inside the deadline, or cannot be
+// identified, the restart stops there with a reason and the next check tries again. Before it stops
+// a writer it records that restart (replica-restart.json), and clears the record only once the new
+// writer reports its version, so a writer that exits after the deadline is started by the next check
+// instead of being taken for one its owner stopped. A replica that was stopped stays stopped.
+// Success is read back from the new writer's own record of the CLI version it runs.
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { configDirFor } from "./config.js";
+import { pendingRestart, pendingRestartPathFor, pidAlive, pidfilePath, replicaStatus, writerIsRunning } from "./replica.js";
+import { ACTIVE_RUNTIME_ENV } from "./update-cli.js";
+/** Whether a restart this CLI began for `dbPath` has not finished: the writer was stopped by it. */
+export function restartPending(home, dbPath) {
+    return pendingRestart(home, dbPath) !== null;
+}
+/** A writer's command line runs `replica start` (bin/launch.js keeps it in one process). */
+export function isReplicaWriter(pid) {
+    const ps = spawnSync("ps", ["-p", String(pid), "-o", "args="], { encoding: "utf8", timeout: 5_000 });
+    return ps.status === 0 && /\sreplica\s+start(\s|$)/.test(ps.stdout);
+}
+/**
+ * The command that starts the new writer. A scheduled run on Linux is a systemd oneshot service, and
+ * when it ends systemd stops every process left in its control group, a detached one included; a
+ * transient scope of the writer's own keeps it running after the release check ends.
+ */
+export function replicaStartCommand(argv, env, platform = process.platform) {
+    const node = [process.execPath, ...argv];
+    return platform === "linux" && env.INVOCATION_ID ? ["systemd-run", "--user", "--scope", "--quiet", "--", ...node] : node;
+}
+const startDetached = (argv, env) => {
+    const run = (command) => {
+        const [cmd, ...args] = command;
+        if (cmd === undefined)
+            return undefined;
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore", env });
+        child.on("error", () => { });
+        child.unref();
+        return child.pid;
+    };
+    // No systemd-run on PATH: start it directly, as `replica start --detach` does.
+    const pid = run(replicaStartCommand(argv, env)) ?? run([process.execPath, ...argv]);
+    if (typeof pid !== "number")
+        throw new Error("detached spawn returned no pid");
+    return pid;
+};
+/** Restart a running replica writer on the CLI the stable command now selects, expecting `target`. */
+export async function restartReplica(ctx, cfg, target, deps) {
+    const status = deps.status ?? (() => replicaStatus(ctx, cfg));
+    const alive = deps.alive ?? pidAlive;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const timeoutMs = deps.timeoutMs ?? 60_000;
+    const pollMs = deps.pollMs ?? 250;
+    const waitFor = async (done) => {
+        for (let waited = 0;; waited += pollMs) {
+            if (done())
+                return true;
+            if (waited >= timeoutMs)
+                return false;
+            await sleep(pollMs);
+        }
+    };
+    const before = status();
+    if (before.dbPath === null)
+        return { outcome: "stopped", detail: "stopped", version: null };
+    const dbPath = before.dbPath;
+    // Stopped: by its owner (it stays stopped), or by an earlier restart that did not finish (it starts).
+    if (!writerIsRunning(before) && !restartPending(ctx.home, dbPath))
+        return { outcome: "stopped", detail: "stopped", version: null };
+    if (writerIsRunning(before)) {
+        // The writer is the process holding the lock (or recorded in its own state, or the pidfile).
+        const pid = before.lockPid ?? before.writer?.pid ?? before.pidfilePid;
+        if (pid === null || !alive(pid) || !(deps.identify ?? isReplicaWriter)(pid))
+            return { outcome: "failed", detail: "writer_unidentified", version: before.writer?.version ?? null };
+        try {
+            mkdirSync(configDirFor(ctx.home), { recursive: true, mode: 0o700 });
+            writeFileSync(pendingRestartPathFor(ctx.home), `${JSON.stringify({ dbPath, target })}\n`, { mode: 0o600 });
+        }
+        catch {
+            // Without the record a late exit would read as an owner's stop: do not stop the writer.
+            return { outcome: "failed", detail: "start_failed", version: before.writer?.version ?? null };
+        }
+        try {
+            (deps.signal ?? ((p) => process.kill(p, "SIGTERM")))(pid);
+        }
+        catch {
+            rmSync(pendingRestartPathFor(ctx.home), { force: true });
+            return { outcome: "failed", detail: "writer_unidentified", version: before.writer?.version ?? null };
+        }
+        const exited = await waitFor(() => !alive(pid) && !writerIsRunning(status()));
+        if (!exited)
+            return { outcome: "failed", detail: "stop_timeout", version: before.writer?.version ?? null };
+    }
+    // Without a staged check's marker, so the person's own command selects the version to run.
+    const env = { ...ctx.env };
+    delete env[ACTIVE_RUNTIME_ENV];
+    let started;
+    try {
+        started = (deps.start ?? startDetached)([deps.launcher, "replica", "start", "--db", dbPath], env);
+        writeFileSync(pidfilePath(dbPath), `${started}\n`);
+    }
+    catch {
+        return { outcome: "failed", detail: "start_failed", version: null };
+    }
+    let now = status();
+    const confirmed = await waitFor(() => {
+        now = status();
+        return writerIsRunning(now) && now.writer?.version === target;
+    });
+    if (!confirmed)
+        return { outcome: "failed", detail: "restart_unconfirmed", version: now.writer?.version ?? null };
+    rmSync(pendingRestartPathFor(ctx.home), { force: true });
+    return { outcome: "updated", detail: "restarted", version: target };
+}

package/dist/update-sdk.js

@@ -0,0 +1,262 @@
+// update-sdk.ts — a project's Catalyst SDK against the approved release (CTC-6708). The SDK is a
+// dependency in the customer's own project, pinned by their lockfile, so a release check only
+// reads it: the declared range, the lockfile's resolution and the installed package are read
+// separately (a manifest range is never reported as the installed version), and the owner is given
+// the one command that moves the project to the approved versions. Reading writes nothing.
+//
+// The project's files change only through `applySdkUpdate`: when its owner runs
+// `catalyst update sdk --project <path>`, or has turned automatic SDK updates on for that project.
+// It runs the project's own package manager by argv (never a shell, never a full upgrade) with
+// exact versions in the dependency group each package already sits in, holds a per-project lock,
+// keeps the package files' bytes, puts them back if the install fails, and reads the result back
+// before calling it updated.
+//
+// Only train members the project already declares are named. Each uses its own approved version:
+// the SDK and its replica modules may sit on different patches of one train.
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDirFor } from "./config.js";
+import { compareVersions, exactVersion } from "./approved-release.js";
+import { isRecord } from "./runner-update.js";
+export const SDK_PACKAGES = {
+    "@catalyst-cloud/sdk": "sdk",
+    "@catalyst-cloud/sdk-replica-node": "sdk-replica-node",
+    "@catalyst-cloud/sdk-replica-browser": "sdk-replica-browser",
+};
+const LOCKFILES = {
+    npm: ["package-lock.json", "npm-shrinkwrap.json"],
+    pnpm: ["pnpm-lock.yaml"],
+    bun: ["bun.lock", "bun.lockb"],
+    yarn: ["yarn.lock"],
+};
+const GROUPS = ["dependencies", "devDependencies", "optionalDependencies"];
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The manager the project declares, else the single one whose lockfile is present. Two lockfiles
+ *  and no declaration is ambiguous: the report says so instead of picking the first one found. */
+export function detectPackageManager(dir, manifest) {
+    const present = Object.keys(LOCKFILES).filter((m) => LOCKFILES[m].some((f) => existsSync(join(dir, f))));
+    if (typeof manifest.packageManager === "string") {
+        const name = manifest.packageManager.split("@")[0];
+        if (name === "npm" || name === "pnpm" || name === "bun" || name === "yarn") {
+            if (present.length > 0 && !present.includes(name))
+                return { manager: null, reason: "lockfile_mismatch" };
+            return { manager: name, reason: null };
+        }
+        return { manager: null, reason: "package_manager_unsupported" };
+    }
+    if (present.length === 1)
+        return { manager: present[0] ?? null, reason: null };
+    if (present.length > 1)
+        return { manager: null, reason: "package_manager_ambiguous" };
+    return { manager: "npm", reason: null };
+}
+function npmLocked(dir, name) {
+    for (const file of LOCKFILES.npm) {
+        const lock = readJson(join(dir, file));
+        if (!isRecord(lock) || !isRecord(lock.packages))
+            continue;
+        const entry = lock.packages[`node_modules/${name}`];
+        if (isRecord(entry))
+            return exactVersion(entry.version);
+    }
+    return null;
+}
+function installedVersion(dir, name) {
+    const manifest = readJson(join(dir, "node_modules", ...name.split("/"), "package.json"));
+    return isRecord(manifest) ? exactVersion(manifest.version) : null;
+}
+const quote = (value) => (/^[A-Za-z0-9_./@:=-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`);
+/** What runs is what node_modules holds; else what the lockfile resolves; else an exact declaration. */
+const currentVersion = (p) => p.installed ?? p.locked ?? exactVersion(p.declared);
+/** A package already past its approved version: an update keeps it where it is, never moves it down. */
+const aheadOfApproved = (p) => {
+    const current = currentVersion(p);
+    return current !== null && p.approved !== null && compareVersions(current, p.approved) > 0;
+};
+/** The exact-version add invocations for the declared packages, one per dependency group, so each
+ *  package stays in the group it is already in. Every spec is a known package at an exact version.
+ *  A package already newer than its approved version is left out. */
+export function sdkUpdateArgv(manager, packages) {
+    const byGroup = new Map();
+    for (const p of packages)
+        if (p.approved !== null && !aheadOfApproved(p))
+            byGroup.set(p.group, [...(byGroup.get(p.group) ?? []), `${p.name}@${p.approved}`]);
+    return [...byGroup].map(([group, specs]) => {
+        const flags = {
+            npm: ["install", "--save-exact", ...(group === "devDependencies" ? ["--save-dev"] : group === "optionalDependencies" ? ["--save-optional"] : [])],
+            pnpm: ["add", "--save-exact", ...(group === "devDependencies" ? ["--save-dev"] : group === "optionalDependencies" ? ["--save-optional"] : [])],
+            bun: ["add", "--exact", ...(group === "devDependencies" ? ["--dev"] : group === "optionalDependencies" ? ["--optional"] : [])],
+            yarn: ["add", "--exact", ...(group === "devDependencies" ? ["--dev"] : group === "optionalDependencies" ? ["--optional"] : [])],
+        };
+        return [manager, ...flags[manager], ...specs];
+    });
+}
+/** The same move as one command a person can paste. */
+export function sdkUpdateCommand(dir, manager, packages) {
+    const argv = sdkUpdateArgv(manager, packages);
+    if (argv.length === 0)
+        return null;
+    return `cd ${quote(dir)} && ${argv.map((a) => a.map(quote).join(" ")).join(" && ")}`;
+}
+/** What `catalyst update sdk` tells the owner to run: this CLI's own explicit, one-project update. */
+export function catalystSdkCommand(dir) {
+    return `catalyst update sdk --project ${quote(dir)}`;
+}
+/** Read one project's SDK packages against `release` (null when no approved record is usable). */
+export function inspectSdkProject(dir, release) {
+    const base = { path: dir, packageManager: null, packages: [], command: null, packageManagerCommand: null };
+    const manifest = readJson(join(dir, "package.json"));
+    if (!isRecord(manifest))
+        return { ...base, status: "unknown", reason: "package_json_unreadable" };
+    const packages = [];
+    for (const [name, member] of Object.entries(SDK_PACKAGES)) {
+        for (const group of GROUPS) {
+            const deps = manifest[group];
+            if (!isRecord(deps) || typeof deps[name] !== "string")
+                continue;
+            packages.push({
+                name,
+                group,
+                declared: deps[name],
+                locked: null,
+                installed: installedVersion(dir, name),
+                approved: release?.members[member] ?? null,
+            });
+            break;
+        }
+    }
+    if (packages.length === 0)
+        return { ...base, status: "no_sdk", reason: "no_sdk" };
+    const detected = detectPackageManager(dir, manifest);
+    if (detected.manager === "npm")
+        for (const p of packages)
+            p.locked = npmLocked(dir, p.name);
+    const project = { ...base, packageManager: detected.manager, packages };
+    if (release === null)
+        return { ...project, status: "approval_unavailable", reason: "approval_unavailable" };
+    if (detected.manager === null)
+        return { ...project, status: "unknown", reason: detected.reason ?? "package_manager_ambiguous" };
+    const pairs = [];
+    for (const p of packages) {
+        if (p.approved === null)
+            return { ...project, status: "approval_unavailable", reason: "approval_unavailable" };
+        const current = currentVersion(p);
+        if (current === null)
+            return { ...project, status: "unknown", reason: "installed_version_unknown" };
+        pairs.push({ current, approved: p.approved });
+    }
+    if (pairs.some((v) => compareVersions(v.current, v.approved) < 0))
+        return {
+            ...project,
+            status: "update_available",
+            reason: "behind_approved",
+            command: catalystSdkCommand(dir),
+            packageManagerCommand: sdkUpdateCommand(dir, detected.manager, packages),
+        };
+    if (pairs.some((v) => compareVersions(v.current, v.approved) > 0))
+        return { ...project, status: "installed_newer", reason: "installed_newer" };
+    return { ...project, status: "current", reason: "current" };
+}
+export const spawnPackageManager = (argv, cwd) => {
+    const [cmd, ...args] = argv;
+    if (cmd === undefined)
+        return { status: 1, stderr: "no command" };
+    const run = spawnSync(cmd, args, { cwd, stdio: ["ignore", "ignore", "pipe"], encoding: "utf8", timeout: 10 * 60_000 });
+    return { status: run.error ? 1 : run.status, stderr: run.error ? run.error.message : (run.stderr ?? "") };
+};
+/** The package files a manager writes: the manifest and every lockfile name it may create. */
+const PACKAGE_FILES = ["package.json", ...Object.values(LOCKFILES).flat()];
+/** Longer than the package manager's own timeout, so a live run's lock is never taken over. */
+const SDK_LOCK_STALE_MS = 15 * 60_000;
+function takeProjectLock(home, dir) {
+    const locks = join(configDirFor(home), "sdk-update-locks");
+    mkdirSync(locks, { recursive: true, mode: 0o700 });
+    const path = join(locks, `${createHash("sha256").update(dir).digest("hex").slice(0, 32)}.lock`);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            closeSync(openSync(path, "wx", 0o600));
+            return path;
+        }
+        catch {
+            // A run killed mid-install leaves its lock behind; past the stale age it is taken over.
+            try {
+                if (Date.now() - statSync(path).mtimeMs <= SDK_LOCK_STALE_MS)
+                    return null;
+                unlinkSync(path);
+            }
+            catch {
+                // gone already: try again
+            }
+        }
+    }
+    return null;
+}
+/** Move one project's declared SDK packages to their approved versions with its own manager. */
+export function applySdkUpdate(home, dir, release, exec = spawnPackageManager) {
+    const project = inspectSdkProject(dir, release);
+    if (project.status === "current")
+        return { outcome: "current", detail: "current", moved: [], project };
+    if (project.status !== "update_available" || project.packageManager === null)
+        return { outcome: "refused", detail: project.reason, moved: [], project };
+    const manager = project.packageManager;
+    const lock = takeProjectLock(home, dir);
+    if (lock === null)
+        return { outcome: "refused", detail: "update_running", moved: [], project };
+    try {
+        // Each package file's bytes before the run, or null for one that did not exist yet.
+        const kept = new Map(PACKAGE_FILES.map((f) => [f, existsSync(join(dir, f)) ? readFileSync(join(dir, f)) : null]));
+        const failed = (detail) => {
+            // Put back what this run changed: earlier bytes for a file it rewrote, removal for one it created.
+            for (const [file, bytes] of kept) {
+                const path = join(dir, file);
+                const now = existsSync(path) ? readFileSync(path) : null;
+                if (bytes === null) {
+                    if (now !== null)
+                        rmSync(path, { force: true });
+                }
+                else if (now === null || !now.equals(bytes))
+                    writeFileSync(path, bytes);
+            }
+            return { outcome: "failed", detail, moved: [], project: inspectSdkProject(dir, release) };
+        };
+        for (const argv of sdkUpdateArgv(manager, project.packages)) {
+            const run = exec(argv, dir);
+            if (run.status !== 0)
+                return failed("package_manager_failed");
+        }
+        const after = inspectSdkProject(dir, release);
+        const moved = [];
+        for (const p of after.packages) {
+            const before = project.packages.find((q) => q.name === p.name);
+            const now = p.installed ?? p.locked;
+            if (before !== undefined && aheadOfApproved(before)) {
+                // Left out of the install: it must still be where it was.
+                const stays = currentVersion(p);
+                if (stays === null || compareVersions(stays, currentVersion(before) ?? stays) !== 0)
+                    return failed("verify_failed");
+                continue;
+            }
+            if (now === null || p.approved === null || compareVersions(now, p.approved) !== 0)
+                return failed("verify_failed");
+            moved.push({ name: p.name, from: before?.installed ?? before?.locked ?? before?.declared ?? "unknown", to: now });
+        }
+        return { outcome: "updated", detail: manager, moved, project: after };
+    }
+    finally {
+        try {
+            unlinkSync(lock);
+        }
+        catch {
+            // released already
+        }
+    }
+}

package/dist/update-skills.js

@@ -0,0 +1,64 @@
+// update-skills.ts — the Cloud skills pack moves to its approved version (CTC-6708). The pack
+// ships inside the CLI package of the same version, so a release check installs that exact CLI
+// package into its own directory (update-cli.ts's stageCliRuntime, which checks it and selects
+// nothing), checks that its bundled skills carry the approved version's stamp, and refreshes the
+// copies of those skills this install already made. That works while the CLI itself is held: the
+// pack comes from the staged package, never from the older CLI's own bundle.
+//
+// It changes only what installSkills already treats as its own: a skill folder stamped by this
+// package. A person's own skill of the same name, a symlinked entry (a plugin or the installer's
+// link) and any skill not installed yet are left as they are. Success is read back from the stamps
+// on disk.
+import { existsSync, lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { installedBundleVersion, installSkills } from "./skills.js";
+import { stageCliRuntime, stagedSkillsDir } from "./update-cli.js";
+const skillNames = (dir) => readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, "SKILL.md")))
+    .map((e) => e.name);
+/** Stamped Cloud skills that are links: installSkills never writes through one, so copying cannot move them. */
+function linkedPackEntries(skillsDir) {
+    let entries;
+    try {
+        entries = readdirSync(skillsDir);
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((name) => {
+        try {
+            return lstatSync(join(skillsDir, name)).isSymbolicLink() && installedBundleVersion(skillsDir, [name]).version !== null;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Refresh the Cloud pack's installed skills in `skillsDir` to exact version `target`. */
+export function applyCloudPackUpdate(home, skillsDir, target, deps = {}) {
+    // Checked before any download, so a linked pack is not fetched again on every run.
+    if (linkedPackEntries(skillsDir).length > 0)
+        return { outcome: "linked", detail: "installation_owner_unknown", version: null };
+    const staged = stageCliRuntime(home, target, deps);
+    if (!staged.ok)
+        return { outcome: "failed", detail: staged.detail, version: null };
+    const source = stagedSkillsDir(staged.root);
+    let names;
+    try {
+        names = skillNames(source);
+    }
+    catch {
+        return { outcome: "failed", detail: "pack_mismatch", version: null };
+    }
+    // The staged package must carry exactly the approved pack, or nothing is copied.
+    if (names.length === 0 || installedBundleVersion(source, names).version !== target)
+        return { outcome: "failed", detail: "pack_mismatch", version: null };
+    try {
+        installSkills(skillsDir, { onlyExisting: true }, source, target);
+    }
+    catch {
+        return { outcome: "failed", detail: "install_failed", version: installedBundleVersion(skillsDir, names).version };
+    }
+    const now = installedBundleVersion(skillsDir, names).version;
+    return now === target ? { outcome: "updated", detail: "refreshed", version: now } : { outcome: "failed", detail: "verify_failed", version: now };
+}

package/dist/update-windows.js

@@ -0,0 +1,81 @@
+// update-windows.ts — the set times of day a self-hosted machine takes a new release (CTC-6709).
+// The 15-minute schedule checks often so an owner sees the approved release quickly, but a busy
+// machine restarting its supervisor every time a release lands would interrupt its owner's day as
+// often as releases ship. So the schedule applies a newer release only once a window has opened
+// since the last window a run settled, and an owner's own `catalyst runner update` applies at once.
+// Windows are wall-clock times in the machine's time zone, or the zone its owner saved.
+/** Four windows a day, spread so a release approved at any time waits at most about eight hours. */
+export const DEFAULT_WINDOW_TIMES = ["03:00", "11:00", "16:00", "22:00"];
+const TIME = /^([01][0-9]|2[0-3]):([0-5][0-9])$/;
+export function defaultWindows() {
+    return { times: [...DEFAULT_WINDOW_TIMES], timeZone: null };
+}
+export function isWindowTime(value) {
+    return TIME.test(value);
+}
+/** Whether this runtime knows the zone. `Intl` throws a RangeError for one it does not. */
+export function isTimeZone(value) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: value });
+        return value.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function machineTimeZone() {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+}
+/** Sorted, distinct `HH:MM` times, or null when any entry is not one or there are none. */
+export function normalizeWindowTimes(values) {
+    if (values.length === 0 || values.length > 24 || !values.every(isWindowTime))
+        return null;
+    return [...new Set(values)].sort();
+}
+/** The zone's wall clock at an instant, as the parts a window time is compared with. */
+function wallClock(ms, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+    }).formatToParts(new Date(ms));
+    const get = (type) => Number(parts.find((p) => p.type === type)?.value);
+    return { year: get("year"), month: get("month"), day: get("day"), hour: get("hour"), minute: get("minute") };
+}
+/** The zone's offset from UTC at an instant, in milliseconds, to the minute. */
+function offsetMs(ms, timeZone) {
+    const w = wallClock(ms, timeZone);
+    return Date.UTC(w.year, w.month - 1, w.day, w.hour, w.minute) - Math.floor(ms / 60_000) * 60_000;
+}
+/** The instant a wall-clock time falls on in the zone. A time a clock change skips or repeats lands within an hour of it. */
+function instantOf(year, month, day, hour, minute, timeZone) {
+    const asUtc = Date.UTC(year, month - 1, day, hour, minute);
+    const first = asUtc - offsetMs(asUtc, timeZone);
+    return asUtc - offsetMs(first, timeZone);
+}
+/** The window before and after `nowMs`. */
+export function windowBounds(nowMs, windows) {
+    const timeZone = windows.timeZone ?? machineTimeZone();
+    const times = normalizeWindowTimes(windows.times) ?? [...DEFAULT_WINDOW_TIMES];
+    const today = wallClock(nowMs, timeZone);
+    const candidates = [];
+    // Two calendar days either side of today's date in the zone. Stepping by date, not by 24 hours,
+    // keeps a 23- or 25-hour day around a clock change from skipping a date or reading one twice.
+    for (let shift = -2; shift <= 2; shift++) {
+        const date = new Date(Date.UTC(today.year, today.month - 1, today.day + shift));
+        for (const time of times) {
+            const [hour, minute] = time.split(":").map(Number);
+            candidates.push(instantOf(date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate(), hour, minute, timeZone));
+        }
+    }
+    candidates.sort((a, b) => a - b);
+    const lastOpenedMs = candidates.filter((ms) => ms <= nowMs).pop();
+    const nextOpensMs = candidates.find((ms) => ms > nowMs);
+    if (lastOpenedMs === undefined || nextOpensMs === undefined)
+        throw new Error(`no update window around ${new Date(nowMs).toISOString()} in ${timeZone}`);
+    return { lastOpenedMs, nextOpensMs, timeZone };
+}