@loomcli/core 0.4.0 → 0.5.0

package/dist/plugin.d.ts

@@ -1,46 +1,34 @@
 import type { MiddlewareContext } from './chain.js';
-import type { AnyExtension, DescriptorRegistry, ExtensionRecords } from './extension.js';
+import type { AttachedChild, Command } from './command.js';
+import type { AnyExtension, DescriptorRegistry } from './extension.js';
+import type { InputRecords } from './globals.js';
+import type { CommandGraph, OptionNode } from './inspect.js';
+import type { OptionValues } from './options.js';
 import type { ProcessSignal } from './signals.js';
 import type { Palette } from './style-state.js';
-import type { ThemeConstraint, ThemeMapping } from './style.js';
-import type { CommandAttachHook, OptionValue, PluginOptionConfig } from './types.js';
+import type { ContextualStyle, ThemeConstraint, ThemeMapping } from './style.js';
+import type { CommandAttachHook, Host, OptionValue, Out, PluginOptionConfig } from './types.js';
 import type { OptionInput } from './validation.js';
 import type { ViewContribution } from './view.js';
 /**
  * The declaration record a plugin contributes its options under: the parsing part of an option
  * config, keyed by option name. A plugin option carries no schema and no presence rule, so the
- * config type publishes neither, and build repeats the rule for a JavaScript author.
+ * config type publishes neither, and `plugin()` repeats the rule for a JavaScript author.
  */
 type PluginOptions = Readonly<Record<string, PluginOptionConfig>>;
 /** The values one plugin's own options take, read through the same rules an action's options are. */
 type PluginOptionValues<Options extends PluginOptions> = {
     readonly [Name in keyof Options]: OptionValue<Options[Name]>;
 };
+/**
+ * The spelling that supplied each of one plugin's own options given as a token, such as `-h`,
+ * `--help`, or `--no-total`. An option filled by an input source, defaulted, or not supplied has
+ * no entry.
+ */
+type PluginOptionSpellings<Options extends PluginOptions> = Readonly<Partial<Record<keyof Options & string, string>>>;
 /** Phantom key. It carries a plugin's declared options in a read position and holds no value. */
 declare const pluginOptions: unique symbol;
 declare const pluginTheme: unique symbol;
