@tailor-platform/sdk 2.10.0 → 2.12.0

package/docs/cli/user.md

@@ -66,9 +66,28 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Commands**
 
-| Command                     | Description                                                                           |
-| --------------------------- | ------------------------------------------------------------------------------------- |
-| [`auth token`](#auth-token) | Print a valid Tailor Platform access token to stdout, refreshing it first if expired. |
+| Command                       | Description                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------------- |
+| [`auth status`](#auth-status) | Show the active Tailor Platform authentication status without printing tokens.        |
+| [`auth token`](#auth-token)   | Print a valid Tailor Platform access token to stdout, refreshing it first if expired. |
+
+### auth status
+
+Show the active Tailor Platform authentication status without printing tokens.
+
+**Usage**
+
+```
+tailor auth status [options]
+```
+
+**Options**
+
+| Option                | Alias | Description       | Required | Default | Env                       |
+| --------------------- | ----- | ----------------- | -------- | ------- | ------------------------- |
+| `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 ### auth token
 
@@ -261,16 +280,33 @@ When no subcommand is provided, defaults to `list`.
 **Output (default):**
 
 ```
- token-name-1: read/write
- token-name-2: read
+┌──────────────┬────────────┬──────────────┬──────────────┐
+│ name         │ scopes     │ createdAt    │ lastUsedAt   │
+├──────────────┼────────────┼──────────────┼──────────────┤
+│ token-name-1 │ read/write │ 8 months ago │ 6 months ago │
+│ token-name-2 │ read       │ 8 months ago │ never        │
+└──────────────┴────────────┴──────────────┴──────────────┘
 ```
 
+`lastUsedAt` reads `never` until the token has been used to authenticate, and is
+updated at most once per hour.
+
 **Output (`-j, --json`):**
 
 ```json
 [
-  { "name": "token-name-1", "scopes": ["read", "write"] },
-  { "name": "token-name-2", "scopes": ["read"] }
+  {
+    "name": "token-name-1",
+    "scopes": ["read", "write"],
+    "createdAt": "2026-01-02T03:04:05.000Z",
+    "lastUsedAt": "2026-03-04T05:06:07.000Z"
+  },
+  {
+    "name": "token-name-2",
+    "scopes": ["read"],
+    "createdAt": "2026-01-02T03:04:05.000Z",
+    "lastUsedAt": null
+  }
 ]
 ```
 

package/docs/cli-reference.md

@@ -231,6 +231,7 @@ Commands for authentication and user management.
 | [login](./cli/user.md#login)                     | Login to Tailor Platform.                                                             |
 | [logout](./cli/user.md#logout)                   | Logout from Tailor Platform.                                                          |
 | [auth](./cli/user.md#auth)                       | Authentication helpers for scripts and plugins.                                       |
+| [auth status](./cli/user.md#auth-status)         | Show the active Tailor Platform authentication status without printing tokens.        |
 | [auth token](./cli/user.md#auth-token)           | Print a valid Tailor Platform access token to stdout, refreshing it first if expired. |
 | [user](./cli/user.md#user)                       | Manage Tailor Platform users.                                                         |
 | [user current](./cli/user.md#user-current)       | Show current user.                                                                    |

package/docs/plugin/custom.md

@@ -83,6 +83,13 @@ interface Plugin<TableConfig = unknown, PluginConfig = unknown> {
 | `executors` | `PluginGeneratedExecutor[]`                     | Additional executors to generate                       |
 | `extends`   | `{ fields?: Record<string, TailorAnyDBField> }` | Fields to add to the source table                      |
 
+Tables in `tables` are validated as complete TailorDB table definitions before registration.
+Fields in `extends.fields` are validated as part of the resulting source table. You can return a
+table builder directly or a structural copy such as `{ ...db.table(...) }`; a copy is accepted as
+long as it retains valid table schema properties. Malformed output stops the build with an error
+that identifies the plugin and relevant table output, without partially registering tables from
+that source table's plugin processing.
+
 **Use cases**:
 
 - Generate derived tables (e.g., archive tables, history tables) from user-defined tables
@@ -115,6 +122,10 @@ onTableLoaded(context) {
 
 Same as `TablePluginOutput` but without `extends` (namespace plugins cannot extend a source table).
 
+Tables in `tables` undergo the same validation and support structural copies. If any returned
+table is malformed, the build stops before namespace-generated tables are registered and the
+error identifies the plugin and relevant table output.
+
 **Use cases**:
 
 - Generate tables that don't derive from a specific user table (e.g., audit log, settings table)

package/docs/plugin/index.md

@@ -102,6 +102,11 @@ Plugins can generate:
 - **Field Extensions**: Additional fields added to the source table
 - **Output Files**: TypeScript code and other files via generation-time hooks
 
+Tables produced by definition-time hooks are validated before registration. This includes
+generated tables and source tables after field extensions are applied. Malformed output stops
+the build with an error that identifies the plugin and relevant table output, without partially
+registering tables from that processing step.
+
 Generated files are placed under `.tailor/<plugin-id>/` (the plugin ID is sanitized,
 e.g. `@example/soft-delete` → `example-soft-delete`), such as:
 

package/docs/testing.md

@@ -24,6 +24,7 @@ For anonymous direct calls:
 Platform API mocks under `@tailor-platform/sdk/vitest` (for use with the [`tailor-runtime` Vitest environment](#runtime-environment-emulation-beta) below):
 
 - `mockTailordb` — TailorDB query stubs and call recording
+- `mockTailordbWithPGlite` — TailorDB backed by a real in-memory Postgres (PGlite)
 - `mockWorkflow` — `tailor.workflow` job / wait / resolve mocks
 - `runWorkflowLocally` — local full-chain workflow runner
 - `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger` — corresponding platform API mocks
@@ -63,7 +64,7 @@ export default defineConfig({
 
 ### Acquiring mocks with `using`
 
-Each mock controller (`mockTailordb`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger`) is a **factory function**. Acquire it inside a test with a [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management) — its state is reset automatically when the test scope exits, so you no longer need `beforeEach(() => mock.reset())`:
+Each mock controller (`mockTailordb`, `mockTailordbWithPGlite`, `mockWorkflow`, `mockSecretmanager`, `mockAuthconnection`, `mockIdp`, `mockFile`, `mockIconv`, `mockAigateway`, `mockLogger`) is a **factory function**. Acquire it inside a test with a [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management) — its state is reset automatically when the test scope exits, so you no longer need `beforeEach(() => mock.reset())`:
 
 ```typescript
 import { mockTailordb } from "@tailor-platform/sdk/vitest";
@@ -144,6 +145,81 @@ Within one `mockTailordb()` instance, use either `onQuery()` matchers or a direc
 
 Pass `{ onUnhandled: "error" }` to make an unmatched query fail instead of returning an empty result.
 
+#### Real SQL execution with PGlite (`mockTailordbWithPGlite`)
+
+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.
+
+```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 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
+    );
+  `);
+});
+
+afterAll(async () => {
+  await pglite.close();
+});
+
+test("upserts against real rows", async () => {
+  using _db = mockTailordbWithPGlite({ namespaces: { "main-db": pglite } });
+  const db = getDB("main-db");
+  await db
+    .insertInto("User")
+    .values({ name: "Existing", email: "exists@example.com", age: 40 })
+    .execute();
+
+  const result = await resolver.body({
+    input: {
+      users: [
+        { name: "Newcomer", email: "new@example.com", age: 22 },
+        { name: "Existing", email: "exists@example.com", age: 41 },
+      ],
+    },
+    caller: null,
+    invoker: null,
+    env: { appName: "Resolver Template", version: 1 },
+  });
+
+  expect(result).toEqual({ created: 1, updated: 1 });
+  const rows = await db.selectFrom("User").selectAll().orderBy("email", "asc").execute();
+  expect(rows.map((row) => row.age)).toEqual([41, 22]);
+});
+```
+
+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:
+
+```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'))
+);
+```
+
+PGlite does not apply the TailorDB `.serial()` configuration itself. Match the `start`, `format`, and any limit that the behavior under test relies on.
+
+- 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.
+- 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.
+
 ### Workflow Mock
 
 Workflow job `.start()` calls use the platform workflow runtime. Acquire `mockWorkflow()` when you want to provide start responses with `setJobHandler` / `enqueueResult` or assert on `startedJobs`. If no response is configured, the mock throws so missing job mocks fail loudly. Use `job(definition)` or `workflow(definition)` to get a stable, fully typed Vitest mock for one definition:
@@ -592,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.
+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).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -169,13 +169,13 @@
     "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@toiroakr/lines-db": "0.12.2",
