@tailor-platform/sdk 2.4.0 → 2.6.0

package/docs/cli/function.md

@@ -16,12 +16,13 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Commands**
 
-| Command                           | Aliases    | Description                                                     |
-| --------------------------------- | ---------- | --------------------------------------------------------------- |
-| [`function get`](#function-get)   | -          | Get a function registry by name                                 |
-| [`function list`](#function-list) | -          | List function registries in a workspace                         |
-| [`function logs`](#function-logs) | -          | List or get function execution logs.                            |
-| [`function run`](#function-run)   | `test-run` | Run a function on the Tailor Platform server without deploying. |
+| Command                               | Aliases    | Description                                                     |
+| ------------------------------------- | ---------- | --------------------------------------------------------------- |
+| [`function get`](#function-get)       | -          | Get a function registry by name                                 |
+| [`function list`](#function-list)     | -          | List function registries in a workspace                         |
+| [`function logs`](#function-logs)     | -          | List or get function execution logs.                            |
+| [`function run`](#function-run)       | `test-run` | Run a function on the Tailor Platform server without deploying. |
+| [`function script`](#function-script) | -          | Scaffold a one-off script to run with `function run`.           |
 
 ### function get
 
@@ -151,6 +152,7 @@ tailor function run [options] <file>
 | `--arg <ARG>`                   | `-a`  | JSON argument to pass to the function                                                          | No       | -                    | -                                   |
 | `--machine-user <MACHINE_USER>` | `-m`  | Machine user name for authentication. Falls back to the active profile's default machine user. | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
 | `--config <CONFIG>`             | `-c`  | Path to SDK config file                                                                        | No       | `"tailor.config.ts"` | -                                   |
+| `--allow-schema-drift`          | -     | Run a scaffolded script even when its schema snapshot no longer matches                        | No       | `false`              | -                                   |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -179,8 +181,66 @@ $ tailor function run build/resolvers/add.js --arg '{"a":1,"b":2}'
 You can pass either a source file (`.ts`) or a pre-bundled file (`.js`).
 When a `.js` file is provided, detection and bundling are skipped and the file is executed as-is.
 
+A script scaffolded by `function script` with a generated `db.ts` is checked against its `db.snapshot.json` before execution and refused on schema drift; pass `--allow-schema-drift` to run it anyway. The check compares table and field structure; hook and validator code changes are not detected.
+
 `test-run` is a deprecated alias of this command and will be removed in v3.
 
 > [!WARNING]
 > Workflow job `.start()` calls do not work in this mode.
 > Started jobs are not executed; only the target job's `body` function runs in isolation.
+
+### function script
+
+Scaffold a one-off script to run with `function run`.
+
+**Usage**
+
+```
+tailor function script [options] <file>
+```
+
+**Arguments**
+
+| Argument | Description                                      | Required |
+| -------- | ------------------------------------------------ | -------- |
+| `file`   | Path to create the script at (must end with .ts) | Yes      |
+
+**Options**
+
+| Option                          | Alias | Description                                                           | Required | Default              | Env                            |
+| ------------------------------- | ----- | --------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                          | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                     | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
+| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                            | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
+| `--namespace <NAMESPACE>`       | -     | Target TailorDB namespace (required when the config does not pin one) | No       | -                    | -                              |
+| `--remote`                      | -     | Generate script-scoped DB types from the deployed schema              | No       | `false`              | -                              |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Examples**
+
+**Scaffold a one-off script (single-namespace project)**
+
+```bash
+$ tailor function script scripts/fix-prices.ts
+```
+
+**Scaffold a script targeting a specific namespace**
+
+```bash
+$ tailor function script scripts/fix-prices.ts --namespace tailordb
+```
+
+**Scaffold from a deployed or external namespace**
+
+```bash
+$ tailor function script scripts/fix-prices.ts --namespace shared --remote
+```
+
+**Notes**
+
+The scaffolded script is a plain default-exported function; execute it with `tailor function run <file>`.
+
+By default, when the project configures `kyselyTypePlugin`, the skeleton imports `getDB()` from the plugin's generated types. Without the plugin, the command uses the namespace's local table definitions to write a script-scoped `db.ts` plus a `db.snapshot.json` next to the script; `function run` refuses to run the script when that snapshot no longer matches the deployed or locally defined table and field structure.
+
+Pass `--remote` to generate the script-scoped files from the deployed schema instead, even when `kyselyTypePlugin` is configured. This is required for an external namespace. Re-running the command refreshes `db.ts` and `db.snapshot.json` from the selected source and leaves the script itself untouched.

package/docs/cli/setup.md

@@ -23,7 +23,7 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 | [`setup preview`](#setup-preview)       | Generate a preview workflow (PR open/sync triggers deploy to a per-PR workspace).                |
 | [`setup action`](#setup-action)         | Generate a per-app composite action for use with setup coordinate (monorepo multi-app deploys).  |
 | [`setup coordinate`](#setup-coordinate) | Generate a coordinator workflow that orchestrates multiple --action-generated composite actions. |
-| [`setup renovate`](#setup-renovate)     | Generate a Renovate config for Tailor dependency and workflow updates.                           |
+| [`setup deps`](#setup-deps)             | Generate a dependency update config for Tailor dependency and workflow updates.                  |
 | [`setup check`](#setup-check)           | Audit generated workflows for drift against the current config/repo (read-only).                 |
 | [`setup delete`](#setup-delete)         | Delete managed workflow/action file(s) and their .github/tailor.lock entries.                    |
 
@@ -63,7 +63,7 @@ tailor setup branch [options]
 | Option                        | Alias | Description                                                                    | Required | Default |
 | ----------------------------- | ----- | ------------------------------------------------------------------------------ | -------- | ------- |
 | `--name <NAME>`               | `-n`  | Name (defaults to the config 'name')                                           | No       | -       |
-| `--branch <BRANCH>`           | -     | Deploy trigger branch (defaults to the detected default branch)                | No       | -       |
+| `--target <TARGET>`           | -     | Deploy trigger branch (defaults to the detected default branch)                | No       | -       |
 | `--environment <ENVIRONMENT>` | -     | GitHub Environment for the plan/deploy jobs (defaults to the workspace name)   | No       | -       |
 | `--erd-preview`               | -     | Add PR ERD viewer artifacts with current/diff previews for TailorDB namespaces | No       | `false` |
 | `--dir <DIR>`                 | `-d`  | App directory (for monorepo setups)                                            | No       | `"."`   |
@@ -71,6 +71,10 @@ tailor setup branch [options]
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+`--branch` is a deprecated alias of `--target` and will be removed in v3.
+
 ### setup check
 
 Audit generated workflows for drift against the current config/repo (read-only).
@@ -136,6 +140,24 @@ tailor setup delete [options] <files>
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+### setup deps
+
+Generate a dependency update config for Tailor dependency and workflow updates.
+
+**Usage**
+
+```
+tailor setup deps [options]
+```
+
+**Options**
+
+| Option                  | Alias | Description                             | Required | Default      |
+| ----------------------- | ----- | --------------------------------------- | -------- | ------------ |
+| `--provider <PROVIDER>` | -     | Dependency update provider to configure | No       | `"renovate"` |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
 ### setup preview
 
 Generate a preview workflow (PR open/sync triggers deploy to a per-PR workspace).
@@ -160,18 +182,6 @@ tailor setup preview [options]
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-### setup renovate
-
-Generate a Renovate config for Tailor dependency and workflow updates.
-
-**Usage**
-
-```
-tailor setup renovate
-```
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
 ### setup tag
 
 Generate a tag-target deploy workflow (tag push triggers deploy).

package/docs/cli/tailordb.md

@@ -125,6 +125,8 @@ tailor tailordb migration generate [options]
 | `--config <CONFIG>`                   | `-c`  | Path to Tailor config file                                                                                                                                                                      | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
 | `--name <NAME>`                       | `-n`  | Optional description for the migration                                                                                                                                                          | No       | -                    | -                    |
 | `--init`                              | -     | Delete existing migrations and start fresh                                                                                                                                                      | No       | `false`              | -                    |
+| `--data-only`                         | -     | Create a migration with no schema changes whose migration script runs a standalone data transformation                                                                                          | No       | `false`              | -                    |
+| `--namespace <NAMESPACE>`             | -     | Target TailorDB namespace for --data-only (required if multiple namespaces exist)                                                                                                               | No       | -                    | -                    |
 | `--rename <RENAME>`                   | -     | Record a field or table rename instead of remove + add (format: "Table.oldField:newField" or "OldTable:NewTable"; repeatable). Renames require a migration script that copies the data.         | No       | -                    | -                    |
 | `--drop <DROP>`                       | -     | Confirm that a removed field or table is a genuine removal, not a rename (format: "Table.field" or "Table"; repeatable). Required in non-interactive runs for a removal with rename candidates. | No       | -                    | -                    |
 | `--expand-contract <EXPAND_CONTRACT>` | -     | Convert a field type through a temporary field (format: "Table.field"; repeatable). Generates two migrations.                                                                                   | No       | -                    | -                    |

package/docs/cli-reference.md

@@ -323,13 +323,14 @@ Commands for managing workflows and executions.
 
 Commands for managing function registries and viewing function execution logs.
 
-| Command                                          | Description                                                     |
-| ------------------------------------------------ | --------------------------------------------------------------- |
-| [function](./cli/function.md#function)           | Manage functions                                                |
-| [function get](./cli/function.md#function-get)   | Get a function registry by name                                 |
-| [function list](./cli/function.md#function-list) | List function registries in a workspace                         |
-| [function logs](./cli/function.md#function-logs) | List or get function execution logs.                            |
-| [function run](./cli/function.md#function-run)   | Run a function on the Tailor Platform server without deploying. |
+| Command                                              | Description                                                     |
+| ---------------------------------------------------- | --------------------------------------------------------------- |
+| [function](./cli/function.md#function)               | Manage functions                                                |
+| [function get](./cli/function.md#function-get)       | Get a function registry by name                                 |
+| [function list](./cli/function.md#function-list)     | List function registries in a workspace                         |
+| [function logs](./cli/function.md#function-logs)     | List or get function execution logs.                            |
+| [function run](./cli/function.md#function-run)       | Run a function on the Tailor Platform server without deploying. |
+| [function script](./cli/function.md#function-script) | Scaffold a one-off script to run with `function run`.           |
 
 ### [Executor Commands](./cli/executor.md)
 
@@ -397,8 +398,8 @@ Commands for setting up project infrastructure.
 | [setup check](./cli/setup.md#setup-check)           | Audit generated workflows for drift against the current config/repo (read-only).                 |
 | [setup coordinate](./cli/setup.md#setup-coordinate) | Generate a coordinator workflow that orchestrates multiple --action-generated composite actions. |
 | [setup delete](./cli/setup.md#setup-delete)         | Delete managed workflow/action file(s) and their .github/tailor.lock entries.                    |
+| [setup deps](./cli/setup.md#setup-deps)             | Generate a dependency update config for Tailor dependency and workflow updates.                  |
 | [setup preview](./cli/setup.md#setup-preview)       | Generate a preview workflow (PR open/sync triggers deploy to a per-PR workspace).                |
-| [setup renovate](./cli/setup.md#setup-renovate)     | Generate a Renovate config for Tailor dependency and workflow updates.                           |
 | [setup tag](./cli/setup.md#setup-tag)               | Generate a tag-target deploy workflow (tag push triggers deploy).                                |
 
 ### [Upgrade Commands](./cli/upgrade.md)

package/docs/github-actions.md

@@ -38,12 +38,13 @@ Run `setup` once per target.
 ### Branch target (recommended for staging)
 
 The branch target fires on pull requests and pushes to the branch you specify
-(defaulting to the repository's default branch when `--branch` is omitted):
+(defaulting to the repository's default branch when `--target` is
+omitted):
 
 ```bash
 tailor setup branch --name my-app-stg
 # Equivalent to:
-tailor setup branch --name my-app-stg --branch main
+tailor setup branch --name my-app-stg --target main
 ```
 
 What it does:
@@ -120,12 +121,12 @@ What it does:
 
 ### Choosing `--branch` for the tag target
 
-`--branch` has two different roles depending on the target kind:
+The branch each target reads plays a different role, under a different flag:
 
-| Target | Role of `--branch`                                                                             |
-| ------ | ---------------------------------------------------------------------------------------------- |
-| Branch | The branch that triggers the workflow (push + PR base). Defaults to the repo's default branch. |
-| Tag    | The branch whose history the tag must be reachable from. Omit to disable the guard entirely.   |
+| Target | Flag       | Role                                                                                           |
+| ------ | ---------- | ---------------------------------------------------------------------------------------------- |
+| Branch | `--target` | The branch that triggers the workflow (push + PR base). Defaults to the repo's default branch. |
+| Tag    | `--branch` | The branch whose history the tag must be reachable from. Omit to disable the guard entirely.   |
 
 The workspace name (`--name`, or the config `name` when omitted) must
 be 3–63 characters of lowercase letters, numbers, and hyphens, and cannot start
@@ -365,7 +366,7 @@ Commit both workflow files and `.github/tailor.lock`.
 Run this command once from the repository root to add Renovate configuration:
 
 ```bash
-tailor setup renovate
+tailor setup deps
 ```
 
 It generates `renovate.json`, which extends Tailor's shared Renovate preset. The
@@ -382,12 +383,13 @@ standard root, `.github`, `.gitlab`, and `.renovaterc` locations, including the
 deprecated `package.json` configuration. When that configuration already extends
 the preset, the command reports that Renovate is set up and changes nothing.
 
-Configuration written in JSON5 or JSONC — with comments or trailing commas —
-cannot be edited without losing those comments, so the command leaves it
-unchanged and asks you to add the preset to its `extends` array yourself.
+JSONC and JSON5 configurations are updated in place while preserving their
+comments and formatting. Configurations that Renovate itself cannot load — such
+as invalid syntax, or duplicate keys outside JSON5 — are left unchanged and
+reported for manual inspection.
 
 `renovate.json` is yours to edit — it is not tracked in `.github/tailor.lock`.
-Add your own rules freely; re-running `tailor setup renovate` does not overwrite
+Add your own rules freely; re-running `tailor setup deps` does not overwrite
 them. To remove it, delete the file.
 
 Renovate updates the SDK dependency and action pins, but it does not regenerate

package/docs/migration/v2.md

@@ -661,7 +661,7 @@ After:
 ```ts
 ownerId: db.uuid().relation({
   type: "n-1",
-  toward: { type: user, as: "user" },
+  toward: { table: user, as: "user" },
 }),
 ```
 
@@ -878,6 +878,10 @@ Also review, and migrate by hand:
 - An invoker option passed via a variable or spread (not a literal object) —
   the codemod only inspects literal object arguments; rename the invoker key
   to authInvoker in the options object's own definition.
+- A renamed triggerJobFunction call whose target is another workflow job —
+  rewrite it further to that job's own .start() method (e.g. worker.start(args)).
+  Calling execJobFunction directly is not detected as a build-time dependency
+  and fails the build.
 ```
 
 </details>
@@ -924,6 +928,10 @@ Also review, and migrate by hand:
   instead; the alias was the same mock function.
 - A file that already imports ExecJobFunctionOptions alongside the removed type —
   rename the remaining references by hand and drop the duplicate specifier.
+- A renamed call whose target is another workflow job — rewrite it further to
+  that job's own .start() method (e.g. worker.start(args)). Calling
+  execJobFunction directly is not detected as a build-time dependency and fails
+  the build.
 ```
 
 </details>
@@ -1661,10 +1669,18 @@ The CLI stores human users by their stable subject ID instead of email (email is
 
 `tailor function logs` maps stack traces against the function bundle only when the execution recorded a `contentHash`. Executions without one now show raw stack traces instead of mapped frames. No source change is required.
 
+### `db.fields.timestamps()`: `updatedAt` becomes required
+
+The `updatedAt` field from `db.fields.timestamps()` changes from optional to required (non-null): it defaults to the current time and keeps refreshing automatically on every update, though a value you provide explicitly is still respected. Applying this change to a table that already has rows with `updatedAt: null` makes `deploy` fail with `field "updatedAt" cannot be updated from non-required to required when records with null values exist`. Backfill those rows first, e.g. `UPDATE <table> SET "updatedAt" = "createdAt" WHERE "updatedAt" IS NULL` for each affected table — see [TailorDB migrations](../services/tailordb-migration.md#performance-and-large-tables) for splitting a large backfill across primary-key ranges if a single `UPDATE` times out.
+
 ### Node.js minimum version raised to 22.15.0
 
-v2 requires Node.js **22.15.0** or later. This is the first version that includes `module.registerHooks()`, which the SDK uses to register its TypeScript loader hook synchronously in the main thread. The actual floor is now **22.18.0**: Node 22.15.0–22.17.x has a bug ([nodejs/node#58607](https://github.com/nodejs/node/issues/58607)) that crashes `tailor seed validate` when requiring `node:`-scheme-only builtins such as `node:sqlite`, fixed upstream in 22.18.0. No source change is required; ensure your environment runs Node.js 22.18.0+.
+v2 requires Node.js **22.15.0** or later. This is the first version that includes `module.registerHooks()`, which the SDK uses to register its TypeScript loader hook synchronously in the main thread. The actual floor is now **22.18.0**: Node 22.15.0–22.17.x has a bug that crashes `tailor seed validate` when requiring `node:`-scheme-only builtins such as `node:sqlite`, fixed upstream by [nodejs/node#58612](https://github.com/nodejs/node/pull/58612) in 22.18.0. No source change is required; ensure your environment runs Node.js 22.18.0+.
 
 ### Legacy bundle artifact cleanup removed from deploy
 
 `tailor deploy` no longer deletes on-disk bundle artifacts (`.entry.js` files, workflow-job bundles, and the `hooks-validate-scripts/` directory) left in the SDK output directory (`.tailor` by default) by SDK versions that predate the current in-memory bundling approach. Current bundlers no longer write these files. No source change is required; if such stale files remain from a very old SDK version, delete only those specific files/directories manually — do not delete the output directory itself, since it also holds deploy state (e.g. `secrets-state/`, `*.context.json`) that existing secrets and Auth Connections depend on.
+
+### First v2 deploy to a v1-deployed environment needs migration sync
+
+The pre-v2 CLI never wrote a script hash into deployed schemas, so the first `tailor deploy` against an environment last deployed with it reports `Remote schema drift detected` with every scripted type showing `has no script hash on remote`. Run `tailor tailordb migration sync <current migration number>` once for that environment to write the missing hashes, then `tailor deploy` as usual. Preview/PR workspaces don't hit this, since they're built with v2 from the start. No source change is required.

package/docs/migration/v3.md

@@ -8,6 +8,55 @@ Run the codemods, then finish anything reported as not migrated automatically:
 npx @tailor-platform/sdk-codemod --from <current-version> --to <target-version>
 ```
 
+## workflow.execJobFunction (imported) removed — use job.start()
+
+**Migration:** Manual
+
+`execJobFunction` on the `workflow` value imported from @tailor-platform/sdk/runtime(/workflow) is removed in v3. Calling it directly from a workflow job body to reach another job is not detected as a build-time dependency and has no working use; the target job's own `.start()` method is the only supported way to call it. This does not affect the ambient `tailor.workflow.execJobFunction` global — that's what `.start()` itself compiles down to at build time, and it remains fully supported.
+
+Before:
+
+```ts
+import { workflow } from "@tailor-platform/sdk/runtime";
+
+await workflow.execJobFunction("worker", { id: 1 });
+```
+
+After:
+
+```ts
+import { worker } from "./jobs/worker";
+
+await worker.start({ id: 1 });
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+workflow.execJobFunction — the value imported from
+@tailor-platform/sdk/runtime or @tailor-platform/sdk/runtime/workflow — is
+removed in v3. Replace each call with the target job's own .start() method:
+import the WorkflowJob the call names and call <job>.start(args, options)
+instead of workflow.execJobFunction("<job-name>", args, options).
+
+This only removes the re-export from @tailor-platform/sdk/runtime. It does
+not affect the ambient tailor.workflow.execJobFunction global, which stays
+fully supported and is what .start() itself compiles down to at build time.
+This codemod does not rewrite ambient tailor.workflow.execJobFunction(...)
+call sites, since removing the import re-export does not affect them — but
+if such a call site sits inside workflow job source and calls another job
+by name, a separate build-time check already rejects it; migrate that call
+to the target job's own .start() method too.
+
+If the job name passed to execJobFunction is not a string literal (a truly
+dynamic dispatch), there is currently no supported replacement — .start()
+only targets a statically known job. Flag this case for a human instead of
+guessing a rewrite.
+```
+
+</details>
+
 ## function test-run → function run
 
 **Migration:** Partially automatic
@@ -39,3 +88,75 @@ unchanged unless it documents a command to type.
 ```
 
 </details>
+
+## setup branch --branch → --target
+
+**Migration:** Partially automatic
+
+Rename the `--branch` option of `tailor setup branch` invocations to `--target`. `--branch` remains as a deprecated alias until it is removed in v3. The `--branch` option of `setup tag`, `setup preview`, and `setup coordinate` is unchanged.
+
+Before:
+
+```sh
+tailor setup branch --name my-app-stg --branch main
+```
+
+After:
+
+```sh
+tailor setup branch --name my-app-stg --target main
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+The `--branch` option of `tailor setup branch` is renamed to `--target`;
+the old spelling is removed in v3. Replace any remaining `--branch` options of
+`setup branch` invocations the codemod did not rewrite (e.g. wrapped across
+lines or invoked through a package runner such as `npx @tailor-platform/sdk`)
+with `--target`. Do not touch the `--branch` option of `setup tag`,
+`setup preview`, or `setup coordinate`, which keeps its name, and leave prose
+that merely mentions the option unchanged unless it documents a command to type.
+```
+
+</details>
+
+## relation() toward.type → toward.table
+
+**Migration:** Partially automatic
+
+Rename the `.relation()` option `toward.type` to `toward.table`, matching the `db.type()` → `db.table()` rename. The relation's own `type` (its cardinality, e.g. `"n-1"`) is unchanged — only the target-table reference nested under `toward` moves.
+
+Before:
+
+```ts
+customerId: db.uuid().relation({
+  type: "n-1",
+  toward: { type: customer },
+}),
+```
+
+After:
+
+```ts
+customerId: db.uuid().relation({
+  type: "n-1",
+  toward: { table: customer },
+}),
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v3, `.relation()`'s `toward.type` option is renamed to
+`toward.table` (it names a target table, not a TypeScript/GraphQL type).
+Rename any remaining `toward.type` the codemod did not rewrite (e.g. a
+`toward` object reached through a shared variable, spread, or computed
+key) to `toward.table`. Do not touch the relation's own outer `type`
+property, which is the relation's cardinality (e.g. "n-1", "1-1",
+"keyOnly") and keeps its name.
+```
+
+</details>