@loomcli/core 0.1.0 → 0.2.0

package/dist/chain.js

@@ -0,0 +1,288 @@
+import { prepareDispatch, routeInvocation } from './command.js';
+import { InternalError, reasonOf, toFailure } from './errors.js';
+import { inspectGraph } from './inspect.js';
+import { booleanValue } from './options.js';
+import { pluginSentence } from './plugin.js';
+/**
+ * The default export a loader must resolve to. A loaded module is data core never declared, so the
+ * check is the one runtime fact that decides it: the export is callable. Core calls it with the
+ * context it owns and ignores whatever it returns.
+ */
+function isMiddlewareExport(value) {
+    return typeof value === 'function';
+}
+/** Whether one option name was supplied as a token, in any spelling a declaration accepts. */
+function supplied(scan, name) {
+    return scan.strings.has(name) || scan.lists.has(name) || scan.booleans.has(name);
+}
+/** A collected value, or the declared array default, as this run's own copy. */
+function collectedValue(collected, declared) {
+    if (collected) {
+        return [...collected];
+    }
+    return Array.isArray(declared) ? [...declared] : [];
+}
+/**
+ * One plugin's own option values for one run: what the pre-scan produced, or the declared default,
+ * filled without validation. A collected value and an array default are copied, so a middleware
+ * that writes to what it received changes neither the declaration nor the next run.
+ */
+function pluginValues(inputs, scan) {
+    const values = {};
+    for (const { config, name } of inputs) {
+        const declared = config.default;
+        if (config.type === 'boolean') {
+            values[name] = booleanValue(scan, name, config);
+        }
+        else if (config.multiple === true) {
+            values[name] = collectedValue(scan.lists.get(name), declared);
+        }
+        else {
+            // Build already proved that a string option without a schema declares a string default.
+            values[name] =
+                scan.strings.get(name) ?? (typeof declared === 'string' ? declared : undefined);
+        }
+    }
+    return values;
+}
+/** Whether one plugin's declared activation matched the tokens the pre-scan consumed. */
+function activates(installed, scan) {
+    const { middleware } = installed;
+    if (!middleware) {
+        return false;
+    }
+    return (middleware.activate === 'always' || middleware.activate.some((name) => supplied(scan, name)));
+}
+/**
+ * The chain for one invocation: each installed plugin whose activation matched, in installation
+ * order. Activation is read from the pre-scan, before any plugin code loads, so a plugin whose
+ * option was never supplied is not in the chain and its loader is never called.
+ */
+function activatedEntries(plugins, scan) {
+    return plugins
+        .filter((installed) => activates(installed, scan))
+        .map((installed) => ({
+        identity: installed.identity,
+        // Activation proved the middleware exists, so the empty loader is never the one core calls.
+        load: installed.middleware?.load ?? (() => undefined),
+        options: pluginValues(installed.inputs, scan),
+    }));
+}
+/**
+ * The routed node inside the inspected graph, which routing already proved reachable. A missing
+ * segment means the two readings of one graph disagree, so the chain stops rather than hand a
+ * middleware the wrong Command.
+ */
+function nodeAt(graph, path) {
+    let node = graph.root;
+    for (const name of path) {
+        const child = node.children.find((entry) => entry.name === name);
+        if (!child) {
+            throw new InternalError(`The routed command "${path.join(' ')}" is not in the inspected graph.`, undefined);
+        }
+        node = child;
+    }
+    return node;
+}
+/** A downstream promise core awaits for its completion alone; its outcome was recorded already. */
+async function quiet(pending) {
+    if (pending) {
+        try {
+            await pending;
+        }
+        catch {
+            // The rejection was recorded where it crossed the `next()` boundary.
+        }
+    }
+}
+/**
+ * The outcome one entry reports to its caller. `'cancelled'` wins over `'taken-over'`, so a later
+ * middleware that returned because it saw the abort reports as cancelled, the order the exit codes
+ * follow. An action that already ran still reports as dispatched.
+ */
+function reported(chain, outcome) {
+    return outcome === 'taken-over' && chain.cancelled() ? 'cancelled' : outcome;
+}
+/** A `next()` call that is no longer live: it dispatches nothing and rejects. */
+function misuse(turn) {
+    const fault = new InternalError(`${pluginSentence(turn.entry.identity)} called next() ${turn.state.returned ? 'after its middleware returned' : 'twice'}.`, undefined);
+    turn.chain.report(fault);
+    const rejected = Promise.reject(fault);
+    void rejected.catch(() => undefined);
+    return rejected;
+}
+/**
+ * The `next` one middleware receives. It is live until that middleware's own result settles, so a
+ * second call, or a call after the middleware returned, rejects and continues nothing.
+ */
+function nextOf(turn) {
+    const { chain, state } = turn;
+    return () => {
+        if (state.returned || state.calls > 0) {
+            return misuse(turn);
+        }
+        state.calls += 1;
+        const pending = chain.step(turn.index + 1).then((outcome) => {
+            state.outcome = outcome;
+            state.settled = true;
+            return outcome;
+        }, (error) => {
+            state.rejection = { value: error };
+            state.settled = true;
+            chain.record(error);
+            throw error;
+        });
+        state.downstream = pending;
+        // Core awaits the downstream promise itself, so a middleware that never awaits `next()` still
+        // Holds the chain open and never ends the run with an unobserved rejection.
+        void pending.catch(() => undefined);
+        return pending;
+    };
+}
+/** The middleware's own result as a value, so the decision below reads one shape. */
+async function call(middleware, context) {
+    try {
+        await middleware(context);
+        return undefined;
+    }
+    catch (error) {
+        return { value: error };
+    }
+}
+/**
+ * What one entry reports to its caller once its own result has settled. A throw before `next()`
+ * settled, or without calling it, is this invocation's failure; a throw during unwinding is an
+ * internal error reported after the primary outcome, which keeps its own code.
+ */
+async function settle(turn, thrown) {
+    const { chain, state } = turn;
+    if (thrown) {
+        const propagated = state.rejection !== undefined && thrown.value === state.rejection.value;
+        if (propagated || !state.settled) {
+            await quiet(state.downstream);
+            throw thrown.value;
+        }
+        /**
+         * A fault core recorded where it was raised, such as a misused `next()`, reaches this point
+         * again when the middleware let it escape. It keeps the one report it already has.
+         */
+        if (!chain.announced(thrown.value)) {
+            chain.report(new InternalError(reasonOf(thrown.value), thrown.value));
+        }
+    }
+    if (state.calls === 0) {
+        return reported(chain, 'taken-over');
+    }
+    await quiet(state.downstream);
+    // A middleware that caught the rejection reports what the chain reached; the recorded failure
+    // Still decides the exit code.
+    return reported(chain, state.outcome ?? (chain.invoked() ? 'dispatched' : 'taken-over'));
+}
+/** The module one loader answers with, whether it throws where it is called or rejects later. */
+async function loadModule(entry) {
+    try {
+        return await entry.load();
+    }
+    catch (error) {
+        throw new InternalError(`Loading plugin "${entry.identity}" failed: ${reasonOf(error)}`, error);
+    }
+}
+/** A plugin's module is loaded when the chain reaches it, never before. */
+async function loadMiddleware(entry) {
+    const module = await loadModule(entry);
+    const handler = module !== null && typeof module === 'object' && 'default' in module
+        ? module.default
+        : undefined;
+    if (!isMiddlewareExport(handler)) {
+        throw new InternalError(`Loading plugin "${entry.identity}" failed: the module exports no default middleware function.`, undefined);
+    }
+    return handler;
+}
+/** One entry's turn: its module loads here, when the chain reaches it and never before. */
+async function runEntry(entry, index, chain) {
+    const middleware = await loadMiddleware(entry);
+    if (chain.cancelled()) {
+        /**
+         * A module import cannot be aborted, so a loader already in flight settles and core starts
+         * nothing with it: the middleware it resolved to is skipped.
+         */
+        return 'cancelled';
+    }
+    const state = { calls: 0, returned: false, settled: false };
+    const turn = { chain, entry, index, state };
+    const thrown = await call(middleware, chain.context(entry, nextOf(turn)));
+    state.returned = true;
+    return settle(turn, thrown);
+}
+/** The whole chain, answering with the failure it raised when a middleware caught that failure. */
+async function runChain(invocation, routed, entries) {
+    const run = { invoked: false, raised: undefined };
+    const terminal = async () => {
+        const dispatch = await prepareDispatch(invocation.graph, routed, invocation);
+        run.invoked = true;
+        await dispatch();
+        return 'dispatched';
+    };
+    const cancelled = () => invocation.signal.aborted;
+    if (entries.length === 0) {
+        if (!cancelled()) {
+            await terminal();
+        }
+        return undefined;
+    }
+    // The graph a middleware reads is the one `inspect()` returns, built once for the run.
+    const graph = inspectGraph(invocation.name, invocation.graph, invocation.facts);
+    const command = nodeAt(graph, routed.path);
+    // Every fault this chain has reported, so the same one raised again carries no second report.
+    const announced = new WeakSet();
+    const chain = {
+        announced: (value) => typeof value === 'object' && value !== null && announced.has(value),
+        cancelled,
+        context: (entry, next) => ({
+            command,
+            graph,
+            host: invocation.host,
+            next,
+            options: entry.options,
+            out: invocation.out,
+            signal: invocation.signal,
+        }),
+        invoked: () => run.invoked,
+        record: (error) => {
+            run.raised ??= toFailure(error);
+        },
+        report: (fault) => {
+            announced.add(fault);
+            invocation.report(fault);
+        },
+        step: (index) => {
+            if (cancelled()) {
+                /**
+                 * Core starts nothing new after cancellation: a middleware the chain has not reached and
+                 * an action not yet dispatched are skipped, and the entries already running unwind.
+                 */
+                return Promise.resolve('cancelled');
+            }
+            const entry = entries[index];
+            return entry ? runEntry(entry, index, chain) : terminal();
+        },
+    };
+    await chain.step(0);
+    return run.raised;
+}
+/**
+ * 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.
+ */
+async function runInvocation(invocation) {
+    const routed = routeInvocation(invocation.graph, invocation.host.argv);
+    const entries = activatedEntries(invocation.plugins, routed.scan);
+    const raised = await runChain(invocation, routed, entries);
+    if (raised) {
+        // The chain resolved because a middleware caught the rejection. The failure it caught still
+        // Decides the exit code, the rule an action's caught output rejection already follows.
+        throw raised;
+    }
+}
+export { runInvocation };

