@abloatai/ablo 0.9.3 → 0.9.5

package/llms-full.txt

@@ -142,10 +142,22 @@ This applies to any API-backed app: Python, Rails, Go, or Node. The backend keep
 its service layer and DB credentials. Ablo gets a Data Source endpoint and uses
 `ABLO_API_KEY`, not a database URL.
 
+When the user DOES use the connection-string path (`Ablo({ databaseUrl })` /
+`DATABASE_URL` at init): the role must be NON-superuser and NON-BYPASSRLS —
+Ablo enforces row-level security and rejects owner roles with
+`database_role_cannot_enforce_rls`. Neon's and Supabase's default dashboard
+strings use the database OWNER (e.g. `neondb_owner`) and ARE rejected. EASIEST: have the user run `npx ablo migrate` — it detects the unsafe role and creates the scoped one automatically from their machine (owner credential never reaches Ablo; new DATABASE_URL written to the env file). Manual alternative — create a scoped role first (`CREATE ROLE ablo_app LOGIN PASSWORD '...'
+NOSUPERUSER NOBYPASSRLS; GRANT CREATE, CONNECT ON DATABASE <db> TO ablo_app;
+GRANT CREATE, USAGE ON SCHEMA public TO ablo_app;`), then swap user/password
+into the same host/db string.
+
 ## Client Behavior
 
-Important options: `schema`, `apiKey`, `baseURL`, `persistence`, `fetch`,
-`defaultHeaders`, `defaultQuery`, `logger`, and `dangerouslyAllowBrowser`.
+The options that matter: `schema` and `apiKey`. Everything else
+(`persistence`, `logger`, transport tuning) has correct defaults — do NOT set
+`baseURL`; the default already routes to the hosted API, and overriding it
+breaks the connection. It exists only for self-hosted/proxy setups the human
+explicitly asks for.
 
 There is intentionally no `databaseURL` option on `Ablo(...)`. Application and
 agent code use `ABLO_API_KEY`. Customer-owned app databases stay private behind
@@ -171,7 +183,7 @@ There are two sandbox surfaces:
   making real Ablo calls. It is agent-first: it should expose a prompt that can
   be pasted into Claude Code or Codex to wire one real model through Ablo.
 - Authenticated org sandboxes are real test environments. The default sandbox is
-  the Stripe-style test mode for an org. It has an isolated sync group prefix,
+  the Stripe-style sandbox for an org. It has an isolated sync group prefix,
   can mint `sk_test_*` keys, and can be reset without touching live state.
 
 Additional org sandboxes can start blank or copy live configuration. Keep
@@ -190,8 +202,10 @@ Use these public environment names:
 - `ABLO_API_KEY` — SDK authentication for app and agent code. Where it comes
   from: the human runs `npx ablo login` once (browser; an agent must not run
   it), and `npx ablo dev` then writes `ABLO_API_KEY=sk_test_…` into
-  `.env.local` automatically. Check the environment and `.env.local` before
-  asking the human for a key.
+  `.env.local` automatically (and gitignores it). Check the environment and
+  `.env.local` for PRESENCE only (`grep -cq '^ABLO_API_KEY=' .env.local`)
+  before asking the human for a key — never print or echo the key value; a
+  secret in agent output lives in the conversation history forever.
 
 Do not ask customers to paste their app database URL into Ablo. If their app
 database is canonical, they expose a Data Source endpoint and keep database

package/llms.txt

