@legionworks/facet 1.9.0

package/src/shared/build/frame-bundle-plugins.ts

@@ -0,0 +1,61 @@
+/**
+ * Bun.build plugins shared by every frame-bundle build (gallery frame
+ * bootstrap + Tier 1 verifier harness).
+ *
+ * The dompurify alias points `import "dompurify"` at the frame shim,
+ * which re-instantiates DOMPurify against the frame's own window. The
+ * import-time default instance captures unbound Document methods from
+ * whatever global the bundler resolved; inlined into a srcdoc bundle
+ * those throw `Illegal invocation` at sanitize time. The shim import
+ * itself is excluded from the alias so it resolves the real package.
+ */
+
+import { basename, join } from "node:path";
+
+/**
+ * Minimal shape of `Bun.build`'s plugin object — the public Bun type
+ * does not export `BunBuildPlugin` (only `BunPlugin` and the inferred
+ * shape from the bundler overloads), so we declare the surface this
+ * module uses. The `setup` callback receives the live build handle and
+ * a per-resolution args bag; both are inferred from the API.
+ */
+interface BunBuildPlugin {
+  readonly name: string;
+  setup(build: {
+    onResolve(
+      filter: { readonly filter: RegExp },
+      callback: (args: {
+        readonly path: string;
+        readonly importer: string;
+      }) => { readonly path: string } | undefined,
+    ): void;
+  }): void;
+}
+
+const DOMPURIFY_SHIM_PATH = join(
+  import.meta.dir,
+  "..",
+  "..",
+  "gallery-web",
+  "frame",
+  "renderers",
+  "dompurify-shim.ts",
+);
+
+export function frameBundlePlugins(): BunBuildPlugin[] {
+  return [
+    {
+      name: "facet-dom-purify-frame-alias",
+      setup(build) {
+        build.onResolve({ filter: /^dompurify$/ }, (args) => {
+          // The shim's OWN import must resolve to the real package.
+          // Bun reports the importer through symlink-copied paths
+          // (e.g. /tmp/node_modules/…), so match by basename, not by
+          // exact path.
+          if (basename(args.importer) === "dompurify-shim.ts") return undefined;
+          return { path: DOMPURIFY_SHIM_PATH };
+        });
+      },
+    },
+  ];
+}

package/src/shared/build-mode.ts

@@ -0,0 +1,28 @@
+export type ServiceLaunch =
+  | {
+      readonly mode: "source";
+      readonly entrypoint: string;
+      readonly tier0RunnerPath: string;
+      readonly tier1RunnerPath: string;
+    }
+  | { readonly mode: "compiled" };
+
+export type Tier0WorkerCommand =
+  | { readonly mode: "source"; readonly entrypoint: string }
+  | { readonly mode: "compiled" };
+
+const BUN_COMPILED_FILESYSTEM_PREFIX = "/$bunfs/";
+
+export function isCompiledRuntime(): boolean {
+  return Bun.main.startsWith(BUN_COMPILED_FILESYSTEM_PREFIX);
+}
+
+export function isCompiledEntrypointArg(argv: readonly string[]): boolean {
+  return argv[0] === "--facet-internal-service" || argv[0] === "--facet-internal-tier0-worker";
+}
+
+export function buildTier0WorkerArgs(command: Tier0WorkerCommand): string[] {
+  return command.mode === "compiled"
+    ? ["--facet-internal-tier0-worker"]
+    : ["run", command.entrypoint];
+}

package/src/shared/config/evidence-read.ts

