@jakubmazanec/cli 0.1.0-a500263

package/dist/ui/internals/Wrapper.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box } from 'ink';
+import { useMemo } from 'react';
+import errorBoundary from 'react-error-boundary';
+import { programContext } from './programContext.js';
+import { Failure } from '../Failure.js';
+/**
+ * A component that wraps anything {@linkcode Program} tries to render with an error boundary and all neccessary providers.
+ */ export const Wrapper = ({ program , children  })=>{
+    let programContextValue = useMemo(()=>({
+            program
+        }), [
+        program
+    ]);
+    return /*#__PURE__*/ _jsx(errorBoundary.ErrorBoundary, {
+        FallbackComponent: Failure,
+        children: /*#__PURE__*/ _jsx(programContext.Provider, {
+            value: programContextValue,
+            children: /*#__PURE__*/ _jsx(Box, {
+                children: children
+            })
+        })
+    });
+};
+
+//# sourceMappingURL=Wrapper.js.map

package/dist/ui/internals/Wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/ui/internals/Wrapper.tsx"],"sourcesContent":["import {Box} from 'ink';\nimport {useMemo, type FC, type PropsWithChildren} from 'react';\nimport errorBoundary from 'react-error-boundary';\n\nimport {programContext} from './programContext.js';\nimport {type Program} from '../../program.js';\nimport {Failure} from '../Failure.js';\n\n/**\n * {@linkcode Wrapper} component props.\n */\nexport type WrapperProps = {\n  program: Program;\n};\n\n/**\n * A component that wraps anything {@linkcode Program} tries to render with an error boundary and all neccessary providers.\n */\nexport const Wrapper: FC<PropsWithChildren<WrapperProps>> = ({program, children}) => {\n  let programContextValue = useMemo(\n    () => ({\n      program,\n    }),\n    [program],\n  );\n\n  return (\n    <errorBoundary.ErrorBoundary FallbackComponent={Failure}>\n      <programContext.Provider value={programContextValue}>\n        <Box>{children}</Box>\n      </programContext.Provider>\n    </errorBoundary.ErrorBoundary>\n  );\n};\n"],"names":["Box","useMemo","errorBoundary","programContext","Failure","Wrapper","program","children","programContextValue","ErrorBoundary","FallbackComponent","Provider","value"],"mappings":";AAAA,SAAQA,GAAG,QAAO,MAAM;AACxB,SAAQC,OAAO,QAAwC,QAAQ;AAC/D,OAAOC,mBAAmB,uBAAuB;AAEjD,SAAQC,cAAc,QAAO,sBAAsB;AAEnD,SAAQC,OAAO,QAAO,gBAAgB;AAStC;;CAEC,GACD,OAAO,MAAMC,UAA+C,CAAC,EAACC,QAAO,EAAEC,SAAQ,EAAC;IAC9E,IAAIC,sBAAsBP,QACxB,IAAO,CAAA;YACLK;QACF,CAAA,GACA;QAACA;KAAQ;IAGX,qBACE,KAACJ,cAAcO;QAAcC,mBAAmBN;kBAC9C,cAAA,KAACD,eAAeQ;YAASC,OAAOJ;sBAC9B,cAAA,KAACR;0BAAKO;;;;AAId,EAAE"}

package/dist/ui/internals/programContext.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import { type Program } from '../../program/Program.js';
+export type ProgramContext = {
+    program: Program;
+};
+/**
+ * A React context that stores {@linkcode Program} instance.
+ */
+export declare const programContext: React.Context<ProgramContext>;

package/dist/ui/internals/programContext.js

@@ -0,0 +1,6 @@
+import React from 'react';
+/**
+ * A React context that stores {@linkcode Program} instance.
+ */ export const programContext = React.createContext({});
+
+//# sourceMappingURL=programContext.js.map

package/dist/ui/internals/programContext.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/ui/internals/programContext.ts"],"sourcesContent":["import React from 'react';\n\nimport {type Program} from '../../program/Program.js';\n\nexport type ProgramContext = {\n  program: Program;\n};\n\n/**\n * A React context that stores {@linkcode Program} instance.\n */\nexport const programContext = React.createContext<ProgramContext>({} as ProgramContext);\n"],"names":["React","programContext","createContext"],"mappings":"AAAA,OAAOA,WAAW,QAAQ;AAQ1B;;CAEC,GACD,OAAO,MAAMC,iBAAiBD,MAAME,cAA8B,CAAC,GAAqB"}

