@legionworks/facet 1.9.0

package/skills/facet/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: facet
+description: Use when creating, publishing, validating, exporting, or inspecting Facet artifacts, diagrams, charts, SVG, Markdown, or gallery output; when choosing between Markdown, Mermaid, SVG, chart, HTML, and TSX; or when a Facet CLI envelope or typed error needs interpretation.
+---
+
+# Facet
+
+Install `@legionworks/facet` with `bun add -g` (recommended), `npm i -g`, or
+`pnpm add -g`; use `bunx @legionworks/facet <verb>` without a global install.
+Bun `1.4.0` or newer is the required runtime. npm and pnpm are distribution
+channels only. The pinned browser downloads on the first visual read-back.
+
+Facet stores and verifies artifact bytes through a versioned CLI envelope. Keep
+artifact bytes separate from host capabilities.
+
+## Choose the artifact type
+
+| Need                     | Type                           | Why                                                                                         |
+| ------------------------ | ------------------------------ | ------------------------------------------------------------------------------------------- |
+| Prose or mixed documents | Markdown                       | Portable authored content.                                                                  |
+| One diagram              | Mermaid                        | A single declarative diagram.                                                               |
+| Authored vector output   | SVG                            | Precise vector output under the SVG contract.                                               |
+| Data visualization       | chart                          | Vega-Lite data visualization; `svg` is default, `canvas` only when chosen for the chart.    |
+| Static semantic report   | HTML                           | Static semantic report with vendored styles.                                                |
+| Component composition    | TSX: `static` \| `interactive` | Use `static` by default; use `interactive` only when runtime state or behavior is required. |
+
+## Publish and check
+
+1. Cold-start check: when environment, launch, or permission errors are present, run `facet doctor`; it is read-only and reports literal repair commands. Check status next and start only when needed: `facet status --start`.
+2. Create or reuse an artifact: `facet create --project-id <id> --slug <slug> --title <title>`.
+3. Publish source bytes with one of these forms:
+
+   ```sh
+   facet publish --artifact-id <id> --type markdown --file path/to/source.md
+   facet publish --artifact-id <id> --type markdown --file -
+   printf '%s' "$SOURCE" | facet publish --artifact-id <id> --type markdown
+   ```
+
+   Use `--watch --file <path>` for operator-led iterative authoring; it streams one publish envelope per changed attempt until Ctrl-C.
+
+4. For every publish response, branch on top-level `ok`. If it is true, separately inspect `data.verdict.status`, `tier`, `artifactId`, and `revisionSha`. `ok: true` only confirms command transport; `status: "error"` is a stored validation result, not a transport refusal.
+5. Read back Tier 0/latest by default: `facet read-back --artifact-id <id>`. Omit `--revision-sha` for the latest revision; pass its SHA only to pin reproducible read-back. Request `--tier 1` or `--tier visual` only when browser-backed evidence is needed.
+
+## Execution and evidence
+
+`--execution static|interactive` applies to TSX only. `static` is the default;
+`interactive` is for client runtime state or behavior. Verdicts carry execution
+only for TSX. Interactive TSX is animation-eligible without probing; static
+artifacts become animation-eligible only after live CSS or Web Animations are
+detected.
+
+Gallery display defaults to `system`; users may select `dark` or `light`, and
+the tab persists that choice. Tier 1 stays dark for deterministic parity.
+
+## Export
+
+Use `facet export <artifactId> --format source` for stored source, or
+`--format render` for retained Tier 1 evidence. Exports write local artifact and
+mandatory sidecar paths plus byte count by default. Use `--include-bytes` only
+when an envelope consumer genuinely needs base64 bytes. Render export preserves
+the detected evidence format:
+
+- detected WebP for new captures;
+- detected PNG for legacy captures.
+
+## Promotion
+
+Promotion is operator-only. The CLI discovers the token from
+`FACET_PROMOTE_TOKEN`, then `FACET_HOME/secrets/promote.token`; never put a
+token on argv.
+
+## Error quick reference
+
+| Error                    | Do next                                                                                                          |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| `invalid_request`        | Correct the command flags, artifact type, or source bytes, then retry.                                           |
+| `artifact_not_found`     | List or create the artifact, then use its returned ID.                                                           |
+| `revision_not_found`     | Omit the SHA for latest, or replace it with a returned revision SHA.                                             |
+| `duplicate_revision`     | Use `error.details.revisionSha` as the existing revision SHA; do not republish identical bytes.                  |
+| `evidence_unavailable`   | Request Tier 1 evidence for that revision before a render export, or export source instead.                      |
+| `output_unwritable`      | Choose a writable `--out` path, resolve collisions, or use `--force` deliberately.                               |
+| `tier0_*`                | Repair the Tier 0 worker or its environment; a returned `status: "error"` is a verdict, not this envelope error. |
+| `tier1_*`                | Repair browser-backed validation availability, then retry the requested Tier 1 read-back.                        |
+| `screenshot_unavailable` | Inspect `Verdict.screenshotError`; it is a degraded stored verdict field, not an envelope error.                 |
+
+## Boundaries
+
+- Promotion is operator-only. Secrets never enter artifacts, notes, or argv.
+- The service is byte-dumb: do not call loopback routes, import renderers, or
+  parse artifact bytes outside the documented CLI workflow.
+- Do not run `facet open` as an agent: it launches local `xdg-open` for human
+  display on the operator's desktop. Ensure the service is active with
+  `facet status --start`, then use the documented [Steel/browser workflow](../../docs/guides/agents.md)
+  or ask a human to inspect.
+- Preserve stdout exactly so callers can parse the versioned envelope.
+- With shell access, the CLI is the integration — MCP is for structured-tool-only hosts, even when the host owns an MCP client. On that surface, `facet_open_url` is safe because it always uses `--no-launch`.
+
+## Deeper reference
+
+→ [Agent workflow](../../docs/guides/agents.md) · [CLI](../../docs/reference/cli.md) · [MCP](../../docs/reference/mcp.md) · [Export](../../docs/reference/export.md) · [Validation](../../docs/reference/validation.md) · [HTML](../../docs/reference/html.md) · [TSX](../../docs/reference/tsx.md) · [Security](../../docs/reference/security.md)

