@caelo-cms/shared 0.10.21 → 0.10.23

package/src/translation.test.ts

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  buildModeOnePrompt,
+  buildModeTwoPrompt,
+  computeBlockDiff,
+  type GlossaryEntry,
+  type ModuleBlockSlot,
+  translationResultPayload,
+} from "./translation.js";
+
+const SLOT = (overrides: Partial<ModuleBlockSlot> = {}): ModuleBlockSlot => ({
+  blockName: "content",
+  position: 0,
+  moduleId: "11111111-1111-4111-8111-111111111111",
+  moduleSlug: "hero",
+  html: "<h1>Welcome</h1>",
+  altText: null,
+  caption: null,
+  ...overrides,
+});
+
+describe("computeBlockDiff", () => {
+  it("returns empty when source and variant align", () => {
+    const slot = SLOT();
+    expect(computeBlockDiff([slot], [slot])).toEqual([]);
+  });
+
+  it("emits changed when html differs", () => {
+    const source = SLOT({ html: "<h1>Welcome — updated</h1>" });
+    const variant = SLOT({ html: "<h1>Willkommen</h1>" });
+    const ops = computeBlockDiff([source], [variant]);
+    expect(ops.length).toBe(1);
+    const [op] = ops;
+    if (op?.kind !== "changed") throw new Error("expected changed");
+    expect(op.before.html).toBe("<h1>Willkommen</h1>");
+    expect(op.after.html).toBe("<h1>Welcome — updated</h1>");
+  });
+
+  it("emits added when source has a slot variant lacks", () => {
+    const source = [SLOT({ position: 0 }), SLOT({ position: 1, html: "<p>New</p>" })];
+    const variant = [SLOT({ position: 0 })];
+    const ops = computeBlockDiff(source, variant);
+    expect(ops.length).toBe(1);
+    expect(ops[0]?.kind).toBe("added");
+  });
+
+  it("emits removed when variant has a slot source lacks", () => {
+    const source = [SLOT({ position: 0 })];
+    const variant = [SLOT({ position: 0 }), SLOT({ position: 1, html: "<p>Stale</p>" })];
+    const ops = computeBlockDiff(source, variant);
+    expect(ops.length).toBe(1);
+    expect(ops[0]?.kind).toBe("removed");
+  });
+
+  it("matches by (blockName, position) — same blockName different position is added/removed", () => {
+    const source = [SLOT({ position: 0 })];
+    const variant = [SLOT({ position: 1 })];
+    const ops = computeBlockDiff(source, variant);
+    expect(ops.length).toBe(2);
+    expect(ops.map((o) => o.kind).sort()).toEqual(["added", "removed"]);
+  });
+
+  it("alt/caption changes count as changed", () => {
+    const source = SLOT({ altText: "A cat" });
+    const variant = SLOT({ altText: "Eine Katze" });
+    const ops = computeBlockDiff([source], [variant]);
+    expect(ops[0]?.kind).toBe("changed");
+  });
+});
+
+const GLOSSARY: GlossaryEntry[] = [
+  { sourceTerm: "Caelo", translation: "Caelo", context: "brand name — never translate" },
+  { sourceTerm: "CMS", translation: "CMS", context: null },
+];
+
+describe("buildModeOnePrompt", () => {
+  it("includes locale codes, structural lock, glossary, style guide", () => {
+    const { system, user } = buildModeOnePrompt({
+      sourceLocale: "en",
+      targetLocale: "de-AT",
+      targetLocaleDisplayName: "German (Austria)",
+      sourceModules: [SLOT()],
+      glossary: GLOSSARY,
+      styleGuide: "Use Sie form (formal).",
+    });
+    expect(system).toContain("Source locale: en");
+    expect(system).toContain("Target locale: de-AT (German (Austria))");
+    expect(system).toContain("STRUCTURAL LOCK");
+    expect(system).toContain("Caelo");
+    expect(system).toContain("Use Sie form");
+    expect(user).toContain("Welcome");
+  });
+
+  it("omits empty glossary block", () => {
+    const { system } = buildModeOnePrompt({
+      sourceLocale: "en",
+      targetLocale: "de",
+      sourceModules: [SLOT()],
+      glossary: [],
+      styleGuide: null,
+    });
+    expect(system).not.toContain("## Glossary");
+    expect(system).not.toContain("## Style guide");
+  });
+});
+
+describe("buildModeTwoPrompt", () => {
+  it("renders structured diff with before/after for changed blocks", () => {
+    const source = SLOT({ html: "<h1>Welcome — Spring sale</h1>" });
+    const variant = SLOT({ html: "<h1>Willkommen</h1>" });
+    const diff = computeBlockDiff([source], [variant]);
+    const { system, user } = buildModeTwoPrompt({
+      sourceLocale: "en",
+      targetLocale: "de",
+      sourceModules: [source],
+      variantModules: [variant],
+      diff,
+      glossary: [],
+      styleGuide: null,
+    });
+    expect(system).toContain("STRUCTURAL LOCK");
+    expect(system).toContain("Return ONE entry per CHANGED module");
+    expect(user).toContain("Existing translation");
+    expect(user).toContain("Willkommen"); // before
+    expect(user).toContain("Spring sale"); // after
+    expect(user).toContain("CHANGED");
+  });
+
+  it("renders empty diff hint when no ops", () => {
+    const slot = SLOT();
+    const { user } = buildModeTwoPrompt({
+      sourceLocale: "en",
+      targetLocale: "de",
+      sourceModules: [slot],
+      variantModules: [slot],
+      diff: [],
+      glossary: [],
+      styleGuide: null,
+    });
+    expect(user).toContain("no changes detected");
+  });
+});
+
+describe("translationResultPayload", () => {
+  it("accepts the expected AI output shape", () => {
+    const ok = translationResultPayload.safeParse({
+      modules: [{ blockName: "content", position: 0, html: "<h1>Willkommen</h1>", altText: null }],
+    });
+    expect(ok.success).toBe(true);
+  });
+
+  it("rejects unknown fields (.strict)", () => {
+    const bad = translationResultPayload.safeParse({
+      modules: [{ blockName: "content", position: 0, html: "<h1>x</h1>", extra: 1 }],
+    });
+    expect(bad.success).toBe(false);
+  });
+});

