@tailor-platform/sdk 2.24.0 → 2.25.0

package/docs/cli/application.md

@@ -74,6 +74,29 @@ tailor deploy [options]
 | `--clean-cache`                         | -     | Clean the bundle cache before building                                               | No       | -                    | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+**JSON result:**
+
+After a successful `tailor deploy --json`, stdout includes `status: "applied"`,
+`summary`, `workspaceId`, and `applications` in config order. Each entry includes
+the config's `name`, `configPath`, and, when configured, `id`, plus `aiGateways`
+and `staticWebsites` keyed by site name. Endpoint `url` and `domain` are included
+when a Platform Application with that name exists. If Auth is configured, `auth`
+includes its `namespace` and `oauth2Clients` with each client's `name` and public `clientId`.
+Client secrets are excluded. These fields are returned even when no deploy plugin
+is registered or no resources changed.
+
+Plugins that return outputs add entries under `deployedHooks`. For example, the
+frontend plugin provides upload results in `deployedHooks[].outputs.frontends`.
+
+```sh
+tailor deploy --json > deploy-result.json
+jq '.applications[] | {name, url, staticWebsites, auth}' deploy-result.json
+```
+
+Dry-run and build-only deployments do not return deployed application information.
+If resources were applied but loading the JSON result fails, the command reports
+`DEPLOY_RESULT_LOAD_FAILED`; fix the error and run `tailor deploy` again.
+
 **Workspace Selection:**
 
 After validating the configuration file, `deploy` resolves a workspace before bundling the

package/docs/cli/secret.md

@@ -36,17 +36,21 @@ tailor secret create [options]
 
 **Options**
 
-| Option                          | Alias | Description               | Required | Default | Env                            |
-| ------------------------------- | ----- | ------------------------- | -------- | ------- | ------------------------------ |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
-| `--profile <PROFILE>`           | `-p`  | Workspace profile         | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
-| `--vault-name <VAULT_NAME>`     | `-V`  | Vault name                | Yes      | -       | -                              |
-| `--name <NAME>`                 | `-n`  | Secret name               | Yes      | -       | -                              |
-| `--value <VALUE>`               | `-v`  | Secret value              | Yes      | -       | -                              |
-| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` | -                              |
+| Option                          | Alias | Description                                          | Required | Default | Env                            |
+| ------------------------------- | ----- | ---------------------------------------------------- | -------- | ------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                         | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile                                    | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
+| `--vault-name <VAULT_NAME>`     | `-V`  | Vault name                                           | Yes      | -       | -                              |
+| `--name <NAME>`                 | `-n`  | Secret name                                          | Yes      | -       | -                              |
+| `--value <VALUE>`               | `-v`  | Secret value (read from standard input when omitted) | No       | -       | -                              |
+| `--yes`                         | `-y`  | Skip confirmation prompts                            | No       | `false` | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+Pass the value with `--value`, or omit `--value` and pipe the value in to keep it out of shell history and process listings, for example `printf '%s' "$STRIPE_KEY" | tailor secret create --vault-name api-keys --name stripe-secret-key`. A piped value can be up to 128 KiB, and one trailing newline is removed from it. In a vault managed by `defineSecretManager()`, the command asks for confirmation before releasing the vault from the config, which needs an interactive terminal, so pass `--yes` when piping the value.
+
 ### secret delete
 
 Delete a secret in a vault.
@@ -103,17 +107,21 @@ tailor secret update [options]
 
 **Options**
 
-| Option                          | Alias | Description               | Required | Default | Env                            |
-| ------------------------------- | ----- | ------------------------- | -------- | ------- | ------------------------------ |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID              | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
-| `--profile <PROFILE>`           | `-p`  | Workspace profile         | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
-| `--vault-name <VAULT_NAME>`     | `-V`  | Vault name                | Yes      | -       | -                              |
-| `--name <NAME>`                 | `-n`  | Secret name               | Yes      | -       | -                              |
-| `--value <VALUE>`               | `-v`  | Secret value              | Yes      | -       | -                              |
-| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false` | -                              |
+| Option                          | Alias | Description                                          | Required | Default | Env                            |
+| ------------------------------- | ----- | ---------------------------------------------------- | -------- | ------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                         | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile                                    | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
+| `--vault-name <VAULT_NAME>`     | `-V`  | Vault name                                           | Yes      | -       | -                              |
+| `--name <NAME>`                 | `-n`  | Secret name                                          | Yes      | -       | -                              |
+| `--value <VALUE>`               | `-v`  | Secret value (read from standard input when omitted) | No       | -       | -                              |
+| `--yes`                         | `-y`  | Skip confirmation prompts                            | No       | `false` | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+Pass the value with `--value`, or omit `--value` and pipe the value in to keep it out of shell history and process listings, for example `printf '%s' "$STRIPE_KEY" | tailor secret update --vault-name api-keys --name stripe-secret-key`. A piped value can be up to 128 KiB, and one trailing newline is removed from it. In a vault managed by `defineSecretManager()`, the command asks for confirmation before releasing the vault from the config, which needs an interactive terminal, so pass `--yes` when piping the value.
+
 ### secret vault
 
 Manage Secret Manager vaults.

