argsbarg 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,9 @@ 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
@@ -40,6 +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.0.1...HEAD
+[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

@@ -3,7 +3,7 @@
 
 [![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**. 

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.1",
+  "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"
   },