ardent-cli 0.0.25 → 0.0.27

package/dist/index.js

@@ -27,7 +27,11 @@ function formatUpgradeRequiredMessage(text) {
   try {
     const json = JSON.parse(text);
     if (json.detail) {
-      return `${formatErrorDetail(json.detail)}
+      const detail = formatErrorDetail(json.detail);
+      if (detail.includes("npm install -g ardent-cli@latest")) {
+        return detail;
+      }
+      return `${detail}
 
   npm install -g ardent-cli@latest`;
     }
@@ -753,29 +757,125 @@ import { Command as Command2 } from "commander";
 var SUCCESS_ENGINE_STATUSES = /* @__PURE__ */ new Set(["healthy", "degraded"]);
 var RETRYABLE_ENGINE_STATUSES = /* @__PURE__ */ new Set(["configuration_verified"]);
 var FAILED_ENGINE_STATUSES = /* @__PURE__ */ new Set(["configuration_failed", "failed_validation"]);
-function assertEngineSetupCompleted(operation) {
+var EngineSetupTerminalStatusError = class extends Error {
+  kind;
+  engineStatus;
+  constructor(kind, engineStatus, message) {
+    super(message);
+    this.name = "EngineSetupTerminalStatusError";
+    this.kind = kind;
+    this.engineStatus = engineStatus;
+  }
+};
+function assertEngineSetupCompleted(operation, connectorName) {
   const result = operation.result;
   if (!result) {
-    throw new Error("Engine setup completed without a result payload.");
+    throw new EngineSetupTerminalStatusError(
+      "malformed_result",
+      null,
+      "Engine setup completed without a result payload."
+    );
   }
   const engineStatus = result.branching_engine_status;
   if (typeof engineStatus !== "string" || engineStatus.length === 0) {
-    throw new Error("Engine setup completed without branching_engine_status in the result.");
+    throw new EngineSetupTerminalStatusError(
+      "malformed_result",
+      null,
+      "Engine setup completed without branching_engine_status in the result."
+    );
   }
   if (SUCCESS_ENGINE_STATUSES.has(engineStatus)) {
     return;
   }
   if (RETRYABLE_ENGINE_STATUSES.has(engineStatus)) {
-    throw new Error(
-      `Engine setup needs retry (status: ${engineStatus}). Run \`ardent connector list\` to inspect connector state, then retry engine setup.`
+    throw new EngineSetupTerminalStatusError(
+      "retryable_engine_status",
+      engineStatus,
+      `Engine setup needs retry (status: ${engineStatus}). Run \`ardent connector retry-setup ${connectorName}\` to retry, or \`ardent connector list\` to inspect connector state first.`
     );
   }
   if (FAILED_ENGINE_STATUSES.has(engineStatus)) {
-    throw new Error(
+    throw new EngineSetupTerminalStatusError(
+      "failed_engine_status",
+      engineStatus,
       `Engine setup failed (status: ${engineStatus}). Run \`ardent connector list\` to inspect connector state.`
     );
   }
-  throw new Error(`Engine setup completed with unexpected status: ${engineStatus}.`);
+  throw new EngineSetupTerminalStatusError(
+    "unexpected_engine_status",
+    engineStatus,
+    `Engine setup completed with unexpected status: ${engineStatus}.`
+  );
+}
+
+// src/lib/engine_setup.ts
+var EngineSetupTimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EngineSetupTimeoutError";
+  }
+};
+var EngineSetupOperationFailedError = class extends Error {
+  operationError;
+  constructor(operationError, connectorName) {
+    super(
+      `Engine setup failed: ${operationError ?? "unknown error"}. Inspect connector state with \`ardent connector list\`, then retry with \`ardent connector retry-setup ${connectorName}\` once the underlying issue is resolved.`
+    );
+    this.name = "EngineSetupOperationFailedError";
+    this.operationError = operationError;
+  }
+};
+async function runEngineSetupWithPolling(connectorId, connectorName) {
+  let dispatch;
+  try {
+    dispatch = await api.post(
+      `/v1/connectors/${connectorId}/engine-setup`,
+      {}
+    );
+  } catch (err) {
+    if (isGatewayTimeoutError(err)) {
+      throw new Error(
+        "Backend dispatch timed out. The engine-setup endpoint is now async and should respond in under a second; this may indicate a backend incident. Try again, or check `ardent connector list` to see if an operation was created anyway."
+      );
+    }
+    throw err;
+  }
+  const operationId = dispatch?.operation_id;
+  if (!operationId) {
+    return { dispatched: false };
+  }
+  const startedAt = Date.now();
+  const maxWaitMs = 20 * 60 * 1e3;
+  const pollIntervalMs = 5 * 1e3;
+  let lastStage = null;
+  while (Date.now() - startedAt < maxWaitMs) {
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    let op;
+    try {
+      op = await api.get(`/v1/operations/${operationId}`);
+    } catch (pollErr) {
+      if (isGatewayTimeoutError(pollErr)) continue;
+      throw pollErr;
+    }
+    if (op.stage && op.stage !== lastStage) {
+      const progressLabel = op.progress != null ? ` (${op.progress}%)` : "";
+      console.log(`  ${op.stage}${progressLabel}`);
+      lastStage = op.stage;
+    }
+    if (op.status === "completed") {
+      assertEngineSetupCompleted(
+        { status: op.status, result: op.result },
+        connectorName
+      );
+      return { dispatched: true };
+    }
+    if (op.status === "failed") {
+      throw new EngineSetupOperationFailedError(op.error, connectorName);
+    }
+  }
+  throw new EngineSetupTimeoutError(
+    `Engine setup did not complete within ${maxWaitMs / 6e4} minutes. Setup may still be running server-side \u2014 do NOT delete the connector. Check status with: ardent connector list (operation ${operationId})`
+  );
 }
 
 // src/lib/onboarding.ts
