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

package/dist/index.js

@@ -5,18 +5,22 @@ import * as path from "pathe";
 import { readPackageJSON } from "pkg-types";
 import { arg, defineCommand, runMain } from "politty";
 import { z } from "zod";
-import { gte, lt, valid } from "semver";
+import { gte, lt, parse, valid } from "semver";
 import * as fs from "node:fs";
-import { Lang, parse } from "@ast-grep/napi";
+import { realpathSync } from "node:fs";
+import { Lang, parse as parse$1 } from "@ast-grep/napi";
 import chalk from "chalk";
 import { structuredPatch } from "diff";
 import picomatch from "picomatch";
+import { execFileSync } from "node:child_process";
 //#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.
+*   residuals (via `legacyPatterns`/`sourceStringLegacyPatterns`/
+*   `sourceTextLegacyPatterns`/`suspiciousPatterns`/
+*   `sourceStringSuspiciousPatterns`/`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
@@ -24,11 +28,94 @@ import picomatch from "picomatch";
 */
 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";
+	return (codemod.legacyPatterns?.length ?? 0) > 0 || (codemod.sourceStringLegacyPatterns?.length ?? 0) > 0 || (codemod.sourceTextLegacyPatterns?.length ?? 0) > 0 || (codemod.suspiciousPatterns?.length ?? 0) > 0 || (codemod.sourceStringSuspiciousPatterns?.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");
+const RENAME_BIN_SOURCE_VALUE_FLAGS = [
+	"--env-file-if-exists",
+	"--env-file",
+	"--profile",
+	"--config",
+	"--workspace-id",
+	"--arg",
+	"--query",
+	"--file",
+	"--name",
+	"--namespace",
+	"--dir",
+	"-e",
+	"-p",
+	"-c",
+	"-w",
+	"-a",
+	"-q",
+	"-f",
+	"-n"
+];
+const RENAME_BIN_SOURCE_COMMANDS = [
+	"api",
+	"apply",
+	"authconnection",
+	"completion",
+	"crash-report",
+	"crashreport",
+	"deploy",
+	"executor",
+	"function",
+	"generate",
+	"init",
+	"login",
+	"logout",
+	"machineuser",
+	"oauth2client",
+	"open",
+	"organization",
+	"profile",
+	"query",
+	"remove",
+	"secret",
+	"setup",
+	"show",
+	"skills",
+	"staticwebsite",
+	"tailordb",
+	"upgrade",
+	"user",
+	"workflow",
+	"workspace"
+];
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const RENAME_BIN_SOURCE_VALUE_GUARDS = RENAME_BIN_SOURCE_VALUE_FLAGS.flatMap((flag) => {
+	const escaped = escapeRegExp(flag);
+	return [`(?<!${escaped}\\s+)`, `(?<!${escaped}=)`];
+}).join("");
+const RENAME_BIN_SOURCE_COMMAND_OR_FLAG = `(?:--?[\\w-]+|${RENAME_BIN_SOURCE_COMMANDS.join("|")})`;
+const RENAME_BIN_SOURCE_COMMAND_TOKEN = "tailor-sdk(?:(?:\\.(?:cmd|ps1|exe))|(?:@[^\\s'\"`;|&)]+))?(?![\\w-])";
+const RENAME_BIN_SOURCE_LEGACY_PATTERN = new RegExp([
+	"(?<![.\\w-])",
+	"(?<![\"'])",
+	"(?<!\\\\[\"'])",
+	RENAME_BIN_SOURCE_VALUE_GUARDS,
+	RENAME_BIN_SOURCE_COMMAND_TOKEN,
+	`(?=\\s*(?:$|${RENAME_BIN_SOURCE_COMMAND_OR_FLAG}\\b))`
+].join(""));
+const RENAME_BIN_QUOTED_SOURCE_LEGACY_PATTERN = new RegExp([
+	"(?:^|[\\s;&|\\x00])(?:sh|bash|zsh)\\s+-\\w*c\\w*\\s+\\\\?[\"']",
+	RENAME_BIN_SOURCE_COMMAND_TOKEN,
+	`(?=\\s*(?:$|${RENAME_BIN_SOURCE_COMMAND_OR_FLAG}\\b))`
+].join(""));
+const RENAME_BIN_QUOTED_LEGACY_COMMAND_PATTERN = new RegExp([
+	RENAME_BIN_SOURCE_VALUE_GUARDS,
+	"[\"']",
+	RENAME_BIN_SOURCE_COMMAND_TOKEN,
+	"(?=\\s*(?:apply\\b|crash-report\\b|[^\"'`]*\\s--machineuser\\b))"
+].join(""));
+const V2_NEXT_1 = "2.0.0-next.1";
+const V2_NEXT_2 = "2.0.0-next.2";
 /** All registered codemods, in registration order. */
 const allCodemods = [
 	{
@@ -37,6 +124,7 @@ const allCodemods = [
 		description: "Migrate defineGenerators() tuple syntax to definePlugins() with explicit plugin imports",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/define-generators-to-plugins/scripts/transform.js",
 		legacyPatterns: ["defineGenerators"],
 		examples: [{
@@ -68,6 +156,7 @@ 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",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/plugin-cli-import/scripts/transform.js",
 		examples: [{
 			before: "import { kyselyTypePlugin } from \"@tailor-platform/sdk/cli\";",
@@ -77,9 +166,10 @@ const allCodemods = [
 	{
 		id: "v2/test-run-arg-input",
 		name: "function test-run --arg input unwrap",
-		description: "Strip the deprecated {input: ...} wrapper from `tailor-sdk function test-run --arg` JSON in scripts and docs",
+		description: "Strip the deprecated {input: ...} wrapper from `tailor function test-run --arg` JSON in scripts and docs",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/test-run-arg-input/scripts/transform.js",
 		filePatterns: [
 			"**/package.json",
@@ -88,16 +178,17 @@ const allCodemods = [
 		],
 		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}'"
+			before: "tailor function test-run resolvers/add.ts --arg '{\"input\":{\"a\":1}}'",
+			after: "tailor function test-run resolvers/add.ts --arg '{\"a\":1}'"
 		}]
 	},
 	{
 		id: "v2/sdk-skills-shim",
-		name: "tailor-sdk-skills → tailor-sdk skills install",
-		description: "Replace deprecated `tailor-sdk-skills` invocations with `tailor-sdk skills install`",
+		name: "tailor-sdk-skills → tailor skills add",
+		description: "Replace deprecated `tailor-sdk-skills` invocations with `tailor skills add`",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/sdk-skills-shim/scripts/transform.js",
 		filePatterns: [
 			"**/package.json",
@@ -108,13 +199,13 @@ const allCodemods = [
 		examples: [{
 			lang: "sh",
 			before: "npx tailor-sdk-skills",
-			after: "tailor-sdk skills install"
+			after: "tailor skills add"
 		}],
 		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",
+			"The standalone tailor-sdk-skills binary is removed in v2; call the skills add",
+			"subcommand on the main tailor CLI instead. Replace any remaining",
 			"tailor-sdk-skills invocations the codemod did not rewrite with",
-			"`tailor-sdk skills install`."
+			"`tailor skills add`."
 		].join("\n")
 	},
 	{
@@ -123,6 +214,7 @@ const allCodemods = [
 		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",
+		prereleaseUntil: V2_NEXT_2,
 		scriptPath: "v2/principal-unify/scripts/transform.js",
 		legacyPatterns: [
 			"TailorUser",
@@ -162,12 +254,40 @@ const allCodemods = [
 			"Use TailorPrincipal for the unified user/actor/invoker type."
 		].join("\n")
 	},
+	{
+		id: "v2/auth-attributes-rename",
+		name: "AttributeMap → Attributes",
+		description: "Rename auth attribute module augmentation and related SDK type names from `AttributeMap` to `Attributes`",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/auth-attributes-rename/scripts/transform.js",
+		legacyPatterns: [
+			"AttributeMap",
+			"interface AttributeMap",
+			"UserAttributeMap",
+			"InferredAttributeMap"
+		],
+		examples: [{
+			caption: "Module augmentation uses `Attributes`:",
+			before: "declare module \"@tailor-platform/sdk\" {\n  interface AttributeMap {\n    role: string;\n  }\n}",
+			after: "declare module \"@tailor-platform/sdk\" {\n  interface Attributes {\n    role: string;\n  }\n}"
+		}],
+		prompt: [
+			"In Tailor SDK v2, the auth attribute type API is renamed from `AttributeMap`",
+			"to `Attributes`; related SDK types are renamed to `UserAttributes` and",
+			"`InferredAttributes`. The codemod rewrites SDK imports, re-exports,",
+			"namespace-qualified references, import() type references, and module",
+			"augmentations. Review any remaining matches manually and leave unrelated",
+			"local names or deploy/proto wire field names unchanged."
+		].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 canonical v2 `tailor-sdk deploy` command",
 		since: "1.0.0",
 		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/apply-to-deploy/scripts/transform.js",
 		filePatterns: [
 			"**/package.json",
@@ -187,6 +307,7 @@ const allCodemods = [
 		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",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/cli-rename/scripts/transform.js",
 		filePatterns: [
 			"**/package.json",
@@ -206,12 +327,98 @@ const allCodemods = [
 			"happen to use `--machineuser` alone."
 		].join("\n")
 	},
+	{
+		id: "v2/env-var-rename",
+		name: "SDK environment variable rename",
+		description: "Rewrite unambiguous removed SDK environment variable names to their v2 `TAILOR_*` names and flag generic names for manual review",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/env-var-rename/scripts/transform.js",
+		filePatterns: [
+			"**/package.json",
+			"**/.env",
+			"**/.env.*",
+			"**/*.{env,sh,bash,zsh,yml,yaml,json,md}",
+			"**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"
+		],
+		legacyPatterns: [
+			"TAILOR_PLATFORM_SDK_CONFIG_PATH",
+			"TAILOR_PLATFORM_SDK_DTS_PATH",
+			"TAILOR_PLATFORM_SDK_ALLOW_CI_ID_INJECTION",
+			"TAILOR_PLATFORM_SDK_BUILD_ONLY",
+			"TAILOR_SDK_OUTPUT_DIR",
+			"TAILOR_SDK_SKILLS_SOURCE",
+			"TAILOR_SDK_VERSION",
+			"PLATFORM_URL",
+			"PLATFORM_OAUTH2_CLIENT_ID",
+			"TAILOR_ENABLE_INLINE_SOURCEMAP",
+			"TAILOR_PLATFORM_QUERY_NEWLINE_ON_ENTER",
+			"LOG_LEVEL",
+			"TAILOR_TOKEN"
+		],
+		sourceStringLegacyPatterns: [
+			"PLATFORM_URL",
+			"PLATFORM_OAUTH2_CLIENT_ID",
+			"LOG_LEVEL"
+		],
+		examples: [{
+			lang: "sh",
+			before: "TAILOR_PLATFORM_SDK_BUILD_ONLY=true tailor-sdk deploy",
+			after: "TAILOR_DEPLOY_BUILD_ONLY=true tailor-sdk deploy"
+		}, {
+			before: "const token = process.env.TAILOR_TOKEN;",
+			after: "const token = process.env.TAILOR_PLATFORM_TOKEN;"
+		}],
+		prompt: [
+			"Review any remaining removed SDK environment variable names after the codemod",
+			"runs. The codemod intentionally leaves generic names such as `LOG_LEVEL`,",
+			"`PLATFORM_URL`, and `PLATFORM_OAUTH2_CLIENT_ID` for manual review because",
+			"they can configure non-SDK tools. Replace only actual SDK usages with their",
+			"v2 names. If a remaining match is an unrelated local identifier, fixture",
+			"label, or historical documentation that intentionally does not configure the",
+			"SDK, leave it unchanged."
+		].join("\n")
+	},
+	{
+		id: "v2/auth-invoker-call-unwrap",
+		name: "auth.invoker(\"name\") → \"name\"",
+		description: "Replace statically identified SDK `auth.invoker(\"name\")` option values with the bare `\"name\"` string while preserving the `authInvoker` key for SDK versions before the option rename.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_1,
+		scriptPath: "v2/auth-invoker-call-unwrap/scripts/transform.js",
+		suspiciousPatterns: ["auth.invoker"],
+		reviewSupersededBy: ["v2/auth-invoker-unwrap"],
+		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 authInvoker: \"name\". These files still contain",
+			"auth.invoker(...) calls 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. Keep the authInvoker key when targeting SDK versions before the invoker",
+			"   option rename; later v2 targets run a separate codemod for that key rename.",
+			"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 auth.invoker() removal."
+		].join("\n"),
+		examples: [{
+			before: "createResolver({ authInvoker: auth.invoker(\"manager\") });",
+			after: "createResolver({ authInvoker: \"manager\" });"
+		}]
+	},
 	{
 		id: "v2/auth-invoker-unwrap",
 		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",
+		prereleaseUntil: V2_NEXT_2,
 		scriptPath: "v2/auth-invoker-unwrap/scripts/transform.js",
 		suspiciousPatterns: [
 			"auth.invoker",
@@ -254,12 +461,46 @@ const allCodemods = [
 			after: "createResolver({ invoker: \"manager\" });"
 		}]
 	},
+	{
+		id: "v2/auth-connection-token-helper",
+		name: "auth.getConnectionToken() → runtime authconnection",
+		description: "The deprecated `auth.getConnectionToken()` helper returned by `defineAuth()` is removed in v2. Use `authconnection.getConnectionToken(...)` from `@tailor-platform/sdk/runtime` in resolvers, executors, and workflows instead.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_2,
+		scriptPath: "v2/auth-connection-token-helper/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		examples: [{
+			before: "import { auth } from \"../tailor.config\";\n\nconst token = await auth.getConnectionToken(\"google\");",
+			after: "import { authconnection } from \"@tailor-platform/sdk/runtime\";\n\nconst token = await authconnection.getConnectionToken(\"google\");"
+		}],
+		prompt: [
+			"In Tailor SDK v2 the auth.getConnectionToken() helper returned by defineAuth()",
+			"is removed. Runtime code should call authconnection.getConnectionToken(...) from",
+			"@tailor-platform/sdk/runtime instead of importing auth from tailor.config.ts.",
+			"",
+			"For each getConnectionToken usage where <receiver> is a defineAuth() result",
+			"imported from tailor.config.ts:",
+			"1. Replace <receiver>.getConnectionToken(<expr>) calls with",
+			"   authconnection.getConnectionToken(<expr>).",
+			"2. Update non-call references, including <receiver>.getConnectionToken,",
+			"   <receiver>[\"getConnectionToken\"], and destructuring from <receiver>, to",
+			"   reference authconnection instead.",
+			"3. Add or reuse `import { authconnection } from \"@tailor-platform/sdk/runtime\"`.",
+			"4. Remove the auth import from tailor.config.ts only when no other auth reference",
+			"   remains in the file.",
+			"",
+			"Leave usages unchanged when the receiver is already the runtime authconnection",
+			"wrapper or global tailor.authconnection."
+		].join("\n")
+	},
 	{
 		id: "v2/tailordb-namespace",
 		name: "Tailordb → tailordb (lowercase ambient namespace)",
 		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",
+		prereleaseUntil: V2_NEXT_1,
 		scriptPath: "v2/tailordb-namespace/scripts/transform.js",
 		legacyPatterns: ["Tailordb."],
 		examples: [{
@@ -283,6 +524,7 @@ const allCodemods = [
 		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",
+		prereleaseUntil: V2_NEXT_2,
 		scriptPath: "v2/execute-script-arg/scripts/transform.js",
 		filePatterns: ["**/*.{ts,tsx,mts,cts,mjs,cjs,js}"],
 		suspiciousPatterns: [[
@@ -309,12 +551,26 @@ const allCodemods = [
 			after: "await executeScript({ ...opts, arg: { a: 1 } });"
 		}]
 	},
+	{
+		id: "v2/wait-point-rename",
+		name: "defineWaitPoint/defineWaitPoints → createWaitPoint/createWaitPoints",
+		description: "Rename `defineWaitPoint` and `defineWaitPoints` to `createWaitPoint` and `createWaitPoints`. The functions create runtime instances with `.wait()` / `.resolve()` methods, so the `create*` prefix is used consistently.",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/wait-point-rename/scripts/transform.js",
+		legacyPatterns: ["defineWaitPoint", "defineWaitPoints"],
+		examples: [{
+			before: "import { defineWaitPoints } from \"@tailor-platform/sdk\";\n\nexport const { approval } = defineWaitPoints((define) => ({\n  approval: define<{ message: string }, { approved: boolean }>(),\n}));",
+			after: "import { createWaitPoints } from \"@tailor-platform/sdk\";\n\nexport const { approval } = createWaitPoints((define) => ({\n  approval: define<{ message: string }, { approved: boolean }>(),\n}));"
+		}]
+	},
 	{
 		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",
+		prereleaseUntil: V2_NEXT_2,
 		filePatterns: ["**/*.{ts,tsx,mts,cts,mjs,cjs,js}"],
 		suspiciousPatterns: ["openDownloadStream", "openFileDownloadStream"],
 		examples: [{
@@ -331,14 +587,18 @@ const allCodemods = [
 	{
 		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.)",
+		description: "Importing `@tailor-platform/sdk` no longer activates the ambient `tailor.*` / `tailordb.*` global declarations. The codemod rewrites simple direct `new tailor.idp.Client(...)` calls to the typed `idp.Client` wrapper from `@tailor-platform/sdk/runtime`; broader runtime global usage remains review-only. 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}"],
+		prereleaseUntil: V2_NEXT_1,
+		scriptPath: "v2/runtime-globals-opt-in/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
 		suspiciousPatterns: [
 			"tailor.context",
 			"tailor.iconv",
 			"tailor.idp",
+			"tailor.secretmanager",
+			"tailor.authconnection",
 			"tailor.workflow",
 			"tailor[",
 			"tailordb.Client",
@@ -351,6 +611,21 @@ const allCodemods = [
 			"TailorErrorMessage",
 			"TailorErrors"
 		],
+		sourceStringSuspiciousPatterns: [
+			"new tailor.idp.Client",
+			/[=(:,[]\s*tailor\.idp\.Client\b/,
+			/(?:(?:=>|[=(:,<{]|\[)\s*|\b(?:return|await|typeof)\s+)tailor\.(?:authconnection|context|iconv|idp|secretmanager|workflow)(?:\.[A-Za-z_$][\w$]*)?\b/,
+			/\btailor\.(?:authconnection|context|iconv|idp|secretmanager|workflow)\.[A-Za-z_$][\w$]*\s*\(/,
+			"tailor[",
+			/\btailordb\.file\.[A-Za-z_$][\w$]*\s*\(/,
+			/(?:(?:=>|[=(:,<{]|\[)\s*|\b(?:return|await|typeof)\s+)tailordb\.file\b/,
+			/(?:\bnew\s+|(?:=>|[=(:,<{]|\[)\s*|\b(?:return|await|typeof)\s+)tailordb\.(?:Client|CommandType|QueryResult)\b/,
+			/<\s*tailordb\.(?:Client|CommandType|QueryResult)\b/,
+			"tailordb[",
+			/(?:\bnew\s+|\bthrow\s+|\binstanceof\s+)Tailor(?:DBFileError|Errors|ErrorMessage)\b/,
+			/(?:[:=<]\s*|\bas\s+)Tailor(?:DBFileError|Errors|ErrorMessage|ErrorItem)\b/,
+			/[:<]\s*TailorErrorItem\b/
+		],
 		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();",
@@ -364,10 +639,11 @@ const allCodemods = [
 			"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.",
+			"typed wrappers from `@tailor-platform/sdk/runtime`. The codemod already",
+			"rewrites direct `new tailor.idp.Client(...)` calls to `new idp.Client(...)`",
+			"when the file has no conflicting `tailor` or `idp` binding. For any remaining",
+			"`tailor.idp.Client` references, either resolve the binding collision and use",
+			"`idp.Client`, or keep the ambient global deliberately.",
 			"",
 			"Only when the file must keep referencing the bare `tailor.*` names directly,",
 			"opt into the global declarations instead by adding one of these:",
@@ -376,7 +652,9 @@ const allCodemods = [
 			"  the relevant tsconfig compilerOptions",
 			"",
 			"Leave files unchanged when the matching name is local, imported from another",
-			"module, or appears only in comments or strings."
+			"module, or appears only in comments or prose strings. Embedded code strings",
+			"that use runtime globals are review-only findings; do not insert imports inside",
+			"string literals."
 		].join("\n")
 	},
 	{
@@ -385,6 +663,7 @@ const allCodemods = [
 		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",
+		prereleaseUntil: V2_NEXT_1,
 		suspiciousPatterns: [".trigger("],
 		examples: [{
 			caption: "Tests must mock the workflow runtime instead of running bodies locally:",
@@ -405,6 +684,7 @@ const allCodemods = [
 		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",
+		prereleaseUntil: V2_NEXT_2,
 		notice: true
 	},
 	{
@@ -413,12 +693,87 @@ const allCodemods = [
 		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",
+		prereleaseUntil: V2_NEXT_1,
 		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.",
+		description: "`tailor 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",
+		prereleaseUntil: V2_NEXT_1,
+		notice: true
+	},
+	{
+		id: "v2/rename-bin",
+		name: "tailor-sdk binary → tailor",
+		description: "Rename the CLI binary from `tailor-sdk` to `tailor` in package.json scripts, shell scripts, CI workflows, source files, generated declaration comments, and documentation. Does not rename `.tailor-sdk` directory paths or the `create-tailor-sdk` scaffolding package. Note: v2 also changes the default generated output directory from `.tailor-sdk/` to `.tailor/` and the setup lock file from `.github/tailor-sdk.lock` to `.github/tailor.lock`. Run `mv .tailor-sdk .tailor` to migrate the generated output directory (preserves auth connection state and other local files). Run `git mv .github/tailor-sdk.lock .github/tailor.lock` if the old lock file exists; without it `tailor setup check` will treat all managed workflows as missing. Exact ignore-file entries for `.tailor-sdk/` are handled by the generated-output ignore codemod.",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/rename-bin/scripts/transform.js",
+		filePatterns: [
+			"**/package.json",
+			"**/*.{sh,bash,zsh,yml,yaml}",
+			"**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}",
+			"**/*.md"
+		],
+		legacyPatterns: ["tailor-sdk"],
+		sourceStringLegacyPatterns: [
+			RENAME_BIN_SOURCE_LEGACY_PATTERN,
+			RENAME_BIN_QUOTED_SOURCE_LEGACY_PATTERN,
+			RENAME_BIN_QUOTED_LEGACY_COMMAND_PATTERN
+		],
+		sourceTextLegacyPatterns: [
+			RENAME_BIN_SOURCE_LEGACY_PATTERN,
+			RENAME_BIN_QUOTED_SOURCE_LEGACY_PATTERN,
+			RENAME_BIN_QUOTED_LEGACY_COMMAND_PATTERN
+		],
+		examples: [{
+			lang: "sh",
+			before: "tailor-sdk deploy\nnpx tailor-sdk@latest login",
+			after: "tailor deploy\nnpx @tailor-platform/sdk@latest login"
+		}],
+		prompt: [
+			"Rename any remaining `tailor-sdk` binary invocations to `tailor`. Only rewrite",
+			"the binary name — leave `.tailor-sdk` directory paths and `create-tailor-sdk`",
+			"package references unchanged."
+		].join("\n")
+	},
+	{
+		id: "v2/tailor-output-ignore-dir",
+		name: ".tailor-sdk ignore entries → .tailor",
+		description: "Rewrite exact ignore-file entries for the v1 generated output directory from `.tailor-sdk` to the v2 `.tailor` directory. Other `.tailor-sdk` paths and prose are left unchanged.",
+		since: "1.0.0",
+		until: "2.0.0",
+		scriptPath: "v2/tailor-output-ignore-dir/scripts/transform.js",
+		filePatterns: [
+			"**/.gitignore",
+			"**/.npmignore",
+			"**/.dockerignore",
+			"**/gitignore",
+			"**/npmignore",
+			"**/dockerignore",
+			"**/_gitignore",
+			"**/_npmignore",
+			"**/_dockerignore",
+			"**/__dot__gitignore",
+			"**/__dot__npmignore",
+			"**/__dot__dockerignore",
+			"**/*.gitignore",
+			"**/*.npmignore",
+			"**/*.dockerignore"
+		],
+		examples: [{
+			lang: "gitignore",
+			before: ".tailor-sdk/",
+			after: ".tailor/"
+		}]
+	},
+	{
+		id: "v2/node-minimum-22-15-0",
+		name: "Node.js minimum version raised to 22.15.0",
+		description: "v2 requires Node.js **22.15.0** or later. This is the first version that includes `module.registerHooks()`, which the SDK uses to register its TypeScript loader hook synchronously in the main thread. No source change is required; ensure your environment runs Node.js 22.15.0+.",
 		since: "1.0.0",
 		until: "2.0.0",
 		notice: true
@@ -432,9 +787,32 @@ const allCodemods = [
 function resolveCodemodScript(scriptPath) {
 	return path.resolve(CODEMODS_ROOT, scriptPath);
 }
+function reachesCodemodBoundary(toVersion, codemod) {
+	if (gte(toVersion, codemod.until)) return true;
+	if (codemod.prereleaseUntil === void 0 || !gte(toVersion, codemod.prereleaseUntil)) return false;
+	const target = parse(toVersion);
+	const boundary = parse(codemod.until);
+	return target.prerelease.length > 0 && target.major === boundary.major && target.minor === boundary.minor && target.patch === boundary.patch;
+}
+function effectiveCodemodBoundary(codemod) {
+	return codemod.prereleaseUntil ?? codemod.until;
+}
+function assertCodemodBoundaries(codemods) {
+	for (const codemod of codemods) {
+		const boundary = parse(codemod.until);
+		if (boundary === null) throw new Error(`Codemod ${codemod.id} until must be a valid semver version: ${codemod.until}`);
+		if (boundary.prerelease.length > 0) throw new Error(`Codemod ${codemod.id} until must be a stable version: ${codemod.until}`);
+		if (codemod.prereleaseUntil === void 0) continue;
+		const prereleaseBoundary = parse(codemod.prereleaseUntil);
+		if (prereleaseBoundary === null) throw new Error(`Codemod ${codemod.id} prereleaseUntil must be a valid semver version: ${codemod.prereleaseUntil}`);
+		if (prereleaseBoundary.prerelease.length === 0) throw new Error(`Codemod ${codemod.id} prereleaseUntil must be a prerelease version: ${codemod.prereleaseUntil}`);
+		if (prereleaseBoundary.major !== boundary.major || prereleaseBoundary.minor !== boundary.minor || prereleaseBoundary.patch !== boundary.patch) throw new Error(`Codemod ${codemod.id} prereleaseUntil must target the same version as until: ${codemod.prereleaseUntil}`);
+	}
+}
 /**
 * Get codemod packages applicable for a version range.
-* A codemod applies when: since <= fromVersion < until <= toVersion
+* A codemod applies when: since <= fromVersion < boundary <= toVersion.
+* A target prerelease reaches `until` only when the codemod declares `prereleaseUntil`.
 * @param fromVersion - Current SDK version (semver)
 * @param toVersion - Target SDK version (semver)
 * @returns Array of applicable codemod packages in registration order
@@ -442,20 +820,21 @@ function resolveCodemodScript(scriptPath) {
 function getApplicableCodemods(fromVersion, toVersion) {
 	if (!valid(fromVersion)) throw new Error(`Invalid fromVersion: ${fromVersion}`);
 	if (!valid(toVersion)) throw new Error(`Invalid toVersion: ${toVersion}`);
-	return allCodemods.filter((codemod) => gte(fromVersion, codemod.since) && lt(fromVersion, codemod.until) && gte(toVersion, codemod.until));
+	assertCodemodBoundaries(allCodemods);
+	return allCodemods.filter((codemod) => gte(fromVersion, codemod.since) && lt(fromVersion, effectiveCodemodBoundary(codemod)) && reachesCodemodBoundary(toVersion, codemod));
 }
 //#endregion
 //#region src/runner.ts
 /** Default file patterns for TypeScript files. */
 const DEFAULT_FILE_PATTERNS = ["**/*.{ts,tsx,mts,cts}"];
 /** Directory names always excluded from file scanning. */
-const EXCLUDE_DIRS = new Set([
+const EXCLUDE_DIRS = /* @__PURE__ */ new Set([
 	"node_modules",
 	"dist",
 	".git"
 ]);
-const ALLOWED_DOT_DIRS = new Set([".github", ".circleci"]);
-const SOURCE_EXTENSIONS = new Set([
+const ALLOWED_DOT_DIRS = /* @__PURE__ */ new Set([".github", ".circleci"]);
+const SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([
 	".ts",
 	".tsx",
 	".mts",
@@ -465,12 +844,36 @@ const SOURCE_EXTENSIONS = new Set([
 	".mjs",
 	".cjs"
 ]);
-const MASKED_SOURCE_NODE_KINDS = new Set([
+const SOURCE_STRING_FRAGMENT_SEPARATOR = "\0";
+const MASKED_SOURCE_NODE_KINDS = /* @__PURE__ */ new Set([
 	"comment",
 	"string",
 	"regex",
-	"string_fragment"
+	"string_fragment",
+	"jsx_text"
+]);
+const SOURCE_VALUE_FLAGS = /* @__PURE__ */ new Set([
+	"--env-file-if-exists",
+	"--env-file",
+	"--profile",
+	"--config",
+	"--workspace-id",
+	"--arg",
+	"--query",
+	"--file",
+	"--name",
+	"--namespace",
+	"--dir",
+	"-e",
+	"-p",
+	"-c",
+	"-w",
+	"-a",
+	"-q",
+	"-f",
+	"-n"
 ]);
+const SOURCE_CLI_BINARY_RE = /^(?:(?:.*[\\/])?tailor(?:\.(?:cmd|ps1|exe))?|(?:.*[\\/])?tailor-sdk(?:@[^\s'"`;|&)]+)?(?:\.(?:cmd|ps1|exe))?|@tailor-platform\/sdk(?:@[^\s'"`;|&)]+)?)$/;
 function shouldSkipDirectory(name) {
 	return EXCLUDE_DIRS.has(name) || name.startsWith(".") && !ALLOWED_DOT_DIRS.has(name);
 }
@@ -514,25 +917,229 @@ function printDiff(filePath, before, after) {
 * Load a transform module from a TypeScript file path.
 * Expects the module to have a default export that is a TransformFn.
 * @param scriptPath - Absolute path to the transform script
-* @returns The transform function
+* @returns The transform function and optional review detector
 */
-async function loadTransform(scriptPath) {
+async function loadTransformModule(scriptPath) {
 	const mod = await import(url.pathToFileURL(scriptPath).href);
 	if (typeof mod.default !== "function") throw new Error(`Transform at ${scriptPath} does not have a default export function`);
-	return mod.default;
+	return {
+		transform: mod.default,
+		reviewFindings: typeof mod.reviewFindings === "function" ? mod.reviewFindings : void 0
+	};
 }
 function contentForResidualMatching(relative, content) {
 	const ext = path.extname(relative).toLowerCase();
 	return SOURCE_EXTENSIONS.has(ext) ? maskSourceNonCode(relative, content) : content;
 }
+function sourceStringFragmentGapForResidualMatching(gap) {
+	if (/^\\["']$/.test(gap)) return gap.slice(1);
+	return /^(?:\\(?:[nrtvf]|\r\n|\r|\n)|\s)+$/.test(gap) ? " " : SOURCE_STRING_FRAGMENT_SEPARATOR;
+}
+function sourceStringNodeContentForResidualMatching(node, content) {
+	const parts = [];
+	let previousFragmentEnd = null;
+	for (const child of node.children()) {
+		if (child.kind() !== "string_fragment") continue;
+		const range = child.range();
+		if (previousFragmentEnd != null && range.start.index > previousFragmentEnd) parts.push(sourceStringFragmentGapForResidualMatching(content.slice(previousFragmentEnd, range.start.index)));
+		parts.push(child.text());
+		previousFragmentEnd = range.end.index;
+	}
+	return parts.length === 0 ? null : parts.join("");
+}
+function sourceStringContentForResidualMatching(relative, content) {
+	const ext = path.extname(relative).toLowerCase();
+	if (!SOURCE_EXTENSIONS.has(ext)) return null;
+	let root;
+	try {
+		root = parse$1(sourceLang(relative), content).root();
+	} catch {
+		return null;
+	}
+	const sourceStrings = [];
+	const visit = (node) => {
+		if (node.kind() === "arguments") {
+			const value = sourceArgumentsCommandContent(node, content);
+			if (value != null) sourceStrings.push(value);
+		}
+		if (node.kind() === "array") {
+			const value = sourceArrayCommandContent(node, content);
+			if (value != null) sourceStrings.push(value);
+		}
+		const kind = node.kind();
+		if (kind === "string" || kind === "template_string") {
+			if (isSourceTailorSdkValueArgument(node, content)) return;
+			const sourceString = sourceStringNodeContentForResidualMatching(node, content);
+			if (sourceString != null) sourceStrings.push(sourceString);
+		}
+		for (const child of node.children()) {
+			if (child.kind() === "string_fragment") continue;
+			visit(child);
+		}
+	};
+	visit(root);
+	return sourceStrings.join(SOURCE_STRING_FRAGMENT_SEPARATOR);
+}
+function isConstVariableDeclarator(node) {
+	return node.parent()?.children().some((child) => child.kind() === "const") ?? false;
+}
+function sourceTextContentForResidualMatching(relative, content) {
+	const ext = path.extname(relative).toLowerCase();
+	if (!SOURCE_EXTENSIONS.has(ext)) return null;
+	let root;
+	try {
+		root = parse$1(sourceLang(relative), content).root();
+	} catch {
+		return null;
+	}
+	const fragments = [];
+	const visit = (node) => {
+		if (node.kind() === "comment" || node.kind() === "jsx_text") {
+			fragments.push(node.text());
+			return;
+		}
+		for (const child of node.children()) visit(child);
+	};
+	visit(root);
+	return fragments.join(SOURCE_STRING_FRAGMENT_SEPARATOR);
+}
+function sourceArgumentsCommandContent(node, source) {
+	const args = sourceArrayElements(node);
+	const executable = args[0] == null ? null : sourceStringLikeNodeContent(args[0], source);
+	const argv = args[1];
+	if (executable == null || argv?.kind() !== "array") return null;
+	const values = sourceArrayCommandValues(argv, source);
+	return values.length === 0 ? null : [executable, ...values].join(" ");
+}
+function sourceArrayCommandContent(node, source) {
+	const values = sourceArrayCommandValues(node, source);
+	return values.length < 2 ? null : values.join(" ");
+}
+function sourceArrayCommandValues(node, source) {
+	const values = [];
+	for (const element of sourceArrayElements(node)) {
+		if (isSourceValueArgument(element, source)) continue;
+		const value = sourceStringLikeNodeContent(element, source);
+		if (value != null) values.push(value);
+	}
+	return values;
+}
+function isSourceTailorSdkValueArgument(fragment, source) {
+	const text = fragment.kind() === "string_fragment" ? fragment.text() : sourceStringLikeNodeContent(fragment, source);
+	return text != null && text.includes("tailor-sdk") && isSourceValueArgument(fragment, source);
+}
+function isSyntaxOnlyNode(node) {
+	const kind = node.kind();
+	return kind === "[" || kind === "]" || kind === "(" || kind === ")" || kind === "," || kind === "comment";
+}
+function sourceArrayElements(node) {
+	return node.children().filter((child) => !isSyntaxOnlyNode(child));
+}
+function nodeRangeKey(node) {
+	const range = node.range();
+	return `${range.start.index}:${range.end.index}`;
+}
+function sourceStringLikeNodeContent(node, source) {
+	const directValue = sourceStringNodeContent(node, source);
+	if (directValue != null) return directValue;
+	return node.kind() === "identifier" ? sourceScopedStringVariableContent(node, source) : null;
+}
+function sourceScopedStringVariableContent(identifier, source) {
+	const name = identifier.text();
+	const before = identifier.range().start.index;
+	let current = identifier.parent();
+	while (current != null) {
+		if (isSourceScopeNode(current)) {
+			const value = findSourceStringVariableInScope(current, name, before, source);
+			if (value != null) return value;
+		}
+		current = current.parent();
+	}
+	return null;
+}
+function findSourceStringVariableInScope(scope, name, before, source) {
+	let value = null;
+	const visit = (node) => {
+		if (node !== scope && isSourceScopeNode(node)) return;
+		if (node.kind() === "variable_declarator" && node.range().end.index < before) {
+			const declarationValue = sourceStringVariableDeclarationValue(node, name, source);
+			if (declarationValue != null) value = declarationValue;
+			return;
+		}
+		for (const child of node.children()) visit(child);
+	};
+	visit(scope);
+	return value;
+}
+function sourceStringVariableDeclarationValue(node, name, source) {
+	if (!isConstVariableDeclarator(node)) return null;
+	const children = node.children();
+	if (children.find((child) => child.kind() === "identifier")?.text() !== name) return null;
+	const initializer = children.findLast((child) => sourceConstInitializerContent(child, source) != null);
+	return initializer == null ? null : sourceConstInitializerContent(initializer, source);
+}
+function sourceConstInitializerContent(node, source) {
+	const directValue = sourceStringNodeContent(node, source);
+	if (directValue != null) return directValue;
+	if (node.kind() !== "as_expression" && node.kind() !== "satisfies_expression" && node.kind() !== "parenthesized_expression") return null;
+	for (const child of node.children()) {
+		const childValue = sourceConstInitializerContent(child, source);
+		if (childValue != null) return childValue;
+	}
+	return null;
+}
+function isSourceScopeNode(node) {
+	const kind = node.kind();
+	return kind === "program" || kind === "statement_block" || kind === "function_declaration" || kind === "arrow_function" || kind === "method_definition";
+}
+function sourceStringNodeContent(node, source) {
+	const kind = node.kind();
+	if (kind !== "string" && kind !== "template_string") return null;
+	if (kind === "template_string" && node.children().some((child) => child.kind() === "template_substitution")) return null;
+	const range = node.range();
+	return source.slice(range.start.index + 1, range.end.index - 1);
+}
+function isSourceValueArgument(fragment, source) {
+	const stringNode = fragment.kind() === "string_fragment" ? fragment.parent() : fragment;
+	if (stringNode == null) return false;
+	const parent = stringNode.parent();
+	if (parent?.kind() !== "array") return false;
+	const elements = sourceArrayElements(parent);
+	const index = elements.findIndex((element) => nodeRangeKey(element) === nodeRangeKey(stringNode));
+	if (index <= 0) return false;
+	if (!isTailorCliArgumentArray(parent, index, source)) return false;
+	const previous = sourceStringLikeNodeContent(elements[index - 1], source);
+	return previous != null && SOURCE_VALUE_FLAGS.has(previous.split("=", 1)[0]) && !previous.includes("=");
+}
+function isTailorCliArgumentArray(arrayNode, index, source) {
+	const argumentsNode = arrayNode.parent();
+	if (argumentsNode?.kind() === "arguments") {
+		const callArgs = sourceArrayElements(argumentsNode);
+		const executable = callArgs[0] == null ? null : sourceStringLikeNodeContent(callArgs[0], source);
+		if (executable != null && SOURCE_CLI_BINARY_RE.test(executable)) return true;
+	}
+	return sourceArrayElements(arrayNode).slice(0, index).some((element) => {
+		const value = sourceStringLikeNodeContent(element, source);
+		return value != null && SOURCE_CLI_BINARY_RE.test(value);
+	});
+}
 function sourceLang(relative) {
 	const ext = path.extname(relative).toLowerCase();
-	return ext === ".tsx" || ext === ".jsx" ? Lang.Tsx : Lang.TypeScript;
+	return ext === ".tsx" || ext === ".jsx" || ext === ".js" ? Lang.Tsx : Lang.TypeScript;
+}
+function isProcessEnvSubscriptKey(node) {
+	const stringNode = node.kind() === "string_fragment" ? node.parent() : node;
+	if (stringNode == null) return false;
+	const stringNodeKind = stringNode.kind();
+	if (stringNodeKind !== "string" && stringNodeKind !== "template_string") return false;
+	const parent = stringNode.parent();
+	return parent?.kind() === "subscript_expression" && /^process\.env\s*\[/.test(parent.text());
 }
 function collectMaskedRanges(root) {
 	const ranges = [];
 	const visit = (node) => {
 		if (MASKED_SOURCE_NODE_KINDS.has(node.kind())) {
+			if (isProcessEnvSubscriptKey(node)) return;
 			const range = node.range();
 			ranges.push([range.start.index, range.end.index]);
 			return;
@@ -545,7 +1152,7 @@ function collectMaskedRanges(root) {
 function maskSourceNonCode(relative, content) {
 	let ranges;
 	try {
-		ranges = collectMaskedRanges(parse(sourceLang(relative), content).root());
+		ranges = collectMaskedRanges(parse$1(sourceLang(relative), content).root());
 	} catch {
 		return content;
 	}
@@ -581,13 +1188,31 @@ 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) {
+function matchResidualPatternFragment(content, pattern) {
+	for (const fragment of content.split(SOURCE_STRING_FRAGMENT_SEPARATOR)) {
+		const label = matchResidualPattern(fragment, pattern);
+		if (label != null) return label;
+	}
+	return null;
+}
+function legacyPatternWarnings(relative, content, sourceStringContent, sourceTextContent, 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.`];
+		const found = new Set(lt.legacyPatterns.map((p) => matchResidualPattern(content, p)).filter((label) => label !== null));
+		if (sourceStringContent != null) for (const pattern of lt.sourceStringLegacyPatterns) {
+			const label = matchResidualPatternFragment(sourceStringContent, pattern);
+			if (label != null) found.add(label);
+		}
+		if (sourceTextContent != null) for (const pattern of lt.sourceTextLegacyPatterns) {
+			const label = matchResidualPatternFragment(sourceTextContent, pattern);
+			if (label != null) found.add(label);
+		}
+		if (found.size === 0) return [];
+		return [`${relative}: contains ${Array.from(found).join(", ")} but was not migrated automatically (rule: ${lt.id}). Manual migration may be needed.`];
 	});
 }
+function compareReviewFindings(a, b) {
+	return a.file.localeCompare(b.file) || a.line - b.line || a.message.localeCompare(b.message) || a.excerpt.localeCompare(b.excerpt);
+}
 /**
 * Run multiple codemods on a project directory using in-memory chaining.
 * Each file is processed through all transforms whose filePatterns match it.
@@ -603,13 +1228,19 @@ async function runCodemods(codemods, targetPath, dryRun) {
 	const loaded = [];
 	for (const { codemod, scriptPath } of codemods) {
 		const patterns = codemod.filePatterns ?? DEFAULT_FILE_PATTERNS;
+		const loadedModule = scriptPath ? await loadTransformModule(scriptPath) : void 0;
 		loaded.push({
 			id: codemod.id,
-			transform: scriptPath ? await loadTransform(scriptPath) : void 0,
+			transform: loadedModule?.transform,
+			reviewFindings: loadedModule?.reviewFindings,
 			matches: picomatch(patterns, { dot: true }),
 			legacyPatterns: codemod.legacyPatterns ?? [],
+			sourceStringLegacyPatterns: codemod.sourceStringLegacyPatterns ?? [],
+			sourceTextLegacyPatterns: codemod.sourceTextLegacyPatterns ?? [],
 			suspiciousPatterns: codemod.suspiciousPatterns ?? [],
-			prompt: codemod.prompt
+			sourceStringSuspiciousPatterns: codemod.sourceStringSuspiciousPatterns ?? [],
+			prompt: codemod.prompt,
+			reviewSupersededBy: codemod.reviewSupersededBy ?? []
 		});
 	}
 	const filesModified = [];
@@ -617,6 +1248,7 @@ async function runCodemods(codemods, targetPath, dryRun) {
 	const appliedCodemodIds = /* @__PURE__ */ new Set();
 	const seen = /* @__PURE__ */ new Set();
 	const suspiciousByCodemod = /* @__PURE__ */ new Map();
+	const findingsByCodemod = /* @__PURE__ */ new Map();
 	for await (const relative of walkFiles(targetPath)) {
 		const absolute = path.resolve(targetPath, relative);
 		if (seen.has(absolute)) continue;
@@ -644,26 +1276,51 @@ async function runCodemods(codemods, targetPath, dryRun) {
 			else await fs.promises.writeFile(absolute, current, "utf-8");
 		}
 		const residualContent = contentForResidualMatching(relative, current);
-		warnings.push(...legacyPatternWarnings(relative, residualContent, matchedTransforms));
+		const sourceStringContent = sourceStringContentForResidualMatching(relative, current);
+		const sourceTextContent = sourceTextContentForResidualMatching(relative, current);
+		warnings.push(...legacyPatternWarnings(relative, residualContent, sourceStringContent, sourceTextContent, 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);
+			if (!lt.prompt) continue;
+			const filesForReview = () => {
+				let files = suspiciousByCodemod.get(lt.id);
+				if (!files) {
+					files = /* @__PURE__ */ new Set();
+					suspiciousByCodemod.set(lt.id, files);
+				}
+				return files;
+			};
+			if (lt.reviewFindings) {
+				const findings = await lt.reviewFindings(current, absolute, relative);
+				if (findings.length > 0) {
+					const files = filesForReview();
+					for (const finding of findings) files.add(finding.file);
+					let existing = findingsByCodemod.get(lt.id);
+					if (!existing) {
+						existing = [];
+						findingsByCodemod.set(lt.id, existing);
+					}
+					existing.push(...findings);
+				}
 			}
+			if (lt.suspiciousPatterns.some((p) => matchResidualPattern(residualContent, p) !== null) || sourceStringContent != null && lt.sourceStringSuspiciousPatterns.some((p) => matchResidualPattern(sourceStringContent, p) !== null)) filesForReview().add(relative);
 		}
 	}
 	const llmReviews = [];
+	const loadedIds = new Set(loaded.map((lt) => lt.id));
 	for (const lt of loaded) {
 		if (!lt.prompt) continue;
-		if (lt.suspiciousPatterns.length > 0) {
+		if (lt.reviewSupersededBy.some((id) => loadedIds.has(id))) continue;
+		if (lt.suspiciousPatterns.length > 0 || lt.sourceStringSuspiciousPatterns.length > 0 || lt.reviewFindings) {
 			const files = suspiciousByCodemod.get(lt.id);
-			if (files) llmReviews.push({
-				codemodId: lt.id,
-				prompt: lt.prompt,
-				files: files.toSorted()
-			});
+			if (files) {
+				const findings = findingsByCodemod.get(lt.id)?.toSorted(compareReviewFindings);
+				llmReviews.push({
+					codemodId: lt.id,
+					prompt: lt.prompt,
+					files: Array.from(files).toSorted(),
+					...findings && findings.length > 0 ? { findings } : {}
+				});
+			}
 		} else if (lt.legacyPatterns.length === 0) llmReviews.push({
 			codemodId: lt.id,
 			prompt: lt.prompt,
@@ -679,12 +1336,64 @@ async function runCodemods(codemods, targetPath, dryRun) {
 	};
 }
 //#endregion
+//#region src/runner-metadata.ts
+const SOURCE_PACKAGE_PATH = "packages/sdk-codemod";
+const LOCAL_BUILD_COMMAND = "pnpm --dir packages/sdk-codemod build";
+function createRunnerMetadata({ packageName, packageVersion, packageRoot, readGit = readGitOutput, realpath = safeRealpath }) {
+	const metadata = {
+		packageName,
+		packageVersion
+	};
+	const gitRoot = readGit(packageRoot, ["rev-parse", "--show-toplevel"]);
+	if (!gitRoot) return metadata;
+	if (path.normalize(path.relative(realpath(gitRoot), realpath(packageRoot))).replaceAll("\\", "/") !== SOURCE_PACKAGE_PATH) return metadata;
+	const gitCommit = readGit(packageRoot, [
+		"rev-parse",
+		"--verify",
+		"HEAD"
+	]);
+	if (!gitCommit) return metadata;
+	return {
+		...metadata,
+		gitCommit,
+		localBuildCommand: LOCAL_BUILD_COMMAND
+	};
+}
+function readGitOutput(cwd, args) {
+	try {
+		return execFileSync("git", [
+			"-C",
+			cwd,
+			...args
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim() || void 0;
+	} catch {
+		return;
+	}
+}
+function safeRealpath(value) {
+	try {
+		return realpathSync(value);
+	} catch {
+		return path.resolve(value);
+	}
+}
+//#endregion
 //#region src/index.ts
-const packageJson = await readPackageJSON(path.dirname(fileURLToPath(import.meta.url)) + "/..");
+const packageRoot = path.dirname(fileURLToPath(import.meta.url)) + "/..";
+const packageJson = await readPackageJSON(packageRoot);
+const packageName = packageJson.name ?? "sdk-codemod";
+const packageVersion = packageJson.version ?? "0.0.0";
 const listCommand = defineCommand({
 	name: "list",
 	description: "List the available codemod rules (id, name, kind, version range).",
-	args: z.object({}).strict(),
+	args: z.strictObject({}),
 	run: () => {
 		const rules = allCodemods.map((codemod) => ({
 			id: codemod.id,
@@ -706,11 +1415,26 @@ const listCommand = defineCommand({
 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`);
+	const findingsByFile = /* @__PURE__ */ new Map();
+	for (const finding of review.findings ?? []) {
+		let findings = findingsByFile.get(finding.file);
+		if (!findings) {
+			findings = [];
+			findingsByFile.set(finding.file, findings);
+		}
+		findings.push(finding);
+	}
+	for (const file of review.files) {
+		process.stderr.write(`  - ${file}\n`);
+		for (const finding of findingsByFile.get(file) ?? []) {
+			process.stderr.write(`    - line ${finding.line}: ${finding.message}\n`);
+			process.stderr.write(`      ${finding.excerpt}\n`);
+		}
+	}
 	process.stderr.write(`\nPrompt for an LLM:\n${review.prompt.trim()}\n`);
 }
 runMain(defineCommand({
-	name: packageJson.name ?? "sdk-codemod",
+	name: packageName,
 	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
@@ -719,8 +1443,11 @@ runMain(defineCommand({
 - \`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.
+  entry has the affected \`files\`, optional file-local \`findings\`, and a
+  \`prompt\` — hand the prompt and files to an LLM (or follow it yourself) to
+  finish those cases.
+- \`runner\`: exact codemod runner identity. Local source builds include the
+  repository commit and the build command used to produce \`dist/index.js\`.
 
 Progress, warnings, and the LLM-review prompts are also printed to \`stderr\` in
 human-readable form, so \`stdout\` stays pure JSON for piping.`,
@@ -731,7 +1458,7 @@ human-readable form, so \`stdout\` stays pure JSON for piping.`,
 		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({
+	args: z.strictObject({
 		from: arg(z.string(), { description: "Source SDK version (the version before upgrade)" }),
 		to: arg(z.string(), { description: "Target SDK version (the version after upgrade)" }),
 		target: arg(z.string().default("."), { description: "Project directory to transform" }),
@@ -739,12 +1466,18 @@ human-readable form, so \`stdout\` stays pure JSON for piping.`,
 			alias: "d",
 			description: "Preview changes without modifying files"
 		})
-	}).strict(),
+	}),
 	run: async (args) => {
 		const targetPath = path.resolve(args.target);
 		const dryRun = args["dry-run"];
+		const runner = createRunnerMetadata({
+			packageName,
+			packageVersion,
+			packageRoot
+		});
 		const codemods = getApplicableCodemods(args.from, args.to);
 		const output = {
+			runner,
 			codemodsApplied: 0,
 			codemodsSkipped: 0,
 			filesModified: [],
@@ -782,6 +1515,6 @@ human-readable form, so \`stdout\` stays pure JSON for piping.`,
 		process.stdout.write(JSON.stringify(output) + "\n");
 		if (output.errors.length > 0) process.exit(1);
 	}
-}), { version: packageJson.version });
+}), { version: packageVersion });
 //#endregion
 export {};