@tailor-platform/sdk 2.37.0 → 2.38.0

package/docs/cli/application.md

@@ -82,7 +82,7 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Notes**
 
-Every workspace belongs to an organization; when none is given or set as a default, interactive runs ask for one and non-interactive runs fail. Workspace creation uses the selected user's default organization and folder set by `user update` when neither location is given and TAILOR_PLATFORM_TOKEN is not set. Giving --organization-id or --folder-id replaces both defaults. Organization and folder IDs loaded by --env-file also replace the defaults; command-line options take precedence, and empty env-file values are ignored. With --create-workspace, an existing workspace must match the resolved name, region, organization, and folder to be reused.
+Every workspace belongs to an organization; when none is given or set as a default, interactive runs ask for one and non-interactive runs fail. Workspace creation uses the selected user's default organization and folder set by `user update` when neither location is given and TAILOR_PLATFORM_TOKEN is not set. Giving --organization-id or --folder-id replaces both defaults. TAILOR_PLATFORM_ORGANIZATION_ID and TAILOR_PLATFORM_FOLDER_ID, including values loaded by --env-file, also replace the defaults; command-line options take precedence, and an empty value of either variable is ignored. With --create-workspace, an existing workspace must match the resolved name, region, organization, and folder to be reused.
 
 **JSON result:**
 
