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

package/docs/configuration.md

@@ -27,7 +27,7 @@ export default defineConfig({
   cors: ["https://example.com"],
   allowedIpAddresses: ["192.168.1.0/24"],
   disableIntrospection: false,
-  logLevel: process.env.LOG_LEVEL ?? "DEBUG",
+  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
 });
 ```
 
@@ -41,16 +41,18 @@ export default defineConfig({
 
 **Disable Introspection**: Disable GraphQL introspection. Default is `false`.
 
-**Log Level**: Controls which `console.*` calls are kept when deployment functions are bundled. Supported values are `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`, and `"SILENT"`. The default is `"DEBUG"` and keeps all console calls. `console.log` is treated as a DEBUG-level call (matching the platform's OpenTelemetry severity mapping), so it is dropped at `"INFO"` and above. For production deployments, use `"WARN"` to keep `console.warn` and `console.error` while dropping debug, log, and info calls:
+**Log Level**: Controls which `console.*` and `logger.*` (from `@tailor-platform/sdk/runtime`) calls are kept when deployment functions are bundled. Supported values are `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`, and `"SILENT"`. The default is `"DEBUG"` and keeps all calls. `console.log` is treated as a DEBUG-level call (matching the platform's OpenTelemetry severity mapping), so it is dropped at `"INFO"` and above, alongside `console.debug` and `logger.debug`. `logger.setAttributes` has no severity and is never dropped, regardless of `logLevel`. For production deployments, use `"WARN"` to keep warn/error calls while dropping debug, log, and info calls:
 
 ```typescript
 export default defineConfig({
   name: "my-app",
-  logLevel: process.env.LOG_LEVEL ?? "DEBUG",
+  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
 });
 ```
 
-This is a bundle-time setting. Changing `LOG_LEVEL` affects newly bundled deployments; already deployed functions must be redeployed.
+This is a bundle-time setting. Changing `TAILOR_APP_LOG_LEVEL` affects newly bundled deployments; already deployed functions must be redeployed.
+
+Only `logger.*` calls made through the SDK's `logger` wrapper (from `@tailor-platform/sdk/runtime` or its `@tailor-platform/sdk/runtime/logger` subpath), or written as `globalThis.tailor.logger.*`, are covered. Other equivalent forms — such as the bare `tailor.logger.*` global or `self.tailor.logger.*` — are not affected by `logLevel`.
 
 ### Service Configuration
 
@@ -82,6 +84,23 @@ export default defineConfig({
 
 **ignores**: Glob patterns to exclude files. Optional. By default, `**/*.test.ts` and `**/*.spec.ts` are automatically ignored. If you explicitly specify `ignores`, the default patterns will not be applied. Use `ignores: []` to include all files including test files.
 
+**Pattern resolution**: `files` and `ignores` patterns are resolved relative to the directory of the `tailor.config.ts` file that declares them, not the directory you run the command from. This matters when deploying [multiple configs](./cli/application.md#deploy) together — each config's patterns only match files under its own directory. If a config's _relative_ patterns match nothing under its own directory, the SDK falls back to resolving them from the directory you ran the command from and logs a warning (this fallback doesn't apply to already-absolute patterns, since their resolution can't change). Update such patterns to be relative to the config's own directory — this fallback will be removed in v2.
+
+### Bundling
+
+Resolvers, executors, workflow jobs, auth hooks, HTTP adapters, TailorDB hooks and validators, functions, seeds, queries, and migration scripts are all bundled before running locally or deploying. Bundling honors `compilerOptions.paths` aliases declared in a `tsconfig.json`, resolved against the importing file's own nearest `tsconfig.json` (the first one found walking up from that file's directory, following its `extends` chain) — so a path alias works the same whether it is imported directly or through another aliased import.
+
+An import that cannot be resolved fails the command instead of shipping a broken bundle, naming the specifier, the importing file, and the tsconfig the build used:
+
+```
+Error [UNRESOLVED_IMPORT]: Could not resolve "@lib/missing" imported from "/path/to/resolver.ts".
+  Suggestion: Check that each import path is correct, and that a `compilerOptions.paths`
+  entry covering it is declared in the importing file's own tsconfig.json or an ancestor.
+  The build used "/path/to/tsconfig.json".
+```
+
+If the unresolved specifier is a Node.js built-in (e.g. `fs`, `crypto`, `path`), the suggestion explains that it is not available in the Tailor Platform runtime and, where one exists, names a Web-standard replacement (e.g. the Fetch API instead of `http`/`https`).
+
 ### External Resources
 
 You can reference resources managed by Terraform or other SDK projects to include them in your application's subgraph. External resources are not deployed by this project but can be used for shared access across multiple applications.
@@ -108,7 +127,8 @@ When using external resources:
 - The resource must be deployed and available before referencing it
 - You can combine external resources with locally-defined resources
 - TailorDB type names must remain unique across local and external TailorDB namespaces; `deploy` checks external TailorDB type names before applying changes
-- Destructive operations like `tailordb truncate` (and `seedPlugin`'s `seed:reset`) automatically exclude external resources to prevent accidental data loss in shared resources
+- Destructive operations like `tailordb truncate` (and `tailor seed apply --truncate`) automatically exclude external resources to prevent accidental data loss in shared resources
+- Subscribing an executor to an external resource's events requires the config that owns the resource in the same `deploy`. Publishing is then enabled automatically, and `deploy` records the dependency so a later deploy without that config asks for confirmation instead of silently turning publishing off
 
 ### Built-in IdP
 
@@ -118,8 +138,14 @@ Configure the Built-in IdP service using `defineIdp()`. See [IdP](./services/idp
 import { defineIdp } from "@tailor-platform/sdk";
 
 const idp = defineIdp("my-idp", {
-  authorization: "loggedIn",
   clients: ["my-client"],
+  permission: {
+    create: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    read: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    update: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    delete: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+  },
 });
 
 export default defineConfig({
@@ -263,6 +289,40 @@ export async function main(trx: Transaction, { env }: MigrationContext): Promise
 }
 ```
 
