@legionworks/facet 1.9.0

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

@@ -0,0 +1,204 @@
+/**
+ * Public command-verb surface. Per-verb request/result schemas live in
+ * `requests.ts` and `results.ts`; the discriminator unions that bind
+ * them into a single `CommandRequest` / `CommandResult` live here so a
+ * caller can `import { CommandRequestSchema, CommandResultSchema } from
+ * "../contracts/commands"` without knowing the internal split.
+ */
+
+import { z } from "zod";
+
+import type { Artifact, Revision, Template } from "../artifact";
+
+import {
+  ArtifactEnvelopeSchema,
+  BaseRequestSchema,
+  BaseResultSchema,
+  ReadBackTierSchema,
+  RevisionEnvelopeSchema,
+  TemplateEnvelopeSchema,
+  normalizeReadBackTier,
+  type ArtifactEnvelope,
+  type ReadBackTier,
+  type RevisionEnvelope,
+  type TemplateEnvelope,
+} from "./_shared";
+import {
+  CommandNameSchema,
+  IMPLEMENTED_COMMANDS,
+  RESERVED_COMMANDS,
+  type CommandName,
+} from "./names";
+import {
+  CreateRequestSchema,
+  InstantiateRequestSchema,
+  ListRequestSchema,
+  OpenRequestSchema,
+  PinRequestSchema,
+  PromoteRequestSchema,
+  PublishArtifactTypeSchema,
+  PublishRequestSchema,
+  ReadBackRequestSchema,
+  ExportFormatSchema,
+  ExportRequestSchema,
+  StatusRequestSchema,
+  type CreateRequest,
+  type InstantiateRequest,
+  type ListRequest,
+  type OpenRequest,
+  type PinRequest,
+  type PromoteRequest,
+  type PublishRequest,
+  type ReadBackRequest,
+  type ExportFormat,
+  type ExportRequest,
+  type StatusRequest,
+} from "./requests";
+import {
+  CreateResultSchema,
+  InstantiateResultSchema,
+  ListResultSchema,
+  OpenResultSchema,
+  PinResultSchema,
+  PromoteResultSchema,
+  PublishResultSchema,
+  ReadBackResultSchema,
+  ExportSidecarSchema,
+  ExportResultSchema,
+  StatusResultSchema,
+  DoctorProbeNameSchema,
+  DoctorProbeResultSchema,
+  DoctorResultSchema,
+  type CreateResult,
+  type InstantiateResult,
+  type ListResult,
+  type OpenResult,
+  type PinResult,
+  type PromoteResult,
+  type PublishResult,
+  type ReadBackResult,
+  type ExportSidecar,
+  type ExportResult,
+  type StatusResult,
+  type DoctorResult,
+} from "./results";
+import {
+  checkArtifactTypeSupported,
+  checkCommandImplemented,
+  checkExecutionSupported,
+  checkRendererSupported,
+} from "./guards";
+
+/**
+ * Discriminated union of every command request the protocol parses.
+ * `export` is included as an implemented command contract; its dispatcher
+ * arm is intentionally landed separately from this contract flip.
+ */
+export const CommandRequestSchema = z.discriminatedUnion("command", [
+  CreateRequestSchema,
+  PublishRequestSchema,
+  ListRequestSchema,
+  ReadBackRequestSchema,
+  StatusRequestSchema,
+  OpenRequestSchema,
+  PromoteRequestSchema,
+  InstantiateRequestSchema,
+  PinRequestSchema,
+  ExportRequestSchema,
+]);
+export type CommandRequest = z.infer<typeof CommandRequestSchema>;
+
+export const CommandResultSchema = z.discriminatedUnion("command", [
+  CreateResultSchema,
+  PublishResultSchema,
+  ListResultSchema,
+  ReadBackResultSchema,
+  StatusResultSchema,
+  OpenResultSchema,
+  PromoteResultSchema,
+  InstantiateResultSchema,
+  PinResultSchema,
+  ExportResultSchema,
+]);
+export type CommandResult = z.infer<typeof CommandResultSchema>;
+
+// Re-export Artifact/Revision/Template so callers can `import { Artifact, Revision, Template } from "..."/commands`.
+export type { Artifact, Revision, Template };
+export type { ArtifactEnvelope, RevisionEnvelope, TemplateEnvelope };
+
+// Surface the full public API. Anything not re-exported here is internal.
+export {
+  // shared primitives
+  ArtifactEnvelopeSchema,
+  BaseRequestSchema,
+  BaseResultSchema,
+  ReadBackTierSchema,
+  RevisionEnvelopeSchema,
+  TemplateEnvelopeSchema,
+  normalizeReadBackTier,
+  // names
+  CommandNameSchema,
+  IMPLEMENTED_COMMANDS,
+  RESERVED_COMMANDS,
+  // requests
+  CreateRequestSchema,
+  PublishRequestSchema,
+  PublishArtifactTypeSchema,
+  ListRequestSchema,
+  ReadBackRequestSchema,
+  StatusRequestSchema,
+  OpenRequestSchema,
+  PromoteRequestSchema,
+  InstantiateRequestSchema,
+  PinRequestSchema,
+  ExportFormatSchema,
+  ExportRequestSchema,
+  // results
+  CreateResultSchema,
+  PublishResultSchema,
+  ListResultSchema,
+  ReadBackResultSchema,
+  StatusResultSchema,
+  OpenResultSchema,
+  PromoteResultSchema,
+  InstantiateResultSchema,
+  PinResultSchema,
+  ExportResultSchema,
+  ExportSidecarSchema,
+  DoctorProbeNameSchema,
+  DoctorProbeResultSchema,
+  DoctorResultSchema,
+  // guards
+  checkCommandImplemented,
+  checkArtifactTypeSupported,
+  checkExecutionSupported,
+  checkRendererSupported,
+};
+
+export type { CommandName };
+export type {
+  CreateRequest,
+  PublishRequest,
+  ListRequest,
+  ReadBackRequest,
+  StatusRequest,
+  OpenRequest,
+  PromoteRequest,
+  InstantiateRequest,
+  PinRequest,
+  ExportFormat,
+  ExportRequest,
+  CreateResult,
+  PublishResult,
+  ListResult,
+  ReadBackResult,
+  StatusResult,
+  DoctorResult,
+  OpenResult,
+  PromoteResult,
+  InstantiateResult,
+  PinResult,
+  ExportResult,
+  ExportSidecar,
+  ReadBackTier,
+};

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

