icore 1.0.14 → 1.0.16

package/examples/presentation-primitives.md

@@ -0,0 +1,190 @@
+# Presentation Primitives
+
+`createPresentation()` is the preferred entrypoint for terminal rendering. The
+primitives below are useful when a command needs explicit view types or when an
+adapter wants to use a renderer directly.
+
+Prefer `presentation.render(...)` first. Direct renderers are lower-level and
+make the caller responsible for choosing the right input shape.
+
+## Empty And Text Views
+
+Use `presentation.empty()` when a command succeeds without terminal output.
+Use `presentation.text(...)` when the command already owns final text.
+
+```ts
+import { createPresentation } from 'icore';
+
+const presentation = createPresentation();
+
+const noOutput = presentation.empty();
+const readyText = presentation.text('cache cleared\n');
+```
+
+These views are format-independent. Rendering them as `table`, `json`, or `csv`
+does not invent structure.
+
+## Record And Records Views
+
+Use `record(...)` and `records(...)` when application data can be represented as
+generic key/value objects.
+
+```ts
+const oneJob = presentation.record({
+  id: 'job-42',
+  status: 'running'
+});
+
+const manyJobs = presentation.records([
+  {
+    id: 'job-41',
+    status: 'done'
+  },
+  {
+    id: 'job-42',
+    status: 'running'
+  }
+]);
+
+presentation.render(oneJob, 'table');
+presentation.render(manyJobs, 'json');
+```
+
+This is the most convenient view for regular reports. The tradeoff is that
+field selection has to happen before the view is created; generic presentation
+code should not inspect domain objects.
+
+## Explicit Table And CSV Views
+
+Use `table(...)` when the application already owns prepared text cells.
+Use `csv(...)` when the application already owns CSV scalar rows.
+
+```ts
+const table = presentation.table([
+  ['id', 'status'],
+  ['job-41', 'done'],
+  ['job-42', 'running']
+]);
+
+const csv = presentation.csv([
+  ['id', 'status'],
+  ['job-41', 'done'],
+  ['job-42', 'running']
+]);
+```
+
+These forms are less convenient than `records(...)`, but they are useful when
+the application needs full control over column sequence and cell values.
+
+## Supported Formats
+
+Use `presentation.formats`, `presentationFormats`, and
+`isPresentationFormat(...)` when a custom boundary accepts a format option.
+
+```ts
+import {
+  isPresentationFormat,
+  presentationFormats
+} from 'icore';
+
+function normalizeFormat(value: unknown) {
+  return isPresentationFormat(value) ? value : 'table';
+}
+
+presentation.formats;
+presentationFormats;
+```
+
+This keeps format checks aligned with the renderer. Avoid copying the string
+union into application code.
+
+## Render Through The Facade
+
+`presentation.render(...)` delegates to `renderPresentationResult(...)`.
+
+```ts
+import { renderPresentationResult } from 'icore';
+
+const view = presentation.records([
+  {
+    id: 'job-42',
+    status: 'running'
+  }
+]);
+
+const fromFacade = presentation.render(view, 'csv');
+const fromPrimitive = renderPresentationResult(view, 'csv');
+```
+
+Prefer the facade in application code. The standalone function is useful for
+tests or custom presentation objects.
+
+## Check Presentation Results
+
+Use `isPresentationResult(...)` before rendering unknown command output.
+
+```ts
+import { isPresentationResult } from 'icore';
+
+function renderUnknown(value: unknown): string {
+  if (!isPresentationResult(value)) {
+    throw new Error('Expected presentation result');
+  }
+
+  return presentation.render(value, 'table');
+}
+```
+
+This is useful at generic boundaries. Inside a command handler, returning a
+known presentation view is usually clearer.
+
+## Use Direct Renderers
+
+The facade exposes renderers for code that already has renderer-specific input.
+
+```ts
+const jsonText = presentation.renderers.json.render({
+  ok: true
+});
+
+const tableText = presentation.renderers.table.render([
+  ['field', 'value'],
+  ['ok', 'true']
+]);
+
+const csvRow = presentation.renderers.csv.renderRow([
+  'job-42',
+  'running'
+]);
+
+const csvText = presentation.renderers.csv.render([
+  ['id', 'status'],
+  ['job-42', 'running']
+]);
+```
+
+The standalone functions provide the same lower-level behavior:
+
+```ts
+import {
+  renderCsv,
+  renderCsvRow,
+  renderJson,
+  renderTextTable
+} from 'icore';
+
+renderJson({ ok: true });
+renderTextTable([
+  ['field', 'value'],
+  ['ok', 'true']
+]);
+renderCsvRow(['job-42', 'running']);
+renderCsv([
+  ['id', 'status'],
+  ['job-42', 'running']
+]);
+```
+
+Direct renderers are sharp tools. They are good for adapters and tests, but
+regular commands should usually return presentation views and let
+`presentation.render(...)` choose the renderer.

