hanzio 3.1.1 → 3.3.0

package/src/cli/README.md

@@ -6,7 +6,8 @@ description: Typed CLIs from Zod object schemas, parsed with node:util parseArgs
 
 Each command's `input` is a Zod object: its keys become flags, Zod validates
 them, and `run` gets the typed result. Parsing is `node:util` `parseArgs`, so
-there is no extra dependency. Runs in Bun and Node 22.4+; needs `zod` 4.
+there is no extra dependency. Runs in Bun and Node 22.4+. Commands with an
+`input` need `zod` 4; a CLI made only of `raw` commands loads without it.
 
 ```ts
 // src/cli.ts
@@ -51,20 +52,27 @@ handles would keep the process alive.
 | `z.string()`, `z.enum([...])` | `--name value` or `--name=value` |
 | `z.number()` | `--repeats 3`, coerced before validation |
 | `z.boolean()` | `--json`; `--no-json` sets `false`; missing is `false` |
+| `noWatch: z.boolean()` | its own flag `--no-watch`, not `--watch` negated |
 | `z.array(z.string())` | repeatable: `--model a --model b`; missing is `[]` |
+| `z.union([z.boolean(), z.string()])` | `--expose` is `true`, `--expose=api,web` is the string |
 | `.optional()`, `.default(x)` | may be left out |
 | `.describe('…')` | help text |
 | `.meta({ positional: true })` | positional, in key order; an array takes the rest |
-| `.meta({ alias: 'r' })` | `-r value` |
-| `.meta({ env: 'APP_REGION' })` | read from the environment when the flag is missing |
+| `.meta({ alias: 'r' })` | `-r value`; longer aliases are flags: `alias: ['r', 'region-name']` |
+| `.meta({ env: 'APP_REGION' })` | read from the environment when the flag is missing; a list is tried in order, and blank values count as unset |
 
 Keys are camelCase in the schema and kebab-case on the command line (`dryRun`
 → `--dry-run`). These are the same `.meta()` keys as `trpc-cli`, plus `env`;
 importing `hanzio/cli` types them on Zod's `GlobalMeta`.
 Pipes read their input side, so `z.stringbool()` takes `--submit true`.
 
-Every CLI gets `-h`/`--help` (root, groups and commands), `--version` when you
-pass `version`, and "Did you mean …?" for mistyped commands and flags.
+Every CLI gets `-h`/`--help` (root, groups and commands), `--version` and
+`-v` when you pass `version`, and "Did you mean …?" for mistyped commands and
+flags. A root command named `version` also answers `--version` and `-v`, so it
+decides the format (`tool v1.2.3`).
+
+`defineCommand({ strict: false })` ignores unknown flags and extra
+positionals instead of exiting 2.
 
 ## Commands
 
@@ -82,6 +90,30 @@ A command is one of:
 - `defineCommand({ raw: true, run })`, which skips parsing: every argument
   after the command name is in `ctx.argv` (for `tool prisma migrate dev`).
 
+The first line of `description` is the command's summary in command lists;
+its help shows all of it. `usage: '[name...] [--all]'` replaces the generated
+arguments in both, and `examples: ['tool stop api']` adds an Examples section
+to its help.
+
+```ts
+defineCli({
+	name: 'evals',
+	defaultCommand: 'run', // `evals` and `evals --case x` run `evals run`
+	commands: { run, inspect }
+})
+```
+
+`defaultCommand` runs when no command name is given, or when the first
+argument is a flag that isn't a global. Pass a function to read it from the
+environment: `defaultCommand: (env) => env.RELEASE_COMMAND`.
+
+`unknownCommand: (name, path) => node` resolves a name the group doesn't
+have, for commands that come from config. Return `undefined` for the usual
+"Unknown command" error.
+
+`help: (text, { path }) => text` rewrites every help screen (`path` is `[]`
+for the root), to add sections such as the tasks a config defines.
+
 `run(input, ctx)` gets:
 
 | `ctx` | |
@@ -118,7 +150,9 @@ const cli = defineCli({
 })
 ```
 
-Globals are accepted before or after the command names. `context` runs after
+Globals are accepted before or after the command names. A positional global
+comes before the first command name, so `globals: z.object({ module:
+z.string().meta({ positional: true }) })` reads `tool ./app.ts list`. `context` runs after
 parsing, so `--help` never connects anywhere. `guard` runs before every
 command. A command defined in its own file types its context by annotating
 `ctx`:
@@ -151,6 +185,29 @@ message is printed without a stack. Other errors print their stack. With
 Run "better-mastra-evals run --help" for usage.
 ```
 
+`onError(error, io)` sees every error first. Return the exit code, or
+`undefined` for the default output; `io.print()` writes that output and
+returns its code. Usage errors are `CliUsageError`s with a `kind`
+(`missing-command`, `unknown-command`, `invalid-arguments`), the command
+`path`, and the `help` for it:
+
+```ts
+defineCli({
+	name: 'tool',
+	commands,
+	onError: (error, io) => {
+		// Help instead of an error when run without a command.
+		if (error instanceof CliUsageError && error.kind === 'missing-command') {
+			io.stdout.write(error.help)
+			return 0
+		}
+		// Keep the message, but exit 1 on bad arguments.
+		const code = io.print()
+		return code === 2 ? 1 : code
+	}
+})
+```
+
 ## Shell completion
 
 A CLI with commands also gets `tool completion bash` and `tool completion

package/src/cli/fields.ts

@@ -1,9 +1,21 @@
-import { z } from 'zod'
+import type { z } from 'zod'
 import { unwrapOnce } from '../zod/introspect'
-import { defOf, type Schema } from '../zod/zodToTypeString'
+import { type Def, defOf, type Schema } from '../zod/zodToTypeString'
 
