@vlandoss/clibuddy 0.4.1-git-e0772c7.0 → 0.5.1-git-87ebfca.0

package/dist/index.d.mts

@@ -1,8 +1,7 @@
 import * as _$ansis from "ansis";
 import { hasTTY, isCI } from "std-env";
 import { PackageJson } from "pkg-types";
-import * as _$zx from "zx";
-import { Options, ProcessOutput, Shell as Shell$1 } from "zx";
+import { NonZeroExitError, Output } from "tinyexec";
 import { Project } from "@pnpm/types";
 
 //#region src/colors.d.ts
@@ -48,35 +47,43 @@ declare function run(fn: () => Promise<void>, logger: {
 }): Promise<void>;
 //#endregion
 //#region src/shell/types.d.ts
-type Shell = Shell$1;
-type ShellOptions = Partial<Options>;
-type CreateOptions = ShellOptions & {
-  localBaseBinPath?: string | Array<string>;
+type ShellOptions = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  verbose?: boolean;
+};
+type RunOptions = ShellOptions & {
+  throwOnError?: boolean;
+  shell?: boolean;
+  stdin?: string;
+  display?: string;
 };
 //#endregion
 //#region src/shell/shell.d.ts
 declare class ShellService {
   #private;
-  constructor(options: ShellOptions);
-  get options(): Partial<_$zx.Options>;
-  get $(): Shell;
+  constructor(options?: ShellOptions);
+  get options(): ShellOptions;
+  at(cwd: string): ShellService;
   child(options: ShellOptions): ShellService;
-  quiet(options?: ShellOptions): ShellService;
-  mute(options?: ShellOptions): ShellService;
-  at(cwd: string, options?: ShellOptions): ShellService;
+  quiet(): ShellService;
+  run(cmd: string, args?: string[], opts?: RunOptions): Promise<Output>;
+  runCaptured(cmd: string, args?: string[], opts?: RunOptions): Promise<Output>;
 }
 //#endregion
 //#region src/shell/create.d.ts
 declare const cwd: string;
-declare function quote(arg: string): string;
-declare const isRaw: (arg: unknown) => arg is {
-  stdout: string;
-};
-declare function createShellService(options?: CreateOptions): ShellService;
+declare function createShellService(options?: ShellOptions): ShellService;
+//#endregion
+//#region src/shell/resolve-bin.d.ts
+declare function resolveBinPath(pkg: string, options: {
+  from: string;
+  binPath?: string;
+  binName?: string;
+}): string;
 //#endregion
 //#region src/shell/utils.d.ts
