@rrlab/cli 1.3.0 → 1.3.1

package/dist/cli.usage.kdl

@@ -1,7 +1,7 @@
 // @generated by @usage-spec/commander from Commander.js metadata
 name rr
 bin rr
-version "1.3.0"
+version "1.3.1"
 usage "[options] [command]"
 flag --about help="show credits & inspiration"
 flag --usage help="print KDL spec for this CLI (https://kdl.dev)"

package/dist/config.d.mts

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

package/dist/errors-VlWGAo7D.mjs

@@ -0,0 +1,27 @@
+//#region src/errors/known-error.ts
+/**
+* Base class for user-facing domain errors. The top-level handler (`reportError`
+* in `src/program/report-error.ts`) renders a `KnownError` as a clean message —
+* no stack trace — and exits 1. Anything that is NOT a `KnownError` is treated
+* as an unexpected bug and surfaces its full stack so it can be reported.
+*
+* Don't set `this.name` in subclasses — keep the plain `Error:` prefix so output
+* stays clean.
+*/
+var KnownError = class extends Error {};
+//#endregion
+//#region src/lib/plugin/errors.ts
+/**
+* Thrown by `PluginRegistry.get` when more than one plugin provides the same
+* capability. The message is load-bearing for the "ambiguity → user narrows
+* config" UX (decision 003) — `registry.test.ts` asserts the plugin names appear.
+*/
+var MultipleProvidersError = class extends KnownError {
+	constructor(kind, pluginNames) {
+		const names = pluginNames.join(", ");
+		const example = pluginNames.map((name) => `${name}({ only: ['${kind}'] })`).join(" or ");
+		super(`Multiple plugins provide capability '${kind}': ${names}. Narrow each plugin's capabilities in run-run.config.ts using the 'only' option — e.g. ${example}.`);
+	}
+};
+//#endregion
+export { KnownError as n, MultipleProvidersError as t };

package/dist/plugin/__tests__/bin-probe.test.mjs

@@ -1,6 +1,6 @@
 import { ToolService } from "../tool-service.mjs";
 import { probeBins } from "../bin-probe.mjs";
