@tailor-platform/sdk 2.28.0 → 2.29.0

package/docs/github-actions.md

@@ -35,7 +35,8 @@ tailor setup ci tag --name my-app-prod \
 
 After running the command, follow the **Next steps** printed to the terminal:
 run `tailor setup ci env` to get the commands that set the secrets and
-variables each GitHub Environment needs (see
+variables each GitHub Environment needs, and `tailor setup ci env --check` to
+confirm none is missing (see
 [Setting secrets and variables](#setting-secrets-and-variables)), then commit
 the generated files.
 
@@ -98,7 +99,8 @@ The generated workflow builds one self-contained ERD viewer HTML file for each
 owned TailorDB namespace in `tailor.config.ts`. The viewer compares the pull
 request merge result with the base branch, can switch between the current schema
 and highlighted diff, uploads the HTML files as unarchived Actions artifacts,
-and upserts a PR comment with artifact links.
+and upserts a PR comment with artifact links. On GitHub Enterprise Server, also
+pass `--ghes` (see [GitHub Enterprise Server](#github-enterprise-server)).
 
 ERD preview does not use Tailor Platform credentials. Fork pull requests still
 build artifacts, but the comment step is skipped because fork tokens cannot
@@ -264,8 +266,8 @@ Everything else is yours, and re-running `setup` keeps it:
 - **These inputs of managed steps:** `ignore` on `tailor-generate-check` and
   `tailor-drift-check`, `fail-on-drift` on `tailor-drift-check`,
   `install-command` on `tailor-install`, `node-version-file` on
-  `tailor-setup`, `label` on `tailor-plan`, and `user-mapping` on
-  `tailor-notify`.
+  `tailor-setup`, `label` on `tailor-plan`, `ttl` on `tailor-preview-deploy`,
+  and `user-mapping` on `tailor-notify`.
 - **Your own jobs in the `needs` of `tailor-result` and
   `tailor-preview-result`**, so they count toward the workflow's result (see
   [Requiring the workflow in branch protection](#requiring-the-workflow-in-branch-protection)).
@@ -296,6 +298,17 @@ The job is skipped whenever `tailor-preview-deploy` is skipped: when a pull
 request is closed, for draft and fork pull requests, and for unlabeled ones with
 `--require-preview-label`.
 
+A preview workspace expires 7 days (`ttl: 7d` on `tailor-preview-deploy`) after
+the last push to its pull request. When a pull request is closed,
+`tailor-preview-cleanup` deletes its workspace and also deletes the other
+expired preview workspaces of the same workspace name in the folder
+(`TAILOR_PLATFORM_FOLDER_ID`, or directly under the organization when unset), so
+a workspace whose own cleanup never ran does not stay forever. A pull request
+that stays idle past the `ttl` can have its workspace deleted while it is still
+open; the next push creates a fresh one. Change `ttl` to keep previews longer or
+shorter. Workflows generated before this was added get these settings the next
+time you run `tailor setup update`.
+
 Each new preview workflow run for a pull request, such as after a push or when
 the pull request is closed, cancels the run still in progress for it, including
 your jobs, so they do not keep running against a workspace that the new run
@@ -468,14 +481,18 @@ protection rules no longer guard your deploys.
 Environment the generated workflows use, the commands that create the
 environment (only when it does not exist yet) and set its secrets and
 variables. It is read-only, so re-run it whenever you add a target. When the
-`origin` remote points at github.com, the output names that repository, so the
-commands work from any directory; otherwise `gh` resolves the repository from
-the current directory and the Terraform output leaves it as a placeholder.
+`origin` remote points at github.com, the output names that repository;
+otherwise it names the repository `gh repo view` reports for the current
+directory, with its host on GitHub Enterprise Server. Either way the commands
+work from any directory. When neither names a repository, `gh` resolves it from
+the current directory when you run the commands, and the Terraform output leaves
+it as a placeholder.
 
 ```bash
 tailor setup ci env                          # gh CLI commands (default)
 tailor setup ci env --format terraform       # Terraform for the integrations/github provider
 tailor setup ci env --environment my-app-stg # only one environment (repeat for several)
+tailor setup ci env --check                  # check what is registered in GitHub (see below)
 ```
 
 The list follows what each generated workflow actually reads:
@@ -517,6 +534,30 @@ protection settings (reviewers, wait timer, branch policy), so importing an
 environment keeps the approval gate you configured; remove the `lifecycle` block
 to manage those settings in Terraform instead.
 
+### Checking what is registered
+
+`tailor setup ci env --check` reads GitHub with `gh` and reports, for each
+environment, which of these entries are registered. It fails when a required
+entry is missing, reports missing optional entries without failing, and prints
+the `gh` commands that set only the missing entries, with where each value comes
+from. It changes nothing, and it checks names only, since GitHub never returns
+secret values.
+
+- An entry set on the repository, or on the organization and shared with the
+  repository, counts as registered, because the workflow reads it from there when
+  the environment does not set it. The report says where each entry was found.
+- An entry registered as the other kind, such as `TAILOR_PLATFORM_WORKSPACE_ID`
+  set as a secret, is reported as missing, because the workflow does not read it.
+  `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID` set as a secret still counts, with a
+  reminder to move it to a variable.
+- `gh` must be installed and logged in (`gh auth login`) as an account with write
+  access to the repository, which listing secrets and variables requires. GitHub
+  answers 404 for a private repository the account cannot see, so the check
+  reports that as an access problem, not as missing entries.
+
+`--environment` narrows the check the same way. `--check` cannot be combined with
+`--format terraform`.
+
 ## GitHub Environments (approval gate)
 
 Both the `plan` and `deploy` jobs are associated with a GitHub Environment — the
@@ -784,6 +825,48 @@ tailor setup ci env
 
 Commit both workflow files and `.github/tailor.lock`.
 
+## GitHub Enterprise Server
+
+The generated workflows also run on GitHub Enterprise Server. Prepare the
+server and its runners first:
+
+- **Runners:** GitHub Enterprise Server has no GitHub-hosted runners. Change
+  `runs-on` on the managed jobs to the labels of your self-hosted runners;
+  re-running `setup` keeps it (see
+  [Customizing the generated workflow](#customizing-the-generated-workflow)).
+  The runners need Actions runner 2.327.1 or later, which runs the Node 24
+  actions the workflows use, and `gh` and `jq` on `PATH` (plus `node` with
+  `--erd-preview`).
+- **Actions from github.com:** the workflows use `tailor-platform/actions`,
+  `actions/checkout`, `actions/setup-node`, `pnpm/action-setup`, and
+  `oven-sh/setup-bun` (and `actions/upload-artifact` with `--erd-preview`).
+  Make them available on the server with GitHub Connect or `actions-sync`. The
+  server ships its own copies of the `actions/*` ones, which may not include
+  the pinned versions: update them with `actions-sync`, or, with GitHub
+  Connect, delete them from the server's `actions` organization (see GitHub's
+  [Using the latest version of the official bundled actions](https://docs.github.com/en/enterprise-server@latest/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/using-the-latest-version-of-the-official-bundled-actions)).
+- **Environment settings:** sign `gh` in to the server
+  (`gh auth login --hostname <host>`) before you run `tailor setup ci env` in a
+  clone of the repository, so that the `gh` commands it prints and its Terraform
+  output target the server. When `gh` cannot tell the repository, the output
+  says to export `GH_HOST=<host>` before running the `gh` commands, or
+  `GITHUB_BASE_URL=https://<host>/` before running Terraform, so that they
+  call the server instead of github.com.
+
+With `--erd-preview`, also pass `--ghes`:
+
+```bash
+tailor setup ci branch --name my-app-stg --erd-preview --ghes
+```
+
+GitHub Enterprise Server does not support `actions/upload-artifact` v4 or
+later, which the workflow uses to upload each ERD viewer unzipped. With
+`--ghes`, the workflow uploads it with v3 instead, so each viewer is a zip
+file, and the PR comment links to the workflow run, which lists the artifacts.
+`setup update` keeps `--ghes`; pass it again whenever you re-run
+`setup ci branch`, or the workflow switches back to the upload that GitHub
+Enterprise Server does not support.
+
 ## Keeping dependencies and actions updated
 
 Run this command once from the repository root to add Renovate configuration:

package/docs/plugin/custom.md

@@ -516,9 +516,9 @@ export default createSoftDeletePlugin();
 ```typescript
 // plugins/soft-delete/executors/on-delete.ts
 import { createExecutor, recordDeletedTrigger } from "@tailor-platform/sdk";
-import type { TailorAnyDBType } from "@tailor-platform/sdk";
 import { withPluginContext } from "@tailor-platform/sdk/plugin";
 import { getDB } from "generated/tailordb";
+import type { TailorAnyDBType } from "@tailor-platform/sdk";
 
 interface SoftDeleteContext {
   sourceTable: TailorAnyDBType;

package/docs/services/resolver.md

@@ -11,64 +11,7 @@ Resolvers provide:
 - Access to TailorDB via Kysely query builder
 - User context for authentication/authorization
 
-## Comparison with Tailor Platform Pipeline Resolver
-
-The SDK's Resolver is a simplified version of Tailor Platform's [Pipeline Resolver](https://docs.tailor.tech/guides/resolver).
-
-| Pipeline Resolver                        | SDK Resolver                      |
-| ---------------------------------------- | --------------------------------- |
-| Multiple steps with different operations | Single `body` function            |
-| Declarative step configuration           | Imperative TypeScript code        |
-| Built-in TailorDB/GraphQL steps          | Direct database access via Kysely |
-| CEL expressions for data transformation  | Native TypeScript transformations |
-
-### Example Comparison
-
-**Pipeline Resolver (Tailor Platform native):**
-
-```yaml
-steps:
-  - name: getUser
-    operation: tailordb.query
-    params:
-      type: User
-      filter:
-        email: { eq: "{{ input.email }}" }
-  - name: updateAge
-    operation: tailordb.mutation
-    params:
-      type: User
-      id: "{{ steps.getUser.id }}"
-      input:
-        age: "{{ steps.getUser.age + 1 }}"
-```
-
-**Resolver (SDK):**
-
-```typescript
-createResolver({
-  name: "incrementUserAge",
-  operation: "mutation",
-  input: { email: t.string() },
-  body: async (context) => {
-    const db = getDB("tailordb");
-    const user = await db
-      .selectFrom("User")
-      .selectAll()
-      .where("email", "=", context.input.email)
-      .executeTakeFirstOrThrow();
-
-    await db
-      .updateTable("User")
-      .set({ age: user.age + 1 })
-      .where("id", "=", user.id)
-      .execute();
-
-    return { oldAge: user.age, newAge: user.age + 1 };
-  },
-  output: t.object({ oldAge: t.int(), newAge: t.int() }),
-});
-```
+For the official Tailor Platform documentation, see [Resolver Guide](https://docs.tailor.tech/guides/resolver).
 
 ## Creating a Resolver
 

package/docs/services/tailordb-migration.md

@@ -425,7 +425,7 @@ Because steps commit separately, a failure does not undo the steps that already
 - If the steps changed since the earlier run, or that run is no longer available, every step runs again from the beginning. See [Editing steps of a migration in progress](#editing-steps-of-a-migration-in-progress).
 - If every step completed but the post-migration schema changes fail (for example, a field the migration makes required still has empty values), the migration also stays in progress with its pre-migration schema, and the next deploy retries those schema changes without running the steps again.
 - To run a completed step again (because it had a bug, or to fix rows the post-migration schema changes reject), change the steps: rename that step and update the `dependsOn` lists that name it, or add a step that fixes the rows. Every step then runs again from the beginning, so this relies on every step being safe to run again; to keep the other completed steps from running again, skip them as described below.
-- While a migration is in progress, `migration set`, `migration sync`, and `migration rebaseline` refuse to run, and `migration test` refuses to use that workspace as its source. Finish the migration with `tailor deploy` first. The one exception is `migration set <N>` with the in-progress migration's own number: it marks that migration as completed and clears its in-progress record. Use it only when the migration's schema changes are already applied, for example after the deploy reported that the checkpoint write could not be confirmed.
+- While a migration is in progress, `migration set`, `migration sync`, and `migration rebaseline` refuse to run, and `migration test` refuses to use that workspace as its source. Finish the migration with `tailor deploy` first, or settle it with `migration resolve` (see [Settling a migration that stays in progress](#settling-a-migration-that-stays-in-progress)). The one exception is `migration set <N>` with the in-progress migration's own number: it marks that migration as completed and clears its in-progress record. Use it only when the migration's schema changes are already applied, for example after the deploy reported that the checkpoint write could not be confirmed.
 
 #### Editing steps of a migration in progress
 
@@ -450,6 +450,15 @@ tailor deploy --migration-skip-steps main-db/backfillUser,main-db/backfillInvoic
 
 Write every step so that running it again is safe: besides the cases above, a step can run a second time when a deploy is interrupted right after it commits. Use `where` clauses that skip rows a step already migrated, as in the example. Rows written while a migration is in progress are not seen by steps that already completed. [Maintenance mode](#maintenance-mode) blocks GraphQL writes but not the writes your resolvers, executors, or workflows make through Kysely, and without it GraphQL clients can write too, so stop such writers until the migration finishes or write steps that tolerate them.
 
+### Settling a migration that stays in progress
+
+When you do not want to resume the migration with another deploy — you abandoned it, or you repaired the data by hand — settle it with `tailor tailordb migration resolve`. Pass exactly one of two options:
+
+- `--rollback` sends the schema of the migration before the failed one, clears the in-progress record, and leaves the checkpoint where it was. The next `tailor deploy` runs the failed migration again from its first step, so every step must be safe to run again. Data changes made by steps that already completed are not undone, and tables that exist only in the failed migration's schema are deleted with their data.
+- `--complete` sends the schema of the failed migration itself, clears the in-progress record, and moves the checkpoint to that migration, without running its `migrate.ts` again. Repair the data first, for example with `tailor query`, and make sure no record lacks a value for a field the migration makes required: the update is rejected while such a record exists, and the migration stays in progress.
+
+Tables that the failed migration removes are deleted with their data under `--complete`. The command refuses to run while an execution of the failed migration is still running; wait for it to finish first. Both options take the namespace's tables out of [maintenance mode](#maintenance-mode) and remove the temporary resources of the failed run. The command shows what it will change and asks for confirmation (`--yes` skips it). As with `migration sync`, the local migration history must reproduce the current table definitions, so settle the migration before you change the tables. If sending the schema stops partway, run the same command again.
+
 ## Supported Schema Changes
 
 | Change Type                       | Breaking? | Migration Script? | Notes                                                                                                                                                                                                                                              |
@@ -976,8 +985,8 @@ When `migrate.ts` already exists (the usual case for breaking changes, where `mi
 // migrations/0005/migrate.test.ts
 import { createKyselyMock } from "@tailor-platform/sdk/vitest";
 import { describe, expect, test } from "vitest";
-import type { Database } from "./db";
 import { main } from "./migrate";
+import type { Database } from "./db";
 
 describe("0005 add required email", () => {
   test("backfills null emails", async () => {
@@ -1013,9 +1022,9 @@ The generated `db.pglite.ts` exports the `CREATE TABLE` script for the same sche
 import { PGlite } from "@electric-sql/pglite";
 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";
+import type { Database } from "./db";
 
 const pglite = new PGlite();
 const db = createKyselyPGlite<Unmigrated<Database>>(pglite);

package/docs/services/workflow.md

@@ -488,9 +488,9 @@ Pass the runtime key through the `executionPolicyKey` option on `job.start()`. F
 
 ```typescript
 import { createWorkflowJob } from "@tailor-platform/sdk";
-import { executionPolicies } from "./policies";
-import { sendNotification } from "./jobs/send-notification";
 import { fetchTenant } from "./jobs/fetch-tenant";
+import { sendNotification } from "./jobs/send-notification";
+import { executionPolicies } from "./policies";
 
 export const mainJob = createWorkflowJob({
   name: "main-job",

package/docs/testing.md

@@ -44,9 +44,9 @@ The Tailor Platform function runtime only provides Web Standard APIs. Node.js bu
 ### Setup
 
 ```typescript
+import { tailorRuntime } from "@tailor-platform/sdk/vitest";
 // vitest.config.ts
 import { defineConfig } from "vitest/config";
-import { tailorRuntime } from "@tailor-platform/sdk/vitest";
 
 export default defineConfig({
   plugins: [tailorRuntime()],
@@ -590,9 +590,9 @@ describe("incrementUserAge resolver", () => {
 Once the logic gets more involved, mocking raw SQL calls becomes brittle. Push database access behind a `DbOperations` interface and test the pure function that uses it:
 
 ```typescript
+import type { Namespace } from "../generated/db";
 // src/resolver/decrementUserAge.ts
 import type { Selectable } from "@tailor-platform/sdk/kysely";
-import type { Namespace } from "../generated/db";
 
 export interface DbOperations {
   transaction: <T>(fn: (ops: DbOperations) => Promise<T>) => Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.28.0",
+  "version": "2.29.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -160,17 +160,16 @@
     "@jridgewell/trace-mapping": "0.3.31",
     "@napi-rs/keyring": "2.1.1",
     "@opentelemetry/api": "1.9.1",
-    "@opentelemetry/exporter-trace-otlp-proto": "0.222.0",
-    "@opentelemetry/resources": "2.11.0",
-    "@opentelemetry/sdk-trace-node": "2.11.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "0.223.0",
+    "@opentelemetry/resources": "2.12.0",
+    "@opentelemetry/sdk-trace-node": "2.12.0",
     "@opentelemetry/semantic-conventions": "1.43.0",
-    "@oxc-project/types": "0.152.0",
-    "@politty/zod": "0.4.3",
+    "@oxc-project/types": "0.154.0",
+    "@politty/zod": "0.5.1",
     "@secretlint/core": "13.0.7",
     "@secretlint/secretlint-rule-preset-recommend": "13.0.7",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@toiroakr/lines-db": "0.15.0",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.3",
     "amaro": "1.2.1",
@@ -184,9 +183,10 @@
     "graphql": "17.0.2",
     "inflection": "3.0.2",
     "kysely": "0.29.6",
+    "lines-db": "0.15.0",
     "mime-types": "3.0.2",
     "open": "11.0.4",
-    "oxc-parser": "0.152.0",
+    "oxc-parser": "0.154.0",
     "p-limit": "7.3.3",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
@@ -200,26 +200,26 @@
     "ts-cron-validator": "1.1.5",
     "type-fest": "5.10.0",
     "xdg-basedir": "5.1.0",
-    "zod": "4.6.5"
+    "zod": "4.6.7"
   },
   "devDependencies": {
-    "@electric-sql/pglite": "0.5.8",
-    "@opentelemetry/sdk-trace-base": "2.11.0",
+    "@electric-sql/pglite": "0.5.9",
+    "@opentelemetry/sdk-trace-base": "2.12.0",
     "@tailor-platform/shared": "^0.0.0",
     "@tailor-platform/tailor-proto": "^0.0.1",
     "@types/mime-types": "3.0.1",
     "@types/node": "24.19.2",
     "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "@vitest/coverage-v8": "5.0.3",
+    "@vitest/coverage-v8": "5.0.4",
     "eslint-plugin-zod": "5.0.0",
-    "oxfmt": "0.71.0",
-    "oxlint": "1.86.0",
-    "oxlint-tsgolint": "7.0.2003",
+    "oxfmt": "0.73.0",
+    "oxlint": "1.88.0",
+    "oxlint-tsgolint": "7.0.2004",
     "sonda": "0.14.0",
     "tsdown": "0.23.1",
     "typescript": "6.0.3",
-    "vitest": "5.0.3",
+    "vitest": "5.0.4",
     "zinfer": "0.4.7"
   },
   "peerDependencies": {