@caelo-cms/shared 0.10.46 → 0.10.48

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAKL,UAAU,EACV,aAAa,EACb,MAAM,GAGP,MAAM,aAAa,CAAC;AACrB,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,aAAa,EACb,aAAa,EAEb,cAAc,EACd,YAAY,GACb,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAKL,UAAU,EACV,aAAa,EACb,MAAM,GAGP,MAAM,aAAa,CAAC;AACrB,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,aAAa,EACb,aAAa,EAEb,cAAc,EACd,YAAY,GACb,MAAM,cAAc,CAAC"}

package/dist/platform-updates.d.ts

@@ -0,0 +1,154 @@
+/**
+ * In-product Caelo updates (epic #696): the vocabulary the admin (Settings →
+ * Updates, the `platform_updates.*` ops), the upgrader job and the Phase 5
+ * scheduler share. One module so the timeline the page renders, the states
+ * the job writes and the database CHECK constraints (migration 0267) agree.
+ */
+import { z } from "zod";
+/** Every state of an update request (`platform_update_requests.status`). */
+export declare const PLATFORM_UPDATE_STATUSES: readonly ["pending", "running", "succeeded", "rolled_back", "failed", "refused", "needs_cloud_shell", "cancelled"];
+export type PlatformUpdateStatusValue = (typeof PLATFORM_UPDATE_STATUSES)[number];
+/** States in which a request is still in flight (at most one at a time). */
+export declare const ACTIVE_UPDATE_STATUSES: readonly PlatformUpdateStatusValue[];
+/** Whether `status` is an end state. */
+export declare function isFinishedUpdateStatus(status: PlatformUpdateStatusValue): boolean;
+/**
+ * The phases of an upgrader run, in order (`platform_update_events.phase`).
+ * `rollback` only appears when a roll had to be undone.
+ */
+export declare const PLATFORM_UPDATE_PHASES: readonly ["queued", "start", "verify", "assess", "backup", "health-baseline", "migrations", "roll", "health", "rollback", "record", "self-update", "finish"];
+export type PlatformUpdatePhase = (typeof PLATFORM_UPDATE_PHASES)[number];
+/** Severity of one timeline line. */
+export declare const PLATFORM_UPDATE_EVENT_LEVELS: readonly ["info", "success", "warn", "error"];
+export type PlatformUpdateEventLevel = (typeof PLATFORM_UPDATE_EVENT_LEVELS)[number];
+/** Who started a request: the Owner's click, or the Phase 5 scheduler. */
+export declare const PLATFORM_UPDATE_TRIGGERS: readonly ["manual", "auto"];
+export type PlatformUpdateTrigger = (typeof PLATFORM_UPDATE_TRIGGERS)[number];
+/**
+ * A run still `running` this long after it started died (the upgrader job's
+ * task timeout is 60 minutes). The next job run, and the next install
+ * request, end it as failed — so a crashed run never blocks updates.
+ */
+export declare const PLATFORM_UPDATE_STALE_MINUTES = 90;
+/**
+ * Why a stale run was ended (shown on its timeline). Provider-neutral: the
+ * same text ends a dead Google Cloud job run and a dead self-hosted agent
+ * run, and Settings → Updates shows each install its own way to upgrade by
+ * hand (Cloud Shell there, the upgrade command on the server here).
+ */
+export declare const PLATFORM_UPDATE_STALE_REASON = "The upgrader stopped before it finished (its run timed out or crashed). The previous release may still serve, or the new one may be partly rolled out: open the site, and if it misbehaves run the upgrade by hand once \u2014 Settings \u2192 Updates shows how for this install.";
+/** Longest an event message may be (DB CHECK). */
+export declare const PLATFORM_UPDATE_EVENT_MAX = 4000;
+/** A SemVer release version without a leading `v` (`0.11.0`, `0.11.0-rc.1`). */
+export declare const releaseVersionSchema: z.ZodString;
+/** How big a step from `from` to `to` is, by SemVer position. */
+export type UpdateKind = "major" | "minor" | "patch";
+/**
+ * Classify the step from the installed release to a newer one.
+ *
+ * @returns null when `to` is not newer than `from` or either is not SemVer.
+ * @example updateKind("0.10.45", "0.10.46") // → "patch"
+ */
+export declare function updateKind(from: string, to: string): UpdateKind | null;
+/** The automatic-update modes. */
+export declare const UPDATE_POLICY_MODES: readonly ["off", "notify", "auto"];
+export type UpdatePolicyMode = (typeof UPDATE_POLICY_MODES)[number];
+/** Release channels a policy may follow (only `stable` installs automatically). */
+export declare const UPDATE_POLICY_CHANNELS: readonly ["stable", "rc", "beta", "alpha"];
+/** Whether `tz` is an IANA time zone this runtime knows. */
+export declare function isKnownTimeZone(tz: string): boolean;
+/**
+ * The Owner's automatic-update policy (`platform_update_policy`), as the
+ * ops read and write it. Major releases have no toggle: they are never
+ * installed automatically before 1.0.
+ */
+export declare const updatePolicySchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        auto: "auto";
+        off: "off";
+        notify: "notify";
+    }>;
+    autoSecurity: z.ZodBoolean;
+    autoPatch: z.ZodBoolean;
+    autoMinor: z.ZodBoolean;
+    channel: z.ZodEnum<{
+        stable: "stable";
+        rc: "rc";
+        beta: "beta";
+        alpha: "alpha";
+    }>;
+    windowStart: z.ZodNullable<z.ZodString>;
+    windowEnd: z.ZodNullable<z.ZodString>;
+    windowTimezone: z.ZodString;
+    soakHours: z.ZodNumber;
+}, z.core.$strict>;
+export type UpdatePolicy = z.infer<typeof updatePolicySchema>;
+/** The policy plus its pause state, as stored. */
+export interface StoredUpdatePolicy extends UpdatePolicy {
+    readonly paused: boolean;
+    readonly pausedReason: string | null;
+    readonly pausedAt: string | null;
+    readonly updatedAt: string;
+}
+/**
+ * Whether `at` falls inside the policy's maintenance window. A window whose
+ * end is before its start spans midnight (`22:00`–`04:00`).
+ */
+export declare function inMaintenanceWindow(policy: Pick<UpdatePolicy, "windowStart" | "windowEnd" | "windowTimezone">, at: Date): boolean;
+/** What the policy needs to know about a release to decide on an automatic install. */
+export interface AutoInstallCandidate {
+    readonly kind: UpdateKind;
+    /** From the signed manifest AND auto-installable (assessAutoInstall's `kind`). */
+    readonly security: boolean;
+    /** Manifest `migrations.contract` (or a skipped contract release). */
+    readonly contractMigrations: boolean;
+    /** The release's channel. */
+    readonly channel: string;
+}
+/**
+ * Whether the policy lets the upgrader install `candidate` unattended at
+ * `at` — the job's check for `trigger = 'auto'` requests (the scheduler
+ * applies the soak period before it ever queues one).
+ *
+ * @returns null when allowed, else the reason in plain words
+ */
+export declare function autoInstallRefusal(policy: Pick<StoredUpdatePolicy, "mode" | "autoSecurity" | "autoPatch" | "autoMinor" | "paused" | "windowStart" | "windowEnd" | "windowTimezone">, candidate: AutoInstallCandidate, at: Date): string | null;
+/**
+ * How long a verified Google sign-in authorizes one guarded action. Long
+ * enough to read the confirmation dialog, short enough that an unattended
+ * browser is useless soon after.
+ */
+export declare const STEP_UP_MAX_AGE_SECONDS = 600;
+/** What a step-up is for (`step_up_challenges.purpose`). */
+export declare const STEP_UP_PURPOSES: readonly ["platform_update", "update_policy", "step_up_client"];
+export type StepUpPurpose = (typeof STEP_UP_PURPOSES)[number];
+/**
+ * Self-hosted installs (#696 Phase 4c): the host agent (`caelo-agent`, a
+ * systemd timer on the install's host) polls for update requests this
+ * often and writes a heartbeat each time it looks.
+ */
+export declare const PLATFORM_UPDATE_AGENT_POLL_SECONDS = 60;
+/**
+ * The admin offers "Install update" on a self-hosted install only while the
+ * agent's last heartbeat is younger than this (five missed polls): a request
+ * nobody picks up would just sit there.
+ */
+export declare const PLATFORM_UPDATE_AGENT_FRESH_SECONDS = 300;
+/** The host agent's last check-in (`platform_update_agent`), as the admin reads it. */
+export interface PlatformUpdateAgentStatus {
+    /** The Caelo release of the agent's own code. */
+    readonly agentVersion: string;
+    /** The host it runs on (its hostname). */
+    readonly host: string;
+    readonly lastSeenAt: string;
+    /**
+     * What would make an install fail on that host (cosign missing, Docker
+     * not reachable), in plain words; null when its preflight passed.
+     */
+    readonly problem: string | null;
+    /** Whether {@link lastSeenAt} is within {@link PLATFORM_UPDATE_AGENT_FRESH_SECONDS}. */
+    readonly checkedInRecently: boolean;
+}
+/** Whether an agent last seen at `lastSeenAt` counts as running at `now`. */
+export declare function agentCheckedInRecently(lastSeenAt: Date | string, now: Date): boolean;
+//# sourceMappingURL=platform-updates.d.ts.map

