@rrlab/cli 1.1.0 → 1.2.0

package/src/actions/plugins/shared.ts

@@ -0,0 +1,58 @@
+import * as clack from "@clack/prompts";
+import type { InstallContext, InstallResult, UninstallContext, UninstallResult } from "#src/lib/plugin/types.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import type { FileOpOutcome } from "#src/services/file-ops.ts";
+
+export type AddOptions = {
+  force?: boolean;
+  yes?: boolean;
+  dryRun?: boolean;
+};
+
+export type RemoveOptions = {
+  yes?: boolean;
+  dryRun?: boolean;
+};
+
+type InstallHook = (ctx: InstallContext) => Promise<InstallResult>;
+type UninstallHook = (ctx: UninstallContext) => Promise<UninstallResult>;
+export type PluginModule = { default?: (opts?: unknown) => { install?: InstallHook; uninstall?: UninstallHook } };
+
+export function hasInPackageJson(ctx: ContextValue, pkgName: string): boolean {
+  const pkg = ctx.appPkg.packageJson;
+  const deps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+    ...pkg.peerDependencies,
+  };
+  return pkgName in deps;
+}
+
+/** Renders a `FileOpOutcome` (from the `file-ops` engine) as the matching clack log line. */
+export function reportFileOp(outcome: FileOpOutcome): void {
+  switch (outcome.status) {
+    case "skipped-exists":
+      clack.log.warn(`Skipping ${outcome.path} — already exists. Use --force to overwrite.`);
+      return;
+    case "created":
+      clack.log.success(`Created ${outcome.path}`);
+      return;
+    case "overwritten":
+      clack.log.success(`Overwrote ${outcome.path}`);
+      return;
+    case "missing":
+      clack.log.warn(`Skipping ${outcome.path} — file does not exist.`);
+      return;
+    case "edited":
+      clack.log.success(`Edited ${outcome.path}`);
+      return;
+    case "unchanged":
+      clack.log.info(`No changes for ${outcome.path}.`);
+      return;
+    case "deleted":
+      clack.log.success(`Deleted ${outcome.path}`);
+      return;
+    case "absent":
+      return;
+  }
+}

package/src/actions/run-tool.ts

@@ -0,0 +1,23 @@
+import { reportTask, runBoard } from "#src/render/board.ts";
+import { type Provider, targetLabel } from "#src/render/labels.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import type { RunReport } from "#src/types/tool.ts";
+
+type RunToolActionOptions<P extends Provider> = {
+  ctx: ContextValue;
+  name: string;
+  provider: P;
+  run: (provider: P) => Promise<RunReport>;
+};
+
+/**
+ * The shared action for a single-provider tool command (lint, format, jsc,
+ * pack): run the provider's verb as one board row labelled `<name> (<tool>) ·
+ * <pkg>`, and aggregate the exit code. The command resolves the provider and
+ * throws MissingPluginError when it's absent, so the provider is required here.
+ * Commands that fan out (tsc) or compose siblings (check) drive the board themselves.
+ */
+export async function runToolAction<P extends Provider>({ ctx, name, provider, run }: RunToolActionOptions<P>): Promise<void> {
+  const result = await runBoard([reportTask(targetLabel(name, provider, ctx.appPkg), () => run(provider))]);
+  if (!result.ok) process.exitCode = 1;
+}

package/src/actions/tsc.ts

