ardent-cli 0.0.49 → 0.0.51

package/dist/index.js

@@ -6,6 +6,9 @@ import { Command as Command8 } from "commander";
 // src/commands/branch/index.ts
 import { Command } from "commander";
 
+// src/commands/branch/create.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
 // src/lib/config.ts
 import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync, unlinkSync } from "fs";
 import { homedir } from "os";
@@ -137,6 +140,24 @@ function getCacheEntry(key) {
   const config = loadConfig();
   return config.cache?.[key];
 }
+function getPendingBranchCreateKey(scopeKey) {
+  return getConfig("pendingBranchCreateKeys")?.[scopeKey];
+}
+function setPendingBranchCreateKey(scopeKey, idempotencyKey) {
+  const config = loadConfig();
+  if (!config.pendingBranchCreateKeys) {
+    config.pendingBranchCreateKeys = {};
+  }
+  config.pendingBranchCreateKeys[scopeKey] = idempotencyKey;
+  saveConfig(config);
+}
+function clearPendingBranchCreateKey(scopeKey) {
+  const config = loadConfig();
+  if (config.pendingBranchCreateKeys && scopeKey in config.pendingBranchCreateKeys) {
+    delete config.pendingBranchCreateKeys[scopeKey];
+    saveConfig(config);
+  }
+}
 function formatIdle(lastActivityIso) {
   if (!lastActivityIso) {
     return "unknown";
@@ -316,11 +337,14 @@ var ApiClient = class {
     });
     return this.handleResponse(response);
   }
