termkit 2.3.1 → 2.4.0

package/README.md

@@ -138,6 +138,31 @@ my-app help
 my-app serve help
 ```
 
+Commands defined without an `.action()` print their help automatically when invoked. This makes parent commands that only group subcommands self-documenting — running `my-app` or `my-app serve` with no further input shows usage instead of erroring.
+
+### Shell
+
+Turn a command tree into an interactive REPL. `Program.shell()` runs the root command's subcommands as a live prompt instead of parsing `process.argv` once.
+
+```ts
+import { Program } from 'termkit'
+
+// ...define commands with Program.command(...)
+
+await Program.shell({ banner: 'myapp shell — type "help", "exit" to quit' })
+```
+
+Two modes:
+
+- **`drill`** (default) — step through the tree one level at a time. Each prompt lists the available subcommands; type a name to descend, `..` to go back up, `help` to print usage, or an exit command to quit. Leaf commands prompt for each declared variable in turn, then run. An empty line at the root exits.
+- **`free`** — type full command lines as you would on the CLI, with Tab completion across the command tree. `exit`/`quit` to leave.
+
+```ts
+await Program.shell({ mode: 'free', promptColor: '#a855f7' })
+```
+
+Options: `mode` (`'drill' | 'free'`, default `'drill'`), `prompt` (free-mode prompt label, defaults to the root command name), `promptColor` (named color, hex string, or xterm number), `banner`, `exitCommands` (default `['exit', 'quit']`), `historySize` (default `100`).
+
 ### configure
 
 Sets global display options for the entire toolkit — accent color used in help output, tables, charts, and prompts; plus Unicode glyph support.
@@ -193,7 +218,7 @@ Pass `search: true` to add a type-to-filter input. Typing narrows the list; Back
 const pkg = await select('Pick a package:', packages, { search: true })
 ```
 
-Pass `maxHeight` to cap the visible rows and enable scrolling. The viewport follows the cursor automatically.
+Pass `maxHeight` to cap the visible rows and enable scrolling. The viewport follows the cursor automatically. Even without `maxHeight`, the list is clamped to the terminal height so a long list never scrolls the screen.
 
 ```ts
 const tz = await select('Timezone?', timezones, { maxHeight: 8 })
@@ -236,7 +261,7 @@ Pass `search: true` to add a type-to-filter input. All printable characters go t
 const pkgs = await multiSelect('Add dependencies:', packages, { search: true })
 ```
 
-Pass `maxHeight` to cap the visible rows with auto-scrolling:
+Pass `maxHeight` to cap the visible rows with auto-scrolling. As with `select`, the list is also clamped to the terminal height automatically so it never scrolls the screen.
 
 ```ts
 const regions = await multiSelect('Deploy to:', regions, { maxHeight: 6 })
@@ -765,6 +790,7 @@ console.log(wrap(longParagraph, 60))
 | `Program.middleware` | `(fn) => fn` | Identity helper for typing middleware inline |
 | `Program.parse` | `(argv) => Promise<void>` | Parse argv using the root command |
 | `Program.setDefaults` | `(defaults) => void` | Apply middleware/options to all new commands |
+| `Program.shell` | `(options?) => Promise<void>` | Run the command tree as an interactive REPL |
 
 ### Functions
 
@@ -787,11 +813,11 @@ console.log(wrap(longParagraph, 60))
 
 ### Classes
 
-`Command`, `Option`, `Variable`, `TermKit`, `Bar`, `MultiBar`, `Spinner`, `Scrollbox`, `Input`, `Select`, `MultiSelect`, `Log`, `Table`, `Column`, `Chart.Bar`, `Chart.VerticalBar`, `Chart.Heatmap`, `Chart.Scatter`, `Chart.Line`
+`Command`, `Option`, `Variable`, `TermKit`, `Shell`, `Bar`, `MultiBar`, `Spinner`, `Scrollbox`, `Input`, `Select`, `MultiSelect`, `Log`, `Table`, `Column`, `Chart.Bar`, `Chart.VerticalBar`, `Chart.Heatmap`, `Chart.Scatter`, `Chart.Line`
 
 ### Types
 
-`ActionFn`, `MiddlewareFn`, `ParsedOptions`, `CommandDefaults`, `VariableType`, `BarMode`, `BarOptions`, `MultiBarOptions`, `SpinnerOptions`, `InputOptions`, `InputReturn`, `InputType`, `SelectItem`, `SelectOptions`, `MultiSelectItem`, `MultiSelectOptions`, `LogOptions`, `TableOptions`, `ColumnOptions`, `ColumnAlign`, `MarkupOptions`, `MarkupStyleFn`, `MarkupStyles`, `HelpColor`, `Chart.BarItem`, `Chart.BarOptions`, `Chart.VerticalBarItem`, `Chart.VerticalBarOptions`, `Chart.HeatmapOptions`, `Chart.ScatterPoint`, `Chart.ScatterOptions`, `Chart.LinePoint`, `Chart.LineOptions`, `Chart.SparklineOptions`
+`ActionFn`, `MiddlewareFn`, `ParsedOptions`, `CommandDefaults`, `ShellOptions`, `VariableType`, `BarMode`, `BarOptions`, `MultiBarOptions`, `SpinnerOptions`, `InputOptions`, `InputReturn`, `InputType`, `SelectItem`, `SelectOptions`, `MultiSelectItem`, `MultiSelectOptions`, `LogOptions`, `TableOptions`, `ColumnOptions`, `ColumnAlign`, `MarkupOptions`, `MarkupStyleFn`, `MarkupStyles`, `HelpColor`, `Chart.BarItem`, `Chart.BarOptions`, `Chart.VerticalBarItem`, `Chart.VerticalBarOptions`, `Chart.HeatmapOptions`, `Chart.ScatterPoint`, `Chart.ScatterOptions`, `Chart.LinePoint`, `Chart.LineOptions`, `Chart.SparklineOptions`
 
 ## Authors
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Command } from '@/models/Command';
 import { Option } from '@/models/Option';
+import type { ShellOptions } from '@/models/Shell';
 import type { MiddlewareFn } from '@/types';
 export type { HelpColor } from '@/config';
 export { configure } from '@/config';
@@ -24,6 +25,8 @@ export type { ScrollboxOptions } from '@/models/Scrollbox';
 export { Scrollbox, scrollbox } from '@/models/Scrollbox';
 export type { SelectItem, SelectOptions } from '@/models/Select';
 export { Select, select } from '@/models/Select';
+export type { ShellOptions } from '@/models/Shell';
+export { Shell } from '@/models/Shell';
 export type { SpinnerOptions } from '@/models/Spinner';
 export { Spinner } from '@/models/Spinner';
 export type { TableOptions } from '@/models/Table';
@@ -48,5 +51,6 @@ export declare const Program: {
     middleware: (fn: MiddlewareFn) => MiddlewareFn;
     parse: (arr: string[]) => Promise<void>;
     setDefaults: (data: CommandDefaults) => void;
+    shell: (options?: ShellOptions) => Promise<void>;
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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