icore 1.0.14 → 1.0.16

package/dist/presentation/renderers/table.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * The text table renderer module converts text rows to aligned terminal text.
+ *
+ * Allowed here:
+ * - computing column widths;
+ * - rendering already prepared string cells;
+ *
+ * This file must not contain domain-specific scalar formatting.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTextTable = renderTextTable;
+/**
+ * Renders prepared text rows as an aligned table without changing cell values.
+ */
+function renderTextTable(rows) {
+    if (rows.length === 0) {
+        return '';
+    }
+    const columnCount = Math.max(...rows.map((row) => row.length));
+    const widths = Array.from({ length: columnCount }, (_, columnIndex) => Math.max(...rows.map((row) => (row[columnIndex] ?? '').length)));
+    return [
+        ...rows.map((row) => widths
+            .map((width, columnIndex) => (row[columnIndex] ?? '').padEnd(width))
+            .join('  ')
+            .trimEnd()),
+        ''
+    ].join('\n');
+}

package/dist/presentation/result-renderer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The presentation result renderer converts generic presentation views into
+ * terminal text using the selected output format.
+ *
+ * Allowed here:
+ * - dispatching presentation views to JSON, CSV, and table renderers;
+ * - converting generic records to renderer input rows;
+ * - validating generic presentation result shapes;
+ *
+ * This file must not contain command execution, stdout/stderr delivery, or
+ * application report mapping.
+ */
+import type { PresentationFormat } from './format-options';
+import type { PresentationResult } from './view';
+/**
+ * Renders a presentation result after the caller selects the terminal format.
+ *
+ * Record-like views are projected to table or CSV rows inside this boundary so
+ * applications do not duplicate generic renderer input shaping.
+ */
+export declare function renderPresentationResult(result: PresentationResult, format?: PresentationFormat): string;
+/**
+ * Checks whether an unknown command result is a supported presentation result.
+ */
+export declare function isPresentationResult(value: unknown): value is PresentationResult;

