@loomcli/core 0.1.1 → 0.3.0

package/dist/command.js

@@ -1,5 +1,9 @@
-import { commandSentence, commandSubject, DeclarationError, NonCallableCommandError, UnexpectedArgumentError, UnknownCommandError, } from './errors.js';
-import { bindGlobals, buildGlobals } from './globals.js';
+var _a;
+import { commandSentence, commandSubject, DeclarationError, NonCallableCommandError, ResultError, UnexpectedArgumentError, UnknownCommandError, } from './errors.js';
+import { buildCommandExtensions, buildExtensions } from './extension.js';
+import { checkDeprecated, checkDescription, checkHidden, checkNoListingFacts, isPlainObject, } from './facts.js';
+import { buildGlobals, keyCollision, spellingCollision } from './globals.js';
+import { resultNode, snapshot } from './inspect.js';
 import { compileOptions, extractGlobals, mergeValues, parseInputs } from './options.js';
 import { captureConfig, validateValues } from './validation.js';
 /** Authored values register here, so the public type publishes no state to reach or replace. */
@@ -12,6 +16,15 @@ function nodeOf(parent, child) {
     }
     return node;
 }
+/** Reject retired globals wiring at graph build, before any invocation reads the options. */
+function checkCommandOptions(name, options) {
+    if (options !== undefined && !isPlainObject(options)) {
+        throw new DeclarationError(`${commandSentence(name)} options must be an object. Supply a Command options object.`);
+    }
+    if (isPlainObject(options) && 'globals' in options) {
+        throw new DeclarationError(`${commandSentence(name)} declares globals. Declare globals on the Application and register its environment.`);
+    }
+}
 /** One name rule for every declared name in the graph, so a child and an argument read alike. */
 function isDeclaredName(name) {
     return typeof name === 'string' && Boolean(name) && !name.startsWith('-') && !/[\s=]/u.test(name);
@@ -27,17 +40,26 @@ function checkAliasName(command, alias) {
         throw new DeclarationError(`${commandSentence(command)} declares an alias named "${String(alias)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
     }
 }
-/** The state every declaration starts from. The unnamed root and each named Command share it. */
-export function freshState(name, globals) {
+/**
+ * The state every declaration starts from. The unnamed root and each named Command share it.
+ * The declaration values arrive captured, because a later change to the options object the author
+ * passed changes nothing the declaration holds.
+ */
+export function freshState(declaration) {
     return {
         actions: [],
         aliases: [],
         bind: () => ({ args: {}, options: {} }),
         children: [],
-        globals,
+        deprecated: declaration.deprecated,
+        description: declaration.description,
+        extensions: [declaration.extensions],
+        hidden: declaration.hidden,
         inputs: [],
         late: [],
-        name,
+        name: declaration.name,
+        options: declaration.options,
+        results: [],
     };
 }
 /** A declaration after the action is an order fault; build reports the first one recorded. */
@@ -70,6 +92,15 @@ export function declareOption(state, input) {
         late: recordLate(state, [{ input, kind: 'input' }]),
     };
 }
+/** Globals close when composition starts; retain late calls for the shared build-order check. */
+export function recordGlobalOption(state, name) {
+    return {
+        ...state,
+        late: state.actions.length > 0 || state.children.length > 0
+            ? [...state.late, { kind: 'global', name }]
+            : state.late,
+    };
+}
 /** One call's names stay one group, so the empty call the types reject still reports as one. */
 export function declareAlias(state, names) {
     return {
@@ -78,8 +109,47 @@ export function declareAlias(state, names) {
         late: recordLate(state, names.map((alias) => ({ alias, kind: 'alias' }))),
     };
 }
+/** Extension layers remain open after inputs and the action have been fixed. */
+export function declareExtensions(state, values) {
+    return { ...state, extensions: [...state.extensions, values] };
+}
+/**
+ * The same channel, read as the result the handler's own declaration names. The value one call
+ * emits is checked where the action was authored, and the channel core hands an action accepts
+ * whatever the routed declaration named, so this reading adds no promise the run does not keep.
+ */
+function declaredChannel(out) {
+    return { ...out, results: (value) => out.results(value) };
+}
+/**
+ * The handler is typed against the result its own declaration carries, and the state holds one
+ * list for every declaration, so the context each handler receives is read back at the call.
+ */
 export function declareAction(state, handler) {
-    return { ...state, actions: [...state.actions, handler] };
+    const stored = (context) => handler({ ...context, out: declaredChannel(context.out) });
+    return { ...state, actions: [...state.actions, stored] };
+}
+/** The result declaration, which closes both result calls and reports lateness like the rest. */
+export function declareResult(state, kind, declaration) {
+    return {
+        ...state,
+        late: recordLate(state, [{ kind: 'result' }]),
+        results: [...state.results, { kind, views: recordOf(declaration, 'views') }],
+    };
+}
+/** A `views()` call reshapes views and closes nothing, so it is never a late declaration. */
+export function declareResultViews(state, replacements, options) {
+    return {
+        ...state,
+        results: [
+            ...state.results,
+            { default: recordOf(options, 'default'), kind: 'views', views: replacements },
+        ],
+    };
+}
+/** One property of an authoring argument, read defensively: build reports whatever it holds. */
+function recordOf(declaration, key) {
+    return isPlainObject(declaration) ? declaration[key] : undefined;
 }
 /** Attaching is a declaration call too, so the receiver keeps the children it already had. */
 export function attachChild(state, child) {
@@ -96,12 +166,18 @@ function checkDeclarationOrder(state) {
     if (!late) {
         return;
     }
+    if (late.kind === 'global') {
+        throw new DeclarationError(`The Application declares global option "${late.name}" after command() or action(). Declare global options before attaching Commands or registering an action.`);
+    }
     if (late.kind === 'input') {
         throw new DeclarationError(`${commandSentence(name)} declares ${late.input.kind} "${late.input.name}" after its action. Declare arguments and options before action().`);
     }
     if (late.kind === 'alias') {
         throw new DeclarationError(`${commandSentence(name)} declares alias "${late.alias}" after its action. Declare aliases before action().`);
     }
+    if (late.kind === 'result') {
+        throw new DeclarationError(`${commandSentence(name)} declares its result after its action. Declare result() or rows() before action().`);
+    }
     // Child identity and names are settled before this call, so the node and its name are valid.
     throw new DeclarationError(`${commandSentence(name)} attaches child "${String(nodeOf(name, late.child).name)}" after its action. Attach children before action().`);
 }
@@ -177,7 +253,7 @@ function buildChild(parent, [name, node], context) {
         throw new DeclarationError(`${commandSentence(parent)} attaches child "${name}", which ${commandSubject(owner)} also attaches. Attach a Command value at one point; create a new Command for each placement.`);
     }
     context.owners.set(node, parent);
-    return node.build(context);
+    return node.build({ ...context, path: [...context.path, name] });
 }
 /** A variadic or optional slot ends the positional list, so nothing may follow either one. */
 function checkSlotOrder(slot, next, subject) {
@@ -216,18 +292,26 @@ function collectArguments(state, subject) {
     }
     return slots;
 }
+/**
+ * One Command's own options against the shared globals table. The table holds the application's
+ * globals and every plugin option, so a local collision reads the same sentence whichever scope on
+ * the other side claimed the name or the spelling.
+ */
 function compileLocalOptions(state, globals, subject) {
     const declarations = state.inputs.filter((input) => input.kind === 'option');
+    const local = { kind: 'local', subject };
+    const application = { kind: 'application' };
     for (const declaration of declarations) {
-        if (globals.names.has(declaration.name)) {
-            throw new DeclarationError(`Option "${declaration.name}" is declared as a global option and as a local option on ${subject}. Rename the local option.`);
+        const claimed = globals.names.get(declaration.name);
+        if (claimed) {
+            throw keyCollision(declaration.name, claimed, local);
         }
     }
     const options = compileOptions(declarations, subject);
     for (const [spelling, option] of options) {
         const global = globals.options.get(spelling);
         if (global) {
-            throw new DeclarationError(`Option spelling "${spelling}" is used by the global option "${global.name}" and the local option "${option.name}" on ${subject}. Change one declaration.`);
+            throw spellingCollision(spelling, { name: global.name, owner: globals.names.get(global.name) ?? application }, { name: option.name, owner: local });
         }
     }
     return options;
@@ -247,44 +331,483 @@ function checkGroup(state, children) {
         throw new DeclarationError(`${commandSentence(name)} declares option "${option.name}" but registers no action to receive it. Register an action or remove the option.`);
     }
 }
+/**
+ * A view name is a bare token the way a child name is, and never an array index, because an
+ * integer-like key does not keep the position the author gave it.
+ */
+function isViewName(name) {
+    return isDeclaredName(name) && !/^(?:0|[1-9]\d*)$/u.test(name);
+}
+/** One entry read back as the whole view its own `render` function names. */
+function isWholeView(entry) {
+    return (typeof entry === 'object' &&
+        entry !== null &&
+        'render' in entry &&
+        typeof entry.render === 'function');
+}
+/** The same reading for the row shape, which core feeds one row at a time. */
+function isRowView(entry) {
+    return (typeof entry === 'object' && entry !== null && 'row' in entry && typeof entry.row === 'function');
+}
+/**
+ * The key one `views()` call selected, spelled the way its own diagnostic names it. A call that
+ * names none keeps whichever key an earlier call named.
+ */
+function selectedKey(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return typeof value === 'string' ? value : (JSON.stringify(value) ?? 'undefined');
+}
+/** The entries one authored `views` record holds, in record order; anything else holds none. */
+function recordEntries(record) {
+    return isPlainObject(record) ? Object.entries(record) : [];
+}
+/**
+ * One `views` entry under the unit its declaration named, read back as the shape its own functions
+ * name. The two shapes are exclusive, and a row view answers a rows declaration alone.
+ */
+function resultView(declaration, name, entry) {
+    const { kind, sentence } = declaration;
+    const whole = isWholeView(entry);
+    const row = isRowView(entry);
+    if (whole && row) {
+        throw new DeclarationError(`${sentence} names view "${name}" with render and row. Supply one of the two.`);
+    }
+    if (row) {
+        if (kind === 'value') {
+            throw new DeclarationError(`${sentence} names row view "${name}" on a value result. Supply a view with render, or declare the result with rows().`);
+        }
+        return entry;
+    }
+    if (whole) {
+        return entry;
+    }
+    throw new DeclarationError(`${sentence} names view "${name}" with a value that is not a view. Supply a view with render or a row view with row.`);
+}
+/**
+ * Every rule the results lane carries, applied to one Command's calls in the order it made them.
+ * The merged record is what the rules read: a later `views()` call replaces a key in place and
+ * appends a new one, so each name keeps the position the call that first named it gave it. A
+ * `default` once named persists through later calls that name none, and the first key answers
+ * until one is named.
+ */
+function buildResult(state, hasAction) {
+    const sentence = commandSentence(state.name);
+    const declarations = state.results.filter((call) => call.kind !== 'views');
+    if (declarations.length > 1) {
+        throw new DeclarationError(`${sentence} declares two results. Declare one result() or rows() call.`);
+    }
+    const declaration = declarations[0];
+    // A `views()` call reshapes a result's views, so one with no result reshapes nothing.
+    // The types publish the call where a result is carried, so this reaches a JavaScript author.
+    if (!declaration) {
+        if (state.results.length > 0) {
+            throw new DeclarationError(`${sentence} reshapes its views and declares no result. Declare result() or rows() before action().`);
+        }
+        return undefined;
+    }
+    if (!hasAction) {
+        throw new DeclarationError(`${sentence} declares a result and no action. Register an action or remove the result.`);
+    }
+    const views = new Map();
+    let selected = undefined;
+    for (const call of state.results) {
+        for (const [name, entry] of recordEntries(call.views)) {
+            const view = resultView({ kind: declaration.kind, sentence }, name, entry);
+            if (!isViewName(name)) {
+                throw new DeclarationError(`${sentence} names view "${name}". Use a nonempty name without whitespace, a leading hyphen, or "=", and not a number.`);
+            }
+            views.set(name, view);
+        }
+        if (call.kind === 'views') {
+            selected = selectedKey(call.default) ?? selected;
+        }
+    }
+    const first = views.keys().next();
+    if (first.done === true) {
+        throw new DeclarationError(`${sentence} declares a result with no views. Name at least one view.`);
+    }
+    if (selected !== undefined && !views.has(selected)) {
+        throw new DeclarationError(`${sentence} selects default view "${selected}", which it does not name. Name the view or select a named one.`);
+    }
+    return { default: selected ?? first.value, kind: declaration.kind, views };
+}
+/** The values one build made, so a value a hook returns is one of them and never a forged shape. */
+const attachments = new WeakMap();
+/**
+ * The declared names of one kind, in declaration order, as a hook reads them. The list is frozen,
+ * because the surface publishes it read-only and a hook reshapes a Command through its calls alone.
+ */
+function declaredNames(declared, kind) {
+    return Object.freeze(declared.inputs.filter((input) => input.kind === kind).map((input) => input.name));
+}
+/**
+ * One Command unlocked for a hook. Every call returns a new value and leaves its receiver
+ * unchanged, and records what it added twice over: on the erased declaration the next value reads
+ * its facts from, and on the call list the declaration reads back once every hook has returned.
+ * The result is resolved for each value, so a `views()` call reports its own fault where it is made
+ * and a later call reads the record that call left behind.
+ */
+class AttachedCommandValue {
+    #state;
+    #result;
+    constructor(state) {
+        this.#state = state;
+        this.#result = resultNode(buildResult(state.declared, state.hasAction));
+        attachments.set(this, state);
+        Object.freeze(this);
+    }
+    get name() {
+        return this.#state.declared.name;
+    }
+    get path() {
+        return this.#state.path;
+    }
+    get hasAction() {
+        return this.#state.hasAction;
+    }
+    get arguments() {
+        return declaredNames(this.#state.declared, 'argument');
+    }
+    get options() {
+        return declaredNames(this.#state.declared, 'option');
+    }
+    get result() {
+        return this.#result;
+    }
+    argument(name, config) {
+        return this.#declare({ config: captureConfig(config), kind: 'argument', name });
+    }
+    option(name, config) {
+        return this.#declare({ config: captureConfig(config), kind: 'option', name });
+    }
+    views(replacements, options) {
+        const call = {
+            default: recordOf(options, 'default'),
+            kind: 'views',
+            views: replacements,
+        };
+        const { declared } = this.#state;
+        return this.#derive({ call, kind: 'views' }, { ...declared, results: [...declared.results, call] });
+    }
+    extend(...values) {
+        return this.#derive({ kind: 'extend', values }, this.#state.declared);
+    }
+    /** One input the running hook declared, which the Command's own names now hold. */
+    #declare(input) {
+        const { declared, identity } = this.#state;
+        return this.#derive({ identity, input, kind: 'input' }, { ...declared, inputs: [...declared.inputs, input] });
+    }
+    #derive(call, declared) {
+        const state = this.#state;
+        return new _a({ ...state, calls: [...state.calls, call], declared });
+    }
+}
+_a = AttachedCommandValue;
+/** The reason one failed hook reports, which is the thrown value's own message. */
+function attachReason(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** One hook's own call, whose failure is the plugin's, and whose own report is its own. */
+function callHook(value, hook, named) {
+    try {
+        return hook(value);
+    }
+    catch (error) {
+        // A hook that reports a declaration fault of its own reports as itself.
+        if (error instanceof DeclarationError) {
+            throw error;
+        }
+        throw new DeclarationError(`Plugin "${named.identity}" failed in onCommandAttach for ${named.subject}: ${attachReason(error)}.`);
+    }
+}
+/**
+ * One plugin's hook over one Command, which answers with the declaration the hook returned. The
+ * returned value has to carry the lineage token of the value the hook received, so the surface of
+ * another Command, or of one an earlier build made, never replays its calls onto this Command.
+ */
+function attachOnce(value, hook, named) {
+    const state = attachments.get(callHook(value, hook, named));
+    if (!state || state.lineage !== named.lineage) {
+        throw new DeclarationError(`Plugin "${named.identity}" returned a value that is not the attached Command from onCommandAttach for ${named.subject}. Return the value it received or a value derived from it.`);
+    }
+    return state;
+}
+/**
+ * Every installed plugin's hook over one Command, in installation order, each receiving what the
+ * previous returned. The calls they made travel back to the declaration the remaining rules read.
+ */
+function runAttachHooks(declared, facts, plugins) {
+    const subject = commandSubject(declared.name);
+    const { lineage } = facts;
+    let progress = { calls: [], declared };
+    for (const installed of plugins) {
+        const hook = installed.onCommandAttach;
+        if (hook) {
+            const identity = installed.identity;
+            const value = new AttachedCommandValue({ ...progress, ...facts, identity });
+            const state = attachOnce(value, hook, { identity, lineage, subject });
+            progress = { calls: state.calls, declared: state.declared };
+        }
+    }
+    return progress.calls;
+}
+/**
+ * One input a hook declared. It joins the values an action reads at run time and the declaration's
+ * types not at all, and it records no late declaration, because a hook's calls are exempt from the
+ * closures `action()` applies.
+ */
+function declareHookInput(state, input) {
+    const previous = state.bind;
+    return {
+        ...state,
+        bind: (values) => {
+            const bound = previous(values);
+            return input.kind === 'argument'
+                ? { ...bound, args: { ...bound.args, ...values.argument(input) } }
+                : { ...bound, options: { ...bound.options, ...values.option(input) } };
+        },
+        inputs: [...state.inputs, input],
+    };
+}
+/** The declaration the hooks left behind, which every remaining build rule reads. */
+function applyAttachCalls(state, calls) {
+    let next = state;
+    for (const call of calls) {
+        if (call.kind === 'input') {
+            next = declareHookInput(next, call.input);
+        }
+        else if (call.kind === 'views') {
+            next = { ...next, results: [...next.results, call.call] };
+        }
+        else {
+            next = declareExtensions(next, call.values);
+        }
+    }
+    return next;
+}
+/** The clause and the remedy an input another plugin's hook already declared earns. */
+function hookClause(kind, identity) {
+    return {
+        clause: `an ${kind} plugin "${identity}" declared through onCommandAttach`,
+        remedy: 'Install one of them.',
+    };
+}
+/**
+ * The remedy a collision against the Command's own declarations, the globals table, or another
+ * plugin's option earns. The remedy follows the target alone, whichever kind the hook declared:
+ * the author renames their own local option or argument, the author renames the colliding global
+ * option, or, when the target is another plugin's option, the two plugins install one of them.
+ */
+function attachedRemedy(target) {
+    if (target === 'local') {
+        return "Rename the Command's option or omit the plugin.";
+    }
+    if (target === 'argument') {
+        return "Rename the Command's argument or omit the plugin.";
+    }
+    if (target === 'global') {
+        return 'Rename the global option or omit the plugin.';
+    }
+    return 'Install one of them.';
+}
+/**
+ * What one name a hook-declared input of either kind collides with, in the order the scopes are
+ * reported: an earlier hook's option, an earlier hook's argument, a local option, a global or
+ * plugin-owned option, or an argument the Command declares. The remedy follows the target alone,
+ * not which kind the hook declared.
+ */
+function attachedCollision(input, held) {
+    const { name } = input;
+    const hook = held.hooks.get(name);
+    if (hook !== undefined) {
+        return hookClause('option', hook);
+    }
+    const hooked = held.hookArguments.get(name);
+    if (hooked !== undefined) {
+        return hookClause('argument', hooked);
+    }
+    if (held.locals.has(name)) {
+        return { clause: 'a local option', remedy: attachedRemedy('local') };
+    }
+    const claimed = held.globals.names.get(name);
+    if (claimed) {
+        const target = claimed.kind === 'plugin' ? 'plugin' : 'global';
+        const clause = claimed.kind === 'plugin' ? `an option of plugin "${claimed.identity}"` : 'a global option';
+        return { clause, remedy: attachedRemedy(target) };
+    }
+    return held.arguments.has(name)
+        ? { clause: 'an argument', remedy: attachedRemedy('argument') }
+        : undefined;
+}
+/**
+ * The spellings one compiled table holds, each under the form its own option is named by, which is
+ * its long form where it declares one and the colliding spelling itself where it declares none.
+ */
+function readSpellings(table, claimed) {
+    const longs = new Map();
+    for (const [spelling, option] of table) {
+        if (option.role === 'long') {
+            longs.set(option.name, spelling);
+        }
+    }
+    for (const [spelling, option] of table) {
+        if (!claimed.has(spelling)) {
+            claimed.set(spelling, longs.get(option.name) ?? spelling);
+        }
+    }
+}
+/** One hook-declared option's spellings, against every spelling the table already claims. */
+function checkAttachedSpelling(declared, named) {
+    const { claimed, subject } = named;
+    const table = compileOptions([declared.input], subject);
+    for (const [spelling] of table) {
+        const used = claimed.get(spelling);
+        if (used !== undefined) {
+            throw new DeclarationError(`Plugin "${declared.identity}" declares option "${declared.input.name}" with spelling "${spelling}" on ${subject}, which "${used}" already uses.`);
+        }
+    }
+    readSpellings(table, claimed);
+}
+/**
+ * Every input a hook declared, against the names and spellings the Command, the globals table, and
+ * an earlier hook already hold. It runs before the Command's own inputs compile, so a hook-declared
+ * input reports as the plugin's fault and never as the author's.
+ */
+function checkAttachedInputs(declared, attached, globals) {
+    const subject = commandSubject(declared.name);
+    const hooked = new Set(attached.map((entry) => entry.input));
+    const authored = declared.inputs.filter((input) => !hooked.has(input));
+    const options = authored.filter((input) => input.kind === 'option');
+    const held = {
+        arguments: new Set(authored.filter((input) => input.kind === 'argument').map((input) => input.name)),
+        globals,
+        hookArguments: new Map(),
+        hooks: new Map(),
+        locals: new Set(options.map((input) => input.name)),
+    };
+    const claimed = new Map();
+    readSpellings(globals.options, claimed);
+    readSpellings(compileOptions(options, subject), claimed);
+    for (const { identity, input } of attached) {
+        const collision = attachedCollision(input, held);
+        if (collision) {
+            throw new DeclarationError(`Plugin "${identity}" declares ${input.kind} "${input.name}" on ${subject}, which is already declared as ${collision.clause}. ${collision.remedy}`);
+        }
+        if (input.kind === 'option') {
+            checkAttachedSpelling({ identity, input }, { claimed, subject });
+            held.hooks.set(input.name, identity);
+        }
+        else {
+            held.hookArguments.set(input.name, identity);
+        }
+    }
+}
 /** Binds one Command's declarations to its action, so an action reads only validated values. */
-function bindDispatch(state, action) {
-    return ({ host, out, passthrough, values }) => {
+function bindDispatch(state, action, globals) {
+    return ({ host, out, passthrough, signal, style, values }) => {
         const bound = state.bind(values);
+        // Last resort: no typed path exists.
+        // The graph erases the binder's generic relationship.
+        // It holds because attachment checks the global output requirement.
+        // Graph build rejects a collision between a global and a local.
+        // This binder returns the Application's validated globals alone.
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        const globalOptions = globals.bind(values);
         return action({
             args: bound.args,
             host,
-            options: { ...bindGlobals(state.globals, values), ...bound.options },
+            options: { ...globalOptions, ...bound.options },
             out,
             passthrough,
+            signal,
+            style,
         });
     };
 }
+/** Each declaration's own facts and extension values, whichever scope declared it. */
+function checkInputFacts(inputs, command, context) {
+    const { name, subject } = command;
+    for (const input of inputs) {
+        const sentence = `${commandSentence(name)} ${input.kind} "${input.name}"`;
+        checkDescription(sentence, input.config.description);
+        if (input.kind === 'argument') {
+            checkNoListingFacts(sentence, input.config);
+        }
+        else {
+            checkHidden(sentence, input.config.hidden);
+            checkDeprecated(sentence, input.config.deprecated);
+        }
+        context.extensions.set(input, buildExtensions({
+            declared: input.config.extensions,
+            descriptors: context.descriptors,
+            subject: { phrase: `on ${subject} ${input.kind} "${input.name}"`, sentence },
+            target: input.kind,
+        }));
+    }
+}
+/** One Command declares arguments or attaches children, whichever declaration made each of them. */
+function checkArgumentPlacement(name, slot, child) {
+    if (slot && child) {
+        throw new DeclarationError(`${commandSentence(name)} declares argument "${slot.input.name}" and attaches child "${child[0]}". Move the argument into a child Command or remove the children.`);
+    }
+}
 /** Validates one declaration against the shared globals table and compiles it for dispatch. */
 export function buildCommand(state, context) {
     const { actions, name } = state;
     const { globals } = context;
     const subject = commandSubject(name);
-    if (state.globals !== globals.source) {
-        throw new DeclarationError(`${commandSentence(name)} holds a different GlobalOptions value than its Application. Share one GlobalOptions value across the declarations.`);
-    }
+    const layer = { phrase: `on ${subject}`, sentence: commandSentence(name) };
+    checkCommandOptions(name, state.options);
+    const description = checkDescription(commandSentence(name), state.description);
+    const hidden = checkHidden(commandSentence(name), state.hidden);
+    const deprecated = checkDeprecated(commandSentence(name), state.deprecated);
+    const declaredExtensions = buildCommandExtensions({
+        descriptors: context.descriptors,
+        layers: state.extensions,
+        subject: layer,
+    });
+    // Each declaration's own facts, in authoring order, before the rules that pair declarations.
+    checkInputFacts(state.inputs, { name, subject }, context);
     const attached = collectChildren(state);
     checkDeclarationOrder(state);
     const aliases = collectAliases(state);
-    const slots = collectArguments(state, subject);
-    const first = slots[0];
-    const child = attached[0];
-    if (first && child) {
-        throw new DeclarationError(`${commandSentence(name)} declares argument "${first.input.name}" and attaches child "${child[0]}". Move the argument into a child Command or remove the children.`);
-    }
+    const declaredSlots = collectArguments(state, subject);
+    checkArgumentPlacement(name, declaredSlots[0], attached[0]);
     if (actions.length > 1) {
         throw new DeclarationError(`${commandSentence(name)} has multiple actions. Register one action.`);
     }
     const action = actions[0];
+    const hasAction = action !== undefined;
+    const declaredResult = buildResult(state, hasAction);
+    /**
+     * The hooks run once the author's declaration is complete and its result is resolved, so a hook
+     * reads an exact record, and every rule below reads what the hooks returned.
+     */
+    // One token per Command per build, which binds a hook's return to the value it received.
+    const lineage = {};
+    const calls = runAttachHooks(state, { hasAction, lineage, path: context.path }, context.plugins);
+    const hooked = applyAttachCalls(state, calls);
+    const hookInputs = calls.filter((call) => call.kind === 'input');
+    checkInputFacts(hookInputs.map((call) => call.input), { name, subject }, context);
+    // The hook-declared names are checked first, so a collision reports in the plugin's voice.
+    // A rule the author's own declaration voices never speaks for a name a hook declared.
+    checkAttachedInputs(hooked, hookInputs, globals);
+    const extensions = calls.some((call) => call.kind === 'extend')
+        ? buildCommandExtensions({
+            descriptors: context.descriptors,
+            layers: hooked.extensions,
+            subject: layer,
+        })
+        : declaredExtensions;
+    const slots = hookInputs.length > 0 ? collectArguments(hooked, subject) : declaredSlots;
+    checkArgumentPlacement(name, slots[0], attached[0]);
+    const result = calls.length > 0 ? buildResult(hooked, hasAction) : declaredResult;
     if (!action) {
-        checkGroup(state, attached);
+        checkGroup(hooked, attached);
     }
-    const options = compileLocalOptions(state, globals, subject);
+    const options = compileLocalOptions(hooked, globals, subject);
     const children = new Map();
     const routes = new Map();
     const claim = aliasNamespace(name, new Set(attached.map((entry) => entry[0])));
@@ -302,17 +825,33 @@ export function buildCommand(state, context) {
         aliases,
         arguments: slots,
         children,
-        dispatch: action ? bindDispatch(state, action) : undefined,
-        inputs: state.inputs,
+        deprecated,
+        description,
+        dispatch: action ? bindDispatch(hooked, action, globals) : undefined,
+        extensions,
+        hidden,
+        inputs: hooked.inputs,
         name,
         options,
+        result,
         routes,
     };
 }
 /** The globals table and the owners record each compile once per invocation and the whole graph shares them. */
-export function buildGraph(root) {
-    const context = { globals: buildGlobals(root.globals), owners: new Map() };
-    return { globals: context.globals, root: buildCommand(root, context) };
+export function buildGraph(root, globals, install) {
+    const context = {
+        descriptors: install.descriptors,
+        extensions: install.extensions,
+        globals: buildGlobals(globals, install.plugins, install),
+        owners: new Map(),
+        path: [],
+        plugins: install.plugins,
+    };
+    return {
+        extensions: context.extensions,
+        globals: context.globals,
+        root: buildCommand(root, context),
+    };
 }
 export class CommandBuilder {
     #state;
@@ -329,7 +868,7 @@ export class CommandBuilder {
             kind: 'argument',
             name,
         };
-        return new CommandBuilder(declareArgument(this.#state, input));
+        return this.derive(declareArgument(this.#state, input));
     }
     option(name, config) {
         const input = {
@@ -337,38 +876,69 @@ export class CommandBuilder {
             kind: 'option',
             name,
         };
-        return new CommandBuilder(declareOption(this.#state, input));
+        return this.derive(declareOption(this.#state, input));
     }
     /**
-     * Hidden aliases are other bare tokens that route to this Command. They invalidate no call, and
-     * the tuple rest parameter rejects a call that names none.
+     * Aliases are other bare tokens that route to this Command. They invalidate no call, and the
+     * tuple rest parameter rejects a call that names none.
      */
     alias(...names) {
-        return new CommandBuilder(declareAlias(this.#state, names));
+        return this.derive(declareAlias(this.#state, names));
     }
     /** A child arrives in any type state, because its own action is the call that finished it. */
     command(child) {
-        return new CommandBuilder(attachChild(this.#state, child));
+        return this.derive(attachChild(this.#state, child));
+    }
+    /**
+     * The value this Command produces for its consumer. The type argument is stated by the author,
+     * so the views record states no type of its own and an omitted argument names none either.
+     */
+    result(declaration) {
+        return this.derive(declareResult(this.#state, 'value', declaration));
     }
-    /** The action is the last declaration call, so the value it returns publishes `AfterAction`. */
+    /** The same declaration over a sequence, whose type argument is one row. */
+    rows(declaration) {
+        return this.derive(declareResult(this.#state, 'rows', declaration));
+    }
+    /**
+     * Views after the fact. It merges by key, so an existing name is replaced in place and a new one
+     * is appended, and `default` names the key core renders when nothing selects another.
+     */
+    views(replacements, options) {
+        return this.derive(declareResultViews(this.#state, replacements, options));
+    }
+    /** The action closes input authoring; `extend()` remains outside this state transition. */
     action(handler) {
-        return new CommandBuilder(declareAction(this.#state, handler));
+        return this.derive(declareAction(this.#state, handler));
+    }
+    extend(...values) {
+        return this.derive(declareExtensions(this.#state, values));
     }
     build(context) {
         return buildCommand(this.#state, context);
     }
+    /**
+     * The same runtime value in the state the calling method's return type names. Each call states
+     * its own transition, and the declared result travels with it unless the call replaces it.
+     */
+    derive(state) {
+        return new CommandBuilder(state);
+    }
 }
-/**
- * The runtime class behind the public constructor. It is generic so that an instance's `Globals`
- * is the type of the value it holds, with `{}` standing in when there is none, which is what each
- * signature of the constructor interface publishes.
- */
+/** The constructor uses the Application registration; public type defaults stay library-neutral. */
 class CommandDeclaration extends CommandBuilder {
-    constructor(name, globals) {
-        super(freshState(name, globals));
+    constructor(name, options) {
+        super(freshState({
+            deprecated: options?.deprecated,
+            description: options?.description,
+            extensions: options?.extensions,
+            hidden: options?.hidden,
+            name,
+            options,
+        }));
     }
 }
-/** The public constructor requires a name and narrows the globals type to the supplied value. */
+/** The public constructor takes a name and one options object, as the Application does. */
 export const Command = CommandDeclaration;
 /** Every declaration in the graph, so defaults are validated before any token is read. */
 export function collectInputs(command) {
@@ -377,6 +947,14 @@ export function collectInputs(command) {
         ...[...command.children.values()].flatMap((child) => collectInputs(child)),
     ];
 }
+/**
+ * The names a routing failure offers: the canonical names of the visible children, in authoring
+ * order. A candidate list is a listing, so a hidden child is absent from it, and a parent whose
+ * children are all hidden offers none.
+ */
+function candidatesOf(command) {
+    return [...command.children].filter(([, child]) => !child.hidden).map(([name]) => name);
+}
 /** Bare tokens, names or aliases, select children until a Command has none; a hyphen commits. */
 export function route(root, tokens) {
     let command = root;
@@ -389,7 +967,7 @@ export function route(root, tokens) {
         }
         const child = command.routes.get(token);
         if (!child) {
-            throw new UnknownCommandError(token, [...command.children.keys()]);
+            throw new UnknownCommandError(token, candidatesOf(command));
         }
         // An alias routes like the canonical name, and the path it walks reports that name alone.
         command = child.command;
@@ -428,25 +1006,103 @@ function bindArguments(command, path, positionals) {
     }
     return values;
 }
-/** Consumes globals, routes to a Command, then validates globals and locals in one pass. */
-export async function selectCommand(graph, invocation) {
-    const { host } = invocation;
-    const scan = extractGlobals(graph.globals.options, [...host.argv]);
-    const { command, path, tokens: rest } = route(graph.root, scan.rest);
+/** Consumes the globals table, then routes the remaining bare tokens to a Command. */
+export function routeInvocation(graph, argv) {
+    const scan = extractGlobals(graph.globals.options, [...argv]);
+    const routed = route(graph.root, scan.rest);
+    return {
+        command: routed.command,
+        path: routed.path,
+        scan: scan.values,
+        tokens: routed.tokens,
+    };
+}
+/**
+ * The frozen records one middleware reads: the routed Command's own inputs, and the tail. Every
+ * value is a plain-data copy frozen to every depth, so a middleware that reaches into a list or a
+ * schema's output object reaches its own copy and contributes nothing to what the action receives.
+ * A value that is neither an array nor a plain object, a class instance or a `Date` a schema
+ * produced, is shared by reference, because core cannot copy it meaningfully.
+ */
+function requestOf(command, values, passthrough) {
+    const args = {};
+    const options = {};
+    for (const input of command.inputs) {
+        const target = input.kind === 'argument' ? args : options;
+        target[input.name] = snapshot(values.read(input));
+    }
+    return Object.freeze({
+        args: Object.freeze(args),
+        options: Object.freeze(options),
+        passthrough: Object.freeze([...passthrough]),
+    });
+}
+/**
+ * The phases that run ahead of the chain: the callable check, local parsing, and validation. It
+ * answers with the call that dispatches, so the caller records that the action was invoked at the
+ * moment it invokes it and no earlier failure reads as a dispatch.
+ */
+async function readyDispatch(graph, routed, invocation) {
+    const { command, path, scan } = routed;
     const { dispatch } = command;
     // A group answers no invocation of its own, so it fails with the routing errors above it.
     if (!dispatch) {
-        throw new NonCallableCommandError(path, [...command.children.keys()]);
+        throw new NonCallableCommandError(path, candidatesOf(command));
     }
-    const parsed = parseInputs(command.options, rest);
+    const parsed = parseInputs(command.options, routed.tokens);
     const args = bindArguments(command, path, parsed.positionals);
     const values = await validateValues({
         command: path,
         defaults: invocation.defaults,
-        host,
+        host: invocation.host,
         inputs: { globals: graph.globals.inputs, locals: command.inputs },
         passthrough: parsed.passthrough,
-        supplied: { args, options: mergeValues(scan.values, parsed.options) },
+        signal: invocation.signal,
+        supplied: { args, options: mergeValues(scan, parsed.options) },
     });
-    return { dispatch, passthrough: parsed.passthrough, values };
+    return {
+        dispatch: async (view) => {
+            // The channel is built at the boundary, because the view a middleware selected is read there.
+            const channel = invocation.channel({ path, result: command.result, view });
+            try {
+                await dispatch({
+                    host: invocation.host,
+                    out: channel.out,
+                    passthrough: parsed.passthrough,
+                    signal: invocation.signal,
+                    style: invocation.style,
+                    values,
+                });
+                /**
+                 * A declared result is a promise the Command makes, so an action that returned normally
+                 * without emitting one broke it. A failure raised before the call is that failure, and a
+                 * cancelled run raises none, because an action that reads its signal and returns is the
+                 * sanctioned path.
+                 */
+                if (command.result && !channel.emitted() && !invocation.signal.aborted) {
+                    throw new ResultError('missing', path);
+                }
+            }
+            catch (error) {
+                // The action's failure is the invocation's outcome.
+                // A sequence it left pending is stopped where it stands rather than drained to its end.
+                channel.stop();
+                throw error;
+            }
+        },
+        request: requestOf(command, values, parsed.passthrough),
+    };
+}
+/**
+ * Prepares one dispatch ahead of the middleware chain and holds whatever fault it found, so a
+ * middleware reads the request before the action runs and a takeover never observes the fault.
+ */
+export async function prepareDispatch(graph, routed, invocation) {
+    const result = routed.command.result;
+    try {
+        return { ...(await readyDispatch(graph, routed, invocation)), kind: 'ready', result };
+    }
+    catch (error) {
+        return { fault: error, kind: 'held', request: null, result };
+    }
 }