@loomcli/core 0.1.1 → 0.3.0

package/dist/command.d.ts

@@ -1,6 +1,11 @@
-import type { BuiltGlobals, GlobalOptions } from './globals.js';
+import type { RegisteredGlobals } from './environment.js';
+import type { DescriptorRegistry, ExtensionRecords, ExtensionValue } from './extension.js';
+import type { BuiltGlobals, GlobalsState } from './globals.js';
 import { compileOptions } from './options.js';
-import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, Host, MultipleConstraint, NameConstraint, OptionConfig, OptionValue, Out, ValidateOmittedConstraint } from './types.js';
+import type { OptionValues } from './options.js';
+import type { BuiltPlugin, PluginBuild } from './plugin.js';
+import type { ContextualStyle } from './style.js';
+import type { Action, ActionChannel, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredResult, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, Host, MultipleConstraint, NameConstraint, OpenResult, OptionConfig, OptionValue, Out, Request, ResultBinding, ResultViews, ResultViewsOf, RowViews, 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. */
 export interface ArgumentSlot {
@@ -9,13 +14,16 @@ export interface ArgumentSlot {
     variadic: boolean;
 }
 export interface DispatchInput {
+    style: ContextualStyle;
     host: Host;
-    out: Out;
+    /** The action's channel, whose `results` accepts whatever the routed declaration named. */
+    out: Out<OpenResult>;
     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,39 +34,53 @@ 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>;
+    /** The result the Command declares, or nothing where it declares none. */
+    /** The built declaration is the shape the write site reads, so the channel carries it. */
+    result: DeclaredResult | undefined;
     routes: ReadonlyMap<string, RoutedChild>;
 }
 /** Phantom key. It marks a Command value, so only a Command can be attached as a child. */
 export declare const commandValue: unique symbol;
 /**
- * Every authoring call a Command can publish. A Command's type state is a subset of these names,
+ * The input, alias, child, and action calls a Command can publish. Its type state is a subset,
  * and each call removes the names it invalidates. A Command attaches children at any depth, so
  * `command()` belongs to every Command and to the unnamed root alike.
  */
-export type CommandMethod = 'action' | 'alias' | 'argument' | 'command' | 'option';
+export type CommandMethod = 'action' | 'alias' | 'argument' | 'command' | 'option' | 'result' | 'rows';
 /** One Command declares arguments or attaches children, so the first call removes the other. */
 export type AfterArgument<State> = Exclude<State, 'command'>;
 /** The same rule read from the other side. */
 export type AfterCommand<State> = Exclude<State, 'argument'>;
-/** The action is the last declaration call, so no declaration call survives it. */
+/** One Command declares one result, so either call removes both. */
+export type AfterResult<State> = Exclude<State, 'result' | 'rows'>;
+/** Registering the action closes input, alias, child, and further action declarations. */
 export type AfterAction = never;
-/** A declaration made after the action, kept in authoring order so build reports the first. */
+/** A declaration made after its authoring phase closed; build reports the first in call order. */
 type LateDeclaration = {
     alias: string;
     kind: 'alias';
+} | {
+    name: string;
+    kind: 'global';
 } | {
     child: object;
     kind: 'child';
+} | {
+    kind: 'result';
 } | {
     input: InputDeclaration;
     kind: 'input';
@@ -68,8 +90,8 @@ type LateDeclaration = {
  * which the types reject and a JavaScript author can still write, reports as the call it is.
  */
 type AliasDeclaration = readonly string[];
-/** The attachable shape of a Command, without its inferred declaration types. */
-interface AttachedCommand {
+/** The private handle one graph node is built through, without its inferred declaration types. */
+interface CommandNodeHandle {
     readonly name: string | null;
     build(context: BuildContext): BuiltCommand;
 }
@@ -81,63 +103,149 @@ 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>;
+    owners: Map<CommandNodeHandle, string | null>;
+    /** The route from the root to the Command being built, which a lifecycle hook reads. */
+    path: readonly string[];
+    /** The installed plugins in installation order, whose hooks run over every Command. */
+    plugins: readonly BuiltPlugin[];
 }
 /**
  * Everything one Command declaration holds. The transitions below copy it with fields replaced, and
  * the Command and Application builders share them, so one declaration call has one implementation.
- * Absent globals stay `undefined`, so every declaration without globals agrees on identity.
  */
+/**
+ * One call of the results lane, in the order it was made. A `result()` or `rows()` call declares
+ * the unit, and a `views()` call reshapes the views of whichever declaration it follows.
+ * Each record arrives unexamined, because build owns every rule the lane carries.
+ */
+export type ResultCall = {
+    kind: 'value' | 'rows';
+    views: unknown;
+} | {
+    default: unknown;
+    kind: 'views';
+    views: unknown;
+};
 export interface CommandState<Args, Options, Globals> {
-    actions: readonly Action<Args, Globals & Options>[];
+    /**
+     * The registered actions, with the declared result erased. An action is stored under the widest
+     * result, so a handler typed from its own declaration stores here and the channel that carries
+     * the result is built for it at dispatch.
+     */
+    actions: readonly Action<Args, Globals & Options, OpenResult>[];
     aliases: readonly AliasDeclaration[];
     bind: (values: ValidatedInputs) => {
         args: Args;
         options: Options;
     };
     children: readonly object[];
-    globals: GlobalOptions<Globals> | undefined;
+    deprecated: unknown;
+    description: unknown;
+    extensions: readonly unknown[];
+    hidden: unknown;
     inputs: readonly InputDeclaration[];
     late: readonly LateDeclaration[];
     name: string | null;
+    options: unknown;
+    results: readonly ResultCall[];
 }
-/** 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;
+    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. */
 export declare function declareOption<Args, Options, Globals, Name extends string, Config extends OptionConfig>(state: CommandState<Args, Options, Globals>, input: OptionInput<Name, Config>): CommandState<Args, Options & Record<Name, OptionValue<Config>>, Globals>;
+/** Globals close when composition starts; retain late calls for the shared build-order check. */
+export declare function recordGlobalOption<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, name: string): CommandState<Args, Options, Globals>;
 /** One call's names stay one group, so the empty call the types reject still reports as one. */
 export declare function declareAlias<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, names: AliasDeclaration): CommandState<Args, Options, Globals>;
-export declare function declareAction<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, handler: Action<Args, Globals & Options>): CommandState<Args, Options, Globals>;
+/** Extension layers remain open after inputs and the action have been fixed. */
+export declare function declareExtensions<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, values: readonly ExtensionValue<'command'>[]): CommandState<Args, Options, Globals>;
+/**
+ * The handler is typed against the result its own declaration carries, and the state holds one
+ * list for every declaration, so the context each handler receives is read back at the call.
+ */
+export declare function declareAction<Args, Options, Globals, Result>(state: CommandState<Args, Options, Globals>, handler: Action<Args, Globals & Options, Result>): CommandState<Args, Options, Globals>;
+/** The result declaration, which closes both result calls and reports lateness like the rest. */
+export declare function declareResult<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, kind: 'value' | 'rows', declaration: unknown): CommandState<Args, Options, Globals>;
+/** A `views()` call reshapes views and closes nothing, so it is never a late declaration. */
+export declare function declareResultViews<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, replacements: unknown, options: unknown): CommandState<Args, Options, Globals>;
 /** Attaching is a declaration call too, so the receiver keeps the children it already had. */
 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;
