feat(cli): add upgrade command with @tailor-platform/sdk-codemod package

.changeset/codemod-infra-upgrade-command.md

@@ -0,0 +1,6 @@
+---
+"@tailor-platform/sdk": minor
+"@tailor-platform/sdk-codemod": patch
+---
+
+Add `upgrade` command with codemod.com-based architecture for automated SDK version migrations. Codemod execution is handled by the new `@tailor-platform/sdk-codemod` package.

CLAUDE.md

@@ -40,7 +40,7 @@ Refer to `example/` for working implementations of all patterns (config, models,
 
 Key files:
 
-- `example/tailor.config.ts` - Configuration with defineConfig, defineAuth, defineIdp, defineStaticWebSite, defineGenerators
+- `example/tailor.config.ts` - Configuration with defineConfig, defineAuth, defineIdp, defineStaticWebSite, definePlugins
 - `example/tailordb/*.ts` - Model definitions with `db.type()`
 - `example/resolvers/*.ts` - Resolver implementations with `createResolver`
 - `example/executors/*.ts` - Executor implementations with `createExecutor`
@@ -74,13 +74,12 @@ Multi-event trigger variants handle multiple events in one executor:
 
 Args include `event` (short name like `"created"`) and `rawEvent` (full event type like `"tailordb.type_record.created"`) for runtime type narrowing.
 
-### Generators
+### Plugins
 
-`defineGenerators()` takes tuples as rest arguments (see `example/tailor.config.ts`). The `@tailor-platform/kysely-type` generator (built into the SDK) is required for `getDB()` in resolvers/executors/workflows.
+`definePlugins()` takes plugin instances as rest arguments (see `example/tailor.config.ts`). The `kyselyTypePlugin` from `@tailor-platform/sdk/plugin/kysely-type` is required for `getDB()` in resolvers/executors/workflows. `defineGenerators()` is deprecated — use `definePlugins()` instead.
 
 ### Configuration
 
-- `definePlugins()` is available for reusable type/resolver/executor generation
 - Static website `.url` property is resolved at deployment time — use it in CORS and redirect URIs
 
 ## Developer Guides

packages/sdk-codemod/codemods/v2/define-generators-to-plugins/codemod.yaml

@@ -0,0 +1,7 @@
+name: "@tailor-platform/define-generators-to-plugins"
+version: "1.0.0"
+description: "Migrate defineGenerators() tuple syntax to definePlugins() with explicit plugin imports"
+engine: jssg
+language: typescript
+since: "1.0.0"
+until: "2.0.0"

packages/sdk-codemod/codemods/v2/define-generators-to-plugins/scripts/transform.ts

@@ -0,0 +1,217 @@
+import { parse, Lang } from "@ast-grep/napi";
+import type { Edit, SgNode } from "@ast-grep/napi";
+
+/**
+ * Known plugin mappings from package name to plugin function/import.
+ */
+const PLUGIN_MAP: Record<string, { functionName: string; importPath: string }> = {
+  "@tailor-platform/kysely-type": {
+    functionName: "kyselyTypePlugin",
+    importPath: "@tailor-platform/sdk/plugin/kysely-type",
+  },
+  "@tailor-platform/seed": {
+    functionName: "seedPlugin",
+    importPath: "@tailor-platform/sdk/plugin/seed",
+  },
+  "@tailor-platform/enum-constants": {
+    functionName: "enumConstantsPlugin",
+    importPath: "@tailor-platform/sdk/plugin/enum-constants",
+  },
+  "@tailor-platform/file-utils": {
+    functionName: "fileUtilsPlugin",
+    importPath: "@tailor-platform/sdk/plugin/file-utils",
+  },
+};
+
+/**
+ * Transform defineGenerators() to definePlugins():
+ *
+ * 1. Rename `defineGenerators` → `definePlugins` in import and call
+ * 2. Transform tuple arguments `["pkg-name", config]` → `pluginFn(config)`
+ * 3. Add plugin imports from their respective SDK paths
+ * @param source - Source code to transform
+ * @returns Transformed source or null if no changes needed
+ */
+export default function transform(source: string): string | null {
+  const tree = parse(Lang.TypeScript, source).root();
+
+  // Only process files that import defineGenerators from the SDK.
+  // This prevents modifying unrelated files that happen to contain the identifier.
+  if (!source.includes("defineGenerators")) {
+    return null;
+  }
+  if (!source.includes("@tailor-platform/sdk")) {
+    return null;
+  }
+
+  const edits: Edit[] = [];
+  const importsToAdd: Map<string, string> = new Map(); // importPath -> functionName
+
+  // Step 1: Find and transform defineGenerators call arguments (tuples → plugin calls)
+  const callNodes = tree.findAll({
+    rule: {
+      pattern: "defineGenerators($$$ARGS)",
+    },
+  });
+
+  let totalArgs = 0;
+  let migratedArgs = 0;
+
+  for (const callNode of callNodes) {
+    // Find array/tuple arguments inside the call
+    const args = callNode.getMultipleMatches("ARGS");
+    for (const arg of args) {
+      if (!arg.isNamed() || arg.kind() === "comment") continue;
+      totalArgs++;
+
+      // Match tuple pattern: ["package-name", config]
+      if (arg.kind() === "array") {
+        const children = arg
+          .children()
+          .filter((c: SgNode) => c.isNamed() && c.kind() !== "comment");
+        if (children.length >= 1) {
+          const packageNameNode = children[0]!;
+          const packageName = packageNameNode.text().replace(/^["']|["']$/g, "");
+          const mapping = PLUGIN_MAP[packageName];
+
+          if (mapping) {
+            migratedArgs++;
+            importsToAdd.set(mapping.importPath, mapping.functionName);
+            // Build replacement: pluginFn(config) or pluginFn() if no config
+            const configNodes = children.slice(1);
+            const configText =
+              configNodes.length > 0 ? configNodes.map((c: SgNode) => c.text()).join(", ") : "";
+            const replacement = `${mapping.functionName}(${configText})`;
+            edits.push(arg.replace(replacement));
+          }
+        }
+      }
+    }
+  }
+
+  // If any arguments could not be migrated, skip the entire transform to avoid
+  // producing invalid code (e.g. mixing tuple syntax with plugin calls).
+  if (totalArgs > 0 && migratedArgs < totalArgs) {
+    return null;
+  }
+
+  // Step 2: Rename defineGenerators → definePlugins in call expressions only.
+  // Import specifiers are handled separately in step 3 to avoid duplicates.
+  const callIdentifiers = tree.findAll({
+    rule: {
+      pattern: "defineGenerators",
+      kind: "identifier",
+      inside: {
+        kind: "call_expression",
+      },
+    },
+  });
+
+  for (const id of callIdentifiers) {
+    edits.push(id.replace("definePlugins"));
+  }
+
+  // Step 3: Handle import specifier for defineGenerators.
+  // If the import already contains definePlugins (mixed config), remove the
+  // defineGenerators specifier instead of renaming it to avoid duplicates.
+  const sdkImportStatements = tree.findAll({
+    rule: {
+      kind: "import_statement",
+      has: {
+        kind: "string",
+        regex: "^[\"']@tailor-platform/sdk[\"']$",
+      },
+    },
+  });
+
+  // Check across ALL SDK import statements whether definePlugins is already
+  // imported (may be in a different statement than defineGenerators).
+  const hasDefinePlugins = sdkImportStatements.some((stmt) =>
+    stmt
+      .findAll({ rule: { kind: "import_specifier" } })
+      .some((s) =>
+        s.children().some((c: SgNode) => c.kind() === "identifier" && c.text() === "definePlugins"),
+      ),
+  );
+
+  for (const importStmt of sdkImportStatements) {
+    const specifiers = importStmt.findAll({
+      rule: { kind: "import_specifier" },
+    });
+
+    for (const spec of specifiers) {
+      const identNode = spec
+        .children()
+        .find((c: SgNode) => c.kind() === "identifier" && c.text() === "defineGenerators");
+      if (!identNode) continue;
+
+      if (hasDefinePlugins) {
+        // Remove the entire specifier (including trailing/leading comma+whitespace)
+        // by replacing the specifier text + any adjacent comma
+        const specText = spec.text();
+        const importText = importStmt.text();
+        const idx = importText.indexOf(specText);
+        if (idx !== -1) {
+          // Check for trailing comma+whitespace or leading comma+whitespace
+          const afterSpec = importText.slice(idx + specText.length);
+          const beforeSpec = importText.slice(0, idx);
+          let removeFrom = idx;
+          let removeTo = idx + specText.length;
+
+          if (afterSpec.match(/^\s*,/)) {
+            removeTo = idx + specText.length + (afterSpec.match(/^\s*,\s*/)![0]?.length ?? 0);
+          } else if (beforeSpec.match(/,\s*$/)) {
+            removeFrom = idx - (beforeSpec.match(/,\s*$/)![0]?.length ?? 0);
+          }
+
+          const cleaned = importText.slice(0, removeFrom) + importText.slice(removeTo);
+          edits.push(importStmt.replace(cleaned));
+        }
+      } else {
+        edits.push(identNode.replace("definePlugins"));
+      }
+    }
+  }
+
+  if (edits.length === 0) {
+    return null;
+  }
+
+  // Apply all edits
+  let result = tree.commitEdits(edits);
+
+  // Step 4: Add new import statements for plugin functions (skip already-present ones)
+  if (importsToAdd.size > 0) {
+    const importLines: string[] = [];
+    for (const [importPath, functionName] of importsToAdd) {
+      const line = `import { ${functionName} } from "${importPath}";`;
+      // Skip if this function is already imported (mixed config scenario).
+      // Use a targeted regex to match import statements containing the function
+      // name, rather than checking the import path which could match unrelated
+      // imports from the same module (e.g. importing a different symbol).
+      const importExists = new RegExp(`import\\s*\\{[^}]*\\b${functionName}\\b[^}]*\\}`, "m").test(
+        result,
+      );
+      if (importExists) continue;
+      importLines.push(line);
+    }
+    // Sort for deterministic output and skip if all imports already present
+    importLines.sort();
+    if (importLines.length === 0) {
+      return result;
+    }
+
+    // Find insertion point: after the @tailor-platform/sdk import line
+    const sdkImportRegex = /^(import\s+.*from\s+["']@tailor-platform\/sdk["'];?)$/m;
+    const match = sdkImportRegex.exec(result);
+    if (match) {
+      const insertPos = (match.index ?? 0) + match[0].length;
+      result = result.slice(0, insertPos) + "\n" + importLines.join("\n") + result.slice(insertPos);
+    } else {
+      // Fallback: prepend imports at the top of the file
+      result = importLines.join("\n") + "\n" + result;
+    }
+  }
+
+  return result;
+}

packages/sdk-codemod/codemods/v2/define-generators-to-plugins/tests/basic/expected.ts

@@ -0,0 +1,15 @@
+import * as path from "node:path";
+import * as url from "node:url";
+import { definePlugins } from "@tailor-platform/sdk";
+import { enumConstantsPlugin } from "@tailor-platform/sdk/plugin/enum-constants";
+import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
+import config from "./tailor.config";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const outDir = path.join(__dirname, "generators-compat-out");
+
+export default config;
+export const generators = definePlugins(
+  kyselyTypePlugin({ distPath: path.join(outDir, "db.ts") }),
+  enumConstantsPlugin({ distPath: path.join(outDir, "enums.ts") }),
+);

packages/sdk-codemod/codemods/v2/define-generators-to-plugins/tests/basic/input.ts

@@ -0,0 +1,13 @@
+import * as path from "node:path";
+import * as url from "node:url";
+import { defineGenerators } from "@tailor-platform/sdk";
+import config from "./tailor.config";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const outDir = path.join(__dirname, "generators-compat-out");
+
+export default config;
+export const generators = defineGenerators(
+  ["@tailor-platform/kysely-type", { distPath: path.join(outDir, "db.ts") }],
+  ["@tailor-platform/enum-constants", { distPath: path.join(outDir, "enums.ts") }],
+);

packages/sdk-codemod/eslint.config.js

@@ -0,0 +1,11 @@
+import eslint from "@eslint/js";
+import { defineConfig, globalIgnores } from "eslint/config";
+import oxlint from "eslint-plugin-oxlint";
+import tseslint from "typescript-eslint";
+
+export default defineConfig([
+  globalIgnores(["dist/", "codemods/"]),
+  eslint.configs.recommended,
+  tseslint.configs.recommended,
+  ...oxlint.configs["flat/recommended"],
+]);

packages/sdk-codemod/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tailor-platform/sdk-codemod",
+  "version": "0.1.0",
+  "description": "Codemod runner for Tailor Platform SDK upgrades",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tailor-platform/sdk.git",
+    "directory": "packages/sdk-codemod"
+  },
+  "bin": "dist/index.js",
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsdown",
+    "lint": "oxlint . && eslint --cache .",
+    "lint:fix": "oxlint --fix . && eslint --cache --fix .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "prepublish": "pnpm run build",
+    "publint": "publint --strict"
+  },
+  "dependencies": {
+    "@ast-grep/napi": "^0.42.0",
+    "chalk": "5.6.2",
+    "diff": "8.0.4",
+    "pathe": "2.0.3",
+    "picomatch": "4.0.4",
+    "pkg-types": "2.3.0",
+    "politty": "0.4.13",
+    "semver": "7.7.4",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "24.12.2",
+    "@types/picomatch": "4.0.2",
+    "@types/semver": "7.7.1",
+    "eslint": "10.2.0",
+    "eslint-plugin-oxlint": "1.58.0",
+    "oxlint": "1.58.0",
+    "tsdown": "0.21.7",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.58.0",
+    "vitest": "4.1.2"
+  }
+}

packages/sdk-codemod/src/helpers.ts

@@ -0,0 +1,22 @@
+import { parse, Lang } from "@ast-grep/napi";
+import type { SgRoot } from "@ast-grep/napi";
+
+/**
+ * Parse TypeScript source code into an ast-grep root.
+ * @param source - TypeScript source code
+ * @returns Parsed AST root
+ */
+export function parseTS(source: string): SgRoot {
+  return parse(Lang.TypeScript, source);
+}
+
+/**
+ * Parse TSX source code into an ast-grep root.
+ * @param source - TSX source code
+ * @returns Parsed AST root
+ */
+export function parseTSX(source: string): SgRoot {
+  return parse(Lang.Tsx, source);
+}
+
+export type { SgRoot, SgNode, Edit } from "@ast-grep/napi";