@loomcli/core 0.2.0 → 0.4.0

package/dist/inspect.d.ts

@@ -1,5 +1,11 @@
 import type { BuiltGraph } from './command.js';
-/** One declared argument. `default` wraps the declared value, so an explicit `undefined` shows. */
+import type { DeclaredResult } from './types.js';
+/** The plain JSON Schema a validated input publishes, or `null` where the graph holds no shape. */
+type InputSchema = Readonly<Record<string, unknown>> | null;
+/**
+ * One declared argument. `default` wraps the declared value, so an explicit `undefined` shows, and
+ * `schema` is the input schema its validator publishes through the Standard JSON Schema converter.
+ */
 interface ArgumentNode {
     readonly name: string;
     readonly description: string | undefined;
@@ -7,6 +13,7 @@ interface ArgumentNode {
     readonly variadic: boolean;
     readonly validated: boolean;
     readonly validateOmitted: boolean;
+    readonly schema: InputSchema;
     readonly default: {
         readonly value: unknown;
     } | undefined;
@@ -14,10 +21,15 @@ interface ArgumentNode {
 }
 /**
  * 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.
+ * `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.
+ * `schema` is the input schema the validator publishes. A Boolean option validates nothing, so its
+ * variant carries the field at `null`, and every projection built on the node holds if a later
+ * contract lets it validate.
  */
 type OptionNode = {
     readonly type: 'string';
@@ -32,6 +44,7 @@ type OptionNode = {
     readonly multiple: boolean;
     readonly validated: boolean;
     readonly validateOmitted: boolean;
+    readonly schema: InputSchema;
     readonly default: {
         readonly value: unknown;
     } | undefined;
@@ -47,6 +60,7 @@ type OptionNode = {
     readonly short: string | null;
     readonly negative: string | null;
     readonly polarity: 'positive' | 'negative' | 'both';
+    readonly schema: InputSchema;
     readonly extensions: Readonly<Record<string, unknown>>;
 };
 /**
@@ -64,11 +78,21 @@ interface CommandNode {
     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`. `version`
  * and `description` are the Application's own core facts. `version` is the declared string, or
@@ -82,6 +106,16 @@ interface CommandGraph {
     readonly globals: readonly OptionNode[];
     readonly root: CommandNode;
 }
+/**
+ * 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
@@ -91,5 +125,5 @@ 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

@@ -17,23 +17,71 @@ function spellingsOf(table, name) {
     return spellings;
 }
 /**
- * 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)));
     }
     if (isPlainObject(value)) {
-        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshot(entry)])));
+        return snapshotRecord(value);
     }
     return value;
 }
+/** The snapshot of one plain object, under the record type the caller already established. */
+function snapshotRecord(value) {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshot(entry)])));
+}
 /** A declared default is wrapped, so `default: undefined` reads apart from no default at all. */
 function declaredDefault(config) {
     return 'default' in config ? Object.freeze({ value: snapshot(config.default) }) : undefined;
 }
+/**
+ * The JSON Schema draft build asks every converter for, with no library options. Every converter
+ * receives this one object, so it is frozen against a library that writes to its argument.
+ */
+const schemaTarget = Object.freeze({ target: 'draft-2020-12' });
+/** Whether a validator declares the Standard JSON Schema converter, both sides, beside `validate`. */
+function publishesSchema(schema) {
+    const props = schema['~standard'];
+    return ('jsonSchema' in props &&
+        typeof props.jsonSchema === 'object' &&
+        props.jsonSchema !== null &&
+        'input' in props.jsonSchema &&
+        typeof props.jsonSchema.input === 'function' &&
+        'output' in props.jsonSchema &&
+        typeof props.jsonSchema.output === 'function');
+}
+/**
+ * The input-side schema a declaration's validator publishes, snapshotted the way a declared
+ * default is, or `null` where the graph holds no published shape: no validator, a validator with
+ * no converter, or a converter that throws or returns anything but a plain object. The contract of
+ * 2026-09-19 made that last case a declaration error `inspect()` alone reports; that diagnostic is
+ * held while the question of how a run tells development from a distributed application is
+ * decided, so it reads `null` on both paths.
+ */
+function inputSchema(config) {
+    const schema = 'validate' in config ? config.validate : undefined;
+    if (schema === undefined) {
+        return null;
+    }
+    // The converter is the library's code from the first property read.
+    // A throw on reaching it and a throw on calling it are one failure.
+    try {
+        if (!publishesSchema(schema)) {
+            return null;
+        }
+        const published = schema['~standard'].jsonSchema.input(schemaTarget);
+        return isPlainObject(published) ? snapshotRecord(published) : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** 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;
@@ -52,6 +100,7 @@ function optionNode(input, { records, scope, table }) {
             name,
             negative,
             polarity: config.polarity ?? 'positive',
+            schema: null,
             scope,
             short,
             type: 'boolean',
@@ -67,6 +116,7 @@ function optionNode(input, { records, scope, table }) {
             multiple: config.multiple === true,
             name,
             required: config.required === true,
+            schema: inputSchema(config),
             scope,
             short,
             type: 'string',
@@ -84,6 +134,7 @@ function argumentNode(slot, records) {
         extensions: extensionsOf(records, slot.input),
         name,
         required: slot.required,
+        schema: inputSchema(config),
         validateOmitted: validatesOmission(slot.input),
         validated: config.validate !== undefined,
         variadic: slot.variadic,
@@ -111,9 +162,21 @@ function commandNode(command, place) {
         name: command.name,
         options: Object.freeze(optionNodes(command.inputs, { records, scope: 'application', table: command.options })),
         path,
+        result: resultNode(command.result),
     };
     return Object.freeze(node);
 }
+/** 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
@@ -138,4 +201,4 @@ function inspectGraph(name, graph, facts) {
     };
     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/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.
  */