@@ -0,0 +1,98 @@
+/**
+ * Evidence-root read resolution.
+ *
+ * The service is the only writer of evidence; the CLI and the export path
+ * are readers. After explicit evidence-root threading, both agree on ONE
+ * canonical root. But default-XDG installs that ran before the threading
+ * wrote evidence under a legacy child-derived root
+ * (`legacyXdgEvidenceRoot`), so readers must tolerate the divergence:
+ * when the canonical root holds no evidence AND the legacy root does, reads
+ * ALSO fall back to the legacy root. Writes never go there — the fallback is
+ * read-only and the canonical root is authoritative for everything new.
+ */
+
+import { readdirSync, statSync } from "node:fs";
+
+export interface EvidenceReadRoot {
+  readonly path: string;
+  /** True when this root is the legacy fallback, false for the canonical root. */
+  readonly legacy: boolean;
+}
+
+export interface EvidenceFs {
+  /** True when `path` exists and holds at least one non-empty file (recursively). */
+  hasEvidence(path: string): boolean;
+}
+
+/**
+ * Recursively true when `path` exists and contains at least one file with
+ * non-zero size. An empty or missing directory is "no evidence".
+ */
+export function directoryHasEvidence(path: string): boolean {
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch {
+    return false;
+  }
+  if (stat.isFile()) return stat.size > 0;
+  if (!stat.isDirectory()) return false;
+  let entries: string[];
+  try {
+    entries = readdirSync(path);
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (directoryHasEvidence(`${path}/${entry}`)) return true;
+  }
+  return false;
+}
+
+/**
+ * Ordered roots a reader should consult. The canonical root is always first;
+ * the legacy root is appended only when the canonical root holds no evidence
+ * while the legacy root does (the pre-threading migration case). Callers that
+ * see a `legacy: true` root should log once and must never write to it.
+ */
+export function resolveEvidenceReadRoots(
+  canonical: string,
+  legacy: string | null,
+  fs: EvidenceFs = { hasEvidence: directoryHasEvidence },
+): EvidenceReadRoot[] {
+  const roots: EvidenceReadRoot[] = [{ path: canonical, legacy: false }];
+  if (
+    legacy !== null &&
+    legacy !== canonical &&
+    !fs.hasEvidence(canonical) &&
+    fs.hasEvidence(legacy)
+  ) {
+    roots.push({ path: legacy, legacy: true });
+  }
+  return roots;
+}
+
+/** Total byte count of evidence across the resolved read roots. */
+export function evidenceBytesAcross(roots: readonly EvidenceReadRoot[]): number {
+  let total = 0;
+  for (const root of roots) total += directoryBytes(root.path);
+  return total;
+}
+
+function directoryBytes(path: string): number {
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch {
+    return 0;
+  }
+  if (stat.isFile()) return stat.size;
+  if (!stat.isDirectory()) return 0;
+  let total = 0;
+  try {
+    for (const entry of readdirSync(path)) total += directoryBytes(`${path}/${entry}`);
+  } catch {
+    // unreadable directory counts as zero
+  }
+  return total;
+}

package/src/shared/config/limits.ts

@@ -0,0 +1,56 @@
+/**
+ * Hard cap on artifact source bytes per ADR 0001 D2. Benchmarks measured
+ * 20/20 clean renders through 5 MB inside the 200 ms visibility budget;
+ * 10 MB breaches it. Renderer-complexity guards are separate from this
+ * cap and live alongside it (see below).
+ */
+export const SOURCE_CAP_BYTES = 5 * 1024 * 1024;
+
+/**
+ * Pinned Chrome for Testing build used by the Tier 1 verifier. Browser-pin
+ * changes must re-check opaque-origin storage isolation, sandbox navigation
+ * limits, `connect-src 'none'`, and nonce-only script execution.
+ */
+export const TIER1_PINNED_VERSION = "151.0.7922.77";
+
+/** Acceptance commands must outlive the Tier 1 verifier and return its typed verdict. */
+export const ACCEPTANCE_TEST_BUDGET_MS = 90_000;
+
+/**
+ * Lexical guard: at most this many ```mermaid fenced blocks in one
+ * artifact. Larger graphs hit the mermaid parser's own limits and
+ * produce unreadable SVGs.
+ */
+export const MAX_MERMAID_BLOCKS = 64;
+
+/**
+ * Lexical guard: at most this many `N<digits>[...]` node declarations
+ * across all mermaid blocks in one artifact. Bounds the rendered DOM
+ * size independent of source byte count.
+ */
+export const MAX_MERMAID_NODES = 10_000;
+
+/**
+ * Bounds HTML token nesting before parse5 tree construction. At 10,000 nested
+ * elements, Tier 0 measured about 100 ms locally, leaving wide margin below
+ * the five-second worker timeout.
+ */
+export const MAX_HTML_NESTING_DEPTH = 10_000;
+
+/** Default in-memory cap for list responses. */
+export const DEFAULT_LIST_LIMIT = 50;
+export const MAX_LIST_LIMIT = 500;
+
+/**
+ * Lexical guard: max bytes in a single SVG artifact. Bounds the render
+ * time on the Tier 1 verifier independent of the source cap (an SVG
+ * can be small in bytes but enormous in DOM).
+ */
+export const MAX_SVG_BYTES = 1 * 1024 * 1024;
+
+/**
+ * Lexical guard: max top-level `<svg>` elements in a single SVG
+ * artifact. Forged pages cannot add more than this without inflating
+ * the verifier's own SVG count past the lexical expectation.
+ */
+export const MAX_SVG_ROOTS = 16;

