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

package/dist/types-C3V27_kd.d.mts

@@ -0,0 +1,173 @@
+import { Pkg, ShellService } from "@vlandoss/clibuddy";
+import { AnyLogger } from "@vlandoss/loggy";
+
+//#region src/types/tool.d.ts
+type FormatOptions = {
+  fix?: boolean;
+};
+type LintOptions = {
+  fix?: boolean;
+};
+type StaticCheckerOptions = {
+  fix?: boolean;
+  fixStaged?: boolean;
+};
+type DoctorOutput = {
+  stdout: string;
+  stderr: string;
+  exitCode: number | undefined;
+};
+type DoctorResult = {
+  ok: boolean;
+  output: DoctorOutput;
+};
+type Doctor = {
+  ui: string;
+  doctor(): Promise<DoctorResult>;
+};
+type Formatter = {
+  bin: string;
+  ui: string;
+  format(options: FormatOptions): Promise<void>;
+};
+type Linter = {
+  bin: string;
+  ui: string;
+  lint(options: LintOptions): Promise<void>;
+};
+type StaticChecker = {
+  bin: string;
+  ui: string;
+  check(options: StaticCheckerOptions): Promise<void>;
+};
+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<void>;
+};
+//#endregion
+//#region src/plugin/types.d.ts
+type Packer = {
+  bin: string;
+  ui: string;
+  pack(): Promise<void>;
+};
+declare const PLUGIN_KINDS: readonly ["lint", "format", "jsc", "tsc", "pack"];
+type PluginKind = (typeof PLUGIN_KINDS)[number];
+type PluginCapabilities = {
+  lint?: Linter & Doctor;
+  format?: Formatter & Doctor;
+  jsc?: StaticChecker & Doctor;
+  tsc?: TypeChecker & Doctor;
+  pack?: Packer & Doctor;
+};
+type PluginContext = {
+  shell: ShellService;
+  logger: AnyLogger;
+  appPkg: Pkg;
+  binPkg: Pkg;
+  cwd: string;
+};
+type Plugin = {
+  name: string;
+  apiVersion: 1;
+  setup(ctx: PluginContext): Promise<PluginCapabilities> | PluginCapabilities;
+  install?(ctx: InstallContext): Promise<InstallResult>;
+  uninstall?(ctx: UninstallContext): Promise<UninstallResult>;
+};
+type ClackPromptsSelectOption<T extends string> = {
+  value: T;
+  label: string;
+  hint?: string;
+};
+type ClackPrompts = {
+  select<T extends string>(opts: {
+    message: string;
+    options: Array<ClackPromptsSelectOption<T>>;
+    initialValue?: T;
+  }): Promise<T | symbol>;
+  confirm(opts: {
+    message: string;
+    initialValue?: boolean;
+  }): Promise<boolean | symbol>;
+  isCancel(value: unknown): value is symbol;
+};
+type InstallFlags = {
+  force: boolean;
+  yes: boolean;
+  nonInteractive: boolean;
+};
+type UninstallFlags = {
+  yes: boolean;
+  nonInteractive: boolean;
+};
+type InstallContext = {
+  shell: ShellService;
+  logger: AnyLogger;
+  appPkg: Pkg;
+  prompts: ClackPrompts;
+  flags: InstallFlags;
+};
+type UninstallContext = {
+  shell: ShellService;
+  logger: AnyLogger;
+  appPkg: Pkg;
+  prompts: ClackPrompts;
+  flags: UninstallFlags;
+};
+/**
+ * Declarative edits on a JSON file. Paths follow JSON Pointer (RFC 6901):
+ * `"/extends"`, `"/compilerOptions/strict"`, `"/extends/0"`.
+ *
+ * NOT strict RFC 6902 JSON Patch — those ops fail on path-condition
+ * mismatches (`add` fails if key exists; `replace` fails if missing), which
+ * doesn't work for our idempotent merge semantics. See D-005.
+ */
+type JsonEdit = {
+  op: "set";
+  path: string;
+  value: unknown; /** "replace" = always set; "if-missing" = only insert when the path doesn't resolve. */
+  mode?: "replace" | "if-missing";
+} | {
+  op: "unset";
+  path: string;
+} | {
+  op: "include";
+  path: string;
+  value: unknown; /** Where to insert into the target array if the value isn't already present. */
+  position?: "start" | "end";
+} | {
+  op: "exclude";
+  path: string;
+  value: unknown;
+};
+type FileOp = {
+  kind: "create";
+  path: string;
+  content: string;
+  overwrite?: boolean;
+} | {
+  kind: "edit-json";
+  path: string;
+  edits: JsonEdit[];
+} /** Escape hatch for non-JSON / TS-module edits. The plugin owns the parse. */ | {
+  kind: "edit-text";
+  path: string;
+  edit: (source: string) => string;
+} | {
+  kind: "delete";
+  path: string;
+};
+type InstallResult = {
+  /** Packages to install in the host's package.json as devDependencies. */devDependencies?: Record<string, string>;
+  files?: FileOp[];
+};
+type UninstallResult = {
+  /** Packages to remove from the host's package.json. */removeDependencies?: string[];
+  files?: FileOp[];
+};
+//#endregion
+export { Linter as C, TypeChecker as D, TypeCheckOptions as E, LintOptions as S, StaticCheckerOptions as T, Doctor as _, InstallFlags as a, FormatOptions 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, DoctorOutput as v, StaticChecker as w, Formatter as x, DoctorResult as y };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@rrlab/cli",
+  "version": "0.0.1-git-87d22db.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": {
+    "url": "https://github.com/variableland/dx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/variableland/dx.git",
+    "directory": "run-run/cli"
+  },
+  "license": "MIT",
+  "author": "rcrd <rcrd@variable.land>",
+  "type": "module",
+  "imports": {
+    "#src/*": "./src/*",
+    "#test/*": "./test/*"
+  },
+  "exports": {
+    "./config": {
+      "types": "./dist/config.d.mts",
+      "default": "./dist/config.mjs"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.mts",
+      "default": "./dist/plugin.mjs"
+    }
+  },
+  "bin": {
+    "rr": "./bin"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.*",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "0.11.0",
+    "@usage-spec/commander": "1.1.0",
+    "comment-json": "4.2.5",
+    "commander": "14.0.3",
+    "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.6.1-git-87d22db.0",
+    "@vlandoss/loggy": "0.2.1-git-87d22db.0"
+  },
+  "devDependencies": {
+    "tsdown": "0.22.0",
+    "@rrlab/tsdown-config": "^0.0.1-git-87d22db.0"
+  },
+  "scripts": {
+    "build": "tsdown && pnpm build:kdl",
+    "build:kdl": "./bin --usage > dist/cli.usage.kdl",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:types": "rr tsc"
+  }
+}