package/dist/ui/internals/rotate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Rotate an array by `n` places.
+ *
+ * @param value An array to rotate.
+ * @param n By how many places the items should move.
+ * @returns The new item with items rotated.
+ */
+export declare function rotate<T>(value: T[], n: number): T[];

package/dist/ui/internals/rotate.js

@@ -0,0 +1,17 @@
+/**
+ * Rotate an array by `n` places.
+ *
+ * @param value An array to rotate.
+ * @param n By how many places the items should move.
+ * @returns The new item with items rotated.
+ */ export function rotate(value, n) {
+    let x = [
+        ...value
+    ];
+    return [
+        ...x.splice(-n % x.length),
+        ...x
+    ];
+}
+
+//# sourceMappingURL=rotate.js.map

package/dist/ui/internals/rotate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/ui/internals/rotate.ts"],"sourcesContent":["/**\n * Rotate an array by `n` places.\n *\n * @param value An array to rotate.\n * @param n By how many places the items should move.\n * @returns The new item with items rotated.\n */\nexport function rotate<T>(value: T[], n: number) {\n  let x = [...value];\n\n  return [...x.splice(-n % x.length), ...x];\n}\n"],"names":["rotate","value","n","x","splice","length"],"mappings":"AAAA;;;;;;CAMC,GACD,OAAO,SAASA,OAAUC,KAAU,EAAEC,CAAS;IAC7C,IAAIC,IAAI;WAAIF;KAAM;IAElB,OAAO;WAAIE,EAAEC,OAAO,CAACF,IAAIC,EAAEE;WAAYF;KAAE;AAC3C"}

package/dist/ui/internals.d.ts

@@ -0,0 +1,3 @@
+export * from './internals/programContext.js';
+export * from './internals/rotate.js';
+export * from './internals/Wrapper.js';

package/dist/ui/internals.js

@@ -0,0 +1,5 @@
+export * from './internals/programContext.js';
+export * from './internals/rotate.js';
+export * from './internals/Wrapper.js';
+
+//# sourceMappingURL=internals.js.map

package/dist/ui/internals.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ui/internals.ts"],"sourcesContent":["export * from './internals/programContext.js';\nexport * from './internals/rotate.js';\nexport * from './internals/Wrapper.js';\n"],"names":[],"mappings":"AAAA,cAAc,gCAAgC;AAC9C,cAAc,wBAAwB;AACtC,cAAc,yBAAyB"}

package/dist/ui/useProgram.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A React hook for accessing {@linkcode Program} instance and `exit` function that is used for showing an error (via an error boundary) and exiting.
+ */
+export declare function useProgram(): {
+    program: import("../program.js").Program;
+    exit: (error: unknown) => void;
+};

package/dist/ui/useProgram.js

@@ -0,0 +1,24 @@
+import { useApp } from 'ink';
+import { useCallback, useContext } from 'react';
+import errorBoundary from 'react-error-boundary';
+import { programContext } from './internals.js';
+/**
+ * A React hook for accessing {@linkcode Program} instance and `exit` function that is used for showing an error (via an error boundary) and exiting.
+ */ export function useProgram() {
+    let { showBoundary  } = errorBoundary.useErrorBoundary();
+    let { exit: appExit  } = useApp();
+    let { program  } = useContext(programContext);
+    let exit = useCallback((error)=>{
+        showBoundary(error);
+        appExit(error);
+    }, [
+        appExit,
+        showBoundary
+    ]);
+    return {
+        program,
+        exit
+    };
+}
+
+//# sourceMappingURL=useProgram.js.map

