@abloatai/cli 0.60.0 → 0.61.0

package/dist/cli.cjs

@@ -3976,7 +3976,7 @@ var init_observeCliError = __esm({
     import_errorObservation = require("@abloatai/transaction/errorObservation");
     import_errors5 = require("@abloatai/transaction/errors");
     dsn = process.env.ABLO_CLI_SENTRY_DSN ?? "https://1ac154bff10b06836e1ea9de9e0d92f0@o4510928209772544.ingest.de.sentry.io/4511660691423312" ?? "";
-    release = process.env.ABLO_CLI_RELEASE ?? "@abloatai/cli@0.60.0";
+    release = process.env.ABLO_CLI_RELEASE ?? "@abloatai/cli@0.61.0";
     initialized = false;
     nativeProcessExit = process.exit.bind(process);
     exitBoundaryInstalled = false;
@@ -4311,7 +4311,7 @@ var init_src2 = __esm({
 
 // src/cliEnvironment.ts
 function cliVersion() {
-  return "0.60.0";
+  return "0.61.0";
 }
 function cliOs() {
   const value = (0, import_node_os.platform)();
@@ -5368,6 +5368,210 @@ var init_dbProvider = __esm({
   }
 });
 
+// src/connect/inspect.ts
+function inspectRegisteredConnection(validation) {
+  if (!validation.ok) {
+    return {
+      object: "database_connection_reconcile",
+      code: "operator_action_required",
+      steps: {
+        database: "pending",
+        registration: "unchanged",
+        snapshot: "pending",
+        readiness: "action_required"
+      },
+      repairItems: [],
+      needsDatabaseReconcile: false,
+      needsSnapshotRequest: false,
+      detail: validation.code ?? validation.message
+    };
+  }
+  if (!validation.reachable) {
+    return {
+      object: "database_connection_reconcile",
+      code: "operator_action_required",
+      steps: {
+        database: "action_required",
+        registration: "unchanged",
+        snapshot: "pending",
+        readiness: "action_required"
+      },
+      repairItems: [],
+      needsDatabaseReconcile: false,
+      needsSnapshotRequest: false,
+      detail: validation.reason ?? "source_unreachable"
+    };
+  }
+  if (validation.failures.length > 0) {
+    const repairItems = [...new Set(validation.failures.map((failure) => failure.item))].sort();
+    const operatorItems = repairItems.filter((item) => !DATABASE_RECONCILABLE_ITEMS.has(item));
+    if (operatorItems.length > 0) {
+      return {
+        object: "database_connection_reconcile",
+        code: "operator_action_required",
+        steps: {
+          database: "action_required",
+          registration: "unchanged",
+          snapshot: "pending",
+          readiness: "action_required"
+        },
+        repairItems,
+        needsDatabaseReconcile: false,
+        needsSnapshotRequest: false,
+        detail: operatorItems.join(",")
+      };
+    }
+    return {
+      object: "database_connection_reconcile",
+      code: "reconciling",
+      steps: {
+        database: "pending",
+        registration: "unchanged",
+        snapshot: "pending",
+        readiness: "pending"
+      },
+      repairItems,
+      needsDatabaseReconcile: true,
+      needsSnapshotRequest: repairItems.some((item) => SNAPSHOT_SENSITIVE_ITEMS.has(item)) || validation.initialSnapshot?.status === "retrying"
+    };
+  }
+  if (validation.initialSnapshot?.status === "retrying") {
+    return {
+      object: "database_connection_reconcile",
+      code: "reconciling",
+      steps: {
+        database: "unchanged",
+        registration: "unchanged",
+        snapshot: "pending",
+        readiness: "pending"
+      },
+      repairItems: [],
+      needsDatabaseReconcile: false,
+      needsSnapshotRequest: true,
+      ...validation.initialSnapshot.detail ? { detail: validation.initialSnapshot.detail } : {}
+    };
+  }
+  if (validation.initialSnapshot?.status === "loading") {
+    return {
+      object: "database_connection_reconcile",
+      code: "loading",
+      steps: {
+        database: "unchanged",
+        registration: "unchanged",
+        snapshot: "loading",
+        readiness: "pending"
+      },
+      repairItems: [],
+      needsDatabaseReconcile: false,
+      needsSnapshotRequest: false
+    };
+  }
+  if (validation.ready) {
+    return {
+      object: "database_connection_reconcile",
+      code: "ready",
+      steps: {
+        database: "unchanged",
+        registration: "unchanged",
+        snapshot: "ready",
+        readiness: "ready"
+      },
+      repairItems: [],
+      needsDatabaseReconcile: false,
+      needsSnapshotRequest: false
+    };
+  }
+  return {
+    object: "database_connection_reconcile",
+    code: "operator_action_required",
+    steps: {
+      database: "unchanged",
+      registration: "unchanged",
+      snapshot: "pending",
+      readiness: "action_required"
+    },
+    repairItems: [],
+    needsDatabaseReconcile: false,
+    needsSnapshotRequest: false,
+    detail: "unclassified_not_ready"
+  };
+}
+function absentConnectionStatus() {
+  return {
+    object: "database_connection_reconcile",
+    code: "absent",
+    steps: {
+      database: "pending",
+      registration: "pending",
+      snapshot: "pending",
+      readiness: "pending"
+    },
+    repairItems: [],
+    needsDatabaseReconcile: true,
+    needsSnapshotRequest: false
+  };
+}
+var SNAPSHOT_SENSITIVE_ITEMS, DATABASE_RECONCILABLE_ITEMS;
+var init_inspect = __esm({
+  "src/connect/inspect.ts"() {
+    "use strict";
+    init_cjs_shims();
+    SNAPSHOT_SENSITIVE_ITEMS = /* @__PURE__ */ new Set([
+      "publication",
+      "publication_drift",
+      "replica_identity",
+      "snapshot_row_security",
+      "table_select"
+    ]);
+    DATABASE_RECONCILABLE_ITEMS = /* @__PURE__ */ new Set([
+      "publication",
+      "replication_role",
+      "replica_identity",
+      "table_select",
+      "snapshot_row_security",
+      "write_role",
+      "row_security",
+      "database_privileges",
+      "schema_privileges",
+      "idempotency_ledger",
+      "table_privileges",
+      "logical_marker",
+      "publication_drift"
+    ]);
+  }
+});
+
+// src/connect/snapshot.ts
+function requestInitialSnapshot(input) {
+  return requestControlPlane({
+    path: "/v1/datasources/resnapshot",
+    method: "POST",
+    ...input.apiUrl ? { baseUrl: input.apiUrl } : {},
+    apiKey: input.apiKey,
+    body: {},
+    responseSchema: import_wire2.datasourceResnapshotResponseSchema
+  });
+}
+var import_wire2;
+var init_snapshot = __esm({
+  "src/connect/snapshot.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_wire2 = require("@abloatai/transaction/wire");
+    init_controlPlane();
+  }
+});
+
+// src/connect/index.ts
+var init_connect = __esm({
+  "src/connect/index.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_inspect();
+    init_snapshot();
+  }
+});
+
 // src/remoteValidation.ts
 function dialFailureReason(err) {
   if (err === null || typeof err !== "object") return null;
@@ -5385,7 +5589,7 @@ function dialFailureReason(err) {
   return null;
 }
 function describeRemoteFailure(failure) {
-  const label = (0, import_wire2.isReadinessItem)(failure.item) ? READINESS_LABELS[failure.item](failure) : failure.item;
+  const label = (0, import_wire3.isReadinessItem)(failure.item) ? READINESS_LABELS[failure.item](failure) : failure.item;
   return { label, fix: failure.fix };
 }
 async function requestRemoteValidation(input) {
@@ -5398,7 +5602,7 @@ async function requestRemoteValidation(input) {
       ...input.connectionString ? { connectionString: input.connectionString } : {},
       ...input.writeConnectionString ? { writeConnectionString: input.writeConnectionString } : {}
     },
-    responseSchema: import_wire2.datasourceValidationResponseSchema,
+    responseSchema: import_wire3.datasourceValidationResponseSchema,
     ...input.fetchImpl ? { fetchImpl: input.fetchImpl } : {}
   });
   if (!result.ok) {
@@ -5419,12 +5623,12 @@ async function requestRemoteValidation(input) {
     failures: verdict.failures
   };
 }
-var import_wire2, DIAL_FAILURE_CODES, withActual, READINESS_LABELS;
+var import_wire3, DIAL_FAILURE_CODES, withActual, READINESS_LABELS;
 var init_remoteValidation = __esm({
   "src/remoteValidation.ts"() {
     "use strict";
     init_cjs_shims();
-    import_wire2 = require("@abloatai/transaction/wire");
+    import_wire3 = require("@abloatai/transaction/wire");
     init_controlPlane();
     DIAL_FAILURE_CODES = /* @__PURE__ */ new Set([
       "ENOTFOUND",
@@ -5777,19 +5981,21 @@ async function registerDirectDataSource(opts) {
       ...opts.replicationSlot ? { replicationSlot: opts.replicationSlot } : {},
       ...opts.publication ? { publication: opts.publication } : {}
     },
-    responseSchema: import_wire3.datasourceSummarySchema
+    responseSchema: import_wire4.datasourceSummarySchema
   });
   if (result.ok) {
     const body = result.value;
     const statusNote = body.status === "active" ? `${opts.route}, active` : opts.route;
-    console.log(
-      `
+    if (!opts.quiet) {
+      console.log(
+        `
   ${import_picocolors8.default.green("\u2713")} Registered${body.host ? ` ${import_picocolors8.default.dim(body.host)}` : ""}${body.id ? ` ${import_picocolors8.default.dim(`(${body.id})`)}` : ""} as a direct DataSource (${statusNote}).
   Your database is connected. Reads follow its replication stream; writes go through Ablo
   and land in your own tables. Rows that already exist load automatically \u2014 no manual
   backfill or row updates. Check their progress with ${import_picocolors8.default.cyan("ablo connect check")}.
 `
-    );
+      );
+    }
     return true;
   }
   const err = result.error;
@@ -5861,14 +6067,14 @@ async function registerDirectDataSource(opts) {
   console.error();
   return false;
 }
-var import_picocolors8, import_zod3, import_wire3, import_source2, import_footprint, DIRECT_DATA_SOURCE_ROUTES, registerFailureDetailsSchema;
+var import_picocolors8, import_zod3, import_wire4, import_source2, import_footprint, DIRECT_DATA_SOURCE_ROUTES, registerFailureDetailsSchema;
 var init_connectSetup = __esm({
   "src/connectSetup.ts"() {
     "use strict";
     init_cjs_shims();
     import_picocolors8 = __toESM(require_picocolors(), 1);
     import_zod3 = require("zod");
-    import_wire3 = require("@abloatai/transaction/wire");
+    import_wire4 = require("@abloatai/transaction/wire");
     init_controlPlane();
     init_remoteValidation();
     import_source2 = require("@abloatai/transaction/source");
@@ -5881,10 +6087,10 @@ var init_connectSetup = __esm({
       "vpn"
     ];
     registerFailureDetailsSchema = import_zod3.z.object({
-      failures: import_zod3.z.array(import_wire3.readinessFailureSchema).optional(),
+      failures: import_zod3.z.array(import_wire4.readinessFailureSchema).optional(),
       reason: import_zod3.z.string().optional(),
       details: import_zod3.z.object({
-        failures: import_zod3.z.array(import_wire3.readinessFailureSchema).optional(),
+        failures: import_zod3.z.array(import_wire4.readinessFailureSchema).optional(),
         reason: import_zod3.z.string().optional()
       }).loose().optional()
     }).loose();
@@ -5910,7 +6116,7 @@ async function deregisterDataSource(opts) {
       path: "/v1/datasources",
       method: "DELETE",
       apiKey: opts.apiKey,
-      responseSchema: import_wire4.datasourceDisconnectedResponseSchema,
+      responseSchema: import_wire5.datasourceDisconnectedResponseSchema,
       ...opts.baseUrl !== void 0 ? { baseUrl: opts.baseUrl } : {},
       ...opts.fetchImpl !== void 0 ? { fetchImpl: opts.fetchImpl } : {}
     });
@@ -6046,7 +6252,7 @@ async function disconnect(argv) {
   }
   renderDisconnected(outcome.response, project, branchLabel);
 }
-var import_picocolors9, import_errors10, import_wire4, DISCONNECT_USAGE;
+var import_picocolors9, import_errors10, import_wire5, DISCONNECT_USAGE;
 var init_disconnect = __esm({
   "src/disconnect.ts"() {
     "use strict";
@@ -6054,7 +6260,7 @@ var init_disconnect = __esm({
     import_picocolors9 = __toESM(require_picocolors(), 1);
     init_dist2();
     import_errors10 = require("@abloatai/transaction/errors");
-    import_wire4 = require("@abloatai/transaction/wire");
+    import_wire5 = require("@abloatai/transaction/wire");
     init_config();
     init_dbRole();
     init_controlPlane();
@@ -6207,7 +6413,7 @@ async function fetchPushedSchema(apiUrl3, apiKey) {
       signal: ctrl.signal
     });
     if (!res.ok) return null;
-    const parsed = import_wire5.schemaReadResponseSchema.safeParse(await res.json());
+    const parsed = import_wire6.schemaReadResponseSchema.safeParse(await res.json());
     if (!parsed.success) return null;
     const read = parsed.data;
     return read.active ? {
@@ -6235,7 +6441,7 @@ async function fetchDeliveryState(apiUrl3, apiKey, timeoutMs = 4e3) {
       signal: ctrl.signal
     });
     if (!res.ok) return { kind: "unknown", detail: `HTTP ${res.status}` };
-    const parsed = import_wire5.logDeliveryResponseSchema.safeParse(await res.json());
+    const parsed = import_wire6.logDeliveryResponseSchema.safeParse(await res.json());
     if (!parsed.success) return { kind: "unknown", detail: "unrecognized response" };
     const { window_seconds, recorded, unroutable, sample } = parsed.data;
     return { kind: "known", window_seconds, recorded, unroutable, sample: sample ?? null };
@@ -6259,7 +6465,7 @@ async function fetchDataSourceState(apiUrl3, apiKey, timeoutMs = 4e3) {
     if (!res.ok) {
       return { kind: "unknown", detail: `HTTP ${res.status}` };
     }
-    const parsed = import_wire5.datasourceListResponseSchema.safeParse(await res.json());
+    const parsed = import_wire6.datasourceListResponseSchema.safeParse(await res.json());
     if (!parsed.success) return { kind: "unknown", detail: "unrecognized response" };
     const rows = parsed.data.data;
     if (rows.length === 0) return { kind: "none" };
@@ -6346,12 +6552,12 @@ function blockers(input) {
   }
   return found;
 }
-var import_wire5, import_schema5, WRITE_READY_VERDICT;
+var import_wire6, import_schema5, WRITE_READY_VERDICT;
 var init_readiness = __esm({
   "src/readiness.ts"() {
     "use strict";
     init_cjs_shims();
-    import_wire5 = require("@abloatai/transaction/wire");
+    import_wire6 = require("@abloatai/transaction/wire");
     init_push();
     init_dbProvider();
     init_remoteValidation();
@@ -6646,7 +6852,7 @@ async function locateExistingConnection(input) {
       connectionString: input.connectionString,
       ...input.schema ? { schema: input.schema } : {}
     },
-    responseSchema: import_wire6.datasourceLocationResponseSchema
+    responseSchema: import_wire7.datasourceLocationResponseSchema
   });
   if (!result.ok) return null;
   if (result.value.held) return result.value.held;
@@ -6660,13 +6866,13 @@ function alreadyConnectedElsewhere(held) {
   const where = held.project ? `project ${held.project}, branch ${held.branch}` : `branch ${held.branch}`;
   return `This database schema is already connected to ${where}. A (database, schema) binding belongs to one plane at a time.`;
 }
-var import_wire6, import_schema6;
+var import_wire7, import_schema6;
 var init_connectPreflight = __esm({
   "src/connectPreflight.ts"() {
     "use strict";
     init_cjs_shims();
     init_src();
-    import_wire6 = require("@abloatai/transaction/wire");
+    import_wire7 = require("@abloatai/transaction/wire");
     init_controlPlane();
     init_push();
     import_schema6 = require("@abloatai/transaction/schema");
@@ -6689,6 +6895,26 @@ function postRegistrationOutcome(input) {
     notice: ROTATE_STRANDED_CREDENTIALS_NOTICE
   };
 }
+function emitReconcileStatus(status2, json) {
+  if (json) {
+    console.log(JSON.stringify(status2));
+    return;
+  }
+  if (status2.code === "ready") {
+    console.log(
+      `  ${import_picocolors12.default.green("\u2713")} Already ready \u2014 database, credentials, and snapshot are unchanged.
+`
+    );
+  } else if (status2.code === "loading") {
+    console.log(
+      `  ${import_picocolors12.default.yellow("\u2014")} Existing rows are loading; re-run the same command to poll readiness.
+`
+    );
+  } else {
+    console.log(`  ${import_picocolors12.default.yellow("\u2014")} ${status2.code}
+`);
+  }
+}
 function isPlaintextRefusal(err) {
   const message2 = err instanceof Error ? err.message : String(err);
   return /plaintext password/i.test(message2);
@@ -6720,15 +6946,10 @@ async function runConnectApply(args) {
   const rotating = args.rotate;
   const verb = rotating ? "connect rotate" : "connect apply";
   let adminUrl = args.url ?? readProjectAdminDatabaseUrl();
-  if (!adminUrl) {
-    throw new import_errors11.AbloValidationError(
-      "No admin connection string. Pass --url <admin-conn> (or set DATABASE_URL) and re-run.",
-      { code: "cli_database_url_missing" }
-    );
-  }
   const adminSource = args.url ? "--url" : "DATABASE_URL";
   let target = "your database";
   try {
+    if (!adminUrl) throw new Error("not resolved yet");
     const parsed = new URL(adminUrl);
     target = `${parsed.host}${parsed.pathname === "/" ? "" : parsed.pathname}`;
   } catch {
@@ -6752,15 +6973,62 @@ ${ambient}` : ""}`,
       { code: "cli_api_key_missing" }
     );
   }
-  console.log(
-    `
+  const apiUrl3 = apiBaseUrl();
+  const planeState = await fetchDataSourceState(apiUrl3, apiKey);
+  const existingRegistration = !rotating && planeState.kind === "connected" && planeState.connections.includes("direct");
+  let existingNeedsSnapshot = false;
+  if (existingRegistration) {
+    const inspected = inspectRegisteredConnection(
+      await requestRemoteValidation({ apiUrl: apiUrl3, apiKey })
+    );
+    if (inspected.code === "ready") {
+      emitReconcileStatus(inspected, args.json);
+      return;
+    }
+    if (inspected.code === "loading") {
+      emitReconcileStatus(inspected, args.json);
+      return;
+    }
+    if (!inspected.needsDatabaseReconcile && inspected.needsSnapshotRequest) {
+      const snapshot = await requestInitialSnapshot({ apiUrl: apiUrl3, apiKey });
+      const resumed = {
+        ...inspected,
+        code: snapshot.replication_slot?.released === false ? "operator_action_required" : "loading",
+        steps: {
+          ...inspected.steps,
+          snapshot: snapshot.replication_slot?.released === false ? "action_required" : "loading",
+          readiness: snapshot.replication_slot?.released === false ? "action_required" : "pending"
+        },
+        ...snapshot.replication_slot?.released === false ? { detail: snapshot.replication_slot.detail ?? "replication_slot_active" } : {}
+      };
+      emitReconcileStatus(resumed, args.json);
+      return;
+    }
+    if (inspected.code === "operator_action_required") {
+      throw new import_errors11.AbloConnectionError(
+        `The registered source needs operator action before it can be reconciled (${inspected.detail ?? "not ready"}).`,
+        { code: "cli_database_unreachable", details: { ...inspected } }
+      );
+    }
+    existingNeedsSnapshot = inspected.needsSnapshotRequest;
+  }
+  if (!adminUrl) {
+    throw new import_errors11.AbloValidationError(
+      "This connection needs database reconciliation. Pass the transient owner connection with --url <admin-conn> (or set DATABASE_URL) and re-run the same `ablo connect apply` operation.",
+      { code: "cli_database_url_missing" }
+    );
+  }
+  if (!args.json) {
+    console.log(
+      `
   ${brand("ablo")} ${import_picocolors12.default.dim(verb)}  ${import_picocolors12.default.dim(rotating ? "re-key the scoped roles" : "set up your database for Ablo")}
 `
-  );
-  console.log(
-    `  ${import_picocolors12.default.dim("\u2192")} ${import_picocolors12.default.bold(target)}${adminSource === "DATABASE_URL" ? import_picocolors12.default.dim("  (admin via DATABASE_URL)") : ""}
+    );
+    console.log(
+      `  ${import_picocolors12.default.dim("\u2192")} ${import_picocolors12.default.bold(target)}${adminSource === "DATABASE_URL" ? import_picocolors12.default.dim("  (admin via DATABASE_URL)") : ""}
 `
-  );
+    );
+  }
   const pooledAdmin = detectPooler(adminUrl);
   if (pooledAdmin?.confidence === "host") {
     if (pooledAdmin.direct) {
@@ -6771,7 +7039,7 @@ ${ambient}` : ""}`,
         target = `${parsed.host}${parsed.pathname === "/" ? "" : parsed.pathname}`;
       } catch {
       }
-      console.log(
+      if (!args.json) console.log(
         `  ${import_picocolors12.default.yellow("!")} ${import_picocolors12.default.bold(pooledLabel)} is a connection pooler, so this run uses the direct host:
     ${import_picocolors12.default.bold(target)}
 ` + import_picocolors12.default.dim(
@@ -6798,7 +7066,7 @@ ${ambient}` : ""}`,
     }
   }
   if (pooledAdmin?.confidence === "port") {
-    console.log(
+    if (!args.json) console.log(
       `  ${import_picocolors12.default.yellow("!")} Port ${import_picocolors12.default.bold(new URL(adminUrl).port)} is the one a connection pooler usually answers on.
 ` + import_picocolors12.default.dim(
         `    Replication cannot run over a pooler, so if that is what this is, point ${import_picocolors12.default.bold("--url")}
@@ -6814,7 +7082,7 @@ ${ambient}` : ""}`,
   }).catch(() => null);
   const mismatch = connectTarget ? describeMismatches(connectTarget.mismatches) : null;
   if (mismatch) {
-    console.log(`  ${import_picocolors12.default.yellow("!")} ${mismatch}
+    if (!args.json) console.log(`  ${import_picocolors12.default.yellow("!")} ${mismatch}
 `);
   }
   const confirmed = connectTarget?.confirmed;
@@ -6859,7 +7127,7 @@ ${ambient}` : ""}`,
     );
   }
   if (args.tables.length === 0) {
-    console.log(
+    if (!args.json) console.log(
       import_picocolors12.default.dim(
         `  publishing the ${tables.length} table${tables.length === 1 ? "" : "s"} declared by your Ablo schema in ${import_picocolors12.default.bold(args.schema)} (${import_picocolors12.default.bold("--tables")} to override)
 `
@@ -6950,6 +7218,13 @@ ${ambient}` : ""}`,
     publication
   });
   const existingRoles = await presentRoles(admin, [role, writeRole]).catch(() => []);
+  if (existingRegistration && existingRoles.length !== 2) {
+    await admin.end({ timeout: 2 });
+    throw new import_errors11.AbloValidationError(
+      `The registered source's scoped role pair is incomplete (${existingRoles.length}/2 present). Re-run with \`ablo connect rotate\` to repair credentials explicitly; no database changes were made.`,
+      { code: "cli_invalid_arguments", details: { existingRoles: [...existingRoles] } }
+    );
+  }
   if (rotatePlane) {
     const refusal = rotateWithoutConnection({ rotating, ...rotatePlane, existingRoles });
     if (refusal) {
@@ -6963,11 +7238,14 @@ ${ambient}` : ""}`,
   }
   const blocker2 = reapplyBlocker({
     rotating,
-    existingRoles
+    // A complete, registered pair keeps its current passwords: apply repairs
+    // only non-secret invariants and never re-registers it. A partial pair is
+    // still refused because it cannot be completed without credential repair.
+    existingRoles: existingRegistration && existingRoles.length === 2 ? [] : existingRoles
   });
   if (blocker2) {
     await admin.end({ timeout: 2 });
-    console.log(
+    if (!args.json) console.log(
       `  ${import_picocolors12.default.yellow("!")} ${blocker2.roles.map((r2) => import_picocolors12.default.bold(r2)).join(" and ")} ${blocker2.plural ? "are" : "is"} already set up here.
 `
     );
@@ -7014,17 +7292,23 @@ ${ambient}` : ""}`,
   });
   const steps = buildPlan("scram-verifier");
   if (pubReconcile.removed.length > 0 || pubReconcile.recreated) {
-    console.log(
-      `  ${import_picocolors12.default.yellow("!")} ${import_picocolors12.default.bold(publication)} already publishes a different set; reconciling to your mapped tables:`
-    );
-    for (const t of pubReconcile.added) console.log(`      ${import_picocolors12.default.green("+")} ${t}`);
-    for (const t of pubReconcile.removed)
-      console.log(`      ${import_picocolors12.default.red("-")} ${t} ${import_picocolors12.default.dim("(stops replicating to Ablo)")}`);
-    if (pubReconcile.recreated && existingPublication.allTables)
-      console.log(`      ${import_picocolors12.default.red("-")} ${import_picocolors12.default.dim("every other table (was FOR ALL TABLES)")}`);
-    console.log();
+    if (!args.json) {
+      console.log(
+        `  ${import_picocolors12.default.yellow("!")} ${import_picocolors12.default.bold(publication)} already publishes a different set; reconciling to your mapped tables:`
+      );
+      for (const t of pubReconcile.added) console.log(`      ${import_picocolors12.default.green("+")} ${t}`);
+      for (const t of pubReconcile.removed) {
+        console.log(`      ${import_picocolors12.default.red("-")} ${t} ${import_picocolors12.default.dim("(stops replicating to Ablo)")}`);
+      }
+      if (pubReconcile.recreated && existingPublication.allTables) {
+        console.log(
+          `      ${import_picocolors12.default.red("-")} ${import_picocolors12.default.dim("every other table (was FOR ALL TABLES)")}`
+        );
+      }
+      console.log();
+    }
   }
-  printPlan(steps, args.showSql);
+  if (!args.json) printPlan(steps, args.showSql);
   if (!args.yes) {
     if (!process.stdout.isTTY) {
       await admin.end({ timeout: 2 });
@@ -7075,9 +7359,39 @@ ${ambient}` : ""}`,
     process.exit(1);
   }
   await admin.end({ timeout: 2 });
+  if (existingRegistration) {
+    const after = inspectRegisteredConnection(
+      await requestRemoteValidation({ apiUrl: apiUrl3, apiKey })
+    );
+    if (after.needsDatabaseReconcile || after.code === "operator_action_required") {
+      throw new import_errors11.AbloConnectionError(
+        `Database reconciliation did not reach the snapshot boundary (${after.detail ?? after.repairItems.join(", ")}).`,
+        { code: "cli_database_unreachable", details: { ...after } }
+      );
+    }
+    if (existingNeedsSnapshot || after.needsSnapshotRequest) {
+      const snapshot = await requestInitialSnapshot({ apiUrl: apiUrl3, apiKey });
+      const reconciled = {
+        ...after,
+        code: snapshot.replication_slot?.released === false ? "operator_action_required" : "loading",
+        steps: {
+          ...after.steps,
+          database: "changed",
+          registration: "unchanged",
+          snapshot: snapshot.replication_slot?.released === false ? "action_required" : "loading",
+          readiness: snapshot.replication_slot?.released === false ? "action_required" : "pending"
+        },
+        ...snapshot.replication_slot?.released === false ? { detail: snapshot.replication_slot.detail ?? "replication_slot_active" } : {}
+      };
+      emitReconcileStatus(reconciled, args.json);
+      return;
+    }
+    emitReconcileStatus(after, args.json);
+    return;
+  }
   const replicationUrl = rewriteDatabaseUrl(adminUrl, role, replicationPassword);
   const writeUrl = rewriteDatabaseUrl(adminUrl, writeRole, writePassword);
-  console.log(`
+  if (!args.json) console.log(`
   ${import_picocolors12.default.green("\u2713")} Roles ${rotating ? "re-keyed" : "created"}.
 `);
   if (!walReady) {
@@ -7129,7 +7443,7 @@ ${ambient}` : ""}`,
     process.exit(1);
   }
   if (replicationProbe.items === null || writeProbe.items === null) {
-    console.log(import_picocolors12.default.dim(`  Couldn't verify from here; Ablo will validate from its own network.
+    if (!args.json) console.log(import_picocolors12.default.dim(`  Couldn't verify from here; Ablo will validate from its own network.
 `));
   }
   const items = [...replicationProbe.items ?? [], ...writeProbe.items ?? []];
@@ -7153,7 +7467,6 @@ ${ambient}` : ""}`,
 `
     );
   }
-  const apiUrl3 = apiBaseUrl();
   const registered = await registerDirectDataSource({
     apiUrl: apiUrl3,
     apiKey,
@@ -7162,7 +7475,8 @@ ${ambient}` : ""}`,
     route: args.route,
     schema: args.schema,
     replicationSlot: footprint.slot,
-    publication
+    publication,
+    quiet: args.json
   });
   process.off("SIGINT", onRotateInterrupt);
   process.off("SIGTERM", onRotateInterrupt);
@@ -7172,6 +7486,22 @@ ${ambient}` : ""}`,
   ${import_picocolors12.default.red(outcome.notice.split("\n").join("\n  "))}
 `);
   }