+    "@toiroakr/lines-db": "0.12.5",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.3",
     "amaro": "1.1.11",
     "confbox": "0.2.4",
     "date-fns": "4.4.0",
-    "es-toolkit": "1.51.0",
+    "es-toolkit": "1.52.0",
     "find-up-simple": "1.0.1",
     "get-east-asian-width": "1.6.0",
     "get-tsconfig": "4.14.3",
@@ -184,21 +184,21 @@
     "inflection": "3.0.2",
     "kysely": "0.29.5",
     "mime-types": "3.0.2",
-    "open": "11.0.1",
+    "open": "11.0.2",
     "oxc-parser": "0.147.0",
     "p-limit": "7.3.1",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
     "pkg-types": "2.3.1",
     "politty": "0.11.9",
-    "rolldown": "1.2.5",
+    "rolldown": "1.2.6",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
     "std-env": "4.2.0",
     "ts-cron-validator": "1.1.5",
     "type-fest": "5.8.0",
     "xdg-basedir": "5.1.0",
-    "zod": "4.4.3"
+    "zod": "4.5.4"
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "2.10.0",
@@ -242,7 +242,7 @@
   "scripts": {
     "test": "vitest",
     "test:unit": "vitest --project=unit*",
-    "test:e2e": "vitest --project=e2e",
+    "test:e2e": "vitest --project=e2e*",
     "test:coverage": "vitest --coverage",
     "docs:check": "vitest run --project=unit* src/cli/docs.test.ts",
     "docs:update": "POLITTY_DOCS_UPDATE=true vitest run --project=unit* src/cli/docs.test.ts",