@tailor-platform/sdk 2.21.0 → 2.23.0

package/docs/cli/application.md

@@ -167,12 +167,20 @@ Before applying changes, `deploy` shows a preview of the planned resource change
 - `-` means the resource will be deleted
 - `±` means the resource will be replaced
 
+An update marked `[forced by SDK version]` shows no configuration difference from what is deployed. It is applied again only because resources of this application were last deployed with a different SDK version.
+
 After the detailed list, a summary line is printed:
 
 ```text
 Plan: 5 to create, 3 to update, 1 to delete
 ```
 
+When some updates are forced by the SDK version, the summary line also shows how many:
+
+```text
+Plan: 0 to create, 12 to update (11 forced by SDK version), 0 to delete
+```
+
 Use `--dry-run` to preview the plan without applying anything. In dry-run mode the plan is written to **stdout**, so it can be captured in CI without `2>&1`:
 
 ```bash
@@ -189,9 +197,16 @@ Pass the global `--json` / `-j` flag to get machine-readable output.
 
 ```json
 {
-  "summary": { "create": 2, "update": 1, "delete": 0, "replace": 0 },
+  "summary": { "create": 2, "update": 2, "delete": 0, "replace": 0, "forcedBySdkVersion": 1 },
   "changes": [
-    { "action": "create", "name": "Order", "labels": ["table"], "namespace": "tailordb" }
+    { "action": "create", "name": "Order", "labels": ["table"], "namespace": "tailordb" },
+    {
+      "action": "update",
+      "name": "Customer",
+      "labels": ["table"],
+      "namespace": "tailordb",
+      "forcedBySdkVersion": true
+    }
   ],
   "warnings": [
     { "type": "unmanaged", "resourceType": "tailorDB", "name": "LegacyType" },
@@ -201,15 +216,18 @@ Pass the global `--json` / `-j` flag to get machine-readable output.
 }
 ```
 
-- `summary` — counts of each change type.
-- `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`.
+- `summary` — counts of each change type. `forcedBySdkVersion` counts the updates forced by the SDK version, which are also included in `update`.
+- `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`. An update forced by the SDK version also has `forcedBySdkVersion: true`.
 - `warnings` — resources not in config (`type: "unmanaged"`) or secrets with missing values (`type: "skippedSecret"`). Unmanaged resources require confirmation in apply mode (apply is cancelled if declined); skipped secrets are non-blocking.
 - `conflicts` — resources owned by another application that conflict with the current config. Require confirmation in apply mode; apply is cancelled if declined.
 
 **Apply** (`--json`): writes a JSON object to stdout:
 
 ```json
-{ "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0 }, "status": "applied" }
+{
+  "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0, "forcedBySdkVersion": 0 },
+  "status": "applied"
+}
 ```
 
 ## remove

package/docs/cli/function.md

@@ -129,9 +129,9 @@ $ tailor function logs <execution-id> --follow
 
 **Notes**
 
-Execution details include `logEntries`, the structured log lines (message, severity, timestamp) recorded while the function ran. They are available while the execution is still running, whereas the flat `logs` string is filled in only after completion. The human-readable view shows the structured entries when present and falls back to `logs` otherwise.
+Execution details include `logEntries`, the structured log lines (message, severity, timestamp) recorded while the function ran. They are available while the execution is still running. The `logs` string joins their messages with newlines.
 
-Use `--follow` to keep polling a running execution and print new log entries as they arrive until it completes. Polling continues while the execution is suspended at a wait point, and indefinitely unless `--timeout` is set. On environments where no structured entries are returned, `--follow` shows the flat `logs` string once the execution completes. With `--json`, `--follow` waits for completion and then emits the final execution details once.
+Use `--follow` to keep polling a running execution and print new log entries as they arrive until it completes. Polling continues while the execution is suspended at a wait point, and indefinitely unless `--timeout` is set. With `--json`, `--follow` waits for completion and then emits the final execution details once.
 
 When viewing a specific execution that failed, the command displays error details with the stack trace mapped back to your original source files (clickable file links and code snippets, matching `function run` output).
 

package/docs/cli-reference.md

@@ -12,12 +12,12 @@ tailor <command> [options]
 
 <a id="global-options"></a>
 
-| Option                                      | Alias | Description                                         | Required | Default |
-| ------------------------------------------- | ----- | --------------------------------------------------- | -------- | ------- |
-| `--env-file <ENV_FILE>`                     | `-e`  | Path to the environment file (error if not found)   | No       | -       |
-| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | -     | Path to the environment file (ignored if not found) | No       | -       |
-| `--verbose`                                 | -     | Enable verbose logging                              | No       | `false` |
-| `--json`                                    | `-j`  | Output as JSON                                      | No       | `false` |
+| Option                                      | Alias | Description                                         | Required | Default | Env                  |
+| ------------------------------------------- | ----- | --------------------------------------------------- | -------- | ------- | -------------------- |
+| `--env-file <ENV_FILE>`                     | `-e`  | Path to the environment file (error if not found)   | No       | -       | -                    |
+| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | -     | Path to the environment file (ignored if not found) | No       | -       | -                    |
+| `--verbose`                                 | -     | Enable verbose logging                              | No       | `false` | -                    |
+| `--json`                                    | `-j`  | Output as JSON                                      | No       | `false` | `TAILOR_JSON_OUTPUT` |
 
 ### Progress and Detailed Logs
 
@@ -34,6 +34,14 @@ human-readable text or empty stdout.
 Commands that only perform side effects and do not define a structured result may leave stdout empty
 even when `--json` is passed.
 
+Set `TAILOR_JSON_OUTPUT=true` (or `1`) to default every command to JSON without passing `--json`
+each time. This is intended for agents, scripts, and CI steps that parse CLI output. An explicit
+flag always wins, so `--json=false` forces table output even when the variable is enabled. The values
+`true`, `True`, `TRUE`, `t`, `T`, and `1` enable JSON; `false`, `False`, `FALSE`, `f`, `F`, and `0`
+keep table output. Other values are rejected. JSON mode also disables interactive prompts, so set the
+variable per invocation or per job rather than exporting it from a shell profile; a command that
+needed a prompt names what selected JSON when it refuses.
+
 Errors, warnings, progress, and diagnostic messages are written to stderr. After argument parsing,
 a command failure under `--json` emits a JSON error envelope to stderr. Failures you can act on — an
 invalid or missing option, a resource that does not exist, an invalid configuration, or an unmet
@@ -96,14 +104,15 @@ is unchanged. Workflows that already echo their own `::error::` around the CLI k
 those messages describe the workflow's own checks, which can fail even when the CLI succeeds.
 
 When the failure has a known source, the annotation carries it: `seed validate` reports the
-offending JSONL file and line, and a rejected config reports its file — or, when the config or a
-file it imports cannot be parsed, that file and the line it failed on. Locations are written
-relative to `GITHUB_WORKSPACE`; a file outside it is annotated without a location rather than with
-a path the runner cannot resolve.
+offending JSONL file and line, including a line that is not valid JSON, and a rejected config
+reports its file — or, when the config or a file it imports cannot be parsed, that file and the line
+it failed on. Locations are written relative to `GITHUB_WORKSPACE`; a file outside it is annotated
+without a location rather than with a path the runner cannot resolve.
 
 For a JSONL file containing a blank line, the annotation's line and the line printed in the report
 text differ: the annotation counts every line in the file, while the printed line counts only the
-records. The annotation points at the row as an editor numbers it.
+records. The annotation points at the row as an editor numbers it. A line that is not valid JSON is
+printed with the line an editor shows, so both agree.
 
 `generate` and `deploy` do not group their per-service progress.
 
@@ -225,7 +234,8 @@ Resolution rules:
   then forwarded, so when the same flag appears on both sides the later one wins. A flag the host
   does not define — including one only some commands declare, such as `--profile` — still has to be
   typed after the plugin's own subcommand. `--help` and `--version` are answered by the host CLI and
-  never dispatch a plugin.
+  never dispatch a plugin. Setting `TAILOR_JSON_OUTPUT=true` also works, which plugins inherit from
+  the environment.
 
 Because resolution is based on `node_modules/.bin` and `PATH`, any package manager that populates
 `node_modules/.bin` works for project-local plugins — npm, pnpm (its content-addressable store is

package/docs/configuration.md

@@ -403,7 +403,7 @@ export default defineConfig({
 
 ### Plugins
 
-Configure plugins using `definePlugins()`. Plugins must be exported as a named export.
+Configure plugins using `definePlugins()`, exported as `export const plugins`.
 
 ```typescript
 import { definePlugins } from "@tailor-platform/sdk";

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.23.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,19 +186,19 @@
     "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",
     "pkg-types": "2.3.3",
-    "rolldown": "1.2.9",
+    "rolldown": "1.2.11",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
     "std-env": "4.2.0",
     "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,9 +213,9 @@
     "@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",
-    "oxlint-tsgolint": "7.0.2002",
+    "oxfmt": "0.70.0",
+    "oxlint": "1.85.0",
+    "oxlint-tsgolint": "7.0.2003",
     "sonda": "0.14.0",
     "tsdown": "0.23.0",
     "typescript": "6.0.3",