Merge pull request #100 from torusresearch/feat/migration-inspection-cli

feat: add a read-only migration inspection command

Author: chaitanyapotti

.changeset/add-migration-inspector.md

@@ -0,0 +1,5 @@
+---
+"@toruslabs/torus-scripts": minor
+---
+
+Add the read-only `torus-scripts-upgrade` command. It inspects an old project and does not change files.

.cursor/skills/migrating-to-torus-cli/SKILL.md

@@ -0,0 +1 @@
+../../../packages/torus-scripts/skills/migrating-to-torus-cli/SKILL.md

README.md

@@ -5,7 +5,7 @@ Torus CLI and devtools
 ## Packages
 
 - [`@toruslabs/config`](packages/config): TypeScript profiles for libraries and applications.
-- [`@toruslabs/torus-scripts`](packages/torus-scripts): Vite+ build and format presets.
+- [`@toruslabs/torus-scripts`](packages/torus-scripts): Vite+ build and format presets. Use `torus-scripts-upgrade` to inspect an old project.
 - [`@toruslabs/oxlint-config-typescript`](packages/oxlint-config-typescript): JavaScript and TypeScript lint preset.
 - [`@toruslabs/oxlint-config-react`](packages/oxlint-config-react): React and Tailwind lint presets.
 - [`@toruslabs/oxlint-config-vue`](packages/oxlint-config-vue): Vue and Tailwind lint presets.

package.json

