argsbarg 1.0.0 → 1.1.0

package/.cursor/rules/code.mdc

@@ -3,8 +3,7 @@ description: Code quality and style rules for TypeScript files
 globs: **/*.ts
 ---
 
-# TypeScript Coding Standards
-
+- Changes must be summarized in CHANGELOG.md under the UNRELEASED section
 - All imports must be ordered alphabetically by their source module path (the `from` clause).
 - Explicit exports using the `export { ... } from "..."` or `export type { ... } from "..."` syntax must be ordered alphabetically by their source module path and placed at the top of the file, immediately below the imports.
 - Types, Interfaces, Functions must have a docstring

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-04-23
+
+
+## [1.0.1] - 2026-04-22
+
+### Changed
+
+- **`CliPositional`** — `argMin` and `argMax` are optional. When omitted, they behave as `argMin: 1` and `argMax: 1` (one required word). Set `argMax: 0` for an unbounded varargs tail.
+- **Release** — `just release <major|minor|patch>` runs `just test` first, then `scripts/release.ts`, which no longer runs typecheck, lint, or tests itself. The release commit uses `git add -A` so all local changes in the repo are included, not only `package.json` and `CHANGELOG.md`.
+
 ## [1.0.0] - 2026-04-22
 
 ### Added
@@ -33,3 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.1.0
+[1.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.0.1
+[1.0.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v1.0.0

package/README.md

@@ -1,9 +1,9 @@
-![Logo](logo.png)
+![Logo](https://github.com/bdombro/bun-argsbarg/blob/main/logo.png)
 <!-- Big money NE - https://patorjk.com/software/taag/#p=testall&f=Bulbhead&t=shebangsy&x=none&v=4&h=4&w=80&we=false> -->
 
 [![GitHub](https://img.shields.io/badge/GitHub-bdombro%2Fbun--argsbarg-181717?logo=github)](https://github.com/bdombro/bun-argsbarg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![npm version](https://img.shields.io/npm/v/bun-argsbarg.svg)](https://www.npmjs.com/package/argsbarg)
+[![npm version](https://img.shields.io/npm/v/argsbarg.svg)](https://www.npmjs.com/package/argsbarg)
 [![Bun](https://img.shields.io/badge/Bun-%23000000.svg?logo=bun&logoColor=white)](https://bun.sh)
 
 Build beautiful, well-behaved CLI apps with Bun — **no third-party runtime dependencies**. 
@@ -17,13 +17,13 @@ Why another CLI parser?
 Also checkout ArgsBarg for [cpp](https://github.com/bdombro/cpp-argsbarg), [nim](https://github.com/bdombro/nim-argsbarg), and [swift](https://github.com/bdombro/swift-argsbarg)!
 
 Halps! -->
-![help-preview.png](docs/help-preview.png)
+![help-preview.png](https://github.com/bdombro/bun-argsbarg/blob/main/docs/help-preview.png)
 
 Sub-level Halps! -->
-![help-l2-preview.png](docs/help-l2-preview.png)
+![help-l2-preview.png](https://github.com/bdombro/bun-argsbarg/blob/main/docs/help-l2-preview.png)
 
 Shell completions! -->
-![completions-preview.png](docs/completions-preview.png)
+![completions-preview.png](https://github.com/bdombro/bun-argsbarg/blob/main/docs/completions-preview.png)
 
 
 ## Usage
@@ -140,7 +140,7 @@ Add `CliPositional` entries to the command’s `positionals` list (separate from
 
 | Fields | Label |
 | --- | --- |
-| default `argMin`/`argMax` (single-slot) | `<n>` |
+| omit `argMin` / `argMax` (defaults `1` / `1`, one required word) | `<n>` |
 | `argMin: 0`, `argMax: 1` | `[n]` |
 | `argMin: 0`, `argMax: 0` | `[n...]` |
 | `argMin: 1`, `argMax: 0` | `<n...>` |

package/examples/nested.ts

@@ -37,8 +37,6 @@ const cli: CliCommand = {
                   name: "path",
                   description: "File or directory.",
                   kind: CliOptionKind.String,
-                  argMin: 1,
-                  argMax: 1,
                 },
               ],
               handler: (ctx) => {
@@ -64,7 +62,6 @@ const cli: CliCommand = {
           name: "files",
           description: "Paths to read.",
           kind: CliOptionKind.String,
-          argMin: 1,
           argMax: 0,
         },
       ],

package/index.d.ts

@@ -0,0 +1,141 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * Option kinds: presence (boolean flag), string (free-form text), or number (strict double).
+ */
+export declare enum CliOptionKind {
+	/** Boolean flag: no value token (may be implicit `"1"` when set). */
+	Presence = "presence",
+	/** Free-form string value. */
+	String = "string",
+	/** Strict floating-point value (parsed at validation time). */
+	Number = "number"
+}
+/**
+ * When fallbackCommand is used for missing or unknown top-level tokens.
+ * Only the program root may set a non-default mode or a non-nil fallbackCommand.
+ */
+export declare enum CliFallbackMode {
+	/**
+	 * If argv has no first subcommand, route to `fallbackCommand`; if the first token is unknown, error.
+	 */
+	MissingOnly = "missingOnly",
+	/**
+	 * If argv has no first subcommand or the first token is not a known child, route to `fallbackCommand`.
+	 */
+	MissingOrUnknown = "missingOrUnknown",
+	/**
+	 * If the first token is present but not a known child, route to `fallbackCommand`.
+	 * When the first subcommand token is missing (empty argv), do not use fallback (implicit root help).
+	 */
+	UnknownOnly = "unknownOnly"
+}
+/**
+ * A named flag or value option (`--long`, `-short`), listed on `CliCommand.options`.
+ */
+export interface CliOption {
+	/** Option name (e.g., "name", "verbose"). */
+	name: string;
+	/** Description shown in help. */
+	description: string;
+	/** Option kind: presence flag, string value, or number value. */
+	kind: CliOptionKind;
+	/** Short option character (e.g., 'n' for -n). */
+	shortName?: string;
+}
+/**
+ * An ordered positional argument slot, listed on `CliCommand.positionals`.
+ */
+export interface CliPositional {
+	/** Positional name (used in help and error messages). */
+	name: string;
+	/** Description shown in help. */
+	description: string;
+	/** Value kind for each consumed token. */
+	kind: CliOptionKind;
+	/**
+	 * Minimum number of values required (default 1).
+	 * Use `0` for an optional slot when paired with `argMax: 1`, or a varargs tail with `argMax: 0`.
+	 */
+	argMin?: number;
+	/**
+	 * Maximum number of values (`1` = a single required or optional word; default 1). Use `0` for an
+	 * unbounded varargs tail (must be the last slot in the command’s `positionals` list).
+	 */
+	argMax?: number;
+}
+/**
+ * A command node: routing group (has commands) or leaf (has handler).
+ *
+ * The value passed to cliRun is the program root: name is the app/binary name,
+ * commands are top-level subcommands, options are global flags.
+ * The root must not set handler or declare positionals (validated at startup).
+ */
+export interface CliCommand {
+	/** Program or command key (e.g., "myapp", "stat", "owner"). */
+	key: string;
+	/** Short description shown in help. */
+	description: string;
+	/** Additional notes shown in help (supports {app} placeholder). */
+	notes?: string;
+	/** Global or command-level flags/options. */
+	options?: CliOption[];
+	/** Positional argument definitions. */
+	positionals?: CliPositional[];
+	/** Nested subcommands (empty for leaf commands). */
+	commands?: CliCommand[];
+	/** Handler function for leaf commands. */
+	handler?: CliHandler;
+	/** Default top-level subcommand when argv omits a command or uses an unknown first token (root only). */
+	fallbackCommand?: string;
+	/** How fallbackCommand is applied (root only). */
+	fallbackMode?: CliFallbackMode;
+}
+/**
+ * Handler closure type for leaf commands.
+ * Supports both sync and async handlers.
+ */
+export type CliHandler = (ctx: CliContext) => void | Promise<void>;
+/**
+ * Error thrown when the static CliCommand tree violates ArgsBarg rules.
+ */
+export declare class CliSchemaValidationError extends Error {
+	/** Creates a schema validation error with a human-readable rule violation. */
+	constructor(message: string);
+}
+/**
+ * Values passed to a leaf command handler after parsing: app name, routed path, args, and merged options.
+ */
+export declare class CliContext {
+	readonly appName: string;
+	readonly commandPath: string[];
+	readonly args: string[];
+	readonly schema: CliCommand;
+	readonly opts: Record<string, string>;
+	/** Captures the merged program root, routed path, positional words, and option map for a leaf handler. */
+	constructor(appName: string, commandPath: string[], args: string[], opts: Record<string, string>, schema: CliCommand);
+	/** Returns whether a presence flag was set (including implicit "1" for boolean options). */
+	hasFlag(name: string): boolean;
+	/** Returns the string value for a string-valued option, if present. */
+	stringOpt(name: string): string | undefined;
+	/** Parses a stored string as a number; returns null if missing or not a strict double string. */
+	numberOpt(name: string): number | null;
+	/**
+	 * Generic typed accessor: parses a stored string using the provided parse function.
+	 * This is the TypeScript-native advantage over the Swift version.
+	 */
+	typedOpt<T>(name: string, parse: (s: string) => T): T | null;
+}
+/**
+ * Validates the schema, parses argv, prints help or errors, runs completion or the leaf handler, then exits.
+ *
+ * @param root The root CliCommand.
+ * @param argv Override the default argv (process.argv.slice(2)).
+ */
+export declare function cliRun(root: CliCommand, argv?: string[]): Promise<never>;
+/**
+ * Prints a red error line and contextual help on stderr, then exits with status 1.
+ */
+export declare function cliErrWithHelp(ctx: CliContext, msg: string): never;
+
+export {};

