just-bash-util 0.1.3 → 0.1.5

package/README.md

@@ -28,9 +28,9 @@ const cli = command("mycli", {
 const serve = cli.command("serve", {
   description: "Start the dev server",
   options: {
-    port: o.number().default(3000).short("p").describe("Port to listen on"),
+    port: o.number().default(3000).alias("p").describe("Port to listen on"),
     host: o.string().describe("Host to bind to"),
-    open: f().short("o").describe("Open browser"),
+    open: f().alias("o").describe("Open browser"),
   },
   args: [a.string().name("entry").describe("Entry file")],
   handler: (args, ctx) => {
@@ -64,11 +64,55 @@ await serve.invoke({ port: 8080, entry: "app.ts" }, ctx);
 - `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
+- `--` end-of-options separator (remaining tokens become positional args and are available via `meta.passthrough`)
 - 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`
 
+#### Options and flags
+
+Option keys are written in camelCase and automatically converted to kebab-case for the CLI:
+
+```ts
+options: {
+  allowEmpty: f(),           // CLI: --allow-empty    handler: args.allowEmpty
+  dryRun: f().alias("n"),    // CLI: --dry-run / -n   handler: args.dryRun
+  message: o.string().alias("m"), // CLI: --message / -m  handler: args.message
+}
+```
+
+Short flags (single-dash, single-character) require `.alias()`. A single-character key like `b: f()` creates the long flag `--b`, **not** the short flag `-b`. To get `-b`, use a descriptive key with an alias:
+
+```ts
+// ✗ b: f()                    → creates --b (long flag), not -b
+// ✓ branch: f().alias("b")   → creates --branch and -b
+```
+
+#### Positional args
+
+Args are required by default. Use `.optional()` for optional args, and `.variadic()` to collect remaining positionals into an array. Chain `.optional().variadic()` for zero-or-more:
+
+```ts
+args: [
+  a.string().name("entry"),                         // required single arg
+  a.string().name("file").optional(),               // optional single arg
+  a.string().name("files").variadic(),              // required: one or more
+  a.string().name("paths").optional().variadic(),   // optional: zero or more → string[]
+]
+```
+
+#### The `--` separator
+
+The `--` token signals end-of-options. Tokens after `--` are treated as positional arguments (not parsed as flags) and are also available in `meta.passthrough`:
+
+```ts
+// mycli checkout -- README.md
+handler: (args, ctx, meta) => {
+  args.target;          // "README.md" (assigned to positional arg)
+  meta.passthrough;     // ["README.md"] (raw tokens after --)
+}
+```
+
 ### `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.
@@ -142,6 +186,15 @@ parsePackageSpecifier("@vue/shared/dist"); // { name: "@vue/shared", subpath: ".
 parsePackageSpecifier("lodash/merge"); // { name: "lodash", subpath: "./merge" }
 ```
 
+**`join` vs `resolve`** — `join` concatenates segments and normalizes; an absolute second argument is kept as-is (appended, not replacing). `resolve` processes right-to-left and stops at the first absolute path, like Node's `path.resolve` (but without prepending `cwd` when no absolute segment exists):
+
+```ts
+join("/repo", "/file.txt");    // "/repo/file.txt" — concatenates with /
+resolve("/repo", "/file.txt"); // "/file.txt"      — absolute segment wins
+resolve("/repo", "file.txt");  // "/repo/file.txt"
+resolve("a", "b");             // "a/b"            — stays relative (no cwd)
+```
+
 ## Peer dependencies
 
 Requires [`just-bash`](https://www.npmjs.com/package/just-bash) ^2.9.6 — provides the `CommandContext` and `ExecResult` types used throughout.

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

@@ -9,9 +9,9 @@ var OptionBuilder = class _OptionBuilder {
   describe(text) {
     return new _OptionBuilder({ ...this._def, description: text });
   }
-  /** Set a short alias (single character) */
-  short(alias) {
-    return new _OptionBuilder({ ...this._def, short: alias });
+  /** Set a short alias (single character, e.g. "p" for -p) */
+  alias(short) {
+    return new _OptionBuilder({ ...this._def, short });
   }
   /** Set an environment variable fallback */
   env(name) {
@@ -56,9 +56,9 @@ var FlagBuilder = class _FlagBuilder {
   describe(text) {
     return new _FlagBuilder({ ...this._def, description: text });
   }
-  /** Set a short alias (single character) */
-  short(alias) {
-    return new _FlagBuilder({ ...this._def, short: alias });
+  /** Set a short alias (single character, e.g. "v" for -v) */
+  alias(short) {
+    return new _FlagBuilder({ ...this._def, short });
   }
   /** Set a default value */
   default(value) {
@@ -91,7 +91,9 @@ var ArgBuilder = class _ArgBuilder {
       required: false
     });
   }
-  /** Mark as variadic — collects all remaining positionals into an array */
+  /** Mark as variadic — collects all remaining positionals into an array.
+   *  If the arg is already optional, element-level undefined is stripped
+   *  (the optionality means "zero or more", not "elements can be undefined"). */
   variadic() {
     return new _ArgBuilder({
       ...this._def,
@@ -208,6 +210,7 @@ function parseArgs(options, argDefs, tokens, env) {
     if (token === "--") {
       i++;
       while (i < tokens.length) {
+        positionals.push(tokens[i]);
         passthrough.push(tokens[i]);
         i++;
       }
@@ -266,10 +269,14 @@ function parseArgs(options, argDefs, tokens, env) {
         const ch = chars[j];
         const entry = shortMap.get(ch);
         if (!entry) {
+          const suggestions = [];
+          if (longMap.has(ch)) {
+            suggestions.push(`--${ch}`);
+          }
           errors.push({
             type: "unknown_option",
             name: `-${ch}`,
-            suggestions: []
+            suggestions
           });
           continue;
         }
@@ -307,6 +314,8 @@ function parseArgs(options, argDefs, tokens, env) {
         errors.push({ type: "missing_required", name: argName, kind: "arg" });
       } else if (argDef.default !== void 0) {
         result[argName] = argDef.default;
+      } else {
+        result[argName] = [];
       }
       posIdx = positionals.length;
     } else {
@@ -527,12 +536,8 @@ var Command = class _Command {
   handler;
   children = /* @__PURE__ */ new Map();
   parent;
-  /** @internal — accumulated builder types for generic inference */
-  _accOpts;
-  /** @internal — args builder types for generic inference */
-  _accArgs;
   /** @internal */
-  constructor(name, description, options, args, examples, omitInherited, handler, accOpts, accArgs) {
+  constructor(name, description, options, args, examples, omitInherited, handler) {
     this.name = name;
     this.description = description;
     this.options = options;
@@ -540,8 +545,6 @@ var Command = class _Command {
     this.examples = examples;
     this.omitInherited = omitInherited;
     this.handler = handler;
-    this._accOpts = accOpts;
-    this._accArgs = accArgs;
   }
   // --------------------------------------------------------------------------
   // Tree building
@@ -549,9 +552,6 @@ var Command = class _Command {
   /** Add a subcommand. Returns the child command for further nesting. */
   command(name, config) {
     const omitSet = new Set(config.omitInherited ?? []);
-    const parentAcc = { ...this._accOpts };
-    for (const key of omitSet) delete parentAcc[key];
-    const accOpts = { ...parentAcc, ...config.options ?? {} };
     const child = new _Command(
       name,
       config.description,
@@ -559,9 +559,7 @@ var Command = class _Command {
       resolveArgsInput(config.args),
       config.examples ?? [],
       omitSet,
-      config.handler,
-      accOpts,
-      config.args ?? []
+      config.handler
     );
     child.parent = this;
     this.children.set(name, child);
@@ -781,9 +779,7 @@ function command(name, config) {
     resolveArgsInput(config.args),
     config.examples ?? [],
     /* @__PURE__ */ new Set(),
-    config.handler,
-    config.options ?? {},
-    config.args ?? []
+    config.handler
   );
 }
 function hasHelpFlag(tokens) {

package/dist/command/index.d.ts

@@ -74,8 +74,8 @@ declare class OptionBuilder<TOut, THasDefault extends boolean = false> {
     constructor(def: OptionDef<TOut>);
     /** Add a description */
     describe(text: string): OptionBuilder<TOut, THasDefault>;
-    /** Set a short alias (single character) */
-    short(alias: string): OptionBuilder<TOut, THasDefault>;
+    /** Set a short alias (single character, e.g. "p" for -p) */
+    alias(short: string): OptionBuilder<TOut, THasDefault>;
     /** Set an environment variable fallback */
     env(name: string): OptionBuilder<TOut, THasDefault>;
     /** Mark as required — removes undefined from TOut */
@@ -94,8 +94,8 @@ declare class FlagBuilder {
     constructor(def?: FlagDef);
     /** Add a description */
     describe(text: string): FlagBuilder;
-    /** Set a short alias (single character) */
-    short(alias: string): FlagBuilder;
+    /** Set a short alias (single character, e.g. "v" for -v) */
+    alias(short: string): FlagBuilder;
     /** Set a default value */
     default(value: boolean): FlagBuilder;
 }
@@ -110,8 +110,10 @@ declare class ArgBuilder<TOut, TName extends string = never, THasDefault extends
     describe(text: string): ArgBuilder<TOut, TName, THasDefault>;
     /** Mark as optional — adds undefined to TOut */
     optional(): ArgBuilder<TOut | undefined, TName, THasDefault>;
-    /** Mark as variadic — collects all remaining positionals into an array */
-    variadic(): ArgBuilder<TOut[], TName, THasDefault>;
+    /** Mark as variadic — collects all remaining positionals into an array.
+     *  If the arg is already optional, element-level undefined is stripped
+     *  (the optionality means "zero or more", not "elements can be undefined"). */
+    variadic(): ArgBuilder<NonNullable<TOut>[], TName, THasDefault>;
     /** Set a default value (also makes the arg optional at parse time) */
     default(value: TOut): ArgBuilder<TOut, TName, true>;
 }
@@ -161,7 +163,7 @@ type InferInvokeArgs<T extends ArgsInput> = {
 } & {
     [I in keyof T & `${number}` as T[I] extends ArgBuilder<infer _V, infer N extends string, infer D> ? [D] extends [true] ? N : T[I] extends ArgBuilder<infer V, any, any> ? undefined extends V ? N : never : never : never]?: T[I] extends ArgBuilder<infer V, any, any> ? V : never;
 };
-declare class Command<TAccOpts extends OptionsInput = {}, TAccArgs extends ArgsInput = []> {
+declare class Command<THandlerArgs extends object = {}, TInvokeArgs extends object = {}> {
     readonly name: string;
     readonly description: string;
     readonly options: OptionsSchema;
@@ -171,12 +173,12 @@ declare class Command<TAccOpts extends OptionsInput = {}, TAccArgs extends ArgsI
     readonly handler?: Handler<any>;
     readonly children: Map<string, Command<any, any>>;
     parent?: Command<any, any>;
-    /** @internal — accumulated builder types for generic inference */
-    readonly _accOpts: TAccOpts;
-    /** @internal — args builder types for generic inference */
-    readonly _accArgs: TAccArgs;
+    /** @internal — phantom type carrying the resolved handler args */
+    readonly _handlerArgs: THandlerArgs;
+    /** @internal — phantom type carrying the resolved invoke args */
+    readonly _invokeArgs: TInvokeArgs;
     /** @internal */
-    constructor(name: string, description: string, options: OptionsSchema, args: ArgsSchema, examples: readonly string[], omitInherited: ReadonlySet<string>, handler: Handler<any> | undefined, accOpts: TAccOpts, accArgs: TAccArgs);
+    constructor(name: string, description: string, options: OptionsSchema, args: ArgsSchema, examples: readonly string[], omitInherited: ReadonlySet<string>, handler: Handler<any> | undefined);
     /** Add a subcommand. Returns the child command for further nesting. */
     command<TOpts extends OptionsInput = {}, const TArgs extends ArgsInput = [], const TOmit extends string[] = []>(name: string, config: {
         readonly description: string;
@@ -184,8 +186,8 @@ declare class Command<TAccOpts extends OptionsInput = {}, TAccArgs extends ArgsI
         readonly args?: TArgs;
         readonly examples?: readonly string[];
         readonly omitInherited?: TOmit;
-        readonly handler?: Handler<Prettify<Omit<InferOptionsFromInput<TAccOpts>, TOmit[number]> & InferOptionsFromInput<TOpts> & InferArgsFromInput<TArgs>>>;
-    }): Command<Omit<TAccOpts, TOmit[number]> & TOpts, TArgs>;
+        readonly handler?: Handler<Prettify<Omit<THandlerArgs, TOmit[number]> & InferOptionsFromInput<TOpts> & InferArgsFromInput<TArgs>>>;
+    }): Command<Prettify<Omit<THandlerArgs, TOmit[number]> & InferOptionsFromInput<TOpts> & InferArgsFromInput<TArgs>>, Prettify<Omit<TInvokeArgs, TOmit[number]> & InferInvokeOptions<TOpts> & InferInvokeArgs<TArgs>>>;
     /** Full path from root (e.g. "mycli db migrate") */
     get fullPath(): string;
     /**
@@ -221,7 +223,7 @@ declare class Command<TAccOpts extends OptionsInput = {}, TAccArgs extends ArgsI
      * await cli.execute(["serve", ...tokens], ctx);
      * ```
      */
-    toTokens(args: Partial<Prettify<InferOptionsFromInput<TAccOpts> & InferArgsFromInput<TAccArgs>>>): string[];
+    toTokens(args: Partial<THandlerArgs>): string[];
     /**
      * Call this command's handler directly with typed args.
      *
@@ -234,7 +236,7 @@ declare class Command<TAccOpts extends OptionsInput = {}, TAccArgs extends ArgsI
      * const result = await serve.invoke({ port: 8080, entry: "app.ts" }, ctx);
      * ```
      */
-    invoke(args: Prettify<InferInvokeOptions<TAccOpts> & InferInvokeArgs<TAccArgs>>, ctx: CommandContext): Promise<ExecResult>;
+    invoke(args: TInvokeArgs, ctx: CommandContext): Promise<ExecResult>;
     /**
      * Execute this command tree with the given tokens.
      *
@@ -251,7 +253,7 @@ declare function command<TOpts extends OptionsInput = {}, const TArgs extends Ar
     readonly args?: TArgs;
     readonly examples?: readonly string[];
     readonly handler?: Handler<Prettify<InferOptionsFromInput<TOpts> & InferArgsFromInput<TArgs>>>;
-}): Command<TOpts, TArgs>;
+}): Command<Prettify<InferOptionsFromInput<TOpts> & InferArgsFromInput<TArgs>>, Prettify<InferInvokeOptions<TOpts> & InferInvokeArgs<TArgs>>>;
 /**
  * Infer the handler args type from a Command instance.
  *
@@ -270,7 +272,7 @@ declare function command<TOpts extends OptionsInput = {}, const TArgs extends Ar
  * //   ^? { port: number; entry: string }
  * ```
  */
-type Infer<T extends Command<any, any>> = Prettify<InferOptionsFromInput<T["_accOpts"]> & InferArgsFromInput<T["_accArgs"]>>;
+type Infer<T extends Command<any, any>> = T["_handlerArgs"];
 
 type ParseArgsResult = {
     ok: true;

package/dist/command/index.js

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

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   generateHelp,
   o,
   parseArgs
-} from "./chunk-QKL3AOEA.js";
+} from "./chunk-RNQNKFXA.js";
 import {
   findUp,
   loadConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "just-bash-util",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "CLI command framework, config file discovery, and path utilities for just-bash",
   "type": "module",
   "license": "MIT",