package/examples/readme.md

@@ -0,0 +1,48 @@
+# Examples
+
+These examples are guide-style notes for application code. They explain what to
+put into a consuming project, how to run it from a terminal, what output to
+expect, and why a particular shape is useful or intentionally limited.
+
+## Terminal Application
+
+- [terminal-app.md](terminal-app.md) shows the regular `createTerminalApp()`
+  path with commands, presentation, and output.
+- [practical-cli-patterns.md](practical-cli-patterns.md) shows application-level
+  patterns for global help/version shortcuts, command help, deprecated options,
+  and edge-case argument handling.
+
+## Layer Toolkit
+
+- [option-schemas.md](option-schemas.md) shows how to describe string,
+  boolean, and number options with defaults, choices, aliases, and inferred
+  TypeScript types.
+- [cli-argument-syntax.md](cli-argument-syntax.md) documents supported CLI
+  argument syntax with terminal input examples.
+- [custom-command-flow.md](custom-command-flow.md) shows explicit
+  `commands.prepare(...)`, `commands.run(...)`, and `commands.runFromArgs(...)`
+  usage without the terminal app boundary.
+- [presentation-output.md](presentation-output.md) shows presentation rendering
+  and output writing without command execution.
+
+## Primitive Mechanics
+
+- [command-resolution.md](command-resolution.md) shows command registries,
+  explicit resolution, command-name guards, and standalone command definitions.
+- [two-phase-primitives.md](two-phase-primitives.md) shows lower-level
+  preparation and execution primitives used behind command facades.
+- [presentation-primitives.md](presentation-primitives.md) shows explicit
+  presentation views, renderers, and format guards.
+- [output-writers.md](output-writers.md) shows stdout/stderr writer primitives
+  and custom sink wiring.
+
+## Compatibility And Rework Candidates
+
+Some examples intentionally show public APIs that are useful but not preferred
+as the first choice for new application code. Those examples call out the
+tradeoff near the method usage.
+
+- [command-resolution.md](command-resolution.md) covers
+  `resolveCommandFromArgs(...)`.
+- [two-phase-primitives.md](two-phase-primitives.md) covers
+  `parseOptionsDetailed(...)` and `parseOptionsSubsetDetailed(...)`.

package/examples/terminal-app.md

@@ -0,0 +1,118 @@
+# Terminal App
+
+Use this shape when your package owns a command-line entrypoint and wants icore
+to connect command parsing, presentation rendering, and stdout/stderr writing.
+
+This is the default shape for a regular terminal application because it keeps
+the CLI boundary in one place: commands return text or presentation views, while
+`createTerminalApp()` owns rendering, stdout/stderr delivery, and exit codes.
+The tradeoff is that command handlers must return terminal-supported values,
+not arbitrary application objects.
+
+Create the file that becomes your CLI entrypoint, for example `src/cli.ts`, and
+put the terminal app composition there:
+
+```ts
+import {
+  createCommand,
+  createOutput,
+  createPresentation,
+  createTerminalApp,
+  presentationFormatOptions
+} from 'icore';
+
+type AppContext = {
+  currentUser: string;
+};
+
+const command = createCommand();
+const presentation = createPresentation();
+
+const commands = command.registry([
+  command.define({
+    path: ['users', 'current'],
+    options: presentationFormatOptions,
+    handle({ context }: {
+      context: AppContext;
+    }) {
+      return presentation.record({
+        user: context.currentUser
+      });
+    }
+  })
+] as const);
+
+const app = createTerminalApp({
+  commands,
+  presentation,
+  output: createOutput()
+});
+
+async function main(args: readonly string[]): Promise<void> {
+  process.exitCode = await app.run(args, {
+    currentUser: 'Alice'
+  }, {
+    strict: true
+  });
+}
+
+void main(process.argv.slice(2));
+```
+
+Create `command`, `presentation`, and `output` once near the entrypoint. That is
+slightly more explicit than hiding them behind defaults, but it keeps stdout,
+stderr, and format behavior visible at the terminal boundary. `strict: true`
+keeps the public command form predictable by rejecting option placement that the
+application does not intentionally support.
+
+After compiling the consuming project, run the generated entrypoint:
+
+```bash
+node dist/cli.js users current
+```
+
+The terminal prints the default table view:
+
+```text
+field  value
+user   Alice
+```
+
+Ask for JSON when the command should be consumed by another process:
+
+```bash
+node dist/cli.js users current --format json
+```
+
+The terminal prints:
+
+```json
+{
+  "user": "Alice"
+}
+```
+
+## Override Format Resolution
+
+By default, `createTerminalApp()` looks for a parsed `format` option and uses it
+when it is one of the supported presentation formats. Override `resolveFormat`
+when format policy is application-specific.
+
+```ts
+const appWithFormatPolicy = createTerminalApp({
+  commands,
+  presentation,
+  output: createOutput(),
+  resolveFormat(prepared) {
+    if (prepared.name === 'users export') {
+      return 'csv';
+    }
+
+    return undefined;
+  }
+});
+```
+
+This is useful when one command has a different default output contract. It is
+also a point where the application can make a bad abstraction: avoid hiding
+format decisions here when a normal `--format` option would be clearer.

