@legionworks/facet 1.9.0

package/src/shared/errors/store-error.ts

@@ -0,0 +1,68 @@
+/**
+ * Store-layer typed error.
+ *
+ * `FacetStoreError` extends `FacetError` so the store's wire-relevant
+ * codes flow through `FacetError.from()` unchanged. The class lives
+ * here (not in `service/store/`) so both `facet-error.ts` and the store
+ * can reference it without an upward dependency from `shared/` to
+ * `service/`. The bridge is the inheritance: `instanceof FacetError`
+ * matches a `FacetStoreError`, the typed code + `retryable` + `details`
+ * are preserved, and the router's `statusFor()` arms become live.
+ */
+
+import { FacetError, type FacetErrorCode, type FacetErrorOptions } from "./facet-error";
+
+export type StoreErrorCode = Extract<
+  FacetErrorCode,
+  | "database_corrupt"
+  | "database_busy"
+  | "disk_full"
+  | "duplicate_revision"
+  | "foreign_key"
+  | "immutable_revision"
+  | "migration_failed"
+  | "invalid_artifact_type"
+  | "constraint"
+  | "revision_capacity_pinned"
+>;
+
+export class FacetStoreError extends FacetError {
+  override readonly name = "FacetStoreError" as const;
+
+  constructor(code: StoreErrorCode, message: string, options: FacetErrorOptions = {}) {
+    super(code, message, options);
+  }
+}
+
+/**
+ * Coerce any thrown value into a typed store error. Recognizes a
+ * pre-existing `FacetStoreError`; for a generic `Error` it string-matches
+ * the common SQLite failure messages to a specific store code. Any
+ * unrecognized error falls back to `constraint` (the generic catch-all
+ * that surfaces as a 409 on the wire).
+ */
+export function asStoreError(error: unknown): FacetStoreError {
+  if (error instanceof FacetStoreError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  const lower = message.toLowerCase();
+  if (
+    lower.includes("not a database") ||
+    lower.includes("malformed") ||
+    lower.includes("corrupt")
+  ) {
+    return new FacetStoreError("database_corrupt", message, { cause: error });
+  }
+  if (lower.includes("busy") || lower.includes("locked")) {
+    return new FacetStoreError("database_busy", message, { cause: error });
+  }
+  if (lower.includes("no space") || lower.includes("enospc") || lower.includes("disk full")) {
+    return new FacetStoreError("disk_full", message, { cause: error });
+  }
+  if (lower.includes("foreign key")) {
+    return new FacetStoreError("foreign_key", message, { cause: error });
+  }
+  if (lower.includes("unique constraint")) {
+    return new FacetStoreError("duplicate_revision", message, { cause: error });
+  }
+  return new FacetStoreError("constraint", message, { cause: error });
+}

package/src/shared/evidence-image.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+
+export const EvidenceImageFormatSchema = z.enum(["png", "webp"]);
+export type EvidenceImageFormat = z.infer<typeof EvidenceImageFormatSchema>;
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+export function sniffEvidenceImageFormat(bytes: Uint8Array): EvidenceImageFormat | null {
+  if (PNG_SIGNATURE.every((value, index) => bytes[index] === value)) return "png";
+  if (
+    bytes.length >= 12 &&
+    bytes[0] === 0x52 &&
+    bytes[1] === 0x49 &&
+    bytes[2] === 0x46 &&
+    bytes[3] === 0x46 &&
+    bytes[8] === 0x57 &&
+    bytes[9] === 0x45 &&
+    bytes[10] === 0x42 &&
+    bytes[11] === 0x50
+  )
+    return "webp";
+  return null;
+}
+
+export function mediaTypeForEvidenceImage(format: EvidenceImageFormat): "image/png" | "image/webp" {
+  return format === "png" ? "image/png" : "image/webp";
+}
+
+export function evidenceImageFormatForMediaType(mediaType: string): EvidenceImageFormat | null {
+  if (mediaType === "image/png") return "png";
+  if (mediaType === "image/webp") return "webp";
+  return null;
+}
+
+export function extensionForEvidenceImage(format: EvidenceImageFormat): ".png" | ".webp" {
+  return format === "png" ? ".png" : ".webp";
+}

package/src/shared/export.ts

@@ -0,0 +1,31 @@
+import type { ArtifactType } from "./contracts/artifact-types";
+import type { ExportFormat, ExportSidecar } from "./contracts/commands";
+import { ExportSidecarSchema } from "./contracts/commands/results";
+import { extensionForEvidenceImage, type EvidenceImageFormat } from "./evidence-image";
+
+const SOURCE_EXTENSION_BY_ARTIFACT = {
+  markdown: ".md",
+  mermaid: ".md",
+  svg: ".svg",
+  chart: ".json",
+  html: ".html",
+  tsx: ".tsx",
+} as const satisfies Record<ArtifactType, ".md" | ".svg" | ".json" | ".html" | ".tsx">;
+
+export function extensionForExport(
+  format: ExportFormat,
+  artifactType: ArtifactType,
+  renderFormat?: EvidenceImageFormat,
+): ".md" | ".svg" | ".json" | ".html" | ".tsx" | ".png" | ".webp" {
+  return format === "render"
+    ? extensionForEvidenceImage(renderFormat ?? "png")
+    : SOURCE_EXTENSION_BY_ARTIFACT[artifactType];
+}
+
+export function sidecarFilenameForArtifact(artifactPath: string): string {
+  return `${artifactPath}.facet.json`;
+}
+
+export function buildExportSidecar(input: ExportSidecar): ExportSidecar {
+  return ExportSidecarSchema.parse(input);
+}

package/src/shared/html/policy.ts

@@ -0,0 +1,108 @@
+export const HTML_DENIED_ELEMENTS = [
+  "script",
+  "iframe",
+  "object",
+  "embed",
+  "form",
+  "link",
+  "meta",
+  "base",
+  "style",
+] as const;
+
+export const HTML_STRUCTURAL_GROUPS = {
+  headings: ["h1", "h2", "h3", "h4", "h5", "h6"],
+  tables: ["table"],
+  lists: ["ul", "ol"],
+  images: ["img"],
+  canvases: ["canvas"],
+} as const;
+
+export const HTML_URL_BEARING_ATTRIBUTES = {
+  img: ["src", "srcset"],
+  source: ["srcset"],
+  a: ["href"],
+} as const;
+
+export const HTML_ALLOWED_ANCHOR_SCHEMES = ["https:", "mailto:"] as const;
+export const HTML_ALLOWED_IMAGE_SCHEMES = ["data:", "https:"] as const;
+
+type HtmlUrlBearingElement = keyof typeof HTML_URL_BEARING_ATTRIBUTES;
+
+function htmlUrlBearingElement(name: string): HtmlUrlBearingElement | null {
+  const normalized = name.toLowerCase();
+  return normalized in HTML_URL_BEARING_ATTRIBUTES ? (normalized as HtmlUrlBearingElement) : null;
+}
+
+export function isHtmlDeniedElement(name: string): boolean {
+  return (HTML_DENIED_ELEMENTS as readonly string[]).includes(name.toLowerCase());
+}
+
+export function isHtmlUrlBearingAttribute(elementName: string, attributeName: string): boolean {
+  const element = htmlUrlBearingElement(elementName);
+  return (
+    element !== null &&
+    HTML_URL_BEARING_ATTRIBUTES[element].includes(attributeName.toLowerCase() as never)
+  );
+}
+
+export function isHtmlUrlAttributeName(attributeName: string): boolean {
+  const normalized = attributeName.toLowerCase();
+  return Object.values(HTML_URL_BEARING_ATTRIBUTES).some((attributes) =>
+    attributes.includes(normalized as never),
+  );
+}
+
+export function isHtmlEventHandlerAttribute(name: string): boolean {
+  return name.toLowerCase().startsWith("on");
+}
+
+export function isHtmlInlineStyleAttribute(name: string): boolean {
+  return name.toLowerCase() === "style";
+}
+
+export function isAllowedHtmlUrl(
+  elementName: string,
+  attributeName: string,
+  value: string,
+): boolean {
+  const element = htmlUrlBearingElement(elementName);
+  if (element === null || !isHtmlUrlBearingAttribute(element, attributeName)) return false;
+  const trimmed = value.trim();
+  if (trimmed.startsWith("//")) return false;
+  let url: URL;
+  try {
+    url = new URL(trimmed, "https://facet.invalid/");
+  } catch {
+    return false;
+  }
+  const scheme = url.protocol.toLowerCase();
+  switch (element) {
+    case "img":
+    case "source":
+      if (scheme === "data:") return isImageDataUrl(url);
+      return (HTML_ALLOWED_IMAGE_SCHEMES as readonly string[]).includes(scheme);
+    case "a":
+      return (HTML_ALLOWED_ANCHOR_SCHEMES as readonly string[]).includes(scheme);
+    default: {
+      const _: never = element;
+      return _;
+    }
+  }
+}
+
+function isImageDataUrl(url: URL): boolean {
+  const comma = url.pathname.indexOf(",");
+  if (comma < 0) return false;
+  const metadata = url.pathname.slice(0, comma);
+  const separator = metadata.indexOf(";");
+  const encodedMediaType = (separator < 0 ? metadata : metadata.slice(0, separator)).trim();
+  let mediaType: string;
+  try {
+    mediaType = decodeURIComponent(encodedMediaType).toLowerCase();
+  } catch {
+    return false;
+  }
+  const parts = mediaType.split("/");
+  return parts.length === 2 && parts[0] === "image" && parts[1]!.length > 0;
+}

package/src/shared/html/style-vocabulary.ts

@@ -0,0 +1,352 @@
+export const HTML_TAILWIND_CLASSES = [
+  "block",
+  "flex",
+  "grid",
+  "inline-flex",
+  "flex-col",
+  "flex-wrap",
+  "items-center",
+  "justify-between",
+  "justify-center",
+  "grid-cols-1",
+  "grid-cols-2",
+  "grid-cols-3",
+  "gap-2",
+  "gap-3",
+  "gap-4",
+  "gap-6",
+  "p-2",
+  "p-3",
+  "p-4",
+  "p-6",
+  "px-3",
+  "px-4",
+  "py-2",
+  "py-3",
+  "m-0",
+  "mt-2",
+  "mt-4",
+  "mb-2",
+  "mb-4",
+  "w-full",
+  "max-w-prose",
+  "max-w-2xl",
+  "text-xs",
+  "text-sm",
+  "text-base",
+  "text-lg",
+  "text-xl",
+  "text-2xl",
+  "font-medium",
+  "font-semibold",
+  "font-bold",
+  "leading-relaxed",
+  "text-left",
+  "text-center",
+  "text-right",
+  "text-legion-ink",
+  "text-legion-muted",
+  "text-legion-cyan",
+  "bg-legion-paper",
+  "bg-legion-ink",
+  "bg-legion-cyan",
+  "border",
+  "border-2",
+  "border-legion-line",
+  "rounded",
+  "rounded-box",
+  "overflow-x-auto",
+  "table",
+  "table-zebra",
+] as const;
+
+export const HTML_DAISY_COMPONENTS = ["alert", "badge", "btn", "card", "stat", "table"] as const;
+
+const HTML_DAISY_BUILD_COMPONENT_CLASSES = [
+  "alert",
+  "aura",
+  "avatar",
+  "badge",
+  "breadcrumbs",
+  "btn",
+  "calendar",
+  "card",
+  "carousel",
+  "chat",
+  "checkbox",
+  "collapse",
+  "countdown",
+  "diff",
+  "divider",
+  "dock",
+  "drawer",
+  "dropdown",
+  "fab",
+  "fieldset",
+  "file-input",
+  "filter",
+  "footer",
+  "hero",
+  "hover-3d",
+  "hover-gallery",
+  "indicator",
+  "input",
+  "kbd",
+  "label",
+  "link",
+  "list",
+  "loading",
+  "mask",
+  "mega-menu",
+  "menu",
+  "mockup-browser",
+  "modal",
+  "navbar",
+  "input-otp",
+  "progress",
+  "radial-progress",
+  "radio",
+  "range",
+  "rating",
+  "select",
+  "skeleton",
+  "stack",
+  "stat",
+  "stats",
+  "status",
+  "steps",
+  "swap",
+  "tab",
+  "table",
+  "textarea",
+  "text-rotate",
+  "timeline",
+  "toast",
+  "toggle",
+  "tooltip",
+  "validator",
+] as const;
+
+const SPACING_VALUES = [
+  "0",
+  "0.5",
+  "1",
+  "1.5",
+  "2",
+  "2.5",
+  "3",
+  "3.5",
+  "4",
+  "5",
+  "6",
+  "7",
+  "8",
+  "9",
+  "10",
+  "11",
+  "12",
+  "14",
+  "16",
+] as const;
+
+const SPACING_PREFIXES = [
+  "p",
+  "px",
+  "py",
+  "pt",
+  "pr",
+  "pb",
+  "pl",
+  "m",
+  "mx",
+  "my",
+  "mt",
+  "mr",
+  "mb",
+  "ml",
+  "gap",
+  "gap-x",
+  "gap-y",
+] as const;
+
+const SEMANTIC_COLORS = [
+  "base-100",
+  "base-200",
+  "base-300",
+  "base-content",
+  "primary",
+  "primary-content",
+  "secondary",
+  "secondary-content",
+  "accent",
+  "accent-content",
+  "neutral",
+  "neutral-content",
+  "info",
+  "info-content",
+  "success",
+  "success-content",
+  "warning",
+  "warning-content",
+  "error",
+  "error-content",
+] as const;
+
+const STANDARD_COLORS = [
+  "slate-300",
+  "slate-500",
+  "slate-700",
+  "gray-300",
+  "gray-500",
+  "gray-700",
+  "blue-300",
+  "blue-500",
+  "blue-700",
+  "green-300",
+  "green-500",
+  "green-700",
+  "amber-300",
+  "amber-500",
+  "amber-700",
+  "red-300",
+  "red-500",
+  "red-700",
+  "white",
+  "black",
+] as const;
+
+const DAISY_COLOR_VARIANTS = [
+  "primary",
+  "secondary",
+  "accent",
+  "neutral",
+  "info",
+  "success",
+  "warning",
+  "error",
+] as const;
+
+const DAISY_COLOR_COMPONENTS = ["alert", "badge", "btn", "checkbox", "radio", "toggle"] as const;
+
+const DAISY_VARIANTS = [
+  "alert-soft",
+  "alert-outline",
+  "alert-vertical",
+  "alert-horizontal",
+  "badge-outline",
+  "badge-dash",
+  "badge-soft",
+  "badge-ghost",
+  "badge-xs",
+  "badge-sm",
+  "badge-md",
+  "badge-lg",
+  "badge-xl",
+  "btn-outline",
+  "btn-dash",
+  "btn-soft",
+  "btn-ghost",
+  "btn-link",
+  "btn-active",
+  "btn-xs",
+  "btn-sm",
+  "btn-md",
+  "btn-lg",
+  "btn-xl",
+  "card-border",
+  "card-dash",
+  "card-xs",
+  "card-sm",
+  "card-md",
+  "card-lg",
+  "card-xl",
+  "stats-horizontal",
+  "stats-vertical",
+  "table-zebra",
+  "table-pin-rows",
+  "table-pin-cols",
+  "table-xs",
+  "table-sm",
+  "table-md",
+  "table-lg",
+  "table-xl",
+] as const;
+
+export const HTML_TAILWIND_BUILD_CLASSES = [
+  ...HTML_TAILWIND_CLASSES,
+  ...HTML_DAISY_BUILD_COMPONENT_CLASSES,
+  ...SPACING_PREFIXES.flatMap((prefix) => SPACING_VALUES.map((value) => `${prefix}-${value}`)),
+  ...SEMANTIC_COLORS.flatMap((color) => [`bg-${color}`, `text-${color}`, `border-${color}`]),
+  ...STANDARD_COLORS.flatMap((color) => [`bg-${color}`, `text-${color}`, `border-${color}`]),
+  ...DAISY_COLOR_COMPONENTS.flatMap((component) =>
+    DAISY_COLOR_VARIANTS.map((variant) => `${component}-${variant}`),
+  ),
+  ...DAISY_VARIANTS,
+  "hidden",
+  "inline-block",
+  "inline-grid",
+  "flex-row",
+  "flex-1",
+  "flex-none",
+  "grow",
+  "shrink-0",
+  "items-start",
+  "items-end",
+  "justify-start",
+  "justify-end",
+  "justify-around",
+  "justify-evenly",
+  "content-start",
+  "content-center",
+  "self-start",
+  "self-center",
+  "self-end",
+  "grid-cols-4",
+  "grid-cols-5",
+  "grid-cols-6",
+  "col-span-2",
+  "col-span-3",
+  "col-span-full",
+  "w-auto",
+  "w-1/2",
+  "w-1/3",
+  "w-2/3",
+  "w-screen",
+  "min-w-0",
+  "max-w-none",
+  "max-w-sm",
+  "max-w-md",
+  "max-w-lg",
+  "max-w-xl",
+  "max-w-3xl",
+  "h-auto",
+  "h-full",
+  "min-h-screen",
+  "text-3xl",
+  "text-4xl",
+  "font-normal",
+  "font-extrabold",
+  "leading-tight",
+  "leading-normal",
+  "uppercase",
+  "lowercase",
+  "tracking-wide",
+  "shadow",
+  "shadow-sm",
+  "shadow-md",
+  "shadow-lg",
+  "rounded-sm",
+  "rounded-md",
+  "rounded-lg",
+  "rounded-xl",
+  "rounded-full",
+  "overflow-auto",
+  "overflow-hidden",
+  "overflow-y-auto",
+] as const;
+
+export const HTML_STYLE_CLASSES_DISTINCT = [
+  ...new Set<string>([...HTML_TAILWIND_CLASSES, ...HTML_DAISY_COMPONENTS]),
+] as const;
+
+export const HTML_STYLE_CLASSES = [...HTML_TAILWIND_CLASSES, ...HTML_DAISY_COMPONENTS] as const;

package/src/shared/logging/logger.ts

@@ -0,0 +1,108 @@
+/**
+ * Structured JSON logger.
+ *
+ * Diagnostics go to STDERR, ONE JSON object per line. STDOUT is reserved
+ * for CLI envelopes — never pollute it from here. Every payload is piped
+ * through `redact()` before serialization so a token accidentally logged
+ * inside a `details` block is scrubbed at the source.
+ *
+ * Required fields: level, event, component, timestamp, pid.
+ * Optional fields: requestId, artifactId, revisionSha, durationMs, errorCode,
+ * rssBytes, pssBytes, dbBytes, evidenceBytes.
+ */
+
+import { redact } from "./redact";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LoggerFields {
+  readonly requestId?: string;
+  readonly artifactId?: string;
+  readonly revisionSha?: string;
+  readonly durationMs?: number;
+  readonly errorCode?: string;
+  readonly rssBytes?: number | null;
+  readonly pssBytes?: number | null;
+  readonly dbBytes?: number;
+  readonly evidenceBytes?: number;
+  readonly [key: string]: unknown;
+}
+
+export interface FacetLoggerOptions {
+  readonly component: string;
+  readonly baseFields?: LoggerFields;
+}
+
+export interface FacetLogger {
+  debug(event: string, fields?: LoggerFields): void;
+  info(event: string, fields?: LoggerFields): void;
+  warn(event: string, fields?: LoggerFields): void;
+  error(event: string, fields?: LoggerFields): void;
+  child(component: string): FacetLogger;
+}
+
+class FacetLoggerImpl implements FacetLogger {
+  constructor(
+    private readonly component: string,
+    private readonly baseFields: LoggerFields = {},
+  ) {}
+
+  child(component: string): FacetLogger {
+    return new FacetLoggerImpl(component, this.baseFields);
+  }
+
+  debug(event: string, fields: LoggerFields = {}): void {
+    this.emit("debug", event, fields);
+  }
+  info(event: string, fields: LoggerFields = {}): void {
+    this.emit("info", event, fields);
+  }
+  warn(event: string, fields: LoggerFields = {}): void {
+    this.emit("warn", event, fields);
+  }
+  error(event: string, fields: LoggerFields = {}): void {
+    this.emit("error", event, fields);
+  }
+
+  private emit(level: LogLevel, event: string, fields: LoggerFields): void {
+    const merged: Record<string, unknown> = {
+      level,
+      event,
+      component: this.component,
+      timestamp: new Date().toISOString(),
+      pid: process.pid,
+      ...this.baseFields,
+      ...fields,
+    };
+    // drop undefined keys so JSON.stringify never emits "key":undefined
+    for (const [k, v] of Object.entries(merged)) {
+      if (v === undefined) delete merged[k];
+    }
+    const scrubbed = redact(merged);
+    process.stderr.write(`${JSON.stringify(scrubbed)}\n`);
+  }
+}
+
+export function createLogger(options: FacetLoggerOptions): FacetLogger {
+  return new FacetLoggerImpl(options.component, options.baseFields ?? {});
+}
+
+const QUIET_NOOP = (): void => {};
+
+/**
+ * No-op logger. Used by integration tests so the test gate is
+ * pristine — the real stderr logger spams JSON lines on every service
+ * event, which drowns the test reporter.
+ */
+export function createQuietLogger(
+  options: FacetLoggerOptions = { component: "test" },
+): FacetLogger {
+  void options;
+  return {
+    debug: QUIET_NOOP,
+    info: QUIET_NOOP,
+    warn: QUIET_NOOP,
+    error: QUIET_NOOP,
+    child: () => createQuietLogger(),
+  };
+}