package/dist/command.d.ts

@@ -1,5 +1,8 @@
+import type { DescriptorRegistry, ExtensionRecords, ExtensionValue } from './extension.js';
 import type { BuiltGlobals, GlobalOptions } from './globals.js';
 import { compileOptions } from './options.js';
+import type { OptionValues } from './options.js';
+import type { BuiltPlugin, PluginBuild } from './plugin.js';
 import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, Host, MultipleConstraint, NameConstraint, OptionConfig, OptionValue, Out, ValidateOmittedConstraint } from './types.js';
 import type { ArgumentInput, DefaultValues, InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
 /** One positional slot: the declaration it fills and whether it takes the remaining tokens. */
@@ -12,10 +15,11 @@ export interface DispatchInput {
     host: Host;
     out: Out;
     passthrough: string[];
+    signal: AbortSignal;
     values: ValidatedInputs;
 }
 /**
- * One child a bare token reaches, under its canonical name or one of its hidden aliases.
+ * One child a bare token reaches, under its canonical name or one of its aliases.
  * `name` repeats the key `children` holds, because `BuiltCommand.name` is `string | null` for the
  * root and the routed path a child extends holds strings alone.
  */
@@ -26,13 +30,17 @@ export interface RoutedChild {
 /**
  * A group registers no action, so its `dispatch` is `undefined` and selection rejects it.
  * `children` is keyed by canonical name, so every candidate list and every walk of the graph reads
- * it, and `routes` adds the hidden aliases, so routing alone resolves them.
+ * it, and `routes` adds the aliases, so routing alone resolves them.
  */
 export interface BuiltCommand {
     aliases: readonly string[];
     arguments: readonly ArgumentSlot[];
     children: ReadonlyMap<string, BuiltCommand>;
+    deprecated: string | undefined;
+    description: string | undefined;
     dispatch: ((input: DispatchInput) => unknown) | undefined;
+    extensions: Readonly<Record<string, unknown>>;
+    hidden: boolean;
     inputs: readonly InputDeclaration[];
     name: string | null;
     options: ReturnType<typeof compileOptions>;
@@ -81,6 +89,8 @@ interface AttachedCommand {
  * owner is the parent whose attachment the walk meets first.
  */
 interface BuildContext {
+    descriptors: DescriptorRegistry;
+    extensions: ExtensionRecords;
     globals: BuiltGlobals;
     owners: Map<AttachedCommand, string | null>;
 }
@@ -97,13 +107,30 @@ export interface CommandState<Args, Options, Globals> {
         options: Options;
     };
     children: readonly object[];
+    deprecated: unknown;
+    description: unknown;
+    extensions: unknown;
+    hidden: unknown;
     globals: GlobalOptions<Globals> | undefined;
     inputs: readonly InputDeclaration[];
     late: readonly LateDeclaration[];
     name: string | null;
+    options: unknown;
 }
-/** The state every declaration starts from. The unnamed root and each named Command share it. */
-export declare function freshState<Globals>(name: string | null, globals: GlobalOptions<Globals> | undefined): CommandState<{}, {}, Globals>;
+/**
+ * The state every declaration starts from. The unnamed root and each named Command share it.
+ * The declaration values arrive captured, because a later change to the options object the author
+ * passed changes nothing the declaration holds.
+ */
+export declare function freshState<Globals>(declaration: {
+    deprecated: unknown;
+    description: unknown;
+    extensions: unknown;
+    globals: GlobalOptions<Globals> | undefined;
+    hidden: unknown;
+    name: string | null;
+    options: unknown;
+}): CommandState<{}, {}, Globals>;
 /** The declared value joins `args` under its literal name, typed by its own config. */
 export declare function declareArgument<Args, Options, Globals, Name extends string, Config extends ArgumentConfig>(state: CommandState<Args, Options, Globals>, input: ArgumentInput<Name, Config>): CommandState<Args & Record<Name, ArgumentValue<Config>>, Options, Globals>;
 /** The declared value joins `options` under its literal name, typed by its own config. */
@@ -115,11 +142,16 @@ export declare function declareAction<Args, Options, Globals>(state: CommandStat
 export declare function attachChild<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, child: object): CommandState<Args, Options, Globals>;
 /** Validates one declaration against the shared globals table and compiles it for dispatch. */
 export declare function buildCommand<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, context: BuildContext): BuiltCommand;
-/** The globals table and the owners record each compile once per invocation and the whole graph shares them. */
-export declare function buildGraph<Args, Options, Globals>(root: CommandState<Args, Options, Globals>): {
+/** One built graph: the shared globals table, the root Command, and the facts each node carries. */
+export interface BuiltGraph {
+    extensions: ExtensionRecords;
     globals: BuiltGlobals;
     root: BuiltCommand;
-};
+}
+/** The globals table and the owners record each compile once per invocation and the whole graph shares them. */
+export declare function buildGraph<Args, Options, Globals>(root: CommandState<Args, Options, Globals>, install: PluginBuild & {
+    plugins: readonly BuiltPlugin[];
+}): BuiltGraph;
 export declare class CommandBuilder<Args, Options, Globals, State extends CommandMethod = CommandMethod> {
     #private;
     readonly [commandValue]: true;
@@ -129,8 +161,8 @@ export declare class CommandBuilder<Args, Options, Globals, State extends Comman
     argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>>;
     option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args, Options & Record<Name, OptionValue<Config>>, Globals, State>;
     /**
-     * Hidden aliases are other bare tokens that route to this Command. They invalidate no call, and
-     * the tuple rest parameter rejects a call that names none.
+     * Aliases are other bare tokens that route to this Command. They invalidate no call, and the
+     * tuple rest parameter rejects a call that names none.
      */
     alias(...names: [string, ...string[]]): Command<Args, Options, Globals, State>;
     /** A child arrives in any type state, because its own action is the call that finished it. */
@@ -147,11 +179,22 @@ export declare class CommandBuilder<Args, Options, Globals, State extends Comman
  * calls, so `Command<A, O, G>` accepts a Command in any state, a finished one included.
  */
 export type Command<Args = {}, Options = {}, Globals = {}, State extends CommandMethod = AfterAction> = Pick<CommandBuilder<Args, Options, Globals, State>, typeof commandValue | typeof declaredTypes | State>;
+/**
+ * Everything a Command configures beside its declarations: the options value every Command in one
+ * application shares, and the core facts the declaration carries.
+ */
+export interface CommandOptions<Globals = {}> {
+    globals?: GlobalOptions<Globals>;
+    description?: string;
+    hidden?: boolean;
+    deprecated?: string;
+    extensions?: readonly ExtensionValue<'command'>[];
+}
 interface CommandConstructor {
     new (name: string): Command<{}, {}, {}, CommandMethod>;
-    new <Globals>(name: string, globals: GlobalOptions<Globals>): Command<{}, {}, Globals, CommandMethod>;
+    new <Globals = {}>(name: string, options: CommandOptions<Globals>): Command<{}, {}, Globals, CommandMethod>;
 }
-/** The public constructor requires a name and narrows the globals type to the supplied value. */
+/** The public constructor takes a name and one options object, as the Application does. */
 export declare const Command: CommandConstructor;
 /** Every declaration in the graph, so defaults are validated before any token is read. */
 export declare function collectInputs(command: BuiltCommand): InputDeclaration[];
@@ -161,16 +204,24 @@ export declare function route(root: BuiltCommand, tokens: readonly string[]): {
     path: string[];
     tokens: string[];
 };
-/** Consumes globals, routes to a Command, then validates globals and locals in one pass. */
-export declare function selectCommand(graph: {
-    globals: BuiltGlobals;
-    root: BuiltCommand;
-}, invocation: {
+/** One invocation after the pre-scan and routing, which the middleware chain runs on top of. */
+export interface RoutedInvocation {
+    command: BuiltCommand;
+    path: readonly string[];
+    scan: OptionValues;
+    tokens: readonly string[];
+}
+/** Consumes the globals table, then routes the remaining bare tokens to a Command. */
+export declare function routeInvocation(graph: BuiltGraph, argv: readonly string[]): RoutedInvocation;
+/**
+ * The phases the middleware chain terminates in: the callable check, local parsing, validation, and
+ * the action. It answers with the call that dispatches, so the caller records that the action was
+ * invoked at the moment it invokes it and no earlier failure reads as a dispatch.
+ */
+export declare function prepareDispatch(graph: BuiltGraph, routed: RoutedInvocation, invocation: {
     defaults: DefaultValues;
     host: Host;
-}): Promise<{
-    dispatch: (input: DispatchInput) => unknown;
-    passthrough: string[];
-    values: ValidatedInputs;
-}>;
+    out: Out;
+    signal: AbortSignal;
+}): Promise<() => unknown>;
 export {};