package/dist/platform-updates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-updates.d.ts","sourceRoot":"","sources":["../src/platform-updates.ts"],"names":[],"mappings":"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"}

package/dist/platform-updates.js

@@ -0,0 +1,238 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * In-product Caelo updates (epic #696): the vocabulary the admin (Settings →
+ * Updates, the `platform_updates.*` ops), the upgrader job and the Phase 5
+ * scheduler share. One module so the timeline the page renders, the states
+ * the job writes and the database CHECK constraints (migration 0267) agree.
+ */
+import { z } from "zod";
+/** Every state of an update request (`platform_update_requests.status`). */
+export const PLATFORM_UPDATE_STATUSES = [
+    "pending",
+    "running",
+    "succeeded",
+    "rolled_back",
+    "failed",
+    "refused",
+    "needs_cloud_shell",
+    "cancelled",
+];
+/** States in which a request is still in flight (at most one at a time). */
+export const ACTIVE_UPDATE_STATUSES = ["pending", "running"];
+/** Whether `status` is an end state. */
+export function isFinishedUpdateStatus(status) {
+    return !ACTIVE_UPDATE_STATUSES.includes(status);
+}
+/**
+ * The phases of an upgrader run, in order (`platform_update_events.phase`).
+ * `rollback` only appears when a roll had to be undone.
+ */
+export const PLATFORM_UPDATE_PHASES = [
+    "queued",
+    "start",
+    "verify",
+    "assess",
+    "backup",
+    "health-baseline",
+    "migrations",
+    "roll",
+    "health",
+    "rollback",
+    "record",
+    "self-update",
+    "finish",
+];
+/** Severity of one timeline line. */
+export const PLATFORM_UPDATE_EVENT_LEVELS = ["info", "success", "warn", "error"];
+/** Who started a request: the Owner's click, or the Phase 5 scheduler. */
+export const PLATFORM_UPDATE_TRIGGERS = ["manual", "auto"];
+/**
+ * A run still `running` this long after it started died (the upgrader job's
+ * task timeout is 60 minutes). The next job run, and the next install
+ * request, end it as failed — so a crashed run never blocks updates.
+ */
+export const PLATFORM_UPDATE_STALE_MINUTES = 90;
+/**
+ * Why a stale run was ended (shown on its timeline). Provider-neutral: the
+ * same text ends a dead Google Cloud job run and a dead self-hosted agent
+ * run, and Settings → Updates shows each install its own way to upgrade by
+ * hand (Cloud Shell there, the upgrade command on the server here).
+ */
+export const PLATFORM_UPDATE_STALE_REASON = "The upgrader stopped before it finished (its run timed out or crashed). The previous release may still serve, or the new one may be partly rolled out: open the site, and if it misbehaves run the upgrade by hand once — Settings → Updates shows how for this install.";
+/** Longest an event message may be (DB CHECK). */
+export const PLATFORM_UPDATE_EVENT_MAX = 4000;
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+/** A SemVer release version without a leading `v` (`0.11.0`, `0.11.0-rc.1`). */
+export const releaseVersionSchema = z
+    .string()
+    .regex(SEMVER, "expected a release version like 0.11.0 (no leading v)");
+/**
+ * Classify the step from the installed release to a newer one.
+ *
+ * @returns null when `to` is not newer than `from` or either is not SemVer.
+ * @example updateKind("0.10.45", "0.10.46") // → "patch"
+ */
+export function updateKind(from, to) {
+    const a = SEMVER.exec(from);
+    const b = SEMVER.exec(to);
+    if (!a || !b)
+        return null;
+    const [fa, fb, fc] = [Number(a[1]), Number(a[2]), Number(a[3])];
+    const [ta, tb, tc] = [Number(b[1]), Number(b[2]), Number(b[3])];
+    if (ta !== fa)
+        return ta > fa ? "major" : null;
+    if (tb !== fb)
+        return tb > fb ? "minor" : null;
+    if (tc !== fc)
+        return tc > fc ? "patch" : null;
+    // Same X.Y.Z: a stable release over its own pre-release, or a later
+    // pre-release (rc.1 → rc.2), is a step.
+    if (a[4] === undefined)
+        return null;
+    if (b[4] === undefined)
+        return "patch";
+    return comparePrerelease(b[4], a[4]) > 0 ? "patch" : null;
+}
+/** SemVer §11 precedence of two pre-release identifier lists. */
+function comparePrerelease(x, y) {
+    const xs = x.split(".");
+    const ys = y.split(".");
+    for (let i = 0; i < Math.max(xs.length, ys.length); i++) {
+        const p = xs[i];
+        const q = ys[i];
+        if (p === undefined)
+            return -1;
+        if (q === undefined)
+            return 1;
+        const pn = /^\d+$/.test(p);
+        const qn = /^\d+$/.test(q);
+        if (pn && qn && Number(p) !== Number(q))
+            return Number(p) - Number(q);
+        if (pn !== qn)
+            return pn ? -1 : 1;
+        if (p !== q)
+            return p < q ? -1 : 1;
+    }
+    return 0;
+}
+/** The automatic-update modes. */
+export const UPDATE_POLICY_MODES = ["off", "notify", "auto"];
+/** Release channels a policy may follow (only `stable` installs automatically). */
+export const UPDATE_POLICY_CHANNELS = ["stable", "rc", "beta", "alpha"];
+const WALL_CLOCK = /^([01]\d|2[0-3]):[0-5]\d$/;
+/** Whether `tz` is an IANA time zone this runtime knows. */
+export function isKnownTimeZone(tz) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The Owner's automatic-update policy (`platform_update_policy`), as the
+ * ops read and write it. Major releases have no toggle: they are never
+ * installed automatically before 1.0.
+ */
+export const updatePolicySchema = z
+    .object({
+    mode: z.enum(UPDATE_POLICY_MODES),
+    autoSecurity: z.boolean(),
+    autoPatch: z.boolean(),
+    autoMinor: z.boolean(),
+    channel: z.enum(UPDATE_POLICY_CHANNELS),
+    /** `HH:MM` local time in `windowTimezone`, or null with windowEnd null = any time. */
+    windowStart: z.string().regex(WALL_CLOCK, "expected HH:MM").nullable(),
+    windowEnd: z.string().regex(WALL_CLOCK, "expected HH:MM").nullable(),
+    windowTimezone: z.string().min(1).max(64).refine(isKnownTimeZone, "unknown time zone"),
+    soakHours: z.number().int().min(0).max(720),
+})
+    .strict()
+    .refine((p) => (p.windowStart === null) === (p.windowEnd === null), {
+    message: "set both ends of the maintenance window, or neither",
+})
+    .refine((p) => p.mode !== "auto" || p.channel === "stable", {
+    message: "automatic installs follow the stable channel only",
+});
+/** Minutes since local midnight of `at` in `timeZone`. */
+function localMinutes(at, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-GB", {
+        timeZone,
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+    }).formatToParts(at);
+    const n = (t) => Number(parts.find((p) => p.type === t)?.value ?? "0");
+    return n("hour") * 60 + n("minute");
+}
+const toMinutes = (hhmm) => Number(hhmm.slice(0, 2)) * 60 + Number(hhmm.slice(3, 5));
+/**
+ * Whether `at` falls inside the policy's maintenance window. A window whose
+ * end is before its start spans midnight (`22:00`–`04:00`).
+ */
+export function inMaintenanceWindow(policy, at) {
+    if (policy.windowStart === null || policy.windowEnd === null)
+        return true;
+    const now = localMinutes(at, policy.windowTimezone);
+    const start = toMinutes(policy.windowStart);
+    const end = toMinutes(policy.windowEnd);
+    if (start === end)
+        return true;
+    return start < end ? now >= start && now < end : now >= start || now < end;
+}
+/**
+ * Whether the policy lets the upgrader install `candidate` unattended at
+ * `at` — the job's check for `trigger = 'auto'` requests (the scheduler
+ * applies the soak period before it ever queues one).
+ *
+ * @returns null when allowed, else the reason in plain words
+ */
+export function autoInstallRefusal(policy, candidate, at) {
+    if (policy.mode !== "auto")
+        return "automatic installs are switched off in the update policy";
+    if (policy.paused)
+        return "automatic installs are paused after a failed install";
+    if (candidate.channel !== "stable")
+        return "only stable releases install automatically";
+    if (candidate.contractMigrations) {
+        return "the release carries destructive database changes; the Owner installs it by hand";
+    }
+    if (candidate.kind === "major")
+        return "major releases never install automatically";
+    const allowed = (candidate.security && policy.autoSecurity) ||
+        (candidate.kind === "patch" && policy.autoPatch) ||
+        (candidate.kind === "minor" && policy.autoMinor);
+    if (!allowed) {
+        return `the policy does not install ${candidate.security ? "security fixes or " : ""}${candidate.kind} releases automatically`;
+    }
+    if (!inMaintenanceWindow(policy, at))
+        return "outside the maintenance window";
+    return null;
+}
+/**
+ * How long a verified Google sign-in authorizes one guarded action. Long
+ * enough to read the confirmation dialog, short enough that an unattended
+ * browser is useless soon after.
+ */
+export const STEP_UP_MAX_AGE_SECONDS = 600;
+/** What a step-up is for (`step_up_challenges.purpose`). */
+export const STEP_UP_PURPOSES = ["platform_update", "update_policy", "step_up_client"];
+/**
+ * Self-hosted installs (#696 Phase 4c): the host agent (`caelo-agent`, a
+ * systemd timer on the install's host) polls for update requests this
+ * often and writes a heartbeat each time it looks.
+ */
+export const PLATFORM_UPDATE_AGENT_POLL_SECONDS = 60;
+/**
+ * The admin offers "Install update" on a self-hosted install only while the
+ * agent's last heartbeat is younger than this (five missed polls): a request
+ * nobody picks up would just sit there.
+ */
+export const PLATFORM_UPDATE_AGENT_FRESH_SECONDS = 300;
+/** Whether an agent last seen at `lastSeenAt` counts as running at `now`. */
+export function agentCheckedInRecently(lastSeenAt, now) {
+    const seen = new Date(lastSeenAt).getTime();
+    return (Number.isFinite(seen) && now.getTime() - seen <= PLATFORM_UPDATE_AGENT_FRESH_SECONDS * 1000);
+}
+//# sourceMappingURL=platform-updates.js.map

