@c9up/ream 0.1.25 → 0.1.27

package/dist/console/Kernel.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Console kernel — registers commands and dispatches argv against them.
+ *
+ * Replaces the previous `CommandRunner`, which parsed argv without knowing the
+ * commands' declared inputs and therefore could not support `--flag value`,
+ * aliases, negation, typed flags, per-command help or required-input checks.
+ *
+ * The kernel accepts any class exposing the static contract in `types.ts` —
+ * extending `BaseCommand` is optional, which is what keeps agnostic packages
+ * free of a `@c9up/ream` dependency.
+ */
+import type { Application } from '../Application.js';
+import { type Logger, Ui } from './cliui.js';
+import { Prompt } from './prompts.js';
+import { type CommandClass, type CommandInstance, type ExecutedCommand, type FlagMetaData, type ParsedInput, type SerializedCommand } from './types.js';
+/**
+ * Called when a global flag was passed to the command invoked from the command
+ * line. Returning `true` stops the dispatch before the command runs.
+ */
+/** The kernel's lifecycle stage — Console `getState()`. */
+export type KernelState = 'idle' | 'booted' | 'running' | 'completed';
+/**
+ * A source of commands (Console `LoadersContract`).
+ *
+ * Two steps, as in Console: the metadata of everything it offers, then the class
+ * for one of them — a loader that reads a directory can answer the first from
+ * a manifest without importing anything.
+ */
+export interface CommandLoader {
+    getMetaData(): Promise<SerializedCommand[]>;
+    getCommand(metadata: SerializedCommand): Promise<CommandClass | null>;
+}
+/**
+ * How a command is built and run (Console `ExecutorContract`).
+ *
+ * `create` returns the instance, ready but untouched; `run` drives its
+ * lifecycle and returns what `run()` produced.
+ */
+export interface CommandExecutor {
+    /**
+     * The fourth argument is Ream's: which UI the command writes through, and
+     * whether it is the one the command line invoked. An executor ported from
+     * Console simply ignores it.
+     */
+    create(Command: CommandClass, parsed: ParsedInput, kernel: Kernel, context: {
+        isMain: boolean;
+        ui: Ui;
+    }): CommandInstance | Promise<CommandInstance>;
+    /** Runs `prepare`, `interact` and `run`, and throws what they throw. */
+    run(command: CommandInstance, kernel: Kernel): unknown;
+}
+/** Renders the failure of the command line (Console `ExceptionHandler`). */
+export interface ErrorRenderer {
+    render(error: unknown, kernel: Kernel): void | Promise<void>;
+}
+export type GlobalFlagListener = (command: CommandClass, kernel: Kernel, parsed: ParsedInput) => boolean | void | Promise<boolean | void>;
+export interface KernelOptions {
+    /**
+     * Boots the application. Called only for commands declaring
+     * `options.startApp` — a scaffolding command must not open a DB connection.
+     */
+    startApp?: () => Promise<Application>;
+    /** Shown in usage lines. */
+    binaryName?: string;
+    /**
+     * Shuts the application down. Handed to the command as `this.terminate()`,
+     * the only way a `staysAlive` command can end itself.
+     */
+    onTerminate?: () => void | Promise<void>;
+    /**
+     * The prompt handed to every command as `this.prompt`.
+     *
+     * Supply one to script its answers with `trap()`: without this the kernel
+     * builds its own, and a command that asks anything is untestable through
+     * `exec()` — it would reach a terminal that is not there.
+     */
+    prompt?: Prompt;
+}
+export interface HandleResult {
+    /** The command asked to keep the process alive (worker, watcher…). */
+    staysAlive: boolean;
+}
+export declare class Kernel {
+    #private;
+    /** Shared by the kernel and every command it runs. */
+    readonly ui: Ui;
+    readonly logger: Logger;
+    /**
+     * The command a kernel runs when none is named. Replace it to ship a
+     * different landing command (Console `Kernel.defaultCommand`).
+     */
+    static defaultCommand: CommandClass;
+    /**
+     * How a command is built and run (Console `Kernel.commandExecutor`).
+     *
+     * The seam AdonisJS itself uses to add dependency injection; Ream's default
+     * already does it — the container builds the command and invokes its hooks,
+     * so `@inject()` works on both. Replace it on a subclass to drive commands
+     * some other way.
+     */
+    static commandExecutor: CommandExecutor;
+    /**
+     * What the CLI says about itself — binary name, versions. Printed above the
+     * command listing when it holds anything (Console `kernel.info`).
+     */
+    readonly info: Map<string, string | number | boolean>;
+    /**
+     * Renders the failure of the command line (Console `kernel.errorHandler`).
+     *
+     * Replaceable: an application that wants its own reporting sets it here
+     * rather than wrapping `handle()`, which is what owns the process.
+     */
+    errorHandler: ErrorRenderer;
+    /**
+     * The exit code the command line ended on (Console `kernel.exitCode`). Set once
+     * the dispatch is over: 1 for a failure, otherwise the command's own.
+     */
+    exitCode: number | undefined;
+    /**
+     * Console's factory — `Kernel.create()` reads better than `new Kernel()`.
+     *
+     * Built through `this`, so a subclass overriding `defaultCommand` or
+     * `commandExecutor` gets its own from the factory as well as from `new`.
+     */
+    static create<T extends typeof Kernel>(this: T, options?: KernelOptions): InstanceType<T>;
+    constructor(options?: KernelOptions);
+    /** Shown in usage lines — commands read it to print their own. */
+    get binaryName(): string;
+    /**
+     * Declare a flag every command accepts (Console `kernel.defineFlag`).
+     *
+     * Global flags steer the CLI, not the command: they are merged into the
+     * parser so no command has to redeclare them, and they are NOT assigned to
+     * the command's properties — a command reads them through `this.parsed.flags`
+     * or, more usually, does not read them at all.
+     */
+    defineFlag(name: string, options?: Partial<FlagMetaData>): this;
+    /** The global flags — Console `kernel.flags`. */
+    get flags(): readonly FlagMetaData[];
+    /**
+     * React to a global flag (Console `kernel.on`). One listener per flag, the last
+     * one registered winning, and only for the command invoked from the command
+     * line. Returning `true` stops there, without running the command — that is
+     * how `--help` short-circuits.
+     */
+    on(flagName: string, listener: GlobalFlagListener): this;
+    register(command: CommandClass): this;
+    registerMany(commands: Iterable<CommandClass>): this;
+    /**
+     * Register the default export of a loaded module when it is a command.
+     * Returns whether anything was registered, so the caller can report a module
+     * that exports the wrong shape instead of ignoring it.
+     */
+    registerModule(mod: unknown): boolean;
+    /**
+     * Register a shorthand expanding to a command and, optionally, its flags —
+     * Console's `commandsAliases`. `resource` → `make:controller --resource` means
+     * `ream resource users` runs `ream make:controller --resource users`.
+     */
+    addAlias(alias: string, expansion: string): this;
+    /**
+     * Resolve a command by name or alias — Console's `find()`.
+     *
+     * Async and throwing, as in Console: a name that resolves to nothing is a call
+     * error, and returning `undefined` pushes every caller into a check it
+     * usually forgets. `await` works even though Ream's registry answers
+     * immediately.
+     */
+    find(name: string): Promise<CommandClass>;
+    /**
+     * Register a source of commands (Console `kernel.addLoader`).
+     *
+     * Consumed by {@link boot}, once. Unlike Console, the classes are resolved there
+     * and then rather than on first use: Ream's registry holds classes, which is
+     * what lets `find()` and `hasCommand()` answer without waiting on a loader.
+     */
+    addLoader(loader: CommandLoader | (() => Promise<CommandLoader>)): this;
+    /**
+     * Load every registered loader's commands. Idempotent, and called by
+     * `handle()` — an application driving its own dispatch calls it itself.
+     */
+    boot(): Promise<void>;
+    /** The kernel's lifecycle stage — Console `getState()`. */
+    getState(): KernelState;
+    /**
+     * The command run when none is named — the one this kernel was built with,
+     * or the application's replacement when it registered one under that name.
+     */
+    getDefaultCommand(): CommandClass;
+    /** The command invoked from the command line, once it has been built. */
+    getMainCommand(): CommandInstance | undefined;
+    /** Before a command name is resolved (Console hook). */
+    finding(callback: (commandName: string) => void | Promise<void>): this;
+    /** Before a command class is read from its loader (Console hook). */
+    loading(callback: (metadata: SerializedCommand) => void | Promise<void>): this;
+    /** After a command class has been loaded (Console hook). */
+    loaded(callback: (command: CommandClass) => void | Promise<void>): this;
+    /** Before a command runs. `isMain` distinguishes the CLI dispatch. */
+    executing(callback: (command: CommandInstance, isMain: boolean) => void | Promise<void>): this;
+    /** After a command has run — not when it failed, as in Console. */
+    executed(callback: (command: CommandInstance, isMain: boolean) => void | Promise<void>): this;
+    /**
+     * The metadata of every registered command, as Console exposes it.
+     *
+     * Metadata rather than the classes themselves: this is the introspection
+     * surface (help, completions, a command palette), and handing out the
+     * constructors invites callers to instantiate a command outside the kernel,
+     * where nothing injects its dependencies or runs its lifecycle. The class is
+     * still reachable through {@link find} when a caller genuinely needs it.
+     */
+    getCommands(): SerializedCommand[];
+    /** One command's metadata, or null — Console's `getCommand()`. */
+    getCommand(commandName: string): SerializedCommand | null;
+    /**
+     * The commands of one namespace. Called without one — or with an empty
+     * string — it answers with the commands that have no namespace at all, which
+     * is the group Console's own listing prints first.
+     */
+    getNamespaceCommands(namespace?: string): SerializedCommand[];
+    /** Every namespace in use, sorted. */
+    getNamespaces(): string[];
+    /** Every registered alias — `static aliases` and the rc file's alike. */
+    getAliases(): string[];
+    /** The command an alias stands for, or null when the alias is unknown. */
+    getAliasCommand(alias: string): SerializedCommand | null;
+    /** Every alias pointing at this command. */
+    getCommandAliases(commandName: string): string[];
+    /**
+     * Names close enough to this one to be what the user meant — Console's
+     * suggestions. Aliases are included: they are names one can legitimately
+     * type, so a typo on one deserves the same help.
+     */
+    getCommandSuggestions(name: string): string[];
+    getNamespaceSuggestions(name: string): string[];
+    handle(rawArgv: readonly string[], nodeArgs?: readonly string[]): Promise<HandleResult>;
+    /**
+     * Build a command, ready to run — the default executor's `create`.
+     *
+     * @internal Public only because {@link commandExecutor} is a static object
+     * and cannot reach the kernel's privates.
+     */
+    buildCommand(Command: CommandClass, parsed: ParsedInput, context?: {
+        isMain: boolean;
+        ui: Ui;
+    }): Promise<CommandInstance>;
+    /**
+     * Run `prepare`, `interact` and `run` — the default executor's `run`.
+     *
+     * `completed` is deliberately NOT here: it must run even when this throws,
+     * which is the kernel's business, not the executor's.
+     *
+     * @internal See {@link buildCommand}.
+     */
+    runLifecycle(command: CommandInstance): Promise<unknown>;
+    /**
+     * Run a command programmatically — Console's `consoleApp.exec()`.
+     *
+     * It REJECTS when the command fails, as Console does: the error is recorded on
+     * the command (`error`, `exitCode` 1) and then rethrown, so a caller cannot
+     * mistake a failure for a success by forgetting to look. `process.exitCode`
+     * is left alone — only the command line owns that.
+     *
+     * To inspect a failing command instead of catching, build it with
+     * {@link create} and drive it yourself, or run it through `handle()` and read
+     * {@link getMainCommand}.
+     */
+    exec(commandName: string, argv?: readonly string[], options?: {
+        ui?: Ui;
+    }): Promise<ExecutedCommand>;
+    /**
+     * Build a command instance without running it (Console `kernel.create`).
+     *
+     * Parsed, injected and hydrated — everything `exec()` does up to the
+     * lifecycle. The escape hatch for driving a command by hand: run it with
+     * `command.exec()` and inspect it whatever it does.
+     */
+    create<T extends CommandClass>(Command: T, argv?: readonly string[]): Promise<InstanceType<T>>;
+    /** Is this name — or alias — dispatchable? Console's `consoleApp.hasCommand()`. */
+    hasCommand(name: string): boolean;
+    /**
+     * `list` — commands grouped by namespace, as Console does.
+     *
+     * `namespaces` narrows the output to those groups; an empty list shows
+     * everything. `make` selects `make:*`, and the empty string the commands that
+     * have no namespace at all.
+     */
+    printList(asJson?: boolean, namespaces?: readonly string[]): void;
+    /** `<command> --help` — usage, arguments and flags for one command. */
+    printCommandHelp(command: CommandClass | SerializedCommand): void;
+}
+/**
+ * A command's metadata, whether or not it extends `BaseCommand`.
+ *
+ * A class declared structurally by an agnostic package has no `serialize()`, so
+ * the fields are read off the statics it does carry.
+ */
+export declare function serializeCommand(command: CommandClass): SerializedCommand;
+//# sourceMappingURL=Kernel.d.ts.map

package/dist/console/Kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Kernel.d.ts","sourceRoot":"","sources":["../../src/console/Kernel.ts"],"names":[],"mappings":"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"}