@loomcli/core 0.5.0 → 0.6.0

package/dist/plugin.d.ts

@@ -1,15 +1,17 @@
 import type { MiddlewareContext } from './chain.js';
 import type { AttachedChild, Command } from './command.js';
-import type { AnyExtension, DescriptorRegistry } from './extension.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 { 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
@@ -78,9 +80,10 @@ interface SourceAnswer {
 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.
+ * 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>;
@@ -92,8 +95,10 @@ 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 & {
@@ -107,13 +112,16 @@ interface PluginDefinition<Options extends PluginOptions = PluginOptions, Theme
 }
 /**
  * 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. Every rule
+ * 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>>;
 /** 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;
@@ -126,7 +134,7 @@ interface InstalledPlugins {
  * 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;
+declare function installPlugins(application: string, plugins: unknown): InstalledPlugins;
 /**
  * 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
@@ -154,8 +162,12 @@ 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;
@@ -164,7 +176,7 @@ interface BuiltPlugin {
     /** 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>;
+    descriptors: ReadonlyMap<string, AdmittedDescriptor>;
     /** The extension record each of the plugin's own options carries. */
     records: InputRecords;
 }
@@ -183,4 +195,4 @@ declare function pluginValues(inputs: readonly OptionInput[], values: OptionValu
 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, BuiltSource, PluginValues, SourceAnswer, SourceContext, SourceResolver, Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionSpellings, PluginOptionValues, };
-export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginValues, };
+export { installPlugins, loadDefault, ownedSignals, plugin, pluginSentence, pluginSpellings, pluginViews, pluginValues, };