@rrlab/cli 1.2.1 → 1.2.2-git-9a2ee7f.0

package/dist/cli.usage.kdl

@@ -1,7 +1,7 @@
 // @generated by @usage-spec/commander from Commander.js metadata
 name rr
 bin rr
-version "1.2.1"
+version "1.2.2-git-9a2ee7f.0"
 usage "[options] [command]"
 flag --about help="show credits & inspiration"
 flag --usage help="print KDL spec for this CLI (https://kdl.dev)"
@@ -31,6 +31,14 @@ cmd format help="check & fix format issues" {
 	flag --fix help="format all the code"
 	cmd doctor help="check if the underlying tool is working correctly"
 }
+cmd test help="run the test suite" {
+	long_help "Passthrough to the configured test runner. Forwards every flag and argument (e.g. --project, --watch) — including --help — straight to the tool. Loads .env.test or .env by default. ('rr test doctor' is reserved for the health check.)"
+	flag --env help="load this env file before running (default: .env.test, then .env)" {
+		arg <ENV>
+	}
+	arg "[args]…" help="arguments forwarded to the test runner" required=#false var=#true
+	cmd doctor help="check if the underlying tool is working correctly"
+}
 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"
@@ -55,13 +63,13 @@ cmd plugins subcommand_required=#true help="manage @rrlab plugins" {
 		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 (ts|biome|oxc|tsdown), optionally with @<spec> e.g. biome@pr-226"
+		arg <name> help="plugin alias (ts|biome|oxc|tsdown|vitest), optionally with @<spec> e.g. biome@pr-226"
 	}
 	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 biome oxc tsdown
+			choices ts biome oxc tsdown vitest
 		}
 	}
 }

package/dist/config.d.mts

