@loomcli/core 0.1.1 → 0.3.0

package/dist/style.d.ts

@@ -0,0 +1,86 @@
+import type { ApplicationEnvironment, RegisteredEnvironment } from './environment.js';
+import type { Plugin, ThemeOf } from './plugin.js';
+import type { Alignment } from './style-wire.js';
+/** Concrete terminal foregrounds; backgrounds use the same palette indices. */
+declare const colors: {
+    black: number;
+    blue: number;
+    brightBlack: number;
+    brightBlue: number;
+    brightCyan: number;
+    brightGreen: number;
+    brightMagenta: number;
+    brightRed: number;
+    brightWhite: number;
+    brightYellow: number;
+    cyan: number;
+    green: number;
+    magenta: number;
+    red: number;
+    white: number;
+    yellow: number;
+};
+type Ansi16Color = keyof typeof colors;
+type ColorName = Ansi16Color;
+interface ColorFallbacks {
+    readonly ansi256?: number | undefined;
+    readonly ansi16?: Ansi16Color | undefined;
+}
+type Ansi256Fallbacks = Pick<ColorFallbacks, 'ansi16'>;
+type RgbArguments = [
+    red: number,
+    green: number,
+    blue: number,
+    fallbacks?: ColorFallbacks | undefined
+];
+type Color = ColorName | readonly ['rgb', number, number, number, ColorFallbacks?] | readonly ['ansi256', number, Ansi256Fallbacks?];
+declare const modifiers: readonly ['bold', 'faint', 'italic', 'underline', 'inverse', 'hidden', 'strikethrough', 'overline'];
+type Modifier = (typeof modifiers)[number];
+declare const tokens: readonly ['dim', 'primary', 'highlight', 'success', 'warning', 'error', 'info'];
+type CoreToken = (typeof tokens)[number];
+type Reset = 'reset' | 'resetForeground' | 'resetBackground';
+type Operation = readonly ['foreground' | 'background', Color] | readonly ['modifier', Modifier] | readonly [Reset] | readonly ['token', string];
+declare const semanticStyle: unique symbol;
+type Style<Names extends string = CoreToken, Semantic extends boolean = false> = {
+    (text: string): string;
+    readonly [semanticStyle]: Semantic;
+    readonly escape: (text: string) => string;
+    readonly hex: (color: string, fallbacks?: ColorFallbacks) => Style<Names, Semantic>;
+    readonly bgHex: (color: string, fallbacks?: ColorFallbacks) => Style<Names, Semantic>;
+    readonly rgb: (...args: RgbArguments) => Style<Names, Semantic>;
+    readonly bgRgb: (...args: RgbArguments) => Style<Names, Semantic>;
+    readonly ansi256: (index: number, fallbacks?: Ansi256Fallbacks) => Style<Names, Semantic>;
+    readonly bgAnsi256: (index: number, fallbacks?: Ansi256Fallbacks) => Style<Names, Semantic>;
+} & {
+    readonly [Name in ColorName | `bg${Capitalize<ColorName>}` | Modifier | Reset]: Style<Names, Semantic>;
+} & {
+    readonly [Name in Names]: Style<Names, true>;
+};
+type ThemeNames<Contributor> = Contributor extends Plugin ? keyof ThemeOf<Contributor> & string : never;
+type EnvironmentStyle<Environment extends ApplicationEnvironment<unknown, readonly Plugin[]>> = Style<CoreToken | ThemeNames<Environment['plugins'][number]>>;
+type ContextualStyle = EnvironmentStyle<RegisteredEnvironment>;
+type ConcreteStyle = Style;
+type ThemeMapping = Readonly<Record<string, ConcreteStyle | undefined>>;
+type ThemeConstraint<Mapping> = {
+    readonly [Key in keyof Mapping]: Key extends Exclude<keyof Style, CoreToken> | (typeof reservedCallableNames)[number] ? never : Mapping[Key];
+};
+declare const open = "\uE000";
+declare const headerEnd = "\uE001";
+declare const close = "\uE002";
+declare const escape = "\uE003";
+declare const chains: WeakMap<object, readonly Operation[]>;
+declare const reservedCallableNames: readonly ['apply', 'arguments', 'bind', 'call', 'caller', 'constructor', 'length', 'name', 'prototype', 'toString', 'toLocaleString', 'valueOf', 'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable', '__proto__', '__defineGetter__', '__defineSetter__', '__lookupGetter__', '__lookupSetter__', 'then'];
+declare const reservedStyleNames: Set<string>;
+declare function frame(header: readonly unknown[], body: string): string;
+declare function escapeText(text: string): string;
+/** Copies options at the helper boundary; the wire parser uses the same value rules. */
+declare function colorFallbacks(value: unknown, allow256: boolean): ColorFallbacks;
+/** Properties are generated from the same catalogs the wire parser validates. */
+declare function createStyle(names?: ReadonlySet<string>): ContextualStyle;
+declare function isColorName(value: unknown): value is ColorName;
+declare function pad(text: string, minimumWidth: number, options?: {
+    align?: Alignment;
+}): string;
+declare const style: Style;
+export type { Ansi16Color, Ansi256Fallbacks, ColorFallbacks, ContextualStyle, Color, ColorName, ConcreteStyle, CoreToken, Modifier, Operation, Style, ThemeConstraint, ThemeMapping, };
+export { colorFallbacks, chains, close, colors, createStyle, escape, escapeText, frame, headerEnd, isColorName, modifiers, open, pad, reservedStyleNames, style, tokens, };

