@tailor-platform/sdk 2.0.0-next.1 → 2.0.0-next.10

package/docs/github-actions.md

@@ -1,10 +1,10 @@
 # GitHub Actions Integration
 
-`tailor-sdk setup github` generates a GitHub Actions workflow that deploys your
+`tailor setup` 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
+> workflow, and the `.github/tailor.lock` schema may change before general
 > availability.
 
 ## Quick start
@@ -14,13 +14,16 @@ lives):
 
 ```bash
 # Branch target: deploy to stg on every push to main
-tailor-sdk setup github -n my-app-stg
+tailor setup -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 \
+tailor setup -n my-app-prod \
   --tag --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.
@@ -33,7 +36,7 @@ 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.
+Run `setup` once per target.
 
 ### Branch target (recommended for staging)
 
@@ -41,9 +44,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-sdk setup github -n my-app-stg
+tailor setup -n my-app-stg
 # Equivalent to:
-tailor-sdk setup github -n my-app-stg --branch main
+tailor setup -n my-app-stg --branch main
 ```
 
 What it does:
@@ -60,13 +63,48 @@ What it does:
 Fork pull requests cannot read repository secrets. For forks, the plan step is
 automatically skipped; `generate-check` and other non-secret checks still run.
 
+#### ERD preview artifacts
+
+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
+```
+
+The generated workflow runs `tailor tailordb erd`, which is provided by the
+`@tailor-platform/sdk-plugin-tailordb-erd` CLI plugin — install it as a
+dev-dependency in your project:
+
+```bash
+npm install -D @tailor-platform/sdk-plugin-tailordb-erd@next
+```
+
+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.
+
+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
+removing TailorDB namespaces. `setup check` reports drift when the recorded ERD
+preview namespaces no longer match the current config.
+
 ### 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 \
+tailor setup -n my-app-prod \
   --tag --tag-pattern "v*" --branch main --environment production
 ```
 
@@ -115,7 +153,7 @@ Because the variable is scoped to a GitHub Environment, both the `plan` and
    this is a manual step:
 
    ```bash
-   tailor-sdk workspace create   # copy the printed workspace id
+   tailor workspace create   # copy the printed workspace id
    ```
 
 2. Set the id as the Environment variable (the environment name is your
@@ -136,7 +174,7 @@ environment is planned.)
 
 ## Generated files
 
-Running `setup github` creates or updates:
+Running `setup` creates or updates:
 
 ### `.github/workflows/tailor-<workspace-name>.yml`
 
@@ -148,17 +186,17 @@ 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.
+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 github` currently regenerates the whole file: if
+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.)
 
-### `.github/tailor-sdk.lock`
+### `.github/tailor.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
@@ -167,15 +205,15 @@ 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
+If your config does not already have an `id` field, `setup` injects one.
+This `id` must be committed alongside the workflow file. In CI, `tailor
 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
+workspace), set `TAILOR_CI_ALLOW_ID_INJECTION=true` to opt back
 into automatic id injection for that pipeline.
 
 ## Secrets
@@ -238,7 +276,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-sdk setup github -n my-app --dir apps/backend
+tailor setup -n my-app --dir apps/backend
 ```
 
 The generated workflow adds a `paths` filter on `apps/backend/**` so the
@@ -247,7 +285,7 @@ SDK commands is set accordingly.
 
 ## Rollback
 
-`tailor-sdk deploy` is declarative: redeploying a past configuration returns
+`tailor 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)
@@ -303,10 +341,10 @@ 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
+tailor setup -n my-app-stg
 
 # Production: tagged commits → prod, with approval gate and branch guard
-tailor-sdk setup github -n my-app-prod \
+tailor setup -n my-app-prod \
   --tag --branch main --environment production
 ```
 
@@ -324,14 +362,24 @@ 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`.
+Commit both workflow files and `.github/tailor.lock`.
+
+## Checking for drift
+
+`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
+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
+finding names a stable rule key for future suppression.
 
 ## Updating the generated workflow
 
-When you upgrade the SDK, re-run `setup github` with the same flags to pick up
+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.
 
-The `.github/tailor-sdk.lock` file records the flags used at generation time,
+The `.github/tailor.lock` file records the flags used at generation time,
 so you can check what arguments were used previously.