@legionworks/facet 1.9.0

package/src/cli/commands/doctor.ts

@@ -0,0 +1,249 @@
+import { existsSync, statSync } from "node:fs";
+import { Database } from "bun:sqlite";
+
+import { computeFacetPaths, type FacetRuntimePaths } from "../../shared/config/paths";
+import { FACET_SCHEMA_VERSION } from "../../shared/contracts/envelope";
+import { CURRENT_STORAGE_VERSION } from "../../shared/storage-version";
+import {
+  isLockStale,
+  readLockMetadata,
+  type LockMetadata,
+} from "../../service/lifecycle/process-lock";
+import { isPidAlive } from "../../shared/util/process";
+import { probeNetnsSupport, type NetnsProbe } from "../../validation/sandbox/netns";
+import { resolveShellBinary } from "../../validation/tier1/launcher";
+import type { DoctorResult } from "../../shared/contracts/commands/results";
+
+export const DOCTOR_PROBE_NAMES = [
+  "bun",
+  "chrome-headless-shell",
+  "netns-userns",
+  "database",
+  "token-permissions",
+  "evidence-permissions",
+  "service-lock",
+] as const;
+export type DoctorProbeName = (typeof DOCTOR_PROBE_NAMES)[number];
+export type DoctorProbeResult = DoctorResult["probes"][number];
+
+type DoctorFs = {
+  exists: (path: string) => boolean;
+  stat: (path: string) => { mode: number };
+};
+type DoctorDb = { quickCheck: string; version: number | null };
+export interface DoctorOptions {
+  readonly argv?: readonly string[];
+  readonly bunVersion?: string;
+  readonly paths?: FacetRuntimePaths;
+  readonly shellBinary?: string | null;
+  readonly netns?: NetnsProbe;
+  readonly fs?: DoctorFs;
+  readonly databaseReader?: (path: string) => DoctorDb;
+  readonly lockReader?: (path: string) => LockMetadata | null;
+  readonly pidAlive?: (pid: number) => boolean;
+  readonly lockStale?: (metadata: LockMetadata) => boolean;
+  readonly statusCheck?: (metadata: LockMetadata) => boolean;
+}
+
+const BUN_VERSION = "1.4.0";
+const shellFix = "bunx --bun puppeteer browsers install chrome-headless-shell@151.0.7922.77";
+const netnsFix =
+  "sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 && unshare --map-current-user --user --net -- /bin/true";
+
+function defaultDbReader(path: string): DoctorDb {
+  const db = new Database(path, { readonly: true, strict: true });
+  try {
+    const quickCheck = String(
+      (db.query("PRAGMA quick_check").get() as { quick_check?: string })?.quick_check,
+    );
+    const row = db.query("SELECT MAX(version) AS version FROM schema_migrations").get() as {
+      version?: number | null;
+    };
+    return { quickCheck, version: row.version ?? null };
+  } finally {
+    db.close();
+  }
+}
+
+function modeOf(fs: DoctorFs, path: string): number | null {
+  try {
+    return fs.stat(path).mode & 0o777;
+  } catch {
+    return null;
+  }
+}
+
+function probe(
+  name: DoctorProbeName,
+  status: "pass" | "fail",
+  summary: string,
+  fixCommand: string | null,
+  details: Record<string, string | number | boolean | null> = {},
+): DoctorProbeResult {
+  return { name, status, summary, fixCommand, details };
+}
+
+function invocationPrefix(argv: readonly string[]): string {
+  const sourceEntrypoint = argv[1];
+  return sourceEntrypoint?.endsWith("/src/cli/main.ts") === true
+    ? `bun ${sourceEntrypoint}`
+    : "facet";
+}
+
+export function runDoctor(options: DoctorOptions = {}): DoctorResult {
+  const paths = options.paths ?? computeFacetPaths();
+  const fs = options.fs ?? { exists: existsSync, stat: statSync };
+  const databaseReader = options.databaseReader ?? defaultDbReader;
+  const lockReader = options.lockReader ?? readLockMetadata;
+  const pidAlive = options.pidAlive ?? isPidAlive;
+  const lockStale = options.lockStale ?? isLockStale;
+  const shellBinary =
+    options.shellBinary === undefined ? resolveShellBinary() : options.shellBinary;
+  const netns = options.netns ?? probeNetnsSupport();
+  const probes: DoctorProbeResult[] = [];
+  const bunVersion = options.bunVersion ?? Bun.version;
+  const restartFix = `${invocationPrefix(options.argv ?? process.argv)} status --start`;
+
+  probes.push(
+    bunVersion === BUN_VERSION
+      ? probe("bun", "pass", bunVersion, null, { version: bunVersion, expected: BUN_VERSION })
+      : probe(
+          "bun",
+          "fail",
+          `${bunVersion}, expected ${BUN_VERSION}`,
+          `curl -fsSL https://bun.sh/install | bash -s "bun-v${BUN_VERSION}"`,
+          {
+            version: bunVersion,
+            expected: BUN_VERSION,
+          },
+        ),
+  );
+  probes.push(
+    shellBinary === null
+      ? probe("chrome-headless-shell", "fail", "pinned shell not found", shellFix, { found: false })
+      : probe("chrome-headless-shell", "pass", shellBinary, null, {
+          found: true,
+          path: shellBinary,
+        }),
+  );
+  probes.push(
+    netns.available
+      ? probe("netns-userns", "pass", "available", null, { available: true })
+      : probe("netns-userns", "fail", netns.reason ?? "unavailable", netnsFix, {
+          available: false,
+          reason: netns.reason,
+        }),
+  );
+
+  if (!fs.exists(paths.database)) {
+    probes.push(probe("database", "fail", "database missing", restartFix, { present: false }));
+  } else {
+    try {
+      const db = databaseReader(paths.database);
+      if (db.quickCheck !== "ok") {
+        probes.push(
+          probe("database", "fail", `quick_check ${db.quickCheck}`, restartFix, {
+            quickCheck: db.quickCheck,
+          }),
+        );
+      } else if (db.version !== CURRENT_STORAGE_VERSION) {
+        probes.push(
+          probe(
+            "database",
+            "fail",
+            `schema v${db.version ?? "unknown"}, expected v${CURRENT_STORAGE_VERSION}`,
+            restartFix,
+            {
+              version: db.version,
+              expected: CURRENT_STORAGE_VERSION,
+            },
+          ),
+        );
+      } else {
+        probes.push(
+          probe("database", "pass", `schema v${db.version}`, null, {
+            quickCheck: db.quickCheck,
+            version: db.version,
+          }),
+        );
+      }
+    } catch (error) {
+      probes.push(
+        probe(
+          "database",
+          "fail",
+          error instanceof Error ? error.message : String(error),
+          restartFix,
+        ),
+      );
+    }
+  }
+
+  const installToken = paths.token.replace(/promote\.token$/, "install.token");
+  const tokenPaths = [installToken, paths.token];
+  const tokenModes = tokenPaths.map((path) => ({ path, mode: modeOf(fs, path) }));
+  const tokenBad = tokenModes.find(({ mode }) => mode !== null && mode !== 0o600);
+  const installMode = modeOf(fs, installToken);
+  probes.push(
+    tokenBad
+      ? probe(
+          "token-permissions",
+          "fail",
+          `${tokenBad.path} mode ${tokenBad.mode?.toString(8)}`,
+          'chmod 600 "$FACET_HOME/secrets/install.token" "$FACET_HOME/secrets/promote.token"',
+          { path: tokenBad.path, mode: tokenBad.mode },
+        )
+      : installMode === null
+        ? probe("token-permissions", "fail", `${installToken} missing`, restartFix, {
+            path: installToken,
+            present: false,
+          })
+        : probe("token-permissions", "pass", "token files mode 600", null, { mode: 0o600 }),
+  );
+
+  const evidenceMode = modeOf(fs, paths.evidence);
+  probes.push(
+    evidenceMode === 0o700
+      ? probe("evidence-permissions", "pass", "mode 700", null, { mode: evidenceMode })
+      : probe(
+          "evidence-permissions",
+          "fail",
+          evidenceMode === null ? "evidence root missing" : `mode ${evidenceMode.toString(8)}`,
+          `mkdir -p "$FACET_HOME/evidence" && chmod 700 "$FACET_HOME/evidence"`,
+          { mode: evidenceMode },
+        ),
+  );
+
+  const lock = lockReader(paths.lock);
+  if (lock === null) {
+    probes.push(probe("service-lock", "pass", "dormant · no lock", null, { state: "dormant" }));
+  } else if (lockStale(lock) || !pidAlive(lock.pid)) {
+    probes.push(
+      probe("service-lock", "fail", "stale or dead lock", restartFix, {
+        pid: lock.pid,
+        stale: true,
+      }),
+    );
+  } else if (lock.contractVersion !== FACET_SCHEMA_VERSION) {
+    probes.push(
+      probe("service-lock", "fail", `cross-version lock ${lock.contractVersion}`, restartFix, {
+        contractVersion: lock.contractVersion,
+      }),
+    );
+  } else if (options.statusCheck !== undefined && !options.statusCheck(lock)) {
+    probes.push(
+      probe("service-lock", "fail", "live service status request failed", restartFix, {
+        pid: lock.pid,
+      }),
+    );
+  } else {
+    probes.push(
+      probe("service-lock", "pass", `active · pid ${lock.pid}`, null, {
+        pid: lock.pid,
+        state: "active",
+      }),
+    );
+  }
+
+  return { command: "doctor", allPassed: probes.every((item) => item.status === "pass"), probes };
+}