@@ -0,0 +1,35 @@
+import { z } from "zod";
+
+/**
+ * Every command verb the protocol recognizes. `RESERVED_COMMANDS` is empty
+ * today; the reserved mechanism remains so a future verb can be described
+ * by the wire schema before its handler is shipped.
+ */
+export const CommandNameSchema = z.enum([
+  "create",
+  "publish",
+  "list",
+  "readBack",
+  "status",
+  "open",
+  "promote",
+  "instantiate",
+  "pin",
+  "export",
+]);
+export type CommandName = z.infer<typeof CommandNameSchema>;
+
+export const IMPLEMENTED_COMMANDS: readonly CommandName[] = [
+  "create",
+  "publish",
+  "list",
+  "readBack",
+  "status",
+  "open",
+  "promote",
+  "instantiate",
+  "pin",
+  "export",
+];
+
+export const RESERVED_COMMANDS: readonly CommandName[] = [];

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

@@ -0,0 +1,149 @@
+import { z } from "zod";
+
+import { ArtifactTypeSchema, RendererSchema } from "../artifact";
+import { TSX_EXECUTION_MODES } from "../../tsx/execution";
+import { MAX_LIST_LIMIT } from "../../config/limits";
+
+import { BaseRequestSchema, ReadBackTierSchema } from "./_shared";
+
+/**
+ * Wire-encoded byte payload for publish. JSON cannot carry a Uint8Array
+ * directly; the v1 contract uses base64 (per D1 review) so a 5 MiB
+ * source fits in ~7 MiB of JSON. The schema validates base64 syntax;
+ * the dispatcher enforces SOURCE_CAP_BYTES on the decoded length and
+ * throws `payload_too_large` so the wire response is a typed 413
+ * rather than a schema-level 400.
+ */
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+
+export const PublishBytesSchema = z.string().superRefine((value, ctx) => {
+  if (value.length === 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "publish.bytes is empty",
+    });
+    return;
+  }
+  if (!BASE64_RE.test(value)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "publish.bytes is not valid base64",
+    });
+  }
+});
+
+/** Publish accepts every implemented artifact type from the canonical contract. */
+export const PublishArtifactTypeSchema = ArtifactTypeSchema;
+
+/**
+ * TSX execution mode. Derived from the canonical `TSX_EXECUTION_MODES`
+ * array so a typo or a new mode lands in one place. The publish
+ * request schema refines this with `artifactType` so a non-TSX request
+ * carrying `execution` is rejected with a typed `invalid_request`
+ * rather than silently coerced.
+ */
+export const TsxExecutionSchema = z.enum(TSX_EXECUTION_MODES);
+
+export const CreateRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("create"),
+  projectId: z.string().min(1),
+  slug: z.string().min(1),
+  title: z.string().min(1),
+});
+export type CreateRequest = z.infer<typeof CreateRequestSchema>;
+
+export const PublishRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("publish"),
+  artifactId: z.string().min(1),
+  artifactType: PublishArtifactTypeSchema,
+  renderer: RendererSchema.default("svg"),
+  bytes: PublishBytesSchema,
+  note: z.string().nullable().optional(),
+  parentRevisionId: z.string().min(1).nullable().optional(),
+  /**
+   * TSX execution mode (D2). Optional on the wire; defaults to
+   * `static` at the service layer when `artifactType === "tsx"`. A
+   * non-TSX artifact type carrying `execution` is rejected by the
+   * `checkExecutionSupported` guard called before storage — the same
+   * pattern `checkRendererSupported` uses for `renderer: "canvas"`
+   * on non-chart types. SuperRefine is intentionally NOT used here:
+   * Zod's discriminated `command` union requires direct ZodObject
+   * options, so cross-field validation belongs in a guard.
+   */
+  execution: TsxExecutionSchema.optional(),
+});
+export type PublishRequest = z.infer<typeof PublishRequestSchema>;
+
+export const ListRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("list"),
+  projectId: z.string().min(1),
+  slugPrefix: z.string().optional(),
+  limit: z.number().int().positive().max(MAX_LIST_LIMIT).optional(),
+});
+export type ListRequest = z.infer<typeof ListRequestSchema>;
+
+export const ReadBackRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("readBack"),
+  artifactId: z.string().min(1),
+  revisionSha: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/)
+    .optional(),
+  tier: ReadBackTierSchema,
+});
+export type ReadBackRequest = z.infer<typeof ReadBackRequestSchema>;
+
+export const StatusRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("status"),
+  artifactId: z.string().min(1).optional(),
+});
+export type StatusRequest = z.infer<typeof StatusRequestSchema>;
+
+export const OpenRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("open"),
+  artifactId: z.string().min(1),
+  revisionSha: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/)
+    .optional(),
+});
+export type OpenRequest = z.infer<typeof OpenRequestSchema>;
+
+export const PromoteRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("promote"),
+  artifactId: z.string().min(1).optional(),
+  revisionId: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string().nullable().optional(),
+  promotedBy: z.string().min(1),
+});
+export type PromoteRequest = z.infer<typeof PromoteRequestSchema>;
+
+export const InstantiateRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("instantiate"),
+  name: z.string().min(1),
+  newSlug: z.string().min(1),
+  projectId: z.string().min(1).optional(),
+});
+export type InstantiateRequest = z.infer<typeof InstantiateRequestSchema>;
+
+export const PinRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("pin"),
+  revisionId: z.string().min(1),
+  pinned: z.boolean(),
+});
+export type PinRequest = z.infer<typeof PinRequestSchema>;
+
+export const ExportFormatSchema = z.enum(["source", "render"]);
+export type ExportFormat = z.infer<typeof ExportFormatSchema>;
+
+export const ExportRequestSchema = BaseRequestSchema.extend({
+  command: z.literal("export"),
+  artifactId: z.string().min(1),
+  revisionSha: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/)
+    .optional(),
+  format: ExportFormatSchema.default("source"),
+});
+export type ExportRequest = z.infer<typeof ExportRequestSchema>;

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