@@ -10,7 +10,7 @@
   ],
   "repository": "git@github.com:torusresearch/torus-cli.git",
   "scripts": {
-    "build": "vp run -r build --fail-if-no-match",
+    "build": "vp run -r --fail-if-no-match build",
     "check": "vp check",
     "typecheck": "tsc --noEmit -p packages/torus-scripts/tsconfig.json && tsc --noEmit -p packages/oxlint-config-typescript/tsconfig.json && tsc --noEmit -p packages/oxlint-config-react/tsconfig.json && tsc --noEmit -p packages/oxlint-config-vue/tsconfig.json && tsc --noEmit -p packages/oxlint-config-node/tsconfig.json",
     "test": "vp test",

packages/torus-scripts/README.md

@@ -58,6 +58,20 @@ For React, import `reactLintPreset` and `tailwindLintPreset` from `@toruslabs/ox
 
 The old `@toruslabs/eslint-config-*` packages are removed. Do not treat an Oxlint rule as equal to an old ESLint rule until you test it in your project.
 
+## Upgrade from the old CLI
+
+The package includes an agent skill at `skills/migrating-to-torus-cli/SKILL.md`. In a consumer project, read it at `node_modules/@toruslabs/torus-scripts/skills/migrating-to-torus-cli/SKILL.md`. To make it available as a project skill in Cursor, copy it to `.cursor/skills/migrating-to-torus-cli/SKILL.md` in that project. Keep the skill and this README from the same package version.
+
+Run `torus-scripts-upgrade <path>` to inspect an old project without changing files. It reports unsupported custom behavior and exits nonzero for those cases. Run `vp migrate` at the workspace root, not inside each package, and review its changes. The diagnostic does not run `vp migrate` for you.
+
+Replace the old commands:
+
+- `torus-scripts build` → define `pack` in the consumer's `vite.config.ts`, then run `vp pack`.
+- `torus-scripts lint` → select an Oxlint package, set root `lint` and `fmt` config, then run `vp check`.
+- `torus-scripts start` → set the consumer's Vite+ dev task. No shared dev server ships.
+- `torus-scripts release` → use Changesets at the repository root.
+- Lerna workspace tasks → run `vp run -r build` with explicit build tasks.
+
 ## TypeScript profiles
 
 `@toruslabs/config` exports `tsconfig.base.json`, `tsconfig.library.json`, and `tsconfig.node.json`. Replace `tsconfig.default.json` or `tsconfig.build.json` with the matching profile.

packages/torus-scripts/package.json

@@ -2,9 +2,13 @@
   "name": "@toruslabs/torus-scripts",
   "version": "8.1.0",
   "type": "module",
-  "description": "Vite+ build and format presets",
+  "description": "Vite+ build and format presets with a read-only migration diagnostic",
+  "bin": {
+    "torus-scripts-upgrade": "./dist/migrate/cli.mjs"
+  },
   "files": [
-    "dist"
+    "dist",
+    "skills/migrating-to-torus-cli/SKILL.md"
   ],
   "scripts": {
     "build": "vp pack",

packages/torus-scripts/skills/migrating-to-torus-cli/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: migrating-to-torus-cli
+description: Use when moving an existing consumer project from old Torus scripts, ESLint presets, or build tools to current Torus CLI and Vite+ presets.
+---
+
+# Migrate a consumer to Torus CLI
+
+Use `node_modules/@toruslabs/torus-scripts/README.md` in an installed consumer, or `packages/torus-scripts/README.md` in this repository, as the current source for presets, commands, and known lint gaps. A successful diagnostic does not prove that a project is ready to migrate.
+
+## Inspect before changes
+
+1. Find the consumer's workspace root. Check `git status`, Node and npm versions, lockfile, scripts, TypeScript profiles, build output, package entry points, lint rules, format rules, tests, and release steps.
+2. Use the installed `torus-scripts-upgrade <absolute-consumer-path>` diagnostic, or build this repository's `@toruslabs/torus-scripts` package first if working from source. The diagnostic reads files only. Record its output and exit code.
+3. Also inspect files that the diagnostic does not cover. In particular, check `package.json` scripts and entry paths, `eslint.config.*`, `tsconfig.json`, and README claims. If the diagnostic reports nothing, do not skip this step.
+4. Identify behavior the new presets do not provide. Stop and ask before removing or changing a required output format, path, browser target, polyfill, CSS behavior, release step, or custom transform. A diagnostic exit code of 1 requires separate review.
+
+## Migrate
+
+1. Agree on the required outputs and checks before editing. Preserve existing work; do not overwrite unrelated changes.
+2. Run `vp help` and `vp help migrate` for the installed Vite+ version. Run `vp migrate` at the consumer workspace root, not in each package. Review its diff before manual edits. If it cannot run, report why; do not claim it ran.
+3. Replace old `torus-scripts` commands with the documented `vp` tasks and package presets. Use a consumer-owned `vite.config.ts` for `pack`, `lint`, and `fmt`. Select the TypeScript profile that fits the package. Keep framework plugins in the consumer. If Vite+ cannot read a YAML Prettier config, compare its settings with `formatPreset()` before removing Prettier.
+4. Do not assume `libraryPreset` preserves CJS paths, old bundles, browser targets, polyfills, or CDN output. Compare built files with `main`, `module`, `types`, `exports`, `unpkg`, and `jsdelivr`. Test both `require` and ESM import. A new ESM build can fail if it imports named exports from a CommonJS dependency. Do not describe an external-import ESM build as a standalone CDN script.
+5. Replace removed ESLint packages only after testing equivalent Oxlint rules. Check Vue template-only and Vue script lint gaps separately. If Tailwind lint is used, merge `jsPlugins`, `rules`, and `settings` rather than spreading fragments over one another. Check that presets and TypeScript profiles exist in the target registry; use local packages only for an explicitly local test.
+6. Keep or replace release automation deliberately. The current guide uses Changesets at the workspace root; a standalone package can retain `npm publish` until its release process is set up.
+7. Review `vp migrate` warnings. It can skip YAML Prettier configs, ESLint rules, or plugin references and change Vitest versions. Check the new TypeScript profile for browser globals and stricter type errors. Check the selected Node runtime against preset engine requirements.
+
+## Monorepos moving off Lerna
+
+1. Map Lerna's workspace, build order, version, and publish tasks before removing it. Run `vp migrate` once at the workspace root. Give each package its own `build` task. Use `vp run -r build` at the root, and verify dependency order and each package's output. Put `vp run` options before the task name, as in `vp run -r --fail-if-no-match build`. `vp run` forwards arguments after the task name to the task, and npm lifecycle scripts fail on unknown options with `EUNKNOWNCONFIG`.
+2. Preserve public package paths before changing their manifests. For packages that expose `dist/lib.esm/index.js`, `dist/lib.cjs/index.js`, and `dist/lib.cjs/types/index.d.ts`, use a consumer-owned `vite.config.ts` with explicit output directories. Adapt this pattern to the installed Vite+ version:
+
+```ts
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  pack: {
+    entry: "src/index.ts",
+    format: {
+      esm: { outDir: "dist/lib.esm" },
+      cjs: { outDir: "dist/lib.cjs" },
+    },
+    dts: true,
+    outExtensions: () => ({ js: ".js", dts: ".d.ts" }),
+    copy: [{ from: "dist/lib.cjs/index.d.ts", to: "dist/lib.cjs/types" }],
+    sourcemap: true,
+  },
+});
+```
+
+3. Set up Changesets at the workspace root when replacing Lerna releases. Set `baseBranch` to the actual branch. Put only packages that must share a version in `fixed`. Use `access: "public"` for public scoped packages; decide whether private packages should version (`privatePackages.version`) and verify internal dependency updates. Check release scripts and published tarballs before removing old release tasks.
+4. Select `@toruslabs/config/tsconfig.library.json` for libraries and `tsconfig.node.json` for Node packages only after confirming those files exist in the installed registry version. For a standalone server, set `rootDir: "./src"` in its package tsconfig if the shared profile resolves it against the wrong directory. Check output layout and type errors after changing profiles.
+5. If a required preset has not been published, test with local packages only by explicit agreement. Keep local paths out of committed manifests and lockfiles. Separate local build results from clean registry installation; do not call the migration complete until the registry install and package checks pass.
+
+## Verify and report
+
+Run the consumer's install, build, lint/check, typecheck, and tests when available. Inspect package contents and import/require entry points if published files changed. If browser tests fail, separate missing browser executables from test failures and browser timeouts. Report each command and result, preserved behavior, manual follow-up, and any check you could not run. Never report a migration as complete if package outputs or lint coverage remain unverified.
+
+Example: A project can get “No known unsupported behavior detected” while its `package.json` entry paths still point at old bundle folders. Inspect the scripts and published paths before changing it.

packages/torus-scripts/src/migrate/cli.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+import { argv, stderr, stdout } from "node:process";
+
+import { exitCodes } from "./model.js";
+
+function isMissingPeer(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ERR_MODULE_NOT_FOUND" && error.message.includes("'vite-plus'");
+}
+
+try {
+  // run.js loads the vite-plus peer dependency. A dynamic import lets a missing peer exit as a failure, not as "blocked".
+  const { run } = await import("./run.js");
+  process.exitCode = await run(argv.slice(2), {
+    stdout: (text) => stdout.write(text),
+    stderr: (text) => stderr.write(text),
+  });
+} catch (error) {
+  const message = isMissingPeer(error)
+    ? "torus-scripts-upgrade needs the vite-plus peer dependency. Install vite-plus in this project, then run the command again."
+    : `torus-scripts-upgrade failed: ${error instanceof Error ? error.message : String(error)}`;
+  stderr.write(`${message}\n`);
+  process.exitCode = exitCodes.failed;
+}

packages/torus-scripts/src/migrate/inspect.ts

@@ -0,0 +1,46 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+
+import { inspectManifest } from "./manifest.js";
+import type { Finding } from "./model.js";
+import { inspectRollupConfig } from "./rollup.js";
+import { type ProjectFile, walkProject } from "./walk.js";
+
+export interface InspectionOptions {
+  maxDirectories?: number;
+}
+
+async function inspectFile(file: ProjectFile, relativePath: string): Promise<Finding[]> {
+  switch (file.kind) {
+    case "rollup":
+      return [{ code: "config", path: relativePath }, ...(await inspectRollupConfig(file.path, relativePath))];
+    case "manifest":
+      return inspectManifest(file.path, relativePath);
+    case "torus-config":
+      return [{ code: "torus-config", path: relativePath }];
+    case "lerna":
+      return [{ code: "lerna", path: relativePath }];
+    case "config":
+      return [{ code: "config", path: relativePath }];
+    case "escaped-link":
+      return [{ code: "escaped-symlink", path: relativePath }];
+    default: {
+      const unhandled: never = file.kind;
+      throw new Error(`Unhandled project file kind: ${String(unhandled)}`);
+    }
+  }
+}
+
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : Number(left > right);
+}
+
+export async function inspectProject(root: string, { maxDirectories = 10_000 }: InspectionOptions = {}): Promise<Finding[]> {
+  const projectRoot = path.resolve(root);
+  if (!(await stat(projectRoot)).isDirectory()) throw new Error(`Inspection root is not a directory: ${projectRoot}`);
+
+  const { files, truncated } = await walkProject(projectRoot, maxDirectories);
+  const findings = (await Promise.all(files.map((file) => inspectFile(file, path.relative(projectRoot, file.path))))).flat();
+  if (truncated) findings.push({ code: "truncated", path: ".", detail: `${maxDirectories} directories` });
+  return findings.sort((left, right) => compareText(left.path, right.path) || compareText(left.code, right.code));
+}

packages/torus-scripts/src/migrate/manifest.ts

@@ -0,0 +1,75 @@
+import { readFile } from "node:fs/promises";
+
+import type { Code, Finding } from "./model.js";
+
+interface Manifest {
+  commands: Set<string>;
+  dependencies: Map<string, string[]>;
+  hasWorkspaces: boolean;
+}
+
+const dependencyFields = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringEntries(value: unknown): [string, string][] {
+  if (!isRecord(value)) return [];
+  return Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string");
+}
+
+function commandWords(script: string): string[] {
+  return script
+    .split(/[\s;&|()]+/)
+    .filter(Boolean)
+    .map((word) => word.replace(/^(?:.*\/)?node_modules\/\.bin\//, ""));
+}
+
+async function readManifest(manifestPath: string): Promise<Manifest | undefined> {
+  let data: unknown;
+  try {
+    data = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+  if (!isRecord(data)) return undefined;
+
+  const dependencies = new Map<string, string[]>();
+  for (const field of dependencyFields) {
+    for (const [name, spec] of stringEntries(data[field])) dependencies.set(name, [...(dependencies.get(name) ?? []), spec]);
+  }
+  return {
+    commands: new Set(stringEntries(data.scripts).flatMap(([, script]) => commandWords(script))),
+    dependencies,
+    hasWorkspaces: data.workspaces !== undefined,
+  };
+}
+
+function torusScriptsSpecCode(spec: string): Code | undefined {
+  const target = spec.replace(/^npm:@toruslabs\/torus-scripts@/, "");
+  if (/^(?:workspace|file|link|portal):/.test(target)) return "local-dependency";
+  const major = /^\s*[~^]?\s*(?:>=?\s*)?v?(\d+)/.exec(target)?.[1];
+  if (major === undefined) return "unknown-dependency-version";
+  return Number(major) < 8 ? "legacy-dependency" : undefined;
+}
+
+export async function inspectManifest(manifestPath: string, relativePath: string): Promise<Finding[]> {
+  const manifest = await readManifest(manifestPath);
+  if (manifest === undefined) return [{ code: "unreadable-manifest", path: relativePath }];
+
+  const findings: Finding[] = [];
+  const add = (code: Code, detail?: string) => findings.push({ code, path: relativePath, ...(detail === undefined ? {} : { detail }) });
+  const uses = (tool: string) => manifest.dependencies.has(tool) || manifest.commands.has(tool);
+
+  if (relativePath !== "package.json" && manifest.hasWorkspaces) add("nested-workspaces");
+  if (uses("lerna")) add("lerna");
+  if (uses("release-it")) add("release-it");
+  if (manifest.commands.has("torus-scripts")) add("legacy-commands");
+  for (const spec of manifest.dependencies.get("@toruslabs/torus-scripts") ?? []) {
+    const code = torusScriptsSpecCode(spec);
+    if (code !== undefined) add(code, spec);
+  }
+  return findings;
+}