@caelo-cms/shared 0.10.53 → 0.10.57

package/src/platform-updates.ts

@@ -19,6 +19,12 @@ export const PLATFORM_UPDATE_STATUSES = [
   "refused",
   "needs_cloud_shell",
   "cancelled",
+  /**
+   * Asked the Owner to act (`needs_cloud_shell`), but the install has since
+   * moved past it: it runs the target release (or a newer one), or a newer
+   * request exists (#817, migration 0317). Shown in the history only.
+   */
+  "superseded",
 ] as const;
 export type PlatformUpdateStatusValue = (typeof PLATFORM_UPDATE_STATUSES)[number];
 
@@ -32,7 +38,9 @@ export function isFinishedUpdateStatus(status: PlatformUpdateStatusValue): boole
 
 /**
  * The phases of an upgrader run, in order (`platform_update_events.phase`).
- * `rollback` only appears when a roll had to be undone.
+ * `rollback` only appears when a roll had to be undone; `converge` only on
+ * the converge route (#819), where the install's cloud setup is brought to
+ * what the release expects before and around the roll.
  */
 export const PLATFORM_UPDATE_PHASES = [
   "queued",
@@ -40,6 +48,7 @@ export const PLATFORM_UPDATE_PHASES = [
   "verify",
   "assess",
   "backup",
+  "converge",
   "health-baseline",
   "migrations",
   "roll",
@@ -51,6 +60,22 @@ export const PLATFORM_UPDATE_PHASES = [
 ] as const;
 export type PlatformUpdatePhase = (typeof PLATFORM_UPDATE_PHASES)[number];
 
+/**
+ * Which in-cloud job installs a request (#819, `platform_update_requests.route`):
+ *
+ *   - `app_roll` — the upgrader job (its own narrow service account): new
+ *     images + expand-only migrations, nothing in the cloud setup changes;
+ *   - `converge` — the converge job, running as the install's existing
+ *     `caelo-provisioner` account: the same upgrade an Owner runs from a
+ *     terminal (backup, converge, roll, health check, rollback), for a
+ *     release that raises the infrastructure contract.
+ *
+ * The admin picks the route from the release manifest before the click;
+ * either job re-checks everything against the signed manifest.
+ */
+export const PLATFORM_UPDATE_ROUTES = ["app_roll", "converge"] as const;
+export type PlatformUpdateRoute = (typeof PLATFORM_UPDATE_ROUTES)[number];
+
 /** Severity of one timeline line. */
 export const PLATFORM_UPDATE_EVENT_LEVELS = ["info", "success", "warn", "error"] as const;
 export type PlatformUpdateEventLevel = (typeof PLATFORM_UPDATE_EVENT_LEVELS)[number];
@@ -128,8 +153,12 @@ function comparePrerelease(x: string, y: string): number {
   return 0;
 }
 
-/** The automatic-update modes. */
-export const UPDATE_POLICY_MODES = ["off", "notify", "auto"] as const;
+/**
+ * The automatic-update modes. There is no "off": security releases are
+ * always announced (maintainer decision on #862; migration 0301 moved
+ * stored `off` rows to `notify`).
+ */
+export const UPDATE_POLICY_MODES = ["notify", "auto"] as const;
 export type UpdatePolicyMode = (typeof UPDATE_POLICY_MODES)[number];
 
 /** Release channels a policy may follow (only `stable` installs automatically). */
@@ -158,6 +187,13 @@ export const updatePolicySchema = z
     autoSecurity: z.boolean(),
     autoPatch: z.boolean(),
     autoMinor: z.boolean(),
+    /**
+     * Releases that change the install's Google Cloud project (an
+     * infrastructure-contract bump) may install on their own. Stored and
+     * shown, but inert until those releases can run from Caelo (#819): the
+     * scheduler treats them as notify-only regardless (auto-update.ts).
+     */
+    autoConverge: 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(),

package/src/preview-compose-deferrals.test.ts

@@ -14,6 +14,7 @@
  */
 
 import { describe, expect, it } from "bun:test";
+import { Parser } from "htmlparser2";
 import { type ComposeDeferral, composePageWithLayout } from "./preview-compose.js";
 
 const LAYOUT = '<html><head></head><body><caelo-slot name="content">_</caelo-slot></body></html>';
@@ -141,4 +142,106 @@ describe("composer — withheld modules", () => {
     expect(html).not.toContain('onload="evil()"');
     expect(html).toContain("&quot;");
   });
+
+  it("prevents </template>, </style>, and </script> inside withheld modules from breaking out of the inert template", () => {
+    const breakout = {
+      ...VIDEO,
+      html: "<div></template><script>alert(1)</script></div>",
+      css: ".v{content:'</style></template><script>alert(2)</script>'}",
+      js: 'const x = "</script></template><script>alert(3)</script>";',
+    };
+    const { html } = composePageWithLayout({
+      templateHtml: TEMPLATE,
+      templateCss: "",
+      blocks: [{ blockName: "main", modules: [breakout] }],
+      layoutHtml: LAYOUT,
+      layoutCss: "",
+      layoutBlocks: [],
+      deferredModules: { [VIDEO.moduleId]: DEFERRAL },
+    });
+    // None of the module's scripts may end up outside the inert template.
+    expect(liveScripts(html).filter((s) => s.includes("alert"))).toEqual([]);
+    expect(html).toContain("&lt;/template><script>alert(1)</script></div>");
+  });
+
+  it("parks JS that could end its <script> as base64 carrying the exact bytes", () => {
+    // `0</script/.test(v)` is valid JS that any `<\/script` rewrite breaks,
+    // and `<!--` + `<script` would keep the browser from ending the element.
+    const js = "window.r = [0</script/.test('x'), '<!--<script>'];";
+    const { html } = composePageWithLayout({
+      templateHtml: TEMPLATE,
+      templateCss: "",
+      blocks: [{ blockName: "main", modules: [{ ...VIDEO, js }] }],
+      layoutHtml: LAYOUT,
+      layoutCss: "",
+      layoutBlocks: [],
+      deferredModules: { [VIDEO.moduleId]: DEFERRAL },
+    });
+    const m =
+      /<script type="text\/plain" data-caelo-deferred-script="[^"]+" data-caelo-encoding="base64">([^<]*)<\/script>/.exec(
+        html,
+      );
+    expect(m).not.toBeNull();
+    expect(Buffer.from(m?.[1] ?? "", "base64").toString("utf8")).toBe(js);
+  });
+
+  it("escapes </style in live module CSS so it cannot add markup to <head>", () => {
+    const { html } = composePageWithLayout({
+      templateHtml: TEMPLATE,
+      templateCss: "",
+      blocks: [
+        { blockName: "main", modules: [{ ...VIDEO, css: ".v{content:'</STYLE><meta x>'}" }] },
+      ],
+      layoutHtml: LAYOUT,
+      layoutCss: "",
+      layoutBlocks: [],
+    });
+    const head = html.slice(0, html.indexOf("</head>"));
+    expect(head).toContain(".v{content:'<\\/STYLE><meta x>'}");
+    expect(head.toLowerCase()).not.toContain("</style><meta");
+  });
+
+  it("keeps a balanced nested <template> inside a withheld module intact", () => {
+    const nested = { ...VIDEO, html: "<ul><template id=row><li>x</li></template></ul>" };
+    const { html } = composePageWithLayout({
+      templateHtml: TEMPLATE,
+      templateCss: "",
+      blocks: [{ blockName: "main", modules: [nested] }],
+      layoutHtml: LAYOUT,
+      layoutCss: "",
+      layoutBlocks: [],
+      deferredModules: { [VIDEO.moduleId]: DEFERRAL },
+    });
+    expect(html).toContain("<template id=row><li>x</li></template></ul></template></div>");
+  });
 });