package/dist/style.js

@@ -0,0 +1,201 @@
+import { isPlainObject } from './facts.js';
+/** Concrete terminal foregrounds; backgrounds use the same palette indices. */
+const colors = {
+    black: 0,
+    blue: 4,
+    brightBlack: 8,
+    brightBlue: 12,
+    brightCyan: 14,
+    brightGreen: 10,
+    brightMagenta: 13,
+    brightRed: 9,
+    brightWhite: 15,
+    brightYellow: 11,
+    cyan: 6,
+    green: 2,
+    magenta: 5,
+    red: 1,
+    white: 7,
+    yellow: 3,
+};
+const modifiers = [
+    'bold',
+    'faint',
+    'italic',
+    'underline',
+    'inverse',
+    'hidden',
+    'strikethrough',
+    'overline',
+];
+const tokens = ['dim', 'primary', 'highlight', 'success', 'warning', 'error', 'info'];
+const open = '\uE000';
+const headerEnd = '\uE001';
+const close = '\uE002';
+const escape = '\uE003';
+const chains = new WeakMap();
+const reservedCallableNames = [
+    'apply',
+    'arguments',
+    'bind',
+    'call',
+    'caller',
+    'constructor',
+    'length',
+    'name',
+    'prototype',
+    'toString',
+    'toLocaleString',
+    'valueOf',
+    'hasOwnProperty',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+    '__proto__',
+    '__defineGetter__',
+    '__defineSetter__',
+    '__lookupGetter__',
+    '__lookupSetter__',
+    'then',
+];
+const reservedStyleNames = new Set([
+    ...Object.keys(colors),
+    ...Object.keys(colors).map((name) => `bg${name.charAt(0).toUpperCase()}${name.slice(1)}`),
+    ...modifiers,
+    'reset',
+    'resetForeground',
+    'resetBackground',
+    'hex',
+    'bgHex',
+    'rgb',
+    'bgRgb',
+    'ansi256',
+    'bgAnsi256',
+    'escape',
+    ...reservedCallableNames,
+]);
+function textOnly(text) {
+    if (typeof text !== 'string') {
+        throw new TypeError('Style helpers require a string.');
+    }
+    return text;
+}
+function frame(header, body) {
+    const encoded = JSON.stringify(header).replace(/[\uE000-\uE003]/gu, (character) => `\\u${character.charCodeAt(0).toString(16)}`);
+    return `${open}${encoded}${headerEnd}${body}${close}`;
+}
+function escapeText(text) {
+    return textOnly(text).replace(/[\uE000-\uE003]/gu, (character) => `${escape}${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function byte(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 255) {
+        throw new RangeError('Color channels and palette indices must be integers from 0 through 255.');
+    }
+    return value;
+}
+/** Copies options at the helper boundary; the wire parser uses the same value rules. */
+function colorFallbacks(value, allow256) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!isPlainObject(value) ||
+        Reflect.ownKeys(value).some((key) => key !== 'ansi16' && !(allow256 && key === 'ansi256'))) {
+        throw new TypeError('Color fallbacks must be a plain object with supported depth names.');
+    }
+    const ansi16 = value.ansi16;
+    const ansi256 = value.ansi256;
+    if (ansi16 !== undefined && !isColorName(ansi16)) {
+        throw new TypeError('The ansi16 fallback must be a terminal foreground color name.');
+    }
+    if (ansi256 !== undefined &&
+        (typeof ansi256 !== 'number' || !Number.isInteger(ansi256) || ansi256 < 0 || ansi256 > 255)) {
+        throw new RangeError('The ansi256 fallback must be an integer from 0 through 255.');
+    }
+    return {
+        ...(ansi16 === undefined ? {} : { ansi16 }),
+        ...(ansi256 === undefined ? {} : { ansi256 }),
+    };
+}
+function rgbColor([red, green, blue, fallbacks]) {
+    const rgb = ['rgb', byte(red), byte(green), byte(blue)];
+    const copied = colorFallbacks(fallbacks, true);
+    return Object.keys(copied).length === 0 ? rgb : [...rgb, copied];
+}
+function indexedColor(index, fallbacks) {
+    const color = ['ansi256', byte(index)];
+    const copied = colorFallbacks(fallbacks, false);
+    return Object.keys(copied).length === 0 ? color : [...color, copied];
+}
+function hexColor(value, fallbacks) {
+    if (typeof value !== 'string' || !/^#(?:[\da-f]{3}|[\da-f]{6})$/iu.test(value)) {
+        throw new TypeError('Hex colors must use #RGB or #RRGGBB.');
+    }
+    const full = value.length === 4
+        ? value.slice(1).replace(/[\da-f]/giu, (digit) => digit + digit)
+        : value.slice(1);
+    return rgbColor([
+        Number.parseInt(full.slice(0, 2), 16),
+        Number.parseInt(full.slice(2, 4), 16),
+        Number.parseInt(full.slice(4, 6), 16),
+        fallbacks,
+    ]);
+}
+/** Properties are generated from the same catalogs the wire parser validates. */
+function createStyle(names = new Set(tokens)) {
+    function chain(operations) {
+        const callable = (text) => frame(['style', operations], textOnly(text));
+        const next = (operation) => chain([...operations, operation]);
+        const helpers = {
+            ansi256: (index, fallbacks) => next(['foreground', indexedColor(index, fallbacks)]),
+            bgAnsi256: (index, fallbacks) => next(['background', indexedColor(index, fallbacks)]),
+            bgHex: (value, fallbacks) => next(['background', hexColor(value, fallbacks)]),
+            bgRgb: (...args) => next(['background', rgbColor(args)]),
+            escape: escapeText,
+            hex: (value, fallbacks) => next(['foreground', hexColor(value, fallbacks)]),
+            rgb: (...args) => next(['foreground', rgbColor(args)]),
+        };
+        const properties = new Map(Object.entries(helpers).map(([name, helper]) => [name, () => helper]));
+        for (const name of Object.keys(colors)) {
+            if (isColorName(name)) {
+                properties.set(name, () => next(['foreground', name]));
+                properties.set(`bg${name.charAt(0).toUpperCase()}${name.slice(1)}`, () => next(['background', name]));
+            }
+        }
+        for (const name of modifiers) {
+            properties.set(name, () => next(['modifier', name]));
+        }
+        for (const name of ['reset', 'resetForeground', 'resetBackground']) {
+            properties.set(name, () => next([name]));
+        }
+        for (const name of names) {
+            properties.set(name, () => next(['token', name]));
+        }
+        const value = new Proxy(callable, {
+            get: (target, property, receiver) => typeof property === 'string' && properties.has(property)
+                ? properties.get(property)?.()
+                : Reflect.get(target, property, receiver),
+        });
+        chains.set(value, operations);
+        Object.freeze(value);
+        // Last resort: no typed path exists from runtime-generated callable properties to mapped keys.
+        // It holds because the catalogs above supply every declared helper and token; chains retain operations for validation.
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        return value;
+    }
+    return chain([]);
+}
+function isColorName(value) {
+    return typeof value === 'string' && Object.hasOwn(colors, value);
+}
+function pad(text, minimumWidth, options) {
+    textOnly(text);
+    if (!Number.isSafeInteger(minimumWidth) || minimumWidth < 0) {
+        throw new RangeError('Padding width must be a nonnegative safe integer.');
+    }
+    const align = options?.align ?? 'left';
+    if (align !== 'left' && align !== 'right' && align !== 'center') {
+        throw new TypeError('Padding alignment must be left, right, or center.');
+    }
+    return frame(['pad', minimumWidth, align], text);
+}
+const style = createStyle();
+export { colorFallbacks, chains, close, colors, createStyle, escape, escapeText, frame, headerEnd, isColorName, modifiers, open, pad, reservedStyleNames, style, tokens, };

package/dist/theme.d.ts

@@ -0,0 +1,3 @@
+import type { Palette } from './style-state.js';
+declare function buildTheme(value: unknown, identity: string): Palette;
+export { buildTheme };

package/dist/theme.js

@@ -0,0 +1,22 @@
+import { DeclarationError } from './errors.js';
+import { isPlainObject } from './facts.js';
+import { chains, reservedStyleNames } from './style.js';
+function buildTheme(value, identity) {
+    if (!isPlainObject(value)) {
+        throw new DeclarationError(`Plugin "${identity}" must declare theme as a mapping of names to concrete style chains.`);
+    }
+    const palette = new Map();
+    for (const [name, chain] of Object.entries(value)) {
+        if (reservedStyleNames.has(name)) {
+            throw new DeclarationError(`Plugin "${identity}" theme name "${name}" shadows a built-in style member.`);
+        }
+        const operations = typeof chain === 'function' ? chains.get(chain) : undefined;
+        if (chain !== undefined &&
+            (operations === undefined || operations.some((entry) => entry[0] === 'token'))) {
+            throw new DeclarationError(`Plugin "${identity}" theme mapping "${name}" must be an unapplied concrete style chain without semantic tokens.`);
+        }
+        palette.set(name, operations ?? []);
+    }
+    return palette;
+}
+export { buildTheme };

package/dist/types.d.ts

@@ -1,6 +1,10 @@
 /// <reference types="node" preserve="true" />
 import type { Readable, Writable } from 'node:stream';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ExtensionValue } from './extension.js';
+import type { ResultNode } from './inspect.js';
+import type { RenderingPolicy } from './rendering.js';
+import type { ContextualStyle } from './style.js';
 type LowercaseLetter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
 type ShortAlias = LowercaseLetter | Uppercase<LowercaseLetter>;
 type OptionSpelling = {
@@ -32,6 +36,31 @@ type Omission = {
 } | {
     validateOmitted?: false;
 };
+/**
+ * The one-line summary every projection reads. It is a core fact: optional, and a string that holds
+ * a character other than whitespace and no line terminator.
+ */
+interface Described {
+    description?: string;
+}
+/**
+ * The two core facts a listing reads on a named Command and on an option.
+ * `hidden` keeps the member off every listing, and an omitted one reads `false`.
+ * `deprecated` is the one-line migration message a listing shows beside the member.
+ * Neither belongs to an argument, which cannot leave the grammar it sits in, or to the root.
+ */
+interface Listed {
+    hidden?: boolean;
+    deprecated?: string;
+}
+/** The extension values one option declaration carries, whatever scope declares the option. */
+interface OptionExtensions {
+    extensions?: readonly ExtensionValue<'option'>[];
+}
+/** The same slot on an argument declaration, typed by the target its values must name. */
+interface ArgumentExtensions {
+    extensions?: readonly ExtensionValue<'argument'>[];
+}
 /**
  * The tokens one declaration collects before validation: one string, or the whole collection. A
  * multiple option and a variadic argument collect alike, so they share this raw shape.
@@ -54,7 +83,7 @@ export type GlobalNameConstraint<Name extends string, Globals> = Name extends ke
 } : unknown;
 /** A required record key excludes open strings; distribution rejects each union member. */
 export type NameConstraint<Name extends string, Whole extends string = Name> = {} extends Record<Name, unknown> ? LiteralNameFault : Name extends Whole ? [Whole] extends [Name] ? unknown : LiteralNameFault : LiteralNameFault;
-export type ExitCode = 0 | 1 | 2;
+export type ExitCode = 0 | 1 | 2 | 130 | 143;
 export interface InputTerminal {
     isTTY: boolean;
 }
@@ -63,6 +92,7 @@ export interface OutputTerminal extends InputTerminal {
     rows: number | undefined;
 }
 export interface Host {
+    platform: string;
     argv: string[];
     cwd: string;
     env: Record<string, string | undefined>;
@@ -76,7 +106,13 @@ export interface Host {
     stderr: Writable;
 }
 export interface RunOptions {
+    rendering?: RenderingPolicy;
     host?: Partial<Host>;
+    /**
+     * A caller-owned signal that cancels the run. Core subscribes to it at run entry and honors an
+     * abort at every phase boundary; it composes with an installed signals owner.
+     */
+    signal?: AbortSignal;
 }
 /** The declaration one schema call validates, under the name and the scope it was declared in. */
 export interface InputIdentity {
@@ -112,35 +148,173 @@ export type ValidationContext = {
     passthrough: readonly string[];
     supplied: SuppliedInputs;
 };
+/** Immutable authoring and measurement context for one view destination. */
+export interface ViewContext {
+    readonly style: ContextualStyle;
+    readonly width: (text: string) => number;
+}
+/** A pure synchronous view turns one typed value into the marked text core resolves. */
+export interface View<Data> {
+    render: (data: Readonly<Data>, context: ViewContext) => string;
+    /** A view has one shape; the row view of Results is the other. */
+    row?: never;
+}
+/**
+ * A row view renders a sequence one row at a time.
+ * `head` and `tail` open and close the sequence, and each defaults to the empty string.
+ * Every function is pure and synchronous and owns the newlines in the text it returns.
+ */
+export interface RowView<Row> {
+    row: (row: Readonly<Row>, index: number, context: ViewContext) => string;
+    head?: (context: ViewContext) => string;
+    tail?: (count: number, context: ViewContext) => string;
+    /** A row view has one shape; the whole view of Rendered output is the other. */
+    render?: never;
+}
+/** The views record of a value result: every entry renders the whole value. */
+export type ResultViews<Value> = Readonly<Record<string, View<Value>>>;
+/**
+ * The views record of a rows result: a whole view over the collected rows, which core buffers the
+ * sequence for, or a row view, which core feeds as the rows arrive.
+ */
+export type RowViews<Row> = Readonly<Record<string, View<readonly Row[]> | RowView<Row>>>;
+/**
+ * One view a result names, with its data type erased, as the view registry erases a declared
+ * view's. The write site reads each function back through the key that resolved it.
+ */
+export type ResultView = View<never> | RowView<never>;
 /**
- * One value turned into the exact text core writes. A renderer owns every byte, the trailing
- * newline included. It is synchronous and pure: it receives the value alone, returns a string, and
- * holds no output handle. A throw or a non-string return is a renderer failure.
+ * One declared result as the write site reads it: the unit the action emits, the view names it
+ * declares in record order, and the key core renders when nothing selects another.
  */
-export interface Renderer<Data> {
-    render: (data: Readonly<Data>) => string;
+export interface DeclaredResult {
+    default: string;
+    kind: 'value' | 'rows';
+    views: ReadonlyMap<string, ResultView>;
 }
-export interface Out {
+/** Phantom key. It brands the surface a lifecycle hook receives, so a forged value is not one. */
+export declare const attachedCommand: unique symbol;
+/**
+ * One Command as `onCommandAttach` receives it: the facts `inspect()` publishes, with their types
+ * erased, and the authoring calls a hook may make. Each call returns a new value whose facts hold
+ * what the call added, so a hook reads its own earlier calls back. The calls a hook cannot make are
+ * absent, because each of them changes what the action was compiled against or the graph's shape.
+ */
+export interface AttachedCommand {
+    readonly [attachedCommand]: true;
+    /** The Command's own name, and `null` for the root. */
+    readonly name: string | null;
+    readonly path: readonly string[];
+    readonly hasAction: boolean;
+    /** The declared argument names, in declaration order. */
+    readonly arguments: readonly string[];
+    /** The declared local option names, in declaration order. */
+    readonly options: readonly string[];
+    readonly result: ResultNode | null;
+    argument(name: string, config: ArgumentConfig): AttachedCommand;
+    option(name: string, config: OptionConfig): AttachedCommand;
+    views(replacements: Readonly<Record<string, ResultView>>, options?: {
+        default?: string;
+    }): AttachedCommand;
+    extend(...values: readonly ExtensionValue<'command'>[]): AttachedCommand;
+}
+/**
+ * The lifecycle hook core calls once per Command at graph build, in installation order, each
+ * receiving what the previous plugin's hook returned.
+ */
+export type CommandAttachHook = (command: AttachedCommand) => AttachedCommand;
+/**
+ * What `out.results` accepts for one declared result. The declaration rides in the declared types
+ * as a closed discriminant, so a Command that declares none carries the neutral `unknown` and its
+ * `out.results` takes `never`. The parameter is never a union, so distribution reaches one member.
+ */
+export type ResultInput<Result> = Result extends {
+    kind: 'value';
+    value: infer Value;
+} ? Value : Result extends {
+    kind: 'rows';
+    row: infer Row;
+} ? Iterable<Row> | AsyncIterable<Row> : never;
+/**
+ * The result an `out` carries where the declaration is not in hand. Its `results` accepts any
+ * value, because the authoring call already checked what the Command declares, and the channel
+ * core builds for an action carries that declaration at run time.
+ */
+export interface OpenResult {
+    kind: 'value';
+    value: unknown;
+}
+/** The record a `views()` call takes, which is the shape the carried result names. */
+export type ResultViewsOf<Result> = Result extends {
+    kind: 'value';
+    value: infer Value;
+} ? ResultViews<Value> : Result extends {
+    kind: 'rows';
+    row: infer Row;
+} ? RowViews<Row> : never;
+export interface Out<Result = unknown> {
     print(message: string): Promise<void>;
     info(message: string): Promise<void>;
     success(message: string): Promise<void>;
     warn(message: string): Promise<void>;
     error(message: string): Promise<void>;
-    /** The neutral presentation call: a rendered value has no purpose and no destination. */
-    render<Data>(data: Data, renderer: Renderer<Data>): Promise<void>;
+    /** The neutral view call: a rendered value has no purpose and no destination. */
+    render<Data>(data: Data, view: View<Data>): Promise<void>;
+    /** The same call over a sequence: core writes each row's text as the source yields it. */
+    render<Row>(rows: Iterable<Row> | AsyncIterable<Row>, view: RowView<Row>): Promise<void>;
+    /**
+     * The Command's own result, emitted once. Property syntax keeps the parameter contravariant, so
+     * a neutral `Out` never stands in for one that carries a declaration.
+     */
+    results: (value: ResultInput<Result>) => Promise<void>;
     fatal(message: string): never;
 }
-export type StringOption = OptionSpelling & Presence & Multiplicity & Omission & {
+/**
+ * What the action's channel answers to: the routed path its diagnostics name, the result the
+ * routed Command declared, and the view this run selected. The declaration decides the
+ * destinations the channel carries, so the redirect is read from the graph once and never from the
+ * view a run selected; `view` decides the rendering alone, and is `null` when nothing selected one
+ * and the declaration's default stands.
+ */
+export interface ResultBinding {
+    path: readonly string[];
+    result: DeclaredResult | undefined;
+    view: string | null;
+}
+/**
+ * The routed Command's invocation after parsing and validation, which every middleware reads. The
+ * values are what the action receives, the output of each declaration's schema, for that Command's
+ * own arguments and local options; global and plugin option values are not here. The records are
+ * untyped and frozen, because a middleware runs ahead of every action and the graph carries no
+ * type for a value.
+ */
+export interface Request {
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly options: Readonly<Record<string, unknown>>;
+    readonly passthrough: readonly string[];
+}
+/** The channel one action receives, with the emission the results lane holds it to. */
+export interface ActionChannel {
+    out: Out<OpenResult>;
+    /** Whether the action emitted its result, which the missing rule reads after it returned. */
+    emitted: () => boolean;
+    /**
+     * Stops every sequence this channel still has pending. The action's own failure stays primary,
+     * so a sequence it never awaited is stopped rather than drained.
+     */
+    stop: () => void;
+}
+export type StringOption = OptionSpelling & Presence & Multiplicity & Omission & Described & Listed & OptionExtensions & {
     type: 'string';
     polarity?: never;
     validate?: StandardSchemaV1;
 };
 /** A variadic argument collects the remaining tokens, so it follows the multiple option rules. */
-export type VariadicArgument = Presence & {
+export type VariadicArgument = Presence & Described & ArgumentExtensions & {
     variadic: true;
     validate?: StandardSchemaV1;
 };
-export type ScalarArgument = Presence & Omission & {
+export type ScalarArgument = Presence & Omission & Described & ArgumentExtensions & {
     variadic?: false;
     validate?: StandardSchemaV1;
 };
@@ -198,7 +372,7 @@ export type ArgumentValue<Config extends ArgumentConfig> = Config extends {
 } | {
     validateOmitted: true;
 } ? never : undefined);
-export type BooleanOption = (OptionSpelling & {
+export type BooleanOption = (OptionSpelling & Described & Listed & OptionExtensions & {
     type: 'boolean';
     validate?: never;
     default?: never;
@@ -206,7 +380,7 @@ export type BooleanOption = (OptionSpelling & {
     required?: never;
     validateOmitted?: never;
     polarity?: 'positive' | 'negative';
-}) | {
+}) | (Described & Listed & OptionExtensions & {
     type: 'boolean';
     validate?: never;
     default?: never;
@@ -216,8 +390,24 @@ export type BooleanOption = (OptionSpelling & {
     polarity: 'both';
     short?: ShortAlias;
     shortOnly?: false;
-};
+});
 export type OptionConfig = StringOption | BooleanOption;
+/**
+ * The parsing part of a string option config, which is all a plugin option declares. A plugin
+ * option carries no schema and no presence rule, because the pre-scan consumes it ahead of routing,
+ * where the validation context every schema is promised cannot exist. Its middleware interprets
+ * the value.
+ * A Boolean plugin option is an ordinary `BooleanOption`, which already declares none of them.
+ */
+export type PluginStringOption = OptionSpelling & Multiplicity & Described & Listed & OptionExtensions & {
+    type: 'string';
+    default?: string | string[];
+    polarity?: never;
+    required?: never;
+    validate?: never;
+    validateOmitted?: never;
+};
+export type PluginOptionConfig = PluginStringOption | BooleanOption;
 export type OptionValue<Config extends OptionConfig> = Config extends StringOption ? Config extends {
     multiple: true;
 } ? ValidatedValue<Config, string[]> : ValidatedValue<Config, string> | (Config extends {
@@ -227,34 +417,40 @@ export type OptionValue<Config extends OptionConfig> = Config extends StringOpti
 } | {
     validateOmitted: true;
 } ? never : undefined) : boolean;
-export interface ActionContext<Args, Options = {}> {
+export interface ActionContext<Args, Options = {}, Result = unknown> {
+    readonly style: ContextualStyle;
     args: Args;
     options: Options;
     passthrough: string[];
-    out: Out;
+    out: Out<Result>;
     host: Host;
+    /** The run's cancellation signal, which a caller or an installed signals owner aborts. */
+    signal: AbortSignal;
 }
-export type Action<Args, Options = {}> = (context: ActionContext<Args, Options>) => unknown;
+export type Action<Args, Options = {}, Result = unknown> = (context: ActionContext<Args, Options, Result>) => unknown;
 /** Phantom key. It keeps the inferred declaration types exact and holds no runtime value. */
 export declare const declaredTypes: unique symbol;
 /**
- * The three inferred types one declaration carries. The phantom member keeps them exact. Args and
- * options widen, so a child can satisfy a looser reader. The globals appear in both a parameter and
- * a return position, which makes them invariant: a child's globals must be the parent's own type,
- * not a subset and not a superset, because one table serves every Command in the graph.
+ * Arguments and local options describe the action's own inputs. Globals are a requirement on the
+ * Receiving Application: a library that needs none can attach wherever its local keys are disjoint.
  */
-export interface DeclaredTypes<Args, Options, Globals> {
+export interface DeclaredTypes<Args, Options, Globals, Result = unknown> {
     args: Args;
-    globals: (value: Globals) => Globals;
+    globals: (value: Globals) => void;
     options: Options;
+    /**
+     * The result the Command declares, or `unknown` where it declares none. A plain field keeps it
+     * covariant, so a child that carries one still satisfies a neutral `Command` annotation.
+     */
+    result: Result;
 }
 /**
  * The handler one declaration accepts. It reads the phantom types, not the `action()` call, so it
  * holds on a fresh declaration, on a partly declared one, and on one that registered its action.
  */
 export type ActionHandler<Declaration> = Declaration extends {
-    [declaredTypes]: DeclaredTypes<infer Args, infer Options, infer Globals>;
-} ? Action<Args, Globals & Options> : never;
+    [declaredTypes]: DeclaredTypes<infer Args, infer Options, infer Globals, infer Result>;
+} ? Action<Args, Globals & Options, Result> : never;
 /** The args object an extracted handler receives for this declaration. */
 export type ActionArgs<Declaration> = ActionArgument<Declaration> extends {
     args: infer Args;