@@ -10,9 +10,9 @@ Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist
 
 First action when integrating into an app: run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla> --storage datasource`. Agents have no TTY — `--yes` is REQUIRED or it HANGS. It scaffolds `ablo/schema.ts`, the client, the Data Source endpoint, and (for Next.js) the browser provider + session route, all on the current API. Edit the generated files rather than hand-writing from this doc.
 
-Second: make sure a key exists. Check `ABLO_API_KEY` in the environment, then `.env.local`. If neither has one, ask the HUMAN to run `npx ablo login` once — it opens a browser and saves a `sk_test_` key locally; an agent must NOT run it. You never copy the key by hand: the next step writes it into `.env.local` for you.
+Second: make sure a key exists — WITHOUT printing it. The key is a secret; it must never appear in your output, your reasoning, or a file you echo (it would live in the conversation history forever). Check PRESENCE only: `[ -n "$ABLO_API_KEY" ] && echo set` and `grep -cq '^ABLO_API_KEY=' .env.local && echo wired` — never `cat .env.local`, never `echo $ABLO_API_KEY`. If neither check passes, ask the HUMAN to run `npx ablo login` once — it opens a browser and saves a `sk_test_` key locally; an agent must NOT run it. You never copy the key by hand: the next step writes it into `.env.local` (and gitignores it) for you.
 
-Then PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. Run `npx ablo dev --no-watch`: it pushes `ablo/schema.ts` (test mode) AND writes `ABLO_API_KEY` into `.env.local` from the stored login. Until the schema is pushed, EVERY write to a new or changed model fails with `server_execute_unknown_model`. Re-run it after schema changes (`npx ablo push` also works once the key is wired; bare `npx ablo dev` watches forever — don't, you have no TTY).
+Then PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. Run `npx ablo dev --no-watch`: it pushes `ablo/schema.ts` (sandbox) AND writes `ABLO_API_KEY` into `.env.local` from the stored login. Until the schema is pushed, EVERY write to a new or changed model fails with `server_execute_unknown_model`. Re-run it after schema changes (`npx ablo push` also works once the key is wired; bare `npx ablo dev` watches forever — don't, you have no TTY).
 
 ## Use this API
 
@@ -120,6 +120,8 @@ Do not add `databaseURL` to `Ablo(...)`. Application and agent code use `ABLO_AP
 
 Every schema model is backed by a database, and the default is YOUR OWN. Keep your rows in your Postgres and expose a Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle is the default; Prisma and Kysely are also supported) — it owns the transaction, exactly-once idempotency, and outbox in ONE pass (no hand-written `commit`/`events`). Your `DATABASE_URL` lives in your app, never in `Ablo(...)`; run `npx ablo migrate` to provision the synced-model tables in your DB.
 
+GOTCHA the user WILL hit: `DATABASE_URL` must use a NON-superuser, NON-BYPASSRLS role (Ablo enforces row-level security; owner roles are rejected with `database_role_cannot_enforce_rls`). Neon's and Supabase's default dashboard connection strings use the database OWNER (e.g. `neondb_owner`) and are rejected. EASIEST: `npx ablo migrate` detects the unsafe role and creates the scoped one automatically from the user's machine (owner credential never reaches Ablo; new DATABASE_URL written to the env file). Manual alternative — create a scoped role first: `CREATE ROLE ablo_app LOGIN PASSWORD '...' NOSUPERUSER NOBYPASSRLS; GRANT CREATE, CONNECT ON DATABASE <db> TO ablo_app; GRANT CREATE, USAGE ON SCHEMA public TO ablo_app;` — then swap user/password into the same host/db string.
+
 ```ts
 // app/api/ablo/source/route.ts
 import { dataSourceNext } from '@abloatai/ablo/source/next';
@@ -179,6 +181,6 @@ Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subp
 - `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the `ablo/data-source.ts` endpoint above.
 - Key: see "Start here" — env → `.env.local` → ask the human to `npx ablo login`; never run `login` yourself, never copy keys by hand (`ablo dev` writes `.env.local`).
 - Adopt an existing DB: `npx ablo pull prisma [path]` / `npx ablo pull drizzle <module>`.
-- `npx ablo dev --no-watch` pushes the schema (test mode) AND writes `ABLO_API_KEY` to `.env.local` (default watches forever); `npx ablo logs --no-follow` (default tails forever); `npx ablo mode test|live` (always pass the arg). `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
+- `npx ablo dev --no-watch` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local` (default watches forever); `npx ablo logs --no-follow` (default tails forever); `npx ablo mode sandbox|production` (always pass the arg). `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
 
 Canonical docs to read before integrating: `quickstart`, `schema-contract`, `integration-guide`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",
@@ -134,6 +134,7 @@
     "check:dist": "node scripts/check-dist-fresh.mjs",
     "pretest": "node scripts/check-dist-fresh.mjs",
     "test": "jest",
+    "test:quickstart": "node scripts/test-quickstart.mjs",
     "test:unit": "jest --testPathPattern=__tests__/unit",
     "test:integration": "jest --testPathPattern=__tests__/integration",
     "test:contract": "jest --testPathPattern=__tests__/contract",
@@ -183,10 +184,11 @@
     }
   },
   "dependencies": {
+    "jiti": "^2.7.0",
     "mobx": "^6.13.7",
     "mobx-react-lite": "^4.0.0",
-    "zod": "^4.0.17",
-    "uuid": "^11.1.0"
+    "uuid": "^11.1.0",
+    "zod": "^4.0.17"
   },
   "devDependencies": {
     "@ai-sdk/provider": "^3.0.0",