-};
-export declare class CommandBuilder<Args, Options, Globals, State extends CommandMethod = CommandMethod> {
+}
+/** 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>, globals: GlobalsState<Globals>, install: PluginBuild & {
+    plugins: readonly BuiltPlugin[];
+}): BuiltGraph;
+export declare class CommandBuilder<Args, Options, Globals, State extends CommandMethod = CommandMethod, Result = unknown> {
     #private;
     readonly [commandValue]: true;
-    readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals>;
+    readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals, Result>;
     constructor(state: CommandState<Args, Options, Globals>);
     get name(): string | null;
-    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>;
+    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>, Result>;
+    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, Result>;
     /**
-     * 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>;
+    alias(...names: [string, ...string[]]): Command<Args, Options, Globals, State, Result>;
     /** A child arrives in any type state, because its own action is the call that finished it. */
-    command(child: Command<unknown, unknown, Globals>): Command<Args, Options, Globals, AfterCommand<State>>;
-    /** The action is the last declaration call, so the value it returns publishes `AfterAction`. */
-    action(handler: Action<Args, Globals & Options>): Command<Args, Options, Globals>;
+    command<const Child extends Command<unknown, unknown, Globals>>(child: Child & NoInfer<AttachmentConstraint<Globals, Child>>): Command<Args, Options, Globals, AfterCommand<State>, Result>;
+    /**
+     * The value this Command produces for its consumer. The type argument is stated by the author,
+     * so the views record states no type of its own and an omitted argument names none either.
+     */
+    result<Value>(declaration: {
+        views: ResultViews<NoInfer<Value>>;
+    }): Command<Args, Options, Globals, AfterResult<State>, {
+        kind: 'value';
+        value: Value;
+    }>;
+    /** The same declaration over a sequence, whose type argument is one row. */
+    rows<Row>(declaration: {
+        views: RowViews<NoInfer<Row>>;
+    }): Command<Args, Options, Globals, AfterResult<State>, {
+        kind: 'rows';
+        row: Row;
+    }>;
+    /**
+     * Views after the fact. It merges by key, so an existing name is replaced in place and a new one
+     * is appended, and `default` names the key core renders when nothing selects another.
+     */
+    views(replacements: ResultViewsOf<Result>, options?: {
+        default?: string;
+    }): Command<Args, Options, Globals, State, Result>;
+    /** The action closes input authoring; `extend()` remains outside this state transition. */
+    action(handler: Action<Args, Globals & Options, Result>): Command<Args, Options, Globals, AfterAction, Result>;
+    extend(...values: readonly ExtensionValue<'command'>[]): Command<Args, Options, Globals, State, Result>;
     build(context: BuildContext): BuiltCommand;
