@loomcli/core 0.1.1 → 0.3.0

package/dist/environment.d.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from './plugin.js';
+/** The shallow type information an Application supplies before its Command graph is composed. */
+interface ApplicationEnvironment<Globals = {}, Plugins extends readonly Plugin[] = readonly []> {
+    readonly globals: Globals;
+    readonly plugins: Plugins;
+}
+interface RegistrationShape {
+    environment?: ApplicationEnvironment<unknown, readonly Plugin[]>;
+}
+/** The Application augments this interface once in its own TypeScript compilation context. */
+interface Register extends RegistrationShape {
+}
+type RegisteredEnvironment = Register extends {
+    environment: infer Environment;
+} ? Environment extends ApplicationEnvironment<unknown, readonly Plugin[]> ? Environment : never : ApplicationEnvironment;
+type RegisteredGlobals = RegisteredEnvironment['globals'];
+/** A private type marker avoids pretending parsed global values exist before an invocation. */
+declare const applicationEnvironment: unique symbol;
+type EnvironmentOf<Value extends {
+    readonly [applicationEnvironment]: ApplicationEnvironment<unknown, readonly Plugin[]>;
+}> = Value[typeof applicationEnvironment];
+export type { ApplicationEnvironment, EnvironmentOf, Register, RegisteredEnvironment, RegisteredGlobals, applicationEnvironment, };

package/dist/environment.js

@@ -0,0 +1 @@
+export {};

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { InputIdentity, Renderer } from './types.js';
+import type { InputIdentity } from './types.js';
 /**
  * The two short-group faults. A value option that is not last in its group names that option's
  * spelling; a group that mixes scopes names the whole group and the two letters that disagree.
@@ -14,28 +14,25 @@ type ShortGroupFault = {
     global: string;
     other: string;
 };
-/** One registration: the class it names, read as the prototype and the name that class holds. */
-interface Registration {
-    name: string;
-    prototype: unknown;
-    render: (failure: LoomError) => unknown;
-}
-/** Phantom key. It marks a failure registration and holds no runtime value. */
-declare const failureRegistration: unique symbol;
-/** The runtime value `renderFailure` returns. Its pair lives in the registry above. */
-declare class RegisteredFailure {
-    readonly [failureRegistration]: true;
-    constructor(registration: Registration);
-}
+/**
+ * Core's own text for one failure: its message under the category prefix its class carries, with
+ * the trailing newline every view's text carries. The four categories are disjoint branches of the
+ * hierarchy, so one ordered test reads every class, and a class without a prefix of its own writes
+ * the sentence alone. It is the default view of every failure class and the text the plain
+ * fallback path writes, so it runs no application code and nothing downstream composes its newline.
+ */
+export declare function defaultText(failure: LoomError): string;
 /** How a diagnostic names one Command inside a sentence: by name, or as the unnamed root. */
 export declare function commandSubject(name: string | null): string;
