just-bash-util 0.1.1 → 0.1.3

package/README.md

@@ -1,11 +1,14 @@
 # just-bash-util
 
+[![npm](https://img.shields.io/npm/v/just-bash-util)](https://www.npmjs.com/package/just-bash-util)
+[![GitHub](https://img.shields.io/github/license/blindmansion/just-bash-util)](https://github.com/blindmansion/just-bash-util)
+
 CLI command framework, config file discovery, and path utilities for [just-bash](https://www.npmjs.com/package/just-bash).
 
 ## Install
 
 ```bash
-bun add just-bash-util just-bash
+npm install just-bash-util just-bash
 ```
 
 ## Modules
@@ -64,6 +67,7 @@ await serve.invoke({ port: 8080, entry: "app.ts" }, ctx);
 - `--` passthrough separator
 - Environment variable fallbacks for options
 - Levenshtein-based "did you mean?" suggestions for typos
+- Automatic error handling — thrown errors in handlers are caught and returned as clean `ExecResult` with `exitCode: 1`
 
 ### `just-bash-util/config` — Config file discovery
 
@@ -72,7 +76,7 @@ Cosmiconfig-style config search that walks up the directory tree, trying convent
 ```ts
 import { searchConfig } from "just-bash-util/config";
 
-// Walks up from cwd trying: package.json#myapp, .myapprc, .myapprc.json, myapp.config.json
+// Walks up from cwd trying: .myapprc, .myapprc.json, myapp.config.json
 const result = await searchConfig(ctx, { name: "myapp" });
 if (result) {
   result.config; // parsed config object
@@ -80,11 +84,14 @@ if (result) {
   result.isEmpty; // true if config is null/undefined/empty object
 }
 
-// Customize search places, starting directory, or add custom loaders
+// Find nearest package.json and return its full contents
+const pkg = await searchConfig(ctx, { name: "package", searchPlaces: ["package.json"] });
+
+// Extract a tool-specific property from package.json
 const result2 = await searchConfig(ctx, {
   name: "myapp",
-  from: "/specific/start/dir",
-  searchPlaces: [".myapprc.json", "myapp.config.json"],
+  searchPlaces: ["package.json", ".myapprc", ".myapprc.json"],
+  packageJsonProp: "myapp",
 });
 ```
 
@@ -123,12 +130,16 @@ import {
   relative,
   parse,
   normalize,
+  parsePackageSpecifier,
 } from "just-bash-util/path";
 
 join("src", "utils", "index.ts"); // "src/utils/index.ts"
 dirname("/project/src/index.ts"); // "/project/src"
 basename("src/index.ts", ".ts"); // "index"
 relative("/a/b/c", "/a/d"); // "../../d"
+
+parsePackageSpecifier("@vue/shared/dist"); // { name: "@vue/shared", subpath: "./dist" }
+parsePackageSpecifier("lodash/merge"); // { name: "lodash", subpath: "./merge" }
 ```
 
 ## Peer dependencies

package/dist/{chunk-DLIJNNDI.js → chunk-FUVD54LW.js}

@@ -3,7 +3,7 @@ import {
   dirname,
   extname,
   join
-} from "./chunk-DAO5RF73.js";
+} from "./chunk-HJ3ZU6QO.js";
 
 // src/config/find-up.ts
 async function findUp(ctx, name, options) {
@@ -88,7 +88,6 @@ function deepMerge(base, override) {
 var defaultLoader = (content) => parseJsonc(content);
 function defaultSearchPlaces(name) {
   return [
-    "package.json",
     `.${name}rc`,
     `.${name}rc.json`,
     `${name}.config.json`
@@ -133,7 +132,7 @@ async function collectAll(ctx, options) {
     from = ctx.cwd,
     searchPlaces = defaultSearchPlaces(name),
     loaders: customLoaders,
-    packageJsonProp = name,
+    packageJsonProp = false,
     stopAt = "/",
     stopWhen
   } = options;
@@ -184,7 +183,7 @@ async function searchConfig(ctx, options) {
     from = ctx.cwd,
     searchPlaces = defaultSearchPlaces(name),
     loaders: customLoaders,
-    packageJsonProp = name,
+    packageJsonProp = false,
     stopAt = "/"
   } = options;
   let dir = from;

package/dist/{chunk-DAO5RF73.js → chunk-HJ3ZU6QO.js}

@@ -115,6 +115,30 @@ function format(pathObject) {
   }
   return `${root}${resolvedBase}`;
 }
+function parsePackageSpecifier(specifier) {
+  if (specifier.startsWith("@")) {
+    const firstSlash2 = specifier.indexOf("/");
+    if (firstSlash2 === -1) {
+      return { name: specifier, subpath: "." };
+    }
+    const secondSlash = specifier.indexOf("/", firstSlash2 + 1);
+    if (secondSlash === -1) {
+      return { name: specifier, subpath: "." };
+    }
+    return {
+      name: specifier.slice(0, secondSlash),
+      subpath: `.${specifier.slice(secondSlash)}`
+    };
+  }
+  const firstSlash = specifier.indexOf("/");
+  if (firstSlash === -1) {
+    return { name: specifier, subpath: "." };
+  }
+  return {
+    name: specifier.slice(0, firstSlash),
+    subpath: `.${specifier.slice(firstSlash)}`
+  };
+}
 function relative(from, to) {
   const fromNorm = normalize(from);
   const toNorm = normalize(to);
@@ -149,5 +173,6 @@ export {
   extname,
   parse,
   format,
+  parsePackageSpecifier,
   relative
 };

package/dist/{chunk-OLDCCFR6.js → chunk-QKL3AOEA.js}

@@ -720,7 +720,12 @@ var Command = class _Command {
         }
       }
     }
-    return this.handler(resolved, ctx, { passthrough: [] });
+    try {
+      return await this.handler(resolved, ctx, { passthrough: [] });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { stdout: "", stderr: message, exitCode: 1 };
+    }
   }
   // --------------------------------------------------------------------------
   // Execution
@@ -746,7 +751,12 @@ var Command = class _Command {
       if (!parsed.ok) {
         return { stdout: "", stderr: formatErrors(parsed.errors), exitCode: 1 };
       }
-      return this.handler(parsed.args, ctx, { passthrough: parsed.passthrough });
+      try {
+        return await this.handler(parsed.args, ctx, { passthrough: parsed.passthrough });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { stdout: "", stderr: message, exitCode: 1 };
+      }
     }
     if (firstToken && !firstToken.startsWith("-")) {
       const suggestions = findSuggestions(firstToken, [...this.children.keys()]);

package/dist/command/index.js

@@ -8,7 +8,7 @@ import {
   generateHelp,
   o,
   parseArgs
-} from "../chunk-OLDCCFR6.js";
+} from "../chunk-QKL3AOEA.js";
 export {
   Command,
   a,

package/dist/config/index.d.ts

@@ -40,7 +40,6 @@ interface SearchConfigOptions {
      * Filenames to look for at each directory level, tried in order.
      *
      * Defaults:
-     * - `"package.json"` (extracts the `name` property)
      * - `".{name}rc"`
      * - `".{name}rc.json"`
      * - `"{name}.config.json"`
@@ -54,7 +53,7 @@ interface SearchConfigOptions {
     /**
      * Property to extract from `package.json`.
      * Set to `false` to disable property extraction (load full object).
-     * Default: the `name` option.
+     * Default: `false`.
      */
     packageJsonProp?: string | false;
     /** Directory to stop searching at (default: `"/"`) */
@@ -105,6 +104,16 @@ interface LoadConfigOptions {
  * const result = await searchConfig(ctx, { name: "myapp" });
  * if (result) console.log(result.config, result.filepath);
  *
+ * // Find nearest package.json and return its full contents
+ * const pkg = await searchConfig(ctx, { name: "package", searchPlaces: ["package.json"] });
+ *
+ * // Extract a specific property from package.json
+ * const result = await searchConfig(ctx, {
+ *   name: "myapp",
+ *   searchPlaces: ["package.json", ".myapprc", ".myapprc.json"],
+ *   packageJsonProp: "myapp",
+ * });
+ *
  * // Layered / cascading config
  * const merged = await searchConfig(ctx, { name: "myapp", merge: true });
  * ```

package/dist/config/index.js

@@ -2,8 +2,8 @@ import {
   findUp,
   loadConfig,
   searchConfig
-} from "../chunk-DLIJNNDI.js";
-import "../chunk-DAO5RF73.js";
+} from "../chunk-FUVD54LW.js";
+import "../chunk-HJ3ZU6QO.js";
 export {
   findUp,
   loadConfig,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { Command, Handler, Infer, ParseArgsResult, ParseError, a, command, f, formatError, formatErrors, generateHelp, o, parseArgs } from './command/index.js';
 export { ConfigResult, FindUpOptions, LoadConfigOptions, Loader, SearchConfigOptions, findUp, loadConfig, searchConfig } from './config/index.js';
-export { ParsedPath, basename, delimiter, dirname, extname, format, isAbsolute, join, normalize, parse, relative, resolve, sep } from './path/index.js';
+export { PackageSpecifier, ParsedPath, basename, delimiter, dirname, extname, format, isAbsolute, join, normalize, parse, parsePackageSpecifier, relative, resolve, sep } from './path/index.js';
 import 'just-bash';

package/dist/index.js

@@ -8,12 +8,12 @@ import {
   generateHelp,
   o,
   parseArgs
-} from "./chunk-OLDCCFR6.js";
+} from "./chunk-QKL3AOEA.js";
 import {
   findUp,
   loadConfig,
   searchConfig
-} from "./chunk-DLIJNNDI.js";
+} from "./chunk-FUVD54LW.js";
 import {
   basename,
   delimiter,
@@ -24,10 +24,11 @@ import {
   join,
   normalize,
   parse,
+  parsePackageSpecifier,
   relative,
   resolve,
   sep
-} from "./chunk-DAO5RF73.js";
+} from "./chunk-HJ3ZU6QO.js";
 export {
   Command,
   a,
@@ -49,6 +50,7 @@ export {
   o,
   parse,
   parseArgs,
+  parsePackageSpecifier,
   relative,
   resolve,
   searchConfig,

package/dist/path/index.d.ts

@@ -33,7 +33,26 @@ interface ParsedPath {
 declare function parse(path: string): ParsedPath;
 /** Build a path string from components (inverse of `parse`) */
 declare function format(pathObject: Partial<ParsedPath>): string;
+interface PackageSpecifier {
+    /** Package name (e.g. `"pkg"` or `"@scope/pkg"`) */
+    name: string;
+    /** Subpath within the package (e.g. `"./sub/path"`), or `"."` for the root */
+    subpath: string;
+}
+/**
+ * Parse a bare package specifier into its package name and subpath.
+ *
+ * Handles both scoped (`@scope/pkg/sub`) and unscoped (`pkg/sub`) specifiers.
+ * The subpath is normalized to start with `"./"` (or `"."` for the root).
+ *
+ * ```ts
+ * parsePackageSpecifier("lodash/merge")     // { name: "lodash", subpath: "./merge" }
+ * parsePackageSpecifier("@vue/shared/dist") // { name: "@vue/shared", subpath: "./dist" }
+ * parsePackageSpecifier("react")            // { name: "react", subpath: "." }
+ * ```
+ */
+declare function parsePackageSpecifier(specifier: string): PackageSpecifier;
 /** Compute the relative path from `from` to `to` */
 declare function relative(from: string, to: string): string;
 
-export { type ParsedPath, basename, delimiter, dirname, extname, format, isAbsolute, join, normalize, parse, relative, resolve, sep };
+export { type PackageSpecifier, type ParsedPath, basename, delimiter, dirname, extname, format, isAbsolute, join, normalize, parse, parsePackageSpecifier, relative, resolve, sep };

package/dist/path/index.js

@@ -8,10 +8,11 @@ import {
   join,
   normalize,
   parse,
+  parsePackageSpecifier,
   relative,
   resolve,
   sep
-} from "../chunk-DAO5RF73.js";
+} from "../chunk-HJ3ZU6QO.js";
 export {
   basename,
   delimiter,
@@ -22,6 +23,7 @@ export {
   join,
   normalize,
   parse,
+  parsePackageSpecifier,
   relative,
   resolve,
   sep

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "just-bash-util",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CLI command framework, config file discovery, and path utilities for just-bash",
   "type": "module",
   "license": "MIT",
   "author": "blindmansion",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blindmansion/just-bash-util.git"
+  },
+  "homepage": "https://github.com/blindmansion/just-bash-util",
+  "bugs": {
+    "url": "https://github.com/blindmansion/just-bash-util/issues"
+  },
   "keywords": [
     "cli",
     "command",