@c9up/ream 0.1.26 → 0.1.27

package/dist/console/Kernel.js

@@ -0,0 +1,1120 @@
+/**
+ * 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 { isReamError, ReamError } from '../errors/ReamError.js';
+import { createAssertions, createSnapshot } from './assertions.js';
+import { Ui } from './cliui.js';
+import { buildFlag } from './decorators.js';
+import { ExceptionHandler } from './ExceptionHandler.js';
+import HelpCommand from './HelpCommand.js';
+import ListCommand from './ListCommand.js';
+import { assignParsedValues, parseArgv, validateParsed } from './parser.js';
+import { Prompt } from './prompts.js';
+import { commandExec } from './tracing.js';
+import { isCommandClass, } from './types.js';
+import { renderErrorWithSuggestions } from './utils.js';
+import { colourise } from './ui.js';
+export class Kernel {
+    #commands = new Map();
+    /**
+     * Commands a loader announced but whose class has not been imported yet.
+     *
+     * Booting reads metadata only, as Console does: listing the commands, answering
+     * `hasCommand()` or printing help must not run the module of a command
+     * nobody asked for.
+     */
+    #pending = new Map();
+    #aliases = new Map();
+    /**
+     * Commands the kernel registered on its own behalf, which an application may
+     * replace — see {@link register}.
+     */
+    #defaults = new Set();
+    /** Flags every command accepts — Console's global command. */
+    #globalFlags = [];
+    #flagListeners = new Map();
+    #loaders = [];
+    #hooks = { finding: [], loading: [], loaded: [], executing: [], executed: [] };
+    #state = 'idle';
+    #mainCommand;
+    #defaultCommand;
+    #executor;
+    /** The application a command was built with, when it asked for one. */
+    #apps = new WeakMap();
+    #startApp;
+    #onTerminate;
+    #prompt;
+    #binaryName;
+    /** Shared by the kernel and every command it runs. */
+    ui = new Ui();
+    logger = this.ui.logger;
+    /**
+     * The command a kernel runs when none is named. Replace it to ship a
+     * different landing command (Console `Kernel.defaultCommand`).
+     */
+    static defaultCommand = ListCommand;
+    /**
+     * 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 = {
+        create(Command, parsed, kernel, context) {
+            return kernel.buildCommand(Command, parsed, context);
+        },
+        run(command, kernel) {
+            return kernel.runLifecycle(command);
+        },
+    };
+    /**
+     * What the CLI says about itself — binary name, versions. Printed above the
+     * command listing when it holds anything (Console `kernel.info`).
+     */
+    info = new Map();
+    /**
+     * 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 = new ExceptionHandler();
+    /**
+     * 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;
+    /**
+     * 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(options = {}) {
+        return new this(options);
+    }
+    constructor(options = {}) {
+        this.#startApp = options.startApp;
+        this.#onTerminate = options.onTerminate;
+        this.#prompt = options.prompt;
+        this.#binaryName = options.binaryName ?? 'ream';
+        // `list` is a command, not a branch in the dispatcher — Console registers it the
+        // same way, which is what makes `hasCommand('list')`, `exec('list')` and
+        // `help list` true statements instead of special cases.
+        // Read off `new.target`, so a subclass overriding `static defaultCommand`
+        // gets its own (Console's customisation point).
+        this.#defaultCommand = new.target.defaultCommand;
+        this.#executor = new.target.commandExecutor;
+        this.register(this.#defaultCommand);
+        this.#defaults.add(this.#defaultCommand.commandName);
+        // `help` is a command for the same reason `list` is: everything the
+        // registry guarantees — introspection, `exec()`, replaceability — is false
+        // for a name only the dispatcher knows.
+        this.register(HelpCommand);
+        this.#defaults.add(HelpCommand.commandName);
+        // Console's `--help`, a global flag whose listener runs the help command.
+        this.defineFlag('help', {
+            type: 'boolean',
+            alias: ['h'],
+            description: 'Display help for the given command',
+        });
+        this.on('help', async (Command, kernel, parsed) => {
+            // Only the mention, not `--no-help`.
+            if (parsed.flags.help !== true)
+                return false;
+            // Whatever was resolved: the named command, or the default one for a bare
+            // `ream --help` — whose own help documents the listing.
+            await kernel.exec('help', [Command.commandName]);
+            return true;
+        });
+        // Console's `--ansi` / `--no-ansi`, declared as what they are: a global flag.
+        // Declaring them makes them visible in help and rejected nowhere, instead
+        // of being intercepted by a special case in the dispatcher.
+        this.defineFlag('ansi', {
+            type: 'boolean',
+            description: 'Force colours on, or off with --no-ansi',
+            showNegatedVariantInHelp: true,
+        });
+        this.on('ansi', (_command, _kernel, parsed) => {
+            if (parsed.flags.ansi === true) {
+                process.env.FORCE_COLOR = '1';
+                delete process.env.NO_COLOR;
+                return;
+            }
+            process.env.NO_COLOR = '1';
+            delete process.env.FORCE_COLOR;
+        });
+    }
+    /** Shown in usage lines — commands read it to print their own. */
+    get binaryName() {
+        return this.#binaryName;
+    }
+    /**
+     * 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, options = {}) {
+        if (this.#state !== 'idle') {
+            throw new ReamError('E_CONSOLE_LATE_GLOBAL_FLAG', `Global flag "--${name}" was declared while the kernel was "${this.#state}".`, { hint: 'Declare global flags while wiring the kernel, before booting it.' });
+        }
+        this.#globalFlags.push(buildFlag(name, options));
+        return this;
+    }
+    /** The global flags — Console `kernel.flags`. */
+    get flags() {
+        return [...this.#globalFlags];
+    }
+    /**
+     * 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, listener) {
+        this.#flagListeners.set(flagName, listener);
+        return this;
+    }
+    register(command) {
+        const existing = this.#commands.get(command.commandName);
+        if (existing !== undefined && existing !== command) {
+            // The kernel's own defaults are replaceable: one registry, and the
+            // application wins — an app shipping its own `list` gets it, the same
+            // rule the CLI applies to the built-in commands it shadows. Two
+            // APPLICATION commands claiming one name stays an error: there is
+            // nothing to arbitrate between them.
+            if (!this.#defaults.has(command.commandName)) {
+                throw new ReamError('E_CONSOLE_DUPLICATE_COMMAND', `Two commands claim the name "${command.commandName}".`, { hint: 'Rename one of them, or namespace it (e.g. "app:provision").' });
+            }
+            this.#defaults.delete(command.commandName);
+        }
+        this.#pending.delete(command.commandName);
+        this.#commands.set(command.commandName, command);
+        // `static aliases` travel with the command; rc-level `commandsAliases` are
+        // registered separately and may still override these.
+        for (const alias of command.aliases ?? []) {
+            this.#aliases.set(alias, [command.commandName]);
+        }
+        return this;
+    }
+    registerMany(commands) {
+        for (const command of commands)
+            this.register(command);
+        return 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) {
+        if (typeof mod !== 'object' || mod === null)
+            return false;
+        const value = Reflect.get(mod, 'default');
+        if (!isCommandClass(value))
+            return false;
+        this.register(value);
+        return true;
+    }
+    /**
+     * 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, expansion) {
+        const tokens = tokeniseExpansion(expansion);
+        if (tokens.length === 0) {
+            throw new ReamError('E_CONSOLE_INVALID_ALIAS', `Alias "${alias}" expands to nothing.`, {
+                hint: 'Expected a command name, e.g. "make:controller --resource".',
+            });
+        }
+        this.#aliases.set(alias, tokens);
+        return 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.
+     */
+    async find(name) {
+        const [resolved] = this.#expandAlias([name]);
+        const commandName = resolved ?? name;
+        await this.#emit(this.#hooks.finding, (handler) => handler(commandName));
+        const loaded = this.#commands.get(commandName);
+        if (loaded !== undefined) {
+            await this.#emit(this.#hooks.loading, (handler) => handler(this.#metadataFor(loaded)));
+            await this.#emit(this.#hooks.loaded, (handler) => handler(loaded));
+            return loaded;
+        }
+        const pending = this.#pending.get(commandName);
+        if (pending === undefined) {
+            throw new ReamError('E_CONSOLE_COMMAND_NOT_FOUND', `Unknown command "${name}".`, {
+                hint: 'Check the name with hasCommand() first, or list them with getCommands().',
+            });
+        }
+        await this.#emit(this.#hooks.loading, (handler) => handler(pending.metadata));
+        // Here is where a loader's module is imported — for the command that was
+        // actually asked for, and once.
+        const command = await pending.loader.getCommand(pending.metadata);
+        if (command === null) {
+            throw new ReamError('E_CONSOLE_COMMAND_NOT_FOUND', `The loader announced "${commandName}" but did not provide it.`, { hint: 'A loader must return the command it listed in its metadata.' });
+        }
+        this.register(command);
+        await this.#emit(this.#hooks.loaded, (handler) => handler(command));
+        return command;
+    }
+    /**
+     * 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) {
+        if (this.#state !== 'idle') {
+            throw new ReamError('E_CONSOLE_LATE_LOADER', `A command loader was added while the kernel was "${this.#state}".`, { hint: 'Add loaders before booting the kernel.' });
+        }
+        this.#loaders.push(loader);
+        return this;
+    }
+    /**
+     * Load every registered loader's commands. Idempotent, and called by
+     * `handle()` — an application driving its own dispatch calls it itself.
+     */
+    async boot() {
+        if (this.#state !== 'idle')
+            return;
+        this.#state = 'booted';
+        for (const entry of this.#loaders) {
+            const loader = typeof entry === 'function' ? await entry() : entry;
+            for (const metadata of await loader.getMetaData()) {
+                // Metadata only — the class is imported by `find()`, when someone asks
+                // for the command. `loading` / `loaded` belong there too.
+                if (!this.#commands.has(metadata.commandName)) {
+                    this.#pending.set(metadata.commandName, { metadata, loader });
+                }
+                // The metadata is what a manifest-style loader publishes; its aliases
+                // may be richer than the class's `static aliases`, and reading only the
+                // class would leave `hasCommand(alias)` answering false for a name the
+                // loader announced.
+                for (const alias of metadata.aliases)
+                    this.addAlias(alias, metadata.commandName);
+            }
+        }
+    }
+    /** The kernel's lifecycle stage — Console `getState()`. */
+    getState() {
+        return this.#state;
+    }
+    /**
+     * 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() {
+        return this.#commands.get(this.#defaultCommand.commandName) ?? this.#defaultCommand;
+    }
+    /** The command invoked from the command line, once it has been built. */
+    getMainCommand() {
+        return this.#mainCommand;
+    }
+    /** Before a command name is resolved (Console hook). */
+    finding(callback) {
+        this.#hooks.finding.push(callback);
+        return this;
+    }
+    /** Before a command class is read from its loader (Console hook). */
+    loading(callback) {
+        this.#hooks.loading.push(callback);
+        return this;
+    }
+    /** After a command class has been loaded (Console hook). */
+    loaded(callback) {
+        this.#hooks.loaded.push(callback);
+        return this;
+    }
+    /** Before a command runs. `isMain` distinguishes the CLI dispatch. */
+    executing(callback) {
+        this.#hooks.executing.push(callback);
+        return this;
+    }
+    /** After a command has run — not when it failed, as in Console. */
+    executed(callback) {
+        this.#hooks.executed.push(callback);
+        return 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() {
+        return this.#allMetadata();
+    }
+    /** One command's metadata, or null — Console's `getCommand()`. */
+    getCommand(commandName) {
+        const command = this.#commands.get(commandName);
+        if (command !== undefined)
+            return this.#metadataFor(command);
+        const pending = this.#pending.get(commandName);
+        // Answered from the metadata a loader published: describing a command must
+        // not require importing it.
+        return pending === undefined
+            ? null
+            : { ...pending.metadata, aliases: this.#aliasesFor(commandName) };
+    }
+    /**
+     * 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) {
+        const wanted = namespace === undefined || namespace === '' ? null : namespace;
+        return this.#allMetadata().filter((command) => command.namespace === wanted);
+    }
+    /** Every namespace in use, sorted. */
+    getNamespaces() {
+        const found = new Set();
+        for (const commandName of this.#names()) {
+            const namespace = namespaceOf(commandName);
+            if (namespace !== null)
+                found.add(namespace);
+        }
+        return [...found].sort((a, b) => a.localeCompare(b));
+    }
+    /** Every registered alias — `static aliases` and the rc file's alike. */
+    getAliases() {
+        return [...this.#aliases.keys()].sort((a, b) => a.localeCompare(b));
+    }
+    /** The command an alias stands for, or null when the alias is unknown. */
+    getAliasCommand(alias) {
+        const expansion = this.#aliases.get(alias);
+        if (expansion === undefined)
+            return null;
+        return this.getCommand(expansion[0] ?? '');
+    }
+    /** Every alias pointing at this command. */
+    getCommandAliases(commandName) {
+        return this.#aliasesFor(commandName);
+    }
+    /**
+     * 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) {
+        return suggestFrom(name, [...this.#names(), ...this.#aliases.keys()]);
+    }
+    getNamespaceSuggestions(name) {
+        return suggestFrom(name, this.getNamespaces());
+    }
+    async handle(rawArgv, nodeArgs = []) {
+        if (this.#state === 'running') {
+            throw new ReamError('E_CONSOLE_KERNEL_RUNNING', 'A command is already running through this kernel.', { hint: 'One kernel drives one command line. Use exec() to call another command.' });
+        }
+        if (this.#state === 'completed') {
+            throw new ReamError('E_CONSOLE_KERNEL_COMPLETED', 'The kernel has finished; it cannot run another command line.', { hint: 'Create a fresh kernel.' });
+        }
+        await this.boot();
+        this.#state = 'running';
+        try {
+            return await this.#dispatch(rawArgv, nodeArgs);
+        }
+        catch (error) {
+            // The command line owns the process, so a failure is REPORTED here rather
+            // than thrown at a caller who has nothing better to do with it — Console's
+            // rule. `exec()` is the path that rethrows.
+            this.exitCode = 1;
+            process.exitCode = 1;
+            await this.errorHandler.render(error, this);
+            return { staysAlive: false };
+        }
+        finally {
+            // In `finally`, not after the call: `handle()` returns early on help, on
+            // an unknown command and on a short-circuiting flag listener. A state set
+            // on the success path alone lies on every other one.
+            this.#state = 'completed';
+        }
+    }
+    async #dispatch(rawArgv, nodeArgs) {
+        const argv = this.#expandAlias(this.#hoistGlobalFlags(rawArgv));
+        const [name, ...rest] = argv;
+        // Resolved through `find()`, like Console's own CLI path: it is what runs the
+        // finding/loading/loaded hooks, and a tool listening to them must see the
+        // command line, not only `exec()`.
+        //
+        // The default command goes through `find()` too: `ream` bare and
+        // `ream <command>` must run the same cycle, hooks included. Resolved by
+        // NAME, so an application that replaced it gets its own.
+        const target = name ?? this.getDefaultCommand().commandName;
+        let Command;
+        try {
+            Command = await this.find(target);
+        }
+        catch (error) {
+            // An unknown name gets the listing's help, not a stack trace: a typo is
+            // the most common way to reach this.
+            if (isReamError(error, 'E_CONSOLE_COMMAND_NOT_FOUND')) {
+                this.#reportUnknown(target);
+                return { staysAlive: false };
+            }
+            throw error;
+        }
+        const argvForCommand = name === undefined ? [] : rest;
+        const parsed = this.#parse(Command, argvForCommand, nodeArgs, true);
+        if (await this.#runFlagListeners(Command, parsed))
+            return { staysAlive: false };
+        this.#validate(Command, parsed);
+        const instance = await this.#runCommand(Command, parsed, true);
+        this.#mainCommand = instance;
+        const failure = Reflect.get(instance, 'error');
+        if (failure !== undefined)
+            throw failure;
+        const exitCode = Reflect.get(instance, 'exitCode');
+        if (typeof exitCode === 'number')
+            this.exitCode = exitCode;
+        if (typeof exitCode === 'number' && exitCode !== 0)
+            process.exitCode = exitCode;
+        return { staysAlive: Command.options?.staysAlive === true };
+    }
+    /**
+     * Parse, build and run one command through its full lifecycle.
+     *
+     * Shared by `handle()` (the CLI path, which rethrows) and `exec()` (the
+     * programmatic path, which reports through the returned instance). Errors are
+     * recorded on the instance rather than thrown, so both callers decide what to
+     * do with them instead of the logic being written twice.
+     */
+    /**
+     * Read argv against a command's declarations, global flags included.
+     *
+     * Separate from {@link #runCommand} because the main command's parsed input
+     * is needed BEFORE the command is built: Console's global-flag listeners see it,
+     * and one of them may end the dispatch.
+     */
+    #parse(Command, argv, nodeArgs, withGlobalFlags) {
+        const parsed = parseArgv(argv, {
+            args: Command.args,
+            // Global flags belong to the command line: they are merged for the
+            // command invoked there, and NOT for `exec()`, as in Console. A caller
+            // passing `--no-ansi` to exec() is passing a flag the command does not
+            // accept, and hearing so is the point.
+            flags: withGlobalFlags ? this.#flagsFor(Command) : (Command.flags ?? []),
+            allowUnknownFlags: Command.options?.allowUnknownFlags,
+            commandName: Command.commandName,
+            // Leniently: the required inputs are checked AFTER the global-flag
+            // listeners have had their say, which is what makes `--help` work on a
+            // command whose flags are required (Console's order).
+            validate: false,
+        });
+        parsed.nodeArgs = [...nodeArgs];
+        return parsed;
+    }
+    /** Hold the parsed input to the command's declarations — after the listeners. */
+    #validate(Command, parsed) {
+        validateParsed(parsed, {
+            args: Command.args,
+            flags: Command.flags,
+            allowUnknownFlags: Command.options?.allowUnknownFlags,
+            commandName: Command.commandName,
+        });
+    }
+    /**
+     * Run the listeners of the global flags that were passed. Returns whether one
+     * of them ended the dispatch.
+     *
+     * Console runs them for the main command only, and before it is built: a command
+     * that will not run must not boot the application first.
+     */
+    async #runFlagListeners(Command, parsed) {
+        for (const [flagName, listener] of this.#flagListeners) {
+            if (parsed.flags[flagName] === undefined)
+                continue;
+            // A command redeclaring the name owns the flag entirely — the value in
+            // `parsed.flags` is ITS value, and handing it to the global listener
+            // would act on something that was never the global flag.
+            if (Command.flags?.some((flag) => flag.flagName === flagName))
+                continue;
+            if ((await listener(Command, this, parsed)) === true)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Build a command: inject, plug in the plumbing, hydrate. Everything up to
+     * the lifecycle, shared by {@link create} and {@link #runCommand}.
+     */
+    async #build(Command, parsed, isMain, ui) {
+        // The application is resolved BEFORE the command is built: with one
+        // available, the command goes through the container so constructor
+        // dependencies are injected (Console parity), and its lifecycle hooks are
+        // invoked through `container.call` so `@inject()` works on them too.
+        const app = await this.#resolveApp(Command);
+        const instance = app === undefined ? new Command() : await app.container.make(Command);
+        Object.assign(instance, {
+            logger: ui.logger,
+            ui,
+            kernel: this,
+            colors: ui.colors,
+            // `handle()` is the command line; `exec()` is another caller.
+            isMain,
+            prompt: this.#prompt ?? new Prompt(),
+            // Console exposes every parsed input, not only the declared ones.
+            parsed,
+            onTerminate: this.#onTerminate,
+        });
+        this.#attachApp(instance, Command, app);
+        // Values after the plumbing, as Console does: the command's own `hydrate()`
+        // when it has one — a ported command may call it again, it is idempotent —
+        // and a plain assignment for a class declared structurally, which has none.
+        const hydrate = Reflect.get(instance, 'hydrate');
+        if (typeof hydrate === 'function')
+            Reflect.apply(hydrate, instance, []);
+        else
+            assignParsedValues(instance, Command.args ?? [], Command.flags ?? [], parsed);
+        // The application is handed back rather than resolved twice: booting it is
+        // not free, and `#resolveApp` is what starts it.
+        return { instance, app };
+    }
+    /**
+     * 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.
+     */
+    async buildCommand(Command, parsed, context = { isMain: false, ui: this.ui }) {
+        const { instance, app } = await this.#build(Command, parsed, context.isMain, context.ui);
+        // Kept off the instance: `this.app` throws by design when the command did
+        // not ask for the application, and the lifecycle still needs to know
+        // whether there is a container to call through.
+        if (app !== undefined)
+            this.#apps.set(instance, app);
+        return instance;
+    }
+    /**
+     * 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}.
+     */
+    async runLifecycle(command) {
+        await this.#invoke(command, 'prepare');
+        await this.#invoke(command, 'interact');
+        return this.#invoke(command, 'run');
+    }
+    /** Call a lifecycle hook, through the container when there is one. */
+    async #invoke(command, hook) {
+        if (typeof command[hook] !== 'function')
+            return undefined;
+        const app = this.#apps.get(command);
+        if (app === undefined)
+            return command[hook]();
+        return app.container.call(command, hook);
+    }
+    async #runCommand(Command, parsed, isMain = false, ui = this.ui) {
+        const instance = await this.#executor.create(Command, parsed, this, { isMain, ui });
+        const invoke = (hook) => this.#invoke(instance, hook);
+        // Console's order: prepare → interact → run → completed. `completed` runs even
+        // when an earlier stage threw, and can mark the error handled.
+        let failure;
+        let result;
+        await this.#emit(this.#hooks.executing, (handler) => handler(instance, isMain));
+        try {
+            // Traced: an APM agent subscribes to `ream.command.exec` and sees every
+            // run without the kernel knowing it is watched. The payload is only built
+            // when somebody listens.
+            result = await (commandExec.hasSubscribers
+                ? commandExec.tracePromise(() => Promise.resolve(this.#executor.run(instance, this)), {
+                    command: Command,
+                    commandInstance: instance,
+                    argv: parsed.args.map(String),
+                })
+                : this.#executor.run(instance, this));
+        }
+        catch (err) {
+            failure = err;
+        }
+        // Assigned before `completed()` so the hook can inspect them.
+        const ran = Object.assign(instance, { error: failure, result });
+        if (typeof ran.completed === 'function') {
+            try {
+                const handled = await invoke('completed');
+                if (handled === true)
+                    ran.error = undefined;
+            }
+            catch (err) {
+                // `completed` is part of the lifecycle, so a throw from it is an
+                // execution failure like any other — it must not escape and turn
+                // `exec()` into a rejection. When an earlier stage had already failed,
+                // that first error is kept as the `cause` rather than lost.
+                ran.error =
+                    ran.error === undefined || !(err instanceof Error)
+                        ? err
+                        : Object.assign(err, { cause: err.cause ?? ran.error });
+            }
+        }
+        // Console's convention: a command that failed without setting its own code
+        // exits 1.
+        const scored = Object.assign(ran, {
+            exitCode: typeof ran.exitCode === 'number' ? ran.exitCode : ran.error === undefined ? 0 : 1,
+        });
+        // Only when it finished: Console runs `executed` after the executor returns, so
+        // a throw skips it. A hook counting successes must not see a failure —
+        // and `completed()` marking the error handled IS a finish.
+        if (scored.error === undefined) {
+            await this.#emit(this.#hooks.executed, (handler) => handler(scored, isMain));
+        }
+        // Attached rather than inherited: a command declared structurally by an
+        // agnostic package never extends BaseCommand, and `exec()` promises these
+        // to every caller. A class that defines its own keeps it — `Object.assign`
+        // only fills what is missing here because we spread ours first.
+        return Object.assign(scored, createAssertions(scored, ui), {
+            toJSON: createSnapshot(scored, Command.commandName, Command.options ?? {}),
+        });
+    }
+    /**
+     * 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}.
+     */
+    async exec(commandName, argv = [], options = {}) {
+        if (this.#state === 'idle')
+            await this.boot();
+        if (this.#state === 'completed') {
+            throw new ReamError('E_CONSOLE_KERNEL_COMPLETED', `The kernel has finished; "${commandName}" cannot be run through it.`, { hint: 'Create a fresh kernel to execute more commands.' });
+        }
+        const expanded = this.#expandAlias([commandName, ...argv]);
+        const [name, ...rest] = expanded;
+        const Command = await this.find(name ?? commandName);
+        // A caller-supplied UI is what silences a command, or captures its output
+        // without touching the kernel's own (Console `exec(..., { ui })`).
+        const parsed = this.#parse(Command, rest, [], false);
+        this.#validate(Command, parsed);
+        const command = await this.#runCommand(Command, parsed, false, options.ui);
+        if (command.error !== undefined)
+            throw command.error;
+        return command;
+    }
+    /**
+     * 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.
+     */
+    async create(Command, argv = []) {
+        if (this.#state === 'idle')
+            await this.boot();
+        const { instance } = await this.#build(Command, this.#parse(Command, argv, [], false), false, this.ui);
+        // The instance IS of the class handed in — built by `new Command()` or by
+        // the container from that same class. Typing it as the structural contract
+        // would hide the command's own API from the caller who named it.
+        return instance;
+    }
+    /** Is this name — or alias — dispatchable? Console's `consoleApp.hasCommand()`. */
+    hasCommand(name) {
+        const known = (commandName) => this.#commands.has(commandName) || this.#pending.has(commandName);
+        if (known(name))
+            return true;
+        const expansion = this.#aliases.get(name);
+        return expansion !== undefined && known(expansion[0] ?? '');
+    }
+    /**
+     * Give the command its application — booting first when it asked for it.
+     *
+     * When it did not, `this.app` is a throwing accessor rather than
+     * `undefined`: a command that resolves a service without declaring
+     * `startApp: true` gets a message naming the fix, instead of a
+     * "cannot read properties of undefined" ten frames deep.
+     */
+    /**
+     * Boot the application when the command asked for it, and hand it back so the
+     * command can be built through the container.
+     */
+    async #resolveApp(Command) {
+        if (Command.options?.startApp !== true)
+            return undefined;
+        if (this.#startApp === undefined) {
+            throw new ReamError('E_CONSOLE_NO_APP', `"${Command.commandName}" requires a booted application, but this kernel was created without one.`, { hint: 'Dispatch through the Ignitor console kernel rather than a bare Kernel instance.' });
+        }
+        return this.#startApp();
+    }
+    #attachApp(instance, Command, app) {
+        if (app === undefined) {
+            Object.defineProperty(instance, 'app', {
+                configurable: true,
+                get: () => {
+                    throw new ReamError('E_CONSOLE_APP_NOT_STARTED', `"${Command.commandName}" accessed this.app without booting the application.`, { hint: `Add: static options: CommandOptions = { startApp: true }` });
+                },
+            });
+            return;
+        }
+        Object.assign(instance, { app });
+    }
+    /**
+     * Swap a leading alias for what it stands for. Only the first token is
+     * considered: an alias is a command shorthand, not a general macro.
+     */
+    #expandAlias(argv) {
+        const [first, ...rest] = argv;
+        if (first === undefined)
+            return argv;
+        const expansion = this.#aliases.get(first);
+        return expansion === undefined ? argv : [...expansion, ...rest];
+    }
+    /**
+     * Run a hook's handlers in registration order.
+     *
+     * The caller passes the invocation rather than the arguments, which keeps
+     * every hook's payload typed — a single variadic `emit` would need a cast to
+     * correlate the hook name with its parameters.
+     */
+    async #emit(handlers, invoke) {
+        for (const handler of handlers)
+            await invoke(handler);
+    }
+    /** The command's own flags, plus the global ones it did not redeclare. */
+    #flagsFor(Command) {
+        const own = [...(Command.flags ?? [])];
+        const declared = new Set(own.map((flag) => flag.flagName));
+        return [...own, ...this.#globalFlags.filter((flag) => !declared.has(flag.flagName))];
+    }
+    /**
+     * Move a global flag written BEFORE the command name to after it.
+     *
+     * `ream --no-ansi list` has to work — that is where a user naturally puts a
+     * CLI-wide switch — but the command name has to be the first token for the
+     * registry lookup. Moving them keeps ONE parser for global and command flags
+     * alike, instead of a second, hand-rolled scan.
+     */
+    #hoistGlobalFlags(argv) {
+        const leading = [];
+        const rest = [...argv];
+        while (rest.length > 0) {
+            const token = rest[0];
+            if (token === '--' || !token.startsWith('-'))
+                break;
+            const name = token.replace(/^--?(no-)?/, '').split('=')[0] ?? '';
+            const meta = this.#globalFlags.find((flag) => flag.flagName === name || flag.alias.includes(name));
+            if (meta === undefined)
+                break;
+            leading.push(rest.shift());
+            // A value-taking flag written apart from its value takes the next token
+            // with it, or the value would be read as the command name.
+            if (meta.type !== 'boolean' && !token.includes('=') && rest[1] !== undefined) {
+                leading.push(rest.shift());
+            }
+        }
+        if (leading.length === 0)
+            return [...argv];
+        const [command, ...args] = rest;
+        return command === undefined ? leading : [command, ...args, ...leading];
+    }
+    #reportUnknown(name) {
+        // Aliases are names the user can legitimately type, so a typo on one has to
+        // be suggestible too.
+        renderErrorWithSuggestions(this.logger, `Unknown command "${name}".`, [
+            ...this.getCommandSuggestions(name).slice(0, 1),
+        ]);
+        process.stderr.write(`  Run "${this.#binaryName} list" to see available commands.\n`);
+        process.exitCode = 1;
+    }
+    /**
+     * `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 = false, namespaces = []) {
+        // Off the metadata, not the classes: listing the commands must not import
+        // the ones a loader has only announced.
+        const all = this.#allMetadata();
+        const commands = namespaces.length === 0
+            ? all
+            : all.filter((command) => namespaces.includes(command.namespace ?? ''));
+        if (asJson) {
+            // The full metadata contract, not a three-field summary: tooling reads
+            // this to build help, completions or a command palette.
+            this.logger.log(JSON.stringify(commands, null, 2));
+            return;
+        }
+        this.logger.log(`\n${colourise('Usage:', 'yellow')} ${this.#binaryName} <command> [options]\n`);
+        // What the CLI says about itself, when it was told anything (Console
+        // `kernel.info`): binary name, framework and app versions.
+        if (this.info.size > 0) {
+            for (const [label, value] of this.info) {
+                this.logger.log(`  ${colourise(label, 'dim')}  ${String(value)}`);
+            }
+            this.logger.log('');
+        }
+        if (commands.length === 0) {
+            this.logger.log('  No commands registered.\n');
+            return;
+        }
+        const width = Math.max(...commands.map((command) => command.commandName.length));
+        const groups = new Map();
+        for (const command of commands) {
+            const group = command.namespace ?? '';
+            const bucket = groups.get(group);
+            if (bucket === undefined)
+                groups.set(group, [command]);
+            else
+                bucket.push(command);
+        }
+        // Ungrouped commands first, then each namespace.
+        for (const [group, entries] of [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+            this.logger.log(group === '' ? colourise('Available commands', 'yellow') : colourise(group, 'yellow'));
+            for (const command of entries) {
+                const suffix = command.aliases.length === 0 ? '' : colourise(` [${command.aliases.join(', ')}]`, 'dim');
+                this.logger.log(`  ${colourise(command.commandName.padEnd(width), 'green')}  ${command.description}${suffix}`);
+            }
+            this.logger.log('');
+        }
+    }
+    /**
+     * Every alias pointing at this command — both `static aliases` and the rc
+     * file's `commandsAliases`, which only differ in where they were declared.
+     */
+    #aliasesFor(commandName) {
+        const found = [];
+        for (const [alias, expansion] of this.#aliases) {
+            if (expansion[0] === commandName)
+                found.push(alias);
+        }
+        return found.sort((a, b) => a.localeCompare(b));
+    }
+    /** Every command name the kernel knows, loaded or merely announced. */
+    #names() {
+        return [...new Set([...this.#commands.keys(), ...this.#pending.keys()])];
+    }
+    /**
+     * The metadata of every command, sorted by name.
+     *
+     * A loaded class wins over the announcement it came from: once imported, the
+     * class IS the contract, and a stale manifest must not describe it.
+     */
+    #allMetadata() {
+        const all = new Map();
+        for (const [commandName, pending] of this.#pending) {
+            all.set(commandName, { ...pending.metadata, aliases: this.#aliasesFor(commandName) });
+        }
+        for (const command of this.#commands.values()) {
+            all.set(command.commandName, this.#metadataFor(command));
+        }
+        return [...all.values()].sort((a, b) => a.commandName.localeCompare(b.commandName));
+    }
+    /**
+     * A command's metadata with the aliases the KERNEL knows about — a command
+     * declares its own, but the rc file can add more, and a consumer reading the
+     * metadata has no way to find those on its own.
+     */
+    #metadataFor(command) {
+        return { ...serializeCommand(command), aliases: this.#aliasesFor(command.commandName) };
+    }
+    /** `<command> --help` — usage, arguments and flags for one command. */
+    printCommandHelp(command) {
+        // Metadata is enough to describe a command, and it is what the `help`
+        // command holds: explaining a command must not import it.
+        const meta = typeof command === 'function' ? serializeCommand(command) : command;
+        const args = meta.args;
+        const flags = meta.flags;
+        const usage = [this.#binaryName, meta.commandName];
+        for (const arg of args) {
+            const label = arg.type === 'spread' ? `...${arg.argumentName}` : arg.argumentName;
+            usage.push(arg.required ? `<${label}>` : `[${label}]`);
+        }
+        if (flags.length > 0)
+            usage.push('[options]');
+        this.logger.log(`\n${colourise('Usage:', 'yellow')} ${usage.join(' ')}\n`);
+        this.logger.log(`  ${meta.description}\n`);
+        const help = meta.help;
+        if (help !== undefined) {
+            // Console substitutes `{{ binaryName }}` so a help block can show a runnable
+            // example without hardcoding the binary's name.
+            for (const line of Array.isArray(help) ? help : [help]) {
+                this.logger.log(`  ${line.replace(/\{\{\s*binaryName\s*\}\}/g, this.#binaryName)}`);
+            }
+            this.logger.log('');
+        }
+        if (args.length > 0) {
+            this.logger.log(colourise('Arguments', 'yellow'));
+            const width = Math.max(...args.map((arg) => arg.argumentName.length));
+            for (const arg of args) {
+                const notes = [
+                    arg.required ? undefined : 'optional',
+                    arg.default === undefined ? undefined : `default: ${String(arg.default)}`,
+                ].filter((note) => note !== undefined);
+                const suffix = notes.length > 0 ? colourise(` (${notes.join(', ')})`, 'dim') : '';
+                this.logger.log(`  ${colourise(arg.argumentName.padEnd(width), 'green')}  ${arg.description ?? ''}${suffix}`);
+            }
+            this.logger.log('');
+        }
+        // The command's own flags, then the global ones under their own heading —
+        // a flag every command accepts but that no help mentions is a flag nobody
+        // discovers.
+        this.#printFlags('Options', flags);
+        this.#printFlags('Global flags', this.#globalFlags);
+    }
+    #printFlags(heading, flags) {
+        if (flags.length > 0) {
+            this.logger.log(colourise(heading, 'yellow'));
+            const labels = flags.map((flag) => {
+                const aliases = flag.alias.map((alias) => `-${alias}`).join(', ');
+                // Booleans are always negatable; this only decides whether help says so.
+                const negated = flag.type === 'boolean' && flag.showNegatedVariantInHelp === true
+                    ? ` | --no-${flag.flagName}`
+                    : '';
+                return `${aliases === '' ? '' : `${aliases}, `}--${flag.flagName}${flag.type === 'boolean' ? '' : `=<${flag.type}>`}${negated}`;
+            });
+            const width = Math.max(...labels.map((label) => label.length));
+            flags.forEach((flag, index) => {
+                const notes = [
+                    flag.required ? 'required' : undefined,
+                    flag.default === undefined ? undefined : `default: ${String(flag.default)}`,
+                ].filter((note) => note !== undefined);
+                const suffix = notes.length > 0 ? colourise(` (${notes.join(', ')})`, 'dim') : '';
+                this.logger.log(`  ${colourise((labels[index] ?? '').padEnd(width), 'green')}  ${flag.description ?? ''}${suffix}`);
+            });
+            this.logger.log('');
+        }
+    }
+}
+/**
+ * Split an alias expansion into argv tokens, honouring quotes.
+ *
+ * A plain `split(/\s+/)` breaks `make:controller --name "Blog Post"` into four
+ * tokens instead of three, so any alias carrying a value with a space was
+ * unrepresentable. Backslash escapes the next character.
+ */
+function tokeniseExpansion(expansion) {
+    const tokens = [];
+    let current = '';
+    let quote;
+    let started = false;
+    for (let i = 0; i < expansion.length; i++) {
+        const char = expansion[i];
+        if (char === '\\' && i + 1 < expansion.length) {
+            current += expansion[++i];
+            started = true;
+            continue;
+        }
+        if (quote !== undefined) {
+            if (char === quote)
+                quote = undefined;
+            else
+                current += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (started) {
+                tokens.push(current);
+                current = '';
+                started = false;
+            }
+            continue;
+        }
+        current += char;
+        started = true;
+    }
+    if (started)
+        tokens.push(current);
+    return tokens;
+}
+/**
+ * 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 function serializeCommand(command) {
+    const own = Reflect.get(command, 'serialize');
+    if (typeof own === 'function') {
+        const serialized = Reflect.apply(own, command, []);
+        if (isSerialized(serialized))
+            return serialized;
+    }
+    return {
+        commandName: command.commandName,
+        namespace: namespaceOf(command.commandName),
+        description: command.description,
+        help: command.help,
+        aliases: [...(command.aliases ?? [])],
+        options: { ...command.options },
+        args: (command.args ?? []).map(({ parse: _p, ...rest }) => rest),
+        flags: (command.flags ?? []).map(({ parse: _p, ...rest }) => rest),
+    };
+}
+/** `make:controller` → `make`; a name without a colon has no namespace. */
+function namespaceOf(commandName) {
+    const colon = commandName.indexOf(':');
+    return colon === -1 ? null : commandName.slice(0, colon);
+}
+function isSerialized(value) {
+    return typeof value === 'object' && value !== null && 'commandName' in value;
+}
+/**
+ * The candidates close enough to `input` to be worth suggesting, nearest first.
+ *
+ * One ranking, used both by the "Did you mean?" line and by the public
+ * suggestion methods — two implementations would eventually disagree about
+ * what counts as close.
+ */
+function suggestFrom(input, candidates) {
+    const threshold = Math.max(2, Math.floor(input.length / 3));
+    return candidates
+        .map((candidate) => ({ candidate, score: distance(input, candidate) }))
+        .filter(({ score }) => score <= threshold)
+        .sort((a, b) => a.score - b.score || a.candidate.localeCompare(b.candidate))
+        .map(({ candidate }) => candidate);
+}
+function distance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let previous = Array.from({ length: cols }, (_, index) => index);
+    for (let i = 1; i < rows; i++) {
+        const current = [i];
+        for (let j = 1; j < cols; j++) {
+            const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+            const insertion = (current[j - 1] ?? 0) + 1;
+            const deletion = (previous[j] ?? 0) + 1;
+            current[j] = Math.min(substitution, insertion, deletion);
+        }
+        previous = current;
+    }
+    return previous[cols - 1] ?? 0;
+}
+//# sourceMappingURL=Kernel.js.map