+  if (args.json && registered) {
+    const initial = absentConnectionStatus();
+    emitReconcileStatus(
+      {
+        ...initial,
+        code: "loading",
+        steps: {
+          database: "changed",
+          registration: "changed",
+          snapshot: "loading",
+          readiness: "pending"
+        }
+      },
+      true
+    );
+  }
   process.exit(outcome.exitCode);
 }
 var import_picocolors12, import_errors11, import_footprint2, ROTATE_STRANDED_CREDENTIALS_NOTICE;
@@ -7186,11 +7516,13 @@ var init_connectApply = __esm({
     import_footprint2 = require("@abloatai/transaction/footprint");
     init_connectSetup();
     init_connectOwnership();
-    init_connect();
+    init_connect2();
     init_dbProvider();
     init_dbRole();
     init_config();
     init_readiness();
+    init_remoteValidation();
+    init_connect();
     init_push();
     init_controlPlane();
     init_theme();
@@ -7212,6 +7544,7 @@ function parseConnectArgs(argv) {
   let envFile;
   let yes = false;
   let showSql = false;
+  let json = false;
   let scan = false;
   let locate = false;
   let manual = false;
@@ -7269,6 +7602,9 @@ function parseConnectArgs(argv) {
       case "--show-sql":
         showSql = true;
         break;
+      case "--json":
+        json = true;
+        break;
       case "--manual":
         manual = true;
         break;
@@ -7316,6 +7652,7 @@ function parseConnectArgs(argv) {
     envFile,
     yes,
     showSql,
+    json,
     scan,
     locate,
     tables,
@@ -7899,7 +8236,7 @@ ${ambient}` : ""}`,
     method: "POST",
     apiKey,
     body: { connectionString: url, schema: args.schema },
-    responseSchema: import_wire7.datasourceLocationResponseSchema
+    responseSchema: import_wire8.datasourceLocationResponseSchema
   });
   if (answer.available === false && !answer.held) {
     console.log(
@@ -7942,13 +8279,7 @@ async function runResnapshot() {
   ${brand("ablo")} ${import_picocolors13.default.dim("connect resnapshot")}  ${import_picocolors13.default.dim("reload existing rows")}
 `
   );
-  const result = await requestControlPlane({
-    path: "/v1/datasources/resnapshot",
-    method: "POST",
-    apiKey,
-    body: {},
-    responseSchema: import_wire7.datasourceResnapshotResponseSchema
-  });
+  const result = await requestInitialSnapshot({ apiKey });
   if (result.replication_slot?.released === false) {
     console.log(`  ${import_picocolors13.default.yellow("\u2014")} Snapshot reset recorded, but the old slot is still active.`);
     if (result.replication_slot.detail) console.log(`  ${import_picocolors13.default.dim(result.replication_slot.detail)}`);
@@ -8039,8 +8370,8 @@ async function connect(argv) {
     })
   );
 }
-var import_errors12, import_picocolors13, import_footprint3, import_wire7, FOOTPRINT_LOOKUP, CONNECT_USAGE;
-var init_connect = __esm({
+var import_errors12, import_picocolors13, import_footprint3, import_wire8, FOOTPRINT_LOOKUP, CONNECT_USAGE;
+var init_connect2 = __esm({
   "src/connect.ts"() {
     "use strict";
     init_cjs_shims();
@@ -8052,7 +8383,8 @@ var init_connect = __esm({
     init_dbRole();
     init_config();
     init_controlPlane();
-    import_wire7 = require("@abloatai/transaction/wire");
+    import_wire8 = require("@abloatai/transaction/wire");
+    init_connect();
     init_theme();
     init_target();
     init_remoteValidation();
@@ -8098,6 +8430,7 @@ var init_connect = __esm({
     --manual             Print the setup SQL instead of running it
     --yes                Set up without the confirmation (non-interactive)
     --show-sql           Show the exact statements before running them
+    --json               Emit stable result and step codes for automation
 
   apply registers with Ablo directly; the admin credential is used only on this
   machine and never persisted. Your app holds only ABLO_API_KEY.`;
@@ -284318,11 +284651,11 @@ async function migrate(argv) {
 }
 
 // src/index.ts
-init_connect();
+init_connect2();
 
 // src/commands.ts
 init_cjs_shims();
-init_connect();
+init_connect2();
 
 // src/docs.ts
 init_cjs_shims();
@@ -285039,7 +285372,7 @@ var import_path6 = require("path");
 var import_schema7 = require("@abloatai/transaction/schema");
 init_push();
 init_controlPlane();
-var import_wire8 = require("@abloatai/transaction/wire");
+var import_wire9 = require("@abloatai/transaction/wire");
 init_config();
 init_readiness();
 init_theme();
@@ -285214,7 +285547,7 @@ async function registerLocalSource(args) {
       reverseChannel: true,
       metadata: { managed_by: "ablo dev --local" }
     },
-    responseSchema: import_wire8.datasourceSummarySchema
+    responseSchema: import_wire9.datasourceSummarySchema
   });
 }
 function classifyKey(apiKey) {
@@ -288322,7 +288655,7 @@ var import_child_process2 = require("child_process");
 var import_picocolors23 = __toESM(require_picocolors(), 1);
 init_dist2();
 var import_errors21 = require("@abloatai/transaction/errors");
-var import_wire9 = require("@abloatai/transaction/wire");
+var import_wire10 = require("@abloatai/transaction/wire");
 init_config();
 init_projects();
 init_theme();
@@ -288517,7 +288850,7 @@ ${import_picocolors23.default.dim(url)}`, "Approve in your browser");
     }
     process.exit(1);
   }
-  const parsedProv = import_wire9.provisionKeyResponseSchema.safeParse(
+  const parsedProv = import_wire10.provisionKeyResponseSchema.safeParse(
     await provRes.json().catch(() => null)
   );
   if (!parsedProv.success) {
@@ -288867,7 +289200,7 @@ async function status(args = []) {
 // src/logs.ts
 init_cjs_shims();
 var import_errors22 = require("@abloatai/transaction/errors");
-var import_wire10 = require("@abloatai/transaction/wire");
+var import_wire11 = require("@abloatai/transaction/wire");
 var import_picocolors25 = __toESM(require_picocolors(), 1);
 init_config();
 init_theme();
@@ -288978,7 +289311,7 @@ async function logs(argv) {
     const json = await res.json();
     return {
       events: json.data ?? json.events ?? [],
-      cursor: json.next_cursor ?? (json.cursor != null ? (0, import_wire10.formatFeedCursor)({ log: json.cursor, claims: 0 }) : (0, import_wire10.formatFeedCursor)(import_wire10.FEED_CURSOR_START))
+      cursor: json.next_cursor ?? (json.cursor != null ? (0, import_wire11.formatFeedCursor)({ log: json.cursor, claims: 0 }) : (0, import_wire11.formatFeedCursor)(import_wire11.FEED_CURSOR_START))
     };
   }
   if (!args.json) {
@@ -289010,9 +289343,9 @@ async function logs(argv) {
     });
     if (!page) continue;
     for (const e2 of page.events) render2(e2, args.json);
-    const prev = (0, import_wire10.parseFeedCursor)(cursor);
-    const next = (0, import_wire10.parseFeedCursor)(page.cursor);
-    if (prev && next && (0, import_wire10.feedCursorAdvanced)(prev, next)) cursor = page.cursor;
+    const prev = (0, import_wire11.parseFeedCursor)(cursor);
+    const next = (0, import_wire11.parseFeedCursor)(page.cursor);
+    if (prev && next && (0, import_wire11.feedCursorAdvanced)(prev, next)) cursor = page.cursor;
   }
 }
 
@@ -289205,10 +289538,14 @@ var import_contract = require("@abloatai/transaction/claims/contract");
 var import_routes = require("@abloatai/transaction/claims/routes");
 init_controlPlane();
 init_config();
+function writeStderr(message2) {
+  process.stderr.write(`${message2}
+`);
+}
 function requireRuntimeKey() {
   const { key } = resolveRuntimeApiKey();
   if (!key) {
-    console.error(
+    writeStderr(
       import_picocolors27.default.red("  No runtime credential.") + import_picocolors27.default.dim(
         ` Run ${import_picocolors27.default.bold("npx ablo login")}, or set ${import_picocolors27.default.bold("ABLO_API_KEY")} to a runtime key.`
       )
@@ -289308,10 +289645,10 @@ function describeAcquired(model, id, granted) {
 async function holdWhile(model, id, flags, apiKey, command) {
   const granted = await acquireClaim(model, id, flags, apiKey);
   if (granted.status === "queued") {
-    if (!flags.json) console.error(describeAcquired(model, id, granted));
+    if (!flags.json) writeStderr(describeAcquired(model, id, granted));
     await waitForGrant(granted.id, flags.ttl, apiKey);
   }
-  if (!flags.json) console.error(`  ${import_picocolors27.default.green("\u2713")} Holding ${import_picocolors27.default.bold(`${model} ${id}`)}.`);
+  if (!flags.json) writeStderr(`  ${import_picocolors27.default.green("\u2713")} Holding ${import_picocolors27.default.bold(`${model} ${id}`)}.`);
   const everyMs = Math.max(1e3, Math.floor((0, import_contract.claimTtlMs)(flags.ttl) / 3));
   const timer2 = setInterval(() => {
     void beat(model, id, flags.ttl, apiKey).catch(() => {
@@ -289351,7 +289688,7 @@ async function holdWhile(model, id, flags, apiKey, command) {
     });
   });
   await giveBack();
-  if (!flags.json) console.error(`  ${import_picocolors27.default.dim("\xB7")} ${import_picocolors27.default.dim(`Released ${model} ${id}.`)}`);
+  if (!flags.json) writeStderr(`  ${import_picocolors27.default.dim("\xB7")} ${import_picocolors27.default.dim(`Released ${model} ${id}.`)}`);
   return code;
 }
 function renderList(rows) {
@@ -289400,7 +289737,7 @@ async function claims(argv = []) {
   }
   const [model, id] = rest;
   if (model === void 0 || id === void 0) {
-    console.error(`  ${import_picocolors27.default.red("\u2717")} Name the row: ${import_picocolors27.default.bold(`ablo claims ${verb} <model> <id>`)}.`);
+    writeStderr(`  ${import_picocolors27.default.red("\u2717")} Name the row: ${import_picocolors27.default.bold(`ablo claims ${verb} <model> <id>`)}.`);
     process.exitCode = 1;
     return;
   }
@@ -289427,8 +289764,9 @@ async function claims(argv = []) {
     else console.log(`  ${import_picocolors27.default.green("\u2713")} Still holding ${import_picocolors27.default.bold(`${model} ${id}`)}.`);
     return;
   }
-  console.error(`  ${import_picocolors27.default.red("\u2717")} Unknown: ${import_picocolors27.default.bold(`ablo claims ${verb}`)}.`);
-  console.error(usageFor("claims"));
+  writeStderr(`  ${import_picocolors27.default.red("\u2717")} Unknown: ${import_picocolors27.default.bold(`ablo claims ${verb}`)}.`);
+  const usage = usageFor("claims");
+  if (usage) writeStderr(usage);
   process.exitCode = 1;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/cli",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "The ablo command line: set up Ablo, connect your database, and push your schema from the terminal.",
   "license": "Apache-2.0",
   "homepage": "https://docs.abloatai.com/cli",
@@ -41,10 +41,10 @@
   },
   "dependencies": {
     "@sentry/node": "^10.18.0",
-    "@abloatai/transaction": "^0.60.0",
+    "@abloatai/transaction": "^0.61.0",
     "jiti": "^2.7.0",
     "zod": "^4.4.3",
-    "@abloatai/humans": "^0.60.0"
+    "@abloatai/humans": "^0.61.0"
   },
   "devDependencies": {
     "@ablo/product-analytics": "file:../product-analytics",