@tailor-platform/sdk 1.76.1 → 1.78.0

package/docs/cli/application.md

@@ -59,19 +59,66 @@ tailor-sdk deploy [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`         |
-| `--config <CONFIG>`             | `-c`  | Path to SDK config file. Use comma-separated paths to deploy multiple apps together. | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-| `--yes`                         | `-y`  | Skip confirmation prompts                                                            | No       | `false`              | -                                 |
-| `--dry-run`                     | `-d`  | Run the command without making any changes                                           | No       | -                    | -                                 |
-| `--no-schema-check`             | -     | Skip schema diff check against migration snapshots                                   | No       | -                    | -                                 |
-| `--no-validate`                 | -     | Skip client-side validation against platform resource constraints                    | No       | -                    | -                                 |
-| `--no-cache`                    | -     | Disable bundle caching for this run                                                  | No       | -                    | -                                 |
-| `--clean-cache`                 | -     | Clean the bundle cache before building                                               | No       | -                    | -                                 |
+| 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`         |
+| `--config <CONFIG>`                     | `-c`  | Path to SDK config file. Use comma-separated paths to deploy multiple apps together. | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
+| `--yes`                                 | `-y`  | Skip confirmation prompts                                                            | No       | `false`              | -                                 |
+| `--create-workspace`                    | -     | Create a workspace when the account has none                                         | No       | -                    | -                                 |
+| `--workspace-name <WORKSPACE_NAME>`     | -     | Name for a workspace created during deploy                                           | No       | -                    | -                                 |
+| `--workspace-region <WORKSPACE_REGION>` | -     | Region for a workspace created during deploy                                         | No       | -                    | -                                 |
+| `--organization-id <ORGANIZATION_ID>`   | -     | Organization ID for a workspace created during deploy                                | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
+| `--folder-id <FOLDER_ID>`               | -     | Folder ID for a workspace created during deploy                                      | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
+| `--dry-run`                             | `-d`  | Run the command without making any changes                                           | No       | -                    | -                                 |
+| `--no-schema-check`                     | -     | Skip schema diff check against migration snapshots                                   | No       | -                    | -                                 |
+| `--no-validate`                         | -     | Skip client-side validation against platform resource constraints                    | No       | -                    | -                                 |
+| `--no-cache`                            | -     | Disable bundle caching for this run                                                  | No       | -                    | -                                 |
+| `--clean-cache`                         | -     | Clean the bundle cache before building                                               | No       | -                    | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+**Workspace Selection:**
+
+After validating the configuration file, `deploy` resolves a workspace before bundling the
+application. Explicit configuration takes precedence in this order: `--workspace-id`,
+`TAILOR_PLATFORM_WORKSPACE_ID`, and the selected profile. Otherwise, `deploy` reuses the workspace
+previously selected for that configuration from project-local state. Each config file keeps an
+independent selection, including when multiple configs share a directory. An explicit workspace also
+updates this selection. Saved selections are verified against the workspaces currently visible to
+the authenticated user before reuse, and `deploy` warns when it uses one.
+
+When the project has no saved selection, `deploy` discovers the account's workspaces:
+
+- One or more workspaces open a selection prompt in an interactive terminal, with an option to
+  create a new workspace. With one workspace in non-interactive or JSON mode, it is selected
+  automatically. With multiple workspaces, pass `--workspace-id` instead.
+- No workspaces open a guided creation flow in an interactive terminal. The flow asks for a name,
+  fetches the available regions from the Platform, and confirms before creating anything. After
+  creation, the output shows how to reuse the workspace with `--workspace-id` or
+  `TAILOR_PLATFORM_WORKSPACE_ID` from CI or another machine.
+
+In CI and other non-interactive environments, workspace creation must be explicit:
+
+```bash
+tailor-sdk deploy \
+  --create-workspace \
+  --workspace-name example-workspace \
+  --workspace-region us-west
+```
+
+`--create-workspace` only creates when the account has no workspace. If the existing workspace
+matches the requested name, region, organization, and folder, `deploy` reuses it so the same command
+is safe to rerun. If multiple workspaces exist, the flag never creates another one or guesses which
+workspace to use. `--yes` skips deployment confirmation but does not authorize workspace creation.
+
+If a saved workspace has been deleted or is no longer accessible, interactive terminals return to
+workspace selection. Non-interactive environments stop with `WORKSPACE_CONTEXT_STALE` instead of
+silently switching to another workspace. Automatically selected targets are printed with their
+region, organization, and workspace ID.
+
+`--dry-run` never creates a workspace or writes project context. When an account has no workspace,
+create one explicitly before requesting a deployment plan.
+
 **Config File Modification:**
 
 On first run, `deploy` automatically injects a stable `id: "<uuid>"` field into your `defineConfig({...})` call in `tailor.config.ts`. This UUID is used to track your application across renames so the SDK can recognize ownership across renames. Commit the generated id to version control. See [Configuration](../configuration.md#application-settings) for details.

package/docs/cli/setup.md

@@ -174,7 +174,7 @@ tailor-sdk setup tag [options]
 | Option                        | Alias | Description                                                                  | Required | Default |
 | ----------------------------- | ----- | ---------------------------------------------------------------------------- | -------- | ------- |
 | `--name <NAME>`               | `-n`  | Name (defaults to the config 'name')                                         | No       | -       |
-| `--tag-pattern <TAG_PATTERN>` | -     | Tag glob to match (defaults to v\*)                                          | No       | `"v*"`  |
+| `--tag-pattern <TAG_PATTERN>` | -     | Tag glob to match (defaults to v*)                                           | No       | `"v*"`  |
 | `--branch <BRANCH>`           | -     | Tag-reachability guard branch (no guard when omitted)                        | No       | -       |
 | `--environment <ENVIRONMENT>` | -     | GitHub Environment for the plan/deploy jobs (defaults to the workspace name) | No       | -       |
 | `--dir <DIR>`                 | `-d`  | App directory (for monorepo setups)                                          | No       | `"."`   |

package/docs/cli/workspace.md

@@ -106,6 +106,7 @@ tailor-sdk workspace create [options]
 | `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID to workspace associate with                                                                 | No       | -         | `TAILOR_PLATFORM_ORGANIZATION_ID` |
 | `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID to workspace associate with                                                                       | No       | -         | `TAILOR_PLATFORM_FOLDER_ID`       |
 | `--profile-name <PROFILE_NAME>`       | `-p`  | Profile name to create                                                                                      | No       | -         | -                                 |
+| `--profile <PROFILE>`                 | -     | Workspace profile used for authentication and Platform selection                                            | No       | -         | `TAILOR_PLATFORM_PROFILE`         |
 | `--profile-user <PROFILE_USER>`       | -     | User email for the profile (defaults to current user)                                                       | No       | -         | -                                 |
 | `--permission <PERMISSION>`           | -     | Profile permission (requires --profile-name). 'read' blocks all write commands while the profile is active. | No       | `"write"` | -                                 |
 
@@ -161,10 +162,11 @@ tailor-sdk workspace list [options]
 
 **Options**
 
-| Option            | Alias | Description                                              | Required | Default  |
-| ----------------- | ----- | -------------------------------------------------------- | -------- | -------- |
-| `--order <ORDER>` | -     | Sort order (asc or desc)                                 | No       | `"desc"` |
-| `--limit <LIMIT>` | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        |
+| Option                | Alias | Description                                                      | Required | Default  | Env                       |
+| --------------------- | ----- | ---------------------------------------------------------------- | -------- | -------- | ------------------------- |
+| `--order <ORDER>`     | -     | Sort order (asc or desc)                                         | No       | `"desc"` | -                         |
+| `--limit <LIMIT>`     | `-l`  | Maximum number of items to return (0 or omit: unlimited)         | No       | -        | -                         |
+| `--profile <PROFILE>` | -     | Workspace profile used for authentication and Platform selection | No       | -        | `TAILOR_PLATFORM_PROFILE` |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 

package/docs/cli-reference.md

@@ -11,12 +11,13 @@ tailor-sdk <command> [options]
 ## Global Options
 
 <a id="global-options"></a>
-| Option | Alias | Description | Required | Default |
-|--------|-------|-------------|----------|---------|
-| `--env-file <ENV_FILE>` | `-e` | Path to the environment file (error if not found) | No | - |
-| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | - | Path to the environment file (ignored if not found) | No | - |
-| `--verbose` | - | Enable verbose logging | No | `false` |
-| `--json` | `-j` | Output as JSON | No | `false` |
+
+| Option                                      | Alias | Description                                         | Required | Default |
+| ------------------------------------------- | ----- | --------------------------------------------------- | -------- | ------- |
+| `--env-file <ENV_FILE>`                     | `-e`  | Path to the environment file (error if not found)   | No       | -       |
+| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | -     | Path to the environment file (ignored if not found) | No       | -       |
+| `--verbose`                                 | -     | Enable verbose logging                              | No       | `false` |
+| `--json`                                    | `-j`  | Output as JSON                                      | No       | `false` |
 
 ### JSON Output
 
@@ -27,8 +28,11 @@ 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.
 
-Errors, warnings, progress, and diagnostic messages are written to stderr. On failure, check the
-non-zero exit code and read stderr; stdout is not guaranteed to contain a JSON error object.
+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. CLI errors include a stable
+`error.code` and may include structured `error.next` and `error.context` fields for automated
+recovery. Diagnostic lines may precede the error envelope, and stdout is not guaranteed to contain
+an error object.
 
 ## Common Options
 

package/docs/runtime.md

@@ -95,17 +95,16 @@ import { expect, test } from "vitest";
 
 test("encodes via iconv", () => {
   using iconvM = mockIconv();
-  iconvM.setResolver(() => new Uint8Array([0x82, 0xa0]));
+  iconvM.convert.mockReturnValue(new Uint8Array([0x82, 0xa0]));
 
   const out = iconv.convert("あ", "UTF-8", "Shift_JIS");
 
   expect(out).toEqual(new Uint8Array([0x82, 0xa0]));
-  expect(iconvM.calls[0]?.method).toBe("convert");
+  expect(iconvM.convert).toHaveBeenCalledWith("あ", "UTF-8", "Shift_JIS");
 }); // iconvM disposed here — the iconv mock is removed (previous state restored)
 
 test("reads from a vault", async () => {
-  using sm = mockSecretmanager();
-  sm.setSecrets({ "my-vault": { API_KEY: "sk-123" } });
+  using sm = mockSecretmanager({ secrets: { "my-vault": { API_KEY: "sk-123" } } });
 
   await expect(secretmanager.getSecret("my-vault", "API_KEY")).resolves.toBe("sk-123");
 });

package/docs/services/aigateway.md

@@ -111,3 +111,5 @@ const { url } = await aigateway.get("my-aigateway");
 ```
 
 Type narrowing is provided by the generated `tailor.d.ts` (the `AIGatewayNameRegistry` interface). Run `tailor-sdk generate` (or `deploy`) after defining new AI Gateways to refresh it. Before the first generate run, `get()` accepts any string.
+
+The same URL is also shown by `tailor-sdk show`, which lists the URL of each AI Gateway defined in `aiGateways` once it has been deployed.

package/docs/services/tailordb.md

@@ -344,7 +344,7 @@ export const user = db
 
 ### Validation
 
-Add validation rules to fields. Validators receive three arguments (executed after hooks):
+Add validation rules to fields. Validators receive three arguments (executed after hooks and built-in type validation):
 
 - `value`: Field value after hook transformation
 - `data`: Entire record data after hook transformations (for accessing other field values)
@@ -352,6 +352,13 @@ Add validation rules to fields. Validators receive three arguments (executed aft
 
 Validators return `true` for success, `false` for failure. Use array form `[validator, errorMessage]` for custom error messages.
 
+**Note:** Custom validators run only when built-in type validation succeeds, so `value` always has the field's declared type. For array fields, the validator is called once with the complete array, not per element:
+
+```typescript
+// value is string[], not string
+db.string({ array: true }).validate(({ value }) => value.length >= 2);
+```
+
 #### Field-level Validation
 
 Set validators directly on individual fields:
@@ -543,6 +550,48 @@ db.type("User", {
    });
    ```
 
+#### GraphQL Operations
+
+Control which GraphQL operations (`create`, `update`, `delete`, `read`) are exposed for a type. All operations are enabled by default.
+
+```typescript
+db.type("Order", {
+  status: db.string(),
+}).features({
+  gqlOperations: {
+    delete: false, // Disable the delete mutation
+  },
+});
+```
+
+Use the `"query"` alias to disable all mutations at once (read-only type: `create`/`update`/`delete` false, `read` true):
+
+```typescript
+db.type("AuditLog", {
+  action: db.string(),
+}).features({
+  gqlOperations: "query",
+});
+```
+
+**Namespace-level default**
+
+Set a default for every type in a TailorDB namespace in `tailor.config.ts`. A type's own `.features({ gqlOperations })` always takes precedence over this default.
+
+```typescript
+// tailor.config.ts
+export default defineConfig({
+  db: {
+    tailordb: {
+      files: ["./tailordb/*.ts"],
+      gqlOperations: { delete: false }, // Default for every type in this namespace
+    },
+  },
+});
+```
+
+This default is re-evaluated on every `tailor-sdk deploy`, so changing it also updates types that already exist on the platform, not only newly created ones.
+
 ### Field Extraction (`pickFields` / `omitFields`)
 
 Extract subsets of fields from a `TailorDBType` for reuse in resolvers, executors, seed schemas, etc.
@@ -570,6 +619,8 @@ Available options:
 | `optional` | Makes the selected fields optional    |
 | `array`    | Makes the selected fields array types |
 
+**Note:** The `array` option cannot change fields with custom validation — their validators expect the original value shape. Define a new field with a matching validator instead.
+
 #### `omitFields(keys)`
 
 Return all fields except the specified ones:

package/docs/services/workflow.md

@@ -397,7 +397,7 @@ export default defineConfig({
 
 `key` accepts `[a-z0-9_:.-]` and must start with `[a-z0-9]`. An exact key must also end with `[a-z0-9]`; a wildcard prefix (`matchType: "prefix"`) may end with any of those characters, since the platform appends a trailing `*` after it. The platform-registered key — including that trailing `*` when wildcarded — is 2 to 64 characters long, so a wildcard prefix must be at most 63 characters. `foo:bar` is a valid exact key; `tenant-api` with `matchType: "prefix"` registers `tenant-api*` as a wildcard prefix.
 
-An exact-key policy applies to dispatches whose runtime key equals the policy key. A wildcard policy applies to every dispatch whose runtime key begins with the prefix; each concrete resolved key gets its own independent pool of the declared size (a `cap = 3` wildcard yields three concurrent dispatches per resolved key, not three across every match). The longest matching prefix wins when a dispatch could match more than one wildcard.
+An exact-key policy applies to dispatches whose runtime key equals the policy key. A wildcard policy applies to every dispatch whose runtime key begins with the prefix; each concrete resolved key gets its own independent pool of the declared size (a `cap = 3` wildcard yields three concurrent dispatches per resolved key, not three across every match). When a dispatch matches more than one policy (for example, an exact key that also falls under a wildcard prefix, or two wildcard prefixes where one starts with the other), every matching policy's cap is enforced independently, and the tightest one blocks.
 
 ### Referencing a Policy from a Workflow