package/src/translation.ts

@@ -0,0 +1,295 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P10 — translation primitives shared between the AI prompt builder,
+ * the Mode 1 / Mode 2 op handlers, and the dashboard.
+ *
+ *   computeBlockDiff(source, variant) — block-level diff per
+ *     CMS_REQUIREMENTS §7.6: matches modules by (block_name, position),
+ *     returns typed `changed` / `added` / `removed` operations. Pure
+ *     function; the AI receives this as Mode 2 prompt context.
+ *
+ *   buildModeOnePrompt(...) / buildModeTwoPrompt(...) — assemble the
+ *     §7.6 sample-payload shapes with glossary + style guide injected.
+ *     Returns the prompt + a structured payload for unit-tests to
+ *     assert against.
+ */
+
+import { z } from "zod";
+
+export interface ModuleBlockSlot {
+  /** The block (e.g. "content", "header") this module sits in. */
+  blockName: string;
+  /** Position within the block. Blocks are ordered + 0-based. */
+  position: number;
+  /** Module id — locked across locales (translations share refs). */
+  moduleId: string;
+  /** Display name shown to the AI for context. */
+  moduleSlug: string;
+  /** The translatable fields of the module. P10 supports HTML body
+   * and three SEO-style metadata fields. Extend as new typed fields
+   * land (e.g. structured-content blocks in P12A). */
+  html: string;
+  altText: string | null;
+  caption: string | null;
+}
+
+export type BlockDiffOp =
+  | {
+      kind: "changed";
+      blockName: string;
+      position: number;
+      moduleId: string;
+      before: ModuleBlockSlot;
+      after: ModuleBlockSlot;
+    }
+  | { kind: "added"; blockName: string; position: number; module: ModuleBlockSlot }
+  | { kind: "removed"; blockName: string; position: number; module: ModuleBlockSlot };
+
+/**
+ * Diff a source page's modules against a variant's modules. Match by
+ * (blockName, position) — the §7.5 contract is that translations
+ * share STRUCTURE with the source (block + position alignment) and
+ * differ only in CONTENT (html / alt / caption per locale). Anything
+ * mis-aligned is `added` (source has it, variant doesn't) or
+ * `removed` (variant has it, source doesn't).
+ *
+ * `changed` rows contain BOTH before + after so the AI prompt can
+ * show the structured diff per the §7.6 sample payload.
+ */
+export function computeBlockDiff(
+  source: readonly ModuleBlockSlot[],
+  variant: readonly ModuleBlockSlot[],
+): BlockDiffOp[] {
+  const ops: BlockDiffOp[] = [];
+  const variantBy = new Map<string, ModuleBlockSlot>();
+  for (const v of variant) variantBy.set(`${v.blockName}|${v.position}`, v);
+  const sourceBy = new Map<string, ModuleBlockSlot>();
+  for (const s of source) sourceBy.set(`${s.blockName}|${s.position}`, s);
+
+  for (const s of source) {
+    const key = `${s.blockName}|${s.position}`;
+    const v = variantBy.get(key);
+    if (!v) {
+      ops.push({ kind: "added", blockName: s.blockName, position: s.position, module: s });
+      continue;
+    }
+    if (s.html !== v.html || s.altText !== v.altText || s.caption !== v.caption) {
+      ops.push({
+        kind: "changed",
+        blockName: s.blockName,
+        position: s.position,
+        moduleId: v.moduleId,
+        before: v,
+        after: s,
+      });
+    }
+  }
+  for (const v of variant) {
+    const key = `${v.blockName}|${v.position}`;
+    if (!sourceBy.has(key)) {
+      ops.push({ kind: "removed", blockName: v.blockName, position: v.position, module: v });
+    }
+  }
+  return ops;
+}
+
+// ---------------------------------------------------------------------
+// Prompt builders
+// ---------------------------------------------------------------------
+
+export interface GlossaryEntry {
+  sourceTerm: string;
+  translation: string;
+  context: string | null;
+}
+
+export interface ModeOnePromptInput {
+  /** Source-locale code (e.g. 'en'). */
+  sourceLocale: string;
+  /** Target locale code (e.g. 'de-AT'). */
+  targetLocale: string;
+  /** Optional locale displayName for context (e.g. "German (Austria)"). */
+  targetLocaleDisplayName?: string;
+  /** Source-page modules. The AI translates each per (blockName, position). */
+  sourceModules: readonly ModuleBlockSlot[];
+  glossary: readonly GlossaryEntry[];
+  styleGuide: string | null;
+}
+
+export interface ModeTwoPromptInput {
+  sourceLocale: string;
+  targetLocale: string;
+  targetLocaleDisplayName?: string;
+  sourceModules: readonly ModuleBlockSlot[];
+  /** The CURRENT variant — passed in full so the AI keeps the prior
+   * translation quality on unchanged blocks. */
+  variantModules: readonly ModuleBlockSlot[];
+  /** Pre-computed diff (call computeBlockDiff first). */
+  diff: readonly BlockDiffOp[];
+  glossary: readonly GlossaryEntry[];
+  styleGuide: string | null;
+}
+
+/**
+ * The AI returns this shape for both Mode 1 and Mode 2: one entry per
+ * source module slot, with the translated content fields. The handler
+ * matches entries back to the variant page's module rows by
+ * (blockName, position).
+ *
+ * Mode 1 returns one entry per source module.
+ * Mode 2 returns entries ONLY for changed blocks (preserves prior
+ *   translation on unchanged ones).
+ */
+export const translationResultModule = z
+  .object({
+    blockName: z.string().min(1),
+    position: z.number().int().min(0),
+    /** Translated module HTML body. */
+    html: z.string(),
+    altText: z.string().nullable().optional(),
+    caption: z.string().nullable().optional(),
+  })
+  .strict();
+
+export const translationResultPayload = z
+  .object({
+    modules: z.array(translationResultModule),
+  })
+  .strict();
+export type TranslationResultPayload = z.infer<typeof translationResultPayload>;
+
+function renderGlossaryBlock(glossary: readonly GlossaryEntry[]): string {
+  if (glossary.length === 0) return "";
+  const lines = glossary.map((g) =>
+    g.context
+      ? `- "${g.sourceTerm}" → "${g.translation}" (${g.context})`
+      : `- "${g.sourceTerm}" → "${g.translation}"`,
+  );
+  return ["", "## Glossary (use these exact translations)", ...lines].join("\n");
+}
+
+function renderStyleGuideBlock(styleGuide: string | null): string {
+  if (!styleGuide || styleGuide.trim().length === 0) return "";
+  return ["", "## Style guide", styleGuide.trim()].join("\n");
+}
+
+function renderSourceModulesBlock(modules: readonly ModuleBlockSlot[]): string {
+  const rendered = modules.map((m) => {
+    const parts = [
+      `### Module ${m.moduleSlug} (block=${m.blockName}, position=${m.position})`,
+      "HTML:",
+      "```html",
+      m.html,
+      "```",
+    ];
+    if (m.altText !== null) parts.push(`alt: ${m.altText}`);
+    if (m.caption !== null) parts.push(`caption: ${m.caption}`);
+    return parts.join("\n");
+  });
+  return rendered.join("\n\n");
+}
+
+export function buildModeOnePrompt(input: ModeOnePromptInput): {
+  system: string;
+  user: string;
+} {
+  const targetLabel = input.targetLocaleDisplayName ?? input.targetLocale;
+  const system = [
+    "You are translating a web page from one locale to another.",
+    `Source locale: ${input.sourceLocale}.`,
+    `Target locale: ${input.targetLocale} (${targetLabel}).`,
+    "",
+    "STRUCTURAL LOCK — the page's module layout (block names + positions) is identical across locales. You may NOT add, remove, or reorder modules. Translate ONLY the content fields (html, alt, caption) of each existing module.",
+    "",
+    "Translate every module listed below into the target locale. Preserve every HTML tag, attribute, class, id, href, and inline style verbatim — only the human-readable text inside tags + the alt/caption fields are translated. Numbers, code samples, and untranslatable proper nouns stay as-is.",
+    "",
+    'Respond with a JSON object matching: {"modules": [{"blockName": str, "position": int, "html": str, "altText": str|null, "caption": str|null}, ...]}. Return ONE entry per source module — same blockName + position.',
+    renderGlossaryBlock(input.glossary),
+    renderStyleGuideBlock(input.styleGuide),
+  ]
+    .filter((s) => s.length > 0)
+    .join("\n");
+  const user = [
+    `# Source page modules (${input.sourceLocale} → ${input.targetLocale})`,
+    "",
+    renderSourceModulesBlock(input.sourceModules),
+  ].join("\n");
+  return { system, user };
+}
+
+export function buildModeTwoPrompt(input: ModeTwoPromptInput): {
+  system: string;
+  user: string;
+} {
+  const targetLabel = input.targetLocaleDisplayName ?? input.targetLocale;
+  const changed = input.diff.filter((d) => d.kind === "changed");
+  const added = input.diff.filter((d) => d.kind === "added");
+  const removed = input.diff.filter((d) => d.kind === "removed");
+
+  const system = [
+    "You are updating an existing translation of a web page after the source changed.",
+    `Source locale: ${input.sourceLocale}.`,
+    `Target locale: ${input.targetLocale} (${targetLabel}).`,
+    "",
+    "STRUCTURAL LOCK — the page's module layout (block names + positions) is identical across locales. You may NOT add, remove, or reorder modules. Translate ONLY the content fields (html, alt, caption) that have CHANGED on the source. Preserve the existing translation verbatim for unchanged modules.",
+    "",
+    "Numbers, code samples, and untranslatable proper nouns stay as-is. Preserve every HTML tag/attribute/class/id/href/inline style in the source verbatim.",
+    "",
+    'Respond with a JSON object matching: {"modules": [{"blockName": str, "position": int, "html": str, "altText": str|null, "caption": str|null}, ...]}. Return ONE entry per CHANGED module — do NOT include unchanged modules in the response.',
+    renderGlossaryBlock(input.glossary),
+    renderStyleGuideBlock(input.styleGuide),
+  ]
+    .filter((s) => s.length > 0)
+    .join("\n");
+
+  const userLines: string[] = [
+    `# Update translation: ${input.sourceLocale} → ${input.targetLocale}`,
+    "",
+    "## Current source (full, for context)",
+    "",
+    renderSourceModulesBlock(input.sourceModules),
+    "",
+    "## Existing translation (preserve unchanged modules verbatim)",
+    "",
+    renderSourceModulesBlock(input.variantModules),
+    "",
+    "## Structured diff",
+  ];
+  if (changed.length === 0 && added.length === 0 && removed.length === 0) {
+    userLines.push("(no changes detected — return an empty `modules` array)");
+  }
+  for (const c of changed) {
+    if (c.kind !== "changed") continue;
+    userLines.push("");
+    userLines.push(
+      `### CHANGED — block=${c.blockName} position=${c.position} module=${c.moduleId}`,
+    );
+    userLines.push("Before (existing translation):");
+    userLines.push("```html");
+    userLines.push(c.before.html);
+    userLines.push("```");
+    userLines.push("Source after (current source HTML to re-translate):");
+    userLines.push("```html");
+    userLines.push(c.after.html);
+    userLines.push("```");
+  }
+  for (const a of added) {
+    if (a.kind !== "added") continue;
+    userLines.push("");
+    userLines.push(
+      `### ADDED in source — block=${a.blockName} position=${a.position} (must translate)`,
+    );
+    userLines.push("```html");
+    userLines.push(a.module.html);
+    userLines.push("```");
+  }
+  for (const r of removed) {
+    if (r.kind !== "removed") continue;
+    userLines.push("");
+    userLines.push(
+      `### REMOVED from source — block=${r.blockName} position=${r.position} (drop from the translation)`,
+    );
+  }
+  return { system, user: userLines.join("\n") };
+}

