icore 1.0.16 → 1.0.18

package/CHANGELOG.md

@@ -9,48 +9,112 @@ Historical entries before this file was introduced were reconstructed from npm
 publish metadata and local git history. Older entries are intentionally
 conservative.
 
+Version boundaries between `1.0.12` and `1.0.15` are draft-level and should be
+verified against git tags.
+
 ## [Unreleased]
 
 ### Added
 
-- Added `createCommand` as a semantic command mechanics facade.
-- Added `createCommands` as a high-level command mechanics facade.
-- Added `createPresentation` and `PresentationResult` for terminal view-model rendering.
-- Added semantic `Presentation` view factory methods such as `presentation.records(...)`.
-- Added `createOutput` as a stdout/stderr output boundary facade.
-- Added semantic `Output.write()` and `Output.error()` methods.
-- Added `createTerminalApp` to compose command, presentation, and output mechanics.
-- Added generic terminal presentation renderers for JSON, CSV, and text tables.
-- Added reusable stdout/stderr text writers with backpressure handling.
-- Added shared `presentationFormatOptions` for common `--format` command options.
-- Added machine-readable `IcoreError` codes and details.
-- Added `parseOptionsSubsetDetailed` for validating known option subsets while preserving unknown raw options.
-- Added opt-in `strict: true` command resolution for rejecting options before command paths.
-- Added `strict: true` support to direct `runCommand` execution.
-- Added typed prepared command `payload` returned from `prepare` and passed to `handle`.
-- Added public `CommandPayload`, `CommandContext`, and `CommandResult` helper types.
-- Added `isPreparedCommandName` for narrowing prepared command unions by name.
-- Added this changelog.
-
-### Changed
-
-- Changed `PreparedCommand` typing to preserve payload correlation when narrowing registry unions by command name.
-- Changed output writers to await promise-returning custom sinks.
-- Reorganized internal source files by CLI framework responsibility without changing the root public API.
-- Split option schema contracts from option value parsing internals.
-- Changed npm package contents to include `CHANGELOG.md`.
-- Removed the redundant `cli` barrel so `index` is the only package entrypoint.
+- Added `TerminalApp.runPrepared(...)` for running prepared commands through terminal rendering and output.
 
-### Removed
+### Changed
+
+- Changed `createTerminalApp` typing to accept command registries with void and prepared payloads.
+- Updated testing instructions to use `yarn build` and `yarn test`.
+
+## [1.0.16]
+
+### Added
+
+- Added `createTerminalApp()` as the top-level terminal application composition API.
+- Added semantic presentation facade: `createPresentation()`.
+- Added semantic output facade: `createOutput()` with `output.write(...)` and `output.error(...)`.
+- Added terminal-ready command output support: text, async text streams, presentation results, and empty output.
+- Added guide-style examples for terminal app, command flow, option schemas, presentation, output, and lower-level mechanics.
 
-- Removed explicit boolean values such as `--flag=true` and `--flag=false`; use `--flag` and `--no-flag`.
+### Changed
+
+- Documentation was reorganized around `command`, `presentation`, and `output`.
+- Examples were grouped by usage level: Terminal Application, Layer Toolkit, Primitive Mechanics.
+- Public README now positions `icore` as terminal application mechanics, not only argv parsing.
+
+## [1.0.15]
+
+### Added
 
-## [1.0.12] - 2026-07-02
+- Added presentation primitives and renderers:
+  - `renderJson`
+  - `renderCsv`
+  - `renderCsvRow`
+  - `renderTextTable`
+  - `renderPresentationResult`
+  - `isPresentationResult`
+- Added reusable output writer primitives:
+  - `createStdoutWriter`
+  - `createStderrWriter`
+  - `createBackpressureTextWriter`
 
 ### Changed
 
