@legionworks/facet 1.9.0

package/src/cli/commands/publish.ts

@@ -0,0 +1,122 @@
+/**
+ * `facet publish` — upload a new revision.
+ *
+ * Source bytes come from `--file <path>` (read from disk) or from
+ * stdin when `--file -` is passed or when stdin is piped. The CLI
+ * NEVER imports a parser or renderer — it only base64-encodes the
+ * raw bytes the user pointed at, then hands them to the service
+ * via the wire contract.
+ *
+ * The service enforces `SOURCE_CAP_BYTES` (5 MiB) on the decoded
+ * length; the CLI surfaces the typed `payload_too_large` response
+ * as a normal envelope. Required flags: `--artifact-id`, `--type`,
+ * and either `--file` or piped stdin.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { FacetError } from "../../shared/errors/facet-error";
+import { ARTIFACT_TYPES } from "../../shared/contracts/artifact-types";
+import { isRenderer } from "../../shared/contracts/renderers";
+import { isTsxExecutionMode } from "../../shared/tsx/execution";
+import { checkExecutionSupported } from "../../shared/contracts/commands/guards";
+import { generateRequestId } from "../../shared/util/time";
+import type { PublishRequest } from "../../shared/contracts/commands/requests";
+import type { ArtifactType } from "../../shared/contracts/artifact";
+
+const VALID_TYPES: ReadonlySet<ArtifactType> = new Set(ARTIFACT_TYPES);
+
+export interface ResolveSourceInput {
+  readonly fileFlag: string | undefined;
+  /** Bytes the caller has already buffered from stdin (empty when not piped). */
+  readonly stdinBytes: Uint8Array;
+}
+
+export function resolveSourceBytes(input: ResolveSourceInput): Uint8Array {
+  const flag = input.fileFlag;
+  if (flag === undefined || flag === "-") {
+    if (input.stdinBytes.length === 0) {
+      throw new FacetError(
+        "invalid_request",
+        "publish: no source bytes — pass --file <path> or pipe bytes on stdin",
+        { retryable: false, details: { reason: "no_source_bytes" } },
+      );
+    }
+    return input.stdinBytes;
+  }
+  return new Uint8Array(readFileSync(flag));
+}
+
+export function buildPublishRequest(
+  args: Readonly<Record<string, string | boolean>>,
+  sourceBytes: Uint8Array,
+): PublishRequest {
+  const artifactId = args["artifact-id"];
+  const type = args["type"];
+  if (typeof artifactId !== "string" || artifactId.length === 0) {
+    throw new FacetError("invalid_request", "--artifact-id is required for publish", {
+      retryable: false,
+    });
+  }
+  if (typeof type !== "string" || !VALID_TYPES.has(type as ArtifactType)) {
+    throw new FacetError(
+      "invalid_request",
+      `--type must be one of: ${[...VALID_TYPES].join(", ")} (got '${String(type)}')`,
+      { retryable: false, details: { reason: "invalid_artifact_type" } },
+    );
+  }
+  if (sourceBytes.length === 0) {
+    throw new FacetError("invalid_request", "publish bytes are empty", {
+      retryable: false,
+      details: { reason: "empty_bytes" },
+    });
+  }
+  const noteValue = args["note"];
+  const parentValue = args["parent-revision-id"];
+  const rendererValue = args["renderer"] ?? "svg";
+  if (!isRenderer(rendererValue)) {
+    throw new FacetError(
+      "invalid_request",
+      `--renderer must be one of: svg, canvas (got '${String(rendererValue)}')`,
+      { retryable: false, details: { reason: "invalid_renderer" } },
+    );
+  }
+  const executionValue = args["execution"];
+  if (
+    executionValue !== undefined &&
+    (typeof executionValue !== "string" || !isTsxExecutionMode(executionValue))
+  ) {
+    throw new FacetError(
+      "invalid_request",
+      `--execution must be one of: static, interactive (got '${String(executionValue)}')`,
+      { retryable: false, details: { reason: "invalid_execution" } },
+    );
+  }
+  // Mirror the dispatcher's `checkExecutionSupported` guard: an
+  // explicit `interactive` execution on a non-tsx type is rejected at
+  // the CLI boundary so the typed `invalid_request` surfaces before
+  // any service round-trip. The predicate lives in
+  // `src/shared/contracts/commands/guards.ts` — import it and
+  // rethrow the typed error so the CLI and the dispatcher share one
+  // source of truth.
+  const executionError = checkExecutionSupported(type, executionValue);
+  if (executionError !== null) throw executionError;
+  // D2: TSX execution defaults to `static` at the CLI boundary so a
+  // downstream consumer that reads the wire request never sees
+  // `execution: undefined` for a tsx artifact.
+  const resolvedExecution =
+    executionValue === "interactive" ? "interactive" : type === "tsx" ? "static" : undefined;
+  return {
+    command: "publish",
+    requestId: generateRequestId(),
+    artifactId,
+    artifactType: type as ArtifactType,
+    renderer: rendererValue,
+    bytes: Buffer.from(sourceBytes).toString("base64"),
+    ...(typeof noteValue === "string" ? { note: noteValue } : {}),
+    ...(typeof parentValue === "string" ? { parentRevisionId: parentValue } : {}),
+    ...(resolvedExecution !== undefined
+      ? { execution: resolvedExecution as PublishRequest["execution"] }
+      : {}),
+  };
+}

