@tailor-platform/sdk 2.0.0-next.1 → 2.0.0-next.2

package/docs/migration/v2.md

@@ -0,0 +1,475 @@
+# Migrating to v2
+
+<!-- Generated from the sdk-codemod registry. Run `pnpm codemod:docs:update` and edit `packages/sdk-codemod/src/registry.ts` instead of this file. -->
+
+Run the codemods, then finish anything reported as not migrated automatically:
+
+```sh
+npx @tailor-platform/sdk-codemod --from <current-version> --to <target-version>
+```
+
+## defineGenerators → definePlugins
+
+**Migration:** Partially automatic
+
+Migrate defineGenerators() tuple syntax to definePlugins() with explicit plugin imports
+
+Before:
+
+```ts
+import { defineGenerators } from "@tailor-platform/sdk";
+
+export const generators = defineGenerators(
+  ["@tailor-platform/kysely-type", { distPath: "db.ts" }],
+);
+```
+
+After:
+
+```ts
+import { definePlugins } from "@tailor-platform/sdk";
+import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
+
+export const generators = definePlugins(kyselyTypePlugin({ distPath: "db.ts" }));
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+defineGenerators() is replaced by definePlugins() in v2. The codemod rewrites the
+known plugin tuples (kysely-type, enum-constants, file-utils, seed). For any
+remaining defineGenerators([...]) the codemod left in place — a plugin it does not
+know, or a non-tuple/spread form — convert it to definePlugins(pluginFn(config)),
+importing the matching plugin from its @tailor-platform/sdk/plugin/<name> subpath.
+```
+
+</details>
+
+## @tailor-platform/sdk/cli plugin imports → dedicated subpaths
+
+**Migration:** Automatic
+
+Rewrite deprecated plugin re-export imports (kyselyTypePlugin, enumConstantsPlugin, fileUtilsPlugin, seedPlugin) from `@tailor-platform/sdk/cli` to their dedicated plugin subpaths
+
+Before:
+
+```ts
+import { kyselyTypePlugin } from "@tailor-platform/sdk/cli";
+```
+
+After:
+
+```ts
+import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
+```
+
+## function test-run --arg input unwrap
+
+**Migration:** Automatic
+
+Strip the deprecated {input: ...} wrapper from `tailor-sdk function test-run --arg` JSON in scripts and docs
+
+Before:
+
+```sh
+tailor-sdk function test-run resolvers/add.ts --arg '{"input":{"a":1}}'
+```
+
+After:
+
+```sh
+tailor-sdk function test-run resolvers/add.ts --arg '{"a":1}'
+```
+
+## tailor-sdk-skills → tailor-sdk skills install
+
+**Migration:** Partially automatic
+
+Replace deprecated `tailor-sdk-skills` invocations with `tailor-sdk skills install`
+
+Before:
+
+```sh
+npx tailor-sdk-skills
+```
+
+After:
+
+```sh
+tailor-sdk skills install
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+The standalone tailor-sdk-skills binary is removed in v2; call the skills install
+subcommand on the main tailor-sdk CLI instead. Replace any remaining
+tailor-sdk-skills invocations the codemod did not rewrite with
+`tailor-sdk skills install`.
+```
+
+</details>
+
+## Unify TailorUser/TailorActor/TailorActorType/TailorInvoker → TailorPrincipal
+
+**Migration:** Partially automatic
+
+Rename TailorUser/TailorActor/TailorActorType/TailorInvoker to TailorPrincipal, drop unauthenticatedTailorUser, rename resolver body `user` to `caller`, and rename TailorDB callback `user` to `invoker`
+
+Type references unify under `TailorPrincipal`:
+
+Before:
+
+```ts
+import type { TailorUser } from "@tailor-platform/sdk";
+```
+
+After:
+
+```ts
+import type { TailorPrincipal } from "@tailor-platform/sdk";
+```
+
+The resolver body `user` becomes `caller`:
+
+Before:
+
+```ts
+body: ({ input, user }) => user.id,
+```
+
+After:
+
+```ts
+body: ({ input, caller }) => caller.id,
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Finish the cases the codemod left for manual migration:
+- Rename user -> caller in resolver bodies the codemod skipped because a `caller`
+  binding already exists or renaming would shadow/collide with another value.
+- Replace member-access on the removed unauthenticatedTailorUser (e.g.
+  unauthenticatedTailorUser.id); the codemod only replaced standalone references
+  with null and left member access to surface a type error.
+- Review helper adapters that still accept or read `context.user`; v2 resolver
+  context uses nullable `caller` and `invoker`, so project-specific helper
+  semantics for anonymous callers and command invokers must be chosen explicitly.
+- Review `caller?.` values passed to APIs that require non-null values. If the
+  resolver requires authentication, throw or otherwise narrow before the call;
+  if anonymous callers are allowed, keep the nullable flow explicit.
+Use TailorPrincipal for the unified user/actor/invoker type.
+```
+
+</details>
+
+## tailor-sdk apply → tailor-sdk deploy
+
+**Migration:** Automatic
+
+Rewrite `tailor-sdk apply` invocations in package.json scripts, shell scripts, CI configs, and docs to the canonical v2 `tailor-sdk deploy` command
+
+Before:
+
+```sh
+tailor-sdk apply --profile prod
+```
+
+After:
+
+```sh
+tailor-sdk deploy --profile prod
+```
+
+## v2 CLI rename
+
+**Migration:** Partially automatic
+
+Rewrite `tailor-sdk crash-report` to `tailor-sdk crashreport` and `--machineuser` to `--machine-user` across package.json scripts, shell scripts, CI configs, and docs
+
+Before:
+
+```sh
+tailor-sdk crash-report list
+tailor-sdk login --machineuser
+```
+
+After:
+
+```sh
+tailor-sdk crashreport list
+tailor-sdk login --machine-user
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Apply the v2 CLI renames the codemod did not reach (only `tailor-sdk`-prefixed
+invocations are rewritten): `tailor-sdk crash-report` -> `tailor-sdk crashreport`
+and the `--machineuser` option -> `--machine-user`. Leave unrelated commands that
+happen to use `--machineuser` alone.
+```
+
+</details>
+
+## auth.invoker("name") → "name"
+
+**Migration:** Partially automatic
+
+Replace `auth.invoker("name")` calls with the bare `"name"` string and drop the `auth` import when no other reference remains. The `auth.invoker()` helper is deprecated in v2 because importing `auth` from `tailor.config.ts` into runtime files pulls Node-only modules into the bundle.
+
+Before:
+
+```ts
+createResolver({ invoker: auth.invoker("manager") });
+```
+
+After:
+
+```ts
+createResolver({ invoker: "manager" });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2 the auth.invoker() helper is removed; an invoker is now the
+machine user name passed directly as a string. The codemod already rewrote the
+string-literal form auth.invoker("name") to "name". These files still contain
+auth.invoker(...) because the argument is not a plain string literal (a variable,
+template literal, function call, or property access).
+
+For each remaining auth.invoker(<expr>) call:
+1. Replace the whole call with <expr> as-is (e.g. auth.invoker(name) becomes name).
+2. Make sure <expr> evaluates to the machine user name (a string); adjust it if it
+   resolves to an object or an auth config value instead.
+3. After removing every auth.invoker usage in a file, delete the now-unused auth
+   import (keeping it pulls Node-only config modules into runtime bundles); leave
+   the import if auth is still referenced elsewhere.
+
+Do not change behavior beyond removing the auth.invoker() indirection.
+```
+
+</details>
+
+## Tailordb → tailordb (lowercase ambient namespace)
+
+**Migration:** Partially automatic
+
+Rewrite references to the removed capital-cased `Tailordb` ambient namespace (`Tailordb.QueryResult`, `Tailordb.CommandType`, `Tailordb.Client`, `typeof Tailordb.Client`) to the lowercase `tailordb.*` namespace exposed by `@tailor-platform/sdk/runtime/globals`. Because v2 no longer activates ambient declarations automatically, each file that contains `tailordb.*` references after the rewrite must also add `import "@tailor-platform/sdk/runtime/globals"`.
+
+Before:
+
+```ts
+const command: Tailordb.CommandType = "SELECT";
+```
+
+After:
+
+```ts
+import "@tailor-platform/sdk/runtime/globals";
+const command: tailordb.CommandType = "SELECT";
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+The capital-cased Tailordb ambient namespace is removed in v2; use the lowercase
+tailordb.* namespace from @tailor-platform/sdk/runtime/globals. The codemod rewrites
+the known members (QueryResult, CommandType, Client). Rewrite any other remaining
+Tailordb.* reference to its tailordb.* equivalent (and confirm the member still
+exists on the lowercase namespace).
+Also add `import "@tailor-platform/sdk/runtime/globals"` at the top of each file
+that contains any tailordb.* type reference — v2 no longer activates ambient
+declarations automatically on SDK import.
+```
+
+</details>
+
+## executeScript arg JSON.stringify → value
+
+**Migration:** Partially automatic
+
+Unwrap `JSON.stringify(...)` passed as the `executeScript` `arg` option. In v2 `arg` takes a JSON-serializable value and is serialized internally, so a pre-stringified argument double-encodes.
+
+Before:
+
+```ts
+await executeScript({ ...opts, arg: JSON.stringify({ a: 1 }) });
+```
+
+After:
+
+```ts
+await executeScript({ ...opts, arg: { a: 1 } });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2 the executeScript() arg option takes a JSON-serializable value
+and is serialized internally, so a pre-stringified argument double-encodes. The
+codemod already rewrote the direct form arg: JSON.stringify(X) to arg: X. Review
+the executeScript calls in these files for cases it could not rewrite — where the
+arg value is reached indirectly, for example:
+- a variable holding a JSON.stringify(...) result (const s = JSON.stringify(x); ... arg: s)
+- JSON.stringify(x, null, 2) or another multi-argument form
+- an options object built or spread dynamically
+
+For each such call, pass the underlying value directly as arg (drop the
+JSON.stringify wrapper) so executeScript serializes it once. Leave calls that
+already pass a plain value unchanged.
+```
+
+</details>
+
+## openDownloadStream → downloadStream
+
+**Migration:** Manual
+
+The deprecated `openDownloadStream` file-streaming API is removed in v2. Use `downloadStream` for streamed file downloads. The generated file utilities now emit `downloadFileStream` (which calls `downloadStream` and returns `FileDownloadStreamResponse`) instead of the removed `openFileDownloadStream` helper.
+
+Before:
+
+```ts
+const res = await openDownloadStream(namespace, typeName, fieldName, recordId);
+```
+
+After:
+
+```ts
+const res = await downloadStream(namespace, typeName, fieldName, recordId);
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The openDownloadStream file-streaming API is removed in v2. Replace every call to
+openDownloadStream with downloadStream (same arguments). If you used the generated
+openFileDownloadStream helper, switch to downloadFileStream, which calls
+downloadStream and returns FileDownloadStreamResponse.
+```
+
+</details>
+
+## Ambient runtime globals are opt-in
+
+**Migration:** Manual
+
+Importing `@tailor-platform/sdk` no longer activates the ambient `tailor.*` / `tailordb.*` global declarations. Normal SDK development does not need them — use the SDK APIs and the typed wrappers from `@tailor-platform/sdk/runtime`. Only if you relied on the ambient globals directly, add `import "@tailor-platform/sdk/runtime/globals"`. (The capital-cased `Tailordb.*` namespace is removed separately — see the `Tailordb → tailordb` codemod.)
+
+Preferred: switch to the typed wrappers from `@tailor-platform/sdk/runtime` and drop the ambient globals:
+
+Before:
+
+```ts
+const client = new tailor.idp.Client();
+```
+
+After:
+
+```ts
+import { idp } from "@tailor-platform/sdk/runtime";
+const client = new idp.Client({ namespace: "my-namespace" });
+```
+
+Fallback: only if you must keep referencing the bare `tailor.*` names, opt into the global declarations:
+
+Before:
+
+```ts
+const client = new tailor.idp.Client();
+```
+
+After:
+
+```ts
+import "@tailor-platform/sdk/runtime/globals";
+const client = new tailor.idp.Client();
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The v2 SDK no longer enables ambient Tailor runtime globals from
+`@tailor-platform/sdk`. For each flagged file that uses `tailor.*`,
+`tailordb.*`, or Tailor runtime error globals, prefer migrating to the
+typed wrappers from `@tailor-platform/sdk/runtime` (e.g. replace
+`new tailor.idp.Client()` with `import { idp } from "@tailor-platform/sdk/runtime"`
+and `new idp.Client({ namespace })`). The wrappers are self-contained, so the
+ambient globals are no longer needed.
+
+Only when the file must keep referencing the bare `tailor.*` names directly,
+opt into the global declarations instead by adding one of these:
+- per-file: `import "@tailor-platform/sdk/runtime/globals";`
+- project-wide: `"types": ["@tailor-platform/sdk/runtime/globals"]` in
+  the relevant tsconfig compilerOptions
+
+Leave files unchanged when the matching name is local, imported from another
+module, or appears only in comments or strings.
+```
+
+</details>
+
+## Workflow .trigger() and trigger tests
+
+**Migration:** Manual
+
+Workflow job `.trigger()` now aligns with the platform runtime: it returns the job result directly instead of a Promise wrapper, and tests no longer run job bodies locally. Mock trigger responses with `mockWorkflow()` (`setJobHandler` / `enqueueResult`, assert via `triggeredJobs`), or use `runWorkflowLocally()` for a full-chain local run.
+
+Tests must mock the workflow runtime instead of running bodies locally:
+
+Before:
+
+```ts
+const result = await orderJob.trigger({ id });
+expect(result.status).toBe("done");
+```
+
+After:
+
+```ts
+using wf = mockWorkflow();
+wf.setJobHandler((jobName) => (jobName === "order-job" ? { status: "done" } : null));
+const result = await orderJob.trigger({ id });
+expect(result.status).toBe("done");
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+Workflow job .trigger() now uses the platform workflow runtime instead of running
+the job body locally. In tests, acquire `using wf = mockWorkflow()` and provide
+trigger responses (setJobHandler / enqueueResult), or use runWorkflowLocally() for a
+full-chain local run; an unmocked trigger now throws. Outside tests, treat the
+trigger result as the job output directly (no Promise wrapper to unwrap).
+```
+
+</details>
+
+## Behavioral changes (no migration required)
+
+These v2 changes alter runtime or CLI behavior; no source change is needed.
+
+### CLI tokens stored in the OS keyring
+
+CLI login tokens are stored in the OS keyring by default when available, falling back to the platform config file when it is not. No source change is required; re-login if you need tokens moved into the keyring.
+
+### CLI users keyed by subject ID
+
+The CLI stores human users by their stable subject ID instead of email (email is kept for display). Legacy email-keyed entries are migrated automatically on the next login or token refresh. No source change is required.
+
+### function logs require a content hash for source mapping
+
+`tailor-sdk function logs` maps stack traces against the function bundle only when the execution recorded a `contentHash`. Executions without one now show raw stack traces instead of mapped frames. No source change is required.