-- Replaced the preliminary flag-only boolean option naming with `syntax: 'flag'`.
-- Documented flag-only boolean option behavior.
+- Extracted generic JSON/CSV/table rendering mechanics from project-specific CLI code.
+
+## [1.0.14]
+
+### Added
+
+- Added command mechanics facade: `createCommand()`.
+- Added command registry flow:
+  - `command.define(...)`
+  - `command.registry(...)`
+  - `commands.prepare(...)`
+  - `commands.run(...)`
+  - `commands.runFromArgs(...)`
+- Added lower-level command primitives:
+  - `defineCommand`
+  - `defineCommandRegistry`
+  - `createCommands`
+  - `resolveCommand`
+  - `prepareCommandFromArgs`
+  - `runPreparedCommand`
+  - `runCommandFromRegistry`
+  - `runCommand`
+
+### Changed
+
+- CLI command execution became explicitly two-phase: prepare without runtime context, then run with context.
+
+## [1.0.13]
+
+### Added
+
+- Added typed option schema composition with `mergeOptionsSchema`.
+- Added option inference helpers for parsed values and provided metadata.
+- Added command-name guards:
+  - `isCommandName`
+  - `isPreparedCommandName`
+- Added detailed option parsing contracts for cases where caller needs explicit provided/not-provided metadata.
+
+### Changed
+
+- Boolean option handling was tightened around flag syntax: `--flag` and `--no-flag`.
+
+## [1.0.12]
+
+### Added
+
+- Added core typed CLI option mechanics based on literal schemas:
+  - `type: 'string'`
+  - `type: 'boolean'`
+  - `type: 'number'`
+- Added GNU-style argv parsing:
+  - `--name value`
+  - `--name=value`
+  - `--flag`
+  - short aliases
+  - `--` terminator
+- Added machine-readable `IcoreError`.
+- Added initial TypeScript-first public API for command-line mechanics.
 
 ## [1.0.11] - 2026-07-02
 
@@ -202,6 +266,10 @@ conservative.
 - Detailed changelog entries were not maintained for these releases.
 
 [Unreleased]: https://github.com/woodger/icore/commits/develop
+[1.0.16]: https://www.npmjs.com/package/icore/v/1.0.16
+[1.0.15]: https://www.npmjs.com/package/icore/v/1.0.15
+[1.0.14]: https://www.npmjs.com/package/icore/v/1.0.14
+[1.0.13]: https://www.npmjs.com/package/icore/v/1.0.13
 [1.0.12]: https://www.npmjs.com/package/icore/v/1.0.12
 [1.0.11]: https://www.npmjs.com/package/icore/v/1.0.11
 [1.0.10]: https://www.npmjs.com/package/icore/v/1.0.10

package/dist/terminal/app.d.ts

@@ -9,7 +9,7 @@
  * This file must not contain argv tokenization, option validation internals,
  * domain behavior, or application-specific report mapping.
  */
-import type { CommandDefinition, CommandResolutionOptions, Commands, PreparedCommand } from '../command/mechanics';
+import type { CommandContext, CommandResolutionOptions, Commands, PreparedCommand } from '../command/mechanics';
 import type { OptionsSchema } from '../options/schema';
 import { type Presentation, type PresentationResult } from '../presentation/facade';
 import { type PresentationFormat } from '../presentation/format-options';
@@ -21,8 +21,27 @@ import { type Output } from '../output/facade';
  * or no output. Other result shapes are rejected before writing to stdout.
  */
 export type TerminalCommandOutput = string | AsyncIterable<string> | PresentationResult | undefined;
