@openbkn/bkn-sdk 0.1.2 → 0.1.3

package/dist/cli.js

@@ -8,6 +8,7 @@ import {
   activePlatform,
   attachToken,
   changePasswordSafe,
+  classifyPath,
   createClient,
   credentialDeviceLogin,
   currentToken,
@@ -16,9 +17,11 @@ import {
   deletePlatform,
   deviceLogin,
   exportCreds,
+  filesUnder,
   formatError,
   getUserSafe,
   isHeadless,
+  lifecycleHint,
   listPlatforms,
   logout,
   openBrowser,
@@ -26,7 +29,9 @@ import {
   parsePkMap,
   rawCall,
   readPlatformConfig,
+  releaseLifecycleSessions,
   renderReportMarkdown,
+  renderTree,
   resolveContext,
   setActivePlatform,
   status,
@@ -36,7 +41,7 @@ import {
   validateFixturePath,
   whoami,
   writePlatformConfig
-} from "./chunk-LH3ONZGQ.js";
+} from "./chunk-PC2F54XD.js";
 
 // src/cli.ts
 import { Command as Command17 } from "commander";
@@ -44,12 +49,12 @@ import { Command as Command17 } from "commander";
 // package.json
 var package_default = {
   name: "@openbkn/bkn-sdk",
-  version: "0.1.2",
+  version: "0.1.3",
   description: "Unified TypeScript SDK + CLI for the BKN (Business Knowledge Network) platform.",
   type: "module",
   license: "Apache-2.0",
   engines: {
-    node: ">=18"
+    node: ">=22.19.0"
   },
   bin: {
     openbkn: "./dist/cli.js"
@@ -89,9 +94,9 @@ var package_default = {
     chalk: "^5.4.1",
     commander: "^13.1.0",
     "csv-parse": "^6.2.1",
-    "js-yaml": "^4.2.0",
+    "js-yaml": "^4.3.0",
     jszip: "^3.10.1",
-    undici: "^8.7.0",
+    undici: "^8.9.0",
     zod: "^3.24.1"
   },
   devDependencies: {
@@ -255,8 +260,7 @@ var NOISE_COLS = /* @__PURE__ */ new Set([
   "status_message",
   "last_check_time",
   "last_discover_status",
-  "health_check_result",
-  "health_check_enabled"
+  "health_check_result"
 ]);
 var isNoiseCol = (c) => NOISE_COLS.has(c) || /_time$/.test(c);
 var isKeyCol = (c) => /^(id|name|key|title|label)$/i.test(c) || /_(id|name|key)$/i.test(c) || /^(status|state|type|category|mode|enabled|version|branch)$/i.test(c);
@@ -1610,7 +1614,11 @@ function callCommand() {
       process.stdout.write(res.body.endsWith("\n") ? res.body : `${res.body}
 `);
     }
-    if (res.status >= 400) process.exitCode = 1;
+    if (res.status >= 400) {
+      const hint = lifecycleHint(res.body);
+      if (hint) console.error(hint);
+      process.exitCode = 1;
+    }
   });
   return group(cmd, "AUTHENTICATION & CONFIG");
 }
@@ -2158,6 +2166,29 @@ function resourceCommand() {
 // src/commands/skill.ts
 import { Command as Command13 } from "commander";
 var int10 = (v) => Number.parseInt(v, 10);
+var positiveInt = (flag) => (v) => {
+  if (!/^\d+$/.test(v)) {
+    throw new InputError(`${flag} must be a positive integer (got '${v}')`);
+  }
+  const n = Number.parseInt(v, 10);
+  if (!Number.isSafeInteger(n) || n <= 0) {
+    throw new InputError(`${flag} must be a positive integer (got '${v}')`);
+  }
+  return n;
+};
+var MOCKED_EXIT_CODE = 125;
+function sandboxExitCode(result) {
+  if (result?.mocked) return MOCKED_EXIT_CODE;
+  const code = result?.exit_code ?? 0;
+  if (!Number.isSafeInteger(code) || code < 0) return 1;
+  return code > 255 ? 1 : code;
+}
+var SKILL_SOURCES = ["custom", "internal"];
+function checkSource(source) {
+  if (source === void 0 || SKILL_SOURCES.includes(source)) return source;
+  throw new InputError(`--source must be one of: ${SKILL_SOURCES.join(" | ")} (got '${source}')`);
+}
+var draftOption = (c) => c.option("--draft", "read the draft (management) version instead of the published one");
 function skillCommand() {
   const cmd = new Command13("skill").description("Skill registry and market");
   const listOpts = (c) => c.option("--name <s>", "filter by name").option("--source <s>", "filter by source").option("--status <s>", "filter by status").option("--limit <n>", "page size", int10, DEFAULT_LIST_LIMIT).option("--page <n>", "page", int10, 1);
@@ -2196,11 +2227,97 @@ function skillCommand() {
   cmd.command("delete <skill-id>").description("Delete a skill").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).skills.delete(id), outputOptions(cmd2));
   });
-  cmd.command("content <skill-id>").description("Read a skill's SKILL.md content index").action(async (id, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).skills.content(id), outputOptions(cmd2));
+  draftOption(cmd.command("content <skill-id>")).description("Read a skill's SKILL.md content index").option("--raw", "write SKILL.md's own text instead of the index JSON").action(async (id, opts, cmd2) => {
+    const skills = clientFrom(cmd2).skills;
+    if (opts.raw) {
+      process.stdout.write(await skills.contentRaw(id, { draft: opts.draft }));
+      return;
+    }
+    printJson(await skills.content(id, { draft: opts.draft }), outputOptions(cmd2));
+  });
+  draftOption(cmd.command("read-file <skill-id> <rel-path>")).description("Read a file inside a skill (progressive)").option("--raw", "write the file's own text instead of the response JSON").action(async (id, relPath, opts, cmd2) => {
+    const skills = clientFrom(cmd2).skills;
+    if (opts.raw) {
+      process.stdout.write(await skills.readFileRaw(id, relPath, { draft: opts.draft }));
+      return;
+    }
+    printJson(await skills.readFile(id, relPath, { draft: opts.draft }), outputOptions(cmd2));
+  });
+  draftOption(cmd.command("files <skill-id> [path]")).description("List a skill's files (one level; --tree for the whole hierarchy)").option("--tree", "render the full hierarchy instead of one level").action(async (id, path, opts, cmd2) => {
+    const skills = clientFrom(cmd2).skills;
+    const out = outputOptions(cmd2);
+    if (opts.tree) {
+      const all = await skills.fileManifest(id, { draft: opts.draft });
+      if (path !== void 0) {
+        const kind = classifyPath(all, path);
+        if (kind === "file")
+          throw new InputError(`'${path}' is a file \u2014 use \`skill read-file\`.`);
+        if (kind === "missing") throw new InputError(`'${path}' not found in skill ${id}.`);
+      }
+      const files = filesUnder(all, path);
+      const bytes = files.reduce((sum, f) => sum + (f.size ?? 0), 0);
+      if (out.json || out.compact) {
+        printJson(
+          {
+            skillId: id,
+            path: path ?? "",
+            files: files.map((f) => ({
+              relPath: f.rel_path,
+              fileType: f.file_type,
+              size: f.size,
+              mime: f.mime_type
+            })),
+            totalFiles: files.length,
+            totalSize: bytes
+          },
+          out
+        );
+        return;
+      }
+      process.stdout.write(`${renderTree(files)}
+
+${files.length} files, ${bytes} B
+`);
+      return;
+    }
+    const listing = await skills.files(id, path, { draft: opts.draft });
+    if (out.json || out.compact) {
+      printJson(listing, out);
+      return;
+    }
+    printJson(
+      listing.entries.map(
+        (e) => e.type === "dir" ? { name: `${e.name}/`, type: "dir", size: e.size, mime: "" } : { name: e.name, type: e.fileType ?? "file", size: e.size, mime: e.mime ?? "" }
+      ),
+      out
+    );
+    process.stdout.write(
+      `${listing.entries.length} entries here; ${listing.totalFiles} files, ${listing.totalSize} B below
+`
+    );
+  });
+  cmd.command("names <ids...>").description("Resolve skill ids to names (unknown ids are skipped)").action(async (ids, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).skills.names(ids), outputOptions(cmd2));
   });
