@rrlab/cli 0.0.3 → 0.0.4-git-c5c6e0f.0

package/dist/cli.usage.kdl

@@ -1,7 +1,7 @@
 // @generated by @usage-spec/commander from Commander.js metadata
 name rr
 bin rr
-version "0.0.3"
+version "0.0.4-git-c5c6e0f.0"
 usage "<command...> [options...]"
 flag --usage help="print KDL spec for this CLI (https://kdl.dev)"
 cmd completion help="print shell completion script (usage)" {
@@ -37,7 +37,7 @@ cmd format help="check & fix format errors" {
 	flag --fix help="format all the code"
 	cmd doctor help="check if the underlying tool is working correctly"
 }
-cmd check help="run static checks (run-run)" {
+cmd check help="run static checks" {
 	long_help "Runs `rr jsc` and `rr tsc` concurrently in-process. Aggregates their exit codes — non-zero when either subcommand fails."
 }
 cmd doctor help="run all plugin doctors" {

package/dist/config.d.mts

@@ -1,4 +1,4 @@
-import { u as Plugin } from "./types-BPHxibPr.mjs";
+import { u as Plugin } from "./types-DnqiiIxe.mjs";
 
 //#region src/types/config.d.ts
 type UserConfig = {

package/dist/plugin.d.mts

@@ -1,8 +1,46 @@
-import { C as Linter, D as TypeChecker, E as TypeCheckOptions, O as ReleaseService, S as LintOptions, T as StaticCheckerOptions, _ as Doctor, a as InstallFlags, b as FormatOptions, c as PLUGIN_KINDS, d as PluginCapabilities, f as PluginContext, g as UninstallResult, h as UninstallFlags, i as InstallContext, k as ReleaseServiceOptions, l as Packer, m as UninstallContext, n as ClackPromptsSelectOption, o as InstallResult, p as PluginKind, r as FileOp, s as JsonEdit, t as ClackPrompts, u as Plugin, v as DoctorOutput, w as StaticChecker, x as Formatter, y as DoctorResult } from "./types-BPHxibPr.mjs";
+import { C as Linter, D as TypeChecker, E as TypeCheckOptions, O as ReleaseService, S as LintOptions, T as StaticCheckerOptions, _ as Doctor, a as InstallFlags, b as FormatOptions, c as PLUGIN_KINDS, d as PluginCapabilities, f as PluginContext, g as UninstallResult, h as UninstallFlags, i as InstallContext, k as ReleaseServiceOptions, l as Packer, m as UninstallContext, n as ClackPromptsSelectOption, o as InstallResult, p as PluginKind, r as FileOp, s as JsonEdit, t as ClackPrompts, u as Plugin, v as DoctorOutput, w as StaticChecker, x as Formatter, y as DoctorResult } from "./types-DnqiiIxe.mjs";
 import { ShellService } from "@vlandoss/clibuddy";
 
+//#region src/plugin/decide-scaffold.d.ts
+type ScaffoldDecision = "create" | "patch" | "overwrite" | "skip";
+type DecideScaffoldOptions = {
+  /** The config file label shown to the user (e.g. `"biome.json"`, `"tsdown.config.ts"`). */label: string; /** Whether the file currently exists in the app project. */
+  fileExists: boolean; /** Short description of what "patch" does, shown in the select option. */
+  patchHint: string;
+  /**
+   * What to return when the file exists and the run is unattended (`--yes` / non-interactive).
+   * - `"patch"` (default): assume the user wants to merge our config into theirs (safe for JSON we can edit).
+   * - `"skip"`: assume the user owns the file (right for TS modules we'd otherwise rewrite blindly).
+   */
+  unattendedExistingAction?: "patch" | "skip";
+};
+declare function decideScaffold(ctx: InstallContext, opts: DecideScaffoldOptions): Promise<ScaffoldDecision>;
+//#endregion
 //#region src/plugin/define-plugin.d.ts
-declare function definePlugin<T = void>(factory: (options: T) => Plugin): (options: T) => Plugin;
+type Caps = Partial<PluginCapabilities>;
+type PluginDefinition<TCaps extends Caps> = {
+  name: string;
+  apiVersion: 1;
+  capabilities(ctx: PluginContext): TCaps | Promise<TCaps>;
+  install?(this: void, ctx: InstallContext): Promise<InstallResult>;
+  uninstall?(this: void, ctx: UninstallContext): Promise<UninstallResult>;
+};
+type WithOnly<TOptions, TKind extends PluginKind> = TOptions extends void ? {
+  only?: readonly TKind[];
+} : TOptions & {
+  only?: readonly TKind[];
+};
+declare function definePlugin<TCaps extends Caps, TOptions = void>(factory: (options: TOptions) => PluginDefinition<TCaps>): (options?: WithOnly<TOptions, keyof TCaps & PluginKind>) => Plugin;
+//#endregion
+//#region src/plugin/pick-preset.d.ts
+type PickPresetOptions<K extends string> = {
+  message: string;
+  presets: Record<K, {
+    label: string;
+  }>;
+  defaultPreset: K;
+};
+declare function pickPreset<K extends string>(ctx: InstallContext, opts: PickPresetOptions<K>): Promise<K>;
 //#endregion
 //#region ../../node_modules/.pnpm/tinyexec@1.1.2/node_modules/tinyexec/dist/main.d.mts
 //#endregion
@@ -49,4 +87,4 @@ declare class ToolService {
   doctor(): Promise<DoctorResult>;
 }
 //#endregion
-export { type ClackPrompts, type ClackPromptsSelectOption, type Doctor, type DoctorOutput, type DoctorResult, type FileOp, type FormatOptions, type Formatter, type InstallContext, type InstallFlags, type InstallResult, type JsonEdit, type LintOptions, type Linter, PLUGIN_KINDS, type Packer, type Plugin, type PluginCapabilities, type PluginContext, type PluginKind, ReleaseService, type ReleaseServiceOptions, type StaticChecker, type StaticCheckerOptions, ToolService, type ToolServiceOptions, type TypeCheckOptions, type TypeChecker, type UninstallContext, type UninstallFlags, type UninstallResult, definePlugin };
+export { type ClackPrompts, type ClackPromptsSelectOption, type DecideScaffoldOptions, type Doctor, type DoctorOutput, type DoctorResult, type FileOp, type FormatOptions, type Formatter, type InstallContext, type InstallFlags, type InstallResult, type JsonEdit, type LintOptions, type Linter, PLUGIN_KINDS, type Packer, type PickPresetOptions, type Plugin, type PluginCapabilities, type PluginContext, type PluginDefinition, type PluginKind, ReleaseService, type ReleaseServiceOptions, type ScaffoldDecision, type StaticChecker, type StaticCheckerOptions, ToolService, type ToolServiceOptions, type TypeCheckOptions, type TypeChecker, type UninstallContext, type UninstallFlags, type UninstallResult, decideScaffold, definePlugin, pickPreset };

package/dist/plugin.mjs

@@ -1,7 +1,37 @@
 import { resolvePackageBin } from "@vlandoss/clibuddy";
-//#region src/plugin/define-plugin.ts
-function definePlugin(factory) {
-	return factory;
+//#region src/plugin/decide-scaffold.ts
+async function decideScaffold(ctx, opts) {
+	const { label, fileExists, patchHint, unattendedExistingAction = "patch" } = opts;
+	if (!fileExists) {
+		if (ctx.flags.yes || ctx.flags.nonInteractive) return "create";
+		const choice = await ctx.prompts.confirm({
+			message: `Scaffold ${label}?`,
+			initialValue: true
+		});
+		if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+		return choice ? "create" : "skip";
+	}
+	if (ctx.flags.yes || ctx.flags.nonInteractive) return unattendedExistingAction;
+	const choice = await ctx.prompts.select({
+		message: `${label} already exists. What do you want to do?`,
+		options: [
+			{
+				value: "patch",
+				label: `Patch — ${patchHint}`
+			},
+			{
+				value: "skip",
+				label: "Skip — leave it alone"
+			},
+			{
+				value: "overwrite",
+				label: "Overwrite — replace with a fresh scaffold"
+			}
+		],
+		initialValue: "patch"
+	});
+	if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+	return choice;
 }
 //#endregion
 //#region src/plugin/tool-service.ts
@@ -53,6 +83,64 @@ var ToolService = class {
 	}
 };
 //#endregion
+//#region src/plugin/bin-probe.ts
+async function probeBins(services, pluginName) {
+	const toolServices = services.filter((s) => s instanceof ToolService);
+	const distinct = /* @__PURE__ */ new Map();
+	for (const svc of toolServices) if (!distinct.has(svc.pkg)) distinct.set(svc.pkg, svc);
+	if (distinct.size === 0) return;
+	const probes = [...distinct.values()].map(async (svc) => {
+		try {
+			await svc.getBinDir();
+		} catch {
+			return svc.pkg;
+		}
+		return null;
+	});
+	const missing = (await Promise.all(probes)).filter((p) => p !== null);
+	if (missing.length === 0) return;
+	const pkgName = `@rrlab/${pluginName}-plugin`;
+	throw new Error(`${pkgName} requires ${missing.join(", ")} to be installed in the host project. Run: rr plugins add ${pluginName}  (or: pnpm add -D ${missing.join(" ")})`);
+}
+//#endregion
+//#region src/plugin/define-plugin.ts
+function definePlugin(factory) {
+	return (options) => {
+		const def = factory(options);
+		const only = options?.only;
+		const pkgName = `@rrlab/${def.name}-plugin`;
+		return {
+			name: def.name,
+			apiVersion: def.apiVersion,
+			install: def.install,
+			uninstall: def.uninstall,
+			async capabilities(ctx) {
+				const map = await def.capabilities(ctx);
+				await probeBins(Object.values(map), def.name);
+				if (!only) return map;
+				for (const k of only) if (!(k in map)) throw new Error(`${pkgName}: unknown capability '${k}' in 'only'. Available: ${Object.keys(map).join(", ")}.`);
+				return Object.fromEntries(only.map((k) => [k, map[k]]));
+			}
+		};
+	};
+}
+//#endregion
+//#region src/plugin/pick-preset.ts
+async function pickPreset(ctx, opts) {
+	const { message, presets, defaultPreset } = opts;
+	if (ctx.flags.yes || ctx.flags.nonInteractive) return defaultPreset;
+	const choice = await ctx.prompts.select({
+		message,
+		options: Object.entries(presets).map(([value, meta]) => ({
+			value,
+			label: meta.label
+		})),
+		initialValue: defaultPreset
+	});
+	if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+	return choice;
+}
+//#endregion
 //#region src/plugin/types.ts
 const PLUGIN_KINDS = [
 	"lint",
@@ -107,4 +195,4 @@ var ReleaseService = class {
 	}
 };
 //#endregion
-export { PLUGIN_KINDS, ReleaseService, ToolService, definePlugin };
+export { PLUGIN_KINDS, ReleaseService, ToolService, decideScaffold, definePlugin, pickPreset };

package/dist/run.mjs

@@ -28,7 +28,8 @@ var PluginRegistry = class {
 		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.`);
+			const example = providers.map(({ plugin }) => `${plugin.name}({ only: ['${kind}'] })`).join(" or ");
+			throw new Error(`Multiple plugins provide capability '${kind}': ${names}. Narrow each plugin's capabilities in run-run.config.ts using the 'only' option — e.g. ${example}.`);
 		}
 		return first.impl;
 	}
@@ -121,9 +122,10 @@ async function createContext(binDir) {
 		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.`);
+		const got = plugin.apiVersion;
+		if (got !== 1) throw new Error(`Plugin '${plugin.name}' targets apiVersion ${got}, but this kernel supports only apiVersion 1.`);
 		debug("registering plugin: %s", plugin.name);
-		const capabilities = await plugin.setup(pluginContext);
+		const capabilities = await plugin.capabilities(pluginContext);
 		registry.register(plugin, capabilities);
 	}
 	return {
@@ -198,8 +200,8 @@ ${runRunColor(`
 * `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() {
+function createCheckCommand(ctx) {
+	return createCommand("check").summary(`run static checks${checkAnnotation(ctx)}`).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) => ({
@@ -230,6 +232,29 @@ function createCheckCommand() {
 function findCommand(program, name) {
 	return program.commands.find((c) => c.name() === name || c.aliases().includes(name));
 }
+/**
+* Mirrors the provider resolution of `jsc` + `tsc` and flattens the
+* underlying tool labels — e.g. biome (composed lint+format) + oxc (tsc)
+* renders as `(biome, oxlint)` rather than `(biome + biome, oxlint)`. When
+* neither sibling has a provider, falls back to the standard `(not
+* configured)` annotation so the help reads consistently with other
+* commands.
+*/
+function checkAnnotation(ctx) {
+	const directJsc = ctx.registry.get("jsc");
+	const linter = ctx.registry.get("lint");
+	const formatter = ctx.registry.get("format");
+	const tsc = ctx.registry.get("tsc");
+	const labels = [];
+	if (directJsc) labels.push(directJsc.ui);
+	else {
+		if (linter) labels.push(linter.ui);
+		if (formatter) labels.push(formatter.ui);
+	}
+	if (tsc) labels.push(tsc.ui);
+	if (labels.length === 0) return pluginAnnotation(void 0);
+	return pluginAnnotation({ ui: [...new Set(labels)].join(", ") });
+}
 //#endregion
 //#region src/program/commands/clean.ts
 function createCleanCommand() {
@@ -971,7 +996,7 @@ async function runRemove(ctx, alias, opts) {
 			}
 		});
 	} catch (err) {
-		clack.log.warn(`Could not load ${pkgName} for uninstall hook: ${err instanceof Error ? err.message : err}`);
+		clack.log.warn(`Could not load ${pkgName} for uninstall hook: ${err instanceof Error ? err.message : String(err)}`);
 	}
 	const planSteps = [];
 	if (inConfig) {
@@ -1036,9 +1061,9 @@ function isDistTag(spec) {
 function hasInPackageJson(ctx, pkgName) {
 	const pkg = ctx.appPkg.packageJson;
 	return pkgName in {
-		...pkg.dependencies ?? {},
-		...pkg.devDependencies ?? {},
-		...pkg.peerDependencies ?? {}
+		...pkg.dependencies,
+		...pkg.devDependencies,
+		...pkg.peerDependencies
 	};
 }
 async function withSpinner(message, fn) {
@@ -1189,7 +1214,7 @@ async function createProgram(options) {
 		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)),
+		}).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(ctx)).addCommand(createDoctorCommand(ctx)).addCommand(createPluginsCommand(ctx)).addCommand(createCleanCommand()).addCommand(createConfigCommand(ctx)),
 		ctx
 	};
 }

package/dist/{types-BPHxibPr.d.mts → types-DnqiiIxe.d.mts}

@@ -48,22 +48,22 @@ type DoctorResult = {
 };
 type Doctor = {
   ui: string;
-  doctor(): Promise<DoctorResult>;
+  doctor: () => Promise<DoctorResult>;
 };
 type Formatter = {
   bin: string;
   ui: string;
-  format(options: FormatOptions): Promise<void>;
+  format: (options: FormatOptions) => Promise<void>;
 };
 type Linter = {
   bin: string;
   ui: string;
-  lint(options: LintOptions): Promise<void>;
+  lint: (options: LintOptions) => Promise<void>;
 };
 type StaticChecker = {
   bin: string;
   ui: string;
-  check(options: StaticCheckerOptions): Promise<void>;
+  check: (options: StaticCheckerOptions) => Promise<void>;
 };
 type TypeCheckOptions = {
   /** Where to run the type checker. Defaults to the kernel's `cwd`. */cwd?: string;
@@ -71,14 +71,14 @@ type TypeCheckOptions = {
 type TypeChecker = {
   bin: string;
   ui: string;
-  check(options?: TypeCheckOptions): Promise<void>;
+  check: (options?: TypeCheckOptions) => Promise<void>;
 };
 //#endregion
 //#region src/plugin/types.d.ts
 type Packer = {
   bin: string;
   ui: string;
-  pack(): Promise<void>;
+  pack: () => Promise<void>;
 };
 declare const PLUGIN_KINDS: readonly ["lint", "format", "jsc", "tsc", "pack"];
 type PluginKind = (typeof PLUGIN_KINDS)[number];
@@ -99,7 +99,7 @@ type PluginContext = {
 type Plugin = {
   name: string;
   apiVersion: 1;
-  setup(ctx: PluginContext): Promise<PluginCapabilities> | PluginCapabilities;
+  capabilities(ctx: PluginContext): Promise<PluginCapabilities>;
   install?(ctx: InstallContext): Promise<InstallResult>;
   uninstall?(ctx: UninstallContext): Promise<UninstallResult>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rrlab/cli",
-  "version": "0.0.3",
+  "version": "0.0.4-git-c5c6e0f.0",
   "description": "The CLI toolbox to fullstack common scripts in Variable Land",
   "homepage": "https://github.com/variableland/dx/tree/main/run-run/cli#readme",
   "bugs": {
@@ -56,7 +56,7 @@
     "memoize": "10.2.0",
     "nypm": "0.6.0",
     "rimraf": "6.1.3",
-    "@vlandoss/loggy": "0.2.1",
+    "@vlandoss/loggy": "0.2.2-git-c5c6e0f.0",
     "@vlandoss/clibuddy": "0.6.1"
   },
   "devDependencies": {

package/src/lib/plugin.ts

@@ -1,4 +1,6 @@
-export { definePlugin } from "#src/plugin/define-plugin.ts";
+export { type DecideScaffoldOptions, decideScaffold, type ScaffoldDecision } from "#src/plugin/decide-scaffold.ts";
+export { definePlugin, type PluginDefinition } from "#src/plugin/define-plugin.ts";
+export { type PickPresetOptions, pickPreset } from "#src/plugin/pick-preset.ts";
 export { ToolService, type ToolServiceOptions } from "#src/plugin/tool-service.ts";
 export type {
   ClackPrompts,

package/src/plugin/bin-probe.ts

@@ -0,0 +1,30 @@
+import { ToolService } from "./tool-service.ts";
+
+export async function probeBins(services: readonly unknown[], pluginName: string): Promise<void> {
+  const toolServices = services.filter((s): s is ToolService => s instanceof ToolService);
+  const distinct = new Map<string, ToolService>();
+  for (const svc of toolServices) {
+    if (!distinct.has(svc.pkg)) distinct.set(svc.pkg, svc);
+  }
+
+  if (distinct.size === 0) return;
+
+  const probes = [...distinct.values()].map(async (svc) => {
+    try {
+      await svc.getBinDir();
+    } catch {
+      return svc.pkg;
+    }
+    return null;
+  });
+
+  const results = await Promise.all(probes);
+  const missing = results.filter((p): p is string => p !== null);
+  if (missing.length === 0) return;
+
+  const pkgName = `@rrlab/${pluginName}-plugin`;
+  throw new Error(
+    `${pkgName} requires ${missing.join(", ")} to be installed in the host project. ` +
+      `Run: rr plugins add ${pluginName}  (or: pnpm add -D ${missing.join(" ")})`,
+  );
+}

package/src/plugin/decide-scaffold.ts

@@ -0,0 +1,46 @@
+import type { InstallContext } from "./types.ts";
+
+export type ScaffoldDecision = "create" | "patch" | "overwrite" | "skip";
+
+export type DecideScaffoldOptions = {
+  /** The config file label shown to the user (e.g. `"biome.json"`, `"tsdown.config.ts"`). */
+  label: string;
+  /** Whether the file currently exists in the app project. */
+  fileExists: boolean;
+  /** Short description of what "patch" does, shown in the select option. */
+  patchHint: string;
+  /**
+   * What to return when the file exists and the run is unattended (`--yes` / non-interactive).
+   * - `"patch"` (default): assume the user wants to merge our config into theirs (safe for JSON we can edit).
+   * - `"skip"`: assume the user owns the file (right for TS modules we'd otherwise rewrite blindly).
+   */
+  unattendedExistingAction?: "patch" | "skip";
+};
+
+export async function decideScaffold(ctx: InstallContext, opts: DecideScaffoldOptions): Promise<ScaffoldDecision> {
+  const { label, fileExists, patchHint, unattendedExistingAction = "patch" } = opts;
+
+  if (!fileExists) {
+    if (ctx.flags.yes || ctx.flags.nonInteractive) return "create";
+    const choice = await ctx.prompts.confirm({
+      message: `Scaffold ${label}?`,
+      initialValue: true,
+    });
+    if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+    return choice ? "create" : "skip";
+  }
+
+  if (ctx.flags.yes || ctx.flags.nonInteractive) return unattendedExistingAction;
+
+  const choice = await ctx.prompts.select<ScaffoldDecision>({
+    message: `${label} already exists. What do you want to do?`,
+    options: [
+      { value: "patch", label: `Patch — ${patchHint}` },
+      { value: "skip", label: "Skip — leave it alone" },
+      { value: "overwrite", label: "Overwrite — replace with a fresh scaffold" },
+    ],
+    initialValue: "patch",
+  });
+  if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+  return choice;
+}

package/src/plugin/define-plugin.ts

@@ -1,5 +1,54 @@
-import type { Plugin } from "./types.ts";
+import { probeBins } from "./bin-probe.ts";
+import type {
+  InstallContext,
+  InstallResult,
+  Plugin,
+  PluginCapabilities,
+  PluginContext,
+  PluginKind,
+  UninstallContext,
+  UninstallResult,
+} from "./types.ts";
 
-export function definePlugin<T = void>(factory: (options: T) => Plugin): (options: T) => Plugin {
-  return factory;
+type Caps = Partial<PluginCapabilities>;
+
+export type PluginDefinition<TCaps extends Caps> = {
+  name: string;
+  apiVersion: 1;
+  capabilities(ctx: PluginContext): TCaps | Promise<TCaps>;
+  install?(this: void, ctx: InstallContext): Promise<InstallResult>;
+  uninstall?(this: void, ctx: UninstallContext): Promise<UninstallResult>;
+};
+
+type WithOnly<TOptions, TKind extends PluginKind> = TOptions extends void
+  ? { only?: readonly TKind[] }
+  : TOptions & { only?: readonly TKind[] };
+
+export function definePlugin<TCaps extends Caps, TOptions = void>(
+  factory: (options: TOptions) => PluginDefinition<TCaps>,
+): (options?: WithOnly<TOptions, keyof TCaps & PluginKind>) => Plugin {
+  return (options) => {
+    // biome-ignore lint/suspicious/noExplicitAny: factory accepts TOptions; callers without options pass undefined
+    const def = factory(options as any);
+    const only = (options as { only?: readonly string[] } | undefined)?.only;
+    const pkgName = `@rrlab/${def.name}-plugin`;
+
+    return {
+      name: def.name,
+      apiVersion: def.apiVersion,
+      install: def.install,
+      uninstall: def.uninstall,
+      async capabilities(ctx: PluginContext): Promise<PluginCapabilities> {
+        const map = (await def.capabilities(ctx)) as PluginCapabilities;
+        await probeBins(Object.values(map), def.name);
+        if (!only) return map;
+        for (const k of only) {
+          if (!(k in map)) {
+            throw new Error(`${pkgName}: unknown capability '${k}' in 'only'. Available: ${Object.keys(map).join(", ")}.`);
+          }
+        }
+        return Object.fromEntries(only.map((k) => [k, map[k as PluginKind]])) as PluginCapabilities;
+      },
+    };
+  };
 }

package/src/plugin/pick-preset.ts

@@ -0,0 +1,23 @@
+import type { InstallContext } from "./types.ts";
+
+export type PickPresetOptions<K extends string> = {
+  message: string;
+  presets: Record<K, { label: string }>;
+  defaultPreset: K;
+};
+
+export async function pickPreset<K extends string>(ctx: InstallContext, opts: PickPresetOptions<K>): Promise<K> {
+  const { message, presets, defaultPreset } = opts;
+  if (ctx.flags.yes || ctx.flags.nonInteractive) return defaultPreset;
+
+  const choice = await ctx.prompts.select<K>({
+    message,
+    options: (Object.entries(presets) as Array<[K, { label: string }]>).map(([value, meta]) => ({
+      value,
+      label: meta.label,
+    })),
+    initialValue: defaultPreset,
+  });
+  if (ctx.prompts.isCancel(choice)) throw new Error("Cancelled by user.");
+  return choice;
+}

package/src/plugin/registry.ts

@@ -18,9 +18,10 @@ export class PluginRegistry {
     if (!first) return undefined;
     if (rest.length > 0) {
       const names = providers.map(({ plugin }) => plugin.name).join(", ");
+      const example = providers.map(({ plugin }) => `${plugin.name}({ only: ['${kind}'] })`).join(" or ");
       throw new Error(
         `Multiple plugins provide capability '${kind}': ${names}. ` +
-          "Disambiguate by narrowing each plugin's capabilities in run-run.config.ts.",
+          `Narrow each plugin's capabilities in run-run.config.ts using the 'only' option — e.g. ${example}.`,
       );
     }
     return first.impl;

package/src/plugin/types.ts

@@ -20,7 +20,7 @@ export type {
 export type Packer = {
   bin: string;
   ui: string;
-  pack(): Promise<void>;
+  pack: () => Promise<void>;
 };
 
 export const PLUGIN_KINDS = ["lint", "format", "jsc", "tsc", "pack"] as const;
@@ -46,7 +46,7 @@ export type PluginContext = {
 export type Plugin = {
   name: string;
   apiVersion: 1;
-  setup(ctx: PluginContext): Promise<PluginCapabilities> | PluginCapabilities;
+  capabilities(ctx: PluginContext): Promise<PluginCapabilities>;
   install?(ctx: InstallContext): Promise<InstallResult>;
   uninstall?(ctx: UninstallContext): Promise<UninstallResult>;
 };

package/src/program/commands/check.ts

@@ -1,5 +1,6 @@
 import { type Command, createCommand } from "commander";
-import { TOOL_LABELS } from "#src/program/ui.ts";
+import { pluginAnnotation } from "#src/program/ui.ts";
+import type { Context } from "#src/services/ctx.ts";
 import { logger } from "#src/services/logger.ts";
 
 /**
@@ -15,9 +16,9 @@ import { logger } from "#src/services/logger.ts";
  * `command.js` — `fn.apply(this, actionArgs)`). `this.parent` gives us the
  * parent program without any late-binding ceremony.
  */
-export function createCheckCommand() {
+export function createCheckCommand(ctx: Context) {
   return createCommand("check")
-    .summary(`run static checks (${TOOL_LABELS.RUN_RUN})`)
+    .summary(`run static checks${checkAnnotation(ctx)}`)
     .description(
       "Runs `rr jsc` and `rr tsc` concurrently in-process. Aggregates their exit codes — non-zero when either subcommand fails.",
     )
@@ -61,3 +62,31 @@ export function createCheckCommand() {
 function findCommand(program: Command, name: string): Command | undefined {
   return program.commands.find((c) => c.name() === name || c.aliases().includes(name));
 }
+
+/**
+ * Mirrors the provider resolution of `jsc` + `tsc` and flattens the
+ * underlying tool labels — e.g. biome (composed lint+format) + oxc (tsc)
+ * renders as `(biome, oxlint)` rather than `(biome + biome, oxlint)`. When
+ * neither sibling has a provider, falls back to the standard `(not
+ * configured)` annotation so the help reads consistently with other
+ * commands.
+ */
+function checkAnnotation(ctx: Context): string {
+  const directJsc = ctx.registry.get("jsc");
+  const linter = ctx.registry.get("lint");
+  const formatter = ctx.registry.get("format");
+  const tsc = ctx.registry.get("tsc");
+
+  const labels: string[] = [];
+  if (directJsc) {
+    labels.push(directJsc.ui);
+  } else {
+    if (linter) labels.push(linter.ui);
+    if (formatter) labels.push(formatter.ui);
+  }
+  if (tsc) labels.push(tsc.ui);
+
+  if (labels.length === 0) return pluginAnnotation(undefined);
+  const distinct = [...new Set(labels)];
+  return pluginAnnotation({ ui: distinct.join(", ") });
+}

package/src/program/commands/plugins.ts

@@ -212,7 +212,7 @@ async function runRemove(ctx: Context, alias: OfficialAlias, opts: RemoveOptions
         });
       }
     } catch (err) {
-      clack.log.warn(`Could not load ${pkgName} for uninstall hook: ${err instanceof Error ? err.message : err}`);
+      clack.log.warn(`Could not load ${pkgName} for uninstall hook: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 
@@ -290,9 +290,9 @@ function isDistTag(spec: string): boolean {
 function hasInPackageJson(ctx: Context, pkgName: string): boolean {
   const pkg = ctx.appPkg.packageJson;
   const deps = {
-    ...(pkg.dependencies ?? {}),
-    ...(pkg.devDependencies ?? {}),
-    ...(pkg.peerDependencies ?? {}),
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+    ...pkg.peerDependencies,
   };
   return pkgName in deps;
 }

package/src/program/index.ts

@@ -40,7 +40,7 @@ export async function createProgram(options: Options) {
     .addCommand(createTsCheckCommand(ctx))
     .addCommand(createLintCommand(ctx))
     .addCommand(createFormatCommand(ctx))
-    .addCommand(createCheckCommand())
+    .addCommand(createCheckCommand(ctx))
     .addCommand(createDoctorCommand(ctx))
     .addCommand(createPluginsCommand(ctx))
     .addCommand(createCleanCommand())

package/src/services/ctx.ts

@@ -52,13 +52,12 @@ export async function createContext(binDir: string): Promise<Context> {
   };
 
   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.`,
-      );
+    const got = plugin.apiVersion as number;
+    if (got !== 1) {
+      throw new Error(`Plugin '${plugin.name}' targets apiVersion ${got}, but this kernel supports only apiVersion 1.`);
     }
     debug("registering plugin: %s", plugin.name);
-    const capabilities = await plugin.setup(pluginContext);
+    const capabilities = await plugin.capabilities(pluginContext);
     registry.register(plugin, capabilities);
   }
 

package/src/types/tool.ts

@@ -24,25 +24,25 @@ export type DoctorResult = {
 
 export type Doctor = {
   ui: string;
-  doctor(): Promise<DoctorResult>;
+  doctor: () => Promise<DoctorResult>;
 };
 
 export type Formatter = {
   bin: string;
   ui: string;
-  format(options: FormatOptions): Promise<void>;
+  format: (options: FormatOptions) => Promise<void>;
 };
 
 export type Linter = {
   bin: string;
   ui: string;
-  lint(options: LintOptions): Promise<void>;
+  lint: (options: LintOptions) => Promise<void>;
 };
 
 export type StaticChecker = {
   bin: string;
   ui: string;
-  check(options: StaticCheckerOptions): Promise<void>;
+  check: (options: StaticCheckerOptions) => Promise<void>;
 };
 
 export type TypeCheckOptions = {
@@ -53,5 +53,5 @@ export type TypeCheckOptions = {
 export type TypeChecker = {
   bin: string;
   ui: string;
-  check(options?: TypeCheckOptions): Promise<void>;
+  check: (options?: TypeCheckOptions) => Promise<void>;
 };