@tailor-platform/sdk 2.21.0 → 2.22.0

package/docs/github-actions.md

@@ -68,7 +68,9 @@ What it does:
   applies the config; it does not re-run the PR plan.
 - On **`workflow_dispatch`** with `dry-run: true`: runs plan only (useful for
   rollback verification — see [Rollback](#rollback)). With `dry-run: false`
-  (default) it deploys, like a push.
+  (default) it deploys the selected branch, like a push. Pass
+  `--restrict-dispatch` to deploy only the target branch this way (see
+  [Restricting manual deploys](#restricting-manual-deploys)).
 
 Fork pull requests cannot read repository secrets. For forks, the plan step is
 automatically skipped; `generate-check` and other non-secret checks still run.
@@ -129,7 +131,9 @@ What it does:
   before the deploy job starts.
 - On **`workflow_dispatch`**: the `tailor-tag-guard` result is ignored — the
   plan job runs regardless of branch reachability (useful for rolling back to
-  any tag). `dry-run: true` stops before the deploy job.
+  any tag). `dry-run: true` stops before the deploy job. With
+  `--restrict-dispatch`, the deploy job runs only for a tag that passes the
+  guard (see [Restricting manual deploys](#restricting-manual-deploys)).
 
 ### Choosing `--branch` for the tag target
 
@@ -190,20 +194,53 @@ Running a workflow setup subcommand creates or updates:
 The workflow file. The `name:` field is set to `Tailor (<workspace-name>)` so
 you can distinguish multiple workspaces in the Actions UI.
 
-Jobs and steps whose `id` starts with `tailor-` are managed by the SDK. Do not
-edit or rename them — the SDK tracks them by id.
-
-You can add your own jobs and steps around the managed ones. To add
-project-specific setup (such as private registry authentication or a system
-dependency), add a step _before_ the managed `tailor-setup` step. For
-post-install extras (such as `playwright install`), add a step _after_ it.
-
-Note that re-running `setup` currently regenerates the whole file: if
-the file differs from what the SDK last wrote — whether you edited a managed
-step or added your own — the command stops and reports the conflict. Pass
-`--force` to discard your edits and regenerate from the current template, then
-re-apply your own steps. (Preserving user-added steps across regeneration is
-planned.)
+See [Customizing the generated workflow](#customizing-the-generated-workflow)
+for what you can edit.
+
+### Customizing the generated workflow
+
+The SDK owns the jobs and steps whose `id` starts with `tailor-`, and the
+top-level keys it writes (`name:`, `on:`, and `permissions:` in a workflow; the
+metadata, inputs, and outputs of a composite action). Do not edit or rename
+them. Everything else is yours, and re-running `setup` keeps it:
+
+- **Your own jobs and steps.** Add them anywhere, without the `tailor-` prefix.
+  A step you add inside a managed job stays right after the managed step it
+  followed. For example, add private registry authentication or a system
+  dependency _before_ the managed `tailor-setup` step, and post-install extras
+  (such as `playwright install`) _after_ it. A job of your own can depend on a
+  managed job with `needs: tailor-deploy`.
+- **Your own top-level keys**, such as a workflow-level `env:` or `defaults:`.
+- **Runtime settings of managed jobs:** `runs-on`, `timeout-minutes`,
+  `container`, and `env`.
+- **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` and on a coordinator's steps that call an app action.
+- **The `run:` command of the `build-site` step** in a composite action.
+
+Comments above your own jobs and steps and at the end of the file are kept too.
+Comments inside managed jobs and steps, and edits to the header comment, are
+not kept.
+
+`setup check` reports an edit to a managed part, and re-running `setup` stops
+on it. Revert the edit, or pass `--force` to reset the managed parts to the
+current template; `--force` still keeps your own jobs, steps, and settings.
+A managed job or step you renamed counts as your own, so `--force` adds the
+managed one back next to it; rename it back instead of forcing. To start over
+from a clean template, delete the file and re-run `setup`.
+
+When a template update removes a managed job that contains steps of yours, or
+a job of yours `needs` a removed job, `setup` stops and names them. Move those
+steps into a job of your own (or update the `needs`) and re-run. `--force` drops
+steps left inside a removed job. It also stops when a new template version adds
+a managed job or step whose id you already use; rename yours, or pass `--force`
+to let the managed one replace it.
+
+Files generated by an older SDK version are compared as a whole, so the first
+re-run after upgrading stops if you edited the file in any way. Re-run once with
+`--force` to switch it to this model; your own jobs and steps are kept.
 
 ### `.github/tailor.lock`
 
@@ -277,7 +314,8 @@ gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg
 Setting them at the environment level isolates each target's credentials and
 keeps them alongside that environment's `TAILOR_PLATFORM_WORKSPACE_ID`
 variable. You can also set them as repository-level secrets if every target
-shares one machine user.
+shares one machine user, but then any workflow on any branch can read them, so
+the environment's protection rules no longer guard your deploys.
 
 ## GitHub Environments (approval gate)
 
@@ -309,8 +347,32 @@ or an out-of-band deploy. With `dry-run` off, a branch-target dispatch goes
 straight to deploy (like a push), while a tag-target dispatch runs plan first
 and then deploys.
 
-For tag targets, you can select any branch or tag when dispatching manually. The tag-guard check is skipped for manual dispatches, so
-you can deploy any commit regardless of branch membership.
+By default you can select any branch or tag when dispatching manually, and it
+deploys that ref. For tag targets, the tag-guard check is skipped for manual
+dispatches, so you can deploy any commit regardless of branch membership.
+
+### Restricting manual deploys
+
+Pass `--restrict-dispatch` to `setup ci branch`, `setup ci tag`, or
+`setup ci coordinate` to limit what a manual dispatch with `dry-run` off can
+deploy:
+
+- **Branch target:** only the target branch. Dispatching another branch skips
+  the deploy job.
+- **Tag target:** only a tag. With `--branch`, the tag must also pass the
+  reachability guard. The tag does not have to match `--tag-pattern`.
+
+Dry runs stay available from any ref. Re-run `setup` with the flag each time you
+regenerate the workflow; it is not carried over from the previous run.
+
+The flag guards against deploying the wrong ref by mistake. It is not an access
+control: a manual dispatch runs the workflow file from the selected ref, so
+anyone who can push a branch can remove the check there. To enforce which refs
+can deploy, configure **Deployment branches and tags** on the target's GitHub
+Environment and keep the machine-user secrets on that environment. Because the
+plan job also enters the environment, allow `refs/pull/*/merge` as well so pull
+request plans keep running, and note that dry runs from other branches are then
+rejected too.
 
 ## Monorepo setup
 
@@ -365,6 +427,8 @@ git push origin v1.2.4
 
 For tag targets, the tag-guard step is bypassed on manual dispatch, so you can
 dispatch from any ref. Environment approval (if configured) applies as usual.
+With `--restrict-dispatch`, step 4 deploys only a tag that passes the guard, and
+a branch target deploys only its target branch, so use Option 1 there.
 
 ### Rollback limitations
 
@@ -445,7 +509,8 @@ subcommand.
 
 `tailor setup check` audits the workflows recorded in
 `.github/tailor.lock` against your current config and repository, without
-writing anything. It reports when a workflow file is missing or hand-edited, a
+writing anything. It reports when a workflow file is missing or its SDK-managed
+parts were edited by hand, a
 newer template is available, `tailor.config.ts` is no longer under the recorded
 `--dir`, or the repository default branch no longer matches a branch target's
 trigger. It exits non-zero when it finds drift, so you can run it in CI. Each
@@ -474,10 +539,11 @@ itself at runtime.
 ## Updating the generated workflow
 
 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 same flags to pick up template improvements. Your own jobs, steps, and
+settings are kept (see
+[Customizing the generated workflow](#customizing-the-generated-workflow)). If
+you edited a managed part, the command stops; revert the edit or pass `--force`
+to reset it.
 
 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

@@ -84,18 +84,83 @@ After:
 import { definePlugins } from "@tailor-platform/sdk";
 import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
 
-export const generators = definePlugins(kyselyTypePlugin({ distPath: "db.ts" }));
+export const plugins = definePlugins(kyselyTypePlugin({ distPath: "db.ts" }));
 ```
 
 <details>
 <summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
 
 ```text
-defineGenerators() is replaced by definePlugins() in v2. The codemod rewrites the
-known plugin tuples (kysely-type, enum-constants, file-utils, seed). For any
-remaining defineGenerators([...]) the codemod left in place — a plugin it does not
+defineGenerators() is replaced by definePlugins() in v2, exported as `plugins` — the
+only export name the SDK reads plugins from. The codemod rewrites the known plugin
+tuples (kysely-type, enum-constants, file-utils, seed) and renames the export variable
+to `plugins` (left alone when the file already binds `plugins` to something else). For
+any remaining defineGenerators([...]) the codemod left in place — a plugin it does not
 know, or a non-tuple/spread form — convert it to definePlugins(pluginFn(config)),
-importing the matching plugin from its @tailor-platform/sdk/plugin/<name> subpath.
+importing the matching plugin from its @tailor-platform/sdk/plugin/<name> subpath, and
+assign the result to `export const plugins`.
+Merge any remaining exported plugin arrays into `plugins`, including bindings
+exported separately with `export { ... }`, and update their importing files.
+Only tailor.config module exports are renamed automatically; preserve helper-module
+exports and expose their plugins under the canonical config export manually.
+```
+
+</details>
+
+## generator/generators → plugins export rename
+
+**Migration:** Partially automatic
+
+Rename the plugin config export (and its imports) from generator/generators to plugins
+
+Before:
+
+```ts
+import { definePlugins } from "@tailor-platform/sdk";
+import myPlugin from "./plugins/my-plugin";
+
+export const generators = definePlugins(myPlugin());
+```
+
+After:
+
+```ts
+import { definePlugins } from "@tailor-platform/sdk";
+import myPlugin from "./plugins/my-plugin";
+
+export const plugins = definePlugins(myPlugin());
+```
+
+Also updates other files that import the export by its old name.
+
+Before:
+
+```ts
+import { generator } from "./tailor.config";
+```
+
+After:
+
+```ts
+import { plugins } from "./tailor.config";
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+The SDK only reads plugins from an export named `plugins`; `generator`/`generators` is
+already `definePlugins()` but under the old name. This codemod renames the export (and
+any `import { generator[s] } from ".../tailor.config"` elsewhere) to `plugins`. It
+leaves a file untouched when it already binds `plugins` to something else, or when a
+bare (unaliased) import's local usages cannot be safely told apart from an unrelated
+same-named binding in that file — rename those by hand to `plugins`.
+Multiple arrays or bindings exported separately with `export { ... }` need manual
+consolidation into the `plugins` export; update their importing files as well.
+Only tailor.config module exports are renamed automatically. Review aliased SDK
+factory calls and helper-module re-exports manually, preserving the helper API.
+Indirect config exports, namespace/dynamic imports, and wildcard re-exports are
+conservatively reported for review; keep unrelated values and canonical references unchanged.
 ```
 
 </details>

package/docs/plugin/index.md

@@ -33,7 +33,7 @@ export default defineConfig({
 });
 ```
 
-**Important**: The `plugins` export must be a named export (not default).
+**Important**: `definePlugins()` must be assigned to a named export called exactly `plugins` (not default, and not any other name).
 
 ### Attaching Plugins to Tables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -164,13 +164,13 @@
     "@opentelemetry/resources": "2.11.0",
     "@opentelemetry/sdk-trace-node": "2.11.0",
     "@opentelemetry/semantic-conventions": "1.43.0",
-    "@oxc-project/types": "0.149.0",
+    "@oxc-project/types": "0.151.0",
     "@politty/zod": "0.3.0",
     "@secretlint/core": "13.0.5",
     "@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.7",
+    "@toiroakr/lines-db": "0.13.0",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.3",
     "amaro": "1.2.1",
@@ -178,7 +178,7 @@
     "date-fns": "4.4.0",
     "es-toolkit": "1.52.0",
     "find-up-simple": "1.0.1",
-    "get-east-asian-width": "1.6.0",
+    "get-east-asian-width": "1.7.0",
     "get-tsconfig": "4.14.3",
     "globals": "17.12.0",
     "graphql": "17.0.2",
@@ -186,7 +186,7 @@
     "kysely": "0.29.6",
     "mime-types": "3.0.2",
     "open": "11.0.4",
-    "oxc-parser": "0.149.0",
+    "oxc-parser": "0.151.0",
     "p-limit": "7.3.3",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
@@ -198,7 +198,7 @@
     "temporal-polyfill": "1.0.5",
     "temporal-spec": "1.0.1",
     "ts-cron-validator": "1.1.5",
-    "type-fest": "5.9.0",
+    "type-fest": "5.10.0",
     "xdg-basedir": "5.1.0",
     "zod": "4.6.5"
   },
@@ -213,8 +213,8 @@
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "5.0.1",
     "eslint-plugin-zod": "4.14.2",
-    "oxfmt": "0.67.0",
-    "oxlint": "1.82.0",
+    "oxfmt": "0.70.0",
+    "oxlint": "1.85.0",
     "oxlint-tsgolint": "7.0.2002",
     "sonda": "0.14.0",
     "tsdown": "0.23.0",