package/docs/cli-reference.md

@@ -31,8 +31,16 @@ For commands that return structured results, passing `--json` writes one parseab
 to stdout on success. Empty successful result sets are emitted as JSON values such as `[]`, not as
 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.
+Many commands that change state print a JSON object describing the outcome. Its `changed` field is
+`true` when the command did work and `false` when it did nothing, for example because the requested
+state was already in place. The other fields identify what the command acted on and report details of
+the outcome. Other state-changing commands print a result without `changed`, or do not report a
+result yet and leave stdout empty even when `--json` is passed.
+
+List commands return at most `--limit` items. When more exist, the list is followed by a notice on
+stderr, `More results exist beyond --limit N. Raise --limit to see more.`, so `--json` output stays a
+plain array of the listed items. Log listings such as `executor jobs`, `function logs`, and
+`workflow executions` default to `--limit 50`; pass `--limit 0` to list everything.
 
 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
@@ -42,11 +50,13 @@ keep table output. Other values are rejected. JSON mode also disables interactiv
 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
-precondition — carry a stable `error.code` such as `PROFILE_NOT_FOUND`, `TAILORDB_NAMESPACE_NOT_FOUND`,
-or `MIGRATION_SCRIPT_REQUIRED`. Where a remediation exists, the envelope also includes
+Errors, warnings, progress, and diagnostic messages are written to stderr. A command failure under
+`--json` or `TAILOR_JSON_OUTPUT` emits a JSON error envelope to stderr, including a failure while
+parsing arguments: an unknown option or subcommand, or an option value that fails validation, is
+reported as `INVALID_ARGUMENTS`. Failures you can act on — an invalid or missing option, a resource
+that does not exist, an invalid configuration, or an unmet precondition — carry a stable `error.code`
+such as `PROFILE_NOT_FOUND`, `TAILORDB_NAMESPACE_NOT_FOUND`, or `MIGRATION_SCRIPT_REQUIRED`. Where a
+remediation exists, the envelope also includes
 `error.suggestion`, `error.help` (the `--help` invocation for the failing command), `error.next` (a
 runnable command), or `error.context`. `UNEXPECTED_ERROR` marks failures without a dedicated code,
 including SDK-internal errors. Diagnostic lines may precede the error envelope, and stdout is not
