@caelo-cms/shared 0.12.10 → 0.12.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/dist/ai-cost.d.ts +146 -0
  2. package/dist/ai-cost.d.ts.map +1 -0
  3. package/dist/ai-cost.js +182 -0
  4. package/dist/ai-cost.js.map +1 -0
  5. package/dist/ai-tools.d.ts +1 -1
  6. package/dist/build-page.d.ts +2 -2
  7. package/dist/cap-failures.d.ts.map +1 -1
  8. package/dist/cap-failures.js +7 -5
  9. package/dist/cap-failures.js.map +1 -1
  10. package/dist/change-journal.d.ts.map +1 -1
  11. package/dist/change-journal.js +13 -0
  12. package/dist/change-journal.js.map +1 -1
  13. package/dist/content.d.ts +3 -3
  14. package/dist/embedding-models.d.ts +95 -0
  15. package/dist/embedding-models.d.ts.map +1 -0
  16. package/dist/embedding-models.js +60 -0
  17. package/dist/embedding-models.js.map +1 -0
  18. package/dist/index.d.ts +4 -0
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +4 -0
  21. package/dist/index.js.map +1 -1
  22. package/dist/module-id-tag.d.ts +13 -0
  23. package/dist/module-id-tag.d.ts.map +1 -1
  24. package/dist/module-id-tag.js +24 -2
  25. package/dist/module-id-tag.js.map +1 -1
  26. package/dist/preview-compose.d.ts +6 -0
  27. package/dist/preview-compose.d.ts.map +1 -1
  28. package/dist/preview-compose.js +9 -3
  29. package/dist/preview-compose.js.map +1 -1
  30. package/dist/site-security-headers.d.ts +2 -2
  31. package/dist/stage-status.d.ts +10 -5
  32. package/dist/stage-status.d.ts.map +1 -1
  33. package/dist/stage-status.js +27 -1
  34. package/dist/stage-status.js.map +1 -1
  35. package/dist/version.d.ts +2 -2
  36. package/dist/version.js +1 -1
  37. package/dist/visitor-ai-origin.d.ts +41 -0
  38. package/dist/visitor-ai-origin.d.ts.map +1 -0
  39. package/dist/visitor-ai-origin.js +65 -0
  40. package/dist/visitor-ai-origin.js.map +1 -0
  41. package/package.json +8 -1
  42. package/src/ai-cost.test.ts +81 -0
  43. package/src/ai-cost.ts +288 -0
  44. package/src/cap-failures.ts +7 -5
  45. package/src/change-journal.ts +25 -0
  46. package/src/embedding-models.test.ts +37 -0
  47. package/src/embedding-models.ts +147 -0
  48. package/src/index.ts +8 -0
  49. package/src/module-id-tag.test.ts +27 -1
  50. package/src/module-id-tag.ts +29 -2
  51. package/src/preview-compose.test.ts +21 -0
  52. package/src/preview-compose.ts +20 -3
  53. package/src/stage-status.ts +29 -1
  54. package/src/version.ts +1 -1
  55. package/src/visitor-ai-origin.ts +86 -0
