icore 1.0.18 → 1.0.19

package/CHANGELOG.md

@@ -17,10 +17,12 @@ verified against git tags.
 ### Added
 
 - Added `TerminalApp.runPrepared(...)` for running prepared commands through terminal rendering and output.
+- Added `TerminalApp.writePreparedOutput(...)` for rendering and writing already obtained terminal output.
 
 ### 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]

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>;
@@ -58,6 +58,13 @@ export type TerminalApp<TCommands extends readonly TerminalCommandDefinition[]>
     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,11 +27,14 @@ 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);
-            const format = resolveFormat(prepared);
-            await writeTerminalOutput(result, format, presentation, output);
+            await writeTerminalOutput(result, resolveFormat(prepared), presentation, output);
             return 0;
         }
         catch (error) {
@@ -47,6 +50,7 @@ function createTerminalApp(options) {
             return options.commands.prepare(args, commandOptions);
         },
         runPrepared,
+        writePreparedOutput,
         async run(args, context, commandOptions) {
             try {
                 const prepared = await options.commands.prepare(args, commandOptions);

package/examples/two-phase-primitives.md

@@ -104,6 +104,43 @@ finally {
 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.18",
+  "version": "1.0.19",
   "description": "Declarative command line interface and terminal presentation mechanics for Node.js",
   "keywords": [
     "command-line",

package/readme.md

@@ -81,7 +81,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)`,
-`runPrepared(prepared, context)`, and `run(args, context)`.
+`writePreparedOutput(prepared, output)`, `runPrepared(prepared, context)`, and
+`run(args, context)`.
 
 Construction inputs:
 
@@ -97,6 +98,8 @@ 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
@@ -118,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()`