@@ -183,16 +183,20 @@ Names that identify a resource across the whole workspace, such as application,
 
 Each config's `files` and `ignores` patterns (see [Service Configuration](../configuration.md#service-configuration)) resolve relative to that config's own directory, not the directory you ran `deploy` from. For example, `apps/buyer/tailor.config.ts` declaring `files: ["db/**/*.ts"]` loads files from `apps/buyer/db/`, independent of where `apps/supplier/tailor.config.ts`'s patterns resolve. If a config's relative patterns match nothing under its own directory, the SDK falls back to the invocation directory and logs a warning (see [Service Configuration](../configuration.md#service-configuration) for details).
 
-**Migration Handling:**
+**Migration Handling (Beta):**
 
-When migrations are configured (`db.tailordb.migration` in config), the `deploy` command automatically:
+When migrations are configured (`db.<namespace>.migration` in config), the `deploy` command:
 
-1. Detects pending migration scripts that haven't been executed
-2. Applies schema changes in a safe order (pre-migration → script execution → post-migration)
-3. Runs the pending migration scripts
-4. Updates the migration checkpoint so the same migrations are not re-run
+1. Checks the migration files and the migration state of each namespace (see Schema Check below) three times: while planning, so `--dry-run` reports a failure too; before it applies anything for any config; and again when it applies each config's TailorDB changes. If the migration files, a checkpoint reset, or the tables to delete changed after planning, the deploy stops with `DEPLOY_PLAN_STALE`.
+2. Resets the checkpoints that the plan showed would be reset to `0000` after a re-baseline, clears an in-progress record that an earlier deploy left on a migration it had already committed, and deletes the tables that a committed migration removed but an earlier deploy did not delete.
+3. Applies the changes of namespaces without pending migrations, except deletions. This also takes their tables out of a maintenance mode that an interrupted deploy left.
+4. Puts every namespace with pending migrations into maintenance mode, unless `maintenanceMode` is `false`.
+5. Runs the pending migrations one namespace at a time, in alphabetical order of the namespace names, and in number order within a namespace. Each migration applies its pre-migration schema, runs its `migrate.ts`, applies its post-migration schema, advances the checkpoint, and then deletes the tables and GraphQL permissions it removed.
+6. With `--no-schema-check`, applies the local table definitions that the pending migrations do not include (see [Schema verification](../services/tailordb/migration.md#schema-verification)).
+7. Takes the tables out of maintenance mode, or with `maintenanceMode: "deploy"`, leaves that to the end of the deploy.
+8. Deletes the remaining tables and GraphQL permissions that are no longer in the config.
 
-See [Automatic Migration Execution](../services/tailordb/migration.md#automatic-migration-execution) for details on automatic migration execution.
+See [Automatic Migration Execution](../services/tailordb/migration.md#automatic-migration-execution) for details on automatic migration execution, and [Several configs in one deploy](../services/tailordb/migration.md#several-configs-in-one-deploy) for the state a failed migration leaves the other configs in.
 
 **Concurrent Deploys:**
 
@@ -207,7 +211,7 @@ By default, `deploy` performs two verification steps:
 
 If remote schema drift is detected, the deploy will fail with an error showing the differences. This helps prevent applying migrations to an inconsistent state.
 
-Use `--no-schema-check` to skip both verifications (not recommended for production). It does not skip the check that the remote migration checkpoint is in the local migration history: when the deployed checkpoint is ahead of the local migration files or belongs to another migration history, the deploy stops before changing anything. Pull the latest migration files, or move the checkpoint on purpose with `tailor tailordb migration sync` or `tailor tailordb migration set`, adding `--force` when the checkpoint belongs to another migration history or has a history label that cannot be read, then deploy again.
+Use `--no-schema-check` to skip both verifications (not recommended for production). It does not skip the check that the remote migration checkpoint is in the local migration history: when the deployed checkpoint is ahead of the local migration files or belongs to another migration history, the deploy stops before changing anything. Pull the latest migration files, or move the checkpoint on purpose with `tailor tailordb migration sync`, adding `--force` when the checkpoint belongs to another migration history or has a history label that cannot be read, then deploy again.
 
 **Plan Output:**
 

package/docs/cli/notification.md

@@ -0,0 +1,128 @@
+---
+description: "List, read and dismiss the platform notifications sent to you from the tailor CLI."
+---
+
+# Notification Commands
+
+Commands for reading the platform notifications addressed to you: alerts you must act on,
+incidents, maintenance notices and announcements. The inbox is per user, so these commands take a
+profile (for its login) but no workspace. Marking a notification read or dismissing it in the CLI
+also changes it in the Console, which shows the same inbox.
+
+When no subcommand is provided, defaults to `list`.
+
+## notification
+
+Read the platform notifications sent to you.
+
+**Usage**
+
+```
+tailor notification [command]
+```
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Commands**
+
+| Command                                         | Description                              |
+| ----------------------------------------------- | ---------------------------------------- |
+| [`notification list`](#notification-list)       | List the notifications in your inbox.    |
+| [`notification read`](#notification-read)       | Show a notification and mark it as read. |
+| [`notification dismiss`](#notification-dismiss) | Remove a notification from your inbox.   |
+
+### notification dismiss
+
+Remove a notification from your inbox.
+
+**Usage**
+
+```
+tailor notification dismiss [options] <id>
+```
+
+**Arguments**
+
+| Argument | Description     | Required |
+| -------- | --------------- | -------- |
+| `id`     | Notification ID | Yes      |
+
+**Options**
+
+| Option                | Alias | Description       | Required | Default | Env                       |
+| --------------------- | ----- | ----------------- | -------- | ------- | ------------------------- |
+| `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+### notification list
+
+List the notifications in your inbox.
+
+**Usage**
+
+```
+tailor notification list [options]
+```
+
+**Options**
+
+| 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: unlimited)                | No       | `50`     | -                         |
+| `--profile <PROFILE>`                       | `-p`  | Workspace profile                                               | No       | -        | `TAILOR_PLATFORM_PROFILE` |
+| `--category <CATEGORY>`                     | -     | Only this category (alert, incident, maintenance, announcement) | No       | -        | -                         |
+| `--severity <SEVERITY>`                     | -     | Only this severity or higher (info, warning, critical)          | No       | -        | -                         |
+| `--unread`                                  | -     | Only unread notifications                                       | No       | `false`  | -                         |
+| `--scope-workspace <SCOPE_WORKSPACE>`       | -     | Only notifications about this workspace ID                      | No       | -        | -                         |
+| `--scope-organization <SCOPE_ORGANIZATION>` | -     | Only notifications about this organization ID                   | No       | -        | -                         |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+### notification read
+
+Show a notification and mark it as read.
+
+**Usage**
+
+```
+tailor notification read [options] <id>
+```
+
+**Arguments**
+
+| Argument | Description                  | Required |
+| -------- | ---------------------------- | -------- |
+| `id`     | Notification ID (repeatable) | Yes      |
+
+**Options**
+
+| Option                | Alias | Description                                      | Required | Default | Env                       |
+| --------------------- | ----- | ------------------------------------------------ | -------- | ------- | ------------------------- |
+| `--no-mark-read`      | -     | Show the notification without marking it as read | No       | `false` | -                         |
+| `--profile <PROFILE>` | `-p`  | Workspace profile                                | No       | -       | `TAILOR_PLATFORM_PROFILE` |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Output (default):**
+
+```
+┌──────────────────────────────────────┬──────────┬──────────────┬─────────────────────────────────┬─────────────┬────────────┐
+│ id                                   │ severity │ category     │ title                           │ arrivedAt   │ readAt     │
+├──────────────────────────────────────┼──────────┼──────────────┼─────────────────────────────────┼─────────────┼────────────┤
+│ 0d2c0f1e-5c2b-4e3a-9c1d-2f6a7b8c9d0e │ warning  │ maintenance  │ Scheduled maintenance on Nov 3  │ 2 hours ago │ unread     │
+│ 1d2c0f1e-5c2b-4e3a-9c1d-2f6a7b8c9d0e │ info     │ announcement │ Platform notifications are live │ 3 days ago  │ 2 days ago │
+└──────────────────────────────────────┴──────────┴──────────────┴─────────────────────────────────┴─────────────┴────────────┘
+```
+
+`tailor notification read <id>` prints the title, the metadata, the body as plain text (it is
+Markdown, shown as written) and the action links, then marks the notification read. Pass
+`--no-mark-read` to only display it. Several IDs can be given at once. If some of them are not
+found, the others are still shown and marked read, and the command then fails naming the missing
+IDs. With a read-only login, the notifications are shown but not marked read, and a warning says
+so.
+
+`tailor notification dismiss <id>` removes a notification from your inbox. This cannot be undone:
+`read` and `list` no longer show it. It needs a profile that is not read-only. Notifications you
+do not dismiss stay until the platform expires or revokes them.

package/docs/cli/tailordb.md

@@ -98,17 +98,16 @@ tailor tailordb migration <command>
 
 **Commands**
 
-| Command                                                           | Description                                                                                                                                                                                                                                                                                                               |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`tailordb migration generate`](#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                                                                                                                                                                                |
-| [`tailordb migration rebaseline`](#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                                                                                                                                                                             |
-| [`tailordb migration resolve`](#tailordb-migration-resolve)       | Settle a migration that a failed deploy left partially applied, or whose run a deploy could not confirm.                                                                                                                                                                                                                  |
-| [`tailordb migration script`](#tailordb-migration-script)         | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.                                                                                                                                                                      |
-| [`tailordb migration set`](#tailordb-migration-set)               | Set migration checkpoint to a specific number.                                                                                                                                                                                                                                                                            |
-| [`tailordb migration status`](#tailordb-migration-status)         | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                                                                                                                                                                                      |
-| [`tailordb migration sync`](#tailordb-migration-sync)             | Sync remote TailorDB schema and checkpoint to a local migration snapshot to recover from schema drift or a checkpoint outside the local history.                                                                                                                                                                          |
-| [`tailordb migration test`](#tailordb-migration-test)             | Test pending migrations with seed fixtures or cloned data in a temporary workspace.                                                                                                                                                                                                                                       |
-| [`tailordb migration validate`](#tailordb-migration-validate)     | Validate the full migration history, unreviewed generated migration scripts, and schema drift (local tables vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found. |
+| Command                                                           | Description                                                                                                                                                    |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`tailordb migration generate`](#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                     |
+| [`tailordb migration rebaseline`](#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                  |
+| [`tailordb migration resolve`](#tailordb-migration-resolve)       | Settle a migration that a failed deploy left partially applied, or whose run a deploy could not confirm.                                                       |
+| [`tailordb migration script`](#tailordb-migration-script)         | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.           |
+| [`tailordb migration status`](#tailordb-migration-status)         | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                           |
+| [`tailordb migration sync`](#tailordb-migration-sync)             | Sync remote TailorDB schema and checkpoint to a local migration snapshot to recover from schema drift or a checkpoint outside the local history.               |
+| [`tailordb migration test`](#tailordb-migration-test)             | Test pending migrations with seed fixtures or cloned data in a temporary workspace.                                                                            |
+| [`tailordb migration validate`](#tailordb-migration-validate)     | Run the migration and schema-drift checks that 'deploy' runs before changing anything, without deploying, and exit with a non-zero code when issues are found. |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -197,6 +196,8 @@ Use this after a deploy failed partway through a migration whose `migrate.ts` ex
 
 For a run that a deploy could not confirm, the command reads how the run ended and shows it before asking for confirmation: use `--complete` when it succeeded, and `--rollback` when it failed, was canceled, or did not start. It refuses while the run is still running, and warns when the option you chose does not fit how the run ended.
 
+`--rollback` also settles a migration that no deploy recorded as in progress, but whose pre-migration schema or maintenance mode a deploy left in place, for example because the deploy stopped before recording it. See "Settling a migration that stays in progress" in the TailorDB Migrations guide for when it runs.
+
 Both options remove the in-progress record, take the tables out of maintenance mode, and remove the temporary resources of the failed run, so `deploy` and the other migration commands work again. As with `tailordb migration sync`, the local migration history must reproduce the current table definitions. If sending the schema stops partway, run the command again.
 
 #### tailordb migration script
@@ -231,43 +232,6 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 When `migrate.ts` already exists, running the command clears a previously recorded `--no-script` acknowledgment, and `--with-test` adds only the tests that do not exist yet (writing `db.pglite.ts` if it is missing). `migrate.pglite.test.ts` is scaffolded only when `@electric-sql/pglite` is installed in the project.
 
-#### tailordb migration set
-
-Set migration checkpoint to a specific number.
-
-**Usage**
-
-```
-tailor tailordb migration set [options] <number>
-```
-
-**Arguments**
-
-| Argument | Description                               | Required |
-| -------- | ----------------------------------------- | -------- |
-| `number` | Migration number to set (e.g., 0001 or 1) | Yes      |
-
-**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 Tailor config file                                                              | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
-| `--yes`                         | `-y`  | Skip confirmation prompts                                                               | No       | `false`              | -                              |
-| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (required if multiple namespaces exist)                       | No       | -                    | -                              |
-| `--force`                       | -     | Proceed even when the namespace records a migration history ID other than the local one | No       | `false`              | -                              |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-**Notes**
-
-The migration number must be a 4-digit value (e.g. `0001`) or a bare integer (e.g. `1`) within 0–9999, and must exist in the local migration history; `0` is always accepted as the baseline, provided the local history passes validation. A gapped history is rejected.
-
-The command refuses to run when the namespace records a migration history ID other than the local one, or one that cannot be read, unless the namespace has neither a checkpoint nor a history ID yet. `--force` replaces that history ID with the local one, or removes it when the local history has none, and still asks for confirmation unless `--yes` is given.
-
-Metadata lookup failures (authentication, permission, or network errors) are reported as errors; only a not-yet-deployed namespace is treated as having no checkpoint.
-
 #### tailordb migration status
 
 Show the current migration status for TailorDB namespaces, including applied and pending migrations.
@@ -359,11 +323,11 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Notes**
 
-The source workspace is read-only. Without --target-workspace-id, the command creates a workspace in the source workspace's region and deletes it after success or failure; pass --keep to retain it for inspection. Right after creating the workspace it records a 24h expiry (unless --keep is given without --keep-ttl), so if the run is interrupted before the command can delete the workspace, workspace prune --expired removes it later. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs. With --keep-ttl, the kept workspace records an expiry; it is not deleted automatically, but workspace prune --expired removes it once the expiry has passed. Organization and folder IDs loaded by --env-file are used the same way as the options; command-line options take precedence, and empty env-file values are ignored.
+The source workspace is read-only. Without --target-workspace-id, the command creates a workspace in the source workspace's region and deletes it after success or failure; pass --keep to retain it for inspection. Right after creating the workspace it records a 24h expiry (unless --keep is given without --keep-ttl), so if the run is interrupted before the command can delete the workspace, workspace prune --expired removes it later. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs. With --keep-ttl, the kept workspace records an expiry; it is not deleted automatically, but workspace prune --expired removes it once the expiry has passed. Command-line options take precedence over TAILOR_PLATFORM_ORGANIZATION_ID and TAILOR_PLATFORM_FOLDER_ID, including values loaded by --env-file, and an empty value of either variable is ignored.
 
 #### tailordb migration validate
 
-Validate the full migration history, unreviewed generated migration scripts, and schema drift (local tables vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found.
+Run the migration and schema-drift checks that 'deploy' runs before changing anything, without deploying, and exit with a non-zero code when issues are found.
 
 **Usage**
 
@@ -373,16 +337,21 @@ tailor tailordb migration validate [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 Tailor config file                                                 | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
-| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (validates all namespaces if not specified)      | No       | -                    | -                              |
-| `--strict`                      | -     | Also fail when a pending migration can drop data without an acknowledgment | 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`      |
+| `--config <CONFIG>`                             | `-c`  | Path to Tailor config file                                                                                                                                  | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
+| `--namespace <NAMESPACE>`                       | `-n`  | Target TailorDB namespace (validates all namespaces if not specified)                                                                                       | No       | -                    | -                              |
+| `--strict`                                      | -     | Also fail when a pending migration can drop data without an acknowledgment                                                                                  | No       | `false`              | -                              |
+| `--migration-skip-steps <MIGRATION_SKIP_STEPS>` | -     | Also check that 'deploy --migration-skip-steps' can skip these steps of a partially applied multi-step migration, as comma-separated namespace/step entries | No       | -                    | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+Migration scripts are checked across the full migration history, not only the pending migrations that `deploy` checks. Like `deploy`, the command bundles only the pending scripts and checks the machine user that runs them.
+
 **See also:** For migration concepts, configuration, workflow, and troubleshooting, see the [TailorDB Migrations guide](../services/tailordb/migration.md).
 
 ### tailordb erd (Beta)

package/docs/cli/workspace.md

@@ -123,7 +123,7 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 Every workspace belongs to an organization. Without --organization-id and --folder-id, on the command line or through TAILOR_PLATFORM_ORGANIZATION_ID / TAILOR_PLATFORM_FOLDER_ID, the workspace is created in the default organization and folder that the logged-in user set with `user update`, unless TAILOR_PLATFORM_TOKEN is set. When none of these gives an organization, the command fails. Giving either option replaces both defaults, and --folder-id requires --organization-id.
 
-TAILOR_PLATFORM_ORGANIZATION_ID and TAILOR_PLATFORM_FOLDER_ID are also read from --env-file. Command-line options take precedence over the corresponding environment variables. Empty values in the env file are treated as not given.
+Command-line options take precedence over TAILOR_PLATFORM_ORGANIZATION_ID and TAILOR_PLATFORM_FOLDER_ID, including values loaded by --env-file. An empty value of either variable is treated as not given.
 
 When --ttl is given but the expiry cannot be confirmed, the command still prints the created workspace, then fails with WORKSPACE_TTL_WRITE_FAILED. With --json, the printed `ttl.state` is then `unconfirmed` instead of `written`, so a script can read the workspace ID and record the expiry again with `workspace ttl set`.