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

package/src/render/board.ts

@@ -0,0 +1,41 @@
+import { type BoardOptions, type BoardResult, type BoardTask, runTaskBoard } from "@vlandoss/clibuddy";
+import type { RunReport } from "#src/types/tool.ts";
+
+export type { BoardResult, BoardTask };
+
+/** Bridges a check-family verb (returns a `RunReport`) to a board row, its `output` becoming the flushed detail. */
+export function reportTask(label: string, run: () => Promise<RunReport>): BoardTask {
+  return {
+    label,
+    async run() {
+      const report = await run();
+      return { ok: report.ok, detail: report.output };
+    },
+  };
+}
+
+// While `rr check` is dispatching, boards stay framed (to divide the sections)
+// and their results land in this collector so `check` can print one verdict.
+let collector: BoardResult[] | null = null;
+
+export async function runCheckSections(run: () => Promise<void>): Promise<BoardResult[]> {
+  const previous = collector;
+  collector = [];
+  try {
+    await run();
+    return collector;
+  } finally {
+    collector = previous;
+  }
+}
+
+/** Runs the rows on the board and returns whether every row passed. */
+export async function runBoard(tasks: BoardTask[], options: BoardOptions = {}): Promise<BoardResult> {
+  const sink = collector;
+  const result = await runTaskBoard(tasks, { ...options, frame: options.frame ?? (sink !== null || undefined) });
+  // Record into the active check collector synchronously (we already awaited the
+  // board), so it's populated before our caller's `await runBoard(...)` resolves
+  // — no microtask race with the section's own continuation.
+  if (sink) sink.push(result);
+  return result;
+}

package/src/render/footer.ts

@@ -0,0 +1,31 @@
+import { palette } from "@vlandoss/clibuddy";
+import { Lines } from "#src/render/lines.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import { SEP } from "#src/ui/theme.ts";
+import { availableCell, installedCell, partitionPlugins, relPath } from "./plugin-view.ts";
+
+export function getFooterText(ctx: ContextValue): string {
+  const { installed, available } = partitionPlugins(ctx);
+
+  const installedLine = installed.map(installedCell).join("   ");
+  const availableLine = available.map(availableCell).join("   ");
+  const fromLine = ctx.config.meta.filepath
+    ? palette.dim(`from ${relPath(ctx, ctx.config.meta.filepath)}`)
+    : palette.dim("(no run-run.config — using defaults)");
+
+  const lines = new Lines();
+
+  lines.newline().add(palette.bold("Plugins:"));
+
+  if (installed.length > 0) {
+    lines.add(`${palette.bold("installed:")}  ${installedLine}${SEP}${fromLine}`, 2);
+  } else {
+    lines.add(`${palette.bold("installed:")}  ${palette.dim("(none)")}${SEP}${fromLine}`, 2);
+  }
+
+  if (available.length > 0) {
+    lines.add(`${palette.bold("available:")}  ${availableLine}${SEP}${palette.dim("install with `rr plugins add <name>`")}`, 2);
+  }
+
+  return lines.render();
+}

package/src/render/labels.ts

@@ -0,0 +1,28 @@
+import { basename } from "node:path";
+import { type Pkg, palette } from "@vlandoss/clibuddy";
+
+export type Provider = { ui: string };
+
+/** `<command> (<tool>)` — the verb plus the `ui` of the tool that backs it (e.g. `lint (biome)`, `tsc (tsc)`). */
+function commandTool(command: string, provider: Provider): string {
+  return `${command} (${provider.ui})`;
+}
+
+function pkgName(appPkg: Pkg): string {
+  return appPkg.packageJson.name ?? basename(appPkg.dirPath);
+}
+
+/** The canonical single-target row label, `<command> (<tool>) · <package>`, so every command reads alike. */
+export function targetLabel(command: string, provider: Provider, appPkg: Pkg): string {
+  return `${commandTool(command, provider)} ${palette.dim(`· ${pkgName(appPkg)}`)}`;
+}
+
+/**
+ * The canonical fan-out section title, `<command> (<tool>) · <n> <unit>`. The
+ * tool is omitted when the fan-out spans several tools (`rr doctor` → `doctor ·
+ * 3 tools`), since the rows then carry the per-tool name.
+ */
+export function fanoutTitle(command: string, provider: Provider | undefined, count: number, unit: string): string {
+  const head = provider ? commandTool(command, provider) : command;
+  return `${head} · ${count} ${unit}`;
+}

package/src/render/lines.ts

