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

package/src/program/commands/tscheck.ts

@@ -0,0 +1,112 @@
+import { cwd, type ShellService } from "@vlandoss/clibuddy";
+import type { AnyLogger } from "@vlandoss/loggy";
+import { createCommand } from "commander";
+import type { Doctor, TypeChecker } from "#src/plugin/types.ts";
+import type { Context } from "#src/services/ctx.ts";
+import { logger } from "#src/services/logger.ts";
+import { missingPluginError } from "../missing-plugin.ts";
+import { pluginAnnotation } from "../ui.ts";
+import { createDoctorSubcommand } from "./doctor.ts";
+
+type TypecheckAtOptions = {
+  dir: string;
+  scripts: Record<string, string | undefined> | undefined;
+  log: AnyLogger;
+  shell: ShellService;
+  tsc: TypeChecker & Doctor;
+};
+
+const getPreScript = (scripts: Record<string, string | undefined> | undefined) => scripts?.pretsc ?? scripts?.pretypecheck;
+
+async function typecheckAt({ dir, scripts, log, shell, tsc }: TypecheckAtOptions) {
+  log.debug(`checking types at ${dir}`);
+
+  const shellAt = cwd === dir ? shell : shell.at(dir);
+
+  try {
+    const preScript = getPreScript(scripts);
+    if (preScript) {
+      log.start(`Running pre-script: ${preScript}`);
+      // Pre-scripts come from package.json and may contain shell features
+      // (`&&`, pipes, env-var substitution) — run them through `/bin/sh -c`.
+      await shellAt.run(preScript, [], { shell: true });
+      log.success("Pre-script completed");
+    }
+
+    log.start("Type checking started");
+    if (cwd === dir) {
+      await tsc.check();
+    } else {
+      await tsc.check({ cwd: dir });
+    }
+    log.success("Typecheck completed");
+  } catch (error) {
+    log.error("Typecheck failed");
+    throw error;
+  }
+}
+
+export function createTsCheckCommand(ctx: Context) {
+  const { appPkg, shell } = ctx;
+  const tsc = ctx.registry.get("tsc");
+
+  const cmd = createCommand("tsc")
+    .alias("tscheck")
+    .summary(`check typescript errors${pluginAnnotation(tsc)}`)
+    .description(
+      "Checks the TypeScript code for type errors, ensuring that the code adheres to the defined type constraints and helps catch potential issues before runtime.",
+    );
+
+  if (tsc) {
+    cmd.addCommand(createDoctorSubcommand(tsc));
+    cmd.addHelpText("afterAll", `\nUnder the hood, this command uses the ${tsc.ui} CLI to check the code.`);
+  }
+
+  cmd.action(async () => {
+    if (!tsc) throw missingPluginError("tsc");
+
+    const isTsProject = (dir: string) => appPkg.hasFile("tsconfig.json", dir);
+
+    if (!appPkg.isMonorepo()) {
+      if (!isTsProject(appPkg.dirPath)) {
+        logger.info("No tsconfig.json found, skipping typecheck");
+        return;
+      }
+
+      await typecheckAt({
+        shell,
+        tsc,
+        dir: appPkg.dirPath,
+        scripts: appPkg.packageJson.scripts,
+        log: logger,
+      });
+
+      return;
+    }
+
+    const 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;
+    }
+
+    await Promise.all(
+      tsProjects.map((p) =>
+        typecheckAt({
+          shell,
+          tsc,
+          dir: p.rootDir,
+          scripts: p.manifest.scripts,
+          log: logger.child({
+            tag: p.manifest.name,
+            namespace: "typecheck",
+          }),
+        }),
+      ),
+    );
+  });
+
+  return cmd;
+}

package/src/program/composed-jsc.ts