-  async post(path, body) {
+  async post(path, body, extraHeaders = {}) {
     const url = `${getApiUrl()}${path}`;
     const response = await fetch(url, {
       method: "POST",
-      headers: this.getHeaders(),
+      headers: {
+        ...this.getHeaders(),
+        ...extraHeaders
+      },
       body: JSON.stringify(body)
     });
     return this.handleResponse(response);
@@ -487,6 +511,58 @@ async function resolveCurrentConnectorId() {
   );
 }
 
+// src/lib/operation_stage_display.ts
+var STAGE_DISPLAY = {
+  // engine_setup_worker / postgres_engine_setup
+  "dispatched": "Queued",
+  "preparing": "Preparing",
+  "creating-neon-project": "Provisioning the branch target",
+  "preparing-target-databases": "Preparing target databases",
+  "deploying-pgstream": "Starting replication",
+  "applying-rls": "Applying RLS policies",
+  "storing-credentials": "Storing connection credentials",
+  "validating": "Validating the branch target",
+  // reset_worker / reset_connector
+  "resetting": "Resetting",
+  "deleting-pgstream": "Stopping replication",
+  "rediscovering-source": "Re-checking the source database",
+  "resetting-neon-main": "Resetting the branch target",
+  "creating-target-schemas": "Recreating target schemas",
+  "redeploying-pgstream": "Restarting replication",
+  // environment deploy_worker
+  "loading_config": "Loading environment configuration",
+  "deploying_infrastructure": "Provisioning environment infrastructure",
+  "recording_success": "Finalizing environment",
+  "cleaning_failed_deploy": "Cleaning up failed environment provisioning",
+  // environment destroy_worker
+  "deleting_private_links": "Removing private network links",
+  "destroying_infrastructure": "Tearing down environment infrastructure",
+  "recording_destroy_success": "Finalizing environment teardown",
+  // discovery_worker / run_discovery_crawl (ARD-1098)
+  "connecting": "Connecting to source",
+  "enumerating_databases": "Listing databases",
+  "scanning_database": "Scanning schema",
+  "writing_schema": "Saving discovered schema",
+  "merging_results": "Combining results",
+  // branch.create.v1 workflow (ARD-1244)
+  "provisioning": "Provisioning the branch",
+  "configuring": "Storing connection credentials",
+  "recording": "Recording the branch",
+  "finalizing": "Finalizing the branch",
+  "activating": "Activating the branch"
+};
+function humanizeRawStage(_raw) {
+  return "Working";
+}
+function operationStageDisplay(stage) {
+  if (!stage) return "Working";
+  const colonIndex = stage.indexOf(":");
+  const base = colonIndex === -1 ? stage : stage.slice(0, colonIndex);
+  const suffix = colonIndex === -1 ? "" : stage.slice(colonIndex + 1);
+  const label = STAGE_DISPLAY[base] ?? humanizeRawStage(base);
+  return suffix ? `${label} (for ${suffix})` : label;
+}
+
 // src/lib/resource_name_validation.ts
 var RESERVED_SUFFIXES = ["pooler", "readonly", "direct"];
 var MAX_RESOURCE_NAME_LENGTH = 100;
@@ -659,6 +735,28 @@ function isMachineReadableBranchInvocation(args2) {
 }
 
 // src/commands/branch/create.ts
+var BRANCH_CREATE_MAX_WAIT_MS = 10 * 60 * 1e3;
+var BRANCH_CREATE_POLL_INTERVAL_MS = 2 * 1e3;
+var BRANCH_CREATE_IN_PROGRESS_DETAIL = "Branch creation is still in progress";
+function branchCreateMaxWaitMs() {
+  return Number(process.env.ARDENT_BRANCH_CREATE_MAX_WAIT_MS) || BRANCH_CREATE_MAX_WAIT_MS;
+}
+function branchCreatePollIntervalMs() {
+  return Number(process.env.ARDENT_BRANCH_CREATE_POLL_INTERVAL_MS) || BRANCH_CREATE_POLL_INTERVAL_MS;
+}
+var BRANCH_CREATE_TRANSIENT_WARN_EVERY = 10;
+function asBranchCreateWarning(value) {
+  if (value && typeof value === "object" && value.type === "stale_source" && typeof value.message === "string") {
+    return value;
+  }
+  return void 0;
+}
+function isBranchCreateInProgressError(err) {
+  if (!(err instanceof Error)) {
+    return false;
+  }
+  return err.message.includes("API error 409") && err.message.includes(BRANCH_CREATE_IN_PROGRESS_DETAIL);
+}
 async function createAction(name, options) {
   const modeResolution = resolveOutputMode(options);
   if (modeResolution.error) {
@@ -681,18 +779,26 @@ async function createAction(name, options) {
     console.error(`\u2717 ${message}`);
     process.exit(1);
   }
+  let idempotencyScopeKey;
   try {
     const startTime = performance.now();
     const connectorId = await resolveCurrentConnectorId();
-    const createResponse = await api.post(
+    idempotencyScopeKey = `${connectorId}:${options.service}:${name}`;
+    let idempotencyKey = getPendingBranchCreateKey(idempotencyScopeKey);
+    if (!idempotencyKey) {
+      idempotencyKey = randomUUID2();
+      setPendingBranchCreateKey(idempotencyScopeKey, idempotencyKey);
+    }
+    const dispatch = await api.post(
       "/v1/branch/create",
       {
         connector_id: connectorId,
         service_type: options.service,
         name
-      }
+      },
+      { "X-Idempotency-Key": idempotencyKey }
     );
-    const warning = createResponse?.warning;
+    const warning = await pollBranchCreate(dispatch.operation_id, idempotencyScopeKey, mode);
     const response = await api.get(`/v1/cli/branches?connector_id=${connectorId}`);
     const apiBranches = response.branches || [];
     let apiBranch;
@@ -746,6 +852,7 @@ async function createAction(name, options) {
     cachedBranches.push(branch);
     setCacheEntry("branches", cachedBranches);
     setCurrentBranch(name);
+    clearPendingBranchCreateKey(idempotencyScopeKey);
     const elapsed = ((performance.now() - startTime) / 1e3).toFixed(1);
     trackEvent("CLI: branch create succeeded", {
       service_type: options.service,
@@ -783,6 +890,15 @@ ${url}`);
       printCurrentConnectorSelectionError(err);
       process.exit(1);
     }
+    if (err instanceof BranchCreateTimeoutError) {
+      trackEvent("CLI: branch create failed", { reason: "timeout", output_mode: mode });
+      if (mode === "json") {
+        process.stdout.write(renderBranchJsonError("timeout", err.message));
+        process.exit(1);
+      }
+      console.error(`\u2717 ${err.message}`);
+      process.exit(1);
+    }
     if (isNetworkError(err)) {
       trackEvent("CLI: branch create failed", { reason: "offline", output_mode: mode });
       if (mode === "json") {
@@ -794,6 +910,22 @@ ${url}`);
       console.error("\u2717 Cannot create branch while offline");
       process.exit(1);
     }
+    if (isBranchCreateInProgressError(err)) {
+      trackEvent("CLI: branch create failed", {
+        reason: "in_progress",
+        output_mode: mode
+      });
+      const message2 = err instanceof Error ? err.message : String(err);
+      if (mode === "json") {
+        process.stdout.write(renderBranchJsonError("api_error", message2));
+        process.exit(1);
+      }
+      console.error("\u2717 Failed:", message2);
+      process.exit(1);
+    }
+    if (idempotencyScopeKey) {
+      clearPendingBranchCreateKey(idempotencyScopeKey);
+    }
     trackEvent("CLI: branch create failed", { reason: "api_error", output_mode: mode });
     const message = err instanceof Error ? err.message : String(err);
     if (mode === "json") {
@@ -804,6 +936,57 @@ ${url}`);
     process.exit(1);
   }
 }
+var BranchCreateTimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BranchCreateTimeoutError";
+  }
+};
+async function pollBranchCreate(operationId, idempotencyScopeKey, mode) {
+  const startedAt = Date.now();
+  const maxWaitMs = branchCreateMaxWaitMs();
+  const pollIntervalMs = branchCreatePollIntervalMs();
+  let lastStage = null;
+  let consecutiveTransientFailures = 0;
+  let firstPoll = true;
+  while (Date.now() - startedAt < maxWaitMs) {
+    if (!firstPoll) {
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    firstPoll = false;
+    let op;
+    try {
+      op = await api.get(`/v1/operations/${operationId}`);
+    } catch (pollErr) {
+      if (isTransientOperationPollError(pollErr)) {
+        consecutiveTransientFailures += 1;
+        if (consecutiveTransientFailures % BRANCH_CREATE_TRANSIENT_WARN_EVERY === 0 && mode !== "json") {
+          console.warn(
+            `  \u26A0 Status check has failed ${consecutiveTransientFailures} times in a row. Branch creation is still running server-side and the CLI will keep waiting.`
+          );
+        }
+        continue;
+      }
+      throw pollErr;
+    }
+    consecutiveTransientFailures = 0;
+    if (op.stage && op.stage !== lastStage && mode !== "json" && mode !== "print-url") {
+      const progressLabel = op.progress != null ? ` (${op.progress}%)` : "";
+      console.log(`  ${operationStageDisplay(op.stage)}${progressLabel}`);
+      lastStage = op.stage;
+    }
+    if (op.status === "completed") {
+      return asBranchCreateWarning(op.result?.warning);
+    }
+    if (op.status === "failed") {
+      clearPendingBranchCreateKey(idempotencyScopeKey);
+      throw new Error(op.error ?? "Branch creation failed");
+    }
+  }
+  throw new BranchCreateTimeoutError(
+    `Branch creation did not complete within ${Math.round(maxWaitMs / 6e4)} minutes. It may still be running server-side \u2014 do NOT assume it failed. Re-run the same command to resume, or check \`ardent branch list\`. If you contact Ardent support, reference operation id ${operationId}.`
+  );
+}
 
 // src/commands/branch/list.ts
 function formatCreatedDate(createdAtIso) {
@@ -1107,52 +1290,6 @@ function printDegradedWarnings(warnings) {
   console.log("  Review this connector with: ardent connector list");
 }
 
-// src/lib/operation_stage_display.ts
-var STAGE_DISPLAY = {
-  // engine_setup_worker / postgres_engine_setup
-  "dispatched": "Starting",
-  "preparing": "Preparing",
-  "creating-neon-project": "Provisioning the branch target",
-  "preparing-target-databases": "Preparing target databases",
-  "deploying-pgstream": "Starting replication",
-  "applying-rls": "Applying RLS policies",
-  "storing-credentials": "Storing connection credentials",
-  "validating": "Validating the branch target",
-  // reset_worker / reset_connector
-  "resetting": "Resetting",
-  "deleting-pgstream": "Stopping replication",
-  "rediscovering-source": "Re-checking the source database",
-  "resetting-neon-main": "Resetting the branch target",
-  "creating-target-schemas": "Recreating target schemas",
-  "redeploying-pgstream": "Restarting replication",
-  // environment deploy_worker
-  "loading_config": "Loading environment configuration",
-  "deploying_infrastructure": "Provisioning environment infrastructure",
-  "recording_success": "Finalizing environment",
-  "cleaning_failed_deploy": "Cleaning up failed environment provisioning",
-  // environment destroy_worker
-  "deleting_private_links": "Removing private network links",
-  "destroying_infrastructure": "Tearing down environment infrastructure",
-  "recording_destroy_success": "Finalizing environment teardown",
-  // discovery_worker / run_discovery_crawl (ARD-1098)
-  "connecting": "Connecting to source",
-  "enumerating_databases": "Listing databases",
-  "scanning_database": "Scanning schema",
-  "writing_schema": "Saving discovered schema",
-  "merging_results": "Combining results"
-};
-function humanizeRawStage(_raw) {
-  return "Working";
-}
-function operationStageDisplay(stage) {
-  if (!stage) return "Working";
-  const colonIndex = stage.indexOf(":");
-  const base = colonIndex === -1 ? stage : stage.slice(0, colonIndex);
-  const suffix = colonIndex === -1 ? "" : stage.slice(colonIndex + 1);
-  const label = STAGE_DISPLAY[base] ?? humanizeRawStage(base);
-  return suffix ? `${label} (for ${suffix})` : label;
-}
-
 // src/lib/discover.ts
 var DiscoveryTimeoutError = class extends Error {
   constructor(message) {

package/package.json

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