@ripast/cli 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harlan Wilton <harlan@harlanzw.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/ripast.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+
+const FRAMEWORK_MARKERS = {
+  vue: ['vue', 'nuxt', '@nuxt/kit'],
+  // svelte: ['svelte', '@sveltejs/kit'], // adapter not yet published
+}
+
+function detectFrameworks(cwd) {
+  const out = []
+  let dir = cwd
+  for (let i = 0; i < 6; i++) {
+    const pkgPath = join(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies }
+        for (const [name, markers] of Object.entries(FRAMEWORK_MARKERS)) {
+          if (out.includes(name))
+            continue
+          if (markers.some(m => allDeps[m]))
+            out.push(name)
+        }
+      }
+      catch {}
+    }
+    const parent = dirname(dir)
+    if (parent === dir)
+      break
+    dir = parent
+  }
+  return out
+}
+
+function ensureAdapters(needed) {
+  if (process.env.RIPAST_REEXEC)
+    return
+  if (!needed.length)
+    return
+
+  const require = createRequire(import.meta.url)
+  const missing = []
+  for (const name of needed) {
+    try { require.resolve(`@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' },
+  })
+  process.exit(res.status ?? 1)
+}
+
+ensureAdapters(detectFrameworks(process.cwd()))
+
+await import('../dist/cli.mjs')

package/dist/cli.d.mts

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

package/dist/cli.mjs

@@ -0,0 +1,502 @@
+import { mkdirSync, readFileSync, renameSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+import { buildDeclarationTree, buildScanGraph, formatAgentDeclarationTree, formatAgentHits, formatAgentScanHits, formatDeclarationTree, formatHits, formatRegressions, formatScanGraph, formatScanHits, printDiffs, resolveVerifyMode, runCssClassRename, runCssClassScan, runMove, runRename, runRenameFile, scan, summarize, writeChanges } from "@ripast/core";
+import { defineCommand, runMain } from "citty";
+import { agent, isAgent } from "std-env";
+const globArg = {
+	type: "string",
+	description: "File glob(s), comma-separated. Defaults to *.ts,*.tsx,*.vue,...  Respects .gitignore."
+};
+const applyArg = {
+	type: "boolean",
+	default: false,
+	description: "Write changes. Default prints a unified diff."
+};
+const verifyArg = {
+	type: "boolean",
+	default: true,
+	description: "Typecheck post-transform; refuse --apply on regression. Disable with --no-verify."
+};
+const verifyModeArg = {
+	type: "string",
+	description: "Verification mode: touched, project, or none. Defaults to touched; --no-verify maps to none."
+};
+const vueArg = {
+	type: "boolean",
+	default: true,
+	description: "Enable Volar pass for .vue files. Disable with --no-vue to force pure ts-morph behavior."
+};
+const jsonArg = {
+	type: "boolean",
+	default: false,
+	description: "Emit machine-readable JSON (suppresses diff/summary text)."
+};
+const profileArg = {
+	type: "string",
+	description: "Output profile: auto, agent, or full. Auto uses std-env isAgent."
+};
+function resolveProfile(raw) {
+	const profile = raw ?? "auto";
+	if (profile !== "auto" && profile !== "agent" && profile !== "full") {
+		process.stderr.write(`ripast: --profile must be "auto", "agent", or "full".\n`);
+		process.exit(2);
+	}
+	return {
+		profile,
+		agentProfile: profile === "agent" || profile === "auto" && isAgent
+	};
+}
+function resolveGraphFormat(raw) {
+	if (raw !== "mermaid" && raw !== "dot") {
+		process.stderr.write(`ripast scan: --graph must be "mermaid" or "dot".\n`);
+		process.exit(2);
+	}
+	return raw;
+}
+function profileHeader() {
+	return `# profile: agent${agent ? ` (${agent})` : ""}`;
+}
+function resolveCliVerifyMode(verify, verifyMode) {
+	if (verifyMode != null) {
+		if (verifyMode !== "none" && verifyMode !== "touched" && verifyMode !== "project") {
+			process.stderr.write(`ripast: --verify-mode must be "none", "touched", or "project".\n`);
+			process.exit(2);
+		}
+		return verifyMode;
+	}
+	return resolveVerifyMode(verify);
+}
+function resolveExportFilter(raw) {
+	if (raw !== "all" && raw !== "exported" && raw !== "local") {
+		process.stderr.write(`ripast tree: --exports must be "all", "exported", or "local".\n`);
+		process.exit(2);
+	}
+	return raw;
+}
+const scanCmd = defineCommand({
+	meta: {
+		name: "scan",
+		description: "rg-prefilter + AST-classify occurrences of an identifier."
+	},
+	args: {
+		pattern: {
+			type: "positional",
+			required: true
+		},
+		glob: globArg,
+		kind: {
+			type: "string",
+			description: "Filter to kind(s), comma-separated. Kinds: identifier-reference, identifier-binding, import-specifier, member-access, property, jsx, string-literal."
+		},
+		graph: {
+			type: "string",
+			description: "Emit a dependency graph for hit files: mermaid or dot."
+		},
+		profile: profileArg,
+		json: {
+			type: "boolean",
+			default: false
+		}
+	},
+	run({ args }) {
+		const { agentProfile } = resolveProfile(args.profile);
+		const opts = {
+			glob: args.glob ? args.glob.split(",") : void 0,
+			kinds: args.kind ? args.kind.split(",") : void 0
+		};
+		if (args.graph) {
+			const graphFormat = resolveGraphFormat(args.graph);
+			process.stdout.write(`${formatScanGraph(buildScanGraph(args.pattern, opts), graphFormat)}\n`);
+			return;
+		}
+		const hits = scan(args.pattern, opts);
+		if (agentProfile && !args.json) {
+			process.stdout.write(`${profileHeader()}\n${formatAgentHits(hits)}\n`);
+			return;
+		}
+		process.stdout.write(`${formatHits(hits, args.json)}\n`);
+	}
+});
+const renameCmd = defineCommand({
+	meta: {
+		name: "rename",
+		description: "Scope-aware symbol rename via ts-morph (handles type-only imports, shadowing, JSX)."
+	},
+	args: {
+		from: {
+			type: "positional",
+			required: true
+		},
+		to: {
+			type: "positional",
+			required: true
+		},
+		tsconfig: { type: "string" },
+		glob: globArg,
+		apply: applyArg,
+		verify: verifyArg,
+		verifyMode: verifyModeArg,
+		scope: {
+			type: "string",
+			description: "Restrict to a single file when multiple files declare the same name."
+		},
+		all: {
+			type: "boolean",
+			default: false,
+			description: "Rename declarations in every file that defines the name (bypasses ambiguity check)."
+		},
+		vue: vueArg,
+		profile: profileArg,
+		json: jsonArg
+	},
+	async run({ args }) {
+		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,
+			verify: verifyMode,
+			scope: args.scope,
+			allowMultiple: args.all,
+			vue: args.vue
+		}), !!args.apply, verifyMode !== "none", !!args.json, resolveProfile(args.profile).agentProfile);
+	}
+});
+const treeCmd = defineCommand({
+	meta: {
+		name: "tree",
+		description: "Print a project declaration tree from top-level AST declarations, grouped by file."
+	},
+	args: {
+		glob: globArg,
+		exports: {
+			type: "string",
+			description: "Declaration filter: all, exported, or local. Defaults to exported for detected agents, all otherwise."
+		},
+		profile: profileArg,
+		json: jsonArg
+	},
+	run({ args }) {
+		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,
+			exports: agentProfile ? "all" : exportFilter
+		});
+		if (agentProfile && !args.json) {
+			process.stdout.write(`${profileHeader()}\n`);
+			process.stdout.write(`${formatAgentDeclarationTree(tree, exportFilter)}\n`);
+			return;
+		}
+		process.stdout.write(`${formatDeclarationTree(tree, !!args.json)}\n`);
+	}
+});
+const moveCmd = defineCommand({
+	meta: {
+		name: "move",
+		description: "Move a top-level exported symbol between files; rewrites import sites project-wide."
+	},
+	args: {
+		symbol: {
+			type: "positional",
+			required: true
+		},
+		from: {
+			type: "string",
+			required: true,
+			description: "Source file path."
+		},
+		to: {
+			type: "string",
+			required: true,
+			description: "Target file path (created if missing)."
+		},
+		tsconfig: { type: "string" },
+		apply: applyArg,
+		verify: verifyArg,
+		verifyMode: verifyModeArg,
+		vue: vueArg,
+		profile: profileArg,
+		json: jsonArg
+	},
+	async run({ args }) {
+		const verifyMode = resolveCliVerifyMode(args.verify, args.verifyMode);
+		emitResult(await runMove(args.symbol, args.from, args.to, {
+			tsconfig: args.tsconfig,
+			verify: verifyMode,
+			vue: args.vue
+		}), !!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);
+	if (json) {
+		const blockedByRegression = verify && apply && r.regressions.length > 0;
+		const wrote = apply && !blockedByRegression;
+		if (wrote) writeChanges(r.changes);
+		const payload = {
+			applied: wrote,
+			dryRun: !apply,
+			blockedByRegression,
+			scanned: r.scanned,
+			summary: s,
+			changes: r.changes.map((c) => ({
+				path: c.rel,
+				absolutePath: c.path,
+				before: c.before,
+				after: c.after
+			})),
+			regressions: r.regressions
+		};
+		process.stdout.write(`${JSON.stringify(payload)}\n`);
+		if (blockedByRegression) process.exit(1);
+		return;
+	}
+	if (agentProfile) {
+		const blockedByRegression = verify && apply && r.regressions.length > 0;
+		process.stdout.write(`${profileHeader()}\n`);
+		process.stdout.write(`changes: ${r.changes.length}/${r.scanned} files, +${s.linesAdded} -${s.linesRemoved} lines\n`);
+		process.stdout.write(`mode: ${apply ? blockedByRegression ? "blocked" : "applied" : "dry-run"}\n`);
+		if (r.changes.length) {
+			process.stdout.write(`files:\n`);
+			for (const c of r.changes) process.stdout.write(`  ${c.rel}\n`);
+		}
+		if (verify && r.regressions.length) {
+			process.stdout.write(`regressions: ${r.regressions.length}\n`);
+			for (const regression of r.regressions.slice(0, 20)) process.stdout.write(`  ${regression.file}:${regression.line}:${regression.col} TS${regression.code} ${regression.message}\n`);
+			if (r.regressions.length > 20) process.stdout.write(`  ... ${r.regressions.length - 20} more\n`);
+			if (apply) {
+				process.stderr.write(`\nripast: refusing to --apply; --no-verify to override.\n`);
+				process.exit(1);
+			}
+		}
+		if (apply) {
+			writeChanges(r.changes);
+			process.stdout.write(`applied: true\n`);
+		} else process.stdout.write(`apply: pass --apply to write, or --profile full to see diff\n`);
+		return;
+	}
+	if (!apply) {
+		process.stdout.write(`${s.files} file${s.files === 1 ? "" : "s"}, +${s.linesAdded} -${s.linesRemoved} lines\n\n`);
+		printDiffs(r.changes);
+	}
+	if (verify && r.regressions.length) {
+		process.stderr.write(`\n${formatRegressions(r.regressions, process.cwd())}\n`);
+		if (apply) {
+			process.stderr.write(`\nripast: refusing to --apply; --no-verify to override.\n`);
+			process.exit(1);
+		}
+	}
+	if (apply) {
+		writeChanges(r.changes);
+		for (const c of r.changes) process.stdout.write(`wrote ${c.rel}\n`);
+	}
+	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({
+	meta: {
+		name: "rename-file",
+		description: "Rename a file and rewrite every import site (including .vue consumers and component-name refs)."
+	},
+	args: {
+		old: {
+			type: "positional",
+			required: true
+		},
+		new: {
+			type: "positional",
+			required: true
+		},
+		tsconfig: { type: "string" },
+		apply: applyArg,
+		verify: verifyArg,
+		profile: profileArg,
+		json: jsonArg
+	},
+	async run({ args }) {
+		const r = await runRenameFile(args.old, args.new, {
+			tsconfig: args.tsconfig,
+			verify: args.verify
+		});
+		const apply = !!args.apply;
+		const verify = !!args.verify;
+		const json = !!args.json;
+		const { agentProfile } = resolveProfile(args.profile);
+		const s = summarize(r.changes);
+		const blockedByRegression = verify && apply && r.regressions.length > 0;
+		const wrote = apply && !blockedByRegression;
+		if (wrote) {
+			writeChanges(r.changes);
+			mkdirSync(dirname(r.fileMove.to), { recursive: true });
+			renameSync(r.fileMove.from, r.fileMove.to);
+		}
+		if (json) {
+			process.stdout.write(`${JSON.stringify({
+				applied: wrote,
+				dryRun: !apply,
+				blockedByRegression,
+				scanned: r.scanned,
+				summary: s,
+				fileMove: r.fileMove,
+				changes: r.changes.map((c) => ({
+					path: c.rel,
+					absolutePath: c.path,
+					before: c.before,
+					after: c.after
+				})),
+				regressions: r.regressions
+			})}\n`);
+			if (blockedByRegression) process.exit(1);
+			return;
+		}
+		if (agentProfile) {
+			process.stdout.write(`${profileHeader()}\n`);
+			process.stdout.write(`rename-file: ${args.old} -> ${args.new}\n`);
+			process.stdout.write(`consumers: ${r.changes.length}/${r.scanned}, +${s.linesAdded} -${s.linesRemoved} lines\n`);
+			process.stdout.write(`mode: ${apply ? blockedByRegression ? "blocked" : "applied" : "dry-run"}\n`);
+			if (r.changes.length) {
+				process.stdout.write(`files:\n`);
+				for (const c of r.changes) process.stdout.write(`  ${c.rel}\n`);
+			}
+			if (verify && r.regressions.length) {
+				process.stdout.write(`regressions: ${r.regressions.length}\n`);
+				if (apply) {
+					process.stderr.write(`\nripast: refusing to --apply; --no-verify to override.\n`);
+					process.exit(1);
+				}
+			}
+			if (!apply) process.stdout.write(`apply: pass --apply to write, or --profile full to see diff\n`);
+			return;
+		}
+		if (!apply) {
+			process.stdout.write(`rename ${args.old} -> ${args.new}\n`);
+			process.stdout.write(`${s.files} consumer file${s.files === 1 ? "" : "s"}, +${s.linesAdded} -${s.linesRemoved} lines\n\n`);
+			printDiffs(r.changes);
+		}
+		if (verify && r.regressions.length) {
+			process.stderr.write(`\n${formatRegressions(r.regressions, process.cwd())}\n`);
+			if (apply) {
+				process.stderr.write(`\nripast: refusing to --apply; --no-verify to override.\n`);
+				process.exit(1);
+			}
+		}
+		if (wrote) {
+			for (const c of r.changes) process.stdout.write(`wrote ${c.rel}\n`);
+			process.stdout.write(`renamed ${args.old} -> ${args.new}\n`);
+		}
+		const suffix = apply ? "" : " (dry run, pass --apply to write)";
+		process.stdout.write(`\n${r.changes.length} consumer file(s) updated${suffix}\n`);
+	}
+});
+const cssClassRenameCmd = defineCommand({
+	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."
+	},
+	args: {
+		from: {
+			type: "positional",
+			required: false
+		},
+		to: {
+			type: "positional",
+			required: false
+		},
+		map: {
+			type: "string",
+			description: "Path to a JSON file with { \"from\": \"to\", ... } flat object. Mutually exclusive with from/to positionals."
+		},
+		glob: globArg,
+		apply: applyArg,
+		profile: profileArg,
+		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);
+	}
+});
+function buildRenameMap(from, to, mapPath) {
+	const hasPair = from != null && to != null;
+	const hasMap = !!mapPath;
+	if (hasPair && hasMap) {
+		process.stderr.write(`ripast css-class-rename: pass either "from to" positionals OR --map, not both.\n`);
+		process.exit(2);
+	}
+	if (!hasPair && !hasMap) {
+		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]]);
+	const raw = readFileSync(resolve(process.cwd(), mapPath), "utf8");
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		process.stderr.write(`ripast css-class-rename: --map file is not valid JSON (${err.message}).\n`);
+		process.exit(2);
+	}
+	if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		process.stderr.write(`ripast css-class-rename: --map must be a flat JSON object, got ${Array.isArray(parsed) ? "array" : typeof parsed}.\n`);
+		process.exit(2);
+	}
+	const entries = [];
+	for (const [k, v] of Object.entries(parsed)) {
+		if (typeof v !== "string") {
+			process.stderr.write(`ripast css-class-rename: --map value for "${k}" is not a string.\n`);
+			process.exit(2);
+		}
+		if (!k) {
+			process.stderr.write(`ripast css-class-rename: --map has an empty key.\n`);
+			process.exit(2);
+		}
+		entries.push([k, String(v)]);
+	}
+	if (!entries.length) {
+		process.stderr.write(`ripast css-class-rename: --map is empty.\n`);
+		process.exit(2);
+	}
+	return new Map(entries);
+}
+runMain(defineCommand({
+	meta: {
+		name: "ripast",
+		description: "AST-aware refactor primitives. ripgrep-prefiltered, dry-run by default."
+	},
+	subCommands: {
+		"scan": scanCmd,
+		"tree": treeCmd,
+		"rename": renameCmd,
+		"rename-file": renameFileCmd,
+		"move": moveCmd,
+		"css-class-rename": cssClassRenameCmd,
+		"css-class-scan": defineCommand({
+			meta: {
+				name: "css-class-scan",
+				description: "Tokenize every class site (strings, Vue class attrs, @apply) and emit a frequency-sorted list. Feeds --map for css-class-rename."
+			},
+			args: {
+				pattern: {
+					type: "string",
+					description: "Comma-separated globs matched against the bare token (e.g. \"bg-*,text-*\"). Default: all tokens."
+				},
+				glob: globArg,
+				profile: profileArg,
+				json: jsonArg
+			},
+			run({ args }) {
+				const { agentProfile } = resolveProfile(args.profile);
+				const hits = runCssClassScan({
+					glob: args.glob ? args.glob.split(",") : void 0,
+					pattern: args.pattern ? args.pattern.split(",") : void 0
+				});
+				if (agentProfile && !args.json) {
+					process.stdout.write(`${profileHeader()}\n${formatAgentScanHits(hits)}\n`);
+					return;
+				}
+				process.stdout.write(`${formatScanHits(hits, !!args.json)}\n`);
+			}
+		})
+	}
+}));
+export {};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ripast/cli",
+  "type": "module",
+  "version": "0.0.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",
+    "email": "harlan@harlanzw.com",
+    "url": "https://harlanzw.com/"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/harlan-zw/ripast#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harlan-zw/ripast.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/harlan-zw/ripast/issues"
+  },
+  "keywords": [
+    "ripast",
+    "cli",
+    "ast",
+    "refactor",
+    "rename",
+    "codemod"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.mjs"
+    }
+  },
+  "main": "./dist/cli.mjs",
+  "types": "./dist/cli.d.ts",
+  "bin": {
+    "ripast": "./bin/ripast.mjs"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.4"
+  },
+  "dependencies": {
+    "citty": "^0.2.2",
+    "std-env": "^4.1.0",
+    "@ripast/core": "0.0.0"
+  },
+  "scripts": {
+    "build": "obuild",
+    "dev:prepare": "obuild --stub"
+  }
+}