package/src/cli/commands/read-back.ts

@@ -0,0 +1,56 @@
+/**
+ * `facet read-back` — fetch a verdict for a revision.
+ *
+ * The public tier surface is `0 | 1 | "visual"`; the CLI accepts the
+ * same. The service normalizes "visual" to 1 via
+ * `normalizeReadBackTier`. Default tier when omitted is 0 (the
+ * browser-free parser path).
+ *
+ * Input-validation errors throw `FacetError("invalid_request", ...)`
+ * so the envelope preserves the typed `invalid_request` code.
+ */
+
+import { generateRequestId } from "../../shared/util/time";
+import { FacetError } from "../../shared/errors/facet-error";
+import type { ReadBackRequest } from "../../shared/contracts/commands/requests";
+import type { ReadBackTier } from "../../shared/contracts/commands/_shared";
+
+const TIER_VALUES = new Set(["0", "1", "visual"]);
+
+function parseTier(raw: string | boolean | undefined): ReadBackTier {
+  if (typeof raw !== "string") return 0;
+  if (!TIER_VALUES.has(raw)) {
+    throw new FacetError("invalid_request", `--tier must be one of: 0, 1, visual (got '${raw}')`, {
+      retryable: false,
+    });
+  }
+  if (raw === "visual") return "visual";
+  return Number(raw) as 0 | 1;
+}
+
+export function buildReadBackRequest(
+  args: Readonly<Record<string, string | boolean>>,
+): ReadBackRequest {
+  const artifactId = args["artifact-id"];
+  const revisionSha = args["revision-sha"];
+  if (typeof artifactId !== "string" || artifactId.length === 0) {
+    throw new FacetError("invalid_request", "--artifact-id is required for read-back", {
+      retryable: false,
+    });
+  }
+  if (
+    revisionSha !== undefined &&
+    (typeof revisionSha !== "string" || !/^[a-f0-9]{64}$/.test(revisionSha))
+  ) {
+    throw new FacetError("invalid_request", "--revision-sha must be a 64-char hex sha256", {
+      retryable: false,
+    });
+  }
+  return {
+    command: "readBack",
+    requestId: generateRequestId(),
+    artifactId,
+    ...(typeof revisionSha === "string" ? { revisionSha } : {}),
+    tier: parseTier(args["tier"]),
+  };
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,114 @@
+/**
+ * `facet status` request builder.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+
+import { generateRequestId } from "../../shared/util/time";
+import type { StatusRequest } from "../../shared/contracts/commands/requests";
+import { FACET_SCHEMA_VERSION } from "../../shared/contracts/envelope";
+import type { FacetRuntimePaths } from "../../shared/config/paths";
+import { evidenceBytesAcross, resolveEvidenceReadRoots } from "../../shared/config/evidence-read";
+import { FACET_VERSION } from "../../shared/version";
+import { readLiveMetadata } from "../service-metadata";
+
+export interface FacetStatusOptions {
+  readonly activeLeases?: number;
+  readonly activeJobs?: number;
+  readonly browserJobs?: number;
+  readonly idleDeadline?: number | null;
+}
+
+export interface FacetStatus {
+  readonly state: "dormant" | "active";
+  readonly process: {
+    readonly pid: number;
+    readonly uptimeMs: number;
+    readonly rssBytes: number | null;
+    readonly pssBytes: number | null;
+  } | null;
+  readonly dbBytes: number;
+  readonly evidenceBytes: number;
+  readonly activeLeases: number;
+  readonly activeJobs: number;
+  readonly browserJobs: number;
+  readonly idleDeadline: number | null;
+  readonly version: string;
+  readonly contractVersion: string;
+}
+
+function directoryBytes(path: string): number {
+  if (!existsSync(path)) return 0;
+  const stat = statSync(path);
+  if (stat.isFile()) return stat.size;
+  if (!stat.isDirectory()) return 0;
+  return readdirSync(path).reduce((total, entry) => total + directoryBytes(`${path}/${entry}`), 0);
+}
+
+function readKbMetric(text: string, key: string): number | null {
+  const match = text.match(new RegExp(`^${key}:\\s+(\\d+)\\s+kB$`, "m"));
+  return match ? Number(match[1]) * 1024 : null;
+}
+
+function processMemory(pid: number): { rssBytes: number | null; pssBytes: number | null } {
+  try {
+    const statusText = readFileSync(`/proc/${pid}/status`, "utf8");
+    const rollupText = readFileSync(`/proc/${pid}/smaps_rollup`, "utf8");
+    return {
+      rssBytes: readKbMetric(statusText, "VmRSS"),
+      pssBytes: readKbMetric(rollupText, "Pss"),
+    };
+  } catch {
+    let rssBytes: number | null = null;
+    try {
+      const statusText = readFileSync(`/proc/${pid}/status`, "utf8");
+      rssBytes = readKbMetric(statusText, "VmRSS");
+    } catch {
+      // The process may have exited or become unreadable between probes.
+    }
+    return { rssBytes, pssBytes: null };
+  }
+}
+
+export function collectFacetStatus(
+  paths: FacetRuntimePaths,
+  options: FacetStatusOptions = {},
+  legacyEvidenceRoot: string | null = null,
+): FacetStatus {
+  const metadata = readLiveMetadata(paths);
+  const memory = metadata === null ? null : processMemory(metadata.pid);
+  const evidenceBytes = evidenceBytesAcross(
+    resolveEvidenceReadRoots(paths.evidence, legacyEvidenceRoot),
+  );
+  return {
+    state: metadata === null ? "dormant" : "active",
+    process:
+      metadata === null
+        ? null
+        : {
+            pid: metadata.pid,
+            uptimeMs: Math.max(0, Date.now() - metadata.startTime),
+            rssBytes: memory?.rssBytes ?? null,
+            pssBytes: memory?.pssBytes ?? null,
+          },
+    dbBytes: directoryBytes(paths.database),
+    evidenceBytes,
+    activeLeases: options.activeLeases ?? 0,
+    activeJobs: options.activeJobs ?? 0,
+    browserJobs: options.browserJobs ?? 0,
+    idleDeadline: options.idleDeadline ?? null,
+    version: FACET_VERSION,
+    contractVersion: FACET_SCHEMA_VERSION,
+  };
+}
+
+export function buildStatusRequest(
+  args: Readonly<Record<string, string | boolean>>,
+): StatusRequest {
+  const artifactId = args["artifact-id"];
+  return {
+    command: "status",
+    requestId: generateRequestId(),
+    ...(typeof artifactId === "string" && artifactId.length > 0 ? { artifactId } : {}),
+  };
+}

package/src/cli/commands/watch.ts

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { dirname, basename } from "node:path";
+import { readFile } from "node:fs/promises";
+import { watch } from "node:fs";
+
+import { errEnvelope, type FacetEnvelope } from "../../shared/contracts/envelope";
+import { FacetError } from "../../shared/errors/facet-error";
+import { generateRequestId } from "../../shared/util/time";
+
+export interface WatchFileEvent {
+  readonly eventType: "rename" | "change";
+  readonly filename?: string | null;
+}
+
+export interface WatchHandle {
+  close(): void;
+}
+
+export interface WatchPublishOptions {
+  readonly filePath: string;
+  readonly debounceMs?: number;
+  readonly signal?: AbortSignal;
+  readonly readFile?: (path: string) => Promise<Uint8Array>;
+  readonly watchDirectory?: (
+    directory: string,
+    callback: (event: WatchFileEvent) => void,
+  ) => WatchHandle;
+  readonly hash?: (bytes: Uint8Array) => string | Promise<string>;
+  readonly setTimer?: (callback: () => void, delayMs: number) => unknown;
+  readonly clearTimer?: (timer: unknown) => void;
+  readonly publish: (bytes: Uint8Array) => Promise<FacetEnvelope<unknown>>;
+  readonly emit: (envelope: FacetEnvelope<unknown>) => void;
+  readonly diagnostic?: (message: string) => void;
+}
+
+export interface WatchExit {
+  readonly code: 0;
+}
+
+const defaultReadFile = async (path: string): Promise<Uint8Array> =>
+  new Uint8Array(await readFile(path));
+
+const defaultWatchDirectory = (
+  directory: string,
+  callback: (event: WatchFileEvent) => void,
+): WatchHandle => {
+  const watcher = watch(directory, (eventType, filename) => {
+    callback(filename == null ? { eventType } : { eventType, filename: filename.toString() });
+  });
+  return { close: () => watcher.close() };
+};
+
+const defaultHash = (bytes: Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
+
+/**
+ * Keep the directory descriptor alive instead of the file descriptor: editors
+ * commonly replace the inode during an atomic save.
+ */
+export async function watchPublishFile(options: WatchPublishOptions): Promise<WatchExit> {
+  const read = options.readFile ?? defaultReadFile;
+  const watchDirectory = options.watchDirectory ?? defaultWatchDirectory;
+  const hash = options.hash ?? defaultHash;
+  const target = basename(options.filePath);
+  const debounceMs = options.debounceMs ?? 100;
+  const signal = options.signal ?? new AbortController().signal;
+  const setTimer =
+    options.setTimer ?? ((callback: () => void, delayMs: number) => setTimeout(callback, delayMs));
+  const clearTimer =
+    options.clearTimer ??
+    ((timer: unknown) => clearTimeout(timer as ReturnType<typeof setTimeout>));
+  let lastHash: string | undefined;
+  let timer: unknown;
+  let running = false;
+  let pending = false;
+  let resolveExit: (() => void) | undefined;
+  const exited = new Promise<void>((resolve) => {
+    resolveExit = resolve;
+  });
+
+  const finish = () => {
+    if (timer !== undefined) clearTimer(timer);
+    timer = undefined;
+    handle.close();
+    resolveExit?.();
+  };
+
+  const publishAttempt = async (): Promise<void> => {
+    if (signal.aborted || running) return;
+    running = true;
+    try {
+      const bytes = await read(options.filePath);
+      const nextHash = await hash(bytes);
+      if (nextHash === lastHash) {
+        options.diagnostic?.("unchanged bytes — skipped publish");
+        return;
+      }
+      const response = await options.publish(bytes);
+      lastHash = nextHash;
+      options.emit(response);
+    } catch (error) {
+      const facet = FacetError.from(error);
+      options.emit(errEnvelope(generateRequestId(), facet.toBody()));
+      options.diagnostic?.(
+        `watch publish failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    } finally {
+      running = false;
+      if (pending && !signal.aborted) {
+        pending = false;
+        schedule();
+      }
+    }
+  };
+
+  const schedule = () => {
+    if (running) {
+      pending = true;
+      return;
+    }
+    if (timer !== undefined) clearTimer(timer);
+    timer = setTimer(() => {
+      timer = undefined;
+      void publishAttempt();
+    }, debounceMs);
+  };
+
+  const handle = watchDirectory(dirname(options.filePath), (event) => {
+    // Atomic saves often report only the temporary inode's rename, not the
+    // final target name; any rename in the parent directory may be the save.
+    if (
+      event.eventType !== "rename" &&
+      event.filename !== undefined &&
+      event.filename !== null &&
+      event.filename !== target
+    )
+      return;
+    schedule();
+  });
+  const abort = () => finish();
+  signal.addEventListener("abort", abort, { once: true });
+  await publishAttempt();
+  if (signal.aborted) finish();
+  await exited;
+  signal.removeEventListener("abort", abort);
+  return { code: 0 };
+}