-declare function isProcessOutput(value: unknown): value is ProcessOutput;
-declare function getPreferLocal(localBaseBinPath: string | Array<string> | undefined): string[] | undefined;
+declare function isNonZeroExitError(value: unknown): value is NonZeroExitError;
 //#endregion
 //#region src/text.d.ts
 declare const text: {
@@ -84,4 +91,4 @@ declare const text: {
   version: (version: string) => string;
 };
 //#endregion
-export { CreateOptions, Pkg, type Project, Shell, ShellOptions, ShellService, colorize, createPkg, createShellService, cwd, dirnameOf, filenameOf, getPreferLocal, hasTTY, isCI, isProcessOutput, isRaw, palette, quote, run, text };
+export { NonZeroExitError, Pkg, type Project, RunOptions, ShellOptions, ShellService, colorize, createPkg, createShellService, cwd, dirnameOf, filenameOf, hasTTY, isCI, isNonZeroExitError, palette, resolveBinPath, run, text };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import ansis, { bold, cyan, dim, green, italic, underline } from "ansis";
 import { hasTTY, isCI } from "std-env";
 import path, { dirname } from "node:path";
@@ -7,7 +8,7 @@ import { readFile } from "node:fs/promises";
 import { findPackages } from "@pnpm/fs.find-packages";
 import { readPackageJSON, resolvePackageJSON, writePackageJSON } from "pkg-types";
 import { parse } from "yaml";
-import { $, ProcessOutput } from "zx";
+import { NonZeroExitError, x } from "tinyexec";
 //#region src/colors.ts
 const colorize = (hex) => ansis.hex(hex);
 const palette = {
@@ -101,12 +102,8 @@ async function createPkg(cwd) {
 }
 //#endregion
 //#region src/shell/utils.ts
-function isProcessOutput(value) {
-	return value instanceof ProcessOutput;
-}
-const getLocalBinPath = (dirPath) => path.join(dirPath, "node_modules", ".bin");
-function getPreferLocal(localBaseBinPath) {
-	return !localBaseBinPath ? void 0 : Array.isArray(localBaseBinPath) ? localBaseBinPath.map(getLocalBinPath) : [localBaseBinPath].map(getLocalBinPath);
+function isNonZeroExitError(value) {
+	return value instanceof NonZeroExitError;
 }
 //#endregion
 //#region src/run.ts
@@ -121,85 +118,124 @@ async function run(fn, logger) {
 	try {
 		await fn();
 	} catch (error) {
-		if (!isProcessOutput(error)) logger.error(formatError(error));
+		if (!isNonZeroExitError(error)) logger.error(formatError(error));
 		process.exit(1);
 	}
 }
 //#endregion
 //#region src/shell/shell.ts
 var ShellService = class ShellService {
-	#shell;
 	#options;
-	constructor(options) {
-		this.#options = Object.freeze(options);
-		this.#shell = $(options);
+	constructor(options = {}) {
+		this.#options = Object.freeze({
+			cwd: options.cwd ?? process.cwd(),
+			env: options.env,
+			verbose: options.verbose ?? true
+		});
 	}
 	get options() {
 		return this.#options;
 	}
-	get $() {
-		return this.#shell;
+	at(cwd) {
+		return this.child({ cwd });
 	}
 	child(options) {
 		return new ShellService({
 			...this.#options,
-			...options
-		});
-	}
-	quiet(options) {
-		return this.child({
 			...options,
-			verbose: false
+			env: options.env ? {
+				...this.#options.env,
+				...options.env
+			} : this.#options.env
 		});
 	}
-	mute(options) {
-		return this.quiet({
-			...options,
-			stdio: "pipe"
+	quiet() {
+		return this.child({ verbose: false });
+	}
+	async run(cmd, args = [], opts = {}) {
+		const merged = this.#mergeRunOpts(opts);
+		if (merged.verbose) printCmdLine(opts.display ?? cmd, args);
+		return x(cmd, args, {
+			throwOnError: opts.throwOnError ?? true,
+			...opts.stdin !== void 0 && { stdin: opts.stdin },
+			nodeOptions: {
+				cwd: merged.cwd,
+				...merged.env && { env: merged.env },
+				stdio: "inherit",
+				...opts.shell && { shell: true }
+			}
 		});
 	}
-	at(cwd, options) {
-		const getLocals = (locals) => typeof locals === "boolean" ? [] : typeof locals === "undefined" ? [] : Array.isArray(locals) ? locals : [locals];
-		const cwdPreferLocal = getPreferLocal(cwd);
-		const preferLocal = options?.preferLocal === false ? false : [
-			...getLocals(this.#options.preferLocal),
-			...getLocals(options?.preferLocal),
-			...cwdPreferLocal ? cwdPreferLocal : []
-		];
-		return this.child({
-			...options,
-			cwd,
-			preferLocal
+	async runCaptured(cmd, args = [], opts = {}) {
+		const merged = this.#mergeRunOpts(opts);
+		return x(cmd, args, {
+			throwOnError: opts.throwOnError ?? true,
+			...opts.stdin !== void 0 && { stdin: opts.stdin },
+			nodeOptions: {
+				cwd: merged.cwd,
+				...merged.env && { env: merged.env },
+				...opts.shell && { shell: true }
+			}
 		});
 	}
+	#mergeRunOpts(opts) {
+		return {
+			cwd: opts.cwd ?? this.#options.cwd ?? process.cwd(),
+			env: opts.env ? {
+				...this.#options.env,
+				...opts.env
+			} : this.#options.env,
+			verbose: opts.verbose ?? this.#options.verbose ?? true
+		};
+	}
 };
+function printCmdLine(cmd, args) {
+	const tail = args.length === 0 ? "" : ` ${args.join(" ")}`;
+	process.stderr.write(`${palette.muted("$")} ${palette.highlight(cmd)}${tail}\n`);
+}
 //#endregion
 //#region src/shell/create.ts
 const cwd = fs.realpathSync(process.cwd());
-function quote(arg) {
-	if (/^[\w./:=@-]+$/i.test(arg) || arg === "") return arg;
-	return arg.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\f/g, "\\f").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t").replace(/\v/g, "\\v").replace(/\0/g, "\\0");
-}
-const isRaw = (arg) => typeof arg === "object" && arg !== null && "stdout" in arg && typeof arg.stdout === "string";
-function defaultQuote(arg) {
-	if (typeof arg === "string") return quote(arg);
-	if (isRaw(arg)) return arg.stdout;
-	throw TypeError(`Unsupported argument type: ${typeof arg}`);
-}
 function createShellService(options = {}) {
 	return new ShellService({
-		verbose: true,
 		cwd,
-		preferLocal: getPreferLocal(options.localBaseBinPath),
-		quote: defaultQuote,
 		...options
 	});
 }
 //#endregion
+//#region src/shell/resolve-bin.ts
+function resolveBinPath(pkg, options) {
+	const pkgRoot = findPackageRoot(createRequire(options.from), pkg);
+	if (options.binPath) return path.join(pkgRoot, options.binPath);
+	const bin = JSON.parse(fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8")).bin;
+	if (!bin) throw new Error(`Package ${pkg} has no "bin" field`);
+	if (typeof bin === "string") return path.join(pkgRoot, bin);
+	const wantName = options.binName ?? pkg.replace(/^@[^/]+\//, "");
+	const rel = bin[wantName] ?? Object.values(bin)[0];
+	if (!rel) throw new Error(`No bin entry found for ${pkg} (asked for ${wantName})`);
+	return path.join(pkgRoot, rel);
+}
+function findPackageRoot(require, pkg) {
+	try {
+		return path.dirname(require.resolve(`${pkg}/package.json`));
+	} catch {}
+	const mainPath = require.resolve(pkg);
+	let dir = path.dirname(mainPath);
+	const fsRoot = path.parse(dir).root;
+	while (dir !== fsRoot) {
+		const pkgJsonPath = path.join(dir, "package.json");
+		if (fs.existsSync(pkgJsonPath)) try {
+			if (JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")).name === pkg) return dir;
+		} catch {}
+		dir = path.dirname(dir);
+	}
+	throw new Error(`Could not find package root for ${pkg} from ${mainPath}`);
+}
+//#endregion
 //#region src/text.ts
 const text = {
 	vland: `${palette.link(palette.primary("https://variable.land"))} 👊`,
 	version: (version) => palette.muted(`v${version}`)
 };
 //#endregion
-export { Pkg, ShellService, colorize, createPkg, createShellService, cwd, dirnameOf, filenameOf, getPreferLocal, hasTTY, isCI, isProcessOutput, isRaw, palette, quote, run, text };
+export { NonZeroExitError, Pkg, ShellService, colorize, createPkg, createShellService, cwd, dirnameOf, filenameOf, hasTTY, isCI, isNonZeroExitError, palette, resolveBinPath, run, text };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vlandoss/clibuddy",
-  "version": "0.4.1-git-e0772c7.0",
+  "version": "0.5.1-git-87ebfca.0",
   "description": "A helper library to create CLIs in Variable Land",
   "homepage": "https://github.com/variableland/dx/tree/main/packages/clibuddy#readme",
   "bugs": {
@@ -32,8 +32,8 @@
     "ansis": "4.2.0",
     "pkg-types": "2.3.0",
     "std-env": "3.9.0",
-    "yaml": "2.8.4",
-    "zx": "8.8.5"
+    "tinyexec": "1.1.2",
+    "yaml": "2.8.4"
   },
   "publishConfig": {
     "access": "public"

package/src/run.ts

@@ -1,4 +1,4 @@
-import { isProcessOutput } from "./shell/utils.ts";
+import { isNonZeroExitError } from "./shell/utils.ts";
 
 function hasMessage(error: unknown): error is { message: string } {
   return (
@@ -18,7 +18,8 @@ export async function run(fn: () => Promise<void>, logger: { error: (...args: un
   try {
     await fn();
   } catch (error) {
-    if (!isProcessOutput(error)) {
+    // The subprocess already streamed its own stderr; don't double-print.
+    if (!isNonZeroExitError(error)) {
       logger.error(formatError(error));
     }
     process.exit(1);

package/src/shell/create.ts

@@ -1,50 +1,9 @@
 import fs from "node:fs";
 import { ShellService } from "./shell.ts";
-import type { CreateOptions } from "./types.ts";
-import { getPreferLocal } from "./utils.ts";
+import type { ShellOptions } from "./types.ts";
 
 export const cwd = fs.realpathSync(process.cwd());
 
-// Inspired by https://dub.sh/6tiHVgn
-export function quote(arg: string) {
-  if (/^[\w./:=@-]+$/i.test(arg) || arg === "") {
-    return arg;
-  }
-
-  return arg
-    .replace(/\\/g, "\\\\")
-    .replace(/'/g, "\\'")
-    .replace(/\f/g, "\\f")
-    .replace(/\n/g, "\\n")
-    .replace(/\r/g, "\\r")
-    .replace(/\t/g, "\\t")
-    .replace(/\v/g, "\\v")
-    .replace(/\0/g, "\\0");
-}
-
-export const isRaw = (arg: unknown): arg is { stdout: string } =>
-  typeof arg === "object" && arg !== null && "stdout" in arg && typeof arg.stdout === "string";
-
-function defaultQuote(arg: unknown) {
-  if (typeof arg === "string") {
-    return quote(arg);
-  }
-
-  if (isRaw(arg)) {
-    return arg.stdout;
-  }
-
-  throw TypeError(`Unsupported argument type: ${typeof arg}`);
-}
-
-export function createShellService(options: CreateOptions = {}) {
-  const preferLocal = getPreferLocal(options.localBaseBinPath);
-
-  return new ShellService({
-    verbose: true,
-    cwd,
-    preferLocal,
-    quote: defaultQuote,
-    ...options,
-  });
+export function createShellService(options: ShellOptions = {}): ShellService {
+  return new ShellService({ cwd, ...options });
 }

package/src/shell/index.ts

@@ -1,4 +1,5 @@
 export * from "./create.ts";
+export * from "./resolve-bin.ts";
 export * from "./shell.ts";
 export * from "./types.ts";
 export * from "./utils.ts";

package/src/shell/resolve-bin.ts

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+export function resolveBinPath(pkg: string, options: { from: string; binPath?: string; binName?: string }): string {
+  const require = createRequire(options.from);
+  const pkgRoot = findPackageRoot(require, pkg);
+
+  if (options.binPath) {
+    return path.join(pkgRoot, options.binPath);
+  }
+
+  const pkgJson = JSON.parse(fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8")) as {
+    bin?: string | Record<string, string>;
+  };
+  const bin = pkgJson.bin;
+  if (!bin) throw new Error(`Package ${pkg} has no "bin" field`);
+
+  if (typeof bin === "string") return path.join(pkgRoot, bin);
+
+  const wantName = options.binName ?? pkg.replace(/^@[^/]+\//, "");
+  const rel = bin[wantName] ?? Object.values(bin)[0];
+  if (!rel) throw new Error(`No bin entry found for ${pkg} (asked for ${wantName})`);
+  return path.join(pkgRoot, rel);
+}
+
+// Two-step lookup tolerates packages that don't expose `./package.json` in
+// their `exports` map (e.g. oxlint) and packages with no `main`/`exports` at
+// all (e.g. @biomejs/biome) — `require.resolve(pkg)` fails for the latter.
+function findPackageRoot(require: NodeJS.Require, pkg: string): string {
+  try {
+    return path.dirname(require.resolve(`${pkg}/package.json`));
+  } catch {
+    // fall through to manual walk
+  }
+
+  const mainPath = require.resolve(pkg);
+  let dir = path.dirname(mainPath);
+  const fsRoot = path.parse(dir).root;
+  while (dir !== fsRoot) {
+    const pkgJsonPath = path.join(dir, "package.json");
+    if (fs.existsSync(pkgJsonPath)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")) as { name?: string };
+        if (data.name === pkg) return dir;
+      } catch {
+        // not a valid package.json — keep walking
+      }
+    }
+    dir = path.dirname(dir);
+  }
+  throw new Error(`Could not find package root for ${pkg} from ${mainPath}`);
+}

package/src/shell/shell.ts

@@ -1,65 +1,76 @@
-import { $ as make$ } from "zx";
-import type { Shell, ShellOptions } from "./types.ts";
-import { getPreferLocal } from "./utils.ts";
+import { type Output, x as tinyexec } from "tinyexec";
+import { palette } from "../colors.ts";
+import type { RunOptions, ShellOptions } from "./types.ts";
 
 export class ShellService {
-  #shell: Shell;
   #options: ShellOptions;
 
-  constructor(options: ShellOptions) {
-    this.#options = Object.freeze(options);
-    this.#shell = make$(options);
+  constructor(options: ShellOptions = {}) {
+    this.#options = Object.freeze({
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env,
+      verbose: options.verbose ?? true,
+    });
   }
 
-  get options() {
+  get options(): ShellOptions {
     return this.#options;
   }
 
-  get $() {
-    return this.#shell;
+  at(cwd: string): ShellService {
+    return this.child({ cwd });
   }
 
-  child(options: ShellOptions) {
+  child(options: ShellOptions): ShellService {
     return new ShellService({
       ...this.#options,
       ...options,
+      env: options.env ? { ...this.#options.env, ...options.env } : this.#options.env,
     });
   }
 
-  quiet(options?: ShellOptions) {
-    return this.child({
-      ...options,
-      verbose: false,
-    });
+  quiet(): ShellService {
+    return this.child({ verbose: false });
   }
 
-  mute(options?: ShellOptions) {
-    return this.quiet({
-      ...options,
-      stdio: "pipe",
+  async run(cmd: string, args: string[] = [], opts: RunOptions = {}): Promise<Output> {
+    const merged = this.#mergeRunOpts(opts);
+    if (merged.verbose) printCmdLine(opts.display ?? cmd, args);
+    return tinyexec(cmd, args, {
+      throwOnError: opts.throwOnError ?? true,
+      ...(opts.stdin !== undefined && { stdin: opts.stdin }),
+      nodeOptions: {
+        cwd: merged.cwd,
+        ...(merged.env && { env: merged.env }),
+        stdio: "inherit",
+        ...(opts.shell && { shell: true }),
+      },
     });
   }
 
-  at(cwd: string, options?: ShellOptions) {
-    const getLocals = (locals: boolean | string | string[] | undefined) =>
-      // NOTE: the boolean handling is done outside when determining preferLocal
-      typeof locals === "boolean" ? [] : typeof locals === "undefined" ? [] : Array.isArray(locals) ? locals : [locals];
-
-    const cwdPreferLocal = getPreferLocal(cwd);
-
-    const preferLocal =
-      options?.preferLocal === false
-        ? false
-        : [
-            ...getLocals(this.#options.preferLocal),
-            ...getLocals(options?.preferLocal),
-            ...(cwdPreferLocal ? cwdPreferLocal : []),
-          ];
-
-    return this.child({
-      ...options,
-      cwd,
-      preferLocal,
+  async runCaptured(cmd: string, args: string[] = [], opts: RunOptions = {}): Promise<Output> {
+    const merged = this.#mergeRunOpts(opts);
+    return tinyexec(cmd, args, {
+      throwOnError: opts.throwOnError ?? true,
+      ...(opts.stdin !== undefined && { stdin: opts.stdin }),
+      nodeOptions: {
+        cwd: merged.cwd,
+        ...(merged.env && { env: merged.env }),
+        ...(opts.shell && { shell: true }),
+      },
     });
   }
+
+  #mergeRunOpts(opts: RunOptions) {
+    return {
+      cwd: opts.cwd ?? this.#options.cwd ?? process.cwd(),
+      env: opts.env ? { ...this.#options.env, ...opts.env } : this.#options.env,
+      verbose: opts.verbose ?? this.#options.verbose ?? true,
+    };
+  }
+}
+
+function printCmdLine(cmd: string, args: string[]): void {
+  const tail = args.length === 0 ? "" : ` ${args.join(" ")}`;
+  process.stderr.write(`${palette.muted("$")} ${palette.highlight(cmd)}${tail}\n`);
 }

package/src/shell/types.ts

@@ -1,9 +1,12 @@
-import type { Options as ZxOptions, Shell as ZxShell } from "zx";
-
-export type Shell = ZxShell;
-
-export type ShellOptions = Partial<ZxOptions>;
+export type ShellOptions = {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  verbose?: boolean;
+};
 
-export type CreateOptions = ShellOptions & {
-  localBaseBinPath?: string | Array<string>;
+export type RunOptions = ShellOptions & {
+  throwOnError?: boolean;
+  shell?: boolean;
+  stdin?: string;
+  display?: string;
 };

package/src/shell/utils.ts

@@ -1,16 +1,7 @@
-import path from "node:path";
-import { ProcessOutput } from "zx";
+import { NonZeroExitError } from "tinyexec";
 
-export function isProcessOutput(value: unknown): value is ProcessOutput {
-  return value instanceof ProcessOutput;
-}
-
-const getLocalBinPath = (dirPath: string) => path.join(dirPath, "node_modules", ".bin");
+export { NonZeroExitError };
 
-export function getPreferLocal(localBaseBinPath: string | Array<string> | undefined) {
-  return !localBaseBinPath
-    ? undefined
-    : Array.isArray(localBaseBinPath)
-      ? localBaseBinPath.map(getLocalBinPath)
-      : [localBaseBinPath].map(getLocalBinPath);
+export function isNonZeroExitError(value: unknown): value is NonZeroExitError {
+  return value instanceof NonZeroExitError;
 }