@tailor-platform/sdk 2.16.0 → 2.17.0

package/dist/vitest/mocks/tailordb-pglite.d.mts

@@ -29,10 +29,11 @@ interface CreatedClient {
  * PGlite instances are borrowed, never closed — close them yourself (e.g. in
  * `afterAll`).
  *
- * Create the tables a test needs up front with `CREATE TABLE` statements
- * matching the generated Kysely types. PGlite runs full PostgreSQL while
- * TailorDB supports a subset of it, so a statement passing here can still be
- * rejected by the platform.
+ * Create the tables a test needs up front: run the script `kyselyTypePlugin`
+ * writes when `pgliteSchemaPath` is set, or your own `CREATE TABLE`
+ * statements matching the generated Kysely types. PGlite runs full PostgreSQL
+ * while TailorDB supports a subset of it, so a statement passing here can
+ * still be rejected by the platform.
  *
  * Transactions on a shared instance are serialized: while one is open,
  * queries from other `getDB` instances on the same PGlite instance wait for

package/docs/cli/tailordb.md

@@ -177,19 +177,19 @@ tailor tailordb migration script [options] <number>
 
 **Options**
 
-| Option                    | Alias | Description                                                                                           | Required | Default              | Env                  |
-| ------------------------- | ----- | ----------------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
-| `--config <CONFIG>`       | `-c`  | Path to Tailor config file                                                                            | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
-| `--namespace <NAMESPACE>` | `-n`  | Target TailorDB namespace (required if multiple namespaces exist)                                     | No       | -                    | -                    |
-| `--no-script`             | -     | Record that this migration intentionally runs without a migration script (requires --reason)          | No       | -                    | -                    |
-| `--reason <REASON>`       | -     | Reason why no migration script is needed (used with --no-script)                                      | No       | -                    | -                    |
-| `--with-test`             | -     | Also add a migrate.test.ts unit-test scaffold; when migrate.ts already exists, only the test is added | No       | -                    | -                    |
+| Option                    | Alias | Description                                                                                  | Required | Default              | Env                  |
+| ------------------------- | ----- | -------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
+| `--config <CONFIG>`       | `-c`  | Path to Tailor config file                                                                   | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
+| `--namespace <NAMESPACE>` | `-n`  | Target TailorDB namespace (required if multiple namespaces exist)                            | No       | -                    | -                    |
+| `--no-script`             | -     | Record that this migration intentionally runs without a migration script (requires --reason) | No       | -                    | -                    |
+| `--reason <REASON>`       | -     | Reason why no migration script is needed (used with --no-script)                             | No       | -                    | -                    |
+| `--with-test`             | -     | Also add the migrate.test.ts and migrate.pglite.test.ts scaffolds                            | No       | -                    | -                    |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Notes**
 
-When `migrate.ts` already exists, running the command clears a previously recorded `--no-script` acknowledgment.
+When `migrate.ts` already exists, running the command clears a previously recorded `--no-script` acknowledgment, and `--with-test` adds only the tests that do not exist yet (writing `db.pglite.ts` if it is missing). `migrate.pglite.test.ts` is scaffolded only when `@electric-sql/pglite` is installed in the project.
 
 #### tailordb migration set
 

package/docs/cli-reference.md

@@ -210,9 +210,13 @@ Resolution rules:
 - **Lookup order:** the project's `node_modules/.bin` (nearest first, walking up from the current
   directory), then your `PATH`. So a plugin installed as a project dev-dependency takes precedence over a
   globally installed one.