package/dist/platform-updates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-updates.js","sourceRoot":"","sources":["../src/platform-updates.ts"],"names":[],"mappings":"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"}

package/dist/subagents.d.ts

@@ -159,8 +159,8 @@ export declare const rebuildReturnShape: z.ZodObject<{
         slug: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
             rebuilt: "rebuilt";
-            skipped: "skipped";
             failed: "failed";
+            skipped: "skipped";
             needs_escalation: "needs_escalation";
         }>;
         notes: z.ZodOptional<z.ZodString>;

package/dist/version.d.ts

@@ -19,7 +19,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export declare const CAELO_VERSION = "0.10.46";
+export declare const CAELO_VERSION = "0.10.48";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import
@@ -31,7 +31,7 @@ export declare const CAELO_VERSION = "0.10.46";
  *
  * @deprecated use CAELO_VERSION
  */
-export declare const CALEO_VERSION = "0.10.46";
+export declare const CALEO_VERSION = "0.10.48";
 /**
  * Parsed shape — major/minor/patch + optional pre-release tag.
  * Stable interface for callers that need to feature-gate (rare —

package/dist/version.js

@@ -20,7 +20,7 @@
  * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
  * follow standard SemVer.
  */
-export const CAELO_VERSION = "0.10.46";
+export const CAELO_VERSION = "0.10.48";
 /**
  * Deprecated alias for back-compat — early P17 work spelled this
  * `CALEO_VERSION` (typo of "Caelo"). New code should import

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caelo-cms/shared",
-  "version": "0.10.46",
+  "version": "0.10.48",
   "private": false,
   "license": "MPL-2.0",
   "description": "Shared Zod schemas + types + the two-pass HTML composer used by every Caelo CMS workspace package. Stable enough for plugin authors and embedders to depend on directly.",

package/src/ai-tools.ts

@@ -174,8 +174,9 @@ export type LoadSkillToolInput = z.infer<typeof loadSkillToolInput>;
 export const addModuleToolInput = z
   .object({
     target: z.enum(["page", "layout", "template"]),
-    /** Slug or uuid of the page / layout / template. Resolved server-side. */
-    targetRef: z.string().min(1).max(200),
+    /** Page: id or URL path. Layout / template: slug or id. Resolved server-side. */
+    // A page path can run to ~390 chars (6 levels x 64-char slugs).
+    targetRef: z.string().min(1).max(500),
     blockName: z.string().min(1).max(80),
     position: positionInputSchema,
     /** Reuse an existing module by id (any target). Mutually exclusive with the
@@ -636,7 +637,8 @@ export const createTemplateToolInput = z
 export const removeModuleFromToolInput = z
   .object({
     target: z.enum(["page", "layout"]),
-    targetRef: z.string().min(1).max(200),
+    // A page path can run to ~390 chars (6 levels x 64-char slugs).
+    targetRef: z.string().min(1).max(500),
     moduleId: z.string().uuid(),
   })
   .strict();
@@ -713,6 +715,9 @@ export const duplicatePageToolInput = z
     newName: z.string().min(1).max(256).optional(),
     newTitle: z.string().min(1).max(256).optional(),
     targetTemplateId: z.string().uuid().optional(),
+    /** Where the copy sits: a parent page id, or null for the top level.
+     *  Omitted = next to the source (same parent). */
+    newParentPageId: z.string().uuid().nullable().optional(),
   })
   .strict();
 