package/examples/two-phase-primitives.md

@@ -0,0 +1,282 @@
+# Two-Phase Primitives
+
+The high-level flow is `commands.prepare(...)` followed by
+`commands.run(...)`. The primitives below are useful when a custom terminal
+boundary needs the same pieces without adopting the full facade.
+
+Prefer the facade first. These primitives are intentionally lower-level and
+become worthwhile only when the application needs a custom lifecycle.
+
+The snippets below use this setup:
+
+```ts
+import {
+  createCommand,
+  createTerminalApp
+} from 'icore';
+
+type AppContext = {
+  workspace: string;
+};
+
+const command = createCommand();
+
+const runJobCommand = command.define({
+  path: ['jobs', 'run'],
+  options: {
+    'job-id': {
+      type: 'string',
+      required: true
+    }
+  } as const,
+  prepare({ options }) {
+    return {
+      jobId: options['job-id'].trim()
+    };
+  },
+  handle({ payload, context }: {
+    payload: { jobId: string };
+    context: AppContext;
+  }) {
+    return `${context.workspace}:${payload.jobId}\n`;
+  }
+});
+
+const commands = command.registry([
+  runJobCommand
+] as const);
+
+const app = createTerminalApp({
+  commands
+});
+```
+
+## Prepare From A Terminal App
+
+`app.prepare(...)` lets an application validate command input before runtime
+context exists.
+
+```ts
+const prepared = await app.prepare([
+  'jobs',
+  'run',
+  '--job-id',
+  'job-42'
+], {
+  strict: true
+});
+
+prepared.name;
+prepared.options;
+prepared.provided;
+```
+
+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.
+
+## Prepare From A Registry
+
+`prepareCommandFromArgs(...)` is the standalone primitive behind
+`commands.prepare(...)`.
+
+```ts
+import {
+  prepareCommandFromArgs,
+  type CommandPayload
+} from 'icore';
+
+const prepared = await prepareCommandFromArgs(commands.registry, [
+  'jobs',
+  'run',
+  '--job-id',
+  'job-42'
+], {
+  strict: true
+});
+
+type Payload = CommandPayload<typeof runJobCommand>;
+```
+
+Use this when code owns a registry but does not use the `commands` object. The
+tradeoff is weaker readability: readers have to know which primitive maps to
+which facade method.
+
+## Run A Prepared Command
+
+`runPreparedCommand(...)` executes a command that was already resolved and
+validated.
+
+```ts
+import {
+  runPreparedCommand,
+  type CommandContext,
+  type CommandResult
+} from 'icore';
+
+type Context = CommandContext<typeof runJobCommand>;
+type Result = CommandResult<typeof runJobCommand>;
+
+const context: Context = {
+  workspace: 'local'
+};
+
+const result: Result = await runPreparedCommand(prepared, context);
+```
+
+This is the safest primitive when context creation has side effects. Prepare
+first, then create the exact context the selected command needs.
+
+## Narrow Prepared Commands
+
+`isPreparedCommandName(...)` narrows a prepared-command union by command name.
+
+```ts
+import { isPreparedCommandName } from 'icore';
+
+if (isPreparedCommandName(prepared, 'jobs run')) {
+  prepared.options['job-id'];
+}
+```
+
+Use this when several commands reuse one preparation flow but need different
+runtime setup. The guard is intentionally narrow: it checks the prepared
+command name, not arbitrary metadata.
+
+## Run From A Registry
+
+`runCommandFromRegistry(...)` is the standalone primitive behind
+`commands.runFromArgs(...)`.
+
+```ts
+import { runCommandFromRegistry } from 'icore';
+
+const output = await runCommandFromRegistry(
+  commands.registry,
+  [
+    'jobs',
+    'run',
+    '--job-id',
+    'job-42'
+  ],
+  {
+    workspace: 'local'
+  },
+  {
+    strict: true
+  }
+);
+```
+
+This is compact, but it removes the explicit gap between validation and runtime
+context creation. Use it when that gap does not matter.
+
+## Run One Command Without A Registry
+
+Use `command.run(...)` or standalone `runCommand(...)` for focused execution of
+one command.
+
+```ts
+import { runCommand } from 'icore';
+
+const outputFromFacade = await command.run(runJobCommand, [
+  'jobs',
+  'run',
+  '--job-id',
+  'job-42'
+], {
+  workspace: 'local'
+}, {
+  strict: true
+});
+
+const outputFromPrimitive = await runCommand(runJobCommand, [
+  'jobs',
+  'run',
+  '--job-id',
+  'job-42'
+], {
+  workspace: 'local'
+}, {
+  strict: true
+});
+```
+
+This is useful for tests and tiny tools. It is a poor fit for large CLIs because
+it skips registry-level command selection.
+
+## Read Provided Metadata
+
+`parseOptionsDetailed(...)` returns parsed values plus a presence map.
+
+```ts
+import {
+  parseOptionsDetailed,
+  type InferProvidedOptions
+} from 'icore';
+
+const schema = {
+  format: {
+    type: 'string',
+    choices: ['table', 'json'],
+    default: 'table'
+  },
+  verbose: {
+    type: 'boolean'
+  }
+} as const;
+
+const parsed = parseOptionsDetailed(schema, {
+  verbose: true
+});
+
+type Provided = InferProvidedOptions<typeof schema>;
+```
+
+The parsed options are:
+
+```ts
+{
+  format: 'table',
+  verbose: true
+}
+```
+
+The provided map is:
+
+```ts
+{
+  format: false,
+  verbose: true
+}
+```
+
+This distinction matters when defaults exist. The command can know whether the
+user explicitly typed an option or received the default.
+
+## Validate A Subset
+
+`parseOptionsSubsetDetailed(...)` validates only options known by one schema and
+leaves the rest untouched.
+
+```ts
+import { parseOptionsSubsetDetailed } from 'icore';
+
+const parsed = parseOptionsSubsetDetailed({
+  format: {
+    type: 'string',
+    choices: ['table', 'json']
+  }
+} as const, {
+  format: 'json',
+  token: 'secret'
+});
+
+parsed.options;
+parsed.rest;
+```
+
+This is useful for staged parsing where bootstrap options and command options
+are validated by different layers. It should be used carefully: accepting
+unknown rest values is a deliberate boundary decision, not a shortcut around
+validation.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "icore",
-  "version": "1.0.14",
-  "description": "Declarative command line interface mechanics for Node.js",
+  "version": "1.0.16",
+  "description": "Declarative command line interface and terminal presentation mechanics for Node.js",
   "keywords": [
     "command-line",
     "argv",
@@ -9,6 +9,11 @@
     "option-parser",
     "command-registry",
     "command-router",
+    "terminal-app",
+    "terminal-output",
+    "presentation",
+    "table-renderer",
+    "csv-renderer",
     "typed-cli",
     "declarative-cli"
   ],
@@ -28,13 +33,14 @@
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
-    "test": "node --test dist/*.test.js",
+    "test": "fwa --prune",
     "lint": "eslint src"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "@types/node": "^26.0.1",
     "eslint": "^9.39.4",
+    "fwa": "^2.0.6",
     "globals": "^17.7.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.62.0"