+/** The routed path names the Command a sentence speaks of; an empty path is the root. */
+export declare function routedSubject(command: readonly string[]): string;
 /** The same subject at the start of a sentence. */
 export declare function commandSentence(name: string | null): string;
 /**
  * Every failure `run()` reports is an instance of a public class. Each class carries the facts its
- * sentence interpolates, so a renderer reads them instead of parsing prose, and the exit status is
+ * sentence interpolates, so a view reads them instead of parsing prose, and the exit status is
  * a field of the base, so a subclass inherits it. `message` never carries a category prefix; the
- * default renderers add it.
+ * default views add it.
  */
 export declare abstract class LoomError extends Error {
     readonly exitCode: 1 | 2;
@@ -109,50 +106,33 @@ export declare class DeclarationError extends LoomError {
 export declare class FatalError extends LoomError {
     constructor(message: string);
 }
-/** Exit 1: an unexpected exception, a non-error throw, or a renderer that could not answer. */
+/** Exit 1: an unexpected exception, a non-error throw, or a view that could not answer. */
 export declare class InternalError extends LoomError {
     readonly cause: unknown;
     constructor(message: string, cause: unknown);
 }
+/** The four ways the results lane is broken, each named where core meets it. */
+export type ResultFault = 'missing' | 'repeated' | 'undeclared' | 'middleware';
+/**
+ * Exit 1: the promise a declared result makes was not kept. It wraps no thrown value, so its
+ * `cause` is `undefined`, and it extends `InternalError`, so an override of that class brands it
+ * and its default text carries the same prefix, while an override keyed by this class reaches it
+ * alone.
+ */
+export declare class ResultError extends InternalError {
+    readonly path: readonly string[];
+    readonly kind: ResultFault;
+    readonly cause: undefined;
+    constructor(kind: ResultFault, path: readonly string[]);
+}
 /** What a diagnostic says about an unexpected value, whether or not it was an Error. */
 export declare function reasonOf(thrown: unknown): string;
 /**
- * Why a returned value is not the text a renderer owes. A renderer is synchronous, so a returned
- * promise is a non-string return like any other, and its rejection is adopted and swallowed here:
- * an unobserved rejection would end the process before the invocation could report anything.
+ * Why a returned value is not the text a view owes. A view is synchronous, so a returned promise is
+ * a non-string return like any other, and its rejection is adopted and swallowed here: an
+ * unobserved rejection would end the process before the invocation could report anything.
  */
 export declare function notTextReason(value: unknown): string;
 /** Every thrown value reaches reporting as a failure class; anything else is internal. */
 export declare function toFailure(thrown: unknown): LoomError;
-/** An opaque registration pairing one failure class with a renderer for its instances. */
-export type FailureRenderer = Pick<RegisteredFailure, typeof failureRegistration>;
-/**
- * A registration pairing one failure class with a renderer for its instances. The helper is the
- * typed path for a class-keyed list, because an array literal cannot carry a different type
- * parameter per element.
- */
-export declare function renderFailure<Failure extends LoomError>(type: abstract new (...args: never[]) => Failure, renderer: Renderer<Failure>): FailureRenderer;
-/** The renderers one application registered, keyed by the class each one names. */
-export type FailureRegistry = ReadonlyMap<unknown, Registration>;
-/** One class answers to one renderer, so a second registration for it is a declaration fault. */
-export declare function buildFailures(failures: readonly FailureRenderer[]): FailureRegistry;
-/**
- * The report of one failure: the text core writes, and whether a registered renderer produced it.
- * An unrendered report carries core's own text, which the plain fallback path writes beside the
- * diagnostic naming the renderer that could not answer.
- */
-export type FailureReport = {
-    kind: 'rendered';
-    text: string;
-} | {
-    kind: 'unrendered';
-    text: string;
-    reason: string;
-};
-/**
- * The text core writes for one failure. Resolution walks the failure's prototype chain most
- * derived first through the application's registrations, then falls to core's own text, so a
- * registration for a base class brands every failure below it.
- */
-export declare function describeFailure(registry: FailureRegistry, failure: LoomError): FailureReport;
 export {};

package/dist/errors.js

@@ -1,7 +1,27 @@
-/** The routed path names the Command a token fault belongs to; an empty path is the root. */
+/** The same subject at the start of a sentence, where a token fault names its Command. */
 function routedSentence(command) {
-    const name = command.at(-1);
-    return name === undefined ? 'The root Command' : commandSentence(name);
+    const subject = routedSubject(command);
+    return `${subject.slice(0, 1).toUpperCase()}${subject.slice(1)}`;
+}
+/** The sentence one results-lane fault reports, which names the Command that holds it. */
+function resultMessage(kind, command) {
+    if (kind === 'missing') {
+        return `${routedSentence(command)} declares a result and its action returned without emitting one. Call out.results() once.`;
+    }
+    if (kind === 'repeated') {
+        return `${routedSentence(command)} emitted its result twice. Call out.results() once.`;
+    }
+    if (kind === 'undeclared') {
+        return `${routedSentence(command)} declares no result. Declare one with result() or rows() before action().`;
+    }
+    return `A middleware called out.results() on ${routedSubject(command)}. Only the action emits a result.`;
+}
+/**
+ * The clause that offers the candidates, which is absent when there are none: every child of the
+ * Command is hidden, so the diagnostic ends after the sentence that names the fault.
+ */
+function offering(candidates) {
+    return candidates.length === 0 ? '' : ` Use one of: ${candidates.join(', ')}.`;
 }
 function shortGroupMessage(fault) {
     return fault.reason === 'value-position'
@@ -10,12 +30,12 @@ function shortGroupMessage(fault) {
 }
 /**
  * Core's own text for one failure: its message under the category prefix its class carries, with
- * the trailing newline every renderer's text carries. The four categories are disjoint branches of
- * the hierarchy, so one ordered test reads every class, and a class without a prefix of its own
- * writes the sentence alone. A default rendering is the same kind of value as a custom one, so
- * nothing downstream composes the newline for it.
+ * the trailing newline every view's text carries. The four categories are disjoint branches of the
+ * hierarchy, so one ordered test reads every class, and a class without a prefix of its own writes
+ * the sentence alone. It is the default view of every failure class and the text the plain
+ * fallback path writes, so it runs no application code and nothing downstream composes its newline.
  */
-function defaultText(failure) {
+export function defaultText(failure) {
     if (failure instanceof UsageError) {
         return `Invalid input: ${failure.message}\n`;
     }
@@ -27,36 +47,15 @@ function defaultText(failure) {
     }
     return `${failure.message}\n`;
 }
-/** Every prototype in a failure's chain, most derived first, so one walk reads the registry. */
-function chainOf(failure) {
-    const chain = [];
-    let prototype = Object.getPrototypeOf(failure);
-    while (prototype !== null) {
-        chain.push(prototype);
-        prototype = Object.getPrototypeOf(prototype);
-    }
-    return chain;
-}
-/** Authored registrations register here, so the public type publishes nothing to reach. */
-const nodes = new WeakMap();
-/** The runtime value `renderFailure` returns. Its pair lives in the registry above. */
-class RegisteredFailure {
-    constructor(registration) {
-        nodes.set(this, registration);
-    }
-}
-/** Reads the pair behind a registered value; anything else is a declaration error. */
-function nodeOf(value) {
-    const registration = nodes.get(value);
-    if (!registration) {
-        throw new DeclarationError('The Application holds a value that is not a failure renderer. Supply the value returned by renderFailure(type, renderer).');
-    }
-    return registration;
-}
 /** How a diagnostic names one Command inside a sentence: by name, or as the unnamed root. */
 export function commandSubject(name) {
     return name === null ? 'the root Command' : `Command "${name}"`;
 }
+/** The routed path names the Command a sentence speaks of; an empty path is the root. */
+export function routedSubject(command) {
+    const name = command.at(-1);
+    return name === undefined ? 'the root Command' : commandSubject(name);
+}
 /** The same subject at the start of a sentence. */
 export function commandSentence(name) {
     const subject = commandSubject(name);
@@ -64,9 +63,9 @@ export function commandSentence(name) {
 }
 /**
  * Every failure `run()` reports is an instance of a public class. Each class carries the facts its
- * sentence interpolates, so a renderer reads them instead of parsing prose, and the exit status is
+ * sentence interpolates, so a view reads them instead of parsing prose, and the exit status is
  * a field of the base, so a subclass inherits it. `message` never carries a category prefix; the
- * default renderers add it.
+ * default views add it.
  */
 export class LoomError extends Error {
     exitCode;
@@ -96,7 +95,7 @@ export class UnknownCommandError extends UsageError {
     token;
     candidates;
     constructor(token, candidates) {
-        super(`Unknown command "${token}". Use one of: ${candidates.join(', ')}.`);
+        super(`Unknown command "${token}".${offering(candidates)}`);
         this.candidates = candidates;
         this.name = 'UnknownCommandError';
         this.token = token;
@@ -107,7 +106,7 @@ export class NonCallableCommandError extends UsageError {
     command;
     candidates;
     constructor(command, candidates) {
-        super(`${routedSentence(command)} requires a subcommand. Use one of: ${candidates.join(', ')}.`);
+        super(`${routedSentence(command)} requires a subcommand.${offering(candidates)}`);
         this.candidates = candidates;
         this.command = command;
         this.name = 'NonCallableCommandError';
@@ -186,7 +185,7 @@ export class FatalError extends LoomError {
         this.name = 'FatalError';
     }
 }
-/** Exit 1: an unexpected exception, a non-error throw, or a renderer that could not answer. */
+/** Exit 1: an unexpected exception, a non-error throw, or a view that could not answer. */
 export class InternalError extends LoomError {
     cause;
     constructor(message, cause) {
@@ -195,67 +194,36 @@ export class InternalError extends LoomError {
         this.name = 'InternalError';
     }
 }
+/**
+ * Exit 1: the promise a declared result makes was not kept. It wraps no thrown value, so its
+ * `cause` is `undefined`, and it extends `InternalError`, so an override of that class brands it
+ * and its default text carries the same prefix, while an override keyed by this class reaches it
+ * alone.
+ */
+export class ResultError extends InternalError {
+    path;
+    kind;
+    constructor(kind, path) {
+        super(resultMessage(kind, path), undefined);
+        this.kind = kind;
+        this.name = 'ResultError';
+        this.path = path;
+    }
+}
 /** What a diagnostic says about an unexpected value, whether or not it was an Error. */
 export function reasonOf(thrown) {
     return thrown instanceof Error ? thrown.message : 'An unknown error occurred.';
 }
 /**
- * Why a returned value is not the text a renderer owes. A renderer is synchronous, so a returned
- * promise is a non-string return like any other, and its rejection is adopted and swallowed here:
- * an unobserved rejection would end the process before the invocation could report anything.
+ * Why a returned value is not the text a view owes. A view is synchronous, so a returned promise is
+ * a non-string return like any other, and its rejection is adopted and swallowed here: an
+ * unobserved rejection would end the process before the invocation could report anything.
  */
 export function notTextReason(value) {
     void Promise.resolve(value).catch(() => undefined);
-    return `The renderer returned ${typeof value} instead of a string.`;
+    return `The view returned ${typeof value} instead of a string.`;
 }
 /** Every thrown value reaches reporting as a failure class; anything else is internal. */
 export function toFailure(thrown) {
     return thrown instanceof LoomError ? thrown : new InternalError(reasonOf(thrown), thrown);
 }
-/**
- * A registration pairing one failure class with a renderer for its instances. The helper is the
- * typed path for a class-keyed list, because an array literal cannot carry a different type
- * parameter per element.
- */
-export function renderFailure(type, renderer) {
-    return new RegisteredFailure({
-        name: 'name' in type && typeof type.name === 'string' ? type.name : 'a failure class',
-        prototype: 'prototype' in type ? type.prototype : undefined,
-        // Resolution reaches this registration through the same class, so the test always holds.
-        render: (failure) => (failure instanceof type ? renderer.render(failure) : undefined),
-    });
-}
-/** One class answers to one renderer, so a second registration for it is a declaration fault. */
-export function buildFailures(failures) {
-    const registry = new Map();
-    for (const failure of failures) {
-        const registration = nodeOf(failure);
-        if (registry.has(registration.prototype)) {
-            throw new DeclarationError(`The Application registers two failure renderers for "${registration.name}". Remove one registration.`);
-        }
-        registry.set(registration.prototype, registration);
-    }
-    return registry;
-}
-/**
- * The text core writes for one failure. Resolution walks the failure's prototype chain most
- * derived first through the application's registrations, then falls to core's own text, so a
- * registration for a base class brands every failure below it.
- */
-export function describeFailure(registry, failure) {
-    const registration = chainOf(failure)
-        .map((prototype) => registry.get(prototype))
-        .find((entry) => entry !== undefined);
-    if (!registration) {
-        return { kind: 'rendered', text: defaultText(failure) };
-    }
-    try {
-        const text = registration.render(failure);
-        return typeof text === 'string'
-            ? { kind: 'rendered', text }
-            : { kind: 'unrendered', reason: notTextReason(text), text: defaultText(failure) };
-    }
-    catch (error) {
-        return { kind: 'unrendered', reason: reasonOf(error), text: defaultText(failure) };
-    }
-}

package/dist/extension.d.ts

@@ -0,0 +1,99 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ArgumentNode, CommandNode, OptionNode } from './inspect.js';
+/** The three declaration kinds an extension can name, each with its own node in the graph. */
+type ExtensionTarget = 'argument' | 'command' | 'option';
+/**
+ * The descriptor supertype a plugin's `extensions` list uses. It publishes the identity and the
+ * target and erases both the schema and the factory call signature, because a schema-typed call
+ * signature relates only by schema identity and a list cannot name one schema per element. A
+ * descriptor is assignable to it; an extension value, which publishes its brand alone, is not.
+ */
+interface AnyExtension {
+    readonly identity: string;
+    readonly target: ExtensionTarget;
+}
+/** One carried value: the input its author supplied and the descriptor that produced it. */
+interface CarriedValue {
+    descriptor: AnyExtension;
+    input: unknown;
+}
+/** Phantom key. It brands an extension value with its target and holds no runtime value. */
+declare const extensionTarget: unique symbol;
+/**
+ * The value one extension produces, branded with its target so a value on the wrong declaration is
+ * a compile error. It publishes the brand alone, so a value is never mistaken for the descriptor
+ * that produced it, and the input it carries stays private to this package.
+ */
+declare class ExtensionCarrier<Target extends ExtensionTarget> {
+    readonly [extensionTarget]: (target: Target) => Target;
+    constructor(record: CarriedValue);
+}
+/** A branded extension value, keyed by its extension's identity and typed by its target. */
+type ExtensionValue<Target extends ExtensionTarget> = Pick<ExtensionCarrier<Target>, typeof extensionTarget>;
+/**
+ * A descriptor that is also a factory: calling it with the schema's input returns the branded value
+ * a declaration carries. The schema is public so a typed read recovers the output type.
+ */
+interface Extension<Target extends ExtensionTarget = ExtensionTarget, Schema extends StandardSchemaV1 = StandardSchemaV1> extends AnyExtension {
+    (input: StandardSchemaV1.InferInput<Schema>): ExtensionValue<Target>;
+    readonly schema: Schema;
+    readonly target: Target;
+}
+/**
+ * One typed fact a plugin defines for one target. The descriptor is compared by reference wherever
+ * it appears, so one identity means one descriptor and a duplicated package copy is visible.
+ */
+declare function extension<Target extends ExtensionTarget, Schema extends StandardSchemaV1>(identity: string, config: {
+    schema: Schema;
+    target: Target;
+}): Extension<Target, Schema>;
+/** The node kind one descriptor's target names, so a read against another kind cannot compile. */
+type NodeFor<Target extends ExtensionTarget> = Target extends 'command' ? CommandNode : Target extends 'option' ? OptionNode : ArgumentNode;
+/** Stored output is plain data the graph froze, so every read of it is read-only to any depth. */
+type DeepReadonly<Value> = Value extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : Value extends object ? {
+    readonly [Key in keyof Value]: DeepReadonly<Value[Key]>;
+} : Value;
+/**
+ * The typed read of one extension value. It takes the node kind the descriptor targets, returns the
+ * stored output or `undefined`, compares the descriptor by reference with the one that produced the
+ * value, and runs no schema.
+ */
+declare function readExtension<Target extends ExtensionTarget, Schema extends StandardSchemaV1>(node: NodeFor<Target>, descriptor: Extension<Target, Schema>): DeepReadonly<StandardSchemaV1.InferOutput<Schema>> | undefined;
+/** The declaration one `extensions` slot belongs to, as its own diagnostics name it. */
+interface ExtensionSubject {
+    /** The subject after a preposition, such as `on Command "get"`. */
+    phrase: string;
+    /** The subject at the start of a sentence, such as `Command "get"`. */
+    sentence: string;
+}
+/** Every descriptor one build has met, so a second descriptor under one identity is visible. */
+type DescriptorRegistry = Map<string, AnyExtension>;
+/**
+ * The record each declaration published during one build, keyed by the declaration itself. The
+ * records live here rather than on the declaration, because one build's outputs belong to that
+ * build alone and inspection reads them back with the nodes it renders.
+ */
+type ExtensionRecords = Map<object, Readonly<Record<string, unknown>>>;
+/** Whether a value is a descriptor: a callable object carrying an identity and a declared target. */
+declare function isDescriptor(value: unknown): value is AnyExtension;
+/** One identity means one descriptor, wherever on the graph that descriptor appears. */
+declare function registerDescriptor(descriptors: DescriptorRegistry, descriptor: AnyExtension): void;
+/** Everything one `extensions` slot needs to answer: whose it is, and what it may carry. */
+interface ExtensionSlot {
+    declared: unknown;
+    descriptors: DescriptorRegistry;
+    subject: ExtensionSubject;
+    target: ExtensionTarget;
+}
+/**
+ * The frozen record one declaration publishes: each carried value validated once, synchronously,
+ * and stored under its extension's identity. The descriptors that produced them are recorded beside
+ * the record, so a typed read compares by reference without the graph carrying a reference.
+ */
+declare function buildExtensions(slot: ExtensionSlot): Readonly<Record<string, unknown>>;
+/** Layers validate in authoring order; replacement updates existing keys without reinsertion. */
+declare function buildCommandExtensions(slot: Omit<ExtensionSlot, 'declared' | 'target'> & {
+    layers: readonly unknown[];
+}): Readonly<Record<string, unknown>>;
+export type { AnyExtension, DeepReadonly, DescriptorRegistry, Extension, ExtensionRecords, ExtensionSubject, ExtensionTarget, ExtensionValue, };
+export { buildCommandExtensions, buildExtensions, extension, isDescriptor, readExtension, registerDescriptor, };