argsbarg 0.1.0 → 1.0.0

package/.cursor/rules/code.mdc

@@ -7,3 +7,4 @@ globs: **/*.ts
 
 - 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

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-04-22
+
+### Added
+
+- `scripts/release.ts` — release automation (`just release <major|minor|patch>`): lint, typecheck, tests, semver bump, CHANGELOG promotion, commit, tag, push, GitHub release, npm publish.
+- `CliPositional` type for entries in `CliCommand.positionals` (name, description, kind, argMin, argMax).
+- `cliPositionalLabel()` for help-style labels of positional slots (exported alongside `cliOptionLabel()`).
+
+### Changed
+
+- **`CliCommand.children` → `CliCommand.commands`** — nested subcommands are declared under `commands` everywhere (schema, parser, validation, help, completion, runtime).
+- **Development tasks** — former `package.json` scripts live in the repo `justfile` (e.g. `just test`, `just lint`). `package.json` no longer defines a `scripts` block.
+- **Public barrel (`src/index.ts`)** — re-exports are limited to schema types and enums, `CliSchemaValidationError`, `CliContext`, `cliRun`, and `cliErrWithHelp`. Parsing (`parse`, `postParseValidate`, …), completion script helpers, help renderers, `cliValidateRoot`, and `utils` number helpers are no longer re-exported from the package entry (import from `src/*.ts` paths in this repo, or depend on internal modules if you fork).
+
+### Removed
+
+- **`createOption()`** — options and positionals are plain object literals; there is no factory helper.
+- **`CliOptionDef`** — replaced by distinct types (see below).
+
+### Breaking
+
+- **`CliOption`** is only for named flags and value options (`options`). It no longer includes `positional`, `argMin`, or `argMax`. Use **`CliPositional`** on `positionals` for ordered arguments and varargs tails.
+- **`CliCommand.positionals`** is now `CliPositional[]`, not `CliOption[]`.
+- 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.
+

package/README.md

@@ -29,23 +29,28 @@ Shell completions! -->
 ## Usage
 
 ```typescript
-import { cliRun, CliCommand, createOption, CliOptionKind, CliFallbackMode } from "argsbarg";
+import { cliRun, CliCommand, CliOptionKind, CliFallbackMode } from "argsbarg";
 
 const cli: CliCommand = {
   key: "helloapp",
   description: "Tiny demo.",
-  children: [
+  commands: [
     {
       key: "hello",
       description: "Say hello.",
       options: [
-        createOption("name", "Who to greet.", {
+        {
+          name: "name",
+          description: "Who to greet.",
           kind: CliOptionKind.String,
           shortName: "n",
-        }),
-        createOption("verbose", "Enable extra logging.", {
+        },
+        {
+          name: "verbose",
+          description: "Enable extra logging.",
+          kind: CliOptionKind.Presence,
           shortName: "v",
-        }),
+        },
       ],
       handler: async (ctx) => {
         const name = ctx.stringOpt("name") ?? "world";
@@ -71,10 +76,10 @@ await cliRun(cli);
 
 Everything you need for a first-class CLI:
 
-- **Nested subcommands** (`CliCommand` with `children` for groups, `handler` for leaves)
+- **Nested subcommands** (`CliCommand` with `commands` for groups, `handler` for leaves)
 - **POSIX-style options** (`-x`, `--long`, `--long=value`)
 - **Bundled presence flags** (`-abc`)
-- **Positional arguments and varargs tails** (`CliOptionDef` with `positional: true`)
+- **Positional arguments and varargs tails** (`CliPositional` objects on `positionals`)
 - **Scoped help** at any routing depth (`-h` / `--help`)
 - **Default-command fallback** (`CliFallbackMode`)
 - **Option separator** (`--` to stop option parsing)
@@ -115,7 +120,7 @@ bun add bun-argsbarg
 
 ## How it works
 
-1. Build a **program root** `CliCommand` using pure TypeScript objects: `key` is the app/binary name, `children` are top-level subcommands, `options` are global flags. The root must not set `handler` or declare `positionals` (validated at startup). Use `fallbackCommand` / `fallbackMode` on the root only for default top-level routing.
+1. Build a **program root** `CliCommand` using pure TypeScript objects: `key` 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). Use `fallbackCommand` / `fallbackMode` on the root only for default top-level routing.
 2. Call `await cliRun(root)` with that root — validates, parses argv, renders help or errors, invokes the leaf handler, and `process.exit`s with status **0** on success, **1** on implicit help or error (explicit `--help` → **0**).
 3. From a handler, `cliErrWithHelp(ctx, "message")` prints a red error line plus contextual help on stderr and exits **1**.
 
@@ -131,14 +136,14 @@ With `MissingOrUnknown` / `UnknownOnly`, unrecognized **root** flags stop root-f
 
 ### Positionals (help labels)
 
-Use `createOption` with `positional: true`. With `argMax: 0`, the tail accepts at least `argMin` tokens and has no upper bound unless you set `argMax` > 0.
+Add `CliPositional` entries to the command’s `positionals` list (separate from `CliOption` flags). With `argMax: 0`, the tail accepts at least `argMin` tokens and has no upper bound unless you set `argMax` > 0.
 
 | Fields | Label |
 | --- | --- |
-| `positional: true`, default `argMin`/`argMax` | `<n>` |
-| `positional: true`, `argMin: 0`, `argMax: 1` | `[n]` |
-| `positional: true`, `argMin: 0`, `argMax: 0` | `[n...]` |
-| `positional: true`, `argMin: 1`, `argMax: 0` | `<n...>` |
+| default `argMin`/`argMax` (single-slot) | `<n>` |
+| `argMin: 0`, `argMax: 1` | `[n]` |
+| `argMin: 0`, `argMax: 0` | `[n...]` |
+| `argMin: 1`, `argMax: 0` | `<n...>` |
 
 ### Reading values (`CliContext`)
 
@@ -160,24 +165,31 @@ Check the `examples/` directory for full working scripts:
 | `ArgsBargNested` | `examples/nested.ts` | Nested `CliCommand` tree, positional tails, async handlers. |
 
 ```bash
-bun examples/minimal.ts --help
-bun examples/minimal.ts hello --name world
-bun examples/nested.ts stat owner lookup -u alice ./README.md
-bun examples/nested.ts read ./README.md
+export PATH="$PATH:$(pwd)/examples"
+
+eval "$(minimal.ts completion zsh)"
+minimal.ts --help
+minimal.ts hello --name world
+
+eval "$(nested.ts completion zsh)"
+nested.ts stat owner lookup -u alice ./README.md
+nested.ts read ./README.md
 ```
 
 
 
 ## Public API overview
 
+The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you need to define a schema and run it. Parsing, completion script generation, help rendering, and schema pre-validation live in other modules under `src/` for tests and advanced integrations.
+
 | Symbol | Role |
 | --- | --- |
-| `CliCommand`, `CliOptionDef`, `CliOptionKind`, `CliFallbackMode` | Schema types. |
-| `createOption()` | Factory helper for options with sensible defaults. |
-| `CliContext`, `CliHandler` | Handler context and async-compatible closure type. |
-| `cliRun(root, [argv])` | Parse argv, dispatch, exit. |
-| `cliErrWithHelp(ctx, msg)` | Error + scoped help, exit 1. |
-| `cliHelpRender(schema, helpPath, useStderr)` | Render help (`schema` is the program root `CliCommand`). |
+| `CliCommand`, `CliOption`, `CliPositional`, `CliHandler` | Schema and handler types. |
+| `CliOptionKind`, `CliFallbackMode` | Option kinds and root fallback behavior. |
+| `CliSchemaValidationError` | Thrown when the static command tree violates schema rules. |
+| `CliContext` | Handler context (`ctx.flag`, `ctx.stringOpt`, `ctx.args`, …). |
+| `cliRun(root, [argv])` | Validate, parse argv, dispatch, exit. |
+| `cliErrWithHelp(ctx, msg)` | Print error + scoped help on stderr, exit 1. |
 
 Reserved identifier (validated at startup): root command **`completion`**.
 

package/examples/minimal.ts

@@ -7,27 +7,32 @@ readers can copy the pattern into their own scripts quickly.
 It demonstrates the minimal Bun integration path.
 */
 