package/src/shared/config/paths.ts

@@ -0,0 +1,96 @@
+import { accessSync, constants } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * All runtime paths the service writes to. Pure path computation — no
+ * filesystem effects. Callers (the database opener, the validation
+ * harness) own the actual mkdir/chmod calls so the path layer can be
+ * exercised in tests without touching the disk.
+ */
+export interface FacetRuntimePaths {
+  /** Persistent state: the SQLite database (with its WAL/SHM sidecars). */
+  readonly database: string;
+  /** Per-run evidence: screenshots, console captures, request logs. */
+  readonly evidence: string;
+  /** Long-lived secret material: the promote-capability token. */
+  readonly token: string;
+  /** Cross-process lock guarding single-writer sections. */
+  readonly lock: string;
+  /** Free-form metadata (project name, gallery title, etc.). */
+  readonly metadata: string;
+}
+
+export interface FacetPathEnvironment {
+  readonly facetHome?: string;
+  readonly xdgDataHome?: string;
+  readonly xdgStateHome?: string;
+  readonly xdgConfigHome?: string;
+  readonly xdgCacheHome?: string;
+}
+
+const FALLBACK_XDG_DATA = `${process.env.HOME ?? ""}/.local/share`;
+const FALLBACK_XDG_STATE = `${process.env.HOME ?? ""}/.local/state`;
+const FALLBACK_XDG_CONFIG = `${process.env.HOME ?? ""}/.config`;
+const FALLBACK_XDG_CACHE = `${process.env.HOME ?? ""}/.cache`;
+
+/**
+ * Resolve generated gallery assets to the checkout when it can be written,
+ * otherwise use the operator-owned cache so installed packages stay immutable.
+ */
+export function resolveGalleryRoot(packageRoot: string, env: FacetPathEnvironment = {}): string {
+  try {
+    accessSync(packageRoot, constants.W_OK);
+    return join(packageRoot, "dist", "gallery");
+  } catch {
+    const facetHome = env.facetHome ?? process.env.FACET_HOME;
+    if (facetHome) return join(facetHome, "cache", "gallery");
+    const cacheHome = env.xdgCacheHome ?? process.env.XDG_CACHE_HOME ?? FALLBACK_XDG_CACHE;
+    return join(cacheHome, "facet", "gallery");
+  }
+}
+
+/**
+ * Compute the five runtime paths. XDG-style: data/state/configurable
+ * each have their own override; `facetHome` (or `FACET_HOME`) wins
+ * outright when set so operators can run a fully self-contained
+ * install without polluting their home directory.
+ */
+export function computeFacetPaths(env: FacetPathEnvironment = {}): FacetRuntimePaths {
+  const facetHome = env.facetHome ?? process.env.FACET_HOME;
+  if (facetHome) {
+    return {
+      database: join(facetHome, "db", "facet.sqlite"),
+      evidence: join(facetHome, "evidence"),
+      token: join(facetHome, "secrets", "promote.token"),
+      lock: join(facetHome, "run", "facet.lock"),
+      metadata: join(facetHome, "metadata.json"),
+    };
+  }
+  const dataHome = env.xdgDataHome ?? process.env.XDG_DATA_HOME ?? FALLBACK_XDG_DATA;
+  const stateHome = env.xdgStateHome ?? process.env.XDG_STATE_HOME ?? FALLBACK_XDG_STATE;
+  const configHome = env.xdgConfigHome ?? process.env.XDG_CONFIG_HOME ?? FALLBACK_XDG_CONFIG;
+  return {
+    database: join(dataHome, "facet", "db", "facet.sqlite"),
+    evidence: join(stateHome, "facet", "evidence"),
+    token: join(dataHome, "facet", "secrets", "promote.token"),
+    lock: join(stateHome, "facet", "run", "facet.lock"),
+    metadata: join(configHome, "facet", "metadata.json"),
+  };
+}
+
+/**
+ * Legacy evidence root for XDG-default installs predating explicit
+ * evidence-root threading. Before the parent CLI passed its evidence root
+ * to the service child, the child derived its paths from
+ * `FACET_HOME = <dataHome>/facet` (see `spawnChild`) and wrote evidence to
+ * `<dataHome>/facet/evidence`, while the parent read
+ * `<stateHome>/facet/evidence`. Returns that child-derived root in XDG mode
+ * so readers can tolerate the divergence; returns null when `FACET_HOME` is
+ * set (that mode never diverged — parent and child always agreed).
+ */
+export function legacyXdgEvidenceRoot(env: FacetPathEnvironment = {}): string | null {
+  const facetHome = env.facetHome ?? process.env.FACET_HOME;
+  if (facetHome) return null;
+  const dataHome = env.xdgDataHome ?? process.env.XDG_DATA_HOME ?? FALLBACK_XDG_DATA;
+  return join(dataHome, "facet", "evidence");
+}

