@caelo-cms/shared 0.10.57 → 0.10.59

package/src/edit-markers.test.ts

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { finalizeEditMarkers, wrapEditableValues } from "./edit-markers.js";
+import { renderTemplate } from "./template-engine.js";
+
+const FIELDS = [
+  { name: "title", kind: "text" },
+  { name: "tags", kind: "text-list" },
+  { name: "links", kind: "link-list" },
+  { name: "photo", kind: "image" },
+] as const;
+
+function render(html: string, values: Record<string, unknown>, sharedPages = 0): string {
+  const wrapped = wrapEditableValues(values, FIELDS);
+  const rendered = renderTemplate({ html, fields: [...FIELDS], contentValues: wrapped }).html;
+  return finalizeEditMarkers(rendered, "content#2", sharedPages);
+}
+
+const marked = (fields: string, shared = 0) =>
+  ` data-caelo-fields="${fields}" data-caelo-placement="content%232" data-caelo-shared="${shared}"`;
+
+const open = (f: string, s = 0) => `<!--caelo:f p=content%232 s=${s} f=${f}-->`;
+const close = "<!--/caelo:f-->";
+
+describe("edit markers (#917)", () => {
+  it("marks a text field in text content", () => {
+    expect(render("<h1>{{title}}</h1>", { title: "Hello & welcome" })).toBe(
+      `<h1>${open("title")}Hello & welcome${close}</h1>`,
+    );
+  });
+
+  it("carries how many pages share a synced placement", () => {
+    expect(render("<h1>{{title}}</h1>", { title: "Hi" }, 4)).toContain(open("title", 4));
+  });
+
+  it("marks text-list items and link-list labels with their index", () => {
+    const html = render(
+      '<ul>{{#tags}}<li>{{.}}</li>{{/tags}}</ul><nav>{{#links}}<a href="{{href}}">{{label}}</a>{{/links}}</nav>',
+      {
+        tags: ["a", "b"],
+        links: [{ label: "Docs", href: "/docs" }],
+      },
+    );
+    expect(html).toContain(`<li>${open("tags.1")}b${close}</li>`);
+    expect(html).toContain(
+      `<a href="/docs"${marked("href=links.0.href")}>${open("links.0.label")}Docs${close}</a>`,
+    );
+  });
+
+  it("leaves other attributes, scripts, styles and titles byte-identical", () => {
+    const html = render(
+      '<div data-x=\'{{title}}\' title="{{title}}"></div><script>var t = "{{title}}";</script><style>/* {{title}} */</style><title>{{title}}</title><!-- {{title}} -->',
+      { title: "Hi > there" },
+    );
+    expect(html).toBe(
+      '<div data-x=\'Hi > there\' title="Hi > there"></div><script>var t = "Hi > there";</script><style>/* Hi > there */</style><title>Hi > there</title><!-- Hi > there -->',
+    );
+    expect(html).not.toMatch(/[\uE000-\uE002]/);
+  });
+
+  it("marks link targets, images and alt text on their tag (#918)", () => {
+    const html = render(
+      '{{#links}}<a href="{{href}}">{{label}}</a>{{/links}}<img src="{{photo}}" alt="{{title}}"/>',
+      { links: [{ label: "Docs", href: "/docs" }], photo: "/m/cup.webp", title: "A cup" },
+      2,
+    );
+    expect(html).toContain(
+      `<a href="/docs"${marked("href=links.0.href", 2)}>${open("links.0.label", 2)}Docs${close}</a>`,
+    );
+    expect(html).toContain(
+      `<img src="/m/cup.webp" alt="A cup"${marked("src=photo alt=title", 2)}/>`,
+    );
+  });
+
+  it("does not mark an attribute assembled from several parts", () => {
+    expect(render('<a href="/tags/{{title}}">x</a>', { title: "cups" })).toBe(
+      '<a href="/tags/cups">x</a>',
+    );
+  });
+
+  it("does not mark values that carry markup, empty values, or non-text kinds", () => {
+    const html = render("<h1>{{title}}</h1><p>{{#tags}}{{.}}{{/tags}}</p>", {
+      title: "<b>Bold</b>",
+      tags: [" "],
+    });
+    expect(html).toBe("<h1><b>Bold</b></h1><p> </p>");
+    expect(wrapEditableValues({ n: 3 }, [{ name: "n", kind: "number" }])).toEqual({ n: 3 });
+  });
+
+  it("keeps conditional sections working on wrapped values", () => {
+    expect(render("{{#title}}<p>{{title}}</p>{{/title}}", { title: "Hi" })).toBe(
+      `<p>${open("title")}Hi${close}</p>`,
+    );
+    expect(render("{{#title}}<p>{{title}}</p>{{/title}}", {})).toBe("");
+  });
+
+  it("encodes placement and field so a comment can never close early", () => {
+    const out = finalizeEditMarkers(
+      wrapEditableValues({ "a--b": "x" }, [{ name: "a--b", kind: "text" }])["a--b"] as string,
+      "main--slot#0",
+      0,
+    );
+    expect(out).toBe("<!--caelo:f p=main%2D%2Dslot%230 s=0 f=a%2D%2Db-->x<!--/caelo:f-->");
+  });
+
+  it("is a no-op on HTML without sentinels", () => {
+    const html = "<h1>Plain</h1><!-- caelo:missing reason=x -->";
+    expect(finalizeEditMarkers(html, "content#0", 0)).toBe(html);
+  });
+});

