clivly 0.7.2 → 0.7.4

package/README.md

@@ -1,189 +1,441 @@
 # clivly
 
-Clivly's consolidated public package.
+The consolidated public package for [Clivly](https://clivly.com) — the CRM that
+lives inside your app. It is two things in one install:
 
-It serves two roles:
+- **A CLI** (`npx clivly …`) that scaffolds your integration, pairs your machine
+  with a workspace, and diagnoses the setup.
+- **A runtime**, imported from typed subpaths (`clivly/sdk`, `clivly/drizzle`,
+  `clivly/vite`, `clivly/auth/*`).
 
-- the CLI you run as `npx clivly ...`
-- the package that exposes the stable runtime subpaths such as `clivly/sdk`
+> **The canonical end-to-end integration guide is
+> [Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md).**
+> This README is the command-level reference.
 
-## Install
+## Prerequisites
+
+| Requirement | Version / note |
+| --- | --- |
+| Node.js | **≥ 22** |
+| An existing app | The CLI scaffolds into a project you already have |
+| Drizzle ORM | Required for `clivly init` to generate a config. Prisma/Kysely/raw-SQL projects hand-write a `fetchPage` source instead |
+| `cloudflared` on `PATH` | Only for `clivly dev` |
+
+## Installation
 
 ```bash
 npm install clivly
 ```
 
-Stable releases publish on npm's `latest` tag. Use `@next` only when you are
-intentionally testing a prerelease build.
-
-This package requires Node `>=22`.
+Published on npm's `latest` tag. Once installed, `npx clivly …` uses your local
+copy rather than re-fetching. Use `@next` only when deliberately testing a
+prerelease cut.
 
-## CLI commands
+## Five-minute quick start
 
 ```bash
-npx clivly init          # scaffold config, route files, and .env placeholders
-npx clivly add widget    # scaffold the chat-session route for the widget
-npx clivly login         # pair this machine and write credentials to .env
-npx clivly status        # check your setup, step by step
-npx clivly dev           # tunnel localhost so remote sync can reach you
-npx clivly push-schema   # report your schema to Clivly without deploying
+npm install clivly
+npx clivly init      # scaffold config + routes + .env, then pair this machine
+npx clivly status    # check every setup step until they all pass
 ```
 
-`ping` and `doctor` remain available as focused aliases around parts of the
-`status` ladder.
+`clivly init` writes exactly three files (plus `.env` keys) — a
+`clivly.config.ts` you own, and two route files Clivly owns. It creates no
+database tables and does not modify your ORM schema.
 
-## Runtime imports
+---
 
-Application code should import from subpaths, not from the package root:
+## Commands
 
-```ts
-import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
-import { fromDrizzle } from "clivly/drizzle";
-import { clivlyVite } from "clivly/vite";
-import { createClerkAuthAdapter } from "clivly/auth/clerk";
-import { createWorkOSAuthAdapter } from "clivly/auth/workos";
-import { createBetterAuthAdapter } from "clivly/auth/better-auth";
-```
+| Command | What it does |
+| --- | --- |
+| [`clivly init`](#clivly-init) | Scaffold config, routes and env placeholders for your app |
+| [`clivly login`](#clivly-login) | Pair this machine and write credentials to your env file |
+| [`clivly status`](#clivly-status) | Check your setup, step by step. Read-only |
+| [`clivly add widget`](#clivly-add-widget) | Scaffold the chat-session route |
+| [`clivly push-schema`](#clivly-push-schema) | Report your schema to Clivly without deploying |
+| [`clivly dev`](#clivly-dev) | Tunnel localhost so remote sync can reach you |
+| `clivly --version` | Print the installed `clivly` version |
+| [`clivly ping` / `connect` / `doctor`](#deprecated-aliases) | Deprecated aliases running parts of `status` |
 
-Do **not** import application code from `clivly` (the package root). The root
-entry is the CLI.
+Every command accepts `--help` (or `-h`), which **describes without acting**.
 
-Provider and framework integrations use optional peer dependencies. Install only
-what your app actually uses, such as `drizzle-orm`, `vite`, `@clerk/backend`,
-`@workos-inc/node`, or `better-auth`.
+---
 
-## `clivly init`
+### `clivly init`
 
-`clivly init` detects your framework from `package.json`, locates your Drizzle
-schema, and writes:
+```bash
+npx clivly init [--force] [--dry-run] [--diff] [--yes] [--no-login] [--no-browser]
+                [--schema <path|package>] [--db-import <specifier>]
+                [--auth-import <specifier>] [--contact-table <table>]
+                [--company-table <table>]
+```
 
-- `clivly.config.ts`
-- the supported Clivly route files for your framework
-- missing `.env` placeholders
+Detects your framework, ORM, auth adapter and app layout, then scaffolds:
 
-It currently targets Drizzle-backed integrations. Prisma and Kysely projects
-can still integrate, but should provide hand-written `fetchPage` sources rather
-than relying on the generated Drizzle path.
+| File | Owned by Clivly |
+| --- | --- |
+| `clivly.config.ts` | No — yours to edit |
+| The tick route for your framework | Yes — `--force` to overwrite |
+| The auth-verify route for your framework | Yes — `--force` to overwrite |
 
-Useful flags:
+Plus `CLIVLY_SECRET_KEY`, `CLIVLY_SYNC_TRIGGER_URL` and
+`CLIVLY_SYNC_TRIGGER_SECRET` placeholders in your env file.
 
 | Flag | Purpose |
 | --- | --- |
-| `--schema <path\|package>` | Where your Drizzle schema lives |
-| `--db-import <specifier>` | Where the Drizzle client lives when it is not beside the schema |
-| `--auth-import <specifier>` | Where your auth instance lives |
-| `--contact-table <name>` | Force the contact entity table |
-| `--company-table <name>` | Force the company entity table |
-| `--force` | Overwrite generated files / `.env` values |
-| `--no-login` | Skip the browser pairing step |
-| `--no-browser` | Print the approval URL instead of opening it |
+| `--dry-run` | Show what would be written; write nothing |
+| `--diff` | Show a diff for files that already exist |
+| `--force` | Overwrite the files Clivly owns |
+| `--yes` | Skip prompts |
+| `--no-login` | Skip browser pairing |
+| `--no-browser` | Pair, but print the URL instead of opening it |
+| `--schema <path\|package>` | Where your Drizzle tables live |
+| `--db-import <specifier>` | Where the Drizzle instance lives, when it is not beside the schema. Accepts `@acme/database#database` to name the export |
+| `--auth-import <specifier>` | Where your better-auth instance lives. Same `#exportName` form. Overrides on-disk probing, which cannot see across a package boundary |
+| `--contact-table <name>` | Use this table as the contact entity, skipping the naming heuristics |
+| `--company-table <name>` | Same for companies |
+
+`--contact-table` and `--company-table` accept either the SQL table name or the
+name it is exported under in your schema module — whichever you have in front of
+you.
+
+When `init` finishes and `CLIVLY_SECRET_KEY` is still empty, it hands you
+straight into `clivly login` so you don't end up staring at a blank env file.
+That step is interactive, so it is skipped automatically when there is no TTY or
+when `CI` is set.
+
+#### Framework support
+
+Route scaffolding exists for these five. Anywhere else, mount the handler
+yourself — it is a plain `(Request) => Promise<Response>`.
+
+| Framework | Tick route written |
+| --- | --- |
+| Next.js | `app/api/clivly/tick/route.ts` (or `src/app/…`) |
+| TanStack Start | `src/routes/api/clivly/tick.ts` |
+| SvelteKit | `src/routes/api/clivly/tick/+server.ts` |
+| Remix | `app/routes/api.clivly.tick.ts` |
+| Nuxt | `server/api/clivly/tick.ts` |
+
+Plain Vue apps can still integrate Clivly, but they need a manual server layer
+for the tick route unless they are on Nuxt.
 
-If no usable contact entity can be found, `init` writes nothing rather than
-generating a broken config.
+#### ORM support
 
-Supported first-class route scaffolding today:
+`init` generates a config for **Drizzle only**. Prisma and Kysely projects
+integrate through a hand-written `fetchPage` source — see the
+[Non-Drizzle sources](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md#non-drizzle-sources)
+section of the guide.
 
-- Next.js
-- TanStack Start
-- SvelteKit
-- Remix
-- Nuxt
+Use `--schema` when your Drizzle schema is not in a common location or in
+`drizzle.config.ts`.
 
-## `clivly add widget`
+#### Monorepos
+
+In a workspace, `init` reads your `pnpm-workspace.yaml` (or `workspaces` array)
+and imports anything owned by a *sibling* package by **package name** rather
+than by a relative path that climbs out of your app:
+
+```ts
+import * as schema from "@acme/database"; // not "../../packages/database/src/index"
+```
+
+`--schema` accepts a package specifier as well as a path:
 
 ```bash
-npx clivly add widget
+npx clivly init --schema @acme/database                  # the package entry
+npx clivly init --schema @acme/database/src/schema.ts    # a subpath inside it
+npx clivly init --schema ./src/db/schema.ts              # a plain path
+```
+
+A real file always wins over a same-named package, so existing relative paths
+keep their meaning.
+
+#### When no contact entity can be found
+
+`init` **writes nothing** rather than scaffolding a config that cannot compile.
+Clivly needs one entity before a config will load, and it will not invent one:
+
 ```
+No usable contact entity
 
-Scaffolds the host-side widget session route that mounts
-`createChatSessionHandler()` from `clivly/sdk`. It is idempotent and supports
-`--dry-run` and `--force`.
+  Tables in @acme/database:
+    widgets
+    invoices
+
+  Pick the one that holds your people and re-run:
+    clivly init --schema @acme/database --contact-table widgets
+
+  Nothing was written — Clivly needs one entity before a config can load.
+```
 
-## `clivly login`
+---
+
+### `clivly login`
 
 ```bash
 npx clivly login [--force] [--rotate] [--api-url <url>] [--no-browser]
 ```
 
-Pairs this machine with a Clivly workspace and writes:
+Pairs this machine with a Clivly workspace and writes `CLIVLY_SECRET_KEY` and
+`CLIVLY_SYNC_TRIGGER_SECRET` into your project's env file. It creates a pairing
+session, prints (and by default opens) an approval link, and waits while you
+approve it in a signed-in browser. The approval link is always printed, so an
+SSH or headless session can be approved by opening the link elsewhere.
+
+| Flag | Effect |
+| --- | --- |
+| `--no-browser` | Print the approval URL without opening a browser |
+| `--force` | Overwrite env values that already have a real value. Without it, existing values are kept and reported as skipped; an empty placeholder (`CLIVLY_SECRET_KEY=`) is always filled in |
+| `--rotate` | Rotate the workspace's remote-sync trigger secret instead of revealing the current one. **Your already-deployed app stops receiving sync triggers until you redeploy it with the new secret** |
+| `--api-url <url>` | Point at a non-default backend |
+
+Before anything is written, the CLI prints which workspace approved the pairing
+and asks you to confirm. Declining writes nothing and exits non-zero. In a
+non-interactive run (no TTY, or `CI` set) the workspace is still printed but you
+are not prompted, so scripted pairing cannot hang.
+
+#### Which env file gets written
 
-- `CLIVLY_SECRET_KEY`
-- `CLIVLY_SYNC_TRIGGER_SECRET`
+The CLI follows your framework's convention. This is not cosmetic on Workers:
+wrangler reads `.dev.vars` and nothing else, so credentials written to `.env`
+would never load.
 
-into your project's `.env`.
+| Framework | Env file |
+| --- | --- |
+| Next.js | `.env.local` |
+| TanStack Start, SvelteKit, Remix, Nuxt | `.env` |
+| Hono on Cloudflare Workers | `.dev.vars` |
+| Anything else | `.env` |
 
-The approval URL is always printed, so headless or SSH sessions can still be
-approved in another browser.
+#### Pairing availability
 
-Notes:
+The pairing endpoints are feature-flagged server-side
+(`CLIVLY_CLI_PAIRING_ENABLED`). **Clivly Cloud has pairing enabled**, so
+`clivly login` is the normal path there. The flag defaults to `false`, so a
+self-hosted backend must opt in — otherwise `clivly login` says so and exits
+non-zero.
 
-- `--force` overwrites existing real values
-- `--rotate` rotates the remote-sync trigger secret instead of revealing the
-  current one
-- pairing is feature-flagged server-side with `CLIVLY_CLI_PAIRING_ENABLED`
+#### Manual credential path
 
-If pairing is unavailable, you can still set credentials manually and then run
-`clivly status`.
+If pairing is unavailable, every credential can be set by hand. Nothing about
+the CLI requires pairing.
 
-## `clivly status`
+| Value | Where to get it | Notes |
+| --- | --- | --- |
+| `CLIVLY_SECRET_KEY` | Dashboard → **Connect app**, or **Settings → API keys** | **Shown once.** Copy it immediately; you cannot retrieve it later, only regenerate. Regenerating **revokes the previous key**, so redeploy after rotating. The legacy name `CLIVLY_API_KEY` is still accepted as a fallback |
+| `CLIVLY_SYNC_TRIGGER_SECRET` | Dashboard → **Integrations → Remote sync** | Must match the value in your app's env exactly. A mismatch surfaces as a `401` on the signed trigger |
+| `CLIVLY_SYNC_TRIGGER_URL` | Your own deployment | The public URL of your mounted tick route, e.g. `https://app.example.com/api/clivly/tick`. Optional until you deploy — push-only setups can leave it unset |
+| `CLIVLY_PUBLISHABLE_KEY` | Same place as the secret key | Only needed for the chat widget. Safe to expose in client code |
+
+Write them into the env file of the package that imports `clivly`, then re-run
+`clivly status` to confirm each step goes green.
+
+> **Running your own Clivly backend?** `CLIVLY_TRIGGER_SECRET_WRAPPING_KEY` (a
+> 32-byte hex key) is a **hard production prerequisite** for pairing. The
+> trigger secret is stored encrypted with it, so without the key set on the
+> server, `clivly login` fails with a 500 at the moment it would hand over
+> credentials. Set it before enabling `CLIVLY_CLI_PAIRING_ENABLED`.
+
+---
+
+### `clivly status`
 
 ```bash
 npx clivly status [--verbose] [--config <path>] [--env-file <path>]
 ```
 
-Walks the setup one rung at a time: credentials, config, schema, sources, and
-connectivity. This is the main diagnostic command for integration issues.
+Walks your setup one step at a time and stops at the first thing that isn't
+ready, telling you what to do about it. **This is the command to reach for when
+something isn't working.** It is read-only and writes nothing.
+
+The ladder: credential → Clivly reachable → `clivly.config` loads →
+`clivly.config` is edge-safe → setup checks → sync trigger URL.
+
+| Flag | Effect |
+| --- | --- |
+| `--verbose` | Show every check, including those that passed |
+| `--config <path>` | Path to `clivly.config.ts` (needed in a monorepo) |
+| `--env-file <path>` | Extra env file to load. Repeatable; later files win |
+
+```bash
+npx clivly status --config ./apps/web/clivly.config.ts
+npx clivly status --env-file ../server/.env
+```
+
+Env precedence, strongest first: **real environment → `--env-file` / the
+`envFiles` array in `clivly.cli.ts` → `.env.local` → `.env`**.
+
+---
 
-## `clivly dev`
+### `clivly add widget`
+
+```bash
+npx clivly add widget [--force] [--dry-run]
+```
+
+Writes the route that mints chat-widget sessions, for your detected framework
+(e.g. `app/api/clivly/widget/session/route.ts` on Next.js). Idempotent.
+
+It creates **no widget record** — that lives in the Clivly dashboard under
+**Settings → Chat widget**. See
+[Adding the chat widget](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
+for the full flow.
+
+| Flag | Effect |
+| --- | --- |
+| `--dry-run` | Show what would be written; write nothing |
+| `--force` | Overwrite the route if it already exists |
+
+---
+
+### `clivly push-schema`
+
+```bash
+npx clivly push-schema [--config <path>]
+```
+
+Sends your discovered tables and columns to Clivly so the dashboard can offer
+them for mapping — without deploying your app. Reads your config; writes nothing
+locally. **Table and column names only; never row data.**
+
+---
+
+### `clivly dev`
 
 ```bash
 npx clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]
 ```
 
 Opens a `cloudflared` tunnel to your local app and registers it with Clivly for
-the lifetime of the session, so remote sync can reach `localhost` during local
-development. The override is cleared on exit.
+the length of the session, so remote sync can reach `localhost` while you
+develop. Your dev server is detected from `package.json` scripts, or pass it
+explicitly after `--`. Needs `cloudflared` on `PATH` and `CLIVLY_SECRET_KEY`
+set. The override is cleared when the process exits; remote sync is otherwise
+deploy-only.
+
+```bash
+npx clivly dev --port 3000 -- npm run dev
+```
 
-Requires:
+It also watches `clivly.config.ts` and tells you when it changes. It cannot
+reload it for you — the config belongs to your app's process, not to the CLI.
 
-- `cloudflared` on `PATH`
-- `CLIVLY_SECRET_KEY` set
+If registration fails, the warning names the cause: an invalid key, a backend
+without the endpoint enabled, an HTTP status Clivly returned, or a genuine
+network failure. Your app keeps running either way, and outbound sync (your app
+→ Clivly) is unaffected — only dashboard-triggered sync needs the tunnel.
 
-## `clivly push-schema`
+| Flag | Effect |
+| --- | --- |
+| `--port <n>` | Local port your app listens on |
+| `--route-path <path>` | Path to your mounted tick route |
+| `--api-url <url>` | Point at a non-default backend |
+
+---
+
+### Deprecated aliases
+
+`ping`, `connect` and `doctor` each run part of the `status` ladder. They still
+work, and are kept because output and docs have recommended them — but prefer
+`clivly status`, which runs the whole ladder and tells you which step you are on.
+
+| Alias | Equivalent scope |
+| --- | --- |
+| `clivly ping` | Credential + reachability |
+| `clivly connect` | The above, plus config and trigger URL |
+| `clivly doctor` | Config, setup checks and edge safety |
+
+Each prints a deprecation notice, then the steps it covers, renumbered to its own
+scope:
 
 ```bash
-npx clivly push-schema [--config <path>]
+$ npx clivly ping
+`clivly ping` is a deprecated alias that runs part of `clivly status`. Prefer `clivly status`.
+
+Clivly status
+  ✅ Step 1 of 2 · API key present — Secret key is set.
+  ✅ Step 2 of 2 · Clivly reachable — Reached org: acme (org_1)
 ```
 
-Reports your discovered schema to Clivly without waiting for a deployed app to
-heartbeat it first.
+`clivly doctor` runs the same read-only checks as `await clivly.doctor()` in
+code: API key present, entities configured, sources configured, concept
+coverage, Drizzle cursor/id columns, sample fetch, mapping dry-run,
+custom-object slugs, heartbeat, and namespace reachability.
 
-## `clivly ping` / `clivly doctor`
+---
 
-`clivly ping` sends one heartbeat and prints a terse pass/fail result.
+## Runtime imports
 
-`clivly doctor` loads your config and runs the same read-only checks exposed by
-`await clivly.doctor()`.
+`clivly` is the consolidated public package. Application code imports from typed
+subpaths:
 
-## Telemetry
+```ts
+import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
+import { fromDrizzle, discoverFromDrizzle } from "clivly/drizzle";
+import { clivlyVite } from "clivly/vite";
+import { createClerkAuthAdapter } from "clivly/auth/clerk";
+import { createWorkOSAuthAdapter } from "clivly/auth/workos";
+import { createBetterAuthAdapter } from "clivly/auth/better-auth";
+```
 
-Clivly collects no telemetry. The CLI makes network requests only to the
-Clivly API you point it at, and only to do the work you asked for: pairing,
-heartbeats, schema pushes, status checks, and tunnel override registration.
+> **Never `import` from the bare `clivly` specifier.** The package root is the
+> CLI binary — it imports `node:fs` and `node:child_process` at module scope, so
+> importing it from app code drags the whole CLI into your bundle and throws at
+> import time on Workers and other edge runtimes.
+
+Provider and framework integrations use **optional peer dependencies**. Install
+only what your app actually uses:
+
+| Subpath | Peer dependency |
+| --- | --- |
+| `clivly/drizzle` | `drizzle-orm` |
+| `clivly/vite` | `vite` |
+| `clivly/auth/clerk` | `@clerk/backend` |
+| `clivly/auth/workos` | `@workos-inc/node` |
+| `clivly/auth/better-auth` | none — you pass your own `betterAuth({...})` instance |
+
+`clivly/core/*` is deprecated in favour of `clivly/internal/*`. It still
+resolves, and emits a one-time `process.emitWarning` naming the replacement (so
+it stays off stdout and cannot corrupt machine-readable CLI output). See
+[STABILITY.md](https://github.com/amani-joseph/clivly.com/blob/master/STABILITY.md).
+
+---
+
+## Common errors
+
+| Symptom | Fix |
+| --- | --- |
+| Generated code doesn't match these docs | `npx clivly --version` — an older installed version is the usual cause |
+| `init` refuses to write, "No usable contact entity" | Pass `--contact-table <name>` |
+| `init` cannot find your schema | Pass `--schema <path\|package>` |
+| `init` scaffolded a `db` import that doesn't resolve | The probe cannot evaluate a db module that throws without `DATABASE_URL`. Fix the `TODO(clivly)` import path it left, or pass `--db-import` |
+| `clivly login` exits non-zero, pairing unavailable | The backend has `CLIVLY_CLI_PAIRING_ENABLED` off. Use the manual credential path above |
+| `clivly dev` cannot start | Install `cloudflared`, or set `CLIVLY_SYNC_TRIGGER_URL` to a tunnel you run yourself |
+| Credentials written but the app never loads them | Wrong env file for your framework — see the table under `clivly login` |
+
+The full troubleshooting table is in the
+[integration guide](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md#8-common-errors-and-troubleshooting).
+
+---
+
+## Telemetry
 
-See the telemetry section in:
-[SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md#telemetry)
+**Clivly collects no telemetry.** The CLI makes network requests only to the
+Clivly API you point it at, and only to do what you asked: pairing, heartbeats,
+schema pushes, and status checks. No usage analytics, no crash reporting, no
+phone-home. See
+[SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md#telemetry).
 
-## More docs
+## Related documentation
 
-- Cloud onboarding guide:
-  [Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)
-- Chat widget guide:
-  [Adding the chat widget](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
-- SDK docs:
-  [packages/sdk/README.md](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md)
-- Release notes:
-  [CHANGELOG.md](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
+- **[Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)** — the canonical end-to-end guide
+- [Adding the chat widget](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
+- [`@clivly/sdk` README](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md) — the runtime API surface
+- [STABILITY.md](https://github.com/amani-joseph/clivly.com/blob/master/STABILITY.md) — import tiers
+- [SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md)
+- [CHANGELOG.md](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
 
 ## License
 

package/drizzle.cjs

@@ -65,11 +65,15 @@ function fromDrizzle(db, table, opts) {
 	const idColumn = columns[idField];
 	if (!cursorColumn) throw new Error(`fromDrizzle: cursorField "${opts.cursorField}" is not a column on "${(0, drizzle_orm.getTableName)(table)}".`);
 	if (!idColumn) throw new Error(`fromDrizzle: idField "${idField}" is not a column on "${(0, drizzle_orm.getTableName)(table)}".`);
+	const projection = {};
+	for (const column of Object.values(columns)) projection[column.name] = column;
+	const cursorColumnName = cursorColumn.name;
+	const idColumnName = idColumn.name;
 	const source = {
 		entity: opts.entity,
-		cursorField: opts.cursorField,
-		idField,
-		fetchPage: ({ since, limit }) => drizzleDb.select().from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit)
+		cursorField: cursorColumnName,
+		idField: idColumnName,
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? drizzle_orm.sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy((0, drizzle_orm.asc)(cursorColumn), (0, drizzle_orm.asc)(idColumn)).limit(limit)
 	};
 	const meta = {
 		columnKeys: Object.keys(columns),

package/drizzle.d.cts

@@ -1,14 +1,6 @@
 import { t as discoverFromDrizzle } from "./drizzle-DmeKSqeF.cjs";
-import { n as SyncSource } from "./types-CsL0rFYh.cjs";
+import { m as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-DRzOtaRT.cjs";
 import { Table } from "drizzle-orm";
-//#region ../sdk/src/namespace-probe.d.ts
-interface NamespaceIntrospector {
-  /** All base table names in the reachable schema. */
-  listTables(): Promise<string[]>;
-  /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
-  sampleSelect(table: string): Promise<void>;
-}
-//#endregion
 //#region ../sdk/src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;

package/drizzle.d.mts

@@ -1,14 +1,6 @@
 import { t as discoverFromDrizzle } from "./drizzle-CFOr9dU9.mjs";
-import { n as SyncSource } from "./types-CsL0rFYh.mjs";
+import { m as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-B4WE45TH.mjs";
 import { Table } from "drizzle-orm";
-//#region ../sdk/src/namespace-probe.d.ts
-interface NamespaceIntrospector {
-  /** All base table names in the reachable schema. */
-  listTables(): Promise<string[]>;
-  /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
-  sampleSelect(table: string): Promise<void>;
-}
-//#endregion
 //#region ../sdk/src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;

package/drizzle.mjs

@@ -64,11 +64,15 @@ function fromDrizzle(db, table, opts) {
 	const idColumn = columns[idField];
 	if (!cursorColumn) throw new Error(`fromDrizzle: cursorField "${opts.cursorField}" is not a column on "${getTableName(table)}".`);
 	if (!idColumn) throw new Error(`fromDrizzle: idField "${idField}" is not a column on "${getTableName(table)}".`);
+	const projection = {};
+	for (const column of Object.values(columns)) projection[column.name] = column;
+	const cursorColumnName = cursorColumn.name;
+	const idColumnName = idColumn.name;
 	const source = {
 		entity: opts.entity,
-		cursorField: opts.cursorField,
-		idField,
-		fetchPage: ({ since, limit }) => drizzleDb.select().from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
+		cursorField: cursorColumnName,
+		idField: idColumnName,
+		fetchPage: ({ since, limit }) => drizzleDb.select(projection).from(table).where(since ? sql`(${cursorColumn}, ${idColumn}) > (${since.time}, ${since.id})` : void 0).orderBy(asc(cursorColumn), asc(idColumn)).limit(limit)
 	};
 	const meta = {
 		columnKeys: Object.keys(columns),