@rrlab/cli 1.1.0 → 1.1.1-git-4903a88.0

package/dist/tool-DKL6TauZ.d.mts

@@ -0,0 +1,43 @@
+//#region src/types/tool.d.ts
+type RunReport = {
+  ok: boolean;
+  output: string;
+};
+type FormatOptions = {
+  fix?: boolean;
+};
+type LintOptions = {
+  fix?: boolean;
+};
+type StaticCheckerOptions = {
+  fix?: boolean;
+  fixStaged?: boolean;
+};
+type TypeCheckOptions = {
+  cwd?: string;
+};
+type Doctor = {
+  doctor: () => Promise<RunReport>;
+};
+type Formatter = {
+  readonly ui: string;
+  format: (options: FormatOptions) => Promise<RunReport>;
+};
+type Linter = {
+  readonly ui: string;
+  lint: (options: LintOptions) => Promise<RunReport>;
+};
+type StaticChecker = {
+  readonly ui: string;
+  check: (options: StaticCheckerOptions) => Promise<RunReport>;
+};
+type TypeChecker = {
+  readonly ui: string;
+  check: (options?: TypeCheckOptions) => Promise<RunReport>;
+};
+type Packer = {
+  readonly ui: string;
+  pack: () => Promise<RunReport>;
+};
+//#endregion
+export { Linter as a, StaticChecker as c, TypeChecker as d, LintOptions as i, StaticCheckerOptions as l, FormatOptions as n, Packer as o, Formatter as r, RunReport as s, Doctor as t, TypeCheckOptions as u };

package/dist/{types-snfbujDH.d.mts → types-Iu4IyWof.d.mts}

@@ -1,3 +1,4 @@
+import { a as Linter, c as StaticChecker, d as TypeChecker, o as Packer, r as Formatter, t as Doctor } from "./tool-DKL6TauZ.mjs";
 import { Pkg, ShellService } from "@vlandoss/clibuddy";
 import { AnyLogger } from "@vlandoss/loggy";
 
@@ -26,74 +27,13 @@ declare class ReleaseService {
   resolve(pkg: string): Promise<string>;
 }
 //#endregion
