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

package/README.md

@@ -0,0 +1,110 @@
+# 🦊 run-run
+
+CLI toolbox to fullstack common scripts in [Variable Land](https://variable.land)
+
+## Prerequisites
+
+- Node.js >= 20.0.0
+
+## Toolbox
+
+- [biome](https://biomejs.dev)
+- [tsc](https://www.typescriptlang.org)
+- [rimraf](https://www.npmjs.com/package/rimraf)
+- [oxfmt](https://oxc.rs/docs/guide/usage/formatter.html)
+- [oxlint](https://oxc.rs/docs/guide/usage/linter.html)
+- [tsdown](https://tsdown.dev)
+
+## Installation
+
+```sh
+pnpm add -D @rrlab/cli
+```
+
+It adds the `rr` command to your project.
+
+## Usage
+
+Run the help command:
+
+```sh
+pnpm rr help
+```
+
+> If you have `node_modules/.bin` on your `PATH` (e.g. via `mise` or `direnv` — see [Shell completion](#shell-completion)), you can drop the `pnpm` prefix and invoke `rr` directly.
+
+See [`CLI.md`](./CLI.md) for the full reference (auto-generated per release).
+
+## Shell completion
+
+`rr` ships a `completion` subcommand that prints a shell-specific script.
+Pick the option that matches your setup.
+
+### Option A — with `mise` or `direnv` (recommended)
+
+If your tooling puts `node_modules/.bin` on `PATH` per-project, `rr` resolves at shell startup and completion picks up new commands automatically on each new shell. Examples:
+
+```toml
+# mise.toml
+[env]
+_.path = ["{{config_root}}/node_modules/.bin"]
+```
+
+```sh
+# .envrc (direnv)
+PATH_add node_modules/.bin
+```
+
+Then add a guarded eval to your shell rc — the guard makes it a no-op when you open a shell outside any project:
+
+```sh
+# zsh — ~/.zshrc
+command -v rr >/dev/null 2>&1 && eval "$(rr completion zsh)"
+
+# bash — ~/.bashrc
+command -v rr >/dev/null 2>&1 && eval "$(rr completion bash)"
+
+# fish — ~/.config/fish/config.fish
+command -v rr >/dev/null 2>&1; and rr completion fish | source
+```
+
+### Option B — without a per-project PATH manager
+
+Cache the completion script once, then source the cached file from your shell rc. Run the generation step from inside a project that has `@rrlab/cli` installed:
+
+```sh
+mkdir -p ~/.cache
+pnpm exec rr completion zsh  > ~/.cache/rr-completion.zsh
+pnpm exec rr completion bash > ~/.cache/rr-completion.bash
+pnpm exec rr completion fish > ~/.cache/rr-completion.fish
+```
+
+```sh
+# zsh — ~/.zshrc
+[ -f ~/.cache/rr-completion.zsh ] && source ~/.cache/rr-completion.zsh
+
+# bash — ~/.bashrc
+[ -f ~/.cache/rr-completion.bash ] && source ~/.cache/rr-completion.bash
+
+# fish — ~/.config/fish/config.fish
+test -f ~/.cache/rr-completion.fish; and source ~/.cache/rr-completion.fish
+```
+
+Regenerate the cache after upgrading `@rrlab/cli` to pick up new commands.
+
+### Prerequisite
+
+The [`usage`](https://usage.jdx.dev) CLI must be on your `PATH` (it powers completion at runtime). Install via one of:
+
+```sh
+mise use -g usage
+brew install usage
+```
+
+## Troubleshooting
+
+To enable debug mode, set the `DEBUG` environment variable to `run-run:*` before running *any* command.
+
+```sh
+DEBUG=run-run:* pnpm rr <command>
+```

package/bin

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -e
+
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  TARGET="$(readlink "$SOURCE")"
+  case "$TARGET" in
+    /*) SOURCE="$TARGET" ;;
+    *) SOURCE="$(dirname "$SOURCE")/$TARGET" ;;
+  esac
+done
+DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+
+if [ "$1" = "completion" ]; then
+  case "$2" in
+    bash | zsh | fish)
+      kdl="$DIR/dist/cli.usage.kdl"
+      if [ ! -f "$kdl" ]; then
+        echo "rr completion: missing $kdl. Reinstall @rrlab/cli or run \`pnpm build\`." >&2
+        exit 1
+      fi
+      if ! command -v usage >/dev/null 2>&1; then
+        echo "rr completion: 'usage' CLI not found in PATH." >&2
+        echo "Install via: mise use -g usage  |  brew install usage" >&2
+        exit 1
+      fi
+      exec usage generate completion "$2" rr --file "$kdl"
+      ;;
+  esac
+  # Unknown shell or `--help`: fall through to Node so Commander prints help/errors.
+fi
+
+# `--usage` emits a KDL spec for downstream parsers (e.g. `usage generate
+# completion`). Force NO_COLOR so command summaries don't leak ANSI escapes
+# into the spec — colors are presentation, KDL is data. Also set
+# RR_USAGE_MODE so per-environment annotations (e.g. the active plugin
+# next to each command) are stripped from the spec — the KDL must be
+# stable across machines.
+for arg in "$@"; do
+  if [ "$arg" = "--usage" ]; then
+    export NO_COLOR=1
+    export RR_USAGE_MODE=1
+    break
+  fi
+done
+
+# In the source repo (tsdown.config.ts present, NOT shipped in the npm tarball),
+# always run from src/ so live edits show up. In a published install, use the
+# bundled dist/run.mjs.
+if [ -f "$DIR/tsdown.config.ts" ]; then
+  exec node "$DIR/src/run.ts" "$@"
+else
+  exec node "$DIR/dist/run.mjs" "$@"
+fi

package/dist/cli.usage.kdl

@@ -0,0 +1,71 @@
+// @generated by @usage-spec/commander from Commander.js metadata
+name rr
+bin rr
+version "0.0.1-git-87d22db.0"
+usage "<command...> [options...]"
+flag --usage help="print KDL spec for this CLI (https://kdl.dev)"
+cmd completion help="print shell completion script (usage)" {
+	long_help "Prints a shell completion script for rr. Add to your shell rc file:\n\n  bash: eval \"$(rr completion bash)\"\n  zsh:  eval \"$(rr completion zsh)\"\n  fish: rr completion fish | source"
+	arg <shell> help="target shell" {
+		choices bash zsh fish
+	}
+}
+cmd pack help="pack a ts library" {
+	long_help "Compiles TypeScript code into JavaScript and generates type declaration files, packaging the library for distribution."
+	cmd doctor help="check if the underlying tool is working correctly"
+}
+cmd jsc help="check format and lint" {
+	alias jscheck
+	long_help "Checks the code for formatting and linting issues, ensuring it adheres to the defined style and quality standards."
+	flag --fix help="try to fix issues automatically"
+	flag --fix-staged help="try to fix staged files only"
+	cmd doctor help="check if the underlying tool is working correctly"
+}
+cmd tsc help="check typescript errors" {
+	alias tscheck
+	long_help "Checks the TypeScript code for type errors, ensuring that the code adheres to the defined type constraints and helps catch potential issues before runtime."
+	cmd doctor help="check if the underlying tool is working correctly"
+}
+cmd lint help="check & fix lint errors" {
+	long_help "Checks the code for linting issues and optionally fixes them, ensuring it adheres to the defined quality standards."
+	flag "-c --check" help="check if the code is valid" default=#true
+	flag --fix help="try to fix all the code"
+	cmd doctor help="check if the underlying tool is working correctly"
+}
+cmd format help="check & fix format errors" {
+	long_help "Checks the code for formatting issues and optionally fixes them, ensuring it adheres to the defined style standards."
+	flag --fix help="format all the code"
+	cmd doctor help="check if the underlying tool is working correctly"
+}
+cmd check help="run static checks (run-run)" {
+	long_help "Runs `rr jsc` and `rr tsc` concurrently in-process. Aggregates their exit codes — non-zero when either subcommand fails."
+}
+cmd doctor help="run all plugin doctors" {
+	long_help "Runs the `doctor()` of every configured plugin capability. Each plugin reports ok / not working. The exit code is non-zero if any reports not working."
+}
+cmd plugins subcommand_required=#true help="manage @rrlab plugins" {
+	cmd list help="list plugins configured in run-run.config.{ts,mts}"
+	cmd add help="install and configure an @rrlab plugin" {
+		flag --force help="re-run install even if the plugin is already configured"
+		flag --yes help="skip prompts and use defaults (non-interactive)"
+		flag --dry-run help="show what would happen, without applying changes"
+		arg <name> help="plugin alias" {
+			choices ts eslint biome oxc tsdown
+		}
+	}
+	cmd remove help="uninstall an @rrlab plugin and undo its config files + deps" {
+		flag --yes help="skip the confirmation prompt"
+		flag --dry-run help="print the plan without applying changes"
+		arg <name> help="plugin alias to remove" {
+			choices ts eslint biome oxc tsdown
+		}
+	}
+}
+cmd clean help="delete dirty files (rimraf)" {
+	long_help "Deletes generated files and folders such as 'dist', 'node_modules', and lock files to ensure a clean state."
+	flag --only-dist help="delete 'dist' folders only"
+	flag --dry-run help="outputs the paths that would be deleted"
+}
+cmd config help="display the current config" {
+	long_help "Displays the current configuration settings, including their source file path if available."
+}

package/dist/config.d.mts

@@ -0,0 +1,11 @@
+import { u as Plugin } from "./types-C3V27_kd.mjs";
+
+//#region src/types/config.d.ts
+type UserConfig = {
+  plugins?: Plugin[];
+};
+//#endregion
+//#region src/lib/config.d.ts
+declare function defineConfig(config: UserConfig): UserConfig;
+//#endregion
+export { defineConfig };

package/dist/config.mjs

@@ -0,0 +1,6 @@
+//#region src/lib/config.ts
+function defineConfig(config) {
+	return config;
+}
+//#endregion
+export { defineConfig };

package/dist/plugin.d.mts

@@ -0,0 +1,52 @@
+import { C as Linter, D as TypeChecker, E as TypeCheckOptions, S as LintOptions, T as StaticCheckerOptions, _ as Doctor, a as InstallFlags, b as FormatOptions, c as PLUGIN_KINDS, d as PluginCapabilities, f as PluginContext, g as UninstallResult, h as UninstallFlags, i as InstallContext, l as Packer, m as UninstallContext, n as ClackPromptsSelectOption, o as InstallResult, p as PluginKind, r as FileOp, s as JsonEdit, t as ClackPrompts, u as Plugin, v as DoctorOutput, w as StaticChecker, x as Formatter, y as DoctorResult } from "./types-C3V27_kd.mjs";
+import { ShellService } from "@vlandoss/clibuddy";
+
+//#region src/plugin/define-plugin.d.ts
+declare function definePlugin<T = void>(factory: (options: T) => Plugin): (options: T) => Plugin;
+//#endregion
+//#region ../../node_modules/.pnpm/tinyexec@1.1.2/node_modules/tinyexec/dist/main.d.mts
+//#endregion
+//#region src/main.d.ts
+interface Output {
+  stderr: string;
+  stdout: string;
+  exitCode: number | undefined;
+}
+//#endregion
+//#region src/plugin/tool-service.d.ts
+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;
+};
+type ExecOptions = {
+  cwd?: string;
+  verbose?: boolean;
+};
+declare class ToolService {
+  #private;
+  get bin(): string;
+  get ui(): string;
+  get pkg(): string;
+  constructor({
+    pkg,
+    bin,
+    ui,
+    shellService,
+    from
+  }: ToolServiceOptions);
+  getBinDir(): Promise<string>;
+  exec(args?: string[], options?: ExecOptions): Promise<Output>;
+  doctor(): Promise<DoctorResult>;
+}
+//#endregion
+export { type ClackPrompts, type ClackPromptsSelectOption, type Doctor, type DoctorOutput, type DoctorResult, type FileOp, type FormatOptions, type Formatter, type InstallContext, type InstallFlags, type InstallResult, type JsonEdit, type LintOptions, type Linter, PLUGIN_KINDS, type Packer, type Plugin, type PluginCapabilities, type PluginContext, type PluginKind, type StaticChecker, type StaticCheckerOptions, ToolService, type ToolServiceOptions, type TypeCheckOptions, type TypeChecker, type UninstallContext, type UninstallFlags, type UninstallResult, definePlugin };

package/dist/plugin.mjs

@@ -0,0 +1,65 @@
+import { resolvePackageBin } from "@vlandoss/clibuddy";
+//#region src/plugin/define-plugin.ts
+function definePlugin(factory) {
+	return factory;
+}
+//#endregion
+//#region src/plugin/tool-service.ts
+var ToolService = class {
+	#shellService;
+	#pkg;
+	#bin;
+	#ui;
+	#from;
+	get bin() {
+		return this.#bin;
+	}
+	get ui() {
+		return this.#ui;
+	}
+	get pkg() {
+		return this.#pkg;
+	}
+	constructor({ pkg, bin, ui, shellService, from }) {
+		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 = [], options = {}) {
+		const { cwd, verbose } = options;
+		return (cwd ? this.#shellService.at(cwd) : this.#shellService).run(await this.getBinDir(), args, {
+			display: this.#bin,
+			verbose
+		});
+	}
+	async doctor() {
+		const output = await this.#shellService.runCaptured(await this.getBinDir(), ["--help"], { throwOnError: false });
+		return {
+			ok: output.exitCode === 0,
+			output: {
+				stdout: output.stdout,
+				stderr: output.stderr,
+				exitCode: output.exitCode
+			}
+		};
+	}
+};
+//#endregion
+//#region src/plugin/types.ts
+const PLUGIN_KINDS = [
+	"lint",
+	"format",
+	"jsc",
+	"tsc",
+	"pack"
+];
+//#endregion
+export { PLUGIN_KINDS, ToolService, definePlugin };