package/src/edit-markers.ts

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #917 — field markers for the Live Edit preview. They let the preview
+ * iframe tell which placement + field a piece of visible text came from,
+ * so the operator can edit that text in place.
+ *
+ * Two steps around the normal module render:
+ *
+ *   1. {@link wrapEditableValues} wraps every plain-text value of a
+ *      placement's content instance in private-use sentinels that carry
+ *      the field path. The template engine substitutes the wrapped value
+ *      like any other string (its escape is the identity), so the
+ *      sentinels land wherever the module author put `{{field}}`.
+ *   2. {@link finalizeEditMarkers} scans the rendered HTML. A sentinel in
+ *      text content becomes a pair of HTML comments around the value:
+ *      `<!--caelo:f p=<placement> s=<0|1> f=<path>-->value<!--/caelo:f-->`.
+ *      Comments do not affect layout or CSS selectors. A sentinel in a
+ *      comment or a raw-text element (`<script>`, `<style>`, `<title>`,
+ *      `<textarea>`) is removed and the value stays as it was. In a tag
+ *      it is removed too; an `href` / `src` / `alt` that is exactly one
+ *      marked value also gets `data-caelo-fields` on its tag (#918).
+ *
+ * Only the editor preview runs this. Published output never carries
+ * markers: the static generator and every other caller of
+ * `pages.render_preview` leave `editMarkers` off.
+ *
+ * Only values without `<` are wrapped: a value that carries markup cannot
+ * be edited as plain text without destroying that markup.
+ */
+
+const START = "\uE000";
+const SEP = "\uE001";
+const END = "\uE002";
+const SENTINELS = /[\uE000-\uE002]/g;
+
+/** Comment prefix of an opening marker; the closing marker is `/caelo:f`. */
+export const EDIT_MARKER_PREFIX = "caelo:f";
+
+/**
+ * Field kinds the preview marks: text (`text`, `text-list` items,
+ * `link-list` labels) and link / image targets (`url`, `image`,
+ * `link-list` hrefs, #918) — the latter usually land in `href` / `src`.
+ */
+const EDITABLE_KINDS = new Set(["text", "text-list", "link-list", "url", "image"]);
+
+/** Attributes whose marked value the editor can change (link target, image, alt text). */
+const MARKABLE_ATTRIBUTES = new Set(["href", "src", "alt"]);
+
+/** Field shape {@link wrapEditableValues} needs: name + kind. */
+export interface EditableFieldDef {
+  readonly name: string;
+  readonly kind?: string;
+}
+
+function editable(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0 && !value.includes("<");
+}
+
+function wrap(path: string, value: string): string {
+  return `${START}${path}${SEP}${value.replace(SENTINELS, "")}${END}`;
+}
+
+/**
+ * Wrap the editable text of a content instance's values in sentinels.
+ * Returns a new object; non-editable values pass through untouched.
+ *
+ * Paths: `<field>` for a `text` / `url` / `image` field, `<field>.<i>`
+ * for a `text-list` item, `<field>.<i>.label` / `<field>.<i>.href` for a
+ * `link-list` item's label / target.
+ *
+ * @example
+ * wrapEditableValues({ hero_title: "Hi" }, [{ name: "hero_title", kind: "text" }]);
+ * // → { hero_title: "\uE000hero_title\uE001Hi\uE002" }
+ */
+export function wrapEditableValues(
+  values: Readonly<Record<string, unknown>>,
+  fields: readonly EditableFieldDef[],
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...values };
+  for (const f of fields) {
+    const kind = f.kind ?? "text";
+    if (!EDITABLE_KINDS.has(kind)) continue;
+    const v = values[f.name];
+    if (kind === "text" || kind === "url" || kind === "image") {
+      if (editable(v)) out[f.name] = wrap(f.name, v);
+    } else if (kind === "text-list" && Array.isArray(v)) {
+      out[f.name] = v.map((item, i) => (editable(item) ? wrap(`${f.name}.${i}`, item) : item));
+    } else if (kind === "link-list" && Array.isArray(v)) {
+      out[f.name] = v.map((item, i) => {
+        if (typeof item !== "object" || item === null) return item;
+        const { label, href } = item as { label?: unknown; href?: unknown };
+        return {
+          ...item,
+          ...(editable(label) ? { label: wrap(`${f.name}.${i}.label`, label) } : {}),
+          ...(editable(href) ? { href: wrap(`${f.name}.${i}.href`, href) } : {}),
+        };
+      });
+    }
+  }
+  return out;
+}
+
+/** Comment-safe encoding: no `--`, no `>`, no whitespace. */
+function attr(value: string): string {
+  return encodeURIComponent(value).replace(/-/g, "%2D");
+}
+
+const RAW_TEXT_ELEMENTS = new Set(["script", "style", "title", "textarea"]);
+
+/** End index (exclusive) of the tag starting at `i`, honouring quoted attribute values. */
+function tagEnd(html: string, i: number): number {
+  let quote: string | null = null;
+  for (let j = i + 1; j < html.length; j += 1) {
+    const c = html[j];
+    if (quote) {
+      if (c === quote) quote = null;
+    } else if (c === '"' || c === "'") {
+      quote = c;
+    } else if (c === ">") {
+      return j + 1;
+    }
+  }
+  return html.length;
+}
+
+/**
+ * Turn sentinels in rendered module HTML into marker comments (text
+ * content) or drop them (everywhere else). See the file header.
+ *
+ * A tag whose `href` / `src` / `alt` value is exactly one marked value
+ * gets `data-caelo-fields="href=<path> …"` plus the placement
+ * (`data-caelo-placement`, `data-caelo-shared`), so the editor can offer
+ * "Edit link" / "Replace image" (#918). A value assembled from several
+ * parts (`href="/blog/{{slug}}"`) is not editable and is not marked.
+ *
+ * @param placement The placement key, `<blockName>#<position>`.
+ * @param sharedPages 0 for a placement with its own content; for a synced
+ *   (shared) one, the number of pages that show the same content.
+ */
+export function finalizeEditMarkers(html: string, placement: string, sharedPages: number): string {
+  if (!html.includes(START)) return html;
+  const open = (path: string) =>
+    `<!--${EDIT_MARKER_PREFIX} p=${attr(placement)} s=${sharedPages} f=${attr(path)}-->`;
+  const close = `<!--/${EDIT_MARKER_PREFIX}-->`;
+  let out = "";
+  let i = 0;
+  while (i < html.length) {
+    const c = html[i];
+    if (c === "<" && html.startsWith("<!--", i)) {
+      const end = html.indexOf("-->", i + 4);
+      const stop = end === -1 ? html.length : end + 3;
+      out += stripSentinels(html.slice(i, stop));
+      i = stop;
+      continue;
+    }
+    if (c === "<" && /[a-zA-Z/!?]/.test(html[i + 1] ?? "")) {
+      const stop = tagEnd(html, i);
+      const tag = html.slice(i, stop);
+      out += markTag(tag, placement, sharedPages);
+      i = stop;
+      const name = /^<([a-zA-Z][a-zA-Z0-9-]*)/.exec(tag)?.[1]?.toLowerCase();
+      if (name && RAW_TEXT_ELEMENTS.has(name) && !tag.endsWith("/>")) {
+        const closeAt = html.toLowerCase().indexOf(`</${name}`, i);
+        const rawStop = closeAt === -1 ? html.length : closeAt;
+        out += stripSentinels(html.slice(i, rawStop));
+        i = rawStop;
+      }
+      continue;
+    }
+    if (c === START) {
+      const sep = html.indexOf(SEP, i);
+      const end = html.indexOf(END, i);
+      if (sep !== -1 && end !== -1 && sep < end) {
+        out += `${open(html.slice(i + 1, sep))}${html.slice(sep + 1, end)}${close}`;
+        i = end + 1;
+        continue;
+      }
+    }
+    if (c !== SEP && c !== END && c !== START) out += c;
+    i += 1;
+  }
+  return out;
+}
+
+const ATTRIBUTE = /([^\s"'=<>/]+)(\s*=\s*)(?:"([^"]*)"|'([^']*)')/g;
+const WHOLE_VALUE = /^\uE000([^\uE001]*)\uE001[^\uE002]*\uE002$/;
+
+/** Strip sentinels from a tag and mark its editable attributes (see finalizeEditMarkers). */
+function markTag(tag: string, placement: string, sharedPages: number): string {
+  if (!tag.includes(START)) return tag;
+  const marks: string[] = [];
+  const cleaned = stripSentinels(
+    tag.replace(ATTRIBUTE, (m, name: string, eq: string, dq?: string, sq?: string) => {
+      const value = dq ?? sq ?? "";
+      if (!value.includes(START)) return m;
+      const whole = WHOLE_VALUE.exec(value);
+      const lower = name.toLowerCase();
+      if (whole?.[1] && MARKABLE_ATTRIBUTES.has(lower)) marks.push(`${lower}=${attr(whole[1])}`);
+      const quote = dq !== undefined ? '"' : "'";
+      return `${name}${eq}${quote}${stripSentinels(value)}${quote}`;
+    }),
+  );
+  if (marks.length === 0) return cleaned;
+  const extra = ` data-caelo-fields="${marks.join(" ")}" data-caelo-placement="${attr(placement)}" data-caelo-shared="${sharedPages}"`;
+  const at = cleaned.endsWith("/>") ? cleaned.length - 2 : cleaned.length - 1;
+  return `${cleaned.slice(0, at)}${extra}${cleaned.slice(at)}`;
+}
+
+/** Drop sentinels and the path they carry, keeping the wrapped value. */
+function stripSentinels(s: string): string {
+  return s.replace(/\uE000[^\uE001]*\uE001/g, "").replace(SENTINELS, "");
+}
+
+/** A parsed opening marker. */
+export interface EditMarker {
+  readonly blockName: string;
+  readonly position: number;
+  readonly synced: boolean;
+  readonly field: string;
+  readonly index?: number;
+}
+
+/**
+ * Parse an opening marker's comment text (without `<!--`/`-->`), or null.
+ * Mirrors what the preview runtime does in the browser.
+ */
+export function parseEditMarker(comment: string): EditMarker | null {
+  const m = /^caelo:f p=(\S+) s=([01]) f=(\S+)$/.exec(comment.trim());
+  if (!m?.[1] || !m[2] || !m[3]) return null;
+  const placement = decodeURIComponent(m[1]);
+  const hash = placement.lastIndexOf("#");
+  const position = Number(placement.slice(hash + 1));
+  if (hash <= 0 || !Number.isInteger(position)) return null;
+  const [field, index] = decodeURIComponent(m[3]).split(".");
+  if (!field) return null;
+  return {
+    blockName: placement.slice(0, hash),
+    position,
+    synced: m[2] === "1",
+    field,
+    ...(index !== undefined ? { index: Number(index) } : {}),
+  };
+}

package/src/google-oauth.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #914 — the shape of a Google OAuth client and the redirect URI IAP
+ * needs on it. Shared so the admin's server-side validation and the setup
+ * page (which shows IAP's redirect URI as the Owner types the client ID)
+ * use one definition.
+ */
+
+/**
+ * A Google OAuth 2.0 client ID (`<project number>-<random>.apps.googleusercontent.com`).
+ * Same pattern as the `operator_oauth_client` CHECK constraint (migration 0323).
+ */
+export const GOOGLE_OAUTH_CLIENT_ID = /^[0-9]+-[a-z0-9]+\.apps\.googleusercontent\.com$/;
+
+/**
+ * IAP's redirect URI for a custom OAuth client: Google sends a signed-in
+ * visitor back to IAP here, so the client must list it among its authorized
+ * redirect URIs (cloud.google.com/iap/docs/custom-oauth-configuration).
+ *
+ * @example
+ *   iapRedirectUri("123-abc.apps.googleusercontent.com")
+ *   // → "https://iap.googleapis.com/v1/oauth/clientIds/123-abc.apps.googleusercontent.com:handleRedirect"
+ */
+export function iapRedirectUri(clientId: string): string {
+  return `https://iap.googleapis.com/v1/oauth/clientIds/${clientId}:handleRedirect`;
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export * from "./ai-tools.js";
 export * from "./auth-forms.js";
 export * from "./auto-update.js";
 export * from "./base-css.js";
+export * from "./bug-intake.js";
 export * from "./build-page.js";
 export * from "./cap-failures.js";
 export * from "./cloud-shell-install.js";
@@ -16,6 +17,7 @@ export * from "./css-var-scan.js";
 export * from "./database-url.js";
 export * from "./design-draft-shell.js";
 export * from "./document-language.js";
+export * from "./edit-markers.js";
 export * from "./font-assets.js";
 export * from "./font-axis-policy.js";
 export * from "./font-usage.js";
@@ -23,8 +25,10 @@ export * from "./fonts.js";
 export * from "./genesis.js";
 export * from "./genesis-inventory.js";
 export * from "./google-models.js";
+export * from "./google-oauth.js";
 export * from "./image-capabilities.js";
 export * from "./interactions.js";
+export * from "./link-canonicalise.js";
 export * from "./link-refs.js";
 export {
   type LogContext,