@loomcli/core 0.3.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drew Butler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/application.d.ts

@@ -1,12 +1,12 @@
-import type { AfterAction, AttachmentConstraint, AfterArgument, AfterCommand, AfterResult, Command, CommandMethod, CommandState, ResultMethod } from './command.js';
+import type { AfterAction, AttachmentConstraint, AfterArgument, AfterCommand, AfterResult, Command, CommandMethod, CommandNodeHandle, CommandState, ResultMethod } from './command.js';
 import type { ApplicationEnvironment, applicationEnvironment } from './environment.js';
 import type { ExtensionValue } from './extension.js';
 import type { GlobalsState } from './globals.js';
 import type { CommandGraph } from './inspect.js';
-import type { Plugin } from './plugin.js';
+import type { BuiltPlugin, Plugin } from './plugin.js';
 import type { RenderingPolicy } from './rendering.js';
-import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, MultipleConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, ResultViews, ResultViewsOf, RowViews, RunOptions, ValidateOmittedConstraint } from './types.js';
-import type { ViewOverride } from './view.js';
+import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, GlobalOmissionConstraint, PerValueConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, ResultViews, ResultViewsOf, RowViews, RunOptions, ValidateOmittedConstraint } from './types.js';
+import type { ViewContributions, ViewOverride } from './view.js';
 /**
  * Every authoring call an Application can publish, beside `run()` and `name`, which always remain.
  * An Application's type state is a subset of these, and each call removes the names it invalidates.
@@ -22,6 +22,23 @@ export interface ApplicationOptions<Plugins extends readonly Plugin[] = readonly
     description?: string;
     version?: string;
 }
+/**
+ * Everything an Application holds beside its root declaration and its globals, each part checked by
+ * the constructor or the call that set it.
+ */
+interface ApplicationConfig {
+    /** Whether the application's own `command()` or `action()` has run, which closes `globalOption()`. */
+    composed: boolean;
+    /** Each installed plugin's view contributions, in installation order. */
+    contributors: readonly ViewContributions[];
+    facts: ApplicationFacts;
+    /** The parent that claimed each node the graph holds, so one value attaches at one point. */
+    owners: ReadonlyMap<CommandNodeHandle, string | null>;
+    plugins: readonly BuiltPlugin[];
+    rendering: RenderingPolicy;
+    /** The application's own view overrides. */
+    views: ViewContributions;
+}
 /**
  * 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.
@@ -30,19 +47,17 @@ declare class ApplicationBuilder<Args, Options, Globals, State extends Applicati
     #private;
     readonly [applicationEnvironment]: ApplicationEnvironment<Globals, Plugins>;
     readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals, Result>;
-    constructor(name: string, root: CommandState<Args, Options, Globals>, config: {
-        declared: DeclaredFacts;
-        views: unknown;
-        options?: unknown;
-        plugins: Plugins | undefined;
+    constructor(name: string, declared: {
+        config: ApplicationConfig;
         globals: GlobalsState<Globals>;
+        root: CommandState<Args, Options, Globals>;
     });
     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>, Plugins, 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>>): Application<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Plugins, Result>;
+    argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>, Plugins, Result>;
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Plugins, Result>;
     globalOption<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & (Name extends keyof Options ? {
         'This option name is already declared as a local option': Name;
-    } : unknown) & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args, Options, Globals & Record<Name, OptionValue<Config>>, State, Plugins, Result>;
+    } : unknown) & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>> & NoInfer<GlobalOmissionConstraint<Config>>): Application<Args, Options, Globals & Record<Name, OptionValue<Config>>, State, Plugins, Result>;
     /** Registering the action closes input authoring; extension configuration remains available. */
     action(handler: Action<Args, Globals & Options, Result>): Application<Args, Options, Globals, AfterAction, Plugins, Result>;
     /** A child arrives in any type state, because its own action is the call that finished it. */
@@ -69,27 +84,26 @@ declare class ApplicationBuilder<Args, Options, Globals, State extends Applicati
         default?: string;
     }): Application<Args, Options, Globals, State, Plugins, Result>;
     extend(...values: readonly ExtensionValue<'command'>[]): Application<Args, Options, Globals, State, Plugins, Result>;