package/dist/ui/useProgram.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ui/useProgram.ts"],"sourcesContent":["import {useApp} from 'ink';\nimport {useCallback, useContext} from 'react';\nimport errorBoundary from 'react-error-boundary';\n\nimport {programContext} from './internals.js';\n\n/**\n * A React hook for accessing {@linkcode Program} instance and `exit` function that is used for showing an error (via an error boundary) and exiting.\n */\nexport function useProgram() {\n  let {showBoundary} = errorBoundary.useErrorBoundary();\n  let {exit: appExit} = useApp();\n  let {program} = useContext(programContext);\n\n  let exit = useCallback(\n    (error: unknown) => {\n      showBoundary(error);\n      appExit(error as Error);\n    },\n    [appExit, showBoundary],\n  );\n\n  return {program, exit};\n}\n"],"names":["useApp","useCallback","useContext","errorBoundary","programContext","useProgram","showBoundary","useErrorBoundary","exit","appExit","program","error"],"mappings":"AAAA,SAAQA,MAAM,QAAO,MAAM;AAC3B,SAAQC,WAAW,EAAEC,UAAU,QAAO,QAAQ;AAC9C,OAAOC,mBAAmB,uBAAuB;AAEjD,SAAQC,cAAc,QAAO,iBAAiB;AAE9C;;CAEC,GACD,OAAO,SAASC;IACd,IAAI,EAACC,aAAY,EAAC,GAAGH,cAAcI;IACnC,IAAI,EAACC,MAAMC,QAAO,EAAC,GAAGT;IACtB,IAAI,EAACU,QAAO,EAAC,GAAGR,WAAWE;IAE3B,IAAII,OAAOP,YACT,CAACU;QACCL,aAAaK;QACbF,QAAQE;IACV,GACA;QAACF;QAASH;KAAa;IAGzB,OAAO;QAACI;QAASF;IAAI;AACvB"}

package/dist/ui.d.ts

@@ -0,0 +1,10 @@
+export * as colors from './ui/colors.js';
+export * from './ui/ErrorDetail.js';
+export * from './ui/form.js';
+export * from './ui/getErrorDetail.js';
+export * as icons from './ui/icons.js';
+export * from './ui/useProgram.js';
+export * from './ui/Failure.js';
+export * from './ui/Header.js';
+export * from './ui/Help.js';
+export * from './ui/Spinner.js';

package/dist/ui.js

@@ -0,0 +1,12 @@
+export * as colors from './ui/colors.js';
+export * from './ui/ErrorDetail.js';
+export * from './ui/form.js';
+export * from './ui/getErrorDetail.js';
+export * as icons from './ui/icons.js';
+export * from './ui/useProgram.js';
+export * from './ui/Failure.js';
+export * from './ui/Header.js';
+export * from './ui/Help.js';
+export * from './ui/Spinner.js';
+
+//# sourceMappingURL=ui.js.map

package/dist/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ui.ts"],"sourcesContent":["export * as colors from './ui/colors.js';\nexport * from './ui/ErrorDetail.js';\nexport * from './ui/form.js';\nexport * from './ui/getErrorDetail.js';\nexport * as icons from './ui/icons.js';\nexport * from './ui/useProgram.js';\nexport * from './ui/Failure.js';\nexport * from './ui/Header.js';\nexport * from './ui/Help.js';\nexport * from './ui/Spinner.js';\n"],"names":["colors","icons"],"mappings":"AAAA,OAAO,KAAKA,MAAM,MAAM,iBAAiB;AACzC,cAAc,sBAAsB;AACpC,cAAc,eAAe;AAC7B,cAAc,yBAAyB;AACvC,OAAO,KAAKC,KAAK,MAAM,gBAAgB;AACvC,cAAc,qBAAqB;AACnC,cAAc,kBAAkB;AAChC,cAAc,iBAAiB;AAC/B,cAAc,eAAe;AAC7B,cAAc,kBAAkB"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@jakubmazanec/cli",
+  "version": "0.1.0-a500263",
+  "description": "TypeScript-first library for building CLIs.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jakubmazanec/js-tools",
+    "directory": "packages/cli"
+  },
+  "license": "LGPL-3.0-only",
+  "author": "Jakub Mazanec <jakub@mazanec.dev>",
+  "sideEffects": false,
+  "type": "module",
+  "exports": "./dist/main.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "swc src -d dist && tsc",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "develop": "concurrently \"swc src -d dist --watch\" \"tsc --watch\"",
+    "document": "typedoc --options typedoc.config.cjs",
+    "format": "prettier . --write --ignore-unknown --ignore-path ../../.prettierignore",
+    "lint": "eslint .",
+    "test": "cross-env FORCE_COLOR=1 NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
+    "typecheck": "tsc --project tsconfig.typecheck.json"
+  },
+  "dependencies": {
+    "@jakubmazanec/args": "1.0.1-a500263",
+    "@jakubmazanec/error": "2.0.1-a500263",
+    "@jakubmazanec/ts-utils": "2.1.0-a500263",
+    "@jakubmazanec/zod-utils": "1.0.0-a500263",
+    "chalk": "^5.2.0",
+    "lodash": "^4.17.21",
+    "react-error-boundary": "^4.0.7"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@types/lodash": "^4.14.195",
+    "@types/node": "^16.18.3",
+    "@types/react": "^18.0.26",
+    "ink": "^3.2.0",
+    "ink-testing-library": "^3.0.0",
+    "react": "^18.2.0"
+  },
+  "peerDependencies": {
+    "@types/react": "17.x || 18.x",
+    "ink": "^3.0.0",
+    "react": "17.x || 18.x"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "packageManager": "npm@8.19.4",
+  "engines": {
+    "node": ">=16.20.0"
+  }
+}