@@ -0,0 +1,35 @@
+import type { Doctor, DoctorResult, Formatter, Linter, StaticChecker, StaticCheckerOptions } from "#src/plugin/types.ts";
+
+/**
+ * Synthesises a `StaticChecker & Doctor` (the `jsc` capability) by composing
+ * a separately-registered linter and formatter. Used when the user's plugin
+ * set provides `lint` and `format` independently (e.g. oxc, or eslint +
+ * prettier) but no single plugin claims `jsc`.
+ *
+ * The check runs lint then format sequentially — interleaved stdout from a
+ * parallel run is hard to read for the user. `fixStaged` is dropped because
+ * the underlying tools don't have a uniform staged-aware mode.
+ */
+export function composedJscProvider(linter: Linter & Doctor, formatter: Formatter & Doctor): StaticChecker & Doctor {
+  return {
+    bin: `${linter.bin}+${formatter.bin}`,
+    ui: `${linter.ui} + ${formatter.ui}`,
+    async check({ fix }: StaticCheckerOptions) {
+      await linter.lint({ fix });
+      await formatter.format({ fix });
+    },
+    async doctor(): Promise<DoctorResult> {
+      const [lintRes, fmtRes] = await Promise.all([linter.doctor(), formatter.doctor()]);
+      const ok = lintRes.ok && fmtRes.ok;
+      const firstFailure = !lintRes.ok ? lintRes : !fmtRes.ok ? fmtRes : undefined;
+      return {
+        ok,
+        output: {
+          stdout: `${linter.ui}:\n${lintRes.output.stdout}\n\n${formatter.ui}:\n${fmtRes.output.stdout}`,
+          stderr: `${linter.ui}:\n${lintRes.output.stderr}\n\n${formatter.ui}:\n${fmtRes.output.stderr}`,
+          exitCode: firstFailure?.output.exitCode ?? 0,
+        },
+      };
+    },
+  };
+}

package/src/program/index.ts

@@ -0,0 +1,50 @@
+import { generateToStdout } from "@usage-spec/commander";
+import { palette } from "@vlandoss/clibuddy";
+import { type Command, createCommand, Option } from "commander";
+import { createContext } from "#src/services/ctx.ts";
+import { createCheckCommand } from "./commands/check.ts";
+import { createCleanCommand } from "./commands/clean.ts";
+import { createCompletionCommand } from "./commands/completion.ts";
+import { createConfigCommand } from "./commands/config.ts";
+import { createDoctorCommand } from "./commands/doctor.ts";
+import { createFormatCommand } from "./commands/format.ts";
+import { createJsCheckCommand } from "./commands/jscheck.ts";
+import { createLintCommand } from "./commands/lint.ts";
+import { createPackCommand } from "./commands/pack.ts";
+import { createPluginsCommand } from "./commands/plugins.ts";
+import { createTsCheckCommand } from "./commands/tscheck.ts";
+import { CREDITS_TEXT, getBannerText } from "./ui.ts";
+
+export type Options = {
+  binDir: string;
+};
+
+export async function createProgram(options: Options) {
+  const ctx = await createContext(options.binDir);
+  const version = ctx.binPkg.version;
+
+  const 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(this: Command) {
+      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));
+
+  return { program, ctx };
+}

package/src/program/missing-plugin.ts

@@ -0,0 +1,18 @@
+const SUGGESTIONS: Record<string, string[]> = {
+  lint: ["biome", "oxc", "eslint"],
+  format: ["biome", "oxc"],
+  jsc: ["biome"],
+  tsc: ["ts"],
+  pack: ["tsdown"],
+};
+
+export function missingPluginError(kind: string): Error {
+  const aliases = SUGGESTIONS[kind] ?? [];
+  const officialList = aliases.map((a) => `@rrlab/plugin-${a}`).join(", ");
+  const addList = aliases.map((a) => `rr plugins add ${a}`).join(" | ");
+  return new Error(
+    `No plugin provides the '${kind}' capability.` +
+      (officialList ? `\n  Install one of: ${officialList}.` : "") +
+      (addList ? `\n  Try: ${addList}.` : ""),
+  );
+}

package/src/program/ui.ts

