@caelo-cms/shared 0.10.48 → 0.10.49

package/src/auto-update.test.ts

@@ -0,0 +1,321 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  type AutoUpdateInput,
+  decideAutoUpdate,
+  isPausedAt,
+  isSecurityRelease,
+  nextWindowOpening,
+  type ReleaseFacts,
+} from "./auto-update.js";
+import type { StoredUpdatePolicy } from "./platform-updates.js";
+
+const NOW = new Date("2026-10-14T12:00:00Z");
+const hoursAgo = (h: number) => new Date(NOW.getTime() - h * 3_600_000).toISOString();
+
+const POLICY: StoredUpdatePolicy = {
+  mode: "auto",
+  autoSecurity: true,
+  autoPatch: true,
+  autoMinor: false,
+  channel: "stable",
+  windowStart: null,
+  windowEnd: null,
+  windowTimezone: "UTC",
+  soakHours: 24,
+  securitySoakHours: 2,
+  paused: false,
+  pausedReason: null,
+  pausedAt: null,
+  pausedUntil: null,
+  pausedByOwner: false,
+  updatedAt: "2026-10-01T00:00:00Z",
+};
+
+const FACTS: ReleaseFacts = {
+  security: false,
+  advisories: [],
+  contractMigrations: false,
+  infraChange: false,
+};
+const SECURITY: ReleaseFacts = {
+  ...FACTS,
+  security: true,
+  advisories: ["GHSA-abcd-efgh-jkmp"],
+};
+
+const INSTALLED = "0.10.47";
+const VERSIONS = { patch: "0.10.48", minor: "0.11.0", major: "1.0.0" } as const;
+
+function input(over: Partial<AutoUpdateInput> & { version?: string; publishedHoursAgo?: number }) {
+  const { version = VERSIONS.patch, publishedHoursAgo = 48, ...rest } = over;
+  return {
+    policy: POLICY,
+    installedVersion: INSTALLED,
+    release: { version, publishedAt: hoursAgo(publishedHoursAgo) },
+    facts: FACTS,
+    upgraderAvailable: true,
+    now: NOW,
+    ...rest,
+  } satisfies AutoUpdateInput;
+}
+
+describe("decideAutoUpdate — release type × policy toggles", () => {
+  type Kind = keyof typeof VERSIONS;
+  const cases: [Kind, boolean, Partial<StoredUpdatePolicy>, string, string | null][] = [
+    // [type, security, policy toggles, expected action, expected basis]
+    ["patch", false, { autoPatch: true }, "install", "patch"],
+    ["patch", false, { autoPatch: false, autoSecurity: true }, "notify", null],
+    ["minor", false, { autoMinor: true }, "install", "minor"],
+    ["minor", false, { autoMinor: false, autoPatch: true }, "notify", null],
+    ["patch", true, { autoSecurity: true, autoPatch: false }, "install", "security"],
+    ["minor", true, { autoSecurity: true, autoMinor: false }, "install", "security"],
+    ["patch", true, { autoSecurity: false, autoPatch: true }, "install", "patch"],
+    ["minor", true, { autoSecurity: false, autoMinor: false }, "notify", null],
+    // Major never installs automatically, whatever is switched on.
+    ["major", false, { autoPatch: true, autoMinor: true, autoSecurity: true }, "notify", null],
+    ["major", true, { autoPatch: true, autoMinor: true, autoSecurity: true }, "notify", null],
+  ];
+  it.each(cases)("%s (security=%s) %o → %s", (kind, security, toggles, action, basis) => {
+    const d = decideAutoUpdate(
+      input({
+        version: VERSIONS[kind],
+        policy: { ...POLICY, ...toggles },
+        facts: security ? SECURITY : FACTS,
+      }),
+    );
+    expect(d.action).toBe(action);
+    expect("basis" in d ? d.basis : null).toBe(basis);
+  });
+});
+
+describe("decideAutoUpdate — security flag needs a published advisory", () => {
+  it("a manifest saying security without a GHSA is a normal release", () => {
+    const facts = { ...FACTS, security: isSecurityRelease({ security: true, advisories: [] }) };
+    const d = decideAutoUpdate(
+      input({ policy: { ...POLICY, autoPatch: false }, facts, publishedHoursAgo: 3 }),
+    );
+    expect(d.action).toBe("notify");
+  });
+  it("isSecurityRelease", () => {
+    expect(isSecurityRelease({ security: true, advisories: ["GHSA-abcd-efgh-jkmp"] })).toBe(true);
+    expect(isSecurityRelease({ security: true, advisories: [] })).toBe(false);
+    expect(isSecurityRelease({ security: false, advisories: ["GHSA-abcd-efgh-jkmp"] })).toBe(false);
+  });
+});
+
+describe("decideAutoUpdate — soak period", () => {
+  const cases: [string, ReleaseFacts, Partial<StoredUpdatePolicy>, number, string][] = [
+    ["patch inside the 24 h soak", FACTS, {}, 23, "wait"],
+    ["patch after the 24 h soak", FACTS, {}, 25, "install"],
+    ["security inside its 2 h soak", SECURITY, {}, 1, "wait"],
+    ["security after its 2 h soak", SECURITY, {}, 3, "install"],
+    ["security with zero soak", SECURITY, { securitySoakHours: 0 }, 0, "install"],
+    // Security soak only applies when the release installs AS a security fix.
+    [
+      "security installed as patch keeps the patch soak",
+      SECURITY,
+      { autoSecurity: false },
+      3,
+      "wait",
+    ],
+    ["zero soak installs at once", FACTS, { soakHours: 0, securitySoakHours: 0 }, 0, "install"],
+  ];
+  it.each(cases)("%s", (_name, facts, policy, publishedHoursAgo, action) => {
+    const d = decideAutoUpdate(
+      input({ facts, policy: { ...POLICY, ...policy }, publishedHoursAgo }),
+    );
+    expect(d.action).toBe(action);
+  });
+
+  it("names when the wait ends", () => {
+    const d = decideAutoUpdate(input({ publishedHoursAgo: 20 }));
+    expect(d.action).toBe("wait");
+    if (d.action !== "wait") return;
+    expect(d.until?.toISOString()).toBe(new Date(NOW.getTime() + 4 * 3_600_000).toISOString());
+    expect(d.paused).toBe(false);
+  });
+
+  it("a release without a publish date is blocked, not guessed", () => {
+    const d = decideAutoUpdate({
+      ...input({}),
+      release: { version: VERSIONS.patch, publishedAt: null },
+    });
+    expect(d.action).toBe("blocked");
+    expect(d.reason).toContain("publish date");
+  });
+});
+
+describe("decideAutoUpdate — maintenance window", () => {
+  // NOW is 12:00 UTC = 14:00 in Berlin (CEST).
+  const cases: [string, Partial<StoredUpdatePolicy>, string][] = [
+    [
+      "inside a daytime window",
+      { windowStart: "13:00", windowEnd: "15:00", windowTimezone: "Europe/Berlin" },
+      "install",
+    ],
+    [
+      "outside a night window",
+      { windowStart: "02:00", windowEnd: "05:00", windowTimezone: "Europe/Berlin" },
+      "wait",
+    ],
+    [
+      "inside a window spanning midnight (UTC)",
+      { windowStart: "11:00", windowEnd: "01:00" },
+      "install",
+    ],
+    ["no window = any time", {}, "install"],
+  ];
+  it.each(cases)("%s", (_name, policy, action) => {
+    expect(decideAutoUpdate(input({ policy: { ...POLICY, ...policy } })).action).toBe(action);
+  });
+
+  it("waits until the window opens", () => {
+    const d = decideAutoUpdate(
+      input({
+        policy: {
+          ...POLICY,
+          windowStart: "02:00",
+          windowEnd: "05:00",
+          windowTimezone: "Europe/Berlin",
+        },
+      }),
+    );
+    expect(d.action === "wait" && d.until?.toISOString()).toBe("2026-10-15T00:00:00.000Z");
+  });
+
+  it("soak ending outside the window waits for the next opening", () => {
+    const d = decideAutoUpdate(
+      input({
+        publishedHoursAgo: 23, // soak ends 13:00 UTC
+        policy: { ...POLICY, windowStart: "20:00", windowEnd: "22:00" },
+      }),
+    );
+    expect(d.action === "wait" && d.until?.toISOString()).toBe("2026-10-14T20:00:00.000Z");
+  });
+});
+
+describe("decideAutoUpdate — pause", () => {
+  const cases: [string, Partial<StoredUpdatePolicy>, string, boolean][] = [
+    [
+      "paused indefinitely by the Owner",
+      { paused: true, pausedAt: hoursAgo(1), pausedByOwner: true },
+      "wait",
+      true,
+    ],
+    [
+      "paused after a failure",
+      { paused: true, pausedAt: hoursAgo(1), pausedReason: "rolled back" },
+      "wait",
+      true,
+    ],
+    [
+      "paused until tomorrow",
+      {
+        paused: true,
+        pausedAt: hoursAgo(1),
+        pausedByOwner: true,
+        pausedUntil: "2026-10-15T00:00:00Z",
+      },
+      "wait",
+      true,
+    ],
+    [
+      "pause already over",
+      { paused: true, pausedAt: hoursAgo(30), pausedByOwner: true, pausedUntil: hoursAgo(1) },
+      "install",
+      false,
+    ],
+  ];
+  it.each(cases)("%s", (_name, policy, action, paused) => {
+    const d = decideAutoUpdate(input({ policy: { ...POLICY, ...policy } }));
+    expect(d.action).toBe(action);
+    if (d.action === "wait") expect(d.paused).toBe(paused);
+  });
+
+  it("isPausedAt", () => {
+    expect(isPausedAt({ paused: false, pausedUntil: null }, NOW)).toBe(false);
+    expect(isPausedAt({ paused: true, pausedUntil: null }, NOW)).toBe(true);
+    expect(isPausedAt({ paused: true, pausedUntil: hoursAgo(-1) }, NOW)).toBe(true);
+    expect(isPausedAt({ paused: true, pausedUntil: hoursAgo(1) }, NOW)).toBe(false);
+  });
+});
+
+describe("decideAutoUpdate — releases that never install automatically", () => {
+  const cases: [string, Partial<AutoUpdateInput>, string][] = [
+    ["infra change", { facts: { ...FACTS, infraChange: true } }, "needs_cloud_shell"],
+    [
+      "infra change on a security fix",
+      { facts: { ...SECURITY, infraChange: true } },
+      "needs_cloud_shell",
+    ],
+    ["destructive migrations", { facts: { ...FACTS, contractMigrations: true } }, "manual"],
+    ["destructive security fix", { facts: { ...SECURITY, contractMigrations: true } }, "manual"],
+    ["manifest unreadable", { facts: { unavailable: "HTTP 404" } }, "blocked"],
+    ["no upgrader", { upgraderAvailable: false }, "blocked"],
+  ];
+  it.each(cases)("%s → %s", (_name, over, action) => {
+    expect(decideAutoUpdate({ ...input({}), ...over }).action).toBe(action);
+  });
+
+  it("infra unknown here is left to the upgrader (it checks install.json)", () => {
+    expect(decideAutoUpdate(input({ facts: { ...FACTS, infraChange: null } })).action).toBe(
+      "install",
+    );
+  });
+
+  it("an infra-changing major is still just a major (notify)", () => {
+    const d = decideAutoUpdate(
+      input({ version: VERSIONS.major, facts: { ...FACTS, infraChange: true } }),
+    );
+    expect(d.action).toBe("notify");
+  });
+});
+
+describe("decideAutoUpdate — upgrader not ready", () => {
+  it("names why the upgrader cannot take the release (e.g. the self-hosted agent)", () => {
+    const d = decideAutoUpdate({
+      ...input({}),
+      upgraderAvailable: false,
+      upgraderProblem: "The update agent on box-1 has not checked in since 10:00.",
+    });
+    expect(d.action).toBe("blocked");
+    expect(d.reason).toContain("has not checked in");
+  });
+});
+
+describe("decideAutoUpdate — modes and versions", () => {
+  it.each([
+    ["up to date", { version: INSTALLED }, "none"],
+    ["older release", { version: "0.10.40" }, "none"],
+    ["notices off", { policy: { ...POLICY, mode: "off" as const } }, "none"],
+    ["notify mode", { policy: { ...POLICY, mode: "notify" as const } }, "notify"],
+    [
+      "notify mode, infra change",
+      { policy: { ...POLICY, mode: "notify" as const }, facts: { ...FACTS, infraChange: true } },
+      "notify",
+    ],
+    ["pre-release", { version: "0.11.0-rc.1" }, "notify"],
+  ] as const)("%s → %s", (_name, over, action) => {
+    expect(decideAutoUpdate(input(over as Parameters<typeof input>[0])).action).toBe(action);
+  });
+
+  it("no release known yet → none", () => {
+    expect(decideAutoUpdate({ ...input({}), release: null }).action).toBe("none");
+  });
+});
+
+describe("nextWindowOpening", () => {
+  it("returns the start of the next window in the window's time zone", () => {
+    const p = { windowStart: "02:00", windowEnd: "05:00", windowTimezone: "America/New_York" };
+    // 12:00 UTC = 08:00 New York (EDT) → next 02:00 New York = 06:00 UTC tomorrow.
+    expect(nextWindowOpening(p, NOW)?.toISOString()).toBe("2026-10-15T06:00:00.000Z");
+  });
+  it("is `from` itself (rounded up to the minute) inside the window", () => {
+    const p = { windowStart: "11:00", windowEnd: "13:00", windowTimezone: "UTC" };
+    expect(nextWindowOpening(p, new Date("2026-10-14T12:00:30Z"))?.toISOString()).toBe(
+      "2026-10-14T12:01:00.000Z",
+    );
+  });
+});

