@tailor-platform/sdk 2.2.0 → 2.4.0

package/docs/configuration.md

@@ -243,7 +243,7 @@ export default defineConfig({
 
 If the same config defines an auth before-login hook, make sure the config module can be evaluated without Node-only globals in the platform runtime. Avoid arbitrary `process.env` reads in that module; pass literal values, or values generated into a config module before deployment, and read them from the hook's `env` argument.
 
-When the SDK deploys application code or runs detected service code with `function test-run`, it passes the resolved values as the `env` argument. Do not read `process.env` from deployed resolvers, executors, workflow jobs, auth hooks, or migration scripts; Node-side environment variables are not available there. Put sensitive values in [Secret Manager](./services/secret.md) instead of `env`.
+When the SDK deploys application code or runs detected service code with `function run`, it passes the resolved values as the `env` argument. Do not read `process.env` from deployed resolvers, executors, workflow jobs, auth hooks, or migration scripts; Node-side environment variables are not available there. Put sensitive values in [Secret Manager](./services/secret.md) instead of `env`.
 
 | Code location             | Runtime access                                                                                                                            |
 | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
@@ -252,7 +252,7 @@ When the SDK deploys application code or runs detected service code with `functi
 | Workflow job body         | `body: (input, { env }) => ...`                                                                                                           |
 | Auth before-login hook    | `handler: async ({ env }) => ...`                                                                                                         |
 | TailorDB migration script | `main(trx, { env }: MigrationContext)`                                                                                                    |
-| `function test-run`       | Same `env` argument shape as the detected resolver, executor, or workflow job                                                             |
+| `function run`            | Same `env` argument shape as the detected resolver, executor, or workflow job                                                             |
 
 ```typescript
 // In resolvers

package/docs/github-actions.md

@@ -1,7 +1,7 @@
 # GitHub Actions Integration
 
-`tailor setup` generates a GitHub Actions workflow that deploys your
-Tailor Platform application automatically on push or tag.
+`tailor setup` generates GitHub repository automation for your Tailor Platform
+application, including deploy workflows and Renovate configuration.
 
 > **Beta:** This command is under active development. CLI flags, the generated
 > workflow, and the `.github/tailor.lock` schema may change before general
@@ -14,16 +14,13 @@ lives):
 
 ```bash
 # Branch target: deploy to stg on every push to main
-tailor setup -n my-app-stg
+tailor setup branch --name my-app-stg
 
 # Tag target: deploy to production when a tag is pushed, with an approval gate
-tailor setup -n my-app-prod \
-  --tag --branch main --environment production
+tailor setup tag --name my-app-prod \
+  --branch main --environment production
 ```
 
-`setup` defaults to the GitHub provider; `--provider github` (`-p github`) is
-accepted but optional, and other providers are not yet supported.
-
 After running the command, follow the **Next steps** printed to the terminal to
 set the required secrets, set the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and
 commit the generated files.
@@ -44,9 +41,9 @@ 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):
 
 ```bash
-tailor setup -n my-app-stg
+tailor setup branch --name my-app-stg
 # Equivalent to:
-tailor setup -n my-app-stg --branch main
+tailor setup branch --name my-app-stg --branch main
 ```
 
 What it does:
@@ -69,7 +66,7 @@ Pass `--erd-preview` on a branch target to add TailorDB ERD preview artifacts
 to pull requests:
 
 ```bash
-tailor setup -n my-app-stg --erd-preview
+tailor setup branch --name my-app-stg --erd-preview
 ```
 
 The generated workflow runs `tailor tailordb erd`, which is provided by the
@@ -90,11 +87,10 @@ ERD preview does not use Tailor Platform credentials. Fork pull requests still
 build artifacts, but the comment step is skipped because fork tokens cannot
 write PR comments.
 
