@c9up/ream 0.1.25 → 0.1.27

package/src/console/ExceptionHandler.ts

@@ -0,0 +1,91 @@
+/**
+ * The default renderer for a failure of the command line (Console's
+ * `ExceptionHandler`).
+ *
+ * A class rather than a function so an application can extend it and override
+ * one step — the usual need is "report this error like the framework does, but
+ * ship it somewhere too".
+ */
+
+import { prettyPrintError } from '../errors/prettyPrintError.js'
+import { isReamError } from '../errors/ReamError.js'
+import type { Kernel } from './Kernel.js'
+
+/** Errors the console raises when a command is called wrongly. */
+const CALL_ERROR_CODES = [
+  'E_CONSOLE_COMMAND_NOT_FOUND',
+  'E_CONSOLE_MISSING_ARGUMENT',
+  'E_CONSOLE_MISSING_ARGUMENT_VALUE',
+  'E_CONSOLE_MISSING_FLAG',
+  'E_CONSOLE_MISSING_FLAG_VALUE',
+  'E_CONSOLE_UNKNOWN_FLAG',
+  'E_CONSOLE_INVALID_FLAG_VALUE',
+  'E_CONSOLE_INVALID_FLAG_GROUP',
+  'E_CONSOLE_UNEXPECTED_ARGUMENT',
+  'E_CONSOLE_PROMPT_CANCELLED',
+]
+
+export class ExceptionHandler {
+  /** Print the whole error, stack included. */
+  debug = true
+
+  /**
+   * Error codes to report as a single line, without a stack.
+   *
+   * The framework's own call errors are always in this set: a missing flag is
+   * something the user typed, and a stack trace of the parser tells them
+   * nothing about it.
+   */
+  knownErrorCodes: string[] = []
+
+  protected get internalKnownErrorCodes(): readonly string[] {
+    return CALL_ERROR_CODES
+  }
+
+  /** One line on stderr, through the kernel's own UI. */
+  protected logError(message: string, kernel: Kernel): void {
+    kernel.logger.error(message)
+  }
+
+  /** The full error, with its stack — what a developer needs. */
+  protected async prettyPrintError(error: unknown): Promise<void> {
+    prettyPrintError(error)
+  }
+
+  async render(error: unknown, kernel: Kernel): Promise<void> {
+    if (typeof error !== 'object' || error === null || !('message' in error)) {
+      this.logError(String(error), kernel)
+      return
+    }
+
+    // An unknown command is a typo: the suggestion is the useful part, the
+    // stack is noise.
+    if (isReamError(error, 'E_CONSOLE_COMMAND_NOT_FOUND')) {
+      this.logError(String(error.message), kernel)
+      return
+    }
+
+    const code = Reflect.get(error, 'code')
+    if (
+      typeof code === 'string' &&
+      (this.internalKnownErrorCodes.includes(code) || this.knownErrorCodes.includes(code))
+    ) {
+      this.logError(String(Reflect.get(error, 'message')), kernel)
+      return
+    }
+
+    // An error that knows how to report itself is left to do it.
+    const render = Reflect.get(error, 'render')
+    if (typeof render === 'function') {
+      await Reflect.apply(render, error, [error, kernel])
+      return
+    }
+
+    if (!this.debug) {
+      kernel.logger.fatal(error instanceof Error ? error : String(error))
+      return
+    }
+
+    await this.prettyPrintError(error)
+  }
+}

package/src/console/HelpCommand.ts

@@ -0,0 +1,37 @@
+/**
+ * `help <command>` — the built-in command explaining another one (Console's
+ * `HelpCommand`).
+ *
+ * A registered command, not a branch in the dispatcher: `hasCommand('help')` is
+ * true, `exec('help', ['make:controller'])` works, and it is replaceable like
+ * any other. It reads METADATA, so explaining a command does not import it.
+ */
+
+import { BaseCommand } from './BaseCommand.js'
+import { args } from './decorators.js'
+import { renderErrorWithSuggestions } from './utils.js'
+
+export default class HelpCommand extends BaseCommand {
+  static override commandName = 'help'
+  static override description = 'View help for a given command'
+
+  @args.string({ argumentName: 'command', description: 'Command name' })
+  declare name: string
+
+  run(): void {
+    const command = this.kernel.getCommand(this.name)
+    if (command === null) {
+      // The same report the kernel gives for an unknown command — one dead end,
+      // one wording.
+      renderErrorWithSuggestions(
+        this.logger,
+        `Command "${this.name}" is not defined.`,
+        this.kernel.getCommandSuggestions(this.name),
+      )
+      this.exitCode = 1
+      return
+    }
+
+    this.kernel.printCommandHelp(command)
+  }
+}

package/src/console/IndexGenerator.ts

@@ -0,0 +1,79 @@
+/**
+ * Writes a commands manifest next to the built commands (Console's
+ * `IndexGenerator`).
+ *
+ * What it buys: listing the commands, or checking that one exists, without
+ * importing a single command module. Scanning a directory means importing every
+ * file in it — the manifest replaces that with one JSON read.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { pathToFileURL } from 'node:url'
+import { FsLoader } from './loaders.js'
+import type { SerializedCommand } from './types.js'
+
+/** What `commands.json` holds. `version` is there to survive a format change. */
+export interface CommandsManifest {
+  version: 1
+  commands: SerializedCommand[]
+}
+
+export class IndexGenerator {
+  readonly #directory: URL
+
+  constructor(commandsDirectory: string | URL) {
+    this.#directory =
+      typeof commandsDirectory === 'string'
+        ? pathToFileURL(`${commandsDirectory}/`)
+        : commandsDirectory
+  }
+
+  /**
+   * Write `commands.json` and the `main.js` / `main.d.ts` loader beside the
+   * commands. Returns the manifest, so a caller can report what it indexed.
+   */
+  async generate(): Promise<CommandsManifest> {
+    const commands = await new FsLoader(this.#directory).getMetaData()
+    const manifest: CommandsManifest = { version: 1, commands }
+
+    await mkdir(this.#directory, { recursive: true })
+    await writeFile(new URL('commands.json', this.#directory), JSON.stringify(manifest, null, 2))
+    await writeFile(new URL('main.js', this.#directory), LOADER)
+    await writeFile(new URL('main.d.ts', this.#directory), LOADER_TYPES)
+
+    return manifest
+  }
+}
+
+/**
+ * The generated loader. It satisfies `CommandLoader` structurally, so the
+ * kernel takes it as-is: `kernel.addLoader(await import('./commands/main.js'))`.
+ */
+const LOADER = `import { readFile } from 'node:fs/promises'
+
+/** Generated by Ream's IndexGenerator — do not edit. */
+let manifest
+
+export async function getMetaData() {
+  if (manifest === undefined) {
+    const contents = await readFile(new URL('./commands.json', import.meta.url), 'utf-8')
+    manifest = JSON.parse(contents).commands
+  }
+  return manifest
+}
+
+export async function getCommand(metadata) {
+  const commands = await getMetaData()
+  const command = commands.find((entry) => entry.commandName === metadata.commandName)
+  if (command === undefined) return null
+
+  const imported = await import(new URL(command.filePath, import.meta.url).href)
+  return imported.default ?? null
+}
+`
+
+const LOADER_TYPES = `import type { CommandClass, SerializedCommand } from '@c9up/ream'
+
+export declare function getMetaData(): Promise<SerializedCommand[]>
+export declare function getCommand(metadata: SerializedCommand): Promise<CommandClass | null>
+`