@abloatai/ablo 0.9.1 → 0.9.3

package/llms.txt

@@ -6,6 +6,14 @@ Here is the problem it solves. Two writers touch `report_stockholm` at once. The
 
 Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist, coordinate with concurrent work, and leave an audit trail.
 
+## Start here
+
+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.
+
+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).
+
 ## Use this API
 
 ```ts
@@ -23,15 +31,16 @@ const schema = defineSchema({
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-const report = await ablo.weatherReports.retrieve('report_stockholm');
+const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
 if (!report) throw new Error('Row not found');
 
-const updated = await ablo.weatherReports.claim('report_stockholm', async (report) => {
-  return ablo.weatherReports.update(
-    report.id,
-    { status: 'ready', forecast: await getForecast(report) },
-    { wait: 'confirmed' },
-  );
+// Claim the row (waits if someone else holds it), read the fresh copy off
+// `claim.data`, write, then auto-release at the end of this scope (`await using`).
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const updated = await ablo.weatherReports.update({
+  id: claim.data.id,
+  data: { status: 'ready', forecast: await getForecast(claim.data) },
+  wait: 'confirmed',
 });
 ```
 
@@ -43,10 +52,10 @@ hosted schema push, and schema-version gating. Do not invent a parallel
 string-keyed write path for rows that belong to a schema model.
 
 For full integrations, use `integration-guide` as the canonical doc. It covers
-the same model API across Ablo-managed state, Data Source-backed app databases,
+the same model API across your own Data Source-backed app databases,
 React selectors, multiplayer, and future agent workers.
 
-Reads come in two flavors, and you pick by whether you can wait. `retrieve(id)`
+Reads come in two flavors, and you pick by whether you can wait. `retrieve({ id })`
 (one row) and `list({ where })` (many) are async — they hit the server and return
 a Promise, so await them. `get(id)`, `getAll({ where })`, and `getCount({ where })`
 are synchronous — they read the local graph and are reactive in render, so no
@@ -68,7 +77,7 @@ first integration path.
 Multiplayer is not a separate mode. When human UI, server actions, and agents use
 the same schema client and write through `ablo.<model>`, Ablo coordinates the
 shared model stream: confirmed deltas fan out to subscribers, active claims are
-visible through `claim.state(id)`, and stale writes can be rejected with `readAt`.
+visible through `claim.state({ id })`, and stale writes can be rejected with `readAt`.
 
 If an app writes directly to its own database outside Ablo, that write bypasses
 coordination until the app reports it through Data Source events.
@@ -76,7 +85,7 @@ coordination until the app reports it through Data Source events.
 ## Nouns
 
 - `Model client` is the typed `ablo.<model>` object generated from schema.
-- `Claim` holds a model row while slow work runs; `claim.state(id)` observes it.
+- `Claim` holds a model row while slow work runs; `claim.state({ id })` observes it.
 - `Commit` is the durable protocol write behind `ablo.<model>.update(...)`.
 - `Receipt` confirms the commit.
 
@@ -109,23 +118,25 @@ A schema is model fields and relations. Advanced schema helpers such as `mutable
 
 Do not add `databaseURL` to `Ablo(...)`. Application and agent code use `ABLO_API_KEY`.
 
-Every schema model has a backing store. By default, Ablo stores rows for declared models, so `ablo.<model>.create/update/delete` write to Ablo-managed state. If the customer database is canonical, expose a Data Source endpoint. With Prisma or Drizzle this is ONE line — pass an ORM `adapter` and it owns the transaction, idempotency, and outbox (no hand-written `commit`/`events`):
+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.
 
 ```ts
 // app/api/ablo/source/route.ts
 import { dataSourceNext } from '@abloatai/ablo/source/next';
-import { prismaDataSource } from '@abloatai/ablo/source';
+import { drizzleDataSource } from '@abloatai/ablo/source/drizzle';
 import { schema } from '@/ablo/schema';