-type TerminalCommandDefinition<TContext> = CommandDefinition<OptionsSchema, TContext, TerminalCommandOutput, readonly [string, ...string[]], unknown, unknown>;
-export type TerminalAppOptions<TContext, TCommands extends readonly TerminalCommandDefinition<TContext>[]> = {
+type BivariantCallback<TInput, TOutput> = {
+    bivarianceHack(input: TInput): TOutput;
+}['bivarianceHack'];
+type TerminalCommandDefinition = {
+    path: readonly [string, ...string[]];
+    options: OptionsSchema;
+    metadata?: unknown;
+    allowExtraPositionals?: boolean;
+    prepare?: BivariantCallback<PreparedCommandInput, unknown | Promise<unknown>>;
+    handle: BivariantCallback<TerminalCommandInput, TerminalCommandOutput | Promise<TerminalCommandOutput>>;
+};
+type PreparedCommandInput = {
+    options: Record<string, unknown>;
+    provided: Record<string, boolean>;
+    positionals: string[];
+};
+type TerminalCommandInput = PreparedCommandInput & {
+    context: unknown;
+    payload?: unknown;
+};
+export type TerminalAppOptions<TCommands extends readonly TerminalCommandDefinition[]> = {
     commands: Commands<TCommands>;
     /** Custom presentation facade. */
     presentation?: Presentation;
@@ -31,14 +50,16 @@ export type TerminalAppOptions<TContext, TCommands extends readonly TerminalComm
     /** Resolves output format. */
     resolveFormat?(prepared: PreparedCommand<TCommands[number]>): PresentationFormat | undefined;
 };
-export type TerminalApp<TContext, TCommands extends readonly TerminalCommandDefinition<TContext>[]> = {
+export type TerminalApp<TCommands extends readonly TerminalCommandDefinition[]> = {
     commands: Commands<TCommands>;
     presentation: Presentation;
     output: Output;
     /** No application context required. */
     prepare(args: readonly string[], options?: CommandResolutionOptions): Promise<PreparedCommand<TCommands[number]>>;
+    /** Runs an already prepared command through terminal rendering and output. */
+    runPrepared(prepared: PreparedCommand<TCommands[number]>, context: CommandContext<TCommands[number]>): Promise<number>;
     /** Returns a process-style exit code. */
-    run(args: readonly string[], context: TContext, options?: CommandResolutionOptions): Promise<number>;
+    run(args: readonly string[], context: CommandContext<TCommands[number]>, options?: CommandResolutionOptions): Promise<number>;
 };
 /**
  * Composes command mechanics, presentation rendering, and output delivery into
@@ -47,5 +68,5 @@ export type TerminalApp<TContext, TCommands extends readonly TerminalCommandDefi
  * Command handlers keep ownership of application work; this facade only
  * prepares commands, renders supported terminal results, and writes output.
  */
-export declare function createTerminalApp<TContext, const TCommands extends readonly TerminalCommandDefinition<TContext>[]>(options: TerminalAppOptions<TContext, TCommands>): TerminalApp<TContext, TCommands>;
+export declare function createTerminalApp<const TCommands extends readonly TerminalCommandDefinition[]>(options: TerminalAppOptions<TCommands>): TerminalApp<TCommands>;
 export {};

package/dist/terminal/app.js

@@ -27,6 +27,18 @@ function createTerminalApp(options) {
     const presentation = options.presentation ?? (0, facade_1.createPresentation)();
     const output = options.output ?? (0, facade_2.createOutput)();
     const resolveFormat = options.resolveFormat ?? resolvePreparedFormat;
+    async function runPrepared(prepared, context) {
+        try {
+            const result = await options.commands.run(prepared, context);
+            const format = resolveFormat(prepared);
+            await writeTerminalOutput(result, format, presentation, output);
+            return 0;
+        }
+        catch (error) {
+            await output.error(renderTerminalError(error));
+            return 1;
+        }
+    }
     return {
         commands: options.commands,
         presentation,
@@ -34,13 +46,11 @@ function createTerminalApp(options) {
         prepare(args, commandOptions) {
             return options.commands.prepare(args, commandOptions);
         },
+        runPrepared,
         async run(args, context, commandOptions) {
             try {
                 const prepared = await options.commands.prepare(args, commandOptions);
-                const result = await options.commands.run(prepared, context);
-                const format = resolveFormat(prepared);
-                await writeTerminalOutput(result, format, presentation, output);
-                return 0;
+                return runPrepared(prepared, context);
             }
             catch (error) {
                 await output.error(renderTerminalError(error));

package/examples/two-phase-primitives.md

@@ -75,6 +75,35 @@ This is useful when the selected command decides which runtime resources to
 create. If preparation fails, the application can print an argument error
 without opening connections or starting background work.
 
+## Run Prepared Through A Terminal App
+
+`app.runPrepared(...)` keeps terminal rendering, stdout/stderr writing, and exit
+code handling in `createTerminalApp()` after the application has created its
+own runtime context.
+
+```ts
+const prepared = await app.prepare([
+  'jobs',
+  'run',
+  '--job-id',
+  'job-42'
+], {
+  strict: true
+});
+
+const context = await createContext(prepared);
+
+try {
+  process.exitCode = await app.runPrepared(prepared, context);
+}
+finally {
+  await cleanup(context);
+}
+```
+
+Resource creation and cleanup stay application-owned. The terminal app only
+runs the prepared command and applies the same output behavior as `app.run(...)`.
+
 ## Prepare From A Registry
 
 `prepareCommandFromArgs(...)` is the standalone primitive behind

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icore",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "Declarative command line interface and terminal presentation mechanics for Node.js",
   "keywords": [
     "command-line",

package/readme.md

@@ -80,8 +80,8 @@ without taking ownership of application behavior.
 
 The checked TypeScript contract lives in [`src/terminal/app.ts`](src/terminal/app.ts).
 
-The method returns an application object with `prepare(args)` and
-`run(args, context)`.
+The method returns an application object with `prepare(args)`,
+`runPrepared(prepared, context)`, and `run(args, context)`.
 
 Construction inputs:
 
@@ -97,6 +97,8 @@ Returned app methods:
 
 - `app.prepare(args, options?)` delegates to
   [`commands.prepare(args, options?)`](#commandsprepareargs-options);
+- `app.runPrepared(prepared, context)` runs an already prepared command, then
+  renders and writes terminal output;
 - `app.run(args, context, options?)` prepares the command, delegates command
   execution to [`commands.run(prepared, context)`](#commandsrunprepared-context),
   then renders and writes terminal output.