@wocha/upgrade 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @wocha/upgrade
+
+Automated codemods for upgrading `@wocha/*` SDK packages. Detects installed versions, applies AST-level transforms for breaking changes, and updates `package.json` dependency ranges.
+
+## Usage
+
+```bash
+npx @wocha/upgrade
+```
+
+From the monorepo during development:
+
+```bash
+pnpm --filter @wocha/upgrade build
+node tools/upgrade/dist/index.js
+```
+
+### Example output
+
+```
+  @wocha/upgrade v0.1.0
+
+  Detected packages:
+    @wocha/react    0.1.0 → 0.2.0
+    @wocha/nextjs   0.1.0 → 0.2.0
+
+  Codemods to apply:
+    ✓ rename-provider (affects 3 files)
+    ✓ update-hook-return (affects 5 files)
+    ✓ middleware-config (affects 1 file)
+
+  ? Apply changes? (Y/n)
+
+  Applied 3 codemods across 9 files.
+  Updated package.json versions.
+
+  Run `pnpm install` to complete the upgrade.
+```
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview codemod changes without writing files or updating `package.json` |
+| `--package <name>` | Upgrade a single package, e.g. `@wocha/react` |
+| `--from <version>` | Override the detected current version |
+| `--to <version>` | Target version (default: latest from npm registry) |
+| `--cwd <path>` | Project directory to upgrade (default: current directory) |
+| `--yes`, `-y` | Apply changes without prompting |
+| `--help`, `-h` | Show help |
+
+## How it works
+
+1. **Detect** — Reads `package.json` and finds all `@wocha/*` dependencies.
+2. **Compare** — Queries the npm registry for the latest version of each package.
+3. **Plan** — Selects codemods whose `version` falls between your current and target versions.
+4. **Preview** — Runs each transform in dry mode to count affected files.
+5. **Apply** — Runs jscodeshift transforms on matching TypeScript/JSX files and bumps dependency versions.
+
+## Writing custom codemods
+
+Codemods live in `src/codemods/<version>/` and export a default jscodeshift transform:
+
+```typescript
+import type { API, FileInfo, Options } from "jscodeshift";
+
+export default function myTransform(file: FileInfo, api: API, _options: Options) {
+  const j = api.jscodeshift.withParser("tsx");
+  const root = j(file.source);
+  let changed = false;
+
+  // ... AST mutations ...
+
+  return changed ? root.toSource() : null;
+}
+```
+
+Register the codemod in `src/registry.ts`:
+
+```typescript
+{
+  id: "my-codemod",
+  version: "0.3.0",
+  package: "@wocha/react",
+  description: "Short description of the breaking change",
+  transform: "codemods/v0.3/my-codemod.js",
+}
+```
+
+The `version` field is the SDK release that **introduces** the breaking change. Codemods run when upgrading from a version **below** `version` to a version **at or above** it.
+
+Add the file to `tsup.config.ts` `entry` array so it is compiled to `dist/`.
+
+## Contributing new codemods
+
+1. Create a transform under `src/codemods/v<release>/`.
+2. Add an entry to `src/registry.ts` with the target package and release version.
+3. Add the file path to `tsup.config.ts` entries.
+4. Test against a sample project:
+
+   ```bash
+   pnpm build
+   node dist/index.js --dry-run --from 0.1.0 --to 0.2.0 --cwd ../../examples/react-quickstart
+   ```
+
+5. Document the breaking change in the SDK CHANGELOG.
+
+### Included example codemods (v0.1 → v0.2)
+
+| ID | Package | Change |
+|----|---------|--------|
+| `rename-provider` | `@wocha/react`, `@wocha/nextjs` | `WochaProvider` → `WochaAuthProvider` |
+| `update-hook-return` | `@wocha/react`, `@wocha/nextjs` | `useSession().session` → `useSession().data` |
+| `middleware-config` | `@wocha/nextjs` | `withWochaAuth({ publicPaths })` → `{ publicRoutes }` |
+
+These represent hypothetical breaking changes for demonstration purposes.
+
+## License
+
+Apache-2.0

package/dist/codemods/v0.2/middleware-config.js