@@ -888,63 +988,6 @@ Example:
 }
 
 // src/commands/connector/create.ts
-var EngineSetupTimeoutError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "EngineSetupTimeoutError";
-  }
-};
-async function runEngineSetupWithPolling(connectorId) {
-  let dispatch;
-  try {
-    dispatch = await api.post(
-      `/v1/connectors/${connectorId}/engine-setup`,
-      {}
-    );
-  } catch (err) {
-    if (isGatewayTimeoutError(err)) {
-      throw new Error(
-        "Backend dispatch timed out. The engine-setup endpoint is now async and should respond in under a second; this may indicate a backend incident. Try again, or check `ardent connector list` to see if an operation was created anyway."
-      );
-    }
-    throw err;
-  }
-  const operationId = dispatch?.operation_id;
-  if (!operationId) {
-    return;
-  }
-  const startedAt = Date.now();
-  const maxWaitMs = 20 * 60 * 1e3;
-  const pollIntervalMs = 5 * 1e3;
-  let lastStage = null;
-  while (Date.now() - startedAt < maxWaitMs) {
-    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
-    let op;
-    try {
-      op = await api.get(`/v1/operations/${operationId}`);
-    } catch (pollErr) {
-      if (isGatewayTimeoutError(pollErr)) continue;
-      throw pollErr;
-    }
-    if (op.stage && op.stage !== lastStage) {
-      const progressLabel = op.progress != null ? ` (${op.progress}%)` : "";
-      console.log(`  ${op.stage}${progressLabel}`);
-      lastStage = op.stage;
-    }
-    if (op.status === "completed") {
-      assertEngineSetupCompleted({ status: op.status, result: op.result });
-      return;
-    }
-    if (op.status === "failed") {
-      throw new Error(
-        `Engine setup failed: ${op.error ?? "unknown error"}. Run \`ardent connector list\` to inspect connector state, or re-trigger setup once the underlying issue is resolved.`
-      );
-    }
-  }
-  throw new EngineSetupTimeoutError(
-    `Engine setup did not complete within ${maxWaitMs / 6e4} minutes. Setup may still be running server-side \u2014 do NOT delete the connector. Check status with: ardent connector list (operation ${operationId})`
-  );
-}
 function parsePostgresUrl(url) {
   const atIndex = url.lastIndexOf("@");
   const credentialsPart = atIndex > 0 ? url.substring(0, atIndex) : url;
@@ -959,6 +1002,11 @@ function parsePostgresUrl(url) {
   if (!username) throw new Error("Username required in connection URL");
   return { host, port, username, password };
 }
+function printEngineSetupRecoveryHint(connectorName) {
+  console.error("\u2717 Engine setup did not complete for this connector.");
+  console.error("  Inspect: ardent connector list");
+  console.error(`  Retry:   ardent connector retry-setup ${connectorName}`);
+}
 async function createAction2(type, url, options) {
   const supportedTypes = ["postgresql"];
   if (!supportedTypes.includes(type.toLowerCase())) {
@@ -1069,11 +1117,10 @@ async function createAction2(type, url, options) {
     if (isByoc) {
       console.log("Setting up branching engine...");
       try {
-        await runEngineSetupWithPolling(connectorId);
+        await runEngineSetupWithPolling(connectorId, connectorName);
       } catch (setupErr) {
         if (!(setupErr instanceof EngineSetupTimeoutError)) {
-          console.error("\u2717 Engine setup failed. To retry, delete and recreate:");
-          console.error(`  ardent connector delete ${connectorName}`);
+          printEngineSetupRecoveryHint(connectorName);
         }
         throw setupErr;
       }
@@ -1100,7 +1147,14 @@ async function createAction2(type, url, options) {
       const connector = await api.get(`/v1/connectors/${connectorId}`);
       if (connector.branching_engine_status === "configuration_verified") {
         console.log("Setting up branching engine...");
-        await runEngineSetupWithPolling(connectorId);
+        try {
+          await runEngineSetupWithPolling(connectorId, connectorName);
+        } catch (setupErr) {
+          if (!(setupErr instanceof EngineSetupTimeoutError)) {
+            printEngineSetupRecoveryHint(connectorName);
+          }
+          throw setupErr;
+        }
       }
     }
     const finalConnector = await api.get(`/v1/connectors/${connectorId}`);
@@ -1108,7 +1162,9 @@ async function createAction2(type, url, options) {
       id: connectorId,
       name: connectorName,
       service_name: "postgresql",
-      status: finalConnector.branching_engine_status ?? finalConnector.connection_status ?? "pending"
+      status: finalConnector.branching_engine_status ?? finalConnector.connection_status ?? "pending",
+      branching_engine_status: finalConnector.branching_engine_status ?? null,
+      connection_error: finalConnector.connection_error ?? null
     };
     const cached = getCacheEntry("connectors");
     const cachedConnectors = cached?.data || [];
@@ -1140,6 +1196,34 @@ async function createAction2(type, url, options) {
   }
 }
 
+// src/lib/connector_render.ts
+var GREEN = "\x1B[32m";
+var CYAN = "\x1B[36m";
+var RED = "\x1B[31m";
+function pendingHint(state, connectorName) {
+  if (state === "validating") {
+    return `engine setup running \u2014 re-run \`ardent connector list\` to refresh, or \`ardent connector retry-setup ${connectorName}\` if it stays this way`;
+  }
+  return `engine setup not finished \u2014 run: ardent connector retry-setup ${connectorName}`;
+}
+var ENGINE_PENDING_STATES = /* @__PURE__ */ new Set(["configuration_verified", "validating"]);
+function renderConnectorIcon(connector) {
+  const engine = connector.branching_engine_status;
+  const statusAllowsEnginePending = connector.status === "healthy" || ENGINE_PENDING_STATES.has(connector.status);
+  if (engine && ENGINE_PENDING_STATES.has(engine) && statusAllowsEnginePending) {
+    return {
+      kind: "engine_pending",
+      icon: "\u25D0",
+      color: CYAN,
+      hint: pendingHint(engine, connector.name)
+    };
+  }
+  if (connector.status === "healthy") {
+    return { kind: "ready", icon: "\u25CF", color: GREEN };
+  }
+  return { kind: "broken", icon: "\u25CB", color: RED };
+}
+
 // src/commands/connector/list.ts
 async function listAction2() {
   let connectors = [];
@@ -1194,23 +1278,28 @@ async function listAction2() {
   const green2 = "\x1B[32m";
   const dim2 = "\x1B[2m";
   const yellow = "\x1B[33m";
-  const reset2 = "\x1B[0m";
   const red = "\x1B[31m";
+  const reset2 = "\x1B[0m";
   console.log("Connectors:\n");
+  let enginePendingCount = 0;
   for (const connector of connectors) {
     const isCurrent = connector.id === currentConnectorId;
-    const icon = connector.status === "healthy" ? "\u25CF" : "\u25CB";
+    const render = renderConnectorIcon(connector);
+    if (render.kind === "engine_pending") enginePendingCount += 1;
     const warnings = connector.warnings ?? [];
     const warningSuffix = warnings.length > 0 ? `  ${yellow}\u26A0 ${warnings.length}${reset2}` : "";
-    const statusSuffix = connector.status === "healthy" ? "" : `  ${red}[${connector.status}]${reset2}`;
+    const statusSuffix = render.kind === "ready" ? "" : `  ${render.color}[${connector.status}]${reset2}`;
+    const nameLine = isCurrent ? `${green2}* ${render.color}${render.icon}${green2} ${connector.name}${reset2}${warningSuffix}${statusSuffix}` : `  ${render.color}${render.icon}${reset2} ${connector.name}${warningSuffix}${statusSuffix}`;
+    console.log(nameLine);
     if (isCurrent) {
-      console.log(`${green2}* ${icon} ${connector.name}${reset2}${warningSuffix}${statusSuffix}`);
       console.log(`${green2}    ${connector.service_name}${reset2}`);
     } else {
-      console.log(`  ${icon} ${connector.name}${warningSuffix}${statusSuffix}`);
       console.log(`${dim2}    ${connector.service_name}${reset2}`);
     }
-    if (connector.status !== "healthy" && connector.connection_error) {
+    if (render.kind === "engine_pending") {
+      console.log(`${render.color}    ${render.hint}${reset2}`);
+    }
+    if (render.kind === "broken" && connector.connection_error) {
       for (const line of connector.connection_error.split("\n")) {
         if (line.trim().length === 0) continue;
         console.log(`${red}    ${line}${reset2}`);
@@ -1221,6 +1310,12 @@ async function listAction2() {
     }
     console.log();
   }
+  if (enginePendingCount > 0) {
+    trackEvent("CLI: connector list rendered engine-pending", {
+      engine_pending_count: enginePendingCount,
+      connector_count: connectors.length
+    });
+  }
 }
 
 // src/commands/connector/delete.ts
@@ -1278,6 +1373,106 @@ async function deleteAction2(name) {
   }
 }
 
+// src/commands/connector/retry-setup.ts
+function connectorRetrySetupFailureTelemetry(err) {
+  if (isPermissionError(err)) {
+    return { reason: "permission_denied" };
+  }
+  if (err instanceof EngineSetupTimeoutError) {
+    return { reason: "polling_timeout" };
+  }
+  if (err instanceof EngineSetupOperationFailedError) {
+    return {
+      reason: "operation_failed",
+      operation_error: err.operationError ?? "unknown error"
+    };
+  }
+  if (err instanceof EngineSetupTerminalStatusError) {
+    return {
+      reason: err.kind,
+      engine_status: err.engineStatus
+    };
+  }
+  return { reason: "api_error" };
+}
+async function retrySetupAction(name) {
+  const currentProjectId = getConfig("currentProjectId");
+  if (!currentProjectId) {
+    console.error("\u2717 No current project set. Switch to a project first:");
+    console.error("  ardent project list");
+    console.error("  ardent project switch <name>");
+    process.exit(1);
+  }
+  let connector;
+  try {
+    const result = await api.get(
+      `/v1/cli/connectors?project_id=${currentProjectId}`
+    );
+    if (!result.connectors) {
+      throw new Error("API returned invalid response: missing connectors array");
+    }
+    setCacheEntry("connectors", result.connectors);
+    connector = result.connectors.find((candidate) => candidate.name === name);
+  } catch (err) {
+    if (isNetworkError(err)) {
+      console.error("\u2717 Cannot run connector retry-setup while offline");
+      process.exit(1);
+    }
+    throw err;
+  }
+  if (!connector) {
+    console.error(`\u2717 Connector "${name}" not found`);
+    console.log("  Run: ardent connector list");
+    process.exit(1);
+  }
+  trackEvent("CLI: connector retry-setup initiated", {
+    connector_id: connector.id,
+    starting_engine_status: connector.branching_engine_status ?? null
+  });
+  console.log(`Setting up branching engine for ${name}...`);
+  try {
+    const { dispatched } = await runEngineSetupWithPolling(connector.id, name);
+    if (dispatched) {
+      trackEvent("CLI: connector retry-setup dispatched", {
+        connector_id: connector.id
+      });
+    }
+    trackEvent("CLI: connector retry-setup succeeded", {
+      connector_id: connector.id,
+      dispatched
+    });
+    try {
+      const refreshed = await api.get(
+        `/v1/cli/connectors?project_id=${currentProjectId}`
+      );
+      if (refreshed.connectors) {
+        setCacheEntry("connectors", refreshed.connectors);
+      }
+    } catch {
+    }
+    if (!dispatched) {
+      console.log("\u2713 Engine already set up \u2014 no work needed");
+    } else {
+      console.log("\u2713 Engine setup complete");
+    }
+  } catch (err) {
+    const failureTelemetry = connectorRetrySetupFailureTelemetry(err);
+    if (isPermissionError(err)) {
+      trackEvent("CLI: connector retry-setup failed", failureTelemetry);
+      console.error("\u2717 You don't have permission to run engine setup on this connector.");
+      process.exit(1);
+    }
+    if (err instanceof EngineSetupTimeoutError) {
+      trackEvent("CLI: connector retry-setup failed", failureTelemetry);
+      console.error(`\u2717 ${err.message}`);
+      process.exit(1);
+    }
+    trackEvent("CLI: connector retry-setup failed", failureTelemetry);
+    console.error("\u2717 Failed:", err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+
 // src/commands/connector/switch.ts
 async function switchAction2(name) {
   const cached = getCacheEntry("connectors");
@@ -1351,6 +1546,9 @@ connectorCommand.command("create <type> [url]").description("Create a new connec
 ).action(createAction2);
 connectorCommand.command("list").description("List your connectors").action(listAction2);
 connectorCommand.command("switch <name>").description("Switch to a different connector").action(switchAction2);
+connectorCommand.command("retry-setup <name>").description(
+  "Retry branching engine setup for a connector that didn't finish (status: configuration_verified or validating)"
+).action(retrySetupAction);
 connectorCommand.command("delete <name>").description("Delete a connector by name").action(deleteAction2);
 
 // src/commands/invite/index.ts
@@ -2279,6 +2477,7 @@ CONNECTORS
   connector create       Connect a database (postgresql, snowflake, etc.)
   connector list         List your connectors (* = current)
   connector switch       Switch to a different connector
+  connector retry-setup  Retry branching engine setup for a connector
   connector delete       Delete a connector
 
 BRANCHES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ardent-cli",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Git for Data infrastructure",
   "type": "module",
   "bin": {