-`--erd-preview` is only available for branch targets with the plan job enabled;
-it cannot be combined with `--tag` or `--no-plan`. The namespace list is
-recorded in `.github/tailor.lock`; the pull request workflow compares the
-head and base lock files so newly added or removed namespaces can still produce
-all-added or all-removed viewer artifacts. Re-run `setup` after adding or
+`--erd-preview` is only available for branch targets. The namespace list is
+recorded in `.github/tailor.lock`; the pull request workflow compares the head
+and base lock files so newly added or removed namespaces can still produce
+all-added or all-removed viewer artifacts. Re-run `setup branch` after adding or
 removing TailorDB namespaces. `setup check` reports drift when the recorded ERD
 preview namespaces no longer match the current config.
 
@@ -104,8 +100,8 @@ The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
 pushed:
 
 ```bash
-tailor setup -n my-app-prod \
-  --tag --tag-pattern "v*" --branch main --environment production
+tailor setup tag --name my-app-prod \
+  --tag-pattern "v*" --branch main --environment production
 ```
 
 What it does:
@@ -131,7 +127,7 @@ What it does:
 | 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.   |
 
-The workspace name (`--workspace-name`, or the config `name` when omitted) must
+The workspace name (`--name`, or the config `name` when omitted) must
 be 3–63 characters of lowercase letters, numbers, and hyphens, and cannot start
 or end with a hyphen. It is used for the generated file name, the workflow
 `name:`, the plan label, and the default GitHub Environment name; it does not
@@ -174,7 +170,7 @@ environment is planned.)
 
 ## Generated files
 
-Running `setup` creates or updates:
+Running a workflow setup subcommand creates or updates:
 
 ### `.github/workflows/tailor-<workspace-name>.yml`
 
@@ -276,7 +272,7 @@ you can deploy any commit regardless of branch membership.
 For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:
 
 ```bash
-tailor setup -n my-app --dir apps/backend
+tailor setup branch --name my-app --dir apps/backend
 ```
 
 The generated workflow adds a `paths` filter on `apps/backend/**` so the