package/src/lib/config.ts

@@ -0,0 +1,5 @@
+import type { UserConfig } from "../types/config.ts";
+
+export function defineConfig(config: UserConfig) {
+  return config;
+}

package/src/lib/plugin.ts

@@ -0,0 +1,31 @@
+export { definePlugin } from "#src/plugin/define-plugin.ts";
+export { ToolService, type ToolServiceOptions } from "#src/plugin/tool-service.ts";
+export type {
+  ClackPrompts,
+  ClackPromptsSelectOption,
+  Doctor,
+  DoctorOutput,
+  DoctorResult,
+  FileOp,
+  FormatOptions,
+  Formatter,
+  InstallContext,
+  InstallFlags,
+  InstallResult,
+  JsonEdit,
+  Linter,
+  LintOptions,
+  Packer,
+  Plugin,
+  PluginCapabilities,
+  PluginContext,
+  PluginKind,
+  StaticChecker,
+  StaticCheckerOptions,
+  TypeChecker,
+  TypeCheckOptions,
+  UninstallContext,
+  UninstallFlags,
+  UninstallResult,
+} from "#src/plugin/types.ts";
+export { PLUGIN_KINDS } from "#src/plugin/types.ts";

package/src/plugin/define-plugin.ts

@@ -0,0 +1,5 @@
+import type { Plugin } from "./types.ts";
+
+export function definePlugin<T = void>(factory: (options: T) => Plugin): (options: T) => Plugin {
+  return factory;
+}