@@ -75,9 +85,11 @@ Use `--verbose` to include debug diagnostics and error stack traces. `DEBUG=true
 sets `RUNNER_DEBUG=1` when debug logging is enabled, so the same command automatically includes
 these details in a debug run. These settings do not enable JSON output; pass `--json` separately.
 
-Capture the original failure's stderr and exit code before retrying. Argument parsing and failures
-before the CLI starts may produce plain text even with `--json`. A failed deployment may have
-already applied changes, so inspect its output before deciding to run it again.
+Capture the original failure's stderr and exit code before retrying. Failures before the CLI starts,
+a rejected `--json` or `TAILOR_JSON_OUTPUT` value, argument errors in the bundled CLI plugins, and
+the install hint for a CLI plugin that is not installed may still produce plain text when JSON output
+is requested. A failed deployment may have already
+applied changes, so inspect its output before deciding to run it again.
 
 ### GitHub Actions Annotations
 
@@ -95,9 +107,9 @@ without reporting through the CLI's error path, such as one relaying a failed re
 writes no annotation.
 
 Set `TAILOR_GITHUB_ACTIONS_ANNOTATIONS=false` (also `off`, `no`, or `0`) to turn annotations off.
-Passing `--json` also suppresses them, so a workflow step that parses `--json` output gets only the
-error envelope on stderr. The flag is honored even when the command fails during argument parsing,
-before the envelope itself becomes available.
+Passing `--json` or setting `TAILOR_JSON_OUTPUT` also suppresses them, so a workflow step that parses
+JSON output gets only the error envelope on stderr, even when the command fails during argument
+parsing.
 
 An annotation does not by itself fail a step: the step still fails on the CLI's exit code, which
 is unchanged. Workflows that already echo their own `::error::` around the CLI keep working;

package/docs/github-actions.md

@@ -199,6 +199,14 @@ 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.
 
+Every checkout in the workflow sets `persist-credentials: false`, so the GitHub
+token is not left in `.git/config` while the job installs and runs your
+project's code. The tag guard step passes the job token only to its
+`git fetch`, and the plan step passes it to its `git fetch` and to the step that
+posts the plan comment on the pull request; neither writes it to `.git/config`.
+If installing your dependencies fetches git repositories
+that require authentication, configure the credentials in your own step.
+
 See [Customizing the generated workflow](#customizing-the-generated-workflow)
 for what you can edit.
 
@@ -218,7 +226,12 @@ them. Everything else is yours, and re-running `setup` keeps it:
   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`.
+  `container`, and `env`. On a managed job generated without an
+  `environment:` (such as `tailor-tag-guard` or `tailor-erd-preview`), you can
+  also add one, for example so a step you added there can read that GitHub
+  Environment's secrets. The `environment:` of `tailor-plan`, `tailor-deploy`,
+  and the preview jobs comes from `--environment`, so change it with that
+  option instead.
 - **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
@@ -479,9 +492,61 @@ For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:
 tailor setup ci branch --name 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.
