@tailor-platform/sdk-codemod 0.3.0-next.0 → 0.3.0-next.2

package/dist/index.js

@@ -7,12 +7,29 @@ import { arg, defineCommand, runMain } from "politty";
 import { z } from "zod";
 import { gte, lt, valid } from "semver";
 import * as fs from "node:fs";
-import { glob } from "node:fs/promises";
+import { Lang, parse } from "@ast-grep/napi";
 import chalk from "chalk";
 import { structuredPatch } from "diff";
 import picomatch from "picomatch";
+//#region src/migration-doc.ts
+/**
+* Classify how much of a migration the codemod automates.
+* - `Automatic`: a transform fully covers it, with no residual to flag.
+* - `Partially automatic`: a transform covers the common cases but flags
+*   residuals (via `legacyPatterns`/`suspiciousPatterns`/`prompt`) to finish.
+* - `Manual`: no transform; the change is migrated by hand (optionally guided
+*   by a `prompt`). Whether a person or an LLM does it does not matter here.
+* @param codemod - The codemod registry entry
+* @returns The automation level
+*/
+function automationLevel(codemod) {
+	if (!codemod.scriptPath) return "Manual";
+	return (codemod.legacyPatterns?.length ?? 0) > 0 || (codemod.suspiciousPatterns?.length ?? 0) > 0 || codemod.prompt != null ? "Partially automatic" : "Automatic";
+}
+//#endregion
 //#region src/registry.ts
 const CODEMODS_ROOT = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), "codemods");