@@ -0,0 +1,59 @@
+import { colorize, palette, text } from "@vlandoss/clibuddy";
+
+export const CREDITS_TEXT = `\nAcknowledgment:
+- kcd-scripts: for main inspiration
+  ${palette.link("https://github.com/kentcdodds/kcd-scripts")}
+
+- peruvian news: in honor to Run Run
+  ${palette.link("https://es.wikipedia.org/wiki/Run_Run")}`;
+
+const rimrafColor = colorize("#7C7270");
+const runRunColor = colorize("#E8722A");
+const usageColor = colorize("#24C55E");
+
+/**
+ * Labels used by kernel-internal commands. Plugin-owned tools (biome, oxc,
+ * tsdown, tsc) define their own colored labels inside each plugin's
+ * `src/index.ts`.
+ */
+export const TOOL_LABELS = {
+  RIMRAF: rimrafColor("rimraf"),
+  RUN_RUN: runRunColor("run-run"),
+  USAGE: usageColor("usage"),
+};
+
+const IS_USAGE_MODE = process.env.RR_USAGE_MODE === "1";
+
+/**
+ * Renders the parenthesised backend hint that follows a command's summary,
+ * e.g. `pack a ts library 📦 (tsdown)` or `… (not configured)` when no plugin
+ * provides the capability.
+ *
+ * Returns an empty string when `RR_USAGE_MODE=1` is set (the kernel's `bin`
+ * script exports it during `rr --usage`) so the KDL spec stays free of
+ * per-environment state — the active plugin set is a property of the host
+ * project, not of the CLI surface.
+ */
+export function pluginAnnotation(provider: { ui: string } | undefined): string {
+  if (IS_USAGE_MODE) return "";
+  return provider ? ` (${provider.ui})` : " (not configured)";
+}
+
+// npx figlet -f "ANSI Shadow" "run-run"
+export function getBannerText(version: string) {
+  const uiLogo = runRunColor(
+    `
+██████╗ ██╗   ██╗███╗   ██╗      ██████╗ ██╗   ██╗███╗   ██╗
+██╔══██╗██║   ██║████╗  ██║      ██╔══██╗██║   ██║████╗  ██║
+██████╔╝██║   ██║██╔██╗ ██║█████╗██████╔╝██║   ██║██╔██╗ ██║
+██╔══██╗██║   ██║██║╚██╗██║╚════╝██╔══██╗██║   ██║██║╚██╗██║
+██║  ██║╚██████╔╝██║ ╚████║      ██║  ██║╚██████╔╝██║ ╚████║
+╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝      ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ${text.version(version)}
+`.trim(),
+  );
+
+  return `
+${uiLogo}
+
+🦊 ${palette.italic(palette.muted("The CLI toolbox for"))} ${text.vland}\n`.trimStart();
+}

package/src/run.ts

@@ -0,0 +1,11 @@
+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));
+
+await run(async () => {
+  const { program } = await createProgram({ binDir: BIN_DIR });
+  await program.parseAsync(process.argv, { from: "node" });
+}, logger);

package/src/services/config-ast.ts

