@loomcli/core 0.1.1 → 0.3.0

package/dist/output.js

@@ -1,5 +1,19 @@
 import { setImmediate } from 'node:timers/promises';
-import { FatalError, notTextReason } from './errors.js';
+import { FatalError, notTextReason, ResultError } from './errors.js';
+import { incompleteResult, lanes } from './lanes.js';
+import { capabilities } from './rendering.js';
+import { writeSequence } from './sequence.js';
+import { resolveText, width } from './style-resolve.js';
+import { createStyle, tokens } from './style.js';
+import { resolveRowView, resolveView, shapeOf } from './view.js';
+function stringValue(value) {
+    if (typeof value !== 'string') {
+        throw new Error(notTextReason(value));
+    }
+    return value;
+}
+/** The opener a reservation holds until its own gate publishes the real one. */
+const unopened = () => undefined;
 class Destination {
     stream;
     tail = Promise.resolve();
@@ -14,16 +28,44 @@ class Destination {
         }
     };
     write(text) {
-        const pending = this.tail.then(() => {
-            if (this.state.kind === 'failed') {
-                throw this.state.error;
-            }
-            return this.writeText(text);
-        });
+        const pending = this.tail.then(() => this.accept(text));
         // Keep the returned rejection observable, while accounting for calls without await.
         this.tail = pending.catch(this.onError);
         return pending;
     }