package/src/cli/client.ts

@@ -0,0 +1,311 @@
+/**
+ * Loopback HTTP client used by every CLI verb.
+ *
+ * The CLI talks to the service over HTTP only — never to the
+ * repository or any renderer module directly. `sendCommand` wraps
+ * the request in a strict `FacetEnvelope`, sends it with Bearer auth
+ * and the correct Host header, and parses the response through the
+ * shared `FacetEnvelopeSchema` so a forged or drift-ed response
+ * surfaces as a typed error envelope.
+ *
+ * Source bytes for `publish` are base64-encoded on the wire; the
+ * schema's `PublishBytesSchema` accepts only valid base64, so an
+ * invalid input is rejected at parse time (typed `invalid_request`).
+ */
+
+import { errEnvelope, parseEnvelope, type FacetEnvelope } from "../shared/contracts/envelope";
+import {
+  CommandRequestSchema,
+  CommandResultSchema,
+  type CommandRequest,
+  type CommandResult,
+} from "../shared/contracts/commands";
+
+const TIER1_TRACE = process.env.FACET_TIER1_TRACE === "1";
+export const FACET_CLIENT_COMMAND_TIMEOUT_MS = 75_000;
+
+function traceTier1Transport(stage: string): void {
+  if (!TIER1_TRACE) return;
+  process.stderr.write(`[tier1-transport] ${stage}\n`);
+}
+
+import { FacetError } from "../shared/errors/facet-error";
+import { generateRequestId } from "../shared/util/time";
+import { isMutationMethod } from "../service/security/http-guards";
+import type { ArtifactType } from "../shared/contracts/artifact-types";
+import type { Renderer } from "../shared/contracts/renderers";
+import type { ScreenshotError, TsxExecutionMode } from "../shared/contracts/validation";
+
+export interface FacetClientOptions {
+  readonly baseUrl: string;
+  readonly installToken: string;
+  readonly promoteToken?: string;
+  readonly commandTimeoutMs?: number;
+  /** `fetch` indirection so tests can stub network. */
+  readonly fetchImpl?: typeof fetch;
+}
+
+export interface SendCommandOptions {
+  /** Set true for any state-changing verb (default: derived from verb name). */
+  readonly isMutation?: boolean;
+  /** Extra headers to merge into the request (Content-Type is added automatically on mutations). */
+  readonly extraHeaders?: Readonly<Record<string, string>>;
+}
+
+export class FacetClient {
+  readonly #baseUrl: string;
+  readonly #installToken: string;
+  readonly #promoteToken: string | undefined;
+  readonly #commandTimeoutMs: number;
+  readonly #fetchImpl: typeof fetch;
+
+  constructor(options: FacetClientOptions) {
+    this.#baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.#installToken = options.installToken;
+    this.#promoteToken = options.promoteToken;
+    this.#commandTimeoutMs = options.commandTimeoutMs ?? FACET_CLIENT_COMMAND_TIMEOUT_MS;
+    this.#fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  /**
+   * Build a typed `CommandRequest` for the given verb + args, parse
+   * it through the shared schema (so a malformed CLI surface fails
+   * here, not in the service), wrap it in an envelope, POST to the
+   * loopback service, and return the parsed response envelope.
+   *
+   * On a non-2xx HTTP response the service still returns a valid
+   * envelope (the router wraps every error in one), so the only
+   * `throw` path is a transport-level failure (connection refused,
+   * DNS error, etc.). Those surface as `FacetError("invalid_envelope",
+   * ...)` so the caller can wrap them in a typed envelope for the
+   * adapter.
+   */
+  async sendCommand(
+    command: CommandRequest,
+    options: SendCommandOptions = {},
+  ): Promise<FacetEnvelope<CommandResult>> {
+    // Re-parse the command via the strict schema — a forged or
+    // drift-ed CLI surface that produced a malformed request fails
+    // here with a typed issue list, never reaching the wire.
+    const parsed = CommandRequestSchema.parse(command);
+    const innerRequestId = parsed.requestId;
+    const isMutation = options.isMutation ?? isMutationMethodFor(parsed.command);
+    const envelope: FacetEnvelope<CommandRequest> = {
+      schemaVersion: "facet.v1",
+      requestId: generateRequestId(),
+      ok: true,
+      data: parsed,
+    };
+    const headers: Record<string, string> = {
+      authorization: `Bearer ${parsed.command === "promote" && this.#promoteToken !== undefined ? this.#promoteToken : this.#installToken}`,
+      host: new URL(this.#baseUrl).host,
+    };
+    if (isMutation) {
+      headers["content-type"] = "application/json";
+    }
+    if (options.extraHeaders) {
+      Object.assign(headers, options.extraHeaders);
+    }
+    let res: Response;
+    let text: string;
+    const signal = AbortSignal.timeout(this.#commandTimeoutMs);
+    try {
+      traceTier1Transport(`client:fetch:start command=${parsed.command}`);
+      res = await this.#fetchImpl(`${this.#baseUrl}/api/v1/commands`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(envelope),
+        signal,
+      });
+      traceTier1Transport(`client:fetch:complete command=${parsed.command} status=${res.status}`);
+      traceTier1Transport(`client:body:start command=${parsed.command}`);
+      text = await res.text();
+      traceTier1Transport(`client:body:complete command=${parsed.command} bytes=${text.length}`);
+    } catch (error) {
+      const timedOut = signal.aborted;
+      throw new FacetError(
+        "invalid_envelope",
+        timedOut
+          ? `Connection timed out after ${this.#commandTimeoutMs}ms`
+          : `Connection failed: ${(error as Error).message}`,
+        {
+          retryable: true,
+          cause: error,
+          details: timedOut
+            ? {
+                reason: "connection_timeout",
+                host: this.#baseUrl,
+                timeoutMs: this.#commandTimeoutMs,
+              }
+            : { reason: "connection_failed", host: this.#baseUrl },
+        },
+      );
+    }
+    let body: unknown;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw new FacetError(
+        "invalid_envelope",
+        `Service response is not valid JSON (status ${res.status})`,
+        { retryable: false, details: { status: res.status } },
+      );
+    }
+    const parsed2 = parseEnvelope(body);
+    if (!parsed2.ok) {
+      // The service's response was a parse failure; surface a typed
+      // error envelope with the same shape as the wire would.
+      return errEnvelope(innerRequestId, parsed2.body) as FacetEnvelope<CommandResult>;
+    }
+    return parsed2.envelope as FacetEnvelope<CommandResult>;
+  }
+}
+
+/**
+ * Map a wire `command` to whether it counts as a mutation. The CLI
+ * must set Content-Type for mutations; the service enforces the same
+ * check on the other side via the shared `isMutationMethod` helper.
+ */
+function isMutationMethodFor(_command: CommandRequest["command"]): boolean {
+  // The CLI only ever sends POST, so every wire command is a
+  // mutation from the HTTP-method standpoint; the service's
+  // mutation guard is always satisfied. This helper exists so the
+  // CLI can express intent in one place and the security
+  // classification stays single-sourced.
+  void isMutationMethod;
+  return true;
+}
+
+/**
+ * Result of a successful publish. `artifactId` and `revisionSha` are
+ * the canonical IDs every downstream verb (read-back, status, open)
+ * carries. Publish is browser-free, so Tier 1 fields remain `null`;
+ * request a visual read-back for a Tier 1 verdict.
+ */
+export interface PublishArtifactResult {
+  readonly artifactId: string;
+  readonly revisionSha: string;
+  readonly tier1Status: string | null;
+  readonly tier1ScreenshotPath: string | null;
+  readonly tier1ScreenshotError: ScreenshotError | null;
+}
+
+export interface PublishArtifactOptions {
+  readonly artifactType: ArtifactType;
+  readonly renderer?: Renderer;
+  readonly bytes: ArrayBuffer;
+  readonly slug?: string;
+  readonly note?: string;
+  readonly execution?: TsxExecutionMode;
+}
+
+/**
+ * Publish a new revision through an existing FacetClient. Resolves
+ * the artifact (create-then-publish) and returns the canonical IDs.
+ * Used by the acceptance test fixture helper, which needs to spawn
+ * a service via the existing CLI infrastructure.
+ */
+export async function publishArtifact(
+  client: FacetClient,
+  options: PublishArtifactOptions,
+): Promise<PublishArtifactResult> {
+  const slug = options.slug ?? `acceptance-${crypto.randomUUID().slice(0, 8)}`;
+  const createRes = await client.sendCommand({
+    command: "create",
+    requestId: generateRequestId(),
+    projectId: "/facet",
+    slug,
+    title: slug,
+  });
+  if (!createRes.ok) {
+    throw FacetError.from(createRes.error);
+  }
+  const parsed = CommandResultSchema.parse(createRes.data);
+  if (parsed.command !== "create") {
+    throw new FacetError("invalid_envelope", `expected create result, got ${parsed.command}`);
+  }
+  const artifactId = parsed.artifact.id;
+  const base64 = btoa(String.fromCharCode(...new Uint8Array(options.bytes)));
+  const publishRes = await client.sendCommand({
+    command: "publish",
+    requestId: generateRequestId(),
+    artifactId,
+    artifactType: options.artifactType,
+    renderer: options.renderer ?? "svg",
+    bytes: base64,
+    ...(options.note !== undefined ? { note: options.note } : {}),
+    ...(options.execution === undefined ? {} : { execution: options.execution }),
+  });
+  if (!publishRes.ok) {
+    throw FacetError.from(publishRes.error);
+  }
+  const parsedPublish = CommandResultSchema.parse(publishRes.data);
+  if (parsedPublish.command !== "publish") {
+    throw new FacetError(
+      "invalid_envelope",
+      `expected publish result, got ${parsedPublish.command}`,
+    );
+  }
+  // Publish stays browser-free. Tier 1 is explicit through read-back.
+  const tier1Status = parsedPublish.tier1Verdict?.status ?? null;
+  return {
+    artifactId,
+    revisionSha: parsedPublish.revision.sha256,
+    tier1Status,
+    tier1ScreenshotPath: parsedPublish.tier1Verdict?.screenshotPath ?? null,
+    tier1ScreenshotError: parsedPublish.tier1Verdict?.screenshotError ?? null,
+  };
+}
+
+export interface ReadBackOptions {
+  readonly artifactId: string;
+  readonly revisionSha: string;
+  readonly tier: 0 | 1 | "visual";
+}
+
+/**
+ * Run `readBack` against an existing FacetClient and return the
+ * typed verdict. The service normalizes "visual" → 1 internally.
+ *
+ * The return shape is the canonical Verdict surface (plus the
+ * request-level `renderer`): the typed envelope is schema-validated
+ * by `CommandResultSchema.parse`, so the verdict that crosses the
+ * wire is already the canonical shape. Field-by-field copying here
+ * is the field-drop class (Must 2) — every field added since the
+ * helper was written was silently dropped. Pass the parsed verdict
+ * through so a new field on the schema is included by default.
+ */
+export async function readBack(
+  client: FacetClient,
+  options: ReadBackOptions,
+): Promise<ReadBackResult> {
+  const res = await client.sendCommand({
+    command: "readBack",
+    requestId: generateRequestId(),
+    artifactId: options.artifactId,
+    revisionSha: options.revisionSha,
+    tier: options.tier,
+  });
+  if (!res.ok) {
+    throw FacetError.from(res.error);
+  }
+  const parsed = CommandResultSchema.parse(res.data);
+  if (parsed.command !== "readBack") {
+    throw new FacetError("invalid_envelope", `expected readBack result, got ${parsed.command}`);
+  }
+  return {
+    renderer: parsed.renderer,
+    verdict: parsed.verdict,
+  };
+}
+
+/**
+ * The canonical read-back result the client returns. The `verdict`
+ * is the canonical Verdict shape (already schema-validated by the
+ * envelope parse), and `renderer` is the request-level binding
+ * that accompanies it. Anything else lives on the verdict.
+ */
+export type ReadBackResult = {
+  readonly renderer: Renderer;
+  readonly verdict: import("../shared/contracts/validation").Verdict;
+};

package/src/cli/commands/create.ts

@@ -0,0 +1,49 @@
+/**
+ * `facet create` — register a new artifact.
+ *
+ * The CLI maps the public verb (`create`) to the wire command
+ * (`create`) and builds a strict `CreateRequest` from the parsed
+ * argv. Required flags: `--project-id`, `--slug`, `--title`. The
+ * request id is minted here so the response envelope carries the
+ * CLI-side correlation id (the service echoes the request id back
+ * in its own envelope).
+ *
+ * Input-validation errors throw `FacetError("invalid_request", ...)`
+ * so the envelope preserves the typed `invalid_request` code (the
+ * house pattern for argv-shape failures) — the main catch recognises
+ * a pre-existing FacetError and passes `toBody()` through unchanged.
+ */
+
+import { generateRequestId } from "../../shared/util/time";
+import { FacetError } from "../../shared/errors/facet-error";
+import type { CreateRequest } from "../../shared/contracts/commands/requests";
+
+export function buildCreateRequest(
+  args: Readonly<Record<string, string | boolean>>,
+): CreateRequest {
+  const projectId = args["project-id"];
+  const slug = args["slug"];
+  const title = args["title"];
+  if (typeof projectId !== "string" || projectId.length === 0) {
+    throw new FacetError("invalid_request", "--project-id is required for create", {
+      retryable: false,
+    });
+  }
+  if (typeof slug !== "string" || slug.length === 0) {
+    throw new FacetError("invalid_request", "--slug is required for create", {
+      retryable: false,
+    });
+  }
+  if (typeof title !== "string" || title.length === 0) {
+    throw new FacetError("invalid_request", "--title is required for create", {
+      retryable: false,
+    });
+  }
+  return {
+    command: "create",
+    requestId: generateRequestId(),
+    projectId,
+    slug,
+    title,
+  };
+}