@@ -0,0 +1,202 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { builders, generateCode, loadFile, type ProxifiedModule, parseModule, writeFile } from "magicast";
+
+const CONFIG_FILENAMES = ["run-run.config.ts", "run-run.config.mts"] as const;
+
+export type PluginEntry = {
+  /** Local binding (e.g. `biome` for `import biome from "@rrlab/plugin-biome"`). */
+  exportName: string;
+  /** Full npm package name (e.g. `@rrlab/plugin-biome`). */
+  pkgName: string;
+};
+
+export type LoadedConfig = {
+  mod: ProxifiedModule;
+  filepath: string;
+  /** True when we generated a fresh config in memory because none existed on disk. */
+  isNew: boolean;
+};
+
+/**
+ * AST-level read/write for `run-run.config.{ts,mts}`. Wraps `magicast` so that
+ * adding/removing a plugin survives formatting, comments, and unrelated config
+ * options. The kernel and the `rr plugins add | remove` command use this
+ * service exclusively — no regex-based edits.
+ */
+export class ConfigAstService {
+  /**
+   * Looks for an existing `run-run.config.{ts,mts}` in `cwd`. If neither
+   * exists, returns a fresh magicast module built from a minimal template
+   * marked as `isNew: true`; the caller decides where to save it.
+   */
+  async load(cwd: string): Promise<LoadedConfig> {
+    for (const name of CONFIG_FILENAMES) {
+      const candidate = path.join(cwd, name);
+      try {
+        await fs.access(candidate);
+        const mod = await loadFile(candidate);
+        return { mod, filepath: candidate, isNew: false };
+      } catch {
+        // try the next candidate
+      }
+    }
+    const filepath = path.join(cwd, "run-run.config.mts");
+    return {
+      mod: parseModule(MINIMAL_TEMPLATE),
+      filepath,
+      isNew: true,
+    };
+  }
+
+  async save(loaded: LoadedConfig): Promise<void> {
+    if (loaded.isNew) {
+      // For a fresh file, write the generated code instead of using
+      // `writeFile` — writeFile expects an existing file as a starting point.
+      const { code } = generateCode(loaded.mod);
+      await fs.writeFile(loaded.filepath, code, "utf8");
+      return;
+    }
+    await writeFile(loaded.mod.$ast, loaded.filepath);
+  }
+
+  /**
+   * Returns true when the config's `plugins` array contains a call to the
+   * given `exportName` (e.g. `biome()`).
+   */
+  hasPlugin(mod: ProxifiedModule, exportName: string): boolean {
+    const plugins = this.#pluginsArray(mod);
+    if (!plugins) return false;
+    for (let i = 0; i < plugins.length; i++) {
+      const item = plugins[i];
+      if (this.#isCallTo(item, exportName)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Adds the import binding and pushes a `exportName()` call onto `plugins`.
+   * No-op when the call is already present (idempotent).
+   */
+  addPlugin(mod: ProxifiedModule, entry: PluginEntry): { changed: boolean } {
+    if (this.hasPlugin(mod, entry.exportName)) return { changed: false };
+
+    // Ensure the import binding exists.
+    if (!mod.imports[entry.exportName]) {
+      mod.imports.$add({ from: entry.pkgName, imported: "default", local: entry.exportName });
+    }
+
+    // Ensure `defineConfig` import + default export shape.
+    this.#ensureDefineConfig(mod);
+
+    // Push `exportName()` onto plugins[].
+    const plugins = this.#ensurePluginsArray(mod);
+    plugins.push(builders.functionCall(entry.exportName));
+
+    return { changed: true };
+  }
+
+  /**
+   * Removes the `exportName()` call from `plugins[]` and, if it was the last
+   * use of that local binding, removes the import too.
+   */
+  removePlugin(mod: ProxifiedModule, exportName: string): { changed: boolean } {
+    const plugins = this.#pluginsArray(mod);
+    if (!plugins) return { changed: false };
+
+    let changed = false;
+    // Iterate in reverse so splicing doesn't shift remaining indices we still
+    // need to inspect.
+    for (let i = plugins.length - 1; i >= 0; i--) {
+      if (this.#isCallTo(plugins[i], exportName)) {
+        plugins.splice(i, 1);
+        changed = true;
+      }
+    }
+
+    if (changed && mod.imports[exportName]) {
+      delete mod.imports[exportName];
+    }
+
+    return { changed };
+  }
+
+  /** Returns the list of plugin exportNames currently in `plugins[]`. */
+  listPlugins(mod: ProxifiedModule): string[] {
+    const plugins = this.#pluginsArray(mod);
+    if (!plugins) return [];
+    const out: string[] = [];
+    for (let i = 0; i < plugins.length; i++) {
+      const item = plugins[i];
+      const name = this.#calleeName(item);
+      if (name) out.push(name);
+    }
+    return out;
+  }
+
+  /**
+   * Locates `defineConfig({ plugins: [...] })` and returns the plugins array
+   * proxy. Returns `undefined` if the config doesn't have that shape.
+   */
+  #pluginsArray(mod: ProxifiedModule): unknown[] | undefined {
+    // biome-ignore lint/suspicious/noExplicitAny: magicast proxies are opaque
+    const def = (mod.exports as any).default;
+    if (!def || def.$type !== "function-call") return undefined;
+    // `def.$args` is a magicast ProxifiedArray (a Proxy, not a real Array) —
+    // `Array.isArray` returns false here, so guard on `.length` instead.
+    const args = def.$args;
+    if (!args || args.length === 0) return undefined;
+    const opts = args[0];
+    if (!opts || typeof opts !== "object") return undefined;
+    return opts.plugins;
+  }
+
+  #ensureDefineConfig(mod: ProxifiedModule): void {
+    if (!mod.imports.defineConfig) {
+      mod.imports.$add({ from: "@rrlab/cli/config", imported: "defineConfig", local: "defineConfig" });
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: magicast proxies are opaque
+    const def = (mod.exports as any).default;
+    if (!def) {
+      // biome-ignore lint/suspicious/noExplicitAny: shape mutation via proxy
+      (mod.exports as any).default = builders.functionCall("defineConfig", { plugins: [] });
+    }
+  }
+
+  #ensurePluginsArray(mod: ProxifiedModule): unknown[] {
+    // biome-ignore lint/suspicious/noExplicitAny: shape mutation via proxy
+    const def = (mod.exports as any).default;
+    const args = def.$args;
+    if (args.length === 0) {
+      args.push({ plugins: [] });
+    }
+    const opts = args[0];
+    if (!opts.plugins) {
+      opts.plugins = [];
+    }
+    return opts.plugins;
+  }
+
+  #isCallTo(item: unknown, exportName: string): boolean {
+    return this.#calleeName(item) === exportName;
+  }
+
+  #calleeName(item: unknown): string | undefined {
+    if (!item || typeof item !== "object") return undefined;
+    // Magicast call expressions expose `$type === "function-call"` and a
+    // `$callee` with the local identifier name.
+    // biome-ignore lint/suspicious/noExplicitAny: opaque proxy
+    const proxy = item as any;
+    if (proxy.$type !== "function-call") return undefined;
+    const callee = proxy.$callee;
+    if (typeof callee === "string") return callee;
+    return undefined;
+  }
+}
+
+const MINIMAL_TEMPLATE = `import { defineConfig } from "@rrlab/cli/config";
+
+export default defineConfig({
+  plugins: [],
+});
+`;