+#### Secret Detection
+
+`env` values are deployed as plaintext, so loading a config fails when one of them looks like a credential:
+
+```
+✖ Secret detected in 'env' in /path/to/tailor.config.ts:
+  - env.SLACK_BOT_TOKEN (matched slack: SLACK_TOKEN)
+    https://github.com/secretlint/secretlint/blob/master/packages/%40secretlint/secretlint-rule-slack/README.md#SLACK_TOKEN
+```
+
+Each finding names the pattern that matched and links to its description, so a value flagged as an AWS account id is distinguishable from one flagged as an AWS secret access key.
+
+Move the value to [Secret Manager](./services/secret.md) to fix this. Detection recognizes the credential formats published by common providers, such as Slack, GitHub and AWS.
+
+A value that is merely long and random-looking, with no recognizable provider format, is reported as a warning instead and does not fail the command.
+
+When detection is wrong about a value, allow it in place with `allowSecretReason`, stating why the value is safe to deploy as plaintext:
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  env: {
+    slackRelayUrl: {
+      value: process.env.SLACK_RELAY_URL ?? "",
+      allowSecretReason: "Public relay endpoint; the token it proxies stays in Secret Manager.",
+    },
+  },
+});
+```
+
+This silences both the failure and the warning, so it also covers a value that is random-looking without being a credential — say so in the reason. Only string and number values accept an allowance: a boolean is never flagged, so it never needs one.
+
+Application code still reads `env.slackRelayUrl` as the value itself: the wrapper only carries the reason and does not reach the deployed application.
+
 ### Workflow Service
 
 Configure Workflow service by specifying glob patterns for workflow files:
@@ -280,6 +340,30 @@ export default defineConfig({
 
 **ignores**: Glob patterns to exclude files. Optional.
 
+### Workflow Execution Policies
+
+Register workspace-scoped execution policies that workflow job functions reference at runtime for per-key concurrency control. See [Execution Policies](./services/workflow.md#execution-policies) in the Workflow guide for the declaration API.
+
+```typescript
+import { defineWorkflowExecutionPolicies } from "@tailor-platform/sdk";
+
+const executionPolicies = defineWorkflowExecutionPolicies((define) => ({
+  premium: define({ concurrencyPolicy: { maxConcurrentExecutions: 5 } }),
+  tenantApi: define({
+    name: "tenant-api",
+    matchType: "prefix",
+    concurrencyPolicy: { maxConcurrentExecutions: 3 },
+  }),
+}));
+
+export default defineConfig({
+  workflow: {
+    files: ["workflows/**/*.ts"],
+    executionPolicies,
+  },
+});
+```
+
 ### Plugins
 
 Configure plugins using `definePlugins()`. Plugins must be exported as a named export.

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.