just-bash-util 0.1.4 → 0.1.5

package/README.md

@@ -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-35QZZQ4A.js → chunk-RNQNKFXA.js}

@@ -210,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++;
       }
@@ -268,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;
         }

package/dist/command/index.js

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

package/dist/index.js

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

package/package.json

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