@@ -0,0 +1,200 @@
+import { z } from "zod";
+
+import { Tier1ResultSchema, VerdictSchema } from "../validation";
+import { ArtifactTypeSchema, RendererSchema } from "../artifact";
+import { EvidenceImageFormatSchema } from "../../evidence-image";
+import { ExportFormatSchema } from "./requests";
+
+export const DoctorProbeNameSchema = z.enum([
+  "bun",
+  "chrome-headless-shell",
+  "netns-userns",
+  "database",
+  "token-permissions",
+  "evidence-permissions",
+  "service-lock",
+]);
+export const DoctorProbeResultSchema = z
+  .object({
+    name: DoctorProbeNameSchema,
+    status: z.enum(["pass", "fail"]),
+    summary: z.string(),
+    fixCommand: z.string().nullable(),
+    details: z.record(z.union([z.string(), z.number(), z.boolean(), z.null()])),
+  })
+  .strict();
+export const DoctorResultSchema = z
+  .object({
+    command: z.literal("doctor"),
+    allPassed: z.boolean(),
+    probes: z.array(DoctorProbeResultSchema),
+  })
+  .strict();
+export type DoctorResult = z.infer<typeof DoctorResultSchema>;
+
+import {
+  ArtifactEnvelopeSchema,
+  BaseResultSchema,
+  RevisionEnvelopeSchema,
+  TemplateEnvelopeSchema,
+} from "./_shared";
+
+export const CreateResultSchema = BaseResultSchema.extend({
+  command: z.literal("create"),
+  artifact: ArtifactEnvelopeSchema,
+});
+export type CreateResult = z.infer<typeof CreateResultSchema>;
+
+export const PublishResultSchema = BaseResultSchema.extend({
+  command: z.literal("publish"),
+  revision: RevisionEnvelopeSchema,
+  verdict: VerdictSchema,
+  /**
+   * Deprecated compatibility field. Publish is browser-free; visual
+   * read-back owns Tier 1 verification.
+   */
+  tier1Verdict: Tier1ResultSchema.nullable().optional(),
+});
+export type PublishResult = z.infer<typeof PublishResultSchema>;
+
+export const ListResultSchema = BaseResultSchema.extend({
+  command: z.literal("list"),
+  artifacts: z.array(ArtifactEnvelopeSchema),
+  nextCursor: z.string().nullable().optional(),
+});
+export type ListResult = z.infer<typeof ListResultSchema>;
+
+/**
+ * Read-back result embeds the canonical `VerdictSchema` from
+ * `validation.ts`. The two definitions are the SAME object so a
+ * `toMatchObject({ verdict })` against a read-back response and a
+ * `toMatchObject(...)` against a Tier 1 run produce the same shape.
+ */
+export const ReadBackResultSchema = BaseResultSchema.extend({
+  command: z.literal("readBack"),
+  renderer: RendererSchema,
+  verdict: VerdictSchema,
+});
+export type ReadBackResult = z.infer<typeof ReadBackResultSchema>;
+
+export const StatusResultSchema = BaseResultSchema.extend({
+  command: z.literal("status"),
+  artifactId: z.string().min(1).optional(),
+  latestRevisionSha: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/)
+    .optional(),
+  revisionCount: z.number().int().nonnegative().optional(),
+  pinnedCount: z.number().int().nonnegative().optional(),
+  templateCount: z.number().int().nonnegative().optional(),
+  state: z.enum(["dormant", "active"]).optional(),
+  process: z
+    .object({
+      pid: z.number().int().positive(),
+      uptimeMs: z.number().nonnegative(),
+      rssBytes: z.number().nonnegative().nullable(),
+      pssBytes: z.number().nonnegative().nullable(),
+    })
+    .nullable()
+    .optional(),
+  dbBytes: z.number().int().nonnegative().optional(),
+  evidenceBytes: z.number().int().nonnegative().optional(),
+  activeLeases: z.number().int().nonnegative().optional(),
+  activeJobs: z.number().int().nonnegative().optional(),
+  browserJobs: z.number().int().nonnegative().optional(),
+  idleDeadline: z.number().int().positive().nullable().optional(),
+  version: z.string().min(1).optional(),
+  contractVersion: z.string().min(1).optional(),
+});
+export type StatusResult = z.infer<typeof StatusResultSchema>;
+
+export const OpenResultSchema = BaseResultSchema.extend({
+  command: z.literal("open"),
+  artifactId: z.string().min(1),
+  revisionSha: z.string().regex(/^[a-f0-9]{64}$/),
+  frameUrl: z.string().min(1),
+  launched: z.boolean(),
+  /**
+   * Out-of-band lease capability for the SSE route. The lease id is
+   * never embedded in `frameUrl`; the client carries it via the
+   * `X-Gallery-Lease` header on the stream connect request.
+   */
+  lease: z.object({
+    leaseId: z.string().min(1),
+    expiresAt: z.number().int().positive(),
+  }),
+});
+export type OpenResult = z.infer<typeof OpenResultSchema>;
+
+export const PromoteResultSchema = BaseResultSchema.extend({
+  command: z.literal("promote"),
+  template: TemplateEnvelopeSchema,
+});
+export type PromoteResult = z.infer<typeof PromoteResultSchema>;
+
+export const InstantiateResultSchema = BaseResultSchema.extend({
+  command: z.literal("instantiate"),
+  artifact: ArtifactEnvelopeSchema,
+  template: TemplateEnvelopeSchema,
+});
+export type InstantiateResult = z.infer<typeof InstantiateResultSchema>;
+
+export const PinResultSchema = BaseResultSchema.extend({
+  command: z.literal("pin"),
+  revisionId: z.string().min(1),
+  pinned: z.boolean(),
+});
+export type PinResult = z.infer<typeof PinResultSchema>;
+
+export const ExportSidecarSchema = z
+  .object({
+    artifactId: z.string().min(1),
+    slug: z.string().min(1),
+    revisionSha: z.string().regex(/^[a-f0-9]{64}$/),
+    artifactType: ArtifactTypeSchema,
+    renderer: RendererSchema,
+    verdict: VerdictSchema,
+    format: ExportFormatSchema,
+    renderFormat: EvidenceImageFormatSchema.optional(),
+    exportedAt: z.string().datetime({ offset: true }),
+  })
+  .superRefine((value, context) => {
+    if (value.format === "render" && value.renderFormat === undefined) {
+      context.addIssue({ code: "custom", message: "render exports require renderFormat" });
+    }
+    if (value.format === "source" && value.renderFormat !== undefined) {
+      context.addIssue({ code: "custom", message: "source exports must omit renderFormat" });
+    }
+  });
+export type ExportSidecar = z.infer<typeof ExportSidecarSchema>;
+
+function isBase64(value: string): boolean {
+  if (value.length % 4 !== 0) return false;
+  let paddingStart = value.length;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    const isUpper = code >= 65 && code <= 90;
+    const isLower = code >= 97 && code <= 122;
+    const isDigit = code >= 48 && code <= 57;
+    if (isUpper || isLower || isDigit || code === 43 || code === 47) continue;
+    if (code === 61) {
+      paddingStart = index;
+      break;
+    }
+    return false;
+  }
+  const padding = value.length - paddingStart;
+  if (padding > 2) return false;
+  for (let index = paddingStart; index < value.length; index += 1) {
+    if (value.charCodeAt(index) !== 61) return false;
+  }
+  return true;
+}
+
+export const ExportResultSchema = BaseResultSchema.extend({
+  command: z.literal("export"),
+  format: ExportFormatSchema,
+  bytes: z.string().refine(isBase64, "Invalid base64"),
+  sidecar: ExportSidecarSchema,
+});
+export type ExportResult = z.infer<typeof ExportResultSchema>;