@rrlab/cli 0.0.1-git-87d22db.0

package/dist/run.mjs

@@ -0,0 +1,1137 @@
+import path from "node:path";
+import { colorize, createPkg, createShellService, cwd, dirnameOf, palette, run, text } from "@vlandoss/clibuddy";
+import { generateToStdout } from "@usage-spec/commander";
+import { Argument, Option, createCommand } from "commander";
+import fs from "node:fs";
+import os from "node:os";
+import { lilconfig } from "lilconfig";
+import { createLoggy } from "@vlandoss/loggy";
+import { glob } from "glob";
+import { rimraf } from "rimraf";
+import fs$1 from "node:fs/promises";
+import * as clack from "@clack/prompts";
+import { addDependency, detectPackageManager, removeDependency } from "nypm";
+import { builders, generateCode, loadFile, parseModule, writeFile } from "magicast";
+import * as cjson from "comment-json";
+//#region src/plugin/registry.ts
+var PluginRegistry = class {
+	#entries = [];
+	register(plugin, capabilities) {
+		this.#entries.push({
+			plugin,
+			capabilities
+		});
+	}
+	get(kind) {
+		const providers = this.#providersOf(kind);
+		const [first, ...rest] = providers;
+		if (!first) return void 0;
+		if (rest.length > 0) {
+			const names = providers.map(({ plugin }) => plugin.name).join(", ");
+			throw new Error(`Multiple plugins provide capability '${kind}': ${names}. Disambiguate by narrowing each plugin's capabilities in run-run.config.ts.`);
+		}
+		return first.impl;
+	}
+	providersOf(kind) {
+		return this.#providersOf(kind).map(({ plugin, impl }) => ({
+			name: plugin.name,
+			impl
+		}));
+	}
+	plugins() {
+		return this.#entries.map(({ plugin }) => plugin);
+	}
+	#providersOf(kind) {
+		const out = [];
+		for (const { plugin, capabilities } of this.#entries) {
+			const impl = capabilities[kind];
+			if (impl != null) out.push({
+				plugin,
+				impl
+			});
+		}
+		return out;
+	}
+};
+//#endregion
+//#region src/services/logger.ts
+const logger = createLoggy({ namespace: "run-run" });
+//#endregion
+//#region src/services/config.ts
+const DEFAULT_CONFIG = { plugins: [] };
+var ConfigService = class {
+	#searcher;
+	constructor() {
+		this.#searcher = lilconfig("run-run", {
+			searchPlaces: ["run-run.config.ts", "run-run.config.mts"],
+			cache: true,
+			stopDir: os.homedir(),
+			loaders: {
+				".ts": (filepath) => import(filepath).then((mod) => mod.default),
+				".mts": (filepath) => import(filepath).then((mod) => mod.default)
+			}
+		});
+	}
+	async load() {
+		const debug = logger.subdebug("load-config");
+		const searchResult = await this.#searcher.search();
+		if (!searchResult || searchResult?.isEmpty) {
+			debug("loaded default config: %O", DEFAULT_CONFIG);
+			return {
+				config: DEFAULT_CONFIG,
+				meta: {
+					isDefault: true,
+					filepath: void 0
+				}
+			};
+		}
+		const config = searchResult.config;
+		debug("loaded config: %O", config);
+		debug("config file: %s", searchResult.filepath);
+		return {
+			config,
+			meta: {
+				isDefault: false,
+				filepath: searchResult.filepath
+			}
+		};
+	}
+};
+//#endregion
+//#region src/services/ctx.ts
+async function createContext(binDir) {
+	const debug = logger.subdebug("create-context");
+	const binPath = fs.realpathSync(binDir);
+	debug("bin path:", binPath);
+	debug("process cwd:", process.cwd());
+	const [appPkg, binPkg] = await Promise.all([createPkg(cwd), createPkg(binPath)]);
+	if (!binPkg) throw new Error("Could not find bin package.json");
+	if (!appPkg) throw new Error("Could not find app package.json");
+	debug("app pkg info: %O", appPkg.info());
+	debug("bin pkg info: %O", binPkg.info());
+	const shell = createShellService();
+	debug("shell service options: %O", shell.options);
+	const config = await new ConfigService().load();
+	const registry = new PluginRegistry();
+	const pluginContext = {
+		shell,
+		logger,
+		appPkg,
+		binPkg,
+		cwd
+	};
+	for (const plugin of config.config.plugins ?? []) {
+		if (plugin.apiVersion !== 1) throw new Error(`Plugin '${plugin.name}' targets apiVersion ${plugin.apiVersion}, but this kernel supports only apiVersion 1.`);
+		debug("registering plugin: %s", plugin.name);
+		const capabilities = await plugin.setup(pluginContext);
+		registry.register(plugin, capabilities);
+	}
+	return {
+		appPkg,
+		binPkg,
+		shell,
+		config,
+		registry
+	};
+}
+//#endregion
+//#region src/program/ui.ts
+const CREDITS_TEXT = `\nAcknowledgment:
+- kcd-scripts: for main inspiration
+  ${palette.link("https://github.com/kentcdodds/kcd-scripts")}
+
+- peruvian news: in honor to Run Run
+  ${palette.link("https://es.wikipedia.org/wiki/Run_Run")}`;
+const rimrafColor = colorize("#7C7270");
+const runRunColor = colorize("#E8722A");
+const usageColor = colorize("#24C55E");
+/**
+* Labels used by kernel-internal commands. Plugin-owned tools (biome, oxc,
+* tsdown, tsc) define their own colored labels inside each plugin's
+* `src/index.ts`.
+*/
+const TOOL_LABELS = {
+	RIMRAF: rimrafColor("rimraf"),
+	RUN_RUN: runRunColor("run-run"),
+	USAGE: usageColor("usage")
+};
+const IS_USAGE_MODE = process.env.RR_USAGE_MODE === "1";
+/**
+* Renders the parenthesised backend hint that follows a command's summary,
+* e.g. `pack a ts library 📦 (tsdown)` or `… (not configured)` when no plugin
+* provides the capability.
+*
+* Returns an empty string when `RR_USAGE_MODE=1` is set (the kernel's `bin`
+* script exports it during `rr --usage`) so the KDL spec stays free of
+* per-environment state — the active plugin set is a property of the host
+* project, not of the CLI surface.
+*/
+function pluginAnnotation(provider) {
+	if (IS_USAGE_MODE) return "";
+	return provider ? ` (${provider.ui})` : " (not configured)";
+}
+function getBannerText(version) {
+	return `
+${runRunColor(`
+██████╗ ██╗   ██╗███╗   ██╗      ██████╗ ██╗   ██╗███╗   ██╗
+██╔══██╗██║   ██║████╗  ██║      ██╔══██╗██║   ██║████╗  ██║
+██████╔╝██║   ██║██╔██╗ ██║█████╗██████╔╝██║   ██║██╔██╗ ██║
+██╔══██╗██║   ██║██║╚██╗██║╚════╝██╔══██╗██║   ██║██║╚██╗██║
+██║  ██║╚██████╔╝██║ ╚████║      ██║  ██║╚██████╔╝██║ ╚████║
+╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝      ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ${text.version(version)}
+`.trim())}
+
+🦊 ${palette.italic(palette.muted("The CLI toolbox for"))} ${text.vland}\n`.trimStart();
+}
+//#endregion
+//#region src/program/commands/check.ts
+/**
+* `rr check` is the umbrella that runs the JS check (lint+format) and the
+* TS type check together. Both subcommands are already wired into
+* commander as siblings (`rr jsc`, `rr tsc`), so we reuse the program's
+* command tree as the action registry instead of duplicating it: look the
+* sibling up by name and invoke its action via `parseAsync([])`, which
+* applies its declared option defaults exactly as if the user had typed
+* `rr jsc` directly.
+*
+* Commander binds the running command as `this` inside an action (see
+* `command.js` — `fn.apply(this, actionArgs)`). `this.parent` gives us the
+* parent program without any late-binding ceremony.
+*/
+function createCheckCommand() {
+	return createCommand("check").summary(`run static checks (${TOOL_LABELS.RUN_RUN})`).description("Runs `rr jsc` and `rr tsc` concurrently in-process. Aggregates their exit codes — non-zero when either subcommand fails.").action(async function checkAction() {
+		const program = this.parent;
+		if (!program) throw new Error("`rr check` requires the parent program to dispatch sibling subcommands.");
+		const cmds = ["jsc", "tsc"].map((name) => ({
+			name,
+			cmd: findCommand(program, name)
+		}));
+		const missing = cmds.filter(({ cmd }) => !cmd).map(({ name }) => name);
+		if (missing.length > 0) {
+			for (const name of missing) logger.error(`rr check: subcommand "${name}" is not registered.`);
+			process.exitCode = 1;
+			return;
+		}
+		const results = await Promise.allSettled(cmds.map(({ cmd }) => cmd.parseAsync([], { from: "user" })));
+		const failed = [];
+		for (const [i, r] of results.entries()) if (r.status === "rejected") failed.push({
+			name: cmds[i]?.name ?? "?",
+			reason: r.reason
+		});
+		if (failed.length > 0) {
+			for (const { name, reason } of failed) {
+				const msg = reason instanceof Error ? reason.message : String(reason);
+				logger.error(`rr check (${name}): ${msg}`);
+			}
+			process.exitCode = 1;
+		}
+	});
+}
+function findCommand(program, name) {
+	return program.commands.find((c) => c.name() === name || c.aliases().includes(name));
+}
+//#endregion
+//#region src/program/commands/clean.ts
+function createCleanCommand() {
+	return createCommand("clean").summary(`delete dirty files (${TOOL_LABELS.RIMRAF})`).description("Deletes generated files and folders such as 'dist', 'node_modules', and lock files to ensure a clean state.").option("--only-dist", "delete 'dist' folders only").option("--dry-run", "outputs the paths that would be deleted").action(async function cleanCommandAction(options) {
+		async function run(paths, globOptions) {
+			if (options.dryRun) {
+				const toDelete = await glob(paths, globOptions);
+				logger.info("Paths that would be deleted: %O", toDelete);
+				return;
+			}
+			logger.start("Clean started");
+			await rimraf(paths, { glob: globOptions });
+			logger.success("Clean completed");
+		}
+		const BUILD_PATHS = ["**/dist"];
+		const ALL_DIRTY_PATHS = [
+			"**/.turbo",
+			"**/node_modules",
+			"pnpm-lock.yaml",
+			"bun.lock",
+			...BUILD_PATHS
+		];
+		if (options.onlyDist) await run(BUILD_PATHS, {
+			cwd,
+			ignore: ["**/node_modules/**"]
+		});
+		else await run(ALL_DIRTY_PATHS, { cwd });
+	}).addHelpText("afterAll", `\nUnder the hood, this command uses ${TOOL_LABELS.RIMRAF} to delete dirty folders or files.`);
+}
+//#endregion
+//#region src/program/commands/completion.ts
+const SHELLS = [
+	"bash",
+	"zsh",
+	"fish"
+];
+function createCompletionCommand() {
+	return createCommand("completion").summary(`print shell completion script (${TOOL_LABELS.USAGE})`).description(`Prints a shell completion script for rr. Add to your shell rc file:
+
+  bash: eval "$(rr completion bash)"
+  zsh:  eval "$(rr completion zsh)"
+  fish: rr completion fish | source`).addArgument(new Argument("<shell>", `target shell`).choices(SHELLS)).addHelpText("afterAll", `\nUnder the hood, this command uses ${TOOL_LABELS.USAGE} (https://usage.jdx.dev).
+Make sure to have it installed and available in your PATH.`);
+}
+//#endregion
+//#region src/program/commands/config.ts
+function createConfigCommand(ctx) {
+	return createCommand("config").summary("display the current config").description("Displays the current configuration settings, including their source file path if available.").action(async function configAction() {
+		const { config, meta } = ctx.config;
+		console.log(palette.muted("Config:"));
+		console.log(config);
+		console.log(palette.muted(`Loaded from ${meta.filepath ? palette.link(meta.filepath) : "n/a"}`));
+	});
+}
+//#endregion
+//#region src/plugin/types.ts
+const PLUGIN_KINDS = [
+	"lint",
+	"format",
+	"jsc",
+	"tsc",
+	"pack"
+];
+//#endregion
+//#region src/program/commands/doctor.ts
+/**
+* Subcommand factory used by every plugin-backed command (lint, format, jsc,
+* tsc, pack) to expose a `doctor` subcommand that verifies the underlying
+* tool is wired correctly. Each calls this with its own provider.
+*/
+function createDoctorSubcommand(service) {
+	return createCommand("doctor").summary("check if the underlying tool is working correctly").action(async function doctorAction() {
+		const debug = logger.subdebug("doctor");
+		const { ok, output } = await service.doctor();
+		if (ok) {
+			logger.success(`${service.ui} ok`);
+			debug("%O", output);
+		} else {
+			logger.error(`${service.ui} not working`);
+			debug("%O", output);
+			process.exit(output.exitCode ?? 1);
+		}
+	});
+}
+/**
+* Top-level `rr doctor` — runs the `doctor()` of every distinct capability
+* impl registered with the kernel. Distinct because a single plugin (e.g.
+* biome) often serves multiple kinds (`lint`, `format`, `jsc`) from the same
+* `BiomeService` instance; running its doctor three times is wasteful.
+*/
+function createDoctorCommand(ctx) {
+	return createCommand("doctor").summary("run all plugin doctors").description("Runs the `doctor()` of every configured plugin capability. Each plugin reports ok / not working. The exit code is non-zero if any reports not working.").action(async () => {
+		const services = collectDistinctDoctors(ctx);
+		if (services.length === 0) {
+			logger.info("No plugins configured. Use `rr plugins add <name>` to install one.");
+			return;
+		}
+		const debug = logger.subdebug("doctor");
+		const results = await Promise.all(services.map(async (svc) => {
+			return {
+				svc,
+				result: await svc.doctor()
+			};
+		}));
+		let failures = 0;
+		for (const { svc, result } of results) if (result.ok) {
+			logger.success(`${svc.ui} ok`);
+			debug("%s: %O", svc.ui, result.output);
+		} else {
+			logger.error(`${svc.ui} not working`);
+			debug("%s: %O", svc.ui, result.output);
+			failures++;
+		}
+		if (failures > 0) process.exitCode = 1;
+	});
+}
+function collectDistinctDoctors(ctx) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const kind of PLUGIN_KINDS) for (const { impl } of ctx.registry.providersOf(kind)) seen.add(impl);
+	return [...seen];
+}
+//#endregion
+//#region src/program/missing-plugin.ts
+const SUGGESTIONS = {
+	lint: [
+		"biome",
+		"oxc",
+		"eslint"
+	],
+	format: ["biome", "oxc"],
+	jsc: ["biome"],
+	tsc: ["ts"],
+	pack: ["tsdown"]
+};
+function missingPluginError(kind) {
+	const aliases = SUGGESTIONS[kind] ?? [];
+	const officialList = aliases.map((a) => `@rrlab/plugin-${a}`).join(", ");
+	const addList = aliases.map((a) => `rr plugins add ${a}`).join(" | ");
+	return /* @__PURE__ */ new Error(`No plugin provides the '${kind}' capability.` + (officialList ? `\n  Install one of: ${officialList}.` : "") + (addList ? `\n  Try: ${addList}.` : ""));
+}
+//#endregion
+//#region src/program/commands/format.ts
+function createFormatCommand(ctx) {
+	const formatter = ctx.registry.get("format");
+	const cmd = createCommand("format").summary(`check & fix format errors${pluginAnnotation(formatter)}`).description("Checks the code for formatting issues and optionally fixes them, ensuring it adheres to the defined style standards.").option("--fix", "format all the code");
+	if (formatter) cmd.addCommand(createDoctorSubcommand(formatter));
+	cmd.action(async (options = {}) => {
+		if (!formatter) throw missingPluginError("format");
+		await formatter.format(options);
+	});
+	if (formatter) cmd.addHelpText("afterAll", `\nUnder the hood, this command uses the ${formatter.ui} CLI to format the code.`);
+	return cmd;
+}
+//#endregion
+//#region src/program/composed-jsc.ts
+/**
+* Synthesises a `StaticChecker & Doctor` (the `jsc` capability) by composing
+* a separately-registered linter and formatter. Used when the user's plugin
+* set provides `lint` and `format` independently (e.g. oxc, or eslint +
+* prettier) but no single plugin claims `jsc`.
+*
+* The check runs lint then format sequentially — interleaved stdout from a
+* parallel run is hard to read for the user. `fixStaged` is dropped because
+* the underlying tools don't have a uniform staged-aware mode.
+*/
+function composedJscProvider(linter, formatter) {
+	return {
+		bin: `${linter.bin}+${formatter.bin}`,
+		ui: `${linter.ui} + ${formatter.ui}`,
+		async check({ fix }) {
+			await linter.lint({ fix });
+			await formatter.format({ fix });
+		},
+		async doctor() {
+			const [lintRes, fmtRes] = await Promise.all([linter.doctor(), formatter.doctor()]);
+			const ok = lintRes.ok && fmtRes.ok;
+			const firstFailure = !lintRes.ok ? lintRes : !fmtRes.ok ? fmtRes : void 0;
+			return {
+				ok,
+				output: {
+					stdout: `${linter.ui}:\n${lintRes.output.stdout}\n\n${formatter.ui}:\n${fmtRes.output.stdout}`,
+					stderr: `${linter.ui}:\n${lintRes.output.stderr}\n\n${formatter.ui}:\n${fmtRes.output.stderr}`,
+					exitCode: firstFailure?.output.exitCode ?? 0
+				}
+			};
+		}
+	};
+}
+//#endregion
+//#region src/program/commands/jscheck.ts
+function createJsCheckCommand(ctx) {
+	const direct = ctx.registry.get("jsc");
+	const linter = ctx.registry.get("lint");
+	const formatter = ctx.registry.get("format");
+	const checker = direct ?? (linter && formatter ? composedJscProvider(linter, formatter) : void 0);
+	const cmd = createCommand("jsc").alias("jscheck").summary(`check format and lint${pluginAnnotation(checker)}`).description("Checks the code for formatting and linting issues, ensuring it adheres to the defined style and quality standards.").option("--fix", "try to fix issues automatically").option("--fix-staged", "try to fix staged files only");
+	if (checker) cmd.addCommand(createDoctorSubcommand(checker));
+	cmd.action(async (options = {}) => {
+		if (!checker) throw missingPluginError("jsc");
+		await checker.check(options);
+	});
+	if (checker) cmd.addHelpText("afterAll", `\nUnder the hood, this command uses the ${checker.ui} CLI to check the code.`);
+	return cmd;
+}
+//#endregion
+//#region src/program/commands/lint.ts
+function createLintCommand(ctx) {
+	const linter = ctx.registry.get("lint");
+	const cmd = createCommand("lint").summary(`check & fix lint errors${pluginAnnotation(linter)}`).description("Checks the code for linting issues and optionally fixes them, ensuring it adheres to the defined quality standards.").option("-c, --check", "check if the code is valid", true).option("--fix", "try to fix all the code");
+	if (linter) cmd.addCommand(createDoctorSubcommand(linter));
+	cmd.action(async (options = {}) => {
+		if (!linter) throw missingPluginError("lint");
+		await linter.lint(options);
+	});
+	if (linter) cmd.addHelpText("afterAll", `\nUnder the hood, this command uses the ${linter.ui} CLI to lint the code.`);
+	return cmd;
+}
+//#endregion
+//#region src/program/commands/pack.ts
+function createPackCommand(ctx) {
+	const packer = ctx.registry.get("pack");
+	const cmd = createCommand("pack").summary(`pack a ts library${pluginAnnotation(packer)}`).description("Compiles TypeScript code into JavaScript and generates type declaration files, packaging the library for distribution.");
+	if (packer) {
+		cmd.addCommand(createDoctorSubcommand(packer));
+		cmd.addHelpText("afterAll", `\nUnder the hood, this command uses the ${packer.ui} CLI to pack the project.`);
+	}
+	cmd.action(async () => {
+		if (!packer) throw missingPluginError("pack");
+		await packer.pack();
+	});
+	return cmd;
+}
+//#endregion
+//#region src/services/config-ast.ts
+const CONFIG_FILENAMES = ["run-run.config.ts", "run-run.config.mts"];
+/**
+* AST-level read/write for `run-run.config.{ts,mts}`. Wraps `magicast` so that
+* adding/removing a plugin survives formatting, comments, and unrelated config
+* options. The kernel and the `rr plugins add | remove` command use this
+* service exclusively — no regex-based edits.
+*/
+var ConfigAstService = class {
+	/**
+	* Looks for an existing `run-run.config.{ts,mts}` in `cwd`. If neither
+	* exists, returns a fresh magicast module built from a minimal template
+	* marked as `isNew: true`; the caller decides where to save it.
+	*/
+	async load(cwd) {
+		for (const name of CONFIG_FILENAMES) {
+			const candidate = path.join(cwd, name);
+			try {
+				await fs$1.access(candidate);
+				return {
+					mod: await loadFile(candidate),
+					filepath: candidate,
+					isNew: false
+				};
+			} catch {}
+		}
+		const filepath = path.join(cwd, "run-run.config.mts");
+		return {
+			mod: parseModule(MINIMAL_TEMPLATE),
+			filepath,
+			isNew: true
+		};
+	}
+	async save(loaded) {
+		if (loaded.isNew) {
+			const { code } = generateCode(loaded.mod);
+			await fs$1.writeFile(loaded.filepath, code, "utf8");
+			return;
+		}
+		await writeFile(loaded.mod.$ast, loaded.filepath);
+	}
+	/**
+	* Returns true when the config's `plugins` array contains a call to the
+	* given `exportName` (e.g. `biome()`).
+	*/
+	hasPlugin(mod, exportName) {
+		const plugins = this.#pluginsArray(mod);
+		if (!plugins) return false;
+		for (let i = 0; i < plugins.length; i++) {
+			const item = plugins[i];
+			if (this.#isCallTo(item, exportName)) return true;
+		}
+		return false;
+	}
+	/**
+	* Adds the import binding and pushes a `exportName()` call onto `plugins`.
+	* No-op when the call is already present (idempotent).
+	*/
+	addPlugin(mod, entry) {
+		if (this.hasPlugin(mod, entry.exportName)) return { changed: false };
+		if (!mod.imports[entry.exportName]) mod.imports.$add({
+			from: entry.pkgName,
+			imported: "default",
+			local: entry.exportName
+		});
+		this.#ensureDefineConfig(mod);
+		this.#ensurePluginsArray(mod).push(builders.functionCall(entry.exportName));
+		return { changed: true };
+	}
+	/**
+	* Removes the `exportName()` call from `plugins[]` and, if it was the last
+	* use of that local binding, removes the import too.
+	*/
+	removePlugin(mod, exportName) {
+		const plugins = this.#pluginsArray(mod);
+		if (!plugins) return { changed: false };
+		let changed = false;
+		for (let i = plugins.length - 1; i >= 0; i--) if (this.#isCallTo(plugins[i], exportName)) {
+			plugins.splice(i, 1);
+			changed = true;
+		}
+		if (changed && mod.imports[exportName]) delete mod.imports[exportName];
+		return { changed };
+	}
+	/** Returns the list of plugin exportNames currently in `plugins[]`. */
+	listPlugins(mod) {
+		const plugins = this.#pluginsArray(mod);
+		if (!plugins) return [];
+		const out = [];
+		for (let i = 0; i < plugins.length; i++) {
+			const item = plugins[i];
+			const name = this.#calleeName(item);
+			if (name) out.push(name);
+		}
+		return out;
+	}
+	/**
+	* Locates `defineConfig({ plugins: [...] })` and returns the plugins array
+	* proxy. Returns `undefined` if the config doesn't have that shape.
+	*/
+	#pluginsArray(mod) {
+		const def = mod.exports.default;
+		if (!def || def.$type !== "function-call") return void 0;
+		const args = def.$args;
+		if (!args || args.length === 0) return void 0;
+		const opts = args[0];
+		if (!opts || typeof opts !== "object") return void 0;
+		return opts.plugins;
+	}
+	#ensureDefineConfig(mod) {
+		if (!mod.imports.defineConfig) mod.imports.$add({
+			from: "@rrlab/cli/config",
+			imported: "defineConfig",
+			local: "defineConfig"
+		});
+		if (!mod.exports.default) mod.exports.default = builders.functionCall("defineConfig", { plugins: [] });
+	}
+	#ensurePluginsArray(mod) {
+		const args = mod.exports.default.$args;
+		if (args.length === 0) args.push({ plugins: [] });
+		const opts = args[0];
+		if (!opts.plugins) opts.plugins = [];
+		return opts.plugins;
+	}
+	#isCallTo(item, exportName) {
+		return this.#calleeName(item) === exportName;
+	}
+	#calleeName(item) {
+		if (!item || typeof item !== "object") return void 0;
+		const proxy = item;
+		if (proxy.$type !== "function-call") return void 0;
+		const callee = proxy.$callee;
+		if (typeof callee === "string") return callee;
+	}
+};
+const MINIMAL_TEMPLATE = `import { defineConfig } from "@rrlab/cli/config";
+
+export default defineConfig({
+  plugins: [],
+});
+`;
+//#endregion
+//#region src/services/json-edit.ts
+/**
+* Applies a sequence of `JsonEdit` ops to a JSON / JSONC source string.
+* Uses `comment-json` so user comments and `extends`-like top-level shape
+* survive a parse → mutate → stringify round-trip.
+*
+* Paths follow JSON Pointer (RFC 6901): `"/extends"`,
+* `"/compilerOptions/strict"`. Indices are valid path segments for arrays
+* (`"/extends/0"`).
+*/
+function applyJsonEdits(source, edits) {
+	let root = source.trim() === "" ? {} : cjson.parse(source);
+	if (root == null || typeof root !== "object") throw new Error(`applyJsonEdits: expected a JSON object/array at the top level, got ${typeof root}.`);
+	for (const edit of edits) root = applyOne(root, edit);
+	return `${cjson.stringify(root, null, 2)}\n`;
+}
+function applyOne(root, edit) {
+	const segments = parsePointer(edit.path);
+	if (edit.op === "set") {
+		const existing = resolve(root, segments);
+		if (edit.mode === "if-missing" && existing !== void 0) return root;
+		return setAt(root, segments, edit.value);
+	}
+	if (edit.op === "unset") return unsetAt(root, segments);
+	if (edit.op === "include") return includeInArray(root, segments, edit.value, edit.position ?? "end");
+	if (edit.op === "exclude") return excludeFromArray(root, segments, edit.value);
+	return root;
+}
+/** Parses a JSON Pointer (RFC 6901) into its segments, decoding `~1` and `~0`. */
+function parsePointer(pointer) {
+	if (pointer === "" || pointer === "/") return [];
+	if (!pointer.startsWith("/")) throw new Error(`Invalid JSON Pointer "${pointer}": must start with "/" or be empty.`);
+	return pointer.slice(1).split("/").map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+function resolve(root, segments) {
+	let cur = root;
+	for (const seg of segments) {
+		if (cur == null) return void 0;
+		cur = cur[arrayIndexIfNumeric(cur, seg)];
+	}
+	return cur;
+}
+function setAt(root, segments, value) {
+	if (segments.length === 0) return value;
+	let cur = root;
+	for (let i = 0; i < segments.length - 1; i++) {
+		const seg = segments[i] ?? "";
+		const key = arrayIndexIfNumeric(cur, seg);
+		if (cur[key] == null || typeof cur[key] !== "object") cur[key] = isNumericIndex(segments[i + 1] ?? "") ? [] : {};
+		cur = cur[key];
+	}
+	const last = segments[segments.length - 1] ?? "";
+	cur[arrayIndexIfNumeric(cur, last)] = value;
+	return root;
+}
+function unsetAt(root, segments) {
+	if (segments.length === 0) return root;
+	let cur = root;
+	for (let i = 0; i < segments.length - 1; i++) {
+		const seg = segments[i] ?? "";
+		if (cur == null) return root;
+		cur = cur[arrayIndexIfNumeric(cur, seg)];
+	}
+	if (cur == null) return root;
+	const last = segments[segments.length - 1] ?? "";
+	if (Array.isArray(cur) && isNumericIndex(last)) cur.splice(Number(last), 1);
+	else delete cur[last];
+	return root;
+}
+function includeInArray(root, segments, value, position) {
+	const existing = resolve(root, segments);
+	if (existing === void 0) return setAt(root, segments, [value]);
+	if (!Array.isArray(existing)) throw new Error(`include: expected an array at "${segments.join("/")}", got ${typeof existing}.`);
+	if (existing.some((item) => deepEqual(item, value))) return root;
+	if (position === "start") existing.unshift(value);
+	else existing.push(value);
+	return root;
+}
+function excludeFromArray(root, segments, value) {
+	const existing = resolve(root, segments);
+	if (!Array.isArray(existing)) return root;
+	const idx = existing.findIndex((item) => deepEqual(item, value));
+	if (idx >= 0) existing.splice(idx, 1);
+	return root;
+}
+function arrayIndexIfNumeric(target, seg) {
+	return Array.isArray(target) && isNumericIndex(seg) ? Number(seg) : seg;
+}
+function isNumericIndex(seg) {
+	return seg !== "" && /^\d+$/.test(seg);
+}
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a == null || b == null) return false;
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+//#endregion
+//#region src/services/plugins-registry.ts
+/**
+* Map from short aliases the user types (`rr plugins add ts`) to the
+* full npm package name and the canonical local binding the plugin file
+* is imported as inside `run-run.config.{ts,mts}`.
+*
+* Third-party plugins use their full package name; the binding is derived
+* by stripping a `@scope/plugin-` (or `@scope/run-run-plugin-`) prefix.
+*/
+const OFFICIAL_PLUGINS = {
+	ts: {
+		pkg: "@rrlab/plugin-ts",
+		exportName: "ts"
+	},
+	eslint: {
+		pkg: "@rrlab/plugin-eslint",
+		exportName: "eslint"
+	},
+	biome: {
+		pkg: "@rrlab/plugin-biome",
+		exportName: "biome"
+	},
+	oxc: {
+		pkg: "@rrlab/plugin-oxc",
+		exportName: "oxc"
+	},
+	tsdown: {
+		pkg: "@rrlab/plugin-tsdown",
+		exportName: "tsdown"
+	}
+};
+function officialAliases() {
+	return Object.keys(OFFICIAL_PLUGINS);
+}
+//#endregion
+//#region src/services/prompts.ts
+/**
+* Adapter that exposes the subset of `@clack/prompts` matching the
+* `ClackPrompts` contract from `@rrlab/cli/plugin`. The contract intentionally
+* stays narrow (`select`, `confirm`, `isCancel`) so plugin install hooks can
+* be tested by injecting a stub without pulling in the real terminal IO.
+*
+* The casts compensate for two small type-shape mismatches:
+* - Our contract requires `label: string`; clack types `label?: string`.
+* - `clack.select` returns `Promise<unknown>` (a non-cancelled value or
+*   `symbol`); our contract narrows that to `Promise<T | symbol>`.
+*
+* Both widenings are safe: every required field is present, and clack's
+* runtime returns either the picked option's `value` (typed `T`) or
+* `clack.isCancel(...)`-detectable `symbol`.
+*/
+function createClackPrompts() {
+	return {
+		select: (opts) => clack.select(opts),
+		confirm: (opts) => clack.confirm(opts),
+		isCancel: (value) => clack.isCancel(value)
+	};
+}
+//#endregion
+//#region src/services/workspace-target.ts
+function resolveWorkspaceChoice(appPkg, pm) {
+	if (!appPkg.isMonorepo()) return { kind: "current" };
+	return {
+		kind: "root",
+		flag: pmNeedsRootFlag(pm) ? true : void 0
+	};
+}
+function toNypmWorkspace(choice) {
+	return choice.kind === "current" ? void 0 : choice.flag;
+}
+function describeWorkspaceChoice(choice) {
+	return choice.kind === "current" ? "the current package" : "the workspace root";
+}
+function pmNeedsRootFlag(pm) {
+	if (!pm) return false;
+	if (pm.name === "pnpm") return true;
+	if (pm.name === "yarn" && (!pm.majorVersion || pm.majorVersion === "1")) return true;
+	return false;
+}
+//#endregion
+//#region src/program/commands/plugins.ts
+function createPluginsCommand(ctx) {
+	const cmd = createCommand("plugins").description("manage @rrlab plugins");
+	cmd.command("list").description("list plugins configured in run-run.config.{ts,mts}").action(() => runList(ctx));
+	cmd.command("add").description("install and configure an @rrlab plugin").addArgument(new Argument("<name>", "plugin alias").choices(officialAliases())).option("--force", "re-run install even if the plugin is already configured").option("--yes", "skip prompts and use defaults (non-interactive)").option("--dry-run", "show what would happen, without applying changes").action((name, opts) => runAdd(ctx, name, opts));
+	cmd.command("remove").description("uninstall an @rrlab plugin and undo its config files + deps").addArgument(new Argument("<name>", "plugin alias to remove").choices(officialAliases())).option("--yes", "skip the confirmation prompt").option("--dry-run", "print the plan without applying changes").action((name, opts) => runRemove(ctx, name, opts));
+	return cmd;
+}
+async function runList(ctx) {
+	const ast = new ConfigAstService();
+	const loaded = await ast.load(ctx.appPkg.dirPath);
+	if (loaded.isNew) {
+		logger.info("No run-run.config.{ts,mts} found. Use `rr plugins add <name>` to start.");
+		return;
+	}
+	const plugins = ast.listPlugins(loaded.mod);
+	const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
+	if (plugins.length === 0) {
+		logger.info(`${rel}: no plugins configured.`);
+		return;
+	}
+	logger.info(`${rel}:`);
+	for (const name of plugins) logger.info(`  - ${name}`);
+}
+async function runAdd(ctx, alias, opts) {
+	const { pkg: pkgName, exportName } = OFFICIAL_PLUGINS[alias];
+	clack.intro(` rr plugins add ${alias} `);
+	const inPkg = hasInPackageJson(ctx, pkgName);
+	const ast = new ConfigAstService();
+	const loaded = await ast.load(ctx.appPkg.dirPath);
+	const inConfig = !loaded.isNew && ast.hasPlugin(loaded.mod, exportName);
+	if (inPkg && inConfig && !opts.force) {
+		clack.log.warn(`${pkgName} is already installed and configured. Use --force to re-run install.`);
+		clack.outro("Nothing to do.");
+		return;
+	}
+	const pm = await detectPackageManager(ctx.appPkg.dirPath);
+	const wsChoice = resolveWorkspaceChoice(ctx.appPkg, pm);
+	const workspace = toNypmWorkspace(wsChoice);
+	const targetLabel = describeWorkspaceChoice(wsChoice);
+	if (opts.dryRun) {
+		clack.log.info(`Would: install ${pkgName} as a devDependency in ${targetLabel}${inPkg ? " (already present, skipped)" : ""}.`);
+		if (!inConfig) {
+			const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
+			clack.log.info(`Would: add ${exportName}() to ${rel} (plugins[]).`);
+		}
+		clack.log.info("Would: run the plugin's install() hook (if any) to fetch peer deps and create files.");
+		clack.outro("Dry run complete.");
+		return;
+	}
+	let installedNow = false;
+	if (!inPkg) {
+		await withSpinner(`Installing ${pkgName}`, async () => {
+			await addDependency([pkgName], {
+				cwd: ctx.appPkg.dirPath,
+				dev: true,
+				silent: true,
+				workspace
+			});
+		});
+		installedNow = true;
+	}
+	let installResult;
+	try {
+		const factory = (await import(pkgName)).default;
+		if (typeof factory !== "function") throw new Error(`Plugin '${pkgName}' did not export a default factory function.`);
+		const plugin = factory();
+		if (plugin.install) {
+			const installCtx = {
+				shell: ctx.shell,
+				logger,
+				appPkg: ctx.appPkg,
+				prompts: createClackPrompts(),
+				flags: {
+					force: !!opts.force,
+					yes: !!opts.yes,
+					nonInteractive: !!opts.yes
+				}
+			};
+			installResult = await plugin.install(installCtx);
+		}
+	} catch (err) {
+		if (installedNow) try {
+			await removeDependency(pkgName, {
+				cwd: ctx.appPkg.dirPath,
+				workspace
+			});
+		} catch {}
+		throw err;
+	}
+	if (installResult?.devDependencies && Object.keys(installResult.devDependencies).length > 0) {
+		const names = Object.keys(installResult.devDependencies);
+		const deps = Object.entries(installResult.devDependencies).map(([k, v]) => `${k}@${v}`);
+		await withSpinner(`Installing ${names.join(", ")}`, async () => {
+			await addDependency(deps, {
+				cwd: ctx.appPkg.dirPath,
+				dev: true,
+				silent: true,
+				workspace
+			});
+		});
+	}
+	for (const op of installResult?.files ?? []) await applyFileOp(ctx.appPkg.dirPath, op, !!opts.force);
+	if (!inConfig) {
+		ast.addPlugin(loaded.mod, {
+			exportName,
+			pkgName
+		});
+		await ast.save(loaded);
+		const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
+		clack.log.success(`Updated ${rel}`);
+	}
+	clack.outro(`Plugin '${alias}' ready 🎉`);
+}
+async function runRemove(ctx, alias, opts) {
+	const { pkg: pkgName, exportName } = OFFICIAL_PLUGINS[alias];
+	clack.intro(` rr plugins remove ${alias} `);
+	const ast = new ConfigAstService();
+	const loaded = await ast.load(ctx.appPkg.dirPath);
+	const inConfig = !loaded.isNew && ast.hasPlugin(loaded.mod, exportName);
+	let uninstallResult;
+	if (hasInPackageJson(ctx, pkgName)) try {
+		const factory = (await import(pkgName)).default;
+		const plugin = typeof factory === "function" ? factory() : void 0;
+		if (plugin?.uninstall) uninstallResult = await plugin.uninstall({
+			shell: ctx.shell,
+			logger,
+			appPkg: ctx.appPkg,
+			prompts: createClackPrompts(),
+			flags: {
+				yes: !!opts.yes,
+				nonInteractive: !!opts.yes
+			}
+		});
+	} catch (err) {
+		clack.log.warn(`Could not load ${pkgName} for uninstall hook: ${err instanceof Error ? err.message : err}`);
+	}
+	const planSteps = [];
+	if (inConfig) {
+		const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
+		planSteps.push(`Remove ${exportName}() from ${rel}`);
+	}
+	for (const op of uninstallResult?.files ?? []) planSteps.push(describeFileOp(op));
+	const depsToRemove = (uninstallResult?.removeDependencies ?? []).filter((dep) => hasInPackageJson(ctx, dep));
+	if (hasInPackageJson(ctx, pkgName) && !depsToRemove.includes(pkgName)) depsToRemove.unshift(pkgName);
+	const pm = await detectPackageManager(ctx.appPkg.dirPath);
+	const wsChoice = resolveWorkspaceChoice(ctx.appPkg, pm);
+	const workspace = toNypmWorkspace(wsChoice);
+	if (depsToRemove.length > 0) planSteps.push(`Uninstall: ${depsToRemove.join(", ")} (from ${describeWorkspaceChoice(wsChoice)})`);
+	if (planSteps.length === 0) {
+		clack.log.warn(`Plugin '${alias}' is not installed nor configured.`);
+		clack.outro("Nothing to do.");
+		return;
+	}
+	clack.log.message(`Plan:\n${planSteps.map((s) => `  • ${s}`).join("\n")}`);
+	if (opts.dryRun) {
+		clack.outro("Dry run complete.");
+		return;
+	}
+	if (!opts.yes) {
+		const choice = await clack.confirm({
+			message: "Proceed?",
+			initialValue: false
+		});
+		if (clack.isCancel(choice) || choice !== true) {
+			clack.outro("Aborted.");
+			return;
+		}
+	}
+	for (const op of uninstallResult?.files ?? []) await applyFileOp(ctx.appPkg.dirPath, op, true);
+	if (inConfig) {
+		ast.removePlugin(loaded.mod, exportName);
+		await ast.save(loaded);
+		const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
+		clack.log.success(`Removed ${exportName}() from ${rel}`);
+	}
+	for (const dep of depsToRemove) await withSpinner(`Uninstalling ${dep}`, async () => {
+		await removeDependency(dep, {
+			cwd: ctx.appPkg.dirPath,
+			workspace
+		});
+	});
+	clack.outro(`Plugin '${alias}' removed.`);
+}
+function hasInPackageJson(ctx, pkgName) {
+	const pkg = ctx.appPkg.packageJson;
+	return pkgName in {
+		...pkg.dependencies ?? {},
+		...pkg.devDependencies ?? {},
+		...pkg.peerDependencies ?? {}
+	};
+}
+async function withSpinner(message, fn) {
+	const sp = clack.spinner();
+	sp.start(message);
+	try {
+		const result = await fn();
+		sp.stop(message);
+		return result;
+	} catch (err) {
+		sp.stop(`${message} — failed`, 1);
+		throw err;
+	}
+}
+function describeFileOp(op) {
+	switch (op.kind) {
+		case "create": return `${op.overwrite ? "Overwrite" : "Create"} ${op.path}`;
+		case "edit-json": return `Edit ${op.path} (${op.edits.length} change${op.edits.length === 1 ? "" : "s"})`;
+		case "edit-text": return `Edit ${op.path}`;
+		case "delete": return `Delete ${op.path}`;
+	}
+}
+async function applyFileOp(cwd, op, force) {
+	const abs = path.join(cwd, op.path);
+	if (op.kind === "create") {
+		const exists = await pathExists(abs);
+		if (exists && !op.overwrite && !force) {
+			clack.log.warn(`Skipping ${op.path} — already exists. Use --force to overwrite.`);
+			return;
+		}
+		await fs$1.mkdir(path.dirname(abs), { recursive: true });
+		await fs$1.writeFile(abs, op.content, "utf8");
+		clack.log.success(`${exists ? "Overwrote" : "Created"} ${op.path}`);
+		return;
+	}
+	if (op.kind === "edit-json") {
+		if (!await pathExists(abs)) {
+			clack.log.warn(`Skipping ${op.path} — file does not exist.`);
+			return;
+		}
+		const source = await fs$1.readFile(abs, "utf8");
+		const next = applyJsonEdits(source, op.edits);
+		if (next !== source) {
+			await fs$1.writeFile(abs, next, "utf8");
+			clack.log.success(`Edited ${op.path}`);
+		} else clack.log.info(`No changes for ${op.path}.`);
+		return;
+	}
+	if (op.kind === "edit-text") {
+		if (!await pathExists(abs)) {
+			clack.log.warn(`Skipping ${op.path} — file does not exist.`);
+			return;
+		}
+		const source = await fs$1.readFile(abs, "utf8");
+		const next = op.edit(source);
+		if (next !== source) {
+			await fs$1.writeFile(abs, next, "utf8");
+			clack.log.success(`Edited ${op.path}`);
+		} else clack.log.info(`No changes for ${op.path}.`);
+		return;
+	}
+	if (op.kind === "delete") {
+		if (!await pathExists(abs)) return;
+		await fs$1.unlink(abs);
+		clack.log.success(`Deleted ${op.path}`);
+		return;
+	}
+}
+async function pathExists(p) {
+	try {
+		await fs$1.access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/program/commands/tscheck.ts
+const getPreScript = (scripts) => scripts?.pretsc ?? scripts?.pretypecheck;
+async function typecheckAt({ dir, scripts, log, shell, tsc }) {
+	log.debug(`checking types at ${dir}`);
+	const shellAt = cwd === dir ? shell : shell.at(dir);
+	try {
+		const preScript = getPreScript(scripts);
+		if (preScript) {
+			log.start(`Running pre-script: ${preScript}`);
+			await shellAt.run(preScript, [], { shell: true });
+			log.success("Pre-script completed");
+		}
+		log.start("Type checking started");
+		if (cwd === dir) await tsc.check();
+		else await tsc.check({ cwd: dir });
+		log.success("Typecheck completed");
+	} catch (error) {
+		log.error("Typecheck failed");
+		throw error;
+	}
+}
+function createTsCheckCommand(ctx) {
+	const { appPkg, shell } = ctx;
+	const tsc = ctx.registry.get("tsc");
+	const cmd = createCommand("tsc").alias("tscheck").summary(`check typescript errors${pluginAnnotation(tsc)}`).description("Checks the TypeScript code for type errors, ensuring that the code adheres to the defined type constraints and helps catch potential issues before runtime.");
+	if (tsc) {
+		cmd.addCommand(createDoctorSubcommand(tsc));
+		cmd.addHelpText("afterAll", `\nUnder the hood, this command uses the ${tsc.ui} CLI to check the code.`);
+	}
+	cmd.action(async () => {
+		if (!tsc) throw missingPluginError("tsc");
+		const isTsProject = (dir) => appPkg.hasFile("tsconfig.json", dir);
+		if (!appPkg.isMonorepo()) {
+			if (!isTsProject(appPkg.dirPath)) {
+				logger.info("No tsconfig.json found, skipping typecheck");
+				return;
+			}
+			await typecheckAt({
+				shell,
+				tsc,
+				dir: appPkg.dirPath,
+				scripts: appPkg.packageJson.scripts,
+				log: logger
+			});
+			return;
+		}
+		const tsProjects = (await appPkg.getWorkspaceProjects()).filter((project) => isTsProject(project.rootDir));
+		if (!tsProjects.length) {
+			logger.warn("No ts projects found in the monorepo, skipping typecheck");
+			return;
+		}
+		await Promise.all(tsProjects.map((p) => typecheckAt({
+			shell,
+			tsc,
+			dir: p.rootDir,
+			scripts: p.manifest.scripts,
+			log: logger.child({
+				tag: p.manifest.name,
+				namespace: "typecheck"
+			})
+		})));
+	});
+	return cmd;
+}
+//#endregion
+//#region src/program/index.ts
+async function createProgram(options) {
+	const ctx = await createContext(options.binDir);
+	const version = ctx.binPkg.version;
+	return {
+		program: createCommand("rr").usage("<command...> [options...]").enablePositionalOptions().version(version, "-v, --version").addOption(new Option("--usage", `print KDL spec for this CLI (${palette.muted(palette.link("https://kdl.dev"))})`)).on("option:usage", function onUsage() {
+			generateToStdout(this);
+			process.exit(0);
+		}).addHelpText("before", getBannerText(version)).addHelpText("after", CREDITS_TEXT).addCommand(createCompletionCommand()).addCommand(createPackCommand(ctx)).addCommand(createJsCheckCommand(ctx)).addCommand(createTsCheckCommand(ctx)).addCommand(createLintCommand(ctx)).addCommand(createFormatCommand(ctx)).addCommand(createCheckCommand()).addCommand(createDoctorCommand(ctx)).addCommand(createPluginsCommand(ctx)).addCommand(createCleanCommand()).addCommand(createConfigCommand(ctx)),
+		ctx
+	};
+}
+//#endregion
+//#region src/run.ts
+const BIN_DIR = path.dirname(dirnameOf(import.meta));
+await run(async () => {
+	const { program } = await createProgram({ binDir: BIN_DIR });
+	await program.parseAsync(process.argv, { from: "node" });
+}, logger);
+//#endregion
+export {};