-/**
- * One plugin's declarations as the registry holds them, with the generic parts erased. Build reads
- * every one of them defensively, because a JavaScript author reaches the same slots, so the erased
- * shape is what the rules below read and no declaration is claimed to be well formed here.
- */
-interface DeclaredPlugin {
-    theme?: unknown;
-    options?: PluginOptions;
-    middleware?: {
-        activate?: unknown;
-        load?: unknown;
-    };
-    onCommandAttach?: unknown;
-    extensions?: readonly AnyExtension[];
-    views?: unknown;
-    signals?: unknown;
-}
-/** The declarations behind one plugin value, read by this package alone. */
-interface PluginNode {
-    definition: DeclaredPlugin;
-    identity: unknown;
-}
 /**
  * The runtime value `plugin()` returns. `Options` appears in a read position alone, which makes it
  * covariant: a `plugins` list holds plugins with different options the way `views` holds
@@ -49,7 +37,7 @@ interface PluginNode {
 declare class PluginDeclaration<Options extends PluginOptions, Theme extends ThemeMapping> {
     readonly [pluginTheme]: Theme;
     readonly [pluginOptions]: () => Options;
-    constructor(node: PluginNode);
+    constructor(node: BuiltPlugin);
 }
 /**
  * One plugin, as the opaque value `plugin()` returns. The declarations behind it stay private to
@@ -61,8 +49,38 @@ type OptionsOf<Contributor> = Contributor extends Plugin<infer Options> ? Option
 /** A middleware reads its own plugin's options and either takes over or continues the chain. */
 type Middleware<Contributor extends Plugin | ((...args: never[]) => Plugin)> = (context: MiddlewareContext<OptionsOf<Contributor>>) => Promise<void> | void;
 /**
- * Everything a plugin declares. Creating and installing the value runs none of its code: a hook
- * runs at graph build, and the middleware runs inside an invocation.
+ * What a configuration source receives: the host, its own plugin's option values, resolved from
+ * argv, the environment, and their defaults, the `OptionNode` of every option core asks about, and
+ * the ordinary channels a middleware and an action already read. Each request is a node inside
+ * `graph`, the graph `inspect()` returns for the run. `out` is the channel a middleware receives,
+ * and `style` the contextual style an action receives, so a source warns and escapes as they do.
+ */
+interface SourceContext<Options extends PluginOptions = PluginOptions> {
+    readonly host: Host;
+    readonly options: PluginOptionValues<Options>;
+    readonly requests: readonly OptionNode[];
+    readonly graph: CommandGraph;
+    readonly out: Out;
+    readonly style: ContextualStyle;
+}
+/**
+ * One answer: a value of the option's raw type, a string, a Boolean, or a list of strings for a
+ * multiple option, and the one-line label core prints in a diagnostic about the value.
+ */
+interface SourceAnswer {
+    readonly value: string | boolean | readonly string[];
+    readonly label: string;
+}
+/**
+ * A configuration source answers the requested options by declared name. A requested option with
+ * no key in the record has no answer and falls through to its default.
+ */
+type SourceResolver<Contributor extends Plugin | ((...args: never[]) => Plugin)> = (context: SourceContext<OptionsOf<Contributor>>) => Promise<Readonly<Record<string, SourceAnswer>>>;
+/**
+ * Everything a plugin declares. `plugin()` checks every rule the definition carries on its own, and
+ * creating and installing the value runs none of its code: a hook runs at graph build, the
+ * middleware runs inside an invocation, and the configuration source runs in the input-source
+ * stage when an unfilled option carries its binding.
  */
 interface PluginDefinition<Options extends PluginOptions = PluginOptions, Theme extends ThemeMapping = ThemeMapping> {
     theme?: Theme & ThemeConstraint<Theme>;
@@ -77,32 +95,61 @@ interface PluginDefinition<Options extends PluginOptions = PluginOptions, Theme
     extensions?: readonly AnyExtension[];
     views?: readonly ViewContribution[];
     signals?: readonly ('SIGINT' | 'SIGTERM')[];
+    source?: {
+        binding: AnyExtension & {
+            readonly target: 'option';
+        };
+        load: () => Promise<{
+            default: SourceResolver<Plugin<Options>>;
+        }>;
+    };
+    commands?: readonly Command<unknown, unknown>[];
 }
 /**
  * One plugin: an identity and the contributions it carries. Creating and installing the value runs
  * none of its code: a hook runs at graph build, and the middleware runs inside an invocation, so an
- * installed plugin an invocation never reaches costs that invocation its hooks alone.
+ * installed plugin an invocation never reaches costs that invocation its hooks alone. Every rule
+ * that one definition carries on its own throws here, before the value exists.
  */
 declare function plugin<Options extends PluginOptions = {}, const Theme extends ThemeMapping = {}>(identity: string, definition: PluginDefinition<Options, Theme>): Plugin<NoInfer<Options>, NoInfer<Theme>>;
-/** One installed plugin, with the declarations build reads out of it in installation order. */
-interface InstalledPlugin {
-    declaration: DeclaredPlugin;
-    identity: string;
-}
 /** How every plugin diagnostic names one plugin at the start of a sentence. */
 declare function pluginSentence(identity: string): string;
