@ripast/cli 0.3.0 → 0.5.0

package/bin/ripast.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { spawnSync } from 'node:child_process'
-import { existsSync, readFileSync } from 'node:fs'
-import { createRequire } from 'node:module'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import process from 'node:process'
+import spawn from 'cross-spawn'
 
 const FRAMEWORK_MARKERS = {
   vue: ['vue', 'nuxt', '@nuxt/kit'],
@@ -42,25 +42,50 @@ function ensureAdapters(needed) {
   if (!needed.length)
     return
 
-  const require = createRequire(import.meta.url)
   const missing = []
   for (const name of needed) {
     try {
-      require.resolve(`@ripast/${name}`)
+      if (!existsSync(new URL(import.meta.resolve(`@ripast/${name}`))))
+        missing.push(`@ripast/${name}`)
     }
     catch { missing.push(`@ripast/${name}`) }
   }
   if (!missing.length)
     return
 
-  const args = ['--yes', '--package=@ripast/cli', ...missing.map(p => `--package=${p}`), '--', 'ripast', ...process.argv.slice(2)]
-  const res = spawnSync('npx', args, {
-    stdio: 'inherit',
-    env: { ...process.env, RIPAST_REEXEC: '1' },
-  })
+  const args = ['dlx', '--package=@ripast/cli', ...missing.map(p => `--package=${p}`), 'ripast', ...process.argv.slice(2)]
+  const options = { stdio: 'inherit', env: { ...process.env, RIPAST_REEXEC: '1' } }
+  let manager = 'pnpm'
+  let res = spawn.sync(manager, args, options)
+  if (res.error?.code === 'ENOENT') {
+    manager = 'npm'
+    // Keep npm's project metadata separate. The executed CLI still uses the caller's cwd.
+    const prefix = mkdtempSync(join(tmpdir(), 'ripast-adapters-'))
+    try {
+      res = spawn.sync(manager, ['exec', '--yes', `--prefix=${prefix}`, '--package=@ripast/cli', ...missing.map(p => `--package=${p}`), '--', 'ripast', ...process.argv.slice(2)], options)
+    }
+    finally { rmSync(prefix, { recursive: true, force: true }) }
+  }
+  if (res.error) {
+    if (res.error.code === 'ENOENT') {
+      process.stderr.write([
+        `ripast: Neither pnpm nor npm was found on PATH. Missing adapters: ${missing.join(', ')}.`,
+        'If either package manager is installed, add its directory to PATH.',
+        'Install pnpm: https://pnpm.io/installation',
+        'Then run pnpm --version and retry.',
+        'After installing npm, you can install the CLI and adapters together:',
+        `  npm install -g @ripast/cli ${missing.join(' ')}`,
+        'For script-only rename, move, or rename-file commands, retry with --no-vue.',
+        '',
+      ].join('\n'))
+    }
+    else {
+      process.stderr.write(`ripast: Could not start ${manager}: ${res.error.message}\n`)
+    }
+  }
   process.exit(res.status ?? 1)
 }
 
-ensureAdapters(detectFrameworks(process.cwd()))
+ensureAdapters(process.argv.includes('--no-vue') ? [] : detectFrameworks(process.cwd()))
 
 await import('../dist/cli.mjs')

package/dist/cli.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/cli.mjs

@@ -4,10 +4,79 @@ import process from "node:process";
 import { buildComponentDetail, buildComponentInventory, buildDeclarationTree, buildDoctorFixes, buildScanGraph, buildUnusedDeclarations, formatAgentDeclarationTree, formatAgentDoctorReport, formatAgentFileScanHits, formatAgentHits, formatAgentInventory, formatAgentScanHits, formatDeclarationTree, formatDetail, formatDoctorReport, formatFileScanHits, formatHits, formatInventory, formatRegressions, formatScanGraph, formatScanHits, formatUnusedDeclarations, getChangedFiles, printDiffs, resolveVerifyMode, runCssClassFileScan, runCssClassRename, runCssClassScan, runDelete, runDoctor, runMove, runRename, runRenameFile, runReplace, runVueTemplateUnwrap, runVueTemplateWrap, scan, summarize, writeChanges } from "@ripast/core";
 import { defineCommand, runMain } from "citty";
 import { agent, isAgent } from "std-env";
+function defineStrictCommand(definition) {
+	return defineCommand({
+		...definition,
+		async setup(context) {
+			if (!definition.subCommands) {
+				const args = (typeof definition.args === "function" ? await definition.args() : await definition.args) ?? {};
+				const allowed = /* @__PURE__ */ new Set(["_"]);
+				const options = /* @__PURE__ */ new Set();
+				let positionalCount = 0;
+				for (const [name, arg] of Object.entries(args)) {
+					const alias = "alias" in arg ? arg.alias : void 0;
+					const aliases = typeof alias === "string" ? [alias] : alias ?? [];
+					for (const key of [name, ...aliases]) {
+						const variants = [
+							key,
+							key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`),
+							key.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
+						];
+						for (const variant of variants) {
+							allowed.add(variant);
+							if (arg.type !== "positional") options.add(variant);
+						}
+					}
+					if (arg.type === "positional") positionalCount++;
+				}
+				for (const name of Object.keys(context.args)) if (!allowed.has(name)) throw new Error(`Unknown option: --${name}. Run the command with --help.`);
+				for (const token of context.rawArgs) {
+					if (token === "--") break;
+					if (!token.startsWith("--")) continue;
+					const name = token.slice(2).split("=")[0].replace(/^no-/, "");
+					if (!options.has(name)) throw new Error(`Unknown option: --${name}. Run the command with --help.`);
+				}
+				const extra = context.args._[positionalCount];
+				if (extra !== void 0) throw new Error(`Unexpected positional argument: ${extra}. Run the command with --help.`);
+			}
+			await definition.setup?.(context);
+		}
+	});
+}
 const globArg = {
 	type: "string",
 	description: "File glob(s), comma-separated. Prefix with ! to exclude (e.g. \"*.ts,!.nuxt/**,!**/*.d.ts\"). Defaults to *.ts,*.tsx,*.vue,...  Respects .gitignore."
 };
+function splitGlobs(value) {
+	const globs = [];
+	let start = 0;
+	let braces = 0;
+	let characterClass = false;
+	let escaped = false;
+	for (let index = 0; index < value.length; index++) {
+		const character = value[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (character === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (character === "[") characterClass = true;
+		else if (character === "]") characterClass = false;
+		else if (!characterClass) {
+			if (character === "{") braces++;
+			else if (character === "}") braces--;
+			else if (character === "," && braces === 0) {
+				globs.push(value.slice(start, index));
+				start = index + 1;
+			}
+		}
+	}
+	globs.push(value.slice(start));
+	return globs;
+}
 const applyArg = {
 	type: "boolean",
 	default: false,
@@ -25,7 +94,7 @@ const verifyModeArg = {
 const vueArg = {
 	type: "boolean",
 	default: true,
-	description: "Enable Volar pass for .vue files. Disable with --no-vue to force pure ts-morph behavior."
+	description: "Enable Volar pass for .vue files. Disable with --no-vue to skip the Volar pass."
 };
 const jsonArg = {
 	type: "boolean",
@@ -103,7 +172,7 @@ function resolveExportFilter(raw) {
 	}
 	return raw;
 }
-const scanCmd = defineCommand({
+const scanCmd = defineStrictCommand({
 	meta: {
 		name: "scan",
 		description: "rg-prefilter + AST-classify occurrences of an identifier."
@@ -131,7 +200,7 @@ const scanCmd = defineCommand({
 	run({ args }) {
 		const { agentProfile } = resolveProfile(args.profile);
 		const opts = {
-			glob: args.glob ? args.glob.split(",") : void 0,
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
 			kinds: args.kind ? args.kind.split(",") : void 0
 		};
 		if (args.graph) {
@@ -147,10 +216,10 @@ const scanCmd = defineCommand({
 		process.stdout.write(`${formatHits(hits, args.json)}\n`);
 	}
 });
-const renameCmd = defineCommand({
+const renameCmd = defineStrictCommand({
 	meta: {
 		name: "rename",
-		description: "Scope-aware symbol rename via ts-morph (handles type-only imports, shadowing, JSX)."
+		description: "Scope-aware symbol rename via the native TypeScript server (handles type-only imports, shadowing, JSX)."
 	},
 	args: {
 		from: {
@@ -183,7 +252,7 @@ const renameCmd = defineCommand({
 		const verifyMode = resolveCliVerifyMode(args.verify, args.verifyMode);
 		emitResult(await runRename(args.from, args.to, {
 			tsconfig: args.tsconfig,
-			glob: args.glob ? args.glob.split(",") : void 0,
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
 			verify: verifyMode,
 			scope: args.scope,
 			allowMultiple: args.all,
@@ -191,7 +260,7 @@ const renameCmd = defineCommand({
 		}), !!args.apply, verifyMode !== "none", !!args.json, resolveProfile(args.profile).agentProfile);
 	}
 });
-const replaceCmd = defineCommand({
+const replaceCmd = defineStrictCommand({
 	meta: {
 		name: "replace",
 		description: "Replace an imported symbol with another project export; updates imports and call sites."
@@ -205,12 +274,15 @@ const replaceCmd = defineCommand({
 			type: "positional",
 			required: true
 		},
-		"tsconfig": { type: "string" },
 		"glob": globArg,
 		"target-scope": {
 			type: "string",
 			description: "Restrict target symbol resolution to a single file when multiple files export the same name."
 		},
+		"target-import": {
+			type: "string",
+			description: "Import specifier for the validated replacement, including framework aliases."
+		},
 		"apply": applyArg,
 		"verify": verifyArg,
 		"verifyMode": verifyModeArg,
@@ -220,14 +292,14 @@ const replaceCmd = defineCommand({
 	async run({ args }) {
 		const verifyMode = resolveCliVerifyMode(args.verify, args.verifyMode);
 		emitResult(await runReplace(args.from, args.to, {
-			tsconfig: args.tsconfig,
-			glob: args.glob ? args.glob.split(",") : void 0,
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
 			verify: verifyMode,
-			targetScope: args["target-scope"]
+			targetScope: args["target-scope"],
+			targetImport: args["target-import"]
 		}), !!args.apply, verifyMode !== "none", !!args.json, resolveProfile(args.profile).agentProfile);
 	}
 });
-const treeCmd = defineCommand({
+const treeCmd = defineStrictCommand({
 	meta: {
 		name: "tree",
 		description: "Print a project declaration tree from top-level AST declarations, grouped by file."
@@ -245,7 +317,7 @@ const treeCmd = defineCommand({
 		const { agentProfile } = resolveProfile(args.profile);
 		const exportFilter = args.exports == null ? agentProfile ? "exported" : "all" : resolveExportFilter(args.exports);
 		const tree = buildDeclarationTree({
-			glob: args.glob ? args.glob.split(",") : void 0,
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
 			exports: agentProfile ? "all" : exportFilter
 		});
 		if (agentProfile && !args.json) {
@@ -256,7 +328,7 @@ const treeCmd = defineCommand({
 		process.stdout.write(`${formatDeclarationTree(tree, !!args.json)}\n`);
 	}
 });
-const unusedCmd = defineCommand({
+const unusedCmd = defineStrictCommand({
 	meta: {
 		name: "unused",
 		description: "Find unreferenced top-level declarations."
@@ -265,22 +337,20 @@ const unusedCmd = defineCommand({
 		glob: globArg,
 		exports: {
 			type: "string",
-			description: "Declaration filter: all, exported, or local. Defaults to local."
+			description: "Declaration filter: all, exported, or local. Defaults to exported (unused local declarations are already caught by tsc noUnusedLocals)."
 		},
-		tsconfig: { type: "string" },
 		json: jsonArg
 	},
-	run({ args }) {
-		const exportFilter = args.exports == null ? "local" : resolveExportFilter(args.exports);
-		const unused = buildUnusedDeclarations({
-			glob: args.glob ? args.glob.split(",") : void 0,
-			exports: exportFilter,
-			tsconfig: args.tsconfig
+	async run({ args }) {
+		const exportFilter = args.exports == null ? "exported" : resolveExportFilter(args.exports);
+		const unused = await buildUnusedDeclarations({
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
+			exports: exportFilter
 		});
 		process.stdout.write(`${formatUnusedDeclarations(unused, !!args.json)}\n`);
 	}
 });
-const moveCmd = defineCommand({
+const moveCmd = defineStrictCommand({
 	meta: {
 		name: "move",
 		description: "Move a top-level exported symbol between files; rewrites import sites project-wide."
@@ -317,7 +387,7 @@ const moveCmd = defineCommand({
 		}), !!args.apply, verifyMode !== "none", !!args.json, resolveProfile(args.profile).agentProfile);
 	}
 });
-const deleteCmd = defineCommand({
+const deleteCmd = defineStrictCommand({
 	meta: {
 		name: "delete",
 		description: "Delete an unused top-level declaration from a file; refuses if references remain."
@@ -332,7 +402,6 @@ const deleteCmd = defineCommand({
 			required: true,
 			description: "Source file path."
 		},
-		tsconfig: { type: "string" },
 		apply: applyArg,
 		verify: verifyArg,
 		verifyMode: verifyModeArg,
@@ -341,14 +410,12 @@ const deleteCmd = defineCommand({
 	},
 	async run({ args }) {
 		const verifyMode = resolveCliVerifyMode(args.verify, args.verifyMode);
-		emitResult(await runDelete(args.symbol, args.from, {
-			tsconfig: args.tsconfig,
-			verify: verifyMode
-		}), !!args.apply, verifyMode !== "none", !!args.json, resolveProfile(args.profile).agentProfile);
+		emitResult(await runDelete(args.symbol, args.from, { verify: verifyMode }), !!args.apply, verifyMode !== "none", !!args.json, resolveProfile(args.profile).agentProfile);
 	}
 });
 function emitResult(r, apply, verify = false, json = false, agentProfile = false) {
 	const s = summarize(r.changes);
+	const warnings = r.warnings ?? [];
 	if (json) {
 		const blockedByRegression = verify && apply && r.regressions.length > 0;
 		const wrote = apply && !blockedByRegression;
@@ -365,12 +432,14 @@ function emitResult(r, apply, verify = false, json = false, agentProfile = false
 				before: c.before,
 				after: c.after
 			})),
-			regressions: r.regressions
+			regressions: r.regressions,
+			warnings
 		};
 		process.stdout.write(`${JSON.stringify(payload)}\n`);
 		if (blockedByRegression) process.exit(1);
 		return;
 	}
+	for (const w of warnings) process.stderr.write(`warning: ${w}\n`);
 	if (agentProfile) {
 		const blockedByRegression = verify && apply && r.regressions.length > 0;
 		process.stdout.write(`${profileHeader()}\n`);
@@ -413,7 +482,7 @@ function emitResult(r, apply, verify = false, json = false, agentProfile = false
 	const suffix = apply ? "" : " (dry run, pass --apply to write)";
 	process.stdout.write(`\n${r.changes.length}/${r.scanned} files changed${suffix}\n`);
 }
-const renameFileCmd = defineCommand({
+const renameFileCmd = defineStrictCommand({
 	meta: {
 		name: "rename-file",
 		description: "Rename a file and rewrite every import site (including .vue consumers and component-name refs)."
@@ -431,6 +500,7 @@ const renameFileCmd = defineCommand({
 		apply: applyArg,
 		verify: verifyArg,
 		verifyMode: verifyModeArg,
+		vue: vueArg,
 		profile: profileArg,
 		json: jsonArg
 	},
@@ -440,7 +510,8 @@ const renameFileCmd = defineCommand({
 		if (recovered.warning) process.stderr.write(`warning: ${recovered.warning}\n`);
 		const r = await runRenameFile(recovered.old, recovered.new, {
 			tsconfig: args.tsconfig,
-			verify: verifyMode
+			verify: verifyMode,
+			vue: args.vue
 		});
 		const apply = !!args.apply;
 		const verify = verifyMode !== "none";
@@ -527,7 +598,7 @@ const renameFileCmd = defineCommand({
 		process.stdout.write(`\n${r.changes.length} consumer file(s) updated${suffix}\n`);
 	}
 });
-const cssClassRenameCmd = defineCommand({
+const cssClassRenameCmd = defineStrictCommand({
 	meta: {
 		name: "css-class-rename",
 		description: "Rename CSS utility class token(s) across strings, Vue templates, and @apply. Pass a single \"from to\" pair, or --map <file.json> for bulk. No typecheck verify."
@@ -551,7 +622,8 @@ const cssClassRenameCmd = defineCommand({
 		json: jsonArg
 	},
 	async run({ args }) {
-		emitResult(await runCssClassRename(buildRenameMap(args.from, args.to, args.map), { glob: args.glob ? args.glob.split(",") : void 0 }), !!args.apply, false, !!args.json, resolveProfile(args.profile).agentProfile);
+		const map = buildRenameMap(args.from, args.to, args.map);
+		emitResult(await runCssClassRename(map, { glob: args.glob ? splitGlobs(args.glob) : void 0 }), !!args.apply, false, !!args.json, resolveProfile(args.profile).agentProfile);
 	}
 });
 function buildRenameMap(from, to, mapPath) {
@@ -565,7 +637,7 @@ function buildRenameMap(from, to, mapPath) {
 		process.stderr.write(`ripast css-class-rename: missing input. Pass "from to" positionals or --map <file.json>.\n`);
 		process.exit(2);
 	}
-	if (hasPair) return new Map([[from, to]]);
+	if (hasPair) return /* @__PURE__ */ new Map([[from, to]]);
 	const raw = readFileSync(resolve(process.cwd(), mapPath), "utf8");
 	let parsed;
 	try {
@@ -596,7 +668,7 @@ function buildRenameMap(from, to, mapPath) {
 	}
 	return new Map(entries);
 }
-const cssClassScanCmd = defineCommand({
+const cssClassScanCmd = defineStrictCommand({
 	meta: {
 		name: "css-class-scan",
 		description: "Tokenize every class site (strings, Vue class attrs, @apply) and emit sortable token or file frequency lists. Use --sort count-asc for rare tokens or --by file for files introducing the most unique classes."
@@ -622,7 +694,7 @@ const cssClassScanCmd = defineCommand({
 		const { agentProfile } = resolveProfile(args.profile);
 		const by = resolveCssClassScanGroup(args.by);
 		const base = {
-			glob: args.glob ? args.glob.split(",") : void 0,
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
 			pattern: args.pattern ? args.pattern.split(",") : void 0
 		};
 		if (by === "file") {
@@ -681,7 +753,7 @@ const rootOnlyArg = {
 	default: false,
 	description: "Match only template-root elements (direct children of <template>); ignores nested matches."
 };
-const vueTemplateWrapCmd = defineCommand({
+const vueTemplateWrapCmd = defineStrictCommand({
 	meta: {
 		name: "vue-template-wrap",
 		description: "Wrap every matching element in a Vue <template> with a parent component. Selector: \"Tag\" or \"Tag[attr]\" / \"Tag[attr=value]\". Wrapper: tag name with optional inline attributes (e.g. \"ProPageStates name=\\\"lh\\\"\")."
@@ -704,13 +776,13 @@ const vueTemplateWrapCmd = defineCommand({
 	},
 	async run({ args }) {
 		emitResult(await runVueTemplateWrap(args.selector, args.wrapper, {
-			glob: args.glob ? args.glob.split(",") : void 0,
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
 			scope: args.scope,
 			rootOnly: args.rootOnly
 		}), !!args.apply, false, !!args.json, resolveProfile(args.profile).agentProfile);
 	}
 });
-const vueTemplateUnwrapCmd = defineCommand({
+const vueTemplateUnwrapCmd = defineStrictCommand({
 	meta: {
 		name: "vue-template-unwrap",
 		description: "Remove every matching element in a Vue <template>, hoisting its children up one level. Inverse of vue-template-wrap."
@@ -729,13 +801,13 @@ const vueTemplateUnwrapCmd = defineCommand({
 	},
 	async run({ args }) {
 		emitResult(await runVueTemplateUnwrap(args.selector, {
-			glob: args.glob ? args.glob.split(",") : void 0,
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
 			scope: args.scope,
 			rootOnly: args.rootOnly
 		}), !!args.apply, false, !!args.json, resolveProfile(args.profile).agentProfile);
 	}
 });
-const componentsCmd = defineCommand({
+const componentsCmd = defineStrictCommand({
 	meta: {
 		name: "components",
 		description: "Inventory Vue/Nuxt components (manifest-first, glob fallback); flag shadowed entries and duplicate-name groups. Pass a name positional for the focused view."
@@ -762,7 +834,7 @@ const componentsCmd = defineCommand({
 	async run({ args }) {
 		const { agentProfile } = resolveProfile(args.profile);
 		const opts = {
-			glob: args.glob ? args.glob.split(",") : void 0,
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
 			source: resolveComponentsSource(args.source)
 		};
 		if (args.name) {
@@ -811,7 +883,100 @@ function resolveComponentsSource(raw) {
 	}
 	return raw;
 }
-runMain(defineCommand({
+const doctorCmd = defineStrictCommand({
+	meta: {
+		name: "doctor",
+		description: "Health checks over the AST graph. Suppress per-file with `// ripast-doctor-ignore-file[: c1,c2]` or per-line with `// ripast-doctor-ignore-next-line[: c1,c2]`."
+	},
+	args: {
+		glob: globArg,
+		checks: {
+			type: "string",
+			description: "Comma-separated subset: dangling-reexport, stale-reexport, stale-import, duplicate-export, orphan-file, orphan-test, inconsistent-import-path, circular-dep, phantom-component, shadowed-component, cross-realm-import, stale-nuxt-config-ref. Default: all (adapter checks run when their framework is detected)."
+		},
+		entry: {
+			type: "string",
+			description: "Comma-separated entry files exempt from orphan check (relative to cwd)."
+		},
+		fix: {
+			type: "boolean",
+			default: false,
+			description: "Compute safe fixes for inconsistent-import-path and dangling-reexport findings."
+		},
+		apply: applyArg,
+		changed: {
+			type: "string",
+			description: "Report only findings on files changed vs git. No value = dirty working tree (staged+unstaged+untracked). With value (e.g. main, HEAD~1) = diff against that ref. Full project is still scanned so cross-file checks stay accurate."
+		},
+		profile: profileArg,
+		json: jsonArg
+	},
+	async run({ args }) {
+		const { agentProfile } = resolveProfile(args.profile);
+		const checks = args.checks ? args.checks.split(",") : void 0;
+		const entry = args.entry ? args.entry.split(",") : void 0;
+		let changedFiles;
+		if (args.changed != null) {
+			const ref = typeof args.changed === "string" && args.changed !== "" && args.changed !== "true" ? args.changed : void 0;
+			changedFiles = getChangedFiles({
+				cwd: process.cwd(),
+				ref
+			});
+			if (!changedFiles.length) {
+				process.stderr.write(`ripast doctor: --changed${ref ? ` ${ref}` : ""} matched no files; nothing to report.\n`);
+				return;
+			}
+		}
+		const report = await runDoctor({
+			glob: args.glob ? splitGlobs(args.glob) : void 0,
+			checks,
+			entry,
+			changedFiles
+		});
+		if (args.fix) {
+			const fix = buildDoctorFixes(report, process.cwd());
+			if (args.json) {
+				process.stdout.write(`${JSON.stringify({
+					findings: report.findings,
+					filesScanned: report.filesScanned,
+					fix: {
+						applied: !!args.apply,
+						files: fix.changes.length,
+						fixed: fix.fixed,
+						skipped: fix.skipped.length
+					},
+					changes: args.apply ? void 0 : fix.changes.map((c) => ({
+						path: c.rel,
+						before: c.before,
+						after: c.after
+					}))
+				})}\n`);
+				if (args.apply && fix.changes.length) writeChanges(fix.changes);
+				if (fix.skipped.length) process.exit(1);
+				return;
+			}
+			const s = summarize(fix.changes);
+			process.stdout.write(`doctor --fix: ${fix.fixed.length} fixable / ${fix.skipped.length} non-fixable findings\n`);
+			process.stdout.write(`${fix.changes.length} file${fix.changes.length === 1 ? "" : "s"}, +${s.linesAdded} -${s.linesRemoved} lines\n\n`);
+			if (!args.apply) {
+				printDiffs(fix.changes);
+				process.stdout.write(`\n(dry run, pass --apply to write)\n`);
+			} else {
+				writeChanges(fix.changes);
+				for (const c of fix.changes) process.stdout.write(`wrote ${c.rel}\n`);
+			}
+			if (fix.skipped.length) process.exit(1);
+			return;
+		}
+		if (agentProfile && !args.json) {
+			process.stdout.write(`${profileHeader()}\n${formatAgentDoctorReport(report)}\n`);
+			return;
+		}
+		process.stdout.write(formatDoctorReport(report, !!args.json));
+		if (report.findings.length) process.exit(1);
+	}
+});
+runMain(defineStrictCommand({
 	meta: {
 		name: "ripast",
 		description: "AST-aware refactor primitives. ripgrep-prefiltered, dry-run by default."
@@ -820,99 +985,7 @@ runMain(defineCommand({
 		"scan": scanCmd,
 		"tree": treeCmd,
 		"unused": unusedCmd,
-		"doctor": defineCommand({
-			meta: {
-				name: "doctor",
-				description: "Health checks over the AST graph. Suppress per-file with `// ripast-doctor-ignore-file[: c1,c2]` or per-line with `// ripast-doctor-ignore-next-line[: c1,c2]`."
-			},
-			args: {
-				glob: globArg,
-				checks: {
-					type: "string",
-					description: "Comma-separated subset: dangling-reexport, stale-reexport, stale-import, duplicate-export, orphan-file, orphan-test, inconsistent-import-path, circular-dep. Default: all."
-				},
-				entry: {
-					type: "string",
-					description: "Comma-separated entry files exempt from orphan check (relative to cwd)."
-				},
-				fix: {
-					type: "boolean",
-					default: false,
-					description: "Compute safe fixes for inconsistent-import-path and dangling-reexport findings."
-				},
-				apply: applyArg,
-				changed: {
-					type: "string",
-					description: "Report only findings on files changed vs git. No value = dirty working tree (staged+unstaged+untracked). With value (e.g. main, HEAD~1) = diff against that ref. Full project is still scanned so cross-file checks stay accurate."
-				},
-				profile: profileArg,
-				json: jsonArg
-			},
-			async run({ args }) {
-				const { agentProfile } = resolveProfile(args.profile);
-				const checks = args.checks ? args.checks.split(",") : void 0;
-				const entry = args.entry ? args.entry.split(",") : void 0;
-				let changedFiles;
-				if (args.changed != null) {
-					const ref = typeof args.changed === "string" && args.changed !== "" && args.changed !== "true" ? args.changed : void 0;
-					changedFiles = getChangedFiles({
-						cwd: process.cwd(),
-						ref
-					});
-					if (!changedFiles.length) {
-						process.stderr.write(`ripast doctor: --changed${ref ? ` ${ref}` : ""} matched no files; nothing to report.\n`);
-						return;
-					}
-				}
-				const report = await runDoctor({
-					glob: args.glob ? args.glob.split(",") : void 0,
-					checks,
-					entry,
-					changedFiles
-				});
-				if (args.fix) {
-					const fix = buildDoctorFixes(report, process.cwd());
-					if (args.json) {
-						process.stdout.write(`${JSON.stringify({
-							findings: report.findings,
-							filesScanned: report.filesScanned,
-							fix: {
-								applied: !!args.apply,
-								files: fix.changes.length,
-								fixed: fix.fixed,
-								skipped: fix.skipped.length
-							},
-							changes: args.apply ? void 0 : fix.changes.map((c) => ({
-								path: c.rel,
-								before: c.before,
-								after: c.after
-							}))
-						})}\n`);
-						if (args.apply && fix.changes.length) writeChanges(fix.changes);
-						if (fix.skipped.length) process.exit(1);
-						return;
-					}
-					const s = summarize(fix.changes);
-					process.stdout.write(`doctor --fix: ${fix.fixed.length} fixable / ${fix.skipped.length} non-fixable findings\n`);
-					process.stdout.write(`${fix.changes.length} file${fix.changes.length === 1 ? "" : "s"}, +${s.linesAdded} -${s.linesRemoved} lines\n\n`);
-					if (!args.apply) {
-						printDiffs(fix.changes);
-						process.stdout.write(`\n(dry run, pass --apply to write)\n`);
-					} else {
-						writeChanges(fix.changes);
-						for (const c of fix.changes) process.stdout.write(`wrote ${c.rel}\n`);
-					}
-					if (fix.skipped.length) process.exit(1);
-					return;
-				}
-				if (agentProfile && !args.json) {
-					process.stdout.write(`${profileHeader()}\n${formatAgentDoctorReport(report)}\n`);
-					return;
-				}
-				process.stdout.write(formatDoctorReport(report, !!args.json));
-				if (report.findings.length) process.exit(1);
-			}
-		}),
+		"doctor": doctorCmd,
 		"rename": renameCmd,
 		"replace": replaceCmd,
 		"rename-file": renameFileCmd,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ripast/cli",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "CLI for ripast. Deterministic AST refactors (rename, move, find-usages, tailwind/CSS class migration) for TypeScript and frontend frameworks. Auto-installs framework adapters as needed.",
   "author": {
     "name": "Harlan Wilton",
@@ -28,29 +28,28 @@
   ],
   "exports": {
     ".": {
-      "types": "./dist/cli.d.ts",
+      "types": "./dist/cli.d.mts",
       "import": "./dist/cli.mjs"
     }
   },
   "main": "./dist/cli.mjs",
-  "types": "./dist/cli.d.ts",
+  "types": "./dist/cli.d.mts",
   "bin": {
     "ripast": "./bin/ripast.mjs"
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "skills"
   ],
   "engines": {
-    "node": ">=20.11"
-  },
-  "peerDependencies": {
-    "typescript": ">=5.4"
+    "node": ">=22.13"
   },
   "dependencies": {
+    "@ripast/core": "0.5.0",
     "citty": "^0.2.2",
-    "std-env": "^4.1.0",
-    "@ripast/core": "0.3.0"
+    "cross-spawn": "^7.0.6",
+    "std-env": "^4.3.0"
   },
   "scripts": {
     "build": "obuild",

package/skills/ripast/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: ripast
+description: "Use Ripast for AST-aware renames, moves, usages, imports, and CSS class migrations across TS, JS, and Vue. Trigger for mechanical changes spanning files."
+---
+
+Ripast ships on npm as `@ripast/cli`. Run commands from the target project's root.
+Requires Node 22.13+.
+If `rg` is missing, Ripast searches files in Node. This can be slower.
+Programmatic regex searches still require `rg`.
+
+## Invocation
+
+```bash
+pnpm dlx @ripast/cli <command> ...
+```
+
+If the project already installs Ripast, use `pnpm exec ripast <command> ...`.
+The CLI installs framework adapters when needed, including `@ripast/vue` for Vue and Nuxt.
+Adapter installation prefers pnpm and uses npm if pnpm is missing.
+If pnpm is unavailable, invoke the published CLI with npm:
+
+```bash
+npm exec --yes --package=@ripast/cli -- ripast <command> ...
+```
+
+## Commands
+
+| Command | Use |
+| --- | --- |
+| `ripast scan <pattern>` | Classify occurrences before a rename. |
+| `ripast tree` | Show top-level declarations and imports. |
+| `ripast unused` | Find declarations without project references. |
+| `ripast rename <from> <to>` | Rename a symbol through the native TypeScript server. |
+| `ripast replace <from> <to>` | Replace an imported symbol with another project export. |
+| `ripast move <symbol> --from <a> --to <b>` | Move an export and update imports. |
+| `ripast delete <symbol> --from <file>` | Delete a declaration if no references remain. |
+| `ripast rename-file <old> <new>` | Rename a file and update importers, including Vue consumers. |
+| `ripast css-class-rename <from> <to>` | Rename a CSS class token. Use `--map <file.json>` for bulk changes. |
+| `ripast css-class-scan` | List class tokens before a migration. |
+
+Run `pnpm dlx @ripast/cli <command> --help` for each command's full flags.
+
+## Apply changes
+
+Keep unrelated work separate. Follow the target repository's worktree rules before writing.
+Start with a scan, then review the dry-run diff:
+
+```bash
+pnpm dlx @ripast/cli scan useStore
+pnpm dlx @ripast/cli rename useStore useAppStore --profile full
+pnpm dlx @ripast/cli rename useStore useAppStore --apply
+```
+
+Mutating refactor commands default to dry-run. Pass `--apply` to write.
+Rename, replace, move, delete, and rename-file verify types by default.
+If new diagnostics appear, verification blocks `--apply`.
+Use `--verify-mode touched|project|none` to choose the verification scope.
+Keep verification enabled unless you have reviewed the reported diagnostics.
+CSS class changes have no typecheck verification.
+
+If several files declare the same name, use `rename --scope <file>`.
+If several files export the replacement, use `replace --target-scope <file>`.
+Use `--json` for machine-readable results where supported.
+Use `--profile full` for full diffs instead of compact agent output.
+
+For Nuxt, prepare the generated configuration before refactoring auto-imports.
+Pass `--tsconfig .nuxt/tsconfig.json` to rename, move, or rename-file:
+
+```bash
+pnpm exec nuxi prepare
+pnpm dlx @ripast/cli rename useCounter useTally --tsconfig .nuxt/tsconfig.json
+```
+
+Review the diff and run the target project's checks after applying it.
+
+## When to use vs Edit
+
+Use Ripast for mechanical changes across files.
+Use a direct edit for one small change in a file you already understand.
+Use `rg` and direct edits for prose or patterns that only occur in strings and comments.
+Start with `scan` when the correct operation is unclear.
+
+Vue support covers script references and template expressions through its adapter.
+Svelte markup and arbitrary custom codemods are outside the supported refactor surface.