package/src/shared/contracts/artifact-types.ts

@@ -0,0 +1,2 @@
+export const ARTIFACT_TYPES = ["markdown", "mermaid", "svg", "chart", "html", "tsx"] as const;
+export type ArtifactType = (typeof ARTIFACT_TYPES)[number];

package/src/shared/contracts/artifact.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+
+import { TSX_EXECUTION_MODES } from "../tsx/execution";
+import { ARTIFACT_TYPES } from "./artifact-types";
+import { RENDERERS } from "./renderers";
+import { EvidenceImageFormatSchema } from "../evidence-image";
+
+export { ARTIFACT_TYPES, type ArtifactType } from "./artifact-types";
+export { RENDERERS, type Renderer } from "./renderers";
+export const ArtifactTypeSchema = z.enum(ARTIFACT_TYPES);
+export const RendererSchema = z.enum(RENDERERS);
+
+const IdSchema = z.string().min(1);
+const IsoTimestampSchema = z.string().datetime({ offset: true });
+const Sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+const ByteSourceSchema = z.instanceof(Uint8Array);
+
+export const ProjectSchema = z.object({
+  id: IdSchema,
+  projectRoot: z.string().min(1),
+  createdAt: IsoTimestampSchema,
+});
+export type Project = z.infer<typeof ProjectSchema>;
+
+export const ArtifactSchema = z.object({
+  id: IdSchema,
+  projectId: IdSchema,
+  slug: z.string().min(1),
+  title: z.string().min(1),
+  createdAt: IsoTimestampSchema,
+  updatedAt: IsoTimestampSchema,
+});
+export type Artifact = z.infer<typeof ArtifactSchema>;
+
+export const RevisionSchema = z.object({
+  id: IdSchema,
+  artifactId: IdSchema,
+  revisionNumber: z.number().int().positive(),
+  parentRevisionId: IdSchema.nullable(),
+  artifactType: ArtifactTypeSchema,
+  renderer: RendererSchema,
+  source: ByteSourceSchema,
+  sha256: Sha256Schema,
+  note: z.string().nullable(),
+  pinned: z.boolean(),
+  createdAt: IsoTimestampSchema,
+  /**
+   * TSX execution mode (D2). Only present for `artifactType === "tsx"`
+   * — every other type stores `'static'` on disk but the field is
+   * absent from the wire form (the dispatch is explicit: `execution`
+   * must be absent, not null, for non-TSX artifacts). Derived from
+   * the canonical `TSX_EXECUTION_MODES` array so a new mode lands in
+   * one place.
+   */
+  execution: z.enum(TSX_EXECUTION_MODES).optional(),
+});
+export type Revision = z.infer<typeof RevisionSchema>;
+
+export const RenderRunSchema = z.object({
+  id: IdSchema,
+  revisionId: IdSchema,
+  tier: z.union([z.literal(0), z.literal(1)]),
+  status: z.string().min(1),
+  expectedJson: z.string(),
+  observedJson: z.string(),
+  screenshotPath: z.string().nullable(),
+  screenshotFormat: EvidenceImageFormatSchema.nullable(),
+  consolePath: z.string().nullable(),
+  /**
+   * TSX compiled-bundle evidence (D7). The compiled bundle is derived
+   * output stored alongside the run, not a wire form — `null` for
+   * non-TSX runs and for TSX runs whose compilation did not produce
+   * a retained file.
+   */
+  compiledPath: z.string().nullable().optional(),
+  screenshotErrorJson: z.string().nullable(),
+  insecureJson: z.string().nullable(),
+  /**
+   * Retained-evidence carve-out: `true` exempts the row from the
+   * last-N retention eviction. Pin/template call sites mark rows
+   * retained; the cleanup policy skips them.
+   */
+  retained: z.boolean(),
+  startedAt: IsoTimestampSchema,
+  finishedAt: IsoTimestampSchema,
+});
+export type RenderRun = z.infer<typeof RenderRunSchema>;
+
+export const TemplateSchema = z.object({
+  id: IdSchema,
+  artifactId: IdSchema,
+  revisionId: IdSchema,
+  name: z.string().min(1),
+  description: z.string().nullable(),
+  promotedBy: z.string().min(1),
+  promotedAt: IsoTimestampSchema,
+});
+export type Template = z.infer<typeof TemplateSchema>;

