@loomcli/core 0.4.0 → 0.6.0

package/dist/output.js

@@ -145,16 +145,21 @@ export class Output {
     signal;
     destinations = new Map();
     renderFault = undefined;
+    // Every value a view failed with.
+    // A caller that lets one propagate never offers it to a translator.
+    viewFaults = new WeakSet();
     // Every fault the output path raised beside its calls, reported after the primary outcome.
     // A source a sequence stopped on and a results-lane fault are both such faults.
     stops = [];
-    // The routed Command an incomplete sequence names, published once routing resolved it.
+    // The path routing walked, which an incomplete sequence names, updated as each name routes.
     route = [];
     /**
      * The channel every caller writes through. It is typed with the result left open, because the
      * 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 +184,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 +245,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')));
@@ -259,7 +266,7 @@ export class Output {
     useViews(registry) {
         this.registry = registry;
     }
-    /** The routed path, published once routing resolved it, which an incomplete sequence names. */
+    /** The path routing walked, updated as each name routes, which an incomplete sequence names. */
     useRoute(path) {
         this.route = path;
     }
@@ -391,10 +398,23 @@ export class Output {
      */
     renderFailed(cause) {
         this.renderFault ??= { cause };
+        if ((typeof cause === 'object' || typeof cause === 'function') && cause !== null) {
+            this.viewFaults.add(cause);
+        }
         const rejection = Promise.reject(cause);
         void rejection.catch(() => undefined);
         return rejection;
     }
+    /**
+     * Whether one value is what a view or a message check failed with during this invocation. A
+     * broken view is a defect in the code that broke the view contract, so an action or a source that
+     * lets its rejection propagate reports it as that defect.
+     */
+    raisedByView(value) {
+        return ((typeof value === 'object' || typeof value === 'function') &&
+            value !== null &&
+            this.viewFaults.has(value));
+    }
     /** What a view failed with during this invocation, if one did. */
     get fault() {
         return this.renderFault;

package/dist/plain.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A structural value core reads as plain data: an object literal, and never a declaration that
+ * carries state of its own. The options slots read it to reject a value that is not an options
+ * object, and inspection reads it to copy a declared value faithfully.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/plain.js

@@ -0,0 +1,12 @@
+/**
+ * A structural value core reads as plain data: an object literal, and never a declaration that
+ * carries state of its own. The options slots read it to reject a value that is not an options
+ * object, and inspection reads it to copy a declared value faithfully.
+ */
+export function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/plugin-rules.d.ts

@@ -0,0 +1,62 @@
+/** A slot that holds a list, such as `plugins` or `commands`, holding a value of another kind. */
+declare const notAList: import("./diagnostic-text.js").DiagnosticRule;
+/**
+ * A declaration core reads by its keys, such as a plugin's middleware or a constructor's options,
+ * that is not an object.
+ */
+declare const notAnObject: import("./diagnostic-text.js").DiagnosticRule;
+/** A list entry that its factory did not build, such as a hand-made plugin or translation. */
+declare const foreignValue: import("./diagnostic-text.js").DiagnosticRule;
+/** One plugin identity installed twice. */
+declare const pluginInstalledTwice: import("./diagnostic-text.js").DiagnosticRule;
+/** A second plugin claiming the theme, the signals, or the configuration source slot. */
+declare const slotTaken: import("./diagnostic-text.js").DiagnosticRule;
+/** A plugin, extension, or view identity outside the identity grammar. */
+declare const invalidIdentity: import("./diagnostic-text.js").DiagnosticRule;
+/** A validator or a presence rule on a plugin option. */
+declare const pluginOptionRule: import("./diagnostic-text.js").DiagnosticRule;
+/** A middleware activation that is missing, empty, or names an option the plugin lacks. */
+declare const middlewareActivation: import("./diagnostic-text.js").DiagnosticRule;
+/** A loader, a hook, or a translator that core cannot call. */
+declare const notAFunction: import("./diagnostic-text.js").DiagnosticRule;
+/** A claimed signal outside SIGINT and SIGTERM. */
+declare const unknownSignal: import("./diagnostic-text.js").DiagnosticRule;
+/** One signal claimed twice by one plugin. */
+declare const signalClaimedTwice: import("./diagnostic-text.js").DiagnosticRule;
+/** A configuration source binding that is not one of the plugin's option extensions. */
+declare const sourceBinding: import("./diagnostic-text.js").DiagnosticRule;
+/** A plugin option that carries its own plugin's source binding. */
+declare const sourceBoundOwnOption: import("./diagnostic-text.js").DiagnosticRule;
+/** Two distinct objects under one extension or declared-view identity. */
+declare const twoPackageCopies: import("./diagnostic-text.js").DiagnosticRule;
+/** A descriptor with no Standard Schema. */
+declare const extensionWithoutSchema: import("./diagnostic-text.js").DiagnosticRule;
+/** An extension value on a declaration its descriptor does not target. */
+declare const extensionTarget: import("./diagnostic-text.js").DiagnosticRule;
+/** Two values of one extension in one layer. */
+declare const extensionValueTwice: import("./diagnostic-text.js").DiagnosticRule;
+/** An extension value its schema rejects, by an issue or by a throw. */
+declare const invalidExtensionValue: import("./diagnostic-text.js").DiagnosticRule;
+/** An extension schema that answers with a promise. */
+declare const asyncExtensionSchema: import("./diagnostic-text.js").DiagnosticRule;
+/** An extension output that is not plain data. */
+declare const extensionOutput: import("./diagnostic-text.js").DiagnosticRule;
+/** An override whose key is neither a declared view nor a failure class. */
+declare const overrideKey: import("./diagnostic-text.js").DiagnosticRule;
+/** One key overridden twice inside one contributor. */
+declare const overrideTwice: import("./diagnostic-text.js").DiagnosticRule;
+/** A `translate()` key that is not a class, or that is a failure class. */
+declare const translationKey: import("./diagnostic-text.js").DiagnosticRule;
+/** An `onCommandAttach` hook that threw or returned a value that is not the attached Command. */
+declare const brokenAttachHook: import("./diagnostic-text.js").DiagnosticRule;
+/** The retired `globals` or `failures` Application option. */
+declare const retiredApplicationOption: import("./diagnostic-text.js").DiagnosticRule;
+/** A packet that is not an object, or whose build is neither value. */
+declare const invalidPacket: import("./diagnostic-text.js").DiagnosticRule;
+/** A rendering policy that is not an object, or holds a setting outside its closed set. */
+declare const renderingPolicyRule: import("./diagnostic-text.js").DiagnosticRule;
+/** A plugin theme that is not a mapping of names to unapplied concrete style chains. */
+declare const themeMapping: import("./diagnostic-text.js").DiagnosticRule;
+/** A theme name that a built-in style member already holds. */
+declare const themeNameTaken: import("./diagnostic-text.js").DiagnosticRule;
+export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, pluginOptionRule, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, };

package/dist/plugin-rules.js

@@ -0,0 +1,155 @@
+import { registerRule } from './diagnostic-text.js';
+/*
+ * Core's rules for the declaration faults of plugins, extensions, views, translators, lifecycle
+ * hooks, and the Application options that install them. Each is declared once here and shared by
+ * every site that raises it, as a plugin's rules are.
+ */
+/** A slot that holds a list, such as `plugins` or `commands`, holding a value of another kind. */
+const notAList = registerRule('@loomcli/core/not-a-list', {
+    explanation: 'Core reads plugins, commands, extensions, views, translators, and signals each as a list, in order. A value of any other kind has no entries to read.',
+    headline: 'Not a list',
+});
+/**
+ * A declaration core reads by its keys, such as a plugin's middleware or a constructor's options,
+ * that is not an object.
+ */
+const notAnObject = registerRule('@loomcli/core/not-an-object', {
+    explanation: "Core reads the options of a Command and of the Application, a plugin's definition, its options record, each of its option declarations, its middleware, its source, and the config of an argument or option by their keys. A value of any other kind has no keys to read.",
+    headline: 'Not an object',
+});
+/** A list entry that its factory did not build, such as a hand-made plugin or translation. */
+const foreignValue = registerRule('@loomcli/core/foreign-value', {
+    explanation: 'Core reads a plugin, an extension, an extension value, a declared view, a view override, and a translation through facts its factory recorded when it built the value. Any other value carries none, even one of the same shape.',
+    headline: 'Value not from its factory',
+});
+/** One plugin identity installed twice. */
+const pluginInstalledTwice = registerRule('@loomcli/core/plugin-installed-twice', {
+    explanation: 'Core keys each plugin by its identity, and a plugin contributes its options, middleware, hooks, and views once, so a second installation would contribute each of them again.',
+    headline: 'Plugin installed twice',
+});
+/** A second plugin claiming the theme, the signals, or the configuration source slot. */
+const slotTaken = registerRule('@loomcli/core/slot-taken', {
+    explanation: 'A slot is a position exactly one plugin claims: the theme, the process signals, and the configuration source. A second claim would leave two plugins answering where core asks one.',
+    headline: 'Slot already claimed',
+});
+/** A plugin, extension, or view identity outside the identity grammar. */
+const invalidIdentity = registerRule('@loomcli/core/invalid-identity', {
+    explanation: 'An identity keys what a plugin, an extension, or a view contributes, names it in every diagnostic, and prefixes the identities of the rules its package declares, so it is a package name as npm spells one, scoped or not, then any subpath segments, each after a / and each of lowercase letters and digits in words joined by single hyphens.',
+    headline: 'Invalid identity',
+});
+/** A validator or a presence rule on a plugin option. */
+const pluginOptionRule = registerRule('@loomcli/core/plugin-option-rule', {
+    explanation: "A plugin's middleware interprets its own options' values, so a plugin option declares how it parses and nothing more: no validator and no presence rule.",
+    headline: 'Rule on a plugin option',
+});
+/** A middleware activation that is missing, empty, or names an option the plugin lacks. */
+const middlewareActivation = registerRule('@loomcli/core/middleware-activation', {
+    explanation: "Activation decides when core loads a plugin's middleware: on every run with 'always', or only when an invocation supplies one of the plugin's own options the list names, so a middleware no invocation needs costs it nothing.",
+    headline: 'Invalid middleware activation',
+});
+/** A loader, a hook, or a translator that core cannot call. */
+const notAFunction = registerRule('@loomcli/core/not-a-function', {
+    explanation: 'Core calls each of these values at a point of its own: load when a run first reaches a middleware or a source, onCommandAttach at graph build, onFailure when a failure renders, and a translator when a foreign throw reaches it. A value core cannot call leaves it nothing to run.',
+    headline: 'Not a function',
+});
+/** A claimed signal outside SIGINT and SIGTERM. */
+const unknownSignal = registerRule('@loomcli/core/unknown-signal', {
+    explanation: 'Core installs listeners for SIGINT and SIGTERM alone, the two signals that ask a command-line program to stop, so a plugin claims one of those.',
+    headline: 'Unknown signal',
+});
+/** One signal claimed twice by one plugin. */
+const signalClaimedTwice = registerRule('@loomcli/core/signal-claimed-twice', {
+    explanation: 'Core installs one listener for each signal a plugin claims, and a second listener on one signal would take the forced path on the first signal the run receives.',
+    headline: 'Signal claimed twice',
+});
+/** A configuration source binding that is not one of the plugin's option extensions. */
+const sourceBinding = registerRule('@loomcli/core/source-binding', {
+    explanation: 'A configuration source answers the options that carry its binding, an extension the plugin lists under extensions that applies to options. Core asks the source about those options without knowing what the binding means.',
+    headline: 'Invalid source binding',
+});
+/** A plugin option that carries its own plugin's source binding. */
+const sourceBoundOwnOption = registerRule('@loomcli/core/source-bound-own-option', {
+    explanation: "A plugin's own options resolve before its configuration source loads, because the source reads them, so none of them can take a value from that source.",
+    headline: 'Source bound to its own option',
+});
+/** Two distinct objects under one extension or declared-view identity. */
+const twoPackageCopies = registerRule('@loomcli/core/two-package-copies', {
+    explanation: 'Core keys each extension and each declared view by its identity and compares it by reference. Two distinct objects under one identity mean two copies of the package that defines it are installed, and a value one copy made cannot be read through the other.',
+    headline: 'Two copies of one package',
+});
+/** A descriptor with no Standard Schema. */
+const extensionWithoutSchema = registerRule('@loomcli/core/extension-without-schema', {
+    explanation: "Core validates each extension value against its descriptor's Standard Schema at the call that carries it, so a descriptor with no schema leaves the value unchecked.",
+    headline: 'Extension without a schema',
+});
+/** An extension value on a declaration its descriptor does not target. */
+const extensionTarget = registerRule('@loomcli/core/extension-target', {
+    explanation: 'An extension is defined for one target, Commands, options, or arguments, and a typed read takes that kind of node alone, so a value on another kind would never be read.',
+    headline: 'Extension on the wrong target',
+});
+/** Two values of one extension in one layer. */
+const extensionValueTwice = registerRule('@loomcli/core/extension-value-twice', {
+    explanation: 'One extensions list or one extend() call sets each extension once, collecting or not, so two values of one extension leave it unclear which the author meant.',
+    headline: 'Extension value twice',
+});
+/** An extension value its schema rejects, by an issue or by a throw. */
+const invalidExtensionValue = registerRule('@loomcli/core/invalid-extension-value', {
+    explanation: "An extension value passes its descriptor's schema at the call that carries it, so every plugin that reads it reads a value the schema accepted.",
+    headline: 'Invalid extension value',
+});
+/** An extension schema that answers with a promise. */
+const asyncExtensionSchema = registerRule('@loomcli/core/async-extension-schema', {
+    explanation: 'Core validates extension values synchronously while it builds the declaration, so a schema that answers with a promise leaves it no verdict to read.',
+    headline: 'Asynchronous extension schema',
+});
+/** An extension output that is not plain data. */
+const extensionOutput = registerRule('@loomcli/core/extension-output', {
+    explanation: "Every projection, the manifest included, reads an extension's output as frozen plain data: strings, finite numbers, Booleans, null, arrays, and plain objects.",
+    headline: 'Extension output not plain data',
+});
+/** An override whose key is neither a declared view nor a failure class. */
+const overrideKey = registerRule('@loomcli/core/override-key', {
+    explanation: 'An override replaces the view of a declared view or of a failure class, so its key is one of them.',
+    headline: 'Invalid override key',
+});
+/** One key overridden twice inside one contributor. */
+const overrideTwice = registerRule('@loomcli/core/override-twice', {
+    explanation: 'Within one contributor, one key answers to one override, so two leave it unclear which the author meant. The same key overridden by two contributors resolves to the first installed.',
+    headline: 'Key overridden twice',
+});
+/** A `translate()` key that is not a class, or that is a failure class. */
+const translationKey = registerRule('@loomcli/core/translation-key', {
+    explanation: 'A translation keys on the foreign error class it replaces. Core offers a translator only a thrown value no failure class made, so the key is a class and never a failure class.',
+    headline: 'Invalid translation key',
+});
+/** An `onCommandAttach` hook that threw or returned a value that is not the attached Command. */
+const brokenAttachHook = registerRule('@loomcli/core/broken-attach-hook', {
+    explanation: "onCommandAttach receives each Command's declaration at graph build and returns it, or a value derived from it, synchronously and without throwing. Core builds the Command the hook returns, so a throw or any other value leaves it nothing to build.",
+    headline: 'Broken attach hook',
+});
+/** The retired `globals` or `failures` Application option. */
+const retiredApplicationOption = registerRule('@loomcli/core/retired-application-option', {
+    explanation: 'The Application no longer reads globals or failures. A global option is declared with globalOption(), so its type reaches every action, and a failure view is an override under views.',
+    headline: 'Retired Application option',
+});
+/** A packet that is not an object, or whose build is neither value. */
+const invalidPacket = registerRule('@loomcli/core/invalid-packet', {
+    explanation: 'The packet says whether the application was built for development, which decides whether a defect shows the author its Developer Diagnostic or the operator one generic message. Its build reads development or distributed.',
+    headline: 'Invalid packet',
+});
+/** A rendering policy that is not an object, or holds a setting outside its closed set. */
+const renderingPolicyRule = registerRule('@loomcli/core/rendering-policy', {
+    explanation: 'The rendering policy decides whether output carries color, modifiers, hyperlinks, and terminal controls. color, modifiers, and hyperlinks each read auto, always, or never, and terminalControls reads strip or preserve.',
+    headline: 'Invalid rendering policy',
+});
+/** A plugin theme that is not a mapping of names to unapplied concrete style chains. */
+const themeMapping = registerRule('@loomcli/core/theme-mapping', {
+    explanation: "A plugin's theme maps each name to an unapplied chain of concrete styles. A semantic token reads the theme itself, so a chain that holds one has no concrete style to resolve to.",
+    headline: 'Invalid theme mapping',
+});
+/** A theme name that a built-in style member already holds. */
+const themeNameTaken = registerRule('@loomcli/core/theme-name-taken', {
+    explanation: 'Each theme name becomes a member of the style object beside the built-in members, so a name a built-in already holds would hide it.',
+    headline: 'Theme name taken',
+});
+export { asyncExtensionSchema, brokenAttachHook, extensionOutput, extensionTarget, extensionValueTwice, extensionWithoutSchema, foreignValue, invalidExtensionValue, invalidIdentity, invalidPacket, middlewareActivation, notAFunction, notAList, notAnObject, overrideKey, overrideTwice, pluginInstalledTwice, pluginOptionRule, renderingPolicyRule, retiredApplicationOption, signalClaimedTwice, slotTaken, sourceBinding, sourceBoundOwnOption, themeMapping, themeNameTaken, translationKey, twoPackageCopies, unknownSignal, };

package/dist/plugin.d.ts

@@ -1,46 +1,36 @@
 import type { MiddlewareContext } from './chain.js';
-import type { AnyExtension, DescriptorRegistry, ExtensionRecords } from './extension.js';
+import type { AttachedChild, Command } from './command.js';
+import type { AdmittedDescriptor, AnyExtension, DescriptorRegistry } from './extension.js';
+import type { InputRecords } from './globals.js';
+import type { FailureHook } from './hints.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 { Translation, TranslationContributor } from './translators.js';
+import type { CommandAttachHook, Host, OptionValue, Out, PluginOptionConfig } from './types.js';
 import type { OptionInput } from './validation.js';
-import type { ViewContribution } from './view.js';
+import type { ViewContribution, ViewSubject } 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 +39,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 +51,39 @@ 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: `onCommandAttach` runs at graph build,
+ * `onFailure` runs when `run()` renders a failure, the middleware runs inside an invocation, the
+ * configuration source runs in the input-source stage when an unfilled option carries its binding,
+ * and a translator runs when a foreign throw its key matches leaves the application's work.
  */
 interface PluginDefinition<Options extends PluginOptions = PluginOptions, Theme extends ThemeMapping = ThemeMapping> {
     theme?: Theme & ThemeConstraint<Theme>;
@@ -74,59 +95,104 @@ interface PluginDefinition<Options extends PluginOptions = PluginOptions, Theme
         }>;
     };
     onCommandAttach?: CommandAttachHook;
+    onFailure?: FailureHook;
     extensions?: readonly AnyExtension[];
     views?: readonly ViewContribution[];
+    translators?: readonly Translation[];
     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.
+ * none of its code: `onCommandAttach` runs at graph build, `onFailure` runs when `run()` renders a
+ * failure, and the middleware runs inside an invocation, so an 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;
+/** The subject a plugin's `views` list reports under, and the call that declared it. */
+declare function pluginViews(identity: string): ViewSubject;
+/** 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(application: string, 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. */
     onCommandAttach: CommandAttachHook | undefined;
+    /** The hook core calls for each failure `run()` renders after graph build, or nothing. */
+    onFailure: FailureHook | undefined;
     /** The plugin's own `views` slot, read once the validated theme is in place. */
     views: unknown;
+    /** The translations the plugin registers, which resolve after the application's. */
+    translators: TranslationContributor;
     identity: string;
     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, AdmittedDescriptor>;
+    /** 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, pluginViews, pluginValues, };