just-bash-util 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blindmansion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# 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
+```
+
+## Modules
+
+### `just-bash-util/command` — CLI framework
+
+Type-safe command trees with fluent builders, inherited options, auto-generated help, and typo suggestions.
+
+```ts
+import { Bash } from "just-bash";
+import { command, o, f, a } from "just-bash-util/command";
+
+const cli = command("mycli", {
+  description: "My CLI tool",
+});
+
+const serve = cli.command("serve", {
+  description: "Start the dev server",
+  options: {
+    port: o.number().default(3000).short("p").describe("Port to listen on"),
+    host: o.string().describe("Host to bind to"),
+    open: f().short("o").describe("Open browser"),
+  },
+  args: [a.string().name("entry").describe("Entry file")],
+  handler: (args, ctx) => {
+    // args is fully typed: { port: number; host: string | undefined; open: boolean; entry: string }
+    return { stdout: `Listening on :${args.port}`, stderr: "", exitCode: 0 };
+  },
+});
+
+const bash = new Bash({ customCommands: [cli.toCommand()] });
+await bash.exec("mycli serve app.ts -p 8080");
+```
+
+Commands can also be executed directly without just-bash:
+
+```ts
+import type { Infer } from "just-bash-util/command";
+
+// Extract handler args type externally (like z.infer)
+type ServeArgs = Infer<typeof serve>;
+
+// Execute from CLI tokens
+await cli.execute(["serve", "app.ts", "-p", "8080"], ctx);
+
+// Or invoke programmatically with typed args
+await serve.invoke({ port: 8080, entry: "app.ts" }, ctx);
+```
+
+**Features:**
+
+- Subcommand nesting with automatic option inheritance
+- `omitInherited` to exclude parent options from specific subcommands
+- `--help` / `-h` auto-generated at every level
+- `--no-<flag>` negation, `-abc` combined short flags, `--key=value` syntax
+- `--` passthrough separator
+- Environment variable fallbacks for options
+- Levenshtein-based "did you mean?" suggestions for typos
+
+### `just-bash-util/config` — Config file discovery
+
+Cosmiconfig-style config search that walks up the directory tree, trying conventional filenames at each level. Comments and trailing commas are supported out of the box.
+
+```ts
+import { searchConfig } from "just-bash-util/config";
+
+// Walks up from cwd trying: package.json#myapp, .myapprc, .myapprc.json, myapp.config.json
+const result = await searchConfig(ctx, { name: "myapp" });
+if (result) {
+  result.config; // parsed config object
+  result.filepath; // absolute path to the file that matched
+  result.isEmpty; // true if config is null/undefined/empty object
+}
+
+// Customize search places, starting directory, or add custom loaders
+const result2 = await searchConfig(ctx, {
+  name: "myapp",
+  from: "/specific/start/dir",
+  searchPlaces: [".myapprc.json", "myapp.config.json"],
+});
+```
+
+**Layered / cascading configs** — pass `merge: true` to collect configs from every directory level and deep-merge them (closest wins):
+
+```ts
+const result = await searchConfig(ctx, { name: "myapp", merge: true });
+// e.g. /project/.myapprc.json  → { indent: 2, rules: { semi: "error" } }
+//      /.myapprc.json           → { indent: 4, color: true, rules: { semi: "warn" } }
+// result.config                → { indent: 2, color: true, rules: { semi: "error" } }
+```
+
+Use `stopWhen` for ESLint-style `root: true` cascading stops:
+
+```ts
+const result = await searchConfig(ctx, {
+  name: "myapp",
+  merge: true,
+  stopWhen: (cfg) => cfg.root === true,
+});
+```
+
+Also exports `loadConfig` for loading a known file path directly (e.g. when the user passes `--config ./path`), and `findUp` for locating files by name up the directory tree.
+
+### `just-bash-util/path` — Path utilities
+
+Pure POSIX path operations with no Node.js dependency.
+
+```ts
+import {
+  join,
+  resolve,
+  dirname,
+  basename,
+  extname,
+  relative,
+  parse,
+  normalize,
+} 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"
+```
+
+## Peer dependencies
+
+Requires [`just-bash`](https://www.npmjs.com/package/just-bash) ^2.9.6 — provides the `CommandContext` and `ExecResult` types used throughout.
+
+## License
+
+MIT

package/dist/chunk-DAO5RF73.js

@@ -0,0 +1,153 @@
+// src/path/index.ts
+var sep = "/";
+var delimiter = ":";
+function isAbsolute(path) {
+  return path.charCodeAt(0) === 47;
+}
+function normalize(path) {
+  if (path === "") return ".";
+  if (path === "/") return "/";
+  const isAbs = path.charCodeAt(0) === 47;
+  const trailingSlash = path.charCodeAt(path.length - 1) === 47;
+  const segments = path.split("/");
+  const result = [];
+  for (const seg of segments) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (isAbs) {
+        result.pop();
+      } else if (result.length > 0 && result[result.length - 1] !== "..") {
+        result.pop();
+      } else {
+        result.push("..");
+      }
+    } else {
+      result.push(seg);
+    }
+  }
+  let out = result.join("/");
+  if (isAbs) {
+    out = "/" + out;
+  }
+  if (trailingSlash && out.length > 1 && !out.endsWith("/")) {
+    out += "/";
+  }
+  return out || (isAbs ? "/" : trailingSlash ? "./" : ".");
+}
+function join(...paths) {
+  if (paths.length === 0) return ".";
+  const joined = paths.filter((p) => p !== "").join("/");
+  if (joined === "") return ".";
+  return normalize(joined);
+}
+function resolve(...paths) {
+  let resolved = "";
+  for (let i = paths.length - 1; i >= 0; i--) {
+    const p = paths[i];
+    if (!p) continue;
+    resolved = resolved ? `${p}/${resolved}` : p;
+    if (p.charCodeAt(0) === 47) break;
+  }
+  return normalize(resolved || ".");
+}
+function dirname(path) {
+  if (path === "") return ".";
+  if (path === "/") return "/";
+  let end = path.length;
+  while (end > 1 && path.charCodeAt(end - 1) === 47) end--;
+  const trimmed = path.slice(0, end);
+  const i = trimmed.lastIndexOf("/");
+  if (i === -1) return ".";
+  if (i === 0) return "/";
+  return trimmed.slice(0, i);
+}
+function basename(path, ext) {
+  if (path === "") return "";
+  let end = path.length;
+  while (end > 1 && path.charCodeAt(end - 1) === 47) end--;
+  const trimmed = path.slice(0, end);
+  if (trimmed === "/") return "";
+  const i = trimmed.lastIndexOf("/");
+  const base = i === -1 ? trimmed : trimmed.slice(i + 1);
+  if (ext && base.endsWith(ext) && base.length > ext.length) {
+    return base.slice(0, base.length - ext.length);
+  }
+  return base;
+}
+function extname(path) {
+  const base = basename(path);
+  if (base === "" || base === "." || base === "..") return "";
+  const i = base.lastIndexOf(".");
+  if (i <= 0) return "";
+  return base.slice(i);
+}
+function parse(path) {
+  if (path === "") return { root: "", dir: "", base: "", name: "", ext: "" };
+  const root = isAbsolute(path) ? "/" : "";
+  let end = path.length;
+  while (end > 1 && path.charCodeAt(end - 1) === 47) end--;
+  const p = path.slice(0, end);
+  const lastSlash = p.lastIndexOf("/");
+  let dir;
+  let base;
+  if (lastSlash === -1) {
+    dir = "";
+    base = p;
+  } else if (lastSlash === 0) {
+    dir = "/";
+    base = p.slice(1);
+  } else {
+    dir = p.slice(0, lastSlash);
+    base = p.slice(lastSlash + 1);
+  }
+  const ext = extname(base);
+  const name = ext ? base.slice(0, base.length - ext.length) : base;
+  return { root, dir, base, name, ext };
+}
+function format(pathObject) {
+  const { root = "", dir, base, name, ext } = pathObject;
+  const resolvedBase = base || `${name || ""}${ext || ""}`;
+  if (dir) {
+    if (dir === root) {
+      return `${dir}${resolvedBase}`;
+    }
+    return `${dir}/${resolvedBase}`;
+  }
+  return `${root}${resolvedBase}`;
+}
+function relative(from, to) {
+  const fromNorm = normalize(from);
+  const toNorm = normalize(to);
+  if (fromNorm === toNorm) return "";
+  const fromParts = fromNorm === "/" ? [""] : fromNorm.split("/");
+  const toParts = toNorm === "/" ? [""] : toNorm.split("/");
+  const fromAbs = fromNorm.charCodeAt(0) === 47;
+  const toAbs = toNorm.charCodeAt(0) === 47;
+  const startIdx = fromAbs && toAbs ? 1 : 0;
+  let common = startIdx;
+  const minLen = Math.min(fromParts.length, toParts.length);
+  while (common < minLen && fromParts[common] === toParts[common]) {
+    common++;
+  }
+  const ups = fromParts.length - common;
+  const rest = toParts.slice(common);
+  const parts = [];
+  for (let i = 0; i < ups; i++) parts.push("..");
+  for (const r of rest) parts.push(r);
+  return parts.join("/") || ".";
+}
+
+export {
+  sep,
+  delimiter,
+  isAbsolute,
+  normalize,
+  join,
+  resolve,
+  dirname,
+  basename,
+  extname,
+  parse,
+  format,
+  relative
+};

package/dist/chunk-DLIJNNDI.js

@@ -0,0 +1,221 @@
+import {
+  basename,
+  dirname,
+  extname,
+  join
+} from "./chunk-DAO5RF73.js";
+
+// src/config/find-up.ts
+async function findUp(ctx, name, options) {
+  const names = Array.isArray(name) ? name : [name];
+  const from = options?.from ?? ctx.cwd;
+  const stopAt = options?.stopAt ?? "/";
+  let dir = from;
+  while (true) {
+    for (const n of names) {
+      const filepath = join(dir, n);
+      if (await ctx.fs.exists(filepath)) {
+        return filepath;
+      }
+    }
+    if (dir === stopAt) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// src/config/jsonc.ts
+function stripJsonComments(input) {
+  let result = "";
+  let i = 0;
+  while (i < input.length) {
+    const ch = input[i];
+    if (ch === '"') {
+      let str = '"';
+      i++;
+      while (i < input.length) {
+        const c = input[i];
+        str += c;
+        if (c === "\\" && i + 1 < input.length) {
+          str += input[i + 1];
+          i += 2;
+          continue;
+        }
+        i++;
+        if (c === '"') break;
+      }
+      result += str;
+      continue;
+    }
+    if (ch === "/" && input[i + 1] === "/") {
+      i += 2;
+      while (i < input.length && input[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && input[i + 1] === "*") {
+      i += 2;
+      while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    result += ch;
+    i++;
+  }
+  return result;
+}
+function parseJsonc(input) {
+  const withoutComments = stripJsonComments(input);
+  const withoutTrailingCommas = withoutComments.replace(/,\s*([}\]])/g, "$1");
+  return JSON.parse(withoutTrailingCommas);
+}
+
+// src/config/explorer.ts
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+function deepMerge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override;
+  }
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    result[key] = key in result ? deepMerge(result[key], override[key]) : override[key];
+  }
+  return result;
+}
+var defaultLoader = (content) => parseJsonc(content);
+function defaultSearchPlaces(name) {
+  return [
+    "package.json",
+    `.${name}rc`,
+    `.${name}rc.json`,
+    `${name}.config.json`
+  ];
+}
+var builtinLoaders = {
+  ".json": defaultLoader,
+  "noExt": defaultLoader
+};
+function resolveLoader(filepath, customLoaders) {
+  const ext = extname(filepath);
+  const key = ext || "noExt";
+  if (customLoaders?.[key]) return customLoaders[key];
+  if (builtinLoaders[key]) return builtinLoaders[key];
+  return defaultLoader;
+}
+function checkEmpty(value) {
+  if (value == null) return true;
+  if (typeof value === "object" && Object.keys(value).length === 0) return true;
+  return false;
+}
+async function loadFileInternal(fs, filepath, customLoaders, packageJsonProp) {
+  const content = await fs.readFile(filepath);
+  const loader = resolveLoader(filepath, customLoaders);
+  let config = loader(content, filepath);
+  if (basename(filepath) === "package.json" && packageJsonProp !== false) {
+    if (config != null && typeof config === "object" && packageJsonProp in config) {
+      config = config[packageJsonProp];
+    } else {
+      return null;
+    }
+  }
+  return {
+    config,
+    filepath,
+    isEmpty: checkEmpty(config)
+  };
+}
+async function collectAll(ctx, options) {
+  const {
+    name,
+    from = ctx.cwd,
+    searchPlaces = defaultSearchPlaces(name),
+    loaders: customLoaders,
+    packageJsonProp = name,
+    stopAt = "/",
+    stopWhen
+  } = options;
+  const results = [];
+  let dir = from;
+  while (true) {
+    for (const place of searchPlaces) {
+      const filepath = join(dir, place);
+      if (!await ctx.fs.exists(filepath)) continue;
+      try {
+        const result = await loadFileInternal(ctx.fs, filepath, customLoaders, packageJsonProp);
+        if (result !== null) {
+          results.push(result);
+          if (stopWhen?.(result.config)) return results;
+          break;
+        }
+      } catch {
+        continue;
+      }
+    }
+    if (dir === stopAt) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return results;
+}
+function mergeResults(results) {
+  if (results.length === 0) return null;
+  if (results.length === 1) return results[0];
+  const merged = results.reduceRight(
+    (acc, r) => deepMerge(acc, r.config),
+    {}
+  );
+  return {
+    config: merged,
+    filepath: results[0].filepath,
+    isEmpty: checkEmpty(merged)
+  };
+}
+async function searchConfig(ctx, options) {
+  if (options.merge) {
+    const results = await collectAll(ctx, options);
+    return mergeResults(results);
+  }
+  const {
+    name,
+    from = ctx.cwd,
+    searchPlaces = defaultSearchPlaces(name),
+    loaders: customLoaders,
+    packageJsonProp = name,
+    stopAt = "/"
+  } = options;
+  let dir = from;
+  while (true) {
+    for (const place of searchPlaces) {
+      const filepath = join(dir, place);
+      if (!await ctx.fs.exists(filepath)) continue;
+      try {
+        const result = await loadFileInternal(ctx.fs, filepath, customLoaders, packageJsonProp);
+        if (result !== null) return result;
+      } catch {
+        continue;
+      }
+    }
+    if (dir === stopAt) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+async function loadConfig(ctx, filepath, options) {
+  const {
+    loaders: customLoaders,
+    packageJsonProp = false
+  } = options ?? {};
+  return loadFileInternal(ctx.fs, filepath, customLoaders, packageJsonProp);
+}
+
+export {
+  findUp,
+  searchConfig,
+  loadConfig
+};