-  cmd.command("read-file <skill-id> <rel-path>").description("Read a file inside a skill (progressive)").action(async (id, relPath, _opts, cmd2) => {
-    printJson(await clientFrom(cmd2).skills.readFile(id, relPath), outputOptions(cmd2));
+  cmd.command("execute <skill-id>").description("Run a skill in the platform sandbox").requiredOption("--entry <shell>", "shell command to run inside the skill's work dir").option(
+    "--timeout <seconds>",
+    "sandbox time limit (the sandbox's own limit when omitted)",
+    positiveInt("--timeout")
+  ).option("--raw", "write the run's stdout/stderr straight through").option("--exit-code", "exit with the sandbox's exit code").action(async (id, opts, cmd2) => {
+    const result = await clientFrom(cmd2).skills.execute(id, {
+      entryShell: opts.entry,
+      timeout: opts.timeout
+    });
+    if (result?.mocked) {
+      process.stderr.write("warning: sandbox reported mocked=true \u2014 the skill did not run\n");
+    }
+    if (opts.raw) {
+      if (result?.stdout) process.stdout.write(result.stdout);
+      if (result?.stderr) process.stderr.write(result.stderr);
+    } else {
+      printJson(result, outputOptions(cmd2));
+    }
+    if (opts.exitCode) process.exitCode = sandboxExitCode(result);
   });
   cmd.command("history <skill-id>").description("Show a skill's version history").action(async (id, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).skills.history(id), outputOptions(cmd2));
@@ -2211,15 +2328,21 @@ function skillCommand() {
       outputOptions(cmd2)
     );
   });