@@ -0,0 +1,147 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * The core catalog of embedding models (epic #1644, R7, issue #1650).
5
+ *
6
+ * A plugin that wants semantic search names a model of this catalog in its
7
+ * configuration (a `catalogModel` config leaf); no plugin ships a model or
8
+ * a binary. Each entry pins the publisher's repository at one revision and
9
+ * every file by SHA-256, so what runs is what was reviewed: the files are
10
+ * fetched once, at image build (`packages/models/scripts/fetch-models.ts`),
11
+ * verified, and verified again when a process loads them. Only MIT and
12
+ * Apache-2.0 models qualify (CLAUDE.md §3); the licence and its notice ship
13
+ * with the files (THIRD_PARTY_NOTICES).
14
+ *
15
+ * This module is data only (no runtime dependency): the plugin SDK
16
+ * validates config values against {@link EMBEDDING_MODEL_IDS}, the admin
17
+ * shows the entries, and `@caelo-cms/models` loads them (natively in the
18
+ * index job, as WebAssembly in the gateway).
19
+ *
20
+ * Why one model: every entry ships in the admin and the gateway image
21
+ * (about 125 MB each), so an entry is added when a measurement shows a
22
+ * site needs what the default cannot do, not to offer a choice for its
23
+ * own sake. `packages/collection-index/bench/semantic.ts` measures the
24
+ * candidates on a labelled German/English site-search set;
25
+ * `bench/semantic-results.md` holds the numbers that chose the default.
26
+ */
27
+
28
+ /** One file of a model, pinned by content. */
29
+ export interface EmbeddingModelFile {
30
+ /** File name in the model's directory (`model.onnx`). */
31
+ readonly name: string;
32
+ /** Path in the source repository at {@link EmbeddingModel.source}'s revision. */
33
+ readonly path: string;
34
+ /** SHA-256 of the file, lowercase hex. */
35
+ readonly sha256: string;
36
+ readonly bytes: number;
37
+ }
38
+
39
+ /** One approved embedding model. */
40
+ export interface EmbeddingModel {
41
+ /** Stable id plugins name in their configuration. */
42
+ readonly id: string;
43
+ /** What the operator sees ("Granite Embedding 97M, multilingual"). */
44
+ readonly label: string;
45
+ /** One sentence for the operator and the AI: what it is good at. */
46
+ readonly description: string;
47
+ readonly source: {
48
+ readonly host: "huggingface.co";
49
+ readonly repo: string;
50
+ /** The repository commit the files are taken from. */
51
+ readonly revision: string;
52
+ };
53
+ readonly licence: "MIT" | "Apache-2.0";
54
+ readonly licenceUrl: string;
55
+ /** The copyright line the notice names. */
56
+ readonly copyright: string;
57
+ readonly files: {
58
+ /** The ONNX graph; loaded from bytes, so it can name no external file. */
59
+ readonly model: EmbeddingModelFile;
60
+ /** The tokenizer (`tokenizer.json`, Hugging Face tokenizers format). */
61
+ readonly tokenizer: EmbeddingModelFile;
62
+ };
63
+ /** Vector dimensions. */
64
+ readonly dims: number;
65
+ /** Tokens embedded per text, special tokens included; a longer text is cut. */
66
+ readonly maxTokens: number;
67
+ /** How token states become the text's vector (then L2-normalised). */
68
+ readonly pooling: "cls" | "mean";
69
+ /** Prepended to the text (e5 models were trained with `query: ` / `passage: `). */
70
+ readonly prefixes: { readonly query: string; readonly passage: string };
71
+ /** The tokenizer's padding token id. */
72
+ readonly padTokenId: number;
73
+ /** The graph's inputs, in the names the export uses. */
74
+ readonly inputs: readonly ("input_ids" | "attention_mask" | "token_type_ids")[];
75
+ /** The graph output holding per-token states (`[batch, tokens, dims]`). */
76
+ readonly output: string;
77
+ /** Languages it serves well, as the publisher documents them. */
78
+ readonly languages: string;
79
+ /** How the published file is quantised. */
80
+ readonly quantization: string;
81
+ }
82
+
83
+ /**
84
+ * Granite Embedding 97M multilingual R2 (IBM, Apache-2.0): chosen by the
85
+ * #1650 measurements (bench/semantic-results.md).
86
+ */
87
+ const GRANITE_97M_R2: EmbeddingModel = {
88
+ id: "granite-embedding-97m-multilingual-r2",
89
+ label: "Granite Embedding 97M, multilingual",
90
+ description:
91
+ "Small multilingual model (52 languages with retrieval training, German and English among them); finds pages by meaning and across languages.",
92
+ source: {
93
+ host: "huggingface.co",
94
+ repo: "ibm-granite/granite-embedding-97m-multilingual-r2",
95
+ revision: "835ad14087e140460703cf0fae09f97d469d65c2",
96
+ },
97
+ licence: "Apache-2.0",
98
+ licenceUrl: "https://www.apache.org/licenses/LICENSE-2.0",
99
+ copyright: "Copyright IBM Corp.",
100
+ files: {
101
+ model: {
102
+ name: "model.onnx",
103
+ path: "onnx/model_quint8_avx2.onnx",
104
+ sha256: "a6022dd8220ea6f6595562a1328ee216f4a94faa55362f2f4747c80f1e78772e",
105
+ bytes: 98_247_878,
106
+ },
107
+ tokenizer: {
108
+ name: "tokenizer.json",
109
+ path: "tokenizer.json",
110
+ sha256: "4f2842d568e2724370aec203652a42ac783c7937f8347a1a2cc7506d71f1582f",
111
+ bytes: 25_301_672,
112
+ },
113
+ },
114
+ dims: 384,
115
+ maxTokens: 512,
116
+ pooling: "cls",
117
+ prefixes: { query: "", passage: "" },
118
+ padTokenId: 179_935,
119
+ inputs: ["input_ids", "attention_mask"],
120
+ output: "last_hidden_state",
121
+ languages:
122
+ "52 languages with retrieval training (German, English, French, Spanish, Italian, Dutch, Polish, …), 200+ in pretraining",
123
+ quantization: "dynamic int8 (uint8 weights), as published",
124
+ };
125
+
126
+ /** Every approved model. */
127
+ export const EMBEDDING_MODELS: readonly EmbeddingModel[] = [GRANITE_97M_R2];
128
+
129
+ /** Catalog ids, for config validation. */
130
+ export const EMBEDDING_MODEL_IDS: readonly string[] = EMBEDDING_MODELS.map((m) => m.id);
131
+
132
+ /** The model a plugin's config offers by default. */
133
+ export const DEFAULT_EMBEDDING_MODEL_ID: string = GRANITE_97M_R2.id;
134
+
135
+ /** The catalog entry of `id`, or undefined. */
136
+ export function embeddingModel(id: string): EmbeddingModel | undefined {
137
+ return EMBEDDING_MODELS.find((m) => m.id === id);
138
+ }
139
+
140
+ /**
141
+ * What an index records as its vector model: the id and the graph's digest.
142
+ * A new revision of the same id is another fingerprint, so an index built
143
+ * with the old files is rebuilt rather than mixed with new query vectors.
144
+ */
145
+ export function embeddingModelFingerprint(model: EmbeddingModel): string {
146
+ return `${model.id}@${model.files.model.sha256.slice(0, 12)}`;
147
+ }
package/src/index.ts CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  export const PROJECT_NAME = "caelo-cms";
4
4
 
5
+ export * from "./ai-cost.js";
5
6
  export * from "./ai-tools.js";
6
7
  export * from "./auth-forms.js";
7
8
  export * from "./auto-update.js";
@@ -24,6 +25,7 @@ export * from "./database-url.js";
24
25
  export * from "./design-draft-shell.js";
25
26
  export * from "./document-language.js";
26
27
  export * from "./edit-markers.js";
28
+ export * from "./embedding-models.js";
27
29
  export * from "./escaped-line-breaks.js";
28
30
  export * from "./font-assets.js";
29
31
  export * from "./font-axis-policy.js";
@@ -57,6 +59,11 @@ export {
57
59
  export * from "./markup-structure.js";
58
60
  export * from "./mcp-access.js";
59
61
  export * from "./media.js";
62
+ export {
63
+ CONTENT_INSTANCE_ATTRIBUTE,
64
+ stripContentInstances,
65
+ tagContentInstance,
66
+ } from "./module-id-tag.js";
60
67
  export * from "./nested-module-render.js";
61
68
  export * from "./owner-setup-token.js";
62
69
  export * from "./page-log.js";
@@ -123,3 +130,4 @@ export {
123
130
  isNewerVersion,
124
131
  parseVersion,
125
132
  } from "./version.js";
133
+ export * from "./visitor-ai-origin.js";
@@ -1,7 +1,12 @@
1
1
  // SPDX-License-Identifier: MPL-2.0
2
2
 
3
3
  import { describe, expect, it } from "bun:test";
4
- import { tagModuleId } from "./module-id-tag.js";
4
+ import {
5
+ CONTENT_INSTANCE_ATTRIBUTE,
6
+ stripContentInstances,
7
+ tagContentInstance,
8
+ tagModuleId,
9
+ } from "./module-id-tag.js";
5
10
 
6
11
  describe("tagModuleId", () => {
7
12
  it("stamps the first opening tag", () => {
@@ -36,3 +41,24 @@ describe("tagModuleId", () => {
36
41
  expect(performance.now() - start).toBeLessThan(500);
37
42
  });
38
43
  });
44
+
45
+ describe("the content-instance stamp (epic #1644)", () => {
46
+ const ID = "11111111-1111-4111-8111-111111111111";
47
+
48
+ it("sits next to the module id, once, also on a self-closing root", () => {
49
+ const tagged = tagContentInstance(tagModuleId("<p>hi</p>", "m1"), ID);
50
+ expect(tagged).toBe(
51
+ `<p data-caelo-module-id="m1" ${CONTENT_INSTANCE_ATTRIBUTE}="${ID}">hi</p>`,
52
+ );
53
+ expect(tagContentInstance(tagged, ID)).toBe(tagged);
54
+ expect(tagContentInstance('<line x1="0"/>', ID)).toBe(
55
+ `<line x1="0" ${CONTENT_INSTANCE_ATTRIBUTE}="${ID}"/>`,
56
+ );
57
+ });
58
+
59
+ it("leaves no trace once stripped", () => {
60
+ const html = `<div data-caelo-module-id="m1" ${CONTENT_INSTANCE_ATTRIBUTE}="${ID}"><p>x</p></div>`;
61
+ expect(stripContentInstances(html)).toBe('<div data-caelo-module-id="m1"><p>x</p></div>');
62
+ expect(stripContentInstances("<p>none</p>")).toBe("<p>none</p>");
63
+ });
64
+ });
@@ -30,18 +30,45 @@ export const MODULE_ID_ATTRIBUTE = "data-caelo-module-id";
30
30
  * @example tagModuleId('<line x1="0"/>', "abc") // '<line x1="0" data-caelo-module-id="abc"/>'
31
31
  */
32
32
  export function tagModuleId(html: string, moduleId: string): string {
33
+ return tagRoot(html, MODULE_ID_ATTRIBUTE, moduleId);
34
+ }
35
+
36
+ /**
37
+ * Epic #1644 — the content instance a placement shows, on its root next to
38
+ * the module id, for page-output observers only: two placements of one
39
+ * design with different content are two blocks to an index. The generator
40
+ * stamps it when an observer reads the page and strips it
41
+ * ({@link stripContentInstances}) before the file is written, so the
42
+ * published HTML never carries it.
43
+ */
44
+ export const CONTENT_INSTANCE_ATTRIBUTE = "data-caelo-content-instance";
45
+
46
+ /** {@link CONTENT_INSTANCE_ATTRIBUTE} on the module's root (idempotent, like {@link tagModuleId}). */
47
+ export function tagContentInstance(html: string, contentInstanceId: string): string {
48
+ return tagRoot(html, CONTENT_INSTANCE_ATTRIBUTE, contentInstanceId);
49
+ }
50
+
51
+ const STAMP = new RegExp(` ${CONTENT_INSTANCE_ATTRIBUTE}="[0-9a-f-]{36}"`, "g");
52
+
53
+ /** The HTML without the observers' content-instance stamps (a fixed-width pattern: linear). */
54
+ export function stripContentInstances(html: string): string {
55
+ return html.includes(CONTENT_INSTANCE_ATTRIBUTE) ? html.replace(STAMP, "") : html;
56
+ }
57
+
58
+ /** `name="value"` on the first opening tag of `html`, unless that tag has `name` already. */
59
+ function tagRoot(html: string, name: string, value: string): string {
33
60
  if (!html) return html;
34
61
  const firstOpen = /<([a-zA-Z][a-zA-Z0-9-]*)\b([^>]*)>/;
35
62
  const m = firstOpen.exec(html);
36
63
  if (!m) return html;
37
64
  const tagAttrs = m[2] ?? "";
38
- if (/\sdata-caelo-module-id\s*=/.test(tagAttrs)) return html;
65
+ if (new RegExp(`\\s${name}\\s*=`).test(tagAttrs)) return html;
39
66
  // String ops, not a `\s*\/\s*$` regex: that backtracks polynomially on
40
67
  // long whitespace runs (CodeQL js/polynomial-redos).
41
68
  const trimmed = tagAttrs.trimEnd();
42
69
  const selfClosing = trimmed.endsWith("/");
43
70
  const attrs = selfClosing ? trimmed.slice(0, -1).trimEnd() : tagAttrs;
44
71
  const close = selfClosing ? "/>" : ">";
45
- const replaced = `<${m[1]}${attrs} ${MODULE_ID_ATTRIBUTE}="${moduleId}"${close}`;
72
+ const replaced = `<${m[1]}${attrs} ${name}="${value}"${close}`;
46
73
  return html.slice(0, m.index) + replaced + html.slice(m.index + m[0].length);
47
74
  }
@@ -60,6 +60,27 @@ describe("composePagePreview", () => {
60
60
  );
61
61
  });
62
62
 
63
+ it("stamps each placement's content instance only when an observer asked for it (#1644)", () => {
64
+ const input = (stampContentInstances: boolean) => ({
65
+ templateHtml: `<body><caelo-slot name="x">_</caelo-slot></body>`,
66
+ templateCss: "",
67
+ stampContentInstances,
68
+ blocks: [
69
+ {
70
+ blockName: "x",
71
+ modules: [
72
+ { ...blankModule, html: "<p>A</p>", contentInstanceId: uid(1) },
73
+ { ...blankModule, html: "<p>B</p>", contentInstanceId: uid(2) },
74
+ ],
75
+ },
76
+ ],
77
+ });
78
+ const stamped = composePagePreview(input(true)).html;
79
+ expect(stamped).toContain(`data-caelo-content-instance="${uid(1)}">A</p>`);
80
+ expect(stamped).toContain(`data-caelo-content-instance="${uid(2)}">B</p>`);
81
+ expect(composePagePreview(input(false)).html).not.toContain("data-caelo-content-instance");
82
+ });
83
+
63
84
  it("orders modules within a block by array order", () => {
64
85
  const out = composePagePreview({
65
86
  templateHtml: `<body><caelo-slot name="x">_</caelo-slot></body>`,
@@ -30,7 +30,7 @@ import type { ModuleFieldKind } from "./content.js";
30
30
  import { findInteractionIds, interactionAssets } from "./interactions.js";
31
31
  import { type LinkResolver, resolveLinkRefsInHtml } from "./link-refs.js";
32
32
  import type { ListPageContext } from "./lists/resolve.js";
33
- import { MODULE_ID_ATTRIBUTE, tagModuleId } from "./module-id-tag.js";
33
+ import { MODULE_ID_ATTRIBUTE, tagContentInstance, tagModuleId } from "./module-id-tag.js";
34
34
  import {
35
35
  type NestedModuleResource,
36
36
  type NestedRenderFailure,
@@ -137,6 +137,17 @@ export interface ComposeTheme {
137
137
  };
138
138
  }
139
139
 
140
+ /** The placement's content instance on its root, when an observer reads the page. */
141
+ function stampPlacement(
142
+ html: string,
143
+ m: { readonly contentInstanceId?: string },
144
+ input: { readonly stampContentInstances?: boolean },
145
+ ): string {
146
+ return input.stampContentInstances && m.contentInstanceId
147
+ ? tagContentInstance(html, m.contentInstanceId)
148
+ : html;
149
+ }
150
+
140
151
  /**
141
152
  * issue #150 — self-hosted web fonts resolved by the caller (font
142
153
  * resolver in admin-core; static generator + preview op thread the
@@ -150,6 +161,12 @@ export interface ComposeFonts {
150
161
  }
151
162
 
152
163
  export interface ComposeInput {
164
+ /**
165
+ * Epic #1644 — stamp each placement's content instance on its root
166
+ * (module-id-tag.ts CONTENT_INSTANCE_ATTRIBUTE) for page-output
167
+ * observers; the generator strips it before the file is written.
168
+ */
169
+ readonly stampContentInstances?: boolean;
153
170
  readonly templateHtml: string;
154
171
  readonly templateCss: string;
155
172
  readonly blocks: readonly ComposeBlock[];
@@ -299,7 +316,7 @@ export function composePagePreview(input: ComposeInput): ComposeOutput {
299
316
  const rendered = renderModuleFields(m, input);
300
317
  recordFailures(moduleFailures, block.blockName, m, rendered.failures);
301
318
  nestedAssetIds.push(...rendered.nestedModuleIds);
302
- return tagModuleId(rendered.html, m.moduleId);
319
+ return stampPlacement(tagModuleId(rendered.html, m.moduleId), m, input);
303
320
  });
304
321
  const html = renderedModuleHtml.join("\n");
305
322
  contentByName.set(block.blockName, html);
@@ -776,7 +793,7 @@ export function composePageWithLayout(input: ComposeWithLayoutInput): ComposeWit
776
793
  nestedAssetIds.push(id);
777
794
  }
778
795
  }
779
- const tagged = tagModuleId(baseHtml, m.moduleId);
796
+ const tagged = stampPlacement(tagModuleId(baseHtml, m.moduleId), m, input);
780
797
  if (!deferral) return tagged;
781
798
  if (deferral.omit) {
782
799
  if (deferral.editorNotice) deferredCss.add(deferral.editorNotice.css);
@@ -61,6 +61,21 @@ export const stageStatusRunSchema = z.object({
61
61
  eta: stageEtaSchema.nullable(),
62
62
  /** Why there is no estimate for a queued or running run; null otherwise. */
63
63
  etaUnavailable: z.string().nullable(),
64
+ /**
65
+ * #1648 — the search indexes (plugin collections) this Stage built, once
66
+ * its build succeeded: Publish live waits for every one to be ready.
67
+ * Absent for a run that has none (no plugin keeps a collection) or no row yet.
68
+ */
69
+ searchIndexes: z
70
+ .array(
71
+ z.object({
72
+ plugin: z.string(),
73
+ collection: z.string(),
74
+ state: z.enum(["pending", "ready", "failed"]),
75
+ error: z.string().nullable(),
76
+ }),
77
+ )
78
+ .optional(),
64
79
  });
65
80
  export type StageStatusRun = z.infer<typeof stageStatusRunSchema>;
66
81
 
@@ -93,6 +108,19 @@ export function describeStageEta(run: Pick<StageStatusRun, "eta" | "etaUnavailab
93
108
  * about 1 min 40 s left (from this run's pace)" or "Failed in generator
94
109
  * after 1 min 34 s: <reason>".
95
110
  */
111
+ /** The search indexes' part of a succeeded Stage's line ("" without any). */
112
+ function describeSearchIndexes(run: StageStatusRun): string {
113
+ const indexes = run.searchIndexes ?? [];
114
+ if (indexes.length === 0) return "";
115
+ const failed = indexes.filter((i) => i.state === "failed");
116
+ const pending = indexes.filter((i) => i.state === "pending");
117
+ if (failed.length > 0)
118
+ return `; search index FAILED (${failed.map((i) => `${i.plugin}/${i.collection}: ${i.error ?? "no reason recorded"}`).join("; ")}) — Publish live is refused until a Stage builds it`;
119
+ if (pending.length > 0)
120
+ return `; search index still building (${pending.map((i) => `${i.plugin}/${i.collection}`).join(", ")}) — Publish live waits for it`;
121
+ return "; search index ready";
122
+ }
123
+
96
124
  export function describeStageRun(run: StageStatusRun): string {
97
125
  const n = (v: number) => v.toLocaleString("en-US");
98
126
  switch (run.phase) {
@@ -105,7 +133,7 @@ export function describeStageRun(run: StageStatusRun): string {
105
133
  case "publishing":
106
134
  return `All ${n(run.pagesTotal ?? 0)} pages built, publishing to staging — ${describeStageEta(run)}`;
107
135
  case "succeeded":
108
- return `Succeeded in ${formatStageDuration(run.elapsedMs)}${run.pagesTotal === null ? "" : ` (${n(run.pagesTotal)} pages)`}`;
136
+ return `Succeeded in ${formatStageDuration(run.elapsedMs)}${run.pagesTotal === null ? "" : ` (${n(run.pagesTotal)} pages)`}${describeSearchIndexes(run)}`;
109
137
  case "failed":
110
138
  return `Failed${run.failedPhase ? ` in ${run.failedPhase}` : ""} after ${formatStageDuration(run.elapsedMs)}: ${run.error ?? "no reason recorded"}`;
111
139
  }
package/src/version.ts CHANGED
@@ -22,7 +22,7 @@
22
22
  * follow standard SemVer.
23
23
  */
24
24
 
25
- export const CAELO_VERSION = "0.12.10";
25
+ export const CAELO_VERSION = "0.12.11";
26
26
 
27
27
  /**
28
28
  * Deprecated alias for back-compat — early P17 work spelled this
@@ -0,0 +1,86 @@
1
+ // SPDX-License-Identifier: MPL-2.0
2
+
3
+ /**
4
+ * Where a visitor's browser streams an AI conversation from (#1654).
5
+ *
6
+ * On `gcp` (load balancer) and self-hosted (Caddy) the site's own origin
7
+ * streams: `/api/*` reaches the gateway unbuffered. On `gcp-firebase` the
8
+ * Firebase Hosting rewrite of `/api/**` buffers a response until it ends,
9
+ * so the widget streams from the gateway's own run.app origin instead
10
+ * (with CORS for the site's origins), the one Cloud Run gives every
11
+ * service: `https://<service>-<project number>.<region>.run.app`.
12
+ *
13
+ * Nothing about it is configured: the service name and region are the
14
+ * env the install already sets (`CAELO_GATEWAY_SERVICE`,
15
+ * `CAELO_GATEWAY_REGION` on the admin; Cloud Run's own `K_SERVICE` on a
16
+ * gateway), the project number and region come from the metadata server
17
+ * of the Cloud Run instance. `CAELO_VISITOR_AI_STREAM_ORIGIN` overrides
18
+ * everything (tests, an install behind its own streaming proxy); an empty
19
+ * value means the site's own origin.
20
+ */
21
+
22
+ /** The override; empty: the site's own origin. */
23
+ export const VISITOR_AI_STREAM_ORIGIN_ENV = "CAELO_VISITOR_AI_STREAM_ORIGIN";
24
+
25
+ /** The deterministic URL Cloud Run gives a service. */
26
+ export function cloudRunServiceOrigin(
27
+ service: string,
28
+ projectNumber: string,
29
+ region: string,
30
+ ): string {
31
+ if (
32
+ !/^[a-z][a-z0-9-]{0,62}$/.test(service) ||
33
+ !/^\d{1,20}$/.test(projectNumber) ||
34
+ !/^[a-z]+-[a-z]+\d+$/.test(region)
35
+ )
36
+ throw new Error(`not a Cloud Run service address: ${service} / ${projectNumber} / ${region}`);
37
+ return `https://${service}-${projectNumber}.${region}.run.app`;
38
+ }
39
+
40
+ /** The project number and region of this Cloud Run instance, from the metadata server. */
41
+ export async function cloudRunInstanceLocation(
42
+ fetchFn: typeof fetch = fetch,
43
+ ): Promise<{ readonly projectNumber: string; readonly region: string }> {
44
+ const res = await fetchFn("http://metadata.google.internal/computeMetadata/v1/instance/region", {
45
+ headers: { "Metadata-Flavor": "Google" },
46
+ signal: AbortSignal.timeout(3000),
47
+ });
48
+ if (!res.ok) throw new Error(`metadata server: instance/region returned HTTP ${res.status}`);
49
+ // projects/<number>/regions/<region>
50
+ const m = /^projects\/(\d+)\/regions\/([a-z]+-[a-z]+\d+)$/.exec((await res.text()).trim());
51
+ if (!m) throw new Error("metadata server: instance/region has an unknown shape");
52
+ return { projectNumber: m[1] as string, region: m[2] as string };
53
+ }
54
+
55
+ /**
56
+ * The origin to stream from, or null for the site's own. `service` and
57
+ * `region` name the gateway (the admin's env); without `region` the
58
+ * instance's own (a gateway asking about itself). The staging gateway
59
+ * always streams on its own origin: it serves the staged site itself, with
60
+ * no Firebase rewrite in front to buffer, and its gate admits only requests
61
+ * carrying the operator's staging cookie, which a run.app request would not.
62
+ */
63
+ export async function visitorAiStreamOrigin(
64
+ env: Readonly<Record<string, string | undefined>>,
65
+ gateway: {
66
+ readonly service: string | undefined;
67
+ readonly region?: string | undefined;
68
+ readonly environment?: "live" | "staging";
69
+ },
70
+ fetchFn: typeof fetch = fetch,
71
+ ): Promise<string | null> {
72
+ const override = env[VISITOR_AI_STREAM_ORIGIN_ENV];
73
+ if (override !== undefined) return override.trim() === "" ? null : new URL(override).origin;
74
+ if (gateway.environment === "staging") return null;
75
+ if (env.CAELO_PROVIDER !== "gcp-firebase") return null;
76
+ if (!gateway.service)
77
+ throw new Error(
78
+ "gcp-firebase: the gateway's Cloud Run service is not named (CAELO_GATEWAY_SERVICE on the admin, K_SERVICE on the gateway); run `cms-provision upgrade`",
79
+ );
80
+ const where = await cloudRunInstanceLocation(fetchFn);
81
+ return cloudRunServiceOrigin(
82
+ gateway.service,
83
+ where.projectNumber,
84
+ gateway.region ?? where.region,
85
+ );
86
+ }