icore 1.0.14 → 1.0.16

package/readme.md

@@ -5,7 +5,7 @@
 [![types](https://img.shields.io/npm/types/icore.svg)](https://www.npmjs.com/package/icore)
 [![license](https://img.shields.io/npm/l/icore.svg)](LICENSE)
 
-Small dependency-free command line interface mechanics for [Node.js®](https://nodejs.org) applications.
+Small dependency-free command line interface and terminal presentation mechanics for [Node.js®](https://nodejs.org) applications.
 
 Supports a practical GNU-style option syntax:
 
@@ -24,20 +24,40 @@ npm install icore
 
 ## Table of Contents
 
-- [Installation](#installation)
-- [API](#api)
-  - [`parseArgv(args, schema?)`](#parseargvargs-schema)
-  - [`parseOptions(schema, values)`](#parseoptionsschema-values)
-  - [`parseOptionsDetailed(schema, values)`](#parseoptionsdetailedschema-values)
-  - [`defineCommand(command)`](#definecommandcommand)
-  - [`defineCommandRegistry(commands)`](#definecommandregistrycommands)
-  - [`isCommandName(registry, value)`](#iscommandnameregistry-value)
-  - [`resolveCommand(registry, positionals)`](#resolvecommandregistry-positionals)
-  - [`resolveCommandFromArgs(registry, args)`](#resolvecommandfromargsregistry-args)
-  - [`prepareCommandFromArgs(registry, args, options?)`](#preparecommandfromargsregistry-args-options)
-  - [`runCommandFromRegistry(registry, args, context, options?)`](#runcommandfromregistryregistry-args-context-options)
-  - [`mergeOptionsSchema(...schemas)`](#mergeoptionsschemaschemas)
-  - [`runCommand(command, args, context, options?)`](#runcommandcommand-args-context-options)
+- [API Reference](#api-reference)
+  - [`createTerminalApp()`](#createterminalapp)
+  - [`createCommand()`](#createcommand)
+    - [`command.define(command)`](#commanddefinecommand)
+    - [`command.registry(commands)`](#commandregistrycommands)
+    - [`command.run(command, args, context)`](#commandruncommand-args-context)
+    - [`createCommands(commands)`](#createcommandscommands)
+    - [`commands.prepare(args, options?)`](#commandsprepareargs-options)
+    - [`commands.run(prepared, context)`](#commandsrunprepared-context)
+    - [`commands.runFromArgs(args, context, options?)`](#commandsrunfromargsargs-context-options)
+  - [`createPresentation()`](#createpresentation)
+    - [`presentation.empty()`](#presentationempty)
+    - [`presentation.text(value)`](#presentationtextvalue)
+    - [`presentation.record(value)`](#presentationrecordvalue)
+    - [`presentation.records(values)`](#presentationrecordsvalues)
+    - [`presentation.table(rows)`](#presentationtablerows)
+    - [`presentation.csv(rows)`](#presentationcsvrows)
+    - [`presentation.render(result, format?)`](#presentationrenderresult-format)
+    - [`presentation.renderers.*`](#presentationrenderers)
+  - [`createOutput()`](#createoutput)
+    - [`output.write(chunk)`](#outputwritechunk)
+    - [`output.error(chunk)`](#outputerrorchunk)
+    - [`output.stdout.write(chunk)`](#outputstdoutwritechunk)
+    - [`output.stderr.write(chunk)`](#outputstderrwritechunk)
+  - [Lower-Level Mechanics](#lower-level-mechanics)
+    - [`parseArgv(args, schema?)`](#parseargv)
+    - [`parseOptionsDetailed(schema, values)`](#parseoptionsdetailed)
+    - [`resolveCommand(registry, positionals)`](#resolvecommand)
+    - [`resolveCommandFromArgs(registry, args)`](#resolvecommandfromargs)
+    - [`prepareCommandFromArgs(registry, args, options?)`](#preparecommandfromargs)
+    - [`runPreparedCommand(prepared, context)`](#runpreparedcommand)
+    - [`runCommandFromRegistry(registry, args, context, options?)`](#runcommandfromregistry)
+    - [`runCommand(command, args, context, options?)`](#runcommand)
+- [Internal Source Layout](#internal-source-layout)
 - [How It Works](#how-it-works)
 - [Example](#example)
 - [Option Schemas](#option-schemas)
@@ -46,374 +66,340 @@ npm install icore
 - [Error Messages](#error-messages)
 - [Project Boundary](#project-boundary)
 
-## API
+## API Reference
 
-### `parseArgv(args, schema?)`
+Start at `createTerminalApp()` for regular terminal applications, then move to
+the construction methods only when the app needs explicit command,
+presentation, or output wiring.
 
-Parses raw CLI arguments into positionals and raw option values.
+### `createTerminalApp()`
 
-```ts
-import { parseArgv } from 'icore';
-
-const argv = parseArgv([
-  'hello',
-  '--name',
-  'Alice',
-  '--uppercase'
-]);
-```
+`createTerminalApp()` is the top-level terminal application composition point.
+It wires command execution, presentation rendering, and stdout/stderr delivery
+without taking ownership of application behavior.
 
-Result:
+The checked TypeScript contract lives in [`src/terminal/app.ts`](src/terminal/app.ts).
 
-```ts
-{
-  positionals: ['hello'],
-  options: {
-    name: 'Alice',
-    uppercase: true
-  }
-}
-```
+The method returns an application object with `prepare(args)` and
+`run(args, context)`.
+
+Construction inputs:
+
+- `commands` is required; build it with [`createCommand()`](#createcommand) and
+  [`command.registry(commands)`](#commandregistrycommands), or directly with
+  [`createCommands(commands)`](#createcommandscommands);
+- `presentation` is optional; omit it to use [`createPresentation()`](#createpresentation);
+- `output` is optional; omit it to use [`createOutput()`](#createoutput);
+- `resolveFormat` is optional and customizes how a prepared command selects a
+  presentation format.
 
-When an option schema is provided, boolean options are parsed as flags without
-consuming the following positional argument:
+Returned app methods:
+
+- `app.prepare(args, options?)` delegates to
+  [`commands.prepare(args, options?)`](#commandsprepareargs-options);
+- `app.run(args, context, options?)` prepares the command, delegates command
+  execution to [`commands.run(prepared, context)`](#commandsrunprepared-context),
+  then renders and writes terminal output.
+
+Minimal shape:
 
 ```ts
-const argv = parseArgv([
-  'hello',
-  '--uppercase',
-  'Alice'
-], {
-  uppercase: {
-    type: 'boolean'
-  }
+const app = createTerminalApp({
+  commands,
+  presentation,
+  output
+});
+
+const args = process.argv.slice(2);
+const exitCode = await app.run(args, context, {
+  strict: true
 });
 ```
 
-Result:
+Command handlers keep ownership of application work. The terminal app only
+accepts terminal-ready results: text, streaming text, presentation results, or
+no output. Application DTO mapping, config loading, network clients, and domain
+behavior stay in the consuming application.
 
-```ts
-{
-  positionals: ['hello', 'Alice'],
-  options: {
-    uppercase: true
-  }
-}
-```
+### `createCommand()`
 
-### `parseOptions(schema, values)`
+`createCommand()` returns the command mechanics entrypoint used to build
+`commands` for `createTerminalApp()`.
 
-Validates raw option values using an option schema and returns typed options.
+Simplified shape:
 
 ```ts
-import { parseOptions } from 'icore';
+const command = createCommand();
 
-const options = parseOptions({
-  name: {
-    type: 'string',
-    default: 'world'
-  },
-  uppercase: {
-    type: 'boolean'
-  }
-} as const, {
-  name: 'Alice',
-  uppercase: true
-});
+command.define(commandDefinition);
+command.registry(commandDefinitions);
+command.run(commandDefinition, args, context);
 ```
 
-Result:
+Build `commands` before creating the terminal app:
 
-```ts
-{
-  name: 'Alice',
-  uppercase: true
-}
-```
+- `createCommand()` creates the command mechanics entrypoint;
+- `command.define(...)` declares one command;
+- `command.registry([...])` returns the `commands` object required by
+  `createTerminalApp()`.
 
-### `parseOptionsDetailed(schema, values)`
+The command definition keeps the application-specific parts: command path,
+option schema, and handler behavior. The terminal app only needs the resulting
+registry object.
 
-Validates raw option values and returns parsed options together with
-user-provided metadata.
+#### `command.define(command)`
 
-```ts
-import { parseOptionsDetailed } from 'icore';
+Declares one command and preserves its literal path and option schema types.
+Use it when defining commands inline before adding them to a registry.
 
-const result = parseOptionsDetailed({
-  name: {
-    type: 'string',
-    default: 'world'
-  },
-  uppercase: {
-    type: 'boolean'
-  }
-} as const, {
-  uppercase: true
-});
-```
+#### `command.registry(commands)`
+
+Builds the `commands` object required by `createTerminalApp()`. It keeps the
+registered command definitions, derived command names, and command flow methods
+together.
+
+#### `command.run(command, args, context)`
 
-Result:
+Runs a single command without a registry. Use it for focused command execution,
+small tests, or custom flows where command path resolution is not needed.
+
+#### `createCommands(commands)`
+
+Use `createCommands(commands)` when the application already has command
+definitions and does not need the `createCommand()` object form.
+
+The returned object is the same `commands` contract consumed by
+`createTerminalApp()`: it can resolve, prepare, and run registered commands.
+
+Simplified shape:
 
 ```ts
-{
-  options: {
-    name: 'world',
-    uppercase: true
-  },
-  provided: {
-    name: false,
-    uppercase: true
-  }
-}
+const commands = createCommands(commandDefinitions);
+
+commands.names;
+commands.registry;
+commands.resolve(positionals);
+commands.resolveFromArgs(args);
+commands.prepare(args, options);
+commands.run(prepared, context);
+commands.runFromArgs(args, context, options);
 ```
 
-`provided` is useful when a default value and an omitted option have different
-application-level meaning.
+Use `commands.prepare(...)` and `commands.run(...)` when application code needs
+the same two-phase flow used by `createTerminalApp()`. Use
+`commands.runFromArgs(...)` for custom terminal boundaries that still want the
+registry-level command flow.
 
-### `defineCommand(command)`
+#### `commands.prepare(args, options?)`
 
-Defines a command while preserving its option schema types.
+Resolves and validates a registered command without runtime context. This is
+the same preparation step used by `app.prepare(...)` and `app.run(...)`.
 
-```ts
-import { defineCommand } from 'icore';
+#### `commands.run(prepared, context)`
 
-const command = defineCommand({
-  path: ['hello'],
-  options: {
-    name: {
-      type: 'string',
-      default: 'world'
-    },
-    uppercase: {
-      type: 'boolean'
-    }
-  },
-  async handle({ options }) {
-    const message = `Hello, ${options.name}!`;
+Runs an already prepared command with application context. Use it after
+`commands.prepare(...)` when the application needs a custom two-phase flow.
 
-    return options.uppercase ? message.toUpperCase() : message;
-  }
-});
-```
+#### `commands.runFromArgs(args, context, options?)`
 
-### `defineCommandRegistry(commands)`
+Resolves, prepares, and runs a registered command without the terminal
+application boundary. Use it when a custom boundary owns presentation or output.
 
-Defines a command registry while preserving literal command path types.
+### `createPresentation()`
 
-```ts
-import { defineCommandRegistry } from 'icore';
+`createPresentation()` creates the presentation object used by
+`createTerminalApp()` to render terminal-ready results.
 
-const registry = defineCommandRegistry([
-  helloCommand,
-  helloFormalCommand
-] as const);
-```
+Source of truth:
+
+- [src/presentation/facade.ts](src/presentation/facade.ts) for the presentation
+  object;
+- [src/presentation/view.ts](src/presentation/view.ts) for presentation view
+  factories;
+- [src/presentation/result-renderer.ts](src/presentation/result-renderer.ts)
+  for rendering presentation results.
 
-The registry exposes ordered commands and derived command names:
+Simplified shape:
 
 ```ts
-registry.commandNames;
+const presentation = createPresentation();
+
+presentation.empty();
+presentation.text(value);
+presentation.record(value);
+presentation.records(values);
+presentation.table(rows);
+presentation.csv(rows);
+presentation.render(result, format);
 ```
 
-Result:
+The presentation object owns generic JSON, CSV, and table rendering mechanics.
+Application code still maps domain objects to presentation-ready values.
 
-```ts
-[
-  'hello',
-  'hello formal'
-]
-```
+#### `presentation.empty()`
 
-Duplicate command paths are rejected.
+Creates a presentation result with no terminal output.
 
-### `isCommandName(registry, value)`
+#### `presentation.text(value)`
 
-Checks whether an unknown value is a command name registered in the registry.
+Wraps ready terminal text. Use it when the command already owns the final text.
 
-```ts
-if (isCommandName(registry, value)) {
-  // value is narrowed to the registry command name union.
-}
-```
+#### `presentation.record(value)`
 
-### `resolveCommand(registry, positionals)`
+Creates a generic one-record view. The renderer can print it as table, CSV, or
+JSON depending on the selected format.
 
-Resolves a command from already parsed positional arguments.
+#### `presentation.records(values)`
 
-```ts
-import { resolveCommand } from 'icore';
+Creates a generic multi-record view. Application code still decides which fields
+belong in each record.
 
-const resolved = resolveCommand(registry, [
-  'hello',
-  'formal',
-  'Alice'
-]);
-```
+#### `presentation.table(rows)`
 
-Result:
+Creates an explicit table view from prepared text rows.
 
-```ts
-{
-  name: 'hello formal',
-  path: ['hello', 'formal'],
-  command: helloFormalCommand,
-  positionals: ['Alice']
-}
-```
+#### `presentation.csv(rows)`
 
-When several command paths match, the most specific command wins. For example,
-`hello formal` is preferred over `hello`.
+Creates an explicit CSV view from scalar rows.
 
-### `resolveCommandFromArgs(registry, args)`
+#### `presentation.render(result, format?)`
 
-Resolves a command from raw CLI arguments. Each candidate command is parsed with
-its own option schema, so boolean flags do not accidentally consume command path
-segments.
+Renders a presentation result to terminal text. The default format is `table`.
 
-```ts
-const resolved = resolveCommandFromArgs(registry, [
-  'hello',
-  '--name',
-  'Alice',
-  '--uppercase'
-]);
-```
+#### `presentation.renderers.*`
+
+Exposes lower-level JSON, table, and CSV renderers for custom presentation
+composition. Prefer `presentation.render(...)` for regular terminal commands.
+
+### `createOutput()`
 
-`resolveCommandFromArgs` keeps legacy option-anywhere command resolution. Use
-`prepareCommandFromArgs(..., { strict: true })` when command path diagnostics
-should reject options before the command path.
+`createOutput()` creates the output object used by `createTerminalApp()` to
+write rendered text.
 
-### `prepareCommandFromArgs(registry, args, options?)`
+Source of truth:
 
-Resolves and validates a command without requiring runtime context or calling
-the command handler.
+- [src/output/facade.ts](src/output/facade.ts) for the output object;
+- [src/output/node-writer.ts](src/output/node-writer.ts) for stdout and stderr
+  writers;
+- [src/output/text-writer.ts](src/output/text-writer.ts) for backpressure-aware
+  text writing.
+
+Simplified shape:
 
 ```ts
-const prepared = await prepareCommandFromArgs(
-  registry,
-  ['hello', '--name', 'Alice', '--uppercase'],
-  {
-    strict: true
-  }
-);
+const output = createOutput();
+
+await output.write(chunk);
+await output.error(chunk);
+await output.stdout.write(chunk);
+await output.stderr.write(chunk);
 ```
 
-A command `prepare` hook can return a typed payload. The payload is available
-on the prepared command before runtime context is created, then passed to the
-handler:
+The default output writes regular text to `stdout` and diagnostic text to
+`stderr`. Pass custom sinks when tests or applications need controlled output.
 
-```ts
-const helloCommand = defineCommand({
-  path: ['hello'],
-  options: {
-    name: {
-      type: 'string',
-      required: true
-    }
-  },
-  prepare({ options }) {
-    return {
-      normalizedName: options.name.trim().toLowerCase()
-    };
-  },
-  handle({ payload, context }) {
-    return context.greeter.greet(payload.normalizedName);
-  }
-});
+#### `output.write(chunk)`
 
-const prepared = await prepareCommandFromArgs(registry, [
-  'hello',
-  '--name',
-  ' Alice '
-]);
+Writes regular terminal output through stdout.
 
-prepared.payload.normalizedName;
-```
+#### `output.error(chunk)`
 
-Use payload for derived CLI data. Runtime resources such as databases, sockets,
-or SDK clients should still be created outside `icore` and passed as `context`.
+Writes diagnostic terminal output through stderr.
 
-With `strict: true`, the command path must appear before options:
+#### `output.stdout.write(chunk)`
 
-```console
-$ node cli.js --unknown hello
-Unexpected argument '--unknown'
-```
+Writes directly to the stdout channel. Use this only when a specific channel
+must be passed around.
 
-Without strict mode, legacy candidate-schema resolution is preserved for
-backward compatibility.
+#### `output.stderr.write(chunk)`
 
-### `runCommandFromRegistry(registry, args, context, options?)`
+Writes directly to the stderr channel. Use this only when a specific channel
+must be passed around.
 
-Resolves a command from a registry and runs its handler.
+### Lower-Level Mechanics
 
-```ts
-const output = await runCommandFromRegistry(
-  registry,
-  ['hello', '--name', 'Alice', '--uppercase'],
-  context,
-  {
-    strict: true
-  }
-);
-```
+Lower-level mechanics sit behind the construction methods. They are kept out of
+the main navigation to keep the application construction path first.
 
-This is **registry-level mechanics only**. Application-specific setup, side
-effects, and output formatting still belong outside `icore`.
+For application code, prefer `createTerminalApp()` first. Drop to this level
+only when the terminal application flow or construction methods are too coarse.
 
-### `mergeOptionsSchema(...schemas)`
+Source of truth:
 
-Merges multiple option schemas while preserving literal option definition types.
-Later schemas override earlier schemas with the same option name.
+- [src/argv/parser.ts](src/argv/parser.ts) for raw argv parsing;
+- [src/options/parser.ts](src/options/parser.ts) for option value validation;
+- [src/command/mechanics.ts](src/command/mechanics.ts) for command resolution,
+  preparation, and execution.
 
-```ts
-import { mergeOptionsSchema } from 'icore';
+#### Parsing And Resolution
 
-const nameOptions = {
-  name: {
-    type: 'string',
-    default: 'world'
-  }
-} as const;
+This group turns raw arguments or positionals into a selected command.
 
-const greetingOptions = {
-  uppercase: {
-    type: 'boolean'
-  }
-} as const;
+- <a id="parseargv"></a>`parseArgv(args, schema?)` parses raw CLI arguments into positionals and raw
+  option values;
+- <a id="resolvecommand"></a>`resolveCommand(registry, positionals)` resolves from already parsed
+  positionals;
+- <a id="resolvecommandfromargs"></a>`resolveCommandFromArgs(registry, args)` resolves from raw CLI arguments by
+  using registered command schemas.
 
-const options = mergeOptionsSchema(nameOptions, greetingOptions);
-```
+Use these methods when command selection is needed without validation or
+execution.
 
-### `runCommand(command, args, context, options?)`
+#### Preparation
 
-Parses arguments, validates options, checks command positionals, and runs the
-handler.
+This group validates command input without runtime context.
 
-```ts
-const output = await runCommand(
-  command,
-  ['hello', '--name', 'Alice', '--uppercase'],
-  context,
-  {
-    strict: true
-  }
-);
-```
+- <a id="parseoptionsdetailed"></a>`parseOptionsDetailed(schema, values)` validates raw option values and keeps
+  option presence metadata;
+- <a id="preparecommandfromargs"></a>`prepareCommandFromArgs(registry, args, options?)` resolves and validates a
+  registered command;
+- `options.strict` rejects options before the command path.
+
+Use preparation when runtime resources should be created only after command
+selection is known.
+
+#### Execution
+
+This group calls command handlers after command input is prepared.
 
-**By default**, extra positionals are rejected. A command can opt in to extra
-positionals with `allowExtraPositionals: true`.
+- <a id="runpreparedcommand"></a>`runPreparedCommand(prepared, context)` runs an already prepared command;
+- <a id="runcommandfromregistry"></a>`runCommandFromRegistry(registry, args, context, options?)` prepares and runs
+  a command from a registry;
+- <a id="runcommand"></a>`runCommand(command, args, context, options?)` runs a single command without a
+  registry.
 
-With `strict: true`, direct command execution also requires the command path to
-appear before options.
+Use execution primitives for custom boundaries. Regular CLI applications should
+usually stay at `createTerminalApp()`.
+
+## Internal Source Layout
+
+The public package entrypoint remains `src/index.ts`. Internal source files are
+grouped by CLI framework responsibility:
+
+```text
+src/
+  argv/          raw argv token parsing
+  options/       option schemas and option value validation
+  command/       command resolution and execution mechanics
+  presentation/  terminal view models and JSON/CSV/table renderers
+  output/        stdout/stderr writer boundaries
+  terminal/      command + presentation + output app composition
+  errors/        machine-readable icore errors
+```
+
+Consumers should continue importing from `icore`; deep imports are an internal
+source layout detail.
 
 ## How It Works
 
 ![yuml diagram](http://yuml.me/diagram/scruffy;dir:LR;/class/[*argv*%20{bg:gray}|External;hello%20--name%20Alice%20--uppercase]->[*matches*%20{bg:lavender}|System;parse,%20resolve,%20validate,%20infer]->[*typed%20result*%20{bg:honeydew}|Container;command=hello;%20name=Alice;%20uppercase=true]->[*your%20app*%20{bg:cornsilk}|System;business%20logic%20and%20output])
 
-
 ## Example
 
+More examples live in [examples/readme.md](examples/readme.md), including
+option schemas, CLI argument syntax, practical CLI patterns, and lower-level
+primitives.
+
 ```ts
 import { defineCommand, runCommand } from 'icore';
 
@@ -713,4 +699,9 @@ Good responsibilities for `icore`:
 - option schema evaluation;
 - command path checking;
 - common argument errors;
-- typed command handler input.
+- typed command handler input;
+- generic JSON, CSV, and text table rendering;
+- stdout/stderr text writer mechanics.
+
+Application-specific report mapping, scalar formatting, API calls, config
+loading, and domain behavior stay outside `icore`.