ardent-cli 0.0.29 → 0.0.31

package/dist/index.js

@@ -762,6 +762,42 @@ branchCommand.command("diff [name]", { hidden: true }).description("(removed) Sh
 // src/commands/connector/index.ts
 import { Command as Command2 } from "commander";
 
+// src/lib/connector_warnings.ts
+var YELLOW = "\x1B[33m";
+var RESET = "\x1B[0m";
+async function fetchConnectorWarnings(projectId, connectorId) {
+  const listed = await api.get(
+    `/v1/cli/connectors?project_id=${encodeURIComponent(projectId)}`
+  );
+  if (!listed.connectors) {
+    throw new Error("connector list response missing connectors array");
+  }
+  for (const connector of listed.connectors) {
+    if (connector.id === connectorId) {
+      return connector.warnings ?? [];
+    }
+  }
+  throw new Error(
+    `connector ${connectorId} absent from /v1/cli/connectors response`
+  );
+}
+function printDegradedWarnings(warnings) {
+  if (warnings.length > 0) {
+    console.log(
+      `${YELLOW}\u26A0 This connector is degraded \u2014 some source objects are excluded from branches:${RESET}`
+    );
+    for (const warning of warnings) {
+      console.log(`${YELLOW}  \u2022 ${warning}${RESET}`);
+    }
+  } else {
+    console.log(
+      `${YELLOW}\u26A0 This connector is degraded \u2014 some source objects are excluded from branches.${RESET}`
+    );
+  }
+  console.log("");
+  console.log("  Review this connector with: ardent connector list");
+}
+
 // src/lib/engine_setup_result.ts
 var SUCCESS_ENGINE_STATUSES = /* @__PURE__ */ new Set(["healthy", "degraded"]);
 var RETRYABLE_ENGINE_STATUSES = /* @__PURE__ */ new Set(["configuration_verified"]);
@@ -1042,6 +1078,349 @@ async function multiSelect(items, promptForItem, options = {}) {
   return accepted;
 }
 
+// src/lib/replica_identity_prompt.ts
+import { createInterface as createInterface2 } from "readline/promises";
+
+// src/lib/replica_identity_decisions.ts
+import { readFileSync as readFileSync3 } from "fs";
+var REPLICA_IDENTITY_DECISIONS = [
+  "exclude",
+  "add_pk",
+  "replica_identity_full"
+];
+function isReplicaIdentityDecision(value) {
+  return typeof value === "string" && REPLICA_IDENTITY_DECISIONS.includes(value);
+}
+function loadDecisionsFromFile(path) {
+  let raw;
+  try {
+    raw = readFileSync3(path, "utf-8");
+  } catch (err) {
+    throw new Error(
+      `Could not read replica-identity decisions file ${path}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Replica-identity decisions file ${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      `Replica-identity decisions file ${path} must be a JSON object mapping "database.schema.table" to a decision.`
+    );
+  }
+  const decisions = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    const parts = key.split(".");
+    if (parts.length !== 3 || parts.some((part) => part.length === 0)) {
+      throw new Error(
+        `Replica-identity decisions file ${path}: key ${JSON.stringify(
+          key
+        )} must be of form "database.schema.table" with three non-empty components.`
+      );
+    }
+    if (!isReplicaIdentityDecision(value)) {
+      throw new Error(
+        `Replica-identity decisions file ${path}: value for ${JSON.stringify(
+          key
+        )} must be one of ${REPLICA_IDENTITY_DECISIONS.join(
+          ", "
+        )} (got ${JSON.stringify(value)}).`
+      );
+    }
+    decisions[key] = value;
+  }
+  return decisions;
+}
+function validateDecisionsAgainstPreflight(decisions, preflight) {
+  const known = new Set(
+    preflight.no_replication_identity_tables.map((row) => row.fqn)
+  );
+  const unknown = Object.keys(decisions).filter((fqn) => !known.has(fqn)).sort();
+  if (unknown.length > 0) {
+    throw new Error(
+      "Replica-identity decisions reference tables that are not in this connector's current preflight list: " + unknown.join(", ") + ".\n  Re-run `ardent connector list` to refresh, then re-submit using FQNs from the connector's preflight (key shape: database.schema.table)."
+    );
+  }
+  const missing = preflight.no_replication_identity_tables.map((row) => row.fqn).filter((fqn) => !Object.prototype.hasOwnProperty.call(decisions, fqn)).sort();
+  if (missing.length > 0) {
+    throw new Error(
+      "Replica-identity decisions file is incomplete. It must include a decision for every table in this connector's current preflight list. Missing: " + missing.join(", ") + ".\n  Add those FQNs to the file, or re-run with --accept-replica-identity-defaults to explicitly keep existing choices and exclude undecided tables."
+    );
+  }
+}
+function buildDefaultedDecisions(preflight) {
+  const decisions = {};
+  for (const row of preflight.no_replication_identity_tables) {
+    decisions[row.fqn] = row.current_decision;
+  }
+  return decisions;
+}
+function formatRowCountEstimate(value) {
+  if (value === null || value < 0) return "unknown";
+  return value.toLocaleString("en-US");
+}
+
+// src/lib/replica_identity_prompt.ts
+var DECISION_DESCRIPTIONS = {
+  exclude: "Exclude the table from replication. Branches will not carry rows for this table.",
+  add_pk: "After adding a PRIMARY KEY on source, keep this table in replication. Setup checks the source before replication starts.",
+  replica_identity_full: "You will run ALTER TABLE ... REPLICA IDENTITY FULL on source. Increases WAL volume on UPDATE/DELETE for this table."
+};
+function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function logPreflightTable(rows) {
+  console.log("");
+  const noun = rows.length === 1 ? "table" : "tables";
+  console.log(
+    `Found ${rows.length} ${noun} on your source database with no replication identity:`
+  );
+  for (const row of rows) {
+    const estimate = formatRowCountEstimate(row.row_count_estimate);
+    console.log(
+      `  - ${row.fqn} (~${estimate} rows, currently: ${row.current_decision})`
+    );
+  }
+  console.log("");
+  console.log(
+    "Replication needs a PRIMARY KEY, a UNIQUE NOT NULL column, or REPLICA IDENTITY FULL"
+  );
+  console.log(
+    "to carry UPDATE/DELETE rows. Tables without any of these cannot be replicated."
+  );
+  console.log("Ardent never runs source-side DDL on your behalf.");
+  console.log("");
+}
+async function promptForDecision(rl, row, index, total) {
+  const estimate = formatRowCountEstimate(row.row_count_estimate);
+  console.log(
+    `[${index + 1}/${total}] ${row.fqn} (~${estimate} rows, currently: ${row.current_decision})`
+  );
+  for (let optionIndex = 0; optionIndex < REPLICA_IDENTITY_DECISIONS.length; optionIndex += 1) {
+    const option = REPLICA_IDENTITY_DECISIONS[optionIndex];
+    console.log(
+      `  ${optionIndex + 1}) ${option} -- ${DECISION_DESCRIPTIONS[option]}`
+    );
+  }
+  const defaultIndex = REPLICA_IDENTITY_DECISIONS.indexOf(row.current_decision);
+  while (true) {
+    const raw = await rl.question(
+      `Choose [1-${REPLICA_IDENTITY_DECISIONS.length}, default=${defaultIndex + 1}]: `
+    );
+    const answer = raw.trim();
+    if (answer === "") return row.current_decision;
+    const numeric = Number.parseInt(answer, 10);
+    if (!Number.isNaN(numeric) && numeric >= 1 && numeric <= REPLICA_IDENTITY_DECISIONS.length) {
+      return REPLICA_IDENTITY_DECISIONS[numeric - 1];
+    }
+    if (REPLICA_IDENTITY_DECISIONS.includes(answer)) {
+      return answer;
+    }
+    console.log(
+      `Unrecognized response. Enter 1-${REPLICA_IDENTITY_DECISIONS.length} or one of: ${REPLICA_IDENTITY_DECISIONS.join(", ")}.`
+    );
+  }
+}
+async function runInteractivePrompt(rows) {
+  const rl = createInterface2({ input: process.stdin, output: process.stdout });
+  try {
+    const decisions = {};
+    for (let index = 0; index < rows.length; index += 1) {
+      const row = rows[index];
+      decisions[row.fqn] = await promptForDecision(rl, row, index, rows.length);
+      console.log("");
+    }
+    return decisions;
+  } finally {
+    rl.close();
+  }
+}
+function logAcceptDefaults(rows, decisions) {
+  logPreflightTable(rows);
+  console.log(
+    "Saving the current/default decision for every table above. Undecided tables will be excluded from replication."
+  );
+  for (const fqn of Object.keys(decisions).sort()) {
+    console.log(`  - ${fqn} -> ${decisions[fqn]}`);
+  }
+  console.log("");
+}
+function logSubmissionDisallowed() {
+  console.error("");
+  console.error(
+    "\u2717 Replica-identity decisions cannot be changed while setup is already in progress."
+  );
+  console.error(
+    "  Wait for the current setup attempt to finish, then retry setup if the connector still shows setup pending."
+  );
+  console.error("  Contact Ardent support if the connector stays validating.");
+}
+function logNonInteractiveRequired(decisionsNeeded) {
+  const noun = decisionsNeeded === 1 ? "table" : "tables";
+  const verb = decisionsNeeded === 1 ? "has" : "have";
+  console.error("");
+  console.error(
+    `\u2717 ${decisionsNeeded} ${noun} on your source database ${verb} no replication identity. A decision is required before setup can continue.`
+  );
+  console.error("");
+  console.error("  This shell is not interactive. Re-run with either:");
+  console.error(
+    '    --replica-identity-decisions <path>     Complete JSON file: { "database.schema.table": "exclude|add_pk|replica_identity_full" }'
+  );
+  console.error(
+    "    --accept-replica-identity-defaults      explicitly keep current choices and exclude undecided tables"
+  );
+}
+function renderReplicaIdentityFullSql(preflight) {
+  const sql = (preflight?.replica_identity_full_sql ?? "").trim();
+  if (sql.length === 0) return;
+  console.log("");
+  console.log(
+    "Run the following on your source database before the next snapshot:"
+  );
+  console.log("");
+  console.log(sql);
+  console.log("");
+}
+async function submitDecisions(connectorId, decisions) {
+  const response = await api.put(
+    `/v1/connectors/${connectorId}/replica-identity-decisions`,
+    { decisions }
+  );
+  return response.replica_identity_preflight ?? null;
+}
+function summarizeDecisions(decisions) {
+  const summary = {
+    decisions_total: Object.keys(decisions).length,
+    decisions_exclude: 0,
+    decisions_add_pk: 0,
+    decisions_replica_identity_full: 0,
+    decisions_unknown: 0
+  };
+  for (const value of Object.values(decisions)) {
+    if (value === "exclude") {
+      summary.decisions_exclude += 1;
+    } else if (value === "add_pk") {
+      summary.decisions_add_pk += 1;
+    } else if (value === "replica_identity_full") {
+      summary.decisions_replica_identity_full += 1;
+    } else {
+      summary.decisions_unknown += 1;
+    }
+  }
+  return summary;
+}
+async function handleReplicaIdentityPreflight(connectorId, options, behavior = {}) {
+  const allowDecisionSubmission = behavior.allowDecisionSubmission ?? true;
+  if (options.replicaIdentityDecisions && options.acceptReplicaIdentityDefaults) {
+    console.error(
+      "\u2717 --replica-identity-decisions and --accept-replica-identity-defaults are mutually exclusive."
+    );
+    console.error("  Pass one or the other.");
+    process.exit(1);
+  }
+  let connector;
+  try {
+    connector = await api.get(
+      `/v1/connectors/${connectorId}`
+    );
+  } catch (err) {
+    console.error(
+      "\u2717 Could not fetch connector for replica-identity preflight:",
+      err instanceof Error ? err.message : String(err)
+    );
+    process.exit(1);
+  }
+  const preflight = connector.replica_identity_preflight ?? null;
+  if (!preflight) {
+    return { submitted: false, preflight: null };
+  }
+  if (preflight.status === "unavailable") {
+    trackEvent("CLI: replica identity preflight unavailable", {
+      connector_id: connectorId
+    });
+    console.error("");
+    console.error(
+      "\u2717 Replica identity preflight is unavailable for this connector. Contact Ardent support."
+    );
+    process.exit(1);
+  }
+  if (preflight.decisions_needed === 0) {
+    return { submitted: false, preflight };
+  }
+  const allDecisionsRecorded = preflight.decisions_recorded >= preflight.decisions_needed;
+  if (allDecisionsRecorded && !options.replicaIdentityDecisions && !options.acceptReplicaIdentityDefaults) {
+    renderReplicaIdentityFullSql(preflight);
+    return { submitted: false, preflight };
+  }
+  if (!allowDecisionSubmission) {
+    logSubmissionDisallowed();
+    process.exit(1);
+  }
+  let decisions;
+  let submissionMode;
+  if (options.replicaIdentityDecisions) {
+    try {
+      decisions = loadDecisionsFromFile(options.replicaIdentityDecisions);
+      validateDecisionsAgainstPreflight(decisions, preflight);
+    } catch (err) {
+      console.error(
+        "\u2717",
+        err instanceof Error ? err.message : String(err)
+      );
+      process.exit(1);
+    }
+    submissionMode = "file";
+  } else if (options.acceptReplicaIdentityDefaults) {
+    decisions = buildDefaultedDecisions(preflight);
+    logAcceptDefaults(preflight.no_replication_identity_tables, decisions);
+    submissionMode = "defaults";
+  } else if (isInteractive()) {
+    logPreflightTable(preflight.no_replication_identity_tables);
+    decisions = await runInteractivePrompt(
+      preflight.no_replication_identity_tables
+    );
+    submissionMode = "interactive";
+  } else {
+    trackEvent("CLI: replica identity preflight non_interactive_required", {
+      connector_id: connectorId,
+      decisions_needed: preflight.decisions_needed
+    });
+    logNonInteractiveRequired(preflight.decisions_needed);
+    process.exit(1);
+  }
+  let refreshed;
+  try {
+    refreshed = await submitDecisions(connectorId, decisions);
+  } catch (err) {
+    trackEvent("CLI: replica identity preflight submission failed", {
+      connector_id: connectorId,
+      mode: submissionMode
+    });
+    console.error(
+      "\u2717 Failed to save replica-identity decisions:",
+      err instanceof Error ? err.message : String(err)
+    );
+    process.exit(1);
+  }
+  trackEvent("CLI: replica identity preflight submitted", {
+    connector_id: connectorId,
+    mode: submissionMode,
+    ...summarizeDecisions(decisions)
+  });
+  renderReplicaIdentityFullSql(refreshed);
+  const total = Object.keys(decisions).length;
+  console.log(
+    `\u2713 Replica-identity decisions saved (${total} ${total === 1 ? "table" : "tables"}).`
+  );
+  return { submitted: true, preflight: refreshed };
+}
+
 // src/commands/connector/create.ts
 function parsePostgresUrl(url) {
   const atIndex = url.lastIndexOf("@");
@@ -1220,7 +1599,15 @@ async function createAction2(type, url, options) {
     }
     const created = await api.post("/v1/connectors", createPayload);
     const connectorId = created.id;
+    const replicaIdentityPreflightOptions = {
+      replicaIdentityDecisions: options.replicaIdentityDecisions,
+      acceptReplicaIdentityDefaults: options.acceptReplicaIdentityDefaults
+    };
     if (isByoc) {
+      await handleReplicaIdentityPreflight(
+        connectorId,
+        replicaIdentityPreflightOptions
+      );
       console.log("Setting up branching engine...");
       try {
         await runEngineSetupWithPolling(connectorId, connectorName);
@@ -1282,6 +1669,10 @@ async function createAction2(type, url, options) {
         }
       }
       if (connector.branching_engine_status === "configuration_verified") {
+        await handleReplicaIdentityPreflight(
+          connectorId,
+          replicaIdentityPreflightOptions
+        );
         console.log("Setting up branching engine...");
         try {
           await runEngineSetupWithPolling(connectorId, connectorName);
@@ -1308,13 +1699,30 @@ async function createAction2(type, url, options) {
     setCacheEntry("connectors", cachedConnectors);
     setConfig("currentConnectorId", connectorId);
     setConfig("currentConnectorName", connectorName);
+    const isDegraded = finalConnector.branching_engine_status === "degraded";
     trackEvent("CLI: connector create succeeded", {
       db_type: type,
       byoc: isByoc,
-      deployment_model: deploymentModel
+      deployment_model: deploymentModel,
+      degraded: isDegraded
     });
-    console.log("\u2713 Connector created and ready");
-    console.log(`  ID: ${connectorId}`);
+    if (isDegraded) {
+      console.log("\u2713 Connector created");
+      console.log(`  ID: ${connectorId}`);
+      console.log("");
+      let warnings = [];
+      try {
+        warnings = await fetchConnectorWarnings(currentProjectId, connectorId);
+      } catch (warningsErr) {
+        trackEvent("CLI: connector create degraded warnings unavailable", {
+          reason: warningsErr instanceof Error ? warningsErr.message : "unknown"
+        });
+      }
+      printDegradedWarnings(warnings);
+    } else {
+      console.log("\u2713 Connector created and ready");
+      console.log(`  ID: ${connectorId}`);
+    }
     showNextStep();
   } catch (err) {
     if (isPermissionError(err)) {
@@ -1334,6 +1742,7 @@ async function createAction2(type, url, options) {
 
 // src/lib/connector_render.ts
 var GREEN = "\x1B[32m";
+var YELLOW2 = "\x1B[33m";
 var CYAN = "\x1B[36m";
 var RED = "\x1B[31m";
 function pendingHint(state, connectorName) {
@@ -1357,6 +1766,9 @@ function renderConnectorIcon(connector) {
   if (connector.status === "healthy") {
     return { kind: "ready", icon: "\u25CF", color: GREEN };
   }
+  if (connector.status === "degraded") {
+    return { kind: "degraded", icon: "\u25CF", color: YELLOW2 };
+  }
   return { kind: "broken", icon: "\u25CB", color: RED };
 }
 
@@ -1540,7 +1952,7 @@ function connectorRetrySetupFailureTelemetry(err) {
   }
   return { reason: "api_error" };
 }
-async function retrySetupAction(name) {
+async function retrySetupAction(name, options = {}) {
   const currentProjectId = getConfig("currentProjectId");
   if (!currentProjectId) {
     console.error("\u2717 No current project set. Switch to a project first:");
@@ -1574,6 +1986,16 @@ async function retrySetupAction(name) {
     connector_id: connector.id,
     starting_engine_status: connector.branching_engine_status ?? null
   });
+  await handleReplicaIdentityPreflight(
+    connector.id,
+    {
+      replicaIdentityDecisions: options.replicaIdentityDecisions,
+      acceptReplicaIdentityDefaults: options.acceptReplicaIdentityDefaults
+    },
+    {
+      allowDecisionSubmission: connector.branching_engine_status !== "validating"
+    }
+  );
   console.log(`Setting up branching engine for ${name}...`);
   try {
     const { dispatched } = await runEngineSetupWithPolling(connector.id, name);
@@ -1586,12 +2008,16 @@ async function retrySetupAction(name) {
       connector_id: connector.id,
       dispatched
     });
+    let postSetupConnector;
     try {
       const refreshed = await api.get(
         `/v1/cli/connectors?project_id=${currentProjectId}`
       );
       if (refreshed.connectors) {
         setCacheEntry("connectors", refreshed.connectors);
+        postSetupConnector = refreshed.connectors.find(
+          (candidate) => candidate.id === connector.id
+        );
       }
     } catch {
     }
@@ -1600,6 +2026,10 @@ async function retrySetupAction(name) {
     } else {
       console.log("\u2713 Engine setup complete");
     }
+    if (postSetupConnector?.branching_engine_status === "degraded") {
+      console.log("");
+      printDegradedWarnings(postSetupConnector.warnings ?? []);
+    }
   } catch (err) {
     const failureTelemetry = connectorRetrySetupFailureTelemetry(err);
     if (isPermissionError(err)) {
@@ -1768,11 +2198,23 @@ connectorCommand.command("create <type> [url]").description("Create a new connec
 ).option(
   "--aws-cluster-name <name>",
   "EKS cluster name in the customer account where pgstream pods run (required with --deployment-model=customer-cloud)"
+).option(
+  "--replica-identity-decisions <path>",
+  'Path to a complete JSON file mapping every current "database.schema.table" preflight FQN -> "exclude" | "add_pk" | "replica_identity_full".'
+).option(
+  "--accept-replica-identity-defaults",
+  "Non-interactively save the current/default decision for every table with no replication identity. Undecided tables are excluded from replication."
 ).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)"
+).option(
+  "--replica-identity-decisions <path>",
+  'Path to a complete JSON file mapping every current "database.schema.table" preflight FQN -> "exclude" | "add_pk" | "replica_identity_full".'
+).option(
+  "--accept-replica-identity-defaults",
+  "Non-interactively save the current/default decision for every table with no replication identity. Undecided tables are excluded from replication."
 ).action(retrySetupAction);
 connectorCommand.command("update <name>").description("Update a connector's configuration").option(
   "--drop-extensions <list>",
@@ -2264,7 +2706,7 @@ projectCommand.command("delete <name>").description("Delete a project by name").
 import { Command as Command6 } from "commander";
 
 // src/lib/settings.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 var SETTING_KEYS = ["default_db", "branch_sql"];
 function requireConnectorAndOrg() {
   const connectorId = getConfig("currentConnectorId");
@@ -2314,7 +2756,7 @@ function resolveValueFromArg(value) {
   if (value.startsWith("@")) {
     const path = value.slice(1);
     try {
-      return readFileSync3(path, "utf-8");
+      return readFileSync4(path, "utf-8");
     } catch (err) {
       throw new Error(
         `Failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`
@@ -2615,7 +3057,7 @@ var logoutCommand = new Command7("logout").description("Logout from Ardent").act
 var statusCommand = new Command7("status").description("Show status").action(statusAction);
 
 // src/lib/update-check.ts
-import { existsSync as existsSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
 import { join as join2 } from "path";
 import { homedir as homedir2 } from "os";
 var UPDATE_CHECK_FILE = join2(homedir2(), ".ardent", "update-check.json");
@@ -2624,7 +3066,7 @@ var PACKAGE_NAME = "ardent-cli";
 function loadCache() {
   try {
     if (existsSync2(UPDATE_CHECK_FILE)) {
-      return JSON.parse(readFileSync4(UPDATE_CHECK_FILE, "utf-8"));
+      return JSON.parse(readFileSync5(UPDATE_CHECK_FILE, "utf-8"));
     }
   } catch {
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ardent-cli",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "description": "Git for Data infrastructure",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "start": "node dist/index.js",
-    "test": "tsx --test src/lib/*.test.ts"
+    "//test": "Keep --test-concurrency=1: the *.test.ts files mutate process-wide globals (process.env.HOME, globalThis.fetch) and race if run in parallel. Remove only after introducing per-file process isolation.",
+    "test": "tsx --test --test-concurrency=1 src/lib/*.test.ts"
   },
   "files": [
     "dist"