@abloatai/ablo 0.16.3 → 0.18.0

package/dist/cli.cjs

@@ -276700,7 +276700,7 @@ var Y2 = ({ indicator: t = "dots" } = {}) => {
 };
 
 // src/cli/index.ts
-var import_picocolors18 = __toESM(require_picocolors(), 1);
+var import_picocolors19 = __toESM(require_picocolors(), 1);
 var import_fs12 = require("fs");
 var import_path7 = require("path");
 var import_child_process2 = require("child_process");
@@ -277009,6 +277009,18 @@ var ERROR_CODES = {
   invalid_schema: wire("validation", 400, false, "The submitted schema could not be parsed."),
   incompatible_change: wire("conflict", 409, false, "The schema change is incompatible with the current schema.")
 };
+function errorCodeSpec(code) {
+  return ERROR_CODES[code];
+}
+function classifyRecovery(code) {
+  const spec = errorCodeSpec(code);
+  if (!spec) return "none";
+  if (spec.recovery) return spec.recovery;
+  if (spec.retryable) return "transient";
+  if (spec.httpStatus === 403) return "permission";
+  if (spec.category === "auth") return "auth_blocked";
+  return "none";
+}
 
 // src/coordination/schema.ts
 init_cjs_shims();
@@ -277331,6 +277343,20 @@ var AbloError = class extends Error {
       ...this.details ?? {}
     };
   }