@@ -0,0 +1,100 @@
+import stringWidth from "fast-string-width";
+
+type Align = "left" | "right";
+
+interface Column<T> {
+  key: keyof T;
+  align?: Align;
+}
+
+interface TableOptions {
+  gap?: number;
+  padStart?: number;
+}
+
+export class Lines {
+  #lines: string[];
+
+  constructor() {
+    this.#lines = [];
+  }
+
+  isEmpty() {
+    return !this.#lines.length;
+  }
+
+  add(data: string | string[], padStart = 0) {
+    if (Array.isArray(data)) {
+      data.forEach((it) => {
+        this.#append(it, padStart);
+      });
+    } else {
+      this.#append(data, padStart);
+    }
+    return this;
+  }
+
+  addTable<T extends Record<string, unknown>>(rows: T[], columns: Column<T>[], opts: TableOptions = {}) {
+    const { gap = 3, padStart = 0 } = opts;
+
+    const sized = columns.map((col) => ({
+      ...col,
+      width: Math.max(...rows.map((row) => stringWidth(String(row[col.key])))),
+    }));
+    const sep = this.#sep(gap);
+
+    rows.forEach((row) => {
+      const cells = sized.map((col) => {
+        const raw = String(row[col.key]);
+        return this.#padCell(raw, col.width, col.align ?? "left");
+      });
+
+      this.#append(cells.join(sep), padStart);
+    });
+
+    return this;
+  }
+
+  newline(prepend = false) {
+    if (prepend) {
+      this.#prepend("");
+    } else {
+      this.#append("");
+    }
+    return this;
+  }
+
+  printStdout() {
+    process.stdout.write(`${this.render()}\n`);
+  }
+
+  render() {
+    return this.#lines.join("\n");
+  }
+
+  #padCell(str: string, width: number, align: Align) {
+    const diff = Math.max(0, width - stringWidth(str));
+    const fill = this.#sep(diff);
+    return align === "right" ? `${fill}${str}` : `${str}${fill}`;
+  }
+
+  #append(str: string, padStart = 0) {
+    if (padStart > 0) {
+      this.#lines.push(`${this.#sep(padStart)}${str}`);
+    } else {
+      this.#lines.push(str);
+    }
+  }
+
+  #prepend(str: string, padStart = 0) {
+    if (padStart > 0) {
+      this.#lines.unshift(`${this.#sep(padStart)}${str}`);
+    } else {
+      this.#lines.unshift(str);
+    }
+  }
+
+  #sep(count: number) {
+    return " ".repeat(count);
+  }
+}

package/src/render/plugin-view.ts

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { palette } from "@vlandoss/clibuddy";
+import { allPluginNames, isPluginName, PLUGINS_DIRECTORY } from "#src/lib/plugin/directory.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import { readPluginMeta } from "#src/services/plugin-meta.ts";
+import type { Plugin } from "../lib/plugin/index.ts";
+
+/**
+ * The single source of truth for how a plugin renders across the UI. The two
+ * plugin screens (the root help footer and `rr config`) stay separate
+ * composing functions, but every painted plugin cell comes from here — so a
+ * color/dot/version-format change happens in one place.
+ */
+
+/** Path of `abs` relative to the host project root, or `abs` itself when already there. */
+export function relPath(ctx: ContextValue, abs: string): string {
+  const rel = path.relative(ctx.appPkg.dirPath, abs);
+  return rel === "" ? abs : rel;
+}
+
+/** The plugin names present in the host's `run-run.config`, in config-file order. */
+export function configuredPlugins(ctx: ContextValue) {
+  return ctx.config.config.plugins ?? [];
+}
+
+/**
+ * Partition every plugin name into installed (configured) vs available (not yet
+ * configured), preserving `PLUGINS_DIRECTORY` declaration order — the order the
+ * root footer renders both rows in.
+ */
+export function partitionPlugins(ctx: ContextValue): { installed: Plugin[]; available: string[] } {
+  const configured = configuredPlugins(ctx);
+
+  const present = Object.fromEntries(configured.map((it) => [it.name, true]));
+
+  const available = allPluginNames().filter((name) => !present[name]);
+
+  return {
+    available,
+    installed: configured,
+  };
+}
+
+/** `● <name>` — a configured plugin in the root footer. */
+export function installedCell(plugin: Plugin): string {
+  return `${plugin.color("●")} ${plugin.name}`;
+}
+
+/** `○ <name>` (dim) — an available-but-unconfigured plugin in the root footer. */
+export function availableCell(label: string): string {
+  return `${palette.dim("○")} ${palette.dim(label)}`;
+}
+
+/** The npm package for a (kernel-trusted) plugin name — official lookup, else the `@rrlab/<name>-plugin` convention. */
+function pkgOf(name: string): string {
+  return isPluginName(name) ? PLUGINS_DIRECTORY[name].pkg : `@rrlab/${name}-plugin`;
+}
+
+/** The plugin's npm package name (dim) — `rr config` table column. */
+export function pkgCell(name: string): string {
+  return palette.dim(pkgOf(name));
+}
+
+/** `v<plugin-version>` or `v?` — `rr config` table column. */
+export function pluginVersionCell(name: string, appDir: string): string {
+  const { pluginVersion } = readPluginMeta(pkgOf(name), appDir);
+  return pluginVersion ? palette.success(`v${pluginVersion}`) : palette.dim("v?");
+}

