@loomcli/core 0.1.0 → 0.2.0

package/dist/application.d.ts

@@ -1,7 +1,9 @@
 import type { AfterAction, AfterArgument, AfterCommand, Command, CommandMethod, CommandState } from './command.js';
 import type { FailureRenderer } from './errors.js';
+import type { ExtensionValue } from './extension.js';
 import type { GlobalOptions } from './globals.js';
 import type { CommandGraph } from './inspect.js';
+import type { Plugin } from './plugin.js';
 import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, MultipleConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, RunOptions, ValidateOmittedConstraint } from './types.js';
 /**
  * Every authoring call an Application can publish, beside `run()` and `name`, which always remain.
@@ -17,6 +19,10 @@ export type ApplicationMethod = Exclude<CommandMethod, 'alias'>;
 export interface ApplicationOptions<Globals = {}> {
     globals?: GlobalOptions<Globals>;
     failures?: readonly FailureRenderer[];
+    plugins?: readonly Plugin[];
+    extensions?: readonly ExtensionValue<'command'>[];
+    description?: string;
+    version?: string;
 }
 /**
  * The Application holds the unnamed root's declaration state and applies the same transitions a
@@ -26,8 +32,10 @@ declare class ApplicationBuilder<Args, Options, Globals, State extends Applicati
     #private;
     readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals>;
     constructor(name: string, root: CommandState<Args, Options, Globals>, config: {
+        declared: DeclaredFacts;
         failures: readonly FailureRenderer[];
         options?: unknown;
+        plugins: readonly Plugin[];
     });
     get name(): string;
     argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>>;
@@ -42,6 +50,13 @@ declare class ApplicationBuilder<Args, Options, Globals, State extends Applicati
      * wrapper publishes the same runtime value in exactly that state.
      */
     private derive;
+    /**
+     * Every rule that reads the declarations alone, in the order `run()` reads them: the options
+     * slot, the installed list, the application's failure registrations, each plugin's declarations,
+     * then the whole Command graph. The registry is published as soon as it is known, so a later
+     * declaration error still reaches the renderers the application registered for it.
+     */
+    private prepare;
     /**
      * The built graph as plain, frozen data. It applies every rule `run()` applies without a schema,
      * in the order `run()` applies them, and throws `DeclarationError` when one fails. Validating a
@@ -64,6 +79,11 @@ interface ApplicationConstructor {
     new (name: string): Application<{}, {}, {}, ApplicationMethod>;
     new <Globals = {}>(name: string, options: ApplicationOptions<Globals>): Application<{}, {}, Globals, ApplicationMethod>;
 }
+/** The same facts as the constructor captured them, before any rule has read them. */
+interface DeclaredFacts {
+    description: unknown;
+    version: unknown;
+}
 /**
  * The public constructor takes a name and one options object. The globals type narrows to the
  * supplied value, and the failure renderers configure the application the way its commands do.

package/dist/application.js

@@ -1,12 +1,36 @@
-import { attachChild, buildGraph, collectInputs, declareAction, declareArgument, declareOption, freshState, selectCommand, } from './command.js';
-import { buildFailures, DeclarationError, describeFailure, InternalError, reasonOf, toFailure, } from './errors.js';
+import { runInvocation } from './chain.js';
+import { attachChild, buildGraph, collectInputs, declareAction, declareArgument, declareOption, freshState, } from './command.js';
+import { buildFailures, DeclarationError, describeFailure, InternalError, mergeFailures, reasonOf, toFailure, } from './errors.js';
+import { checkDescription, checkNoListingFacts, checkVersion, isPlainObject } from './facts.js';
 import { isGlobalOptions } from './globals.js';
 import { captureHost } from './host.js';
 import { inspectGraph } from './inspect.js';
 import { Output, reportPlainly } from './output.js';
+import { buildPlugins, installPlugins, ownedSignals, pluginSentence } from './plugin.js';
+import { bracketRun, cancellationCode, isCancellationEcho } from './signals.js';
 import { captureConfig, checkDeclarations, prepareInputs } from './validation.js';
 /** The registry a failure is reported through when the application's own could not be built. */
 const noRegistrations = new Map();
