@tailor-platform/sdk 1.76.2 → 1.78.0

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

@@ -1,3 +1,5 @@
+import { FileDownloadAsBase64Response, FileDownloadResponse, FileDownloadStreamResponse, FileMetadata, FileStreamIterator, FileUploadOptions, FileUploadResponse, FileUploadStreamOptions } from "../../runtime/file.mjs";
+import { Mock } from "vitest";
 //#region src/vitest/mocks/file.d.ts
 type FileResolver = (method: string, call: FileCall) => unknown;
 interface FileCall {
@@ -7,8 +9,14 @@ interface FileCall {
   fieldName: string;
   recordId: string;
 }
+/** Controls fallback behavior for File calls without a configured result. */
+interface MockFileOptions {
+  /** Return a type-compatible fixture or throw when no behavior is configured. */
+  onUnhandled?: "fallback" | "error";
+}
 /**
  * Acquire a disposable mock for `tailordb.file`. Restored on dispose.
+ * @param options - Controls behavior for calls without a configured result
  * @returns Disposable File mock control object
  * @example
  * ```typescript
@@ -16,26 +24,36 @@ interface FileCall {
  *
  * test("mock file download", async () => {
  *   using file = mockFile();
- *   file.enqueueResult({ data: new Uint8Array([1, 2, 3]), metadata: { ... } });
+ *   file.download.mockResolvedValue({ data: new Uint8Array(), metadata: { ... } });
  *   // …
  * });
  * ```
  */
-declare function mockFile(): {
+declare function mockFile(options?: MockFileOptions): {
   setResolver(value: FileResolver): void;
   /**
-   * Enqueue a single result for the next `tailordb.file` call (FIFO; falls
-   * back to `setResolver` when exhausted).
+   * Enqueue a single result for the next `tailordb.file` call.
+   * The queue is shared across all methods and namespaces.
    * @param result - Result to return from the next file call
    */
   enqueueResult(result: unknown): void;
   /**
    * Enqueue results for multiple subsequent `tailordb.file` calls.
+   * The queue is shared across all methods and namespaces.
    * @param results - Results to enqueue, one per upcoming call
    */
   enqueueResults(...results: unknown[]): void;
-  readonly calls: FileCall[];
+  calls: FileCall[];
+  clear(): void;
   reset(): void;
+  delete: Mock<(namespace: string, typeName: string, fieldName: string, recordId: string) => Promise<void>>;
+  upload: Mock<(namespace: string, typeName: string, fieldName: string, recordId: string, data: string | ArrayBuffer | Uint8Array | number[], options?: FileUploadOptions) => Promise<FileUploadResponse>>;
+  download: Mock<(namespace: string, typeName: string, fieldName: string, recordId: string) => Promise<FileDownloadResponse>>;
+  downloadAsBase64: Mock<(namespace: string, typeName: string, fieldName: string, recordId: string) => Promise<FileDownloadAsBase64Response>>;
+  getMetadata: Mock<(namespace: string, typeName: string, fieldName: string, recordId: string) => Promise<FileMetadata>>;
+  openDownloadStream: Mock<(namespace: string, typeName: string, fieldName: string, recordId: string) => Promise<FileStreamIterator>>;
+  downloadStream: Mock<(namespace: string, typeName: string, fieldName: string, recordId: string) => Promise<FileDownloadStreamResponse>>;
+  uploadStream: Mock<(namespace: string, typeName: string, fieldName: string, recordId: string, readableStream: ReadableStream<Uint8Array | ArrayBuffer>, options?: FileUploadStreamOptions) => Promise<FileUploadResponse>>;
 } & Disposable;
 //#endregion
-export { mockFile };
+export { MockFileOptions, mockFile };

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

@@ -1,11 +1,24 @@
+import { MockInstance } from "vitest";
 //#region src/vitest/mocks/iconv.d.ts
 type IconvResolver = (method: string, args: unknown[]) => unknown;
+type IconvMethod = "convert" | "convertBuffer" | "decode" | "encode" | "encodings";
 interface IconvCall {
-  method: string;
+  method: IconvMethod;
   args: unknown[];
 }
+type ConversionResult = string | Uint8Array;
+type ConvertMockProcedure = (input: string | Uint8Array | ArrayBuffer, fromEncoding: string, toEncoding: string) => ConversionResult;
+type ConvertBufferMockProcedure = (input: Uint8Array | ArrayBuffer, fromEncoding: string, toEncoding: string) => ConversionResult;
+type EncodeMockProcedure = (input: string, encoding: string) => ConversionResult;
+type TypedOperationMock<RuntimeProcedure, MockProcedure extends (...args: never[]) => unknown> = RuntimeProcedure & MockInstance<MockProcedure>;
+/** Controls how unconfigured Iconv operations are handled. */
+interface MockIconvOptions {
+  /** Return an empty type-compatible value or throw when no behavior is configured. */
+  onUnhandled?: "fallback" | "error";
+}
 /**
  * Acquire a disposable mock for `tailor.iconv`. Restored on dispose.
+ * @param options - Fallback behavior for unconfigured operations
  * @returns Disposable Iconv mock control object
  * @example
  * ```typescript
@@ -13,15 +26,26 @@ interface IconvCall {
  *
  * test("mock encoding conversion", () => {
  *   using iconv = mockIconv();
- *   iconv.setResolver((method) => (method === "decode" ? "decoded-text" : null));
+ *   iconv.decode.mockReturnValue("decoded-text");
  *   // …
  * });
  * ```
  */
-declare function mockIconv(): {
+declare function mockIconv(options?: MockIconvOptions): {
+  /** The `convert` `vi.fn`. */
+  convert: TypedOperationMock<(<T extends string>(str: string | Uint8Array | ArrayBuffer, fromEncoding: string, toEncoding: T) => T extends "UTF8" | "UTF-8" ? string : Uint8Array), ConvertMockProcedure>;
+  /** The `convertBuffer` `vi.fn`. */
+  convertBuffer: TypedOperationMock<(<T extends string>(buffer: Uint8Array | ArrayBuffer, fromEncoding: string, toEncoding: T) => T extends "UTF8" | "UTF-8" ? string : Uint8Array), ConvertBufferMockProcedure>;
+  /** The `decode` `vi.fn`. */
+  decode: import("vitest").Mock<(input: Uint8Array | ArrayBuffer, encoding: string) => string>;
+  /** The `encode` `vi.fn`. */
+  encode: TypedOperationMock<(<T extends string>(str: string, encoding: T) => T extends "UTF8" | "UTF-8" ? string : Uint8Array), EncodeMockProcedure>;
+  /** The `encodings` `vi.fn`. */
+  encodings: import("vitest").Mock<() => string[]>;
   setResolver(value: IconvResolver): void;
   readonly calls: IconvCall[];
+  clear: () => void;
   reset(): void;
 } & Disposable;
 //#endregion
-export { mockIconv };
+export { MockIconvOptions, mockIconv };

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

@@ -1,44 +1,60 @@
+import { IdpClientConstructor, IdpClientInstance } from "../../runtime/idp.mjs";
 import { Mock } from "vitest";
 //#region src/vitest/mocks/idp.d.ts
+type IdpMethod = keyof IdpClientInstance;
 type IdpResolver = (method: string, args: unknown[], namespace: string) => unknown;
 interface IdpCall {
   method: string;
   args: unknown[];
   namespace: string;
 }
+/** Controls fallback behavior for IdP calls without a configured result. */
+interface MockIdpOptions {
+  /** Return a type-compatible fixture or throw when no behavior is configured. */
+  onUnhandled?: "fallback" | "error";
+}
+type IdpNamespaceMocks = { [Method in IdpMethod]: Mock<IdpClientInstance[Method]>; };
 /**
  * Acquire a disposable mock for `tailor.idp`. Restored on dispose.
+ * @param options - Controls behavior for calls without a configured result
  * @returns Disposable IDP mock control object
  * @example
  * ```typescript
  * import { mockIdp } from "@tailor-platform/sdk/vitest";
  *
- * test("resolver-based", async () => {
+ * test("returns a user", async () => {
  *   using idp = mockIdp();
- *   idp.setResolver((method) =>
- *     method === "user" ? { id: "u-1", name: "alice", disabled: false } : null,
- *   );
+ *   idp.namespace("my-idp").user.mockResolvedValue({
+ *     id: "u-1",
+ *     name: "alice",
+ *     disabled: false,
+ *     mfaEnrolled: false,
+ *     mfaFactorIds: [],
+ *   });
  *   // …
  * });
  * ```
  */
-declare function mockIdp(): {
+declare function mockIdp(options?: MockIdpOptions): {
   /** The mock IDP `Client` constructor (`vi.fn`). */
-  Client: Mock;
+  Client: Mock<IdpClientConstructor>;
+  namespace: (name: string) => IdpNamespaceMocks;
   setResolver(value: IdpResolver): void;
   /**
-   * Enqueue a single result for the next IDP call (FIFO; falls back to
-   * `setResolver` when exhausted).
+   * Enqueue a single result for the next IDP call.
+   * The queue is shared across all methods and namespaces.
    * @param result - Result to return from the next IDP call
    */
   enqueueResult(result: unknown): void;
   /**
    * Enqueue results for multiple subsequent IDP calls.
+   * The queue is shared across all methods and namespaces.
    * @param results - Results to enqueue, one per upcoming call
    */
   enqueueResults(...results: unknown[]): void;
   readonly calls: IdpCall[];
+  clear(): void;
   reset(): void;
 } & Disposable;
 //#endregion
-export { mockIdp };
+export { MockIdpOptions, mockIdp };

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

@@ -5,31 +5,40 @@ interface SecretCall {
   name?: string;
   names?: readonly string[];
 }
+/** Initial fixtures for a Secret Manager mock. */
+interface MockSecretmanagerOptions {
+  /** Secrets to merge over fixtures inherited from the currently installed mock. */
+  secrets?: Record<string, Record<string, string>>;
+}
 /**
  * Acquire a disposable mock for `tailor.secretmanager`. The secret store is
  * inherited (cloned) from the currently-installed mock on acquisition and
  * restored on dispose, so secrets seeded outside the test survive across
  * `using` scopes while per-test `setSecrets()` overrides stay isolated.
+ * @param options - Initial Secret Manager fixtures
  * @returns Disposable SecretManager mock control object
  * @example
  * ```typescript
  * import { mockSecretmanager } from "@tailor-platform/sdk/vitest";
  *
  * test("reads secrets from vault", async () => {
- *   using sm = mockSecretmanager();
- *   sm.setSecrets({ "my-vault": { API_KEY: "sk-123" } });
+ *   using sm = mockSecretmanager({ secrets: { "my-vault": { API_KEY: "sk-123" } } });
+ *   sm.setSecret("my-vault", "API_KEY", "replacement");
  *   // …
  * });
  * ```
  */
-declare function mockSecretmanager(): {
+declare function mockSecretmanager(options?: MockSecretmanagerOptions): {
   /** The `getSecret` `vi.fn`. */
   getSecret: import("vitest").Mock<(vault: string, name: string) => Promise<string | undefined>>;
   /** The `getSecrets` `vi.fn`. */
   getSecrets: import("vitest").Mock<(<const T extends readonly string[]>(vault: string, names: T) => Promise<Partial<Record<T[number], string>>>)>;
   setSecrets(secrets: Record<string, Record<string, string>>): void;
+  setSecret(vault: string, name: string, value: string): void;
+  mergeSecrets(vault: string, secrets: Record<string, string>): void;
   readonly calls: SecretCall[];
+  clear(): void;
   reset(): void;
 } & Disposable;
 //#endregion
-export { mockSecretmanager };
+export { MockSecretmanagerOptions, mockSecretmanager };

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

@@ -1,5 +1,30 @@
 //#region src/vitest/mocks/tailordb.d.ts
-type QueryResolver = (query: string, params: unknown[]) => unknown[];
+type QueryResolver = (query: string, params: unknown[]) => unknown[] | undefined;
+/** Controls how unmatched TailorDB queries are handled. */
+interface MockTailordbOptions {
+  /** Return an empty result or throw when no configured query behavior matches. */
+  onUnhandled?: "fallback" | "error";
+}
+/** Matches a TailorDB query by SQL text and optionally by parameters. */
+interface QueryMatch {
+  /** Exact SQL text or regular expression to match. */
+  sql: string | RegExp;
+  /** Exact parameters or a predicate for parameter matching. */
+  params?: readonly unknown[] | ((params: unknown[]) => boolean);
+}
+/** Selects TailorDB queries that receive a configured response. */
+type QueryMatcher = string | RegExp | QueryMatch | ((query: string, params: unknown[]) => boolean);
+/** Configures persistent and one-time responses for matched queries. */
+interface QueryBehavior<Row> {
+  /** Return these rows for every matching query after one-time responses are consumed. */
+  returnsRows(rows: Row[]): QueryBehavior<Row>;
+  /** Return these rows for the next matching query. */
+  returnsRowsOnce(rows: Row[]): QueryBehavior<Row>;
+  /** Reject every matching query after one-time responses are consumed. */
+  rejects(error: unknown): QueryBehavior<Row>;
+  /** Reject the next matching query. */
+  rejectsOnce(error: unknown): QueryBehavior<Row>;
+}
 interface ExecutedQuery {
   query: string;
   params: unknown[];
@@ -19,32 +44,41 @@ declare class MockQueryResult {
  * `tailordb.Client` whose `queryObject` is a shared `vi.fn()` (so query
  * responses can be staged before the client is constructed). Restored on
  * dispose.
+ * @param options - Query fallback behavior
  * @returns Disposable TailorDB mock control object
  * @example
  * ```typescript
  * import { mockTailordb } from "@tailor-platform/sdk/vitest";
  *
- * test("order-based", async () => {
+ * test("query-based", async () => {
  *   using db = mockTailordb();
- *   db.enqueueResults([], [{ age: 30 }], []); // BEGIN / SELECT / COMMIT
+ *   db.onQuery({ sql: /FROM users/, params: ["u-1"] }).returnsRows([{ age: 30 }]);
  *   // …
- *   expect(db.queryObject).toHaveBeenCalledTimes(3);
+ *   expect(db.queryObject).toHaveBeenCalled();
  *   expect(db.Client).toHaveBeenCalledWith({ namespace: "tailordb" });
  * });
  * ```
  */
-declare function mockTailordb(): {
+declare function mockTailordb(options?: MockTailordbOptions): {
   /** The mock `tailordb.Client` constructor (`vi.fn`). */
   Client: import("vitest").Mock<(this: any, config?: {
     namespace?: string;
   }) => void>;
   /** The shared `queryObject` `vi.fn` used by every client and transaction. */
-  queryObject: import("vitest").Mock<(_query: string, _params?: unknown[]) => Promise<MockQueryResult>>;
+  queryObject: import("vitest").Mock<(query: string, params?: unknown[]) => Promise<MockQueryResult>>;
   /**
    * Set a fallback query resolver. Called when the enqueue queue is empty.
    * @param resolver - Function that returns rows for a given query and params
    */
   setQueryResolver(resolver: QueryResolver): void;
+  /**
+   * Configure responses for queries matching SQL text, parameters, or a predicate.
+   * More recently registered matchers take precedence.
+   * Do not combine matchers with a direct `queryObject.mockImplementation()` override.
+   * @param matcher - Query matcher
+   * @returns Chainable query behavior
+   */
+  onQuery<Row = unknown>(matcher: QueryMatcher): QueryBehavior<Row>;
   /**
    * Enqueue rows for the next `queryObject` call (FIFO; takes priority over
    * `setQueryResolver`). Call with no arguments for an empty result.
@@ -56,6 +90,11 @@ declare function mockTailordb(): {
    * @param rowsList - Rows arrays, one per upcoming query
    */
   enqueueResults(...rowsList: unknown[][]): void;
+  /**
+   * Enqueue row arrays for subsequent queries whose exact order is under test.
+   * @param rowsList - Rows arrays, one per upcoming query
+   */
+  enqueueRows(...rowsList: unknown[][]): void;
   /**
    * All queries executed via `queryObject`, in order, derived from the vi.fn
    * call records.
@@ -67,8 +106,10 @@ declare function mockTailordb(): {
    * @returns Created clients array
    */
   readonly createdClients: CreatedClient[];
+  /** Clear recorded calls while preserving configured query behavior. */
+  clear(): void;
   /** Reset query responses and recorded calls (keeps the mock installed). */
   reset(): void;
 } & Disposable;
 //#endregion
-export { mockTailordb };
+export { MockTailordbOptions, QueryBehavior, QueryMatch, QueryMatcher, mockTailordb };

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

@@ -1,5 +1,9 @@
 import { TailorEnv } from "../../runtime/types.mjs";
 import { TriggerJobFunctionOptions } from "../../runtime/workflow.mjs";
+import { WorkflowJob } from "../../configure/services/workflow/job.mjs";
+import { Workflow } from "../../configure/services/workflow/workflow.mjs";
+import { WaitPointInstance } from "../../configure/services/workflow/wait-point.mjs";
+import { Mock } from "vitest";
 //#region src/vitest/mocks/workflow.d.ts
 type JobHandler = (jobName: string, args: unknown, options?: TriggerJobFunctionOptions) => unknown;
 type TriggerWorkflowOptions = {
@@ -21,6 +25,7 @@ interface TriggeredJob {
   args: unknown;
   options?: TriggerJobFunctionOptions;
 }
+type WaitPayload<Payload> = [Payload] extends [undefined] ? undefined : Payload;
 /**
  * Acquire a disposable mock for workflow operations (`tailor.workflow`).
  * Restored on dispose.
@@ -29,25 +34,50 @@ interface TriggeredJob {
  * ```typescript
  * import { mockWorkflow } from "@tailor-platform/sdk/vitest";
  *
- * test("job handler", async () => {
+ * test("job trigger", async () => {
  *   using wf = mockWorkflow();
- *   wf.setJobHandler((name) => (name === "validate" ? { valid: true } : null));
- *   await runWorkflowUnderTest(); // calls tailor.workflow.triggerJobFunction("validate", {})
- *   expect(wf.triggerJobFunction).toHaveBeenCalledWith("validate", {});
+ *   const job = wf.job(validateOrder);
+ *   job.mockResolvedValue({ valid: true });
+ *   await runWorkflowUnderTest();
+ *   expect(job).toHaveBeenCalled();
  * });
  * ```
  */
 declare function mockWorkflow(): {
   /** The `triggerJobFunction` `vi.fn`. */
-  triggerJobFunction: import("vitest").Mock<(jobName: string, args?: unknown, _options?: TriggerJobFunctionOptions) => unknown>;
+  triggerJobFunction: Mock<(jobName: string, args?: unknown, _options?: TriggerJobFunctionOptions) => unknown>;
   /** The `triggerWorkflow` `vi.fn`. */
-  triggerWorkflow: import("vitest").Mock<(workflowName: string, args?: unknown, _options?: TriggerWorkflowOptions) => Promise<string>>;
+  triggerWorkflow: Mock<(workflowName: string, args?: unknown, _options?: TriggerWorkflowOptions) => Promise<string>>;
   /** The `resumeWorkflow` `vi.fn`. */
-  resumeWorkflow: import("vitest").Mock<(executionId: string) => Promise<string>>;
+  resumeWorkflow: Mock<(executionId: string) => Promise<string>>;
   /** The `wait` `vi.fn`. */
-  wait: import("vitest").Mock<(_key: string, _payload?: unknown) => unknown>;
+  wait: Mock<(_key: string, _payload?: unknown) => unknown>;
   /** The `resolve` `vi.fn`. */
-  resolve: import("vitest").Mock<(_executionId: string, _key: string, _callback: (payload: unknown) => unknown) => Promise<void>>;
+  resolve: Mock<(_executionId: string, _key: string, _callback: (payload: unknown) => unknown) => Promise<void>>;
+  /**
+   * Get a stable, typed mock for a workflow job's `trigger` method.
+   * The real trigger behavior is used until an implementation or result is configured.
+   * @param definition - Workflow job definition to mock
+   * @returns Typed `trigger` mock for the definition
+   */
+  job<Name extends string, Input, Output>(definition: WorkflowJob<Name, Input, Output>): Mock<WorkflowJob<Name, Input, Output>["trigger"]>;
+  /**
+   * Get a stable, typed mock for a workflow definition's `trigger` method.
+   * The real trigger behavior is used until an implementation or result is configured.
+   * @param definition - Workflow definition to mock
+   * @returns Typed `trigger` mock for the definition
+   */
+  workflow<Definition extends Workflow>(definition: Definition): Mock<Definition["trigger"]>;
+  /**
+   * Get stable, typed mocks for a wait point's `wait` and `resolve` methods.
+   * @param definition - Wait point definition to mock
+   * @returns Typed wait point mock control object
+   */
+  waitPoint<Payload, Result>(definition: WaitPointInstance<Payload, Result>): {
+    wait: Mock<WaitPointInstance<Payload, Result>["wait"]>;
+    resolve: Mock<WaitPointInstance<Payload, Result>["resolve"]>;
+    setResolvePayload(payload: WaitPayload<Payload>): void;
+  };
   /**
    * Set a fallback job handler. Called when the enqueue queue is empty.
    * @param handler - Function returning a result for a job name, args, and options
@@ -115,6 +145,8 @@ declare function mockWorkflow(): {
     executionId: string;
     key: string;
   }[];
+  /** Clear recorded calls while preserving configured responses. */
+  clear(): void;
   /** Reset all workflow responses and recorded calls (keeps the mock installed). */
   reset(): void;
 } & Disposable;

package/dist/vitest/setup.mjs

@@ -1,5 +1,5 @@
-import { t as RUNTIME_FLAG_KEY } from "../globals-z6zYMjlr.mjs";
-import { t as mockSecretmanager } from "../secretmanager-Bd45j7an.mjs";
+import { t as RUNTIME_FLAG_KEY } from "../globals-CvizbGLY.mjs";
+import { t as mockSecretmanager } from "../secretmanager-IY4UvinW.mjs";
 import { pathToFileURL } from "node:url";
 import { afterEach, beforeAll, beforeEach } from "vitest";
 

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.