@loomcli/core 0.1.1 → 0.3.0

package/dist/inspect.d.ts

@@ -1,8 +1,9 @@
-import type { BuiltCommand } from './command.js';
-import type { BuiltGlobals } from './globals.js';
+import type { BuiltGraph } from './command.js';
+import type { DeclaredResult } from './types.js';
 /** One declared argument. `default` wraps the declared value, so an explicit `undefined` shows. */
 interface ArgumentNode {
     readonly name: string;
+    readonly description: string | undefined;
     readonly required: boolean;
     readonly variadic: boolean;
     readonly validated: boolean;
@@ -10,11 +11,24 @@ interface ArgumentNode {
     readonly default: {
         readonly value: unknown;
     } | undefined;
+    readonly extensions: Readonly<Record<string, unknown>>;
 }
-/** One declared option, in the shape its type gives it. Spellings are the accepted CLI forms. */
+/**
+ * One declared option, in the shape its type gives it. Spellings are the accepted CLI forms, and
+ * `scope` tells an application's own option from a plugin option, which reaches no action. An
+ * option a plugin's lifecycle hook declared on a Command is that Command's own in every respect, so
+ * it reads `application` and names no plugin.
+ * `hidden` is `false` unless the declaration says `true`, and `deprecated` is the declared
+ * migration message or `undefined`. A listing projection omits a hidden node and marks a
+ * deprecated one; parsing binds without reading either.
+ */
 type OptionNode = {
     readonly type: 'string';
     readonly name: string;
+    readonly description: string | undefined;
+    readonly hidden: boolean;
+    readonly deprecated: string | undefined;
+    readonly scope: 'application' | 'plugin';
     readonly long: string | null;
     readonly short: string | null;
     readonly required: boolean;
@@ -24,38 +38,81 @@ type OptionNode = {
     readonly default: {
         readonly value: unknown;
     } | undefined;
+    readonly extensions: Readonly<Record<string, unknown>>;
 } | {
     readonly type: 'boolean';
     readonly name: string;
+    readonly description: string | undefined;
+    readonly hidden: boolean;
+    readonly deprecated: string | undefined;
+    readonly scope: 'application' | 'plugin';
     readonly long: string | null;
     readonly short: string | null;
     readonly negative: string | null;
     readonly polarity: 'positive' | 'negative' | 'both';
+    readonly extensions: Readonly<Record<string, unknown>>;
 };
 /**
  * One Command in the graph. `name` is `null` for the root, and `path` is its route from it.
- * `aliases` holds the hidden aliases in declaration order, so a Command appears once, under its
- * canonical name, and `path` never holds an alias.
+ * `aliases` holds the aliases in declaration order, so a Command appears once, under its canonical
+ * name, and `path` never holds an alias. The root reports the Application's description, so a
+ * projection that walks nodes never special-cases it, and it reads `hidden: false` and
+ * `deprecated: undefined`, the two core facts a listing reads on every other node.
  */
 interface CommandNode {
     readonly name: string | null;
     readonly aliases: readonly string[];
     readonly path: readonly string[];
+    readonly description: string | undefined;
+    readonly hidden: boolean;
+    readonly deprecated: string | undefined;
     readonly hasAction: boolean;
+    readonly result: ResultNode | null;
     readonly arguments: readonly ArgumentNode[];
     readonly options: readonly OptionNode[];
     readonly children: readonly CommandNode[];
+    readonly extensions: Readonly<Record<string, unknown>>;
+}
+/**
+ * The result one Command declares: the unit its action emits, the view names in record order, and
+ * the name of the view core renders when nothing selects another.
+ */
+interface ResultNode {
+    readonly kind: 'value' | 'rows';
+    readonly views: readonly string[];
+    readonly default: string;
 }
-/** One built graph as plain data. The globals appear once here and in no `CommandNode`. */
+/**
+ * One built graph as plain data. The globals appear once here and in no `CommandNode`. `version`
+ * and `description` are the Application's own core facts. `version` is the declared string, or
+ * `0.0.0` when the Application declares none, so it is never `undefined`. `description` stays
+ * `undefined` where the Application declares none.
+ */
 interface CommandGraph {
     readonly name: string;
+    readonly version: string;
+    readonly description: string | undefined;
     readonly globals: readonly OptionNode[];
     readonly root: CommandNode;
 }
-/** Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. */
-declare function inspectGraph(name: string, graph: {
-    globals: BuiltGlobals;
-    root: BuiltCommand;
+/**
+ * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
+ * consumer cannot reach the source through the copy, and a later call reports the value again.
+ * Primitives and library objects, such as a class instance or a `Date` a schema produced, are
+ * reported as they are, because core cannot copy them meaningfully. The graph reads it for a
+ * declared value and the chain reads it for the request one middleware holds.
+ */
+export declare function snapshot(value: unknown): unknown;
+/** The declared result as plain data, or `null` on a Command that declares none. */
+declare function resultNode(result: DeclaredResult | undefined): ResultNode | null;
+/**
+ * Renders one built graph as frozen plain data. Nothing here reads a host fact or a schema. The
+ * globals list holds the application's own options, then each installed plugin's in installation
+ * order, which is the order the globals table holds them in.
+ */
+declare function inspectGraph(name: string, graph: BuiltGraph, facts: {
+    description: string | undefined;
+    version: string;
 }): CommandGraph;
-export type { ArgumentNode, CommandGraph, CommandNode, OptionNode };
-export { inspectGraph };
+export type { ArgumentNode, CommandGraph, CommandNode, OptionNode, ResultNode };
+export { inspectGraph, resultNode };

package/dist/inspect.js

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

package/dist/lanes.d.ts

@@ -0,0 +1,26 @@
+import type { AnyDeclaredView, DeclaredView } from './view.js';
+/** The five semantic methods, each with the glyph and the style token its lane carries. */
+type Lane = 'error' | 'info' | 'print' | 'success' | 'warn';
+/**
+ * The five lane views core declares, one per semantic method. An application replaces the function
+ * of any of them through `views`, and the replacement owns the gutter the default supplies.
+ */
+declare const lanes: Readonly<Record<Lane, DeclaredView<string>>>;
+/**
+ * What one sequence that stopped early reports: the Command it belongs to, the rows its source
+ * produced before the stop, and the rows core wrote. `head` is no row, so it is not counted.
+ */
+interface IncompleteResult {
+    path: readonly string[];
+    yielded: number;
+    written: number;
+}
+/**
+ * The line a sequence writes on stderr when it stopped before its end, so an empty result and a
+ * truncated one never read alike. An override that returns the empty string silences it.
+ */
+declare const incompleteResult: DeclaredView<IncompleteResult>;
+/** Every view core declares, so one build register holds their identities from the start. */
+declare const coreViews: readonly AnyDeclaredView[];
+export type { IncompleteResult, Lane };
+export { coreViews, incompleteResult, lanes };

package/dist/lanes.js

@@ -0,0 +1,45 @@
+import { routedSubject } from './errors.js';
+import { glyph } from './glyphs.generated.js';
+import { view } from './view.js';
+/**
+ * The identity prefix core's own views take, the package name by the plugin-identity convention.
+ * Core compiles from `src` alone, so the name is spelled here rather than read from the manifest.
+ */
+const core = '@loomcli/core';
+/**
+ * The default function of a marked lane: the matching glyph and one space before the first line,
+ * and continuation lines indented by the measured gutter without repeating the glyph. The
+ * semantic method appends the newline, so the view returns none.
+ */
+function marked(mark) {
+    return (message, context) => {
+        const glyphText = glyph[mark];
+        const gutter = ' '.repeat(context.width(glyphText) + 1);
+        return `${context.style[mark](glyphText)} ${message.replace(/(?<newline>\r?\n)(?!$)/gu, `$<newline>${gutter}`)}`;
+    };
+}
+/** One lane view over the original message string, line breaks and authored styles included. */
+function lane(name, render) {
+    return view(`${core}/lanes/${name}`, { render });
+}
+/**
+ * The five lane views core declares, one per semantic method. An application replaces the function
+ * of any of them through `views`, and the replacement owns the gutter the default supplies.
+ */
+const lanes = {
+    error: lane('error', marked('error')),
+    info: lane('info', marked('info')),
+    print: lane('print', (message) => message),
+    success: lane('success', marked('success')),
+    warn: lane('warn', marked('warning')),
+};
+/**
+ * The line a sequence writes on stderr when it stopped before its end, so an empty result and a
+ * truncated one never read alike. An override that returns the empty string silences it.
+ */
+const incompleteResult = view(`${core}/results/incomplete`, {
+    render: ({ path, written, yielded }) => `Output is incomplete: ${routedSubject(path)} stopped after ${yielded} rows, ${written} written.\n`,
+});
+/** Every view core declares, so one build register holds their identities from the start. */
+const coreViews = [...Object.values(lanes), incompleteResult];
+export { coreViews, incompleteResult, lanes };

package/dist/options.d.ts

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

package/dist/options.js

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

package/dist/output.d.ts

@@ -1,5 +1,9 @@
 import type { Writable } from 'node:stream';
-import type { Host, Out } from './types.js';
+import type { Lane } from './lanes.js';
+import type { RenderingPolicy } from './rendering.js';
+import type { Palette } from './style-state.js';
+import type { ActionChannel, Host, OpenResult, Out, ResultBinding, ViewContext } from './types.js';
+import type { ViewRegistry } from './view.js';
 type WriteState = {
     kind: 'ok';
 } | {
@@ -7,44 +11,118 @@ type WriteState = {
     error: unknown;
 };
 /** The semantic calls, which choose a destination. A rendered value has no purpose of its own. */
-type Purpose = 'print' | 'info' | 'success' | 'warn' | 'error';
+type Purpose = Lane;
+/** The two streams every write site names. */
+type Stream = 'stdout' | 'stderr';
 export declare class Output {
-    readonly host: Pick<Host, 'stdout' | 'stderr'>;
+    readonly host: Host;
+    private readonly signal;
     private readonly destinations;
     private renderFault;
-    readonly out: Out;
-    constructor(host: Pick<Host, 'stdout' | 'stderr'>);
-    /** A semantic message is one line on its destination; only `print` writes to stdout. */
-    emit(kind: Purpose, message: string): Promise<void>;
+    private readonly stops;
+    private 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.
+     */
+    readonly out: Out<OpenResult>;
+    private palette;
+    private policy;
+    private registry;
+    style: import("./style.js").ContextualStyle;
+    constructor(host: Host, signal: AbortSignal);
+    /**
+     * 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: ResultBinding): ActionChannel;
+    /**
+     * 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.
+     */
+    private results;
+    /**
+     * 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.
+     */
+    private resultFault;
+    /** The registry one invocation resolves through, republished as each contributor is read. */
+    useViews(registry: ViewRegistry): void;
+    /** The routed path, published once routing resolved it, which an incomplete sequence names. */
+    useRoute(path: readonly string[]): void;
+    /** What this invocation's output raised beside its calls, in the order it was raised. */
+    get stopped(): readonly unknown[];
+    configure(policy: RenderingPolicy, palette: Palette): void;
+    context(destination: Stream): ViewContext;
+    /**
+     * 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: Purpose, message: string, destination: Stream): Promise<void>;
     /**
      * 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: string): Promise<void>;
     /**
-     * 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.
+     */
+    private renderValue;
+    /**
+     * 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.
+     */
+    private sequenceView;
+    /**
+     * 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.
+     */
+    private sequence;
+    /**
+     * 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.
+     */
+    private incomplete;
+    /**
+     * 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.
      */
     private rendered;
     /**
-     * The rejected call. The first renderer failure is the reported one, so a later one adds no
+     * 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.
      */
     private renderFailed;
-    /** What a renderer failed with during this invocation, if one did. */
+    /** What a view failed with during this invocation, if one did. */
     get fault(): {
         cause: unknown;
     } | undefined;
+    /** The queue one stream writes through, opened the first time this invocation reaches it. */
+    private destination;
     private write;
     settle(): Promise<WriteState>;
     dispose(): void;
 }
 /**
  * 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.
  */