-import { i as it, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-09ScyH13.mjs";
+import { i as it, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-CipsEAq5.mjs";
 //#region src/lib/plugin/__tests__/bin-probe.test.ts
 const FROM = import.meta.url;
 var ResolvableService = class extends ToolService {

package/dist/plugin/__tests__/decide-scaffold.test.mjs

@@ -1,5 +1,5 @@
 import { decideScaffold } from "../decide-scaffold.mjs";
-import { i as it, n as vi, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-09ScyH13.mjs";
+import { i as it, n as vi, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-CipsEAq5.mjs";
 //#region src/lib/plugin/__tests__/decide-scaffold.test.ts
 function makeCtx(overrides = {}) {
 	return {

package/dist/plugin/__tests__/define-plugin.test.mjs

@@ -1,6 +1,6 @@
 import { ToolService } from "../tool-service.mjs";
 import { definePlugin } from "../define-plugin.mjs";
-import { i as it, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-09ScyH13.mjs";
+import { i as it, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-CipsEAq5.mjs";
 //#region src/lib/plugin/__tests__/define-plugin.test.ts
 function ctx() {
 	return {

package/dist/plugin/__tests__/pick-preset.test.mjs

@@ -1,5 +1,5 @@
 import { pickPreset } from "../pick-preset.mjs";
-import { i as it, n as vi, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-09ScyH13.mjs";
+import { i as it, n as vi, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-CipsEAq5.mjs";
 //#region src/lib/plugin/__tests__/pick-preset.test.ts
 function makeCtx(overrides = {}) {
 	return {

package/dist/plugin/__tests__/registry.test.mjs

@@ -1,5 +1,5 @@
-import { t as PluginRegistry } from "../../registry-BgqfKK5L.mjs";
-import { i as it, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-09ScyH13.mjs";
+import { t as PluginRegistry } from "../../registry-B-GhzVIO.mjs";
+import { i as it, r as describe, t as globalExpect } from "../../test.DNmyFkvJ-CipsEAq5.mjs";
 //#region src/lib/plugin/__tests__/registry.test.ts
 function plugin(name) {
 	return {

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

@@ -1,4 +1,4 @@
-import { i as InstallContext } from "../types-CNXhLCKf.mjs";
+import { i as InstallContext } from "../types-CJ251E7V.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-CNXhLCKf.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-CJ251E7V.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-CNXhLCKf.mjs";
+import { l as PluginCapability } from "../types-CJ251E7V.mjs";
 
 //#region src/lib/plugin/directory.d.ts
 declare const PLUGINS_DIRECTORY: {

package/dist/plugin/errors.d.mts

@@ -1,10 +1,22 @@
+//#region src/errors/known-error.d.ts
+/**
+ * Base class for user-facing domain errors. The top-level handler (`reportError`
+ * in `src/program/report-error.ts`) renders a `KnownError` as a clean message —
+ * no stack trace — and exits 1. Anything that is NOT a `KnownError` is treated
+ * as an unexpected bug and surfaces its full stack so it can be reported.
+ *
+ * Don't set `this.name` in subclasses — keep the plain `Error:` prefix so output
+ * stays clean.
+ */
+declare class KnownError extends Error {}
+//#endregion
 //#region src/lib/plugin/errors.d.ts
 /**
  * Thrown by `PluginRegistry.get` when more than one plugin provides the same
  * capability. The message is load-bearing for the "ambiguity → user narrows
  * config" UX (decision 003) — `registry.test.ts` asserts the plugin names appear.
  */
-declare class MultipleProvidersError extends Error {
+declare class MultipleProvidersError extends KnownError {
   constructor(kind: string, pluginNames: readonly string[]);
 }
 //#endregion

package/dist/plugin/errors.mjs

@@ -1,15 +1,2 @@
-//#region src/lib/plugin/errors.ts
-/**
-* Thrown by `PluginRegistry.get` when more than one plugin provides the same
-* capability. The message is load-bearing for the "ambiguity → user narrows
-* config" UX (decision 003) — `registry.test.ts` asserts the plugin names appear.
-*/
-var MultipleProvidersError = class extends Error {
-	constructor(kind, pluginNames) {
-		const names = pluginNames.join(", ");
-		const example = pluginNames.map((name) => `${name}({ only: ['${kind}'] })`).join(" or ");
-		super(`Multiple plugins provide capability '${kind}': ${names}. Narrow each plugin's capabilities in run-run.config.ts using the 'only' option — e.g. ${example}.`);
-	}
-};
-//#endregion
+import { t as MultipleProvidersError } from "../errors-VlWGAo7D.mjs";
 export { MultipleProvidersError };

package/dist/plugin/index.d.mts

@@ -1,5 +1,5 @@
-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 { 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-CJ251E7V.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-faVTe0v0.mjs";
 import { DecideScaffoldOptions, ScaffoldDecision, decideScaffold } from "./decide-scaffold.mjs";
 import { PluginDefinition, definePlugin } from "./define-plugin.mjs";
 import { PickPresetOptions, pickPreset } from "./pick-preset.mjs";

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

@@ -1,4 +1,4 @@
-import { i as InstallContext } from "../types-CNXhLCKf.mjs";
+import { i as InstallContext } from "../types-CJ251E7V.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-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";
+import { c as Plugin, d as PluginServices, l as PluginCapability } from "../types-CJ251E7V.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-faVTe0v0.mjs";
 
 //#region src/lib/plugin/registry.d.ts
 type Provider<K extends PluginCapability> = {

package/dist/plugin/registry.mjs

@@ -1,2 +1,2 @@
-import { t as PluginRegistry } from "../registry-BgqfKK5L.mjs";
+import { t as PluginRegistry } from "../registry-B-GhzVIO.mjs";
 export { PluginRegistry };

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

@@ -1,5 +1,5 @@
-import { s as RunReport } from "../tool-z8C0qtc5.mjs";
-import { ShellService } from "@vlandoss/clibuddy";
+import { s as RunReport } from "../tool-faVTe0v0.mjs";
+import { ShellService } from "@variablelab/clibuddy";
 
 //#region src/lib/plugin/tool-service.d.ts
 type ToolServiceOptions = {

package/dist/plugin/tool-service.mjs

@@ -1,4 +1,4 @@
-import { palette, resolvePackageBin } from "@vlandoss/clibuddy";
+import { palette, resolvePackageBin } from "@variablelab/clibuddy";
 //#region src/lib/plugin/tool-service.ts
 var ToolService = class {
 	#shellService;

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-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 { 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-CJ251E7V.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-faVTe0v0.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/{registry-BgqfKK5L.mjs → registry-B-GhzVIO.mjs}

@@ -1,7 +1,7 @@
 import { providersOf } from "./plugin/directory.mjs";
-import { MultipleProvidersError } from "./plugin/errors.mjs";
+import { n as KnownError, t as MultipleProvidersError } from "./errors-VlWGAo7D.mjs";
 //#region src/errors/missing-plugin.ts
-var MissingPluginError = class extends Error {
+var MissingPluginError = class extends KnownError {
 	constructor(capability) {
 		const plugins = providersOf(capability);
 		const pkgList = plugins.map((it) => it.pkg).join(", ");

package/dist/run.mjs

@@ -1,10 +1,10 @@
 import { createRequire } from "node:module";
 import path, { basename } from "node:path";
-import { colorize, createPkg, createShellService, cwd, dirnameOf, palette, runTaskBoard, text } from "@vlandoss/clibuddy";
+import { colorize, createPkg, createShellService, cwd, dirnameOf, palette, runTaskBoard, text } from "@variablelab/clibuddy";
 import fs from "node:fs";
 import os from "node:os";
 import { lilconfig } from "lilconfig";
-import { createLoggy } from "@vlandoss/loggy";
+import { createLoggy } from "@variablelab/loggy";
 import { Argument, Command } from "commander";
 import stringWidth from "fast-string-width";
 import { glob } from "glob";
@@ -15,9 +15,21 @@ import fs$1 from "node:fs/promises";
 import { builders, generateCode, loadFile, parseModule, writeFile } from "magicast";
 import * as cjson from "comment-json";
 import { generateToStdout } from "@usage-spec/commander";
+//#region src/errors/known-error.ts
+/**
+* Base class for user-facing domain errors. The top-level handler (`reportError`
+* in `src/program/report-error.ts`) renders a `KnownError` as a clean message —
+* no stack trace — and exits 1. Anything that is NOT a `KnownError` is treated
+* as an unexpected bug and surfaces its full stack so it can be reported.
+*
+* Don't set `this.name` in subclasses — keep the plain `Error:` prefix so output
+* stays clean.
+*/
+var KnownError = class extends Error {};
+//#endregion
 //#region src/errors/plugin-api-version.ts
 /** Thrown when a configured plugin targets an apiVersion the kernel doesn't support. */
-var PluginApiVersionError = class extends Error {
+var PluginApiVersionError = class extends KnownError {
 	constructor(pluginName, got) {
 		super(`Plugin '${pluginName}' targets apiVersion ${got}, but this kernel supports only apiVersion 1.`);
 	}
@@ -73,7 +85,7 @@ function providersOf(capability) {
 }
 //#endregion
 //#region src/errors/missing-plugin.ts
-var MissingPluginError = class extends Error {
+var MissingPluginError = class extends KnownError {
 	constructor(capability) {
 		const plugins = providersOf(capability);
 		const pkgList = plugins.map((it) => it.pkg).join(", ");
@@ -88,7 +100,7 @@ var MissingPluginError = class extends Error {
 * capability. The message is load-bearing for the "ambiguity → user narrows
 * config" UX (decision 003) — `registry.test.ts` asserts the plugin names appear.
 */
-var MultipleProvidersError = class extends Error {
+var MultipleProvidersError = class extends KnownError {
 	constructor(kind, pluginNames) {
 		const names = pluginNames.join(", ");
 		const example = pluginNames.map((name) => `${name}({ only: ['${kind}'] })`).join(" or ");
@@ -869,14 +881,14 @@ function createPackCommand(ctx) {
 //#endregion
 //#region src/errors/invalid-plugin-module.ts
 /** Thrown when an installed plugin package doesn't export a default factory function. */
-var InvalidPluginModuleError = class extends Error {
+var InvalidPluginModuleError = class extends KnownError {
 	constructor(pkgName) {
 		super(`Plugin '${pkgName}' did not export a default factory function.`);
 	}
 };
 //#endregion
 //#region src/errors/unknown-plugin.ts
-var UnknownPluginError = class extends Error {
+var UnknownPluginError = class extends KnownError {
 	constructor(name) {
 		super(`'${name}' is invalid for argument 'name'. Allowed choices are ${allPluginNames().join(", ")}.`);
 	}
@@ -1694,7 +1706,29 @@ async function createProgram(meta) {
 	return cmd;
 }
 //#endregion
+//#region src/program/report-error.ts
+/**
+* Renders a fatal error at the program boundary. A `KnownError` is a user-facing
+* domain error (missing plugin, bad config, …) — print just its message so the
+* guidance it carries lands without a wall of stack frames. Anything else is an
+* unexpected bug: surface the full stack so it can be reported.
+*
+* Only renders; the caller sets `process.exitCode`.
+*/
+function reportError(error) {
+	if (error instanceof KnownError) {
+		logger.error(error.message);
+		return;
+	}
+	logger.error(error instanceof Error ? error.stack ?? error.message : error);
+}
+//#endregion
 //#region src/run.ts
-await (await createProgram(import.meta)).run();
+try {
+	await (await createProgram(import.meta)).run();
+} catch (error) {
+	reportError(error);
+	process.exitCode = 1;
+}
 //#endregion
 export {};

package/dist/{test.DNmyFkvJ-09ScyH13.mjs → test.DNmyFkvJ-CipsEAq5.mjs}

@@ -10228,7 +10228,7 @@ function memo(fn) {
 	};
 }
 async function saveInlineSnapshots(environment, snapshots) {
-	const MagicString = (await import("./magic-string.es-BgIV5Mu3.mjs")).default;
+	const MagicString = (await import("./magic-string.es-Dk-MMA0F.mjs")).default;
 	const files = new Set(snapshots.map((i) => i.file));
 	await Promise.all(Array.from(files).map(async (file) => {
 		const snaps = snapshots.filter((i) => i.file === file);

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

@@ -1,6 +1,6 @@
-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";
+import { a as Linter, c as StaticChecker, d as TestRunner, o as Packer, p as TypeChecker, r as Formatter, t as Doctor } from "./tool-faVTe0v0.mjs";
+import { Pkg, ShellService } from "@variablelab/clibuddy";
+import { AnyLogger } from "@variablelab/loggy";
 
 //#region src/services/release.d.ts
 type ReleaseServiceOptions = {

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@rrlab/cli",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "The CLI toolbox to fullstack common scripts in Variable Land",
-  "homepage": "https://github.com/variableland/dx/tree/main/run-run/cli#readme",
+  "homepage": "https://github.com/withvariablelab/dx/tree/main/run-run/cli#readme",
   "bugs": {
-    "url": "https://github.com/variableland/dx/issues"
+    "url": "https://github.com/withvariablelab/dx/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/variableland/dx.git",
+    "url": "git+https://github.com/withvariablelab/dx.git",
     "directory": "run-run/cli"
   },
   "license": "MIT",
@@ -57,12 +57,12 @@
     "memoize": "10.2.0",
     "nypm": "0.6.0",
     "rimraf": "6.1.3",
-    "@vlandoss/loggy": "0.2.1",
-    "@vlandoss/clibuddy": "0.7.1"
+    "@variablelab/clibuddy": "0.7.2",
+    "@variablelab/loggy": "0.2.2"
   },
   "devDependencies": {
     "tsdown": "0.22.0",
-    "@rrlab/tsdown-config": "^0.1.0"
+    "@rrlab/tsdown-config": "^0.1.1"
   },
   "scripts": {
     "build": "tsdown && pnpm build:kdl",

package/src/actions/clean.ts

@@ -1,4 +1,4 @@
-import { cwd } from "@vlandoss/clibuddy";
+import { cwd } from "@variablelab/clibuddy";
 import { type GlobOptions, glob } from "glob";
 import { rimraf } from "rimraf";
 import { logger } from "#src/services/logger.ts";

package/src/actions/config.ts

@@ -1,4 +1,4 @@
-import { palette } from "@vlandoss/clibuddy";
+import { palette } from "@variablelab/clibuddy";
 import { Lines } from "#src/render/lines.ts";
 import { configuredPlugins, pkgCell, pluginVersionCell, relPath } from "#src/render/plugin-view.ts";
 import type { ContextValue } from "#src/services/context.ts";

package/src/errors/invalid-plugin-module.ts

@@ -1,5 +1,7 @@
+import { KnownError } from "./known-error.ts";
+
 /** Thrown when an installed plugin package doesn't export a default factory function. */
-export class InvalidPluginModuleError extends Error {
+export class InvalidPluginModuleError extends KnownError {
   constructor(pkgName: string) {
     super(`Plugin '${pkgName}' did not export a default factory function.`);
   }

package/src/errors/known-error.ts

@@ -0,0 +1,10 @@
+/**
+ * Base class for user-facing domain errors. The top-level handler (`reportError`
+ * in `src/program/report-error.ts`) renders a `KnownError` as a clean message —
+ * no stack trace — and exits 1. Anything that is NOT a `KnownError` is treated
+ * as an unexpected bug and surfaces its full stack so it can be reported.
+ *
+ * Don't set `this.name` in subclasses — keep the plain `Error:` prefix so output
+ * stays clean.
+ */
+export class KnownError extends Error {}

package/src/errors/missing-plugin.ts

@@ -1,7 +1,8 @@
 import { providersOf } from "#src/lib/plugin/directory.ts";
 import type { PluginCapability } from "../lib/plugin/index.ts";
+import { KnownError } from "./known-error.ts";
 
-export class MissingPluginError extends Error {
+export class MissingPluginError extends KnownError {
   constructor(capability: PluginCapability) {
     const plugins = providersOf(capability);
 

package/src/errors/plugin-api-version.ts

@@ -1,5 +1,7 @@
+import { KnownError } from "./known-error.ts";
+
 /** Thrown when a configured plugin targets an apiVersion the kernel doesn't support. */
-export class PluginApiVersionError extends Error {
+export class PluginApiVersionError extends KnownError {
   constructor(pluginName: string, got: number) {
     super(`Plugin '${pluginName}' targets apiVersion ${got}, but this kernel supports only apiVersion 1.`);
   }

package/src/errors/unknown-plugin.ts

@@ -1,6 +1,7 @@
 import { allPluginNames } from "#src/lib/plugin/directory.ts";
+import { KnownError } from "./known-error.ts";
 
-export class UnknownPluginError extends Error {
+export class UnknownPluginError extends KnownError {
   constructor(name: string) {
     super(`'${name}' is invalid for argument 'name'. Allowed choices are ${allPluginNames().join(", ")}.`);
   }

package/src/lib/plugin/errors.ts

@@ -1,9 +1,11 @@
+import { KnownError } from "#src/errors/known-error.ts";
+
 /**
  * Thrown by `PluginRegistry.get` when more than one plugin provides the same
  * capability. The message is load-bearing for the "ambiguity → user narrows
  * config" UX (decision 003) — `registry.test.ts` asserts the plugin names appear.
  */
-export class MultipleProvidersError extends Error {
+export class MultipleProvidersError extends KnownError {
   constructor(kind: string, pluginNames: readonly string[]) {
     const names = pluginNames.join(", ");
     const example = pluginNames.map((name) => `${name}({ only: ['${kind}'] })`).join(" or ");

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

@@ -1,4 +1,4 @@
-import { palette, resolvePackageBin, type ShellService } from "@vlandoss/clibuddy";
+import { palette, resolvePackageBin, type ShellService } from "@variablelab/clibuddy";
 import type { RunReport } from "#src/types/tool.ts";
 
 export type ToolServiceOptions = {

package/src/lib/plugin/types.ts

@@ -1,5 +1,5 @@
-import type { Pkg, ShellService } from "@vlandoss/clibuddy";
-import type { AnyLogger as Logger } from "@vlandoss/loggy";
+import type { Pkg, ShellService } from "@variablelab/clibuddy";
+import type { AnyLogger as Logger } from "@variablelab/loggy";
 import type { ReleaseService } from "#src/services/release.ts";
 import type { Doctor, Formatter, Linter, Packer, StaticChecker, TestRunner, TypeChecker } from "#src/types/tool.ts";
 

package/src/program/commands/check.ts

@@ -1,4 +1,4 @@
-import { palette } from "@vlandoss/clibuddy";
+import { palette } from "@variablelab/clibuddy";
 import { jscAction } from "#src/actions/jsc.ts";
 import { tscAction } from "#src/actions/tsc.ts";
 import { runCheckSections } from "#src/render/board.ts";

package/src/program/commands/clean.ts

@@ -1,4 +1,4 @@
-import { colorize } from "@vlandoss/clibuddy";
+import { colorize } from "@variablelab/clibuddy";
 import { cleanAction } from "#src/actions/clean.ts";
 import { createCommand } from "../base.ts";
 

package/src/program/commands/completion.ts

@@ -1,4 +1,4 @@
-import { colorize } from "@vlandoss/clibuddy";
+import { colorize } from "@variablelab/clibuddy";
 import { Argument } from "commander";
 import { createCommand } from "../base.ts";
 

package/src/program/index.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { dirnameOf } from "@vlandoss/clibuddy";
+import { dirnameOf } from "@variablelab/clibuddy";
 import { ContextService } from "#src/services/context.ts";
 import { createCheckCommand } from "./commands/check.ts";
 import { createCleanCommand } from "./commands/clean.ts";

package/src/program/report-error.ts

@@ -0,0 +1,19 @@
+import { KnownError } from "#src/errors/known-error.ts";
+import { logger } from "#src/services/logger.ts";
+
+/**
+ * Renders a fatal error at the program boundary. A `KnownError` is a user-facing
+ * domain error (missing plugin, bad config, …) — print just its message so the
+ * guidance it carries lands without a wall of stack frames. Anything else is an
+ * unexpected bug: surface the full stack so it can be reported.
+ *
+ * Only renders; the caller sets `process.exitCode`.
+ */
+export function reportError(error: unknown): void {
+  if (error instanceof KnownError) {
+    logger.error(error.message);
+    return;
+  }
+
+  logger.error(error instanceof Error ? (error.stack ?? error.message) : error);
+}

package/src/program/root.ts

@@ -1,5 +1,5 @@
 import { generateToStdout } from "@usage-spec/commander";
-import { palette } from "@vlandoss/clibuddy";
+import { palette } from "@variablelab/clibuddy";
 import { Command } from "commander";
 import { getBannerText } from "#src/render/banner.ts";
 import { getFooterText } from "#src/render/footer.ts";

package/src/render/banner.ts

@@ -1,4 +1,4 @@
-import { palette, text } from "@vlandoss/clibuddy";
+import { palette, text } from "@variablelab/clibuddy";
 import { runRunColor } from "#src/ui/theme.ts";
 import { Lines } from "./lines.ts";
 

package/src/render/board.ts

@@ -1,4 +1,4 @@
-import { type BoardOptions, type BoardResult, type BoardTask, runTaskBoard } from "@vlandoss/clibuddy";
+import { type BoardOptions, type BoardResult, type BoardTask, runTaskBoard } from "@variablelab/clibuddy";
 import type { RunReport } from "#src/types/tool.ts";
 
 export type { BoardResult, BoardTask };

package/src/render/footer.ts

@@ -1,4 +1,4 @@
-import { palette } from "@vlandoss/clibuddy";
+import { palette } from "@variablelab/clibuddy";
 import { Lines } from "#src/render/lines.ts";
 import type { ContextValue } from "#src/services/context.ts";
 import { SEP } from "#src/ui/theme.ts";

package/src/render/labels.ts

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { type Pkg, palette } from "@vlandoss/clibuddy";
+import { type Pkg, palette } from "@variablelab/clibuddy";
 
 export type Provider = { ui: string };
 

package/src/render/plugin-view.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { palette } from "@vlandoss/clibuddy";
+import { palette } from "@variablelab/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";

package/src/run.ts

@@ -1,5 +1,14 @@
 import { createProgram } from "./program/index.ts";
+import { reportError } from "./program/report-error.ts";
 
-const program = await createProgram(import.meta);
-
-await program.run();
+try {
+  const program = await createProgram(import.meta);
+  await program.run();
+} catch (error) {
+  // Both context build-up (createProgram) and command execution (run) can throw
+  // domain errors; render them cleanly here rather than letting Node dump a raw
+  // stack trace. `process.exitCode` (not `process.exit`) lets the logger's
+  // stderr write flush before the process tears down.
+  reportError(error);
+  process.exitCode = 1;
+}

package/src/services/context.ts

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import { createPkg, createShellService, cwd, type Pkg, type ShellService } from "@vlandoss/clibuddy";
+import { createPkg, createShellService, cwd, type Pkg, type ShellService } from "@variablelab/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";

package/src/services/logger.ts

@@ -1,4 +1,4 @@
-import { createLoggy } from "@vlandoss/loggy";
+import { createLoggy } from "@variablelab/loggy";
 
 export const logger = createLoggy({
   namespace: "run-run",

package/src/services/workspace-target.ts

@@ -1,4 +1,4 @@
-import type { Pkg } from "@vlandoss/clibuddy";
+import type { Pkg } from "@variablelab/clibuddy";
 import type { PackageManager } from "nypm";
 
 export type WorkspaceChoice = { kind: "current" } | { kind: "root"; flag: true | undefined };

package/src/ui/theme.ts

@@ -1,4 +1,4 @@
-import { colorize, palette } from "@vlandoss/clibuddy";
+import { colorize, palette } from "@variablelab/clibuddy";
 
 export const SEP = `  ${palette.dim("·")}  `;