+    /** The globals table the root's options and every joining subtree meet. */
+    private table;
     /**
-     * Root declaration calls preserve the Application configuration. The next state
-     * travels through this call: each method names its transition in its return type, and the
-     * wrapper publishes the same runtime value in exactly that state.
+     * Root declaration calls preserve the Application configuration, with the parts a call changed.
+     * The next state travels through this call: each method names its transition in its return type,
+     * and the 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
-     * application's own view overrides, the options slot, the installed list, each plugin's
-     * declarations, then the whole Command graph. The application's overrides are read and published
-     * first, because they need core's identities and nothing else, so every later declaration error
-     * reaches them, while a fault in that list itself reports through core's own text. The merged
-     * registry is published once the whole build has succeeded, so a build-time fault never resolves
-     * through a plugin's overrides, which build has not yet validated.
+     * The graph build, which applies the rules no earlier moment could know: the root's
+     * finished-Command rules and every lifecycle hook's contribution. The application's own overrides
+     * are published first, so a build fault reports through them. The merged registry is published
+     * once the build has succeeded, so a build fault never resolves through a plugin's overrides.
      */
     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
-     * declared default through its schema can be asynchronous, so that one rule stays in `run()`.
-     * Nothing is cached: each call builds the graph anew.
+     * The built graph as plain, frozen data. It builds the graph as `run()` does and throws
+     * `DeclarationError` for the same build faults. Validating a declared default through its schema
+     * can be asynchronous, so that one rule stays in `run()`. Nothing is cached: each call builds the
+     * graph anew.
      */
     inspect(): CommandGraph;
     run(options?: RunOptions): Promise<ExitCode>;
@@ -107,11 +121,10 @@ interface ApplicationConstructor {
     new (name: string): Application<{}, {}, {}, ApplicationMethod, readonly []>;
     new <const Plugins extends readonly Plugin[] = readonly []>(name: string, options: ApplicationOptions<Plugins>): Application<{}, {}, {}, ApplicationMethod, Plugins>;
 }
