@clickraft/cli 0.6.1 → 0.7.1

package/dist/index.js

@@ -146,17 +146,35 @@ var EXIT_CODE_MAP = {
     retryable: false,
     hint: "Run `node-type list` for the current set of node types."
   },
-  WORKFLOW_VERSION_REQUIRED: {
+  CANVAS_REV_MISMATCH: {
+    exitCode: 7,
+    category: "conflict",
+    retryable: false,
+    hint: "The workflow was updated elsewhere. Re-fetch and retry with the current canvas_rev."
+  },
+  CANVAS_REV_REQUIRED: {
     exitCode: 2,
     category: "usage",
     retryable: false,
-    hint: 'Send `If-Match: "<version>"` from the last `workflow get` response.'
+    hint: "Include --canvas-rev or use --auto-rev."
   },
-  WORKFLOW_VERSION_CONFLICT: {
+  WORKER_UNREACHABLE: {
+    exitCode: 6,
+    category: "network",
+    retryable: true,
+    hint: "Collaboration service temporarily unavailable. Retry."
+  },
+  IDEMPOTENCY_IN_PROGRESS: {
     exitCode: 7,
     category: "conflict",
     retryable: false,
-    hint: "The workflow was updated elsewhere. Re-fetch and retry."
+    hint: "A request with this idempotency key is currently in-flight. Retry in a moment."
+  },
+  TOKEN_NAME_INVALID: {
+    exitCode: 2,
+    category: "usage",
+    retryable: false,
+    hint: "Agent token name is malformed."
   },
   WORKFLOW_NOT_FOUND: {
     exitCode: 2,
@@ -2881,6 +2899,170 @@ async function listTokens(options) {
   return data;
 }
 
+// src/schemas/workflows.ts
+import { z as z12 } from "zod";
+var WorkflowDeclaredParamSchema = z12.object({
+  name: z12.string(),
+  type: z12.string(),
+  required: z12.boolean().optional(),
+  defaultValue: z12.unknown().optional(),
+  description: z12.unknown().optional()
+}).passthrough();
+var WorkflowSummarySchema = z12.object({
+  id: z12.string().uuid(),
+  name: z12.string(),
+  tags: z12.array(z12.string()),
+  declared_params: z12.array(WorkflowDeclaredParamSchema).nullable().default([]),
+  canvas_rev: z12.number().int().nonnegative(),
+  updated_at: z12.string()
+}).strict();
+var WorkflowsListResponseSchema = z12.object({
+  items: z12.array(WorkflowSummarySchema),
+  nextCursor: z12.string().nullable()
+}).strict();
+var WorkflowDetailSchema = z12.object({
+  id: z12.string().uuid(),
+  name: z12.string(),
+  description: z12.string().nullable(),
+  tags: z12.array(z12.string()),
+  declared_params: z12.array(WorkflowDeclaredParamSchema).nullable().default([]),
+  canvas_rev: z12.number().int().nonnegative(),
+  nodes: z12.array(z12.unknown()),
+  edges: z12.array(z12.unknown()),
+  created_at: z12.string(),
+  updated_at: z12.string()
+}).strict();
+var WorkflowCreateResponseSchema = z12.object({
+  id: z12.string().uuid(),
+  name: z12.string(),
+  description: z12.string().nullable(),
+  tags: z12.array(z12.string()),
+  declared_params: z12.array(WorkflowDeclaredParamSchema).nullable().default([]),
+  canvas_rev: z12.number().int().nonnegative(),
+  created_at: z12.string(),
+  updated_at: z12.string()
+}).strict();
+var WorkflowMutateResponseSchema = z12.object({
+  canvas_rev: z12.number().int().nonnegative(),
+  applied: z12.number().int().nonnegative(),
+  workflow: WorkflowDetailSchema
+}).strict();
+
+// src/commands/workflow/internal.ts
+async function buildWorkflowClient(opts) {
+  const cfg = await loadConfig({
+    flagProfile: opts.profile,
+    flagApiBaseUrl: opts.apiBaseUrl,
+    flagToken: opts.token
+  });
+  return new ApiClient({
+    apiBaseUrl: cfg.apiBaseUrl,
+    accessToken: cfg.accessToken,
+    signal: opts.signal,
+    cloudflareAccess: cfg.cloudflareAccess
+  });
+}
+
+// src/commands/workflow/get.ts
+async function getWorkflow(opts) {
+  const client = opts.client ?? await buildWorkflowClient(opts);
+  return client.request({
+    method: "GET",
+    path: `/workflows/${encodeURIComponent(opts.id)}`,
+    responseSchema: WorkflowDetailSchema,
+    signal: opts.signal
+  });
+}
+
+// src/commands/workflow/apply.ts
+async function applyWorkflow(opts) {
+  const client = opts.client ?? await buildWorkflowClient(opts);
+  try {
+    return await patchWorkflow(client, opts);
+  } catch (err) {
+    if (!(err instanceof ApiError)) throw err;
+    const isRevConflict = err.code === "CANVAS_REV_MISMATCH" || err.meta.status === 409 && err.meta.details != null;
+    if (!isRevConflict || !opts.autoRev) throw err;
+    const snapshot = await getWorkflow({ id: opts.id, client, signal: opts.signal });
+    const retryResult = await patchWorkflow(client, {
+      ...opts,
+      canvasRev: snapshot.canvas_rev,
+      // Fresh key — the body changed (different canvas_rev), so reusing
+      // the caller's key would trigger IDEMPOTENCY_KEY_CONFLICT.
+      idempotencyKey: void 0
+    });
+    return { ...retryResult, retriedWithRev: snapshot.canvas_rev };
+  }
+}
+async function patchWorkflow(client, opts) {
+  const data = await client.request({
+    method: "PATCH",
+    path: `/workflows/${encodeURIComponent(opts.id)}`,
+    body: {
+      canvas_rev: opts.canvasRev,
+      operations: opts.operations
+    },
+    idempotencyKey: opts.idempotencyKey,
+    responseSchema: WorkflowMutateResponseSchema,
+    signal: opts.signal
+  });
+  return {
+    canvasRev: data.canvas_rev,
+    applied: data.applied,
+    workflow: data.workflow
+  };
+}
+
+// src/commands/workflow/create.ts
+function toParamArray(input) {
+  if (Array.isArray(input)) return input;
+  return Object.entries(input).map(([key, val]) => {
+    const def = typeof val === "object" && val !== null ? val : {};
+    if (def.name !== void 0 && def.name !== key) {
+      throw new ArgError(
+        `declared_params key '${key}' conflicts with inner name '${String(def.name)}'.`
+      );
+    }
+    return { name: key, ...def };
+  });
+}
+async function createWorkflow(opts) {
+  const client = opts.client ?? await buildWorkflowClient(opts);
+  const body = { name: opts.name };
+  if (opts.description !== void 0) body.description = opts.description;
+  if (opts.tags !== void 0 && opts.tags.length > 0) body.tags = opts.tags;
+  if (opts.declaredParams !== void 0) body.declared_params = toParamArray(opts.declaredParams);
+  return client.request({
+    method: "POST",
+    path: "/workflows",
+    body,
+    responseSchema: WorkflowCreateResponseSchema,
+    signal: opts.signal
+  });
+}
+
+// src/commands/workflow/list.ts
+async function listWorkflows(opts) {
+  const client = opts.client ?? await buildWorkflowClient(opts);
+  const data = await client.request({
+    method: "GET",
+    path: "/workflows",
+    query: {
+      cursor: opts.cursor,
+      limit: opts.limit,
+      tags: opts.tags?.join(","),
+      declared_params_has_key: opts.declaredParamsHasKey
+    },
+    responseSchema: WorkflowsListResponseSchema,
+    signal: opts.signal
+  });
+  return {
+    items: data.items,
+    nextCursor: data.nextCursor,
+    hasMore: data.nextCursor !== null
+  };
+}
+
 // src/errors/format.ts
 var FALLBACK_HINT = "See `clickraft --help` or contact support.";
 function formatHumanError(err) {
@@ -3330,6 +3512,81 @@ function formatExpiresAt(iso) {
   const days = Math.round((ms - Date.now()) / (24 * 60 * 60 * 1e3));
   return `${date.toISOString()} (~${days}d)`;
 }
+function renderWorkflowCreateResult(result, out) {
+  const lines = [
+    `Created workflow "${result.name}"`,
+    `  ID:         ${result.id}`,
+    `  Canvas rev: ${result.canvas_rev}`,
+    `  Created:    ${result.created_at.slice(0, 19)}`
+  ];
+  out.write(lines.join("\n") + "\n");
+}
+function renderWorkflowsList(result, out) {
+  const { items } = result;
+  if (items.length === 0) {
+    out.write("No workflows.\n");
+    return;
+  }
+  const MAX_TAGS = 3;
+  const headers = ["ID", "NAME", "TAGS", "REV", "UPDATED"];
+  const data = items.map((w) => {
+    const shown = w.tags.slice(0, MAX_TAGS).join(", ");
+    const extra = w.tags.length > MAX_TAGS ? ` +${w.tags.length - MAX_TAGS} more` : "";
+    return [
+      w.id.slice(0, 8),
+      w.name,
+      w.tags.length > 0 ? shown + extra : "\u2014",
+      String(w.canvas_rev),
+      w.updated_at.slice(0, 10)
+    ];
+  });
+  const widths = headers.map(
+    (header, i) => Math.max(header.length, ...data.map((cells) => cells[i].length))
+  );
+  const padRow = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
+  out.write(padRow(headers) + "\n");
+  for (const cells of data) out.write(padRow(cells) + "\n");
+  if (result.hasMore) {
+    out.write("\nMore results available. Use --cursor to fetch the next page.\n");
+  }
+}
+function renderWorkflowDetail(detail, out) {
+  const pad = 17;
+  const lines = [
+    detail.name,
+    `${"ID:".padEnd(pad)}${detail.id}`,
+    `${"Canvas rev:".padEnd(pad)}${detail.canvas_rev}`,
+    `${"Tags:".padEnd(pad)}${detail.tags.length > 0 ? detail.tags.join(", ") : "\u2014"}`,
+    `${"Created:".padEnd(pad)}${detail.created_at.slice(0, 19)}`,
+    `${"Updated:".padEnd(pad)}${detail.updated_at.slice(0, 19)}`,
+    `${"Nodes:".padEnd(pad)}${detail.nodes.length}`,
+    `${"Edges:".padEnd(pad)}${detail.edges.length}`
+  ];
+  if (detail.description) {
+    lines.push("", detail.description);
+  }
+  const params = detail.declared_params;
+  lines.push("", "Declared parameters:");
+  if (!params || params.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const p of params) {
+      const req = p.required ? "required" : "optional";
+      const desc = p.description ? `: ${p.description}` : "";
+      lines.push(`  - ${p.name} (${p.type}, ${req})${desc}`);
+    }
+  }
+  out.write(lines.join("\n") + "\n");
+}
+function renderWorkflowApplyResult(result, out) {
+  const lines = [
+    `Applied ${result.applied} operation${result.applied === 1 ? "" : "s"}. New canvas_rev: ${result.canvasRev}`
+  ];
+  if (result.retriedWithRev !== void 0) {
+    lines.push(`  (auto-rev: resolved conflict, retried with canvas_rev ${result.retriedWithRev})`);
+  }
+  out.write(lines.join("\n") + "\n");
+}
 
 // src/cli/dispatch.ts
 async function dispatch(options) {
@@ -3559,6 +3816,10 @@ function renderRootHelp(version) {
     "  generate wait           Wait for an existing job to reach a terminal state",
     "  generate get            Fetch the current state of a job",
     "  jobs wait               Alias of `generate wait`",
+    "  workflow create         Create a new empty workflow",
+    "  workflow list           List workflows in your organization",
+    "  workflow get            Fetch a workflow snapshot by ID",
+    "  workflow apply          Apply operations to a workflow (canvas mutation)",
     "  upload <file>           Upload a local file and return its public URL",
     "",
     "Options:",
@@ -3852,6 +4113,83 @@ function renderCommandHelp(command) {
         "  --json",
         ""
       ].join("\n");
+    case "workflow":
+      return [
+        "Usage: clickraft workflow <subcommand> [options]",
+        "",
+        "Subcommands:",
+        "  create  Create a new empty workflow",
+        "  list    List workflows in your organization",
+        "  get     Fetch a workflow snapshot by ID",
+        "  apply   Apply operations to a workflow (canvas mutation)",
+        ""
+      ].join("\n");
+    case "workflow create":
+      return [
+        "Usage: clickraft workflow create --name <name> [options]",
+        "",
+        "Creates a new empty workflow.",
+        "",
+        "Options:",
+        "  --name <name>             Workflow name (required unless --from-file)",
+        "  --description <text>      Optional description",
+        "  --tags <tag>              Tag (repeatable)",
+        "  --from-file <path>        Read the full create payload as JSON from a file",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
+    case "workflow list":
+      return [
+        "Usage: clickraft workflow list [options]",
+        "",
+        "Lists workflows in your organization. Supports cursor-based pagination.",
+        "",
+        "Options:",
+        "  --tags <csv>              Filter by tags (comma-separated)",
+        "  --has-param <key>         Filter to workflows that declare this param",
+        "  --limit <n>               Max results per page (1-100, default: 20)",
+        "  --cursor <token>          Pagination cursor from a previous response",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
+    case "workflow get":
+      return [
+        "Usage: clickraft workflow get <id> [options]",
+        "",
+        "Fetches a workflow snapshot including nodes and edges.",
+        "",
+        "Options:",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
+    case "workflow apply":
+      return [
+        "Usage: clickraft workflow apply <id> [options]",
+        "",
+        "Applies mutation operations to a workflow. Requires --canvas-rev or --auto-rev.",
+        "",
+        "Options:",
+        "  --from-file <path>        JSON file with operations (array or { canvas_rev, operations })",
+        "  --op <json>               Single operation as JSON string (repeatable)",
+        "  --canvas-rev <n>          The canvas_rev preconditioning the mutation",
+        "  --auto-rev                Fetch current canvas_rev first; retry once on 409",
+        "  --idempotency-key <key>   Override the auto-generated idempotency key",
+        "  --dry-run                 Print the request payload without sending it",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
     default:
       return `Unknown command: ${path}
 Run \`clickraft --help\` for available commands.
@@ -3898,6 +4236,15 @@ function matchNewCommand(argv) {
     if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "models" };
     return { kind: "unknown-sub", verb: "models", sub };
   }
+  if (verb === "workflow") {
+    const sub = argv[1];
+    if (sub === "create") return { kind: "cmd", path: "workflow.create", verbTokenCount: 2 };
+    if (sub === "list") return { kind: "cmd", path: "workflow.list", verbTokenCount: 2 };
+    if (sub === "get") return { kind: "cmd", path: "workflow.get", verbTokenCount: 2 };
+    if (sub === "apply") return { kind: "cmd", path: "workflow.apply", verbTokenCount: 2 };
+    if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "workflow" };
+    return { kind: "unknown-sub", verb: "workflow", sub };
+  }
   return null;
 }
 async function runNewCommand(newCmd, options, stdout, stderr) {
@@ -3958,6 +4305,14 @@ async function runNewCommand(newCmd, options, stdout, stderr) {
         return await runProductList(argvAfterVerb, ctx, rc);
       case "models.list":
         return await runModelsList(argvAfterVerb, ctx, rc);
+      case "workflow.create":
+        return await runWorkflowCreate(argvAfterVerb, ctx, rc);
+      case "workflow.list":
+        return await runWorkflowList(argvAfterVerb, ctx, rc);
+      case "workflow.get":
+        return await runWorkflowGet(argvAfterVerb, ctx, rc);
+      case "workflow.apply":
+        return await runWorkflowApply(argvAfterVerb, ctx, rc);
     }
   } catch (err) {
     if (isAbortedError(err, options.signal)) {
@@ -4329,6 +4684,211 @@ function emitModelsList(result, ctx, rc, parsed) {
     }
   });
 }
+async function runWorkflowCreate(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS, "name", "description", "from-file"],
+    boolean: [...COMMON_RICH_BOOL_FLAGS],
+    array: ["tags"]
+  });
+  let name = parsed.string.name;
+  let description = parsed.string.description;
+  let tags = parsed.array.tags;
+  let declaredParams;
+  if (parsed.string["from-file"]) {
+    const raw = await readJsonFile(parsed.string["from-file"]);
+    if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+      const obj = raw;
+      name = name ?? (typeof obj.name === "string" ? obj.name : void 0);
+      description = description ?? (typeof obj.description === "string" ? obj.description : void 0);
+      if (!tags && Array.isArray(obj.tags)) tags = obj.tags;
+      if (obj.declared_params != null && typeof obj.declared_params === "object") {
+        declaredParams = obj.declared_params;
+      }
+    }
+  }
+  if (!name) throw new ArgError("--name is required (or provide it in --from-file).");
+  const result = await createWorkflow({
+    name,
+    description,
+    tags,
+    declaredParams,
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  emitWorkflowCreate(result, ctx, rc);
+  return 0;
+}
+async function runWorkflowList(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS, "tags", "has-param", "cursor", "limit"],
+    boolean: [...COMMON_RICH_BOOL_FLAGS]
+  });
+  const limit = optionalInt(parsed.string.limit, "limit");
+  if (limit !== void 0 && (limit < 1 || limit > 100)) {
+    throw new ArgError("--limit must be between 1 and 100.");
+  }
+  const result = await listWorkflows({
+    cursor: parsed.string.cursor,
+    limit,
+    tags: parsed.string.tags ? parsed.string.tags.split(",").map((s) => s.trim()).filter(Boolean) : void 0,
+    declaredParamsHasKey: parsed.string["has-param"],
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  ctx.nextCursor = result.nextCursor ?? void 0;
+  emitWorkflowList(result, ctx, rc);
+  return 0;
+}
+async function runWorkflowGet(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS],
+    boolean: [...COMMON_RICH_BOOL_FLAGS]
+  });
+  const id = parsed.positional[0];
+  if (!id) throw new ArgError("Missing required <id> argument.");
+  const detail = await getWorkflow({
+    id,
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  emitWorkflowDetail(detail, ctx, rc);
+  return 0;
+}
+async function runWorkflowApply(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS, "canvas-rev", "from-file", "idempotency-key"],
+    boolean: [...COMMON_RICH_BOOL_FLAGS, "auto-rev", "dry-run"],
+    array: ["op"]
+  });
+  const id = parsed.positional[0];
+  if (!id) throw new ArgError("Missing required <id> argument.");
+  let operations = [];
+  let fileCanvasRev;
+  if (parsed.string["from-file"]) {
+    const raw = await readJsonFile(parsed.string["from-file"]);
+    if (Array.isArray(raw)) {
+      operations = raw;
+    } else if (typeof raw === "object" && raw !== null && "operations" in raw) {
+      const obj = raw;
+      operations = obj.operations;
+      if (typeof obj.canvas_rev === "number") fileCanvasRev = obj.canvas_rev;
+    } else {
+      throw new ArgError(
+        '--from-file must contain a JSON array or an object with an "operations" key.'
+      );
+    }
+  }
+  if (parsed.array.op) {
+    for (const opStr of parsed.array.op) {
+      try {
+        operations.push(JSON.parse(opStr));
+      } catch {
+        throw new ArgError(`Invalid JSON in --op: ${opStr}`);
+      }
+    }
+  }
+  if (operations.length === 0) {
+    throw new ArgError("No operations provided. Use --from-file or --op.");
+  }
+  if (operations.length > 100) {
+    throw new ArgError("At most 100 operations per request.");
+  }
+  const autoRev = parsed.boolean["auto-rev"] === true;
+  let canvasRev;
+  if (parsed.string["canvas-rev"] !== void 0) {
+    const n = optionalInt(parsed.string["canvas-rev"], "canvas-rev");
+    if (n === void 0) throw new ArgError("--canvas-rev must be a non-negative integer.");
+    canvasRev = n;
+  } else if (autoRev) {
+    const snapshot = await getWorkflow({
+      id,
+      profile: parsed.string.profile,
+      apiBaseUrl: parsed.string["api-base-url"],
+      token: parsed.string.token,
+      signal: rc.signal
+    });
+    canvasRev = snapshot.canvas_rev;
+  } else if (fileCanvasRev !== void 0) {
+    canvasRev = fileCanvasRev;
+  } else {
+    throw new ArgError(
+      "Must provide --canvas-rev, use --auto-rev, or include canvas_rev in --from-file."
+    );
+  }
+  if (parsed.boolean["dry-run"] === true) {
+    const payload = { canvas_rev: canvasRev, operations };
+    rc.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    return 0;
+  }
+  const result = await applyWorkflow({
+    id,
+    canvasRev,
+    operations,
+    idempotencyKey: parsed.string["idempotency-key"],
+    autoRev,
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  emitWorkflowApply(result, ctx, rc);
+  return 0;
+}
+function emitWorkflowCreate(result, ctx, rc) {
+  if (rc.signal?.aborted) throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(result, ctx)) + "\n");
+    return;
+  }
+  renderWorkflowCreateResult(result, rc.stdout);
+}
+function emitWorkflowList(result, ctx, rc) {
+  if (rc.signal?.aborted) throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(result, ctx)) + "\n");
+    return;
+  }
+  renderWorkflowsList(result, rc.stdout);
+}
+function emitWorkflowDetail(detail, ctx, rc) {
+  if (rc.signal?.aborted) throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(detail, ctx)) + "\n");
+    return;
+  }
+  renderWorkflowDetail(detail, rc.stdout);
+}
+function emitWorkflowApply(result, ctx, rc) {
+  if (rc.signal?.aborted) throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(result, ctx)) + "\n");
+    return;
+  }
+  renderWorkflowApplyResult(result, rc.stdout);
+}
+async function readJsonFile(filePath) {
+  const { readFile: readFile3 } = await import("fs/promises");
+  let text;
+  try {
+    text = await readFile3(filePath, "utf8");
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") throw new ArgError(`File not found: ${filePath}`);
+    if (code === "EACCES") throw new ArgError(`Permission denied: ${filePath}`);
+    throw new ArgError(`Failed to read file: ${filePath}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ArgError(`File is not valid JSON: ${filePath}`);
+  }
+}
 
 // src/index.ts
 var __filename2 = fileURLToPath(import.meta.url);