@c9up/ream 0.1.25 → 0.1.27

package/src/console/decorators.ts

@@ -0,0 +1,199 @@
+/**
+ * `@args` / `@flags` decorators — declarative command inputs (Console parity).
+ *
+ * Legacy (experimental) property decorators, matching the rest of the codebase
+ * and the project's swc config (`legacyDecorator: true`). Metadata is written
+ * onto the class as the static `args` / `flags` arrays the kernel reads, so a
+ * command satisfies the dispatch contract without inheriting anything.
+ *
+ *   export default class Provision extends BaseCommand {
+ *     static commandName = 'provision'
+ *     static description = 'Create the owner account'
+ *
+ *     @flags.string({ description: 'Owner email', required: true })
+ *     declare email: string
+ *
+ *     @flags.string({ default: 'Owner' })
+ *     declare name: string
+ *   }
+ *
+ * Properties are declared with `declare` on purpose: under `target: ES2022`
+ * a real class field would be re-initialised to `undefined` at construction
+ * and wipe the value the kernel assigned.
+ */
+
+import { ReamError } from '../errors/ReamError.js'
+import type { ArgumentMetaData, FlagMetaData } from './types.js'
+
+/** `startServer` → `start-server`. */
+function dashCase(value: string): string {
+  return value.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+/**
+ * Own-property lists per class.
+ *
+ * A subclass must not push into its parent's array — that would leak its flags
+ * onto every sibling. When the class does not own the list yet, seed a copy of
+ * whatever it inherited so extending a command keeps the parent's inputs.
+ */
+function ownList<T>(ctor: object, key: 'args' | 'flags'): T[] {
+  if (!Object.hasOwn(ctor, key)) {
+    const inherited: unknown = Reflect.get(ctor, key)
+    Reflect.set(ctor, key, Array.isArray(inherited) ? [...inherited] : [])
+  }
+  const list: unknown = Reflect.get(ctor, key)
+  return Array.isArray(list) ? list : []
+}
+
+export interface ArgumentOptions {
+  /** Name shown in help. Defaults to the dash-cased property name. */
+  argumentName?: string
+  description?: string
+  /** Defaults to `true`, as in Console — positional arguments are expected. */
+  required?: boolean
+  default?: string | string[]
+  /** Accept an empty value instead of reporting it (Console `allowEmptyValue`). */
+  allowEmptyValue?: boolean
+  /** Transform or validate the value before assignment (Console `parse`). */
+  parse?: (value: string | string[]) => unknown
+}
+
+export interface FlagOptions {
+  /** 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 | string[]
+  default?: string | string[] | number | boolean
+  /** Defaults to `false` — a flag is optional unless stated otherwise. */
+  required?: boolean
+  /** Accept `--flag` with no value behind it (Console `allowEmptyValue`). */
+  allowEmptyValue?: boolean
+  /** Transform or validate the value before assignment (Console `parse`). */
+  parse?: (value: string | string[] | number | boolean) => unknown
+  /**
+   * Show `--no-<flag>` next to the flag in help. Booleans are always negatable;
+   * this only decides whether help says so.
+   */
+  showNegatedVariantInHelp?: boolean
+}
+
+/**
+ * Reject an argument order the command line could never satisfy (Console).
+ *
+ * Exported because `BaseCommand.defineArgument()` declares arguments through a
+ * different path: one rule, or a decorated command would accept what the same
+ * declaration written by hand refuses.
+ */
+export function assertArgumentOrder(
+  declared: readonly ArgumentMetaData[],
+  incoming: Pick<ArgumentMetaData, 'argumentName' | 'required'>,
+): void {
+  const last = declared[declared.length - 1]
+  if (last === undefined) return
+
+  if (last.type === 'spread') {
+    throw new ReamError(
+      'E_CONSOLE_INVALID_ARGUMENT',
+      `Argument "${incoming.argumentName}" comes after the spread argument "${last.argumentName}".`,
+      { hint: 'A spread argument consumes the rest, so it must be declared last.' },
+    )
+  }
+  if (incoming.required && last.required === false) {
+    throw new ReamError(
+      'E_CONSOLE_INVALID_ARGUMENT',
+      `Required argument "${incoming.argumentName}" comes after the optional "${last.argumentName}".`,
+      { hint: 'Declare the required arguments first, or make this one optional.' },
+    )
+  }
+}
+
+/**
+ * Build one argument's metadata from what was declared.
+ *
+ * The single builder for both declaration paths — the decorators and
+ * `BaseCommand.defineArgument()`. Two field-by-field copies is how a new option
+ * ends up honoured on one path and silently dropped on the other, which is
+ * exactly what happened to `allowEmptyValue`.
+ */
+export function buildArgument(
+  name: string,
+  options: Partial<ArgumentMetaData> = {},
+): ArgumentMetaData {
+  return {
+    type: options.type ?? 'string',
+    propertyName: options.propertyName ?? name,
+    argumentName: options.argumentName ?? dashCase(name),
+    description: options.description,
+    // An argument with a default is optional by definition.
+    required: options.required ?? options.default === undefined,
+    default: options.default,
+    allowEmptyValue: options.allowEmptyValue,
+    parse: options.parse,
+  }
+}
+
+/** The same, for a flag. */
+export function buildFlag(name: string, options: Partial<FlagMetaData> = {}): FlagMetaData {
+  return {
+    type: options.type ?? 'boolean',
+    propertyName: options.propertyName ?? name,
+    flagName: options.flagName ?? dashCase(name),
+    description: options.description,
+    alias: options.alias ?? [],
+    required: options.required ?? false,
+    default: options.default,
+    allowEmptyValue: options.allowEmptyValue,
+    parse: options.parse,
+    showNegatedVariantInHelp: options.showNegatedVariantInHelp,
+  }
+}
+
+function defineArgument(type: ArgumentMetaData['type'], options: ArgumentOptions) {
+  return (target: object, propertyKey: string | symbol): void => {
+    const argument = buildArgument(String(propertyKey), { ...options, type })
+    const list = ownList<ArgumentMetaData>(target.constructor, 'args')
+    assertArgumentOrder(list, argument)
+    list.push(argument)
+  }
+}
+
+function defineFlag(type: FlagMetaData['type'], options: FlagOptions) {
+  return (target: object, propertyKey: string | symbol): void => {
+    // `alias` is a string or a list at the decorator, always a list in the
+    // metadata — the only shape the builder cannot normalise for both paths.
+    const alias = options.alias === undefined ? [] : [options.alias].flat()
+    const list = ownList<FlagMetaData>(target.constructor, 'flags')
+    list.push(buildFlag(String(propertyKey), { ...options, type, alias }))
+  }
+}
+
+/** Positional arguments. Declaration order is the command-line order. */
+export const args = {
+  /** A single positional value. */
+  string(options: ArgumentOptions = {}) {
+    return defineArgument('string', options)
+  },
+  /** Collects every remaining positional into an array. Declare it last. */
+  spread(options: ArgumentOptions = {}) {
+    return defineArgument('spread', options)
+  },
+}
+
+/** Named flags. */
+export const flags = {
+  string(options: FlagOptions = {}) {
+    return defineFlag('string', options)
+  },
+  boolean(options: FlagOptions = {}) {
+    return defineFlag('boolean', options)
+  },
+  number(options: FlagOptions = {}) {
+    return defineFlag('number', options)
+  },
+  /** Repeatable flag: `--tag a --tag b` → `['a', 'b']`. */
+  array(options: FlagOptions = {}) {
+    return defineFlag('array', options)
+  },
+}

package/src/console/index.ts

@@ -0,0 +1,67 @@
+/**
+ * `@c9up/ream/console` — the console command surface.
+ *
+ * The SDK is ours — only the shape is borrowed: a command declares its name,
+ * its args and its flags, then runs.
+ *
+ *   import { BaseCommand, args, flags } from '@c9up/ream/console'
+ */
+
+export { BaseCommand } from './BaseCommand.js'
+export type { ConsoleOptions } from './Console.js'
+export { Console } from './Console.js'
+export type { Colors, StyleName, TaskOutcome } from './cliui.js'
+export {
+  Action,
+  Box,
+  Logger,
+  Table,
+  TaskContext,
+  Tasks,
+  Ui,
+} from './cliui.js'
+export type { ArgumentOptions, FlagOptions } from './decorators.js'
+export { args, flags } from './decorators.js'
+export { ExceptionHandler } from './ExceptionHandler.js'
+export { default as HelpCommand } from './HelpCommand.js'
+export type { CommandsManifest } from './IndexGenerator.js'
+export { IndexGenerator } from './IndexGenerator.js'
+export type {
+  CommandExecutor,
+  CommandLoader,
+  ErrorRenderer,
+  GlobalFlagListener,
+  HandleResult,
+  KernelOptions,
+  KernelState,
+} from './Kernel.js'
+export { Kernel, serializeCommand } from './Kernel.js'
+export { default as ListCommand } from './ListCommand.js'
+export { FsLoader, ListLoader } from './loaders.js'
+export type { ParseOptions } from './parser.js'
+export { Parser, parseArgv } from './parser.js'
+export type {
+  BooleanPromptOptions,
+  MultiplePromptOptions,
+  PromptChoice,
+  PromptOptions,
+  SelectPromptOptions,
+} from './prompts.js'
+export { Prompt, PromptTrap } from './prompts.js'
+export { commandExec } from './tracing.js'
+export type {
+  ArgumentMetaData,
+  CommandClass,
+  CommandInstance,
+  CommandOptions,
+  ExecutedCommand,
+  FlagMetaData,
+  ParsedInput,
+} from './types.js'
+export { isCommandClass } from './types.js'
+export {
+  renderErrorWithSuggestions,
+  sortAlphabetically,
+  validateCommand,
+  validateCommandMetaData,
+} from './utils.js'

package/src/console/loaders.ts

@@ -0,0 +1,145 @@
+/**
+ * The two loaders Console ships — `ListLoader` and `FsLoader`.
+ *
+ * A loader answers in two steps: the metadata of everything it offers, then the
+ * class for one of them. The kernel reads the first at boot and the second only
+ * when a command is asked for, so neither listing nor describing imports a
+ * module nobody is going to run.
+ */
+
+import { readdir } from 'node:fs/promises'
+import { pathToFileURL } from 'node:url'
+import type { CommandLoader } from './Kernel.js'
+import { serializeCommand } from './Kernel.js'
+import { type CommandClass, isCommandClass, type SerializedCommand } from './types.js'
+
+/**
+ * Commands given as classes (Console `ListLoader`).
+ *
+ * The form a package uses to ship its commands: they are already imported, so
+ * there is nothing to defer.
+ */
+export class ListLoader implements CommandLoader {
+  readonly #commands: readonly CommandClass[]
+
+  constructor(commands: readonly CommandClass[]) {
+    this.#commands = [...commands]
+  }
+
+  async getMetaData(): Promise<SerializedCommand[]> {
+    return this.#commands.map(serializeCommand)
+  }
+
+  async getCommand(metadata: SerializedCommand): Promise<CommandClass | null> {
+    return this.#commands.find((command) => command.commandName === metadata.commandName) ?? null
+  }
+}
+
+/**
+ * Commands found in a directory (Console `FsLoader`).
+ *
+ * Reading the metadata imports each file — without a manifest there is no other
+ * way to know what a file declares, and Console's own `FsLoader` does the same. The
+ * gain is elsewhere: `getCommand()` never imports anything twice.
+ */
+export class FsLoader implements CommandLoader {
+  readonly #directory: URL
+  readonly #filter: ((filePath: string) => boolean) | undefined
+  readonly #commands = new Map<string, CommandClass>()
+  readonly #paths = new Map<string, string>()
+  #onSkipped: ((fileName: string) => void) | undefined
+
+  /**
+   * @param directory Where to look, as a path or a URL.
+   * @param filter Files to keep. Everything is loaded when it is omitted.
+   */
+  constructor(directory: string | URL, filter?: (filePath: string) => boolean) {
+    this.#directory = typeof directory === 'string' ? pathToFileURL(`${directory}/`) : directory
+    this.#filter = filter
+  }
+
+  /**
+   * Called for a file that exports no command.
+   *
+   * Reported rather than thrown: the directory is scanned by convention, so a
+   * stray helper there must not make the whole CLI unusable.
+   */
+  onSkipped(handler: (fileName: string) => void): this {
+    this.#onSkipped = handler
+    return this
+  }
+
+  async getMetaData(): Promise<SerializedCommand[]> {
+    let entries: Array<{ name: string; isDirectory(): boolean; parentPath?: string }>
+    try {
+      entries = await readdir(this.#directory, { withFileTypes: true, recursive: true })
+    } catch {
+      // No such directory — perfectly normal.
+      return []
+    }
+
+    const files = entries
+      .filter((entry) => !entry.isDirectory() && isCommandFile(entry.name))
+      .map((entry) => new URL(entry.name, directoryUrl(entry.parentPath, this.#directory)))
+      .filter((file) => this.#filter === undefined || this.#filter(file.pathname))
+      .sort((a, b) => a.href.localeCompare(b.href))
+
+    for (const file of files) {
+      const command = commandOf(await this.import(file))
+      if (command === undefined) {
+        this.#onSkipped?.(file.pathname.split('/').pop() ?? file.pathname)
+        continue
+      }
+      this.#commands.set(command.commandName, command)
+      this.#paths.set(command.commandName, relativeTo(this.#directory, file))
+    }
+
+    return [...this.#commands.values()].map((command) => ({
+      ...serializeCommand(command),
+      filePath: this.#paths.get(command.commandName),
+    }))
+  }
+
+  async getCommand(metadata: SerializedCommand): Promise<CommandClass | null> {
+    return this.#commands.get(metadata.commandName) ?? null
+  }
+
+  /**
+   * How a file is imported. Overridable because an application may compile its
+   * own sources — Ream's Ignitor routes this through the app's importer.
+   */
+  protected import(file: URL): Promise<unknown> {
+    return import(file.href)
+  }
+}
+
+/** `./make/controller.ts` — how a manifest refers back to the file. */
+function relativeTo(directory: URL, file: URL): string {
+  return `./${file.href.slice(directory.href.length)}`
+}
+
+/** `.ts` / `.js` modules only, skipping declarations and `_private` helpers. */
+function isCommandFile(name: string): boolean {
+  if (name.startsWith('_') || name.endsWith('.d.ts')) return false
+  return /\.(ts|js|mts|mjs)$/.test(name)
+}
+
+/**
+ * `readdir(recursive)` reports nested entries via `parentPath`; older Node
+ * builds omit it for top-level entries, where the base directory is correct.
+ */
+function directoryUrl(parentPath: string | undefined, fallback: URL): URL {
+  if (parentPath === undefined) return fallback
+  // `readdir` echoes the path it was given, which already ends with a slash
+  // when it came from a URL. Adding a second one yields `…/commands//greet.ts`:
+  // still importable, but wrong the moment the path is written to a manifest.
+  const href = pathToFileURL(parentPath).href
+  return new URL(href.endsWith('/') ? href : `${href}/`)
+}
+
+/** The command a module default-exports, or undefined when it exports none. */
+function commandOf(mod: unknown): CommandClass | undefined {
+  if (typeof mod !== 'object' || mod === null) return undefined
+  const value = Reflect.get(mod, 'default')
+  return isCommandClass(value) ? value : undefined
+}