@@ -1,4 +1,4 @@
-import { c as Plugin } from "./types-Iu4IyWof.mjs";
+import { c as Plugin } from "./types-CNXhLCKf.mjs";
 
 //#region src/types/config.d.ts
 type UserConfig = {

package/dist/plugin/decide-scaffold.d.mts

@@ -1,4 +1,4 @@
-import { i as InstallContext } from "../types-Iu4IyWof.mjs";
+import { i as InstallContext } from "../types-CNXhLCKf.mjs";
 
 //#region src/lib/plugin/decide-scaffold.d.ts
 type ScaffoldDecision = "create" | "patch" | "overwrite" | "skip";

package/dist/plugin/define-plugin.d.mts

@@ -1,4 +1,4 @@
-import { c as Plugin, d as PluginServices, f as UninstallContext, i as InstallContext, l as PluginCapability, m as UninstallResult, o as InstallResult, u as PluginContext } from "../types-Iu4IyWof.mjs";
+import { c as Plugin, d as PluginServices, f as UninstallContext, i as InstallContext, l as PluginCapability, m as UninstallResult, o as InstallResult, u as PluginContext } from "../types-CNXhLCKf.mjs";
 
 //#region src/lib/plugin/define-plugin.d.ts
 type PluginDefinition<TServices extends PluginServices> = {

package/dist/plugin/directory.d.mts

@@ -1,4 +1,4 @@
-import { l as PluginCapability } from "../types-Iu4IyWof.mjs";
+import { l as PluginCapability } from "../types-CNXhLCKf.mjs";
 
 //#region src/lib/plugin/directory.d.ts
 declare const PLUGINS_DIRECTORY: {
@@ -22,6 +22,11 @@ declare const PLUGINS_DIRECTORY: {
     readonly name: "tsdown";
     readonly capabilities: ["pack"];
   };
+  readonly vitest: {
+    readonly pkg: "@rrlab/vitest-plugin";
+    readonly name: "vitest";
+    readonly capabilities: ["test"];
+  };
 };
 type PluginName = keyof typeof PLUGINS_DIRECTORY;
 declare function allPluginNames(): readonly PluginName[];
@@ -42,6 +47,10 @@ declare function providersOf(capability: PluginCapability): ({
   readonly pkg: "@rrlab/tsdown-plugin";
   readonly name: "tsdown";
   readonly capabilities: ["pack"];
+} | {
+  readonly pkg: "@rrlab/vitest-plugin";
+  readonly name: "vitest";
+  readonly capabilities: ["test"];
 })[];
 //#endregion
 export { PLUGINS_DIRECTORY, PluginName, allPluginNames, isPluginName, providersOf };

package/dist/plugin/directory.mjs

@@ -28,6 +28,11 @@ const PLUGINS_DIRECTORY = {
 		pkg: "@rrlab/tsdown-plugin",
 		name: "tsdown",
 		capabilities: ["pack"]
+	},
+	vitest: {
+		pkg: "@rrlab/vitest-plugin",
+		name: "vitest",
+		capabilities: ["test"]
 	}
 };
 function allPluginNames() {

package/dist/plugin/index.d.mts

@@ -1,7 +1,7 @@
-import { a as InstallFlags, c as Plugin, d as PluginServices, f as UninstallContext, g as ReleaseServiceOptions, h as ReleaseService, i as InstallContext, l as PluginCapability, m as UninstallResult, n as ClackPromptsSelectOption, o as InstallResult, p as UninstallFlags, r as FileOp, s as JsonEdit, t as ClackPrompts, u as PluginContext } from "../types-Iu4IyWof.mjs";
-import { a as Linter, c as StaticChecker, d as TypeChecker, i as LintOptions, l as StaticCheckerOptions, n as FormatOptions, o as Packer, r as Formatter, s as RunReport, t as Doctor, u as TypeCheckOptions } from "../tool-DKL6TauZ.mjs";
+import { a as InstallFlags, c as Plugin, d as PluginServices, f as UninstallContext, g as ReleaseServiceOptions, h as ReleaseService, i as InstallContext, l as PluginCapability, m as UninstallResult, n as ClackPromptsSelectOption, o as InstallResult, p as UninstallFlags, r as FileOp, s as JsonEdit, t as ClackPrompts, u as PluginContext } from "../types-CNXhLCKf.mjs";
+import { a as Linter, c as StaticChecker, d as TestRunner, f as TypeCheckOptions, i as LintOptions, l as StaticCheckerOptions, n as FormatOptions, o as Packer, p as TypeChecker, r as Formatter, s as RunReport, t as Doctor, u as TestRunOptions } from "../tool-z8C0qtc5.mjs";
 import { DecideScaffoldOptions, ScaffoldDecision, decideScaffold } from "./decide-scaffold.mjs";
 import { PluginDefinition, definePlugin } from "./define-plugin.mjs";
 import { PickPresetOptions, pickPreset } from "./pick-preset.mjs";
 import { ToolService, ToolServiceOptions } from "./tool-service.mjs";
-export { type ClackPrompts, type ClackPromptsSelectOption, type DecideScaffoldOptions, type Doctor, type FileOp, type FormatOptions, type Formatter, type InstallContext, type InstallFlags, type InstallResult, type JsonEdit, type LintOptions, type Linter, type Packer, type PickPresetOptions, type Plugin, type PluginCapability, type PluginContext, type PluginDefinition, type PluginServices, ReleaseService, type ReleaseServiceOptions, type RunReport, type ScaffoldDecision, type StaticChecker, type StaticCheckerOptions, ToolService, type ToolServiceOptions, type TypeCheckOptions, type TypeChecker, type UninstallContext, type UninstallFlags, type UninstallResult, decideScaffold, definePlugin, pickPreset };
+export { type ClackPrompts, type ClackPromptsSelectOption, type DecideScaffoldOptions, type Doctor, type FileOp, type FormatOptions, type Formatter, type InstallContext, type InstallFlags, type InstallResult, type JsonEdit, type LintOptions, type Linter, type Packer, type PickPresetOptions, type Plugin, type PluginCapability, type PluginContext, type PluginDefinition, type PluginServices, ReleaseService, type ReleaseServiceOptions, type RunReport, type ScaffoldDecision, type StaticChecker, type StaticCheckerOptions, type TestRunOptions, type TestRunner, ToolService, type ToolServiceOptions, type TypeCheckOptions, type TypeChecker, type UninstallContext, type UninstallFlags, type UninstallResult, decideScaffold, definePlugin, pickPreset };

package/dist/plugin/pick-preset.d.mts

@@ -1,4 +1,4 @@
-import { i as InstallContext } from "../types-Iu4IyWof.mjs";
+import { i as InstallContext } from "../types-CNXhLCKf.mjs";
 
 //#region src/lib/plugin/pick-preset.d.ts
 type PickPresetOptions<K extends string> = {

package/dist/plugin/registry.d.mts

@@ -1,5 +1,5 @@
-import { c as Plugin, d as PluginServices, l as PluginCapability } from "../types-Iu4IyWof.mjs";
-import { a as Linter, c as StaticChecker, d as TypeChecker, o as Packer, r as Formatter, t as Doctor } from "../tool-DKL6TauZ.mjs";
+import { c as Plugin, d as PluginServices, l as PluginCapability } from "../types-CNXhLCKf.mjs";
+import { a as Linter, c as StaticChecker, d as TestRunner, o as Packer, p as TypeChecker, r as Formatter, t as Doctor } from "../tool-z8C0qtc5.mjs";
 
 //#region src/lib/plugin/registry.d.ts
 type Provider<K extends PluginCapability> = {
@@ -11,7 +11,7 @@ declare class PluginRegistry {
   register(plugin: Plugin, services: PluginServices): void;
   getServiceOrThrow<K extends PluginCapability>(capability: K): NonNullable<PluginServices[K]>;
   getService<K extends PluginCapability>(capability: K): NonNullable<PluginServices[K]> | undefined;
-  getAllServices(): NonNullable<(Linter & Doctor) | (Formatter & Doctor) | (StaticChecker & Doctor) | (TypeChecker & Doctor) | (Packer & Doctor) | undefined>[];
+  getAllServices(): NonNullable<(Linter & Doctor) | (Formatter & Doctor) | (StaticChecker & Doctor) | (TypeChecker & Doctor) | (Packer & Doctor) | (TestRunner & Doctor) | undefined>[];
   providersOf<K extends PluginCapability>(capability: K): Provider<K>[];
   providerOf<K extends PluginCapability>(capability: K): Provider<K> | undefined;
 }

package/dist/plugin/tool-service.d.mts

@@ -1,4 +1,4 @@
-import { s as RunReport } from "../tool-DKL6TauZ.mjs";
+import { s as RunReport } from "../tool-z8C0qtc5.mjs";
 import { ShellService } from "@vlandoss/clibuddy";
 
 //#region src/lib/plugin/tool-service.d.ts
@@ -39,6 +39,19 @@ declare class ToolService {
    * and the caller can aggregate. See `decisions/013-check-stream-to-capture-contract.md`.
    */
   runReport(args?: string[], options?: RunReportOptions): Promise<RunReport>;
+  /**
+   * Streams the command straight to the terminal (`stdio: "inherit"`) and
+   * returns its exit code — the counterpart to `runReport` for passthrough
+   * verbs (e.g. a test runner) where capturing would break watch mode, colors,
+   * interactive UI, and `--help` forwarding. `verbose: false` suppresses the
+   * `$ <cmd>` line so the wrapped tool fully owns the terminal. Takes an
+   * explicit `command` because a passthrough may need to wrap its bin (e.g.
+   * `node --env-file=… <bin>`) rather than spawn it directly.
+   *
+   * A missing exit code (signal-killed, e.g. OOM) is reported as failure (`1`),
+   * mirroring `runReport`'s strict `=== 0`.
+   */
+  runStreamed(command: string, args?: string[], options?: RunReportOptions): Promise<number>;
   doctor(): Promise<RunReport>;
 }
 //#endregion

package/dist/plugin/tool-service.mjs

@@ -41,6 +41,24 @@ var ToolService = class {
 			output: body ? `${header}\n${body}` : header
 		};
 	}
+	/**
+	* Streams the command straight to the terminal (`stdio: "inherit"`) and
+	* returns its exit code — the counterpart to `runReport` for passthrough
+	* verbs (e.g. a test runner) where capturing would break watch mode, colors,
+	* interactive UI, and `--help` forwarding. `verbose: false` suppresses the
+	* `$ <cmd>` line so the wrapped tool fully owns the terminal. Takes an
+	* explicit `command` because a passthrough may need to wrap its bin (e.g.
+	* `node --env-file=… <bin>`) rather than spawn it directly.
+	*
+	* A missing exit code (signal-killed, e.g. OOM) is reported as failure (`1`),
+	* mirroring `runReport`'s strict `=== 0`.
+	*/
+	async runStreamed(command, args = [], options = {}) {
+		return (await (options.cwd ? this.#shellService.at(options.cwd) : this.#shellService).run(command, args, {
+			throwOnError: false,
+			verbose: false
+		})).exitCode ?? 1;
+	}
 	async doctor() {
 		const output = await this.#shellService.runCaptured(await this.getBinDir(), ["--help"], { throwOnError: false });
 		const ok = output.exitCode === 0;

package/dist/plugin/types.d.mts

@@ -1,3 +1,3 @@
-import { a as InstallFlags, c as Plugin, d as PluginServices, f as UninstallContext, i as InstallContext, l as PluginCapability, m as UninstallResult, n as ClackPromptsSelectOption, o as InstallResult, p as UninstallFlags, r as FileOp, s as JsonEdit, t as ClackPrompts, u as PluginContext } from "../types-Iu4IyWof.mjs";
-import { a as Linter, c as StaticChecker, d as TypeChecker, i as LintOptions, l as StaticCheckerOptions, n as FormatOptions, o as Packer, r as Formatter, s as RunReport, t as Doctor, u as TypeCheckOptions } from "../tool-DKL6TauZ.mjs";
-export { ClackPrompts, ClackPromptsSelectOption, type Doctor, FileOp, type FormatOptions, type Formatter, InstallContext, InstallFlags, InstallResult, JsonEdit, type LintOptions, type Linter, type Packer, Plugin, PluginCapability, PluginContext, PluginServices, type RunReport, type StaticChecker, type StaticCheckerOptions, type TypeCheckOptions, type TypeChecker, UninstallContext, UninstallFlags, UninstallResult };
+import { a as InstallFlags, c as Plugin, d as PluginServices, f as UninstallContext, i as InstallContext, l as PluginCapability, m as UninstallResult, n as ClackPromptsSelectOption, o as InstallResult, p as UninstallFlags, r as FileOp, s as JsonEdit, t as ClackPrompts, u as PluginContext } from "../types-CNXhLCKf.mjs";
+import { a as Linter, c as StaticChecker, d as TestRunner, f as TypeCheckOptions, i as LintOptions, l as StaticCheckerOptions, n as FormatOptions, o as Packer, p as TypeChecker, r as Formatter, s as RunReport, t as Doctor, u as TestRunOptions } from "../tool-z8C0qtc5.mjs";
+export { ClackPrompts, ClackPromptsSelectOption, type Doctor, FileOp, type FormatOptions, type Formatter, InstallContext, InstallFlags, InstallResult, JsonEdit, type LintOptions, type Linter, type Packer, Plugin, PluginCapability, PluginContext, PluginServices, type RunReport, type StaticChecker, type StaticCheckerOptions, type TestRunOptions, type TestRunner, type TypeCheckOptions, type TypeChecker, UninstallContext, UninstallFlags, UninstallResult };

package/dist/run.mjs

@@ -53,6 +53,11 @@ const PLUGINS_DIRECTORY = {
 		pkg: "@rrlab/tsdown-plugin",
 		name: "tsdown",
 		capabilities: ["pack"]
+	},
+	vitest: {
+		pkg: "@rrlab/vitest-plugin",
+		name: "vitest",
+		capabilities: ["test"]
 	}
 };
 function allPluginNames() {
@@ -1578,6 +1583,38 @@ function createPluginsCommand(ctx) {
 	return cmd;
 }
 //#endregion
+//#region src/actions/test.ts
+/**
+* The action for the `test` passthrough. Unlike the captured verbs (lint, pack,
+* …) it doesn't drive the task-board: the runner streams straight to the
+* terminal and resolves with the tool's exit code, which we mirror onto
+* `process.exitCode` so `rr test` fails when the suite fails.
+*/
+async function testAction({ runner, options, args }) {
+	const code = await runner.test({
+		envFile: options.envFile,
+		args
+	});
+	if (code !== 0) process.exitCode = code;
+}
+//#endregion
+//#region src/program/commands/test.ts
+function createTestCommand(ctx) {
+	return createCommand("test").addCapabilities(["test"]).summary("run the test suite").description("Passthrough to the configured test runner. Forwards every flag and argument (e.g. --project, --watch) — including --help — straight to the tool. Loads .env.test or .env by default. ('rr test doctor' is reserved for the health check.)").allowUnknownOption(true).passThroughOptions(true).helpOption(false).option("--env <path>", "load this env file before running (default: .env.test, then .env)").argument("[args...]", "arguments forwarded to the test runner").action(async (args = [], options = {}) => {
+		await testAction({
+			ctx,
+			runner: ctx.plugins.getServiceOrThrow("test"),
+			options: { envFile: options.env },
+			args
+		});
+	}).addDoctorCommand(async () => {
+		await doctorOneAction({
+			ctx,
+			service: ctx.plugins.getServiceOrThrow("test")
+		});
+	});
+}
+//#endregion
 //#region src/program/commands/tscheck.ts
 function createTsCheckCommand(ctx) {
 	return createCommand("tsc").alias("tscheck").addCapabilities(["typecheck"]).summary("check types errors").description("Checks type errors, ensuring that the code adheres to the defined type constraints and helps catch potential issues before runtime.").action(async () => {
@@ -1653,7 +1690,7 @@ var RunRunCmd = class extends Command {
 async function createProgram(meta) {
 	const ctx = await new ContextService(path.dirname(dirnameOf(meta))).getContext();
 	const cmd = new RunRunCmd(ctx);
-	cmd.commandsGroup("Code quality:").addCommand(createCheckCommand(ctx)).addCommand(createJsCheckCommand(ctx)).addCommand(createTsCheckCommand(ctx)).addCommand(createLintCommand(ctx)).addCommand(createFormatCommand(ctx)).commandsGroup("Build:").addCommand(createPackCommand(ctx)).commandsGroup("Maintenance:").addCommand(createCleanCommand()).addCommand(createDoctorCommand(ctx)).commandsGroup("Meta:").addCommand(createCompletionCommand()).addCommand(createPluginsCommand(ctx)).addCommand(createConfigCommand(ctx));
+	cmd.commandsGroup("Code quality:").addCommand(createCheckCommand(ctx)).addCommand(createJsCheckCommand(ctx)).addCommand(createTsCheckCommand(ctx)).addCommand(createLintCommand(ctx)).addCommand(createFormatCommand(ctx)).commandsGroup("Testing:").addCommand(createTestCommand(ctx)).commandsGroup("Build:").addCommand(createPackCommand(ctx)).commandsGroup("Maintenance:").addCommand(createCleanCommand()).addCommand(createDoctorCommand(ctx)).commandsGroup("Meta:").addCommand(createCompletionCommand()).addCommand(createPluginsCommand(ctx)).addCommand(createConfigCommand(ctx));
 	return cmd;
 }
 //#endregion

package/dist/{tool-DKL6TauZ.d.mts → tool-z8C0qtc5.d.mts}

@@ -39,5 +39,19 @@ type Packer = {
   readonly ui: string;
   pack: () => Promise<RunReport>;
 };
+type TestRunOptions = {
+  /** Env file to load before running (resolved by the provider). */envFile?: string; /** Arguments forwarded verbatim to the test runner. */
+  args: string[];
+};
+type TestRunner = {
+  readonly ui: string;
+  /**
+   * Streams a passthrough test run and resolves with the tool's exit code.
+   * Unlike the other verbs it returns a number, not a `RunReport`: a test
+   * runner needs an inherited TTY (watch mode, colors, `--help`), so its output
+   * is never captured for the board.
+   */
+  test: (options: TestRunOptions) => Promise<number>;
+};
 //#endregion
-export { Linter as a, StaticChecker as c, TypeChecker as d, LintOptions as i, StaticCheckerOptions as l, FormatOptions as n, Packer as o, Formatter as r, RunReport as s, Doctor as t, TypeCheckOptions as u };
+export { Linter as a, StaticChecker as c, TestRunner as d, TypeCheckOptions as f, LintOptions as i, StaticCheckerOptions as l, FormatOptions as n, Packer as o, TypeChecker as p, Formatter as r, RunReport as s, Doctor as t, TestRunOptions as u };

package/dist/{types-Iu4IyWof.d.mts → types-CNXhLCKf.d.mts}

@@ -1,4 +1,4 @@
-import { a as Linter, c as StaticChecker, d as TypeChecker, o as Packer, r as Formatter, t as Doctor } from "./tool-DKL6TauZ.mjs";
+import { a as Linter, c as StaticChecker, d as TestRunner, o as Packer, p as TypeChecker, r as Formatter, t as Doctor } from "./tool-z8C0qtc5.mjs";
 import { Pkg, ShellService } from "@vlandoss/clibuddy";
 import { AnyLogger } from "@vlandoss/loggy";
 
@@ -35,6 +35,7 @@ type PluginServices = {
   jscheck?: StaticChecker & Doctor;
   typecheck?: TypeChecker & Doctor;
   pack?: Packer & Doctor;
+  test?: TestRunner & Doctor;
 };
 type PluginContext = {
   shell: ShellService;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rrlab/cli",
-  "version": "1.2.1",
+  "version": "1.2.2-git-9a2ee7f.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": {

package/src/actions/test.ts

@@ -0,0 +1,20 @@
+import type { ContextValue } from "#src/services/context.ts";
+import type { Doctor, TestRunner } from "#src/types/tool.ts";
+
+export type TestActionConfig = {
+  ctx: ContextValue;
+  runner: TestRunner & Doctor;
+  options: { envFile?: string };
+  args: string[];
+};
+
+/**
+ * The action for the `test` passthrough. Unlike the captured verbs (lint, pack,
+ * …) it doesn't drive the task-board: the runner streams straight to the
+ * terminal and resolves with the tool's exit code, which we mirror onto
+ * `process.exitCode` so `rr test` fails when the suite fails.
+ */
+export async function testAction({ runner, options, args }: TestActionConfig): Promise<void> {
+  const code = await runner.test({ envFile: options.envFile, args });
+  if (code !== 0) process.exitCode = code;
+}

package/src/lib/plugin/directory.ts

@@ -11,6 +11,7 @@ export const PLUGINS_DIRECTORY = {
   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"] },
+  vitest: { pkg: "@rrlab/vitest-plugin", name: "vitest", capabilities: ["test"] },
 } as const satisfies Record<string, PluginInfo>;
 
 export type PluginName = keyof typeof PLUGINS_DIRECTORY;

package/src/lib/plugin/index.ts

@@ -24,6 +24,8 @@ export type {
   RunReport,
   StaticChecker,
   StaticCheckerOptions,
+  TestRunner,
+  TestRunOptions,
   TypeChecker,
   TypeCheckOptions,
   UninstallContext,

package/src/lib/plugin/tool-service.ts

@@ -70,6 +70,24 @@ export class ToolService {
     return { ok: output.exitCode === 0, output: body ? `${header}\n${body}` : header };
   }
 
+  /**
+   * Streams the command straight to the terminal (`stdio: "inherit"`) and
+   * returns its exit code — the counterpart to `runReport` for passthrough
+   * verbs (e.g. a test runner) where capturing would break watch mode, colors,
+   * interactive UI, and `--help` forwarding. `verbose: false` suppresses the
+   * `$ <cmd>` line so the wrapped tool fully owns the terminal. Takes an
+   * explicit `command` because a passthrough may need to wrap its bin (e.g.
+   * `node --env-file=… <bin>`) rather than spawn it directly.
+   *
+   * A missing exit code (signal-killed, e.g. OOM) is reported as failure (`1`),
+   * mirroring `runReport`'s strict `=== 0`.
+   */
+  async runStreamed(command: string, args: string[] = [], options: RunReportOptions = {}): Promise<number> {
+    const sh = options.cwd ? this.#shellService.at(options.cwd) : this.#shellService;
+    const result = await sh.run(command, args, { throwOnError: false, verbose: false });
+    return result.exitCode ?? 1;
+  }
+
   async doctor(): Promise<RunReport> {
     const output = await this.#shellService.runCaptured(await this.getBinDir(), ["--help"], { throwOnError: false });
     const ok = output.exitCode === 0;

package/src/lib/plugin/types.ts

@@ -1,7 +1,7 @@
 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, Packer, StaticChecker, TypeChecker } from "#src/types/tool.ts";
+import type { Doctor, Formatter, Linter, Packer, StaticChecker, TestRunner, TypeChecker } from "#src/types/tool.ts";
 
 export type * from "#src/types/tool.ts";
 
@@ -13,6 +13,7 @@ export type PluginServices = {
   jscheck?: StaticChecker & Doctor;
   typecheck?: TypeChecker & Doctor;
   pack?: Packer & Doctor;
+  test?: TestRunner & Doctor;
 };
 
 export type PluginContext = {

package/src/program/commands/test.ts

@@ -0,0 +1,36 @@
+import { doctorOneAction } from "#src/actions/doctor.ts";
+import { testAction } from "#src/actions/test.ts";
+import type { ContextValue } from "#src/services/context.ts";
+import { createCommand } from "../base.ts";
+
+type ActionOptions = {
+  env?: string;
+};
+
+export function createTestCommand(ctx: ContextValue) {
+  return (
+    createCommand("test")
+      .addCapabilities(["test"])
+      .summary("run the test suite")
+      .description(
+        "Passthrough to the configured test runner. Forwards every flag and argument (e.g. --project, --watch) — including --help — straight to the tool. Loads .env.test or .env by default. ('rr test doctor' is reserved for the health check.)",
+      )
+      // Pure passthrough: don't parse the tool's flags, don't capture --help.
+      // `--env` is consumed only when it precedes the forwarded args. It's not
+      // named `--env-file`: Node's early `--env-file` scanner would grab that
+      // token off the `rr` process's argv before Commander ever sees it.
+      .allowUnknownOption(true)
+      .passThroughOptions(true)
+      .helpOption(false)
+      .option("--env <path>", "load this env file before running (default: .env.test, then .env)")
+      .argument("[args...]", "arguments forwarded to the test runner")
+      .action(async (args: string[] = [], options: ActionOptions = {}) => {
+        const runner = ctx.plugins.getServiceOrThrow("test");
+        await testAction({ ctx, runner, options: { envFile: options.env }, args });
+      })
+      .addDoctorCommand(async () => {
+        const runner = ctx.plugins.getServiceOrThrow("test");
+        await doctorOneAction({ ctx, service: runner });
+      })
+  );
+}

package/src/program/index.ts

@@ -11,6 +11,7 @@ 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 { createTestCommand } from "./commands/test.ts";
 import { createTsCheckCommand } from "./commands/tscheck.ts";
 import { RunRunCmd } from "./root.ts";
 
@@ -29,6 +30,8 @@ export async function createProgram(meta: ImportMeta) {
     .addCommand(createTsCheckCommand(ctx))
     .addCommand(createLintCommand(ctx))
     .addCommand(createFormatCommand(ctx))
+    .commandsGroup("Testing:")
+    .addCommand(createTestCommand(ctx))
     .commandsGroup("Build:")
     .addCommand(createPackCommand(ctx))
     .commandsGroup("Maintenance:")

package/src/types/tool.ts

@@ -48,3 +48,21 @@ export type Packer = {
   readonly ui: string;
   pack: () => Promise<RunReport>;
 };
+
+export type TestRunOptions = {
+  /** Env file to load before running (resolved by the provider). */
+  envFile?: string;
+  /** Arguments forwarded verbatim to the test runner. */
+  args: string[];
+};
+
+export type TestRunner = {
+  readonly ui: string;
+  /**
+   * Streams a passthrough test run and resolves with the tool's exit code.
+   * Unlike the other verbs it returns a number, not a `RunReport`: a test
+   * runner needs an inherited TTY (watch mode, colors, `--help`), so its output
+   * is never captured for the board.
+   */
+  test: (options: TestRunOptions) => Promise<number>;
+};