+/** What the installed list resolves to: the plugins in order, and every descriptor they define. */
+interface InstalledPlugins {
+    descriptors: DescriptorRegistry;
+    plugins: readonly BuiltPlugin[];
+}
+/**
+ * The installed list in composition order, with every rule that reads two plugins together: an
+ * identity installed twice, a second claim on the theme slot, the signals slot, or the
+ * configuration source, and two distinct descriptors under one identity. The slot is read
+ * defensively, because a JavaScript author reaches it with any value. Each plugin's own rules
+ * already ran at its `plugin()` call.
+ */
+declare function installPlugins(plugins: unknown): InstalledPlugins;
 /**
- * The installed list in composition order, with the rules that read the list itself. The slot is
- * read defensively, because a JavaScript author reaches it with any value. Each plugin's own
- * declarations are read by the build steps that consume them, in the order those steps run.
+ * The default export one plugin loader resolves to, checked by the guard its caller supplies. A
+ * loader that throws where it is called and one that rejects later are one failure, and a module
+ * without the export names the kind of function it owed, such as `middleware` or `source`.
  */
-declare function installPlugins(plugins: unknown): readonly InstalledPlugin[];
+declare function loadDefault<Export>(identity: string, load: () => unknown, owed: {
+    guard: (value: unknown) => value is Export;
+    noun: string;
+}): Promise<Export>;
 /** One plugin's declared middleware: what wakes it, and the loader that fetches its module. */
 interface BuiltMiddleware {
     activate: 'always' | readonly string[];
     load: () => unknown;
 }
-/** One installed plugin's declarations, read once per build in installation order. */
+/**
+ * One plugin's configuration source: the identity of the binding that marks an option as
+ * configuration-bound, and the loader that fetches the resolver's module.
+ */
+interface BuiltSource {
+    binding: string;
+    load: () => unknown;
+}
+/** One plugin's declarations, read once at its `plugin()` call. */
 interface BuiltPlugin {
     theme: Palette | undefined;
     /** The hook core calls once per Command at graph build, or nothing where none is declared. */
@@ -113,20 +160,27 @@ interface BuiltPlugin {
     inputs: readonly OptionInput[];
     middleware: BuiltMiddleware | undefined;
     signals: readonly ProcessSignal[];
+    source: BuiltSource | undefined;
+    /** The Commands the plugin attaches to the root, in list order. */
+    commands: readonly AttachedChild[];
+    /** Every descriptor the plugin defines or its options' values name, by identity. */
+    descriptors: ReadonlyMap<string, AnyExtension>;
+    /** The extension record each of the plugin's own options carries. */
+    records: InputRecords;
 }
-/** The shared registers one build fills while it reads each plugin's contributions. */
-interface PluginBuild {
-    descriptors: DescriptorRegistry;
-    extensions: ExtensionRecords;
-}
-/**
- * Every installed plugin's declarations, in installation order. A plugin's own extensions register
- * before any declaration carries a value, so a duplicated package copy is reported from the list
- * that installed it.
- */
-declare function buildPlugins(installed: readonly InstalledPlugin[], build: PluginBuild): readonly BuiltPlugin[];
 /** The signals the one slot owner claimed, or none when no installed plugin claims the slot. */
 declare function ownedSignals(plugins: readonly BuiltPlugin[]): readonly ProcessSignal[];
+/** The value shape a plugin option takes, which is what `OptionValue` gives its declaration. */
+type PluginValues = Record<string, string | string[] | boolean | undefined>;
+/**
+ * One plugin's own option values for one run: what argv or an input source supplied, or the
+ * declared default, filled without validation. A collected value and an array default are copied,
+ * so a plugin that writes to what it received changes neither the declaration nor the next run.
+ * Entries become own keys even for a name such as `__proto__`, which assignment would not.
+ */
+declare function pluginValues(inputs: readonly OptionInput[], values: OptionValues): PluginValues;
+/** One plugin's own spellings for one run, frozen, so no plugin writes what another reads. */
+declare function pluginSpellings(inputs: readonly OptionInput[], values: OptionValues): Readonly<Record<string, string>>;
 type ThemeOf<Contributor> = [Contributor] extends [never] ? {} : Contributor extends Plugin<PluginOptions, infer Theme> ? Theme : {};
-export type { ThemeOf, BuiltPlugin, InstalledPlugin, Middleware, OptionsOf, Plugin, PluginBuild, PluginDefinition, PluginOptions, PluginOptionValues, };
-export { buildPlugins, installPlugins, ownedSignals, plugin, pluginSentence };
+export type { ThemeOf, BuiltPlugin, BuiltSource, PluginValues, SourceAnswer, SourceContext, SourceResolver, Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionSpellings, PluginOptionValues, };
+export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginValues, };