package/src/shared/contracts/commands/_shared.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+import { TSX_EXECUTION_MODES } from "../../tsx/execution";
+import { ArtifactTypeSchema, RendererSchema, TemplateSchema } from "../artifact";
+
+/**
+ * Shared wire-envelope schemas reused by every command verb's request
+ * and result. Kept in one place so a typo in `requestId` or a SHA
+ * regex drift is fixed in a single file.
+ */
+export const ArtifactEnvelopeSchema = z.object({
+  id: z.string().min(1),
+  projectId: z.string().min(1),
+  slug: z.string().min(1),
+  title: z.string().min(1),
+  createdAt: z.string().datetime({ offset: true }),
+  updatedAt: z.string().datetime({ offset: true }),
+});
+export type ArtifactEnvelope = z.infer<typeof ArtifactEnvelopeSchema>;
+
+export const RevisionEnvelopeSchema = z.object({
+  id: z.string().min(1),
+  artifactId: z.string().min(1),
+  revisionNumber: z.number().int().positive(),
+  parentRevisionId: z.string().min(1).nullable(),
+  artifactType: ArtifactTypeSchema,
+  renderer: RendererSchema,
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  note: z.string().nullable(),
+  pinned: z.boolean(),
+  createdAt: z.string().datetime({ offset: true }),
+  /**
+   * TSX execution mode (D2). Omitted from the wire for every non-TSX
+   * artifact type so existing wire fixtures stay byte-identical after
+   * the TSX arc lands. The service emits this key only when the
+   * revision's `artifactType` is `"tsx"`. Derived from the canonical
+   * `TSX_EXECUTION_MODES` array so a new mode lands in one place.
+   */
+  execution: z.enum(TSX_EXECUTION_MODES).optional(),
+});
+export type RevisionEnvelope = z.infer<typeof RevisionEnvelopeSchema>;
+
+export const TemplateEnvelopeSchema = TemplateSchema;
+export type TemplateEnvelope = z.infer<typeof TemplateEnvelopeSchema>;
+
+/** Every request carries a `requestId` for correlation with its result. */
+export const BaseRequestSchema = z.object({ requestId: z.string().min(1) });
+
+/** Every result echoes the request's `requestId`. */
+export const BaseResultSchema = z.object({ requestId: z.string().min(1) });
+
+/** Public read-back tier. `0` and `1` are the literal verifier tiers; `"visual"` is sugar for `1`. */
+export const ReadBackTierSchema = z.union([z.literal(0), z.literal(1), z.literal("visual")]);
+export type ReadBackTier = z.infer<typeof ReadBackTierSchema>;
+
+/** Normalize a public read-back tier to a numeric validation tier. */
+export function normalizeReadBackTier(tier: ReadBackTier): 0 | 1 {
+  return tier === "visual" ? 1 : tier;
+}

