@c9up/ream 0.1.26 → 0.1.27

package/src/console/types.ts

@@ -0,0 +1,280 @@
+/**
+ * Console command contract — the STATIC shape the kernel dispatches against.
+ *
+ * Console parity: a command is a class carrying its own metadata as statics
+ * (`commandName`, `description`, `options`) plus the argument/flag metadata
+ * collected by the `@args` / `@flags` decorators. The kernel never requires the
+ * class to extend {@link BaseCommand}: ANY class exposing these statics is
+ * dispatchable.
+ *
+ * That is deliberate. Framework-agnostic packages (atlas and friends) must not
+ * import `@c9up/ream` — the same constraint that made the old `AtlasCommand`
+ * duck-type the `{ name, description, run }` object shape. Keeping the contract
+ * on statics lets those packages declare classes with typed args/flags and stay
+ * dependency-free.
+ */
+
+/** Per-command behaviour switches. Mirrors Console's `CommandOptions`. */
+export interface CommandOptions {
+  /**
+   * Boot the application (providers, DB, container) before `run()`.
+   *
+   * Defaults to `false`, as in Console: a scaffolding command has no business
+   * opening a database connection. Commands that resolve services from the
+   * container must opt in.
+   */
+  startApp?: boolean
+
+  /**
+   * Keep the process alive after `run()` resolves (long-running commands such
+   * as a queue worker). Defaults to `false` — the kernel tears the app down and
+   * lets the process exit.
+   */
+  staysAlive?: boolean
+
+  /**
+   * Accept flags the command did not declare instead of failing. Off by
+   * default so a typo (`--warm` for `--warn`) is reported, not swallowed.
+   */
+  allowUnknownFlags?: boolean
+}
+
+/** Metadata recorded by an `@args.*` decorator. */
+export interface ArgumentMetaData {
+  type: 'string' | 'spread'
+  /** Class property the parsed value is assigned to. */
+  propertyName: string
+  /** Name shown in help output (defaults to the dash-cased property name). */
+  argumentName: string
+  description?: string
+  required: boolean
+  default?: string | string[]
+  /**
+   * Accept an empty value (`ream greet ""`). Rejected by default, as in Console: an
+   * empty positional is nearly always a shell variable that did not expand.
+   */
+  allowEmptyValue?: boolean
+  /** Transforms/validates the raw value before it is assigned (Console `parse`). */
+  parse?: (value: string | string[]) => unknown
+}
+
+/** Metadata recorded by a `@flags.*` decorator. */
+export interface FlagMetaData {
+  type: 'string' | 'boolean' | 'number' | 'array'
+  /** Class property the parsed value is assigned to. */
+  propertyName: string
+  /** Name used on the command line (defaults to the dash-cased property name). */
+  flagName: string
+  description?: string
+  /** Single-character shorthands, e.g. `['r']` for `-r`. */
+  alias: string[]
+  default?: string | string[] | number | boolean
+  required: boolean
+  /**
+   * Accept `--name` with nothing behind it, as an empty value rather than an
+   * error (Console `allowEmptyValue`).
+   */
+  allowEmptyValue?: boolean
+  /** Transforms/validates the coerced value before it is assigned (Console `parse`). */
+  parse?: (value: string | string[] | number | boolean) => unknown
+  /** List `--no-<flag>` alongside the flag in help (booleans only). */
+  showNegatedVariantInHelp?: boolean
+}
+
+/** What the kernel produces from argv and assigns onto the command instance. */
+/**
+ * The parsed CLI input, in the shape Console publishes it.
+ *
+ * Positionals are a LIST, in declaration order, and flags are keyed by their
+ * COMMAND-LINE name — `parsed.flags['user-email']`, not `parsed.flags.userEmail`.
+ * The property names are what the values are assigned TO on the command; the
+ * parsed bag describes what was typed.
+ */
+export interface ParsedInput {
+  args: unknown[]
+  flags: Record<string, unknown>
+  /**
+   * Names of the flags that were passed but not declared (Console
+   * `this.parsed.unknownFlags`). Their values are in {@link flags}; this is the
+   * list a command inspects to know what it was handed but does not know about.
+   */
+  unknownFlags: string[]
+  /**
+   * Positionals beyond what the command declared.
+   *
+   * Normally none: an undeclared positional is an error. A command running with
+   * `allowUnknownFlags` is a proxy, so they are kept here instead of being
+   * dropped — forwarding them is the whole point of such a command.
+   */
+  extraArgs: string[]
+  /** Console's name for {@link extraArgs} — the same array, not a copy. */
+  _: string[]
+  /**
+   * The arguments node itself was started with (Console `nodeArgs`), filled only
+   * for the command invoked from the command line.
+   */
+  nodeArgs: string[]
+}
+
+/**
+ * The instance side of a command.
+ *
+ * Only `run()` is required. The lifecycle hooks are optional: the kernel calls
+ * whichever the command defines, in Console's order — prepare, interact, run,
+ * completed.
+ */
+export interface CommandInstance {
+  /**
+   * Whatever it returns becomes `result` on the executed command.
+   *
+   * Parameters are allowed: the container injects them (Console `@inject()` on a
+   * lifecycle method), and a no-arg signature would reject those commands.
+   */
+  run(...args: never[]): unknown
+  prepare?(...args: never[]): void | Promise<void>
+  interact?(...args: never[]): void | Promise<void>
+  /** Returning `true` marks the error handled, stopping its propagation. */
+  // biome-ignore lint/suspicious/noConfusingVoidType: Console contract — returning `true` marks the error handled, returning nothing is the normal case
+  completed?(...args: never[]): boolean | void | Promise<boolean | void>
+  /** Set by the command to force a code; the kernel fills it in otherwise. */
+  exitCode?: number
+  /** Filled by the kernel before `completed()` runs. */
+  error?: unknown
+  /** Filled by the kernel with what `run()` returned. */
+  result?: unknown
+}
+
+/**
+ * A command's metadata as plain data (Console `serialize`).
+ *
+ * JSON-safe on purpose: the `parse` callbacks carried by the live metadata are
+ * dropped, so this can be printed, cached or sent over a wire without a
+ * function silently disappearing at the boundary.
+ */
+/**
+ * How one positional argument is parsed (Console `ArgumentsParserOptions`).
+ *
+ * Derived from the declarations by `BaseCommand.getParserOptions()`. Ream's own
+ * parser reads the declarations directly; this shape exists so code ported from
+ * Console — which inspects it — keeps working.
+ */
+export interface ArgumentsParserOptions {
+  type: 'string' | 'spread'
+  default?: string | string[]
+  parse?: (value: string | string[]) => unknown
+}
+
+/** How the flags are parsed, grouped by type (Console `FlagsParserOptions`). */
+export interface FlagsParserOptions {
+  all: string[]
+  string: string[]
+  boolean: string[]
+  number: string[]
+  array: string[]
+  /** Flag name → its single-character shorthands. */
+  alias: Record<string, string[]>
+  count: string[]
+  /** Flag name → its `parse` callback. */
+  coerce: Record<string, (value: never) => unknown>
+  default: Record<string, unknown>
+}
+
+export interface SerializedCommand {
+  commandName: string
+  /**
+   * Where the command was found, relative to the directory it was loaded from.
+   *
+   * Set by loaders that read files, and by nothing else: it is what lets a
+   * generated manifest import a command without scanning anything.
+   */
+  filePath?: string
+  /** The part before `:` — `make` for `make:controller`, null when there is none. */
+  namespace: string | null
+  description: string
+  help?: string | string[]
+  aliases: string[]
+  options: CommandOptions
+  args: Array<Omit<ArgumentMetaData, 'parse'>>
+  flags: Array<Omit<FlagMetaData, 'parse'>>
+}
+
+/**
+ * A snapshot of a command that has run (Console `toJSON`).
+ *
+ * Unlike {@link SerializedCommand} this is about one execution: the values it
+ * received and what it produced. `args` / `flags` are the parsed VALUES, not
+ * their declarations.
+ */
+export interface CommandSnapshot {
+  commandName: string
+  options: CommandOptions
+  /** Positional VALUES in declaration order — Console exposes a list here. */
+  args: unknown[]
+  flags: Record<string, unknown>
+  error: unknown
+  result: unknown
+  exitCode: number | undefined
+}
+
+/**
+ * A command that has run.
+ *
+ * The three outcome fields are guaranteed here, which is what `exec()` returns:
+ * without it the documented `command.exitCode` / `.result` / `.error` does not
+ * typecheck for a caller, and the only way to read them is a reflective escape
+ * hatch — which is exactly what the tests had ended up doing.
+ */
+/**
+ * Assertions available on a command that has run.
+ *
+ * Part of what `exec()` returns, so a caller can use them without the type
+ * hiding what exists at runtime. The kernel attaches them to every command it
+ * runs, including one that does not extend `BaseCommand`.
+ */
+export interface CommandAssertions {
+  assertSucceeded(): void
+  assertFailed(): void
+  assertExitCode(expected: number): void
+  assertNotExitCode(unexpected: number): void
+  assertLog(message: string, stream?: 'stdout' | 'stderr'): void
+  assertLogMatches(pattern: RegExp, stream?: 'stdout' | 'stderr'): void
+  assertTableRows(expected: readonly (readonly string[])[]): void
+}
+
+export interface ExecutedCommand extends CommandInstance, CommandAssertions {
+  exitCode: number
+  error: unknown
+  result: unknown
+  /** A snapshot of this execution (Console `toJSON`). */
+  toJSON(): CommandSnapshot
+}
+
+/**
+ * The static side. `args` / `flags` are optional so a command with neither
+ * still satisfies the contract without declaring empty arrays.
+ */
+export interface CommandClass {
+  // Not `new ()`: a command built through the container receives its injected
+  // dependencies, and a zero-arg signature rejects every such class.
+  new (...args: never[]): CommandInstance
+  commandName: string
+  description: string
+  /** Alternative names the command also answers to (Console `static aliases`). */
+  aliases?: readonly string[]
+  options?: CommandOptions
+  args?: readonly ArgumentMetaData[]
+  flags?: readonly FlagMetaData[]
+  /** Longer help text printed under the usage line by `<cmd> --help`. */
+  help?: string | string[]
+}
+
+/** Narrowing guard used by the kernel when loading modules. */
+export function isCommandClass(value: unknown): value is CommandClass {
+  if (typeof value !== 'function') return false
+  const candidate = value as Partial<CommandClass>
+  return (
+    typeof candidate.commandName === 'string' &&
+    candidate.commandName.length > 0 &&
+    typeof candidate.description === 'string'
+  )
+}

