@abloatai/ablo 0.16.3 → 0.17.0

package/dist/cli.cjs

@@ -277378,7 +277378,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 +278098,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 +278231,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 +278250,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 +279252,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 +279339,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 +279372,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 +279397,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 +279517,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;
@@ -279687,7 +279537,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 +279779,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 +279869,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,7 +279880,7 @@ 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" }
     );
   }
@@ -280032,14 +279891,14 @@ async function push(argv) {
   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();
   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 +279906,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 +279924,56 @@ 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"}`));
+    if (code === "database_role_cannot_enforce_rls") {
       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(
+          `  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.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 +279981,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 +280033,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 +280109,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 +280120,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 +280464,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 +280573,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 +280625,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(
@@ -282355,6 +282505,7 @@ var LOGO = `
   ${brand("ablo")} ${import_picocolors18.default.dim("sync engine")}
 `;
 var SUBCOMMAND_USAGE = {
+  connect: CONNECT_USAGE,
   migrate: MIGRATE_USAGE
 };
 async function main() {
@@ -282402,6 +282553,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") {
@@ -282465,7 +282618,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`);