package/src/shared/contracts/commands/guards.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+
+import type { Renderer } from "../renderers";
+import { FacetError } from "../../errors/facet-error";
+
+import {
+  CommandNameSchema,
+  IMPLEMENTED_COMMANDS,
+  RESERVED_COMMANDS,
+  type CommandName,
+} from "./names";
+import { PublishArtifactTypeSchema } from "./requests";
+
+export {
+  CommandNameSchema,
+  IMPLEMENTED_COMMANDS,
+  RESERVED_COMMANDS,
+  type CommandName,
+  PublishArtifactTypeSchema,
+};
+
+/**
+ * Returns a `reserved_not_implemented` FacetError for any reserved verb and
+ * `null` for every implemented verb. The command dispatcher calls this before
+ * running any handler.
+ */
+export function checkCommandImplemented(name: CommandName): FacetError | null {
+  if ((RESERVED_COMMANDS as readonly CommandName[]).includes(name)) {
+    return new FacetError(
+      "reserved_not_implemented",
+      `Command '${name}' is reserved and not implemented in this build`,
+      { retryable: false, details: { command: name } },
+    );
+  }
+  return null;
+}
+
+/**
+ * Future reserved artifact types return `unsupported_reserved_type`; every
+ * known type currently returns `null`. The publish dispatcher calls this
+ * before passing bytes into the store.
+ */
+export function checkArtifactTypeSupported(_type: string): FacetError | null {
+  return null;
+}
+
+/** Returns `invalid_request` when a renderer is incompatible with the artifact type. */
+export function checkRendererSupported(
+  artifactType: string,
+  renderer: Renderer,
+): FacetError | null {
+  if (renderer === "canvas" && artifactType !== "chart") {
+    return new FacetError(
+      "invalid_request",
+      `Renderer '${renderer}' is only supported for artifact type 'chart'`,
+      { retryable: false, details: { artifactType, renderer } },
+    );
+  }
+  return null;
+}
+
+/**
+ * Returns `invalid_request` when an `interactive` execution is set on a
+ * non-TSX artifact. `static` is the default and is silently accepted on
+ * every type (mirroring how `renderer: "svg"` is accepted on every
+ * artifact type — it is the canonical default). Callers see a typed
+ * error before any service round-trip or storage write; the publish
+ * dispatcher calls this before passing the request into the store.
+ */
+export function checkExecutionSupported(
+  artifactType: string,
+  execution: string | undefined,
+): FacetError | null {
+  if (execution === "interactive" && artifactType !== "tsx") {
+    return new FacetError(
+      "invalid_request",
+      `Execution mode 'interactive' is only supported for artifact type 'tsx' (got '${artifactType}')`,
+      { retryable: false, details: { artifactType, execution } },
+    );
+  }
+  return null;
+}
+
+// Re-export zod here so the barrel's `import { z } from "zod"` callers
+// keep working without re-importing.
+export { z };