argsbarg 1.0.0 → 1.0.1

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,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +40,6 @@ 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.0.1...HEAD
+[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,4 +1,4 @@
-![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)
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "scripts": {
     "//just": "echo this app uses justfile for development tasks"

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}`,
       );