hanzio 3.2.0 → 3.3.0

package/dist/redis/concurrency-limit.d.ts

@@ -8,10 +8,19 @@ export type RedisConcurrencyLimitOptions = {
     maxStartsPerSecond?: number;
     failOpenAfterMs?: number;
     commandTimeoutMs?: number;
-    /** Receives throttled warnings. Defaults to `console`. */
-    logger?: Pick<Console, 'warn'>;
+    /** Receives throttled warnings with `{ key, error }`. Defaults to `console`. */
+    logger?: {
+        warn(message: string, attributes: Record<string, unknown>): void;
+    };
+    /** The label `onWait` and `onQueueDepth` report under. Default: `key`. */
+    metricLabel?: string;
     /** Called when a caller starts queueing; the returned function runs once it stops. */
-    onWait?: (stage: ConcurrencyLimitStage) => (() => void) | void;
+    onWait?: (stage: ConcurrencyLimitStage, metricLabel: string) => (() => void) | void;
+    /**
+     * Called once with `queueDepth`, to register a gauge; the returned function
+     * runs on `dispose()`.
+     */
+    onQueueDepth?: (queueDepth: () => number, metricLabel: string) => (() => void) | void;
 };
 export type RedisConcurrencyLimit = {
     <T>(run: () => Promise<T>, signal?: AbortSignal): Promise<T>;
@@ -46,10 +55,11 @@ export type RedisConcurrencyLimit = {
  * That verdict is shared per limiter: once tripped, later calls degrade
  * immediately while a background probe watches for Redis to come back.
  *
- * `onWait` and `queueDepth` feed metrics. A limiter minted per tenant or per
- * customer host should report under a shared pool label rather than its key,
- * or every key ever touched leaves a permanent series. Call `dispose()` when
- * such a limiter is discarded, and unregister any gauge reading `queueDepth`.
+ * `onWait` and `onQueueDepth` feed metrics under `metricLabel`. A limiter
+ * minted per tenant or per customer host should share one pool label rather
+ * than default to its key, or every key ever touched leaves a permanent
+ * series. Call `dispose()` when such a limiter is discarded; it also runs the
+ * unregister function `onQueueDepth` returned.
  *
  * @example
  * const withLimit = createRedisConcurrencyLimit({

package/dist/src/cli/index.js

@@ -1,10 +1,12 @@
 import {
   CliError2,
+  CliUsageError2,
   defineCommand2,
   defineCli2
-} from "../../index-nfvq3zax.js";
+} from "../../index-818f7jz4.js";
 export {
   CliError2 as CliError,
+  CliUsageError2 as CliUsageError,
   defineCli2 as defineCli,
   defineCommand2 as defineCommand
 };

package/dist/src/crypto/index.js

@@ -1,3 +1,11 @@
+import {
+  SealerError2,
+  sealerKeyInputs2,
+  formatEnvelope2,
+  parseEnvelope2,
+  jsonToSeal2,
+  createSealer2
+} from "../../index-zz773050.js";
 import {
   utf8Encode2,
   utf8Decode2,
@@ -7,117 +15,14 @@ import {
   decodeBase64Url2,
   bytesToHex2,
   hexToBytes2,
-  toBytes,
   safeEqual2,
   randomBytes2,
   randomToken2,
   sha2562,
   sha256Hex2,
   hmacSign2,
-  verifyHmacSignature2,
-  getSubtleCrypto
+  verifyHmacSignature2
 } from "../../index-rp5pqghz.js";
-// src/crypto/sealer.ts
-var ERROR_MESSAGES = {
-  malformed: "Malformed sealed value",
-  unsupported_version: "Unsupported sealed value version",
-  decrypt_failed: "Could not open sealed value: wrong key or tampered data"
-};
-
-class SealerError extends Error {
-  code;
-  constructor(code) {
-    super(ERROR_MESSAGES[code]);
-    this.name = "SealerError";
-    this.code = code;
-  }
-}
-var PREFIX = "enc:v1:";
-var IV_BYTES = 12;
-var TAG_BYTES = 16;
-var DEFAULT_INFO = "hanzio.sealer.aes-256-gcm.v1";
-function createSealer(options) {
-  const { secret, salt = "", info = DEFAULT_INFO } = options;
-  const secretBytes = toBytes(secret);
-  if (secretBytes.length === 0) {
-    throw new TypeError("Sealer secret must not be empty");
-  }
-  let keyPromise;
-  const getKey = () => {
-    if (!keyPromise) {
-      keyPromise = deriveKey(secretBytes, salt, info);
-      keyPromise.catch(() => {
-        keyPromise = undefined;
-      });
-    }
-    return keyPromise;
-  };
-  const seal = async (plaintext) => {
-    const iv = randomBytes2(IV_BYTES);
-    const encrypted = new Uint8Array(await getSubtleCrypto().encrypt({ name: "AES-GCM", iv }, await getKey(), utf8Encode2(plaintext)));
-    const tagStart = encrypted.length - TAG_BYTES;
-    return `${PREFIX}${encodeBase64Url2(iv)}.${encodeBase64Url2(encrypted.subarray(tagStart))}.${encodeBase64Url2(encrypted.subarray(0, tagStart))}`;
-  };
-  const open = async (sealed) => {
-    if (typeof sealed !== "string" || !sealed.startsWith(PREFIX)) {
-      const isOtherVersion = typeof sealed === "string" && /^enc:v\d+:/.test(sealed);
-      throw new SealerError(isOtherVersion ? "unsupported_version" : "malformed");
-    }
-    const parts = sealed.slice(PREFIX.length).split(".");
-    let iv;
-    let tag;
-    let ciphertext;
-    try {
-      if (parts.length !== 3)
-        throw new Error;
-      iv = decodeBase64Url2(parts[0]);
-      tag = decodeBase64Url2(parts[1]);
-      ciphertext = decodeBase64Url2(parts[2]);
-    } catch (_error) {
-      throw new SealerError("malformed");
-    }
-    if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
-      throw new SealerError("malformed");
-    }
-    const encrypted = new Uint8Array(ciphertext.length + TAG_BYTES);
-    encrypted.set(ciphertext);
-    encrypted.set(tag, ciphertext.length);
-    const key = await getKey();
-    let plaintext;
-    try {
-      plaintext = await getSubtleCrypto().decrypt({ name: "AES-GCM", iv }, key, encrypted);
-    } catch (_error) {
-      throw new SealerError("decrypt_failed");
-    }
-    return utf8Decode2(plaintext);
-  };
-  return {
-    seal,
-    open,
-    async sealJson(value) {
-      const json = JSON.stringify(value);
-      if (json === undefined) {
-        throw new TypeError("sealJson value is not JSON-serializable");
-      }
-      return seal(json);
-    },
-    async openJson(sealed) {
-      return JSON.parse(await open(sealed));
-    }
-  };
-}
-async function deriveKey(secret, salt, info) {
-  const subtle = getSubtleCrypto();
-  const baseKey = await subtle.importKey("raw", secret, "HKDF", false, [
-    "deriveKey"
-  ]);
-  return subtle.deriveKey({
-    name: "HKDF",
-    hash: "SHA-256",
-    salt: utf8Encode2(salt),
-    info: utf8Encode2(info)
-  }, baseKey, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
-}
 // src/crypto/webhook.ts
 var TIMESTAMP = /^\d+$/;
 async function verifySvixSignature(options) {
@@ -174,18 +79,22 @@ function readHeader(headers, name) {
   return;
 }
 export {
-  SealerError,
+  SealerError2 as SealerError,
   bytesToHex2 as bytesToHex,
-  createSealer,
+  createSealer2 as createSealer,
   decodeBase642 as decodeBase64,
   decodeBase64Url2 as decodeBase64Url,
   encodeBase642 as encodeBase64,
   encodeBase64Url2 as encodeBase64Url,
+  formatEnvelope2 as formatEnvelope,
   hexToBytes2 as hexToBytes,
   hmacSign2 as hmacSign,
+  jsonToSeal2 as jsonToSeal,
+  parseEnvelope2 as parseEnvelope,
   randomBytes2 as randomBytes,
   randomToken2 as randomToken,
   safeEqual2 as safeEqual,
+  sealerKeyInputs2 as sealerKeyInputs,
   sha2562 as sha256,
   sha256Hex2 as sha256Hex,
   utf8Decode2 as utf8Decode,

package/dist/src/crypto/node.js

@@ -0,0 +1,67 @@
+import {
+  SealerError2,
+  sealerKeyInputs2,
+  formatEnvelope2,
+  parseEnvelope2,
+  jsonToSeal2
+} from "../../index-zz773050.js";
+
+// src/crypto/node.ts
+import {
+  createCipheriv,
+  createDecipheriv,
+  hkdfSync,
+  randomBytes
+} from "node:crypto";
+var ALGORITHM = "aes-256-gcm";
+function createSealerSync(options) {
+  const { secret, contexts } = sealerKeyInputs2(options);
+  const keys = [];
+  const getKey = (index) => {
+    let key = keys[index];
+    if (!key) {
+      const { salt, info } = contexts[index];
+      key = Buffer.from(hkdfSync("sha256", secret, salt, info, 32));
+      keys[index] = key;
+    }
+    return key;
+  };
+  const seal = (plaintext) => {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv(ALGORITHM, getKey(0), iv);
+    const ciphertext = Buffer.concat([
+      cipher.update(plaintext, "utf8"),
+      cipher.final()
+    ]);
+    return formatEnvelope2(iv, cipher.getAuthTag(), ciphertext);
+  };
+  const openEnvelope = ({ iv, tag, ciphertext }) => {
+    for (let index = 0;index < contexts.length; index++) {
+      try {
+        const decipher = createDecipheriv(ALGORITHM, getKey(index), iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([
+          decipher.update(ciphertext),
+          decipher.final()
+        ]).toString("utf8");
+      } catch (_error) {}
+    }
+    throw new SealerError2("decrypt_failed");
+  };
+  return {
+    seal,
+    open(sealed) {
+      const envelope = parseEnvelope2(sealed, options.passthroughUnsealed);
+      return envelope ? openEnvelope(envelope) : sealed;
+    },
+    sealJson: (value) => seal(jsonToSeal2(value)),
+    openJson(sealed) {
+      const envelope = parseEnvelope2(sealed, options.passthroughUnsealed);
+      return envelope ? JSON.parse(openEnvelope(envelope)) : sealed;
+    }
+  };
+}
+export {
+  SealerError2 as SealerError,
+  createSealerSync
+};

package/dist/src/i18n/cli.js

@@ -3,7 +3,7 @@ import {
   CliError2,
   defineCommand2,
   defineCli2
-} from "../../index-nfvq3zax.js";
+} from "../../index-818f7jz4.js";
 import"../../index-najbyzpr.js";
 import {
   validateCatalogs2,

package/dist/src/redis/index.js

@@ -315,6 +315,7 @@ function createRedisConcurrencyLimit(input) {
   if (!Number.isInteger(input.max) || input.max < 1)
     throw new Error(`max must be a positive integer, got ${input.max}`);
   const logger = input.logger ?? console;
+  const metricLabel = input.metricLabel ?? input.key;
   const commandTimeoutMs = input.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
   const send = withCommandTimeout(input.send, commandTimeoutMs);
   const ttlMs = String(input.slotTtlMs);
@@ -435,7 +436,7 @@ function createRedisConcurrencyLimit(input) {
     return {
       depth: () => queue.length,
       acquire(token) {
-        const stopWait = input.onWait?.(stage);
+        const stopWait = input.onWait?.(stage, metricLabel);
         const granted = new Promise((resolve) => {
           queue.push({ token, settle: resolve });
         });
@@ -451,6 +452,7 @@ function createRedisConcurrencyLimit(input) {
   const slotPump = createPump("slot", input.max, async (tokens) => parseGrantReply(await acquireScript([inflightKey, cooldownKey], [String(input.max), ttlMs, ...tokens])));
   const startPump = maxStartsPerSecond === undefined ? null : createPump("start", maxStartsPerSecond, async (tokens) => parseGrantReply(await startScript([startsKey, cooldownKey], [String(maxStartsPerSecond), String(START_WINDOW_MS), ...tokens])));
   const queueDepth = () => slotPump.depth() + (startPump?.depth() ?? 0);
+  let unregisterQueueDepth = input.onQueueDepth?.(queueDepth, metricLabel);
   const heldTokens = new Set;
   let heartbeatTimer = null;
   function scheduleHeartbeat() {
@@ -555,6 +557,8 @@ function createRedisConcurrencyLimit(input) {
     }
   }
   function dispose() {
+    unregisterQueueDepth?.();
+    unregisterQueueDepth = undefined;
     if (probeTimer) {
       clearTimeout(probeTimer);
       probeTimer = null;

package/dist/src/testing/index.js

@@ -205,11 +205,30 @@ function mockCallArg(fn, callIndex = 0, argIndex = 0) {
   return fn.mock.calls[callIndex]?.[argIndex];
 }
 // src/testing/module-mocker.ts
+import { isAbsolute } from "node:path";
+function resolveFrom(baseDir) {
+  return (specifier) => {
+    if (isAbsolute(specifier))
+      return specifier;
+    if (specifier.startsWith("."))
+      return Bun.resolveSync(specifier, baseDir);
+    try {
+      return Bun.resolveSync(specifier, baseDir);
+    } catch (error) {
+      try {
+        return Bun.resolveSync(`./${specifier}`, baseDir);
+      } catch {
+        throw error;
+      }
+    }
+  };
+}
+
 class ModuleMocker {
-  resolve;
   restorers = [];
-  constructor(resolve = (specifier) => specifier) {
-    this.resolve = resolve;
+  resolve;
+  constructor(baseDirOrResolve = (specifier) => specifier) {
+    this.resolve = typeof baseDirOrResolve === "string" ? resolveFrom(baseDirOrResolve) : baseDirOrResolve;
   }
   async mock(specifier, renderMocks) {
     const { mock } = await import("bun:test");
@@ -222,7 +241,7 @@ class ModuleMocker {
     });
   }
   clear() {
-    for (const restore of this.restorers)
+    for (const restore of this.restorers.toReversed())
       restore();
     this.restorers = [];
   }

package/dist/string/index.d.ts

@@ -3,7 +3,7 @@ export type JsonValue = string | number | boolean | null | JsonObject | JsonArra
 export type JsonObject = {
     [key: string]: JsonValue | undefined;
 };
-export type JsonArray = Array<JsonValue | undefined>;
+export type JsonArray = JsonValue[];
 /**
  * Parses the first number-like token in a string. Only a `-` directly before
  * the digits is a sign, so `'2024-01-05'` gives `2024`. Whitespace and the

package/dist/testing/module-mocker.d.ts

@@ -9,21 +9,21 @@ type ModuleExports = Record<string, unknown>;
  * keep working, and `clear()` re-registers the originals. Call it in
  * `afterEach` or `afterAll`.
  *
- * Bun resolves specifiers relative to the file that registers the mock, so
- * pass absolute paths or package names. A `resolve` function maps your own
- * shorthand (an `@/` alias, a source-root-relative path) to absolute paths.
+ * Without an argument, pass absolute paths. Pass your source root to resolve
+ * against it: package names from there (so mocks hit the same copy your code
+ * imports), and `./lib/x` or `lib/x` relative to it. A function maps your own
+ * shorthand, such as an `@/` alias, to absolute paths instead.
  *
  * @example
- * const moduleMocker = new ModuleMocker((specifier) =>
- *   specifier.startsWith('@/') ? path.resolve(srcDir, specifier.slice(2)) : specifier
- * )
- * await moduleMocker.mock('@/lib/posthog', () => ({ captureException: mock() }))
+ * const moduleMocker = new ModuleMocker(srcDir)
+ * await moduleMocker.mock('lib/posthog.ts', () => ({ captureException: mock() }))
+ * await moduleMocker.mock('ai', () => ({ generateText: mock() }))
  * afterAll(() => moduleMocker.clear())
  */
 export declare class ModuleMocker {
-    private readonly resolve;
     private restorers;
-    constructor(resolve?: (specifier: string) => string);
+    private readonly resolve;
+    constructor(baseDirOrResolve?: string | ((specifier: string) => string));
     mock(specifier: string, renderMocks: () => ModuleExports): Promise<void>;
     clear(): void;
 }

package/dist/testing/prisma.d.ts

@@ -1,5 +1,9 @@
 import type { Mock, mock } from 'bun:test';
-export type PrismaMethodMock = Mock<(...args: unknown[]) => Promise<unknown>>;
+/**
+ * `never[]` parameters let `mockImplementation` take a callback that types its
+ * arguments; the plain call signature keeps the mock callable with any.
+ */
+export type PrismaMethodMock = Mock<(...args: never[]) => Promise<unknown>> & ((...args: unknown[]) => Promise<unknown>);
 /**
  * A Prisma client where every model delegate and every method is a Bun mock,
  * created on first access, like `jest-mock-extended`'s `mockDeep()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanzio",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "A lightweight set of utility functions for TypeScript",
   "type": "module",
   "module": "./dist/src/index.js",
@@ -107,6 +107,12 @@
       "import": "./dist/src/crypto/index.js",
       "default": "./dist/src/crypto/index.js"
     },
+    "./crypto/node": {
+      "types": "./dist/crypto/node.d.ts",
+      "bun": "./src/crypto/node.ts",
+      "import": "./dist/src/crypto/node.js",
+      "default": "./dist/src/crypto/node.js"
+    },
     "./storage": {
       "types": "./dist/storage/index.d.ts",
       "bun": "./src/storage/index.ts",
@@ -194,7 +200,7 @@
   },
   "scripts": {
     "build": "rm -rf dist && bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/zod/index.ts ./src/api-wrapper/index.ts ./src/api-wrapper/testing.ts ./src/api-wrapper/connection-auth.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/cool-console-log/index.ts ./src/format/index.ts ./src/format/phone.ts ./src/crypto/index.ts ./src/storage/index.ts ./src/i18n/index.ts ./src/i18n/vue.ts ./src/i18n/i18next.ts ./src/i18n/vite.ts ./src/i18n/check.ts ./src/i18n/cli.ts ./src/iso/index.ts ./src/secrets/index.ts ./src/secrets/vite.ts ./src/secrets/worker.ts ./src/redis/index.ts ./src/http/index.ts ./src/cli/index.ts ./src/testing/index.ts --outdir ./dist --target node --packages external --splitting",
+    "build:js": "bun build ./src/index.ts ./src/zod/index.ts ./src/api-wrapper/index.ts ./src/api-wrapper/testing.ts ./src/api-wrapper/connection-auth.ts ./src/jwt/index.ts ./src/sitemap/index.ts ./src/p-queue/index.ts ./src/cool-console-log/index.ts ./src/format/index.ts ./src/format/phone.ts ./src/crypto/index.ts ./src/crypto/node.ts ./src/storage/index.ts ./src/i18n/index.ts ./src/i18n/vue.ts ./src/i18n/i18next.ts ./src/i18n/vite.ts ./src/i18n/check.ts ./src/i18n/cli.ts ./src/iso/index.ts ./src/secrets/index.ts ./src/secrets/vite.ts ./src/secrets/worker.ts ./src/redis/index.ts ./src/http/index.ts ./src/cli/index.ts ./src/testing/index.ts --outdir ./dist --target node --packages external --splitting",
     "build:types": "tsgo -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "test": "bun test",

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