+/** All registered codemods, in registration order. */
 const allCodemods = [
 	{
 		id: "v2/define-generators-to-plugins",
@@ -21,7 +38,29 @@ const allCodemods = [
 		since: "1.0.0",
 		until: "2.0.0",
 		scriptPath: "v2/define-generators-to-plugins/scripts/transform.js",
-		legacyPatterns: ["defineGenerators"]
+		legacyPatterns: ["defineGenerators"],
+		examples: [{
+			before: [
+				"import { defineGenerators } from \"@tailor-platform/sdk\";",
+				"",
+				"export const generators = defineGenerators(",
+				"  [\"@tailor-platform/kysely-type\", { distPath: \"db.ts\" }],",
+				");"
+			].join("\n"),
+			after: [
+				"import { definePlugins } from \"@tailor-platform/sdk\";",
+				"import { kyselyTypePlugin } from \"@tailor-platform/sdk/plugin/kysely-type\";",
+				"",
+				"export const generators = definePlugins(kyselyTypePlugin({ distPath: \"db.ts\" }));"
+			].join("\n")
+		}],
+		prompt: [
+			"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."
+		].join("\n")
 	},
 	{
 		id: "v2/plugin-cli-import",
@@ -29,7 +68,11 @@ const allCodemods = [
 		description: "Rewrite deprecated plugin re-export imports (kyselyTypePlugin, enumConstantsPlugin, fileUtilsPlugin, seedPlugin) from `@tailor-platform/sdk/cli` to their dedicated plugin subpaths",
 		since: "1.0.0",
 		until: "2.0.0",
-		scriptPath: "v2/plugin-cli-import/scripts/transform.js"
+		scriptPath: "v2/plugin-cli-import/scripts/transform.js",
+		examples: [{
+			before: "import { kyselyTypePlugin } from \"@tailor-platform/sdk/cli\";",
+			after: "import { kyselyTypePlugin } from \"@tailor-platform/sdk/plugin/kysely-type\";"
+		}]
 	},
 	{
 		id: "v2/test-run-arg-input",
@@ -42,7 +85,12 @@ const allCodemods = [
 			"**/package.json",
 			"**/*.{sh,bash,zsh}",
 			"**/*.md"
-		]
+		],
+		examples: [{
+			lang: "sh",
+			before: "tailor-sdk function test-run resolvers/add.ts --arg '{\"input\":{\"a\":1}}'",
+			after: "tailor-sdk function test-run resolvers/add.ts --arg '{\"a\":1}'"
+		}]
 	},
 	{
 		id: "v2/sdk-skills-shim",
@@ -56,39 +104,87 @@ const allCodemods = [
 			"**/*.{sh,bash,zsh,yml,yaml}",
 			"**/*.md"
 		],
-		legacyPatterns: ["tailor-sdk-skills"]
+		legacyPatterns: ["tailor-sdk-skills"],
+		examples: [{
+			lang: "sh",
+			before: "npx tailor-sdk-skills",
+			after: "tailor-sdk skills install"
+		}],
+		prompt: [
+			"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`."
+		].join("\n")
 	},
 	{
 		id: "v2/principal-unify",
-		name: "Unify TailorUser/TailorActor/TailorInvoker → TailorPrincipal",
-		description: "Rename TailorUser/TailorActor/TailorInvoker to TailorPrincipal, drop unauthenticatedTailorUser, and rename resolver body `user` to `caller`",
+		name: "Unify TailorUser/TailorActor/TailorActorType/TailorInvoker → TailorPrincipal",
+		description: "Rename TailorUser/TailorActor/TailorActorType/TailorInvoker to TailorPrincipal, drop unauthenticatedTailorUser, rename resolver body `user` to `caller`, and rename TailorDB callback `user` to `invoker`",
 		since: "1.0.0",
 		until: "2.0.0",
 		scriptPath: "v2/principal-unify/scripts/transform.js",
 		legacyPatterns: [
 			"TailorUser",
 			"TailorActor",
+			"TailorActorType",
 			"TailorInvoker",
 			"unauthenticatedTailorUser"
-		]
+		],
+		suspiciousPatterns: [
+			"caller?.",
+			"context.user",
+			"context.invoker ?? context.user",
+			"ResolverContext"
+		],
+		examples: [{
+			caption: "Type references unify under `TailorPrincipal`:",
+			before: "import type { TailorUser } from \"@tailor-platform/sdk\";",
+			after: "import type { TailorPrincipal } from \"@tailor-platform/sdk\";"
+		}, {
+			caption: "The resolver body `user` becomes `caller`:",
+			before: "body: ({ input, user }) => user.id,",
+			after: "body: ({ input, caller }) => caller.id,"
+		}],
+		prompt: [
+			"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."
+		].join("\n")
 	},
 	{
 		id: "v2/apply-to-deploy",
 		name: "tailor-sdk apply → tailor-sdk deploy",
-		description: "Rewrite `tailor-sdk apply` invocations in package.json scripts, shell scripts, CI configs, and docs to the v2-recommended `tailor-sdk deploy` alias",
+		description: "Rewrite `tailor-sdk apply` invocations in package.json scripts, shell scripts, CI configs, and docs to the canonical v2 `tailor-sdk deploy` command",
 		since: "1.0.0",
 		until: "2.0.0",
 		scriptPath: "v2/apply-to-deploy/scripts/transform.js",
 		filePatterns: [
 			"**/package.json",
 			"**/*.{sh,bash,zsh,yml,yaml}",
+			"**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
 			"**/*.md"
-		]
+		],
+		examples: [{
+			lang: "sh",
+			before: "tailor-sdk apply --profile prod",
+			after: "tailor-sdk deploy --profile prod"
+		}]
 	},
 	{
 		id: "v2/cli-rename",
-		name: "v2 CLI rename (single-word commands)",
-		description: "Rewrite `tailor-sdk crash-report` invocations to the v2 single-word `tailor-sdk crashreport` form across package.json scripts, shell scripts, CI configs, and docs",
+		name: "v2 CLI rename",
+		description: "Rewrite `tailor-sdk crash-report` to `tailor-sdk crashreport` and `--machineuser` to `--machine-user` across package.json scripts, shell scripts, CI configs, and docs",
 		since: "1.0.0",
 		until: "2.0.0",
 		scriptPath: "v2/cli-rename/scripts/transform.js",
@@ -96,25 +192,236 @@ const allCodemods = [
 			"**/package.json",
 			"**/*.{sh,bash,zsh,yml,yaml}",
 			"**/*.md"
-		]
+		],
+		legacyPatterns: ["tailor-sdk crash-report", "--machineuser"],
+		examples: [{
+			lang: "sh",
+			before: "tailor-sdk crash-report list\ntailor-sdk login --machineuser",
+			after: "tailor-sdk crashreport list\ntailor-sdk login --machine-user"
+		}],
+		prompt: [
+			"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."
+		].join("\n")
 	},
 	{
 		id: "v2/auth-invoker-unwrap",
-		name: "auth.invoker(\"name\") → \"name\"",
-		description: "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.",
+		name: "auth.invoker(\"name\") → invoker: \"name\"",
+		description: "Rename statically identified SDK `authInvoker` options to `invoker`, replace `auth.invoker(\"name\")` there with the bare `\"name\"` string, and drop the `auth` import when no other reference remains. Ambiguous workflow `.trigger()` calls are left for manual review. The `auth.invoker()` helper is removed in v2 because importing `auth` from `tailor.config.ts` into runtime files pulls Node-only modules into the bundle.",
 		since: "1.0.0",
 		until: "2.0.0",
 		scriptPath: "v2/auth-invoker-unwrap/scripts/transform.js",
-		legacyPatterns: ["auth.invoker"]
+		suspiciousPatterns: [
+			"auth.invoker",
+			"authInvoker:",
+			"authInvoker :",
+			"authInvoker?",
+			"{ authInvoker",
+			", authInvoker",
+			"\n  authInvoker",
+			"\n    authInvoker",
+			"\n      authInvoker",
+			"\"authInvoker\":",
+			"\"authInvoker\" :",
+			"\"authInvoker\"?",
+			"'authInvoker':",
+			"'authInvoker' :",
+			"'authInvoker'?"
+		],
+		prompt: [
+			"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",
+			"statically identified SDK option form authInvoker: auth.invoker(\"name\") to invoker: \"name\" and renamed supported authInvoker option keys. These files still contain",
+			"auth.invoker(...) calls or authInvoker keys that need manual review.",
+			"",
+			"For each remaining auth.invoker(<expr>) call:",
+			"1. Replace the whole call with <expr> only where the target option expects a",
+			"   machine user name string; platform/runtime authInvoker payloads still expect",
+			"   the object form.",
+			"2. Rename remaining authInvoker option keys to invoker only for SDK resolver,",
+			"   executor, workflow.trigger(), or startWorkflow() options. Keep platform/runtime",
+			"   payload keys such as tailor.workflow.triggerWorkflow(..., { authInvoker: ... }).",
+			"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 the SDK option rename and auth.invoker() removal."
+		].join("\n"),
+		examples: [{
+			before: "createResolver({ invoker: auth.invoker(\"manager\") });",
+			after: "createResolver({ invoker: \"manager\" });"
+		}]
 	},
 	{
 		id: "v2/tailordb-namespace",
 		name: "Tailordb → tailordb (lowercase ambient namespace)",
-		description: "Rewrite references to the deprecated capital-cased `Tailordb` ambient namespace (`Tailordb.QueryResult`, `Tailordb.CommandType`, `Tailordb.Client`, `typeof Tailordb.Client`) to the new lowercase `tailordb.*` namespace re-published by the SDK in place of `@tailor-platform/function-types`.",
+		description: "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\"`.",
 		since: "1.0.0",
 		until: "2.0.0",
 		scriptPath: "v2/tailordb-namespace/scripts/transform.js",
-		legacyPatterns: ["Tailordb."]
+		legacyPatterns: ["Tailordb."],
+		examples: [{
+			before: "const command: Tailordb.CommandType = \"SELECT\";",
+			after: "import \"@tailor-platform/sdk/runtime/globals\";\nconst command: tailordb.CommandType = \"SELECT\";"
+		}],
+		prompt: [
+			"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."
+		].join("\n")
+	},
+	{
+		id: "v2/execute-script-arg",
+		name: "executeScript arg JSON.stringify → value",
+		description: "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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/execute-script-arg/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,mjs,cjs,js}"],
+		suspiciousPatterns: [[
+			"executeScript",
+			"JSON.stringify",
+			/\barg\s*[:=]|["']arg["']\s*(?::|\]\s*[:=])/
+		]],
+		prompt: [
+			"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."
+		].join("\n"),
+		examples: [{
+			before: "await executeScript({ ...opts, arg: JSON.stringify({ a: 1 }) });",
+			after: "await executeScript({ ...opts, arg: { a: 1 } });"
+		}]
+	},
+	{
+		id: "v2/open-download-stream",
+		name: "openDownloadStream → downloadStream",
+		description: "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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,mjs,cjs,js}"],
+		suspiciousPatterns: ["openDownloadStream", "openFileDownloadStream"],
+		examples: [{
+			before: "const res = await openDownloadStream(namespace, typeName, fieldName, recordId);",
+			after: "const res = await downloadStream(namespace, typeName, fieldName, recordId);"
+		}],
+		prompt: [
+			"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."
+		].join("\n")
+	},
+	{
+		id: "v2/runtime-globals-opt-in",
+		name: "Ambient runtime globals are opt-in",
+		description: "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.)",
+		since: "1.0.0",
+		until: "2.0.0",
+		filePatterns: ["**/*.{ts,tsx,mts,cts}"],
+		suspiciousPatterns: [
+			"tailor.context",
+			"tailor.iconv",
+			"tailor.idp",
+			"tailor.workflow",
+			"tailor[",
+			"tailordb.Client",
+			"tailordb.CommandType",
+			"tailordb.QueryResult",
+			"tailordb.file",
+			"tailordb[",
+			"TailorDBFileError",
+			"TailorErrorItem",
+			"TailorErrorMessage",
+			"TailorErrors"
+		],
+		examples: [{
+			caption: "Preferred: switch to the typed wrappers from `@tailor-platform/sdk/runtime` and drop the ambient globals:",
+			before: "const client = new tailor.idp.Client();",
+			after: "import { idp } from \"@tailor-platform/sdk/runtime\";\nconst client = new idp.Client({ namespace: \"my-namespace\" });"
+		}, {
+			caption: "Fallback: only if you must keep referencing the bare `tailor.*` names, opt into the global declarations:",
+			before: "const client = new tailor.idp.Client();",
+			after: "import \"@tailor-platform/sdk/runtime/globals\";\nconst client = new tailor.idp.Client();"
+		}],
+		prompt: [
+			"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."
+		].join("\n")
+	},
+	{
+		id: "v2/workflow-trigger-dispatch",
+		name: "Workflow .trigger() and trigger tests",
+		description: "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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		suspiciousPatterns: [".trigger("],
+		examples: [{
+			caption: "Tests must mock the workflow runtime instead of running bodies locally:",
+			before: "const result = await orderJob.trigger({ id });\nexpect(result.status).toBe(\"done\");",
+			after: "using wf = mockWorkflow();\nwf.setJobHandler((jobName) => (jobName === \"order-job\" ? { status: \"done\" } : null));\nconst result = await orderJob.trigger({ id });\nexpect(result.status).toBe(\"done\");"
+		}],
+		prompt: [
+			"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)."
+		].join("\n")
+	},
+	{
+		id: "v2/cli-token-keyring-storage",
+		name: "CLI tokens stored in the OS keyring",
+		description: "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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		notice: true
+	},
+	{
+		id: "v2/cli-users-by-subject",
+		name: "CLI users keyed by subject ID",
+		description: "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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		notice: true
+	},
+	{
+		id: "v2/function-logs-content-hash",
+		name: "function logs require a content hash for source mapping",
+		description: "`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.",
+		since: "1.0.0",
+		until: "2.0.0",
+		notice: true
 	}
 ];
 /**
@@ -147,6 +454,44 @@ const EXCLUDE_DIRS = new Set([
 	"dist",
 	".git"
 ]);
+const ALLOWED_DOT_DIRS = new Set([".github", ".circleci"]);
+const SOURCE_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs"
+]);
+const MASKED_SOURCE_NODE_KINDS = new Set([
+	"comment",
+	"string",
+	"regex",
+	"string_fragment"
+]);
+function shouldSkipDirectory(name) {
+	return EXCLUDE_DIRS.has(name) || name.startsWith(".") && !ALLOWED_DOT_DIRS.has(name);
+}
+async function* walkFiles(root, relativeDir = "") {
+	const absoluteDir = path.join(root, relativeDir);
+	let entries;
+	try {
+		entries = await fs.promises.readdir(absoluteDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const relative = relativeDir ? path.join(relativeDir, entry.name) : entry.name;
+		if (entry.isDirectory()) {
+			if (shouldSkipDirectory(entry.name)) continue;
+			yield* walkFiles(root, relative);
+			continue;
+		}
+		if (entry.isFile()) yield relative;
+	}
+}
 /**
 * Print a colorized unified diff for a single file to stderr.
 * @param filePath - Absolute path to the file
@@ -176,6 +521,73 @@ async function loadTransform(scriptPath) {
 	if (typeof mod.default !== "function") throw new Error(`Transform at ${scriptPath} does not have a default export function`);
 	return mod.default;
 }
+function contentForResidualMatching(relative, content) {
+	const ext = path.extname(relative).toLowerCase();
+	return SOURCE_EXTENSIONS.has(ext) ? maskSourceNonCode(relative, content) : content;
+}
+function sourceLang(relative) {
+	const ext = path.extname(relative).toLowerCase();
+	return ext === ".tsx" || ext === ".jsx" ? Lang.Tsx : Lang.TypeScript;
+}
+function collectMaskedRanges(root) {
+	const ranges = [];
+	const visit = (node) => {
+		if (MASKED_SOURCE_NODE_KINDS.has(node.kind())) {
+			const range = node.range();
+			ranges.push([range.start.index, range.end.index]);
+			return;
+		}
+		for (const child of node.children()) visit(child);
+	};
+	visit(root);
+	return ranges;
+}
+function maskSourceNonCode(relative, content) {
+	let ranges;
+	try {
+		ranges = collectMaskedRanges(parse(sourceLang(relative), content).root());
+	} catch {
+		return content;
+	}
+	ranges = ranges.toSorted(([a], [b]) => a - b);
+	const chars = content.split("");
+	for (const [start, end] of ranges) for (let i = start; i < end && i < chars.length; i++) if (chars[i] !== "\n" && chars[i] !== "\r") chars[i] = " ";
+	return chars.join("");
+}
+function isIdentifierChar(char) {
+	return char != null && /^[A-Za-z0-9_$]$/.test(char);
+}
+function matchesPattern(content, pattern) {
+	if (typeof pattern === "string") {
+		const checkLeft = isIdentifierChar(pattern[0]);
+		const checkRight = isIdentifierChar(pattern.at(-1));
+		let index = content.indexOf(pattern);
+		while (index !== -1) {
+			const before = index > 0 ? content[index - 1] : void 0;
+			const after = content[index + pattern.length];
+			if ((!checkLeft || !isIdentifierChar(before)) && (!checkRight || !isIdentifierChar(after))) return true;
+			index = content.indexOf(pattern, index + 1);
+		}
+		return false;
+	}
+	pattern.lastIndex = 0;
+	return pattern.test(content);
+}
+function patternLabel(pattern) {
+	return typeof pattern === "string" ? pattern : pattern.toString();
+}
+/** Resolve a residual pattern against content, returning its label when matched. */
+function matchResidualPattern(content, pattern) {
+	if (!Array.isArray(pattern)) return matchesPattern(content, pattern) ? patternLabel(pattern) : null;
+	return pattern.every((p) => matchesPattern(content, p)) ? pattern.map((p) => patternLabel(p)).join(" + ") : null;
+}
+function legacyPatternWarnings(relative, content, transforms) {
+	return transforms.flatMap((lt) => {
+		const found = lt.legacyPatterns.map((p) => matchResidualPattern(content, p)).filter((label) => label !== null);
+		if (found.length === 0) return [];
+		return [`${relative}: contains ${found.join(", ")} but was not migrated automatically (rule: ${lt.id}). Manual migration may be needed.`];
+	});
+}
 /**
 * Run multiple codemods on a project directory using in-memory chaining.
 * Each file is processed through all transforms whose filePatterns match it.
@@ -193,24 +605,24 @@ async function runCodemods(codemods, targetPath, dryRun) {
 		const patterns = codemod.filePatterns ?? DEFAULT_FILE_PATTERNS;
 		loaded.push({
 			id: codemod.id,
-			transform: await loadTransform(scriptPath),
-			matches: picomatch(patterns),
-			legacyPatterns: codemod.legacyPatterns ?? []
+			transform: scriptPath ? await loadTransform(scriptPath) : void 0,
+			matches: picomatch(patterns, { dot: true }),
+			legacyPatterns: codemod.legacyPatterns ?? [],
+			suspiciousPatterns: codemod.suspiciousPatterns ?? [],
+			prompt: codemod.prompt
 		});
 	}
-	const allPatterns = /* @__PURE__ */ new Set();
-	for (const { codemod } of codemods) for (const p of codemod.filePatterns ?? DEFAULT_FILE_PATTERNS) allPatterns.add(p);
 	const filesModified = [];
 	const warnings = [];
 	const appliedCodemodIds = /* @__PURE__ */ new Set();
 	const seen = /* @__PURE__ */ new Set();