+    /** One text queued behind whatever preceded it, on a destination that has not failed. */
+    accept(text) {
+        if (this.state.kind === 'failed') {
+            throw this.state.error;
+        }
+        return this.writeText(text);
+    }
+    /**
+     * One place held in this destination's order from the moment a sequence is issued until it
+     * closes. Later calls queue behind the gate, so they write after the sequence's last piece
+     * whether or not their caller awaited the sequence, and the gate keeps the destination undrained
+     * while the sequence is live, which is what makes a pending sequence open output.
+     */
+    reserve() {
+        const previous = this.tail;
+        let open = unopened;
+        const gate = new Promise((resolve) => {
+            open = resolve;
+        });
+        this.tail = previous.then(() => gate);
+        // The sequence's own pieces queue on each other, ahead of the gate that holds its place.
+        let pieces = previous;
+        return {
+            close: () => {
+                open(pieces);
+            },
+            write: (text) => {
+                const pending = pieces.then(() => this.accept(text));
+                pieces = pending.catch(this.onError);
+                return pending;
+            },
+        };
+    }
     writeText(text) {
         return new Promise((resolve, reject) => {
             if (this.stream.destroyed || this.stream.writableEnded) {
@@ -63,7 +105,18 @@ class Destination {
         this.stream.off('error', this.onError);
     }
 }
-/** The text a renderer produced, or the value that stands for its failure to produce text. */
+/** The sentence one view value of the wrong shape reports, which is the fault of its call. */
+function shapeReason(both) {
+    return both
+        ? 'The view carries render and row. Supply one of the two.'
+        : 'The view carries neither render nor row. Supply a view with render or a row view with row.';
+}
+/**
+ * No contributor at all. A result's selected view is replaced by view name alone, so the
+ * Application's override list never reaches a result's views, which carry no identity.
+ */
+const bare = [];
+/** The text a view produced, or the value that stands for its failure to produce text. */
 function renderText(produce) {
     try {
         const text = produce();
@@ -73,50 +126,266 @@ function renderText(produce) {
         return { failed: error };
     }
 }
+/**
+ * The data one view reads back through the key that resolved it. A result's views are stored with
+ * their data type erased, as the view registry erases a declared view's, so the write site hands
+ * each function the value its own declaration checked.
+ */
+function erased(value) {
+    // Last resort: no typed path exists.
+    // A views record holds one entry per view name and carries no type parameter per entry.
+    // Every view it stores reads its data as the erased type the registry uses.
+    // It holds because the authoring call checked the value against the declaration the record answers.
+    // Build proved every entry in that record renders the declared type.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return value;
+}
 export class Output {
     host;
+    signal;
     destinations = new Map();
     renderFault = undefined;
+    // Every fault the output path raised beside its calls, reported after the primary outcome.
+    // A source a sequence stopped on and a results-lane fault are both such faults.
+    stops = [];
+    // The routed Command an incomplete sequence names, published once routing resolved it.
+    route = [];
+    /**
+     * The channel every caller writes through. It is typed with the result left open, because the
+     * declaration a call answers to is checked where the action was authored.
+     */
     out;
-    constructor(host) {
+    palette = new Map();
+    policy = {};
+    // The contributors this invocation resolves a declared view through, published once they build.
+    registry = [];
+    style = createStyle();
+    constructor(host, signal) {
         this.host = host;
+        this.signal = signal;
         this.out = {
-            error: (message) => this.emit('error', message),
+            error: (message) => this.emit('error', message, 'stderr'),
             fatal: (message) => {
                 throw new FatalError(message);
             },
-            info: (message) => this.emit('info', message),
-            print: (message) => this.emit('print', message),
-            render: (data, renderer) => this.rendered(() => renderer.render(data)),
-            success: (message) => this.emit('success', message),
-            warn: (message) => this.emit('warn', message),
+            info: (message) => this.emit('info', message, 'stderr'),
+            print: (message) => this.emit('print', message, 'stdout'),
+            // The data type is erased here, as it is in the registry.
+            // One call dispatches on the shape of the view it was handed.
+            // Every view function reads its data back through its own key.
+            render: (data, value) => this.renderValue(data, value, { destination: 'stdout' }),
+            // Only the action emits a result, so this call is the middleware fault whatever was declared.
+            results: () => this.resultFault('middleware'),
+            success: (message) => this.emit('success', message, 'stderr'),
+            warn: (message) => this.emit('warn', message, 'stderr'),
+        };
+    }
+    /**
+     * The channel one action receives. On a Command that declares a result nothing the action writes
+     * but the result reaches stdout: `print` and `render` move to stderr, and they move the view
+     * context with the destination, so capability detection follows the stream the bytes reach. The
+     * destination is decided here, from the declaration, and never from the view a run selected.
+     */
+    channel(binding) {
+        const destination = binding.result ? 'stderr' : 'stdout';
+        const emission = { calls: 0, live: new Set() };
+        const target = { destination, live: emission.live };
+        return {
+            emitted: () => emission.calls > 0,
+            out: {
+                ...this.out,
+                print: (message) => this.emit('print', message, destination),
+                // The data type is erased here, as it is in the registry.
+                // One call dispatches on the shape of the view it was handed.
+                // Every view function reads its data back through its own key.
+                render: (data, value) => this.renderValue(data, value, target),
+                results: (value) => this.results(binding, emission, value),
+            },
+            stop: () => {
+                for (const stop of emission.live) {
+                    stop();
+                }
+            },
         };
     }
-    /** A semantic message is one line on its destination; only `print` writes to stdout. */
-    emit(kind, message) {
-        return this.write(kind === 'print' ? this.host.stdout : this.host.stderr, `${message}\n`);
+    /**
+     * One `out.results` call on the action's channel. The declaration decides the unit, the selected
+     * view decides how it renders, and stdout carries the result under either one. The selected
+     * view is the one a middleware named before the action dispatched, or the declaration's default
+     * when none did. A call the declaration does not answer for is a fault of the lane and writes
+     * nothing.
+     */
+    results(binding, emission, value) {
+        const { path, result } = binding;
+        if (!result) {
+            return this.resultFault('undeclared', path);
+        }
+        if (emission.calls > 0) {
+            return this.resultFault('repeated', path);
+        }
+        emission.calls += 1;
+        const selected = binding.view ?? result.default;
+        const view = result.views.get(selected);
+        if (!view) {
+            // Build proved the default names a view the record holds.
+            // The boundary proved a selected name is one too, so this is core's own fault.
+            return this.renderFailed(new Error(`The view "${selected}" is not declared.`));
+        }
+        if (result.kind === 'rows') {
+            return this.sequence(erased(value), this.sequenceView(view, bare), {
+                destination: 'stdout',
+                live: emission.live,
+            });
+        }
+        if (typeof view.row === 'function') {
+            // Build rejects a row view on a value result, so reaching one here is core's own fault.
+            return this.renderFailed(new Error(`The view "${selected}" renders rows, not a value.`));
+        }
+        return this.rendered(() => resolveView(bare, view)(erased(value), this.context('stdout')));
+    }
+    /**
+     * One fault of the results lane: the call rejects, and the same failure is reported after this
+     * invocation's primary outcome, so a call the action never awaited still turns a would-be 0 into
+     * 1 and one the action let propagate is reported once.
+     */
+    resultFault(kind, path = this.route) {
+        const fault = new ResultError(kind, path);
+        this.stops.push(fault);
+        const rejected = Promise.reject(fault);
+        void rejected.catch(() => undefined);
+        return rejected;
+    }
+    /** The registry one invocation resolves through, republished as each contributor is read. */
+    useViews(registry) {
+        this.registry = registry;
+    }
+    /** The routed path, published once routing resolved it, which an incomplete sequence names. */
+    useRoute(path) {
+        this.route = path;
+    }
+    /** What this invocation's output raised beside its calls, in the order it was raised. */
+    get stopped() {
+        return this.stops;
+    }
+    configure(policy, palette) {
+        this.policy = policy;
+        this.palette = palette;
+        this.style = createStyle(new Set([...tokens, ...palette.keys()]));
+    }
+    context(destination) {
+        const caps = capabilities(this.host, destination, this.policy);
+        return Object.freeze({
+            style: this.style,
+            width: (text) => width(text, this.palette, caps),
+        });
+    }
+    /**
+     * A semantic message is one line on its destination; only `print` writes to stdout. The message
+     * is checked before the lane view runs, and this call appends the one newline after it, so a
+     * lane view returns none and an override that returns the empty string still writes one.
+     */
+    emit(kind, message, destination) {
+        return this.rendered(() => {
+            if (typeof message !== 'string') {
+                throw new TypeError('Output messages must be strings.');
+            }
+            const render = resolveView(this.registry, lanes[kind]);
+            return `${stringValue(render(message, this.context(destination)))}\n`;
+        }, destination);
     }
     /**
      * The failure report of one invocation. Like `render`, the text is queued on its destination
-     * exactly as given: the caller already carries its own trailing newline, whether that text came
-     * from a registered renderer or from core's own default text.
+     * after style resolution: the caller already carries its own trailing newline, whether that text
+     * came from a resolved view or from core's own default text.
      */
     report(text) {
-        return this.write(this.host.stderr, text);
+        return this.rendered(() => text, 'stderr');
     }
     /**
-     * The renderer owns every byte, so its text is queued on stdout exactly as returned. A throw or
-     * a non-string return rejects this call alone: nothing is written for it, later output still
-     * writes, and the recorded cause ends the invocation once the action has completed.
+     * One `out.render` call, dispatched on the shape of the view it was handed. The two shapes are
+     * exclusive, so a JavaScript author's value that carries both, or neither, is the output-view
+     * fault of this call and nothing is written for it.
      */
-    rendered(produce) {
-        const rendered = renderText(produce);
-        return 'text' in rendered
-            ? this.write(this.host.stdout, rendered.text)
-            : this.renderFailed(rendered.failed);
+    renderValue(data, value, target) {
+        const shape = shapeOf(value);
+        if (shape === 'both' || shape === 'neither') {
+            return this.renderFailed(new Error(shapeReason(shape === 'both')));
+        }
+        // The shape was named above, so this second read narrows the value rather than deciding it.
+        if (typeof value.render === 'function') {
+            return this.rendered(() => resolveView(this.registry, value)(data, this.context(target.destination)), target.destination);
+        }
+        return this.sequence(data, this.sequenceView(value, this.registry), target);
+    }
+    /**
+     * The view one sequence writes through, in the shape its own view carries. The caller supplies
+     * the contributors the view resolves through: `out.render`'s call-site view resolves through
+     * this invocation's registry, as ADR-0021 requires, and a result's view resolves through none,
+     * because a result's selected view is replaced by view name alone.
+     */
+    sequenceView(value, registry) {
+        if (typeof value.row === 'function') {
+            return { kind: 'rows', view: resolveRowView(registry, value) };
+        }
+        const render = resolveView(registry, value);
+        return { kind: 'whole', render: (rows, context) => render(erased(rows), context) };
     }
     /**
-     * The rejected call. The first renderer failure is the reported one, so a later one adds no
+     * One sequence, which holds its place on the destination from here until its last piece is
+     * written. The returned rejection is observed here as well, because an action that never awaits
+     * the call must not end the process with an unhandled rejection.
+     */
+    sequence(source, view, target) {
+        const { destination } = target;
+        const place = this.destination(this.host[destination]).reserve();
+        const sequence = writeSequence({
+            close: place.close,
+            context: this.context(destination),
+            incomplete: (facts) => {
+                this.incomplete(facts);
+            },
+            path: this.route,
+            piece: (produce) => this.rendered(produce, destination, place.write),
+            signal: this.signal,
+            source,
+            stopped: (cause) => {
+                this.stops.push(cause);
+            },
+            view,
+        });
+        // A sequence its own channel can stop, so an action's failure ends it rather than draining it.
+        target.live?.add(sequence.stop);
+        void sequence.pending.catch(() => undefined);
+        return sequence.pending;
+    }
+    /**
+     * The line one incomplete sequence writes on stderr, ahead of the fault's own report. It resolves
+     * through the registry like any other rendered output, so an override that returns the empty
+     * string silences it and one that throws is a view fault. A stderr that has failed already takes
+     * the plain fallback path and no further.
+     */
+    incomplete(facts) {
+        const context = this.context('stderr');
+        if (this.destinations.get(this.host.stderr)?.state.kind === 'failed') {
+            void reportPlainly(this.host.stderr, incompleteResult.render(facts, context));
+            return;
+        }
+        void this.rendered(() => resolveView(this.registry, incompleteResult)(facts, context), 'stderr').catch(() => undefined);
+    }
+    /**
+     * The write site owns its newline; core resolves the view's marked text before queuing it. A
+     * throw or a non-string return rejects this call alone: nothing is written for it, later output
+     * still writes, and the recorded cause ends the invocation once the action has completed.
+     */
+    rendered(produce, destination = 'stdout', write) {
+        const rendered = renderText(() => resolveText(stringValue(produce()), this.palette, capabilities(this.host, destination, this.policy)));
+        if (!('text' in rendered)) {
+            return this.renderFailed(rendered.failed);
+        }
+        return write ? write(rendered.text) : this.write(this.host[destination], rendered.text);
+    }
+    /**
+     * The rejected call. The first view failure is the reported one, so a later one adds no
      * second diagnostic, and the rejection is observed here as well, because an action that never
      * awaits the call must not end the process with an unhandled rejection.
      */
@@ -126,17 +395,21 @@ export class Output {
         void rejection.catch(() => undefined);
         return rejection;
     }
-    /** What a renderer failed with during this invocation, if one did. */
+    /** What a view failed with during this invocation, if one did. */
     get fault() {
         return this.renderFault;
     }
-    write(stream, text) {
+    /** The queue one stream writes through, opened the first time this invocation reaches it. */
+    destination(stream) {
         let destination = this.destinations.get(stream);
         if (!destination) {
             destination = new Destination(stream);
             this.destinations.set(stream, destination);
         }
-        return destination.write(text);
+        return destination;
+    }
+    write(stream, text) {
+        return this.destination(stream).write(text);
     }
     async settle() {
         let drained = false;
@@ -167,7 +440,7 @@ export class Output {
 }
 /**
  * The plain fallback path: a fresh destination on stderr, outside the invocation's queues and
- * outside every registration, so no application code runs on it. The caller composes the newlines
+ * outside every override, so no application code runs on it. The caller composes the newlines
  * between whatever it is reporting, then passes the one string this writes verbatim. A failed
  * write ends reporting.
  */

package/dist/plugin.d.ts

@@ -0,0 +1,132 @@
+import type { MiddlewareContext } from './chain.js';
+import type { AnyExtension, DescriptorRegistry, ExtensionRecords } from './extension.js';
+import type { ProcessSignal } from './signals.js';
+import type { Palette } from './style-state.js';
+import type { ThemeConstraint, ThemeMapping } from './style.js';
+import type { CommandAttachHook, OptionValue, PluginOptionConfig } from './types.js';
+import type { OptionInput } from './validation.js';
+import type { ViewContribution } from './view.js';
+/**
+ * The declaration record a plugin contributes its options under: the parsing part of an option
+ * config, keyed by option name. A plugin option carries no schema and no presence rule, so the
+ * config type publishes neither, and build repeats the rule for a JavaScript author.
+ */
+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;
+declare const pluginTheme: unique symbol;
+/**
+ * One plugin's declarations as the registry holds them, with the generic parts erased. Build reads
+ * every one of them defensively, because a JavaScript author reaches the same slots, so the erased
+ * shape is what the rules below read and no declaration is claimed to be well formed here.
+ */
+interface DeclaredPlugin {
+    theme?: unknown;
+    options?: PluginOptions;
+    middleware?: {
+        activate?: unknown;
+        load?: unknown;
+    };
+    onCommandAttach?: unknown;
+    extensions?: readonly AnyExtension[];
+    views?: unknown;
+    signals?: unknown;
+}
+/** The declarations behind one plugin value, read by this package alone. */
+interface PluginNode {
+    definition: DeclaredPlugin;
+    identity: unknown;
+}
+/**
+ * The runtime value `plugin()` returns. `Options` appears in a read position alone, which makes it
+ * covariant: a `plugins` list holds plugins with different options the way `views` holds
+ * overrides for different keys, and `Middleware` and `load` accept a narrower plugin.
+ */
+declare class PluginDeclaration<Options extends PluginOptions, Theme extends ThemeMapping> {
+    readonly [pluginTheme]: Theme;
+    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, Theme extends ThemeMapping = {}> = Pick<PluginDeclaration<Options, Theme>, typeof pluginOptions | typeof pluginTheme>;
+/** 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. Creating and installing the value runs none of its code: a hook
+ * runs at graph build, and the middleware runs inside an invocation.
+ */
+interface PluginDefinition<Options extends PluginOptions = PluginOptions, Theme extends ThemeMapping = ThemeMapping> {
+    theme?: Theme & ThemeConstraint<Theme>;
+    options?: Options;
+    middleware?: {
+        activate: 'always' | readonly (keyof Options & string)[];
+        load: () => Promise<{
+            default: Middleware<Plugin<Options>>;
+        }>;
+    };
+    onCommandAttach?: CommandAttachHook;
+    extensions?: readonly AnyExtension[];
+    views?: readonly ViewContribution[];
+    signals?: readonly ('SIGINT' | 'SIGTERM')[];
+}
+/**
+ * One plugin: an identity and the contributions it carries. Creating and installing the value runs
+ * none of its code: a hook runs at graph build, and the middleware runs inside an invocation, so an
+ * installed plugin an invocation never reaches costs that invocation its hooks alone.
+ */
+declare function plugin<Options extends PluginOptions = {}, const Theme extends ThemeMapping = {}>(identity: string, definition: PluginDefinition<Options, Theme>): Plugin<NoInfer<Options>, NoInfer<Theme>>;
+/** One installed plugin, with the declarations build reads out of it in installation order. */
+interface InstalledPlugin {
+    declaration: DeclaredPlugin;
+    identity: string;
+}
+/** How every plugin diagnostic names one plugin at the start of a sentence. */
+declare function pluginSentence(identity: string): string;
+/**
+ * The 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 {
+    theme: Palette | undefined;
+    /** The hook core calls once per Command at graph build, or nothing where none is declared. */
+    onCommandAttach: CommandAttachHook | undefined;
+    /** The plugin's own `views` slot, read once the validated theme is in place. */
+    views: unknown;
+    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[];
+type ThemeOf<Contributor> = [Contributor] extends [never] ? {} : Contributor extends Plugin<PluginOptions, infer Theme> ? Theme : {};
+export type { ThemeOf, BuiltPlugin, InstalledPlugin, Middleware, OptionsOf, Plugin, PluginBuild, PluginDefinition, PluginOptions, PluginOptionValues, };
+export { buildPlugins, installPlugins, ownedSignals, plugin, pluginSentence };