package/src/console/ui.ts

@@ -0,0 +1,37 @@
+/**
+ * Console UI — `this.logger` and `this.prompt` on every command (Console parity).
+ *
+ * Kept dependency-free: the framework ships no colour or prompt library, and
+ * pulling one in for the CLI surface alone is not worth the install weight.
+ */
+
+import { stdout } from 'node:process'
+
+/** Colour is opt-out via NO_COLOR and skipped when piped to a file. */
+function supportsColour(stream: NodeJS.WriteStream): boolean {
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
+  if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== '') return true
+  return Boolean(stream.isTTY)
+}
+
+const CODES = {
+  reset: '\u001B[0m',
+  dim: '\u001B[2m',
+  red: '\u001B[31m',
+  green: '\u001B[32m',
+  yellow: '\u001B[33m',
+  blue: '\u001B[34m',
+  magenta: '\u001B[35m',
+  cyan: '\u001B[36m',
+} as const
+
+export type Colour = keyof Omit<typeof CODES, 'reset'>
+
+export function colourise(
+  text: string,
+  colour: Colour,
+  stream: NodeJS.WriteStream = stdout,
+): string {
+  if (!supportsColour(stream)) return text
+  return `${CODES[colour]}${text}${CODES.reset}`
+}

package/src/console/utils.ts