package/src/constants.ts

@@ -0,0 +1 @@
+export const DELIMITER = '$ ';

package/src/main.ts

@@ -0,0 +1,2 @@
+export * from './program.js';
+export * from './ui.js';

package/src/program/Command.ts

@@ -0,0 +1,121 @@
+import {
+  type Argv,
+  parseArguments,
+  type OptionsConfig,
+  type ParametersConfig,
+  type Arguments,
+} from '@jakubmazanec/args';
+
+import {type CommandAction} from './CommandAction.js';
+import {type CommandOptions} from './CommandOptions.js';
+import {type Program} from './Program.js';
+// import {type ProgramCommand} from './ProgramCommand.js';
+
+/**
+ * Command encapsulates piece of a CLI's logic and is executed when {@linkcode Program} instance parses that command from the command line arguments.
+ */
+export class Command<
+  A extends string,
+  const B extends ParametersConfig | undefined = undefined,
+  const C extends OptionsConfig | undefined = undefined,
+  D extends boolean = false,
+  E extends boolean = false,
+> {
+  /* implements ProgramCommand*/
+  readonly name: A;
+  readonly description?: string;
+  readonly parameters: B extends ParametersConfig ? B : null;
+  readonly options: C extends OptionsConfig ? C : null;
+  readonly allowUnknownOptions: D;
+  readonly allowUnknownParameters: E;
+  private readonly action: CommandAction<A, B, C, D, E>;
+
+  /**
+   * @param name Command name, ie. space-separated words consisting only of letters, numbers (but not at the start of the word) or dashes.
+   * @param action Function that runs when command is executed.
+   * @param options Additionl command options.
+   */
+  constructor(
+    name: A,
+    action: CommandAction<A, B, C, D, E>,
+    {
+      description,
+      parameters,
+      options,
+      allowUnknownOptions,
+      allowUnknownParameters,
+    }: CommandOptions<NonNullable<B>, NonNullable<C>, D, E>,
+  ) {
+    this.name = name;
+    this.action = action;
+
+    if (description) {
+      this.description = description;
+    }
+
+    if (parameters) {
+      this.parameters = parameters as B extends ParametersConfig ? B : null;
+    } else {
+      this.parameters = null as B extends ParametersConfig ? B : null;
+    }
+
+    if (options) {
+      this.options = options as C extends OptionsConfig ? C : null;
+    } else {
+      this.options = null as C extends OptionsConfig ? C : null;
+    }
+
+    if (allowUnknownOptions) {
+      this.allowUnknownOptions = allowUnknownOptions;
+    } else {
+      this.allowUnknownOptions = false as D;
+    }
+
+    if (allowUnknownParameters) {
+      this.allowUnknownParameters = allowUnknownParameters;
+    } else {
+      this.allowUnknownParameters = false as E;
+    }
+  }
+
+  /**
+   * Parses a list of command line arguments into an arguments object. Parser is pre-configured based on this command.
+   */
+  parseArguments(argv: Argv): Arguments<{
+    commands: readonly [A];
+    parameters: B;
+    options: C;
+    allowUnknownOptions: D;
+    allowUnknownParameters: E;
+  }> {
+    return parseArguments(argv, {
+      commands: [this.name],
+      parameters: this.parameters ?? undefined,
+      options: this.options ?? undefined,
+      allowUnknownOptions: this.allowUnknownOptions,
+      allowUnknownParameters: this.allowUnknownParameters,
+    } as {
+      commands: readonly [A];
+      parameters: B;
+      options: C;
+      allowUnknownOptions: D;
+      allowUnknownParameters: E;
+    });
+  }
+
+  /**
+   * Executes command action with provided parsed arguments and {@linkcode Program} instance.
+   */
+  async run(
+    parsedArgs: Arguments<{
+      commands: readonly [A];
+      parameters: B;
+      options: C;
+      allowUnknownOptions: D;
+      allowUnknownParameters: E;
+    }>,
+    program: Program,
+  ): Promise<void> {
+    await this.action(parsedArgs, program);
+  }
+}