package/src/auto-update.ts

@@ -0,0 +1,315 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The automatic-update decision (epic #696 Phase 5): given the Owner's
+ * policy, the installed and the newest release, and what the release's
+ * manifest says about it, what the scheduler inside the admin does now.
+ *
+ * Pure and table-tested (auto-update.test.ts). The scheduler
+ * (admin-core platform-updates/scheduler.ts) gathers the inputs, this
+ * decides, the `platform_updates.scheduler_tick` op records the decision,
+ * queues the install and the Owner's emails.
+ *
+ * The scheduler is not the trust boundary. It reads the manifest without
+ * checking its signature (the admin image ships no cosign), so it only
+ * decides *when to ask*. The upgrader job verifies the signed manifest
+ * and refuses an automatic request the policy, the infrastructure contract
+ * or destructive migrations forbid (provisioning upgrader-assess.ts),
+ * including one queued as a security fix for a release whose signed
+ * manifest names no advisory — so a forged "security" flag cannot shorten
+ * the soak period.
+ *
+ * Rules, in order (maintainer decisions on #696):
+ *   1. nothing newer, or notices off → none;
+ *   2. off the stable channel, or the policy only notifies → notify;
+ *   3. major → notify (never automatic before 1.0);
+ *   4. release information unreadable → blocked (fails loudly, no guess);
+ *   5. changes the cloud setup → needs_cloud_shell (never automatic);
+ *   6. destructive database changes → manual (never automatic);
+ *   7. the kind is not switched on (security / patch / minor) → notify;
+ *   8. no upgrader on this install → blocked;
+ *   9. paused by the Owner or after a failure → wait;
+ *  10. soak period not over (security releases: their own, shorter one) → wait;
+ *  11. outside the maintenance window → wait until it opens;
+ *  12. otherwise → install.
+ */
+
+import {
+  inMaintenanceWindow,
+  type StoredUpdatePolicy,
+  type UpdateKind,
+  updateKind,
+} from "./platform-updates.js";
+
+/** Why the scheduler queued an automatic install (`platform_update_requests.auto_basis`). */
+export const AUTO_UPDATE_BASES = ["security", "patch", "minor"] as const;
+export type AutoUpdateBasis = (typeof AUTO_UPDATE_BASES)[number];
+
+/** What the scheduler last did (`platform_update_scheduler.last_action`). */
+export const AUTO_UPDATE_ACTIONS = [
+  "none",
+  "notify",
+  "wait",
+  "install",
+  "manual",
+  "needs_cloud_shell",
+  "blocked",
+] as const;
+export type AutoUpdateAction = (typeof AUTO_UPDATE_ACTIONS)[number];
+
+/** The Owner's update emails (`platform_update_notifications.kind`). */
+export const UPDATE_NOTIFICATION_KINDS = [
+  "available",
+  "scheduled",
+  "installed",
+  "failed",
+  "needs_cloud_shell",
+] as const;
+export type UpdateNotificationKind = (typeof UPDATE_NOTIFICATION_KINDS)[number];
+
+/**
+ * Whether a release counts as a security fix: the signed manifest says so
+ * AND names at least one published GitHub Security Advisory (#696 decision
+ * 2). The release workflow refuses `security: true` without one; this is
+ * the second line.
+ */
+export function isSecurityRelease(manifest: {
+  readonly security: boolean;
+  readonly advisories: readonly string[];
+}): boolean {
+  return manifest.security && manifest.advisories.length > 0;
+}
+
+/** What the scheduler knows about the newest release from its manifest. */
+export interface ReleaseFacts {
+  /** {@link isSecurityRelease} of the manifest. */
+  readonly security: boolean;
+  readonly advisories: readonly string[];
+  /** The release, or one it skips, carries destructive (contract) migrations. */
+  readonly contractMigrations: boolean;
+  /**
+   * The release raises the infrastructure contract over the installed one.
+   * null: not known here (the installed release has no manifest, or the
+   * install has no separate cloud setup) — the upgrader checks it against
+   * the install's own state before it changes anything.
+   */
+  readonly infraChange: boolean | null;
+}
+
+/** Everything {@link decideAutoUpdate} looks at. */
+export interface AutoUpdateInput {
+  readonly policy: StoredUpdatePolicy;
+  readonly installedVersion: string;
+  /** The newest release the release check found, or null. */
+  readonly release: { readonly version: string; readonly publishedAt: string | null } | null;
+  /** The release's facts, or why they could not be read. */
+  readonly facts: ReleaseFacts | { readonly unavailable: string };
+  /** This install has an upgrader the admin can hand a request to. */
+  readonly upgraderAvailable: boolean;
+  /** Why it has none right now, in plain words (null: none set up at all). */
+  readonly upgraderProblem?: string | null;
+  readonly now: Date;
+}
+
+/** What the scheduler does with the newest release now. */
+export type AutoUpdateDecision =
+  | { readonly action: "none"; readonly reason: string }
+  | {
+      readonly action: "notify" | "manual" | "needs_cloud_shell" | "blocked";
+      readonly version: string;
+      readonly kind: UpdateKind;
+      readonly reason: string;
+    }
+  | {
+      readonly action: "wait";
+      readonly version: string;
+      readonly kind: UpdateKind;
+      readonly basis: AutoUpdateBasis;
+      readonly reason: string;
+      /** When it becomes installable; null = until the Owner resumes. */
+      readonly until: Date | null;
+      /** Waiting because automatic installs are paused (not soak/window). */
+      readonly paused: boolean;
+    }
+  | {
+      readonly action: "install";
+      readonly version: string;
+      readonly kind: UpdateKind;
+      readonly basis: AutoUpdateBasis;
+      readonly reason: string;
+    };
+
+/** Whether automatic installs are paused at `now` (an Owner pause may have ended). */
+export function isPausedAt(
+  policy: Pick<StoredUpdatePolicy, "paused" | "pausedUntil">,
+  now: Date,
+): boolean {
+  if (!policy.paused) return false;
+  return policy.pausedUntil === null || new Date(policy.pausedUntil).getTime() > now.getTime();
+}
+
+/**
+ * The first minute at or after `from` inside the maintenance window, or
+ * null when it does not open within two days (cannot happen for a valid
+ * window; null keeps the caller honest instead of guessing).
+ */
+export function nextWindowOpening(
+  policy: Pick<StoredUpdatePolicy, "windowStart" | "windowEnd" | "windowTimezone">,
+  from: Date,
+): Date | null {
+  const start = new Date(Math.ceil(from.getTime() / 60_000) * 60_000);
+  for (let m = 0; m <= 2 * 24 * 60; m++) {
+    const at = new Date(start.getTime() + m * 60_000);
+    if (inMaintenanceWindow(policy, at)) return at;
+  }
+  return null;
+}
+
+const KIND_WORDS: Record<UpdateKind, string> = {
+  major: "major release",
+  minor: "minor release",
+  patch: "patch release",
+};
+
+const BASIS_WORDS: Record<AutoUpdateBasis, string> = {
+  security: "security fix",
+  patch: "patch release",
+  minor: "minor release",
+};
+
+/** `v0.11.0` channel by its pre-release tag (`0.11.0-rc.1` → rc). */
+function isStable(version: string): boolean {
+  return !version.includes("-");
+}
+
+const hours = (n: number) => `${n} hour${n === 1 ? "" : "s"}`;
+
+/** Decide what the scheduler does now. See the file comment for the rules. */
+export function decideAutoUpdate(input: AutoUpdateInput): AutoUpdateDecision {
+  const { policy, release, now } = input;
+  if (!release) {
+    return { action: "none", reason: "The release check has not found a Caelo release yet." };
+  }
+  const kind = updateKind(input.installedVersion, release.version);
+  if (kind === null) {
+    return { action: "none", reason: `v${input.installedVersion} is the newest release.` };
+  }
+  if (policy.mode === "off") {
+    return { action: "none", reason: "Update notices are switched off in the update policy." };
+  }
+  const v = release.version;
+  const base = { version: v, kind } as const;
+  if (!isStable(v)) {
+    return {
+      action: "notify",
+      ...base,
+      reason: `v${v} is a pre-release; only stable releases install automatically.`,
+    };
+  }
+  if (policy.mode === "notify") {
+    return {
+      action: "notify",
+      ...base,
+      reason: `v${v} is available. The update policy only notifies; the Owner installs it.`,
+    };
+  }
+  if (kind === "major") {
+    return {
+      action: "notify",
+      ...base,
+      reason: `v${v} is a major release; major releases never install automatically before Caelo 1.0.`,
+    };
+  }
+  if ("unavailable" in input.facts) {
+    return {
+      action: "blocked",
+      ...base,
+      reason: `The release information of v${v} could not be read (${input.facts.unavailable}), so it is not installed automatically. The next check tries again; the Owner can install it from Settings → Updates.`,
+    };
+  }
+  const facts = input.facts;
+  if (facts.infraChange === true) {
+    return {
+      action: "needs_cloud_shell",
+      ...base,
+      reason: `v${v} changes this install's cloud setup, which the admin may not do. It is never installed automatically: the Owner runs it once with their own account in Cloud Shell.`,
+    };
+  }
+  if (facts.contractMigrations) {
+    return {
+      action: "manual",
+      ...base,
+      reason: `v${v} makes database changes the previous release cannot run on, so it never installs automatically. The Owner installs it from Settings → Updates.`,
+    };
+  }
+  const basis: AutoUpdateBasis | null =
+    facts.security && policy.autoSecurity
+      ? "security"
+      : kind === "patch" && policy.autoPatch
+        ? "patch"
+        : kind === "minor" && policy.autoMinor
+          ? "minor"
+          : null;
+  if (basis === null) {
+    const what = facts.security ? `security fix (${KIND_WORDS[kind]})` : KIND_WORDS[kind];
+    return {
+      action: "notify",
+      ...base,
+      reason: `v${v} is a ${what}; the update policy does not install those automatically. The Owner installs it.`,
+    };
+  }
+  if (!input.upgraderAvailable) {
+    return {
+      action: "blocked",
+      ...base,
+      reason: input.upgraderProblem
+        ? `v${v} could install automatically, but the upgrader cannot take it now: ${input.upgraderProblem}`
+        : `v${v} could install automatically, but this install has no upgrader the admin can start. Run the upgrade command from Settings → Updates once; it sets the upgrader up.`,
+    };
+  }
+  const auto = { ...base, basis } as const;
+  if (isPausedAt(policy, now)) {
+    const until = policy.pausedUntil === null ? null : new Date(policy.pausedUntil);
+    const who = policy.pausedByOwner ? "by the Owner" : "after a failed automatic install";
+    return {
+      action: "wait",
+      ...auto,
+      until,
+      paused: true,
+      reason: `Automatic installs are paused ${who}${until ? ` until ${until.toISOString()}` : " until the Owner resumes them"}${policy.pausedReason ? ` (${policy.pausedReason})` : ""}.`,
+    };
+  }
+  if (release.publishedAt === null) {
+    return {
+      action: "blocked",
+      ...base,
+      reason: `The publish date of v${v} is not known, so its soak period cannot be counted. The next release check fills it in.`,
+    };
+  }
+  const soak = basis === "security" ? policy.securitySoakHours : policy.soakHours;
+  const ready = new Date(new Date(release.publishedAt).getTime() + soak * 3_600_000);
+  if (ready.getTime() > now.getTime()) {
+    const opening = inMaintenanceWindow(policy, ready) ? ready : nextWindowOpening(policy, ready);
+    return {
+      action: "wait",
+      ...auto,
+      until: opening,
+      paused: false,
+      reason: `v${v} (${BASIS_WORDS[basis]}) installs automatically once it has been out for ${hours(soak)}${opening && opening.getTime() !== ready.getTime() ? " and the maintenance window is open" : ""}.`,
+    };
+  }
+  if (!inMaintenanceWindow(policy, now)) {
+    return {
+      action: "wait",
+      ...auto,
+      until: nextWindowOpening(policy, now),
+      paused: false,
+      reason: `v${v} (${BASIS_WORDS[basis]}) installs automatically when the maintenance window opens (${policy.windowStart}–${policy.windowEnd} ${policy.windowTimezone}).`,
+    };
+  }
+  return {
+    action: "install",
+    ...auto,
+    reason: `v${v} (${BASIS_WORDS[basis]}) installs automatically: the update policy allows it, its ${hours(soak)} soak period is over${policy.windowStart ? " and the maintenance window is open" : ""}.`,
+  };
+}

package/src/index.ts

@@ -4,6 +4,7 @@ export const PROJECT_NAME = "caelo-cms";
 
 export * from "./ai-tools.js";
 export * from "./auth-forms.js";
+export * from "./auto-update.js";
 export * from "./base-css.js";
 export * from "./build-page.js";
 export * from "./cap-failures.js";
@@ -43,6 +44,7 @@ export * from "./preview-scanner.js";
 export * from "./proposal-status.js";
 export * from "./provisioning-command.js";
 export * from "./redirect-target.js";
+export * from "./release-manifest.js";
 export * from "./responsive-images.js";
 export * from "./result.js";
 export * from "./safe-keys.js";

package/src/platform-updates.test.ts

@@ -66,9 +66,12 @@ describe("autoInstallRefusal", () => {
     windowEnd: null,
     windowTimezone: "UTC",
     soakHours: 24,
+    securitySoakHours: 2,
     paused: false,
     pausedReason: null,
     pausedAt: null,
+    pausedUntil: null,
+    pausedByOwner: false,
     updatedAt: "2026-10-13T00:00:00Z",
   };
   const now = new Date("2026-10-13T12:00:00Z");
@@ -125,6 +128,7 @@ describe("updatePolicySchema", () => {
     windowEnd: "04:00",
     windowTimezone: "Europe/Berlin",
     soakHours: 24,
+    securitySoakHours: 2,
   };
   it("accepts a sane policy and rejects broken ones", () => {
     expect(updatePolicySchema.safeParse(base).success).toBe(true);
@@ -134,6 +138,7 @@ describe("updatePolicySchema", () => {
       { ...base, windowStart: "25:00" },
       { ...base, windowTimezone: "Nowhere/Land" },
       { ...base, soakHours: 1000 },
+      { ...base, securitySoakHours: 48 },
       { ...base, extra: true },
     ]) {
       expect(updatePolicySchema.safeParse(bad).success).toBe(false);