-/** The same facts as the constructor captured them, before any rule has read them. */
-interface DeclaredFacts {
-    rendering: unknown;
-    description: unknown;
-    version: unknown;
+/** The core facts one Application declares, validated at construction and reported by `inspect()`. */
+interface ApplicationFacts {
+    description: string | undefined;
+    version: string;
 }
 export declare const Application: ApplicationConstructor;
 export {};

package/dist/application.js

@@ -1,13 +1,14 @@
 import { runInvocation } from './chain.js';
-import { attachChild, buildGraph, collectInputs, declareAction, declareExtensions, declareArgument, declareOption, declareResult, declareResultViews, freshState, recordGlobalOption, } from './command.js';
+import { attachToRoot, childNode, buildGraph, checkDeclaredOptions, collectInputs, declareAction, declareExtensions, declareArgument, declareOption, declareResult, declareResultViews, freshState, isPortableName, layerOf, portableNameCorrection, } from './command.js';
 import { DeclarationError, InternalError, reasonOf, toFailure } from './errors.js';
+import { storeCommandLayers } from './extension.js';
 import { checkDescription, checkNoListingFacts, checkVersion, isPlainObject } from './facts.js';
-import { declareGlobalOption, emptyGlobals } from './globals.js';
+import { declareGlobalOption, emptyGlobals, globalTable } from './globals.js';
 import { captureHost } from './host.js';
 import { inspectGraph } from './inspect.js';
 import { coreViews } from './lanes.js';
 import { Output, reportPlainly } from './output.js';
-import { buildPlugins, installPlugins, ownedSignals, pluginSentence } from './plugin.js';
+import { installPlugins, ownedSignals, pluginSentence } from './plugin.js';
 import { renderingPolicy } from './rendering.js';
 import { bracketRun, cancellationCode, isCancellationEcho } from './signals.js';
 import { captureConfig, checkDeclarations, prepareInputs } from './validation.js';
@@ -64,24 +65,13 @@ function checkSignal(signal) {
 class ApplicationBuilder {
     #name;
     #root;
-    // The override list the constructor read out of the options slot, unexamined until build.
-    #views;
-    #plugins;
     #globals;
-    // 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.#views = config.views;
+    #config;
+    constructor(name, declared) {
         this.#name = name;
-        this.#options = config.options;
-        this.#plugins = config.plugins;
-        this.#globals = config.globals;
-        this.#root = root;
+        this.#config = declared.config;
+        this.#globals = declared.globals;
+        this.#root = declared.root;
     }
     get name() {
         return this.#name;
@@ -100,29 +90,38 @@ class ApplicationBuilder {
             kind: 'option',
             name,
         };
-        return this.derive(declareOption(this.#root, input));
+        return this.derive(declareOption(this.#root, input, this.table()));
     }
     globalOption(name, config) {
+        // The plugins' Commands attach at construction, so only the application's own calls close it.
+        if (this.#config.composed) {
+            throw new DeclarationError(`The Application declares global option "${name}" after command() or action(). Declare global options before attaching Commands or registering an action.`);
+        }
         const input = {
             config: captureConfig(config),
             kind: 'option',
             name,
         };
-        return new ApplicationBuilder(this.#name, recordGlobalOption(this.#root, name), {
-            declared: this.#declared,
-            globals: declareGlobalOption(this.#globals, input),
-            options: this.#options,
-            plugins: this.#plugins,
-            views: this.#views,
-        });
+        const descriptors = new Map(this.#root.descriptors);
+        const globals = declareGlobalOption(this.#globals, input, descriptors);
+        const root = { ...this.#root, descriptors };
+        checkDeclaredOptions(root, globalTable(globals.inputs, this.#config.plugins));
+        checkDeclarations([input]);
+        return new ApplicationBuilder(this.#name, { config: this.#config, globals, root });
     }
     /** Registering the action closes input authoring; extension configuration remains available. */
     action(handler) {
-        return this.derive(declareAction(this.#root, handler));
+        return this.derive(declareAction(this.#root, handler), { composed: true });
     }
     /** A child arrives in any type state, because its own action is the call that finished it. */
     command(child) {
-        return this.derive(attachChild(this.#root, child));
+        const scope = {
+            descriptors: new Map(this.#root.descriptors),
+            owners: new Map(this.#config.owners),
+            table: this.table(),
+        };
+        const root = attachToRoot(this.#root, childNode(null, child), scope);
+        return this.derive(root, { composed: true, owners: scope.owners });
     }
     /**
      * The value the root action produces for its consumer. The type argument is stated by the
@@ -142,50 +141,38 @@ class ApplicationBuilder {
     extend(...values) {
         return this.derive(declareExtensions(this.#root, values));
     }
+    /** The globals table the root's options and every joining subtree meet. */
+    table() {
+        return globalTable(this.#globals.inputs, this.#config.plugins);
+    }
     /**
-     * Root declaration calls preserve the Application configuration. The next state
-     * travels through this call: each method names its transition in its return type, and the
-     * wrapper publishes the same runtime value in exactly that state.
+     * Root declaration calls preserve the Application configuration, with the parts a call changed.
+     * The next state travels through this call: each method names its transition in its return type,
+     * and the wrapper publishes the same runtime value in exactly that state.
      */
-    derive(root) {
-        return new ApplicationBuilder(this.#name, root, {
-            declared: this.#declared,
-            globals: this.#globals,
-            options: this.#options,
-            plugins: this.#plugins,
-            views: this.#views,
-        });
+    derive(root, changed = {}) {
+        return new ApplicationBuilder(this.#name, { config: { ...this.#config, ...changed }, globals: this.#globals, root });
     }
     /**
-     * Every rule that reads the declarations alone, in the order `run()` reads them: the
-     * application's own view overrides, the options slot, the installed list, each plugin's
-     * declarations, then the whole Command graph. The application's overrides are read and published
-     * first, because they need core's identities and nothing else, so every later declaration error
-     * reaches them, while a fault in that list itself reports through core's own text. The merged
-     * registry is published once the whole build has succeeded, so a build-time fault never resolves
-     * through a plugin's overrides, which build has not yet validated.
+     * The graph build, which applies the rules no earlier moment could know: the root's
+     * finished-Command rules and every lifecycle hook's contribution. The application's own overrides
+     * are published first, so a build fault reports through them. The merged registry is published
+     * once the build has succeeded, so a build fault never resolves through a plugin's overrides.
      */
     prepare(stage) {
-        const identities = viewIdentities(coreViews);
-        const application = buildViews({ declares: false, sentence: 'The Application' }, this.#views, identities);
-        stage.views([application]);
-        stage.rendering(renderingPolicy(this.#declared.rendering));
-        const facts = checkOptions(this.#options, this.#declared);
-        const installed = installPlugins(this.#plugins ?? []);
-        const install = { descriptors: new Map(), extensions: new Map() };
-        const plugins = buildPlugins(installed, install);
+        const { contributors, facts, plugins, rendering, views } = this.#config;
+        stage.views([views]);
+        stage.rendering(rendering);
         stage.plugins(plugins);
-        const contributors = plugins.map((entry) => buildViews({ declares: true, sentence: pluginSentence(entry.identity) }, entry.views, identities));
-        const graph = buildGraph(this.#root, this.#globals, { ...install, plugins });
-        checkDeclarations([...graph.globals.inputs, ...collectInputs(graph.root)]);
-        stage.views([application, ...contributors]);
+        const graph = buildGraph(this.#root, this.#globals, plugins);
+        stage.views([views, ...contributors]);
         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
-     * declared default through its schema can be asynchronous, so that one rule stays in `run()`.
-     * Nothing is cached: each call builds the graph anew.
+     * The built graph as plain, frozen data. It builds the graph as `run()` does and throws
+     * `DeclarationError` for the same build faults. Validating a declared default through its schema
+     * can be asynchronous, so that one rule stays in `run()`. Nothing is cached: each call builds the
+     * graph anew.
      */
     inspect() {
         const built = this.prepare({
@@ -231,8 +218,7 @@ class ApplicationBuilder {
                 const host = captureHost(overrides, stderr);
                 const invocationOutput = new Output(host, controller.signal);
                 output = invocationOutput;
-                // The policy is read inside the build, after the application's own overrides are published.
-                // A faulty rendering declaration then reports through the view the application listed.
+                // The constructor validated the declared policy, which the build hands over after the overrides.
                 let policy = {};
                 signals = bracketRun(controller, checkSignal(options?.signal));
                 const built = this.prepare({
@@ -272,6 +258,7 @@ class ApplicationBuilder {
                             invocationOutput.useRoute(path);
                         },
                         signal: controller.signal,
+                        sourceOut: output.sourceOut,
                         style: output.style,
                     });
                 }
@@ -366,58 +353,83 @@ class ApplicationBuilder {
     }
 }
 /** Reject obsolete wiring before silently losing options that invocations depend on. */
-function checkOptions(options, declared) {
-    if (options !== undefined) {
-        if (!isPlainObject(options)) {
-            throw new DeclarationError('The Application options must be an object. Supply an Application options object.');
-        }
-        if ('globals' in options) {
-            throw new DeclarationError('The Application options contain globals. Declare them with globalOption(name, config).');
-        }
-        if ('failures' in options) {
-            throw new DeclarationError('The Application options contain failures. Declare view overrides under views with override(key, view).');
-        }
-        // 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);
+function checkOptions(options) {
+    if (options === undefined) {
+        return { description: undefined, version: checkVersion(undefined) };
+    }
+    if (!isPlainObject(options)) {
+        throw new DeclarationError('The Application options must be an object. Supply an Application options object.');
+    }
+    if ('globals' in options) {
+        throw new DeclarationError('The Application options contain globals. Declare them with globalOption(name, config).');
+    }
+    if ('failures' in options) {
+        throw new DeclarationError('The Application options contain failures. Declare view overrides under views with override(key, view).');
     }
+    // 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),
+        description: checkDescription('The Application', options.description),
+        version: checkVersion(options.version),
     };
 }
+/**
+ * Every rule `new Application(name, options)` applies, in the order it reads the slot: the
+ * application's own view overrides, the rendering policy, the options slot and its facts, the
+ * installed list and every rule between two plugins, the root's extension values, and then each
+ * plugin's Commands, which attach to the root first, in installation order and list order.
+ */
+function declareApplication(options) {
+    const slot = isPlainObject(options) ? options : undefined;
+    const identities = viewIdentities(coreViews);
+    const views = buildViews({ declares: false, sentence: 'The Application' }, slot?.views, identities);
+    const rendering = renderingPolicy(slot?.rendering);
+    const facts = checkOptions(options);
+    const installed = installPlugins(slot?.plugins ?? []);
+    const { plugins } = installed;
+    const contributors = plugins.map((entry) => buildViews({ declares: true, sentence: pluginSentence(entry.identity) }, entry.views, identities));
+    const table = globalTable([], plugins);
+    const descriptors = installed.descriptors;
+    const extensions = storeCommandLayers({
+        descriptors,
+        layers: [slot?.extensions],
+        subject: layerOf(null),
+    });
+    // The Application checks its own facts, so the root carries none.
+    // Its diagnostics name the Application rather than the root Command.
+    let root = freshState({
+        descriptors,
+        extensions,
+        facts: { deprecated: undefined, description: undefined, hidden: false },
+        name: null,
+    });
+    const owners = new Map();
+    for (const command of plugins.flatMap((entry) => entry.commands)) {
+        root = attachToRoot(root, command.node, {
+            descriptors: new Map(root.descriptors),
+            owners,
+            table,
+        });
+    }
+    return {
+        config: { composed: false, contributors, facts, owners, plugins, rendering, views },
+        globals: emptyGlobals(),
+        root,
+    };
+}
+/** The application name is typed as a command at the prompt, so it answers to the portable rule. */
+function checkApplicationName(name) {
+    if (!isPortableName(name)) {
+        throw new DeclarationError(`Application name "${String(name)}" is invalid. ${portableNameCorrection}`);
+    }
+    return name;
+}
 /** Constructor inference preserves the installed plugin tuple; globals start empty. */
 class ApplicationDeclaration extends ApplicationBuilder {
     constructor(name, options) {
-        // The options slot is read defensively, never inspected.
-        // An invalid value still yields `views` and the facts of some kind.
-        // `checkOptions` reports such a value 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,
-            hidden: undefined,
-            name: null,
-            options: undefined,
-        }), {
-            declared: {
-                description: options?.description,
-                rendering: isPlainObject(options?.rendering)
-                    ? { ...options.rendering }
-                    : options?.rendering,
-                version: options?.version,
-            },
-            globals: emptyGlobals(),
-            options,
-            plugins: options?.plugins,
-            // The read is loose because the slot is reachable from JavaScript with any value at all.
-            // An Application value passed here answers `views` with its own authoring method.
-            // The public `ApplicationOptions.views` stays exactly `readonly ViewOverride[]`.
-            // An options slot that is no plain object carries no override list, and its own rule reports it.
-            views: isPlainObject(options) ? options.views : undefined,
-        });
+        // The arguments evaluate in order, so the name is checked before any option is read.
+        super(checkApplicationName(name), declareApplication(options));
     }
 }
 export const Application = ApplicationDeclaration;

package/dist/bindings.d.ts

@@ -0,0 +1,26 @@
+/** The two keys the binding rules read, whichever scope declared the option. */
+interface BindingConfig {
+    readonly env?: unknown;
+    readonly multiple?: unknown;
+}
+/**
+ * The environment binding one option declares, or `undefined` when it declares none. A multiple
+ * option takes its list from the configuration source, so it cannot bind, and a bound name must be
+ * a variable name. `sentence` names the declaration at the start of the diagnostic.
+ */
+export declare function checkEnvBinding(sentence: string, config: BindingConfig): string | undefined;
+/** An argument is identified by its place among bare tokens, so no variable can stand in for it. */
+export declare function checkNoArgumentBinding(sentence: string, config: object): void;
+/** One option bound to a variable, with the phrase a duplicate-variable diagnostic names it by. */
+export interface BoundOption {
+    readonly site: string;
+    readonly variable: string;
+}
+/**
+ * The variables one scope binds, each to the phrase of the option that binds it. Within one
+ * invocation's scope a variable binds one option, so a second binder is a declaration error that
+ * names the first binder, in scope order, and then the second. `held` is what an enclosing scope
+ * already binds, such as the globals table under a Command's own options.
+ */
+export declare function claimVariables(bound: readonly BoundOption[], held?: ReadonlyMap<string, string>): ReadonlyMap<string, string>;
+export {};

package/dist/bindings.js

@@ -0,0 +1,45 @@
+import { DeclarationError } from './errors.js';
+/** A variable name: a letter or an underscore, then letters, digits, or underscores. */
+const variableName = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/**
+ * The environment binding one option declares, or `undefined` when it declares none. A multiple
+ * option takes its list from the configuration source, so it cannot bind, and a bound name must be
+ * a variable name. `sentence` names the declaration at the start of the diagnostic.
+ */
+export function checkEnvBinding(sentence, config) {
+    const env = config.env;
+    if (env === undefined) {
+        return undefined;
+    }
+    if (config.multiple === true) {
+        throw new DeclarationError(`${sentence} is a multiple option and declares env. Remove env; a list comes from the configuration source.`);
+    }
+    if (typeof env !== 'string' || !variableName.test(env)) {
+        const quoted = typeof env === 'string' ? ` "${env}"` : '';
+        throw new DeclarationError(`${sentence} env${quoted} is not a variable name. Use a letter or an underscore, then letters, digits, or underscores.`);
+    }
+    return env;
+}
+/** An argument is identified by its place among bare tokens, so no variable can stand in for it. */
+export function checkNoArgumentBinding(sentence, config) {
+    if ('env' in config) {
+        throw new DeclarationError(`${sentence} declares env, which applies to options alone. Remove it.`);
+    }
+}
+/**
+ * The variables one scope binds, each to the phrase of the option that binds it. Within one
+ * invocation's scope a variable binds one option, so a second binder is a declaration error that
+ * names the first binder, in scope order, and then the second. `held` is what an enclosing scope
+ * already binds, such as the globals table under a Command's own options.
+ */
+export function claimVariables(bound, held = new Map()) {
+    const claimed = new Map(held);
+    for (const { site, variable } of bound) {
+        const owner = claimed.get(variable);
+        if (owner !== undefined) {
+            throw new DeclarationError(`Variable "${variable}" is bound by ${owner} and ${site}. Bind each variable to one option.`);
+        }
+        claimed.set(variable, site);
+    }
+    return claimed;
+}

package/dist/chain.d.ts

@@ -1,7 +1,7 @@
 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 { BuiltPlugin, PluginOptions, PluginOptionSpellings, PluginOptionValues } from './plugin.js';
 import type { ContextualStyle } from './style.js';
 import type { ActionChannel, Host, OpenResult, Out, Request, ResultBinding } from './types.js';
 import type { DefaultValues } from './validation.js';
@@ -13,14 +13,17 @@ 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. `request` is the routed Command's
- * invocation, parsed and validated ahead of the chain, and `null` while core holds a fault and on a
- * group. `view` names the view the result renders through: it reads as the declaration's default
- * until a middleware assigns one, and as `null` on a Command that declares none. The last
- * assignment before the dispatch boundary wins, and one made after it changes nothing.
+ * and never another plugin's or the application's globals, and `spellings` holds the spelling that
+ * supplied each of them as a token, which a filled or defaulted option never has. `request` is the
+ * routed Command's invocation, parsed and validated ahead of the chain, and `null` while core holds
+ * a fault and on a group. `view` names the view the result renders through: it reads as the
+ * declaration's default until a middleware assigns one, and as `null` on a Command that declares
+ * none. The last assignment before the dispatch boundary wins, and one made after it changes
+ * nothing.
  */
 interface MiddlewareContext<Options extends PluginOptions = PluginOptions> {
     readonly options: PluginOptionValues<Options>;
+    readonly spellings: PluginOptionSpellings<Options>;
     readonly graph: CommandGraph;
     readonly command: CommandNode;
     readonly request: Request | null;
@@ -49,6 +52,8 @@ interface Invocation {
      * receives the channel the results lane builds for the Command that was routed.
      */
     out: Out<OpenResult>;
+    /** The channel a configuration source receives, whose results call names the source. */
+    sourceOut: Out<OpenResult>;
     plugins: readonly BuiltPlugin[];
     /** A fault reported after the primary outcome, which turns a would-be 0 into 1. */
     report: (fault: LoomError) => void;