package/src/services/config.ts

@@ -0,0 +1,54 @@
+import os from "node:os";
+import { type AsyncSearcher, lilconfig } from "lilconfig";
+import type { ExportedConfig, UserConfig } from "#src/types/config.ts";
+import { logger } from "./logger.ts";
+
+const DEFAULT_CONFIG: UserConfig = {
+  plugins: [],
+};
+
+export class ConfigService {
+  #searcher: AsyncSearcher;
+
+  constructor() {
+    this.#searcher = lilconfig("run-run", {
+      searchPlaces: ["run-run.config.ts", "run-run.config.mts"],
+      cache: true,
+      stopDir: os.homedir(),
+      loaders: {
+        ".ts": (filepath: string) => import(filepath).then((mod) => mod.default),
+        ".mts": (filepath: string) => import(filepath).then((mod) => mod.default),
+      },
+    });
+  }
+
+  async load(): Promise<ExportedConfig> {
+    const debug = logger.subdebug("load-config");
+
+    const searchResult = await this.#searcher.search();
+
+    if (!searchResult || searchResult?.isEmpty) {
+      debug("loaded default config: %O", DEFAULT_CONFIG);
+      return {
+        config: DEFAULT_CONFIG,
+        meta: {
+          isDefault: true,
+          filepath: undefined,
+        },
+      };
+    }
+
+    const config = searchResult.config as UserConfig;
+
+    debug("loaded config: %O", config);
+    debug("config file: %s", searchResult.filepath);
+
+    return {
+      config,
+      meta: {
+        isDefault: false,
+        filepath: searchResult.filepath,
+      },
+    };
+  }
+}

package/src/services/ctx.ts

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import { createPkg, createShellService, cwd, type Pkg, type ShellService } from "@vlandoss/clibuddy";
+import { PluginRegistry } from "#src/plugin/registry.ts";
+import type { PluginContext } from "#src/plugin/types.ts";
+import type { ExportedConfig } from "#src/types/config.ts";
+import { ConfigService } from "./config.ts";
+import { logger } from "./logger.ts";
+
+export type Context = {
+  binPkg: Pkg;
+  appPkg: Pkg;
+  shell: ShellService;
+  config: ExportedConfig;
+  registry: PluginRegistry;
+};
+
+export async function createContext(binDir: string): Promise<Context> {
+  const debug = logger.subdebug("create-context");
+
+  const binPath = fs.realpathSync(binDir);
+
+  debug("bin path:", binPath);
+  debug("process cwd:", process.cwd());
+
+  const [appPkg, binPkg] = await Promise.all([createPkg(cwd), createPkg(binPath)]);
+
+  if (!binPkg) {
+    throw new Error("Could not find bin package.json");
+  }
+
+  if (!appPkg) {
+    throw new Error("Could not find app package.json");
+  }
+
+  debug("app pkg info: %O", appPkg.info());
+  debug("bin pkg info: %O", binPkg.info());
+
+  const shell = createShellService();
+
+  debug("shell service options: %O", shell.options);
+
+  const 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 ?? []) {
+    if (plugin.apiVersion !== 1) {
+      throw new Error(
+        `Plugin '${plugin.name}' targets apiVersion ${plugin.apiVersion}, but this kernel supports only apiVersion 1.`,
+      );
+    }
+    debug("registering plugin: %s", plugin.name);
+    const capabilities = await plugin.setup(pluginContext);
+    registry.register(plugin, capabilities);
+  }
+
+  return {
+    appPkg,
+    binPkg,
+    shell,
+    config,
+    registry,
+  };
+}