-  cmd.command("register <directory>").description("Zip a local skill directory and register it").option("--source <s>", "source tag").option("--extend-info <json>", "extra metadata as JSON").action(async (dir, opts, cmd2) => {
+  cmd.command("register <directory>").description("Zip a local skill directory and register it").option("--source <s>", `source tag: ${SKILL_SOURCES.join(" | ")}`, "custom").option("--extend-info <json>", "extra metadata as JSON").action(async (dir, opts, cmd2) => {
     const extendInfo = opts.extendInfo ? JSON.parse(opts.extendInfo) : void 0;
     printJson(
-      await clientFrom(cmd2).skills.register(dir, { source: opts.source, extendInfo }),
+      await clientFrom(cmd2).skills.register(dir, {
+        source: checkSource(opts.source),
+        extendInfo
+      }),
       outputOptions(cmd2)
     );
   });
-  cmd.command("download <skill-id> [out-path]").description("Download a skill archive to a local .zip").action(async (skillId, outPath, _o, cmd2) => {
-    printJson(await clientFrom(cmd2).skills.download(skillId, outPath), outputOptions(cmd2));
+  draftOption(cmd.command("download <skill-id> [out-path]")).description("Download a skill archive to a local .zip").action(async (skillId, outPath, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).skills.download(skillId, outPath, { draft: opts.draft }),
+      outputOptions(cmd2)
+    );
   });
   cmd.command("install <skill-id> [directory]").description("Download a skill archive and extract it locally").action(async (skillId, dir, _o, cmd2) => {
     printJson(await clientFrom(cmd2).skills.install(skillId, dir), outputOptions(cmd2));
@@ -2441,30 +2564,108 @@ function traceCommand() {
   cmd.command("graph <trace-id>").description("Fetch normalized trace graph by trace id").action(async (traceId, _opts, cmd2) => {
     printJson(await clientFrom(cmd2).trace.graph(traceId), outputOptions(cmd2));
   });
-  cmd.command("evidence-chain [trace-id]").description("Fetch BKN Trace evidence chain by trace id or --request-id").option("--request-id <id>", "BKN request id scope").option("--limit <n>", "maximum evidence trace batches", (v) => Number.parseInt(v, 10)).action(async (traceId, opts, cmd2) => {
+  const conversations = cmd.command("conversations").description("Manage Trace conversations");
+  conversations.command("list").description("List conversations in the authorized owner scope").option("--limit <n>", "page size, 1..100", (value) => Number.parseInt(value, 10)).action(async (opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).trace.evidenceChain(traceScope(traceId, opts.requestId), {
-        limit: opts.limit
+      await clientFrom(cmd2).trace.lifecycle.listConversations({ limit: opts.limit }),
+      outputOptions(cmd2)
+    );
+  });
+  conversations.command("ensure-current <external-conversation-key>").description("Ensure the current Core-owned conversation generation").option("--one-shot", "create a one-shot conversation").option("--idempotency-key <key>", "stable idempotency key").action(async (externalConversationKey, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.ensureConversation({
+        external_conversation_key: externalConversationKey,
+        idempotency_key: opts.idempotencyKey,
+        one_shot: Boolean(opts.oneShot)
       }),
       outputOptions(cmd2)
     );
   });
-  cmd.command("business-graph [trace-id]").description("Fetch BKN Trace business semantic graph by trace id or --request-id").option("--request-id <id>", "BKN request id scope").option("--limit <n>", "maximum evidence trace batches", (v) => Number.parseInt(v, 10)).action(async (traceId, opts, cmd2) => {
+  conversations.command("create-new-generation <external-conversation-key>").description("Create the next Core-owned conversation generation").requiredOption("--idempotency-key <key>", "stable idempotency key").action(async (externalConversationKey, opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).trace.businessGraph(traceScope(traceId, opts.requestId), {
-        limit: opts.limit
+      await clientFrom(cmd2).trace.lifecycle.createNewConversationGeneration({
+        external_conversation_key: externalConversationKey,
+        idempotency_key: opts.idempotencyKey
       }),
       outputOptions(cmd2)
     );
   });
-  cmd.command("snapshot-preview [trace-id]").description("Fetch metadata-only evidence snapshot preview by trace id or --request-id").option("--request-id <id>", "BKN request id scope").option("--limit <n>", "maximum evidence trace batches", (v) => Number.parseInt(v, 10)).action(async (traceId, opts, cmd2) => {
+  conversations.command("resume <conversation-id>").description("Resume an existing authorized conversation").action(async (conversationId, _opts, cmd2) => {
     printJson(
-      await clientFrom(cmd2).trace.snapshotPreview(traceScope(traceId, opts.requestId), {
-        limit: opts.limit
+      await clientFrom(cmd2).trace.lifecycle.resumeConversation({
+        conversation_id: conversationId
       }),
       outputOptions(cmd2)
     );
   });
+  conversations.command("get <conversation-id>").description("Get an authorized conversation").action(async (conversationId, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.getConversation(conversationId),
+      outputOptions(cmd2)
+    );
+  });
+  conversations.command("close <conversation-id>").description("Close an active conversation").option("--idempotency-key <key>", "stable idempotency key").action(async (conversationId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.closeConversation(conversationId, {
+        idempotency_key: opts.idempotencyKey
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  const interactions = cmd.command("interactions").description("Inspect Trace interactions");
+  interactions.command("start <conversation-id>").description("Start one managed interaction").requiredOption("--idempotency-key <key>", "stable idempotency key").option("--agent-name <name>", "conversation-level Agent display name").option(
+    "--lease-seconds <n>",
+    "interaction lease duration",
+    (value) => Number.parseInt(value, 10)
+  ).action(async (conversationId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.startInteraction(conversationId, {
+        idempotency_key: opts.idempotencyKey,
+        agent_name: opts.agentName,
+        lease_seconds: opts.leaseSeconds
+      }),
+      outputOptions(cmd2)
+    );
+  });
+  interactions.command("get <interaction-id>").description("Get an authorized interaction").action(async (interactionId, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.getInteraction(interactionId),
+      outputOptions(cmd2)
+    );
+  });
+  for (const action of ["complete", "fail", "cancel", "handoff"]) {
+    interactions.command(`${action} <interaction-id>`).description(`${action} a managed interaction using a 3.0 completion manifest`).requiredOption("--body-file <path>", "read completion manifest JSON from a protected file").action(async (interactionId, opts, cmd2) => {
+      const input = readBody(opts);
+      const lifecycle = clientFrom(cmd2).trace.lifecycle;
+      const terminal = {
+        complete: lifecycle.completeInteraction,
+        fail: lifecycle.failInteraction,
+        cancel: lifecycle.cancelInteraction,
+        handoff: lifecycle.handoffInteraction
+      }[action];
+      printJson(await terminal(interactionId, input), outputOptions(cmd2));
+    });
+  }
+  const operations = cmd.command("operations").description("Inspect and retry operations");
+  operations.command("get <operation-id>").description("Get an authorized operation").action(async (operationId, _opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.getOperation(operationId),
+      outputOptions(cmd2)
+    );
+  });
+  operations.command("retry <operation-id>").description("Create the next retry attempt for an eligible failed operation").requiredOption("--body-file <path>", "read retry request JSON from a protected file").action(async (operationId, opts, cmd2) => {
+    printJson(
+      await clientFrom(cmd2).trace.lifecycle.retryOperationAttempt(
+        operationId,
+        readBody(opts)
+      ),
+      outputOptions(cmd2)
+    );
+  });
+  const receipts = cmd.command("receipts").description("Inspect durable operation receipts");
+  receipts.command("get <receipt-id>").description("Get an authorized operation receipt").action(async (receiptId, _opts, cmd2) => {
+    printJson(await clientFrom(cmd2).trace.lifecycle.getReceipt(receiptId), outputOptions(cmd2));
+  });
   cmd.command("get <conversation-id>").description("Fetch all trace spans for a conversation").option("--max-spans <n>", "max spans", (v) => Number.parseInt(v, 10)).action(async (conversationId, opts, cmd2) => {
     printJson(
       await clientFrom(cmd2).trace.spans(conversationId, { maxSpans: opts.maxSpans }),
@@ -2521,25 +2722,55 @@ function traceCommand() {
     printJson(result, outputOptions(cmd2));
     if (!result.ok) process.exitCode = 1;
   });
-  const evidence = cmd.command("evidence").description("Submit BKN Trace 2.x business evidence events");
-  evidence.command("emit <file>").description("Submit a BKN Trace 2.0/2.1 event batch JSON file").action(async (file, _opts, cmd2) => {
-    const body = JSON.parse(readFileSync5(file, "utf8"));
-    printJson(await clientFrom(cmd2).trace.emitEvidenceEvents(body), outputOptions(cmd2));
-  });
   return group(cmd, "TRACE AI");
 }
-function traceScope(traceId, requestId) {
-  if (traceId && requestId) {
-    throw new InputError("Provide either trace id or --request-id, not both.");
-  }
-  if (requestId) return { requestId };
-  if (traceId) return traceId;
-  throw new InputError("Provide a trace id or --request-id.");
-}
 
 // src/commands/vega.ts
 import { Command as Command16 } from "commander";
 var int12 = (v) => Number.parseInt(v, 10);
+var bool = (value) => {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  throw new InputError("boolean value must be true or false");
+};
+var parseJsonObject = (value, flag) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new InputError(`${flag} must be valid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new InputError(`${flag} must be a JSON object`);
+  }
+  return parsed;
+};
+var parseStringRecord = (value, flag) => {
+  const parsed = parseJsonObject(value, flag);
+  if (Object.values(parsed).some((item) => typeof item !== "string")) {
+    throw new InputError(`${flag} values must be strings`);
+  }
+  return parsed;
+};
+var healthCheckSchedule = (mode, cronExpr) => {
+  if (!mode) {
+    if (cronExpr) throw new InputError("a health-check cron expression requires enabled mode");
+    return void 0;
+  }
+  if (mode === "enabled") {
+    if (!cronExpr) {
+      throw new InputError("a health-check cron expression is required in enabled mode");
+    }
+    return { mode, cronExpr };
+  }
+  if (mode === "inherit" || mode === "disabled") {
+    if (cronExpr) {
+      throw new InputError("a health-check cron expression is only valid in enabled mode");
+    }
+    return { mode };
+  }
+  throw new InputError("health-check mode must be inherit, enabled, or disabled");
+};
 var parsePairs2 = (raw) => {
   if (!raw) return void 0;
   return raw.split(",").map((part) => {
@@ -2580,45 +2811,48 @@ function vegaCommand() {
       outputOptions(cmd)
     );
   });
-  catalog.command("health <ids...>").description("Health-status for one or more catalogs").action(async (ids, _opts, cmd) => {
-    printJson(await clientFrom(cmd).vega.catalogHealth(ids), outputOptions(cmd));
+  catalog.command("health <id>").description("Health-status for a catalog").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.catalogHealth(id), outputOptions(cmd));
   });
-  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--extensions <json>", "extension key/value JSON object").action(async (opts, cmd) => {
-    let connectorConfig;
-    try {
-      connectorConfig = JSON.parse(opts.connectorConfig);
-    } catch {
-      throw new Error("--connector-config must be valid JSON");
-    }
-    const extensions = opts.extensions ? JSON.parse(opts.extensions) : void 0;
+  catalog.command("create").description("Create a catalog (data source)").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type (e.g. mysql)").requiredOption("--connector-config <json>", "connector config JSON").option("--id <id>", "explicit catalog id").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled", "create enabled (default: disabled)").option("--internal", "create an internal catalog").option("--extensions <json>", "extension key/value JSON object").option("--allow-unhealthy", "save the catalog when its connection test fails").option("--health-check-mode <mode>", "health schedule: inherit | enabled | disabled").option("--health-check-cron <expr>", "cron expression for enabled health checks").action(async (opts, cmd) => {
+    const connectorConfig = parseJsonObject(opts.connectorConfig, "--connector-config");
+    const extensions = opts.extensions ? parseStringRecord(opts.extensions, "--extensions") : void 0;
     printJson(
-      await clientFrom(cmd).vega.createCatalog({
-        id: opts.id,
-        name: opts.name,
-        connectorType: opts.connectorType,
-        connectorConfig,
-        tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
-        description: opts.description,
-        enabled: opts.enabled ? true : void 0,
-        internal: opts.internal ? true : void 0,
-        extensions
-      }),
+      await clientFrom(cmd).vega.createCatalog(
+        {
+          id: opts.id,
+          name: opts.name,
+          connectorType: opts.connectorType,
+          connectorConfig,
+          tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
+          description: opts.description,
+          enabled: opts.enabled ? true : void 0,
+          internal: opts.internal ? true : void 0,
+          extensions,
+          healthCheckSchedule: healthCheckSchedule(opts.healthCheckMode, opts.healthCheckCron)
+        },
+        { allowUnhealthy: opts.allowUnhealthy ? true : void 0 }
+      ),
       outputOptions(cmd)
     );
   });
-  catalog.command("update <id>").description("Update a catalog").option("--name <s>", "catalog name").option("--connector-type <s>", "connector type").option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--enabled <bool>", "enabled state").option("--extensions <json>", "extension key/value JSON object").action(async (id, opts, cmd) => {
-    const connectorConfig = opts.connectorConfig ? JSON.parse(opts.connectorConfig) : void 0;
-    const extensions = opts.extensions ? JSON.parse(opts.extensions) : void 0;
+  catalog.command("update <id>").description("Fully update a catalog").requiredOption("--name <s>", "catalog name").requiredOption("--connector-type <s>", "connector type").requiredOption("--enabled <bool>", "current enabled state", bool).option("--connector-config <json>", "connector config JSON").option("--tags <t1,t2>", "comma-separated tags").option("--description <s>", "description").option("--extensions <json>", "extension key/value JSON object").option("--allow-unhealthy", "save the update when its connection test fails").action(async (id, opts, cmd) => {
+    const connectorConfig = opts.connectorConfig ? parseJsonObject(opts.connectorConfig, "--connector-config") : void 0;
+    const extensions = opts.extensions ? parseStringRecord(opts.extensions, "--extensions") : void 0;
     printJson(
-      await clientFrom(cmd).vega.updateCatalog(id, {
-        name: opts.name,
-        connectorType: opts.connectorType,
-        connectorConfig,
-        tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
-        description: opts.description,
-        enabled: opts.enabled === void 0 ? void 0 : opts.enabled === "true",
-        extensions
-      }),
+      await clientFrom(cmd).vega.updateCatalog(
+        id,
+        {
+          name: opts.name,
+          connectorType: opts.connectorType,
+          connectorConfig,
+          tags: opts.tags ? String(opts.tags).split(",").map((t) => t.trim()).filter(Boolean) : void 0,
+          description: opts.description,
+          enabled: opts.enabled,
+          extensions
+        },
+        { allowUnhealthy: opts.allowUnhealthy ? true : void 0 }
+      ),
       outputOptions(cmd)
     );
   });
@@ -2634,6 +2868,26 @@ function vegaCommand() {
   catalog.command("test-connection <id>").description("Test a catalog connection").action(async (id, _opts, cmd) => {
     printJson(await clientFrom(cmd).vega.testCatalogConnection(id), outputOptions(cmd));
   });
+  catalog.command("test-connection-config").description("Test an unpersisted catalog connection configuration").requiredOption("--connector-type <s>", "connector type").requiredOption("--connector-config <json>", "connector config JSON").action(async (opts, cmd) => {
+    printJson(
+      await clientFrom(cmd).vega.testCatalogConnectionConfig({
+        connectorType: opts.connectorType,
+        connectorConfig: parseJsonObject(opts.connectorConfig, "--connector-config")
+      }),
+      outputOptions(cmd)
+    );
+  });
+  catalog.command("health-check-schedule <id>").description("Get a catalog health-check schedule").action(async (id, _opts, cmd) => {
+    printJson(await clientFrom(cmd).vega.catalogHealthCheckSchedule(id), outputOptions(cmd));
+  });
+  catalog.command("set-health-check-schedule <id>").description("Update a catalog health-check schedule").requiredOption("--mode <mode>", "health schedule: inherit | enabled | disabled").option("--cron <expr>", "cron expression for enabled health checks").action(async (id, opts, cmd) => {
+    const schedule = healthCheckSchedule(opts.mode, opts.cron);
+    if (!schedule) throw new InputError("--mode is required");
+    printJson(
+      await clientFrom(cmd).vega.updateCatalogHealthCheckSchedule(id, schedule),
+      outputOptions(cmd)
+    );
+  });
   catalog.command("discover <id>").description("Trigger catalog resource discovery").option("--wait", "wait for discovery to complete").action(async (id, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.discoverCatalog(id, Boolean(opts.wait)),
@@ -2749,11 +3003,16 @@ function vegaCommand() {
     );
     printJson(task, outputOptions(cmd));
   });
-  dataset.command("build-status <resource-id> <task-id>").description("Show a BuildTask's state and progress").action(async (_resourceId, taskId, _opts, cmd) => {
+  dataset.command("build-status <task-id>").description("Show a BuildTask's state and progress").action(async (taskId, _opts, cmd) => {
     const task = await clientFrom(cmd).vega.buildStatus(taskId);
     printJson(task, outputOptions(cmd));
   });
-  dataset.command("build-list").description("List BuildTasks").option("--limit <n>", "page size", int12, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--resource-id <id>", "filter by resource id").option("--catalog-id <id>", "filter by catalog id").option("--status <status>", "comma-separated statuses").option("--active", "only running/init tasks").option("--mode <mode>", "filter by mode: batch | streaming").option("--order-by <field>", "default | created_at | updated_at | status | mode").option("--order <dir>", "asc | desc").action(async (opts, cmd) => {
+  dataset.command("build-list").description("List BuildTasks").option("--limit <n>", "page size", int12, DEFAULT_LIST_LIMIT).option("--offset <n>", "page offset", int12, 0).option("--resource-id <id>", "filter by resource id").option("--catalog-id <id>", "filter by catalog id").option("--status <status>", "comma-separated statuses").option("--active", "only running/init tasks").option("--mode <mode>", "filter by mode: batch | streaming").option("--order-by <field>", "created_at | updated_at").option("--order <dir>", "asc | desc").action(async (opts, cmd) => {
+    if (opts.orderBy === "default") {
+      throw new InputError(
+        '--order-by default is no longer supported; use "created_at" or "updated_at"'
+      );
+    }
     printJson(
       await clientFrom(cmd).vega.buildTasks({
         limit: opts.limit,
@@ -2769,7 +3028,7 @@ function vegaCommand() {
       outputOptions(cmd)
     );
   });
-  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart from the beginning").action(async (taskId, opts, cmd) => {
+  dataset.command("build-start <task-id>").description("Start a BuildTask").option("--reset", "restart a full task from the beginning (ignored for incremental tasks)").action(async (taskId, opts, cmd) => {
     printJson(
       await clientFrom(cmd).vega.startBuildTask(taskId, { reset: opts.reset }),
       outputOptions(cmd)
@@ -2816,6 +3075,8 @@ try {
   await program.parseAsync(argv);
 } catch (err) {
   console.error(formatError(err));
+  await releaseLifecycleSessions();
   process.exit(toExitCode(err));
 }
+await releaseLifecycleSessions();
 //# sourceMappingURL=cli.js.map