package/dist/plugin.js

@@ -1,9 +1,15 @@
-import { DeclarationError } from './errors.js';
-import { buildExtensions, isDescriptor, registerDescriptor } from './extension.js';
+import { checkEnvBinding, claimVariables } from './bindings.js';
+import { attach, commandNode } from './command.js';
+import { DeclarationError, InternalError, reasonOf } from './errors.js';
+import { appliesTo, buildExtensions, isDescriptor, registerDescriptor } from './extension.js';
 import { checkDeprecated, checkDescription, checkHidden, isPlainObject } from './facts.js';
+import { boundOptions } from './globals.js';
+import { coreViews } from './lanes.js';
+import { booleanValue, compileOptions } from './options.js';
 import { isProcessSignal } from './signals.js';
 import { buildTheme } from './theme.js';
 import { captureConfig, checkDeclarations } from './validation.js';
+import { buildViews, viewIdentities } from './view.js';
 /** Authored values register here, so the public type publishes no state to reach or replace. */
 const nodes = new WeakMap();
 /**
@@ -20,7 +26,8 @@ class PluginDeclaration {
 /**
  * One plugin: an identity and the contributions it carries. Creating and installing the value runs
  * none of its code: a hook runs at graph build, and the middleware runs inside an invocation, so an
- * installed plugin an invocation never reaches costs that invocation its hooks alone.
+ * installed plugin an invocation never reaches costs that invocation its hooks alone. Every rule
+ * that one definition carries on its own throws here, before the value exists.
  */
 function plugin(identity, definition) {
     const captured = {
@@ -29,10 +36,7 @@ function plugin(identity, definition) {
             ? {}
             : { theme: isPlainObject(definition.theme) ? { ...definition.theme } : definition.theme }),
     };
-    return new PluginDeclaration({
-        definition: isPlainObject(definition) ? captured : definition,
-        identity,
-    });
+    return new PluginDeclaration(readPlugin(identity, isPlainObject(definition) ? captured : definition));
 }
 /** How every plugin diagnostic names one plugin at the start of a sentence. */
 function pluginSentence(identity) {
@@ -46,46 +50,70 @@ function nodeOf(value) {
     }
     return node;
 }
