@caelo-cms/shared 0.10.22 → 0.10.23

package/src/index.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MPL-2.0
+
+export const PROJECT_NAME = "caelo-cms";
+
+export * from "./ai-tools.js";
+export * from "./auth-forms.js";
+export * from "./base-css.js";
+export * from "./build-page.js";
+export * from "./cap-failures.js";
+export * from "./content.js";
+export * from "./context.js";
+export * from "./css-gradient-scan.js";
+export * from "./css-var-scan.js";
+export * from "./design-manifest.js";
+export * from "./fonts.js";
+export * from "./genesis.js";
+export * from "./genesis-inventory.js";
+export * from "./i18n.js";
+export * from "./interactions.js";
+export {
+  type LogContext,
+  type Logger,
+  type LoggerOptions,
+  type LogLevel,
+  makeLogger,
+  mintRequestId,
+  redact,
+  type ServiceName,
+  type StructuredLogEntry,
+} from "./logger.js";
+export * from "./media.js";
+export * from "./page-log.js";
+export * from "./preview-compose.js";
+export * from "./preview-scanner.js";
+export * from "./proposal-status.js";
+export * from "./responsive-images.js";
+export * from "./result.js";
+export * from "./safe-keys.js";
+export * from "./seo.js";
+export * from "./skills.js";
+export * from "./snapshots.js";
+export * from "./strip-cdata.js";
+export * from "./structured-sets.js";
+export * from "./subagents.js";
+export * from "./template-engine.js";
+export * from "./theme-importers/auto-detect.js";
+export * from "./theme-importers/dtcg.js";
+export * from "./theme-importers/loose.js";
+export * from "./theme-importers/shadcn.js";
+export * from "./theme-importers/style-dictionary.js";
+export * from "./theme-importers/tailwind.js";
+export * from "./theme-literal-binding.js";
+export * from "./theme-normalize.js";
+export * from "./theme-ramp.js";
+export * from "./theme-render.js";
+export * from "./themes.js";
+export * from "./themes-errors.js";
+export * from "./translation.js";
+export { CAELO_VERSION, CALEO_VERSION, type CaeloVersion, parseVersion } from "./version.js";