+  /**
+   * A single, leak-proof line for logs and `String(err)` / template
+   * interpolation: `AbloValidationError [code]: message (see docs) [request_id: …]`.
+   *
+   * Deliberately does NOT dump `details`, `cause`, or the stack — the thing that
+   * makes `console.error(richError)` an unreadable wall of text. The structured
+   * payload stays available via {@link toJSON}; this is the human one-liner.
+   */
+  toString() {
+    const code = this.code ? ` [${this.code}]` : "";
+    const docs = this.docUrl ? ` (see ${this.docUrl})` : "";
+    const req = this.requestId ? ` [request_id: ${this.requestId}]` : "";
+    return `${this.name}${code}: ${this.message}${docs}${req}`;
+  }
 };
 function docUrlForCode(code) {
   return `https://docs.abloatai.com/errors#${code}`;
@@ -277378,7 +277404,7 @@ var ErrorBodyShapeSchema = import_zod4.z.object({
 }).passthrough();
 
 // src/cli/migrate.ts
-var import_picocolors4 = __toESM(require_picocolors(), 1);
+var import_picocolors3 = __toESM(require_picocolors(), 1);
 var import_fs5 = require("fs");
 
 // node_modules/postgres/src/index.js
@@ -278098,7 +278124,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
   async function cancel({ pid, secret }, resolve6, reject) {
     try {
       cancelMessage = bytes_default().i32(16).i32(80877102).i32(pid).i32(secret).end(16);
-      await connect();
+      await connect2();
       socket.once("error", reject);
       socket.once("close", resolve6);
     } catch (error2) {
@@ -278231,7 +278257,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
       incomings = null;
     }
   }
-  async function connect() {
+  async function connect2() {
     terminated = false;
     backendParameters = {};
     socket || (socket = await createSocket());
@@ -278250,7 +278276,7 @@ function Connection(options, queues = {}, { onopen = noop, onend = noop, onclose
     hostIndex = (hostIndex + 1) % port.length;
   }
   function reconnect() {
-    setTimeout(connect, closedTime ? Math.max(0, closedTime + delay - import_perf_hooks.performance.now()) : 0);
+    setTimeout(connect2, closedTime ? Math.max(0, closedTime + delay - import_perf_hooks.performance.now()) : 0);
   }
   function connected() {
     try {
@@ -279252,7 +279278,7 @@ function Postgres(a, b4) {
     const c = open.length ? open.shift() : await new Promise((resolve6, reject) => {
       const query = { reserve: resolve6, reject };
       queries.push(query);
-      closed.length && connect(closed.shift(), query);
+      closed.length && connect2(closed.shift(), query);
     });
     move(c, reserved);
     c.reserved = () => queue.length ? c.execute(queue.shift()) : move(c, reserved);
@@ -279339,7 +279365,7 @@ function Postgres(a, b4) {
     if (open.length)
       return go(open.shift(), query);
     if (closed.length)
-      return connect(closed.shift(), query);
+      return connect2(closed.shift(), query);
     busy.length ? go(busy.shift(), query) : queries.push(query);
   }
   function go(c, query) {
@@ -279372,7 +279398,7 @@ function Postgres(a, b4) {
       queries.shift().reject(Errors.connection("CONNECTION_DESTROYED", options));
     resolve6();
   }
-  function connect(c, query) {
+  function connect2(c, query) {
     move(c, connecting);
     c.connect(query);
     return c;
@@ -279397,7 +279423,7 @@ function Postgres(a, b4) {
     c.reserved = null;
     c.onclose && (c.onclose(e2), c.onclose = null);
     options.onclose && options.onclose(c.id);
-    queries.length && connect(c, queries.shift());
+    queries.length && connect2(c, queries.shift());
   }
 }
 function parseOptions(a, b4) {
@@ -279517,158 +279543,8 @@ function osUsername() {
 
 // src/cli/dbRole.ts
 init_cjs_shims();
-var import_crypto2 = require("crypto");
-var import_picocolors2 = __toESM(require_picocolors(), 1);
 var import_fs2 = require("fs");
 var import_path = require("path");
-var DEFAULT_SCOPED_ROLE = "ablo_app";
-async function detectRoleSafety(sql) {
-  const rows = await sql`SELECT rolname, rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user`;
-  const row = rows[0];
-  if (!row) return { role: "unknown", superuser: false, bypassRls: false, unsafe: false };
-  return {
-    role: row.rolname,
-    superuser: row.rolsuper,
-    bypassRls: row.rolbypassrls,
-    unsafe: row.rolsuper || row.rolbypassrls
-  };
-}
-function generateRolePassword() {
-  return (0, import_crypto2.randomBytes)(24).toString("base64url");
-}
-function scramSha256Verifier(password, iterations = 4096) {
-  const salt = (0, import_crypto2.randomBytes)(16);
-  const saltedPassword = (0, import_crypto2.pbkdf2Sync)(password, salt, iterations, 32, "sha256");
-  const clientKey = (0, import_crypto2.createHmac)("sha256", saltedPassword).update("Client Key").digest();
-  const storedKey = (0, import_crypto2.createHash)("sha256").update(clientKey).digest();
-  const serverKey = (0, import_crypto2.createHmac)("sha256", saltedPassword).update("Server Key").digest();
-  return `SCRAM-SHA-256$${iterations}:${salt.toString("base64")}$${storedKey.toString("base64")}:${serverKey.toString("base64")}`;
-}
-function scopedRoleStatements(input) {
-  const role = input.role ?? DEFAULT_SCOPED_ROLE;
-  const q2 = (id) => `"${id.replace(/"/g, '""')}"`;
-  const pw = (input.passwordMode ?? "scram-verifier") === "scram-verifier" ? scramSha256Verifier(input.password) : input.password.replace(/'/g, "''");
-  return [
-    `DO $$ BEGIN
-  CREATE ROLE ${q2(role)} LOGIN PASSWORD '${pw}'
-    NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE;
-EXCEPTION WHEN duplicate_object THEN
-  -- Rerun: rotate ONLY the password. Re-asserting attributes here trips
-  -- managed-Postgres permission walls (Neon: "permission denied to alter
-  -- role" for attribute changes by non-superusers); the attributes were set
-  -- at creation, and the server-side probe still audits the live role.
-  ALTER ROLE ${q2(role)} WITH LOGIN PASSWORD '${pw}';
-END $$;`,
-    `GRANT CREATE, CONNECT ON DATABASE ${q2(input.database)} TO ${q2(role)};`,
-    `GRANT CREATE, USAGE ON SCHEMA public TO ${q2(role)};`
-  ];
-}
-function rewriteDatabaseUrl(ownerUrl, role, password) {
-  const url = new URL(ownerUrl);
-  url.username = role;
-  url.password = password;
-  return url.toString();
-}
-async function createScopedRole(ownerUrl, options) {
-  const role = options?.role ?? DEFAULT_SCOPED_ROLE;
-  const password = generateRolePassword();
-  const database = new URL(ownerUrl).pathname.replace(/^\//, "") || "postgres";
-  const sql = src_default(ownerUrl, { max: 1, prepare: false, onnotice: () => {
-  } });
-  try {
-    try {
-      for (const statement of scopedRoleStatements({ database, role, password })) {
-        await sql.unsafe(statement);
-      }
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (!/plaintext password/i.test(message)) throw err;
-      for (const statement of scopedRoleStatements({ database, role, password, passwordMode: "plaintext" })) {
-        await sql.unsafe(statement);
-      }
-    }
-  } finally {
-    await sql.end({ timeout: 5 });
-  }
-  return { role, databaseUrl: rewriteDatabaseUrl(ownerUrl, role, password) };
-}
-async function ensureScopedRoleInteractive(dbUrl) {
-  let safety;
-  try {
-    const sql = src_default(dbUrl, { max: 1, prepare: false, onnotice: () => {
-    } });
-    try {
-      safety = await detectRoleSafety(sql);
-    } finally {
-      await sql.end({ timeout: 5 });
-    }
-  } catch {
-    return dbUrl;
-  }
-  if (!safety.unsafe) return dbUrl;
-  const why = safety.superuser ? "a superuser" : "BYPASSRLS";
-  console.log(
-    `
-  ${import_picocolors2.default.yellow("!")} DATABASE_URL connects as ${import_picocolors2.default.bold(safety.role)} \u2014 ${why}, so row-level security can't be enforced.
-    Ablo's server will refuse this connection (${import_picocolors2.default.bold("database_role_cannot_enforce_rls")}).`
-  );
-  if (!process.stdout.isTTY) {
-    console.log(
-      import_picocolors2.default.dim(
-        `    Create a scoped role and update DATABASE_URL \u2014 run \`npx ablo migrate\` interactively
-    to do it automatically, or see https://docs.abloatai.com/quickstart#scoped-role`
-      )
-    );
-    return dbUrl;
-  }
-  const proceed = await ye({
-    message: `Create a scoped role ${DEFAULT_SCOPED_ROLE} (NOSUPERUSER, NOBYPASSRLS) and update DATABASE_URL?`,
-    initialValue: true
-  });
-  if (pD(proceed) || !proceed) {
-    console.log(import_picocolors2.default.dim("    Skipped \u2014 see https://docs.abloatai.com/quickstart#scoped-role for the manual recipe."));
-    return dbUrl;
-  }
-  const { role, databaseUrl } = await createScopedRole(dbUrl);
-  const where = persistDatabaseUrl(databaseUrl);
-  console.log(
-    `  ${import_picocolors2.default.green("\u2713")} Created role ${import_picocolors2.default.bold(role)} and updated ${import_picocolors2.default.bold("DATABASE_URL")} in ${import_picocolors2.default.bold(where)}.
-` + import_picocolors2.default.dim(`    The owner credential never left this machine; the new password was written, not printed.`)
-  );
-  return databaseUrl;
-}
-function persistDatabaseUrl(databaseUrl, cwd = process.cwd()) {
-  const line = `DATABASE_URL=${databaseUrl}`;
-  for (const name of [".env.local", ".env"]) {
-    const path = (0, import_path.resolve)(cwd, name);
-    if (!(0, import_fs2.existsSync)(path)) continue;
-    const content = (0, import_fs2.readFileSync)(path, "utf8");
-    if (/^DATABASE_URL=/m.test(content)) {
-      (0, import_fs2.writeFileSync)(path, content.replace(/^DATABASE_URL=.*$/m, line));
-      return name;
-    }
-  }
-  const envLocal = (0, import_path.resolve)(cwd, ".env.local");
-  if ((0, import_fs2.existsSync)(envLocal)) {
-    const content = (0, import_fs2.readFileSync)(envLocal, "utf8");
-    (0, import_fs2.appendFileSync)(envLocal, `${content.endsWith("\n") || content.length === 0 ? "" : "\n"}${line}
-`);
-  } else {
-    (0, import_fs2.writeFileSync)(envLocal, `${line}
-`, { mode: 384 });
-  }
-  const gitignorePath = (0, import_path.resolve)(cwd, ".gitignore");
-  const gitignore = (0, import_fs2.existsSync)(gitignorePath) ? (0, import_fs2.readFileSync)(gitignorePath, "utf8") : "";
-  if (!/^(\.env\.local|\.env\*|\.env\.\*|\.env.*)$/m.test(gitignore)) {
-    (0, import_fs2.writeFileSync)(
-      gitignorePath,
-      `${gitignore.endsWith("\n") || gitignore.length === 0 ? gitignore : `${gitignore}
-`}.env.local
-`
-    );
-  }
-  return ".env.local";
-}
 function readProjectDatabaseUrl(cwd = process.cwd()) {
   const fromEnv = process.env.DATABASE_URL ?? process.env.ABLO_DATABASE_URL;
   if (fromEnv) return fromEnv;
@@ -279680,6 +279556,16 @@ function readProjectDatabaseUrl(cwd = process.cwd()) {
   }
   return null;
 }
+function readProjectApiKey(cwd = process.cwd()) {
+  if (process.env.ABLO_API_KEY) return { key: process.env.ABLO_API_KEY, source: "env" };
+  for (const name of [".env.local", ".env"]) {
+    const path = (0, import_path.resolve)(cwd, name);
+    if (!(0, import_fs2.existsSync)(path)) continue;
+    const match = (0, import_fs2.readFileSync)(path, "utf8").match(/^ABLO_API_KEY=(.+)$/m);
+    if (match?.[1]) return { key: match[1].trim().replace(/^["']|["']$/g, ""), source: name };
+  }
+  return null;
+}
 
 // src/cli/migrate.ts
 var import_schema3 = require("@abloatai/ablo/schema");
@@ -279687,7 +279573,7 @@ var import_source = require("@abloatai/ablo/source");
 
 // src/cli/push.ts
 init_cjs_shims();
-var import_picocolors3 = __toESM(require_picocolors(), 1);
+var import_picocolors2 = __toESM(require_picocolors(), 1);
 
 // src/auth/credentialPolicy.ts
 init_cjs_shims();
@@ -279929,7 +279815,16 @@ var DEFAULT_URL = "https://api.abloatai.com";
 function fmtSignal(s) {
   const sig = s;
   const where = sig.field ? `${sig.model}.${sig.field}` : sig.model;
-  return `    \u2022 ${import_picocolors3.default.bold(where ?? "?")} \u2014 ${sig.detail ?? ""}`;
+  let line = `    \u2022 ${import_picocolors2.default.bold(where ?? "?")} \u2014 ${sig.detail ?? ""}`;
+  if (sig.shadowed) {
+    const env = sig.shadowed.environment ?? "production";
+    const ver = sig.shadowed.version != null ? `v${sig.shadowed.version}` : "active";
+    const when = sig.shadowed.pushedAt ? new Date(sig.shadowed.pushedAt).toISOString().slice(0, 10) : "unknown date";
+    const by = sig.shadowed.pushedBy ? ` by ${sig.shadowed.pushedBy}` : "";
+    line += `
+      ${import_picocolors2.default.dim(`\u21B3 baseline: ${env} ${ver}, pushed ${when}${by}`)}`;
+  }
+  return line;
 }
 async function pushSchema(schema, args) {
   const schemaJson = JSON.parse((0, import_schema2.serializeSchema)(schema));
@@ -280010,7 +279905,7 @@ async function loadSchema(schemaPath, exportName) {
   const abs = (0, import_path3.resolve)(process.cwd(), schemaPath);
   if (!(0, import_fs4.existsSync)(abs)) {
     throw new AbloValidationError(
-      `schema not found at ${import_picocolors3.default.bold(schemaPath)}. Run ${import_picocolors3.default.bold("npx ablo init")} or pass ${import_picocolors3.default.bold("--schema <path>")}.`,
+      `schema not found at ${import_picocolors2.default.bold(schemaPath)}. Run ${import_picocolors2.default.bold("npx ablo init")} or pass ${import_picocolors2.default.bold("--schema <path>")}.`,
       { code: "cli_invalid_arguments" }
     );
   }
@@ -280021,25 +279916,50 @@ async function loadSchema(schemaPath, exportName) {
   const schema = mod[exportName] ?? nested?.[exportName];
   if (!schema || typeof schema !== "object" || !("models" in schema)) {
     throw new AbloValidationError(
-      `${import_picocolors3.default.bold(schemaPath)} has no \`${exportName}\` export that looks like a Schema. Did you \`export const ${exportName} = defineSchema({ ... })\`?`,
+      `${import_picocolors2.default.bold(schemaPath)} has no \`${exportName}\` export that looks like a Schema. Did you \`export const ${exportName} = defineSchema({ ... })\`?`,
       { code: "cli_invalid_arguments" }
     );
   }
   return schema;
 }
+function maskKey(key) {
+  return key ? `${key.slice(0, 12)}\u2026` : "(none)";
+}
+function describeKeySource(source) {
+  switch (source) {
+    case "env":
+      return "ABLO_API_KEY (environment)";
+    case ".env.local":
+      return ".env.local";
+    case ".env":
+      return ".env";
+    case "login":
+      return "`ablo login` (stored sandbox config)";
+  }
+}
 async function push(argv) {
   let args;
   try {
     args = parsePushArgs(argv);
   } catch (err) {
-    console.error(import_picocolors3.default.red(`  ${err instanceof Error ? err.message : String(err)}`));
+    console.error(import_picocolors2.default.red(`  ${err instanceof Error ? err.message : String(err)}`));
     process.exit(1);
   }
-  if (!args.apiKey) args.apiKey = resolveApiKey();
+  let keySource = "env";
+  if (!args.apiKey) {
+    const fromProject = readProjectApiKey();
+    if (fromProject) {
+      args.apiKey = fromProject.key;
+      keySource = fromProject.source;
+    } else {
+      args.apiKey = resolveApiKey();
+      keySource = "login";
+    }
+  }
   if (!args.apiKey) {
     console.error(
-      import_picocolors3.default.red(`  No API key.`) + import_picocolors3.default.dim(
-        ` Run ${import_picocolors3.default.bold("npx ablo login")} for the sandbox dev loop \u2014 or set ${import_picocolors3.default.bold("ABLO_API_KEY")} (${import_picocolors3.default.bold("sk_test_")} = sandbox; ${import_picocolors3.default.bold("sk_live_")} = deliberate production deploy). Mode is currently '${getMode()}'.`
+      import_picocolors2.default.red(`  No API key.`) + import_picocolors2.default.dim(
+        ` Run ${import_picocolors2.default.bold("npx ablo login")} for the sandbox dev loop \u2014 or set ${import_picocolors2.default.bold("ABLO_API_KEY")} (${import_picocolors2.default.bold("sk_test_")} = sandbox; ${import_picocolors2.default.bold("sk_live_")} = deliberate production deploy). Mode is currently '${getMode()}'.`
       )
     );
     process.exit(1);
@@ -280047,17 +279967,17 @@ async function push(argv) {
   const schema = await loadSchema(args.schemaPath, args.exportName);
   const hash = (0, import_schema2.schemaHash)(schema);
   console.log(
-    `  Pushing ${import_picocolors3.default.bold(args.schemaPath)} ${import_picocolors3.default.dim(`(${Object.keys(schema.models).length} models, hash ${hash})`)} \u2192 ${import_picocolors3.default.dim(args.url)}`
+    `  Pushing ${import_picocolors2.default.bold(args.schemaPath)} ${import_picocolors2.default.dim(`(${Object.keys(schema.models).length} models, hash ${hash})`)} \u2192 ${import_picocolors2.default.dim(args.url)}`
   );
   const { ok: resOk, status: status2, body, bodyText } = await pushSchema(schema, args);
   if (resOk) {
     if (body.unchanged) {
-      console.log(`  ${import_picocolors3.default.dim("\u25CB")} No changes \u2014 schema already active (v${body.version}).`);
+      console.log(`  ${import_picocolors2.default.dim("\u25CB")} No changes \u2014 schema already active (v${body.version}).`);
     } else {
-      console.log(`  ${import_picocolors3.default.green("\u2713")} Activated ${import_picocolors3.default.bold(`v${body.version}`)} ${import_picocolors3.default.dim(`(hash ${body.hash})`)}`);
+      console.log(`  ${import_picocolors2.default.green("\u2713")} Activated ${import_picocolors2.default.bold(`v${body.version}`)} ${import_picocolors2.default.dim(`(hash ${body.hash})`)}`);
       if (Array.isArray(body.warnings) && body.warnings.length > 0) {
-        console.log(import_picocolors3.default.yellow(`  Applied ${body.warnings.length} destructive change(s):`));
-        for (const w2 of body.warnings) console.log(import_picocolors3.default.yellow(fmtSignal(w2)));
+        console.log(import_picocolors2.default.yellow(`  Applied ${body.warnings.length} destructive change(s):`));
+        for (const w2 of body.warnings) console.log(import_picocolors2.default.yellow(fmtSignal(w2)));
       }
     }
     return;
@@ -280065,27 +279985,63 @@ async function push(argv) {
   if (status2 === 409) {
     const unexecutable = Array.isArray(body.unexecutable) ? body.unexecutable : [];
     const warnings = Array.isArray(body.warnings) ? body.warnings : [];
-    console.error(import_picocolors3.default.red("  Incompatible change \u2014 this push is not safe to apply as-is."));
+    console.error(import_picocolors2.default.red("  Incompatible change \u2014 this push is not safe to apply as-is."));
     if (unexecutable.length > 0) {
-      console.error(import_picocolors3.default.red(`  Unexecutable (would fail on existing rows):`));
-      for (const u2 of unexecutable) console.error(import_picocolors3.default.red(fmtSignal(u2)));
+      console.error(import_picocolors2.default.red(`  Unexecutable (would fail on existing rows):`));
+      for (const u2 of unexecutable) console.error(import_picocolors2.default.red(fmtSignal(u2)));
     }
     if (warnings.length > 0) {
-      console.error(import_picocolors3.default.yellow(`  Destructive (data loss):`));
-      for (const w2 of warnings) console.error(import_picocolors3.default.yellow(fmtSignal(w2)));
+      console.error(import_picocolors2.default.yellow(`  Destructive (data loss):`));
+      for (const w2 of warnings) console.error(import_picocolors2.default.yellow(fmtSignal(w2)));
+    }
+    const hasShadowed = [...unexecutable, ...warnings].some(
+      (s) => s.shadowed != null
+    );
+    if (hasShadowed) {
+      console.error(
+        import_picocolors2.default.dim(
+          "  These models exist in the baseline above but not in your push. Sandbox readers fall"
+        )
+      );
+      console.error(
+        import_picocolors2.default.dim(
+          "  back to the production schema until you push your own, so applying this drops them."
+        )
+      );
     }
-    console.error(import_picocolors3.default.dim(`  Re-push with ${import_picocolors3.default.bold("--force")} to override, or use ${import_picocolors3.default.bold("--rename old:new")} if you renamed a model.`));
+    console.error(import_picocolors2.default.dim(`  Re-push with ${import_picocolors2.default.bold("--force")} to override, or use ${import_picocolors2.default.bold("--rename old:new")} if you renamed a model.`));
   } else if (status2 === 403) {
-    console.error(import_picocolors3.default.red(`  Forbidden: ${body.message ?? body.reason ?? "key lacks schema:push scope"}`));
-    if (args.apiKey != null && classifyCredentialKind(args.apiKey) === "restricted") {
+    const code = body.code ?? body.reason;
+    const serverMsg = body.message ?? body.reason;
+    console.error(import_picocolors2.default.red(`  Forbidden${code ? ` [${code}]` : ""}: ${serverMsg ?? "permission denied"}`));
+    console.error(import_picocolors2.default.dim(`  Push used ${import_picocolors2.default.bold(maskKey(args.apiKey))} from ${describeKeySource(keySource)}.`));
+    if (code === "database_role_cannot_enforce_rls") {
+      console.error(
+        import_picocolors2.default.dim(
+          `  Your database role bypasses row-level security. Run ${import_picocolors2.default.bold("npx ablo migrate")} to create a scoped (NOBYPASSRLS) role and repoint DATABASE_URL, then re-push.`
+        )
+      );
+    } else if (code === "database_tables_unforced_rls") {
+      console.error(
+        import_picocolors2.default.dim(
+          `  One or more synced tables don't have FORCE ROW LEVEL SECURITY. Run ${import_picocolors2.default.bold("npx ablo migrate")} to (re)apply the tenant policies, then re-push.`
+        )
+      );
+    } else if (args.apiKey != null && classifyCredentialKind(args.apiKey) === "restricted") {
+      console.error(
+        import_picocolors2.default.dim(
+          `  Schema pushes need a SECRET key: ${import_picocolors2.default.bold("sk_test_")} (sandbox dev loop) or a dashboard ${import_picocolors2.default.bold("sk_live_")} (production deploy: ${import_picocolors2.default.bold("ABLO_API_KEY=sk_live_\u2026 npx ablo push")}).`
+        )
+      );
+    } else {
       console.error(
-        import_picocolors3.default.dim(
-          `  Schema pushes need a SECRET key: ${import_picocolors3.default.bold("sk_test_")} (sandbox dev loop) or a dashboard ${import_picocolors3.default.bold("sk_live_")} (production deploy: ${import_picocolors3.default.bold("ABLO_API_KEY=sk_live_\u2026 npx ablo push")}).`
+        import_picocolors2.default.dim(
+          `  This key isn't authorized to push schema (needs ${import_picocolors2.default.bold("schema:push")}). ` + (keySource === "login" ? `It's your stored ${import_picocolors2.default.bold("ablo login")} sandbox key \u2014 a key in ${import_picocolors2.default.bold(".env.local")} or ${import_picocolors2.default.bold("ABLO_API_KEY")} takes precedence, so put a schema:push key there (sandbox ${import_picocolors2.default.bold("sk_test_")} or production ${import_picocolors2.default.bold("sk_live_")}) and re-push. ` : `Use a schema:push key \u2014 a sandbox ${import_picocolors2.default.bold("sk_test_")} or production ${import_picocolors2.default.bold("sk_live_")}. `) + `Manage keys at https://abloatai.com`
         )
       );
     }
   } else {
-    console.error(import_picocolors3.default.red(`  Push failed (${status2}): ${body.message ?? body.reason ?? bodyText}`));
+    console.error(import_picocolors2.default.red(`  Push failed (${status2}): ${body.message ?? body.reason ?? bodyText}`));
   }
   process.exit(1);
 }
@@ -280093,6 +280049,10 @@ async function push(argv) {
 // src/cli/migrate.ts
 var MIGRATE_USAGE = `  ablo migrate \u2014 provision your schema's tables in your own Postgres (DATABASE_URL)
 
+  To connect a real database, run \`ablo connect\` \u2014 Ablo reads your WAL via logical
+  replication, the one way. \`migrate\` is the optional escape hatch for provisioning
+  tables when you don't already have them.
+
   Usage:
     npx ablo migrate                      Create the synced-model tables (with row-level security)
     npx ablo migrate --dry-run            Print the SQL without executing it
@@ -280141,8 +280101,8 @@ function planFor(schema, targetSchema = "public") {
 }
 var log = {
   info: (msg, fields) => console.log(`[migrate] ${msg}`, fields),
-  warn: (msg, fields) => console.warn(import_picocolors4.default.yellow(`[migrate] ${msg}`), fields),
-  error: (msg, fields) => console.error(import_picocolors4.default.red(`[migrate] ${msg}`), fields)
+  warn: (msg, fields) => console.warn(import_picocolors3.default.yellow(`[migrate] ${msg}`), fields),
+  error: (msg, fields) => console.error(import_picocolors3.default.red(`[migrate] ${msg}`), fields)
 };
 var PG_LOCK_NOT_AVAILABLE = "55P03";
 var LOCK_TIMEOUT = process.env.ABLO_SCHEMA_LOCK_TIMEOUT ?? process.env.ABLO_DDL_LOCK_TIMEOUT ?? "5s";
@@ -280217,7 +280177,7 @@ async function migrate(argv) {
   try {
     args = parseMigrateArgs(argv);
   } catch (err) {
-    console.error(import_picocolors4.default.red(`  ${err instanceof Error ? err.message : String(err)}`));
+    console.error(import_picocolors3.default.red(`  ${err instanceof Error ? err.message : String(err)}`));
     process.exit(1);
   }
   const schema = await loadSchema(args.schemaPath, args.exportName);
@@ -280228,31 +280188,290 @@ async function migrate(argv) {
   ].join("\n");
   const totalStatements = plan.statements.length + plan.concurrent.length;
   console.log(
-    `  ${import_picocolors4.default.dim("Schema")} ${import_picocolors4.default.bold(args.schemaPath)} \u2192 ${import_picocolors4.default.dim(`${Object.keys(schema.models).length} models, ${totalStatements} statements`)}`
+    `  ${import_picocolors3.default.dim("Schema")} ${import_picocolors3.default.bold(args.schemaPath)} \u2192 ${import_picocolors3.default.dim(`${Object.keys(schema.models).length} models, ${totalStatements} statements`)}`
   );
   if (args.outputFile) {
     (0, import_fs5.writeFileSync)(args.outputFile, sql + "\n");
-    console.log(`  ${import_picocolors4.default.green("\u2713")} SQL written to ${import_picocolors4.default.bold(args.outputFile)}`);
+    console.log(`  ${import_picocolors3.default.green("\u2713")} SQL written to ${import_picocolors3.default.bold(args.outputFile)}`);
     return;
   }
   if (args.dryRun) {
     console.log("\n" + sql + "\n");
     return;
   }
-  const dbUrl = process.env.DATABASE_URL ?? process.env.ABLO_DATABASE_URL;
+  const dbUrl = readProjectDatabaseUrl();
   if (!dbUrl) {
-    console.error(import_picocolors4.default.red("  Set DATABASE_URL (or ABLO_DATABASE_URL) to apply, or use --dry-run to preview."));
+    console.error(
+      import_picocolors3.default.red(
+        "  No DATABASE_URL found (checked process env, .env.local, .env). Set it to apply, or use --dry-run to preview."
+      )
+    );
     process.exit(1);
   }
-  const effectiveUrl = await ensureScopedRoleInteractive(dbUrl);
   try {
-    await applyStatements(effectiveUrl, args.targetSchema, plan.statements, plan.concurrent);
-    console.log(`  ${import_picocolors4.default.green("\u2713")} Migration complete`);
+    await applyStatements(dbUrl, args.targetSchema, plan.statements, plan.concurrent);
+    console.log(`  ${import_picocolors3.default.green("\u2713")} Migration complete`);
   } catch {
     process.exit(1);
   }
 }
 
+// src/cli/connect.ts
+init_cjs_shims();
+var import_picocolors4 = __toESM(require_picocolors(), 1);
+
+// src/cli/theme.ts
+init_cjs_shims();
+var RESET = "\x1B[0m";
+var PAPER_BG = "\x1B[48;2;250;250;250m";
+var BLACK_FG = "\x1B[38;2;0;0;0m";
+function colorEnabled() {
+  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+}
+function brand(label = "ablo") {
+  if (!colorEnabled()) return label;
+  return `${PAPER_BG}${BLACK_FG} ${label} ${RESET}`;
+}
+
+// src/cli/connect.ts
+var ABLO_PUBLICATION = "ablo_publication";
+var ABLO_REPLICATION_ROLE = "ablo_replicator";
+function parseConnectArgs(argv) {
+  let check2 = false;
+  let tables = [];
+  let role = ABLO_REPLICATION_ROLE;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--check":
+        check2 = true;
+        break;
+      case "--tables": {
+        const value = argv[++i] ?? "";
+        tables = value.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+        break;
+      }
+      case "--role":
+        role = argv[++i] ?? role;
+        break;
+      default:
+        throw new AbloValidationError(`unknown flag: ${arg}`, { code: "cli_invalid_arguments" });
+    }
+  }
+  return { check: check2, tables, role };
+}
+function quoteIdent(id) {
+  return `"${id.replace(/"/g, '""')}"`;
+}
+function connectSetupSql(input) {
+  const role = input.role && input.role.length > 0 ? input.role : ABLO_REPLICATION_ROLE;
+  const tables = input.tables ?? [];
+  const publicationTarget = tables.length > 0 ? `FOR TABLE ${tables.map(quoteIdent).join(", ")}` : "FOR ALL TABLES";
+  return [
+    // 1. Turn on logical decoding. Requires a restart (it's not reloadable).
+    `ALTER SYSTEM SET wal_level = 'logical';`,
+    // 2. Publish the tables Ablo should read.
+    `CREATE PUBLICATION ${quoteIdent(ABLO_PUBLICATION)} ${publicationTarget};`,
+    // 3. A least-privilege role: it can stream replication and SELECT, nothing more.
+    `CREATE ROLE ${quoteIdent(role)} WITH REPLICATION LOGIN PASSWORD '<password>';`,
+    `GRANT SELECT ON ALL TABLES IN SCHEMA public TO ${quoteIdent(role)};`,
+    // Future tables get SELECT automatically, so the publication doesn't outgrow the grant.
+    `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO ${quoteIdent(role)};`
+  ];
+}
+function printConnectRecipe(args) {
+  const sql = connectSetupSql({ tables: args.tables, role: args.role });
+  console.log(`
+  ${brand("ablo")} ${import_picocolors4.default.dim("connect")}  ${import_picocolors4.default.dim("logical replication \u2014 the one way to connect a real database")}
+`);
+  console.log(
+    `  Ablo READS your write-ahead log (WAL) and ${import_picocolors4.default.bold("never")} runs DDL, owns, or migrates your
+  schema. Your app keeps writing through your own backend \u2014 Ablo only tails the changes.
+  Run this once against your Postgres ${import_picocolors4.default.dim("(as a superuser / the DB owner)")}:
+`
+  );
+  console.log(`  ${import_picocolors4.default.bold("1.")} Enable logical decoding ${import_picocolors4.default.dim("(then RESTART Postgres \u2014 wal_level is not reloadable)")}`);
+  console.log(`       ${import_picocolors4.default.cyan(sql[0])}`);
+  console.log(
+    import_picocolors4.default.dim(
+      `       On Amazon RDS / Aurora you can't ALTER SYSTEM: set ${import_picocolors4.default.bold("rds.logical_replication = 1")} in the
+       instance's parameter group instead, then reboot.`
+    )
+  );
+  console.log(`
+  ${import_picocolors4.default.bold("2.")} Publish the tables Ablo should read`);
+  console.log(`       ${import_picocolors4.default.cyan(sql[1])}`);
+  if (args.tables.length === 0) {
+    console.log(import_picocolors4.default.dim(`       (Scope it with ${import_picocolors4.default.bold("ablo connect --tables a,b,c")} to publish a subset.)`));
+  }
+  console.log(`
+  ${import_picocolors4.default.bold("3.")} Create a least-privilege replication role ${import_picocolors4.default.dim("(pick your own password)")}`);
+  console.log(`       ${import_picocolors4.default.cyan(sql[2])}`);
+  console.log(`       ${import_picocolors4.default.cyan(sql[3])}`);
+  console.log(`       ${import_picocolors4.default.cyan(sql[4])}`);
+  console.log(
+    import_picocolors4.default.dim(
+      `       On Amazon RDS, the REPLICATION attribute is granted, not set directly:
+       ${import_picocolors4.default.bold(`GRANT rds_replication TO ${quoteIdent(args.role)};`)}`
+    )
+  );
+  console.log(
+    `
+  ${import_picocolors4.default.bold("4.")} Put the role's connection string in ${import_picocolors4.default.bold("DATABASE_URL")}, then verify:
+       ${import_picocolors4.default.cyan("npx ablo connect --check")}
+`
+  );
+  console.log(
+    import_picocolors4.default.dim(
+      `  Reminder: Ablo never writes to your database on this path. Provisioning tables with
+  ${import_picocolors4.default.bold("ablo migrate")} is a separate, optional escape hatch \u2014 connecting a real database is this.`
+    )
+  );
+  console.log();
+}
+function printCheckItem(item) {
+  if (item.ok) {
+    console.log(`  ${import_picocolors4.default.green("\u2713")} ${item.label}`);
+  } else {
+    console.log(`  ${import_picocolors4.default.red("\u2717")} ${item.label}`);
+    if (item.fix) {
+      for (const line of item.fix.split("\n")) console.log(`      ${import_picocolors4.default.red("\u2022")} ${line}`);
+    }
+  }
+}
+async function probeReadiness(sql, opts = {}) {
+  const publication = opts.publication ?? ABLO_PUBLICATION;
+  const items = [];
+  const walRows = await sql.unsafe(`SHOW wal_level`);
+  const walLevel = walRows[0]?.setting ?? "unknown";
+  items.push(
+    walLevel === "logical" ? { ok: true, label: `wal_level is ${import_picocolors4.default.bold("logical")}` } : {
+      ok: false,
+      label: `wal_level is ${import_picocolors4.default.bold(walLevel)} (need ${import_picocolors4.default.bold("logical")})`,
+      fix: `ALTER SYSTEM SET wal_level = 'logical'; then RESTART Postgres.
+On RDS/Aurora set rds.logical_replication = 1 in the parameter group, then reboot.`
+    }
+  );
+  const pubRows = await sql.unsafe(
+    `SELECT puballtables FROM pg_publication WHERE pubname = $1`,
+    [publication]
+  );
+  items.push(
+    pubRows.length > 0 ? {
+      ok: true,
+      label: `publication ${import_picocolors4.default.bold(publication)} exists ${import_picocolors4.default.dim(pubRows[0].puballtables ? "(all tables)" : "(table subset)")}`
+    } : {
+      ok: false,
+      label: `publication ${import_picocolors4.default.bold(publication)} not found`,
+      fix: `CREATE PUBLICATION ${quoteIdent(publication)} FOR ALL TABLES;`
+    }
+  );
+  const roleRows = await sql.unsafe(
+    `SELECT rolreplication, rolsuper FROM pg_roles WHERE rolname = current_user`
+  );
+  const role = roleRows[0];
+  const hasReplication = Boolean(role && (role.rolreplication || role.rolsuper));
+  items.push(
+    hasReplication ? { ok: true, label: `DATABASE_URL role can stream replication ${import_picocolors4.default.dim("(REPLICATION)")}` } : {
+      ok: false,
+      label: `DATABASE_URL role lacks the ${import_picocolors4.default.bold("REPLICATION")} attribute`,
+      fix: `ALTER ROLE current_user WITH REPLICATION;
+On RDS: GRANT rds_replication TO <your_role>;`
+    }
+  );
+  if (pubRows.length > 0) {
+    const badRows = await sql.unsafe(
+      `SELECT c.relname AS table_name, c.relreplident
+         FROM pg_publication_tables pt
+         JOIN pg_class c ON c.relname = pt.tablename
+         JOIN pg_namespace n ON n.oid = c.relnamespace AND n.nspname = pt.schemaname
+        WHERE pt.pubname = $1
+          AND (
+            c.relreplident = 'n'
+            OR (
+              c.relreplident = 'd'
+              AND NOT EXISTS (
+                SELECT 1 FROM pg_index i
+                 WHERE i.indrelid = c.oid AND i.indisprimary
+              )
+            )
+          )`,
+      [publication]
+    );
+    items.push(
+      badRows.length === 0 ? { ok: true, label: `all published tables have a usable REPLICA IDENTITY` } : {
+        ok: false,
+        label: `${badRows.length} published table${badRows.length === 1 ? "" : "s"} cannot replicate UPDATE/DELETE`,
+        fix: badRows.map(
+          (r2) => `${r2.table_name}: add a PRIMARY KEY, or ALTER TABLE ${quoteIdent(r2.table_name)} REPLICA IDENTITY FULL;`
+        ).join("\n")
+      }
+    );
+  }
+  return items;
+}
+async function runCheck() {
+  const dbUrl = readProjectDatabaseUrl();
+  if (!dbUrl) {
+    console.error(
+      import_picocolors4.default.red("  No DATABASE_URL found (checked process env, .env.local, .env).") + import_picocolors4.default.dim(` Set it to the Postgres you want Ablo to read, then re-run ${import_picocolors4.default.bold("ablo connect --check")}.`)
+    );
+    process.exit(1);
+  }
+  console.log(`
+  ${brand("ablo")} ${import_picocolors4.default.dim("connect --check")}  ${import_picocolors4.default.dim("logical-replication readiness")}
+`);
+  const sql = src_default(dbUrl, { max: 1, prepare: false, onnotice: () => {
+  } });
+  let items;
+  try {
+    items = await probeReadiness(sql);
+  } catch (err) {
+    const pg = err ?? {};
+    console.error(import_picocolors4.default.red(`  Couldn't read the database: ${pg.message ?? String(err)}`));
+    await sql.end({ timeout: 2 });
+    process.exit(1);
+  }
+  await sql.end({ timeout: 2 });
+  for (const item of items) printCheckItem(item);
+  const failures = items.filter((i) => !i.ok).length;
+  console.log();
+  if (failures === 0) {
+    console.log(`  ${import_picocolors4.default.green("\u2713")} Ready \u2014 Ablo can connect and tail this database's WAL.
+`);
+    process.exit(0);
+  }
+  console.log(
+    `  ${import_picocolors4.default.red(`${failures} item${failures === 1 ? "" : "s"} to fix`)} ${import_picocolors4.default.dim(`\u2014 apply the fixes above, then re-run ${import_picocolors4.default.bold("ablo connect --check")}.`)}
+`
+  );
+  process.exit(1);
+}
+async function connect(argv) {
+  let args;
+  try {
+    args = parseConnectArgs(argv);
+  } catch (err) {
+    console.error(import_picocolors4.default.red(`  ${err instanceof Error ? err.message : String(err)}`));
+    process.exit(1);
+  }
+  if (args.check) {
+    await runCheck();
+    return;
+  }
+  printConnectRecipe(args);
+}
+var CONNECT_USAGE = `  ablo connect \u2014 connect a real database to Ablo via logical replication (the one way)
+
+  Ablo READS your WAL and never runs DDL, owns, or migrates your schema. Your app
+  keeps writing through your own backend.
+
+  Usage:
+    npx ablo connect                      Print the exact setup SQL for your Postgres
+    npx ablo connect --tables a,b,c       Publish only these tables (default: all tables)
+    npx ablo connect --role <name>        Name the replication role (default: ablo_replicator)
+    npx ablo connect --check              Validate DATABASE_URL is replication-ready`;
+
 // src/cli/generate.ts
 init_cjs_shims();
 var import_fs6 = require("fs");
@@ -280313,21 +280532,6 @@ var import_picocolors6 = __toESM(require_picocolors(), 1);
 var import_fs7 = require("fs");
 var import_path5 = require("path");
 var import_schema5 = require("@abloatai/ablo/schema");
-
-// src/cli/theme.ts
-init_cjs_shims();
-var RESET = "\x1B[0m";
-var PAPER_BG = "\x1B[48;2;250;250;250m";
-var BLACK_FG = "\x1B[38;2;0;0;0m";
-function colorEnabled() {
-  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
-}
-function brand(label = "ablo") {
-  if (!colorEnabled()) return label;
-  return `${PAPER_BG}${BLACK_FG} ${label} ${RESET}`;
-}
-
-// src/cli/dev.ts
 function parseDevArgs(argv) {
   let schemaPath = DEFAULT_SCHEMA_PATH;
   let exportName = DEFAULT_EXPORT;
@@ -280437,11 +280641,27 @@ async function runPush(schema, args) {
   if (status2 === 409) {
     const unexecutable = Array.isArray(body.unexecutable) ? body.unexecutable : [];
     const warnings = Array.isArray(body.warnings) ? body.warnings : [];
+    const hasShadowed = [...unexecutable, ...warnings].some(
+      (s) => s.shadowed != null
+    );
     const lines = [
-      "Incompatible schema change \u2014 not safe to apply as-is.",
+      import_picocolors6.default.bold("Incompatible schema change \u2014 not safe to apply as-is."),
+      "",
       ...unexecutable.map((u2) => import_picocolors6.default.red(fmtSignal(u2))),
       ...warnings.map((w2) => import_picocolors6.default.yellow(fmtSignal(w2))),
-      import_picocolors6.default.dim(`Run ${import_picocolors6.default.bold("ablo push --force")} (or ${import_picocolors6.default.bold("--rename old:new")}) to resolve.`)
+      "",
+      ...hasShadowed ? [
+        import_picocolors6.default.dim(
+          "  These models exist in the baseline above but not in your push. Sandbox readers"
+        ),
+        import_picocolors6.default.dim(
+          "  fall back to the production schema until you push your own, so applying this drops them."
+        ),
+        ""
+      ] : [],
+      import_picocolors6.default.dim(
+        `  Fix: ${import_picocolors6.default.bold("ablo push --force")} to apply anyway, or ${import_picocolors6.default.bold("--rename old:new")} if you renamed a model.`
+      )
     ];
     return { ok: false, message: lines.join("\n") };
   }
@@ -280473,8 +280693,6 @@ async function dev(argv) {
   console.log(`
   ${brand("ablo")} ${import_picocolors6.default.dim("push")} ${import_picocolors6.default.dim("(sandbox)")}
 `);
-  const projectDbUrl = readProjectDatabaseUrl();
-  if (projectDbUrl) await ensureScopedRoleInteractive(projectDbUrl);
   const schema = await loadSchema(args.schemaPath, args.exportName);
   const modelCount = Object.keys(schema.models).length;
   console.log(
@@ -282350,11 +282568,89 @@ async function drizzlePull(argv) {
   );
 }
 
+// src/cli/renderError.ts
+init_cjs_shims();
+var import_picocolors18 = __toESM(require_picocolors(), 1);
+var RECOVERY_HINT = {
+  transient: "This looks transient \u2014 retry in a moment.",
+  permission: "Your key isn't allowed to do this \u2014 check its scopes or role.",
+  session_expiry: "Your session expired \u2014 sign in again.",
+  access_credential_expiry: "Your access credential expired \u2014 refresh it and retry.",
+  auth_blocked: "Authentication was blocked."
+};
+function titleForType(type) {
+  const core = type.replace(/^Ablo/, "").replace(/Error$/, "");
+  const spaced = core.replace(/([a-z0-9])([A-Z])/g, "$1 $2").trim();
+  if (!spaced) return "Error";
+  return /error$/i.test(spaced) ? spaced : `${spaced} error`;
+}
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x2) => typeof x2 === "string");
+}
+function renderKnownDetails(details, line) {
+  if (!details) return;
+  const { retryAfterSeconds, missingIds, requiredCapability, unexecutable, errors } = details;
+  if (typeof retryAfterSeconds === "number") line(`    ${import_picocolors18.default.dim("retry")}  after ${retryAfterSeconds}s`);
+  if (isStringArray(missingIds) && missingIds.length > 0) {
+    const shown = missingIds.slice(0, 5).join(", ");
+    const more = missingIds.length > 5 ? ` (+${missingIds.length - 5} more)` : "";
+    line(`    ${import_picocolors18.default.dim("missing")} ${shown}${more}`);
+  }
+  if (typeof requiredCapability === "string") line(`    ${import_picocolors18.default.dim("needs")}  ${requiredCapability}`);
+  if (Array.isArray(unexecutable) && unexecutable.length > 0) {
+    line(`    ${import_picocolors18.default.dim("blocked")} ${unexecutable.length} change(s) can't be applied \u2014 see \`unexecutable\` (--verbose)`);
+  }
+  if (Array.isArray(errors)) {
+    for (const e2 of errors.slice(0, 8)) {
+      if (e2 && typeof e2 === "object") {
+        const rec = e2;
+        const where = typeof rec.param === "string" ? `${rec.param}: ` : "";
+        const msg = typeof rec.message === "string" ? rec.message : "";
+        if (msg) line(`    ${import_picocolors18.default.dim("\xB7")} ${where}${msg}`);
+      }
+    }
+  }
+}
+function renderCliError(err, opts = {}) {
+  const line = opts.write ?? ((l2) => console.error(l2));
+  const verbose = opts.verbose ?? (process.argv.includes("--verbose") || process.env.ABLO_VERBOSE === "1");
+  if (err instanceof AbloError) {
+    const codeTag = err.code ? `  ${import_picocolors18.default.dim(`[${err.code}]`)}` : "";
+    line("");
+    line(`  ${brand("ablo")} ${import_picocolors18.default.red("\u2717")} ${import_picocolors18.default.bold(titleForType(err.type))}${codeTag}`);
+    line("");
+    line(`    ${err.message}`);
+    if (err.param) line(`    ${import_picocolors18.default.dim("field")}  ${err.param}`);
+    renderKnownDetails(err.details, line);
+    const hint = err.code ? RECOVERY_HINT[classifyRecovery(err.code)] : void 0;
+    if (hint) line(`    ${import_picocolors18.default.dim(hint)}`);
+    if (err.docUrl) line(`    ${import_picocolors18.default.dim("docs")}   ${err.docUrl}`);
+    if (err.requestId) line(`    ${import_picocolors18.default.dim("ref")}    ${err.requestId}`);
+    if (verbose) {
+      if (err.details && Object.keys(err.details).length > 0) {
+        line(`    ${import_picocolors18.default.dim("details")} ${JSON.stringify(err.details)}`);
+      }
+      if (err.stack) line(import_picocolors18.default.dim(err.stack));
+    }
+    line("");
+    process.exitCode = 1;
+    return;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  line("");
+  line(`  ${brand("ablo")} ${import_picocolors18.default.red("\u2717")} ${message}`);
+  if (verbose && err instanceof Error && err.stack) line(import_picocolors18.default.dim(err.stack));
+  else line(`    ${import_picocolors18.default.dim("Run with --verbose for the full error.")}`);
+  line("");
+  process.exitCode = 1;
+}
+
 // src/cli/index.ts
 var LOGO = `
-  ${brand("ablo")} ${import_picocolors18.default.dim("sync engine")}
+  ${brand("ablo")} ${import_picocolors19.default.dim("sync engine")}
 `;
 var SUBCOMMAND_USAGE = {
+  connect: CONNECT_USAGE,
   migrate: MIGRATE_USAGE
 };
 async function main() {
@@ -282386,7 +282682,7 @@ async function main() {
     const devArgs = process.argv.slice(3);
     const oneShot = devArgs.includes("--no-watch");
     console.log(
-      import_picocolors18.default.dim(
+      import_picocolors19.default.dim(
         oneShot ? "  `ablo dev --no-watch` is `ablo push` (push once, no watcher) \u2014 running that." : "  `ablo dev` is now `ablo push --watch` \u2014 running that."
       )
     );
@@ -282402,6 +282698,8 @@ async function main() {
     } else {
       await pull(rest);
     }
+  } else if (command === "connect") {
+    await connect(process.argv.slice(3));
   } else if (command === "migrate") {
     await migrate(process.argv.slice(3));
   } else if (command === "push") {
@@ -282411,14 +282709,14 @@ async function main() {
     const guard = guardActiveProjectKey();
     if (!guard.ok && guard.available.length > 0 && !rest.includes("--url")) {
       console.error(
-        `  ${import_picocolors18.default.yellow("\u26A0")} active project ${import_picocolors18.default.bold(guard.activeProfile)} has no stored key ${import_picocolors18.default.dim(
+        `  ${import_picocolors19.default.yellow("\u26A0")} active project ${import_picocolors19.default.bold(guard.activeProfile)} has no stored key ${import_picocolors19.default.dim(
           `(you have keys for: ${guard.available.join(", ")})`
         )}`
       );
       const loginCmd = guard.activeProfile === "default" ? "ablo login" : `ablo login --project ${guard.activeProfile}`;
       console.error(
-        import_picocolors18.default.dim(
-          `    Mint one with ${import_picocolors18.default.bold(loginCmd)}, or switch with ${import_picocolors18.default.bold("ablo projects use <slug>")}.`
+        import_picocolors19.default.dim(
+          `    Mint one with ${import_picocolors19.default.bold(loginCmd)}, or switch with ${import_picocolors19.default.bold("ablo projects use <slug>")}.`
         )
       );
       process.exitCode = 1;
@@ -282436,13 +282734,13 @@ async function main() {
     await generate(process.argv.slice(3));
   } else if (command === "schema") {
     console.error(
-      `  ${import_picocolors18.default.red("\u2717")} \`ablo schema push\` was renamed to \`${brand("ablo push")}\`.`
+      `  ${import_picocolors19.default.red("\u2717")} \`ablo schema push\` was renamed to \`${brand("ablo push")}\`.`
     );
     console.error(`    Run \`ablo push${process.argv.slice(4).join(" ") ? " " + process.argv.slice(4).join(" ") : ""}\` instead.`);
     process.exitCode = 1;
   } else {
     console.log(LOGO);
-    console.log(`  ${import_picocolors18.default.bold("Usage:")}`);
+    console.log(`  ${import_picocolors19.default.bold("Usage:")}`);
     console.log(`    npx ablo init                          Scaffold ablo/ directory + starter schema`);
     console.log(`    npx ablo init --yes [--framework nextjs] Non-interactive (agents/CI): no prompts, flag-driven`);
     console.log(`                  [--auth apikey] [--storage direct|endpoint] [--project <slug>] [--no-project]`);
@@ -282465,7 +282763,9 @@ async function main() {
     console.log(`    npx ablo pull prisma [path]            Generate schema.ts from a Prisma schema (keeps enums + relations)`);
     console.log(`    npx ablo pull drizzle <module>         Generate schema.ts from a Drizzle schema (keeps enums + relations)`);
     console.log(`    npx ablo check                         Check your existing database fits the schema (read-only, creates no tables)`);
-    console.log(`    npx ablo migrate                       Provision your synced-model tables in your own Postgres (DATABASE_URL)`);
+    console.log(`    npx ablo connect                       Connect a real database \u2014 prints the logical-replication setup SQL (the one way)`);
+    console.log(`    npx ablo connect --check               Validate DATABASE_URL is replication-ready (wal_level, publication, role, replica identity)`);
+    console.log(`    npx ablo migrate                       Provision your synced-model tables in your own Postgres (optional escape hatch \u2014 \`connect\` is the way)`);
     console.log(`    npx ablo migrate --dry-run             Print the SQL without executing (preview)`);
     console.log(`    npx ablo push                          Upload your schema definition to Ablo (metadata only \u2014 rows stay in your DB)`);
     console.log(`    npx ablo push --force                  Allow destructive/unexecutable changes`);
@@ -282475,10 +282775,10 @@ async function main() {
     console.log(`    npx ablo generate                      Emit TypeScript types from your schema`);
     console.log(`    npx ablo generate --out path.ts        Write generated types to a path`);
     console.log();
-    console.log(`  ${import_picocolors18.default.bold("Schema workflow:")}`);
+    console.log(`  ${import_picocolors19.default.bold("Schema workflow:")}`);
     console.log(`    The server holds its own copy of your schema \u2014 edit ${brand("ablo/schema.ts")}, then`);
     console.log(`    run ${brand("ablo push")} (or keep ${brand("ablo dev")} running) before the server will accept`);
-    console.log(`    writes to new or changed models. Skip it and writes fail with ${import_picocolors18.default.yellow("server_execute_unknown_model")}.`);
+    console.log(`    writes to new or changed models. Skip it and writes fail with ${import_picocolors19.default.yellow("server_execute_unknown_model")}.`);
     console.log();
   }
 }
@@ -282529,7 +282829,7 @@ async function ensureInitProject(opts) {
   const ensured = await ensureProject(slug);
   if (ensured) {
     console.log(
-      `  ${import_picocolors18.default.green("\u2713")} ${ensured.created ? "Created" : "Using"} project ${import_picocolors18.default.bold(ensured.slug)} ${import_picocolors18.default.dim(`(${ensured.id})`)} \u2014 keys you mint for it are isolated from the org's other apps.`
+      `  ${import_picocolors19.default.green("\u2713")} ${ensured.created ? "Created" : "Using"} project ${import_picocolors19.default.bold(ensured.slug)} ${import_picocolors19.default.dim(`(${ensured.id})`)} \u2014 keys you mint for it are isolated from the org's other apps.`
     );
   }
 }
@@ -282571,7 +282871,7 @@ async function chooseBool(flagValue, fallback, interactive, prompt) {
 async function init(args = []) {
   const opts = parseInitArgs(args);
   const interactive = Boolean(process.stdin.isTTY) && !opts.yes && !process.env.CI;
-  Ie(`${brand("ablo")} ${import_picocolors18.default.dim("sync engine")}`);
+  Ie(`${brand("ablo")} ${import_picocolors19.default.dim("sync engine")}`);
   if (!(0, import_fs12.existsSync)("package.json")) {
     xe("No package.json found. Run this from your project root.");
     process.exit(1);
@@ -282656,7 +282956,7 @@ async function init(args = []) {
   if (pullExisting) {
     const dbUrl = process.env.DATABASE_URL ?? process.env.ABLO_DATABASE_URL;
     if (!dbUrl) {
-      schemaNote = import_picocolors18.default.dim(" (no DATABASE_URL \u2014 wrote starter; run `ablo pull` later)");
+      schemaNote = import_picocolors19.default.dim(" (no DATABASE_URL \u2014 wrote starter; run `ablo pull` later)");
     } else {
       try {
         const pulled = await buildSchemaSourceFromDb({
@@ -282666,12 +282966,12 @@ async function init(args = []) {
         });
         if (pulled.models.length > 0) {
           schemaSource = pulled.source;
-          schemaNote = import_picocolors18.default.dim(` (pulled ${pulled.models.length} models)`);
+          schemaNote = import_picocolors19.default.dim(` (pulled ${pulled.models.length} models)`);
         } else {
-          schemaNote = import_picocolors18.default.dim(" (no adoptable tables \u2014 wrote starter)");
+          schemaNote = import_picocolors19.default.dim(" (no adoptable tables \u2014 wrote starter)");
         }
       } catch {
-        schemaNote = import_picocolors18.default.dim(" (pull failed \u2014 wrote starter)");
+        schemaNote = import_picocolors19.default.dim(" (pull failed \u2014 wrote starter)");
       }
     }
   }
@@ -282697,14 +282997,14 @@ async function init(args = []) {
     const existing = (0, import_fs12.readFileSync)(envFile, "utf-8");
     if (!existing.includes("ABLO_")) {
       (0, import_fs12.writeFileSync)(envFile, existing + "\n" + envBody);
-      created.push(`${envFile} ${import_picocolors18.default.dim("(appended)")}`);
+      created.push(`${envFile} ${import_picocolors19.default.dim("(appended)")}`);
     } else {
-      created.push(`${envFile} ${import_picocolors18.default.dim("(already configured)")}`);
+      created.push(`${envFile} ${import_picocolors19.default.dim("(already configured)")}`);
     }
   }
   if (wireRealKey && resolvedKey) {
     wireEnvLocal(resolvedKey);
-    created.push(`.env.local ${import_picocolors18.default.dim("(ABLO_API_KEY set from your login)")}`);
+    created.push(`.env.local ${import_picocolors19.default.dim("(ABLO_API_KEY set from your login)")}`);
   }
   if (agent) {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "agent.ts"), generateAgent());
@@ -282719,17 +283019,17 @@ async function init(args = []) {
     }
     const providersPath = (0, import_path7.join)(layout.appBase, "providers.tsx");
     (0, import_fs12.writeFileSync)(providersPath, generateProviders());
-    created.push(`${providersPath} ${import_picocolors18.default.dim(`(wrap ${(0, import_path7.join)(layout.appBase, "layout.tsx")} in <Providers>)`)}`);
+    created.push(`${providersPath} ${import_picocolors19.default.dim(`(wrap ${(0, import_path7.join)(layout.appBase, "layout.tsx")} in <Providers>)`)}`);
     const sessionDir = (0, import_path7.join)(layout.appBase, "api", "ablo-session");
     (0, import_fs12.mkdirSync)(sessionDir, { recursive: true });
     (0, import_fs12.writeFileSync)((0, import_path7.join)(sessionDir, "route.ts"), generateSessionRoute());
-    created.push(`${(0, import_path7.join)(sessionDir, "route.ts")} ${import_picocolors18.default.dim("(wire your auth)")}`);
+    created.push(`${(0, import_path7.join)(sessionDir, "route.ts")} ${import_picocolors19.default.dim("(wire your auth)")}`);
   }
   if (framework !== "vanilla") {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "TaskList.tsx"), generateComponent());
     created.push(`${abloDir}/TaskList.tsx`);
   }
-  Me(created.map((f) => `${import_picocolors18.default.green("\u2713")} ${f}`).join("\n"), "Created");
+  Me(created.map((f) => `${import_picocolors19.default.green("\u2713")} ${f}`).join("\n"), "Created");
   const pm = detectPackageManager();
   if (opts.install) {
     const s = Y2();
@@ -282738,45 +283038,45 @@ async function init(args = []) {
       (0, import_child_process2.execSync)(`${pm} add @abloatai/ablo`, { stdio: "ignore" });
       s.stop("Installed @abloatai/ablo");
     } catch {
-      s.stop(`${import_picocolors18.default.yellow("!")} Couldn't auto-install \u2014 run ${import_picocolors18.default.bold(`${pm} install @abloatai/ablo`)}`);
+      s.stop(`${import_picocolors19.default.yellow("!")} Couldn't auto-install \u2014 run ${import_picocolors19.default.bold(`${pm} install @abloatai/ablo`)}`);
     }
   }
   const steps = [
-    `Get a ${import_picocolors18.default.bold("sk_test_")} key at ${import_picocolors18.default.cyan("https://abloatai.com")}`,
-    `Run ${import_picocolors18.default.bold("npx ablo login")} (or add ${import_picocolors18.default.bold("ABLO_API_KEY")} to ${import_picocolors18.default.bold(envFile)})`,
-    `Set ${import_picocolors18.default.bold("DATABASE_URL")} in ${import_picocolors18.default.bold(envFile)} \u2014 your Postgres is the system of record; rows live there, never with Ablo`,
-    `Run ${import_picocolors18.default.bold("npx ablo dev")} \u2014 pushes your schema definition and watches for changes`,
+    `Get a ${import_picocolors19.default.bold("sk_test_")} key at ${import_picocolors19.default.cyan("https://abloatai.com")}`,
+    `Run ${import_picocolors19.default.bold("npx ablo login")} (or add ${import_picocolors19.default.bold("ABLO_API_KEY")} to ${import_picocolors19.default.bold(envFile)})`,
+    `Set ${import_picocolors19.default.bold("DATABASE_URL")} in ${import_picocolors19.default.bold(envFile)} \u2014 your Postgres is the system of record; rows live there, never with Ablo`,
+    `Run ${import_picocolors19.default.bold("npx ablo dev")} \u2014 pushes your schema definition and watches for changes`,
     ...storage === "direct" ? [
-      `Provision your DB: ${import_picocolors18.default.bold("npx ablo migrate")} (creates your synced-model tables with row-level security; keep your own migrations for everything else)`
+      `Provision your DB: ${import_picocolors19.default.bold("npx ablo migrate")} (creates your synced-model tables with row-level security; keep your own migrations for everything else)`
     ] : [
-      `Provision your DB: ${import_picocolors18.default.bold("npx ablo migrate")} (creates your Ablo-model tables + the adapter tables; keep your own migrations for everything else), then mount ${import_picocolors18.default.bold(`${abloDir}/data-source.ts`)} at ${import_picocolors18.default.bold("/api/ablo/source")}`
+      `Provision your DB: ${import_picocolors19.default.bold("npx ablo migrate")} (creates your Ablo-model tables + the adapter tables; keep your own migrations for everything else), then mount ${import_picocolors19.default.bold(`${abloDir}/data-source.ts`)} at ${import_picocolors19.default.bold("/api/ablo/source")}`
     ],
     ...framework === "nextjs" ? [
-      `Wrap ${import_picocolors18.default.bold((0, import_path7.join)(layout.appBase, "layout.tsx"))} in ${import_picocolors18.default.bold("<Providers>")} (${(0, import_path7.join)(layout.appBase, "providers.tsx")}) and add your auth to ${import_picocolors18.default.bold((0, import_path7.join)(layout.appBase, "api", "ablo-session", "route.ts"))}`
+      `Wrap ${import_picocolors19.default.bold((0, import_path7.join)(layout.appBase, "layout.tsx"))} in ${import_picocolors19.default.bold("<Providers>")} (${(0, import_path7.join)(layout.appBase, "providers.tsx")}) and add your auth to ${import_picocolors19.default.bold((0, import_path7.join)(layout.appBase, "api", "ablo-session", "route.ts"))}`
     ] : [],
-    `Run ${import_picocolors18.default.bold(`${pm} run dev`)} and open two browser tabs \u2014 changes sync in real-time`,
+    `Run ${import_picocolors19.default.bold(`${pm} run dev`)} and open two browser tabs \u2014 changes sync in real-time`,
     ...agent ? [
-      `Run ${import_picocolors18.default.bold(`npx tsx ${abloDir}/agent.ts`)} \u2014 an AI teammate edits the same tasks`,
-      `Run ${import_picocolors18.default.bold("npx ablo logs")} to watch human + agent commits stream by`
+      `Run ${import_picocolors19.default.bold(`npx tsx ${abloDir}/agent.ts`)} \u2014 an AI teammate edits the same tasks`,
+      `Run ${import_picocolors19.default.bold("npx ablo logs")} to watch human + agent commits stream by`
     ] : []
   ];
   Me(steps.map((s, i) => `${i + 1}. ${s}`).join("\n"), "Next steps");
   const existingKey = resolveApiKey("sandbox");
   if (existingKey) {
     await ensureInitProject(opts);
-    Se(`Already authorized ${import_picocolors18.default.dim(`(${existingKey.slice(0, 11)}\u2026)`)} \u2014 run ${import_picocolors18.default.bold("npx ablo push")} next. ${import_picocolors18.default.dim("Docs:")} https://abloatai.com/docs`);
+    Se(`Already authorized ${import_picocolors19.default.dim(`(${existingKey.slice(0, 11)}\u2026)`)} \u2014 run ${import_picocolors19.default.bold("npx ablo push")} next. ${import_picocolors19.default.dim("Docs:")} https://abloatai.com/docs`);
     return;
   }
   if (interactive && opts.login) {
     const loginNow = await ye({ message: "Log in now? (opens your browser)", initialValue: true });
     if (!pD(loginNow) && loginNow) {
-      Se(`${import_picocolors18.default.dim("Docs:")} https://abloatai.com/docs`);
+      Se(`${import_picocolors19.default.dim("Docs:")} https://abloatai.com/docs`);
       await login();
       await ensureInitProject(opts);
       return;
     }
   }
-  Se(`Run ${import_picocolors18.default.bold("npx ablo login")} when ready. ${import_picocolors18.default.dim("Docs:")} https://abloatai.com/docs`);
+  Se(`Run ${import_picocolors19.default.bold("npx ablo login")} when ready. ${import_picocolors19.default.dim("Docs:")} https://abloatai.com/docs`);
 }
 function generateSchema() {
   return `import { defineSchema, model, relation, z } from '@abloatai/ablo/schema';
@@ -283054,7 +283354,9 @@ async function main() {
 }
 
 main().catch((err) => {
-  console.error(err);
+  // Ablo errors stringify to one clean line (code + message + docs link),
+  // never a stack/object dump \u2014 see AbloError.toString().
+  console.error(String(err));
   process.exit(1);
 });
 `;
@@ -283141,22 +283443,33 @@ export function Providers({ children }: { children: React.ReactNode }) {
 `;
 }
 function generateSessionRoute() {
-  return `import { sync } from '@/ablo';
+  return `import { headers } from 'next/headers';
+import { sync } from '@/ablo';
+import { auth } from '@/lib/auth'; // your server-side betterAuth({ ... }) instance
 
 // Mints the browser's session token. The browser never sees your sk_ key \u2014 it
-// only gets this token, which already names your org + the user you assert here.
-// Replace getCurrentUser() with your real auth (NextAuth / Clerk / Better Auth / \u2026).
+// only gets this short-lived token, already scoped to your org + the user you
+// assert here. The browser fetches THIS route at a relative URL
+// ('/api/ablo-session') \u2014 that's correct + best practice (same-origin, cookies
+// flow automatically); the SDK refreshes it in the browser only.
 export async function POST(): Promise<Response> {
-  const user = await getCurrentUser(); // \u2190 your auth: who is making this request?
+  const user = await getCurrentUser();
   if (!user) return new Response('Unauthorized', { status: 401 });
 
   const { token } = await sync.sessions.create({ user: { id: user.id } });
   return Response.json({ token });
 }
 
-// TODO: replace with your auth provider's "current user" lookup.
+// Validate the signed-in user SERVER-SIDE. This ships wired for Better Auth;
+// \`getSession\` is the server method \u2014 pass the request headers (async in current
+// Next.js), it does NOT read cookies implicitly. Using a different provider?
+// Replace the body:
+//   \u2022 NextAuth:  const s = await auth();            return s?.user ? { id: s.user.id } : null;
+//   \u2022 Clerk:     const { userId } = await auth();   return userId ? { id: userId } : null;
+//   \u2022 Supabase:  const { data } = await supabase.auth.getUser(); return data.user ? { id: data.user.id } : null;
 async function getCurrentUser(): Promise<{ id: string } | null> {
-  return null;
+  const session = await auth.api.getSession({ headers: await headers() });
+  return session?.user ? { id: session.user.id } : null;
 }
 `;
 }
@@ -283166,7 +283479,10 @@ function detectPackageManager() {
   if ((0, import_fs12.existsSync)("bun.lockb")) return "bun";
   return "npm";
 }
-main().catch(console.error);
+main().catch((err) => {
+  renderCliError(err);
+  process.exit(process.exitCode ?? 1);
+});
 /*! Bundled license information:
 
 @ts-morph/common/dist/typescript.js: