@caelo-cms/shared 0.10.21 → 0.10.23

package/src/theme-importers/auto-detect.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * v0.11.1 (issue #76) — theme import format auto-detection chain.
+ *
+ * Tries each importer in priority order:
+ *
+ *   1. DTCG (most specific: `$value` leaves)
+ *   2. Style Dictionary (`value` leaves)
+ *   3. Tailwind 4 (`@theme { … }` block)
+ *   4. shadcn (`:root { … }` CSS variables)
+ *   5. Loose key-value (`{looseName: value}` JSON object)
+ *
+ * The first importer that doesn't throw a "shape" rejection wins.
+ * "Hard" parse errors (e.g. TailwindImportError for calc()) surface
+ * verbatim — they signal the input WAS that format but unparseable.
+ *
+ * Returns `{format, tokens}` so the caller's tool result can echo the
+ * detected format back to the AI for next-turn awareness.
+ */
+
+import type { ThemeDocument } from "../themes.js";
+import {
+  NoImporterMatched,
+  NotDtcgShape,
+  NotLooseShape,
+  NotShadcnShape,
+  NotStyleDictionaryShape,
+  NotTailwindShape,
+} from "../themes-errors.js";
+import { importDtcg } from "./dtcg.js";
+import { importLoose } from "./loose.js";
+import { importShadcn } from "./shadcn.js";
+import { importStyleDictionary } from "./style-dictionary.js";
+import { importTailwind } from "./tailwind.js";
+
+export type DetectedFormat = "dtcg" | "style-dictionary" | "tailwind" | "shadcn" | "loose";
+
+export interface AutoDetectResult {
+  readonly format: DetectedFormat;
+  readonly tokens: ThemeDocument;
+}
+
+interface ImporterDef {
+  readonly format: DetectedFormat;
+  readonly importer: (body: string) => ThemeDocument;
+  /** When true, the auto-detect chain falls through on this error class. */
+  readonly fallThroughOn: ReadonlyArray<new (...args: never[]) => Error>;
+}
+
+const CHAIN: readonly ImporterDef[] = [
+  { format: "dtcg", importer: importDtcg, fallThroughOn: [NotDtcgShape] },
+  {
+    format: "style-dictionary",
+    importer: importStyleDictionary,
+    fallThroughOn: [NotStyleDictionaryShape],
+  },
+  { format: "tailwind", importer: importTailwind, fallThroughOn: [NotTailwindShape] },
+  { format: "shadcn", importer: importShadcn, fallThroughOn: [NotShadcnShape] },
+  { format: "loose", importer: importLoose, fallThroughOn: [NotLooseShape] },
+];
+
+export function autoDetectAndImport(body: string): AutoDetectResult {
+  const attempts: Array<{ format: string; reason: string }> = [];
+  for (const def of CHAIN) {
+    try {
+      const tokens = def.importer(body);
+      return { format: def.format, tokens };
+    } catch (e) {
+      const isFallThrough = def.fallThroughOn.some((cls) => e instanceof cls);
+      if (!isFallThrough) {
+        // Hard error: the input WAS in this format but the importer
+        // can't handle it. Surface verbatim so the operator/AI gets a
+        // concrete fix-it.
+        throw e;
+      }
+      attempts.push({
+        format: def.format,
+        reason: e instanceof Error ? (e.message.split("\n")[0] ?? "rejected") : "rejected",
+      });
+    }
+  }
+  throw new NoImporterMatched(attempts);
+}

package/src/theme-importers/css-comments.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Strip `/* … *\/` block comments from a CSS string.
+ *
+ * The body uses a "tempered dot" (`(?:(?!\*\/)[\s\S])*`) rather than a lazy
+ * `[\s\S]*?`: the lazy form backtracks O(n²) on an unterminated comment in
+ * untrusted theme CSS (CodeQL js/polynomial-redos). The tempered form has a
+ * single unambiguous match path and stops at the first `*\/`, so the output
+ * is identical to the lazy form on valid CSS. Single-sourced here so the two
+ * theme importers (tailwind, shadcn) cannot drift to a vulnerable variant.
+ */
+export function stripCssComments(css: string): string {
+  return css.replace(/\/\*(?:(?!\*\/)[\s\S])*\*\//g, "");
+}

package/src/theme-importers/dtcg.ts

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * v0.11.0 — DTCG (W3C Design Tokens Format) import / export for the
+ * `themes` primitive (#45 Phase 7 slice 1).
+ *
+ * The full format-auto-detect (Style Dictionary / Tailwind 4 @theme /
+ * shadcn `:root` / loose key-value) is v0.11.2 — see the follow-up
+ * comment §4 on #45. This slice ships the DTCG side only so design
+ * tooling (Figma, Tokens Studio, Style Dictionary) round-trips cleanly
+ * from day one.
+ *
+ * The shape we accept IS the same shape `themes.tokens` jsonb carries,
+ * because `themes.ts`'s Zod schema mirrors DTCG. So `importDtcg` is
+ * essentially `JSON.parse + validateThemeTokens`; `exportDtcg` returns
+ * the stored tokens jsonb after stable-stringification. The wrappers
+ * exist so we have explicit entry points to grow Style-Dictionary /
+ * Tailwind / shadcn / loose parsers next to in v0.11.2 without
+ * widening `themes.ts`.
+ */
+
+import { type Theme, type ThemeDocument, validateThemeTokens } from "../themes.js";
+import { NotDtcgShape } from "../themes-errors.js";
+
+/**
+ * Parse a DTCG JSON document into a validated tokens tree. Three
+ * failure surfaces:
+ *
+ *   1. Malformed JSON         → `DTCG parse failed: <SyntaxError msg>`
+ *   2. Valid JSON, no `$value` anywhere → `NotDtcgShape` (round-2
+ *      opt §2: pre-Zod sniff for the common case where the operator
+ *      pastes a Tailwind / Style Dictionary / Figma export and the
+ *      AI sees a deeply-nested Zod path mismatch instead of a clear
+ *      "this isn't DTCG" hint).
+ *   3. Valid JSON, has $value leaves, but Zod rejects something → the
+ *      ZodError surfaces verbatim (per-token path mismatch, missing
+ *      composite sub-field, etc.).
+ */
+export function importDtcg(body: string): ThemeDocument {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`DTCG parse failed: ${msg}`);
+  }
+  if (!hasAnyDollarValue(parsed)) {
+    throw new NotDtcgShape();
+  }
+  return validateThemeTokens(parsed);
+}
+
+/**
+ * Walks the parsed tree once, returns true as soon as ANY leaf object
+ * carries a `$value` key. Cheap O(n) over the parsed structure — same
+ * shape Zod will walk anyway during full validation, just early-exits.
+ * Treats arrays as nested containers so a shadow-layer array of
+ * composite values still sniffs as DTCG.
+ */
+function hasAnyDollarValue(node: unknown): boolean {
+  if (node === null || typeof node !== "object") return false;
+  if (Array.isArray(node)) return node.some(hasAnyDollarValue);
+  const obj = node as Record<string, unknown>;
+  if ("$value" in obj) return true;
+  for (const v of Object.values(obj)) {
+    if (hasAnyDollarValue(v)) return true;
+  }
+  return false;
+}
+
+/**
+ * Emit a stable DTCG JSON document for the given theme. Keys are
+ * sorted alphabetically at every nesting level so the output is
+ * byte-for-byte deterministic — Style Dictionary / Tokens Studio diff
+ * cleanly under git.
+ *
+ * Only `tokens` is exported; asset URLs and the `is_active` flag are
+ * Caelo-specific and have no DTCG representation. Operators bind
+ * assets through `set_theme_asset`, not through an exported JSON file.
+ */
+export function exportDtcg(theme: Pick<Theme, "tokens">): string {
+  return `${JSON.stringify(sortDeep(theme.tokens), null, 2)}\n`;
+}
+
+function sortDeep(value: unknown): unknown {
+  if (value === null) return null;
+  if (Array.isArray(value)) return value.map(sortDeep);
+  if (typeof value !== "object") return value;
+  const obj = value as Record<string, unknown>;
+  const sortedKeys = Object.keys(obj).sort((a, b) => {
+    // DTCG convention: $-prefixed metadata keys ($value, $type,
+    // $description, $extensions) sort BEFORE plain group keys so a
+    // leaf renders with its metadata up top, then its sub-references
+    // (if any) below. Within each tier keys sort alphabetically.
+    const aDollar = a.startsWith("$");
+    const bDollar = b.startsWith("$");
+    if (aDollar && !bDollar) return -1;
+    if (!aDollar && bDollar) return 1;
+    return a.localeCompare(b);
+  });
+  const out: Record<string, unknown> = {};
+  for (const k of sortedKeys) {
+    out[k] = sortDeep(obj[k]);
+  }
+  return out;
+}

package/src/theme-importers/loose.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * v0.11.1 (issue #76) — loose key-value JSON object importer.
+ *
+ * Accepts a flat JSON object of `{looseName: value}` pairs and runs
+ * each entry through `normalizeTokens` + `applyDtcgWrites` so the
+ * result lands at canonical DTCG paths. This is the same path
+ * `themes.update_tokens` uses for AI-supplied input — extracted here
+ * so `import_theme` can offer a "paste a flat object, server figures
+ * out where each one goes" surface.
+ *
+ * The importer starts from an empty document so it produces a complete
+ * tokens tree (no existing tokens merged in). Callers wanting a patch
+ * use `themes.update_tokens` directly.
+ */
+
+import { normalizeTokens } from "../theme-normalize.js";
+import { applyDtcgWrites, type ThemeDocument, validateThemeTokens } from "../themes.js";
+import { NotLooseShape } from "../themes-errors.js";
+
+export function importLoose(body: string): ThemeDocument {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new NotLooseShape(`loose-format parse failed: ${msg}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new NotLooseShape("loose-format input must be a JSON object");
+  }
+  // Reject inputs that are clearly other formats so auto-detect doesn't
+  // accidentally swallow them at the last hop.
+  if (hasNestedDollarValue(parsed) || hasNestedPlainValue(parsed)) {
+    throw new NotLooseShape(
+      "input has nested `$value` / `value` leaves — looks like DTCG or Style Dictionary, not loose",
+    );
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  if (Object.keys(obj).length === 0) {
+    throw new NotLooseShape("loose-format input is an empty object");
+  }
+  // Normalize loose names → canonical paths (throws UnknownTokenName on
+  // ambiguity, per the v0.11.0 normalizer's failure surface).
+  const normalized = normalizeTokens(obj);
+  // Apply to an empty document so the result is a complete tokens tree.
+  const written = applyDtcgWrites({}, normalized.set, normalized.types);
+  return validateThemeTokens(written);
+}
+
+function hasNestedDollarValue(node: unknown): boolean {
+  if (node === null || typeof node !== "object" || Array.isArray(node)) return false;
+  const obj = node as Record<string, unknown>;
+  for (const [k, v] of Object.entries(obj)) {
+    if (k === "$value") return true;
+    if (typeof v === "object" && v !== null && hasNestedDollarValue(v)) return true;
+  }
+  return false;
+}
+
+function hasNestedPlainValue(node: unknown): boolean {
+  if (node === null || typeof node !== "object" || Array.isArray(node)) return false;
+  const obj = node as Record<string, unknown>;
+  // A "Style Dictionary leaf" looks like `{value: <primitive>, ...}` —
+  // not a top-level flat key whose value is a primitive.
+  for (const v of Object.values(obj)) {
+    if (v && typeof v === "object" && !Array.isArray(v)) {
+      const inner = v as Record<string, unknown>;
+      if ("value" in inner && typeof inner.value !== "object") return true;
+      if (hasNestedPlainValue(v)) return true;
+    }
+  }
+  return false;
+}

package/src/theme-importers/shadcn.ts

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * v0.11.1 (issue #76) — shadcn CSS-variable importer.
+ *
+ * shadcn-style themes ship as a `:root { … }` (+ optional `.dark { … }`)
+ * block of unprefixed CSS variables:
+ *
+ *   :root {
+ *     --background: 0 0% 100%;
+ *     --primary: 222.2 47.4% 11.2%;
+ *     --primary-foreground: 210 40% 98%;
+ *   }
+ *   .dark {
+ *     --background: 222.2 84% 4.9%;
+ *     --primary: 210 40% 98%;
+ *   }
+ *
+ * Each unprefixed name maps to `color.<name>` (shadcn variables are
+ * exclusively colors today — typography/spacing live in Tailwind config).
+ * When both blocks exist, paired names land as `{light, dark}` composite
+ * color values; lone names emit flat values.
+ */
+
+import { type ThemeDocument, validateThemeTokens } from "../themes.js";
+import { NotShadcnShape } from "../themes-errors.js";
+import { stripCssComments } from "./css-comments.js";
+
+interface CssVarMap {
+  readonly [name: string]: string;
+}
+
+export function importShadcn(body: string): ThemeDocument {
+  // Quick rejections so the auto-detect chain can fall through fast.
+  if (/"value"\s*:/i.test(body)) {
+    throw new NotShadcnShape('input contains `"value":` — looks like Style Dictionary JSON');
+  }
+  const lightBlock = extractBlock(body, ":root");
+  if (lightBlock === null) {
+    throw new NotShadcnShape();
+  }
+  const lightVars = parseCssVars(lightBlock);
+  if (Object.keys(lightVars).length === 0) {
+    throw new NotShadcnShape(":root block found but no `--name: value;` pairs inside");
+  }
+  const darkBlock = extractBlock(body, ".dark");
+  const darkVars = darkBlock === null ? null : parseCssVars(darkBlock);
+
+  const color: Record<string, unknown> = {};
+  for (const [name, lightVal] of Object.entries(lightVars)) {
+    const wrapped = wrapColorValue(lightVal);
+    if (darkVars && darkVars[name] !== undefined) {
+      color[name] = {
+        $value: { light: wrapped, dark: wrapColorValue(darkVars[name]) },
+        $type: "color",
+      };
+    } else {
+      color[name] = { $value: wrapped, $type: "color" };
+    }
+  }
+  // Surface dark-only names too (no light counterpart). Rare but real
+  // when an operator splits brand variants across blocks.
+  if (darkVars) {
+    for (const [name, darkVal] of Object.entries(darkVars)) {
+      if (name in color) continue;
+      color[name] = { $value: wrapColorValue(darkVal), $type: "color" };
+    }
+  }
+
+  const doc: ThemeDocument = { color };
+  return validateThemeTokens(doc);
+}
+
+/**
+ * Find a selector block (e.g. `:root` or `.dark`) and return the body
+ * inside the matching braces. Strips block comments before matching.
+ */
+function extractBlock(body: string, selector: string): string | null {
+  const stripped = stripCssComments(body);
+  // Escape regex specials in the selector (`.` for `.dark`).
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`${escaped}\\s*\\{`).exec(stripped);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  let depth = 1;
+  let i = start;
+  while (i < stripped.length && depth > 0) {
+    const ch = stripped[i];
+    if (ch === "{") depth += 1;
+    else if (ch === "}") depth -= 1;
+    if (depth === 0) break;
+    i += 1;
+  }
+  if (depth !== 0) return null;
+  return stripped.slice(start, i);
+}
+
+function parseCssVars(block: string): CssVarMap {
+  const out: Record<string, string> = {};
+  for (const raw of block.split(";")) {
+    const line = raw.trim();
+    if (line.length === 0 || !line.startsWith("--")) continue;
+    const colonIdx = line.indexOf(":");
+    if (colonIdx <= 0) continue;
+    const name = line.slice(2, colonIdx).trim();
+    const value = line.slice(colonIdx + 1).trim();
+    if (name.length === 0 || value.length === 0) continue;
+    out[name] = value;
+  }
+  return out;
+}
+
+/**
+ * shadcn often stores HSL channels without the `hsl(...)` wrapper
+ * (`--primary: 222.2 47.4% 11.2%`). Detect that shape and wrap so the
+ * resulting value is a valid CSS color string the renderer / browser
+ * can use directly. Hex / oklch / rgb / hsl(...) values pass through
+ * unchanged.
+ */
+function wrapColorValue(raw: string): string {
+  const trimmed = raw.trim();
+  // Already a recognised CSS color → pass through.
+  if (/^#[0-9a-fA-F]{3,8}$/.test(trimmed)) return trimmed;
+  if (/^(oklch|rgb|rgba|hsl|hsla|lab|lch|color|hwb)\s*\(/i.test(trimmed)) return trimmed;
+  if (/^(transparent|currentColor)$/i.test(trimmed)) return trimmed;
+  // Three space-separated tokens with a `%` somewhere → shadcn HSL triple.
+  if (/^\d+(\.\d+)?\s+\d+(\.\d+)?%\s+\d+(\.\d+)?%$/.test(trimmed)) {
+    return `hsl(${trimmed})`;
+  }
+  // Bare named color or anything else — pass through; the Zod schema
+  // will catch genuinely-broken inputs at validateThemeTokens.
+  return trimmed;
+}

package/src/theme-importers/style-dictionary.ts

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * v0.11.1 (issue #76) — Style Dictionary v3/v4 importer.
+ *
+ * Style Dictionary stores tokens as `{ value: "…", attributes?: {…} }`
+ * leaves instead of DTCG's `$value` / `$type`. This importer walks the
+ * tree, rewrites `value` → `$value` (and `type` → `$type` where set),
+ * preserves `attributes` blocks under `$extensions.styleDictionary`,
+ * and feeds the result through `validateThemeTokens` for round-trip
+ * compatibility with the DTCG storage shape.
+ *
+ * Recognition heuristic: input must be valid JSON with at least one
+ * nested `{ value: … }` leaf and NO `$value` keys (the latter would
+ * indicate DTCG — the auto-detect chain handles priority).
+ */
+
+import { type ThemeDocument, validateThemeTokens } from "../themes.js";
+import { NotStyleDictionaryShape } from "../themes-errors.js";
+
+export function importStyleDictionary(body: string): ThemeDocument {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new NotStyleDictionaryShape(`Style Dictionary parse failed: ${msg}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new NotStyleDictionaryShape("Style Dictionary input must be a JSON object");
+  }
+  if (hasDollarValue(parsed)) {
+    throw new NotStyleDictionaryShape(
+      "input has `$value` leaves — looks like DTCG, not Style Dictionary",
+    );
+  }
+  if (!hasPlainValue(parsed)) {
+    throw new NotStyleDictionaryShape(
+      "input has no `{ value: … }` leaves typical of Style Dictionary",
+    );
+  }
+  const dtcg = rewriteSdToDtcg(parsed);
+  // Top-level Style Dictionary categories may not exactly match DTCG
+  // (e.g. `size` instead of `spacing`); rename common cases so the
+  // resulting document validates and renders correctly.
+  const renamed = renameTopLevelCategories(dtcg);
+  return validateThemeTokens(renamed);
+}
+
+function hasDollarValue(node: unknown): boolean {
+  if (node === null || typeof node !== "object") return false;
+  if (Array.isArray(node)) return node.some(hasDollarValue);
+  const obj = node as Record<string, unknown>;
+  if ("$value" in obj) return true;
+  for (const v of Object.values(obj)) {
+    if (hasDollarValue(v)) return true;
+  }
+  return false;
+}
+
+function hasPlainValue(node: unknown): boolean {
+  if (node === null || typeof node !== "object") return false;
+  if (Array.isArray(node)) return node.some(hasPlainValue);
+  const obj = node as Record<string, unknown>;
+  // A leaf in Style Dictionary has `value` AND no nested object siblings
+  // carrying their own value. Detecting "has value somewhere" is enough
+  // for the auto-detect sniff; full validation happens in rewriteSdToDtcg.
+  if ("value" in obj && typeof obj.value !== "object") return true;
+  for (const v of Object.values(obj)) {
+    if (hasPlainValue(v)) return true;
+  }
+  return false;
+}
+
+function rewriteSdToDtcg(node: unknown): unknown {
+  if (node === null || typeof node !== "object" || Array.isArray(node)) return node;
+  const obj = node as Record<string, unknown>;
+  // Leaf detection: has `value` but no nested children that themselves
+  // have `value` (deepest-first rewrite).
+  if ("value" in obj && typeof obj.value !== "object") {
+    const leaf: Record<string, unknown> = { $value: obj.value };
+    if ("type" in obj && typeof obj.type === "string") {
+      leaf.$type = obj.type;
+    }
+    if ("description" in obj && typeof obj.description === "string") {
+      leaf.$description = obj.description;
+    }
+    if ("attributes" in obj && obj.attributes && typeof obj.attributes === "object") {
+      leaf.$extensions = { styleDictionary: { attributes: obj.attributes } };
+    }
+    return leaf;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    out[k] = rewriteSdToDtcg(v);
+  }
+  return out;
+}
+
+/**
+ * Common Style Dictionary category name → DTCG category map. Only
+ * applied at the root; nested groups keep their original names.
+ */
+const SD_TO_DTCG_CATEGORY: Record<string, string> = {
+  size: "spacing",
+  sizes: "spacing",
+  spaces: "spacing",
+  colors: "color",
+  fonts: "typography",
+  font: "typography",
+  shadows: "shadow",
+  radii: "radius",
+  borderRadius: "radius",
+};
+
+function renameTopLevelCategories(doc: unknown): unknown {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return doc;
+  const obj = doc as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    const renamed = SD_TO_DTCG_CATEGORY[k];
+    out[renamed ?? k] = v;
+  }
+  return out;
+}