@caelo-cms/shared 0.10.48 → 0.10.50

package/dist/redirect-emit-gcp.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The redirect plan as GCP URL-map path rules (provider `gcp`: GCS backend
+ * bucket behind the global external Application Load Balancer, #587).
+ *
+ * Why URL-map rules: the load balancer answers a `urlRedirect` path rule
+ * itself, at the edge, before the backend bucket is asked — no compute on
+ * the static request path (CLAUDE.md §11.B Tier 1). The alternatives do not
+ * exist on this stack: GCS has no per-object redirects, and the URL map's
+ * custom error responses can only point at a backend bucket, so a bucket
+ * 404 cannot be handed to the gateway for a `redirects.lookup`.
+ *
+ * Limits (https://cloud.google.com/load-balancing/docs/quotas, "URL maps",
+ * fixed — they cannot be raised): per path matcher at most 1,000 path
+ * rules and 1,000 predicates, where every path of a path rule is one
+ * predicate. Every host has exactly one path matcher, so the site host's
+ * redirects share that budget with its own routing rules (`/api/*`). A plan
+ * that does not fit is refused with {@link GcpUrlMapBudgetError} BEFORE
+ * anything changes — the load balancer keeps the previous rules, and the
+ * error names the counts and the ways out. Dropping redirects silently
+ * would turn linked URLs into 404s without anyone noticing. Going past the
+ * quota is tracked in #751.
+ *
+ * Rules this module owns are recognised by their `urlRedirect` (the stack's
+ * own rules route to a service), so re-applying a plan replaces exactly the
+ * previous plan's rules and keeps everything else in the path matcher.
+ */
+import type { RedirectPlan } from "./redirect-plan.js";
+/** Path rules per path matcher (URL map quota, global external ALB). */
+export declare const GCP_URL_MAP_MAX_PATH_RULES = 1000;
+/** Predicates (paths across all path rules) per path matcher. */
+export declare const GCP_URL_MAP_MAX_PREDICATES = 1000;
+export type GcpRedirectResponseCode = "MOVED_PERMANENTLY_DEFAULT" | "FOUND" | "SEE_OTHER" | "TEMPORARY_REDIRECT" | "PERMANENT_REDIRECT";
+/** A path rule of a URL map path matcher (Compute REST shape). */
+export interface GcpPathRule {
+    readonly paths: readonly string[];
+    readonly service?: string;
+    readonly urlRedirect?: {
+        readonly pathRedirect?: string;
+        readonly redirectResponseCode?: GcpRedirectResponseCode;
+        readonly stripQuery?: boolean;
+        readonly [key: string]: unknown;
+    };
+    readonly [key: string]: unknown;
+}
+/** A URL map path matcher (Compute REST shape; other fields kept as-is). */
+export interface GcpPathMatcher {
+    readonly name: string;
+    readonly pathRules?: readonly GcpPathRule[];
+    readonly routeRules?: readonly unknown[];
+    readonly [key: string]: unknown;
+}
+/** The plan does not fit the path matcher's quota; nothing was changed. */
+export declare class GcpUrlMapBudgetError extends Error {
+    readonly redirectCount: number;
+    readonly predicatesNeeded: number;
+    readonly rulesNeeded: number;
+    constructor(redirectCount: number, predicatesNeeded: number, rulesNeeded: number);
+}
+/**
+ * One `urlRedirect` path rule per planned redirect. 410 entries have no
+ * URL-map equivalent and answer the bucket's 404.
+ *
+ * @throws when a planned redirect cannot be expressed as a URL-map rule
+ *         (a `*` in the from path would turn it into a wildcard; a target
+ *         with a query or fragment cannot be a `pathRedirect`).
+ */
+export declare function gcpRedirectPathRules(plan: RedirectPlan): GcpPathRule[];
+/** Whether a path rule is one a redirect plan wrote (see module comment). */
+export declare function isGcpRedirectRule(rule: GcpPathRule): boolean;
+/**
+ * The path matcher with its redirect rules replaced by the plan's. Rules
+ * that are not redirects stay first, in their order — `/api/*` keeps
+ * routing to the gateway. Path rules match the longest path, so the order
+ * between them does not change routing.
+ *
+ * @throws {GcpUrlMapBudgetError} when the result exceeds the quota.
+ */
+export declare function withGcpRedirects(matcher: GcpPathMatcher, plan: RedirectPlan): GcpPathMatcher;
+/**
+ * Check a plan against the budget a path matcher with `baseRules` leaves,
+ * without a URL map at hand (Stage runs it so an over-quota redirect set
+ * is reported before Confirm-publish).
+ *
+ * @throws {GcpUrlMapBudgetError} when the plan does not fit.
+ */
+export declare function assertGcpRedirectBudget(plan: RedirectPlan, baseRules: readonly GcpPathRule[]): void;
+/** The site's own routing in the `public` path matcher (stack + budget). */
+export declare const GCP_PUBLIC_BASE_PATHS: readonly string[];
+//# sourceMappingURL=redirect-emit-gcp.d.ts.map

package/dist/redirect-emit-gcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect-emit-gcp.d.ts","sourceRoot":"","sources":["../src/redirect-emit-gcp.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAmB,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AAE5F,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAC/C,iEAAiE;AACjE,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAU/C,MAAM,MAAM,uBAAuB,GAC/B,2BAA2B,GAC3B,OAAO,GACP,WAAW,GACX,oBAAoB,GACpB,oBAAoB,CAAC;AAEzB,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,oBAAoB,CAAC,EAAE,uBAAuB,CAAC;QACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACjC,CAAC;IACF,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACzC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,2EAA2E;AAC3E,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM;gBAFnB,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM;CAO/B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,EAAE,CAEtE;AAwBD,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,YAAY,GAAG,cAAc,CAc5F;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,SAAS,WAAW,EAAE,GAChC,IAAI,CAEN;AAED,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAe,CAAC"}

package/dist/redirect-emit-gcp.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: MPL-2.0
+/** Path rules per path matcher (URL map quota, global external ALB). */
+export const GCP_URL_MAP_MAX_PATH_RULES = 1000;
+/** Predicates (paths across all path rules) per path matcher. */
+export const GCP_URL_MAP_MAX_PREDICATES = 1000;
+/** `urlRedirect.redirectResponseCode` per stored status. */
+const RESPONSE_CODE = {
+    301: "MOVED_PERMANENTLY_DEFAULT",
+    302: "FOUND",
+    307: "TEMPORARY_REDIRECT",
+    308: "PERMANENT_REDIRECT",
+};
+/** The plan does not fit the path matcher's quota; nothing was changed. */
+export class GcpUrlMapBudgetError extends Error {
+    redirectCount;
+    predicatesNeeded;
+    rulesNeeded;
+    constructor(redirectCount, predicatesNeeded, rulesNeeded) {
+        super(`The GCP load balancer serves at most ${GCP_URL_MAP_MAX_PREDICATES} redirect paths and ${GCP_URL_MAP_MAX_PATH_RULES} rules per site (a fixed URL-map quota); this site's ${redirectCount} redirect(s) need ${predicatesNeeded} paths and ${rulesNeeded} rules, counting the site's own routing. Nothing was published and the live redirects are unchanged. Next step: delete redirects nobody links to any more (find_redirects lists them, bulk_delete_redirects removes them) — every redirect whose old URL ends in '/' or not costs two paths, a file-like one ('/old.html') costs one — then publish again. Serving larger redirect sets on this provider is tracked in https://github.com/caelo-cms/caelo-cms/issues/751.`);
+        this.redirectCount = redirectCount;
+        this.predicatesNeeded = predicatesNeeded;
+        this.rulesNeeded = rulesNeeded;
+        this.name = "GcpUrlMapBudgetError";
+    }
+}
+/**
+ * One `urlRedirect` path rule per planned redirect. 410 entries have no
+ * URL-map equivalent and answer the bucket's 404.
+ *
+ * @throws when a planned redirect cannot be expressed as a URL-map rule
+ *         (a `*` in the from path would turn it into a wildcard; a target
+ *         with a query or fragment cannot be a `pathRedirect`).
+ */
+export function gcpRedirectPathRules(plan) {
+    return plan.redirects.map(toPathRule);
+}
+function toPathRule(r) {
+    if (r.matchPaths.some((p) => p.includes("*"))) {
+        throw new Error(`redirect-emit-gcp: the redirect for ${JSON.stringify(r.fromPath)} contains '*', which a GCP URL map reads as a wildcard. Percent-encode it ('%2A') with bulk_create_redirects (upsert), then publish again.`);
+    }
+    if (!r.preserveQuery) {
+        throw new Error(`redirect-emit-gcp: the redirect ${r.fromPath} → ${r.location} targets a URL with a query string or fragment, which a GCP URL-map redirect cannot carry. Point it at the page's path with bulk_create_redirects (upsert), then publish again.`);
+    }
+    return {
+        paths: [...r.matchPaths],
+        urlRedirect: {
+            pathRedirect: r.location,
+            redirectResponseCode: RESPONSE_CODE[r.statusCode],
+            // The visitor's query string rides along, like on every provider.
+            stripQuery: false,
+        },
+    };
+}
+/** Whether a path rule is one a redirect plan wrote (see module comment). */
+export function isGcpRedirectRule(rule) {
+    return rule.urlRedirect !== undefined && rule.service === undefined;
+}
+/**
+ * The path matcher with its redirect rules replaced by the plan's. Rules
+ * that are not redirects stay first, in their order — `/api/*` keeps
+ * routing to the gateway. Path rules match the longest path, so the order
+ * between them does not change routing.
+ *
+ * @throws {GcpUrlMapBudgetError} when the result exceeds the quota.
+ */
+export function withGcpRedirects(matcher, plan) {
+    if (matcher.routeRules && matcher.routeRules.length > 0) {
+        throw new Error(`redirect-emit-gcp: path matcher ${JSON.stringify(matcher.name)} uses routeRules; a path matcher holds either pathRules or routeRules, and Caelo's stack writes pathRules. The URL map was changed outside the stack — restore it with the installer, then publish again.`);
+    }
+    const kept = (matcher.pathRules ?? []).filter((r) => !isGcpRedirectRule(r));
+    const redirects = gcpRedirectPathRules(plan);
+    const pathRules = [...kept, ...redirects];
+    const predicates = pathRules.reduce((n, r) => n + r.paths.length, 0);
+    if (predicates > GCP_URL_MAP_MAX_PREDICATES || pathRules.length > GCP_URL_MAP_MAX_PATH_RULES) {
+        throw new GcpUrlMapBudgetError(redirects.length, predicates, pathRules.length);
+    }
+    return { ...matcher, pathRules };
+}
+/**
+ * Check a plan against the budget a path matcher with `baseRules` leaves,
+ * without a URL map at hand (Stage runs it so an over-quota redirect set
+ * is reported before Confirm-publish).
+ *
+ * @throws {GcpUrlMapBudgetError} when the plan does not fit.
+ */
+export function assertGcpRedirectBudget(plan, baseRules) {
+    withGcpRedirects({ name: "budget-check", pathRules: baseRules }, plan);
+}
+/** The site's own routing in the `public` path matcher (stack + budget). */
+export const GCP_PUBLIC_BASE_PATHS = ["/api/*"];
+//# sourceMappingURL=redirect-emit-gcp.js.map

package/dist/redirect-emit-gcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect-emit-gcp.js","sourceRoot":"","sources":["../src/redirect-emit-gcp.ts"],"names":[],"mappings":"AAAA,mCAAmC;AA+BnC,wEAAwE;AACxE,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAC/C,iEAAiE;AACjE,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAE/C,4DAA4D;AAC5D,MAAM,aAAa,GAAwD;IACzE,GAAG,EAAE,2BAA2B;IAChC,GAAG,EAAE,OAAO;IACZ,GAAG,EAAE,oBAAoB;IACzB,GAAG,EAAE,oBAAoB;CAC1B,CAAC;AA8BF,2EAA2E;AAC3E,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAElC;IACA;IACA;IAHX,YACW,aAAqB,EACrB,gBAAwB,EACxB,WAAmB;QAE5B,KAAK,CACH,wCAAwC,0BAA0B,uBAAuB,0BAA0B,wDAAwD,aAAa,qBAAqB,gBAAgB,cAAc,WAAW,2cAA2c,CAClsB,CAAC;QANO,kBAAa,GAAb,aAAa,CAAQ;QACrB,qBAAgB,GAAhB,gBAAgB,CAAQ;QACxB,gBAAW,GAAX,WAAW,CAAQ;QAK5B,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAkB;IACrD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,UAAU,CAAC,CAAkB;IACpC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,uCAAuC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,4IAA4I,CAC9M,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,mCAAmC,CAAC,CAAC,QAAQ,MAAM,CAAC,CAAC,QAAQ,iLAAiL,CAC/O,CAAC;IACJ,CAAC;IACD,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC;QACxB,WAAW,EAAE;YACX,YAAY,EAAE,CAAC,CAAC,QAAQ;YACxB,oBAAoB,EAAE,aAAa,CAAC,CAAC,CAAC,UAAU,CAAC;YACjD,kEAAkE;YAClE,UAAU,EAAE,KAAK;SAClB;KACF,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,OAAO,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC;AACtE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAuB,EAAE,IAAkB;IAC1E,IAAI,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,mCAAmC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,2MAA2M,CAC3Q,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,SAAS,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACrE,IAAI,UAAU,GAAG,0BAA0B,IAAI,SAAS,CAAC,MAAM,GAAG,0BAA0B,EAAE,CAAC;QAC7F,MAAM,IAAI,oBAAoB,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAkB,EAClB,SAAiC;IAEjC,gBAAgB,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,IAAI,CAAC,CAAC;AACzE,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,MAAM,qBAAqB,GAAsB,CAAC,QAAQ,CAAC,CAAC"}

package/dist/redirect-plan.d.ts

@@ -0,0 +1,69 @@
+/** The redirect statuses the redirects table stores (besides 410). */
+export type RedirectStatusCode = 301 | 302 | 307 | 308;
+/** A row of the redirects table, as the static generator dumps it. */
+export interface RedirectTableRow {
+    readonly fromPath: string;
+    readonly toPath: string;
+    readonly statusCode: number;
+}
+/** How the deploy target emits page URLs (`DeployTarget.pageUrlStyle`). */
+export type RedirectPageUrlStyle = "directory" | "no-extension";
+/** One redirect the serving layer answers. */
+export interface PlannedRedirect {
+    /** The stored from path without a trailing slash (`/` for the root). */
+    readonly fromPath: string;
+    /** Every request path this entry answers, exactly (`/old`, `/old/`). */
+    readonly matchPaths: readonly string[];
+    /** The Location header value (a same-site path, see module comment). */
+    readonly location: string;
+    readonly statusCode: RedirectStatusCode;
+    /** Append the request's query string to {@link location}. */
+    readonly preserveQuery: boolean;
+}
+/** One path the serving layer answers with 410 Gone (where it can). */
+export interface PlannedGone {
+    readonly fromPath: string;
+    readonly matchPaths: readonly string[];
+}
+/** Everything a serving layer needs to answer the redirects table. */
+export interface RedirectPlan {
+    readonly redirects: readonly PlannedRedirect[];
+    readonly gone: readonly PlannedGone[];
+    /** From paths left out because a build file serves them (#575). */
+    readonly shadowedByBuild: readonly string[];
+}
+/**
+ * Parse the generator's `_redirects` file (`<from> <to> <status>` per line,
+ * `#` comments). Throws on a malformed line — a rule silently dropped is a
+ * 404 on a URL someone links to.
+ *
+ * @example
+ *   parseRedirectsFile("# generated\n/old /new 301\n")
+ *   // → [{ fromPath: "/old", toPath: "/new", statusCode: 301 }]
+ */
+export declare function parseRedirectsFile(text: string): RedirectTableRow[];
+/**
+ * Serialise rows into the `_redirects` file format {@link parseRedirectsFile}
+ * reads (also the Netlify / Cloudflare Pages format).
+ */
+export declare function formatRedirectsFile(rows: readonly RedirectTableRow[]): string;
+/** Arguments of {@link buildRedirectPlan}. */
+export interface BuildRedirectPlanArgs {
+    readonly rows: readonly RedirectTableRow[];
+    readonly pageUrlStyle: RedirectPageUrlStyle;
+    /**
+     * Every file of the build, relative to the build root without a leading
+     * slash (`de/preise/index.html`). A from path one of them serves is left
+     * out of the plan.
+     */
+    readonly servedFiles: ReadonlySet<string>;
+}
+/**
+ * Build the redirect plan every provider serves (see the module comment for
+ * the semantics). Pure and deterministic: entries keep the rows' order.
+ * Throws with an actionable message on rows no edge layer can serve
+ * correctly — a malformed path, an unsafe target, conflicting duplicates, a
+ * loop.
+ */
+export declare function buildRedirectPlan(args: BuildRedirectPlanArgs): RedirectPlan;
+//# sourceMappingURL=redirect-plan.d.ts.map

package/dist/redirect-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect-plan.d.ts","sourceRoot":"","sources":["../src/redirect-plan.ts"],"names":[],"mappings":"AAwCA,sEAAsE;AACtE,MAAM,MAAM,kBAAkB,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEvD,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,cAAc,CAAC;AAEhE,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IACtC,mEAAmE;IACnE,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAKD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAgBnE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAM7E;AAED,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC3C;AAQD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,YAAY,CA+B3E"}

package/dist/redirect-plan.js

@@ -0,0 +1,218 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The redirect plan: what every serving layer answers for the rows of the
+ * `redirects` table (#587).
+ *
+ * Each provider serves redirects through its own edge mechanism (Caddy
+ * `map` + `redir`, a GCP URL map, Firebase Hosting `config.redirects`, a
+ * CloudFront Function with a KeyValueStore, Front Door rules). They all
+ * consume this one plan, so a redirect means the same thing on every
+ * provider:
+ *
+ * - **Exact paths.** A row matches its `from` path exactly (case-sensitive)
+ *   and the same path with a trailing slash — in the directory page style
+ *   `/old/` is the URL people link to. A from path whose last segment
+ *   looks like a file (`/old.html`) matches only as written.
+ * - **The build wins.** A row whose from path a file of the build serves
+ *   is left out (#575): a live page always beats a recorded redirect, as
+ *   in the admin's 404 fallback (`redirects.lookup`). The edge layers
+ *   evaluate redirects BEFORE static files, so without this a slug moved
+ *   back to its old path would be shadowed (or loop with the reverse row).
+ * - **Chains collapse.** `/a → /b` plus `/b → /c` serves `/a → /c` in one
+ *   hop; crawlers follow few hops and every hop costs a round-trip. A hop
+ *   is followed only through rows that are themselves in the plan. The
+ *   collapsed status is permanent only when every hop is, and preserves
+ *   the method (307/308) only when every hop does.
+ * - **Loops fail the build.** A cycle can only ever answer "too many
+ *   redirects"; the error names it.
+ * - **Location.** In the directory style a page's canonical URL ends in
+ *   `/`; the Location points there directly (the host would otherwise add
+ *   a second hop). The visitor's query string is carried over unless the
+ *   target has its own query or fragment.
+ * - **410.** Rows with status 410 become `gone` entries. Layers that can
+ *   answer a bare status (Caddy, CloudFront) send 410; the others answer
+ *   the 404 a path without a file gets anyway.
+ */
+import { redirectTargetIssue } from "./redirect-target.js";
+import { trimTrailingSlashes } from "./url.js";
+const REDIRECT_STATUSES = new Set([301, 302, 307, 308]);
+const GONE_STATUS = 410;
+/**
+ * Parse the generator's `_redirects` file (`<from> <to> <status>` per line,
+ * `#` comments). Throws on a malformed line — a rule silently dropped is a
+ * 404 on a URL someone links to.
+ *
+ * @example
+ *   parseRedirectsFile("# generated\n/old /new 301\n")
+ *   // → [{ fromPath: "/old", toPath: "/new", statusCode: 301 }]
+ */
+export function parseRedirectsFile(text) {
+    const rows = [];
+    for (const [index, raw] of text.split("\n").entries()) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        const parts = line.split(" ");
+        const [fromPath, toPath, status] = parts;
+        const statusCode = Number(status);
+        if (parts.length !== 3 || !fromPath || !toPath || !Number.isInteger(statusCode)) {
+            throw new Error(`redirect-plan: _redirects line ${index + 1} is not "<from> <to> <status>": ${JSON.stringify(raw)}. The static generator writes this file from the redirects table — fix the row there (find_redirects / bulk_create_redirects) and rebuild.`);
+        }
+        rows.push({ fromPath, toPath, statusCode });
+    }
+    return rows;
+}
+/**
+ * Serialise rows into the `_redirects` file format {@link parseRedirectsFile}
+ * reads (also the Netlify / Cloudflare Pages format).
+ */
+export function formatRedirectsFile(rows) {
+    return [
+        "# Auto-generated by Caelo static-generator. Do not edit by hand.",
+        ...rows.map((r) => `${r.fromPath} ${r.toPath} ${r.statusCode}`),
+        "",
+    ].join("\n");
+}
+/**
+ * Build the redirect plan every provider serves (see the module comment for
+ * the semantics). Pure and deterministic: entries keep the rows' order.
+ * Throws with an actionable message on rows no edge layer can serve
+ * correctly — a malformed path, an unsafe target, conflicting duplicates, a
+ * loop.
+ */
+export function buildRedirectPlan(args) {
+    const rows = normaliseRows(args.rows);
+    const shadowedByBuild = [];
+    const live = new Map();
+    for (const row of rows) {
+        if (servedByBuild(row.bare, args.servedFiles)) {
+            shadowedByBuild.push(row.bare);
+            continue;
+        }
+        live.set(row.bare, row);
+    }
+    const redirects = [];
+    const gone = [];
+    for (const row of live.values()) {
+        const matchPaths = matchPathsFor(row.bare);
+        if (row.statusCode === GONE_STATUS) {
+            gone.push({ fromPath: row.bare, matchPaths });
+            continue;
+        }
+        const { target, statusCode } = collapseChain(row, live);
+        const location = locationFor(target, args.pageUrlStyle);
+        redirects.push({
+            fromPath: row.bare,
+            matchPaths,
+            location,
+            statusCode,
+            preserveQuery: !/[?#]/.test(location),
+        });
+    }
+    return { redirects, gone, shadowedByBuild };
+}
+function normaliseRows(rows) {
+    const byBare = new Map();
+    const out = [];
+    for (const row of rows) {
+        const { fromPath, toPath, statusCode } = row;
+        const shown = JSON.stringify(fromPath);
+        if (!fromPath.startsWith("/") || /[\s\p{Cc}]/u.test(fromPath)) {
+            throw new Error(`redirect-plan: from path ${shown} must start with '/' and contain no whitespace or control characters. Fix the row with bulk_create_redirects (upsert) or delete it with bulk_delete_redirects, then rebuild.`);
+        }
+        if (/[?#]/.test(fromPath)) {
+            throw new Error(`redirect-plan: from path ${shown} contains '?' or '#'. Redirects match the URL path only, so this row can never match. Re-create it for the path alone (e.g. '${pathBeforeQuery(fromPath)}') or delete it with bulk_delete_redirects, then rebuild.`);
+        }
+        if (statusCode !== GONE_STATUS && !REDIRECT_STATUSES.has(statusCode)) {
+            throw new Error(`redirect-plan: the redirect for ${shown} has status ${statusCode}; the redirects table allows 301, 302, 307, 308 or 410. Fix the row and rebuild.`);
+        }
+        if (statusCode !== GONE_STATUS) {
+            const targetIssue = redirectTargetIssue(toPath);
+            if (targetIssue)
+                throw new Error(`redirect-plan: the redirect for ${shown}: ${targetIssue}`);
+        }
+        const bare = stripTrailingSlash(fromPath);
+        const normalised = { bare, toPath, statusCode };
+        const existing = byBare.get(bare);
+        if (existing) {
+            if (existing.toPath === toPath && existing.statusCode === statusCode)
+                continue;
+            throw new Error(`redirect-plan: two redirects answer ${JSON.stringify(bare)} (with and without the trailing slash) differently: → ${existing.toPath} (${existing.statusCode}) and → ${toPath} (${statusCode}). Delete one with bulk_delete_redirects, then rebuild.`);
+        }
+        byBare.set(bare, normalised);
+        out.push(normalised);
+    }
+    return out;
+}
+/** Follow `row`'s target through the plan's own rows to the final hop. */
+function collapseChain(row, live) {
+    const visited = [row.bare];
+    let target = row.toPath;
+    let permanent = isPermanent(row.statusCode);
+    let preservesMethod = preservesRequestMethod(row.statusCode);
+    for (;;) {
+        // A target with its own query or fragment is a different URL than the
+        // path the next row matches; the chain ends there.
+        if (/[?#]/.test(target))
+            break;
+        const next = live.get(stripTrailingSlash(target));
+        if (!next || next.statusCode === GONE_STATUS)
+            break;
+        if (visited.includes(next.bare)) {
+            const cycle = [...visited.slice(visited.indexOf(next.bare)), next.bare].join(" → ");
+            throw new Error(`redirect-plan: the redirects ${cycle} form a loop, which browsers answer with "too many redirects". Delete the row that should no longer apply with bulk_delete_redirects (find_redirects lists them), then rebuild.`);
+        }
+        visited.push(next.bare);
+        permanent &&= isPermanent(next.statusCode);
+        preservesMethod &&= preservesRequestMethod(next.statusCode);
+        target = next.toPath;
+    }
+    return { target, statusCode: combinedStatus(permanent, preservesMethod) };
+}
+function isPermanent(status) {
+    return status === 301 || status === 308;
+}
+function preservesRequestMethod(status) {
+    return status === 307 || status === 308;
+}
+function combinedStatus(permanent, preservesMethod) {
+    if (permanent)
+        return preservesMethod ? 308 : 301;
+    return preservesMethod ? 307 : 302;
+}
+function stripTrailingSlash(path) {
+    return path.length > 1 ? trimTrailingSlashes(path) || "/" : path;
+}
+/** The part of a stored path before its first `?` or `#` (`/` if empty). */
+function pathBeforeQuery(path) {
+    const cut = path.search(/[?#]/);
+    return (cut === -1 ? path : path.slice(0, cut)) || "/";
+}
+/** Whether the last path segment names a file (`/a/b.html`). */
+function looksLikeFile(path) {
+    return path.slice(path.lastIndexOf("/") + 1).includes(".");
+}
+function matchPathsFor(bare) {
+    if (bare === "/" || looksLikeFile(bare))
+        return [bare];
+    return [bare, `${bare}/`];
+}
+/** Does a file of the build answer `bare`? Hosts serve `/x` from the file
+ *  `x` and from the directory index `x/index.html`. */
+function servedByBuild(bare, servedFiles) {
+    if (bare === "/")
+        return servedFiles.has("index.html");
+    const rel = bare.slice(1);
+    return servedFiles.has(rel) || servedFiles.has(`${rel}/index.html`);
+}
+/** In the directory style, internal page paths end in "/"; files (anything
+ *  with an extension in its last segment) and URLs with a query or fragment
+ *  stay as they are. */
+function locationFor(toPath, pageUrlStyle) {
+    if (pageUrlStyle !== "directory" || toPath.endsWith("/"))
+        return toPath;
+    if (/[?#]/.test(toPath) || looksLikeFile(toPath))
+        return toPath;
+    return `${toPath}/`;
+}
+//# sourceMappingURL=redirect-plan.js.map

package/dist/redirect-plan.js.map

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

package/dist/release-manifest.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The release manifest's shape and where it lives (epic #696) — shared by
+ * the provisioning CLI / upgrader job, which verify its Sigstore signature
+ * with cosign before trusting it (provisioning release-manifest.ts), and
+ * the admin's auto-update scheduler, which only *reads* it to decide when
+ * to queue an install (the admin image ships no cosign; the job verifies).
+ *
+ * The artifact is one OCI manifest with two layers — the JSON manifest and
+ * its Sigstore bundle — pushed by `release.yml` on the release tag.
+ * {@link fetchReleaseArtifact} fetches both blobs and checks each against
+ * its content digest; it does NOT check the signature.
+ */
+import { z } from "zod";
+/** Release channels. Pre-release versions name theirs (`0.11.0-rc.1` → `rc`). */
+export declare const RELEASE_CHANNELS: readonly ["stable", "rc", "beta", "alpha"];
+export type ReleaseChannel = (typeof RELEASE_CHANNELS)[number];
+/** The services a release ships images for. */
+export declare const RELEASE_IMAGES: readonly ["admin", "gateway", "ops"];
+export type ReleaseImage = (typeof RELEASE_IMAGES)[number];
+/** A `sha256:<64 hex>` image / blob digest. */
+export declare const IMAGE_DIGEST: RegExp;
+/** Zod schema of `release-manifest.json` (manifestVersion 1). */
+export declare const ReleaseManifestSchema: z.ZodObject<{
+    manifestVersion: z.ZodLiteral<1>;
+    version: z.ZodString;
+    channel: z.ZodEnum<{
+        stable: "stable";
+        rc: "rc";
+        beta: "beta";
+        alpha: "alpha";
+    }>;
+    digests: z.ZodObject<{
+        admin: z.ZodString;
+        gateway: z.ZodString;
+        ops: z.ZodString;
+    }, z.core.$strip>;
+    minFromVersion: z.ZodString;
+    infraContractVersion: z.ZodNumber;
+    migrations: z.ZodObject<{
+        contract: z.ZodBoolean;
+        lastContractVersion: z.ZodNullable<z.ZodString>;
+        head: z.ZodString;
+    }, z.core.$strip>;
+    security: z.ZodBoolean;
+    advisories: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ReleaseManifest = z.infer<typeof ReleaseManifestSchema>;
+/** Registry the manifests are read from — the public AR mirror Cloud Run pulls from. */
+export declare const RELEASE_MANIFEST_REGISTRY = "europe-west1-docker.pkg.dev";
+/** Repository path of the manifest artifact inside {@link RELEASE_MANIFEST_REGISTRY}. */
+export declare const RELEASE_MANIFEST_REPOSITORY = "caelo-website/caelo-cms-images/release-manifest";
+/** OCI artifact type + layer media types of the pushed manifest. */
+export declare const RELEASE_MANIFEST_ARTIFACT_TYPE = "application/vnd.caelo.release-manifest.v1";
+export declare const RELEASE_MANIFEST_MEDIA_TYPE = "application/vnd.caelo.release-manifest.v1+json";
+export declare const SIGSTORE_BUNDLE_MEDIA_TYPE = "application/vnd.dev.sigstore.bundle.v0.3+json";
+/** Why fetching the artifact failed. */
+export type ReleaseArtifactErrorCode = "registry" | "artifact-shape" | "blob-digest";
+export type ReleaseArtifactResult = {
+    readonly ok: true;
+    readonly manifestBytes: Uint8Array;
+    readonly bundleBytes: Uint8Array;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: ReleaseArtifactErrorCode;
+        readonly message: string;
+    };
+};
+/** Where and how {@link fetchReleaseArtifact} reaches the registry. */
+export interface ReleaseArtifactDeps {
+    readonly fetch: (url: string, init?: RequestInit) => Promise<Response>;
+    /** Registry host + repository; default to the fixed public mirror. */
+    readonly registry?: string;
+    readonly repository?: string;
+}
+/**
+ * Fetch the release manifest artifact of `version` and both its layers,
+ * each checked against its content digest. Verifies NO signature: callers
+ * that act on the manifest verify the bundle (provisioning
+ * fetchVerifiedReleaseManifest); the admin's scheduler only plans with it.
+ *
+ * @param version - SemVer without a leading `v` (the caller validates it).
+ */
+export declare function fetchReleaseArtifact(version: string, deps: ReleaseArtifactDeps): Promise<ReleaseArtifactResult>;
+/**
+ * Parse manifest bytes against {@link ReleaseManifestSchema} and check they
+ * describe `version`.
+ *
+ * @returns the manifest, or a plain-words problem
+ */
+export declare function parseReleaseManifest(bytes: Uint8Array, version: string): {
+    readonly ok: true;
+    readonly manifest: ReleaseManifest;
+} | {
+    readonly ok: false;
+    readonly code: "schema" | "version-mismatch";
+    readonly message: string;
+};
+//# sourceMappingURL=release-manifest.d.ts.map

package/dist/release-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-manifest.d.ts","sourceRoot":"","sources":["../src/release-manifest.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,4CAA6C,CAAC;AAC3E,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,+CAA+C;AAC/C,eAAO,MAAM,cAAc,sCAAuC,CAAC;AACnE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,+CAA+C;AAC/C,eAAO,MAAM,YAAY,QAA0B,CAAC;AAOpD,iEAAiE;AACjE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;iBAuBhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AACvE,yFAAyF;AACzF,eAAO,MAAM,2BAA2B,oDAAoD,CAAC;AAE7F,oEAAoE;AACpE,eAAO,MAAM,8BAA8B,8CAA8C,CAAC;AAC1F,eAAO,MAAM,2BAA2B,mDAAmD,CAAC;AAC5F,eAAO,MAAM,0BAA0B,kDAAkD,CAAC;AAE1F,wCAAwC;AACxC,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAErF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAA;CAAE,GAC3F;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACvF,CAAC;AAEN,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvE,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAiBD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CA6DhC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,GAEb;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,kBAAkB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAuBjG"}