@@ -0,0 +1,30 @@
+// src/codemods/v0.2/middleware-config.ts
+function renamePublicPathsKey(node) {
+  let changed = false;
+  for (const prop of node.properties) {
+    const isProperty = prop.type === "Property" || prop.type === "ObjectProperty";
+    if (isProperty && prop.key.type === "Identifier" && prop.key.name === "publicPaths") {
+      prop.key.name = "publicRoutes";
+      changed = true;
+    }
+  }
+  return changed;
+}
+function middlewareConfig(file, api, _options) {
+  const j = api.jscodeshift.withParser("tsx");
+  const root = j(file.source);
+  let changed = false;
+  root.find(j.CallExpression, {
+    callee: { type: "Identifier", name: "withWochaAuth" }
+  }).forEach((path) => {
+    for (const arg of path.node.arguments) {
+      if (arg?.type === "ObjectExpression" && renamePublicPathsKey(arg)) {
+        changed = true;
+      }
+    }
+  });
+  return changed ? root.toSource() : null;
+}
+export {
+  middlewareConfig as default
+};

package/dist/codemods/v0.2/rename-provider.js

@@ -0,0 +1,46 @@
+// src/codemods/v0.2/rename-provider.ts
+var WOCHA_PACKAGES = ["@wocha/react", "@wocha/nextjs"];
+function renameProvider(file, api, _options) {
+  const j = api.jscodeshift.withParser("tsx");
+  const root = j(file.source);
+  let changed = false;
+  root.find(j.ImportDeclaration).forEach((path) => {
+    const source = path.node.source.value;
+    if (typeof source !== "string" || !WOCHA_PACKAGES.includes(source)) {
+      return;
+    }
+    path.node.specifiers?.forEach((spec) => {
+      if (spec.type === "ImportSpecifier" && spec.imported.type === "Identifier" && spec.imported.name === "WochaProvider") {
+        spec.imported.name = "WochaAuthProvider";
+        if (spec.local?.type === "Identifier" && spec.local.name === "WochaProvider") {
+          spec.local.name = "WochaAuthProvider";
+        }
+        changed = true;
+      }
+    });
+  });
+  root.find(j.JSXIdentifier, { name: "WochaProvider" }).forEach((path) => {
+    path.node.name = "WochaAuthProvider";
+    changed = true;
+  });
+  root.find(j.Identifier, { name: "WochaProvider" }).forEach((path) => {
+    if (j(path).closest(j.ImportDeclaration).size() > 0) {
+      return;
+    }
+    if (j(path).closest(j.JSXOpeningElement).size() > 0) {
+      return;
+    }
+    if (j(path).closest(j.JSXClosingElement).size() > 0) {
+      return;
+    }
+    if (j(path).closest(j.JSXMemberExpression).size() > 0) {
+      return;
+    }
+    path.node.name = "WochaAuthProvider";
+    changed = true;
+  });
+  return changed ? root.toSource() : null;
+}
+export {
+  renameProvider as default
+};

package/dist/codemods/v0.2/update-hook-return.js

