@loomcli/core 0.3.0 → 0.5.0

package/dist/options.d.ts

@@ -7,7 +7,11 @@ export interface OptionValues {
     strings: Map<string, string>;
     lists: Map<string, string[]>;
     booleans: Map<string, boolean>;
+    /** The spelling of the token that supplied each parsed option, which no input source writes. */
+    spellings: Map<string, string>;
 }
+/** Every parsed value lands in one of these maps; `lists` holds the repeated string options. */
+export declare function emptyValues(): OptionValues;
 /** Which accepted form a table entry is. The table owns the convention, so readers never re-derive it. */
 type SpellingRole = 'long' | 'negative' | 'short';
 type OptionForm = {
@@ -30,13 +34,82 @@ type OptionSpelling = OptionForm & {
  */
 export declare function booleanValue(values: OptionValues, name: string, config: OptionConfig): boolean;
 export declare function compileOptions(declarations: readonly OptionDeclaration[], subject: string): Map<string, OptionSpelling>;
+/**
+ * Whether a token reads as an option: it starts with a hyphen. Routing stops at one, and a
+ * separate value is never one. The parser and `locate` read each token through this rule.
+ */
+export declare function isOptionToken(token: string): boolean;
+/** A long option token and the inline value it carries after its first `=`, if any. */
+export interface LongToken {
+    spelling: string;
+    inline: string | undefined;
+}
+/**
+ * A token that starts with `--` split at its first `=` into the spelling and the inline value, or
+ * `undefined` for any other token. The parser and `locate` split long tokens through this rule.
+ */
+export declare function longToken(token: string): LongToken | undefined;
+/**
+ * The name of the string option one long spelling names in a table, which takes its value after
+ * `=`, or `undefined` for a Boolean, negative, short, or unknown spelling.
+ */
+export declare function longStringOption(spellings: ReadonlyMap<string, OptionSpelling>, spelling: string): string | undefined;
+/**
+ * A string option whose value the next token supplies, where the tokens ended first. A complete
+ * invocation reports it as a missing value; a partial one reads the next word as that value.
+ */
+export interface AwaitingValue {
+    name: string;
+    spelling: string;
+}
+/** One option name a token newly supplied, with the index of that token in the list read. */
+export interface SuppliedOption {
+    name: string;
+    token: number;
+}
+/**
+ * The pre-scan's reading of a token list that may stop short. `positions` holds the index in
+ * `tokens` of each `rest` token, and `awaiting` is the global option the last token left without
+ * its value.
+ */
+export interface GlobalScan {
+    awaiting: AwaitingValue | undefined;
+    positions: number[];
+    rest: string[];
+    supplied: SuppliedOption[];
+    values: OptionValues;
+}
 /** Consumes global options anywhere before the passthrough delimiter and leaves the rest routable. */
+export declare function scanGlobals(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): GlobalScan;
+/** The pre-scan of a complete invocation, where a global still waiting for its value is a fault. */
 export declare function extractGlobals(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): {
     rest: string[];
     values: OptionValues;
 };
+/**
+ * Whether one option holds a value a tier supplied: a token in any spelling it accepts, or a fill
+ * from an input source. A declared default is never in these maps, so it never counts.
+ */
+export declare function isSupplied(values: OptionValues, name: string): boolean;
+/** One run's own copy of parsed values, which the input-source stage fills without touching argv's. */
+export declare function copyValues(values: OptionValues): OptionValues;
 /** Global and local keys never overlap, so one merged view feeds a single validation pass. */
 export declare function mergeValues(globals: OptionValues, locals: OptionValues): OptionValues;
+/**
+ * One Command's reading of its own tokens, which may stop short. `delimited` says a bare `--` was
+ * read, and `awaiting` is the option the last token left without its value.
+ */
+export interface InputScan {
+    awaiting: AwaitingValue | undefined;
+    delimited: boolean;
+    options: OptionValues;
+    passthrough: string[];
+    positionals: string[];
+    supplied: SuppliedOption[];
+}
+/** Reads one Command's tokens into options, positionals, and the passthrough tail. */
+export declare function scanInputs(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): InputScan;
+/** Parses a complete invocation's local tokens, where a waiting option is a missing value. */
 export declare function parseInputs(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): {
     options: OptionValues;
     passthrough: string[];

package/dist/options.js

@@ -1,7 +1,7 @@
 import { DeclarationError, MissingValueError, RepeatedOptionError, ShortGroupError, UnexpectedValueError, UnknownOptionError, } from './errors.js';
 /** Every parsed value lands in one of these maps; `lists` holds the repeated string options. */
-function emptyValues() {
-    return { booleans: new Map(), lists: new Map(), strings: new Map() };
+export function emptyValues() {
+    return { booleans: new Map(), lists: new Map(), spellings: new Map(), strings: new Map() };
 }
 function validateDeclaration({ name, config }) {
     if (typeof name !== 'string') {
@@ -89,6 +89,26 @@ export function compileOptions(declarations, subject) {
     }
     return spellings;
 }
+/**
+ * Whether a token reads as an option: it starts with a hyphen. Routing stops at one, and a
+ * separate value is never one. The parser and `locate` read each token through this rule.
+ */
+export function isOptionToken(token) {
+    return token.startsWith('-');
+}
+/**
+ * A token that starts with `--` split at its first `=` into the spelling and the inline value, or
+ * `undefined` for any other token. The parser and `locate` split long tokens through this rule.
+ */
+export function longToken(token) {
+    if (!token.startsWith('--')) {
+        return undefined;
+    }
+    const equals = token.indexOf('=');
+    return equals === -1
+        ? { inline: undefined, spelling: token }
+        : { inline: token.slice(equals + 1), spelling: token.slice(0, equals) };
+}
 function lookup(spellings, spelling) {
     const option = spellings.get(spelling);
     if (!option) {
@@ -96,20 +116,33 @@ function lookup(spellings, spelling) {
     }
     return option;
 }
+/**
+ * The name of the string option one long spelling names in a table, which takes its value after
+ * `=`, or `undefined` for a Boolean, negative, short, or unknown spelling.
+ */
+export function longStringOption(spellings, spelling) {
+    const option = spellings.get(spelling);
+    return option?.type === 'string' && option.role === 'long' ? option.name : undefined;
+}
 function acceptValue({ option, spelling, values, next, inline, }) {
     const repeatable = option.type === 'string' && option.multiple;
     if (!repeatable && (values.strings.has(option.name) || values.booleans.has(option.name))) {
         throw new RepeatedOptionError(spelling);
     }
+    // A repeatable option records its last occurrence, because each one overwrites the entry.
+    values.spellings.set(option.name, spelling);
     if (option.type === 'boolean') {
         if (inline !== undefined) {
             throw new UnexpectedValueError(spelling, inline);
         }
         values.booleans.set(option.name, option.value);
-        return false;
+        return 'alone';
     }
     const value = inline ?? next;
-    if (value === undefined || (inline === undefined && value.startsWith('-'))) {
+    if (value === undefined) {
+        return { name: option.name, spelling };
+    }
+    if (inline === undefined && isOptionToken(value)) {
         throw new MissingValueError(spelling);
     }
     if (repeatable) {
@@ -120,14 +153,13 @@ function acceptValue({ option, spelling, values, next, inline, }) {
     else {
         values.strings.set(option.name, value);
     }
-    return inline === undefined;
+    return inline === undefined ? 'next' : 'alone';
 }
 function parseOption(spellings, input, values) {
     const { token, next } = input;
-    if (token.startsWith('--')) {
-        const equals = token.indexOf('=');
-        const spelling = equals === -1 ? token : token.slice(0, equals);
-        const inline = equals === -1 ? undefined : token.slice(equals + 1);
+    const long = longToken(token);
+    if (long) {
+        const { inline, spelling } = long;
         return acceptValue({ inline, next, option: lookup(spellings, spelling), spelling, values });
     }
     if (token === '-') {
@@ -141,20 +173,37 @@ function parseOption(spellings, input, values) {
             throw new ShortGroupError({ reason: 'value-position', token: spelling });
         }
         const inline = suffix.startsWith('=') ? suffix.slice(1) : undefined;
-        if (acceptValue({ inline, next, option, spelling, values })) {
-            return true;
+        const reading = acceptValue({ inline, next, option, spelling, values });
+        if (reading !== 'alone') {
+            return reading;
         }
     }
-    return false;
+    return 'alone';
+}
+/**
+ * Reads one option token into the scan and answers whether it took the next token too. The names
+ * it newly supplied join `supplied` in the order the values map first recorded them, so a repeated
+ * option keeps its first position.
+ */
+function readOption(spellings, input, state) {
+    const known = state.values.spellings.size;
+    const reading = parseOption(spellings, input, state.values);
+    for (const name of [...state.values.spellings.keys()].slice(known)) {
+        state.supplied.push({ name, token: input.index });
+    }
+    if (typeof reading === 'object') {
+        state.awaiting = reading;
+    }
+    return reading === 'next';
 }
 /**
  * A hyphen token belongs to the globals when its long spelling or every short letter does. The
  * pre-scan reads the globals alone, so a letter it does not own is only "not a global option".
  */
 function isGlobalToken(spellings, token) {
-    if (token.startsWith('--')) {
-        const equals = token.indexOf('=');
-        return spellings.has(equals === -1 ? token : token.slice(0, equals));
+    const long = longToken(token);
+    if (long) {
+        return spellings.has(long.spelling);
     }
     const group = token.slice(1).split('=')[0] ?? '';
     let global = '';
@@ -177,52 +226,100 @@ function isGlobalToken(spellings, token) {
     return true;
 }
 /** Consumes global options anywhere before the passthrough delimiter and leaves the rest routable. */
-export function extractGlobals(spellings, tokens) {
-    const values = emptyValues();
+export function scanGlobals(spellings, tokens) {
+    const state = { awaiting: undefined, supplied: [], values: emptyValues() };
     const rest = [];
+    const positions = [];
     for (let index = 0; index < tokens.length; index += 1) {
         const token = tokens[index];
         if (token === undefined) {
             break;
         }
         if (token === '--') {
-            rest.push(...tokens.slice(index));
-            return { rest, values };
+            // One push per token, because a spread call would overflow the stack on a long list.
+            for (const [offset, tail] of tokens.slice(index).entries()) {
+                rest.push(tail);
+                positions.push(index + offset);
+            }
+            break;
         }
-        if (!token.startsWith('-') || !isGlobalToken(spellings, token)) {
+        if (!isOptionToken(token) || !isGlobalToken(spellings, token)) {
             rest.push(token);
+            positions.push(index);
         }
-        else if (parseOption(spellings, { next: tokens[index + 1], token }, values)) {
+        else if (readOption(spellings, { index, next: tokens[index + 1], token }, state)) {
             index += 1;
         }
     }
+    return { ...state, positions, rest };
+}
+/** The pre-scan of a complete invocation, where a global still waiting for its value is a fault. */
+export function extractGlobals(spellings, tokens) {
+    const { awaiting, rest, values } = scanGlobals(spellings, tokens);
+    if (awaiting) {
+        throw new MissingValueError(awaiting.spelling);
+    }
     return { rest, values };
 }
+/**
+ * Whether one option holds a value a tier supplied: a token in any spelling it accepts, or a fill
+ * from an input source. A declared default is never in these maps, so it never counts.
+ */
+export function isSupplied(values, name) {
+    return values.strings.has(name) || values.lists.has(name) || values.booleans.has(name);
+}
+/** One run's own copy of parsed values, which the input-source stage fills without touching argv's. */
+export function copyValues(values) {
+    return {
+        booleans: new Map(values.booleans),
+        lists: new Map([...values.lists].map(([name, list]) => [name, [...list]])),
+        spellings: new Map(values.spellings),
+        strings: new Map(values.strings),
+    };
+}
 /** Global and local keys never overlap, so one merged view feeds a single validation pass. */
 export function mergeValues(globals, locals) {
     return {
         booleans: new Map([...globals.booleans, ...locals.booleans]),
         lists: new Map([...globals.lists, ...locals.lists]),
+        spellings: new Map([...globals.spellings, ...locals.spellings]),
         strings: new Map([...globals.strings, ...locals.strings]),
     };
 }
-export function parseInputs(spellings, tokens) {
-    const options = emptyValues();
+/** Reads one Command's tokens into options, positionals, and the passthrough tail. */
+export function scanInputs(spellings, tokens) {
+    const state = { awaiting: undefined, supplied: [], values: emptyValues() };
     const positionals = [];
+    const read = (passthrough, delimited) => ({
+        awaiting: state.awaiting,
+        delimited,
+        options: state.values,
+        passthrough,
+        positionals,
+        supplied: state.supplied,
+    });
     for (let index = 0; index < tokens.length; index += 1) {
         const token = tokens[index];
         if (token === undefined) {
             break;
         }
         if (token === '--') {
-            return { options, passthrough: tokens.slice(index + 1), positionals };
+            return read(tokens.slice(index + 1), true);
         }
-        if (!token.startsWith('-')) {
+        if (!isOptionToken(token)) {
             positionals.push(token);
         }
-        else if (parseOption(spellings, { next: tokens[index + 1], token }, options)) {
+        else if (readOption(spellings, { index, next: tokens[index + 1], token }, state)) {
             index += 1;
         }
     }
-    return { options, passthrough: [], positionals };
+    return read([], false);
+}
+/** Parses a complete invocation's local tokens, where a waiting option is a missing value. */
+export function parseInputs(spellings, tokens) {
+    const { awaiting, options, passthrough, positionals } = scanInputs(spellings, tokens);
+    if (awaiting) {
+        throw new MissingValueError(awaiting.spelling);
+    }
+    return { options, passthrough, positionals };
 }

package/dist/output.d.ts

@@ -26,6 +26,8 @@ export declare class Output {
      * declaration a call answers to is checked where the action was authored.
      */
     readonly out: Out<OpenResult>;
+    /** The channel a configuration source receives: `out` with the results call naming a source. */
+    readonly sourceOut: Out<OpenResult>;
     private palette;
     private policy;
     private registry;

package/dist/output.js

@@ -155,6 +155,8 @@ export class Output {
      * declaration a call answers to is checked where the action was authored.
      */
     out;
+    /** The channel a configuration source receives: `out` with the results call naming a source. */
+    sourceOut;
     palette = new Map();
     policy = {};
     // The contributors this invocation resolves a declared view through, published once they build.
@@ -179,6 +181,8 @@ export class Output {
             success: (message) => this.emit('success', message, 'stderr'),
             warn: (message) => this.emit('warn', message, 'stderr'),
         };
+        // A configuration source writes through the same channel, and its results call names it.
+        this.sourceOut = { ...this.out, results: () => this.resultFault('source') };
     }
     /**
      * The channel one action receives. On a Command that declares a result nothing the action writes
@@ -238,7 +242,7 @@ export class Output {
             });
         }
         if (typeof view.row === 'function') {
-            // Build rejects a row view on a value result, so reaching one here is core's own fault.
+            // The result() call rejects a row view on a value result, so reaching one here is core's own fault.
             return this.renderFailed(new Error(`The view "${selected}" renders rows, not a value.`));
         }
         return this.rendered(() => resolveView(bare, view)(erased(value), this.context('stdout')));

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, };