@tailor-platform/sdk 2.23.0 → 2.25.0

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/docs/services/workflow.md

@@ -516,6 +516,9 @@ You can start a workflow execution from a resolver using `workflow.start()`.
 
 - `workflow.start(args, options?)` returns a workflow run ID (`Promise<string>`).
 - To run with machine-user permissions, pass `{ invoker: "<machine-user>" }`. The name is type-narrowed to the machine users defined in your auth config.
+- Import the workflow from its workflow file with a default import (or a namespace import, calling `wf.default.start(...)`), using a relative path or a `tsconfig.json` `paths` alias. The build replaces the `.start()` call with a platform call, so it has to recognize the workflow: export it as the file's default export — either `createWorkflow({ name: "..." })` itself or the result of a helper function that calls `createWorkflow()`.
+- Call `.start()` directly on the imported name (`orderProcessingWorkflow.start(...)`, or `wf.default.start(...)` for a namespace import). If you first assign the workflow to another variable (`const wf = orderProcessingWorkflow; wf.start(...)`) or pass it to a function, the call is neither rewritten nor checked, and fails at runtime.
+- If a `.start()` call is made on an export of a workflow file that the build cannot recognize as a workflow or job defined that way, the build fails. A `.start()` on a workflow imported from anywhere other than a workflow file (for example re-exported from a shared package) cannot be checked, and fails at runtime.
 
 ```typescript
 import { createResolver, t } from "@tailor-platform/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.23.0",
+  "version": "2.25.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -164,10 +164,10 @@
     "@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.5",
-    "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
+    "@secretlint/core": "13.0.6",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.6",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
     "@toiroakr/lines-db": "0.13.0",
@@ -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",
@@ -208,13 +208,13 @@
     "@tailor-platform/shared": "^0.0.0",
     "@tailor-platform/tailor-proto": "^0.0.1",
     "@types/mime-types": "3.0.1",
-    "@types/node": "24.13.6",
+    "@types/node": "24.19.0",
     "@types/semver": "7.8.0",
     "@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-BtZ8hmx9.mjs

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