package/docs/runtime.md

@@ -78,7 +78,7 @@ The runtime entry re-exports the following namespaces. Detailed signatures, para
 - `idp` — IdP user management (`new Client({ namespace })`)
 - `workflow` — workflow & job control (`triggerWorkflow`, `triggerJobFunction`, `wait`, `resolve`)
 - `context` — execution context (`getInvoker`)
-- `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`, `openDownloadStream` _(deprecated)_)
+- `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`)
 
 ## Testing
 

package/docs/services/auth.md

@@ -139,18 +139,18 @@ export const user = db.type("User", {
 });
 ```
 
-The `attributeList` values are accessible via `user.attributeList` as a tuple:
+The `attributeList` values are accessible via the runtime principal's `attributeList` as a tuple:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const [organizationId, teamId] = context.user.attributeList;
+  const [organizationId, teamId] = context.caller?.attributeList ?? [];
 },
 
 // In TailorDB hooks
 .hooks({
   field: {
-    create: ({ user }) => user.attributeList[0], // First UUID from list
+    create: ({ invoker }) => invoker?.attributeList[0] ?? null, // First UUID from list
   },
 })
 ```
@@ -160,7 +160,7 @@ body: (context) => {
 When you want to use machine users without defining a `userProfile`, define `machineUserAttributes` instead. These attributes are used for:
 
 - type-safe `machineUsers[*].attributes`
-- `context.user.attributes` typing (via `tailor.d.ts`)
+- runtime principal `attributes` typing (via `tailor.d.ts`)
 
 ```typescript
 import { defineAuth, t } from "@tailor-platform/sdk";
@@ -200,12 +200,12 @@ machineUsers: {
 },
 ```
 
-**attributes**: Values for attributes enabled in `userProfile.attributes` (or all fields defined in `machineUserAttributes` when `userProfile` is omitted). All enabled fields must be set here. These values are accessible via `user.attributes`:
+**attributes**: Values for attributes enabled in `userProfile.attributes` (or all fields defined in `machineUserAttributes` when `userProfile` is omitted). All enabled fields must be set here. These values are accessible via the runtime principal's `attributes`:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const role = context.user.attributes?.role;
+  const role = context.caller?.attributes.role;
 },
 ```
 
@@ -230,25 +230,25 @@ machineUsers: {
 },
 ```
 