@@ -0,0 +1,23 @@
+// src/codemods/v0.2/update-hook-return.ts
+function updateHookReturn(file, api, _options) {
+  const j = api.jscodeshift.withParser("tsx");
+  const root = j(file.source);
+  let changed = false;
+  root.find(j.CallExpression, {
+    callee: { type: "Identifier", name: "useSession" }
+  }).forEach((callPath) => {
+    const parent = callPath.parent;
+    if (parent.node.type !== "MemberExpression") {
+      return;
+    }
+    const member = parent.node;
+    if (member.property.type === "Identifier" && member.property.name === "session" && member.object === callPath.node) {
+      member.property.name = "data";
+      changed = true;
+    }
+  });
+  return changed ? root.toSource() : null;
+}
+export {
+  updateHookReturn as default
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import chalk from "chalk";
+import { existsSync } from "fs";
+import { join as join3 } from "path";
+import prompts from "prompts";
+
+// src/detect.ts
+import { readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import semver2 from "semver";
+
+// src/registry.ts
+import semver from "semver";
+var codemods = [
+  {
+    id: "rename-provider",
+    version: "0.2.0",
+    package: "@wocha/react",
+    description: "Renames WochaProvider to WochaAuthProvider",
+    transform: "codemods/v0.2/rename-provider.js"
+  },
+  {
+    id: "rename-provider-nextjs",
+    version: "0.2.0",
+    package: "@wocha/nextjs",
+    description: "Renames WochaProvider to WochaAuthProvider",
+    transform: "codemods/v0.2/rename-provider.js"
+  },
+  {
+    id: "update-hook-return",
+    version: "0.2.0",
+    package: "@wocha/react",
+    description: "Changes useSession().session to useSession().data",
+    transform: "codemods/v0.2/update-hook-return.js"
+  },
+  {
+    id: "update-hook-return-nextjs",
+    version: "0.2.0",
+    package: "@wocha/nextjs",
+    description: "Changes useSession().session to useSession().data",
+    transform: "codemods/v0.2/update-hook-return.js"
+  },
+  {
+    id: "middleware-config",
+    version: "0.2.0",
+    package: "@wocha/nextjs",
+    description: "Renames publicPaths to publicRoutes in withWochaAuth config",
+    transform: "codemods/v0.2/middleware-config.js"
+  }
+];
+function codemodsForUpgrade(pkg, fromVersion, toVersion) {
+  return codemods.filter((mod) => {
+    if (mod.package !== pkg) {
+      return false;
+    }
+    return semver.gt(mod.version, fromVersion) && semver.lte(mod.version, toVersion);
+  });
+}
+function uniqueCodemods(mods) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const mod of mods) {
+    if (seen.has(mod.transform)) {
+      continue;
+    }
+    seen.add(mod.transform);
+    result.push(mod);
+  }
+  return result;
+}
+
+// src/detect.ts
+var WOCHA_SCOPE = "@wocha/";
+function readPackageJson(cwd) {
+  const path = join(cwd, "package.json");
+  const raw = readFileSync(path, "utf8");
+  return JSON.parse(raw);
+}
+function collectGreetPackages(pkg) {
+  const sections = [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies];
+  const found = /* @__PURE__ */ new Map();
+  for (const section of sections) {
+    if (!section) {
+      continue;
+    }
+    for (const [name, range] of Object.entries(section)) {
+      if (name.startsWith(WOCHA_SCOPE)) {
+        found.set(name, range);
+      }
+    }
+  }
+  return found;
+}
+function normalizeVersion(range) {
+  const cleaned = range.replace(/^[\^~>=<]+/, "");
+  const coerced = semver2.coerce(cleaned);
+  return coerced?.version ?? cleaned;
+}
+async function fetchLatestVersion(packageName) {
+  try {
+    const output = execSync(`npm view ${packageName} version --json`, {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    const parsed = JSON.parse(output);
+    const version = Array.isArray(parsed) ? parsed[parsed.length - 1] : parsed;
+    if (semver2.valid(version)) {
+      return version;
+    }
+  } catch {
+  }
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
+    if (res.ok) {
+      const data = await res.json();
+      if (data.version && semver2.valid(data.version)) {
+        return data.version;
+      }
+    }
+  } catch {
+  }
+  throw new Error(`Could not resolve latest version for ${packageName}`);
+}
+async function detectUpgrades(options) {
+  const pkgJson = readPackageJson(options.cwd);
+  const greetPackages = collectGreetPackages(pkgJson);
+  const results = [];
+  for (const [name, range] of greetPackages) {
+    if (options.packageFilter && name !== options.packageFilter) {
+      continue;
+    }
+    const currentVersion = options.fromVersion ?? normalizeVersion(range);
+    let latestVersion;
+    if (options.toVersion) {
+      latestVersion = options.toVersion;
+    } else {
+      try {
+        latestVersion = await fetchLatestVersion(name);
+      } catch {
+        continue;
+      }
+    }
+    if (!semver2.valid(currentVersion) || !semver2.valid(latestVersion)) {
+      continue;
+    }
+    if (semver2.gte(currentVersion, latestVersion)) {
+      continue;
+    }
+    const applicable = codemodsForUpgrade(name, currentVersion, latestVersion);
+    results.push({
+      package: name,
+      currentVersion,
+      latestVersion,
+      codemods: applicable
+    });
+  }
+  return results;
+}
+function updatePackageJsonVersions(cwd, upgrades, dryRun) {
+  const path = join(cwd, "package.json");
+  const pkgJson = readPackageJson(cwd);
+  let changed = false;
+  for (const upgrade of upgrades) {
+    const sections = ["dependencies", "devDependencies", "peerDependencies"];
+    for (const section of sections) {
+      const deps = pkgJson[section];
+      if (deps?.[upgrade.package]) {
+        const next = `^${upgrade.latestVersion}`;
+        if (deps[upgrade.package] !== next) {
+          deps[upgrade.package] = next;
+          changed = true;
+        }
+      }
+    }
+  }
+  if (changed && !dryRun) {
+    writeFileSync(path, `${JSON.stringify(pkgJson, null, 2)}
+`, "utf8");
+  }
+  return changed;
+}
+
+// src/runner.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import { globSync } from "glob";
+import jscodeshift from "jscodeshift";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var FILE_GLOBS = [
+  "**/*.{ts,tsx,js,jsx,mjs,cjs}",
+  "!**/node_modules/**",
+  "!**/dist/**",
+  "!**/.next/**",
+  "!**/build/**",
+  "!**/coverage/**"
+];
+function findSourceFiles(cwd) {
+  return globSync(FILE_GLOBS, { cwd, absolute: true, nodir: true });
+}
+async function loadTransform(transformPath) {
+  const absolute = join2(__dirname, transformPath);
+  const mod = await import(pathToFileURL(absolute).href);
+  return mod.default;
+}
+async function applyTransform(filePath, source, transform) {
+  const api = {
+    jscodeshift,
+    j: jscodeshift,
+    stats: () => {
+    },
+    report: () => {
+    }
+  };
+  const result = transform({ path: filePath, source }, api, {});
+  const resolved = result instanceof Promise ? await result : result;
+  if (typeof resolved !== "string" || resolved === source) {
+    return null;
+  }
+  return resolved;
+}
+async function previewCodemod(codemod, cwd) {
+  const transform = await loadTransform(codemod.transform);
+  const files = findSourceFiles(cwd);
+  const affected = [];
+  for (const file of files) {
+    const source = readFileSync2(file, "utf8");
+    const output = await applyTransform(file, source, transform);
+    if (output !== null) {
+      affected.push(file);
+    }
+  }
+  return affected;
+}
+async function planCodemods(codemods2, cwd) {
+  const plans = [];
+  for (const codemod of codemods2) {
+    const affectedFiles = await previewCodemod(codemod, cwd);
+    plans.push({ codemod, affectedFiles });
+  }
+  return plans;
+}
+async function runCodemods(plans, _cwd, dryRun) {
+  const results = [];
+  for (const plan of plans) {
+    if (plan.affectedFiles.length === 0) {
+      continue;
+    }
+    const transform = await loadTransform(plan.codemod.transform);
+    const filesModified = [];
+    for (const file of plan.affectedFiles) {
+      const source = readFileSync2(file, "utf8");
+      const output = await applyTransform(file, source, transform);
+      if (output !== null) {
+        filesModified.push(file);
+        if (!dryRun) {
+          writeFileSync2(file, output, "utf8");
+        }
+      }
+    }
+    results.push({
+      codemodId: plan.codemod.id,
+      filesModified,
+      dryRun
+    });
+  }
+  return results;
+}
+
+// src/cli.ts
+var VERSION = "0.1.0";
+function parseArgs(argv) {
+  const options = {
+    cwd: process.cwd(),
+    dryRun: false,
+    yes: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--yes":
+      case "-y":
+        options.yes = true;
+        break;
+      case "--package":
+        options.packageFilter = argv[++i];
+        break;
+      case "--from":
+        options.fromVersion = argv[++i];
+        break;
+      case "--to":
+        options.toVersion = argv[++i];
+        break;
+      case "--cwd":
+        options.cwd = argv[++i] ?? process.cwd();
+        break;
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+        break;
+      default:
+        break;
+    }
+  }
+  return options;
+}
+function printHelp() {
+  console.log(`
+Usage: wocha-upgrade [options]
+
+Automated codemods for upgrading @wocha SDK packages.
+
+Options:
+  --dry-run           Preview changes without writing files
+  --package <name>    Upgrade a specific @wocha package
+  --from <version>    Override detected current version
+  --to <version>      Target version (default: latest from npm)
+  --cwd <path>        Project directory (default: current directory)
+  --yes, -y           Apply changes without prompting
+  -h, --help          Show this help message
+`);
+}
+function collectCodemods(upgrades) {
+  const all = [];
+  for (const upgrade of upgrades) {
+    all.push(...upgrade.codemods);
+  }
+  return uniqueCodemods(all);
+}
+async function runCli(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+  if (!existsSync(join3(options.cwd, "package.json"))) {
+    console.error(chalk.red("Error: No package.json found in the current directory."));
+    return 1;
+  }
+  console.log();
+  console.log(chalk.bold(`  @wocha/upgrade v${VERSION}`));
+  console.log();
+  let upgrades;
+  try {
+    upgrades = await detectUpgrades({
+      cwd: options.cwd,
+      packageFilter: options.packageFilter,
+      fromVersion: options.fromVersion,
+      toVersion: options.toVersion
+    });
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+    return 1;
+  }
+  if (upgrades.length === 0) {
+    console.log(chalk.dim("  No @wocha packages need upgrading."));
+    console.log();
+    return 0;
+  }
+  console.log(chalk.bold("  Detected packages:"));
+  for (const upgrade of upgrades) {
+    console.log(
+      `    ${upgrade.package.padEnd(22)} ${chalk.yellow(upgrade.currentVersion)} \u2192 ${chalk.green(upgrade.latestVersion)}`
+    );
+  }
+  console.log();
+  const codemodList = collectCodemods(upgrades);
+  if (codemodList.length === 0) {
+    console.log(chalk.dim("  No codemods required for this upgrade."));
+    console.log();
+    return 0;
+  }
+  const plans = await planCodemods(codemodList, options.cwd);
+  console.log(chalk.bold("  Codemods to apply:"));
+  for (const plan of plans) {
+    const count = plan.affectedFiles.length;
+    const marker = count > 0 ? chalk.green("\u2713") : chalk.dim("\u25CB");
+    const suffix = count === 1 ? "1 file" : count > 0 ? `${count} files` : "no matching files";
+    console.log(`    ${marker} ${plan.codemod.id} ${chalk.dim(`(affects ${suffix})`)}`);
+  }
+  console.log();
+  if (options.dryRun) {
+    console.log(chalk.cyan("  Dry run \u2014 no files will be modified."));
+    console.log();
+  }
+  const hasChanges = plans.some((plan) => plan.affectedFiles.length > 0);
+  if (!hasChanges) {
+    console.log(chalk.dim("  No source files matched the codemods."));
+    console.log();
+    return 0;
+  }
+  let shouldApply = options.yes;
+  if (!shouldApply && !options.dryRun) {
+    const response = await prompts({
+      type: "confirm",
+      name: "apply",
+      message: "Apply changes?",
+      initial: true
+    });
+    shouldApply = response.apply === true;
+  } else if (options.dryRun) {
+    shouldApply = true;
+  }
+  if (!shouldApply) {
+    console.log(chalk.dim("  Upgrade cancelled."));
+    console.log();
+    return 0;
+  }
+  const results = await runCodemods(plans, options.cwd, options.dryRun);
+  const totalFiles = new Set(results.flatMap((r) => r.filesModified)).size;
+  const appliedCodemods = results.filter((r) => r.filesModified.length > 0).length;
+  console.log();
+  if (options.dryRun) {
+    console.log(
+      chalk.cyan(
+        `  Would apply ${appliedCodemods} codemod${appliedCodemods === 1 ? "" : "s"} across ${totalFiles} file${totalFiles === 1 ? "" : "s"}.`
+      )
+    );
+  } else {
+    console.log(
+      chalk.green(
+        `  Applied ${appliedCodemods} codemod${appliedCodemods === 1 ? "" : "s"} across ${totalFiles} file${totalFiles === 1 ? "" : "s"}.`
+      )
+    );
+    const pkgUpdated = updatePackageJsonVersions(options.cwd, upgrades, false);
+    if (pkgUpdated) {
+      console.log(chalk.green("  Updated package.json versions."));
+    }
+    console.log();
+    console.log(chalk.dim("  Run `pnpm install` to complete the upgrade."));
+  }
+  console.log();
+  return 0;
+}
+
+// src/index.ts
+runCli().then((code) => {
+  process.exit(code);
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@wocha/upgrade",
+  "version": "0.1.0",
+  "description": "Automated codemods for upgrading @wocha SDK packages",
+  "author": "Wocha",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wocha-dev/wocha.git",
+    "directory": "tools/upgrade"
+  },
+  "homepage": "https://github.com/wocha-dev/wocha/tree/main/tools/upgrade#readme",
+  "bugs": {
+    "url": "https://github.com/wocha-dev/wocha/issues"
+  },
+  "keywords": [
+    "wocha",
+    "authentication",
+    "codemod",
+    "upgrade",
+    "migration"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "wocha-upgrade": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "glob": "^11.0.0",
+    "jscodeshift": "^17.0.0",
+    "prompts": "^2.4.2",
+    "semver": "^7.6.0"
+  },
+  "devDependencies": {
+    "@types/jscodeshift": "^17.0.0",
+    "@types/node": "^22.0.0",
+    "@types/prompts": "^2.4.9",
+    "@types/semver": "^7.5.8",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}