@@ -0,0 +1,69 @@
+/**
+ * The helpers Console exposes around commands (`@adonisjs/consoleApp` utils).
+ *
+ * They exist as exports because a custom loader needs them: validating what a
+ * module exported, and reporting a name that resolved to nothing.
+ */
+
+import { ReamError } from '../errors/ReamError.js'
+import type { Logger } from './cliui.js'
+import { type CommandClass, isCommandClass, type SerializedCommand } from './types.js'
+
+/** Sort command and namespace names the way the listing does. */
+export function sortAlphabetically(prev: string, curr: string): number {
+  return prev.localeCompare(curr)
+}
+
+/**
+ * Report a name that resolved to nothing, with the closest matches.
+ *
+ * Shared by the kernel's unknown-command report and the `help` command: two
+ * wordings for the same dead end is how they end up disagreeing.
+ */
+export function renderErrorWithSuggestions(
+  logger: Logger,
+  message: string,
+  suggestions: readonly string[],
+): void {
+  logger.error(message)
+  if (suggestions.length === 0) return
+  process.stderr.write(`  Did you mean "${suggestions.slice(0, 4).join('", "')}"?\n`)
+}
+
+/**
+ * Assert that a module's export is a command class.
+ *
+ * `exportPath` names the file, because the useful part of the message is WHICH
+ * module exported the wrong thing.
+ */
+export function validateCommand(
+  command: unknown,
+  exportPath: string,
+): asserts command is CommandClass {
+  if (isCommandClass(command)) return
+  throw new ReamError('E_CONSOLE_INVALID_COMMAND', `Invalid command exported from ${exportPath}.`, {
+    hint: 'Expected a class with a static commandName, a static description and a run() method.',
+  })
+}
+
+/** The same, for a metadata object a loader published. */
+export function validateCommandMetaData(
+  metadata: unknown,
+  exportPath: string,
+): asserts metadata is SerializedCommand {
+  const invalid = (reason: string): never => {
+    throw new ReamError(
+      'E_CONSOLE_INVALID_COMMAND_METADATA',
+      `Invalid command metadata exported from ${exportPath}: ${reason}.`,
+    )
+  }
+
+  if (typeof metadata !== 'object' || metadata === null) invalid('expected an object')
+  const record = metadata as Record<string, unknown>
+  if (typeof record.commandName !== 'string' || record.commandName === '') {
+    invalid('"commandName" is missing')
+  }
+  if (typeof record.description !== 'string') invalid('"description" is missing')
+  if (!Array.isArray(record.args)) invalid('"args" is missing')
+  if (!Array.isArray(record.flags)) invalid('"flags" is missing')
+}

