@tailor-platform/sdk 1.49.0 → 1.50.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +1 -1
  3. package/dist/cli/index.mjs +92 -4
  4. package/dist/cli/index.mjs.map +1 -1
  5. package/dist/cli/lib.d.mts +1409 -1373
  6. package/dist/cli/lib.mjs +1 -1
  7. package/dist/cli/lib.mjs.map +1 -1
  8. package/dist/{runtime-oZgK353r.mjs → runtime-DgsMnMrO.mjs} +483 -168
  9. package/dist/runtime-DgsMnMrO.mjs.map +1 -0
  10. package/docs/cli/tailordb.md +50 -0
  11. package/docs/cli-reference.md +1 -0
  12. package/docs/services/tailordb-migration.md +49 -31
  13. package/package.json +3 -3
  14. package/dist/runtime-oZgK353r.mjs.map +0 -1
  15. /package/{skills → agent-skills}/tailor-sdk/SKILL.md +0 -0
package/docs/cli/tailordb.md CHANGED
@@ -154,6 +154,7 @@ tailor-sdk tailordb migration [command]
154
154
  | Command | Description |
155
155
  | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
156
156
  | [`tailordb migration generate`](#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot. |
157
+ | [`tailordb migration script`](#tailordb-migration-script) | Add a migration script (migrate.ts) template to an existing migration directory. |
157
158
  | [`tailordb migration set`](#tailordb-migration-set) | Set migration checkpoint to a specific number. |
158
159
  | [`tailordb migration status`](#tailordb-migration-status) | Show the current migration status for TailorDB namespaces, including applied and pending migrations. |
159
160
 
@@ -204,6 +205,55 @@ tailor-sdk tailordb migration generate [options]
204
205
  See [Global Options](../cli-reference.md#global-options) for options available to all commands.
205
206
 
206
207
  <!-- politty:command:tailordb migration generate:global-options-link:end -->
208
+ <!-- politty:command:tailordb migration script:heading:start -->
209
+
210
+ #### tailordb migration script
211
+
212
+ <!-- politty:command:tailordb migration script:heading:end -->
213
+
214
+ <!-- politty:command:tailordb migration script:description:start -->
215
+
216
+ Add a migration script (migrate.ts) template to an existing migration directory.
217
+
218
+ <!-- politty:command:tailordb migration script:description:end -->
219
+
220
+ <!-- politty:command:tailordb migration script:usage:start -->
221
+
222
+ **Usage**
223
+
224
+ ```
225
+ tailor-sdk tailordb migration script [options] <number>
226
+ ```
227
+
228
+ <!-- politty:command:tailordb migration script:usage:end -->
229
+
230
+ <!-- politty:command:tailordb migration script:arguments:start -->
231
+
232
+ **Arguments**
233
+
234
+ | Argument | Description | Required |
235
+ | -------- | ----------------------------------------------------- | -------- |
236
+ | `number` | Migration number to add a script to (e.g., 0001 or 1) | Yes |
237
+
238
+ <!-- politty:command:tailordb migration script:arguments:end -->
239
+
240
+ <!-- politty:command:tailordb migration script:options:start -->
241
+
242
+ **Options**
243
+
244
+ | Option | Alias | Description | Required | Default | Env |
245
+ | ------------------------- | ----- | ----------------------------------------------------------------- | -------- | -------------------- | --------------------------------- |
246
+ | `--config <CONFIG>` | `-c` | Path to SDK config file | No | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
247
+ | `--namespace <NAMESPACE>` | `-n` | Target TailorDB namespace (required if multiple namespaces exist) | No | - | - |
248
+
249
+ <!-- politty:command:tailordb migration script:options:end -->
250
+
251
+ <!-- politty:command:tailordb migration script:global-options-link:start -->
252
+
253
+ See [Global Options](../cli-reference.md#global-options) for options available to all commands.
254
+
255
+ <!-- politty:command:tailordb migration script:global-options-link:end -->
256
+
207
257
  <!-- politty:command:tailordb migration set:heading:start -->
208
258
 
209
259
  #### tailordb migration set
package/docs/cli-reference.md CHANGED
@@ -114,6 +114,7 @@ Commands for managing TailorDB tables, data, and schema migrations.
114
114
  | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
115
115
  | [tailordb truncate](./cli/tailordb.md#tailordb-truncate) | Truncate (delete all records from) TailorDB tables. |
116
116
  | [tailordb migration generate](./cli/tailordb.md#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot. |
117
+ | [tailordb migration script](./cli/tailordb.md#tailordb-migration-script) | Add a migration script (migrate.ts) template to an existing migration directory. |
117
118
  | [tailordb migration set](./cli/tailordb.md#tailordb-migration-set) | Set migration checkpoint to a specific number. |
118
119
  | [tailordb migration status](./cli/tailordb.md#tailordb-migration-status) | Show the current migration status for TailorDB namespaces, including applied and pending migrations. |
119
120
  | [tailordb erd export](./cli/tailordb.md#tailordb-erd-export) | Export Liam ERD dist from applied TailorDB schema. |
package/docs/services/tailordb-migration.md CHANGED
@@ -23,14 +23,14 @@ migrations/
23
23
  │ └── schema.json
24
24
  ├── 0001/ # First change
25
25
  │ ├── diff.json # Field-level diff from 0000
26
- │ ├── migrate.ts # Data migration script (only if breaking)
26
+ │ ├── migrate.ts # Data migration script (auto-generated for breaking changes; can be added manually via `migration script`)
27
27
  │ └── db.ts # Kysely types for the script (pre-migration shape)
28
28
  ├── 0002/
29
29
  │ └── diff.json # No script — non-breaking changes only
30
30
  └── ...
31
31
  ```
32
32
 
33
- `0000` always contains a full snapshot. `0001` and onward contain a diff plus, for breaking changes, a script and its types. **Commit the entire `migrations/` directory to version control.**
33
+ `0000` always contains a full snapshot. `0001` and onward contain a diff plus, optionally, a script and its types (auto-generated for breaking changes, or added manually via `tailordb migration script` for warning-tier changes). **Commit the entire `migrations/` directory to version control.**
34
34
 
35
35
  ## Initial Setup
36
36
 
@@ -113,6 +113,24 @@ A typical change cycle:
113
113
  ```
114
114
  The pre-migration phase relaxes the new field to optional, the script runs and populates values, then the post-migration phase enforces `required: true`.
115
115
 
116
+ ### Warnings and optional migration scripts
117
+
118
+ Some non-breaking changes can still cause data loss — most notably removing a field (`field_removed`) or removing a type (`type_removed`). `migration generate` reports these as **warnings**:
119
+
120
+ ```
121
+ Warning: data loss possible:
122
+
123
+ - User.legacyParentId: Field removed (existing data will be dropped in the post-migration phase)
124
+ ```
125
+
126
+ No `migrate.ts` is generated automatically because the schema change itself is non-breaking, but the existing data is dropped during the post-migration phase. If you need to preserve or transform that data first (for example, copy a column into another table before it disappears), add a script with:
127
+
128
+ ```bash
129
+ tailor-sdk tailordb migration script 0002
130
+ ```
131
+
132
+ This writes `migrations/0002/migrate.ts` and `migrations/0002/db.ts` next to the existing `diff.json`. The removed field stays readable inside `migrate.ts` because the pre-migration phase keeps it on the type until the script finishes (see [Per-migration phases](#per-migration-phases)). The next `tailor-sdk deploy` runs the script automatically — `migrate.ts` is executed whenever the file exists on disk, regardless of whether the diff itself required it.
133
+
116
134
  ## Configuration
117
135
 
118
136
  ```typescript
@@ -139,12 +157,12 @@ export default defineConfig({
139
157
 
140
158
  ## Generated Files
141
159
 
142
- | File | When generated | Description |
143
- | ------------------ | -------------------------------- | --------------------------------------------------------------------------------------------------------- |
144
- | `0000/schema.json` | First `migration generate` | Full snapshot of all types in the namespace. |
145
- | `XXXX/diff.json` | Every subsequent migration | Field-level diff against the previous snapshot. |
146
- | `XXXX/migrate.ts` | Only for breaking changes | Data transformation script. The `main` export receives a Kysely `Transaction`. |
147
- | `XXXX/db.ts` | Generated alongside `migrate.ts` | Kysely types reflecting the schema **before** this migration. Re-generated on every `migration generate`. |
160
+ | File | When generated | Description |
161
+ | ------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
162
+ | `0000/schema.json` | First `migration generate` | Full snapshot of all types in the namespace. |
163
+ | `XXXX/diff.json` | Every subsequent migration | Field-level diff against the previous snapshot. |
164
+ | `XXXX/migrate.ts` | Auto-generated for breaking changes; added manually via `tailordb migration script` for warning-tier changes | Data transformation script. The `main` export receives a Kysely `Transaction`. |
165
+ | `XXXX/db.ts` | Generated once when `migrate.ts` is created | Kysely types reflecting the schema **before** this migration. |
148
166
 
149
167
  `db.ts` reflects the pre-migration schema because the script runs after the pre-migration phase has temporarily relaxed breaking constraints (e.g., a new `required` field is added as `optional` first), so the data being read still matches the previous shape.
150
168
 
@@ -178,25 +196,25 @@ export async function main(trx: Transaction): Promise<void> {
178
196
 
179
197
  ## Supported Schema Changes
180
198
 
181
- | Change Type | Breaking? | Migration Script? | Notes |
182
- | ------------------------------ | --------- | ----------------- | ------------------------------------------------------------------------------------- |
183
- | Add optional field | No | No | Schema change only |
184
- | Add required field | Yes | Yes | Script populates default values |
185
- | Remove field | No | No | Schema change only — data is preserved server-side |
186
- | Change optional → required | Yes | Yes | Script sets defaults for null values |
187
- | Change required → optional | No | No | Schema change only |
188
- | Add index | No | No | Schema change only |
189
- | Remove index | No | No | Schema change only |
190
- | Add unique constraint | Yes | Yes | Script must resolve duplicate values |
191
- | Remove unique constraint | No | No | Schema change only |
192
- | Add enum value | No | No | Schema change only |
193
- | Remove enum value | Yes | Yes | Script migrates records with removed values |
194
- | Add type | No | No | Schema change only |
195
- | Remove type | No | No | Schema change only — data is preserved server-side |
196
- | Change foreign key target type | Yes | Yes | Script updates references to the new target |
197
- | Change field type | - | - | **Not supported** — see [3-step migration](#3-step-migration-for-unsupported-changes) |
198
- | Change array → single value | - | - | **Not supported** — see [3-step migration](#3-step-migration-for-unsupported-changes) |
199
- | Change single value → array | - | - | **Not supported** — see [3-step migration](#3-step-migration-for-unsupported-changes) |
199
+ | Change Type | Breaking? | Migration Script? | Notes |
200
+ | ------------------------------ | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
201
+ | Add optional field | No | No | Schema change only |
202
+ | Add required field | Yes | Yes | Script populates default values |
203
+ | Remove field | No | Optional | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve data before the field is dropped. The field stays readable from `migrate.ts` during Pre-migration and is dropped in Post-migration. |
204
+ | Change optional → required | Yes | Yes | Script sets defaults for null values |
205
+ | Change required → optional | No | No | Schema change only |
206
+ | Add index | No | No | Schema change only |
207
+ | Remove index | No | No | Schema change only |
208
+ | Add unique constraint | Yes | Yes | Script must resolve duplicate values |
209
+ | Remove unique constraint | No | No | Schema change only |
210
+ | Add enum value | No | No | Schema change only |
211
+ | Remove enum value | Yes | Yes | Script migrates records with removed values |
212
+ | Add type | No | No | Schema change only |
213
+ | Remove type | No | Optional | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve data before the type is dropped. The type stays readable from `migrate.ts` during Pre-migration and is dropped in Post-migration. |
214
+ | Change foreign key target type | Yes | Yes | Script updates references to the new target |
215
+ | Change field type | - | - | **Not supported** — see [3-step migration](#3-step-migration-for-unsupported-changes) |
216
+ | Change array → single value | - | - | **Not supported** — see [3-step migration](#3-step-migration-for-unsupported-changes) |
217
+ | Change single value → array | - | - | **Not supported** — see [3-step migration](#3-step-migration-for-unsupported-changes) |
200
218
 
201
219
  ### 3-step migration for unsupported changes
202
220
 
@@ -216,11 +234,11 @@ When you run `tailor-sdk deploy`, the SDK detects pending migrations (anything p
216
234
 
217
235
  For each pending migration:
218
236
 
219
- 1. **Pre-migration**: Type changes that would be breaking are applied in a relaxed form first. Newly-required fields are added as optional; fields whose `optional → required` transition is breaking are temporarily kept optional. Non-breaking changes that are part of the same migration are also applied here.
220
- 2. **Script execution**: If `diff.requiresMigrationScript` is true, `migrate.ts` is bundled and sent to the platform via the script execution API. It runs as the configured machine user inside a transaction.
221
- 3. **Post-migration**: Required constraints are enforced; field/type deletions are applied; the `sdk-migration` label is bumped to this migration's number.
237
+ 1. **Pre-migration**: Type changes that would be breaking are applied in a relaxed form first. Newly-required fields are added as optional; fields whose `optional → required` transition is breaking are temporarily kept optional. Fields that are being removed in this migration are temporarily kept on the type so that `migrate.ts` can still read them (for example, to `innerJoin` through a foreign key that is about to be dropped). Non-breaking changes that are part of the same migration are also applied here.
238
+ 2. **Script execution**: If `migrate.ts` exists on disk for this migration, it is bundled and sent to the platform via the script execution API and runs as the configured machine user inside a transaction. The script is hard-required for breaking changes (`diff.requiresMigrationScript`) but is also executed when present for warning-tier diffs — see [Warnings and optional migration scripts](#warnings-and-optional-migration-scripts).
239
+ 3. **Post-migration**: Required constraints are enforced; field and type deletions are applied (the columns/tables are physically dropped here); the `sdk-migration` label is bumped to this migration's number.
222
240
 
223
- This split is what allows existing rows to be backfilled before the database starts rejecting nulls.
241
+ This split is what allows existing rows to be backfilled before the database starts rejecting nulls, and what lets `migrate.ts` traverse foreign-key fields that the same migration removes.
224
242
 
225
243
  ### Schema verification
226
244
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tailor-platform/sdk",
3
- "version": "1.49.0",
3
+ "version": "1.50.1",
4
4
  "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -18,7 +18,7 @@
18
18
  "docs",
19
19
  "postinstall.mjs",
20
20
  "README.md",
21
- "skills"
21
+ "agent-skills"
22
22
  ],
23
23
  "type": "module",
24
24
  "sideEffects": [
@@ -110,7 +110,7 @@
110
110
  "@tailor-platform/function-kysely-tailordb": "0.1.3",
111
111
  "@tailor-platform/function-types": "0.8.5",
112
112
  "@toiroakr/lines-db": "0.9.2",
113
- "@toiroakr/read-multiline": "0.3.2",
113
+ "@toiroakr/read-multiline": "0.4.1",
114
114
  "@urql/core": "6.0.1",
115
115
  "chalk": "5.6.2",
116
116
  "chokidar": "5.0.0",