package/src/build-page.ts

@@ -195,6 +195,12 @@ export const buildPageTargetSchema = z
     name: z.string().min(1).max(256).optional(),
     templateId: z.string().uuid().optional(),
     status: pageStatusSchema.optional(),
+    /**
+     * 0263 — create the page UNDER this parent page; its URL becomes
+     * "<parent's path>/<slug>". Create mode only (an existing page moves
+     * with `pages.move_many`).
+     */
+    parentPageId: z.string().uuid().optional(),
     /**
      * Migration linkage (issue #278 flow): the `import_pages` row this
      * page rebuilds. The op stamps `import_pages.accepted_page_id` with
@@ -208,9 +214,9 @@ export const buildPageTargetSchema = z
   })
   .strict()
   .superRefine((page, ctx) => {
-    const createKeys = (["slug", "title", "name", "templateId", "status"] as const).filter(
-      (k) => page[k] !== undefined,
-    );
+    const createKeys = (
+      ["slug", "title", "name", "templateId", "status", "parentPageId"] as const
+    ).filter((k) => page[k] !== undefined);
     if (page.pageId !== undefined) {
       if (createKeys.length > 0) {
         ctx.addIssue({

package/src/cloud-shell-install.test.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { cloudShellInstallUrl } from "./cloud-shell-install.js";
+
+describe("cloudShellInstallUrl", () => {
+  it("pins the release branch of the install repo and the provider's tutorial", () => {
+    expect(cloudShellInstallUrl("0.10.47", "gcp")).toBe(
+      "https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/caelo-cms/install&cloudshell_git_branch=release-v0.10.47&cloudshell_tutorial=gcp.md",
+    );
+    expect(cloudShellInstallUrl("v1.2.3", "gcp-firebase")).toContain(
+      "cloudshell_git_branch=release-v1.2.3&cloudshell_tutorial=gcp-firebase.md",
+    );
+  });
+
+  it("refuses pre-releases and garbage: they have no pinned branch", () => {
+    expect(() => cloudShellInstallUrl("0.11.0-rc.1", "gcp")).toThrow(/only stable releases/);
+    expect(() => cloudShellInstallUrl("latest", "gcp")).toThrow();
+  });
+});

package/src/cloud-shell-install.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The "Open in Google Cloud Shell" install link (epic #696, Phase 3).
+ *
+ * The link opens github.com/caelo-cms/install on the `release-v<version>`
+ * branch that repository's track-release workflow creates for every stable
+ * release (and never moves), with the provider's walkthrough tutorial. Its
+ * `run.sh` pins and verifies exactly that release of the provisioner. One
+ * builder for every place that shows the link — README, docs, and the
+ * admin's "run this release in Cloud Shell" hint — so they can't drift.
+ */
+
+/** The repository the Cloud Shell button clones. */
+export const CLOUD_SHELL_INSTALL_REPO = "https://github.com/caelo-cms/install";
+
+/** The button image Google publishes for "Open in Cloud Shell" links. */
+export const CLOUD_SHELL_BUTTON_IMAGE = "https://gstatic.com/cloudssh/images/open-btn.svg";
+
+/** Providers the Cloud Shell install covers (one tutorial each). */
+export type CloudShellProvider = "gcp" | "gcp-firebase";
+
+const STABLE = /^v?(\d+\.\d+\.\d+)$/;
+
+/**
+ * The Cloud Shell install link for a stable release.
+ *
+ * @throws for a pre-release or non-SemVer version — only stable releases
+ *   get a `release-v<version>` branch in the install repository
+ *
+ * @example cloudShellInstallUrl("0.10.47", "gcp")
+ *   // → "https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/caelo-cms/install&cloudshell_git_branch=release-v0.10.47&cloudshell_tutorial=gcp.md"
+ */
+export function cloudShellInstallUrl(version: string, provider: CloudShellProvider): string {
+  const m = STABLE.exec(version);
+  if (!m) {
+    throw new Error(
+      `no Cloud Shell install link for "${version}": only stable releases are pinned in ${CLOUD_SHELL_INSTALL_REPO}`,
+    );
+  }
+  return [
+    "https://shell.cloud.google.com/cloudshell/editor",
+    `?cloudshell_git_repo=${CLOUD_SHELL_INSTALL_REPO}`,
+    `&cloudshell_git_branch=release-v${m[1]}`,
+    `&cloudshell_tutorial=${provider}.md`,
+  ].join("");
+}

package/src/content.ts

@@ -563,6 +563,33 @@ export const pageCreateSchema = z
      * left the first page unpublished.)
      */
     status: pageStatusSchema.optional(),
+    /**
+     * 0263 — nested page URLs: create the page under this parent; its URL
+     * becomes "<parent's path>/<slug>". Omit (or null) for a top-level page.
+     */
+    parentPageId: z.string().uuid().nullable().optional(),
+  })
+  .strict();
+
+/**
+ * 0263 — `pages.move_many`: reparent pages (their whole subtrees move
+ * with them) and optionally rename them in the same step.
+ */
+export const pageMoveSchema = z
+  .object({
+    pageId: z.string().uuid(),
+    /** The new parent page, or null for the top level. */
+    parentPageId: z.string().uuid().nullable(),
+    /** Rename while moving — required when the target URL is taken. */
+    newSlug: slugSchema.optional(),
+  })
+  .strict();
+
+export const pagesMoveManySchema = z
+  .object({
+    moves: z.array(pageMoveSchema).min(1).max(200),
+    /** `'skip'` suppresses the 301s from the old URLs (operator asked for 404s). */
+    redirectFromOld: z.enum(["auto", "skip"]).default("auto"),
   })
   .strict();