package/src/cli/commands/export.ts

@@ -0,0 +1,179 @@
+/**
+ * `facet export` — fetch source or retained render bytes and write the
+ * artifact plus its disclosure sidecar locally.
+ *
+ * Output paths and overwrite policy stay outside the wire request so the
+ * service cannot be used as a general filesystem writer.
+ */
+
+import { existsSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join, resolve } from "node:path";
+
+import type { ExportRequest } from "../../shared/contracts/commands/requests";
+import { ExportRequestSchema } from "../../shared/contracts/commands/requests";
+import type { ExportResult } from "../../shared/contracts/commands/results";
+import { extensionForExport, sidecarFilenameForArtifact } from "../../shared/export";
+import { FacetError } from "../../shared/errors/facet-error";
+import { generateRequestId } from "../../shared/util/time";
+
+export interface ExportPaths {
+  readonly artifactPath: string;
+  readonly sidecarPath: string;
+}
+
+export function buildExportRequest(
+  args: Readonly<Record<string, string | boolean>>,
+): ExportRequest {
+  const artifactId = args["artifact-id"];
+  if (typeof artifactId !== "string" || artifactId.length === 0) {
+    throw new FacetError("invalid_request", "export: artifact id is required", {
+      retryable: false,
+    });
+  }
+  const revision = args["revision"];
+  return ExportRequestSchema.parse({
+    command: "export",
+    requestId: generateRequestId(),
+    artifactId,
+    ...(typeof revision === "string" ? { revisionSha: revision } : {}),
+    format: typeof args["format"] === "string" ? args["format"] : "source",
+  });
+}
+
+export { extensionForExport } from "../../shared/export";
+export { sidecarFilenameForArtifact } from "../../shared/export";
+
+function sanitizeDerivedNamePart(value: string): string {
+  return value
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/\.\.+/g, "-")
+    .replace(/^[.-]+|[.-]+$/g, "")
+    .slice(0, 80)
+    .replace(/^[.-]+|[.-]+$/g, "");
+}
+
+function derivedSlug(result: ExportResult): string {
+  return (
+    sanitizeDerivedNamePart(result.sidecar.slug) ||
+    sanitizeDerivedNamePart(result.sidecar.artifactId) ||
+    "artifact"
+  );
+}
+
+function removeIfExists(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Best-effort cleanup must not replace the original write failure.
+  }
+}
+
+export function resolveExportPaths(
+  result: ExportResult,
+  outFlag: string | undefined,
+  cwd: string,
+): ExportPaths {
+  const extension = extensionForExport(
+    result.format,
+    result.sidecar.artifactType,
+    result.sidecar.renderFormat,
+  );
+  const artifactPath =
+    outFlag === undefined
+      ? resolve(cwd, `${derivedSlug(result)}-${result.sidecar.revisionSha.slice(0, 7)}${extension}`)
+      : resolve(cwd, outFlag);
+  return { artifactPath, sidecarPath: sidecarFilenameForArtifact(artifactPath) };
+}
+
+export function writeExportFiles(
+  result: ExportResult,
+  paths: ExportPaths,
+  force: boolean,
+  renameFile: typeof renameSync = renameSync,
+): void {
+  const artifactExistedBeforeWrite = existsSync(paths.artifactPath);
+  const sidecarExistedBeforeWrite = existsSync(paths.sidecarPath);
+  if (!force) {
+    const existing = [
+      artifactExistedBeforeWrite ? paths.artifactPath : null,
+      sidecarExistedBeforeWrite ? paths.sidecarPath : null,
+    ].filter((path): path is string => path !== null);
+    if (existing.length > 0) {
+      throw new FacetError(
+        "invalid_request",
+        `export output already exists: ${existing.join(", ")} (pass --force to replace)`,
+        { retryable: false, details: { reason: "output_exists" } },
+      );
+    }
+  }
+
+  mkdirSync(dirname(paths.artifactPath), { recursive: true });
+  mkdirSync(dirname(paths.sidecarPath), { recursive: true });
+  for (const target of [paths.artifactPath, paths.sidecarPath]) {
+    if (existsSync(target) && statSync(target).isDirectory()) {
+      throw new Error(`export output is a directory: ${target}`);
+    }
+  }
+
+  const artifactTempPath = join(
+    dirname(paths.artifactPath),
+    `.${basename(paths.artifactPath)}.${randomUUID()}.tmp`,
+  );
+  const sidecarTempPath = join(
+    dirname(paths.sidecarPath),
+    `.${basename(paths.sidecarPath)}.${randomUUID()}.tmp`,
+  );
+  const artifactBackupPath = artifactExistedBeforeWrite
+    ? join(dirname(paths.artifactPath), `.${basename(paths.artifactPath)}.${randomUUID()}.bak`)
+    : null;
+  const sidecarBackupPath = sidecarExistedBeforeWrite
+    ? join(dirname(paths.sidecarPath), `.${basename(paths.sidecarPath)}.${randomUUID()}.bak`)
+    : null;
+  let artifactRenamed = false;
+  let sidecarRenamed = false;
+
+  const restoreTarget = (target: string, backup: string | null, wasRenamed: boolean): void => {
+    try {
+      if (backup !== null) {
+        if (existsSync(target)) removeIfExists(target);
+        if (existsSync(backup)) renameSync(backup, target);
+      } else if (wasRenamed) {
+        removeIfExists(target);
+      }
+    } catch {
+      // Best-effort rollback must not mask the original rename failure.
+    }
+  };
+
+  try {
+    writeFileSync(artifactTempPath, Buffer.from(result.bytes, "base64"), {
+      flag: "wx",
+      mode: 0o600,
+    });
+    writeFileSync(sidecarTempPath, `${JSON.stringify(result.sidecar, null, 2)}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    if (artifactBackupPath !== null) renameFile(paths.artifactPath, artifactBackupPath);
+    if (sidecarBackupPath !== null) renameFile(paths.sidecarPath, sidecarBackupPath);
+    renameFile(artifactTempPath, paths.artifactPath);
+    artifactRenamed = true;
+    renameFile(sidecarTempPath, paths.sidecarPath);
+    sidecarRenamed = true;
+    if (artifactBackupPath !== null) removeIfExists(artifactBackupPath);
+    if (sidecarBackupPath !== null) removeIfExists(sidecarBackupPath);
+  } catch (error) {
+    for (const tempPath of [artifactTempPath, sidecarTempPath]) {
+      try {
+        unlinkSync(tempPath);
+      } catch {
+        // Preserve the write or rename failure as the useful error at the CLI boundary.
+      }
+    }
+    restoreTarget(paths.sidecarPath, sidecarBackupPath, sidecarRenamed);
+    restoreTarget(paths.artifactPath, artifactBackupPath, artifactRenamed);
+    throw error;
+  }
+}

package/src/cli/commands/instantiate.ts

@@ -0,0 +1,35 @@
+/**
+ * `facet instantiate` — create a new artifact from a named template.
+ *
+ * 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 { InstantiateRequest } from "../../shared/contracts/commands/requests";
+
+export function buildInstantiateRequest(
+  args: Readonly<Record<string, string | boolean>>,
+): InstantiateRequest {
+  const name = args["name"];
+  const newSlug = args["new-slug"];
+  if (typeof name !== "string" || name.length === 0) {
+    throw new FacetError("invalid_request", "--name is required for instantiate", {
+      retryable: false,
+    });
+  }
+  if (typeof newSlug !== "string" || newSlug.length === 0) {
+    throw new FacetError("invalid_request", "--new-slug is required for instantiate", {
+      retryable: false,
+    });
+  }
+  const projectId = args["project-id"];
+  return {
+    command: "instantiate",
+    requestId: generateRequestId(),
+    name,
+    newSlug,
+    ...(typeof projectId === "string" ? { projectId } : {}),
+  };
+}

package/src/cli/commands/list.ts

@@ -0,0 +1,49 @@
+/**
+ * `facet list` — list artifacts for a project.
+ *
+ * Supports optional `--slug-prefix` and `--limit` filters. The
+ * service applies its own `MAX_LIST_LIMIT` cap, so the CLI does
+ * NOT clamp — a too-large limit surfaces as a typed `invalid_request`
+ * from the service and the envelope carries the typed code.
+ *
+ * Input-validation errors throw `FacetError("invalid_request", ...)`
+ * so the envelope preserves the typed `invalid_request` code; the
+ * main catch recognises a pre-existing FacetError and passes its
+ * body through unchanged.
+ */
+
+import { generateRequestId } from "../../shared/util/time";
+import { FacetError } from "../../shared/errors/facet-error";
+import { MAX_LIST_LIMIT } from "../../shared/config/limits";
+import type { ListRequest } from "../../shared/contracts/commands/requests";
+
+export function buildListRequest(args: Readonly<Record<string, string | boolean>>): ListRequest {
+  const projectId = args["project-id"];
+  if (typeof projectId !== "string" || projectId.length === 0) {
+    throw new FacetError("invalid_request", "--project-id is required for list", {
+      retryable: false,
+    });
+  }
+  const slugPrefix = args["slug-prefix"];
+  const limit = args["limit"];
+  const limitNumber = typeof limit === "string" ? Number(limit) : undefined;
+  if (
+    limitNumber !== undefined &&
+    (!Number.isSafeInteger(limitNumber) || limitNumber < 1 || limitNumber > MAX_LIST_LIMIT)
+  ) {
+    throw new FacetError(
+      "invalid_request",
+      `--limit must be an integer between 1 and ${MAX_LIST_LIMIT}`,
+      {
+        retryable: false,
+      },
+    );
+  }
+  return {
+    command: "list",
+    requestId: generateRequestId(),
+    projectId,
+    ...(typeof slugPrefix === "string" ? { slugPrefix } : {}),
+    ...(limitNumber !== undefined ? { limit: limitNumber } : {}),
+  };
+}

package/src/cli/commands/open.ts

@@ -0,0 +1,75 @@
+/**
+ * `facet open` — issue a gallery lease + frame URL for a revision.
+ *
+ * The frame URL does NOT carry the lease id; the lease is delivered
+ * out-of-band in the response body. The CLI prints the envelope
+ * verbatim and lets the adapter carry the lease to its own
+ * transport.
+ *
+ * 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 { OpenRequest } from "../../shared/contracts/commands/requests";
+import { spawn } from "node:child_process";
+
+export type OpenLauncher = (url: string) => void | Promise<void>;
+
+export interface DisplayOpenResult {
+  readonly frameUrl: string;
+  readonly installToken?: string;
+}
+
+function launchWithXdgOpen(url: string): void {
+  const child = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+  child.unref();
+}
+
+export async function launchDisplay(
+  result: DisplayOpenResult,
+  launcher: OpenLauncher = launchWithXdgOpen,
+): Promise<boolean> {
+  if (result.installToken !== undefined && result.frameUrl.includes(result.installToken)) {
+    throw new FacetError("invalid_envelope", "Display URL contains the install token", {
+      retryable: false,
+    });
+  }
+  const parsed = new URL(result.frameUrl);
+  if (parsed.hostname !== "127.0.0.1") {
+    throw new FacetError("invalid_envelope", "Display URL must be loopback-only", {
+      retryable: false,
+    });
+  }
+  try {
+    await launcher(result.frameUrl);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function buildOpenRequest(args: Readonly<Record<string, string | boolean>>): OpenRequest {
+  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 open", {
+      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: "open",
+    requestId: generateRequestId(),
+    artifactId,
+    ...(revisionSha === undefined ? {} : { revisionSha }),
+  };
+}

package/src/cli/commands/pin.ts

@@ -0,0 +1,39 @@
+/**
+ * `facet pin` — pin or unpin a revision.
+ *
+ * `--pinned true|false` is parsed as a boolean; anything else is a
+ * usage error before the wire.
+ *
+ * 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 { PinRequest } from "../../shared/contracts/commands/requests";
+
+function parsePinned(raw: string | boolean | undefined): boolean {
+  if (typeof raw === "boolean") return raw;
+  if (typeof raw === "string") {
+    if (raw === "true") return true;
+    if (raw === "false") return false;
+  }
+  throw new FacetError("invalid_request", "--pinned must be 'true' or 'false'", {
+    retryable: false,
+  });
+}
+
+export function buildPinRequest(args: Readonly<Record<string, string | boolean>>): PinRequest {
+  const revisionId = args["revision-id"];
+  if (typeof revisionId !== "string" || revisionId.length === 0) {
+    throw new FacetError("invalid_request", "--revision-id is required for pin", {
+      retryable: false,
+    });
+  }
+  return {
+    command: "pin",
+    requestId: generateRequestId(),
+    revisionId,
+    pinned: parsePinned(args["pinned"]),
+  };
+}

package/src/cli/commands/promote.ts

@@ -0,0 +1,49 @@
+/**
+ * `facet promote` — promote a revision to a named template.
+ *
+ * Promote requires the operator token (enforced by the service at
+ * the router level — install-bearer callers receive 403). The CLI
+ * does NOT inject the operator token; out-of-band provisioning is
+ * the only path to a working promote, by design (ADR 0001 D4).
+ *
+ * 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 { PromoteRequest } from "../../shared/contracts/commands/requests";
+
+export function buildPromoteRequest(
+  args: Readonly<Record<string, string | boolean>>,
+): PromoteRequest {
+  const revisionId = args["revision-id"];
+  const name = args["name"];
+  const promotedBy = args["promoted-by"];
+  if (typeof revisionId !== "string" || revisionId.length === 0) {
+    throw new FacetError("invalid_request", "--revision-id is required for promote", {
+      retryable: false,
+    });
+  }
+  if (typeof name !== "string" || name.length === 0) {
+    throw new FacetError("invalid_request", "--name is required for promote", {
+      retryable: false,
+    });
+  }
+  if (typeof promotedBy !== "string" || promotedBy.length === 0) {
+    throw new FacetError("invalid_request", "--promoted-by is required for promote", {
+      retryable: false,
+    });
+  }
+  const artifactId = args["artifact-id"];
+  const description = args["description"];
+  return {
+    command: "promote",
+    requestId: generateRequestId(),
+    revisionId,
+    name,
+    promotedBy,
+    ...(typeof artifactId === "string" ? { artifactId } : {}),
+    ...(typeof description === "string" ? { description } : {}),
+  };
+}