package/src/render/steps.ts

@@ -0,0 +1,20 @@
+import * as clack from "@clack/prompts";
+
+/**
+ * Runs `fn` under a clack spinner: the message stays on success, and is
+ * suffixed with `— failed` (error level) before the error re-throws. Used by
+ * the interactive `plugins add/remove` flows to frame each install/uninstall
+ * step.
+ */
+export async function withSpinner<T>(message: string, fn: () => Promise<T>): Promise<T> {
+  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;
+  }
+}

package/src/run.ts

@@ -1,11 +1,5 @@
-import path from "node:path";
-import { dirnameOf, run } from "@vlandoss/clibuddy";
 import { createProgram } from "./program/index.ts";
-import { logger } from "./services/logger.ts";
 
-const BIN_DIR = path.dirname(dirnameOf(import.meta));
+const program = await createProgram(import.meta);
 
-await run(async () => {
-  const { program } = await createProgram({ binDir: BIN_DIR });
-  await program.parseAsync(process.argv, { from: "node" });
-}, logger);
+await program.run();

package/src/services/config.ts

@@ -25,7 +25,9 @@ export class ConfigService {
   async load(): Promise<ExportedConfig> {
     const debug = logger.subdebug("load-config");
 
+    const start = performance.now();
     const searchResult = await this.#searcher.search();
+    const loadMs = performance.now() - start;
 
     if (!searchResult || searchResult?.isEmpty) {
       debug("loaded default config: %O", DEFAULT_CONFIG);
@@ -34,6 +36,7 @@ export class ConfigService {
         meta: {
           isDefault: true,
           filepath: undefined,
+          loadMs,
         },
       };
     }
@@ -48,6 +51,7 @@ export class ConfigService {
       meta: {
         isDefault: false,
         filepath: searchResult.filepath,
+        loadMs,
       },
     };
   }

package/src/services/context.ts

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import { createPkg, createShellService, cwd, type Pkg, type ShellService } from "@vlandoss/clibuddy";
+import { PluginApiVersionError } from "#src/errors/plugin-api-version.ts";
+import { PluginRegistry } from "#src/lib/plugin/registry.ts";
+import type { PluginContext } from "#src/lib/plugin/types.ts";
+import type { ExportedConfig } from "#src/types/config.ts";
+import { ConfigService } from "./config.ts";
+import { logger } from "./logger.ts";
+import { PluginServices } from "./plugin-services.ts";
+
+export type ContextValue = {
+  binPkg: Pkg;
+  appPkg: Pkg;
+  shell: ShellService;
+  config: ExportedConfig;
+  plugins: PluginServices;
+};
+
+export class ContextService {
+  #binDir: string;
+
+  constructor(binDir: string) {
+    this.#binDir = binDir;
+  }
+
+  async getContext(): Promise<ContextValue> {
+    const debug = logger.subdebug("create-context");
+
+    const binPath = fs.realpathSync(this.#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 configService = new ConfigService();
+    const config = await configService.load();
+
+    const registry = new PluginRegistry();
+
+    const pluginContext: PluginContext = {
+      shell,
+      logger,
+      appPkg,
+      binPkg,
+      cwd,
+    };
+
+    for (const plugin of config.config.plugins ?? []) {
+      const got = plugin.apiVersion as number;
+      if (got !== 1) {
+        throw new PluginApiVersionError(plugin.name, got);
+      }
+      debug("registering plugin: %s", plugin.name);
+      const services = await plugin.services(pluginContext);
+      registry.register(plugin, services);
+    }
+
+    const plugins = new PluginServices(registry);
+
+    return {
+      appPkg,
+      binPkg,
+      shell,
+      config,
+      plugins,
+    };
+  }
+}

package/src/services/file-ops.ts

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { FileOp } from "#src/lib/plugin/types.ts";
+import { applyJsonEdits } from "./json-edit.ts";
+
+/**
+ * The semantic outcome of applying one `FileOp`. The engine performs the
+ * filesystem work and reports what happened — it never writes to the terminal.
+ * Callers (the `plugins add/remove` flows) map the outcome to their own
+ * progress UI, which keeps this engine pure and unit-testable without spawning.
+ */
+export type FileOpOutcome =
+  | { op: "create"; path: string; status: "created" | "overwritten" | "skipped-exists" }
+  | { op: "edit"; path: string; status: "edited" | "unchanged" | "missing" }
+  | { op: "delete"; path: string; status: "deleted" | "absent" };
+
+/**
+ * Applies a single declarative `FileOp` under `cwd`. `force` overrides the
+ * `create` overwrite guard. Idempotent for `delete` (absent file is a no-op)
+ * and skips edits when the target file is missing.
+ */
+export async function applyFileOp(cwd: string, op: FileOp, force: boolean): Promise<FileOpOutcome> {
+  const abs = path.join(cwd, op.path);
+
+  if (op.kind === "create") {
+    const exists = await pathExists(abs);
+    if (exists && !op.overwrite && !force) {
+      return { op: "create", path: op.path, status: "skipped-exists" };
+    }
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, op.content, "utf8");
+    return { op: "create", path: op.path, status: exists ? "overwritten" : "created" };
+  }
+
+  if (op.kind === "edit-json") {
+    if (!(await pathExists(abs))) return { op: "edit", path: op.path, status: "missing" };
+    const source = await fs.readFile(abs, "utf8");
+    const next = applyJsonEdits(source, op.edits);
+    if (next === source) return { op: "edit", path: op.path, status: "unchanged" };
+    await fs.writeFile(abs, next, "utf8");
+    return { op: "edit", path: op.path, status: "edited" };
+  }
+
+  if (op.kind === "edit-text") {
+    if (!(await pathExists(abs))) return { op: "edit", path: op.path, status: "missing" };
+    const source = await fs.readFile(abs, "utf8");
+    const next = op.edit(source);
+    if (next === source) return { op: "edit", path: op.path, status: "unchanged" };
+    await fs.writeFile(abs, next, "utf8");
+    return { op: "edit", path: op.path, status: "edited" };
+  }
+
+  if (!(await pathExists(abs))) return { op: "delete", path: op.path, status: "absent" };
+  await fs.unlink(abs);
+  return { op: "delete", path: op.path, status: "deleted" };
+}
+
+/** A one-line, side-effect-free description of a `FileOp` for the remove plan. */
+export function describeFileOp(op: FileOp): string {
+  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 pathExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/services/json-edit.ts

@@ -1,5 +1,5 @@
 import * as cjson from "comment-json";
-import type { JsonEdit } from "#src/plugin/types.ts";
+import type { JsonEdit } from "#src/lib/plugin/types.ts";
 
 /**
  * Applies a sequence of `JsonEdit` ops to a JSON / JSONC source string.

package/src/services/plugin-meta.ts

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+export type PluginMeta = {
+  /** Plugin npm package name, e.g. `@rrlab/biome-plugin`. */
+  pkgName: string;
+  /** Plugin npm package version, e.g. `1.1.0`. `undefined` when not resolvable. */
+  pluginVersion?: string;
+};
+
+/** Resolves the installed version of a plugin's npm package from the host's `node_modules`. */
+export function readPluginMeta(pkgName: string, fromDir: string): PluginMeta {
+  const result: PluginMeta = { pkgName };
+  const manifest = readPackageJson(pkgName, fromDir);
+  if (!manifest) return result;
+
+  result.pluginVersion = typeof manifest.version === "string" ? manifest.version : undefined;
+  return result;
+}
+
+type Manifest = {
+  version?: string;
+};
+
+function readPackageJson(pkgName: string, fromDir: string): Manifest | undefined {
+  try {
+    const resolved = require.resolve(`${pkgName}/package.json`, { paths: [fromDir] });
+    return JSON.parse(fs.readFileSync(resolved, "utf8")) as Manifest;
+  } catch {
+    // Some packages don't export `./package.json`. Fall back to walking up from
+    // the main entry.
+    try {
+      const entry = require.resolve(pkgName, { paths: [fromDir] });
+      const found = findPackageJsonUpwards(entry, pkgName);
+      return found ? (JSON.parse(fs.readFileSync(found, "utf8")) as Manifest) : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+function findPackageJsonUpwards(file: string, pkgName: string): string | undefined {
+  let dir = path.dirname(file);
+  // Walk up until we find a package.json whose `name` matches `pkgName`.
+  for (let i = 0; i < 12; i += 1) {
+    const candidate = path.join(dir, "package.json");
+    if (fs.existsSync(candidate)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(candidate, "utf8")) as { name?: string };
+        if (manifest.name === pkgName) return candidate;
+      } catch {
+        // ignore malformed package.json and keep walking
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}

package/src/services/plugin-services.ts

@@ -0,0 +1,41 @@
+import { MissingPluginError } from "#src/errors/missing-plugin.ts";
+import type { PluginRegistry } from "../lib/plugin/registry.ts";
+import type { PluginCapability } from "../lib/plugin/types.ts";
+import { StaticCheckService } from "./static-checker.ts";
+
+export class PluginServices {
+  #registry: PluginRegistry;
+
+  constructor(registry: PluginRegistry) {
+    this.#registry = registry;
+  }
+
+  getAllServices() {
+    return this.#registry.getAllServices();
+  }
+
+  providerOf<K extends PluginCapability>(capability: K) {
+    return this.#registry.providerOf(capability);
+  }
+
+  getServiceOrThrow<K extends PluginCapability>(capability: K) {
+    return this.#registry.getServiceOrThrow(capability);
+  }
+
+  getJsChecker() {
+    const checker = this.#registry.getService("jscheck");
+
+    if (checker) {
+      return checker;
+    }
+
+    const linter = this.#registry.getService("lint");
+    const formatter = this.#registry.getService("format");
+
+    if (linter && formatter) {
+      return new StaticCheckService(linter, formatter);
+    }
+
+    throw new MissingPluginError("jscheck");
+  }
+}

package/src/services/prompts.ts

@@ -1,5 +1,5 @@
 import * as clack from "@clack/prompts";
-import type { ClackPrompts } from "#src/plugin/types.ts";
+import type { ClackPrompts } from "#src/lib/plugin/types.ts";
 
 /**
  * Adapter that exposes the subset of `@clack/prompts` matching the

package/src/services/static-checker.ts

@@ -0,0 +1,46 @@
+import type { Doctor, Formatter, Linter, RunReport, StaticChecker, StaticCheckerOptions } from "#src/types/tool.ts";
+
+export class StaticCheckService implements StaticChecker, Doctor {
+  #linter: Linter & Doctor;
+  #formatter: Formatter & Doctor;
+
+  get ui() {
+    return `${this.#linter.ui} + ${this.#formatter.ui}`;
+  }
+
+  constructor(linter: Linter & Doctor, formatter: Formatter & Doctor) {
+    this.#linter = linter;
+    this.#formatter = formatter;
+  }
+
+  async check(options: StaticCheckerOptions): Promise<RunReport> {
+    const lintReport = await this.#linter.lint(options);
+    const formatReport = await this.#formatter.format(options);
+
+    return this.#mergeReports([
+      { ui: this.#linter.ui, report: lintReport },
+      { ui: this.#formatter.ui, report: formatReport },
+    ]);
+  }
+
+  async doctor(): Promise<RunReport> {
+    const [lintRes, fmtRes] = await Promise.all([this.#linter.doctor(), this.#formatter.doctor()]);
+
+    return this.#mergeReports([
+      { ui: this.#linter.ui, report: lintRes },
+      { ui: this.#formatter.ui, report: fmtRes },
+    ]);
+  }
+
+  #mergeReports(parts: Array<{ ui: string; report: RunReport }>): RunReport {
+    const sections = parts
+      .filter((part) => part.report.output.trim())
+      .map((part) => `${part.ui}:\n${part.report.output}`)
+      .join("\n\n");
+
+    return {
+      ok: parts.every((part) => part.report.ok),
+      output: sections,
+    };
+  }
+}

package/src/types/config.ts

@@ -1,4 +1,4 @@
-import type { Plugin } from "#src/plugin/types.ts";
+import type { Plugin } from "#src/lib/plugin/types.ts";
 
 export type UserConfig = {
   plugins?: Plugin[];
@@ -8,6 +8,7 @@ export type ExportedConfig = {
   config: UserConfig;
   meta: {
     isDefault: boolean;
+    loadMs: number;
     filepath?: string;
   };
 };