-These values are accessible via `user.attributeList`:
+These values are accessible via the runtime principal's `attributeList`:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const [organizationId, teamId] = context.user.attributeList;
+  const [organizationId, teamId] = context.caller?.attributeList ?? [];
 },
 
 // In TailorDB hooks
 .hooks({
   field: {
-    create: ({ user }) => user.attributes?.role === "ADMIN" ? "default" : null,
+    create: ({ invoker }) => invoker?.attributes.role === "ADMIN" ? "default" : null,
   },
 })
 
 // In TailorDB validate
 .validate({
   field: [
-    ({ user }) => user.attributes?.role === "ADMIN",
+    ({ invoker }) => invoker?.attributes.role === "ADMIN",
     "Only admins can set this field",
   ],
 })
@@ -269,7 +269,7 @@ tailor-sdk machineuser token <name>
 
 ### Specifying a machine user invoker
 
-Resolvers, executors, and `workflow.trigger()` accept an `authInvoker` option that chooses which machine user runs the operation. Pass the machine user name as a plain string — it is type-narrowed to the names you registered in `machineUsers`.
+Resolvers, executors, and `workflow.trigger()` accept an `invoker` option that chooses which machine user runs the operation. Pass the machine user name as a plain string — it is type-narrowed to the names you registered in `machineUsers`.
 
 ```typescript
 // tailor.config.ts
@@ -298,7 +298,7 @@ export default createResolver({
     // Trigger workflow with machine user permissions
     const workflowRunId = await myWorkflow.trigger(
       { id: input.id },
-      { authInvoker: "admin-machine-user" },
+      { invoker: "admin-machine-user" },
     );
     return { workflowRunId };
   },

package/docs/services/executor.md

@@ -219,7 +219,7 @@ createExecutor({
 });
 ```
 