-import { prisma } from '@/lib/prisma';
+import { db } from '@/db';
+
+export const runtime = 'nodejs'; // the route touches your database
 
 export const { POST } = dataSourceNext({
   schema,
   apiKey: process.env.ABLO_API_KEY!,
-  adapter: prismaDataSource(prisma, schema), // or drizzleDataSource(db, tables)
+  adapter: drizzleDataSource(db, schema), // or prismaDataSource(prisma, schema) / kyselyDataSource(db, schema)
 });
 ```
 
-`npx ablo init` generates this file for you (see CLI below). Customer-owned app database credentials stay private — Ablo only calls the endpoint.
+`npx ablo init` defaults to this — it scaffolds the endpoint and the `DATABASE_URL` for you (see CLI below). Your app database credentials stay private — Ablo only calls the endpoint.
 
 ## Sandboxes
 
@@ -156,6 +167,7 @@ Import from these public paths only:
 - `@abloatai/ablo/source` — `dataSource`, the `DataSourceAdapter` spine, `prismaDataSource`. For a customer-canonical Data Source endpoint.
 - `@abloatai/ablo/source/next` — `dataSourceNext` (Next.js App Router `{ POST }`).
 - `@abloatai/ablo/source/drizzle` — `drizzleDataSource`.
+- `@abloatai/ablo/source/kysely` — `kyselyDataSource`.
 - `@abloatai/ablo/source/conformance` — `runDataSourceTests` to prove a custom adapter/handler.
 
 Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subpaths. (`/source` IS public — it's the Data Source endpoint surface above.)
@@ -165,8 +177,8 @@ Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subp
 `ablo init` and other prompts need a TTY; an agent/CI run has none and will HANG. Always:
 
 - `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.
-- Authenticate with the `ABLO_API_KEY` env var. Do NOT run `ablo login` (opens a browser).
+- 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` (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 (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.
 
 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.1",
+  "version": "0.9.3",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,6 +9,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "ablo": "./dist/cli.cjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -65,6 +68,11 @@
       "import": "./dist/source/adapters/drizzle.js",
       "default": "./dist/source/adapters/drizzle.js"
     },
+    "./source/kysely": {
+      "types": "./dist/source/adapters/kysely.d.ts",
+      "import": "./dist/source/adapters/kysely.js",
+      "default": "./dist/source/adapters/kysely.js"
+    },
     "./source/next": {
       "types": "./dist/source/next.d.ts",
       "import": "./dist/source/next.js",
@@ -106,6 +114,7 @@
     "examples",
     "AGENTS.md",
     "llms.txt",
+    "llms-full.txt",
     "LICENSE",
     "NOTICE",
     "README.md",
@@ -113,13 +122,17 @@
   ],
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "build": "npm run clean && tsc -p tsconfig.build.json && npm run build:cli",
+    "build:cli": "tsup --config tsup.cli.config.ts",
+    "typecheck:cli": "tsc -p tsconfig.cli.json",
     "pack:check": "npm_config_cache=${TMPDIR:-/tmp}/ablo-npm-cache npm pack --dry-run",
     "lint:imports": "node scripts/check-js-extensions.mjs",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",
     "lint:pkg": "publint",
     "prepublishOnly": "npm run build && npm run lint:pkg",
+    "check:dist": "node scripts/check-dist-fresh.mjs",
+    "pretest": "node scripts/check-dist-fresh.mjs",
     "test": "jest",
     "test:unit": "jest --testPathPattern=__tests__/unit",
     "test:integration": "jest --testPathPattern=__tests__/integration",
@@ -159,7 +172,7 @@
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "drizzle-orm": ">=0.30.0"
+    "drizzle-orm": ">=0.44.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -177,6 +190,8 @@
   },
   "devDependencies": {
     "@ai-sdk/provider": "^3.0.0",
+    "@clack/prompts": "^0.11.0",
+    "@prisma/client": "^7.3.0",
     "@types/jest": "^29.5.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
@@ -189,10 +204,15 @@
     "fast-check": "^3.0.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "jiti": "^2.7.0",
     "mobx": "^6.13.7",
+    "picocolors": "^1.1.0",
+    "postgres": "^3.4.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "ts-jest": "^29.4.0",
+    "ts-morph": "^26.0.0",
+    "tsup": "^8.0.0",
     "typescript": "^5.8.3",
     "publint": "^0.3.21"
   }