package/src/interactions.ts

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #160 — the vetted interaction baseline (epic #149).
+ *
+ * A header without a working mobile menu reads as broken, not minimal
+ * — and hand-rolled per-module JS gets focus/aria handling wrong more
+ * often than right. This module carries the FUNCTIONAL (non-aesthetic)
+ * CSS + JS for the built-in nav renderer: hamburger toggle under the
+ * mobile breakpoint, `aria-expanded` bookkeeping, escape-to-close.
+ * All colors/spacing stay the module/theme's business — these rules
+ * only govern show/hide behaviour, so they don't violate the
+ * no-global-look re-scope (#151).
+ *
+ * The composer includes each asset ONCE per page when at least one
+ * nav-menu module rendered (natural dedup, same rule as #158).
+ */
+
+/** Functional-only rules: collapse/expand mechanics, zero aesthetics. */
+export const NAV_FUNCTIONAL_CSS =
+  ".caelo-nav-menu .caelo-nav-toggle{display:none;background:none;border:0;cursor:pointer;padding:0.5rem;color:inherit;font:inherit}" +
+  ".caelo-nav-menu .caelo-nav-toggle .caelo-nav-bar{display:block;width:1.25em;height:2px;background:currentColor;margin:0.25em 0}" +
+  "@media (max-width: 720px){" +
+  ".caelo-nav-menu .caelo-nav-toggle{display:inline-block}" +
+  ".caelo-nav-menu > ul{display:none}" +
+  '.caelo-nav-menu[data-nav-open="true"] > ul{display:block}' +
+  "}";
+
+/**
+ * Toggle behaviour. Runs deferred; idempotent per element via the
+ * data attribute; closes on Escape and returns focus to the toggle.
+ */
+export const NAV_TOGGLE_JS =
+  "(function(){" +
+  "document.querySelectorAll('.caelo-nav-menu').forEach(function(nav){" +
+  "var btn=nav.querySelector('.caelo-nav-toggle');if(!btn)return;" +
+  "btn.addEventListener('click',function(){" +
+  "var open=nav.getAttribute('data-nav-open')==='true';" +
+  "nav.setAttribute('data-nav-open',String(!open));" +
+  "btn.setAttribute('aria-expanded',String(!open));" +
+  "});" +
+  "nav.addEventListener('keydown',function(e){" +
+  "if(e.key==='Escape'&&nav.getAttribute('data-nav-open')==='true'){" +
+  "nav.setAttribute('data-nav-open','false');" +
+  "btn.setAttribute('aria-expanded','false');btn.focus();" +
+  "}});" +
+  "});" +
+  "})();";

package/src/logger.ts

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P16 — structured logger. JSON-per-line to stderr; the host environment
+ * (operator's log aggregator: Loki/Datadog/CloudWatch/etc.) ships from
+ * there. Stable shape across every Caelo service so a single
+ * `request_id` query reconstructs the full timeline.
+ *
+ * Redaction pass replaces values for keys matching common-secret regex
+ * with `***` so a stray `{password: "..."}` extra never lands in logs.
+ *
+ * NOT a replacement for `audit_events` — audit captures intent (op,
+ * actor, succeeded), structured logs capture trace (request_id,
+ * service-to-service hops, latency, errors). Cross-correlate via the
+ * shared `request_id` column.
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export type ServiceName = "admin" | "gateway" | "orchestrator" | "plugin-host" | "static-gen";
+
+export interface LogContext {
+  readonly requestId: string;
+  readonly actorId?: string;
+  readonly actorKind?: "human" | "ai" | "system" | "plugin";
+  readonly opName?: string;
+  readonly chatSessionId?: string;
+  readonly pluginSlug?: string;
+}
+
+export interface StructuredLogEntry {
+  readonly ts: string;
+  readonly level: LogLevel;
+  readonly msg: string;
+  readonly service: ServiceName;
+  readonly env: string;
+  readonly ctx: LogContext;
+  readonly extra?: Record<string, unknown>;
+}
+
+// Word-anchored — without the boundaries `key` would match `monkey`,
+// `token` would match `tokenizer`, `secret` would match `secretary`.
+// Whole-key match is the right semantic for log-field redaction.
+const SECRET_KEY_RE =
+  /^(password|passwd|secret|secrets|token|tokens|api[-_]?key|api[-_]?keys|cookie|cookies|authorization|bearer|x[-_]api[-_]?key|csrf[-_]?secret|cookie[-_]?secret)$/i;
+
+export function redact(input: unknown): unknown {
+  if (input === null || typeof input !== "object") return input;
+  if (Array.isArray(input)) return input.map(redact);
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(input)) {
+    if (SECRET_KEY_RE.test(k)) {
+      out[k] = "***";
+    } else if (v && typeof v === "object") {
+      out[k] = redact(v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export interface Logger {
+  with(ctx: Partial<LogContext>): Logger;
+  debug(msg: string, extra?: Record<string, unknown>): void;
+  info(msg: string, extra?: Record<string, unknown>): void;
+  warn(msg: string, extra?: Record<string, unknown>): void;
+  error(msg: string, extra?: Record<string, unknown>): void;
+}
+
+export interface LoggerOptions {
+  readonly service: ServiceName;
+  readonly env?: string;
+  /** Defaults to console.error so structured logs flow to stderr. */
+  readonly sink?: (entry: StructuredLogEntry) => void;
+  /** Minimum level to emit; default 'info' (suppresses 'debug'). */
+  readonly minLevel?: LogLevel;
+}
+
+const LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+export function makeLogger(opts: LoggerOptions): Logger {
+  const env = opts.env ?? process.env.CAELO_ENV ?? "dev";
+  const minRank = LEVEL_RANK[opts.minLevel ?? "info"];
+  const sink =
+    opts.sink ??
+    ((entry: StructuredLogEntry) => {
+      process.stderr.write(`${JSON.stringify(entry)}\n`);
+    });
+
+  function emit(
+    ctx: LogContext,
+    level: LogLevel,
+    msg: string,
+    extra?: Record<string, unknown>,
+  ): void {
+    if (LEVEL_RANK[level] < minRank) return;
+    const entry: StructuredLogEntry = {
+      ts: new Date().toISOString(),
+      level,
+      msg,
+      service: opts.service,
+      env,
+      ctx,
+      extra: extra ? (redact(extra) as Record<string, unknown>) : undefined,
+    };
+    sink(entry);
+  }
+
+  function buildLogger(ctx: LogContext): Logger {
+    return {
+      with(extraCtx) {
+        return buildLogger({ ...ctx, ...extraCtx });
+      },
+      debug(msg, extra) {
+        emit(ctx, "debug", msg, extra);
+      },
+      info(msg, extra) {
+        emit(ctx, "info", msg, extra);
+      },
+      warn(msg, extra) {
+        emit(ctx, "warn", msg, extra);
+      },
+      error(msg, extra) {
+        emit(ctx, "error", msg, extra);
+      },
+    };
+  }
+
+  // Default ctx has a synthetic request_id so a logger created outside
+  // of any request boundary still produces correlatable output (visible
+  // in the log stream as `synthetic-…`).
+  return buildLogger({ requestId: `synthetic-${crypto.randomUUID().slice(0, 8)}` });
+}
+
+/**
+ * Mint a fresh request_id at a request boundary. Caller threads through
+ * ExecutionContext + outbound HTTP headers (`X-Caelo-Request-Id`).
+ */
+export function mintRequestId(): string {
+  return crypto.randomUUID();
+}

package/src/media.test.ts

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import {
+  buildMediaUrl,
+  buildStorageKey,
+  extractMediaRefs,
+  MEDIA_ALLOWED_MIMES,
+  MEDIA_HARD_LIMIT_BYTES,
+  MEDIA_SIZE_CAPS,
+  MEDIA_VARIANT_TAGS,
+  MEDIA_VARIANT_WIDTHS,
+  mediaListInputSchema,
+  mediaSetCdnInputSchema,
+  mediaUploadInputSchema,
+  slugifyMediaName,
+} from "./media.js";
+
+describe("media URL helpers", () => {
+  it("builds a slug URL: orig is flat, named variants nest under the slug", () => {
+    expect(buildMediaUrl("searchviu-logo", "orig")).toBe("/_caelo/media/searchviu-logo");
+    expect(buildMediaUrl("searchviu-hero", "webp-800")).toBe(
+      "/_caelo/media/searchviu-hero/webp-800",
+    );
+  });
+
+  it("extracts slug refs (orig implied when flat) deduped", () => {
+    const html = `
+      <img src="/_caelo/media/searchviu-hero/webp-800" alt="x" />
+      <img src="/_caelo/media/searchviu-hero/webp-800" alt="y" />
+      <img src="/_caelo/media/searchviu-logo" />
+    `;
+    expect(extractMediaRefs(html)).toEqual([
+      { ref: "searchviu-hero", isSlug: true, variant: "webp-800" },
+      { ref: "searchviu-logo", isSlug: true, variant: "orig" },
+    ]);
+  });
+
+  it("still parses the legacy /_caelo/media/<uuid>/<variant> form as an id ref", () => {
+    const html = `
+      <img src="/_caelo/media/short-slug/webp-800" />
+      <img src="/_caelo/media/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa/square-800" />
+    `;
+    expect(extractMediaRefs(html)).toEqual([
+      { ref: "short-slug", isSlug: true, variant: "webp-800" },
+      { ref: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", isSlug: false, variant: "square-800" },
+    ]);
+  });
+
+  it("slugifies a human label: accents stripped, kebab-cased, extension dropped", () => {
+    expect(slugifyMediaName("SearchVIU Logo.png")).toBe("searchviu-logo");
+    expect(slugifyMediaName("Über uns – Team!")).toBe("uber-uns-team");
+    expect(slugifyMediaName("   ")).toBe("image");
+    expect(slugifyMediaName("a".repeat(80)).length).toBeLessThanOrEqual(60);
+  });
+
+  it("buildStorageKey is sha-prefixed", () => {
+    expect(buildStorageKey("abc123", "webp-800", "webp")).toBe("abc123/webp-800.webp");
+  });
+});
+
+describe("media size caps + allowlist", () => {
+  it("each allowed MIME has a positive size cap below the hard limit", () => {
+    for (const m of MEDIA_ALLOWED_MIMES) {
+      const cap = MEDIA_SIZE_CAPS[m];
+      expect(cap).toBeGreaterThan(0);
+      expect(cap).toBeLessThanOrEqual(MEDIA_HARD_LIMIT_BYTES);
+    }
+  });
+
+  it("variant widths cover the non-orig tags only", () => {
+    for (const t of MEDIA_VARIANT_TAGS) {
+      if (t === "orig") continue;
+      expect(MEDIA_VARIANT_WIDTHS[t]).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("media schemas", () => {
+  it("mediaUploadInputSchema accepts a minimal valid payload", () => {
+    const r = mediaUploadInputSchema.safeParse({
+      sha256: "a".repeat(64),
+      originalName: "hero.jpg",
+      mime: "image/jpeg",
+      sizeBytes: 1024,
+      width: 1920,
+      height: 1080,
+      alt: "",
+      storageKey: `${"a".repeat(64)}/orig.jpg`,
+      variants: [
+        {
+          variant: "orig",
+          format: "jpeg",
+          width: 1920,
+          height: 1080,
+          sizeBytes: 1024,
+          storageKey: `${"a".repeat(64)}/orig.jpg`,
+        },
+      ],
+    });
+    expect(r.success).toBe(true);
+  });
+
+  it("mediaUploadInputSchema rejects non-hex sha256", () => {
+    const r = mediaUploadInputSchema.safeParse({
+      sha256: "not-a-sha",
+      originalName: "x",
+      mime: "image/jpeg",
+      sizeBytes: 1,
+      width: null,
+      height: null,
+      storageKey: "x",
+      variants: [
+        {
+          variant: "orig",
+          format: "jpeg",
+          width: null,
+          height: null,
+          sizeBytes: 1,
+          storageKey: "x",
+        },
+      ],
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("mediaUploadInputSchema rejects unknown MIME", () => {
+    const r = mediaUploadInputSchema.safeParse({
+      sha256: "a".repeat(64),
+      originalName: "x",
+      mime: "application/zip",
+      sizeBytes: 1,
+      width: null,
+      height: null,
+      storageKey: "x",
+      variants: [
+        {
+          variant: "orig",
+          format: "jpeg",
+          width: null,
+          height: null,
+          sizeBytes: 1,
+          storageKey: "x",
+        },
+      ],
+    });
+    expect(r.success).toBe(false);
+  });
+
+  it("mediaListInputSchema defaults sort=recent and limit=60", () => {
+    const r = mediaListInputSchema.parse({});
+    expect(r.sort).toBe("recent");
+    expect(r.limit).toBe(60);
+    expect(r.offset).toBe(0);
+  });
+
+  it("mediaSetCdnInputSchema rejects threshold below 1", () => {
+    expect(mediaSetCdnInputSchema.safeParse({ enabled: true, threshold: 0 }).success).toBe(false);
+  });
+});