@loomcli/core 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -2,11 +2,17 @@ export { Application } from './application.js';
 export { Command } from './command.js';
 export { validationContext, validationContextKey } from './context.js';
 export { DeclarationError, FatalError, InputError, InternalError, LoomError, MissingValueError, NonCallableCommandError, RepeatedOptionError, ShortGroupError, UnexpectedArgumentError, UnexpectedValueError, UnknownCommandError, UnknownOptionError, UsageError, renderFailure, } from './errors.js';
+export { extension, readExtension } from './extension.js';
 export { GlobalOptions } from './globals.js';
+export { plugin } from './plugin.js';
 export { issuePath } from './validation.js';
 export type { StandardSchemaV1 } from '@standard-schema/spec';
 export type { ApplicationMethod, ApplicationOptions } from './application.js';
+export type { ChainOutcome, MiddlewareContext } from './chain.js';
 export type { FailureRenderer, InputProblem } from './errors.js';
-export type { CommandMethod } from './command.js';
+export type { AnyExtension, Extension, ExtensionValue } from './extension.js';
+export type { CommandMethod, CommandOptions } from './command.js';
+export type { CancellationReason } from './signals.js';
 export type { ArgumentNode, CommandGraph, CommandNode, OptionNode } from './inspect.js';
+export type { Middleware, OptionsOf, Plugin, PluginDefinition, PluginOptions, PluginOptionValues, } from './plugin.js';
 export type { Action, ActionArgs, ActionContext, ActionHandler, ActionOptions, ArgumentConfig, BooleanOption, ExitCode, Host, InputIdentity, InputTerminal, Out, OptionConfig, OutputTerminal, Renderer, RunOptions, ScalarArgument, StringOption, SuppliedInputs, ValidationContext, VariadicArgument, } from './types.js';

package/dist/index.js

@@ -2,5 +2,7 @@ export { Application } from './application.js';
 export { Command } from './command.js';
 export { validationContext, validationContextKey } from './context.js';
 export { DeclarationError, FatalError, InputError, InternalError, LoomError, MissingValueError, NonCallableCommandError, RepeatedOptionError, ShortGroupError, UnexpectedArgumentError, UnexpectedValueError, UnknownCommandError, UnknownOptionError, UsageError, renderFailure, } from './errors.js';
+export { extension, readExtension } from './extension.js';
 export { GlobalOptions } from './globals.js';
+export { plugin } from './plugin.js';
 export { issuePath } from './validation.js';

package/dist/inspect.d.ts