package/src/version.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P17.0 — single source of truth for the Caelo version.
+ *
+ * Bumped via `bun run scripts/release.ts <new-version>` which:
+ *   1. Updates this constant + the root package.json `version`,
+ *   2. Re-signs every Tier-1 plugin manifest under packages/plugins/,
+ *   3. Builds + writes the release notes via `scripts/release-notes.ts`,
+ *   4. Tags the commit as `vX.Y.Z`,
+ *   5. Pushes — GitHub Actions takes over for the publish step.
+ *
+ * Read by:
+ *   - admin's /security index page (header badge + about-modal),
+ *   - cms-provision CLI's `version` subcommand,
+ *   - User-Agent header on plugin-host's outbound HTTP calls,
+ *   - Tier-1 manifest signing (the version is hashed into the
+ *     signature payload so a manifest from version 0.5.0 can't be
+ *     replayed as a 0.6.0 manifest).
+ *
+ * Format: SemVer 2.0.0. Pre-1.0 minor bumps are breaking; post-1.0
+ * follow standard SemVer.
+ */
+
+export const CAELO_VERSION = "0.10.23";
+
+/**
+ * Deprecated alias for back-compat — early P17 work spelled this
+ * `CALEO_VERSION` (typo of "Caelo"). New code should import
+ * `CAELO_VERSION`. Kept as a re-export so external consumers of this
+ * published package (plugin authors / embedders) keep compiling;
+ * removal is deferred to the next major bump. Knip flags this as a
+ * duplicate export — suppressed in `knip.json#ignoreIssues` because the
+ * alias is intentional, mirroring `subagents.ts`.
+ *
+ * @deprecated use CAELO_VERSION
+ */
+export const CALEO_VERSION = CAELO_VERSION;
+
+/**
+ * Parsed shape — major/minor/patch + optional pre-release tag.
+ * Stable interface for callers that need to feature-gate (rare —
+ * Caelo doesn't do feature flags, but version-gating a deprecation
+ * warning is a legitimate use).
+ */
+export interface CaeloVersion {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  readonly preRelease: string | null;
+  readonly raw: string;
+}
+
+export function parseVersion(raw: string = CAELO_VERSION): CaeloVersion {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(raw);
+  if (!m) {
+    throw new Error(`invalid Caelo version: ${raw}`);
+  }
+  return {
+    major: Number.parseInt(m[1] ?? "0", 10),
+    minor: Number.parseInt(m[2] ?? "0", 10),
+    patch: Number.parseInt(m[3] ?? "0", 10),
+    preRelease: m[4] ?? null,
+    raw,
+  };
+}