package/src/container/Container.ts

@@ -10,7 +10,13 @@
  */
 
 import 'reflect-metadata'
-import { getInjectTokens, getServiceMetadata, getServiceRegistry } from '../decorators/Service.js'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import {
+  getInjectTokens,
+  getMethodInjectTokens,
+  getServiceMetadata,
+  getServiceRegistry,
+} from '../decorators/Service.js'
 import { didYouMean } from '../errors/FuzzyMatcher.js'
 import { ReamError } from '../errors/ReamError.js'
 import type { Binding, ServiceFactory, ServiceToken } from './types.js'
@@ -22,6 +28,12 @@ import type { Binding, ServiceFactory, ServiceToken } from './types.js'
  */
 const RESERVED_TOKEN_NAMES = new Set(['__proto__', 'constructor', 'prototype'])
 
+/** One resolution chain: the tokens on it, and a set for O(1) membership. */
+interface ResolutionChain {
+  stack: string[]
+  set: Set<string>
+}
+
 export class Container {
   #bindings: Map<string, Binding> = new Map()
   #singletons: Map<string, unknown> = new Map()
@@ -37,8 +49,16 @@ export class Container {
   #aliases: Map<string, ServiceToken> = new Map()
   /** token key → post-resolution callbacks (AdonisJS `container.resolving`). */
   #resolvingHooks: Map<string, Array<(value: unknown) => void | Promise<void>>> = new Map()
-  #resolutionStack: string[] = []
-  #resolutionSet: Set<string> = new Set()
+  /**
+   * The resolution chain currently being walked, for cycle detection.
+   *
+   * Scoped to the async context, NOT to the container: `resolve()` is async, so
+   * two independent chains interleave, and a stack held on the instance would
+   * splice them together and report a cycle neither of them has. Per-container
+   * storage keeps a chain that crosses two containers from colliding on a token
+   * name they happen to share.
+   */
+  readonly #chain = new AsyncLocalStorage<ResolutionChain>()
 
   // ─── Explicit bindings ────────────────────────────────────
 
@@ -162,21 +182,30 @@ export class Container {
 
     const key = this.#tokenToKey(token)
 
-    if (this.#resolutionSet.has(key)) {
-      const cycle = [...this.#resolutionStack, key].join(' → ')
+    // Top of a chain: open one, so everything this resolution triggers shares
+    // it and nothing outside it does.
+    const chain = this.#chain.getStore()
+    if (chain === undefined) {
+      return this.#chain.run({ stack: [], set: new Set() }, () =>
+        this.resolve<T>(token, runtimeValues),
+      )
+    }
+
+    if (chain.set.has(key)) {
+      const cycle = [...chain.stack, key].join(' → ')
       throw new ReamError('CIRCULAR_DEPENDENCY', `Circular dependency detected: ${cycle}`, {
         hint: 'Break the cycle by resolving one dependency lazily inside a method (`await container.make(Dep)`) instead of injecting it in the constructor.',
         context: { chain: cycle },
       })
     }
-    this.#resolutionStack.push(key)
-    this.#resolutionSet.add(key)
+    chain.stack.push(key)
+    chain.set.add(key)
 
     try {
       return await this.#resolveInner<T>(key, token, runtimeValues)
     } finally {
-      this.#resolutionStack.pop()
-      this.#resolutionSet.delete(key)
+      chain.stack.pop()
+      chain.set.delete(key)
     }
   }
 
@@ -196,8 +225,16 @@ export class Container {
     const target: Ctor = Object.getPrototypeOf(instance).constructor
     const paramTypes: unknown[] =
       Reflect.getMetadata('design:paramtypes', target.prototype, method) ?? []
-
-    const len = Math.max(paramTypes.length, runtimeValues?.length ?? 0)
+    // `@Inject('token')` on a method parameter — a named binding the reflected
+    // type cannot express (an interface, or a class registered under a name).
+    const injectTokens = getMethodInjectTokens(target.prototype, method)
+
+    // `@Inject` counts towards the parameter span too: a method may carry named
+    // tokens without `design:paramtypes` being emitted for it, and computing the
+    // span from the reflected types alone left the loop at zero iterations —
+    // the tokens were read and then never used.
+    const injectSpan = injectTokens.size === 0 ? 0 : Math.max(...injectTokens.keys()) + 1
+    const len = Math.max(paramTypes.length, runtimeValues?.length ?? 0, injectSpan)
     // Sequential resolution keeps the shared cycle-detection stack consistent.
     const args: unknown[] = []
     for (let index = 0; index < len; index += 1) {
@@ -206,6 +243,11 @@ export class Container {
         args.push(runtimeValues[index])
         continue
       }
+      const named = injectTokens.get(index)
+      if (named !== undefined) {
+        args.push(await this.resolve(named))
+        continue
+      }
       const type = paramTypes[index]
       args.push(isInjectableClass(type) ? await this.resolve(type) : undefined)
     }
@@ -261,7 +303,7 @@ export class Container {
   async #resolveInner<T>(key: string, token: ServiceToken, runtimeValues?: unknown[]): Promise<T> {
     // 1. Check swaps (test overrides) — a swap factory may be async.
     if (this.#overrides.has(key)) {
-      const swapped = await this.#overrides.get(key)?.()
+      const swapped = await this.#overrides.get(key)?.(this)
       return swapped as T
     }
 
@@ -273,7 +315,7 @@ export class Container {
     // 3. Check explicit bindings — the factory may be async.
     const binding = this.#bindings.get(key)
     if (binding) {
-      const instance = binding.factory ? await binding.factory() : undefined
+      const instance = binding.factory ? await binding.factory(this) : undefined
       if (binding.scope === 'singleton') {
         this.#singletons.set(key, instance)
       }

package/src/container/types.ts

@@ -17,8 +17,21 @@ export interface ServiceMetadata {
 // biome-ignore lint/suspicious/noExplicitAny: IoC container tokens must accept any constructor signature
 export type ServiceToken = (new (...args: any[]) => unknown) | string | symbol
 
-/** Factory function for creating service instances. */
-export type ServiceFactory = () => unknown
+/**
+ * Resolver handed to a binding factory so it can resolve its own dependencies
+ * (AdonisJS parity: `container.singleton(token, async (resolver) =>
+ * await resolver.make(Dep))`). The Container itself satisfies this contract.
+ */
+export interface ContainerResolver {
+  make<T>(token: ServiceToken, runtimeValues?: unknown[]): Promise<T>
+}
+
+/**
+ * Factory function for creating service instances. Receives a {@link
+ * ContainerResolver} (AdonisJS parity) — the async container means a factory
+ * that needs another binding must `await resolver.make(Dep)`.
+ */
+export type ServiceFactory = (resolver: ContainerResolver) => unknown
 
 /** Binding entry in the container. */
 export interface Binding {

package/src/decorators/Service.ts

@@ -51,11 +51,23 @@ export function Service(options: { scope?: ServiceScope; as?: string } = {}): Cl
  * @implements FR16
  */
 export function Inject(token: ServiceToken): ParameterDecorator {
-  return (target, _propertyKey, parameterIndex) => {
+  return (target, propertyKey, parameterIndex) => {
+    // A constructor parameter reports no property key and lands on the class;
+    // a method parameter lands on the prototype and MUST be keyed by method
+    // name, or every method of the class would share one map and overwrite
+    // each other's tokens.
     const existingTokens: Map<number, ServiceToken> =
-      Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) ?? new Map()
+      (propertyKey === undefined
+        ? Reflect.getOwnMetadata(INJECT_METADATA_KEY, target)
+        : Reflect.getOwnMetadata(INJECT_METADATA_KEY, target, propertyKey)) ?? new Map()
+
     existingTokens.set(parameterIndex, token)
-    Reflect.defineMetadata(INJECT_METADATA_KEY, existingTokens, target)
+
+    if (propertyKey === undefined) {
+      Reflect.defineMetadata(INJECT_METADATA_KEY, existingTokens, target)
+    } else {
+      Reflect.defineMetadata(INJECT_METADATA_KEY, existingTokens, target, propertyKey)
+    }
   }
 }
 
@@ -66,6 +78,19 @@ export function getInjectTokens(target: AnyConstructor): Map<number, ServiceToke
   return Reflect.getOwnMetadata(INJECT_METADATA_KEY, target) ?? new Map()
 }
 
+/**
+ * Get named injection tokens for one method's parameters.
+ *
+ * `target` is the prototype carrying the method — that is where a parameter
+ * decorator on a method writes.
+ */
+export function getMethodInjectTokens(
+  target: object,
+  propertyKey: string | symbol,
+): Map<number, ServiceToken> {
+  return Reflect.getOwnMetadata(INJECT_METADATA_KEY, target, propertyKey) ?? new Map()
+}
+
 /**
  * @inject() class decorator — marks a controller (or service) for transient IoC resolution.
  *

package/src/errors/ReamError.ts

@@ -7,6 +7,37 @@
  * @implements FR71, FR72, FR73, FR77
  */
 
+/**
+ * Is this a Ream error, and one of these codes?
+ *
+ * The framework carries ONE error type with a `code`, because an error can be
+ * raised in Rust and rebuilt in TypeScript across the NAPI boundary — see
+ * {@link ReamError.fromNapi}. A class per code cannot cross that line, so the
+ * check that replaces `instanceof MyError` is this one.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await consoleApp.exec('provision')
+ * } catch (error) {
+ *   if (isReamError(error, 'E_CONSOLE_MISSING_FLAG', 'E_CONSOLE_MISSING_ARGUMENT')) {
+ *     console.error(error.hint)   // narrowed: `error` IS a ReamError here
+ *     return
+ *   }
+ *   throw error
+ * }
+ * ```
+ */
+export function isReamError(error: unknown): error is ReamError
+export function isReamError<const Code extends string>(
+  error: unknown,
+  ...codes: [Code, ...Code[]]
+): error is ReamError & { code: Code }
+export function isReamError(error: unknown, ...codes: string[]): boolean {
+  if (!(error instanceof ReamError)) return false
+  return codes.length === 0 || codes.includes(error.code)
+}
+
 export class ReamError extends Error {
   /** Error code (e.g., "ATLAS_QUERY_ERROR", "CONTAINER_NOT_FOUND") */
   readonly code: string

package/src/errors/prettyPrintError.ts

@@ -0,0 +1,20 @@
+/**
+ * Render an error for a human reading a terminal (AdonisJS `prettyPrintError`).
+ *
+ * Its own module rather than a helper inside `Ignitor.ts`: the console kernel
+ * renders the failures of the command it ran, and reaching into the Ignitor for
+ * that would make the two import each other.
+ */
+
+import { ReamError } from './ReamError.js'
+
+export function prettyPrintError(error: unknown): void {
+  if (error instanceof ReamError) {
+    console.error(error.toDevString())
+  } else if (error instanceof Error) {
+    console.error(`\n  ${error.message}\n`)
+    if (error.stack) console.error(error.stack)
+  } else {
+    console.error(error)
+  }
+}