@@ -341,11 +337,11 @@ A typical setup with staging and production:
 
 ```bash
 # Staging: main → stg (deploy on every push to main)
-tailor setup -n my-app-stg
+tailor setup branch --name my-app-stg
 
 # Production: tagged commits → prod, with approval gate and branch guard
-tailor setup -n my-app-prod \
-  --tag --branch main --environment production
+tailor setup tag --name my-app-prod \
+  --branch main --environment production
 ```
 
 Then provision each workspace and set its id on the matching environment (the
@@ -364,6 +360,41 @@ gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env production
 
 Commit both workflow files and `.github/tailor.lock`.
 
+## Keeping dependencies and actions updated
+
+Run this command once from the repository root to add Renovate configuration:
+
+```bash
+tailor setup renovate
+```
+
+It generates `renovate.json`, which extends Tailor's shared Renovate preset. The
+preset groups `@tailor-platform/*` package updates into one pull request and
+lets Renovate update the SHA-pinned GitHub Actions used by generated workflows.
+Enable Renovate for the repository by following the
+[Renovate onboarding guide](https://docs.renovatebot.com/getting-started/installing-onboarding/),
+then commit the generated file.
+
+If the repository already has Renovate configuration, the command adds
+`github>tailor-inc/renovate-config` to its `extends` array in place instead of
+writing a new file, leaving your other settings untouched. It checks Renovate's
+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.
+
+`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
+them. To remove it, delete the file.
+
+Renovate updates the SDK dependency and action pins, but it does not regenerate
+the workflow template. After an SDK update, `tailor setup check --ci` reports a
+template-version warning until you re-run the relevant workflow setup
+subcommand.
+
 ## Checking for drift
 
 `tailor setup check` audits the workflows recorded in
@@ -374,12 +405,26 @@ newer template is available, `tailor.config.ts` is no longer under the recorded
 trigger. It exits non-zero when it finds drift, so you can run it in CI. Each
 finding names a stable rule key for future suppression.
 
+Workflows generated by `setup branch`, `setup tag`, `setup preview`, and
+`setup coordinate` self-audit: each contains a `tailor-drift-check` step that
+runs the check in CI. Preview workflows run it alongside each preview deploy,
+so pull requests that deploy no preview (drafts, fork PRs, and unlabeled PRs
+in label-triggered mode) skip the check. A single run audits every target
+recorded in `.github/tailor.lock`, so per-app composite actions generated by
+`setup action` are covered by their coordinator's step and do not carry one of
+their own.
+
+Drift findings are advisory by default. Set the repository variable
+`TAILOR_PLATFORM_FAIL_ON_DRIFT` to `true` to make unsuppressed findings fail
+the job. Execution and configuration errors fail regardless of this variable.
+
 ## Updating the generated workflow
 
-When you upgrade the SDK, re-run `setup` with the same flags to pick up
-template improvements. If the SDK detects that you have hand-edited a managed
-section, it stops and asks you to use `--force` to overwrite your edits, or to
-move your customizations into your own steps before regenerating.
+When you upgrade the SDK, re-run the relevant workflow setup subcommand with
+the same flags to pick up template improvements. If the SDK detects that you
+have hand-edited a managed section, it stops and asks you to use `--force` to
+overwrite your edits, or to move your customizations into your own steps before
+regenerating.
 
 The `.github/tailor.lock` file records the flags used at generation time,
 so you can check what arguments were used previously.

package/docs/migration/v2.md

@@ -8,6 +8,60 @@ Run the codemods, then finish anything reported as not migrated automatically:
 npx @tailor-platform/sdk-codemod --from <current-version> --to <target-version>
 ```
 
+## Type-only imports → `import type`
+
+**Migration:** Manual
+
+The v2 CLI runs TypeScript by stripping types from each file in isolation,
+with no cross-file type information. A plain (non-`type`) import of a
+type-only export therefore survives stripping and fails when the module
+loads:
+
+```
+SyntaxError: The requested module './types.ts' does not provide an export named 'Row'
+```
+
+`tailor generate` / `tailor deploy` stop at this error before doing any work.
+Import types with `import type` (or the inline `type` modifier), and
+re-export them with `export type`, in every module the CLI loads. Generated
+Kysely types (`DB`, `Insertable`, `Selectable`, table row types) are almost
+entirely type-only, so v1 projects typically hit this in many files at once.
+Set `"verbatimModuleSyntax": true` in tsconfig.json to catch every violation
+at typecheck; projects scaffolded by v2 `tailor init` enable it by default.
+
+Before:
+
+```ts
+import { DB, getDB } from "./generated/db";
+```
+
+After:
+
+```ts
+import { type DB, getDB } from "./generated/db";
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+In Tailor SDK v2 the CLI loads TypeScript by stripping types from each file
+in isolation, so type-only exports do not exist at runtime and plain imports
+of them fail to load with "does not provide an export named '<name>'".
+Migrate the project so every type-only import and re-export is marked:
+
+1. Add `"verbatimModuleSyntax": true` to compilerOptions in tsconfig.json.
+2. Run `tsc --noEmit` and fix every reported violation: add the `type`
+   modifier to type-only named imports (`import type { Row }` or
+   `import { type Row, marker }`) and change type-only re-exports to
+   `export type { ... }`.
+
+Only add `type` modifiers; do not reorder, remove, or otherwise change
+imports that are used as values.
+```
+
+</details>
+
 ## defineGenerators → definePlugins
 
 **Migration:** Partially automatic
@@ -1368,7 +1422,7 @@ single generation pass and resolves once it completes.
 
 **Migration:** Partially automatic
 
-`seedPlugin` no longer generates the `exec.mjs` seed runner. Seeding and validation move to the `tailor seed` commands provided by the `@tailor-platform/sdk-plugin-seed` CLI plugin: install it as a devDependency, replace `node <distPath>/exec.mjs` invocations with `tailor seed apply` and `node <distPath>/exec.mjs validate` with `tailor seed validate`, and delete the stale generated `<distPath>/exec.mjs` file. Seed data and schema generation (`data/*.jsonl`, `data/*.schema.ts`) is unchanged, and the `tailor seed apply` options mirror the old script (`--machine-user`, `--namespace`, `--skip-idp`, `--truncate`, `--yes`, type-name arguments), plus a new `--upsert` flag to update existing rows instead of failing on duplicate ids.
+`seedPlugin` no longer generates the `exec.mjs` seed runner. Seeding and validation move to the `tailor seed` commands provided by the `@tailor-platform/sdk-plugin-seed` CLI plugin: install it as a devDependency, replace `node <distPath>/exec.mjs` invocations with `tailor seed apply` and `node <distPath>/exec.mjs validate` with `tailor seed validate`, and delete the stale generated `<distPath>/exec.mjs` file. Seed data and schema generation (`data/*.jsonl`, `data/*.schema.ts`) is unchanged, and the `tailor seed apply` options mirror the old script (`--machine-user`, `--namespace`, `--skip-idp`, `--truncate`, `--yes`, entity-name arguments), plus a new `--upsert` flag to update existing rows instead of failing on duplicate ids.
 
 Before:
 
@@ -1394,8 +1448,8 @@ CLI plugin (@tailor-platform/sdk-plugin-seed) replaces it:
 - Install @tailor-platform/sdk-plugin-seed as a devDependency next to
   @tailor-platform/sdk.
 - Replace `node <distPath>/exec.mjs [options] [types...]` invocations with
-  `tailor seed apply [options] [types...]` (same options: --machine-user/-m,
-  --namespace/-n, --skip-idp, --truncate, --yes, and type-name arguments,
+  `tailor seed apply [options] [entities...]` (same options: --machine-user/-m,
+  --namespace/-n, --skip-idp, --truncate, --yes, and entity-name arguments,
   plus a new --upsert flag to update existing rows instead of failing on
   duplicate ids).
 - Replace `node <distPath>/exec.mjs validate [path]` with
@@ -1609,7 +1663,7 @@ The CLI stores human users by their stable subject ID instead of email (email is
 
 ### 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. No source change is required; ensure your environment runs Node.js 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+.
 
 ### Legacy bundle artifact cleanup removed from deploy
 

package/docs/migration/v3.md

@@ -0,0 +1,41 @@
+# Migrating to v3
+
+<!-- Generated from the sdk-codemod registry. Run `pnpm codemod:docs:update` and edit `packages/sdk-codemod/src/registry.ts` instead of this file. -->
+
+Run the codemods, then finish anything reported as not migrated automatically:
+
+```sh
+npx @tailor-platform/sdk-codemod --from <current-version> --to <target-version>
+```
+
+## function test-run → function run
+
+**Migration:** Partially automatic
+
+Rename `tailor function test-run` invocations to `tailor function run`. `test-run` remains as a deprecated alias until it is removed in v3.
+
+Before:
+
+```sh
+tailor function test-run resolvers/add.ts --arg '{"a":1,"b":2}'
+```
+
+After:
+
+```sh
+tailor function run resolvers/add.ts --arg '{"a":1,"b":2}'
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+The `tailor function test-run` subcommand is renamed to `tailor function run`;
+the old name is removed in v3. Replace any remaining `function test-run`
+invocations the codemod did not rewrite (e.g. wrapped across lines or invoked
+through a package runner such as `npx @tailor-platform/sdk`) with
+`function run`. Leave prose that merely mentions the old subcommand name
+unchanged unless it documents a command to type.
+```
+
+</details>

package/docs/quickstart.md

@@ -12,7 +12,7 @@ Contact us [here](https://www.tailor.tech/demo) to get started.
 
 ### Install Node.js
 
-The SDK requires Node.js 22.15.0 or later. Install Node.js via your package manager by following the official Node.js instructions.
+The SDK requires Node.js 22.18.0 or later. Install Node.js via your package manager by following the official Node.js instructions.
 
 Alternatively, you can use [Bun](https://bun.sh/) as the runtime.
 

package/docs/services/aigateway.md

@@ -26,9 +26,7 @@ Configure an AI Gateway using `defineAIGateway()`:
 ```typescript
 import { defineAIGateway, defineConfig } from "@tailor-platform/sdk";
 
-const aiGateway = defineAIGateway("my-aigateway", {
-  authNamespace: "default",
-});
+const aiGateway = defineAIGateway("my-aigateway", {});
 
 export default defineConfig({
   name: "my-app",
@@ -40,14 +38,42 @@ export default defineConfig({
 
 ### authNamespace
 
-The auth namespace used to resolve request tokens against your workspace's auth configuration. Must match an existing auth namespace.
+The auth namespace used to resolve request tokens against your workspace's auth configuration. Optional — when omitted, it defaults to your application's own Auth service (local or external, the name passed to `defineAuth()`), which is what most AI Gateways need. Omitting it without an Auth service configured is rejected by `deploy`/`generate`, asking you to either define one or set `authNamespace` explicitly:
 
 ```typescript
-defineAIGateway("my-aigateway", {
-  authNamespace: "default",
+import { defineAIGateway, defineAuth, defineConfig } from "@tailor-platform/sdk";
+
+const auth = defineAuth("my-auth", {
+  // ...auth configuration...
+});
+
+const aiGateway = defineAIGateway("my-aigateway", {}); // defaults to "my-auth"
+
+export default defineConfig({
+  name: "my-app",
+  auth,
+  aiGateways: [aiGateway],
 });
 ```
 
+Type-checked and autocompleted against your own Auth service name via the generated `tailor.d.ts` (the `AuthNamespaceNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining an Auth service to refresh it. Before the first generate run, `authNamespace` accepts any string.
+
+To authenticate against a **different** application's Auth service, reference it as an [external resource](../configuration.md#external-resources) in your own config — `authNamespace` then defaults to it like any other Auth service:
+
+```typescript
+import { defineAIGateway, defineConfig } from "@tailor-platform/sdk";
+
+const aiGateway = defineAIGateway("my-aigateway", {}); // defaults to "shared-auth"
+
+export default defineConfig({
+  name: "my-app",
+  auth: { name: "shared-auth", external: true },
+  aiGateways: [aiGateway],
+});
+```
+
+An `authNamespace` that doesn't match any auth namespace in your workspace surfaces only at runtime, as `401 Unauthorized` on every request to the gateway.
+
 ### cors
 
 Optional list of allowed origins for browser-based clients. Each entry is one of:
@@ -61,7 +87,6 @@ An optional `:port` may be appended in all URL forms. Omitting `cors` (or passin
 
 ```typescript
 defineAIGateway("my-aigateway", {
-  authNamespace: "default",
   cors: ["https://app.example.com", "https://*.example.com"],
 });
 ```
@@ -81,8 +106,7 @@ const website = defineStaticWebSite("my-frontend", {
 });
 
 const aiGateway = defineAIGateway("my-aigateway", {
-  // Name of an auth namespace in your workspace; request tokens are resolved against it.
-  authNamespace: "default",
+  // authNamespace omitted: defaults to this app's own Auth service, declared below.
   cors: [website.url],
 });
 

package/docs/services/executor.md

@@ -374,7 +374,7 @@ must return the same input type.
 
 ### Authentication for Operations
 
-GraphQL and Workflow operations can specify an `invoker` to execute with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names defined in your auth config:
+`graphql`, `function`, `jobFunction`, and `workflow` operations can specify an `invoker` to execute with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names defined in your auth config:
 
 ```typescript
 import { createExecutor, scheduleTrigger } from "@tailor-platform/sdk";
@@ -390,6 +390,10 @@ export default createExecutor({
 });
 ```
 
+The machine user is resolved in your application's auth namespace — the name of your Auth service, local or external. `webhook` is the only operation kind that does not accept `invoker`, since it calls an external URL rather than acting inside your workspace.
+
+Without an `invoker`, the operation runs as whoever raised the trigger event, or anonymously when there is no such principal — as with a `schedule` trigger. Declare an `invoker` whenever the operation needs an identity of its own.
+
 ## Event Payloads
 
 Each trigger type provides specific context data in the callback functions.