+The `working-directory` for SDK commands is set accordingly, and the workflow
+only plans and deploys when that subdirectory changes. The workflow itself
+starts on every pull request and push: a `tailor-changes` job checks whether
+the change touches `apps/backend/**`, and the plan, deploy, and ERD preview jobs
+are skipped when it does not. A skipped job reports success, so you can make
+these checks required in branch protection; a workflow that a `paths` trigger
+filter never started would leave them pending instead. If the `tailor-changes` job
+itself fails (for example, on a GitHub API error), the plan, deploy, and ERD
+preview jobs fail too instead of being skipped, so a required check blocks
+merging and nothing is deployed. Re-run the failed jobs once the cause is gone.
+
+### Deploying several apps together
+
+To deploy several apps to the same workspace from one workflow, repeat `--dir`
+and pass `--name` for the workflow:
+
+```bash
+tailor setup ci branch --name erp --dir apps/erp/backend --dir apps/users/backend
+```
+
+`setup ci branch`, `setup ci tag`, and `setup ci preview` accept repeated
+`--dir`. The workflow plans and deploys every app's `tailor.config.ts` in one
+[multi-config deploy](./cli/application.md#deploy) from the repository root, so
+an app can reference resources of another app with `external: true`. Add
+`@tailor-platform/sdk` to the root `package.json` so the `tailor` CLI resolves
+there; setup stops until it is declared. The generate check runs for each app
+directory, as do seed validation and the migration drift check on branch and tag
+workflows, and a change under any app directory runs the workflow's jobs.
+
+With `--erd-preview`, each TailorDB namespace is previewed from the app that
+owns it. A namespace may be owned by only one app; the others reference it with
+`external: true`.
+
+With more than one app, the preview comment does not link an application URL.
+
+### Running on changes outside the app directories
+
+When the apps depend on code outside their directories, such as a frontend or
+shared packages, add those paths with `--paths` on `setup ci branch` or
+`setup ci preview`. Repeat it for each pattern:
+
+```bash
+tailor setup ci preview --name erp --region asia-northeast \
+  --dir apps/erp/backend --dir apps/users/backend \
+  --paths "apps/*/frontend/**" --paths "modules/**" --paths pnpm-lock.yaml
+```
+
+The patterns are checked after the app directories, in order, and the last
+pattern that matches a changed file decides whether it counts. `*` matches
+within one path segment, `**` matches any number of segments, and a pattern
+starting with `!` excludes matching paths, so it can also exclude files inside
+an app directory, for example `--paths '!apps/erp/backend/**/*.md'`. Other glob
+characters (`?`, `+`, `[ ]`, `{ }`, `( )`, and `\`) are not supported, and
+`setup ci` rejects a pattern that contains them. An app at the repository root already
+runs on every change, so `--paths` is not accepted with `--dir .`.
 
 ## Rollback
 

package/docs/plugin/custom.md

@@ -6,7 +6,7 @@ Create your own plugins by implementing the `Plugin` interface.
 
 ## Requirements
 
-**Plugins must use default export**:
+**Plugins with definition-time hooks must use default export**:
 
 ```typescript
 // plugin.ts
@@ -48,6 +48,9 @@ interface Plugin<TableConfig = unknown, PluginConfig = unknown> {
   onExecutorReady?(
     context: ExecutorReadyContext<PluginConfig>,
   ): GeneratorResult | Promise<GeneratorResult>;
+  onDeployed?(
+    context: DeployedContext<PluginConfig>,
+  ): void | DeployedHookResult | Promise<void | DeployedHookResult>;
 }
 ```
 
@@ -254,6 +257,78 @@ onExecutorReady(ctx) {
 },
 ```
 
+### onDeployed
+
+Runs once after every application in the deploy has been applied, including when
+there are no resource changes. Hooks run sequentially in config order, then in
+`definePlugins()` registration order. No `importPath` or table attachment is required.
+
+Use `ctx.application` for the registering application's ID, URL, domain, AI
+Gateway URLs, static websites, and public OAuth client IDs. `ctx.application.id`
+is the `id` from `defineConfig()` and is `undefined` when the config has none.
+`ctx.applications` contains all applications in a multi-config deploy with the
+same fields. OAuth client secrets are never included.
+
+`ctx.configPath` is the absolute path of the registering config. `ctx.workspaceId`
+and `ctx.pluginConfig` identify the deployment workspace and the plugin's options.
+Use `ctx.logger.info`, `warn`, and `success` for diagnostics; they write to stderr
+and preserve deploy's JSON stdout.
+
+```typescript
+import { definePlugins, type Plugin } from "@tailor-platform/sdk";
+
+const deployedInfo: Plugin = {
+  id: "@example/deployed-info",
+  description: "Reports the deployed application URL",
+  onDeployed(ctx) {
+    const url = ctx.application.url;
+    if (!url) return;
+    ctx.logger.success(`Application ready: ${url}`);
+    return { outputs: { url } };
+  },
+};
+
+export const plugins = definePlugins(deployedInfo);
+```
+
+To publish assets, look up the site with `ctx.application.staticWebsites[name]`
+and await its `publish(dir)` with an absolute directory path. Only websites
+declared in the registering config appear there; any other name is `undefined`,
+so check the site before publishing. Websites of other configs are listed under
+`ctx.applications` with their `name` and `url` only, so a plugin can read their
+URLs but cannot publish to them. The result contains `url` and `skippedFiles`; report skipped
+files so users can correct files that could not be uploaded.
+
+To run a shell command such as a build, await `ctx.exec(command, { workingDir, env })`.
+It rejects when the command exits with a non-zero code. By default the command's
+stdout and stderr both go to stderr so `tailor deploy --json` stdout stays parseable;
+pass `output: "capture"` to receive them as `stdout` and `stderr` instead, or
+`output: "ignore"` to discard them. Use `ctx.exec` rather than importing
+`node:child_process` in the plugin: `tailor.config.ts` is also bundled into
+functions that run on the Tailor Platform, such as auth hooks, and a plugin module
+that imports Node.js-only modules makes that bundle fail.
+
+Return JSON-serializable `outputs` to include a result in `deployedHooks` under
+`tailor deploy --json`. Each entry identifies the application and plugin. This
+key is omitted when no hook supplies outputs. `outputs` must be a plain object whose
+values are only strings, finite numbers, booleans, `null`, arrays, and plain objects;
+any other value, such as `undefined`, a function, or a `Date`, fails the hook.
+Output values may be typed with an `interface`. The type checker rejects a
+`Date`, function, `Map`, or other non-JSON value placed directly in `outputs` or in
+an object or array literal, but a `Date` or class instance nested inside an
+interface-typed value is caught only when `tailor deploy` runs the hook.
+
+A failed hook stops later hooks with `DEPLOYED_HOOK_FAILED`. The same error is
+reported when the deployed information passed to hooks cannot be loaded. Platform
+resources have already been applied and are not rolled back. The error lists any hooks
+that did not run, with the application each belongs to. Fix the hook and run `tailor deploy` again; hooks run again even
+if there are no resource changes.
+
+Hooks do not run during dry-run, build-only, or migration test deployments.
+Dry-run lists the pending hooks; with `--json`, they appear under
+`pendingDeployedHooks` as `{ application, pluginId }` entries. Calling `deploy()` from the programmatic CLI
+API runs hooks under the same conditions as `tailor deploy`.
+
 ## Hook Scheduling Rules
 
 Each generation-time hook runs at its own pipeline phase, regardless of what other hooks the same plugin implements:

package/docs/plugin/frontend.md

@@ -0,0 +1,124 @@
+# Frontend Plugin
+
+`frontendPlugin` builds frontend assets and uploads them to Static Websites after
+`tailor deploy` applies your application. It can provide deployed URLs and public
+OAuth client IDs as build environment variables.
+
+## Installation
+
+```sh
+pnpm add -D @tailor-platform/sdk-plugin-frontend
+```
+
+Use an SDK version that supports `onDeployed` hooks. When testing a PR before
+that SDK release, install both the SDK and frontend plugin from the same
+`pkg.pr.new` commit.
+
+## Monorepo example
+
+Given this layout:
+
+```text
+apps/
+  backend/
+    tailor.config.ts
+  web/
+    package.json
+    dist/
+```
+
+Register the plugin in `apps/backend/tailor.config.ts`:
+
+```typescript
+import { defineConfig, definePlugins, defineStaticWebSite } from "@tailor-platform/sdk";
+import { frontendPlugin } from "@tailor-platform/sdk-plugin-frontend";
+
+const website = defineStaticWebSite("my-frontend", { description: "Web app" });
+
+export default defineConfig({
+  name: "my-app",
+  staticWebsites: [website],
+});
+
+export const plugins = definePlugins(
+  frontendPlugin({
+    site: website,
+    workingDir: "../web",
+    build: "pnpm run build",
+    distDir: "dist",
+    env: ({ site, application }) => ({
+      ...(application.url ? { VITE_TAILOR_APP_URL: application.url } : {}),
+      VITE_SITE_URL: site.url,
+      VITE_OAUTH2_CLIENT_ID:
+        application.auth?.oauth2Clients.find((client) => client.name === "web")?.clientId ?? "",
+    }),
+  }),
+);
+```
+
+Run `tailor deploy --config apps/backend/tailor.config.ts` from the repository
+root. `workingDir` is where `build` runs, relative to the config's directory, so
+this example builds in `apps/web`. `distDir` is the directory your build writes
+its assets to, relative to `workingDir`, so this example publishes `apps/web/dist`.
+Set it to match your build tool's output setting; the plugin does not change where
+the build writes. Omitting `workingDir` uses the config's directory. Absolute paths are
+also accepted.
+
+`site` accepts either a `defineStaticWebSite()` result or a site name. The site
+must be declared in `staticWebsites` of the same config that registers
+`frontendPlugin`. With multiple configs, register each frontend in the config that
+declares its site; a site from another config fails before the build starts. The
+`env` callback can still read the URLs of other configs' sites from `applications`.
+
+## Build environment
+
+`env` is an optional function that returns environment variables, synchronously
+or asynchronously. Its values override matching variables inherited from the
+parent process. Choose variable names for your frontend framework; the plugin
+does not add a prefix.
+
+The callback receives the destination `site`, the registering `application`, all
+`applications` in the deploy, and `workspaceId`. Each application lists its static
+websites by name under `staticWebsites`, so `application.staticWebsites.admin?.url`
+reads another site of the same config.
+Only public OAuth client IDs are provided. Values embedded into browser assets
+are visible to visitors, so supply only values intended for public use.
+
+Build commands run in a shell. Their stdout and stderr both go to stderr, keeping
+`tailor deploy --json` stdout available for the JSON result. Builds have no timeout.
+
+## Upload existing assets
+
+Omit `build` to upload an existing directory:
+
+```typescript
+export const plugins = definePlugins(
+  frontendPlugin({ site: "my-frontend", workingDir: "../web", distDir: "dist" }),
+);
+```
+
+For multiple frontends, pass each one as another argument, as in
+`frontendPlugin(web, admin)`; register the plugin only once. Each site may appear
+only once. Frontends are built and uploaded sequentially, in argument order. At
+least one frontend is required, and each `distDir` must be non-empty. A `build` that is empty or only whitespace is rejected; omit `build` instead to publish without building.
+
+## Deploy behavior and failures
+
+The plugin runs even if no platform resources changed. It does not run during
+dry-run, build-only, generation, or migration test deployments. Dry-run lists the
+plugin as a pending deploy hook.
+
+An unknown site, a site declared in another config, failed build, missing output directory, or failed upload stops
+later frontends and deploy hooks. Platform resources have already been applied;
+fix the error and run `tailor deploy` again. Successfully uploaded frontends are
+not rolled back. Skipped upload files produce warnings and are listed in the result.
+
+With `--json`, the result contains a `deployedHooks` entry for
+`@tailor-platform/frontend`. Its `outputs.frontends` array contains each site's
+`site`, published `url`, and `skippedFiles`.
+
+The same deploy result includes `workspaceId` and `applications`, including each
+config's Static Website URLs, AI Gateway URLs, and public OAuth client IDs. The
+application endpoint URL and domain are present when a Platform Application with
+the config's name exists. Read these directly from `tailor deploy --json`; a
+separate `show` command is not required.

package/docs/plugin/index.md

@@ -115,7 +115,7 @@ e.g. `@example/soft-delete` → `example-soft-delete`), such as:
 
 ## Plugin Lifecycle
 
-Plugins have 5 hooks across two lifecycle phases. Each hook fires at a specific point in the `tailor generate` pipeline:
+Plugins have definition-time, generation-time, and deploy-time hooks. The generation lifecycle is:
 
 ```
 tailor generate
@@ -156,7 +156,29 @@ These hooks produce TailorDB tables, resolvers, and executors that become part o
 
 These hooks receive all finalized data and produce output files (TypeScript code, etc.). No `importPath` required.
 
-A plugin can implement hooks from either or both phases.
+### Deploy-time hooks
+
+```
+tailor deploy
+│
+├─ Build and review resource changes
+├─ Apply all applications and services
+└─ onDeployed                ← each registered plugin, in config order
+```
+
+| Hook         | Available data                                                   | Can do                                   |
+| ------------ | ---------------------------------------------------------------- | ---------------------------------------- |
+| `onDeployed` | Deployed application URLs, website URLs, public OAuth client IDs | Build assets and publish static websites |
+
+Deploy hooks run even when there are no resource changes. They do not run during
+`tailor generate`, dry-run, build-only, or migration test deployments. Dry-run lists
+which hooks would run. A deploy-only plugin needs neither `importPath` nor table attachments.
+
+A plugin can implement hooks from any combination of phases.
+
+## Deploying Frontends
+
+See [Frontend Plugin](./frontend.md) to build frontends and upload them to static websites as part of `tailor deploy`.
 
 ## Creating Custom Plugins
 

package/docs/services/auth.md

@@ -351,6 +351,8 @@ Get OAuth2 client credentials using the CLI:
 tailor oauth2client get <name>
 ```
 
+`tailor show` also lists the client ID, without the secret, of each OAuth2 client defined in `oauth2Clients` once it has been deployed. If your credentials cannot list OAuth2 clients, as with the workspace viewer role, it warns and reports `oauth2Clients` as `null`.
+
 ## Identity Provider
 
 Connect to an external identity provider:

package/docs/services/secret.md

@@ -197,13 +197,14 @@ tailor secret create \
   --name stripe-secret-key \
   --value sk_live_xxxxx
 
-# Update a secret
-tailor secret update \
+# Update a secret, reading the value from standard input
+printf '%s' "$STRIPE_SECRET_KEY" | tailor secret update \
   --vault-name api-keys \
-  --name stripe-secret-key \
-  --value sk_live_yyyyy
+  --name stripe-secret-key
 ```
 
+A value passed with `--value` can show up in your shell history and in process listings. Without `--value`, the command reads the value from standard input instead, accepting up to 128 KiB and removing one trailing newline.
+
 ### List Secrets
 
 ```bash

package/docs/services/staticwebsite.md

@@ -130,6 +130,8 @@ export default defineConfig({
 
 Resolver, executor, workflow job, and auth before-login hook code, and TailorDB migration scripts, that read [`env`](../configuration.md#environment-variables) receive the deployed URL, even when the same deploy both creates the website and reads its URL — one `deploy` call resolves it, with no second, manually-triggered `deploy` needed. If the referenced website does not exist at all, the CLI warns and leaves the unresolved reference in place. If the reference still can't be resolved after this deploy's rebuild, the deploy fails instead of shipping the unresolved reference. This platform lookup only happens during `deploy`; `function run` passes the literal `<name>:url` string unchanged, since it never talks to the platform to resolve it.
 
+The deployed URL is also shown by `tailor show`, which lists the URL of each static website defined in `staticWebsites` once it has been deployed.
+
 ## Complete Example
 
 ```typescript

package/docs/services/tailordb-migration.md

@@ -240,7 +240,7 @@ This writes a numbered migration with an empty `diff.json`, a `migrate.ts` skele
 
 The command requires a clean state: if the namespace has schema changes that are not yet in migration files, generate the schema migration first. With multiple namespaces, pass `--namespace` to name the target. `--data-only` cannot be combined with `--init`, `--rename`, `--drop`, or `--expand-contract`.
 
-A data-only migration runs in **every** workspace the history is applied to, including freshly created ones. Write the script so it is safe against tables with no matching rows (a set-based `UPDATE` with a `WHERE` clause is naturally a no-op on an empty table). For a fix that should run in a single environment only, or that is too large for one transaction, run it outside the migration history instead.
+A data-only migration runs in **every** workspace the history is applied to, including freshly created ones. Write the script so it is safe against tables with no matching rows (a set-based `UPDATE` with a `WHERE` clause is naturally a no-op on an empty table). For a fix that should run in a single environment only, or that is too large for one transaction, run it outside the migration history instead, for example as a one-off script scaffolded with [`tailor function script`](../cli/function.md#function-script) and executed against a single workspace with [`tailor function run`](../cli/function.md#function-run).
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.24.0",
+  "version": "2.25.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -164,7 +164,7 @@
     "@opentelemetry/resources": "2.11.0",
     "@opentelemetry/sdk-trace-node": "2.11.0",
     "@opentelemetry/semantic-conventions": "1.43.0",
-    "@oxc-project/types": "0.151.0",
+    "@oxc-project/types": "0.152.0",
     "@politty/zod": "0.3.0",
     "@secretlint/core": "13.0.6",
     "@secretlint/secretlint-rule-preset-recommend": "13.0.6",
@@ -191,7 +191,7 @@
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
     "pkg-types": "2.3.3",
-    "rolldown": "1.2.11",
+    "rolldown": "1.2.12",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
     "std-env": "4.2.0",
@@ -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.70.0",
-    "oxlint": "1.85.0",
+    "oxfmt": "0.71.0",
+    "oxlint": "1.86.0",
     "oxlint-tsgolint": "7.0.2003",
     "sonda": "0.14.0",
     "tsdown": "0.23.0",

package/dist/application-BDqze-wy.mjs

@@ -1 +0,0 @@
-import{n as e,t}from"./application-CfqvzV3I.mjs";export{t as defineApplication,e as generatePluginFilesIfNeeded};