-Executor callbacks receive the trigger args, including `env` from `defineConfig({ env })`. `function` and `jobFunction` `body` args also include an `invoker` field: the principal running this function, overridden by `authInvoker` when set; `null` for anonymous calls. Other operation kinds (`graphql`, `webhook`, `workflow`) receive `env` through their callback args but do not pass `invoker` into those callbacks.
+Executor callbacks receive the trigger args, including `env` from `defineConfig({ env })`. `function` and `jobFunction` `body` args also include an `invoker` field: the principal running this function, or the machine user configured through the operation `invoker` option; `null` for anonymous calls. Other operation kinds (`graphql`, `webhook`, `workflow`) receive `env` through their callback args but do not pass `invoker` into those callbacks.
 
 ### Job Function Operation
 
@@ -331,7 +331,7 @@ createExecutor({
 
 ### Authentication for Operations
 
-GraphQL and Workflow operations can specify an `authInvoker` to execute with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names defined in your auth config:
+GraphQL and Workflow operations can specify an `invoker` to execute with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names defined in your auth config:
 
 ```typescript
 import { createExecutor, scheduleTrigger } from "@tailor-platform/sdk";
@@ -342,7 +342,7 @@ export default createExecutor({
   operation: {
     kind: "graphql",
     query: `mutation { cleanupOldRecords { count } }`,
-    authInvoker: "batch-processor",
+    invoker: "batch-processor",
   },
 });
 ```

package/docs/services/resolver.md

@@ -208,7 +208,7 @@ Validation functions receive:
 
 - `value` - The field value being validated
 - `data` - The entire input object
-- `user` - The user performing the operation
+- `invoker` - The principal performing the operation
 
 You can specify validation as:
 
@@ -234,8 +234,8 @@ Validation runs automatically before the `body` function executes. When validati
 Define actual resolver logic in the `body` function. Function arguments include:
 
 - `input` - Input data from GraphQL request
-- `user` - The user who called this resolver; unaffected by `authInvoker`
-- `invoker` - The principal running this function; equals `user` by default, or the machine user set by `authInvoker`. `null` for anonymous calls.
+- `caller` - The user or machine user who called this resolver; unaffected by `invoker`. `null` for anonymous calls.
+- `invoker` - The principal running this function; equals `caller` by default, or the machine user configured through the resolver `invoker` option. `null` for anonymous calls.
 - `env` - Environment variables declared in `tailor.config.ts`
 
 ### Using Kysely for Database Access
@@ -352,7 +352,7 @@ createResolver({
 
 ## Authentication
 
-Specify an `authInvoker` to execute the resolver with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names you defined in your auth config:
+Specify an `invoker` to execute the resolver with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names you defined in your auth config:
 
 ```typescript
 import { createResolver, t } from "@tailor-platform/sdk";
@@ -365,10 +365,10 @@ export default createResolver({
     // Executes as "batch-processor" machine user
     return { result: "ok" };
   },
-  authInvoker: "batch-processor",
+  invoker: "batch-processor",
 });
 ```
 
 The machine user name is looked up in the auth service configured on your app (`machineUsers` in `defineAuth`). The namespace is resolved automatically — no need to import `auth` from `tailor.config.ts` in resolver files.
 
-**Note:** `authInvoker` controls the permissions for database operations and other platform actions. The `user` object passed to `body` still reflects the original caller, while `invoker` reflects the principal actually running the body.
+**Note:** The `invoker` option controls the permissions for database operations and other platform actions. The `caller` object passed to `body` still reflects the original caller, while the `invoker` body field reflects the principal actually running the body.