+
+/**
+ * The text of every `<script>` a browser would run because it sits outside
+ * any `<template>` — tokenized like a browser (style / script bodies are
+ * raw text, so a `</template` inside them is not a tag).
+ */
+function liveScripts(html: string): string[] {
+  const scripts: string[] = [];
+  let templateDepth = 0;
+  let current: string | null = null;
+  const parser = new Parser({
+    onopentag(name) {
+      if (name === "template") templateDepth++;
+      if (name === "script" && templateDepth === 0) current = "";
+    },
+    ontext(text) {
+      if (current !== null) current += text;
+    },
+    onclosetag(name) {
+      if (name === "template") templateDepth--;
+      if (name === "script" && current !== null) {
+        scripts.push(current);
+        current = null;
+      }
+    },
+  });
+  parser.write(html);
+  parser.end();
+  return scripts;
+}

package/src/preview-compose.ts

@@ -28,6 +28,7 @@
 import { BASE_TECHNICAL_CSS } from "./base-css.js";
 import type { ModuleFieldKind } from "./content.js";
 import { NAV_FUNCTIONAL_CSS, NAV_TOGGLE_JS } from "./interactions.js";
+import { type LinkResolver, resolveLinkRefsInHtml } from "./link-refs.js";
 import {
   type NestedModuleResource,
   type NestedRenderFailure,
@@ -39,7 +40,9 @@ import {
   extractInnerOfTopLevelContentSlot,
   listSlotNames,
 } from "./preview-scanner.js";
+import { escapeStyleText, scriptNeedsEncoding, utf8ToBase64 } from "./raw-text-escape.js";
 import { stripCdataGuards } from "./strip-cdata.js";
+import { balanceTemplateCloses } from "./template-balance.js";
 import { renderTemplate, type TemplateField } from "./template-engine.js";
 import { renderThemeCss as renderThemeCssFromTokens } from "./theme-render.js";
 import type { ThemeDocument } from "./themes.js";
@@ -176,6 +179,15 @@ export interface ComposeInput {
    * `nested-renderer-unavailable` failure.
    */
   readonly nestedModules?: NestedRenderResolver;
+  /**
+   * Epic #724 — resolves internal references (`caelo:page/<id>`,
+   * `caelo:media/<id>`) for THIS page: in every placed and nested
+   * module and in nav-menu items. A broken reference becomes a
+   * `link-target-missing:<kind>/<id>` module failure; without a resolver
+   * every reference fails with `link-resolver-unavailable` (loud — a
+   * deploy refuses it).
+   */
+  readonly linkResolver?: LinkResolver;
 }
 
 /**
@@ -224,11 +236,11 @@ export function fontsHeadFragment(fonts: ComposeFonts | undefined): string | nul
   const links = fonts.preloads
     .map((href) => {
       const format = /\.(woff2?|ttf|otf)(?:[?#]|$)/.exec(href)?.[1];
-      return `<link rel="preload" as="font"${format ? ` type="font/${format}"` : ""} crossorigin href="${href}">`;
+      return `<link rel="preload" as="font"${format ? ` type="font/${format}"` : ""} crossorigin href="${escapeAttr(href)}">`;
     })
     .join("");
-  const style =
-    fonts.css.trim().length > 0 ? `<style data-source="fonts">${fonts.css}</style>` : "";
+  const safeCss = escapeStyleText(fonts.css);
+  const style = safeCss.trim().length > 0 ? `<style data-source="fonts">${safeCss}</style>` : "";
   const fragment = links + style;
   return fragment.length > 0 ? fragment : null;
 }
@@ -287,7 +299,9 @@ export function composePagePreview(input: ComposeInput): ComposeOutput {
       let baseHtml: string;
       if (navMenuItems !== null) {
         navRendered = true;
-        baseHtml = renderNavMenuHtml(navMenuItems);
+        const nav = renderNavMenuHtml(navMenuItems, input.linkResolver);
+        baseHtml = nav.html;
+        recordFailures(moduleFailures, block.blockName, m, nav.failures);
       } else {
         const rendered = renderModuleFields(m, input);
         baseHtml = rendered.html;
@@ -355,7 +369,7 @@ export function composePagePreview(input: ComposeInput): ComposeOutput {
   );
 
   if (allCss.length > 0) {
-    const styleTag = `<style data-source="modules">\n${allCss.join("\n")}\n</style>`;
+    const styleTag = `<style data-source="modules">\n${escapeStyleText(allCss.join("\n"))}\n</style>`;
     html = injectBefore(html, HEAD_CLOSE_RE, styleTag);
   }
   if (allJs.length > 0) {
@@ -423,8 +437,25 @@ function escapeText(s: string): string {
  * Render a nav-menu's typed items into HTML. Recursively handles
  * children for submenus. Plain `<nav><ul><li>` so site CSS can theme
  * it via the `caelo-nav-menu` class.
+ *
+ * Epic #724 — item hrefs may be internal references; they resolve
+ * through `resolver` like module content, and a broken one is returned
+ * as a failure attributed to the nav-menu module.
  */
-function renderNavMenuHtml(items: readonly unknown[]): string {
+function renderNavMenuHtml(
+  items: readonly unknown[],
+  resolver: LinkResolver | undefined,
+): { html: string; failures: NestedRenderFailure[] } {
+  const missing: string[] = [];
+  const renderNavItem = (item: NavMenuItem): string => {
+    const target = item.target === "_blank" ? ' target="_blank" rel="noopener"' : "";
+    const inner =
+      item.children && item.children.length > 0
+        ? `<ul>${item.children.map(renderNavItem).join("")}</ul>`
+        : "";
+    const href = resolveLinkRefsInHtml(item.href, resolver, missing);
+    return `<li><a href="${escapeAttr(href)}"${target}>${escapeText(item.label)}</a>${inner}</li>`;
+  };
   const safeItems = items.filter((it): it is NavMenuItem => {
     if (!it || typeof it !== "object") return false;
     const o = it as { label?: unknown; href?: unknown };
@@ -437,15 +468,8 @@ function renderNavMenuHtml(items: readonly unknown[]): string {
     '<button type="button" class="caelo-nav-toggle" aria-expanded="false" aria-label="Menu">' +
     '<span class="caelo-nav-bar"></span><span class="caelo-nav-bar"></span><span class="caelo-nav-bar"></span>' +
     "</button>";
-  return `<nav class="caelo-nav-menu" data-nav-open="false">${toggle}<ul>${safeItems.map(renderNavItem).join("")}</ul></nav>`;
-}
-function renderNavItem(item: NavMenuItem): string {
-  const target = item.target === "_blank" ? ' target="_blank" rel="noopener"' : "";
-  const inner =
-    item.children && item.children.length > 0
-      ? `<ul>${item.children.map(renderNavItem).join("")}</ul>`
-      : "";
-  return `<li><a href="${escapeAttr(item.href)}"${target}>${escapeText(item.label)}</a>${inner}</li>`;
+  const html = `<nav class="caelo-nav-menu" data-nav-open="false">${toggle}<ul>${safeItems.map(renderNavItem).join("")}</ul></nav>`;
+  return { html, failures: missing.map((reason) => ({ field: "", reason })) };
 }
 
 /**
@@ -502,6 +526,7 @@ function renderModuleFields(
     readonly dataLists?: Readonly<Record<string, ReadonlyArray<Readonly<Record<string, string>>>>>;
     readonly dormantDataLists?: Readonly<Record<string, string>>;
     readonly nestedModules?: NestedRenderResolver;
+    readonly linkResolver?: LinkResolver;
   },
 ): RenderedModuleFields {
   // The substitution engine (renderTemplate) already unwraps CDATA
@@ -511,7 +536,15 @@ function renderModuleFields(
     Object.keys(input.dataLists ?? {}).length > 0 ||
     Object.keys(input.dormantDataLists ?? {}).length > 0;
   if (!m.fields && !m.contentValues && !input.theme && !hasLists) {
-    return { html: stripCdataGuards(m.html), failures: [], nestedModuleIds: [] };
+    // Still resolve references: pre-rendered (editor preview) and
+    // field-less chrome modules carry links in their raw HTML too.
+    const missing: string[] = [];
+    const html = resolveLinkRefsInHtml(stripCdataGuards(m.html), input.linkResolver, missing);
+    return {
+      html,
+      failures: missing.map((reason) => ({ field: "", reason })),
+      nestedModuleIds: [],
+    };
   }
   const fields: TemplateField[] = (m.fields ?? []).map((f) => ({
     name: f.name,
@@ -537,7 +570,12 @@ function renderModuleFields(
         values: m.contentValues ?? {},
       },
       input.nestedModules,
-      { themeAssets, dataLists: input.dataLists, dormantDataLists: input.dormantDataLists },
+      {
+        themeAssets,
+        dataLists: input.dataLists,
+        dormantDataLists: input.dormantDataLists,
+        linkResolver: input.linkResolver,
+      },
     );
     return { html: r.html, failures: r.failures, nestedModuleIds: [...r.touchedModuleIds] };
   }
@@ -548,6 +586,7 @@ function renderModuleFields(
     dataLists: input.dataLists,
     dormantDataLists: input.dormantDataLists,
     themeAssets,
+    linkResolver: input.linkResolver,
   });
   return {
     html: r.html,
@@ -637,22 +676,30 @@ function wrapDeferredModule(
 ): string {
   const attr = (v: string): string =>
     v.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+  // Inside the inert <template>, only an element's own end tag ends a
+  // <style> / <script>; a `</template` there is text. So CSS needs just
+  // its own close escaped, JS that could end its <script> ships base64
+  // (the runtime decodes it, see consent-manager runtime.ts), and the
+  // markup needs its unmatched `</template>` closes neutralized
+  // (balanced nested templates stay).
+  const safeHtml = balanceTemplateCloses(moduleHtml);
   const gated = [module, ...nestedModules];
   const css = gated
     .filter((g) => g.css.trim().length > 0)
-    .map((g) => `<style data-source="module">${g.css}</style>`)
+    .map((g) => `<style data-source="module">${escapeStyleText(g.css)}</style>`)
     .join("");
   const js = gated
     .filter((g) => g.js.trim().length > 0)
-    .map(
-      (g) =>
-        `<script type="text/plain" data-caelo-deferred-script="${attr(g.moduleId)}">${g.js}</script>`,
+    .map((g) =>
+      scriptNeedsEncoding(g.js)
+        ? `<script type="text/plain" data-caelo-deferred-script="${attr(g.moduleId)}" data-caelo-encoding="base64">${utf8ToBase64(g.js)}</script>`
+        : `<script type="text/plain" data-caelo-deferred-script="${attr(g.moduleId)}">${g.js}</script>`,
     )
     .join("");
   return [
     `<div data-caelo-deferred="${attr(deferral.pluginSlug)}" data-reason="${attr(deferral.reason)}" data-module="${attr(module.slug)}">`,
     `<div data-caelo-deferred-placeholder>${deferral.placeholderHtml}</div>`,
-    `<template data-caelo-deferred-content>${css}${moduleHtml}${js}</template>`,
+    `<template data-caelo-deferred-content>${css}${safeHtml}${js}</template>`,
     `</div>`,
   ].join("");
 }
@@ -775,7 +822,9 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
     let baseHtml: string;
     if (navMenuItems !== null) {
       navRendered = true;
-      baseHtml = renderNavMenuHtml(navMenuItems);
+      const nav = renderNavMenuHtml(navMenuItems, input.linkResolver);
+      baseHtml = nav.html;
+      recordFailures(moduleFailures, blockName, m, nav.failures);
     } else {
       const rendered = renderModuleFields(m, input);
       baseHtml = rendered.html;
@@ -902,7 +951,7 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeOut
     html = injectBefore(
       html,
       HEAD_CLOSE_RE,
-      `<style data-source="modules">\n${cssParts.join("\n")}\n</style>`,
+      `<style data-source="modules">\n${escapeStyleText(cssParts.join("\n"))}\n</style>`,
     );
   }
   if (jsParts.length > 0) {

package/src/raw-text-escape.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Escapes for CSS and JS that the composer places inside `<style>` /
+ * `<script>` elements. The HTML tokenizer ends those elements at the first
+ * `</style` / `</script` (ASCII case-insensitive), wherever it sits in the
+ * CSS or JS, so unescaped text there would end the element and put the
+ * rest into the document as markup — into `<head>` for CSS, which the
+ * structured-head invariant forbids.
+ */
+
+const STYLE_CLOSE_RE = /<\/style/gi;
+
+/**
+ * CSS safe to place between `<style>` and `</style>`. `<\/style` means
+ * what `</style` means wherever CSS can hold that sequence (strings,
+ * `url()`, comments — `\/` is an escaped `/`), so the CSS is unchanged.
+ */
+export function escapeStyleText(css: string): string {
+  return css.replace(STYLE_CLOSE_RE, (m) => `<\\${m.slice(1)}`);
+}
+
+/**
+ * Whether `js` cannot be placed verbatim inside a `<script>` element:
+ * a `</script` would end it, and a `<!--` switches the tokenizer into
+ * script-data escaping where a nested `<script` keeps the real `</script>`
+ * from ending it. No textual rewrite keeps every JavaScript program's
+ * meaning (regex literals and `String.raw` observe an inserted
+ * backslash), so callers that hit this ship the bytes encoded instead.
+ */
+export function scriptNeedsEncoding(js: string): boolean {
+  return /<\/script|<!--/i.test(js);
+}
+
+/** Standard base64 of `text`'s UTF-8 bytes (browser- and Bun-safe, no Buffer). */
+export function utf8ToBase64(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  let bin = "";
+  const CHUNK = 0x8000;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(bin);
+}

package/src/redirect-emit-gcp.ts

@@ -161,5 +161,19 @@ export function assertGcpRedirectBudget(
   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: readonly string[] = ["/api/*"];
+/**
+ * The site's own routing in the `public` path matcher (stack + budget): the
+ * paths the load balancer sends to the gateway instead of the static bucket.
+ * `/api/*` is the gateway's whole API, the remote-MCP broker included
+ * (#806). The two `/.well-known/oauth-*` prefixes are the broker's
+ * discovery documents, which MCP clients look up at the host root (RFC 9728
+ * protected-resource metadata, RFC 8414 authorization-server metadata) —
+ * they must reach the gateway, not 404 in the bucket. No
+ * `openid-configuration` prefix: the broker is not an OpenID provider and
+ * serves no such document (#899), so the site keeps that path.
+ */
+export const GCP_PUBLIC_BASE_PATHS: readonly string[] = [
+  "/api/*",
+  "/.well-known/oauth-protected-resource/*",
+  "/.well-known/oauth-authorization-server/*",
+];

package/src/redirect-emit.test.ts

@@ -153,20 +153,22 @@ describe("GCP URL-map rules", () => {
   });
 
   it("refuses a plan over the 1,000-predicate quota with the counts, before any change", () => {
+    // The base rule routes /api/* and the remote-MCP discovery paths (#806).
+    expect(GCP_PUBLIC_BASE_PATHS).toHaveLength(3);
     const base = [{ paths: [...GCP_PUBLIC_BASE_PATHS] }];
     const rows = (n: number) => Array.from({ length: n }, (_, i) => row(`/p${i}`, "/x"));
-    expect(() => assertGcpRedirectBudget(planOf(rows(499)), base)).not.toThrow();
+    expect(() => assertGcpRedirectBudget(planOf(rows(498)), base)).not.toThrow();
     try {
-      assertGcpRedirectBudget(planOf(rows(500)), base);
+      assertGcpRedirectBudget(planOf(rows(499)), base);
       throw new Error("expected GcpUrlMapBudgetError");
     } catch (e) {
       expect(e).toBeInstanceOf(GcpUrlMapBudgetError);
       expect((e as GcpUrlMapBudgetError).predicatesNeeded).toBe(1001);
-      expect((e as Error).message).toContain("500 redirect(s) need 1001 paths");
+      expect((e as Error).message).toContain("499 redirect(s) need 1001 paths");
       expect((e as Error).message).toContain("bulk_delete_redirects");
     }
     // File-like paths cost one predicate each.
-    const files = Array.from({ length: 999 }, (_, i) => row(`/p${i}.html`, "/x"));
+    const files = Array.from({ length: 997 }, (_, i) => row(`/p${i}.html`, "/x"));
     expect(() => assertGcpRedirectBudget(planOf(files), base)).not.toThrow();
   });
 

package/src/release-manifest.ts

@@ -71,12 +71,23 @@ export const SIGSTORE_BUNDLE_MEDIA_TYPE = "application/vnd.dev.sigstore.bundle.v
 /** Why fetching the artifact failed. */
 export type ReleaseArtifactErrorCode = "registry" | "artifact-shape" | "blob-digest";
 
+/** Why {@link fetchReleaseArtifact} failed. */
+export interface ReleaseArtifactError {
+  readonly code: ReleaseArtifactErrorCode;
+  readonly message: string;
+  /**
+   * Set on `registry` errors a retry may cure: the registry could not be
+   * reached, timed out, rate-limited (429) or failed (5xx). Absent when the
+   * registry answered that the manifest, tag or blob does not exist (404 and
+   * other 4xx) — retrying that changes nothing, so callers that would
+   * otherwise "try again later" must treat it as a verdict.
+   */
+  readonly transient?: true;
+}
+
 export type ReleaseArtifactResult =
   | { readonly ok: true; readonly manifestBytes: Uint8Array; readonly bundleBytes: Uint8Array }
-  | {
-      readonly ok: false;
-      readonly error: { readonly code: ReleaseArtifactErrorCode; readonly message: string };
-    };
+  | { readonly ok: false; readonly error: ReleaseArtifactError };
 
 /** Where and how {@link fetchReleaseArtifact} reaches the registry. */
 export interface ReleaseArtifactDeps {
@@ -101,6 +112,22 @@ const fail = (code: ReleaseArtifactErrorCode, message: string): ReleaseArtifactR
   error: { code, message },
 });
 
+/** A `registry` failure a retry may cure (see {@link ReleaseArtifactError.transient}). */
+const failTransient = (message: string): ReleaseArtifactResult => ({
+  ok: false,
+  error: { code: "registry", message, transient: true },
+});
+
+/** Whether an HTTP status says "try again" rather than "it does not exist". */
+function isTransientStatus(status: number): boolean {
+  return status >= 500 || status === 429 || status === 408;
+}
+
+/** A non-OK registry response as a failure, transient or not by its status. */
+function failStatus(status: number, message: string): ReleaseArtifactResult {
+  return isTransientStatus(status) ? failTransient(message) : fail("registry", message);
+}
+
 /**
  * Fetch the release manifest artifact of `version` and both its layers,
  * each checked against its content digest. Verifies NO signature: callers
@@ -120,6 +147,11 @@ export async function fetchReleaseArtifact(
       headers: { Accept: "application/vnd.oci.image.manifest.v1+json" },
     });
     if (!res.ok) {
+      if (isTransientStatus(res.status)) {
+        return failTransient(
+          `the registry at ${base} could not serve the release manifest of v${version} (HTTP ${res.status}); try again later.`,
+        );
+      }
       return fail(
         "registry",
         `no release manifest for v${version} at ${base} (HTTP ${res.status}). Releases before the signed manifest (epic #696) have none; otherwise check the version exists.`,
@@ -131,7 +163,7 @@ export async function fetchReleaseArtifact(
     }
     artifact = parsed.data;
   } catch (e) {
-    return fail("registry", `registry unreachable: ${e instanceof Error ? e.message : String(e)}`);
+    return failTransient(`registry unreachable: ${e instanceof Error ? e.message : String(e)}`);
   }
 
   if (artifact.artifactType !== RELEASE_MANIFEST_ARTIFACT_TYPE) {
@@ -153,7 +185,7 @@ export async function fetchReleaseArtifact(
 
   const blob = async (layerDigest: string): Promise<Uint8Array | ReleaseArtifactResult> => {
     const res = await deps.fetch(`${base}/blobs/${layerDigest}`);
-    if (!res.ok) return fail("registry", `blob ${layerDigest}: HTTP ${res.status}`);
+    if (!res.ok) return failStatus(res.status, `blob ${layerDigest}: HTTP ${res.status}`);
     const bytes = new Uint8Array(await res.arrayBuffer());
     const actual = await sha256Digest(bytes);
     if (actual !== layerDigest) {
@@ -171,7 +203,7 @@ export async function fetchReleaseArtifact(
     if (!(bundleBytes instanceof Uint8Array)) return bundleBytes;
     return { ok: true, manifestBytes, bundleBytes };
   } catch (e) {
-    return fail("registry", `registry unreachable: ${e instanceof Error ? e.message : String(e)}`);
+    return failTransient(`registry unreachable: ${e instanceof Error ? e.message : String(e)}`);
   }
 }
 

package/src/responsive-images.test.ts

@@ -58,6 +58,16 @@ describe("enrichResponsiveImages (issue #162)", () => {
     expect(out.match(/srcset=/g)).toHaveLength(1);
   });
 
+  it("inserts URLs verbatim even when they spell $-replacement patterns", () => {
+    // A string replacement would expand `$&` into the matched text.
+    const out = enrichResponsiveImages(IMG, byAsset, {
+      rewriteSrc: true,
+      urlFor: (id, v) => `/cdn/$&/${id}/${v}`,
+    });
+    expect(out).toContain(`src="/cdn/$&/${ASSET}/webp-800"`);
+    expect(out).toContain(`/cdn/$&/${ASSET}/webp-400 400w`);
+  });
+
   it("skips srcset for sub-two-entry ladders and non-media images", () => {
     const single = new Map([[ASSET, [{ variant: "webp-800", format: "webp" }]]]);
     const out = enrichResponsiveImages(IMG, single, {

package/src/responsive-images.ts

@@ -137,7 +137,10 @@ export function enrichResponsiveImages(
 
     let out = tag;
     if (options.rewriteSrc) {
-      out = out.replace(srcMatch[0], `src="${options.urlFor(assetId, variant, requestedFormat)}"`);
+      out = out.replace(
+        srcMatch[0],
+        () => `src="${options.urlFor(assetId, variant, requestedFormat)}"`,
+      );
     }
 
     // #667 — an `orig` embed (the default `/_caelo/media/<slug>` form,
@@ -155,7 +158,7 @@ export function enrichResponsiveImages(
         ? origSrcset(variants, assetId, options)
         : null;
     if (origLadder) {
-      out = out.replace(/<img\b/, `<img srcset="${origLadder}"`);
+      out = out.replace(/<img\b/, () => `<img srcset="${origLadder}"`);
     }
 
     if (familyVariants.length >= 2 && !/\bsrcset=/i.test(out)) {
@@ -168,7 +171,7 @@ export function enrichResponsiveImages(
           : "100vw";
       out = out.replace(
         /<img\b/,
-        `<img srcset="${srcset}" sizes="${/\bsizes=/i.test(out) ? "" : sizes}"`,
+        () => `<img srcset="${srcset}" sizes="${/\bsizes=/i.test(out) ? "" : sizes}"`,
       );
       out = out.replace(/\bsizes=""\s*/g, "");
     }

package/src/seo.test.ts

@@ -192,6 +192,13 @@ describe("injectSeoIntoHead", () => {
   it("falls back to prepending when the document has no </head>", () => {
     expect(injectSeoIntoHead("<body>x</body>", "<title>X</title>")).toContain("<title>X</title>");
   });
+
+  it("preserves literal $-replacement patterns in headBlock", () => {
+    const html = "<html><head></head><body>x</body></html>";
+    const headBlock = "<title>Price $& and $' and $`</title>";
+    const out = injectSeoIntoHead(html, headBlock);
+    expect(out).toContain(headBlock);
+  });
 });
 
 describe("schemas", () => {