package/src/program/CommandAction.ts

@@ -0,0 +1,23 @@
+import {type OptionsConfig, type ParametersConfig, type Arguments} from '@jakubmazanec/args';
+
+import {type Program} from './Program.js';
+
+/**
+ * Command action.
+ */
+export type CommandAction<
+  A extends string,
+  B extends ParametersConfig | undefined = undefined,
+  C extends OptionsConfig | undefined = undefined,
+  D extends boolean = false,
+  E extends boolean = false,
+> = (
+  parsedArgs: Arguments<{
+    commands: readonly [A];
+    parameters: B;
+    options: C;
+    allowUnknownOptions: D;
+    allowUnknownParameters: E;
+  }>,
+  program: Program,
+) => Promise<void>;

package/src/program/CommandArguments.ts

@@ -0,0 +1,9 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- needed */
+import {type Command} from './Command.js';
+
+/**
+ * Parsed command arguments type.
+ */
+export type CommandArguments<C extends Command<any, any, any, any, any>> = ReturnType<
+  C['parseArguments']
+>;

package/src/program/CommandOptions.ts

@@ -0,0 +1,17 @@
+import {type OptionsConfig, type ParametersConfig} from '@jakubmazanec/args';
+
+/**
+ * New command options.
+ */
+export type CommandOptions<
+  B extends ParametersConfig,
+  C extends OptionsConfig,
+  D extends boolean,
+  E extends boolean,
+> = {
+  description?: string;
+  parameters?: B | undefined;
+  options?: C | undefined;
+  allowUnknownOptions?: D | undefined;
+  allowUnknownParameters?: E | undefined;
+};

package/src/program/Program.ts

@@ -0,0 +1,136 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- needed */
+import {type ParametersConfig, type Argv, type OptionsConfig} from '@jakubmazanec/args';
+
+import {type Command} from './Command.js';
+import {ProgramError} from './ProgramError.js';
+import {type ProgramOptions} from './ProgramOptions.js';
+import {type ProgramStreams} from './ProgramStreams.js';
+import {Wrapper} from '../ui/internals.js';
+import {Failure, Help} from '../ui.js';
+
+/**
+ * Program manages and executes {@linkcode Program} instances attached to it based on parsing command line arguments.
+ */
+export class Program {
+  /** Program name. */
+  readonly name?: string;
+
+  /** Program version. */
+  readonly version?: string;
+
+  /** Program description. */
+  readonly description?: string;
+
+  /** Program executable name. */
+  readonly bin?: string;
+
+  /** Program commands */
+  readonly commands: Array<
+    Command<string, ParametersConfig | undefined, OptionsConfig | undefined, boolean, boolean>
+  > = [];
+
+  protected isRendering = false;
+
+  readonly streams: ProgramStreams = {
+    stderr: process.stderr,
+    stdin: process.stdin,
+    stdout: process.stdout,
+  };
+
+  constructor({name, version, description, bin}: ProgramOptions) {
+    if (name) {
+      this.name = name;
+    }
+
+    if (version) {
+      this.version = version;
+    }
+
+    if (description) {
+      this.description = description;
+    }
+
+    if (bin) {
+      this.bin = bin;
+    }
+  }
+
+  /**
+   * Adds command to the program.
+   *
+   * @param command Command to add.
+   * @returns Program instance.
+   */
+  addCommand(command: Command<any, any, any, any, any>): this {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument -- it doesn't matter here; `any` is used to make TypeScript happy in this method, but isn't propagated further.
+    this.commands.push(command);
+
+    return this;
+  }
+
+  /**
+   * Renders a React element using Ink and outputs to the configured streams.
+   */
+  async renderElement(element: React.ReactElement): Promise<void> {
+    if (this.isRendering) {
+      throw new ProgramError('NO_NESTED_RENDER');
+    } else {
+      this.isRendering = true;
+    }
+
+    let {render} = await import('ink');
+    let {createElement} = await import('react');
+    let {stdin, stdout, stderr} = this.streams;
+
+    try {
+      render(createElement(Wrapper, {program: this}, element), {
+        exitOnCtrlC: true,
+        patchConsole: true,
+        stderr,
+        stdin,
+        stdout,
+      });
+    } catch (error: unknown) {
+      if (error instanceof Error) {
+        await this.renderElement(createElement(Failure, {error}));
+      }
+    } finally {
+      this.isRendering = false;
+    }
+  }
+
+  /**
+   * Runs the program.
+   *
+   * @param argv Unparsed command line arguments.
+   */
+  async run(argv: Argv): Promise<void> {
+    let hasCommandRun = false;
+
+    for (let command of this.commands) {
+      let parsedArgs = command.parseArguments(argv);
+
+      if (parsedArgs.command) {
+        hasCommandRun = true;
+
+        if (parsedArgs.errors.length) {
+          let {createElement} = await import('react');
+
+          for (let error of parsedArgs.errors) {
+            await this.renderElement(createElement(Failure, {error}));
+          }
+        } else {
+          await command.run(parsedArgs, this);
+
+          break;
+        }
+      }
+    }
+
+    if (!hasCommandRun) {
+      let {createElement} = await import('react');
+
+      await this.renderElement(createElement(Help, {program: this}));
+    }
+  }
+}

