@tailor-platform/sdk 1.60.3 → 1.63.0

package/docs/github-actions.md

@@ -0,0 +1,337 @@
+# GitHub Actions Integration
+
+`tailor-sdk setup github` generates a GitHub Actions workflow that deploys your
+Tailor Platform application automatically on push or tag.
+
+> **Beta:** This command is under active development. CLI flags, the generated
+> workflow, and the `.github/tailor-sdk.lock` schema may change before general
+> availability.
+
+## Quick start
+
+Run the command from the root of your SDK project (where `tailor.config.ts`
+lives):
+
+```bash
+# Branch target: deploy to stg on every push to main
+tailor-sdk setup github -n my-app-stg
+
+# Tag target: deploy to production when a tag is pushed, with an approval gate
+tailor-sdk setup github -n my-app-prod \
+  --tag --branch main --environment production
+```
+
+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.
+
+The generated workflow deploys to whichever workspace its
+`TAILOR_PLATFORM_WORKSPACE_ID` Environment variable points at — it never
+creates or renames a workspace. Provision the workspace and set that variable
+before the first deploy (see [Targeting a workspace](#targeting-a-workspace)).
+
+## Targets
+
+A _target_ is one workflow file that handles one deployment destination.
+Run `setup github` 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):
+
+```bash
+tailor-sdk setup github -n my-app-stg
+# Equivalent to:
+tailor-sdk setup github -n my-app-stg --branch main
+```
+
+What it does:
+
+- On **pull request**: runs `generate`, checks that generated files are
+  committed (`generate-check`), and posts a deployment plan as a PR comment.
+  (The plan and deploy jobs are independent; pull requests run plan only.)
+- On **push to the branch**: deploys. The deploy action runs `generate` and
+  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.
+
+Fork pull requests cannot read repository secrets. For forks, the plan step is
+automatically skipped; `generate-check` and other non-secret checks still run.
+
+### Tag target (recommended for production)
+
+The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
+pushed:
+
+```bash
+tailor-sdk setup github -n my-app-prod \
+  --tag --tag-pattern "v*" --branch main --environment production
+```
+
+What it does:
+
+- **`tailor-tag-guard`** (generated when `--branch` is supplied): checks that
+  the tagged commit is reachable from `main`. A tag on an unrelated commit is
+  silently skipped, not an error.
+- **`tailor-plan`**: runs `generate`, `generate-check`, and posts a plan
+  summary to the Actions step summary (no PR comment, because there is no PR).
+- **`tailor-deploy`**: waits for `tailor-plan`, then deploys. If the target
+  environment has required reviewers configured, GitHub requires their approval
+  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.
+
+### Choosing `--branch` for the tag target
+
+`--branch` has two different roles depending on the target kind:
+
+| 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.   |
+
+The workspace name (`--workspace-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
+select which workspace gets deployed (see
+[Targeting a workspace](#targeting-a-workspace)).
+
+## Targeting a workspace
+
+The generated `plan` and `deploy` jobs target a workspace by **id**, read from
+the `TAILOR_PLATFORM_WORKSPACE_ID` GitHub Environment variable. They never
+resolve a workspace by name and never create one. Set this variable per
+environment before the first deploy.
+
+Because the variable is scoped to a GitHub Environment, both the `plan` and
+`deploy` jobs declare `environment:` so the value resolves. When you omit
+`--environment`, the environment name defaults to the workspace name.
+
+1. Provision the workspace (once per environment) and obtain its id. For now
+   this is a manual step:
+
+   ```bash
+   tailor-sdk workspace create   # copy the printed workspace id
+   ```
+
+2. Set the id as the Environment variable (the environment name is your
+   `--environment` value, or the workspace name when omitted):
+
+   ```bash
+   gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
+   ```
+
+If `TAILOR_PLATFORM_WORKSPACE_ID` is unset, `deploy` fails because the target
+workspace is not provisioned, and `plan` reports that the workspace is not
+provisioned yet instead of running a dry-run.
+
+If the target environment has required reviewers, that approval gate applies to
+the `plan` job as well as `deploy`, because `plan` must enter the environment to
+read the variable. (A token-based read that lets `plan` run without entering the
+environment is planned.)
+
+## Generated files
+
+Running `setup github` creates or updates:
+
+### `.github/workflows/tailor-<workspace-name>.yml`
+
+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 setup steps. For post-install
+extras (such as `playwright install`), add a step _after_ them.
+
+Note that re-running `setup github` 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.)
+
+### `.github/tailor-sdk.lock`
+
+A machine-owned JSON file that tracks which files the SDK manages, the inputs
+they were generated from, and their content hashes. **Commit this file. Never
+edit it by hand.** The SDK uses it to recognize its own files on re-runs and to
+detect hand edits.
+
+### `tailor.config.ts` (id injection)
+
+If your config does not already have an `id` field, `setup github` injects one.
+This `id` must be committed alongside the workflow file. In CI, `tailor-sdk
+deploy` refuses to inject a new id — if the id were assigned fresh on each CI
+run, every deploy would create a brand-new application and lose ownership of
+previously deployed resources.
+
+If your pipeline intentionally deploys a fresh, throwaway application on every
+run (for example an end-to-end test harness that creates and deletes its own
+workspace), set `TAILOR_PLATFORM_SDK_ALLOW_CI_ID_INJECTION=true` to opt back
+into automatic id injection for that pipeline.
+
+## Secrets
+
+The generated workflow reads two secrets:
+
+| Secret                                       | Description                |
+| -------------------------------------------- | -------------------------- |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Machine user client ID     |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Machine user client secret |
+
+Set them on the target GitHub Environment (the `--environment` value, or the
+workspace name when omitted) with the GitHub CLI:
+
+```bash
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
+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.
+
+## GitHub Environments (approval gate)
+
+Both the `plan` and `deploy` jobs are associated with a GitHub Environment — the
+`--environment` value, or the workspace name when omitted. The environment holds
+that target's `TAILOR_PLATFORM_WORKSPACE_ID` variable and machine-user secrets,
+and lets you:
+
+- **Require reviewer approval** before the jobs run (suitable for production).
+- **Scope secrets and the workspace-id variable** to specific environments so
+  staging and production deploy to separate workspaces with separate machine
+  users.
+
+To configure the environment, go to your repository's **Settings → Environments**
+and create an environment whose name matches the target's environment. Add
+required reviewers, the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and the
+environment-scoped secrets there.
+
+Required reviewers gate the `plan` job as well, because `plan` must enter the
+environment to read `TAILOR_PLATFORM_WORKSPACE_ID`. (A token-based read that
+lets `plan` run without entering the environment is planned.)
+
+## Manual runs and dry-run
+
+You can trigger the workflow manually from **Actions → Run workflow**. The
+`dry-run` input (boolean, default `false`) runs the plan job without
+deploying. Use this to preview what would change before executing a rollback
+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.
+
+## Monorepo setup
+
+For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:
+
+```bash
+tailor-sdk setup github -n my-app --dir apps/backend
+```
+
+The generated workflow adds a `paths` filter on `apps/backend/**` so the
+workflow only runs when that subdirectory changes. The `working-directory` for
+SDK commands is set accordingly.
+
+## Rollback
+
+`tailor-sdk deploy` is declarative: redeploying a past configuration returns
+the platform to that state. The recommended rollback approaches are:
+
+### Option 1 — Revert the commit (branch target)
+
+```bash
+git revert <commit-sha>
+git push
+```
+
+The push triggers the deploy job, which applies the reverted configuration. To
+preview the diff first, open the revert as a pull request (the plan job comments
+the diff) or use a `dry-run: true` manual dispatch before merging.
+
+### Option 2 — Advance the tag (tag target)
+
+Move the production tag to an earlier commit:
+
+```bash
+git tag -f v1.2.3 <earlier-commit-sha>
+git push --force-with-lease origin v1.2.3
+```
+
+Or create a new tag that points to the earlier commit:
+
+```bash
+git tag v1.2.4 <earlier-commit-sha>
+git push origin v1.2.4
+```
+
+### Option 3 — Manual dispatch with dry-run verification
+
+1. Go to **Actions → `Tailor (<workspace-name>)` → Run workflow**.
+2. Enter the tag or ref you want to redeploy.
+3. Set `dry-run` to `true` and run. Inspect the plan output.
+4. Run again with `dry-run` set to `false`.
+
+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.
+
+### Rollback limitations
+
+- **Schema and data are not rolled back.** If the older config expects a schema
+  state that no longer exists, the plan may show errors. In that case, review
+  the diff carefully before proceeding.
+- **Seed data** is not part of the deployment pipeline and is unaffected by
+  rollbacks.
+- **Static websites** are not yet integrated into the generated pipeline.
+  Static asset rollbacks must be performed manually.
+
+## Multi-environment example
+
+A typical setup with staging and production:
+
+```bash
+# Staging: main → stg (deploy on every push to main)
+tailor-sdk setup github -n my-app-stg
+
+# Production: tagged commits → prod, with approval gate and branch guard
+tailor-sdk setup github -n my-app-prod \
+  --tag --branch main --environment production
+```
+
+Then provision each workspace and set its id on the matching environment (the
+staging target's environment defaults to `my-app-stg`; production uses
+`production`):
+
+```bash
+gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg
+
+gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env production
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env production
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env production
+```
+
+Commit both workflow files and `.github/tailor-sdk.lock`.
+
+## Updating the generated workflow
+
+When you upgrade the SDK, re-run `setup github` 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-sdk.lock` file records the flags used at generation time,
+so you can check what arguments were used previously.

package/docs/services/tailordb-migration.md

@@ -312,6 +312,21 @@ Use cases:
 
 `migration set` does not perform a true rollback. To undo a schema/data change in production, write a new forward migration that reverses it (see [Rollback Strategy](#rollback-strategy)).
 
+## `migration sync` Semantics
+
+`tailor-sdk tailordb migration sync <N>` reconstructs the schema snapshot at migration `N` from the working tree's migration history and **overwrites the remote schema to match it**, then sets the `sdk-migration` label to `N`. Unlike `migration set`, it changes the remote schema as well as the bookkeeping. Like `set`, it never runs `migrate.ts` scripts itself — it only changes what the next `apply` considers pending:
+
+| Movement                         | Effect on next `apply`                                                                    | Effect on data                                                                                             |
+| -------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Backward (e.g., `0003` → `0001`) | Migrations `0002` and `0003` become pending and re-execute, including their `migrate.ts`. | Types absent from snapshot `0001` are deleted along with their data; re-executed scripts may rewrite data. |
+| Forward (e.g., `0001` → `0003`)  | Migrations `0002` and `0003` are skipped — their `migrate.ts` scripts will not run.       | Data the skipped scripts would have migrated stays as-is.                                                  |
+
+Before anything is sent to the remote, `sync` verifies that replaying the full migration history reproduces the current local type definitions. If it does not — because migration files were edited and no longer match, or because a schema change has not been recorded with `migration generate` yet — the command fails without touching the remote. This means a rewritten migration history is validated before it can overwrite the deployed schema.
+
+Because syncing backward causes already-applied scripts to re-execute on the next deploy, **write `migrate.ts` scripts to be idempotent** (see [Performance and Large Tables](#performance-and-large-tables) for resumable `where` clauses).
+
+The main use case is recovering from drift after a `deploy --no-schema-check` from an older revision: instead of checking out that revision, run `migration sync <N>` to restore the remote to a known snapshot, then `tailor-sdk deploy` to apply the remaining migrations from the working tree.
+
 ## Team Workflow and CI/CD
 
 ### Branch coordination
@@ -426,7 +441,8 @@ For genuinely different schemas across environments, prefer separate workspaces
 1. `tailor-sdk tailordb migration status` to see local vs remote.
 2. Compare with teammates — has someone applied different migrations?
 3. If remote was changed manually, decide whether to update local migrations to match or to use `migration set <N>` to align bookkeeping.
-4. As a last resort in non-production environments, `--no-schema-check` skips both checks. Do not use this as a routine workaround.
+4. To force the remote schema back to a known snapshot, use `migration sync <N>` (see [`migration sync` Semantics](#migration-sync-semantics)).
+5. As a last resort in non-production environments, `--no-schema-check` skips both checks. Do not use this as a routine workaround.
 
 ### "No machine user available for migration execution"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "1.60.3",
+  "version": "1.63.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -138,6 +138,7 @@
     "@0no-co/graphql.web": "1.2.0",
     "@badgateway/oauth2-client": "3.3.1",
     "@bufbuild/protobuf": "2.12.0",
+    "@bufbuild/protovalidate": "1.2.0",
     "@connectrpc/connect": "2.1.1",
     "@connectrpc/connect-node": "2.1.1",
     "@inquirer/core": "11.2.1",
@@ -175,14 +176,14 @@
     "pkg-types": "2.3.1",
     "politty": "0.5.1",
     "rolldown": "1.1.0",
-    "semver": "7.8.2",
+    "semver": "7.8.3",
     "sql-highlight": "6.1.0",
     "std-env": "4.1.0",
     "table": "6.9.0",
     "ts-cron-validator": "1.1.5",
     "tsx": "4.22.4",
     "type-fest": "5.7.0",
-    "undici": "8.4.0",
+    "undici": "8.4.1",
     "xdg-basedir": "5.1.0",
     "zod": "4.4.3"
   },

package/dist/application-D4tRNn90.mjs

@@ -1,4 +0,0 @@
-
-import { n as generatePluginFilesIfNeeded, r as loadApplication, t as defineApplication } from "./application-pusdxz35.mjs";
-
-export { defineApplication };