+/**
+ * Whether one failure is the cancellation the run already reports, which core does not report a
+ * second time. Any other failure after cancellation is rendered as usual.
+ */
+function silenced(thrown, signal, cancelled) {
+    return cancelled !== undefined && isCancellationEcho(thrown, signal.reason);
+}
+/**
+ * The caller's own signal, read where it enters. A JavaScript caller reaches the slot with any
+ * value, and a value that is not an `AbortSignal` would otherwise escape as a raw TypeError.
+ */
+function checkSignal(signal) {
+    if (signal === undefined) {
+        return undefined;
+    }
+    if (!(signal instanceof AbortSignal)) {
+        throw new InternalError('run() received a signal that is not an AbortSignal. Supply the signal of an AbortController.', undefined);
+    }
+    return signal;
+}
 /**
  * The Application holds the unnamed root's declaration state and applies the same transitions a
  * Command does, so each declaration call has one typed implementation and no builder to recover.
@@ -15,14 +39,19 @@ class ApplicationBuilder {
     #name;
     #root;
     #failures;
-    // The constructor's raw options argument stays unexamined until build.
+    #plugins;
+    // The constructor's raw options argument, kept for the slot's own shape rules.
     // The options-slot rules answer at the same point every other authoring fault does:
     // `inspect()` and `run()`.
     #options;
+    // The facts the constructor read out of that slot, unexamined until build.
+    #declared;
     constructor(name, root, config) {
+        this.#declared = config.declared;
         this.#failures = config.failures;
         this.#name = name;
         this.#options = config.options;
+        this.#plugins = config.plugins;
         this.#root = root;
     }
     get name() {
@@ -59,10 +88,33 @@ class ApplicationBuilder {
      */
     derive(root) {
         return new ApplicationBuilder(this.#name, root, {
+            declared: this.#declared,
             failures: this.#failures,
             options: this.#options,
+            plugins: this.#plugins,
         });
     }