-import { cliRun, CliCommand, createOption, CliOptionKind, CliFallbackMode } from "../src/index.ts";
+import { cliRun, CliCommand, CliOptionKind, CliFallbackMode } from "../src/index.ts";
 
 const cli: CliCommand = {
   key: "minimal.ts",
   description: "Tiny demo.",
-  children: [
+  commands: [
     {
       key: "hello",
       description: "Say hello.",
       options: [
-        createOption("name", "Who to greet.", {
+        {
+          name: "name",
+          description: "Who to greet.",
           kind: CliOptionKind.String,
           shortName: "n",
-        }),
-        createOption("verbose", "Enable extra logging.", {
+        },
+        {
+          name: "verbose",
+          description: "Enable extra logging.",
+          kind: CliOptionKind.Presence,
           shortName: "v",
-        }),
+        },
       ],
       handler: (ctx) => {
         const name = ctx.stringOpt("name") ?? "world";
-        if (ctx.flag("verbose")) {
+        if (ctx.hasFlag("verbose")) {
           console.log("verbose mode");
         }
         console.log(`hello ${name}`);

package/examples/nested.ts

@@ -7,34 +7,39 @@ and fallback commands fit together in one schema.
 It demonstrates how the schema scales beyond one command.
 */
 
-import { cliRun, CliCommand, createOption, CliOptionKind, CliFallbackMode } from "../src/index.ts";
+import { cliRun, CliCommand, CliOptionKind, CliFallbackMode } from "../src/index.ts";
 
 const cli: CliCommand = {
   key: "nested.ts",
   description: "Nested groups demo.",
-  children: [
+  commands: [
     {
       key: "stat",
       description: "File metadata.",
-      children: [
+      commands: [
         {
           key: "owner",
           description: "Ownership helpers.",
-          children: [
+          commands: [
             {
               key: "lookup",
               description: "Resolve owner info.",
               options: [
-                createOption("user-name", "User to look up.", {
+                {
+                  name: "user-name",
+                  description: "User to look up.",
                   kind: CliOptionKind.String,
                   shortName: "u",
-                }),
+                },
               ],
               positionals: [
-                createOption("path", "File or directory.", {
+                {
+                  name: "path",
+                  description: "File or directory.",
                   kind: CliOptionKind.String,
-                  positional: true,
-                }),
+                  argMin: 1,
+                  argMax: 1,
+                },
               ],
               handler: (ctx) => {
                 const user = ctx.stringOpt("user-name") ?? "?";
@@ -55,12 +60,13 @@ const cli: CliCommand = {
       description: "Print the first line of each file.",
       notes: "Pass one or more file paths. {app} prints the first line of each.",
       positionals: [
-        createOption("files", "Paths to read.", {
+        {
+          name: "files",
+          description: "Paths to read.",
           kind: CliOptionKind.String,
-          positional: true,
           argMin: 1,
           argMax: 0,
-        }),
+        },
       ],
       handler: async (ctx) => {
         if (ctx.args.length === 0) {

package/justfile

@@ -0,0 +1,32 @@
+# https://github.com/casey/just — run `just` to list recipes.
+
+_:
+    @just --list
+
+# typecheck the codebase
+check-types:
+    bun x tsc
+
+# run the minimal example
+example:
+    bun ./examples/minimal.ts
+
+# run the minimal example and watch for changes
+example-watch:
+    bun --watch ./examples/minimal.ts
+
+# format the codebase
+format:
+    bun x biome format ./src ./scripts --write
+
+# lint the codebase
+lint:
+    bun x biome check ./src ./scripts
+
+# Typecheck, lint, then run the test suite.
+test: check-types format lint
+    bun test
+
+# publish to github and npm
+release bump: test
+    bun scripts/release.ts {{bump}}

package/package.json

@@ -1,25 +1,20 @@
 {
   "name": "argsbarg",
-  "version": "0.1.0",
+  "version": "1.0.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",
   "bin": {
-    "argsbarg": "./src/index.ts"
+    "argsbarg": "src/index.ts"
   },
   "exports": {
     ".": "./src/index.ts"
   },
-  "scripts": {
-    "test": "bun check-types && bun lint && bun test",
-    "dev": "bun --watch ./examples/minimal.ts",
-    "lint": "bun x biome check ./src",
-    "format": "bun x biome format ./src --write",
-    "check-types": "bun x tsc",
-    "release": "bun x npm publish"
-  },
   "devDependencies": {
     "@types/bun": "^1.3.12"
   }
-}
+}

package/plan.md

@@ -13,9 +13,9 @@
 - **Phase 1**: Core Schema Types (`src/types.ts`)
   - `CliOptionKind` enum (Presence, String, Number)
   - `CliFallbackMode` enum (MissingOnly, MissingOrUnknown, UnknownOnly)
-  - `CliCommand`, `CliOptionDef`, `CliHandler`, `CliContext` interfaces
+  - `CliCommand`, `CliOption`, `CliPositional`, `CliHandler`, `CliContext` interfaces
   - `CliSchemaValidationError` class
-  - Helper factories: `createOption()`, `createCommand()`
+  - `CliOption` on `options`, `CliPositional` on `positionals`, nested routes under `commands`
 
 - **Phase 2**: Argument Parser (`src/parse.ts`)
   - `parse(root, argv)` with long/short options, bundling, equals syntax

package/scripts/release.ts

@@ -0,0 +1,154 @@
+#!/usr/bin/env bun
+/**
+ * Release workflow: bump semver; update CHANGELOG; 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.
+ *
+ * Usage: `bun scripts/release.ts <major|minor|patch>` (usually via `just release <bump>`.)
+ *
+ * Requires: `git`, `gh` (authenticated), `npm` logged in for publish. The release commit stages **all**
+ * repo changes (`git add -A`), not only the version and CHANGELOG edits from this script.
+ */
+
+import { unlink } from "fs/promises";
+
+/** Returns the parent directory of an absolute file path. */
+function parentDir(absolute: string): string {
+  const s = absolute.replace(/[/\\]+$/, "");
+  const i = Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\"));
+  if (i <= 0) {
+    return s;
+  }
+  return s.slice(0, i);
+}
+
+/** Monorepo root: parent of `scripts/` (directory of this file). */
+const repoRoot = parentDir(import.meta.dir);
+
+/** Which semver segment to increment for the next release. */
+type Bump = "major" | "minor" | "patch";
+
+/** Prints usage to stderr and exits with status 1. */
+function usage(): never {
+  console.error("Usage: bun scripts/release.ts <major|minor|patch>");
+  process.exit(1);
+}
+
+/** Parses the release bump level from argv; exits on invalid input. */
+function parseBump(s: string | undefined): Bump {
+  if (s === "major" || s === "minor" || s === "patch") {
+    return s;
+  }
+  usage();
+}
+
+/** Returns the next `x.y.z` version for the given `major` | `minor` | `patch` segment. */
+function bumpSemver(version: string, part: Bump): string {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(version.trim());
+  if (!m) {
+    throw new Error(`package.json version must be semver x.y.z, got: ${JSON.stringify(version)}`);
+  }
+  let major = Number(m[1]);
+  let minor = Number(m[2]);
+  let patch = Number(m[3]);
+  if (part === "major") {
+    major += 1;
+    minor = 0;
+    patch = 0;
+  } else if (part === "minor") {
+    minor += 1;
+    patch = 0;
+  } else {
+    patch += 1;
+  }
+  return `${major}.${minor}.${patch}`;
+}
+
+/** 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(" ")}`);
+  const proc = Bun.spawnSync({ cmd, cwd, stdout: "inherit", stderr: "inherit" });
+  if (proc.exitCode !== 0) {
+    console.error(`\n${label} failed (exit ${proc.exitCode})`);
+    process.exit(proc.exitCode ?? 1);
+  }
+}
+
+/** Moves `[Unreleased]` content under a new `## [version] - date` heading and leaves an empty Unreleased. */
+function promoteChangelog(content: string, version: string, date: string): string {
+  const header = "## [Unreleased]";
+  const idx = content.indexOf(header);
+  if (idx === -1) {
+    throw new Error("CHANGELOG.md: missing ## [Unreleased] section");
+  }
+  const lineEnd = content.indexOf("\n", idx);
+  if (lineEnd === -1) {
+    throw new Error("CHANGELOG.md: malformed after [Unreleased]");
+  }
+  const bodyStart = lineEnd + 1;
+  const nextIdx = content.indexOf("\n## [", bodyStart);
+  const body =
+    nextIdx === -1 ? content.slice(bodyStart).trimEnd() : content.slice(bodyStart, nextIdx).trimEnd();
+  const tail = nextIdx === -1 ? "" : content.slice(nextIdx + 1);
+  const before = content.slice(0, idx);
+  const newBlock = `${header}\n\n## [${version}] - ${date}\n${body}\n\n`;
+  return before + newBlock + tail;
+}
+
+/** Returns the markdown body of one version section for `gh release` notes. */
+function extractReleaseNotes(nextChangelog: string, version: string, date: string): string {
+  const verHeader = `## [${version}] - ${date}`;
+  const ni = nextChangelog.indexOf(verHeader);
+  if (ni === -1) {
+    throw new Error("internal: promoted version header not found in CHANGELOG");
+  }
+  const nextHdrAt = nextChangelog.indexOf("\n## [", ni + verHeader.length);
+  if (nextHdrAt === -1) {
+    return nextChangelog.slice(ni).trimEnd();
+  }
+  return nextChangelog.slice(ni, nextHdrAt).trimEnd();
+}
+
+/** Joins a root path and a file segment with a single path separator. */
+function joinFile(root: string, segment: string): string {
+  const r = root.replace(/[/\\]+$/, "");
+  return `${r}/${segment}`;
+}
+
+const bump = parseBump(process.argv[2]);
+
+const pkgPath = joinFile(repoRoot, "package.json");
+const pkgText = await Bun.file(pkgPath).text();
+const pkg = JSON.parse(pkgText) as { name: string; version: string };
+const nextVersion = bumpSemver(pkg.version, bump);
+const releaseDate = new Date().toISOString().slice(0, 10);
+
+pkg.version = nextVersion;
+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);
+await Bun.write(changelogPath, nextChangelog);
+
+const notesPath = joinFile(repoRoot, ".release-notes.tmp.md");
+const notesContent = extractReleaseNotes(nextChangelog, nextVersion, releaseDate);
+await Bun.write(notesPath, `${notesContent}\n`);
+
+const tag = `v${nextVersion}`;
+const msg = `release ${tag}`;
+
+try {
+  run("git add (all)", ["git", "add", "-A"], repoRoot);
+  run("git commit", ["git", "commit", "-m", msg], repoRoot);
+  run("git tag", ["git", "tag", "-a", tag, "-m", msg], repoRoot);
+  run("git push", ["git", "push"], repoRoot);
+  run("git push tags", ["git", "push", "--tags"], repoRoot);
+  run("gh release", ["gh", "release", "create", tag, "--title", tag, "--notes-file", notesPath], repoRoot);
+  run("npm publish", ["npm", "publish"], repoRoot);
+} finally {
+  await unlink(notesPath).catch(() => {});
+}
+
+console.log(`\nDone: published ${pkg.name}@${nextVersion} (${tag}).`);