-/** The identity one installed value declares, which is a nonempty string installed once. */
-function readIdentity(node, installed) {
-    const { identity } = node;
+/** The identity one plugin declares, which is a nonempty string. */
+function readIdentity(identity) {
     if (typeof identity !== 'string') {
         throw new DeclarationError('A plugin declares an identity that is not a string. Supply a nonempty string, such as the package name.');
     }
     if (identity === '') {
         throw new DeclarationError('A plugin declares an empty identity. Supply a nonempty string, such as the package name.');
     }
-    if (installed.has(identity)) {
-        throw new DeclarationError(`The Application installs plugin "${identity}" twice. Install each plugin once.`);
-    }
     return identity;
 }
 /** The declarations one plugin value carries, which a JavaScript author reaches as any value. */
-function definitionOf(identity, node) {
-    const { definition } = node;
+function definitionOf(identity, definition) {
     if (!isPlainObject(definition)) {
         throw new DeclarationError(`${pluginSentence(identity)} declares a definition that is not an object. Supply { options, middleware, extensions, views }.`);
     }
     return definition;
 }
 /**
- * The installed list in composition order, with the rules that read the list itself. The slot is
- * read defensively, because a JavaScript author reaches it with any value. Each plugin's own
- * declarations are read by the build steps that consume them, in the order those steps run.
+ * The installed list in composition order, with every rule that reads two plugins together: an
+ * identity installed twice, a second claim on the theme slot, the signals slot, or the
+ * configuration source, and two distinct descriptors under one identity. The slot is read
+ * defensively, because a JavaScript author reaches it with any value. Each plugin's own rules
+ * already ran at its `plugin()` call.
  */
 function installPlugins(plugins) {
     if (!Array.isArray(plugins)) {
         throw new DeclarationError('The Application plugins must be an array. Supply a list of plugin values.');
     }
-    const installed = [];
+    const list = plugins;
+    const installed = list.map((value) => nodeOf(value));
     const identities = new Set();
-    for (const value of plugins) {
-        const node = nodeOf(value);
-        const identity = readIdentity(node, identities);
+    const descriptors = new Map();
+    // Each slot has one owner, so the first plugin to claim it names the second claimant's diagnostic.
+    const owners = {};
+    for (const entry of installed) {
+        const { identity } = entry;
+        if (identities.has(identity)) {
+            throw new DeclarationError(`The Application installs plugin "${identity}" twice. Install each plugin once.`);
+        }
         identities.add(identity);
-        installed.push({ declaration: definitionOf(identity, node), identity });
+        if (entry.theme !== undefined) {
+            if (owners.theme !== undefined) {
+                throw new DeclarationError(`${pluginSentence(identity)} claims the theme slot, which plugin "${owners.theme}" already holds. Install one owner.`);
+            }
+            owners.theme = identity;
+        }
+        for (const descriptor of entry.descriptors.values()) {
+            registerDescriptor(descriptors, descriptor);
+        }
+        // An empty claim leaves the signals slot free.
+        if (entry.signals.length > 0) {
+            if (owners.signals !== undefined) {
+                throw new DeclarationError(`${pluginSentence(identity)} claims the signals slot, which plugin "${owners.signals}" already holds. Install one owner.`);
+            }
+            owners.signals = identity;
+        }
+        if (entry.source) {
+            if (owners.source !== undefined) {
+                throw new DeclarationError(`${pluginSentence(identity)} declares a configuration source, which plugin "${owners.source}" already declares. Install one source.`);
+            }
+            owners.source = identity;
+        }
     }
-    return installed;
+    return { descriptors, plugins: installed };
 }
 /** The keys a plugin option may not declare, in the order its diagnostic names them. */
 const forbidden = ['validate', 'validateOmitted', 'required'];
@@ -96,7 +124,7 @@ function checkPluginOption(sentence, config) {
     }
     const rejected = forbidden.find((key) => key in config);
     if (rejected !== undefined) {
-        throw new DeclarationError(`${sentence} declares ${rejected}. Remove it; a plugin option carries no schema or presence rule, and the middleware interprets the value.`);
+        throw new DeclarationError(`${sentence} declares ${rejected}. Remove it; a plugin option carries no validator or presence rule, and the middleware interprets the value.`);
     }
     checkDescription(sentence, config.description);
     checkHidden(sentence, config.hidden);
@@ -114,10 +142,11 @@ function readOptions(identity, declared, build) {
     for (const [name, config] of Object.entries(declared ?? {})) {
         const sentence = `${pluginSentence(identity)} option "${name}"`;
         checkPluginOption(sentence, config);
+        checkEnvBinding(sentence, config);
         const input = { config: captureConfig(config), kind: 'option', name };
         // The shared rules name the plugin and the option, so a fault reads with its contributor.
         checkDeclarations([input], sentence);
-        build.extensions.set(input, buildExtensions({
+        build.records.set(input, buildExtensions({
             declared: config.extensions,
             descriptors: build.descriptors,
             subject: {
@@ -128,6 +157,9 @@ function readOptions(identity, declared, build) {
         }));
         inputs.push(input);
     }
+    // Two options of one plugin meet in the one table the pre-scan reads, so they share its rules.
+    compileOptions(inputs, `plugin "${identity}"`);
+    claimVariables(boundOptions(inputs, (name) => `plugin "${identity}" option "${name}"`));
     return inputs;
 }
 /** One activation name, which must be one of the plugin's own declared options. */
@@ -158,6 +190,27 @@ function readActivation(identity, declared, names) {
 function isLoader(value) {
     return typeof value === 'function';
 }
+/**
+ * The default export one plugin loader resolves to, checked by the guard its caller supplies. A
+ * loader that throws where it is called and one that rejects later are one failure, and a module
+ * without the export names the kind of function it owed, such as `middleware` or `source`.
+ */
+async function loadDefault(identity, load, owed) {
+    let module = undefined;
+    try {
+        module = await load();
+    }
+    catch (error) {
+        throw new InternalError(`Loading plugin "${identity}" failed: ${reasonOf(error)}`, error);
+    }
+    const exported = module !== null && typeof module === 'object' && 'default' in module
+        ? module.default
+        : undefined;
+    if (!owed.guard(exported)) {
+        throw new InternalError(`Loading plugin "${identity}" failed: the module exports no default ${owed.noun} function.`, undefined);
+    }
+    return exported;
+}
 /** One plugin's middleware, or `undefined` for a plugin that declares none. */
 function readMiddleware(identity, declared, names) {
     if (declared === undefined) {
@@ -173,6 +226,30 @@ function readMiddleware(identity, declared, names) {
     }
     return { activate, load };
 }
+/**
+ * The Commands one plugin attaches to the root, each checked by the attach the root applies, as a
+ * finished Command, against the plugin's own earlier Commands, and against the nesting cap. The
+ * Application attaches them again when it is constructed, against every other root child.
+ */
+function readCommands(identity, declared) {
+    if (declared === undefined) {
+        return [];
+    }
+    if (!Array.isArray(declared)) {
+        throw new DeclarationError(`${pluginSentence(identity)} declares commands that are not an array. Supply a list of Command values.`);
+    }
+    const list = declared;
+    const commands = [];
+    // A for...of walk reads a hole as undefined, which the entry rule rejects, where map would skip it.
+    for (const value of list) {
+        const node = commandNode(value);
+        if (!node) {
+            throw new DeclarationError(`${pluginSentence(identity)} holds a value that is not a Command. Supply the value returned by new Command(name).`);
+        }
+        commands.push(attach({ argument: undefined, children: commands, hasAction: false, name: null }, node));
+    }
+    return commands;
+}
 /**
  * One plugin's claim on the signals slot, drawn from the closed set core installs listeners for.
  * An empty list claims nothing, so it leaves the slot free for another plugin.
@@ -216,6 +293,38 @@ function readHook(identity, declared) {
     }
     return declared;
 }
+/**
+ * The configuration source one plugin declares, or `undefined` for a plugin that declares none.
+ * The binding is one of the plugin's own option-target extensions, so core knows which options to
+ * ask about without knowing what the binding means. The plugin's own options resolve before the
+ * source loads, so none of them may carry its binding.
+ */
+function readSource(identity, declaration, own) {
+    const declared = declaration.source;
+    if (declared === undefined) {
+        return undefined;
+    }
+    const sentence = pluginSentence(identity);
+    if (!isPlainObject(declared)) {
+        throw new DeclarationError(`${sentence} declares a source that is not an object. Supply { binding, load }.`);
+    }
+    const { binding, load } = declared;
+    const listed = (declaration.extensions ?? []).some((descriptor) => descriptor === binding);
+    if (!listed || !isDescriptor(binding)) {
+        throw new DeclarationError(`${sentence} declares a source binding that is not one of its extensions. Supply a descriptor the plugin lists under extensions.`);
+    }
+    if (binding.target !== 'option') {
+        throw new DeclarationError(`${sentence} declares source binding "${binding.identity}", which applies to ${appliesTo(binding.target)}. Supply an extension that applies to options.`);
+    }
+    if (!isLoader(load)) {
+        throw new DeclarationError(`${sentence} declares a source with no load function. Supply load: () => import('./source.js').`);
+    }
+    const carrier = own.inputs.find((input) => Object.hasOwn(own.build.records.get(input) ?? {}, binding.identity));
+    if (carrier) {
+        throw new DeclarationError(`${sentence} option "${carrier.name}" carries its own source binding. Remove the value; the source's own options resolve before it loads.`);
+    }
+    return { binding: binding.identity, load };
+}
 /** A plugin's own list names the extensions it defines, before any declaration carries one. */
 function defineExtensions(identity, declaration, build) {
     const { extensions } = declaration;
@@ -230,49 +339,78 @@ function defineExtensions(identity, declaration, build) {
     }
 }
 /**
- * Every installed plugin's declarations, in installation order. A plugin's own extensions register
- * before any declaration carries a value, so a duplicated package copy is reported from the list
- * that installed it.
+ * Every rule one definition carries on its own, in the order the definition's slots are read. The
+ * plugin's own extensions register before any declaration carries a value, so a duplicated package
+ * copy is reported from the list that defines it. The views list is read against core's view
+ * identities, and the Application reads it again against every other contributor's.
  */
-function buildPlugins(installed, build) {
-    /**
-     * The signals slot has one owner, so the first plugin to claim it names the second claimant's
-     * diagnostic. An empty claim leaves the slot free.
-     */
-    let owner = undefined;
-    let themeOwner = undefined;
-    return installed.map(({ declaration, identity }) => {
-        let theme = undefined;
-        if (declaration.theme !== undefined) {
-            if (themeOwner !== undefined) {
-                throw new DeclarationError(`${pluginSentence(identity)} claims the theme slot, which plugin "${themeOwner}" already holds. Install one owner.`);
-            }
-            theme = buildTheme(declaration.theme, identity);
-            themeOwner = identity;
-        }
-        defineExtensions(identity, declaration, build);
-        const inputs = readOptions(identity, declaration.options, build);
-        const names = new Set(inputs.map((input) => input.name));
-        const signals = readSignals(identity, declaration.signals);
-        if (signals.length > 0) {
-            if (owner !== undefined) {
-                throw new DeclarationError(`${pluginSentence(identity)} claims the signals slot, which plugin "${owner}" already holds. Install one owner.`);
-            }
-            owner = identity;
-        }
-        return {
-            identity,
-            inputs,
-            middleware: readMiddleware(identity, declaration.middleware, names),
-            onCommandAttach: readHook(identity, declaration.onCommandAttach),
-            signals,
-            theme,
-            views: declaration.views,
-        };
-    });
+function readPlugin(identity, definition) {
+    const named = readIdentity(identity);
+    const declaration = definitionOf(named, definition);
+    const theme = declaration.theme === undefined ? undefined : buildTheme(declaration.theme, named);
+    const build = { descriptors: new Map(), records: new Map() };
+    defineExtensions(named, declaration, build);
+    const inputs = readOptions(named, declaration.options, build);
+    const names = new Set(inputs.map((input) => input.name));
+    const signals = readSignals(named, declaration.signals);
+    const source = readSource(named, declaration, { build, inputs });
+    const commands = readCommands(named, declaration.commands);
+    const middleware = readMiddleware(named, declaration.middleware, names);
+    const onCommandAttach = readHook(named, declaration.onCommandAttach);
+    buildViews({ declares: true, sentence: pluginSentence(named) }, declaration.views, viewIdentities(coreViews));
+    return {
+        commands,
+        descriptors: build.descriptors,
+        identity: named,
+        inputs,
+        middleware,
+        onCommandAttach,
+        records: build.records,
+        signals,
+        source,
+        theme,
+        views: declaration.views,
+    };
 }
 /** The signals the one slot owner claimed, or none when no installed plugin claims the slot. */
 function ownedSignals(plugins) {
     return plugins.find((entry) => entry.signals.length > 0)?.signals ?? [];
 }
-export { buildPlugins, installPlugins, ownedSignals, plugin, pluginSentence };
+/** 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 option's value for one run: what a tier supplied, or the declared default. */
+function pluginValue({ config, name }, values) {
+    const declared = config.default;
+    if (config.type === 'boolean') {
+        return booleanValue(values, name, config);
+    }
+    if (config.multiple === true) {
+        return collectedValue(values.lists.get(name), declared);
+    }
+    // Build already proved that a string option without a validator declares a string default.
+    return values.strings.get(name) ?? (typeof declared === 'string' ? declared : undefined);
+}
+/**
+ * One plugin's own option values for one run: what argv or an input source supplied, or the
+ * declared default, filled without validation. A collected value and an array default are copied,
+ * so a plugin that writes to what it received changes neither the declaration nor the next run.
+ * Entries become own keys even for a name such as `__proto__`, which assignment would not.
+ */
+function pluginValues(inputs, values) {
+    return Object.fromEntries(inputs.map((input) => [input.name, pluginValue(input, values)]));
+}
+/** One plugin's own spellings for one run, frozen, so no plugin writes what another reads. */
+function pluginSpellings(inputs, values) {
+    // Entries become own keys even for a name such as `__proto__`, which assignment would not.
+    const spelled = inputs.flatMap(({ name }) => {
+        const spelling = values.spellings.get(name);
+        return spelling === undefined ? [] : [[name, spelling]];
+    });
+    return Object.freeze(Object.fromEntries(spelled));
+}
+export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginValues, };

package/dist/sources.d.ts

@@ -0,0 +1,56 @@
+import { InputError, InternalError } from './errors.js';
+import type { ExtensionRecords } from './extension.js';
+import type { CommandGraph, OptionNode } from './inspect.js';
+import type { OptionValues } from './options.js';
+import type { BuiltPlugin } from './plugin.js';
+import type { ContextualStyle } from './style.js';
+import type { Host, Out } from './types.js';
+import type { OptionInput } from './validation.js';
+/**
+ * One scope the stage fills: its options in declaration order, and the values argv supplied them.
+ * The stage writes each fill into `values`, so the caller hands it the run's own copy.
+ */
+interface StageScope {
+    global: boolean;
+    inputs: readonly OptionInput[];
+    values: OptionValues;
+}
+/** Everything one input-source stage reads. */
+interface SourceStage {
+    extensions: ExtensionRecords;
+    /** The globals table: the application's global options, then each plugin's in install order. */
+    globals: StageScope;
+    host: Host;
+    /** The graph `inspect()` would return for the run, built on its first read. */
+    inspected: () => CommandGraph;
+    /** The routed Command's own options, or `undefined` while local parsing holds a fault. */
+    locals: StageScope | undefined;
+    /** The channel a source writes through, whose results call names the source. */
+    out: Out;
+    plugins: readonly BuiltPlugin[];
+    /** The `OptionNode` of one option, read from the graph `inspect()` would return for the run. */
+    request: (input: OptionInput, global: boolean) => OptionNode;
+    signal: AbortSignal;
+    /** The contextual style an action receives, so a source escapes raw data before it warns. */
+    style: ContextualStyle;
+}
+/**
+ * What the stage found beside the values it filled. `labels` names where each filled option's value
+ * came from, by option name, and `rejected` names the variable of each Boolean option whose value
+ * is outside the grammar. Both are internal to core's failure messages. `fault` is a configuration
+ * source's own fault, or the `InputError` its resolver threw, which stops the stage and takes the
+ * place of every validation problem.
+ */
+interface SourceOutcome {
+    fault: InternalError | InputError | undefined;
+    labels: ReadonlyMap<string, string>;
+    rejected: ReadonlyMap<string, string>;
+}
+/**
+ * The input-source stage: the environment, then the configuration source, for every option in
+ * scope that argv left unfilled. When no option is left to ask, the source never loads. A source
+ * fault stops the stage and fills nothing more.
+ */
+declare function fillInputs(stage: SourceStage): Promise<SourceOutcome>;
+export type { SourceOutcome, SourceStage, StageScope };
+export { fillInputs };