@tailor-platform/sdk 2.23.0 → 2.25.0

package/dist/vitest/mocks/file.d.mts

@@ -46,9 +46,9 @@ export declare function mockFile(options?: MockFileOptions): {
   calls: FileCall[];
   clear(): void;
   reset(): void;
+  delete: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<void>>;
   download: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<FileDownloadResponse>>;
   downloadAsBase64: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<FileDownloadAsBase64Response>>;
-  delete: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<void>>;
   getMetadata: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<FileMetadata>>;
   downloadStream: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string) => Promise<FileDownloadStreamResponse>>;
   uploadStream: Mock<(namespace: string, tableName: string, fieldName: string, recordId: string, readableStream: ReadableStream<Uint8Array | ArrayBuffer>, options?: FileUploadStreamOptions) => Promise<FileUploadResponse>>;

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/configuration.md

@@ -25,8 +25,10 @@ export default defineConfig({
   cors: ["https://example.com"],
   allowedIpAddresses: ["192.168.1.0/24"],
   disableIntrospection: false,
-  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
   metadata: { "erp-kit-version": "v1-2-3" },
+  buildOptions: {
+    logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  },
 });
 ```
 
@@ -58,12 +60,16 @@ export default defineConfig({
 
 Entries are only added or overwritten. An entry removed from the config keeps its last deployed value on the platform, and labels the config does not name are left untouched. Because those retained labels count towards the platform's limit of 20 labels per resource, `deploy` reports the overflow and stops before changing the application when the labels it would leave behind exceed that limit. The labels are written when the application itself is deployed, so a config with no TailorDB, Resolver, IdP, or Auth service has no application to carry them.
 
-**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:
+**Build Options**: `buildOptions` groups the settings that control how resolvers, executors, workflow jobs, and other functions are bundled: `logLevel` (below), `inlineSourcemap` (whether bundled functions embed an inline sourcemap for readable error stack traces; default `true`), and `allowedRuntimeGlobals` (see [Node-only globals](#node-only-globals)). The top-level `logLevel` and `inlineSourcemap` fields still work but are deprecated; `tailor upgrade` moves them into `buildOptions`. Setting the same option both at the top level and in `buildOptions` is rejected.
+
+**Log Level** (`buildOptions.logLevel`): 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.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  buildOptions: {
+    logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  },
 });
 ```
 
@@ -121,6 +127,25 @@ Error [UNRESOLVED_IMPORT]: Could not resolve "@lib/missing" imported from "/path
 
 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`).
 
+#### Node-only globals
+
+The Tailor Platform runtime does not define Node-only globals such as `process`, `Buffer`, or `require`. When a bundled resolver, executor, or workflow job references one, the build fails with `FORBIDDEN_RUNTIME_GLOBAL`, naming the global and where it is referenced: the file in your own code, or the installed package (code under `node_modules`). A reference behind a `typeof` check, such as `if (typeof process !== "undefined") { ... }`, is not reported.
+
+You cannot change an installed package's code, and it may reference a global only on a code path your use never reaches. When you have confirmed that, allow the reference with `buildOptions.allowedRuntimeGlobals`, keyed by package name. List the globals to allow, or set `true` to allow all of them, including any the package only starts referencing in a later version. Code in that package that does reach the global throws a `ReferenceError` at runtime:
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  buildOptions: {
+    allowedRuntimeGlobals: {
+      "@ai-sdk/gateway": ["Buffer"],
+    },
+  },
+});
+```
+
+`buildOptions.allowedRuntimeGlobals` has no effect on your own code. Packages from your own workspace (for example, a pnpm or npm workspace) are bundled from their source directory rather than from `node_modules`, so they count as your own code.
+
 ### 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.