package/src/plugin/registry.ts

@@ -0,0 +1,47 @@
+import type { Plugin, PluginCapabilities, PluginKind } from "./types.ts";
+
+type Entry = {
+  plugin: Plugin;
+  capabilities: PluginCapabilities;
+};
+
+export class PluginRegistry {
+  #entries: Entry[] = [];
+
+  register(plugin: Plugin, capabilities: PluginCapabilities): void {
+    this.#entries.push({ plugin, capabilities });
+  }
+
+  get<K extends PluginKind>(kind: K): NonNullable<PluginCapabilities[K]> | undefined {
+    const providers = this.#providersOf(kind);
+    const [first, ...rest] = providers;
+    if (!first) return undefined;
+    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.",
+      );
+    }
+    return first.impl;
+  }
+
+  providersOf<K extends PluginKind>(kind: K): Array<{ name: string; impl: NonNullable<PluginCapabilities[K]> }> {
+    return this.#providersOf(kind).map(({ plugin, impl }) => ({ name: plugin.name, impl }));
+  }
+
+  plugins(): readonly Plugin[] {
+    return this.#entries.map(({ plugin }) => plugin);
+  }
+
+  #providersOf<K extends PluginKind>(kind: K): Array<{ plugin: Plugin; impl: NonNullable<PluginCapabilities[K]> }> {
+    const out: Array<{ plugin: Plugin; impl: NonNullable<PluginCapabilities[K]> }> = [];
+    for (const { plugin, capabilities } of this.#entries) {
+      const impl = capabilities[kind];
+      if (impl != null) {
+        out.push({ plugin, impl: impl as NonNullable<PluginCapabilities[K]> });
+      }
+    }
+    return out;
+  }
+}

package/src/plugin/tool-service.ts