+    /**
+     * The same runtime value in the state the calling method's return type names. Each call states
+     * its own transition, and the declared result travels with it unless the call replaces it.
+     */
+    private derive;
 }
 /**
  * The authoring surface of a Command in one type state. Every call returns a new declaration value,
@@ -146,12 +254,31 @@ export declare class CommandBuilder<Args, Options, Globals, State extends Comman
  * calls a value still offers. It defaults to the state after `action()`, which publishes the fewest
  * 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>;
-interface CommandConstructor {
-    new (name: string): Command<{}, {}, {}, CommandMethod>;
-    new <Globals>(name: string, globals: GlobalOptions<Globals>): Command<{}, {}, Globals, CommandMethod>;
+export type Command<Args = {}, Options = {}, Globals = {}, State extends CommandMethod = AfterAction, Result = unknown> = Pick<CommandBuilder<Args, Options, Globals, State, Result>, typeof commandValue | typeof declaredTypes | 'extend' | State | ResultMethod<Result>>;
+/**
+ * `views()` is published in every state on a declaration that carries a result, and on none that
+ * carries none. It is a key of the picked surface rather than a member of the state union, because
+ * the state union answers the calls a declaration closes and this one closes nothing.
+ */
+export type ResultMethod<Result> = unknown extends Result ? never : 'views';
+/**
+ * The core facts and initial extension values a named Command carries.
+ */
+export interface CommandOptions {
+    description?: string;
+    hidden?: boolean;
+    deprecated?: string;
+    extensions?: readonly ExtensionValue<'command'>[];
 }
-/** The public constructor requires a name and narrows the globals type to the supplied value. */
+/** Collect every union member's known local keys before testing for a global collision. */
+type LocalKeys<Child> = Child extends {
+    readonly [declaredTypes]: {
+        options: infer Options;
+    };
+} ? keyof Options : never;
+export type AttachmentConstraint<Globals, Child> = Extract<keyof Globals, LocalKeys<Child>> extends never ? unknown : never;
+type CommandConstructor = new (name: string, options?: CommandOptions) => Command<{}, {}, RegisteredGlobals, CommandMethod>;
+/** 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 +288,44 @@ 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;
+/** What one invocation reaches the middleware chain with. */
+export interface DispatchInvocation {
+    /** The channel the action receives, which the results lane builds from the routed node. */
+    channel: (binding: ResultBinding) => ActionChannel;
     defaults: DefaultValues;
     host: Host;
-}): Promise<{
-    dispatch: (input: DispatchInput) => unknown;
-    passthrough: string[];
-    values: ValidatedInputs;
-}>;
+    signal: AbortSignal;
+    style: ContextualStyle;
+}
+/**
+ * One invocation prepared ahead of the middleware chain. `'ready'` carries the request a middleware
+ * reads and the call that dispatches; `'held'` carries the fault this phase found, which core
+ * raises at the dispatch boundary and never before, so a takeover swallows it. `result` is what the
+ * routed Command declared, whose views a middleware selects among, on either shape.
+ */
+export type Prepared = {
+    result: DeclaredResult | undefined;
+} & ({
+    dispatch: (view: string | null) => Promise<void>;
+    kind: 'ready';
+    request: Request;
+} | {
+    fault: unknown;
+    kind: 'held';
+    request: null;
+});
+/**
+ * Prepares one dispatch ahead of the middleware chain and holds whatever fault it found, so a
+ * middleware reads the request before the action runs and a takeover never observes the fault.
+ */
+export declare function prepareDispatch(graph: BuiltGraph, routed: RoutedInvocation, invocation: DispatchInvocation): Promise<Prepared>;
 export {};