package/dist/presentation/result-renderer.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * The presentation result renderer converts generic presentation views into
+ * terminal text using the selected output format.
+ *
+ * Allowed here:
+ * - dispatching presentation views to JSON, CSV, and table renderers;
+ * - converting generic records to renderer input rows;
+ * - validating generic presentation result shapes;
+ *
+ * This file must not contain command execution, stdout/stderr delivery, or
+ * application report mapping.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPresentationResult = renderPresentationResult;
+exports.isPresentationResult = isPresentationResult;
+const csv_1 = require("./renderers/csv");
+const json_1 = require("./renderers/json");
+const table_1 = require("./renderers/table");
+/**
+ * Renders a presentation result after the caller selects the terminal format.
+ *
+ * Record-like views are projected to table or CSV rows inside this boundary so
+ * applications do not duplicate generic renderer input shaping.
+ */
+function renderPresentationResult(result, format = 'table') {
+    if (result.type === 'empty') {
+        return '';
+    }
+    if (result.type === 'text') {
+        return result.value;
+    }
+    if (format === 'json') {
+        return (0, json_1.renderJson)(presentationResultToJsonValue(result));
+    }
+    if (result.type === 'table') {
+        return format === 'csv'
+            ? (0, csv_1.renderCsv)(result.rows)
+            : (0, table_1.renderTextTable)(result.rows);
+    }
+    if (result.type === 'csv') {
+        return format === 'csv'
+            ? (0, csv_1.renderCsv)(result.rows)
+            : (0, table_1.renderTextTable)(rowsToTextRows(result.rows));
+    }
+    if (result.type === 'record') {
+        return format === 'csv'
+            ? (0, csv_1.renderCsv)(recordToCsvRows(result.value))
+            : (0, table_1.renderTextTable)(recordToTextRows(result.value));
+    }
+    return format === 'csv'
+        ? (0, csv_1.renderCsv)(recordsToCsvRows(result.value))
+        : (0, table_1.renderTextTable)(recordsToTextRows(result.value));
+}
+/**
+ * Checks whether an unknown command result is a supported presentation result.
+ */
+function isPresentationResult(value) {
+    if (typeof value !== 'object' || value === null || !('type' in value)) {
+        return false;
+    }
+    const result = value;
+    if (result['type'] === 'empty') {
+        return true;
+    }
+    if (result['type'] === 'text') {
+        return typeof result['value'] === 'string';
+    }
+    if (result['type'] === 'record') {
+        return result['value'] === null || isRecord(result['value']);
+    }
+    if (result['type'] === 'records') {
+        return Array.isArray(result['value']);
+    }
+    if (result['type'] === 'table' || result['type'] === 'csv') {
+        return Array.isArray(result['rows']);
+    }
+    return false;
+}
+function presentationResultToJsonValue(result) {
+    if (result.type === 'empty') {
+        return null;
+    }
+    if (result.type === 'text') {
+        return result.value;
+    }
+    if (result.type === 'record') {
+        return result.value;
+    }
+    if (result.type === 'records') {
+        return result.value;
+    }
+    if (result.type === 'table') {
+        return result.rows;
+    }
+    if (result.type === 'csv') {
+        return result.rows;
+    }
+    return assertNever(result);
+}
+function recordToTextRows(record) {
+    if (record === null) {
+        return [];
+    }
+    return [
+        ['field', 'value'],
+        ...Object.keys(record).map((key) => [
+            key,
+            formatPresentationCell(record[key])
+        ])
+    ];
+}
+function recordsToTextRows(records) {
+    if (records.length === 0) {
+        return [];
+    }
+    const keys = collectRecordKeys(records);
+    return [
+        keys,
+        ...records.map((record) => keys.map((key) => formatPresentationCell(record[key])))
+    ];
+}
+function recordToCsvRows(record) {
+    if (record === null) {
+        return [];
+    }
+    const keys = Object.keys(record);
+    return [
+        keys,
+        keys.map((key) => toCsvCell(record[key]))
+    ];
+}
+function recordsToCsvRows(records) {
+    if (records.length === 0) {
+        return [];
+    }
+    const keys = collectRecordKeys(records);
+    return [
+        keys,
+        ...records.map((record) => keys.map((key) => toCsvCell(record[key])))
+    ];
+}
+function rowsToTextRows(rows) {
+    return rows.map((row) => row.map(formatPresentationCell));
+}
+function collectRecordKeys(records) {
+    const keys = [];
+    const seen = new Set();
+    for (const record of records) {
+        for (const key of Object.keys(record)) {
+            if (!seen.has(key)) {
+                keys.push(key);
+                seen.add(key);
+            }
+        }
+    }
+    return keys;
+}
+function formatPresentationCell(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return JSON.stringify(value) ?? String(value);
+}
+function toCsvCell(value) {
+    if (typeof value === 'string'
+        || typeof value === 'number'
+        || typeof value === 'boolean') {
+        return value;
+    }
+    return formatPresentationCell(value);
+}
+function assertNever(value) {
+    throw new Error(`Unexpected presentation result: ${String(value)}`);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/presentation/view.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The presentation view module defines generic terminal view models.
+ *
+ * Allowed here:
+ * - JSON-like record views;
+ * - explicit table and CSV views;
+ * - text and empty terminal result views;
+ *
+ * This file must not contain renderer implementation or application report
+ * mapping.
+ */
+export type CsvCell = string | number | boolean;
+export type CsvRow = readonly CsvCell[];
+export type TextTableRow = readonly string[];
+export type PresentationRecord = Readonly<Record<string, unknown>>;
+export type EmptyPresentationView = {
+    type: 'empty';
+};
+export type TextPresentationView = {
+    type: 'text';
+    value: string;
+};
+export type RecordPresentationView = {
+    type: 'record';
+    value: PresentationRecord | null;
+};
+export type RecordsPresentationView = {
+    type: 'records';
+    value: readonly PresentationRecord[];
+};
+export type TablePresentationView = {
+    type: 'table';
+    rows: readonly TextTableRow[];
+};
+export type CsvPresentationView = {
+    type: 'csv';
+    rows: readonly CsvRow[];
+};
+export type PresentationView = EmptyPresentationView | TextPresentationView | RecordPresentationView | RecordsPresentationView | TablePresentationView | CsvPresentationView;
+export type PresentationResult = PresentationView;
+export type PresentationViewFactory = {
+    /** No output. */
+    empty(): EmptyPresentationView;
+    /** Ready terminal text. */
+    text(value: string): TextPresentationView;
+    /** One generic record. */
+    record(value: PresentationRecord | null): RecordPresentationView;
+    /** Generic records. */
+    records(value: readonly PresentationRecord[]): RecordsPresentationView;
+    /** Prepared text rows. */
+    table(rows: readonly TextTableRow[]): TablePresentationView;
+    /** CSV scalar rows. */
+    csv(rows: readonly CsvRow[]): CsvPresentationView;
+};
+/**
+ * Creates view-model factory methods without binding them to an output format.
+ */
+export declare function createPresentationViewFactory(): PresentationViewFactory;

package/dist/presentation/view.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * The presentation view module defines generic terminal view models.
+ *
+ * Allowed here:
+ * - JSON-like record views;
+ * - explicit table and CSV views;
+ * - text and empty terminal result views;
+ *
+ * This file must not contain renderer implementation or application report
+ * mapping.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPresentationViewFactory = createPresentationViewFactory;
+/**
+ * Creates view-model factory methods without binding them to an output format.
+ */
+function createPresentationViewFactory() {
+    return {
+        empty() {
+            return {
+                type: 'empty'
+            };
+        },
+        text(value) {
+            return {
+                type: 'text',
+                value
+            };
+        },
+        record(value) {
+            return {
+                type: 'record',
+                value
+            };
+        },
+        records(value) {
+            return {
+                type: 'records',
+                value
+            };
+        },
+        table(rows) {
+            return {
+                type: 'table',
+                rows
+            };
+        },
+        csv(rows) {
+            return {
+                type: 'csv',
+                rows
+            };
+        }
+    };
+}

package/dist/terminal/app.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The terminal app module composes command, presentation, and output mechanics.
+ *
+ * Allowed here:
+ * - preparing and running command facades;
+ * - rendering presentation results;
+ * - writing command output through the output facade;
+ *
+ * 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 { OptionsSchema } from '../options/schema';
+import { type Presentation, type PresentationResult } from '../presentation/facade';
+import { type PresentationFormat } from '../presentation/format-options';
+import { type Output } from '../output/facade';
+/**
+ * Supported handler result 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.
+ */
+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>[]> = {
+    commands: Commands<TCommands>;
+    /** Custom presentation facade. */
+    presentation?: Presentation;
+    /** Custom output facade. */
+    output?: Output;
+    /** Resolves output format. */
+    resolveFormat?(prepared: PreparedCommand<TCommands[number]>): PresentationFormat | undefined;
+};
+export type TerminalApp<TContext, TCommands extends readonly TerminalCommandDefinition<TContext>[]> = {
+    commands: Commands<TCommands>;
+    presentation: Presentation;
+    output: Output;
+    /** No application context required. */
+    prepare(args: readonly string[], options?: CommandResolutionOptions): Promise<PreparedCommand<TCommands[number]>>;
+    /** Returns a process-style exit code. */
+    run(args: readonly string[], context: TContext, options?: CommandResolutionOptions): Promise<number>;
+};
+/**
+ * Composes command mechanics, presentation rendering, and output delivery into
+ * a terminal application boundary.
+ *
+ * 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 {};

package/dist/terminal/app.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * The terminal app module composes command, presentation, and output mechanics.
+ *
+ * Allowed here:
+ * - preparing and running command facades;
+ * - rendering presentation results;
+ * - writing command output through the output facade;
+ *
+ * This file must not contain argv tokenization, option validation internals,
+ * domain behavior, or application-specific report mapping.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTerminalApp = createTerminalApp;
+const facade_1 = require("../presentation/facade");
+const format_options_1 = require("../presentation/format-options");
+const result_renderer_1 = require("../presentation/result-renderer");
+const facade_2 = require("../output/facade");
+/**
+ * Composes command mechanics, presentation rendering, and output delivery into
+ * a terminal application boundary.
+ *
+ * Command handlers keep ownership of application work; this facade only
+ * prepares commands, renders supported terminal results, and writes output.
+ */
+function createTerminalApp(options) {
+    const presentation = options.presentation ?? (0, facade_1.createPresentation)();
+    const output = options.output ?? (0, facade_2.createOutput)();
+    const resolveFormat = options.resolveFormat ?? resolvePreparedFormat;
+    return {
+        commands: options.commands,
+        presentation,
+        output,
+        prepare(args, commandOptions) {
+            return options.commands.prepare(args, commandOptions);
+        },
+        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;
+            }
+            catch (error) {
+                await output.error(renderTerminalError(error));
+                return 1;
+            }
+        }
+    };
+}
+/**
+ * Writes only terminal-supported command output shapes.
+ *
+ * This keeps the terminal boundary explicit: application objects must be
+ * mapped to text or presentation views before they reach stdout.
+ */
+async function writeTerminalOutput(result, format, presentation, output) {
+    if (result === undefined) {
+        return;
+    }
+    if (typeof result === 'string') {
+        await output.write(result);
+        return;
+    }
+    if (isAsyncIterable(result)) {
+        for await (const chunk of result) {
+            await output.write(chunk);
+        }
+        return;
+    }
+    if ((0, result_renderer_1.isPresentationResult)(result)) {
+        await output.write(presentation.render(result, format));
+        return;
+    }
+    throw new Error('Expected terminal command output');
+}
+/**
+ * Keeps the default format convention local to terminal composition.
+ */
+function resolvePreparedFormat(prepared) {
+    const options = prepared.options;
+    const format = options['format'];
+    return (0, format_options_1.isPresentationFormat)(format) ? format : undefined;
+}
+/**
+ * Converts thrown values to terminal error text without changing the error
+ * contract exposed to command handlers.
+ */
+function renderTerminalError(error) {
+    if (error instanceof Error) {
+        return `${error.message}\n`;
+    }
+    return `${String(error)}\n`;
+}
+function isAsyncIterable(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && Symbol.asyncIterator in value);
+}