just-bash-util 0.1.6 → 0.1.8

package/README.md

@@ -64,9 +64,10 @@ 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, counted flags (`-vvv` → 3)
-- `--` end-of-options separator (remaining tokens become positional args and are available via `meta.passthrough`)
+- `--` end-of-options separator (remaining tokens go to `meta.passthrough` without consuming positional args)
 - Environment variable fallbacks for options
 - Levenshtein-based "did you mean?" suggestions for typos
+- `transformArgs` callback to rewrite tokens before parsing — support non-standard shorthand syntax like `-5` → `-n 5`
 - Automatic error handling — thrown errors in handlers are caught and returned as clean `ExecResult` with `exitCode: 1`
 
 #### Options and flags
@@ -113,16 +114,43 @@ args: [
 
 #### 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`:
+The `--` token stops all parsing. Tokens after `--` go exclusively into `meta.passthrough` — they are **not** consumed as positional args or parsed as flags. Positional args must appear before `--`:
 
 ```ts
+// mycli checkout main -- README.md
+handler: (args, ctx, meta) => {
+  args.target;          // "main" (positional arg before --)
+  meta.passthrough;     // ["README.md"] (tokens after --)
+}
+
 // mycli checkout -- README.md
 handler: (args, ctx, meta) => {
-  args.target;          // "README.md" (assigned to positional arg)
-  meta.passthrough;     // ["README.md"] (raw tokens after --)
+  args.target;          // undefined (no positional before --)
+  meta.passthrough;     // ["README.md"]
 }
 ```
 
+#### Token rewriting with `transformArgs`
+
+Commands can define a `transformArgs` callback to rewrite the raw token array before it reaches the parser. This is useful for supporting non-standard shorthand syntax that the parser wouldn't otherwise understand:
+
+```ts
+cli.command("log", {
+  description: "Show commit log",
+  transformArgs: (tokens) =>
+    tokens.map((t) => (/^-(\d+)$/.test(t) ? `-n${t.slice(1)}` : t)),
+  options: {
+    maxCount: o.number().alias("n").describe("Limit output to n commits"),
+  },
+  handler: (args) => {
+    // git log -5  →  tokens rewritten to -n5  →  args.maxCount === 5
+    return { stdout: `showing ${args.maxCount} commits`, stderr: "", exitCode: 0 };
+  },
+});
+```
+
+The callback receives a mutable copy of the tokens and returns the rewritten array. It runs only in `execute()` (token-based invocation) — `invoke()` takes typed args directly, so there's nothing to transform.
+
 ### `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.

package/dist/{chunk-4J5EECVQ.js → chunk-4EGDYWA4.js}

@@ -217,7 +217,6 @@ function parseArgs(options, argDefs, tokens, env) {
     if (token === "--") {
       i++;
       while (i < tokens.length) {
-        positionals.push(tokens[i]);
         passthrough.push(tokens[i]);
         i++;
       }
@@ -550,10 +549,11 @@ var Command = class _Command {
   examples;
   omitInherited;
   handler;
+  transformArgs;
   children = /* @__PURE__ */ new Map();
   parent;
   /** @internal */
-  constructor(name, description, options, args, examples, omitInherited, handler) {
+  constructor(name, description, options, args, examples, omitInherited, handler, transformArgs) {
     this.name = name;
     this.description = description;
     this.options = options;
@@ -561,6 +561,7 @@ var Command = class _Command {
     this.examples = examples;
     this.omitInherited = omitInherited;
     this.handler = handler;
+    this.transformArgs = transformArgs;
   }
   // --------------------------------------------------------------------------
   // Tree building
@@ -575,7 +576,8 @@ var Command = class _Command {
       resolveArgsInput(config.args),
       config.examples ?? [],
       omitSet,
-      config.handler
+      config.handler,
+      config.transformArgs
     );
     child.parent = this;
     this.children.set(name, child);
@@ -763,7 +765,8 @@ var Command = class _Command {
       return { stdout: generateHelp(this), stderr: "", exitCode: 0 };
     }
     if (this.handler) {
-      const parsed = parseArgs(this.allOptions, this.args, [...tokens], env);
+      const effective = this.transformArgs ? this.transformArgs([...tokens]) : [...tokens];
+      const parsed = parseArgs(this.allOptions, this.args, effective, env);
       if (!parsed.ok) {
         return { stdout: "", stderr: formatErrors(parsed.errors), exitCode: 1 };
       }
@@ -797,7 +800,8 @@ function command(name, config) {
     resolveArgsInput(config.args),
     config.examples ?? [],
     /* @__PURE__ */ new Set(),
-    config.handler
+    config.handler,
+    config.transformArgs
   );
 }
 function hasHelpFlag(tokens) {

package/dist/command/index.d.ts

@@ -177,6 +177,7 @@ declare class Command<THandlerArgs extends object = {}, TInvokeArgs extends obje
     readonly examples: readonly string[];
     readonly omitInherited: ReadonlySet<string>;
     readonly handler?: Handler<any>;
+    readonly transformArgs?: (tokens: string[]) => string[];
     readonly children: Map<string, Command<any, any>>;
     parent?: Command<any, any>;
     /** @internal — phantom type carrying the resolved handler args */
@@ -184,7 +185,7 @@ declare class Command<THandlerArgs extends object = {}, TInvokeArgs extends obje
     /** @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);
+    constructor(name: string, description: string, options: OptionsSchema, args: ArgsSchema, examples: readonly string[], omitInherited: ReadonlySet<string>, handler: Handler<any> | undefined, transformArgs?: (tokens: string[]) => string[]);
     /** 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;
@@ -192,6 +193,7 @@ declare class Command<THandlerArgs extends object = {}, TInvokeArgs extends obje
         readonly args?: TArgs;
         readonly examples?: readonly string[];
         readonly omitInherited?: TOmit;
+        readonly transformArgs?: (tokens: string[]) => string[];
         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") */
@@ -258,6 +260,7 @@ declare function command<TOpts extends OptionsInput = {}, const TArgs extends Ar
     readonly options?: TOpts;
     readonly args?: TArgs;
     readonly examples?: readonly string[];
+    readonly transformArgs?: (tokens: string[]) => string[];
     readonly handler?: Handler<Prettify<InferOptionsFromInput<TOpts> & InferArgsFromInput<TArgs>>>;
 }): Command<Prettify<InferOptionsFromInput<TOpts> & InferArgsFromInput<TArgs>>, Prettify<InferInvokeOptions<TOpts> & InferInvokeArgs<TArgs>>>;
 /**

package/dist/command/index.js

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

package/dist/index.js

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

package/package.json

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