icore 1.0.17 → 1.0.19

package/CHANGELOG.md

@@ -9,48 +9,114 @@ 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.
+- Added `TerminalApp.writePreparedOutput(...)` for rendering and writing already obtained terminal output.
 
-### Removed
+### Changed
+
+- Changed `createTerminalApp` typing to accept command registries with void and prepared payloads.
+- Changed `createTerminalApp` typing to allow custom command results when consumers run prepared commands themselves.
+- 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 +268,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

@@ -15,10 +15,10 @@ import { type Presentation, type PresentationResult } from '../presentation/faca
 import { type PresentationFormat } from '../presentation/format-options';
 import { type Output } from '../output/facade';
 /**
- * Supported handler result shapes for the terminal app boundary.
+ * Supported terminal output shapes for the terminal app boundary.
  *
- * Domain commands may return ready text, streaming text, a presentation view,
- * or no output. Other result shapes are rejected before writing to stdout.
+ * Terminal output may be ready text, streaming text, a presentation view, or
+ * no output. Other result shapes are rejected before writing to stdout.
  */
 export type TerminalCommandOutput = string | AsyncIterable<string> | PresentationResult | undefined;
 type BivariantCallback<TInput, TOutput> = {
@@ -30,7 +30,7 @@ type TerminalCommandDefinition = {
     metadata?: unknown;
     allowExtraPositionals?: boolean;
     prepare?: BivariantCallback<PreparedCommandInput, unknown | Promise<unknown>>;
-    handle: BivariantCallback<TerminalCommandInput, TerminalCommandOutput | Promise<TerminalCommandOutput>>;
+    handle: BivariantCallback<TerminalCommandInput, unknown | Promise<unknown>>;
 };
 type PreparedCommandInput = {
     options: Record<string, unknown>;
@@ -56,6 +56,15 @@ export type TerminalApp<TCommands extends readonly TerminalCommandDefinition[]>
     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>;
+    /**
+     * Renders and writes already obtained terminal output.
+     *
+     * String output is written exactly as provided; add a trailing newline in the
+     * command result when line output is desired.
+     */
+    writePreparedOutput(prepared: PreparedCommand<TCommands[number]>, output: TerminalCommandOutput): Promise<void>;
     /** Returns a process-style exit code. */
     run(args: readonly string[], context: CommandContext<TCommands[number]>, options?: CommandResolutionOptions): Promise<number>;
 };

package/dist/terminal/app.js

@@ -27,6 +27,21 @@ 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 writePreparedOutput(prepared, terminalOutput) {
+        const format = resolveFormat(prepared);
+        await writeTerminalOutput(terminalOutput, format, presentation, output);
+    }
+    async function runPrepared(prepared, context) {
+        try {
+            const result = await options.commands.run(prepared, context);
+            await writeTerminalOutput(result, resolveFormat(prepared), presentation, output);
+            return 0;
+        }
+        catch (error) {
+            await output.error(renderTerminalError(error));
+            return 1;
+        }
+    }
     return {
         commands: options.commands,
         presentation,
@@ -34,13 +49,12 @@ function createTerminalApp(options) {
         prepare(args, commandOptions) {
             return options.commands.prepare(args, commandOptions);
         },
+        runPrepared,
+        writePreparedOutput,
         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,72 @@ 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(...)`.
+
+## Write Prepared Output
+
+Use `app.writePreparedOutput(...)` when the application needs to inspect the raw
+command result before terminal output is written.
+
+```ts
+const prepared = await app.prepare([
+  'jobs',
+  'run',
+  '--job-id',
+  'job-42'
+], {
+  strict: true
+});
+
+const context = await createContext(prepared);
+
+try {
+  const result = await app.commands.run(prepared, context);
+
+  if (isShutdownHandle(result)) {
+    installShutdownHooks(result);
+
+    return;
+  }
+
+  await app.writePreparedOutput(prepared, result);
+}
+finally {
+  await cleanup(context);
+}
+```
+
+Only terminal output belongs here: ready text, streaming text, presentation
+results, or no output. Strings are written exactly as provided; include `\n`
+when line output is desired.
+
 ## Prepare From A Registry
 
 `prepareCommandFromArgs(...)` is the standalone primitive behind

package/package.json

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

package/readme.md

@@ -80,7 +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
+The method returns an application object with `prepare(args)`,
+`writePreparedOutput(prepared, output)`, `runPrepared(prepared, context)`, and
 `run(args, context)`.
 
 Construction inputs:
@@ -97,6 +98,10 @@ Returned app methods:
 
 - `app.prepare(args, options?)` delegates to
   [`commands.prepare(args, options?)`](#commandsprepareargs-options);
+- `app.writePreparedOutput(prepared, output)` renders and writes already
+  obtained terminal output without running the command;
+- `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.
@@ -116,10 +121,15 @@ const exitCode = await app.run(args, context, {
 });
 ```
 
-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.
+Command handlers keep ownership of application work. Terminal output methods
+accept terminal-ready results: text, streaming text, presentation results, or no
+output. If a command returns an application lifecycle object, run it with
+`app.commands.run(...)`, inspect or map the result, then pass only terminal
+output to `app.writePreparedOutput(...)`. Application DTO mapping, config
+loading, network clients, and domain behavior stay in the consuming application.
+
+String output is written exactly as provided. Return `\n` from the command when
+line output is desired.
 
 ### `createCommand()`