package/justfile

@@ -27,6 +27,10 @@ lint:
 test: check-types format lint
     bun test
 
+# generate type declarations for the package
+typegen:
+    bunx dts-bundle-generator --out-file index.d.ts src/index.ts
+
 # publish to github and npm
-release bump: test
+release bump: test typegen
     bun scripts/release.ts {{bump}}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "argsbarg",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"
   },
   "main": "./src/index.ts",
   "module": "./src/index.ts",
-  "types": "./src/index.ts",
+  "types": "./index.d.ts",
   "bin": {
     "argsbarg": "src/index.ts"
   },

package/scripts/release.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 /**
- * Release workflow: bump semver; update CHANGELOG; commit, tag, push, GitHub release, npm publish.
+ * Release workflow: bump semver; update CHANGELOG (trailing release reference links); commit, tag, push,
+ * GitHub release, npm publish.
  *
  * **Run `just test` (or the individual `just check-types`, `just lint`, `bun test`) before this
  * script** — it does not typecheck, lint, or run tests. The `just release` recipe runs checks first.
@@ -65,6 +66,94 @@ function bumpSemver(version: string, part: Bump): string {
   return `${major}.${minor}.${patch}`;
 }
 
+/** Returns stdout from a successful subprocess, trimmed; throws if the command fails. */
+function runCapture(cmd: string[], cwd: string = repoRoot): string {
+  const proc = Bun.spawnSync({ cmd, cwd, stdout: "pipe", stderr: "pipe" });
+  if (proc.exitCode !== 0) {
+    const err = new TextDecoder().decode(proc.stderr);
+    throw new Error(`Command failed: ${cmd.join(" ")}\n${err}`);
+  }
+  return new TextDecoder().decode(proc.stdout).trimEnd();
+}
+
+/** Parses `git remote get-url origin` into `https://github.com/owner/repo`, or null if not GitHub. */
+function githubRepoBaseFromOrigin(origin: string): string | null {
+  const trimmed = origin.trim();
+  let path = trimmed.replace(/^git@[^:]+:/, "").replace(/^https?:\/\/[^/]+\//, "");
+  if (path.endsWith(".git")) {
+    path = path.slice(0, -4);
+  }
+  if (!/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/.test(path)) {
+    return null;
+  }
+  return `https://github.com/${path}`;
+}
+
+/**
+ * Collects released semver headings from changelog body in document order (newest first when
+ * headings follow Keep a Changelog order after each release).
+ */
+function releasedSemverVersionsFromChangelog(md: string): string[] {
+  const re = /^## \[(\d+\.\d+\.\d+)\] /gm;
+  const out: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(md)) !== null) {
+    out.push(m[1]!);
+  }
+  return out;
+}
+
+/**
+ * Strips optional legacy `## Links` heading and/or trailing Keep-a-Changelog reference link lines
+ * (`[...]: http...`) at the end of the file.
+ */
+function stripChangelogLinkDefinitions(md: string): string {
+  let s = md.replace(/\r?\n## Links\r?\n/, "\n");
+  const lines = s.split(/\r?\n/);
+  let i = lines.length;
+  while (i > 0 && lines[i - 1] === "") {
+    i -= 1;
+  }
+  const refLine = /^\[[^\]]+\]: .+$/;
+  while (i > 0 && refLine.test(lines[i - 1]!)) {
+    i -= 1;
+  }
+  while (i > 0 && lines[i - 1] === "") {
+    i -= 1;
+  }
+  if (i > 0 && lines[i - 1] === "## Links") {
+    i -= 1;
+  }
+  while (i > 0 && lines[i - 1] === "") {
+    i -= 1;
+  }
+  if (i === 0) {
+    return "";
+  }
+  return lines.slice(0, i).join("\n");
+}
+
+/**
+ * Appends reference link definitions (no visible heading): `[Unreleased]` → compare latest tag to `HEAD`,
+ * and each released `[x.y.z]` → release tag URL.
+ */
+function appendChangelogLinkDefinitions(md: string, repoBase: string): string {
+  const body = stripChangelogLinkDefinitions(md).trimEnd();
+  const versions = releasedSemverVersionsFromChangelog(body);
+  if (versions.length === 0) {
+    return `${body}\n`;
+  }
+  const newest = versions[0]!;
+  const lines = [
+    "",
+    "",
+    `[Unreleased]: ${repoBase}/compare/v${newest}...HEAD`,
+    ...versions.map((v) => `[${v}]: ${repoBase}/releases/tag/v${v}`),
+    "",
+  ];
+  return `${body}${lines.join("\n")}`;
+}
+
 /** Runs a subprocess, inheriting stdio, and exits the process on non-zero status. */
 function run(label: string, cmd: string[], cwd: string = repoRoot): void {
   console.log(`\n→ ${label}: ${cmd.join(" ")}`);
@@ -129,7 +218,13 @@ await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 
 const changelogPath = joinFile(repoRoot, "CHANGELOG.md");
 const changelog = await Bun.file(changelogPath).text();
-const nextChangelog = promoteChangelog(changelog, nextVersion, releaseDate);
+const promoted = promoteChangelog(changelog, nextVersion, releaseDate);
+const origin = runCapture(["git", "remote", "get-url", "origin"], repoRoot);
+const repoBase = githubRepoBaseFromOrigin(origin);
+if (repoBase === null) {
+  throw new Error(`Could not parse GitHub repo URL from origin: ${JSON.stringify(origin)}`);
+}
+const nextChangelog = appendChangelogLinkDefinitions(promoted, repoBase);
 await Bun.write(changelogPath, nextChangelog);
 
 const notesPath = joinFile(repoRoot, ".release-notes.tmp.md");

package/src/help.ts

@@ -177,11 +177,12 @@ export function cliOptionLabel(o: CliOption, color: boolean): string {
 
 /** Formats a positional slot label (`<n>`, `[n]`, or varargs) for help. */
 export function cliPositionalLabel(p: CliPositional, color: boolean): string {
+  const { argMin = 1, argMax = 1 } = p;
   let r: string;
-  if (p.argMax === 1) {
-    r = p.argMin === 0 ? "[" + p.name + "]" : "<" + p.name + ">";
+  if (argMax === 1) {
+    r = argMin === 0 ? "[" + p.name + "]" : "<" + p.name + ">";
   } else {
-    r = p.argMin === 0 ? "[" + p.name + "...]" : "<" + p.name + "...>";
+    r = argMin === 0 ? "[" + p.name + "...]" : "<" + p.name + "...>";
   }
   if (!color) return r;
   return style.aquaBold(r);

package/src/parse.ts

@@ -10,9 +10,9 @@ across every entry path.
 import { CliContext } from "./context.ts";
 import {
   CliCommand,
+  CliFallbackMode,
   CliOption,
   CliOptionKind,
-  CliFallbackMode,
 } from "./types.ts";
 import { fullStringIsDouble } from "./utils.ts";
 
@@ -234,8 +234,9 @@ function finishLeaf(
   const args: string[] = [];
 
   for (const p of node.positionals ?? []) {
-    if (p.argMax === 1) {
-      if (p.argMin >= 1) {
+    const { argMin = 1, argMax = 1 } = p;
+    if (argMax === 1) {
+      if (argMin >= 1) {
         if (idx >= argv.length) {
           return errorResult(`Missing positional argument: ${p.name}`);
         }
@@ -249,21 +250,21 @@ function finishLeaf(
     }
 
     let count = 0;
-    if (p.argMax === 0) {
+    if (argMax === 0) {
       while (idx < argv.length) {
         args.push(argv[idx]);
         idx += 1;
         count += 1;
       }
     } else {
-      while (count < p.argMax && idx < argv.length) {
+      while (count < argMax && idx < argv.length) {
         args.push(argv[idx]);
         idx += 1;
         count += 1;
       }
     }
-    if (count < p.argMin) {
-      return errorResult(`Expected at least ${p.argMin} argument(s) for ${p.name}, got ${count}`);
+    if (count < argMin) {
+      return errorResult(`Expected at least ${argMin} argument(s) for ${p.name}, got ${count}`);
     }
   }
 

package/src/types.ts

@@ -64,10 +64,16 @@ export interface CliPositional {
   description: string;
   /** Value kind for each consumed token. */
   kind: CliOptionKind;
-  /** Minimum number of values required. */
-  argMin: number;
-  /** Maximum number of values (0 = unlimited, for a varargs tail). */
-  argMax: number;
+  /**
+   * Minimum number of values required (default 1).
+   * Use `0` for an optional slot when paired with `argMax: 1`, or a varargs tail with `argMax: 0`.
+   */
+  argMin?: number;
+  /**
+   * Maximum number of values (`1` = a single required or optional word; default 1). Use `0` for an
+   * unbounded varargs tail (must be the last slot in the command’s `positionals` list).
+   */
+  argMax?: number;
 }
 
 /**

package/src/validate.ts

@@ -96,15 +96,16 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
   // Validate positionals
   const positionals = cmd.positionals ?? [];
   for (const p of positionals) {
-    if (p.argMin < 0) {
+    if (p.argMin !== undefined && p.argMin < 0) {
       throw new CliSchemaValidationError(`argMin must be >= 0 for positional ${cmd.key}/${p.name}`);
     }
-    if (p.argMax < 0) {
+    if (p.argMax !== undefined && p.argMax < 0) {
       throw new CliSchemaValidationError(
         `argMax must be >= 0 (use 0 for unlimited) for positional ${cmd.key}/${p.name}`,
       );
     }
-    if (p.argMax > 0 && p.argMin > p.argMax) {
+    const { argMin = 1, argMax = 1 } = p;
+    if (argMax > 0 && argMin > argMax) {
       throw new CliSchemaValidationError(
         `argMin must not exceed argMax for positional ${cmd.key}/${p.name}`,
       );
@@ -114,7 +115,8 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
   // Check positional ordering: required before optional
   let sawOptional = false;
   for (const p of positionals) {
-    if (p.argMin === 0) {
+    const { argMin = 1 } = p;
+    if (argMin === 0) {
       sawOptional = true;
     } else if (sawOptional) {
       throw new CliSchemaValidationError(`Required positional after optional in scope ${cmd.key}`);
@@ -123,7 +125,8 @@ function walkCommand(cmd: CliCommand, isRoot: boolean = false): void {
 
   // Check unlimited positional must be last
   for (let idx = 0; idx < positionals.length; idx++) {
-    if (positionals[idx].argMax === 0 && idx + 1 < positionals.length) {
+    const { argMax = 1 } = positionals[idx]!;
+    if (argMax === 0 && idx + 1 < positionals.length) {
       throw new CliSchemaValidationError(
         `Unlimited positional (argMax == 0) must be last in scope ${cmd.key}`,
       );