@@ -0,0 +1,65 @@
+import { type BoardTask, 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, TypeChecker } from "#src/types/tool.ts";
+
+export type TscActionConfig = {
+  ctx: ContextValue;
+  tsc: TypeChecker & Doctor;
+};
+
+type Scripts = Record<string, string | undefined> | undefined;
+
+const getPreScript = (scripts: Scripts) => scripts?.pretsc ?? scripts?.pretypecheck;
+
+export async function tscAction({ ctx, tsc }: TscActionConfig): Promise<void> {
+  const { appPkg, shell } = ctx;
+
+  const isTsProject = (dir: string) => appPkg.hasFile("tsconfig.json", dir);
+
+  // A package's `pretsc`/`pretypecheck` runs captured, inside the task, so its
+  // output stays grouped with that package. It may use shell features, so it
+  // goes through `/bin/sh -c`. A failing pre-script fails the task before tsc.
+  const typecheckTask = (label: string, dir: string, scripts: Scripts): BoardTask =>
+    reportTask(label, async () => {
+      const preScript = getPreScript(scripts);
+      if (preScript) {
+        const pre = await shell.at(dir).runCaptured(preScript, [], { shell: true, throwOnError: false });
+        if ((pre.exitCode ?? 0) !== 0) {
+          const output = [pre.stdout, pre.stderr]
+            .map((s) => s?.trim())
+            .filter(Boolean)
+            .join("\n");
+          return { ok: false, output: `pre-script \`${preScript}\` failed\n${output}` };
+        }
+      }
+      return tsc.check({ cwd: dir });
+    });
+
+  if (!appPkg.isMonorepo()) {
+    if (!isTsProject(appPkg.dirPath)) {
+      logger.info("No tsconfig.json found, skipping typecheck");
+      return;
+    }
+
+    // Single package → compact board; the row carries the canonical
+    // `tsc (<tool>) · <pkg>` label like every other single-target command.
+    const label = targetLabel("tsc", tsc, appPkg);
+    const result = await runBoard([typecheckTask(label, appPkg.dirPath, appPkg.packageJson.scripts)]);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  const projects = await appPkg.getWorkspaceProjects();
+  const tsProjects = projects.filter((project) => isTsProject(project.rootDir));
+
+  if (!tsProjects.length) {
+    logger.warn("No ts projects found in the monorepo, skipping typecheck");
+    return;
+  }
+
+  const tasks = tsProjects.map((p) => typecheckTask(p.manifest.name ?? p.rootDir, p.rootDir, p.manifest.scripts));
+  const result = await runBoard(tasks, { title: fanoutTitle("tsc", tsc, tsProjects.length, "packages") });
+  if (!result.ok) process.exitCode = 1;
+}

package/src/errors/invalid-plugin-module.ts

@@ -0,0 +1,6 @@
+/** Thrown when an installed plugin package doesn't export a default factory function. */
+export class InvalidPluginModuleError extends Error {
+  constructor(pkgName: string) {
+    super(`Plugin '${pkgName}' did not export a default factory function.`);
+  }
+}

package/src/errors/missing-plugin.ts

@@ -0,0 +1,17 @@
+import { providersOf } from "#src/lib/plugin/directory.ts";
+import type { PluginCapability } from "../lib/plugin/index.ts";
+
+export class MissingPluginError extends Error {
+  constructor(capability: PluginCapability) {
+    const plugins = providersOf(capability);
+
+    const pkgList = plugins.map((it) => it.pkg).join(", ");
+    const addList = plugins.map((it) => `rr plugins add ${it.name}`).join(" | ");
+
+    super(
+      `No plugin provides the '${capability}' capability.` +
+        (pkgList ? `\n  Install one of: ${pkgList}.` : "") +
+        (addList ? `\n  Try: ${addList}.` : ""),
+    );
+  }
+}

package/src/errors/plugin-api-version.ts

@@ -0,0 +1,6 @@
+/** Thrown when a configured plugin targets an apiVersion the kernel doesn't support. */
+export class PluginApiVersionError extends Error {
+  constructor(pluginName: string, got: number) {
+    super(`Plugin '${pluginName}' targets apiVersion ${got}, but this kernel supports only apiVersion 1.`);
+  }
+}

package/src/errors/unknown-plugin.ts

@@ -0,0 +1,7 @@
+import { allPluginNames } from "#src/lib/plugin/directory.ts";
+
+export class UnknownPluginError extends Error {
+  constructor(name: string) {
+    super(`'${name}' is invalid for argument 'name'. Allowed choices are ${allPluginNames().join(", ")}.`);
+  }
+}

package/src/lib/plugin/define-plugin.ts

@@ -0,0 +1,56 @@
+import { probeBins } from "./bin-probe.ts";
+import type {
+  InstallContext,
+  InstallResult,
+  Plugin,
+  PluginCapability,
+  PluginContext,
+  PluginServices,
+  UninstallContext,
+  UninstallResult,
+} from "./types.ts";
+
+export type PluginDefinition<TServices extends PluginServices> = {
+  apiVersion: 1;
+  name: string;
+  color: (value: string) => string;
+  services(ctx: PluginContext): TServices | Promise<TServices>;
+  install?(this: void, ctx: InstallContext): Promise<InstallResult>;
+  uninstall?(this: void, ctx: UninstallContext): Promise<UninstallResult>;
+};
+
+type Options<TKind extends PluginCapability> = { only?: readonly TKind[] };
+
+export function definePlugin<TServices extends PluginServices>(
+  definition: PluginDefinition<TServices>,
+): (options?: Options<keyof TServices & PluginCapability>) => Plugin {
+  return (options) => {
+    const only = options?.only;
+    const pkgName = `@rrlab/${definition.name}-plugin`;
+
+    return {
+      name: definition.name,
+      color: definition.color,
+      ui: definition.color(definition.name),
+      apiVersion: definition.apiVersion,
+      install: definition.install,
+      uninstall: definition.uninstall,
+      async services(ctx: PluginContext): Promise<PluginServices> {
+        const services = await definition.services(ctx);
+        await probeBins(Object.values(services), definition.name);
+
+        if (!only) {
+          return services;
+        }
+
+        for (const k of only) {
+          if (!(k in services)) {
+            throw new Error(`${pkgName}: unknown capability '${k}' in 'only'. Available: ${Object.keys(services).join(", ")}.`);
+          }
+        }
+
+        return Object.fromEntries(only.map((capability) => [capability, services[capability]]));
+      },
+    };
+  };
+}

package/src/lib/plugin/directory.ts

@@ -0,0 +1,30 @@
+import type { PluginCapability } from "./types.ts";
+
+type PluginInfo = {
+  readonly pkg: string;
+  readonly name: string;
+  readonly capabilities: PluginCapability[];
+};
+
+export const PLUGINS_DIRECTORY = {
+  ts: { pkg: "@rrlab/ts-plugin", name: "ts", capabilities: ["typecheck"] },
+  biome: { pkg: "@rrlab/biome-plugin", name: "biome", capabilities: ["format", "jscheck", "lint"] },
+  oxc: { pkg: "@rrlab/oxc-plugin", name: "oxc", capabilities: ["format", "lint", "jscheck", "typecheck"] },
+  tsdown: { pkg: "@rrlab/tsdown-plugin", name: "tsdown", capabilities: ["pack"] },
+} as const satisfies Record<string, PluginInfo>;
+
+export type PluginName = keyof typeof PLUGINS_DIRECTORY;
+
+export function allPluginNames(): readonly PluginName[] {
+  return Object.keys(PLUGINS_DIRECTORY) as PluginName[];
+}
+
+export function isPluginName(name: string): name is PluginName {
+  return Object.hasOwn(PLUGINS_DIRECTORY, name);
+}
+
+export function providersOf(capability: PluginCapability) {
+  return Object.values(PLUGINS_DIRECTORY).filter((info: PluginInfo) => {
+    return info.capabilities.includes(capability);
+  });
+}

package/src/lib/plugin/errors.ts

@@ -0,0 +1,15 @@
+/**
+ * Thrown by `PluginRegistry.get` when more than one plugin provides the same
+ * capability. The message is load-bearing for the "ambiguity → user narrows
+ * config" UX (decision 003) — `registry.test.ts` asserts the plugin names appear.
+ */
+export class MultipleProvidersError extends Error {
+  constructor(kind: string, pluginNames: readonly string[]) {
+    const names = pluginNames.join(", ");
+    const example = pluginNames.map((name) => `${name}({ only: ['${kind}'] })`).join(" or ");
+    super(
+      `Multiple plugins provide capability '${kind}': ${names}. ` +
+        `Narrow each plugin's capabilities in run-run.config.ts using the 'only' option — e.g. ${example}.`,
+    );
+  }
+}

package/src/lib/{plugin.ts → plugin/index.ts}

@@ -1,7 +1,8 @@
-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 { ReleaseService, type ReleaseServiceOptions } from "#src/services/release.ts";
+export { type DecideScaffoldOptions, decideScaffold, type ScaffoldDecision } from "./decide-scaffold.ts";
+export { definePlugin, type PluginDefinition } from "./define-plugin.ts";
+export { type PickPresetOptions, pickPreset } from "./pick-preset.ts";
+export { ToolService, type ToolServiceOptions } from "./tool-service.ts";
 export type {
   ClackPrompts,
   ClackPromptsSelectOption,
@@ -17,9 +18,9 @@ export type {
   LintOptions,
   Packer,
   Plugin,
-  PluginCapabilities,
+  PluginCapability,
   PluginContext,
-  PluginKind,
+  PluginServices,
   RunReport,
   StaticChecker,
   StaticCheckerOptions,
@@ -28,6 +29,4 @@ export type {
   UninstallContext,
   UninstallFlags,
   UninstallResult,
-} from "#src/plugin/types.ts";
-export { PLUGIN_KINDS } from "#src/plugin/types.ts";
-export { ReleaseService, type ReleaseServiceOptions } from "#src/services/release.ts";
+} from "./types.ts";

package/src/lib/plugin/registry.ts

@@ -0,0 +1,82 @@
+import { MissingPluginError } from "#src/errors/missing-plugin.ts";
+import { MultipleProvidersError } from "./errors.ts";
+import type { Plugin, PluginCapability, PluginServices } from "./types.ts";
+
+type RegistryEntry = {
+  plugin: Plugin;
+  services: PluginServices;
+};
+
+type Provider<K extends PluginCapability> = {
+  plugin: Plugin;
+  service: NonNullable<PluginServices[K]>;
+};
+
+export class PluginRegistry {
+  #entries: RegistryEntry[] = [];
+
+  register(plugin: Plugin, services: PluginServices) {
+    this.#entries.push({ plugin, services });
+  }
+
+  getServiceOrThrow<K extends PluginCapability>(capability: K) {
+    const provider = this.providerOf(capability);
+    if (!provider) {
+      throw new MissingPluginError(capability);
+    }
+    return provider.service;
+  }
+
+  getService<K extends PluginCapability>(capability: K) {
+    const provider = this.providerOf(capability);
+    return provider?.service;
+  }
+
+  getAllServices() {
+    const seen = new Set<NonNullable<PluginServices[PluginCapability]>>();
+
+    for (const { services } of this.#entries) {
+      for (const service of Object.values(services)) {
+        if (service) seen.add(service);
+      }
+    }
+
+    return [...seen];
+  }
+
+  providersOf<K extends PluginCapability>(capability: K) {
+    const providers: Array<Provider<K>> = [];
+
+    for (const { plugin, services } of this.#entries) {
+      const service = services[capability];
+
+      if (service) {
+        providers.push({
+          plugin,
+          service: service as NonNullable<PluginServices[K]>,
+        });
+      }
+    }
+
+    return providers;
+  }
+
+  providerOf<K extends PluginCapability>(capability: K) {
+    const providers = this.providersOf(capability);
+
+    const [first, ...rest] = providers;
+
+    if (!first) {
+      return undefined;
+    }
+
+    if (rest.length > 0) {
+      throw new MultipleProvidersError(
+        capability,
+        providers.map(({ plugin }) => plugin.name),
+      );
+    }
+
+    return first;
+  }
+}

package/src/{plugin → lib/plugin}/tool-service.ts

@@ -2,9 +2,9 @@ import { palette, resolvePackageBin, type ShellService } from "@vlandoss/clibudd
 import type { RunReport } from "#src/types/tool.ts";
 
 export type ToolServiceOptions = {
-  pkg: string;
-  bin?: string;
-  ui: string;
+  pkg?: string;
+  bin: string;
+  color: (str: string) => string;
   shellService: ShellService;
   /**
    * Module URL the resolver walks up from when looking for `pkg` in
@@ -24,25 +24,21 @@ export class ToolService {
   #shellService: ShellService;
   #pkg: string;
   #bin: string;
-  #ui: string;
   #from: string;
+  #ui: string;
 
-  get bin() {
-    return this.#bin;
+  get pkg() {
+    return this.#pkg;
   }
 
   get ui() {
     return this.#ui;
   }
 
-  get pkg() {
-    return this.#pkg;
-  }
-
-  constructor({ pkg, bin, ui, shellService, from }: ToolServiceOptions) {
-    this.#pkg = pkg;
-    this.#bin = bin ?? pkg;
-    this.#ui = ui;
+  constructor({ pkg, bin, color, shellService, from }: ToolServiceOptions) {
+    this.#bin = bin;
+    this.#pkg = pkg ?? bin;
+    this.#ui = color(bin);
     this.#shellService = shellService;
     this.#from = from;
   }

package/src/{plugin → lib/plugin}/types.ts

@@ -1,36 +1,17 @@
 import type { Pkg, ShellService } from "@vlandoss/clibuddy";
 import type { AnyLogger as Logger } from "@vlandoss/loggy";
 import type { ReleaseService } from "#src/services/release.ts";
-import type { Doctor, Formatter, Linter, RunReport, StaticChecker, TypeChecker } from "#src/types/tool.ts";
+import type { Doctor, Formatter, Linter, Packer, StaticChecker, TypeChecker } from "#src/types/tool.ts";
 
-export type {
-  Doctor,
-  FormatOptions,
-  Formatter,
-  Linter,
-  LintOptions,
-  RunReport,
-  StaticChecker,
-  StaticCheckerOptions,
-  TypeChecker,
-  TypeCheckOptions,
-} from "#src/types/tool.ts";
+export type * from "#src/types/tool.ts";
 
-export type Packer = {
-  bin: string;
-  ui: string;
-  pack: () => Promise<RunReport>;
-};
-
-export const PLUGIN_KINDS = ["lint", "format", "jsc", "tsc", "pack"] as const;
-
-export type PluginKind = (typeof PLUGIN_KINDS)[number];
+export type PluginCapability = keyof PluginServices;
 
-export type PluginCapabilities = {
+export type PluginServices = {
   lint?: Linter & Doctor;
   format?: Formatter & Doctor;
-  jsc?: StaticChecker & Doctor;
-  tsc?: TypeChecker & Doctor;
+  jscheck?: StaticChecker & Doctor;
+  typecheck?: TypeChecker & Doctor;
   pack?: Packer & Doctor;
 };
 
@@ -43,9 +24,11 @@ export type PluginContext = {
 };
 
 export 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>;
 };
@@ -83,12 +66,6 @@ export 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;
 };
 

package/src/program/base.ts

@@ -0,0 +1,75 @@
+import { Command } from "commander";
+import { Lines } from "#src/render/lines.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import type { PluginCapability } from "../lib/plugin/index.ts";
+
+class Cmd extends Command {
+  capabilities: PluginCapability[] = [];
+
+  addCapabilities(capabilities: PluginCapability[]) {
+    this.capabilities = capabilities;
+    return this;
+  }
+
+  addHelpTextAfter(ctx: ContextValue) {
+    super.addHelpText("after", () => {
+      const seeAlso = new Set<string>();
+
+      this.parent?.commands?.forEach((cmd) => {
+        if (cmd instanceof Cmd) {
+          const sameWork = cmd.capabilities.some((it) => this.capabilities.includes(it));
+          if (sameWork && cmd.name() !== this.name()) {
+            seeAlso.add(cmd.name());
+          }
+        }
+      });
+
+      const poweredBy = new Set<string>();
+
+      this.capabilities.forEach((it) => {
+        const provider = ctx.plugins.providerOf(it);
+
+        if (provider) {
+          poweredBy.add(provider.plugin.ui);
+        }
+      });
+
+      const lines = new Lines();
+
+      if (seeAlso.size > 0) {
+        lines.add("See also:").add(
+          [...seeAlso].map((it) => `- ${it}`),
+          2,
+        );
+      }
+
+      if (seeAlso.size > 0 && poweredBy.size > 0) {
+        lines.newline();
+      }
+
+      if (poweredBy.size > 0) {
+        lines.add("Powered by:").add(
+          [...poweredBy].map((it) => `- ${it}`),
+          2,
+        );
+      }
+
+      if (lines.isEmpty()) {
+        return "";
+      }
+
+      return lines.newline(true).render();
+    });
+
+    return this;
+  }
+
+  addDoctorCommand(actionFn: () => Promise<void>) {
+    const cmd = new Command("doctor").summary("check if the underlying tool is working correctly").action(actionFn);
+    return this.addCommand(cmd);
+  }
+}
+
+export function createCommand(name: string) {
+  return new Cmd(name);
+}