@@ -1,8 +1,8 @@
-import type { BuiltCommand } from './command.js';
-import type { BuiltGlobals } from './globals.js';
+import type { BuiltGraph } from './command.js';
 /** One declared argument. `default` wraps the declared value, so an explicit `undefined` shows. */
 interface ArgumentNode {
     readonly name: string;
+    readonly description: string | undefined;
     readonly required: boolean;
     readonly variadic: boolean;
     readonly validated: boolean;
@@ -10,11 +10,22 @@ interface ArgumentNode {
     readonly default: {
         readonly value: unknown;
     } | undefined;
+    readonly extensions: Readonly<Record<string, unknown>>;
 }
-/** One declared option, in the shape its type gives it. Spellings are the accepted CLI forms. */
+/**
+ * One declared option, in the shape its type gives it. Spellings are the accepted CLI forms, and
+ * `scope` tells an application's own option from a plugin option, which reaches no action.
+ * `hidden` is `false` unless the declaration says `true`, and `deprecated` is the declared
+ * migration message or `undefined`. A listing projection omits a hidden node and marks a
+ * deprecated one; parsing binds without reading either.
+ */
 type OptionNode = {
     readonly type: 'string';
     readonly name: string;
+    readonly description: string | undefined;
+    readonly hidden: boolean;
+    readonly deprecated: string | undefined;
+    readonly scope: 'application' | 'plugin';
     readonly long: string | null;
     readonly short: string | null;
     readonly required: boolean;
@@ -24,38 +35,61 @@ type OptionNode = {
     readonly default: {
         readonly value: unknown;
     } | undefined;
+    readonly extensions: Readonly<Record<string, unknown>>;
 } | {
     readonly type: 'boolean';
     readonly name: string;
+    readonly description: string | undefined;
+    readonly hidden: boolean;
+    readonly deprecated: string | undefined;
+    readonly scope: 'application' | 'plugin';
     readonly long: string | null;
     readonly short: string | null;
     readonly negative: string | null;
     readonly polarity: 'positive' | 'negative' | 'both';
+    readonly extensions: Readonly<Record<string, unknown>>;
 };
 /**
  * One Command in the graph. `name` is `null` for the root, and `path` is its route from it.
- * `aliases` holds the hidden aliases in declaration order, so a Command appears once, under its
- * canonical name, and `path` never holds an alias.
+ * `aliases` holds the aliases in declaration order, so a Command appears once, under its canonical
+ * name, and `path` never holds an alias. The root reports the Application's description, so a
+ * projection that walks nodes never special-cases it, and it reads `hidden: false` and
+ * `deprecated: undefined`, the two core facts a listing reads on every other node.
  */
 interface CommandNode {
     readonly name: string | null;
     readonly aliases: readonly string[];
     readonly path: readonly string[];
+    readonly description: string | undefined;
+    readonly hidden: boolean;
+    readonly deprecated: string | undefined;
     readonly hasAction: boolean;
     readonly arguments: readonly ArgumentNode[];
     readonly options: readonly OptionNode[];
     readonly children: readonly CommandNode[];
+    readonly extensions: Readonly<Record<string, unknown>>;
 }
-/** One built graph as plain data. The globals appear once here and in no `CommandNode`. */
+/**
+ * One built graph as plain data. The globals appear once here and in no `CommandNode`. `version`
+ * and `description` are the Application's own core facts. `version` is the declared string, or
+ * `0.0.0` when the Application declares none, so it is never `undefined`. `description` stays
+ * `undefined` where the Application declares none.
+ */
 interface CommandGraph {
     readonly name: string;
+    readonly version: string;
+    readonly description: string | undefined;
     readonly globals: readonly OptionNode[];
     readonly root: CommandNode;
 }
-/** Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. */
-declare function inspectGraph(name: string, graph: {
-    globals: BuiltGlobals;
-    root: BuiltCommand;
+/**
+ * Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. The
+ * globals list holds the application's own options, then each installed plugin's in installation
+ * order, which is the order the globals table holds them in.
+ */
+declare function inspectGraph(name: string, graph: BuiltGraph, facts: {
+    description: string | undefined;
+    version: string;
 }): CommandGraph;
 export type { ArgumentNode, CommandGraph, CommandNode, OptionNode };
 export { inspectGraph };

package/dist/inspect.js

@@ -1,4 +1,7 @@
+import { isPlainObject } from './facts.js';
 import { validatesOmission } from './validation.js';
+/** A declaration that carries no extension value publishes one shared, empty frozen record. */
+const noExtensions = Object.freeze({});
 /**
  * Reads the spellings out of the compiled table the parser uses, so inspection cannot report a
  * form the parser does not accept. Each entry carries its own role, so the naming convention has
@@ -13,14 +16,6 @@ function spellingsOf(table, name) {
     }
     return spellings;
 }
-/** A structural value core can copy faithfully. Anything else is a library object it leaves alone. */
-function isPlainObject(value) {
-    if (value === null || typeof value !== 'object') {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
 /**
  * A snapshot of one declared value. Arrays and plain objects are copied and frozen to any depth, so
  * a consumer cannot reach the declaration through the graph, and a later call reports the declared
@@ -39,18 +34,40 @@ function snapshot(value) {
 function declaredDefault(config) {
     return 'default' in config ? Object.freeze({ value: snapshot(config.default) }) : undefined;
 }
-function optionNode(input, table) {
+/** One declaration's extension record, which is the shared empty one when it carries no value. */
+function extensionsOf(records, declaration) {
+    return records.get(declaration) ?? noExtensions;
+}
+function optionNode(input, { records, scope, table }) {
     const { config, name } = input;
     const { long, negative, short } = spellingsOf(table, name);
+    const extensions = extensionsOf(records, input);
     const node = config.type === 'boolean'
-        ? { long, name, negative, polarity: config.polarity ?? 'positive', short, type: 'boolean' }
+        ? {
+            deprecated: config.deprecated,
+            description: config.description,
+            extensions,
+            hidden: config.hidden === true,
+            long,
+            name,
+            negative,
+            polarity: config.polarity ?? 'positive',
+            scope,
+            short,
+            type: 'boolean',
+        }
         : {
             default: declaredDefault(config),
+            deprecated: config.deprecated,
+            description: config.description,
+            extensions,
+            hidden: config.hidden === true,
             long,
             // The parser reads the same test, so a collection reports as one here and there.
             multiple: config.multiple === true,
             name,
             required: config.required === true,
+            scope,
             short,
             type: 'string',
             validateOmitted: validatesOmission(input),
@@ -59,10 +76,12 @@ function optionNode(input, table) {
     return Object.freeze(node);
 }
 /** The built slots already answer presence and arity, so the node repeats no config reading. */
-function argumentNode(slot) {
+function argumentNode(slot, records) {
     const { config, name } = slot.input;
     const node = {
         default: declaredDefault(config),
+        description: config.description,
+        extensions: extensionsOf(records, slot.input),
         name,
         required: slot.required,
         validateOmitted: validatesOmission(slot.input),
@@ -71,27 +90,51 @@ function argumentNode(slot) {
     };
     return Object.freeze(node);
 }
-function optionNodes(inputs, table) {
-    return Object.freeze(inputs.filter((input) => input.kind === 'option').map((input) => optionNode(input, table)));
+function optionNodes(inputs, read) {
+    return inputs.filter((input) => input.kind === 'option').map((input) => optionNode(input, read));
 }
-function commandNode(command, path) {
+/**
+ * One Command as frozen plain data. A child reports the description its own declaration carries,
+ * and the root reports the Application's, which is why the caller supplies that one.
+ */
+function commandNode(command, place) {
+    const { path, records } = place;
     const node = {
         aliases: Object.freeze([...command.aliases]),
-        arguments: Object.freeze(command.arguments.map((slot) => argumentNode(slot))),
-        children: Object.freeze([...command.children].map(([name, child]) => commandNode(child, Object.freeze([...path, name])))),
+        arguments: Object.freeze(command.arguments.map((slot) => argumentNode(slot, records))),
+        children: Object.freeze([...command.children].map(([name, child]) => commandNode(child, { path: Object.freeze([...path, name]), records }))),
+        deprecated: command.deprecated,
+        description: 'description' in place ? place.description : command.description,
+        extensions: command.extensions,
         hasAction: command.dispatch !== undefined,
+        hidden: command.hidden,
         name: command.name,
-        options: optionNodes(command.inputs, command.options),
+        options: Object.freeze(optionNodes(command.inputs, { records, scope: 'application', table: command.options })),
         path,
     };
     return Object.freeze(node);
 }
-/** Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. */
-function inspectGraph(name, graph) {
+/**
+ * Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. The
+ * globals list holds the application's own options, then each installed plugin's in installation
+ * order, which is the order the globals table holds them in.
+ */
+function inspectGraph(name, graph, facts) {
+    const records = graph.extensions;
+    const table = graph.globals.options;
     const inspected = {
-        globals: optionNodes(graph.globals.inputs, graph.globals.options),
+        description: facts.description,
+        globals: Object.freeze([
+            ...optionNodes(graph.globals.inputs, { records, scope: 'application', table }),
+            ...graph.globals.plugins.flatMap((installed) => optionNodes(installed.inputs, { records, scope: 'plugin', table })),
+        ]),
         name,
-        root: commandNode(graph.root, Object.freeze([])),
+        root: commandNode(graph.root, {
+            description: facts.description,
+            path: Object.freeze([]),
+            records,
+        }),
+        version: facts.version,
     };
     return Object.freeze(inspected);
 }

package/dist/options.d.ts

@@ -22,6 +22,13 @@ type OptionForm = {
 type OptionSpelling = OptionForm & {
     role: SpellingRole;
 };
+/**
+ * One Boolean option's value for one invocation: the value the parser consumed, or the value its
+ * declared polarity gives an absent option. A negative-only option is absent as `true`, because its
+ * one spelling turns the value off. Every scope reads it here, so a plugin option and a validated
+ * declaration answer the same rule.
+ */
+export declare function booleanValue(values: OptionValues, name: string, config: OptionConfig): boolean;
 export declare function compileOptions(declarations: readonly OptionDeclaration[], subject: string): Map<string, OptionSpelling>;
 /** Consumes global options anywhere before the passthrough delimiter and leaves the rest routable. */
 export declare function extractGlobals(spellings: ReadonlyMap<string, OptionSpelling>, tokens: readonly string[]): {

package/dist/options.js

@@ -48,6 +48,15 @@ function addSpelling(spellings, spelling, option) {
     }
     spellings.set(spelling, option);
 }
+/**
+ * One Boolean option's value for one invocation: the value the parser consumed, or the value its
+ * declared polarity gives an absent option. A negative-only option is absent as `true`, because its
+ * one spelling turns the value off. Every scope reads it here, so a plugin option and a validated
+ * declaration answer the same rule.
+ */
+export function booleanValue(values, name, config) {
+    return values.booleans.get(name) ?? config.polarity === 'negative';
+}
 export function compileOptions(declarations, subject) {
     const spellings = new Map();
     const names = new Set();

package/dist/plugin.d.ts

@@ -0,0 +1,116 @@
+import type { MiddlewareContext } from './chain.js';
+import type { FailureRenderer } from './errors.js';
+import type { AnyExtension, DescriptorRegistry, ExtensionRecords } from './extension.js';
+import type { ProcessSignal } from './signals.js';
+import type { OptionValue, PluginOptionConfig } from './types.js';
+import type { OptionInput } from './validation.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.
+ */
+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]>;
+};
+/** Phantom key. It carries a plugin's declared options in a read position and holds no value. */
+declare const pluginOptions: 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 {
+    options?: PluginOptions;
+    middleware?: {
+        activate?: unknown;
+        load?: unknown;
+    };
+    extensions?: readonly AnyExtension[];
+    failures?: readonly FailureRenderer[];
+    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 `failures` holds
+ * renderers for different classes, and `Middleware` and `load` accept a narrower plugin.
+ */
+declare class PluginDeclaration<Options extends PluginOptions> {
+    readonly [pluginOptions]: () => Options;
+    constructor(node: PluginNode);
+}
+/**
+ * One plugin, as the opaque value `plugin()` returns. The declarations behind it stay private to
+ * this package, so no consumer can read or replace them.
+ */
+type Plugin<Options extends PluginOptions = PluginOptions> = Pick<PluginDeclaration<Options>, typeof pluginOptions>;
+/** The declared options of a plugin, or of the factory that returns one. */
+type OptionsOf<Contributor> = Contributor extends Plugin<infer Options> ? Options : Contributor extends (...args: never[]) => Plugin<infer Options> ? Options : PluginOptions;
+/** 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. It holds declarations alone and performs no work. */
+interface PluginDefinition<Options extends PluginOptions = PluginOptions> {
+    options?: Options;
+    middleware?: {
+        activate: 'always' | readonly (keyof Options & string)[];
+        load: () => Promise<{
+            default: Middleware<Plugin<Options>>;
+        }>;
+    };
+    extensions?: readonly AnyExtension[];
+    failures?: readonly FailureRenderer[];
+    signals?: readonly ('SIGINT' | 'SIGTERM')[];
+}
+/**
+ * One plugin: an identity and the declarations it contributes. The value performs no work when it
+ * is created and none when it is installed, so an installed plugin an invocation never reaches
+ * costs that invocation nothing.
+ */
+declare function plugin<Options extends PluginOptions = PluginOptions>(identity: string, definition: PluginDefinition<Options>): Plugin<Options>;
+/** 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 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.
+ */
+declare function installPlugins(plugins: unknown): readonly InstalledPlugin[];
+/** 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. */
+interface BuiltPlugin {
+    failures: readonly FailureRenderer[];
+    identity: string;
+    inputs: readonly OptionInput[];
+    middleware: BuiltMiddleware | undefined;
+    signals: readonly ProcessSignal[];
+}
+/** 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[];
+export type { BuiltPlugin, InstalledPlugin, Middleware, OptionsOf, Plugin, PluginBuild, PluginDefinition, PluginOptions, PluginOptionValues, };
+export { buildPlugins, installPlugins, ownedSignals, plugin, pluginSentence };