@johannes.latzel/terminal 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Johannes B. Latzel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# Terminal
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![NPM](https://nodei.co/npm/@johannes.latzel/terminal.svg?style=shields&data=n,v,u,d,s)](https://www.npmjs.com/package/@johannes.latzel/terminal)
+[![version](https://img.shields.io/github/package-json/v/johanneslatzel/terminal)](https://github.com/johanneslatzel/terminal/releases)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue)](https://www.typescriptlang.org/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/johanneslatzel/terminal/pulls)
+[![Feedback Welcome](https://img.shields.io/badge/feedback-welcome-brightgreen)](https://github.com/johanneslatzel/terminal/discussions)
+[![codecov](https://codecov.io/gh/johanneslatzel/terminal/graph/badge.svg)](https://codecov.io/gh/johanneslatzel/terminal)
+[![CI](https://github.com/johanneslatzel/terminal/actions/workflows/ci.yml/badge.svg)](https://github.com/johanneslatzel/terminal/actions/workflows/ci.yml)
+[![Socket Badge](https://badge.socket.dev/npm/package/@johannes.latzel/terminal/latest)](https://badge.socket.dev/npm/package/@johannes.latzel/terminal/latest)
+
+Tree-structured TypeScript terminal/shell engine with automatic help, tab completion, `--flag` argument parsing, interactive prompting for missing required arguments, and a lifecycle hook system.
+
+## Prerequisites
+
+- Node.js >= 18
+
+## Installation
+
+```bash
+npm install @johannes.latzel/terminal
+```
+
+## Documentation
+
+Full documentation at **[johanneslatzel.github.io/terminal/](https://johanneslatzel.github.io/terminal/)**
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).
+
+## Contributing
+
+Issues and PRs welcome at [github.com/johanneslatzel/terminal](https://github.com/johanneslatzel/terminal).

package/dist/command-arguments.d.ts

@@ -0,0 +1,120 @@
+import * as readline from 'node:readline';
+import type { z } from 'zod';
+/** Describes a single command-line argument (`--name value`). */
+export interface CommandArgumentDefinition {
+    /** Argument name (without `--` prefix). */
+    name: string;
+    /** Human-readable description shown in help output. */
+    description?: string;
+    /** Whether the argument must always be provided. */
+    required?: boolean;
+    /** Zod schema describing the argument's expected type and constraints. */
+    schema: z.ZodType;
+    /** 0-based index for positional (bare token) arguments. */
+    position?: number;
+}
+/**
+ * Wraps a parsed argument record (`--name value` pairs) and provides
+ * typed accessors that validate and coerce values via the argument's
+ * {@link CommandArgumentDefinition} zod schema. When an argument is
+ * missing and a readline interface is available, the accessor prompts
+ * the user interactively.
+ *
+ * Every `require*` accessor requires a matching
+ * {@link CommandArgumentDefinition} to exist for the requested name.
+ * If no definition is found, an {@link InvalidArgumentsError} is thrown.
+ *
+ * ## Choosing an accessor
+ *
+ * | Accessor | When to use | Schema examples |
+ * |---|---|---|
+ * | `require<T>(name)` | Value arg that must be present (or prompted). The Zod schema handles all parsing. | `z.coerce.number()`, `z.string().min(1)`, `z.enum([...])` |
+ * | `flag(name)` | CLI flag with `--flag` / `--flag false` semantics. Absent → `false`. | `z.boolean()`, `z.literal(true)` |
+ *
+ * Don't use `z.coerce.boolean()` or `z.boolean({ coerce: true })` in schemas —
+ * Zod 4's boolean coercion uses `Boolean()` which turns `"false"` into `true`.
+ * Always use `flag(name)` to read boolean arguments instead.
+ */
+export declare class CommandArguments {
+    private record;
+    private rl;
+    private argDefs?;
+    /**
+     * @param record  - Parsed `--name value` pairs.
+     * @param rl      - Readline interface for interactive prompting, or `null`
+     *                  to disable prompting and throw on missing args.
+     * @param argDefs - Optional argument definitions used for schema-based
+     *                  validation. Looked up by name per accessor call.
+     */
+    constructor(record: Record<string, string>, rl: readline.Interface | null, argDefs?: CommandArgumentDefinition[] | undefined);
+    /**
+     * Check whether an argument was provided on the command line.
+     * @param name - Argument name (without `--` prefix).
+     */
+    has(name: string): boolean;
+    /**
+     * Return the raw string value of an argument, or `undefined` if
+     * the argument was not provided.
+     * @param name - Argument name (without `--` prefix).
+     */
+    raw(name: string): string | undefined;
+    /**
+     * Return the validated value of an argument. The return type is
+     * determined by the generic parameter `T`, which should match
+     * the output type of the argument's Zod schema.
+     *
+     * The schema handles all type coercion (e.g. `z.coerce.number()`
+     * converts string `"42"` → number `42`) and constraint validation
+     * (e.g. `z.string().min(1)` rejects empty strings).
+     *
+     * Use this for value-type arguments that must be present or prompted.
+     * For boolean flags, use {@link flag} instead.
+     *
+     * If the argument was not provided on the command line, prompts
+     * the user interactively (when a readline interface is available).
+     *
+     * @example
+     * ```ts
+     * const name = await args.require<string>('name');
+     * const count = await args.require<number>('count');
+     * const size = await args.require<string>('size');
+     * ```
+     *
+     * @param name - Argument name (without `--` prefix).
+     * @throws {InvalidArgumentsError} When no definition exists for
+     *   `name`, when schema validation fails, or when the argument is
+     *   missing and no readline interface is available.
+     */
+    require<T = unknown>(name: string): Promise<T>;
+    /**
+     * Return the boolean value of a flag argument. Accepts `"true"`,
+     * `"false"`, `"1"`, and `"0"` (case-insensitive for true/false).
+     *
+     * Unlike {@link require}, this method treats a missing argument as
+     * `false` — the convention for CLI flags (`--verbose` → true,
+     * absent → false).
+     *
+     * Don't use `z.coerce.boolean()` in your schemas — Zod 4 uses
+     * `Boolean()` which turns `"false"` into `true`. Instead, define
+     * the schema as `z.boolean()` and always read the value with
+     * this method. The string-to-boolean coercion is handled here
+     * before the schema validates the result.
+     *
+     * @example
+     * ```ts
+     * const verbose = await args.flag('verbose');
+     * //   --verbose      → true
+     * //   --verbose false → false
+     * //   (absent)       → false
+     * ```
+     *
+     * @param name - Argument name (without `--` prefix).
+     * @throws {InvalidArgumentsError} When no definition exists for
+     *   `name`, or when the value is not a valid boolean string.
+     */
+    flag(name: string): Promise<boolean>;
+    private resolve;
+    private promptRequired;
+    private requireDef;
+}
+//# sourceMappingURL=command-arguments.d.ts.map

package/dist/command-arguments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-arguments.d.ts","sourceRoot":"","sources":["../src/command-arguments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACtC,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,gBAAgB;IASrB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,OAAO,CAAC;IAVpB;;;;;;OAMG;gBAES,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,EAAE,EAAE,QAAQ,CAAC,SAAS,GAAG,IAAI,EAC7B,OAAO,CAAC,EAAE,yBAAyB,EAAE,YAAA;IAGjD;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIrC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAYpD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAkB5B,OAAO;IAUrB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,UAAU;CASrB"}

package/dist/command-arguments.js

@@ -0,0 +1,155 @@
+import { InvalidArgumentsError } from './errors.js';
+/**
+ * Wraps a parsed argument record (`--name value` pairs) and provides
+ * typed accessors that validate and coerce values via the argument's
+ * {@link CommandArgumentDefinition} zod schema. When an argument is
+ * missing and a readline interface is available, the accessor prompts
+ * the user interactively.
+ *
+ * Every `require*` accessor requires a matching
+ * {@link CommandArgumentDefinition} to exist for the requested name.
+ * If no definition is found, an {@link InvalidArgumentsError} is thrown.
+ *
+ * ## Choosing an accessor
+ *
+ * | Accessor | When to use | Schema examples |
+ * |---|---|---|
+ * | `require<T>(name)` | Value arg that must be present (or prompted). The Zod schema handles all parsing. | `z.coerce.number()`, `z.string().min(1)`, `z.enum([...])` |
+ * | `flag(name)` | CLI flag with `--flag` / `--flag false` semantics. Absent → `false`. | `z.boolean()`, `z.literal(true)` |
+ *
+ * Don't use `z.coerce.boolean()` or `z.boolean({ coerce: true })` in schemas —
+ * Zod 4's boolean coercion uses `Boolean()` which turns `"false"` into `true`.
+ * Always use `flag(name)` to read boolean arguments instead.
+ */
+export class CommandArguments {
+    record;
+    rl;
+    argDefs;
+    /**
+     * @param record  - Parsed `--name value` pairs.
+     * @param rl      - Readline interface for interactive prompting, or `null`
+     *                  to disable prompting and throw on missing args.
+     * @param argDefs - Optional argument definitions used for schema-based
+     *                  validation. Looked up by name per accessor call.
+     */
+    constructor(record, rl, argDefs) {
+        this.record = record;
+        this.rl = rl;
+        this.argDefs = argDefs;
+    }
+    /**
+     * Check whether an argument was provided on the command line.
+     * @param name - Argument name (without `--` prefix).
+     */
+    has(name) {
+        return name in this.record;
+    }
+    /**
+     * Return the raw string value of an argument, or `undefined` if
+     * the argument was not provided.
+     * @param name - Argument name (without `--` prefix).
+     */
+    raw(name) {
+        return this.record[name];
+    }
+    /**
+     * Return the validated value of an argument. The return type is
+     * determined by the generic parameter `T`, which should match
+     * the output type of the argument's Zod schema.
+     *
+     * The schema handles all type coercion (e.g. `z.coerce.number()`
+     * converts string `"42"` → number `42`) and constraint validation
+     * (e.g. `z.string().min(1)` rejects empty strings).
+     *
+     * Use this for value-type arguments that must be present or prompted.
+     * For boolean flags, use {@link flag} instead.
+     *
+     * If the argument was not provided on the command line, prompts
+     * the user interactively (when a readline interface is available).
+     *
+     * @example
+     * ```ts
+     * const name = await args.require<string>('name');
+     * const count = await args.require<number>('count');
+     * const size = await args.require<string>('size');
+     * ```
+     *
+     * @param name - Argument name (without `--` prefix).
+     * @throws {InvalidArgumentsError} When no definition exists for
+     *   `name`, when schema validation fails, or when the argument is
+     *   missing and no readline interface is available.
+     */
+    async require(name) {
+        const raw = await this.resolve(name);
+        const def = this.requireDef(name);
+        const parsed = def.schema.safeParse(raw);
+        if (!parsed.success) {
+            throw new InvalidArgumentsError(`Argument "${name}": ${parsed.error.issues.map((e) => e.message).join('; ')}`);
+        }
+        return parsed.data;
+    }
+    /**
+     * Return the boolean value of a flag argument. Accepts `"true"`,
+     * `"false"`, `"1"`, and `"0"` (case-insensitive for true/false).
+     *
+     * Unlike {@link require}, this method treats a missing argument as
+     * `false` — the convention for CLI flags (`--verbose` → true,
+     * absent → false).
+     *
+     * Don't use `z.coerce.boolean()` in your schemas — Zod 4 uses
+     * `Boolean()` which turns `"false"` into `true`. Instead, define
+     * the schema as `z.boolean()` and always read the value with
+     * this method. The string-to-boolean coercion is handled here
+     * before the schema validates the result.
+     *
+     * @example
+     * ```ts
+     * const verbose = await args.flag('verbose');
+     * //   --verbose      → true
+     * //   --verbose false → false
+     * //   (absent)       → false
+     * ```
+     *
+     * @param name - Argument name (without `--` prefix).
+     * @throws {InvalidArgumentsError} When no definition exists for
+     *   `name`, or when the value is not a valid boolean string.
+     */
+    async flag(name) {
+        if (!this.has(name))
+            return false;
+        const raw = this.record[name];
+        const lower = raw.toLowerCase();
+        const bool = lower === 'true' || lower === '1';
+        if (!bool && lower !== 'false' && lower !== '0') {
+            throw new InvalidArgumentsError(`Argument "${name}" must be a boolean, got "${raw}"`);
+        }
+        const def = this.requireDef(name);
+        const validated = def.schema.safeParse(bool);
+        if (!validated.success) {
+            throw new InvalidArgumentsError(`Argument "${name}": ${validated.error.issues.map((e) => e.message).join('; ')}`);
+        }
+        return validated.data;
+    }
+    async resolve(name) {
+        if (name in this.record) {
+            return this.record[name];
+        }
+        if (this.rl) {
+            return await this.promptRequired(name);
+        }
+        throw new InvalidArgumentsError(`Argument "${name}" is required but not provided`);
+    }
+    promptRequired(name) {
+        return new Promise((resolve) => {
+            this.rl.question(`argument [${name}]: `, resolve);
+        });
+    }
+    requireDef(name) {
+        const def = this.argDefs?.find((d) => d.name === name);
+        if (!def) {
+            throw new InvalidArgumentsError(`Argument "${name}" is not defined. Add it to the command's definitions() array.`);
+        }
+        return def;
+    }
+}
+//# sourceMappingURL=command-arguments.js.map

package/dist/command-arguments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-arguments.js","sourceRoot":"","sources":["../src/command-arguments.ts"],"names":[],"mappings":"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"}

package/dist/command-factory.d.ts

@@ -0,0 +1,17 @@
+import { Command, CommandContainer, type CommandContext } from './types.js';
+import type { CommandArgumentDefinition, CommandArguments } from './command-arguments.js';
+import type { z } from 'zod';
+/**
+ * Create a leaf command from a name, description, argument definitions,
+ * and a handler callback — no need to subclass `Command`.
+ */
+export declare function command(name: string, description: string | undefined, argDefs: CommandArgumentDefinition[], execute: (ctx: CommandContext, args: CommandArguments) => void | Promise<void>): Command;
+/**
+ * Create a namespace container with an optional list of child commands.
+ */
+export declare function container(name: string, description?: string, children?: Command[]): CommandContainer;
+/**
+ * Convenience factory for a single argument definition.
+ */
+export declare function arg(name: string, description: string | undefined, schema: z.ZodType, position?: number): CommandArgumentDefinition;
+//# sourceMappingURL=command-factory.d.ts.map

package/dist/command-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-factory.d.ts","sourceRoot":"","sources":["../src/command-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;GAGG;AACH,wBAAgB,OAAO,CACnB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,yBAAyB,EAAE,EACpC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC/E,OAAO,CAST;AAED;;GAEG;AACH,wBAAgB,SAAS,CACrB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,OAAO,EAAE,GACrB,gBAAgB,CAYlB;AAED;;GAEG;AACH,wBAAgB,GAAG,CACf,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,QAAQ,CAAC,EAAE,MAAM,GAClB,yBAAyB,CAK3B"}

package/dist/command-factory.js

@@ -0,0 +1,43 @@
+import { Command, CommandContainer } from './types.js';
+/**
+ * Create a leaf command from a name, description, argument definitions,
+ * and a handler callback — no need to subclass `Command`.
+ */
+export function command(name, description, argDefs, execute) {
+    return new (class extends Command {
+        constructor() {
+            super(name, description, argDefs);
+        }
+        async execute(ctx, args) {
+            await execute(ctx, args);
+        }
+    })();
+}
+/**
+ * Create a namespace container with an optional list of child commands.
+ */
+export function container(name, description, children) {
+    const c = new (class extends CommandContainer {
+        constructor() {
+            super(name, description);
+        }
+    })();
+    if (children) {
+        for (const child of children) {
+            c.add(child);
+        }
+    }
+    return c;
+}
+/**
+ * Convenience factory for a single argument definition.
+ */
+export function arg(name, description, schema, position) {
+    const def = { name, schema };
+    if (description !== undefined)
+        def.description = description;
+    if (position !== undefined)
+        def.position = position;
+    return def;
+}
+//# sourceMappingURL=command-factory.js.map

package/dist/command-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-factory.js","sourceRoot":"","sources":["../src/command-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAuB,MAAM,YAAY,CAAC;AAI5E;;;GAGG;AACH,MAAM,UAAU,OAAO,CACnB,IAAY,EACZ,WAA+B,EAC/B,OAAoC,EACpC,OAA8E;IAE9E,OAAO,IAAI,CAAC,KAAM,SAAQ,OAAO;QAC7B;YACI,KAAK,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;QACtC,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,GAAmB,EAAE,IAAsB;YACrD,MAAM,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC;KACJ,CAAC,EAAE,CAAC;AACT,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CACrB,IAAY,EACZ,WAAoB,EACpB,QAAoB;IAEpB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAM,SAAQ,gBAAgB;QACzC;YACI,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QAC7B,CAAC;KACJ,CAAC,EAAE,CAAC;IACL,IAAI,QAAQ,EAAE,CAAC;QACX,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC3B,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;IACL,CAAC;IACD,OAAO,CAAC,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,GAAG,CACf,IAAY,EACZ,WAA+B,EAC/B,MAAiB,EACjB,QAAiB;IAEjB,MAAM,GAAG,GAA8B,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACxD,IAAI,WAAW,KAAK,SAAS;QAAE,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC;IAC7D,IAAI,QAAQ,KAAK,SAAS;QAAE,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACpD,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/command-tree.d.ts

@@ -0,0 +1,40 @@
+import { Command, CommandContainer, type CommandContext } from './types.js';
+import type { CommandArguments } from './command-arguments.js';
+/**
+ * Root of the command tree. Maintains the full set of registered
+ * commands and provides lookup, traversal, and completion support.
+ */
+export declare class CommandTree extends CommandContainer {
+    constructor();
+    /**
+     * Default execution: prints a global help listing of all
+     * registered root commands.
+     */
+    execute(ctx: CommandContext, _args: CommandArguments): Promise<void>;
+    /**
+     * Walk the command tree by matching input tokens against
+     * command names. Returns the deepest matching command and
+     * any remaining (unmatched) tokens.
+     *
+     * @param tokens - Tokenized input (e.g. `["config", "set", "--theme", "dark"]`).
+     * @returns The matched command and unused tokens, or `null` when
+     *   no command matches.
+     */
+    find(tokens: string[]): {
+        command: Command;
+        args: string[];
+    } | null;
+    /**
+     * Returns a shallow copy of all root-level commands.
+     * Used by the help system and completer.
+     */
+    getRoots(): Command[];
+    /**
+     * Find command names that match a case-insensitive prefix.
+     * Used for error suggestions when a command is not found.
+     *
+     * @param prefix - The user's typed (partial) command name.
+     */
+    findSuggestions(prefix: string): string[];
+}
+//# sourceMappingURL=command-tree.d.ts.map

package/dist/command-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-tree.d.ts","sourceRoot":"","sources":["../src/command-tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D;;;GAGG;AACH,qBAAa,WAAY,SAAQ,gBAAgB;;IAK7C;;;OAGG;IACG,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1E;;;;;;;;OAQG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI;IA4BnE;;;OAGG;IACH,QAAQ,IAAI,OAAO,EAAE;IAIrB;;;;;OAKG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;CAM5C"}

package/dist/command-tree.js

@@ -0,0 +1,77 @@
+import { CommandContainer } from './types.js';
+import { globalHelp } from './commands/help.js';
+/**
+ * Root of the command tree. Maintains the full set of registered
+ * commands and provides lookup, traversal, and completion support.
+ */
+export class CommandTree extends CommandContainer {
+    constructor() {
+        super('__root__');
+    }
+    /**
+     * Default execution: prints a global help listing of all
+     * registered root commands.
+     */
+    async execute(ctx, _args) {
+        const output = globalHelp(this.commands());
+        ctx.stdout.write(output + '\n');
+    }
+    /**
+     * Walk the command tree by matching input tokens against
+     * command names. Returns the deepest matching command and
+     * any remaining (unmatched) tokens.
+     *
+     * @param tokens - Tokenized input (e.g. `["config", "set", "--theme", "dark"]`).
+     * @returns The matched command and unused tokens, or `null` when
+     *   no command matches.
+     */
+    find(tokens) {
+        if (tokens.length === 0)
+            return null;
+        let level = this.commands();
+        let matched = null;
+        let tokenIndex = 0;
+        for (const token of tokens) {
+            const cmd = level.find((c) => c.name() === token);
+            if (!cmd)
+                break;
+            matched = cmd;
+            tokenIndex++;
+            if (cmd instanceof CommandContainer) {
+                const children = cmd.commands();
+                if (children.length > 0) {
+                    level = children;
+                }
+                else {
+                    break;
+                }
+            }
+            else {
+                break;
+            }
+        }
+        if (!matched)
+            return null;
+        return { command: matched, args: tokens.slice(tokenIndex) };
+    }
+    /**
+     * Returns a shallow copy of all root-level commands.
+     * Used by the help system and completer.
+     */
+    getRoots() {
+        return [...this.commands()];
+    }
+    /**
+     * Find command names that match a case-insensitive prefix.
+     * Used for error suggestions when a command is not found.
+     *
+     * @param prefix - The user's typed (partial) command name.
+     */
+    findSuggestions(prefix) {
+        const lower = prefix.toLowerCase();
+        return this.commands()
+            .filter((c) => c.name().toLowerCase().startsWith(lower))
+            .map((c) => c.name());
+    }
+}
+//# sourceMappingURL=command-tree.js.map

package/dist/command-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-tree.js","sourceRoot":"","sources":["../src/command-tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,gBAAgB,EAAuB,MAAM,YAAY,CAAC;AAE5E,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,gBAAgB;IAC7C;QACI,KAAK,CAAC,UAAU,CAAC,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,GAAmB,EAAE,KAAuB;QACtD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC3C,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;;;OAQG;IACH,IAAI,CAAC,MAAgB;QACjB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAErC,IAAI,KAAK,GAAc,IAAI,CAAC,QAAQ,EAAE,CAAC;QACvC,IAAI,OAAO,GAAmB,IAAI,CAAC;QACnC,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,CAAC;YAClD,IAAI,CAAC,GAAG;gBAAE,MAAM;YAChB,OAAO,GAAG,GAAG,CAAC;YACd,UAAU,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;gBAClC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;gBAChC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACtB,KAAK,GAAG,QAAQ,CAAC;gBACrB,CAAC;qBAAM,CAAC;oBACJ,MAAM;gBACV,CAAC;YACL,CAAC;iBAAM,CAAC;gBACJ,MAAM;YACV,CAAC;QACL,CAAC;QAED,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;IAChE,CAAC;IAED;;;OAGG;IACH,QAAQ;QACJ,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAChC,CAAC;IAED;;;;;OAKG;IACH,eAAe,CAAC,MAAc;QAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,QAAQ,EAAE;aACjB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;aACvD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9B,CAAC;CACJ"}

package/dist/commands/clear.d.ts

@@ -0,0 +1,10 @@
+import { Command, type CommandContext } from '../types.js';
+import type { CommandArguments } from '../command-arguments.js';
+/**
+ * Built-in `clear` command. Clears the terminal screen.
+ */
+export declare class ClearCommand extends Command {
+    constructor();
+    execute(ctx: CommandContext, _args: CommandArguments): void;
+}
+//# sourceMappingURL=clear.d.ts.map

package/dist/commands/clear.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../src/commands/clear.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE;;GAEG;AACH,qBAAa,YAAa,SAAQ,OAAO;;IAKrC,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;CAG9D"}

package/dist/commands/clear.js

@@ -0,0 +1,13 @@
+import { Command } from '../types.js';
+/**
+ * Built-in `clear` command. Clears the terminal screen.
+ */
+export class ClearCommand extends Command {
+    constructor() {
+        super('clear', 'Clear terminal');
+    }
+    execute(ctx, _args) {
+        ctx.stdout.write('\x1Bc');
+    }
+}
+//# sourceMappingURL=clear.js.map

package/dist/commands/clear.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear.js","sourceRoot":"","sources":["../../src/commands/clear.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAuB,MAAM,aAAa,CAAC;AAG3D;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,OAAO;IACrC;QACI,KAAK,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,CAAC,GAAmB,EAAE,KAAuB;QAChD,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;CACJ"}

package/dist/commands/exit.d.ts

@@ -0,0 +1,10 @@
+import { Command, type CommandContext } from '../types.js';
+import type { CommandArguments } from '../command-arguments.js';
+/**
+ * Built-in `exit` command. Stops the terminal loop.
+ */
+export declare class ExitCommand extends Command {
+    constructor();
+    execute(ctx: CommandContext, _args: CommandArguments): void;
+}
+//# sourceMappingURL=exit.d.ts.map

package/dist/commands/exit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.d.ts","sourceRoot":"","sources":["../../src/commands/exit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE;;GAEG;AACH,qBAAa,WAAY,SAAQ,OAAO;;IAKpC,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;CAG9D"}

package/dist/commands/exit.js

@@ -0,0 +1,13 @@
+import { Command } from '../types.js';
+/**
+ * Built-in `exit` command. Stops the terminal loop.
+ */
+export class ExitCommand extends Command {
+    constructor() {
+        super('exit', 'Exit the terminal');
+    }
+    execute(ctx, _args) {
+        ctx.exit();
+    }
+}
+//# sourceMappingURL=exit.js.map

package/dist/commands/exit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.js","sourceRoot":"","sources":["../../src/commands/exit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAuB,MAAM,aAAa,CAAC;AAG3D;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,OAAO;IACpC;QACI,KAAK,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,GAAmB,EAAE,KAAuB;QAChD,GAAG,CAAC,IAAI,EAAE,CAAC;IACf,CAAC;CACJ"}

package/dist/commands/help.d.ts

@@ -0,0 +1,40 @@
+import { Command, type CommandContext } from '../types.js';
+import type { CommandArguments } from '../command-arguments.js';
+/**
+ * Render a global help listing for a set of root commands.
+ * Each command is shown as `name   description`, names are
+ * left-aligned to the longest command name.
+ */
+export declare function globalHelp(commands: Command[]): string;
+/**
+ * Render detailed help for a single command, including its
+ * name, description, argument definitions, and subcommands.
+ */
+export declare function commandHelp(command: Command): string;
+/**
+ * Resolve a token path against a command list and render
+ * help for the resolved command. Returns an error message
+ * if the path does not match any command.
+ */
+export declare function scopedHelp(commands: Command[], pathTokens: string[]): string;
+/**
+ * Walk the command tree matching each token to a command name.
+ * Returns the deepest matching command, or `undefined` if a token
+ * cannot be matched or extra tokens trail a leaf node.
+ */
+export declare function resolveCommand(commands: Command[], tokens: string[]): Command | undefined;
+/**
+ * Built-in `help` command. Lists all commands or shows detailed
+ * help for a specific command by name.
+ *
+ * @example
+ * ```
+ * > help                     # list all commands
+ * > help --command config    # show help for the "config" command
+ * ```
+ */
+export declare class HelpCommand extends Command {
+    constructor();
+    execute(ctx: CommandContext, args: CommandArguments): Promise<void>;
+}
+//# sourceMappingURL=help.d.ts.map

package/dist/commands/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/commands/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAQhE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAStD;AAeD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CA0BpD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAM5E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,GAAG,SAAS,CAoBzF;AAED;;;;;;;;;GASG;AACH,qBAAa,WAAY,SAAQ,OAAO;;IAY9B,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAc5E"}