-//#region src/types/tool.d.ts
-/**
- * The outcome of a check-family tool (lint / format / static check / type
- * check) captured rather than streamed. `ok` is the tool's exit code — never a
- * guess parsed from output, since tool summaries are unstable and not uniform
- * (tsc and oxfmt emit none) — and `output` is the combined stdout+stderr (color
- * preserved), flushed verbatim under the package label. See decisions/013.
- */
-type RunReport = {
-  ok: boolean;
-  output: string;
-};
-type FormatOptions = {
-  fix?: boolean;
-};
-type LintOptions = {
-  fix?: boolean;
-};
-type StaticCheckerOptions = {
-  fix?: boolean;
-  fixStaged?: boolean;
-};
-type Doctor = {
-  ui: string;
-  /**
-   * Verifies the tool is wired correctly. Returns a `RunReport` like every
-   * other verb so the board renders it identically — `output` leads with the
-   * `$ <bin> --help` liveness command, plus the error if the bin won't run.
-   */
-  doctor: () => Promise<RunReport>;
-};
-type Formatter = {
-  bin: string;
-  ui: string;
-  format: (options: FormatOptions) => Promise<RunReport>;
-};
-type Linter = {
-  bin: string;
-  ui: string;
-  lint: (options: LintOptions) => Promise<RunReport>;
-};
-type StaticChecker = {
-  bin: string;
-  ui: string;
-  check: (options: StaticCheckerOptions) => Promise<RunReport>;
-};
-type TypeCheckOptions = {
-  /** Where to run the type checker. Defaults to the kernel's `cwd`. */cwd?: string;
-};
-type TypeChecker = {
-  bin: string;
-  ui: string;
-  check: (options?: TypeCheckOptions) => Promise<RunReport>;
-};
-//#endregion
-//#region src/plugin/types.d.ts
-type Packer = {
-  bin: string;
-  ui: string;
-  pack: () => Promise<RunReport>;
-};
-declare const PLUGIN_KINDS: readonly ["lint", "format", "jsc", "tsc", "pack"];
-type PluginKind = (typeof PLUGIN_KINDS)[number];
-type PluginCapabilities = {
+//#region src/lib/plugin/types.d.ts
+type PluginCapability = keyof PluginServices;
+type PluginServices = {
   lint?: Linter & Doctor;
   format?: Formatter & Doctor;
-  jsc?: StaticChecker & Doctor;
-  tsc?: TypeChecker & Doctor;
+  jscheck?: StaticChecker & Doctor;
+  typecheck?: TypeChecker & Doctor;
   pack?: Packer & Doctor;
 };
 type PluginContext = {
@@ -104,9 +44,11 @@ type PluginContext = {
   cwd: string;
 };
 type Plugin = {
-  name: string;
   apiVersion: 1;
-  capabilities(ctx: PluginContext): Promise<PluginCapabilities>;
+  name: string;
+  readonly ui: string;
+  color(label: string): string;
+  services(ctx: PluginContext): Promise<PluginServices>;
   install?(ctx: InstallContext): Promise<InstallResult>;
   uninstall?(ctx: UninstallContext): Promise<UninstallResult>;
 };
@@ -142,12 +84,6 @@ type InstallContext = {
   appPkg: Pkg;
   prompts: ClackPrompts;
   flags: InstallFlags;
-  /**
-   * The release this install is running against — encapsulates the dist-tag the
-   * user picked (`rr plugins add biome@pr-226`) and resolves install specs for
-   * related packages under it. Use `ctx.release.resolve(pkg)` for every
-   * `@rrlab/*-config` sibling so previews and `latest` work uniformly.
-   */
   release: ReleaseService;
 };
 type UninstallContext = {
@@ -209,4 +145,4 @@ type UninstallResult = {
   files?: FileOp[];
 };
 //#endregion
-export { StaticChecker as C, ReleaseService as D, TypeChecker as E, ReleaseServiceOptions as O, RunReport as S, TypeCheckOptions as T, Doctor as _, InstallFlags as a, LintOptions as b, PLUGIN_KINDS as c, PluginCapabilities as d, PluginContext as f, UninstallResult as g, UninstallFlags as h, InstallContext as i, Packer as l, UninstallContext as m, ClackPromptsSelectOption as n, InstallResult as o, PluginKind as p, FileOp as r, JsonEdit as s, ClackPrompts as t, Plugin as u, FormatOptions as v, StaticCheckerOptions as w, Linter as x, Formatter as y };
+export { InstallFlags as a, Plugin as c, PluginServices as d, UninstallContext as f, ReleaseServiceOptions as g, ReleaseService as h, InstallContext as i, PluginCapability as l, UninstallResult as m, ClackPromptsSelectOption as n, InstallResult as o, UninstallFlags as p, FileOp as r, JsonEdit as s, ClackPrompts as t, PluginContext as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rrlab/cli",
-  "version": "1.1.0",
+  "version": "1.1.1-git-4903a88.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": {
@@ -24,8 +24,8 @@
       "default": "./dist/config.mjs"
     },
     "./plugin": {
-      "types": "./dist/plugin.d.mts",
-      "default": "./dist/plugin.mjs"
+      "types": "./dist/plugin/index.d.mts",
+      "default": "./dist/plugin/index.mjs"
     }
   },
   "bin": {
@@ -48,15 +48,16 @@
   "dependencies": {
     "@clack/prompts": "0.11.0",
     "@usage-spec/commander": "1.1.0",
-    "comment-json": "4.2.5",
     "commander": "14.0.3",
+    "comment-json": "4.2.5",
+    "fast-string-width": "3.0.2",
     "glob": "13.0.6",
     "lilconfig": "3.1.3",
     "magicast": "0.3.5",
     "memoize": "10.2.0",
     "nypm": "0.6.0",
     "rimraf": "6.1.3",
-    "@vlandoss/clibuddy": "0.7.0",
+    "@vlandoss/clibuddy": "0.7.1-git-4903a88.0",
     "@vlandoss/loggy": "0.2.1"
   },
   "devDependencies": {

package/src/actions/clean.ts

@@ -0,0 +1,36 @@
+import { cwd } from "@vlandoss/clibuddy";
+import { type GlobOptions, glob } from "glob";
+import { rimraf } from "rimraf";
+import { logger } from "#src/services/logger.ts";
+
+export type CleanOptions = {
+  onlyDist: boolean;
+  dryRun: boolean;
+};
+
+export type CleanActionConfig = {
+  options: CleanOptions;
+};
+
+export async function cleanAction({ options }: CleanActionConfig): Promise<void> {
+  async function run(paths: string[], globOptions: 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 });
+  }
+}

package/src/actions/config.ts

@@ -0,0 +1,46 @@
+import { palette } from "@vlandoss/clibuddy";
+import { Lines } from "#src/render/lines.ts";
+import { configuredPlugins, pkgCell, pluginVersionCell, relPath } from "#src/render/plugin-view.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import { SEP } from "#src/ui/theme.ts";
+
+export type ConfigActionConfig = {
+  ctx: ContextValue;
+};
+
+export function configAction({ ctx }: ConfigActionConfig): void {
+  const { meta } = ctx.config;
+
+  const lines = new Lines();
+
+  lines
+    .add(palette.bold("Source:"))
+    .add(
+      meta.filepath
+        ? `${relPath(ctx, meta.filepath)}${SEP}${palette.dim(`loaded in ${Math.round(meta.loadMs)}ms`)}`
+        : `${palette.dim("(no run-run.config — using defaults)")}`,
+      2,
+    )
+    .add(palette.bold("\nPlugins:"));
+
+  const plugins = configuredPlugins(ctx);
+
+  if (!plugins.length) {
+    lines.add(palette.dim("No plugins configured. Try `rr plugins add <name>`."), 2);
+  } else {
+    const rows = plugins.map((p) => ({
+      name: `${p.color("●")} ${p.name}`,
+      pkg: pkgCell(p.name),
+      version: pluginVersionCell(p.name, ctx.appPkg.dirPath),
+    }));
+
+    // biome-ignore format: i prefer multilines here
+    lines.addTable(rows, [
+      { key: "name" },
+      { key: "pkg", align: "right" },
+      { key: "version" }
+    ], { padStart: 2 });
+  }
+
+  lines.printStdout();
+}

package/src/actions/doctor.ts

@@ -0,0 +1,47 @@
+import { reportTask, runBoard } from "#src/render/board.ts";
+import { fanoutTitle, targetLabel } from "#src/render/labels.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import { logger } from "#src/services/logger.ts";
+import type { Doctor } from "#src/types/tool.ts";
+
+/** A capability impl reduced to what `doctor` needs: its health check plus the label to render it under. */
+export type DoctorService = Doctor & { readonly ui: string };
+
+export type DoctorActionConfig = {
+  ctx: ContextValue;
+};
+
+export type DoctorOneActionConfig = {
+  ctx: ContextValue;
+  service: DoctorService;
+};
+
+/**
+ * A single tool's `doctor` as one board row (`doctor (<tool>) · <pkg>`) — used
+ * by the `doctor` subcommand each plugin-backed command exposes.
+ */
+export async function doctorOneAction({ ctx, service }: DoctorOneActionConfig): Promise<void> {
+  const result = await runBoard([reportTask(targetLabel("doctor", service, ctx.appPkg), () => service.doctor())]);
+  if (!result.ok) process.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`, `jscheck`) from the same
+ * `BiomeService` instance; running its doctor three times is wasteful.
+ */
+export async function doctorAction({ ctx }: DoctorActionConfig): Promise<void> {
+  const services = ctx.plugins.getAllServices();
+
+  if (services.length === 0) {
+    logger.info("No plugins configured. Use `rr plugins add <name>` to install one.");
+    return;
+  }
+
+  // Each tool's health check is one parallel board row — a fan-out across
+  // tools, so the rows carry the tool name and the title omits a single tool.
+  const tasks = services.map((svc) => reportTask(svc.ui, () => svc.doctor()));
+  const result = await runBoard(tasks, { title: fanoutTitle("doctor", undefined, services.length, "tools") });
+  if (!result.ok) process.exitCode = 1;
+}

package/src/actions/format.ts

@@ -0,0 +1,13 @@
+import type { ContextValue } from "#src/services/context.ts";
+import type { Doctor, FormatOptions, Formatter } from "#src/types/tool.ts";
+import { runToolAction } from "./run-tool.ts";
+
+export type FormatActionConfig = {
+  ctx: ContextValue;
+  formatter: Formatter & Doctor;
+  options: FormatOptions;
+};
+
+export function formatAction({ ctx, formatter, options }: FormatActionConfig) {
+  return runToolAction({ ctx, name: "format", provider: formatter, run: (p) => p.format(options) });
+}

package/src/actions/jsc.ts

@@ -0,0 +1,13 @@
+import type { ContextValue } from "#src/services/context.ts";
+import type { Doctor, StaticChecker, StaticCheckerOptions } from "#src/types/tool.ts";
+import { runToolAction } from "./run-tool.ts";
+
+export type JscActionConfig = {
+  ctx: ContextValue;
+  checker: StaticChecker & Doctor;
+  options: StaticCheckerOptions;
+};
+
+export function jscAction({ ctx, checker, options }: JscActionConfig) {
+  return runToolAction({ ctx, name: "jsc", provider: checker, run: (p) => p.check(options) });
+}

package/src/actions/lint.ts

@@ -0,0 +1,13 @@
+import type { ContextValue } from "#src/services/context.ts";
+import type { Doctor, Linter, LintOptions } from "#src/types/tool.ts";
+import { runToolAction } from "./run-tool.ts";
+
+export type LintActionConfig = {
+  ctx: ContextValue;
+  linter: Linter & Doctor;
+  options: LintOptions;
+};
+
+export function lintAction({ ctx, linter, options }: LintActionConfig) {
+  return runToolAction({ ctx, name: "lint", provider: linter, run: (p) => p.lint(options) });
+}

package/src/actions/pack.ts

@@ -0,0 +1,12 @@
+import type { ContextValue } from "#src/services/context.ts";
+import type { Doctor, Packer } from "#src/types/tool.ts";
+import { runToolAction } from "./run-tool.ts";
+
+export type PackActionConfig = {
+  ctx: ContextValue;
+  packer: Packer & Doctor;
+};
+
+export function packAction({ ctx, packer }: PackActionConfig) {
+  return runToolAction({ ctx, name: "pack", provider: packer, run: (p) => p.pack() });
+}

package/src/actions/plugins/add.ts

@@ -0,0 +1,143 @@
+import path from "node:path";
+import * as clack from "@clack/prompts";
+import { addDependency, detectPackageManager, removeDependency } from "nypm";
+import { InvalidPluginModuleError } from "#src/errors/invalid-plugin-module.ts";
+import { UnknownPluginError } from "#src/errors/unknown-plugin.ts";
+import { PLUGINS_DIRECTORY, type PluginName } from "#src/lib/plugin/directory.ts";
+import type { InstallContext, InstallResult } from "#src/lib/plugin/types.ts";
+import { withSpinner } from "#src/render/steps.ts";
+import { ConfigAstService } from "#src/services/config-ast.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import { applyFileOp } from "#src/services/file-ops.ts";
+import { logger } from "#src/services/logger.ts";
+import { createClackPrompts } from "#src/services/prompts.ts";
+import { ReleaseService } from "#src/services/release.ts";
+import { describeWorkspaceChoice, resolveWorkspaceChoice, toNypmWorkspace } from "#src/services/workspace-target.ts";
+import { type AddOptions, hasInPackageJson, type PluginModule, reportFileOp } from "./shared.ts";
+
+/** Split a `<name>[@<spec>]` input (e.g. `biome@pr-226`) into the plugin name and optional spec. */
+function parsePluginSpec(input: string): { name: string; spec?: string } {
+  const at = input.indexOf("@");
+  if (at <= 0) return { name: input };
+  return { name: input.slice(0, at), spec: input.slice(at + 1) };
+}
+
+/** A dist-tag starts with a letter and contains only safe identifier chars. Version ranges (`^0.1`, `>=1`, `0.0.2`, `*`) don't match. */
+function isDistTag(spec: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(spec) && spec !== "latest";
+}
+
+export type AddPluginActionConfig = {
+  ctx: ContextValue;
+  args: { name: PluginName };
+  options: AddOptions;
+};
+
+export async function addPluginAction({ ctx, args, options }: AddPluginActionConfig): Promise<void> {
+  const { name: pluginName, spec } = parsePluginSpec(args.name);
+  if (!(pluginName in PLUGINS_DIRECTORY)) {
+    throw new UnknownPluginError(pluginName);
+  }
+  const { pkg: pkgName, name: binding } = PLUGINS_DIRECTORY[pluginName as PluginName];
+  const tag = spec && isDistTag(spec) ? spec : undefined;
+  const installSpec = spec ? `${pkgName}@${spec}` : pkgName;
+
+  clack.intro(` rr plugins add ${args.name} `);
+
+  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, binding);
+
+  if (inPkg && inConfig && !options.force && !spec) {
+    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);
+  // A spec means "(re)install at this spec" — upgrade even when the package is already in package.json.
+  const willInstall = !inPkg || !!spec;
+
+  if (options.dryRun) {
+    const presence = willInstall
+      ? inPkg
+        ? " (already present, will be updated to this spec)"
+        : ""
+      : " (already present, skipped)";
+    clack.log.info(`Would: install ${installSpec} as a devDependency in ${targetLabel}${presence}.`);
+    if (!inConfig) {
+      const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
+      clack.log.info(`Would: add ${binding}() 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 (willInstall) {
+    await withSpinner(`Installing ${installSpec}`, async () => {
+      await addDependency([installSpec], { cwd: ctx.appPkg.dirPath, dev: true, silent: true, workspace });
+    });
+    // Only mark for rollback when this was a fresh install — a failed upgrade can't be safely reverted to the previous version.
+    if (!inPkg) installedNow = true;
+  }
+
+  let installResult: InstallResult | undefined;
+  try {
+    const mod = (await import(pkgName)) as PluginModule;
+    const factory = mod.default;
+    if (typeof factory !== "function") {
+      throw new InvalidPluginModuleError(pkgName);
+    }
+    const plugin = factory();
+    if (plugin.install) {
+      const installCtx: InstallContext = {
+        shell: ctx.shell,
+        logger,
+        appPkg: ctx.appPkg,
+        prompts: createClackPrompts(),
+        flags: {
+          force: !!options.force,
+          yes: !!options.yes,
+          nonInteractive: !!options.yes,
+        },
+        release: new ReleaseService(tag),
+      };
+      installResult = await plugin.install(installCtx);
+    }
+  } catch (err) {
+    if (installedNow) {
+      try {
+        await removeDependency(pkgName, { cwd: ctx.appPkg.dirPath, silent: true, workspace });
+      } catch {
+        // best-effort rollback — don't mask the original error
+      }
+    }
+    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 ?? []) {
+    reportFileOp(await applyFileOp(ctx.appPkg.dirPath, op, !!options.force));
+  }
+
+  if (!inConfig) {
+    ast.addPlugin(loaded.mod, { exportName: binding, pkgName });
+    await ast.save(loaded);
+    const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
+    clack.log.success(`Updated ${rel}`);
+  }
+
+  clack.outro(`Plugin '${pluginName}' ready 🎉`);
+}

package/src/actions/plugins/list.ts

@@ -0,0 +1,27 @@
+import path from "node:path";
+import { ConfigAstService } from "#src/services/config-ast.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import { logger } from "#src/services/logger.ts";
+
+export type ListPluginsActionConfig = {
+  ctx: ContextValue;
+};
+
+export async function listPluginsAction({ ctx }: ListPluginsActionConfig): Promise<void> {
+  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}`);
+  }
+}

package/src/actions/plugins/remove.ts

@@ -0,0 +1,110 @@
+import path from "node:path";
+import * as clack from "@clack/prompts";
+import { detectPackageManager, removeDependency } from "nypm";
+import { PLUGINS_DIRECTORY, type PluginName } from "#src/lib/plugin/directory.ts";
+import type { UninstallResult } from "#src/lib/plugin/types.ts";
+import { withSpinner } from "#src/render/steps.ts";
+import { ConfigAstService } from "#src/services/config-ast.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import { applyFileOp, describeFileOp } from "#src/services/file-ops.ts";
+import { logger } from "#src/services/logger.ts";
+import { createClackPrompts } from "#src/services/prompts.ts";
+import { describeWorkspaceChoice, resolveWorkspaceChoice, toNypmWorkspace } from "#src/services/workspace-target.ts";
+import { hasInPackageJson, type PluginModule, type RemoveOptions, reportFileOp } from "./shared.ts";
+
+export type RemovePluginActionConfig = {
+  ctx: ContextValue;
+  args: { name: PluginName };
+  options: RemoveOptions;
+};
+
+export async function removePluginAction({ ctx, args, options }: RemovePluginActionConfig): Promise<void> {
+  const { name } = args;
+  const { pkg: pkgName, name: binding } = PLUGINS_DIRECTORY[name];
+
+  clack.intro(` rr plugins remove ${name} `);
+
+  const ast = new ConfigAstService();
+  const loaded = await ast.load(ctx.appPkg.dirPath);
+  const inConfig = !loaded.isNew && ast.hasPlugin(loaded.mod, binding);
+
+  // Collect plugin's uninstall plan (only if pkg is installed + has uninstall hook).
+  let uninstallResult: UninstallResult | undefined;
+  if (hasInPackageJson(ctx, pkgName)) {
+    try {
+      const mod = (await import(pkgName)) as PluginModule;
+      const factory = mod.default;
+      const plugin = typeof factory === "function" ? factory() : undefined;
+      if (plugin?.uninstall) {
+        uninstallResult = await plugin.uninstall({
+          shell: ctx.shell,
+          logger,
+          appPkg: ctx.appPkg,
+          prompts: createClackPrompts(),
+          flags: { yes: !!options.yes, nonInteractive: !!options.yes },
+        });
+      }
+    } catch (err) {
+      clack.log.warn(`Could not load ${pkgName} for uninstall hook: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  const planSteps: string[] = [];
+  if (inConfig) {
+    const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
+    planSteps.push(`Remove ${binding}() 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 '${name}' is not installed nor configured.`);
+    clack.outro("Nothing to do.");
+    return;
+  }
+
+  clack.log.message(`Plan:\n${planSteps.map((s) => `  • ${s}`).join("\n")}`);
+
+  if (options.dryRun) {
+    clack.outro("Dry run complete.");
+    return;
+  }
+
+  if (!options.yes) {
+    const choice = await clack.confirm({ message: "Proceed?", initialValue: false });
+    if (clack.isCancel(choice) || choice !== true) {
+      clack.outro("Aborted.");
+      return;
+    }
+  }
+
+  // Apply file ops first (they may need the plugin's source to still be importable).
+  for (const op of uninstallResult?.files ?? []) {
+    reportFileOp(await applyFileOp(ctx.appPkg.dirPath, op, /* force */ true));
+  }
+  if (inConfig) {
+    ast.removePlugin(loaded.mod, binding);
+    await ast.save(loaded);
+    const rel = path.relative(ctx.appPkg.dirPath, loaded.filepath) || loaded.filepath;
+    clack.log.success(`Removed ${binding}() from ${rel}`);
+  }
+  for (const dep of depsToRemove) {
+    await withSpinner(`Uninstalling ${dep}`, async () => {
+      await removeDependency(dep, { cwd: ctx.appPkg.dirPath, silent: true, workspace });
+    });
+  }
+
+  clack.outro(`Plugin '${name}' removed.`);
+}