+    /**
+     * Every rule that reads the declarations alone, in the order `run()` reads them: the options
+     * slot, the installed list, the application's failure registrations, each plugin's declarations,
+     * then the whole Command graph. The registry is published as soon as it is known, so a later
+     * declaration error still reaches the renderers the application registered for it.
+     */
+    prepare(register) {
+        const facts = checkOptions(this.#options, this.#declared);
+        const installed = installPlugins(this.#plugins);
+        const application = buildFailures(this.#failures);
+        register(application);
+        const install = { descriptors: new Map(), extensions: new Map() };
+        const plugins = buildPlugins(installed, install);
+        register(mergeFailures([
+            application,
+            ...plugins.map((entry) => buildFailures(entry.failures, pluginSentence(entry.identity))),
+        ]));
+        const graph = buildGraph(this.#root, { ...install, plugins });
+        checkDeclarations([...graph.globals.inputs, ...collectInputs(graph.root)]);
+        return { facts, graph, plugins };
+    }
     /**
      * The built graph as plain, frozen data. It applies every rule `run()` applies without a schema,
      * in the order `run()` applies them, and throws `DeclarationError` when one fails. Validating a
@@ -70,11 +122,8 @@ class ApplicationBuilder {
      * Nothing is cached: each call builds the graph anew.
      */
     inspect() {
-        checkOptions(this.#options);
-        buildFailures(this.#failures);
-        const graph = buildGraph(this.#root);
-        checkDeclarations([...graph.globals.inputs, ...collectInputs(graph.root)]);
-        return inspectGraph(this.#name, graph);
+        const built = this.prepare(() => undefined);
+        return inspectGraph(this.#name, built.graph, built.facts);
     }
     async run(options) {
         let stderr = process.stderr;
@@ -83,91 +132,159 @@ class ApplicationBuilder {
         let reportingFailed = false;
         // A registry that could not be built reports through core's defaults, not through itself.
         let registry = undefined;
+        // Faults a plugin raised beside the primary outcome, reported after it and never before it.
+        const faults = [];
+        // One private controller per run, subscribed to the caller's signal at run entry.
+        const controller = new AbortController();
+        /**
+         * The bracket this run holds. It exists once the caller's own signal has been read, so a
+         * signal that is not an `AbortSignal` is reported through the failure path like any other.
+         */
+        let signals = undefined;
+        // A cancelled run resolves its cancellation code whenever it ends after graph build.
+        // A declaration or internal failure raised before that ends the run with its own code instead.
+        let graphBuilt = false;
+        const cancellation = () => {
+            const reason = graphBuilt ? signals?.reason() : undefined;
+            return reason ? cancellationCode(reason) : undefined;
+        };
+        /**
+         * Every exit path of the run leaves through the removal below, the one place it is written,
+         * so no listener this run installed outlives it however the run ends.
+         */
         try {
-            const overrides = options?.host;
-            stderr = overrides?.stderr ?? stderr;
-            const host = captureHost(overrides, stderr);
-            output = new Output(host);
-            checkOptions(this.#options);
-            registry = buildFailures(this.#failures);
-            const graph = buildGraph(this.#root);
-            const inputs = { globals: graph.globals.inputs, locals: collectInputs(graph.root) };
-            const defaults = await prepareInputs(inputs, host);
-            const selected = await selectCommand(graph, { defaults, host });
-            await selected.dispatch({
-                host,
-                out: output.out,
-                passthrough: selected.passthrough,
-                values: selected.values,
-            });
-            // The fault check covers the same window the write accounting covers.
-            // A render failure an unawaited helper raised is still this invocation's failure.
-            await output.settle();
-            const fault = output.fault;
-            if (fault) {
-                // The action returned, so the renderer failure is this invocation's own failure.
-                throw new InternalError(`Rendering output failed: ${reasonOf(fault.cause)}`, fault.cause);
-            }
-        }
-        catch (error) {
             try {
-                const failure = toFailure(error);
-                code = failure.exitCode;
-                output ??= new Output({ stderr, stdout: process.stdout });
-                const writes = await output.settle();
-                if (writes.kind === 'ok') {
-                    const report = describeFailure(registry ?? noRegistrations, failure);
-                    if (report.kind === 'rendered') {
-                        // The renderer already owns every byte, trailing newline included: pass it through.
-                        await output.report(report.text);
+                const overrides = options?.host;
+                stderr = overrides?.stderr ?? stderr;
+                const host = captureHost(overrides, stderr);
+                output = new Output(host);
+                signals = bracketRun(controller, checkSignal(options?.signal));
+                const built = this.prepare((value) => {
+                    registry = value;
+                });
+                const { graph } = built;
+                const inputs = { globals: graph.globals.inputs, locals: collectInputs(graph.root) };
+                const defaults = await prepareInputs(inputs, host);
+                graphBuilt = true;
+                if (!controller.signal.aborted) {
+                    /**
+                     * The listeners the validated signals owner claimed. A build failure installs none, and
+                     * neither does a run the caller had already cancelled: it touches the process not at all.
+                     */
+                    signals.install(ownedSignals(built.plugins));
+                    await runInvocation({
+                        defaults,
+                        facts: built.facts,
+                        graph,
+                        host,
+                        name: this.#name,
+                        out: output.out,
+                        plugins: built.plugins,
+                        report: (fault) => faults.push(fault),
+                        signal: controller.signal,
+                    });
+                }
+                // The fault check covers the same window the write accounting covers.
+                // A render failure an unawaited helper raised is still this invocation's failure.
+                await output.settle();
+                const fault = output.fault;
+                if (fault) {
+                    // The action returned, so the renderer failure is this invocation's own failure.
+                    throw new InternalError(`Rendering output failed: ${reasonOf(fault.cause)}`, fault.cause);
+                }
+            }
+            catch (error) {
+                try {
+                    const failure = toFailure(error);
+                    code = failure.exitCode;
+                    output ??= new Output({ stderr, stdout: process.stdout });
+                    const writes = await output.settle();
+                    if (writes.kind === 'ok' && !silenced(error, controller.signal, cancellation())) {
+                        const report = describeFailure(registry ?? noRegistrations, failure);
+                        if (report.kind === 'rendered') {
+                            // The renderer already owns every byte, trailing newline included: pass it through.
+                            await output.report(report.text);
+                        }
+                        else {
+                            code = 1;
+                            // `report.text` is core's default text, which already ends in `\n`.
+                            await reportPlainly(stderr, `${report.text}Internal error: Rendering the failure failed: ${report.reason}\n`);
+                        }
+                    }
+                }
+                catch {
+                    code = 1;
+                    reportingFailed = true;
+                }
+            }
+            // A plugin's own fault is reported after the primary outcome and turns a would-be 0 into 1.
+            // The primary outcome keeps its code, the way a renderer failure leaves it alone.
+            // It is reported the way the primary failure is, so a registered renderer answers its class.
+            for (const fault of faults) {
+                if (!silenced(fault, controller.signal, cancellation())) {
+                    code = code === 0 ? 1 : code;
+                    try {
+                        const report = describeFailure(registry ?? noRegistrations, fault);
+                        if (report.kind === 'rendered') {
+                            await output?.report(report.text);
+                        }
+                        else {
+                            code = 1;
+                            await reportPlainly(stderr, `${report.text}Internal error: Rendering the failure failed: ${report.reason}\n`);
+                        }
                     }
-                    else {
-                        code = 1;
-                        // `report.text` is core's default text, which already ends in `\n`.
-                        await reportPlainly(stderr, `${report.text}Internal error: Rendering the failure failed: ${report.reason}\n`);
+                    catch {
+                        reportingFailed = true;
                     }
                 }
             }
-            catch {
-                code = 1;
-                reportingFailed = true;
+            if (output) {
+                const writes = await output.settle();
+                if (writes.kind === 'failed') {
+                    code = 1;
+                    reportingFailed = true;
+                }
+                output.dispose();
             }
-        }
-        if (output) {
-            const writes = await output.settle();
-            if (writes.kind === 'failed') {
-                code = 1;
-                reportingFailed = true;
+            if (reportingFailed) {
+                await reportPlainly(stderr, 'Internal error: Could not write invocation output.\n');
             }
-            output.dispose();
+            /**
+             * One rule orders every code: a cancelled run resolves its signal's code, and a broken
+             * failure renderer or destination in that run is reported as text without changing it. The
+             * signal decides the code whatever the action did afterward, so this reading comes last.
+             */
+            code = cancellation() ?? code;
+            process.exitCode = code;
+            return code;
         }
-        if (reportingFailed) {
-            await reportPlainly(stderr, 'Internal error: Could not write invocation output.\n');
+        finally {
+            signals?.finish();
         }
-        process.exitCode = code;
-        return code;
     }
 }
-/** The options slot holds one object literal, so a declaration that carries state is not one. */
-function isPlainObject(value) {
-    if (value === null || typeof value !== 'object') {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
 /**
  * The second argument, read where it is supplied. The retired positional form declares its globals
  * on a value that holds no `globals` key, so without this rule the globals vanish silently and the
- * operator, not the author, meets the consequence as an unknown-option error.
+ * operator, not the author, meets the consequence as an unknown-option error. The slot's own shape
+ * settles first, because a slot that is not an options object carries no facts to report.
  */
-function checkOptions(options) {
+function checkOptions(options, declared) {
     if (isGlobalOptions(options)) {
         throw new DeclarationError('The Application takes an options object. Supply { globals } instead of a positional GlobalOptions value.');
     }
-    if (options !== undefined && !isPlainObject(options)) {
-        throw new DeclarationError('The Application options must be an object. Supply { globals, failures }.');
+    if (options !== undefined) {
+        if (!isPlainObject(options)) {
+            throw new DeclarationError('The Application options must be an object. Supply { globals, failures }.');
+        }
+        // The root is every page's entry point, so it carries neither listing fact.
+        // A key that may not be there is a fault of the slot, so it answers with the slot's shape.
+        checkNoListingFacts('The Application', options);
     }
+    return {
+        description: checkDescription('The Application', declared.description),
+        version: checkVersion(declared.version),
+    };
 }
 /**
  * The runtime class behind the public constructor. It is generic so that an instance's `Globals`
@@ -177,8 +294,23 @@ function checkOptions(options) {
 class ApplicationDeclaration extends ApplicationBuilder {
     constructor(name, options) {
         // The options slot is read defensively, never inspected: an invalid value still yields
-        // `globals` and `failures` of some kind, and `checkOptions` reports it at build instead.
-        super(name, freshState(null, options?.globals), { failures: options?.failures ?? [], options });
+        // `globals`, `failures`, and the facts of some kind, and `checkOptions` reports it at build.
+        // The root's own slot and core facts stay empty, because the Application checks its own slot.
+        // Its diagnostics name the Application rather than the root Command.
+        super(name, freshState({
+            deprecated: undefined,
+            description: undefined,
+            extensions: options?.extensions,
+            globals: options?.globals,
+            hidden: undefined,
+            name: null,
+            options: undefined,
+        }), {
+            declared: { description: options?.description, version: options?.version },
+            failures: options?.failures ?? [],
+            options,
+            plugins: options?.plugins ?? [],
+        });
     }
 }
 /**

package/dist/chain.d.ts

@@ -0,0 +1,49 @@
+import type { BuiltGraph } from './command.js';
+import type { LoomError } from './errors.js';
+import type { CommandGraph, CommandNode } from './inspect.js';
+import type { BuiltPlugin, PluginOptions, PluginOptionValues } from './plugin.js';
+import type { Host, Out } from './types.js';
+import type { DefaultValues } from './validation.js';
+/**
+ * What the rest of one chain did: the action ran, a later middleware took over by returning without
+ * calling its own `next()`, or the run was cancelled before the action ran.
+ */
+type ChainOutcome = 'cancelled' | 'dispatched' | 'taken-over';
+/**
+ * What one middleware receives. `graph` is the frozen graph `inspect()` returns, built once for the
+ * run, and `command` is the routed node inside it. `options` holds this plugin's own option values
+ * and never another plugin's or the application's globals.
+ */
+interface MiddlewareContext<Options extends PluginOptions = PluginOptions> {
+    readonly options: PluginOptionValues<Options>;
+    readonly graph: CommandGraph;
+    readonly command: CommandNode;
+    readonly host: Host;
+    readonly out: Out;
+    readonly signal: AbortSignal;
+    readonly next: () => Promise<ChainOutcome>;
+}
+/** Everything one invocation needs after its graph is built and its defaults are validated. */
+interface Invocation {
+    defaults: DefaultValues;
+    facts: {
+        description: string | undefined;
+        version: string;
+    };
+    graph: BuiltGraph;
+    host: Host;
+    name: string;
+    out: Out;
+    plugins: readonly BuiltPlugin[];
+    /** A fault reported after the primary outcome, which turns a would-be 0 into 1. */
+    report: (fault: LoomError) => void;
+    signal: AbortSignal;
+}
+/**
+ * Runs one invocation: the global pre-scan, routing, the middleware chain, and the phases the chain
+ * terminates in. A middleware that returns without calling `next()` has taken over, so the
+ * remaining tokens are never parsed and nothing later in the chain runs.
+ */
+declare function runInvocation(invocation: Invocation): Promise<void>;
+export type { ChainOutcome, Invocation, MiddlewareContext };
+export { runInvocation };