@@ -0,0 +1,77 @@
+import { resolvePackageBin, type ShellService } from "@vlandoss/clibuddy";
+import type { DoctorResult } from "#src/types/tool.ts";
+
+export type ToolServiceOptions = {
+  pkg: string;
+  bin?: string;
+  ui: string;
+  shellService: ShellService;
+  /**
+   * Module URL the resolver walks up from when looking for `pkg` in
+   * `node_modules`. Plugins MUST pass their own `import.meta.url` so the
+   * binary is resolved from the plugin's own dependency graph (peer-installed
+   * by the host project), not the kernel's. Kernel-internal services pass
+   * `import.meta.url` of their own module file.
+   */
+  from: string;
+};
+
+export type ExecOptions = {
+  cwd?: string;
+  verbose?: boolean;
+};
+
+export class ToolService {
+  #shellService: ShellService;
+  #pkg: string;
+  #bin: string;
+  #ui: string;
+  #from: string;
+
+  get bin() {
+    return this.#bin;
+  }
+
+  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;
+    this.#shellService = shellService;
+    this.#from = from;
+  }
+
+  async getBinDir() {
+    return resolvePackageBin(this.#pkg, {
+      from: this.#from,
+      binName: this.#bin,
+    });
+  }
+
+  async exec(args: string[] = [], options: ExecOptions = {}) {
+    const { cwd, verbose } = options;
+    const sh = cwd ? this.#shellService.at(cwd) : this.#shellService;
+    return sh.run(await this.getBinDir(), args, { display: this.#bin, verbose });
+  }
+
+  async doctor(): Promise<DoctorResult> {
+    const output = await this.#shellService.runCaptured(await this.getBinDir(), ["--help"], { throwOnError: false });
+    const ok = output.exitCode === 0;
+
+    return {
+      ok,
+      output: {
+        stdout: output.stdout,
+        stderr: output.stderr,
+        exitCode: output.exitCode,
+      },
+    };
+  }
+}

package/src/plugin/types.ts

@@ -0,0 +1,139 @@
+import type { Pkg, ShellService } from "@vlandoss/clibuddy";
+import type { AnyLogger as Logger } from "@vlandoss/loggy";
+import type { Doctor, Formatter, Linter, StaticChecker, TypeChecker } from "#src/types/tool.ts";
+
+export type {
+  Doctor,
+  DoctorOutput,
+  DoctorResult,
+  FormatOptions,
+  Formatter,
+  Linter,
+  LintOptions,
+  StaticChecker,
+  StaticCheckerOptions,
+  TypeChecker,
+  TypeCheckOptions,
+} from "#src/types/tool.ts";
+
+export type Packer = {
+  bin: string;
+  ui: string;
+  pack(): Promise<void>;
+};
+
+export const PLUGIN_KINDS = ["lint", "format", "jsc", "tsc", "pack"] as const;
+
+export type PluginKind = (typeof PLUGIN_KINDS)[number];
+
+export type PluginCapabilities = {
+  lint?: Linter & Doctor;
+  format?: Formatter & Doctor;
+  jsc?: StaticChecker & Doctor;
+  tsc?: TypeChecker & Doctor;
+  pack?: Packer & Doctor;
+};
+
+export type PluginContext = {
+  shell: ShellService;
+  logger: Logger;
+  appPkg: Pkg;
+  binPkg: Pkg;
+  cwd: string;
+};
+
+export type Plugin = {
+  name: string;
+  apiVersion: 1;
+  setup(ctx: PluginContext): Promise<PluginCapabilities> | PluginCapabilities;
+  install?(ctx: InstallContext): Promise<InstallResult>;
+  uninstall?(ctx: UninstallContext): Promise<UninstallResult>;
+};
+
+export type ClackPromptsSelectOption<T extends string> = {
+  value: T;
+  label: string;
+  hint?: string;
+};
+
+export type ClackPrompts = {
+  select<T extends string>(opts: {
+    message: string;
+    options: Array<ClackPromptsSelectOption<T>>;
+    initialValue?: T;
+  }): Promise<T | symbol>;
+  confirm(opts: { message: string; initialValue?: boolean }): Promise<boolean | symbol>;
+  isCancel(value: unknown): value is symbol;
+};
+
+export type InstallFlags = {
+  force: boolean;
+  yes: boolean;
+  nonInteractive: boolean;
+};
+
+export type UninstallFlags = {
+  yes: boolean;
+  nonInteractive: boolean;
+};
+
+export type InstallContext = {
+  shell: ShellService;
+  logger: Logger;
+  appPkg: Pkg;
+  prompts: ClackPrompts;
+  flags: InstallFlags;
+};
+
+export type UninstallContext = {
+  shell: ShellService;
+  logger: Logger;
+  appPkg: Pkg;
+  prompts: ClackPrompts;
+  flags: UninstallFlags;
+};
+
+/**
+ * Declarative edits on a JSON file. Paths follow JSON Pointer (RFC 6901):
+ * `"/extends"`, `"/compilerOptions/strict"`, `"/extends/0"`.
+ *
+ * NOT strict RFC 6902 JSON Patch — those ops fail on path-condition
+ * mismatches (`add` fails if key exists; `replace` fails if missing), which
+ * doesn't work for our idempotent merge semantics. See D-005.
+ */
+export type JsonEdit =
+  | {
+      op: "set";
+      path: string;
+      value: unknown;
+      /** "replace" = always set; "if-missing" = only insert when the path doesn't resolve. */
+      mode?: "replace" | "if-missing";
+    }
+  | { op: "unset"; path: string }
+  | {
+      op: "include";
+      path: string;
+      value: unknown;
+      /** Where to insert into the target array if the value isn't already present. */
+      position?: "start" | "end";
+    }
+  | { op: "exclude"; path: string; value: unknown };
+
+export type FileOp =
+  | { kind: "create"; path: string; content: string; overwrite?: boolean }
+  | { kind: "edit-json"; path: string; edits: JsonEdit[] }
+  /** Escape hatch for non-JSON / TS-module edits. The plugin owns the parse. */
+  | { kind: "edit-text"; path: string; edit: (source: string) => string }
+  | { kind: "delete"; path: string };
+
+export type InstallResult = {
+  /** Packages to install in the host's package.json as devDependencies. */
+  devDependencies?: Record<string, string>;
+  files?: FileOp[];
+};
+
+export type UninstallResult = {
+  /** Packages to remove from the host's package.json. */
+  removeDependencies?: string[];
+  files?: FileOp[];
+};

package/src/program/commands/check.ts

@@ -0,0 +1,63 @@
+import { type Command, createCommand } from "commander";
+import { TOOL_LABELS } from "#src/program/ui.ts";
+import { logger } from "#src/services/logger.ts";
+
+/**
+ * `rr check` is the umbrella that runs the JS check (lint+format) and the
+ * TS type check together. Both subcommands are already wired into
+ * commander as siblings (`rr jsc`, `rr tsc`), so we reuse the program's
+ * command tree as the action registry instead of duplicating it: look the
+ * sibling up by name and invoke its action via `parseAsync([])`, which
+ * applies its declared option defaults exactly as if the user had typed
+ * `rr jsc` directly.
+ *
+ * Commander binds the running command as `this` inside an action (see
+ * `command.js` — `fn.apply(this, actionArgs)`). `this.parent` gives us the
+ * parent program without any late-binding ceremony.
+ */
+export 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(this: Command) {
+      const program = this.parent;
+      if (!program) {
+        // Can only happen if this command is invoked detached from the root
+        // program — current bin only constructs it as a subcommand.
+        throw new Error("`rr check` requires the parent program to dispatch sibling subcommands.");
+      }
+
+      const targets = ["jsc", "tsc"];
+      const cmds = targets.map((name) => ({ name, cmd: findCommand(program, name) }));
+
+      const missing = cmds.filter(({ cmd }) => !cmd).map(({ name }) => name);
+      if (missing.length > 0) {
+        for (const name of missing) logger.error(`rr check: subcommand "${name}" is not registered.`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const results = await Promise.allSettled(
+        // biome-ignore lint/style/noNonNullAssertion: missing is guarded above
+        cmds.map(({ cmd }) => cmd!.parseAsync([], { from: "user" })),
+      );
+
+      const failed: Array<{ name: string; reason: unknown }> = [];
+      for (const [i, r] of results.entries()) {
+        if (r.status === "rejected") failed.push({ name: cmds[i]?.name ?? "?", reason: r.reason });
+      }
+      if (failed.length > 0) {
+        for (const { name, reason } of failed) {
+          const msg = reason instanceof Error ? reason.message : String(reason);
+          logger.error(`rr check (${name}): ${msg}`);
+        }
+        process.exitCode = 1;
+      }
+    });
+}
+
+function findCommand(program: Command, name: string): Command | undefined {
+  return program.commands.find((c) => c.name() === name || c.aliases().includes(name));
+}

package/src/program/commands/clean.ts

@@ -0,0 +1,53 @@
+import { cwd } from "@vlandoss/clibuddy";
+import { createCommand } from "commander";
+import { type GlobOptions, glob } from "glob";
+import { rimraf } from "rimraf";
+import { logger } from "#src/services/logger.ts";
+import { TOOL_LABELS } from "../ui.ts";
+
+type Options = {
+  onlyDist: boolean;
+  dryRun: boolean;
+};
+
+export function createCleanCommand() {
+  return createCommand("clean")
+    .summary(`delete dirty files (${TOOL_LABELS.RIMRAF})`)
+    .description("Deletes generated files and folders such as 'dist', 'node_modules', and lock files to ensure a clean state.")
+    .option("--only-dist", "delete 'dist' folders only")
+    .option("--dry-run", "outputs the paths that would be deleted")
+    .action(async function cleanCommandAction(options: Options) {
+      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,
+        });
+      }
+    })
+    .addHelpText("afterAll", `\nUnder the hood, this command uses ${TOOL_LABELS.RIMRAF} to delete dirty folders or files.`);
+}