-	for (const pattern of allPatterns) for await (const relative of glob(pattern, {
-		cwd: targetPath,
-		exclude: (name) => EXCLUDE_DIRS.has(name)
-	})) {
+	const suspiciousByCodemod = /* @__PURE__ */ new Map();
+	for await (const relative of walkFiles(targetPath)) {
 		const absolute = path.resolve(targetPath, relative);
 		if (seen.has(absolute)) continue;
 		seen.add(absolute);
+		const matchedTransforms = loaded.filter((lt) => lt.matches(relative));
+		if (matchedTransforms.length === 0) continue;
 		let original;
 		try {
 			original = await fs.promises.readFile(absolute, "utf-8");
@@ -218,10 +630,8 @@ async function runCodemods(codemods, targetPath, dryRun) {
 			continue;
 		}
 		let current = original;
-		const matchedTransforms = [];
-		for (const lt of loaded) {
-			if (!lt.matches(relative)) continue;
-			matchedTransforms.push(lt);
+		for (const lt of matchedTransforms) {
+			if (!lt.transform) continue;
 			const result = await lt.transform(current, absolute);
 			if (result != null) {
 				current = result;
@@ -232,24 +642,95 @@ async function runCodemods(codemods, targetPath, dryRun) {
 			filesModified.push(absolute);
 			if (dryRun) printDiff(absolute, original, current);
 			else await fs.promises.writeFile(absolute, current, "utf-8");
-		} else for (const lt of matchedTransforms) {
-			const found = lt.legacyPatterns.filter((p) => original.includes(p));
-			if (found.length > 0) warnings.push(`${relative}: contains ${found.join(", ")} but was not migrated automatically (rule: ${lt.id}). Manual migration may be needed.`);
+		}
+		const residualContent = contentForResidualMatching(relative, current);
+		warnings.push(...legacyPatternWarnings(relative, residualContent, matchedTransforms));
+		for (const lt of matchedTransforms) {
+			if (!lt.prompt || lt.suspiciousPatterns.length === 0) continue;
+			if (lt.suspiciousPatterns.some((p) => matchResidualPattern(residualContent, p) !== null)) {
+				const files = suspiciousByCodemod.get(lt.id) ?? [];
+				files.push(relative);
+				suspiciousByCodemod.set(lt.id, files);
+			}
 		}
 	}
+	const llmReviews = [];
+	for (const lt of loaded) {
+		if (!lt.prompt) continue;
+		if (lt.suspiciousPatterns.length > 0) {
+			const files = suspiciousByCodemod.get(lt.id);
+			if (files) llmReviews.push({
+				codemodId: lt.id,
+				prompt: lt.prompt,
+				files: files.toSorted()
+			});
+		} else if (lt.legacyPatterns.length === 0) llmReviews.push({
+			codemodId: lt.id,
+			prompt: lt.prompt,
+			files: []
+		});
+	}
 	return {
 		changed: filesModified.length > 0,
 		filesModified,
 		warnings,
-		appliedCodemodIds
+		appliedCodemodIds,
+		llmReviews
 	};
 }
 //#endregion
 //#region src/index.ts
 const packageJson = await readPackageJSON(path.dirname(fileURLToPath(import.meta.url)) + "/..");
+const listCommand = defineCommand({
+	name: "list",
+	description: "List the available codemod rules (id, name, kind, version range).",
+	args: z.object({}).strict(),
+	run: () => {
+		const rules = allCodemods.map((codemod) => ({
+			id: codemod.id,
+			name: codemod.name,
+			kind: codemod.notice ? "Notice" : automationLevel(codemod),
+			since: codemod.since,
+			until: codemod.until
+		}));
+		for (const rule of rules) process.stderr.write(`  ${rule.id}  [${rule.kind}]  ${rule.name}\n`);
+		process.stdout.write(JSON.stringify(rules) + "\n");
+	}
+});
+/**
+* Print an LLM-assisted review task to stderr: the flagged files plus the
+* codemod's migration prompt, ready to hand to an LLM for the cases the
+* deterministic transform could not complete on its own.
+* @param review - The review task (codemod id, prompt, files)
+*/
+function printLlmReview(review) {
+	const scope = review.files.length > 0 ? "the codemod cannot safely migrate these automatically" : "review the project for this manual change";
+	process.stderr.write(`\n🤖 LLM-assisted review suggested (${review.codemodId}) — ${scope}:\n`);
+	for (const file of review.files) process.stderr.write(`  - ${file}\n`);
+	process.stderr.write(`\nPrompt for an LLM:\n${review.prompt.trim()}\n`);
+}
 runMain(defineCommand({
 	name: packageJson.name ?? "sdk-codemod",
 	description: packageJson.description ?? "Codemod runner for Tailor Platform SDK upgrades",
+	subCommands: { list: listCommand },
+	notes: `Applies the codemods matching the \`--from\`/\`--to\` version range to the
+\`--target\` directory, then writes a JSON summary to \`stdout\`:
+
+- \`filesModified\`: files a codemod changed
+- \`warnings\`: files that may still need manual migration
+- \`llmReviews\`: changes the codemods could not fully migrate on their own. Each
+  entry has the affected \`files\` and a \`prompt\` — hand the prompt and files to
+  an LLM (or follow it yourself) to finish those cases.
+
+Progress, warnings, and the LLM-review prompts are also printed to \`stderr\` in
+human-readable form, so \`stdout\` stays pure JSON for piping.`,
+	examples: [{
+		cmd: "--from 1.64.0 --to 2.0.0",
+		desc: "Apply every codemod for the 1.64.0 -> 2.0.0 upgrade to the current project"
+	}, {
+		cmd: "--from 1.64.0 --to 2.0.0 --dry-run",
+		desc: "Preview the changes and any LLM-review prompts without writing files"
+	}],
 	args: z.object({
 		from: arg(z.string(), { description: "Source SDK version (the version before upgrade)" }),
 		to: arg(z.string(), { description: "Target SDK version (the version after upgrade)" }),
@@ -268,7 +749,8 @@ runMain(defineCommand({
 			codemodsSkipped: 0,
 			filesModified: [],
 			warnings: [],
-			errors: []
+			errors: [],
+			llmReviews: []
 		};
 		if (codemods.length === 0) {
 			process.stdout.write(JSON.stringify(output) + "\n");
@@ -276,7 +758,7 @@ runMain(defineCommand({
 		}
 		const codemodEntries = codemods.map((codemod) => ({
 			codemod,
-			scriptPath: resolveCodemodScript(codemod.scriptPath)
+			scriptPath: codemod.scriptPath ? resolveCodemodScript(codemod.scriptPath) : void 0
 		}));
 		for (const { codemod } of codemodEntries) process.stderr.write(`Running: ${codemod.name} - ${codemod.description}\n`);
 		try {
@@ -285,8 +767,10 @@ runMain(defineCommand({
 			output.codemodsSkipped = codemods.length - result.appliedCodemodIds.size;
 			output.filesModified = result.filesModified;
 			output.warnings = result.warnings;
+			output.llmReviews = result.llmReviews;
 			if (result.changed) process.stderr.write(`  ${result.filesModified.length} file(s) modified\n`);
 			else process.stderr.write("  No changes needed\n");
+			for (const review of output.llmReviews) printLlmReview(review);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			output.errors.push({