hacksh 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,262 @@
-# Temporary Holding Version
+# hacksh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Define a type-safe command-line interface with a Zod 4 object schema. The same schema parses and
+validates arguments, infers the value passed to `run`, and generates help.
+
+The name comes from 拍手 (_hakushu_), the Japanese word for "clap", as a nod to
+[clap](https://github.com/clap-rs/clap), the command-line argument parser for Rust. It is spelled
+with _hack_ and _sh_, as in shell.
+
+## Install
+
+```sh
+pnpm add hacksh zod
+```
+
+hacksh is an ESM package and supports Node.js 22.18 or newer. Zod is a peer dependency, so an
+application controls the Zod 4 version it uses. The public schema types and schema inspection use
+the shared `zod/v4/core` API and accept schemas created with either `zod` or `zod/mini`.
+
+## Define and run a command
+
+```ts
+import { z } from "zod";
+import { defineCommand, runMain } from "hacksh";
+
+const main = defineCommand({
+  name: "gh-pr-commits",
+  version: "0.1.0",
+  description: "List commits in a GitHub pull request",
+  args: z.object({
+    _: z.tuple([
+      z.coerce.number().int().optional().describe("Pull request number").meta({ title: "PR" }),
+    ]),
+    repo: z.string().optional().describe("Repository in OWNER/REPO format"),
+    verbose: z.boolean().default(false).describe("Show details"),
+  }),
+  argOptions: { repo: { alias: "R" }, verbose: { alias: ["v", "V"] } },
+  async run({ args, rawArgs, extraArgs, passthrough }) {
+    // args is { _: [number?]; repo?: string; verbose: boolean }
+    console.log({ args, rawArgs, extraArgs, passthrough });
+  },
+});
+
+await runMain(main);
+```
+
+```sh
+gh-pr-commits 42 -R owner/repo --verbose
+gh-pr-commits --help
+gh-pr-commits --version
+```
+
+Boolean fields are flags and other fields take a value. Both a schema key and its kebab-case form
+are accepted (`--dryRun` and `--dry-run`). A default-on flag can be disabled with `--no-`, such as
+`--no-verbose`. Boolean flags also accept the explicit forms `--verbose=true` and
+`--verbose=false`; other inline values and values on a negated flag (such as
+`--no-verbose=false`) are validation errors. Value options accept `--repo owner/repo` and
+`--repo=owner/repo`; values such as `false` remain strings for non-boolean fields.
+
+## Positional arguments
+
+Declare positional arguments as a `z.tuple` in the `_` field. Tuple items are assigned in order,
+and the tuple rest collects all remaining values. Optional or defaulted items must come after
+required ones, and items cannot be booleans or arrays. The `_` field is never a named option.
+
+```ts
+const copy = defineCommand({
+  name: "copy",
+  args: z.object({
+    _: z.tuple(
+      [z.string().describe("Output directory").meta({ title: "DESTINATION" })],
+      z.string().describe("Input files").meta({ title: "FILES" }),
+    ),
+  }),
+  run({ args }) {
+    const [destination, ...files] = args._; // [string, ...string[]]
+  },
+});
+```
+
+```sh
+copy out a.txt b.txt   # { _: ["out", "a.txt", "b.txt"] }
+```
+
+Help and validation errors label each item with its `.meta({ title })`, such as `<DESTINATION>` and
+`[FILES...]`. Untitled items are labeled by position (`ARG1`, `ARG2`, ...) and an untitled rest is
+labeled `ARGS`. Use `z.array` instead of a tuple to accept only variadic values. Without a rest,
+additional positional arguments are kept in `extraArgs`. Unknown options are also kept in
+`extraArgs`; arguments after `--` are kept in `passthrough`.
+
+## Argument options
+
+Use `argOptions` to set short aliases and help labels for each named option without changing
+schema keys, parsed output, or validation error paths. `z.enum` choices and schema descriptions
+appear in generated help, including enums inside the supported schema wrappers and tuple items.
+
+```ts
+const convert = defineCommand({
+  name: "convert",
+  args: z.object({
+    _: z.tuple(
+      [z.enum(["small", "large"]).describe("Item size").meta({ title: "SIZE" })],
+      z.string().describe("Input files").meta({ title: "INPUT" }),
+    ),
+    format: z.enum(["json", "yaml"]).optional().describe("Output format"),
+    overwrite: z.boolean().default(true).describe("Replace existing files"),
+    verbose: z.boolean().default(false).describe("Show details"),
+  }),
+  argOptions: {
+    format: { alias: "f", valueName: "FORMAT" },
+    overwrite: { negatedDescription: "Keep existing files" },
+    verbose: { alias: ["v", "V"] },
+  },
+});
+```
+
+```sh
+convert large -f yaml -v a.txt b.txt
+# { _: ["large", "a.txt", "b.txt"], format: "yaml", overwrite: true, verbose: true }
+```
+
+```text
+USAGE convert [OPTIONS] <SIZE> [INPUT...]
+
+ARGUMENTS
+
+  SIZE  Item size (Choices: small, large) (Required)
+  INPUT...  Input files
+
+OPTIONS
+
+  -f, --format=<FORMAT>  Output format (Choices: json, yaml)
+  --overwrite  Replace existing files (Default: true)
+  --no-overwrite  Keep existing files
+  -v, -V, --verbose  Show details (Default: false)
+```
+
+- `alias` gives a named option one or more single-character short forms.
+- `valueName` sets the value label of a named option.
+- `negatedDescription` describes the `--no-` form of a boolean flag.
+
+`argOptions` keys are checked against the argument schema. `defineCommand` throws a `TypeError`
+when an alias is longer than one character or is used by more than one option, and when
+`argOptions` has a `_` key. Without an alias of the same letter, `-h` and `-v` are shorthands
+for `--help` and `--version`. Defining an `h` or `v` alias replaces the shorthand, so `convert -v`
+above sets `verbose`; `--help` and `--version` remain available. Help remains plain text when
+`NO_COLOR` or `CI` is set.
+
+## Subcommands
+
+```ts
+const main = defineCommand({
+  name: "worktree",
+  args: z.object({ repo: z.string() }),
+  subCommands: {
+    new: defineCommand({
+      args: z.object({ name: z.string() }),
+      async run({ args }) {
+        console.log(args.name);
+      },
+    }),
+    migrate: defineCommand({
+      hidden: true,
+      run() {
+        // Internal or deprecated command, still callable as `worktree migrate`.
+      },
+    }),
+  },
+  async run() {
+    // Runs only when no subcommand is selected.
+  },
+});
+```
+
+Parent options precede the subcommand (`worktree --repo owner/repo new --name feature`). A selected
+subcommand prevents the parent `run` handler from running. `worktree new --help` displays help for
+`new`. Set `hidden: true` on a subcommand to omit its name and description from its parent's help
+listing, including usage shown for an unknown command. Hidden commands remain available by name and
+their own `--help` output remains available. If every subcommand is hidden, help keeps the generic
+`<COMMAND>` syntax but omits the empty `COMMANDS` section.
+
+## Programmatic execution and errors
+
+`runCommand(command, argv)` handles help and version output without exiting, throws errors to its
+caller, and returns the selected `run` handler's result.
+
+For parsing and usage rendering without execution, use the async composition APIs. `parseArgs`
+parses exactly the supplied command definition and argument segment, returns its schema output only,
+and throws `ZittyValidationError` on failure. It does not route subcommands, act on help or version
+tokens, or bypass validation; callers that resolve commands themselves must pass the selected
+command and its segment. `renderUsage` has no output side effects; `showUsage` sends that same text
+to an optional synchronous or asynchronous writer (and otherwise uses `console.log`). These
+functions are async so future command-resolution features can be added without changing their
+return types.
+
+```ts
+import { parseArgs, renderUsage, showUsage } from "hacksh";
+
+const args = await parseArgs(main, ["42", "--repo", "owner/repo"]);
+// args is inferred from the schema as:
+// { pr?: number; repo?: string; verbose: boolean }
+
+const text: string = await renderUsage(main); // does not write output
+await showUsage(main, {
+  async write(usage) {
+    await Promise.resolve();
+    console.info(usage);
+  },
+});
+```
+
+The `run` context includes `cmd`, the actual resolved command definition. An unnamed subcommand is
+represented by a completed copy whose `name` is its key; the original definition is not mutated.
+
+`runMain(command)` reads `process.argv`, prints validation or usage errors, and exits with status 1.
+Use `argv` to inject arguments, or `createMain` to make a reusable entry point. Invocation arguments
+passed to the returned function take precedence over configured `argv`; omitting both falls back to
+`process.argv.slice(2)`. Both functions return `Promise<void>`.
+
+```ts
+import { createMain } from "hacksh";
+
+const mainEntry = createMain(main, { argv: ["--verbose"] });
+await mainEntry(); // uses the configured argv
+await mainEntry([]); // an explicit empty invocation overrides it
+```
+
+`showUsage` customizes both ordinary help and the usage appended to validation or routing errors.
+The supplied `write` function targets stdout for help and stderr for errors. The callback may be
+async. Pass `onError` to replace the entire default error display, including usage:
+
+```ts
+await runMain(main, {
+  argv: ["--help"],
+  async showUsage(command, { write }) {
+    await write(await renderUsage(command));
+  },
+  async onError(error) {
+    console.error(`gh-pr-commits: ${error instanceof Error ? error.message : String(error)}`);
+  },
+});
+```
+
+Usage failures are `ZittyUsageError` instances. Argument failures are
+`ZittyValidationError` instances whose `issues` identify CLI names such as `--repo` or `<PR>`.
+
+## Development
+
+| Command            | Description                               |
+| ------------------ | ----------------------------------------- |
+| `vp check`         | Format, lint, and type check              |
+| `vp test`          | Run tests                                 |
+| `vp pack`          | Build `src/index.ts` into `dist`          |
+| `vp run ready`     | Run check, test, and build                |
+| `pnpm test:packed` | Test the tarball with Node 22.18 and Deno |
+
+The packed-consumer test must execute its Node consumer with exactly Node 22.18.0. Run pnpm itself
+under that version, or supply an absolute executable path explicitly:
+
+```sh
+ZITTY_MINIMUM_NODE=/absolute/path/to/node-v22.18.0 pnpm test:packed
+```

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { $ZodIssue, $ZodObject, output } from "zod/v4/core";
+//#region src/schema.d.ts
+type ArgsSchema = $ZodObject;
+type EmptyArgs = $ZodObject<{}>;
+type ShapeOf<S extends ArgsSchema> = S["_zod"]["def"]["shape"];
+type ArgKey<S extends ArgsSchema> = Extract<keyof ShapeOf<S>, string>;
+type OptionKey<S extends ArgsSchema> = Exclude<ArgKey<S>, typeof POSITIONALS_KEY>;
+declare const POSITIONALS_KEY = "_";
+//#endregion
+//#region src/command.d.ts
+interface ArgOptions {
+  alias?: string | readonly string[];
+  valueName?: string;
+  negatedDescription?: string;
+}
+type ArgOptionsMap<S extends ArgsSchema> = Partial<Record<OptionKey<S>, ArgOptions>>;
+interface CommandContext<S extends ArgsSchema> {
+  cmd: CommandDef<S>;
+  args: output<S>;
+  rawArgs: string[];
+  passthrough: string[];
+  extraArgs: string[];
+}
+interface CommandDef<S extends ArgsSchema = EmptyArgs> {
+  name?: string;
+  version?: string;
+  description?: string;
+  hidden?: boolean;
+  args?: S;
+  argOptions?: ArgOptionsMap<S>;
+  subCommands?: Record<string, CommandDef<ArgsSchema>>;
+  run?(context: CommandContext<S>): unknown;
+}
+type AnyCommandDef = CommandDef<ArgsSchema>;
+declare function defineCommand<S extends ArgsSchema = EmptyArgs>(def: CommandDef<S>): CommandDef<S>;
+//#endregion
+//#region src/errors.d.ts
+interface ZittyIssue {
+  arg: string;
+  message: string;
+  issue?: $ZodIssue;
+}
+declare class ZittyUsageError extends Error {
+  readonly command: AnyCommandDef;
+  constructor(message: string, command: AnyCommandDef, options?: ErrorOptions);
+}
+declare class ZittyValidationError extends ZittyUsageError {
+  readonly issues: ReadonlyArray<ZittyIssue>;
+  constructor(command: AnyCommandDef, issues: ReadonlyArray<ZittyIssue>);
+}
+//#endregion
+//#region src/parser.d.ts
+/**
+ * Parse and validate one command segment without routing, builtin handling, or output.
+ */
+declare function parseArgs<S extends ArgsSchema>(command: CommandDef<S>, argv: string[]): Promise<output<S>>;
+//#endregion
+//#region src/usage.d.ts
+type UsageWriter = (text: string) => void | Promise<void>;
+interface ShowUsageOptions {
+  write?: UsageWriter;
+}
+type UsageOutput = Required<Pick<ShowUsageOptions, "write">>;
+type ShowUsageCallback = (command: AnyCommandDef, output: UsageOutput) => void | Promise<void>;
+/** Generate usage text without writing to stdout or stderr. */
+declare function renderUsage(command: AnyCommandDef): Promise<string>;
+/** Generate and write usage text, awaiting asynchronous writers. */
+declare function showUsage(command: AnyCommandDef, options?: ShowUsageOptions): Promise<void>;
+//#endregion
+//#region src/run.d.ts
+declare function runCommand<S extends ArgsSchema>(root: CommandDef<S>, argv: string[]): Promise<unknown>;
+interface RunMainOptions {
+  onError?: (error: unknown) => void | Promise<void>;
+  argv?: string[];
+  showUsage?: ShowUsageCallback;
+}
+declare function runMain<S extends ArgsSchema>(command: CommandDef<S>, options?: RunMainOptions): Promise<void>;
+declare function createMain<S extends ArgsSchema>(command: CommandDef<S>, options?: RunMainOptions): (argv?: string[]) => Promise<void>;
+//#endregion
+export { type ArgOptions, type ArgOptionsMap, type CommandContext, type CommandDef, type RunMainOptions, type ShowUsageCallback, type ShowUsageOptions, type UsageOutput, type UsageWriter, type ZittyIssue, ZittyUsageError, ZittyValidationError, createMain, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,528 @@
+import { globalRegistry, safeParseAsync } from "zod/v4/core";
+import { parseArgs as parseArgs$1 } from "node:util";
+//#region src/options.ts
+function kebabCase(value) {
+	return value.replaceAll(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function aliasList(value) {
+	return typeof value === "string" ? [value] : value;
+}
+function definition(schema) {
+	return schema._zod.def;
+}
+function innerSchema(def) {
+	switch (def.type) {
+		case "optional":
+		case "nonoptional":
+		case "nullable":
+		case "default":
+		case "prefault":
+		case "catch":
+		case "readonly": return def.innerType;
+		case "pipe": return def.in;
+		default: return;
+	}
+}
+/** Read only the common zod/v4/core definition and registry structures. */
+function readArgInfo(schema) {
+	let current = schema;
+	let required = true;
+	let defaultValue;
+	let description;
+	let title;
+	while (current) {
+		const metadata = globalRegistry.get(current);
+		description ??= metadata?.description;
+		title ??= metadata?.title;
+		const def = definition(current);
+		if (def.type === "optional" || def.type === "default" || def.type === "prefault") required = false;
+		if (def.type === "default" && defaultValue === void 0) defaultValue = def.defaultValue;
+		current = innerSchema(def);
+	}
+	const base = unwrapInput(schema);
+	return {
+		takesValue: definition(base).type !== "boolean",
+		required,
+		defaultValue,
+		description,
+		title,
+		choices: enumChoices(base)
+	};
+}
+/** Read the `_` tuple or array schema that declares positional arguments. */
+function readPositionals(shape) {
+	const field = shape["_"];
+	if (!field) return void 0;
+	const def = definition(unwrapInput(field));
+	let items;
+	let rest;
+	if (def.type === "tuple") {
+		items = def.items;
+		rest = def.rest ?? void 0;
+	} else if (def.type === "array") {
+		items = [];
+		rest = def.element;
+	} else throw new TypeError("Positional arguments `_` must use a tuple or array schema");
+	return {
+		items: items.map((schema, index) => ({
+			schema,
+			label: readArgInfo(schema).title ?? `ARG${index + 1}`
+		})),
+		rest: rest && {
+			schema: rest,
+			label: readArgInfo(rest).title ?? "ARGS"
+		}
+	};
+}
+function enumChoices(schema) {
+	const def = definition(schema);
+	const candidate = def.type === "array" ? unwrapInput(def.element) : schema;
+	if (definition(candidate).type !== "enum") return void 0;
+	const values = candidate._zod.values;
+	return values ? [...values].map(String) : void 0;
+}
+/** Whether the schema accepts an array after removing supported input wrappers. */
+function isArrayInput(schema) {
+	return definition(unwrapInput(schema)).type === "array";
+}
+function unwrapInput(schema) {
+	let current = schema;
+	for (;;) {
+		const inner = innerSchema(definition(current));
+		if (!inner) return current;
+		current = inner;
+	}
+}
+function schemaShape(schema) {
+	return schema._zod.def.shape;
+}
+//#endregion
+//#region src/command.ts
+function defineCommand(def) {
+	const shape = def.args ? schemaShape(def.args) : {};
+	const positionals = readPositionals(shape);
+	if (positionals) {
+		let sawOptional = false;
+		for (const { schema, label } of positionals.items) {
+			const info = readArgInfo(schema);
+			if (isArrayInput(schema)) throw new TypeError(`Positional argument \`${label}\` cannot be an array; use a tuple rest`);
+			if (!info.takesValue) throw new TypeError(`Boolean argument \`${label}\` cannot be positional`);
+			if (sawOptional && info.required) throw new TypeError(`Required positional \`${label}\` cannot follow an optional positional`);
+			sawOptional ||= !info.required;
+		}
+		if (def.subCommands && Object.keys(def.subCommands).length > 0) throw new TypeError("A command cannot define both positional arguments and subcommands");
+	}
+	const usedAliases = /* @__PURE__ */ new Set();
+	for (const [key, options] of Object.entries(def.argOptions ?? {})) {
+		if (key === "_") throw new TypeError("Positional arguments cannot have argument options");
+		if (!shape[key]) throw new TypeError(`Unknown argument options key \`${key}\``);
+		if (options?.alias === void 0) continue;
+		for (const alias of aliasList(options.alias)) {
+			if (alias.length !== 1) throw new TypeError(`Alias \`${alias}\` must be exactly one character`);
+			if (usedAliases.has(alias)) throw new TypeError(`Duplicate alias \`${alias}\``);
+			usedAliases.add(alias);
+		}
+	}
+	for (const key of Object.keys(shape)) if (key !== "_" && /^no[-A-Z]/.test(key)) throw new TypeError(`Option \`${key}\` conflicts with --no- negation`);
+	return def;
+}
+//#endregion
+//#region src/errors.ts
+var ZittyUsageError = class extends Error {
+	command;
+	constructor(message, command, options) {
+		super(message, options);
+		this.name = "ZittyUsageError";
+		this.command = command;
+	}
+};
+var ZittyValidationError = class extends ZittyUsageError {
+	issues;
+	constructor(command, issues) {
+		super(`Invalid arguments:\n${issues.map(({ arg, message }) => `  ${arg}: ${message}`).join("\n")}`, command);
+		this.name = "ZittyValidationError";
+		this.issues = issues;
+	}
+};
+//#endregion
+//#region src/parser.ts
+function optionModel(command) {
+	const definitions = /* @__PURE__ */ new Map();
+	const parserOptions = {};
+	const allAliases = /* @__PURE__ */ new Set();
+	if (command.args) for (const [key, schema] of Object.entries(schemaShape(command.args))) {
+		if (key === "_") continue;
+		const alias = command.argOptions?.[key]?.alias;
+		const aliases = alias ? aliasList(alias) : [];
+		const definition = {
+			key,
+			kebabName: kebabCase(key),
+			takesValue: readArgInfo(schema).takesValue
+		};
+		const type = definition.takesValue ? "string" : "boolean";
+		for (const name of /* @__PURE__ */ new Set([key, definition.kebabName])) {
+			definitions.set(name, definition);
+			parserOptions[name] = { type };
+		}
+		for (const alias of aliases) {
+			allAliases.add(alias);
+			definitions.set(alias, definition);
+			parserOptions[alias] = {
+				type,
+				short: alias
+			};
+		}
+	}
+	return {
+		definitions,
+		parserOptions,
+		aliases: allAliases
+	};
+}
+function commandPositionals(command) {
+	return command.args ? readPositionals(schemaShape(command.args)) : void 0;
+}
+function displayName(command, path) {
+	const [first, index] = path;
+	if (typeof first !== "string") return "arguments";
+	if (first !== "_") return `--${kebabCase(first)}`;
+	const positionals = commandPositionals(command);
+	if (!positionals || typeof index !== "number") return "arguments";
+	const item = positionals.items[index];
+	if (item) return `<${item.label}>`;
+	return positionals.rest ? `<${positionals.rest.label}...>` : "arguments";
+}
+function tokenizeCommandArgs(command, rawArgs) {
+	const model = optionModel(command);
+	const separator = rawArgs.indexOf("--");
+	const beforeSeparator = separator === -1 ? [...rawArgs] : rawArgs.slice(0, separator);
+	const passthrough = separator === -1 ? [] : rawArgs.slice(separator + 1);
+	const negativeIndexes = /* @__PURE__ */ new Set();
+	const valuedNegativeIndexes = /* @__PURE__ */ new Set();
+	const issues = [];
+	let recordedMissingValue = false;
+	const parserArgs = beforeSeparator.map((raw, index) => {
+		if (!raw.startsWith("--no-")) return raw;
+		const equals = raw.indexOf("=");
+		const name = raw.slice(5, equals === -1 ? void 0 : equals);
+		const definition = model.definitions.get(name);
+		if (!definition || definition.takesValue) return raw;
+		negativeIndexes.add(index);
+		if (equals !== -1) {
+			valuedNegativeIndexes.add(index);
+			return `--${definition.key}${raw.slice(equals)}`;
+		}
+		return `--${definition.key}`;
+	});
+	const parsed = parseArgs$1({
+		args: parserArgs,
+		options: model.parserOptions,
+		allowPositionals: true,
+		strict: false,
+		tokens: true
+	});
+	const tokens = [];
+	const unknownIndexes = /* @__PURE__ */ new Set();
+	let help = false;
+	let helpIndex;
+	let version = false;
+	let versionIndex;
+	for (const token of parsed.tokens) {
+		if (token.kind === "positional") {
+			tokens.push({
+				kind: "positional",
+				index: token.index,
+				value: token.value
+			});
+			continue;
+		}
+		if (token.kind !== "option") continue;
+		const isHelp = token.rawName === "--help" || token.rawName === "-h" && !model.aliases.has("h");
+		const isVersion = token.rawName === "--version" || token.rawName === "-v" && !model.aliases.has("v");
+		if (isHelp) {
+			help = true;
+			helpIndex ??= token.index;
+		}
+		if (isVersion) {
+			version = true;
+			versionIndex ??= token.index;
+		}
+		const definition = model.definitions.get(token.name);
+		if (definition) {
+			if (definition.takesValue && (token.value === void 0 || !token.inlineValue && token.value.startsWith("-") && token.value !== "-")) {
+				if (!recordedMissingValue) {
+					issues.push({
+						index: token.index,
+						issue: {
+							arg: `--${definition.kebabName}`,
+							message: "requires a value"
+						}
+					});
+					recordedMissingValue = true;
+				}
+			}
+			let value = token.value ?? true;
+			if (!definition.takesValue) {
+				if (valuedNegativeIndexes.has(token.index)) {
+					const rawName = beforeSeparator[token.index].split("=", 1)[0];
+					issues.push({
+						index: token.index,
+						issue: {
+							arg: rawName,
+							message: "does not accept a value"
+						}
+					});
+					value = false;
+				} else if (negativeIndexes.has(token.index)) value = false;
+				else if (token.inlineValue) if (token.value === "true") value = true;
+				else if (token.value === "false") value = false;
+				else issues.push({
+					index: token.index,
+					issue: {
+						arg: token.rawName,
+						message: "expects true or false"
+					}
+				});
+			}
+			tokens.push({
+				kind: "known-option",
+				index: token.index,
+				definition,
+				value: definition.takesValue ? token.value ?? "" : value
+			});
+		} else if (!unknownIndexes.has(token.index)) {
+			unknownIndexes.add(token.index);
+			tokens.push({
+				kind: "unknown-option",
+				index: token.index,
+				value: beforeSeparator[token.index]
+			});
+		}
+	}
+	return {
+		tokens,
+		passthrough,
+		issues,
+		help,
+		helpIndex,
+		version,
+		versionIndex
+	};
+}
+function tokenizedBefore(tokenized, endIndex) {
+	const help = tokenized.helpIndex !== void 0 && tokenized.helpIndex < endIndex;
+	const version = tokenized.versionIndex !== void 0 && tokenized.versionIndex < endIndex;
+	return {
+		tokens: tokenized.tokens.filter((token) => token.index < endIndex),
+		passthrough: [],
+		issues: tokenized.issues.filter(({ index }) => index < endIndex),
+		help,
+		helpIndex: help ? tokenized.helpIndex : void 0,
+		version,
+		versionIndex: version ? tokenized.versionIndex : void 0
+	};
+}
+function zodIssues(command, issues) {
+	return issues.map((issue) => ({
+		arg: displayName(command, issue.path),
+		message: issue.message,
+		issue
+	}));
+}
+async function parseCommandArgs(command, rawArgs, tokenized = tokenizeCommandArgs(command, rawArgs)) {
+	if (tokenized.issues.length > 0) throw new ZittyValidationError(command, tokenized.issues.map(({ issue }) => issue));
+	const input = {};
+	const positionals = commandPositionals(command);
+	const positionalValues = [];
+	if (positionals) input["_"] = positionalValues;
+	const extraArgs = [];
+	for (const token of tokenized.tokens) if (token.kind === "known-option") input[token.definition.key] = token.value;
+	else if (token.kind === "unknown-option") extraArgs.push(token.value);
+	else if (positionals && (positionals.rest || positionalValues.length < positionals.items.length)) positionalValues.push(token.value);
+	else extraArgs.push(token.value);
+	if (!command.args) return {
+		args: input,
+		passthrough: tokenized.passthrough,
+		extraArgs
+	};
+	const result = await safeParseAsync(command.args, input);
+	if (!result.success) throw new ZittyValidationError(command, zodIssues(command, result.error.issues));
+	return {
+		args: result.data,
+		passthrough: tokenized.passthrough,
+		extraArgs
+	};
+}
+/**
+* Parse and validate one command segment without routing, builtin handling, or output.
+*/
+async function parseArgs(command, argv) {
+	return (await parseCommandArgs(command, argv)).args;
+}
+//#endregion
+//#region src/usage.ts
+function details(description, required, defaultValue, choices) {
+	const parts = [description];
+	if (choices) parts.push(`(Choices: ${choices.join(", ")})`);
+	if (required) parts.push("(Required)");
+	if (defaultValue !== void 0) parts.push(`(Default: ${formatDefault(defaultValue)})`);
+	return parts.filter(Boolean).join(" ");
+}
+function formatDefault(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return value.toString();
+	if (value === null) return "null";
+	return JSON.stringify(value) ?? "undefined";
+}
+function heading(command) {
+	const identity = command.name ? `${command.name}${command.version ? ` v${command.version}` : ""}` : command.version ? `v${command.version}` : void 0;
+	if (command.description && identity) return `${command.description} (${identity})`;
+	return command.description ?? identity;
+}
+function formatUsage(command) {
+	const lines = [];
+	const title = heading(command);
+	if (title) lines.push(title, "");
+	const shape = command.args ? schemaShape(command.args) : {};
+	const positionals = readPositionals(shape);
+	const items = positionals?.items ?? [];
+	const rest = positionals?.rest;
+	const syntax = items.map(({ schema, label }) => readArgInfo(schema).required ? `<${label}>` : `[${label}]`);
+	if (rest) syntax.push(`[${rest.label}...]`);
+	if (command.subCommands && Object.keys(command.subCommands).length > 0) syntax.push("<COMMAND>");
+	lines.push(`USAGE ${command.name ?? "command"} [OPTIONS]${syntax.length ? ` ${syntax.join(" ")}` : ""}`);
+	if (items.length > 0 || rest) {
+		lines.push("", "ARGUMENTS", "");
+		for (const { schema, label } of items) {
+			const info = readArgInfo(schema);
+			lines.push(`  ${label}  ${details(info.description, info.required, info.defaultValue, info.choices)}`.trimEnd());
+		}
+		if (rest) {
+			const info = readArgInfo(rest.schema);
+			lines.push(`  ${rest.label}...  ${details(info.description, false, void 0, info.choices)}`.trimEnd());
+		}
+	}
+	const options = Object.entries(shape).filter(([key]) => key !== "_");
+	if (options.length > 0) {
+		lines.push("", "OPTIONS", "");
+		for (const [key, schema] of options) {
+			const info = readArgInfo(schema);
+			const argOptions = command.argOptions?.[key];
+			const prefix = argOptions?.alias ? `${aliasList(argOptions.alias).map((item) => `-${item}`).join(", ")}, ` : "";
+			const valueName = argOptions?.valueName ?? kebabCase(key);
+			const long = `--${kebabCase(key)}${info.takesValue ? `=<${valueName}>` : ""}`;
+			lines.push(`  ${prefix}${long}  ${details(info.description, info.required, info.defaultValue, info.choices)}`.trimEnd());
+			if (!info.takesValue && argOptions?.negatedDescription) lines.push(`  --no-${kebabCase(key)}  ${argOptions.negatedDescription}`);
+		}
+	}
+	const visibleSubCommands = Object.entries(command.subCommands ?? {}).filter(([, child]) => !child.hidden);
+	if (visibleSubCommands.length > 0) {
+		lines.push("", "COMMANDS", "");
+		for (const [name, child] of visibleSubCommands) lines.push(`  ${name}  ${child.description ?? ""}`.trimEnd());
+	}
+	return lines.join("\n");
+}
+/** Generate usage text without writing to stdout or stderr. */
+async function renderUsage(command) {
+	return formatUsage(command);
+}
+/** Generate and write usage text, awaiting asynchronous writers. */
+async function showUsage(command, options = {}) {
+	const text = await renderUsage(command);
+	return (options.write ?? console.log)(text);
+}
+//#endregion
+//#region src/run.ts
+function namedChild(child, name) {
+	return child.name ? child : {
+		...child,
+		name
+	};
+}
+function resolveCommand(root, rawArgs) {
+	let command = root;
+	let remaining = rawArgs;
+	const parents = [];
+	const segments = [];
+	for (;;) {
+		const tokenized = tokenizeCommandArgs(command, remaining);
+		const index = command.subCommands ? tokenized.tokens.find((token) => token.kind === "positional")?.index : void 0;
+		if (index === void 0) {
+			const segment = {
+				command,
+				rawArgs: remaining,
+				tokenized
+			};
+			segments.push(segment);
+			return {
+				...segment,
+				parents,
+				segments
+			};
+		}
+		const name = remaining[index];
+		const child = command.subCommands?.[name];
+		if (!child) throw new ZittyUsageError(`Unknown command \`${name}\``, command);
+		const prefix = remaining.slice(0, index);
+		const segment = {
+			command,
+			rawArgs: prefix,
+			tokenized: tokenizedBefore(tokenized, index)
+		};
+		parents.push(segment);
+		segments.push(segment);
+		command = namedChild(child, name);
+		remaining = remaining.slice(index + 1);
+	}
+}
+async function executeCommand(root, argv, displayUsage) {
+	const resolved = resolveCommand(root, argv);
+	if (resolved.segments[0]?.tokenized.version) {
+		console.log(root.version ?? "");
+		return;
+	}
+	if (resolved.segments.some(({ tokenized }) => tokenized.help)) {
+		await displayUsage(resolved.command, { write: (text) => console.log(text) });
+		return;
+	}
+	for (const parent of resolved.parents) await parseCommandArgs(parent.command, parent.rawArgs, parent.tokenized);
+	const parsed = await parseCommandArgs(resolved.command, resolved.rawArgs, resolved.tokenized);
+	if (!resolved.command.run) throw new ZittyUsageError("No command specified", resolved.command);
+	return resolved.command.run({
+		...parsed,
+		cmd: resolved.command,
+		rawArgs: resolved.rawArgs
+	});
+}
+async function runCommand(root, argv) {
+	return executeCommand(root, argv, showUsage);
+}
+async function runMain(command, options = {}) {
+	const displayUsage = options.showUsage ?? showUsage;
+	try {
+		await executeCommand(command, options.argv ?? process.argv.slice(2), displayUsage);
+	} catch (error) {
+		if (options.onError) {
+			await options.onError(error);
+			process.exit(1);
+		}
+		try {
+			if (error instanceof ZittyUsageError) {
+				console.error(error.message);
+				await displayUsage(error.command, { write: (text) => console.error(text) });
+			} else console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+		} finally {
+			process.exit(1);
+		}
+	}
+}
+function createMain(command, options = {}) {
+	return (argv) => runMain(command, argv === void 0 ? options : {
+		...options,
+		argv
+	});
+}
+//#endregion
+export { ZittyUsageError, ZittyValidationError, createMain, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["parseNodeArgs"],"sources":["../src/options.ts","../src/schema.ts","../src/command.ts","../src/errors.ts","../src/parser.ts","../src/usage.ts","../src/run.ts"],"sourcesContent":["export function kebabCase(value: string): string {\n  return value.replaceAll(/([a-z0-9])([A-Z])/g, \"$1-$2\").toLowerCase();\n}\n\nexport function aliasList(value: string | readonly string[]): readonly string[] {\n  return typeof value === \"string\" ? [value] : value;\n}\n","import { globalRegistry, type $ZodObject, type $ZodType } from \"zod/v4/core\";\n\nexport type ArgsSchema = $ZodObject;\nexport type EmptyArgs = $ZodObject<{}>;\nexport type ShapeOf<S extends ArgsSchema> = S[\"_zod\"][\"def\"][\"shape\"];\nexport type ArgKey<S extends ArgsSchema> = Extract<keyof ShapeOf<S>, string>;\nexport type OptionKey<S extends ArgsSchema> = Exclude<ArgKey<S>, typeof POSITIONALS_KEY>;\n\nexport const POSITIONALS_KEY = \"_\";\n\nexport interface ArgInfo {\n  readonly takesValue: boolean;\n  readonly required: boolean;\n  readonly defaultValue: unknown;\n  readonly description: string | undefined;\n  readonly title: string | undefined;\n  readonly choices: readonly string[] | undefined;\n}\n\nexport interface Positional {\n  readonly schema: $ZodType;\n  readonly label: string;\n}\n\nexport interface Positionals {\n  readonly items: readonly Positional[];\n  readonly rest: Positional | undefined;\n}\n\ntype ZodDef = Record<string, unknown> & { type: string };\n\nfunction definition(schema: $ZodType): ZodDef {\n  return schema._zod.def as ZodDef;\n}\n\nfunction innerSchema(def: ZodDef): $ZodType | undefined {\n  switch (def.type) {\n    case \"optional\":\n    case \"nonoptional\":\n    case \"nullable\":\n    case \"default\":\n    case \"prefault\":\n    case \"catch\":\n    case \"readonly\":\n      return def.innerType as $ZodType;\n    case \"pipe\":\n      return def.in as $ZodType;\n    default:\n      return undefined;\n  }\n}\n\n/** Read only the common zod/v4/core definition and registry structures. */\nexport function readArgInfo(schema: $ZodType): ArgInfo {\n  let current: $ZodType | undefined = schema;\n  let required = true;\n  let defaultValue: unknown;\n  let description: string | undefined;\n  let title: string | undefined;\n\n  while (current) {\n    const metadata = globalRegistry.get(current);\n    description ??= metadata?.description;\n    title ??= metadata?.title;\n\n    const def = definition(current);\n    if (def.type === \"optional\" || def.type === \"default\" || def.type === \"prefault\") {\n      required = false;\n    }\n    if (def.type === \"default\" && defaultValue === undefined) defaultValue = def.defaultValue;\n    current = innerSchema(def);\n  }\n\n  const base = unwrapInput(schema);\n  return {\n    takesValue: definition(base).type !== \"boolean\",\n    required,\n    defaultValue,\n    description,\n    title,\n    choices: enumChoices(base),\n  };\n}\n\n/** Read the `_` tuple or array schema that declares positional arguments. */\nexport function readPositionals(shape: Record<string, $ZodType>): Positionals | undefined {\n  const field = shape[POSITIONALS_KEY];\n  if (!field) return undefined;\n  const def = definition(unwrapInput(field));\n  let items: readonly $ZodType[];\n  let rest: $ZodType | undefined;\n  if (def.type === \"tuple\") {\n    items = def.items as readonly $ZodType[];\n    rest = (def.rest as $ZodType | null) ?? undefined;\n  } else if (def.type === \"array\") {\n    items = [];\n    rest = def.element as $ZodType;\n  } else {\n    throw new TypeError(\"Positional arguments `_` must use a tuple or array schema\");\n  }\n  return {\n    items: items.map((schema, index) => ({\n      schema,\n      label: readArgInfo(schema).title ?? `ARG${index + 1}`,\n    })),\n    rest: rest && { schema: rest, label: readArgInfo(rest).title ?? \"ARGS\" },\n  };\n}\n\nfunction enumChoices(schema: $ZodType): readonly string[] | undefined {\n  const def = definition(schema);\n  const candidate = def.type === \"array\" ? unwrapInput(def.element as $ZodType) : schema;\n  const candidateDef = definition(candidate);\n  if (candidateDef.type !== \"enum\") return undefined;\n  const values = candidate._zod.values;\n  return values ? [...values].map(String) : undefined;\n}\n\n/** Whether the schema accepts an array after removing supported input wrappers. */\nexport function isArrayInput(schema: $ZodType): boolean {\n  return definition(unwrapInput(schema)).type === \"array\";\n}\n\nfunction unwrapInput(schema: $ZodType): $ZodType {\n  let current = schema;\n  for (;;) {\n    const inner = innerSchema(definition(current));\n    if (!inner) return current;\n    current = inner;\n  }\n}\n\nexport function schemaShape(schema: ArgsSchema): Record<string, $ZodType> {\n  return schema._zod.def.shape as Record<string, $ZodType>;\n}\n","import type { output } from \"zod/v4/core\";\nimport { aliasList } from \"./options.ts\";\nimport {\n  isArrayInput,\n  POSITIONALS_KEY,\n  readArgInfo,\n  readPositionals,\n  schemaShape,\n  type ArgsSchema,\n  type EmptyArgs,\n  type OptionKey,\n} from \"./schema.ts\";\n\nexport interface ArgOptions {\n  alias?: string | readonly string[];\n  valueName?: string;\n  negatedDescription?: string;\n}\n\nexport type ArgOptionsMap<S extends ArgsSchema> = Partial<Record<OptionKey<S>, ArgOptions>>;\n\nexport interface CommandContext<S extends ArgsSchema> {\n  cmd: CommandDef<S>;\n  args: output<S>;\n  rawArgs: string[];\n  passthrough: string[];\n  extraArgs: string[];\n}\n\nexport interface CommandDef<S extends ArgsSchema = EmptyArgs> {\n  name?: string;\n  version?: string;\n  description?: string;\n  hidden?: boolean;\n  args?: S;\n  argOptions?: ArgOptionsMap<S>;\n  subCommands?: Record<string, CommandDef<ArgsSchema>>;\n  run?(context: CommandContext<S>): unknown;\n}\n\nexport type AnyCommandDef = CommandDef<ArgsSchema>;\n\nexport function defineCommand<S extends ArgsSchema = EmptyArgs>(def: CommandDef<S>): CommandDef<S> {\n  const shape = def.args ? schemaShape(def.args) : {};\n  const positionals = readPositionals(shape);\n\n  if (positionals) {\n    let sawOptional = false;\n    for (const { schema, label } of positionals.items) {\n      const info = readArgInfo(schema);\n      if (isArrayInput(schema)) {\n        throw new TypeError(\n          `Positional argument \\`${label}\\` cannot be an array; use a tuple rest`,\n        );\n      }\n      if (!info.takesValue) {\n        throw new TypeError(`Boolean argument \\`${label}\\` cannot be positional`);\n      }\n      if (sawOptional && info.required) {\n        throw new TypeError(\n          `Required positional \\`${label}\\` cannot follow an optional positional`,\n        );\n      }\n      sawOptional ||= !info.required;\n    }\n    if (def.subCommands && Object.keys(def.subCommands).length > 0) {\n      throw new TypeError(\"A command cannot define both positional arguments and subcommands\");\n    }\n  }\n\n  const usedAliases = new Set<string>();\n  for (const [key, options] of Object.entries(def.argOptions ?? {})) {\n    if (key === POSITIONALS_KEY) {\n      throw new TypeError(\"Positional arguments cannot have argument options\");\n    }\n    if (!shape[key]) throw new TypeError(`Unknown argument options key \\`${key}\\``);\n    if (options?.alias === undefined) continue;\n    for (const alias of aliasList(options.alias)) {\n      if (alias.length !== 1)\n        throw new TypeError(`Alias \\`${alias}\\` must be exactly one character`);\n      if (usedAliases.has(alias)) throw new TypeError(`Duplicate alias \\`${alias}\\``);\n      usedAliases.add(alias);\n    }\n  }\n\n  for (const key of Object.keys(shape)) {\n    if (key !== POSITIONALS_KEY && /^no[-A-Z]/.test(key)) {\n      throw new TypeError(`Option \\`${key}\\` conflicts with --no- negation`);\n    }\n  }\n\n  return def;\n}\n","import type { $ZodIssue } from \"zod/v4/core\";\nimport type { AnyCommandDef } from \"./command.ts\";\n\nexport interface ZittyIssue {\n  arg: string;\n  message: string;\n  issue?: $ZodIssue;\n}\n\nexport class ZittyUsageError extends Error {\n  readonly command: AnyCommandDef;\n\n  constructor(message: string, command: AnyCommandDef, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"ZittyUsageError\";\n    this.command = command;\n  }\n}\n\nexport class ZittyValidationError extends ZittyUsageError {\n  readonly issues: ReadonlyArray<ZittyIssue>;\n\n  constructor(command: AnyCommandDef, issues: ReadonlyArray<ZittyIssue>) {\n    super(\n      `Invalid arguments:\\n${issues.map(({ arg, message }) => `  ${arg}: ${message}`).join(\"\\n\")}`,\n      command,\n    );\n    this.name = \"ZittyValidationError\";\n    this.issues = issues;\n  }\n}\n","import { parseArgs as parseNodeArgs } from \"node:util\";\nimport { safeParseAsync, type $ZodIssue, type output } from \"zod/v4/core\";\nimport type { AnyCommandDef, CommandDef } from \"./command.ts\";\nimport { ZittyValidationError, type ZittyIssue } from \"./errors.ts\";\nimport { aliasList, kebabCase } from \"./options.ts\";\nimport {\n  POSITIONALS_KEY,\n  readArgInfo,\n  readPositionals,\n  schemaShape,\n  type ArgsSchema,\n  type Positionals,\n} from \"./schema.ts\";\n\nexport interface ParsedCommand<S extends ArgsSchema> {\n  args: output<S>;\n  passthrough: string[];\n  extraArgs: string[];\n}\n\ninterface OptionDefinition {\n  readonly key: string;\n  readonly kebabName: string;\n  readonly takesValue: boolean;\n}\n\ninterface OptionModel {\n  readonly definitions: Map<string, OptionDefinition>;\n  readonly parserOptions: Record<string, { type: \"string\" | \"boolean\"; short?: string }>;\n  readonly aliases: Set<string>;\n}\n\ninterface KnownOptionToken {\n  readonly kind: \"known-option\";\n  readonly index: number;\n  readonly definition: OptionDefinition;\n  readonly value: string | boolean;\n}\n\ninterface UnknownOptionToken {\n  readonly kind: \"unknown-option\";\n  readonly index: number;\n  readonly value: string;\n}\n\ninterface PositionalToken {\n  readonly kind: \"positional\";\n  readonly index: number;\n  readonly value: string;\n}\n\ntype CommandToken = KnownOptionToken | UnknownOptionToken | PositionalToken;\n\nexport interface TokenizedCommandArgs {\n  readonly tokens: readonly CommandToken[];\n  readonly passthrough: string[];\n  readonly issues: readonly IndexedIssue[];\n  readonly help: boolean;\n  readonly helpIndex: number | undefined;\n  readonly version: boolean;\n  readonly versionIndex: number | undefined;\n}\n\ninterface IndexedIssue {\n  readonly index: number;\n  readonly issue: ZittyIssue;\n}\n\nfunction optionModel(command: AnyCommandDef): OptionModel {\n  const definitions = new Map<string, OptionDefinition>();\n  const parserOptions: OptionModel[\"parserOptions\"] = {};\n  const allAliases = new Set<string>();\n\n  if (command.args) {\n    for (const [key, schema] of Object.entries(schemaShape(command.args))) {\n      if (key === POSITIONALS_KEY) continue;\n      const alias = command.argOptions?.[key]?.alias;\n      const aliases = alias ? aliasList(alias) : [];\n      const definition: OptionDefinition = {\n        key,\n        kebabName: kebabCase(key),\n        takesValue: readArgInfo(schema).takesValue,\n      };\n      const type = definition.takesValue ? \"string\" : \"boolean\";\n      for (const name of new Set([key, definition.kebabName])) {\n        definitions.set(name, definition);\n        parserOptions[name] = { type };\n      }\n      for (const alias of aliases) {\n        allAliases.add(alias);\n        definitions.set(alias, definition);\n        parserOptions[alias] = { type, short: alias };\n      }\n    }\n  }\n  return { definitions, parserOptions, aliases: allAliases };\n}\n\nfunction commandPositionals(command: AnyCommandDef): Positionals | undefined {\n  return command.args ? readPositionals(schemaShape(command.args)) : undefined;\n}\n\nfunction displayName(command: AnyCommandDef, path: readonly PropertyKey[]): string {\n  const [first, index] = path;\n  if (typeof first !== \"string\") return \"arguments\";\n  if (first !== POSITIONALS_KEY) return `--${kebabCase(first)}`;\n  const positionals = commandPositionals(command);\n  if (!positionals || typeof index !== \"number\") return \"arguments\";\n  const item = positionals.items[index];\n  if (item) return `<${item.label}>`;\n  return positionals.rest ? `<${positionals.rest.label}...>` : \"arguments\";\n}\n\nexport function tokenizeCommandArgs(\n  command: AnyCommandDef,\n  rawArgs: readonly string[],\n): TokenizedCommandArgs {\n  const model = optionModel(command);\n  const separator = rawArgs.indexOf(\"--\");\n  const beforeSeparator = separator === -1 ? [...rawArgs] : rawArgs.slice(0, separator);\n  const passthrough = separator === -1 ? [] : rawArgs.slice(separator + 1);\n  const negativeIndexes = new Set<number>();\n  const valuedNegativeIndexes = new Set<number>();\n  const issues: IndexedIssue[] = [];\n  let recordedMissingValue = false;\n  const parserArgs = beforeSeparator.map((raw, index) => {\n    if (!raw.startsWith(\"--no-\")) return raw;\n    const equals = raw.indexOf(\"=\");\n    const name = raw.slice(5, equals === -1 ? undefined : equals);\n    const definition = model.definitions.get(name);\n    if (!definition || definition.takesValue) return raw;\n    negativeIndexes.add(index);\n    if (equals !== -1) {\n      valuedNegativeIndexes.add(index);\n      return `--${definition.key}${raw.slice(equals)}`;\n    }\n    return `--${definition.key}`;\n  });\n\n  const parsed = parseNodeArgs({\n    args: parserArgs,\n    options: model.parserOptions,\n    allowPositionals: true,\n    strict: false,\n    tokens: true,\n  });\n  const tokens: CommandToken[] = [];\n  const unknownIndexes = new Set<number>();\n  let help = false;\n  let helpIndex: number | undefined;\n  let version = false;\n  let versionIndex: number | undefined;\n  for (const token of parsed.tokens) {\n    if (token.kind === \"positional\") {\n      tokens.push({ kind: \"positional\", index: token.index, value: token.value });\n      continue;\n    }\n    if (token.kind !== \"option\") continue;\n    const isHelp =\n      token.rawName === \"--help\" || (token.rawName === \"-h\" && !model.aliases.has(\"h\"));\n    const isVersion =\n      token.rawName === \"--version\" || (token.rawName === \"-v\" && !model.aliases.has(\"v\"));\n    if (isHelp) {\n      help = true;\n      helpIndex ??= token.index;\n    }\n    if (isVersion) {\n      version = true;\n      versionIndex ??= token.index;\n    }\n    const definition = model.definitions.get(token.name);\n    if (definition) {\n      if (\n        definition.takesValue &&\n        (token.value === undefined ||\n          (!token.inlineValue && token.value.startsWith(\"-\") && token.value !== \"-\"))\n      ) {\n        if (!recordedMissingValue) {\n          issues.push({\n            index: token.index,\n            issue: { arg: `--${definition.kebabName}`, message: \"requires a value\" },\n          });\n          recordedMissingValue = true;\n        }\n      }\n      let value: string | boolean = token.value ?? true;\n      if (!definition.takesValue) {\n        if (valuedNegativeIndexes.has(token.index)) {\n          const rawName = beforeSeparator[token.index]!.split(\"=\", 1)[0]!;\n          issues.push({\n            index: token.index,\n            issue: { arg: rawName, message: \"does not accept a value\" },\n          });\n          value = false;\n        } else if (negativeIndexes.has(token.index)) {\n          value = false;\n        } else if (token.inlineValue) {\n          if (token.value === \"true\") value = true;\n          else if (token.value === \"false\") value = false;\n          else {\n            issues.push({\n              index: token.index,\n              issue: { arg: token.rawName, message: \"expects true or false\" },\n            });\n          }\n        }\n      }\n      tokens.push({\n        kind: \"known-option\",\n        index: token.index,\n        definition,\n        value: definition.takesValue ? (token.value ?? \"\") : value,\n      });\n    } else if (!unknownIndexes.has(token.index)) {\n      unknownIndexes.add(token.index);\n      tokens.push({\n        kind: \"unknown-option\",\n        index: token.index,\n        value: beforeSeparator[token.index]!,\n      });\n    }\n  }\n\n  return {\n    tokens,\n    passthrough,\n    issues,\n    help,\n    helpIndex,\n    version,\n    versionIndex,\n  };\n}\n\nexport function tokenizedBefore(\n  tokenized: TokenizedCommandArgs,\n  endIndex: number,\n): TokenizedCommandArgs {\n  const help = tokenized.helpIndex !== undefined && tokenized.helpIndex < endIndex;\n  const version = tokenized.versionIndex !== undefined && tokenized.versionIndex < endIndex;\n  return {\n    tokens: tokenized.tokens.filter((token) => token.index < endIndex),\n    passthrough: [],\n    issues: tokenized.issues.filter(({ index }) => index < endIndex),\n    help,\n    helpIndex: help ? tokenized.helpIndex : undefined,\n    version,\n    versionIndex: version ? tokenized.versionIndex : undefined,\n  };\n}\n\nfunction zodIssues(command: AnyCommandDef, issues: readonly $ZodIssue[]): ZittyIssue[] {\n  return issues.map((issue) => ({\n    arg: displayName(command, issue.path),\n    message: issue.message,\n    issue,\n  }));\n}\n\nexport async function parseCommandArgs<S extends ArgsSchema>(\n  command: CommandDef<S>,\n  rawArgs: string[],\n  tokenized: TokenizedCommandArgs = tokenizeCommandArgs(command, rawArgs),\n): Promise<ParsedCommand<S>> {\n  if (tokenized.issues.length > 0) {\n    throw new ZittyValidationError(\n      command,\n      tokenized.issues.map(({ issue }) => issue),\n    );\n  }\n\n  const input: Record<string, string | boolean | string[] | undefined> = {};\n  const positionals = commandPositionals(command);\n  const positionalValues: string[] = [];\n  if (positionals) input[POSITIONALS_KEY] = positionalValues;\n  const extraArgs: string[] = [];\n  for (const token of tokenized.tokens) {\n    if (token.kind === \"known-option\") input[token.definition.key] = token.value;\n    else if (token.kind === \"unknown-option\") extraArgs.push(token.value);\n    else if (\n      positionals &&\n      (positionals.rest || positionalValues.length < positionals.items.length)\n    ) {\n      positionalValues.push(token.value);\n    } else extraArgs.push(token.value);\n  }\n\n  if (!command.args)\n    return { args: input as output<S>, passthrough: tokenized.passthrough, extraArgs };\n  const result = await safeParseAsync(command.args, input);\n  if (!result.success)\n    throw new ZittyValidationError(command, zodIssues(command, result.error.issues));\n  return { args: result.data, passthrough: tokenized.passthrough, extraArgs };\n}\n\n/**\n * Parse and validate one command segment without routing, builtin handling, or output.\n */\nexport async function parseArgs<S extends ArgsSchema>(\n  command: CommandDef<S>,\n  argv: string[],\n): Promise<output<S>> {\n  return (await parseCommandArgs(command, argv)).args;\n}\n","import type { AnyCommandDef } from \"./command.ts\";\nimport { aliasList, kebabCase } from \"./options.ts\";\nimport { POSITIONALS_KEY, readArgInfo, readPositionals, schemaShape } from \"./schema.ts\";\n\nfunction details(\n  description: string | undefined,\n  required: boolean,\n  defaultValue: unknown,\n  choices: readonly string[] | undefined,\n): string {\n  const parts = [description];\n  if (choices) parts.push(`(Choices: ${choices.join(\", \")})`);\n  if (required) parts.push(\"(Required)\");\n  if (defaultValue !== undefined) parts.push(`(Default: ${formatDefault(defaultValue)})`);\n  return parts.filter(Boolean).join(\" \");\n}\n\nfunction formatDefault(value: unknown): string {\n  if (typeof value === \"string\") return value;\n  if (typeof value === \"number\" || typeof value === \"boolean\" || typeof value === \"bigint\") {\n    return value.toString();\n  }\n  if (value === null) return \"null\";\n  return JSON.stringify(value) ?? \"undefined\";\n}\n\nfunction heading(command: AnyCommandDef): string | undefined {\n  const identity = command.name\n    ? `${command.name}${command.version ? ` v${command.version}` : \"\"}`\n    : command.version\n      ? `v${command.version}`\n      : undefined;\n  if (command.description && identity) return `${command.description} (${identity})`;\n  return command.description ?? identity;\n}\n\nfunction formatUsage(command: AnyCommandDef): string {\n  const lines: string[] = [];\n  const title = heading(command);\n  if (title) lines.push(title, \"\");\n\n  const shape = command.args ? schemaShape(command.args) : {};\n  const positionals = readPositionals(shape);\n  const items = positionals?.items ?? [];\n  const rest = positionals?.rest;\n  const syntax = items.map(({ schema, label }) =>\n    readArgInfo(schema).required ? `<${label}>` : `[${label}]`,\n  );\n  if (rest) syntax.push(`[${rest.label}...]`);\n  if (command.subCommands && Object.keys(command.subCommands).length > 0) syntax.push(\"<COMMAND>\");\n  lines.push(\n    `USAGE ${command.name ?? \"command\"} [OPTIONS]${syntax.length ? ` ${syntax.join(\" \")}` : \"\"}`,\n  );\n\n  if (items.length > 0 || rest) {\n    lines.push(\"\", \"ARGUMENTS\", \"\");\n    for (const { schema, label } of items) {\n      const info = readArgInfo(schema);\n      lines.push(\n        `  ${label}  ${details(info.description, info.required, info.defaultValue, info.choices)}`.trimEnd(),\n      );\n    }\n    if (rest) {\n      const info = readArgInfo(rest.schema);\n      lines.push(\n        `  ${rest.label}...  ${details(info.description, false, undefined, info.choices)}`.trimEnd(),\n      );\n    }\n  }\n\n  const options = Object.entries(shape).filter(([key]) => key !== POSITIONALS_KEY);\n  if (options.length > 0) {\n    lines.push(\"\", \"OPTIONS\", \"\");\n    for (const [key, schema] of options) {\n      const info = readArgInfo(schema);\n      const argOptions = command.argOptions?.[key];\n      const prefix = argOptions?.alias\n        ? `${aliasList(argOptions.alias)\n            .map((item) => `-${item}`)\n            .join(\", \")}, `\n        : \"\";\n      const valueName = argOptions?.valueName ?? kebabCase(key);\n      const long = `--${kebabCase(key)}${info.takesValue ? `=<${valueName}>` : \"\"}`;\n      lines.push(\n        `  ${prefix}${long}  ${details(info.description, info.required, info.defaultValue, info.choices)}`.trimEnd(),\n      );\n      if (!info.takesValue && argOptions?.negatedDescription) {\n        lines.push(`  --no-${kebabCase(key)}  ${argOptions.negatedDescription}`);\n      }\n    }\n  }\n\n  const visibleSubCommands = Object.entries(command.subCommands ?? {}).filter(\n    ([, child]) => !child.hidden,\n  );\n  if (visibleSubCommands.length > 0) {\n    lines.push(\"\", \"COMMANDS\", \"\");\n    for (const [name, child] of visibleSubCommands) {\n      lines.push(`  ${name}  ${child.description ?? \"\"}`.trimEnd());\n    }\n  }\n  return lines.join(\"\\n\");\n}\n\nexport type UsageWriter = (text: string) => void | Promise<void>;\n\nexport interface ShowUsageOptions {\n  write?: UsageWriter;\n}\n\nexport type UsageOutput = Required<Pick<ShowUsageOptions, \"write\">>;\n\nexport type ShowUsageCallback = (\n  command: AnyCommandDef,\n  output: UsageOutput,\n) => void | Promise<void>;\n\n/** Generate usage text without writing to stdout or stderr. */\nexport async function renderUsage(command: AnyCommandDef): Promise<string> {\n  return formatUsage(command);\n}\n\n/** Generate and write usage text, awaiting asynchronous writers. */\nexport async function showUsage(\n  command: AnyCommandDef,\n  options: ShowUsageOptions = {},\n): Promise<void> {\n  const text = await renderUsage(command);\n  return (options.write ?? console.log)(text);\n}\n","import type { ArgsSchema } from \"./schema.ts\";\nimport type { AnyCommandDef, CommandDef } from \"./command.ts\";\nimport { ZittyUsageError } from \"./errors.ts\";\nimport {\n  parseCommandArgs,\n  tokenizedBefore,\n  tokenizeCommandArgs,\n  type TokenizedCommandArgs,\n} from \"./parser.ts\";\nimport { showUsage, type ShowUsageCallback } from \"./usage.ts\";\n\ninterface CommandSegment {\n  command: AnyCommandDef;\n  rawArgs: string[];\n  tokenized: TokenizedCommandArgs;\n}\n\ninterface ResolvedCommand extends CommandSegment {\n  parents: CommandSegment[];\n  segments: CommandSegment[];\n}\n\nfunction namedChild(child: AnyCommandDef, name: string): AnyCommandDef {\n  return child.name ? child : { ...child, name };\n}\n\nfunction resolveCommand(root: AnyCommandDef, rawArgs: string[]): ResolvedCommand {\n  let command = root;\n  let remaining = rawArgs;\n  const parents: ResolvedCommand[\"parents\"] = [];\n  const segments: ResolvedCommand[\"segments\"] = [];\n\n  for (;;) {\n    const tokenized = tokenizeCommandArgs(command, remaining);\n    const index = command.subCommands\n      ? tokenized.tokens.find((token) => token.kind === \"positional\")?.index\n      : undefined;\n    if (index === undefined) {\n      const segment = { command, rawArgs: remaining, tokenized };\n      segments.push(segment);\n      return { ...segment, parents, segments };\n    }\n    const name = remaining[index]!;\n    const child = command.subCommands?.[name];\n    if (!child) throw new ZittyUsageError(`Unknown command \\`${name}\\``, command);\n    const prefix = remaining.slice(0, index);\n    const segment = { command, rawArgs: prefix, tokenized: tokenizedBefore(tokenized, index) };\n    parents.push(segment);\n    segments.push(segment);\n    command = namedChild(child, name);\n    remaining = remaining.slice(index + 1);\n  }\n}\n\nasync function executeCommand<S extends ArgsSchema>(\n  root: CommandDef<S>,\n  argv: string[],\n  displayUsage: ShowUsageCallback,\n): Promise<unknown> {\n  const resolved = resolveCommand(root, argv);\n  if (resolved.segments[0]?.tokenized.version) {\n    console.log(root.version ?? \"\");\n    return undefined;\n  }\n  if (resolved.segments.some(({ tokenized }) => tokenized.help)) {\n    await displayUsage(resolved.command, { write: (text) => console.log(text) });\n    return undefined;\n  }\n\n  for (const parent of resolved.parents) {\n    await parseCommandArgs(parent.command, parent.rawArgs, parent.tokenized);\n  }\n  const parsed = await parseCommandArgs(resolved.command, resolved.rawArgs, resolved.tokenized);\n  if (!resolved.command.run) {\n    throw new ZittyUsageError(\"No command specified\", resolved.command);\n  }\n  return resolved.command.run({ ...parsed, cmd: resolved.command, rawArgs: resolved.rawArgs });\n}\n\nexport async function runCommand<S extends ArgsSchema>(\n  root: CommandDef<S>,\n  argv: string[],\n): Promise<unknown> {\n  return executeCommand(root, argv, showUsage);\n}\n\nexport interface RunMainOptions {\n  onError?: (error: unknown) => void | Promise<void>;\n  argv?: string[];\n  showUsage?: ShowUsageCallback;\n}\n\nexport async function runMain<S extends ArgsSchema>(\n  command: CommandDef<S>,\n  options: RunMainOptions = {},\n): Promise<void> {\n  const displayUsage = options.showUsage ?? showUsage;\n  try {\n    await executeCommand(command, options.argv ?? process.argv.slice(2), displayUsage);\n  } catch (error) {\n    if (options.onError) {\n      await options.onError(error);\n      process.exit(1);\n    }\n    try {\n      if (error instanceof ZittyUsageError) {\n        console.error(error.message);\n        await displayUsage(error.command, { write: (text) => console.error(text) });\n      } else {\n        console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);\n      }\n    } finally {\n      process.exit(1);\n    }\n  }\n}\n\nexport function createMain<S extends ArgsSchema>(\n  command: CommandDef<S>,\n  options: RunMainOptions = {},\n): (argv?: string[]) => Promise<void> {\n  return (argv) => runMain(command, argv === undefined ? options : { ...options, argv });\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "hacksh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "@vitest/coverage-v8": "4.1.10",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
+    "vite-plus": "0.2.8",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.20.0",
+      "onFail": "download"
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "check": "vp check",
+    "test": "vp test",
+    "test:packed": "node scripts/test-packed-consumers.mjs",
+    "ready": "vp run check && vp run test && vp run build"
+  }
 }