-- **Place global flags after the plugin command.** Only the arguments following the plugin name are
-  forwarded; a global flag placed before it (e.g. `tailor --json tailordb erd export`) is consumed by
-  the host CLI and does not reach the plugin. Write `tailor tailordb erd export --json` instead.
+- **Global flags reach the plugin from either side.** `tailor --json tailordb erd export` and
+  `tailor tailordb erd export --json` both forward `--json`, and likewise `--verbose` and the
+  `--env-file` options. A flag typed before the plugin name is consumed by the host CLI first and
+  then forwarded, so when the same flag appears on both sides the later one wins. A flag the host
+  does not define — including one only some commands declare, such as `--profile` — still has to be
+  typed after the plugin's own subcommand. `--help` and `--version` are answered by the host CLI and
+  never dispatch a plugin.
 
 Because resolution is based on `node_modules/.bin` and `PATH`, any package manager that populates
 `node_modules/.bin` works for project-local plugins — npm, pnpm (its content-addressable store is

package/docs/services/tailordb-migration.md

@@ -24,7 +24,8 @@ migrations/
 ├── 0001/                    # First change
 │   ├── diff.json            # Field-level diff from 0000
 │   ├── migrate.ts           # Data migration script (auto-generated for breaking changes; can be added manually via `migration script`)
-│   └── db.ts                # Kysely types for the script (pre-migration shape)
+│   ├── db.ts                # Kysely types for the script (pre-migration shape)
+│   └── db.pglite.ts         # CREATE TABLE script of that shape, for PGlite tests
 ├── 0002/
 │   └── diff.json            # No script — non-breaking changes only
 └── ...
@@ -129,7 +130,7 @@ No `migrate.ts` is generated automatically because the schema change itself is n
 tailor tailordb migration script 0002
 ```
 
-This writes `migrations/0002/migrate.ts` and `migrations/0002/db.ts` next to the existing `diff.json` (add `--with-test` to also scaffold a `migrate.test.ts` — see [Testing Migrations Locally](#testing-migrations-locally)). The removed field stays readable inside `migrate.ts` because the pre-migration phase keeps it on the table until the script finishes (see [Per-migration phases](#per-migration-phases)). The next `tailor deploy` runs the script automatically — `migrate.ts` is executed whenever the file exists on disk, regardless of whether the diff itself required it.
+This writes `migrations/0002/migrate.ts`, `migrations/0002/db.ts`, and `migrations/0002/db.pglite.ts` next to the existing `diff.json` (add `--with-test` to also scaffold the tests — see [Testing Migrations Locally](#testing-migrations-locally)). The removed field stays readable inside `migrate.ts` because the pre-migration phase keeps it on the table until the script finishes (see [Per-migration phases](#per-migration-phases)). The next `tailor deploy` runs the script automatically — `migrate.ts` is executed whenever the file exists on disk, regardless of whether the diff itself required it.
 
 If the data loss is intentional and no script is needed, record that decision the same way as for breaking changes (see [Breaking changes without a script](#breaking-changes-without-a-script)):
 
@@ -267,13 +268,15 @@ export default defineConfig({
 
 ## Generated Files
 
-| File                   | When generated                                                                                                                            | Description                                                                                                              |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `0000/schema.json`     | First `migration generate`                                                                                                                | Full snapshot of all tables in the namespace.                                                                            |
-| `XXXX/diff.json`       | Every subsequent migration                                                                                                                | Field-level diff against the previous snapshot.                                                                          |
-| `XXXX/migrate.ts`      | Auto-generated for breaking changes and `--data-only` migrations; added manually via `tailordb migration script` for warning-tier changes | Data transformation script. The `main` export receives a Kysely `Transaction`.                                           |
-| `XXXX/db.ts`           | Generated once when `migrate.ts` is created                                                                                               | Kysely types reflecting the schema **before** this migration. Exports `Database`, `Transaction`, and `MigrationContext`. |
-| `XXXX/migrate.test.ts` | Added via `tailordb migration script --with-test`                                                                                         | Unit-test scaffold for `migrate.ts` (see [Testing Migrations Locally](#testing-migrations-locally)). Never deployed.     |
+| File                          | When generated                                                                                                                            | Description                                                                                                              |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `0000/schema.json`            | First `migration generate`                                                                                                                | Full snapshot of all tables in the namespace.                                                                            |
+| `XXXX/diff.json`              | Every subsequent migration                                                                                                                | Field-level diff against the previous snapshot.                                                                          |
+| `XXXX/migrate.ts`             | Auto-generated for breaking changes and `--data-only` migrations; added manually via `tailordb migration script` for warning-tier changes | Data transformation script. The `main` export receives a Kysely `Transaction`.                                           |
+| `XXXX/db.ts`                  | Generated once when `migrate.ts` is created                                                                                               | Kysely types reflecting the schema **before** this migration. Exports `Database`, `Transaction`, and `MigrationContext`. |
+| `XXXX/db.pglite.ts`           | Generated with `db.ts`                                                                                                                    | `CREATE TABLE` script of the same schema, for running `migrate.ts` on PGlite. Never deployed.                            |
+| `XXXX/migrate.test.ts`        | Added via `tailordb migration script --with-test`                                                                                         | Unit-test scaffold for `migrate.ts` (see [Testing Migrations Locally](#testing-migrations-locally)). Never deployed.     |
+| `XXXX/migrate.pglite.test.ts` | Added via `tailordb migration script --with-test` when `@electric-sql/pglite` is installed                                                | PGlite test scaffold for `migrate.ts`. Never deployed.                                                                   |
 
 `db.ts` reflects the pre-migration schema because the script runs after the pre-migration phase has temporarily relaxed breaking constraints (e.g., a new `required` field is added as `optional` first), so the data being read still matches the previous shape.
 
@@ -811,7 +814,7 @@ Scaffold a ready-to-fill test next to the script with:
 tailor tailordb migration script 0005 --with-test
 ```
 
-When `migrate.ts` already exists (the usual case for breaking changes, where `migration generate` creates it), the command adds only `migrate.test.ts`. Or write the test by hand:
+When `migrate.ts` already exists (the usual case for breaking changes, where `migration generate` creates it), the command adds only the tests that do not exist yet, plus a missing `db.pglite.ts`. Or write the test by hand:
 
 ```typescript
 // migrations/0005/migrate.test.ts
@@ -845,30 +848,24 @@ A statement-level test verifies what the script issues, not what it does to data
 npm install -D @electric-sql/pglite
 ```
 
-Create the tables the script touches (matching the shape in the generated `db.ts`), stage rows, then run the script in a transaction. Type the instance with `Unmigrated<Database>` rather than `Database`: `db.ts` types a column the migration makes required as `T | null` on read but `T` on write (and an enum it narrows as the old values on read but the new ones on write), so that `migrate.ts` cannot write what the migration is removing — which would also stop the test from staging the rows the script has to convert. `Unmigrated` lets every column be written with whatever it can still be read as; `main` still receives a `Transaction<Database>`.
+The generated `db.pglite.ts` exports the `CREATE TABLE` script for the same schema `db.ts` types — the tables as the pre-migration phase leaves them while `migrate.ts` runs, including relaxed constraints, renamed fields under both names, and retained removed fields. Run it once on the PGlite instance, stage rows, then run the script in a transaction. `tailor tailordb migration script <N> --with-test` scaffolds this test too when `@electric-sql/pglite` is installed. Type the instance with `Unmigrated<Database>` rather than `Database`: `db.ts` types a column the migration makes required as `T | null` on read but `T` on write (and an enum it narrows as the old values on read but the new ones on write), so that `migrate.ts` cannot write what the migration is removing — which would also stop the test from staging the rows the script has to convert. `Unmigrated` lets every column be written with whatever it can still be read as; `main` still receives a `Transaction<Database>`.
 
 ```typescript
 // migrations/0005/migrate.pglite.test.ts
 import { PGlite } from "@electric-sql/pglite";
-import { sql } from "@tailor-platform/sdk/kysely";
 import { createKyselyPGlite, type Unmigrated } from "@tailor-platform/sdk/vitest";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import type { Database } from "./db";
+import { pgliteSchema } from "./db.pglite";
 import { main } from "./migrate";
 
-const db = createKyselyPGlite<Unmigrated<Database>>(new PGlite());
+const pglite = new PGlite();
+const db = createKyselyPGlite<Unmigrated<Database>>(pglite);
 
+// PGlite loads Postgres on first use, which can take longer than the default hook timeout.
 beforeAll(async () => {
-  await sql`
-    CREATE TABLE "User" (
-      "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-      "name" text NOT NULL,
-      "email" text,
-      "createdAt" timestamptz NOT NULL,
-      "updatedAt" timestamptz NOT NULL
-    )
-  `.execute(db);
-});
+  await pglite.exec(pgliteSchema.tailordb);
+}, 60_000);
 
 afterAll(async () => {
   await db.destroy();
@@ -896,10 +893,14 @@ describe("0005 add required email", () => {
 });
 ```
 
+Pass nested field values as JavaScript objects or arrays of objects, without `JSON.stringify`.
+Generated migration types use `Record<string, unknown>` for each nested object so scripts can
+work with both old and new members during a migration; narrow member values before using them.
+
 Two caveats keep this from replacing a scratch workspace:
 
 - PGlite runs full PostgreSQL, while TailorDB supports [a subset of it](https://docs.tailor.tech/guides/function/accessing-tailordb#supported-sql-queries) — a statement that passes here can still be rejected on deploy.
-- The `CREATE TABLE` statements are yours, so they can drift from the schema the platform actually has.
+- `db.pglite.ts` mirrors the column shape, not the platform: hooks, validations, and permissions do not run, and the limits listed under [Real SQL execution with PGlite](../testing.md#real-sql-execution-with-pglite-mocktailordbwithpglite) apply.
 
 ### Beyond unit tests
 

package/docs/testing.md

@@ -149,26 +149,30 @@ Pass `{ onUnhandled: "error" }` to make an unmatched query fail instead of retur
 
 Instead of staging responses, back TailorDB with [`@electric-sql/pglite`](https://pglite.dev/) — an in-memory PostgreSQL (install it as a devDependency) — so the queries a resolver, executor, or workflow job issues through `getDB()` execute against real data. `getDB(namespace)` needs no test-side swap: acquire the mock, and each namespace you list resolves to its PGlite instance.
 
-Create the tables the test touches with `CREATE TABLE` statements matching the generated Kysely types — `text` for string and enum fields, `timestamptz` for date/datetime, `jsonb` for nested objects. The schema only has to match what your code reads and writes, not TailorDB's storage; relations are not enforced.
+Let `kyselyTypePlugin` generate the `CREATE TABLE` script for you: set `pgliteSchemaPath` next to `distPath`, and `tailor generate` writes a module exporting one script per namespace, derived from the same table definitions as the Kysely types.
+
+```typescript
+// tailor.config.ts
+kyselyTypePlugin({
+  distPath: "./generated/db.ts",
+  pgliteSchemaPath: "./generated/db.pglite.ts",
+});
+```
+
+Run the namespace's script once per PGlite instance. Every statement is `IF NOT EXISTS`, so applying it again to an instance that already has the tables is harmless.
 
 ```typescript
 import { PGlite } from "@electric-sql/pglite";
 import { mockTailordbWithPGlite } from "@tailor-platform/sdk/vitest";
 import { afterAll, beforeAll, expect, test } from "vitest";
 import { getDB } from "../generated/db";
+import { pgliteSchema } from "../generated/db.pglite";
 import resolver from "./upsertUsers";
 
 const pglite = new PGlite();
 
 beforeAll(async () => {
-  await pglite.exec(`
-    CREATE TABLE "User" (
-      "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-      "name" text NOT NULL,
-      "email" text NOT NULL,
-      "age" integer NOT NULL
-    );
-  `);
+  await pglite.exec(pgliteSchema["main-db"]);
 });
 
 afterAll(async () => {
@@ -201,21 +205,19 @@ test("upserts against real rows", async () => {
 });
 ```
 
-A `.serial()` field is omitted from generated `getDB()` inserts, so its PGlite column must generate a value. Use an identity for an integer serial. For a formatted string serial, create a sequence and reproduce the format in its `DEFAULT` expression:
+The generated columns follow the Kysely types, not TailorDB's storage: `text` for string and enum fields, `timestamptz` for datetime, `date` and `time` for date and time, `numeric` for decimal, rounded to the configured scale and read back with exactly that many fractional digits, `jsonb` for nested objects (and arrays of them), Postgres arrays for other array fields. `id` is a generated `uuid` primary key, `.unique()` fields and unique `.indexes()` are enforced, so `ON CONFLICT` upserts behave, and `.default()` values become column defaults (`"now"` becomes the current time). `.serial()` fields are assigned by the database from the configured `start`, `maxValue`, and format. Relations are not enforced.
 
-```sql
-CREATE SEQUENCE "invoiceNumberSequence" START WITH 1000;
-CREATE TABLE "Invoice" (
-  "sequentialId" integer GENERATED BY DEFAULT AS IDENTITY (START WITH 1),
-  "invoiceNumber" text NOT NULL
-    DEFAULT ('INV-' || lpad(nextval('"invoiceNumberSequence"')::text, 5, '0'))
-);
-```
+What the script cannot reproduce:
+
+- Hooks, validations, and permissions do not run. A required field whose value only its own field-level create hook supplies is created nullable, so inserts that omit it succeed; give it a `.default()` if the test reads it back. A field filled by a table-level hook stays `NOT NULL`, as its Kysely type still requires it on insert.
+- Serial formats are reproduced for a single `%d`, `%x`, or `%X` specifier with an optional zero-padded width; an octal `%o` format fails generation with an error naming the field.
+- A datetime inside a nested object reads back as a string from `jsonb`, not a `Date`.
+- On a persistent PGlite (`dataDir`), tables created by an earlier run are kept as they were; drop them or start from an empty directory after changing a table definition.
 
-PGlite does not apply the TailorDB `.serial()` configuration itself. Match the `start`, `format`, and any limit that the behavior under test relies on.
+To hand-write DDL instead — for a table not in the schema, or to add a constraint — run your own statements after the script, or without it.
 
 - The PGlite instance is yours: the mock never closes it, so close it in `afterAll`. Reuse one instance across a suite — creating one per test is slow.
-- Pass the same instance under several namespaces to drive them against one shared database.
+- Pass the same instance under several namespaces to drive them against one shared database. Two namespaces with a same-named table cannot share one instance, because the second script leaves the first table as it is.
 - Seed through `getDB` itself. When a column type rejects a value that only the test must stage, use `createKyselyPGlite<Unmigrated<...>>(pglite)` instead — see [Testing Migrations Locally](./services/tailordb-migration.md#testing-migrations-locally). This only affects test setup; it cannot supply a `.serial()` value for an insert issued by the code under test.
 - Transactions on a shared instance are serialized: while one is open, queries from other `getDB` instances wait. Do not use `test.concurrent` with a shared instance, and do not query the same instance through a second `getDB` from inside a transaction — that waits on itself.
 - PGlite runs full PostgreSQL while TailorDB supports a subset of it, and TailorDB hooks, validations, and permissions do not run here — a test passing on PGlite can still behave differently on the platform. Keep [`mockTailordb`](#tailordb-mock) or [`createKyselyMock`](#kysely-layer-mock-createkyselymock) tests for query shape and error paths, and E2E tests for platform behavior.
@@ -666,7 +668,7 @@ describe("upsertUsers resolver", () => {
 
 Reach for [`mockTailordb`](#mocking-the-tailordb-client) instead when you want to drive the raw query sequence at the `tailordb.Client` level rather than at the Kysely layer, or [`mockTailordbWithPGlite`](#real-sql-execution-with-pglite-mocktailordbwithpglite) to execute the queries against a real in-memory Postgres.
 
-TailorDB migration scripts (`migrate.ts`) are unit-tested the same way: the generated `db.ts` exports the `Database` interface to type the mock, and `tailor tailordb migration script <N> --with-test` scaffolds a ready-to-fill test. To execute a migration script against real rows in an in-memory Postgres, use `createKyselyPGlite` with `@electric-sql/pglite`. See [Testing Migrations Locally](./services/tailordb-migration.md#testing-migrations-locally).
+TailorDB migration scripts (`migrate.ts`) are unit-tested the same way: the generated `db.ts` exports the `Database` interface to type the mock, and `tailor tailordb migration script <N> --with-test` scaffolds a ready-to-fill test. To execute a migration script against real rows in an in-memory Postgres, use `createKyselyPGlite` with `@electric-sql/pglite` and the generated `db.pglite.ts` schema. See [Testing Migrations Locally](./services/tailordb-migration.md#testing-migrations-locally).
 
 #### Resolvers that resume a workflow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -155,8 +155,8 @@
     "@bufbuild/protovalidate": "1.2.0",
     "@connectrpc/connect": "2.2.0",
     "@connectrpc/connect-node": "2.2.0",
-    "@inquirer/core": "12.0.2",
-    "@inquirer/prompts": "8.7.1",
+    "@inquirer/core": "12.0.3",
+    "@inquirer/prompts": "8.7.2",
     "@jridgewell/trace-mapping": "0.3.31",
     "@napi-rs/keyring": "2.0.0",
     "@opentelemetry/api": "1.9.1",
@@ -190,7 +190,7 @@
     "p-limit": "7.3.2",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
-    "pkg-types": "2.3.2",
+    "pkg-types": "2.3.3",
     "rolldown": "1.2.7",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
@@ -201,15 +201,16 @@
     "zod": "4.5.4"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "0.5.8",
     "@opentelemetry/sdk-trace-base": "2.11.0",
     "@tailor-platform/shared": "^0.0.0",
     "@tailor-platform/tailor-proto": "^0.0.1",
     "@types/mime-types": "3.0.1",
-    "@types/node": "24.13.3",
+    "@types/node": "24.13.4",
     "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "5.0.0",
-    "eslint-plugin-zod": "4.12.0",
+    "eslint-plugin-zod": "4.12.1",
     "oxfmt": "0.66.0",
     "oxlint": "1.81.0",
     "oxlint-tsgolint": "7.0.2001",
@@ -217,7 +218,7 @@
     "tsdown": "0.23.0",
     "typescript": "6.0.3",
     "vitest": "5.0.0",
-    "zinfer": "0.4.5"
+    "zinfer": "0.4.6"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.2.0",

package/dist/application-Dw3t9p2f.mjs

@@ -1 +0,0 @@
-import{n as e,t}from"./application-wYQ-ivDg.mjs";export{t as defineApplication,e as generatePluginFilesIfNeeded};