-/** Thrown for bad argv. The CLI prints it with a `--help` hint and exits 2. */
-export class UsageError extends Error {}
+// No runtime `zod` import: a CLI made only of raw commands loads without it.
+
+/** Thrown for bad argv; `cli.run()` turns it into a `CliUsageError`. */
+export class UsageError extends Error {
+	constructor(
+		message: string,
+		readonly kind:
+			| 'missing-command'
+			| 'unknown-command'
+			| 'invalid-arguments' = 'invalid-arguments'
+	) {
+		super(message)
+	}
+}
 
 /** One key of an input or globals object, read as a flag or a positional. */
 export type Field = {
@@ -16,11 +28,53 @@ export type Field = {
 	hasDefault: boolean
 	defaultValue: unknown
 	description?: string
+	/** One-letter short flag. */
 	alias?: string
-	env?: string
+	/** Extra long flag names, from multi-character aliases. */
+	aliases: string[]
+	env: string[]
+	/** `--name` alone is `true`, `--name=value` is the value. */
+	optionalValue: boolean
 	choices?: string[]
 }
 
+/** The `parseArgs` option name. A `noX` key is its own flag, never `--x` negated. */
+export const optionName = (field: Field) =>
+	field.flag.startsWith('no-') ? field.key : field.flag
+
+const strings = (value: unknown, what: string, key: string): string[] => {
+	const list = value === undefined ? [] : Array.isArray(value) ? value : [value]
+	if (list.some((item) => typeof item !== 'string' || !item))
+		throw new Error(
+			`hanzio/cli: ${what} ${JSON.stringify(value)} of "${key}" must be a string or string[]`
+		)
+	return list
+}
+
+const kindOf = (def: Def) =>
+	def.type === 'boolean'
+		? 'boolean'
+		: def.type === 'number'
+			? 'number'
+			: 'string'
+
+function choicesOf(def: Def): string[] | undefined {
+	if (def.type === 'enum') return Object.values(def.entries).map(String)
+	if (def.type === 'literal') return def.values.map(String)
+	return undefined
+}
+
+// `z.union([z.boolean(), z.string()])` (or `z.literal(true)`): an optional value.
+function optionalValueOf(def: Def): Def | undefined {
+	if (def.type !== 'union' || def.options.length !== 2) return undefined
+	const [a, b] = def.options.map(defOf) as [Def, Def]
+	const flag = (d: Def) =>
+		d.type === 'boolean' || (d.type === 'literal' && d.values.includes(true))
+	if (flag(a) && kindOf(b) === 'string' && b.type !== 'literal') return b
+	if (flag(b) && kindOf(a) === 'string' && a.type !== 'literal') return a
+	return undefined
+}
+
 const kebab = (key: string) =>
 	key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
 
@@ -37,7 +91,10 @@ function toField(key: string, schema: Schema): Field {
 	let defaultValue: unknown
 	let current = schema
 	for (;;) {
-		const meta = z.globalRegistry.get(current)
+		// `.meta()` with no argument reads Zod's global registry.
+		const meta = (
+			current as { meta?: () => Record<string, unknown> | undefined }
+		).meta?.()
 		if (meta) metas.unshift(meta)
 		const def = defOf(current)
 		if (def.type === 'optional') optional = true
@@ -61,20 +118,12 @@ function toField(key: string, schema: Schema): Field {
 		}
 		def = defOf(element)
 	}
-	const alias = meta.alias
-	if (alias !== undefined && (typeof alias !== 'string' || alias.length !== 1))
-		throw new Error(
-			`hanzio/cli: alias ${JSON.stringify(alias)} of "${key}" must be one character`
-		)
+	const valueDef = multiple ? undefined : optionalValueOf(def)
+	const names = strings(meta.alias, 'alias', key)
 	return {
 		key,
 		flag: kebab(key),
-		kind:
-			def.type === 'boolean'
-				? 'boolean'
-				: def.type === 'number'
-					? 'number'
-					: 'string',
+		kind: valueDef ? 'string' : kindOf(def),
 		multiple,
 		positional: meta.positional === true,
 		optional,
@@ -82,14 +131,11 @@ function toField(key: string, schema: Schema): Field {
 		defaultValue,
 		description:
 			typeof meta.description === 'string' ? meta.description : undefined,
-		alias,
-		env: typeof meta.env === 'string' ? meta.env : undefined,
-		choices:
-			def.type === 'enum'
-				? Object.values(def.entries).map(String)
-				: def.type === 'literal'
-					? def.values.map(String)
-					: undefined
+		alias: names.find((name) => name.length === 1),
+		aliases: names.filter((name) => name.length > 1).map(kebab),
+		env: strings(meta.env, 'env', key),
+		optionalValue: valueDef !== undefined,
+		choices: choicesOf(valueDef ?? def)
 	}
 }
 
@@ -108,14 +154,16 @@ function coerce(field: Field, value: string | boolean): unknown {
 
 /**
  * Builds the raw object Zod validates: flag values and positionals by key,
- * numbers coerced, `.meta({ env })` as fallback, and a missing required
- * boolean or array read as `false` or `[]`.
+ * numbers coerced, `.meta({ env })` as fallback (blank variables count as
+ * unset), and a missing required boolean or array read as `false` or `[]`.
+ * Extra positionals are a usage error unless `strict` is false.
  */
 export function readFields(
 	fields: Field[],
 	values: Record<string, string | boolean | (string | boolean)[] | undefined>,
 	positionals: string[],
-	env: Record<string, string | undefined>
+	env: Record<string, string | undefined>,
+	strict = true
 ): Record<string, unknown> {
 	const result: Record<string, unknown> = {}
 	const queue = [...positionals]
@@ -127,11 +175,13 @@ export function readFields(
 					? queue.splice(0)
 					: undefined
 				: queue.shift()
-		else raw = values[field.flag]
-		if (raw === undefined && field.env && env[field.env] !== undefined) {
-			const value = env[field.env] as string
-			raw = field.multiple ? [value] : value
-		}
+		else raw = values[optionName(field)]
+		if (field.optionalValue && raw === '') raw = true
+		const value =
+			raw === undefined
+				? field.env.map((name) => env[name]).find((value) => value?.trim())
+				: undefined
+		if (value !== undefined) raw = field.multiple ? [value] : value
 		if (raw === undefined) {
 			if (field.optional || field.hasDefault) continue
 			if (field.multiple) raw = []
@@ -142,7 +192,8 @@ export function readFields(
 			? raw.map((item) => coerce(field, item))
 			: coerce(field, raw)
 	}
-	if (queue.length) throw new UsageError(`Unexpected argument "${queue[0]}"`)
+	if (strict && queue.length)
+		throw new UsageError(`Unexpected argument "${queue[0]}"`)
 	return result
 }
 
@@ -154,14 +205,20 @@ export function fieldLabel(field: Field): string {
 				? `[${field.flag}]`
 				: `<${field.flag}>`
 	const name =
-		field.kind === 'boolean' && field.defaultValue === true
+		field.kind === 'boolean' &&
+		field.defaultValue === true &&
+		!field.flag.startsWith('no-')
 			? `--[no-]${field.flag}`
 			: `--${field.flag}`
+	const type = `<${field.choices?.join('|') ?? field.kind}>`
 	const value =
 		field.kind === 'boolean'
 			? ''
-			: ` <${field.choices?.join('|') ?? field.kind}>${field.multiple ? '...' : ''}`
-	return `${field.alias ? `-${field.alias}, ` : ''}${name}${value}`
+			: field.optionalValue
+				? `[=${type}]`
+				: ` ${type}${field.multiple ? '...' : ''}`
+	const aliases = field.aliases.map((alias) => `, --${alias}`).join('')
+	return `${field.alias ? `-${field.alias}, ` : ''}${name}${aliases}${value}`
 }
 
 export function fieldHelp(field: Field): string {
@@ -172,7 +229,7 @@ export function fieldHelp(field: Field): string {
 	return [
 		field.description,
 		showDefault && `(default: ${JSON.stringify(field.defaultValue)})`,
-		field.env && `[env: ${field.env}]`
+		field.env.length > 0 && `[env: ${field.env.join(', ')}]`
 	]
 		.filter(Boolean)
 		.join(' ')