package/src/program/ProgramDetail.ts

@@ -0,0 +1,9 @@
+/**
+ * Detailed program information.
+ */
+export type ProgramDetail = {
+  name?: string;
+  version?: string;
+  description?: string;
+  bin?: string;
+};

package/src/program/ProgramError.ts

@@ -0,0 +1,9 @@
+import {createCustomError} from '@jakubmazanec/error';
+
+/**
+ * A subclass of `Error` that indicates a program failure.
+ */
+export const ProgramError = createCustomError('ProgramError', {
+  NO_NESTED_RENDER:
+    'A React render process already exists. This usually occurs by triggering nested render calls.',
+});

package/src/program/ProgramOptions.ts

@@ -0,0 +1,16 @@
+/**
+ * Options for creating new {@linkcode Program} instance.
+ */
+export type ProgramOptions = {
+  /** Program name. */
+  name?: string | undefined;
+
+  /** Program version. */
+  version?: string | undefined;
+
+  /** Program description. */
+  description?: string | undefined;
+
+  /** Program executable name. */
+  bin?: string | undefined;
+};

package/src/program/ProgramStreams.ts

@@ -0,0 +1,8 @@
+/**
+ * {@linkcode Program} streams;
+ */
+export type ProgramStreams = {
+  stderr: NodeJS.WriteStream;
+  stdin: NodeJS.ReadStream;
+  stdout: NodeJS.WriteStream;
+};

package/src/program/getProgramDetail.ts

@@ -0,0 +1,38 @@
+import {type PackageJson} from '@jakubmazanec/zod-utils';
+
+import {type ProgramDetail} from './ProgramDetail.js';
+
+/**
+ * Creates detailed information about a {@lincode Program}.
+ */
+export function getProgramDetail(packageJson: PackageJson) {
+  let programDetail: ProgramDetail = {};
+
+  if (packageJson.name) {
+    programDetail.name = packageJson.name;
+  }
+
+  if (packageJson.version) {
+    programDetail.version = packageJson.version;
+  }
+
+  if (packageJson.description) {
+    programDetail.description = packageJson.description;
+  }
+
+  if (packageJson.bin && typeof packageJson.bin !== 'string') {
+    let bins = Object.entries(packageJson.bin);
+
+    if (bins.length === 1) {
+      let firstBin = bins[0] as [string, string];
+
+      [programDetail.bin] = firstBin;
+    }
+  }
+
+  if (typeof packageJson.bin === 'string' && packageJson.name) {
+    programDetail.bin = packageJson.name;
+  }
+
+  return programDetail;
+}

package/src/program.ts

@@ -0,0 +1,10 @@
+export * from './program/Command.js';
+export * from './program/CommandAction.js';
+export * from './program/CommandArguments.js';
+export * from './program/CommandOptions.js';
+export * from './program/getProgramDetail.js';
+export * from './program/Program.js';
+export * from './program/ProgramDetail.js';
+export * from './program/ProgramError.js';
+export * from './program/ProgramOptions.js';
+export * from './program/ProgramStreams.js';

package/src/ui/ErrorDetail.ts

@@ -0,0 +1,12 @@
+/**
+ * Detailed error information.
+ */
+export type ErrorDetail = {
+  label: string;
+  description?: string;
+  stack?: string;
+  cause?: {
+    description?: string;
+    stack?: string;
+  };
+};