@loomcli/core 0.1.0

package/dist/application.d.ts

@@ -0,0 +1,72 @@
+import type { AfterAction, AfterArgument, AfterCommand, Command, CommandMethod, CommandState } from './command.js';
+import type { FailureRenderer } from './errors.js';
+import type { GlobalOptions } from './globals.js';
+import type { CommandGraph } from './inspect.js';
+import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, MultipleConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, RunOptions, ValidateOmittedConstraint } from './types.js';
+/**
+ * Every authoring call an Application can publish, beside `run()` and `name`, which always remain.
+ * An Application's type state is a subset of these, and each call removes the names it invalidates.
+ * The unnamed root declares what a named Command declares, except for `alias()`: the root answers
+ * to no bare token, so it has no name to alias.
+ */
+export type ApplicationMethod = Exclude<CommandMethod, 'alias'>;
+/**
+ * Everything an application configures beside its declarations: the options every Command shares,
+ * and the renderers that answer the failure classes core throws.
+ */
+export interface ApplicationOptions<Globals = {}> {
+    globals?: GlobalOptions<Globals>;
+    failures?: readonly FailureRenderer[];
+}
+/**
+ * The Application holds the unnamed root's declaration state and applies the same transitions a
+ * Command does, so each declaration call has one typed implementation and no builder to recover.
+ */
+declare class ApplicationBuilder<Args, Options, Globals, State extends ApplicationMethod = ApplicationMethod> {
+    #private;
+    readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals>;
+    constructor(name: string, root: CommandState<Args, Options, Globals>, config: {
+        failures: readonly FailureRenderer[];
+        options?: unknown;
+    });
+    get name(): string;
+    argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>>;
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args, Options & Record<Name, OptionValue<Config>>, Globals, State>;
+    /** The action is the last call, so it returns `AfterAction`: only `run()` and `name` remain. */
+    action(handler: Action<Args, Globals & Options>): Application<Args, Options, Globals>;
+    /** A child arrives in any type state, because its own action is the call that finished it. */
+    command(child: Command<unknown, unknown, Globals>): Application<Args, Options, Globals, AfterCommand<State>>;
+    /**
+     * One wrapper for every declaration call, so the Application keeps its name. The next state
+     * travels through this call: each method names its transition in its return type, and the
+     * wrapper publishes the same runtime value in exactly that state.
+     */
+    private derive;
+    /**
+     * The built graph as plain, frozen data. It applies every rule `run()` applies without a schema,
+     * in the order `run()` applies them, and throws `DeclarationError` when one fails. Validating a
+     * declared default through its schema can be asynchronous, so that one rule stays in `run()`.
+     * Nothing is cached: each call builds the graph anew.
+     */
+    inspect(): CommandGraph;
+    run(options?: RunOptions): Promise<ExitCode>;
+}
+/**
+ * The authoring surface of an Application in one type state: the root Command's calls, `command()`,
+ * `inspect()`, `run()`, and `name`. Every authoring call returns a new declaration value, leaves
+ * its receiver unchanged, and publishes only the calls that are still valid after it. `inspect()`,
+ * `run()`, and `name` survive every call. `State` lists the authoring calls a value still offers.
+ * It defaults to the state after `action()`, which publishes the fewest calls, so
+ * `Application<A, O, G>` accepts an application in any state, a finished one included.
+ */
+export type Application<Args = {}, Options = {}, Globals = {}, State extends ApplicationMethod = AfterAction> = Pick<ApplicationBuilder<Args, Options, Globals, State>, typeof declaredTypes | 'inspect' | 'name' | 'run' | State>;
+interface ApplicationConstructor {
+    new (name: string): Application<{}, {}, {}, ApplicationMethod>;
+    new <Globals = {}>(name: string, options: ApplicationOptions<Globals>): Application<{}, {}, Globals, ApplicationMethod>;
+}
+/**
+ * The public constructor takes a name and one options object. The globals type narrows to the
+ * supplied value, and the failure renderers configure the application the way its commands do.
+ */
+export declare const Application: ApplicationConstructor;
+export {};

package/dist/application.js

@@ -0,0 +1,188 @@
+import { attachChild, buildGraph, collectInputs, declareAction, declareArgument, declareOption, freshState, selectCommand, } from './command.js';
+import { buildFailures, DeclarationError, describeFailure, InternalError, reasonOf, toFailure, } from './errors.js';
+import { isGlobalOptions } from './globals.js';
+import { captureHost } from './host.js';
+import { inspectGraph } from './inspect.js';
+import { Output, reportPlainly } from './output.js';
+import { captureConfig, checkDeclarations, prepareInputs } from './validation.js';
+/** The registry a failure is reported through when the application's own could not be built. */
+const noRegistrations = new Map();
+/**
+ * The Application holds the unnamed root's declaration state and applies the same transitions a
+ * Command does, so each declaration call has one typed implementation and no builder to recover.
+ */
+class ApplicationBuilder {
+    #name;
+    #root;
+    #failures;
+    // The constructor's raw options argument stays unexamined until build.
+    // The options-slot rules answer at the same point every other authoring fault does:
+    // `inspect()` and `run()`.
+    #options;
+    constructor(name, root, config) {
+        this.#failures = config.failures;
+        this.#name = name;
+        this.#options = config.options;
+        this.#root = root;
+    }
+    get name() {
+        return this.#name;
+    }
+    argument(name, config) {
+        const input = {
+            config: captureConfig(config),
+            kind: 'argument',
+            name,
+        };
+        return this.derive(declareArgument(this.#root, input));
+    }
+    option(name, config) {
+        const input = {
+            config: captureConfig(config),
+            kind: 'option',
+            name,
+        };
+        return this.derive(declareOption(this.#root, input));
+    }
+    /** The action is the last call, so it returns `AfterAction`: only `run()` and `name` remain. */
+    action(handler) {
+        return this.derive(declareAction(this.#root, handler));
+    }
+    /** A child arrives in any type state, because its own action is the call that finished it. */
+    command(child) {
+        return this.derive(attachChild(this.#root, child));
+    }
+    /**
+     * One wrapper for every declaration call, so the Application keeps its name. The next state
+     * travels through this call: each method names its transition in its return type, and the
+     * wrapper publishes the same runtime value in exactly that state.
+     */
+    derive(root) {
+        return new ApplicationBuilder(this.#name, root, {
+            failures: this.#failures,
+            options: this.#options,
+        });
+    }
+    /**
+     * The built graph as plain, frozen data. It applies every rule `run()` applies without a schema,
+     * in the order `run()` applies them, and throws `DeclarationError` when one fails. Validating a
+     * declared default through its schema can be asynchronous, so that one rule stays in `run()`.
+     * Nothing is cached: each call builds the graph anew.
+     */
+    inspect() {
+        checkOptions(this.#options);
+        buildFailures(this.#failures);
+        const graph = buildGraph(this.#root);
+        checkDeclarations([...graph.globals.inputs, ...collectInputs(graph.root)]);
+        return inspectGraph(this.#name, graph);
+    }
+    async run(options) {
+        let stderr = process.stderr;
+        let output = undefined;
+        let code = 0;
+        let reportingFailed = false;
+        // A registry that could not be built reports through core's defaults, not through itself.
+        let registry = undefined;
+        try {
+            const overrides = options?.host;
+            stderr = overrides?.stderr ?? stderr;
+            const host = captureHost(overrides, stderr);
+            output = new Output(host);
+            checkOptions(this.#options);
+            registry = buildFailures(this.#failures);
+            const graph = buildGraph(this.#root);
+            const inputs = { globals: graph.globals.inputs, locals: collectInputs(graph.root) };
+            const defaults = await prepareInputs(inputs, host);
+            const selected = await selectCommand(graph, { defaults, host });
+            await selected.dispatch({
+                host,
+                out: output.out,
+                passthrough: selected.passthrough,
+                values: selected.values,
+            });
+            // The fault check covers the same window the write accounting covers.
+            // A render failure an unawaited helper raised is still this invocation's failure.
+            await output.settle();
+            const fault = output.fault;
+            if (fault) {
+                // The action returned, so the renderer failure is this invocation's own failure.
+                throw new InternalError(`Rendering output failed: ${reasonOf(fault.cause)}`, fault.cause);
+            }
+        }
+        catch (error) {
+            try {
+                const failure = toFailure(error);
+                code = failure.exitCode;
+                output ??= new Output({ stderr, stdout: process.stdout });
+                const writes = await output.settle();
+                if (writes.kind === 'ok') {
+                    const report = describeFailure(registry ?? noRegistrations, failure);
+                    if (report.kind === 'rendered') {
+                        // The renderer already owns every byte, trailing newline included: pass it through.
+                        await output.report(report.text);
+                    }
+                    else {
+                        code = 1;
+                        // `report.text` is core's default text, which already ends in `\n`.
+                        await reportPlainly(stderr, `${report.text}Internal error: Rendering the failure failed: ${report.reason}\n`);
+                    }
+                }
+            }
+            catch {
+                code = 1;
+                reportingFailed = true;
+            }
+        }
+        if (output) {
+            const writes = await output.settle();
+            if (writes.kind === 'failed') {
+                code = 1;
+                reportingFailed = true;
+            }
+            output.dispose();
+        }
+        if (reportingFailed) {
+            await reportPlainly(stderr, 'Internal error: Could not write invocation output.\n');
+        }
+        process.exitCode = code;
+        return code;
+    }
+}
+/** The options slot holds one object literal, so a declaration that carries state is not one. */
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * The second argument, read where it is supplied. The retired positional form declares its globals
+ * on a value that holds no `globals` key, so without this rule the globals vanish silently and the
+ * operator, not the author, meets the consequence as an unknown-option error.
+ */
+function checkOptions(options) {
+    if (isGlobalOptions(options)) {
+        throw new DeclarationError('The Application takes an options object. Supply { globals } instead of a positional GlobalOptions value.');
+    }
+    if (options !== undefined && !isPlainObject(options)) {
+        throw new DeclarationError('The Application options must be an object. Supply { globals, failures }.');
+    }
+}
+/**
+ * The runtime class behind the public constructor. It is generic so that an instance's `Globals`
+ * is the type of the value it holds, with `{}` standing in when there is none, which is what each
+ * signature of the constructor interface publishes.
+ */
+class ApplicationDeclaration extends ApplicationBuilder {
+    constructor(name, options) {
+        // The options slot is read defensively, never inspected: an invalid value still yields
+        // `globals` and `failures` of some kind, and `checkOptions` reports it at build instead.
+        super(name, freshState(null, options?.globals), { failures: options?.failures ?? [], options });
+    }
+}
+/**
+ * The public constructor takes a name and one options object. The globals type narrows to the
+ * supplied value, and the failure renderers configure the application the way its commands do.
+ */
+export const Application = ApplicationDeclaration;

package/dist/command.d.ts

@@ -0,0 +1,176 @@
+import type { BuiltGlobals, GlobalOptions } from './globals.js';
+import { compileOptions } from './options.js';
+import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, Host, MultipleConstraint, NameConstraint, OptionConfig, OptionValue, Out, ValidateOmittedConstraint } from './types.js';
+import type { ArgumentInput, DefaultValues, InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
+/** One positional slot: the declaration it fills and whether it takes the remaining tokens. */
+export interface ArgumentSlot {
+    input: InputDeclaration;
+    required: boolean;
+    variadic: boolean;
+}
+export interface DispatchInput {
+    host: Host;
+    out: Out;
+    passthrough: string[];
+    values: ValidatedInputs;
+}
+/**
+ * One child a bare token reaches, under its canonical name or one of its hidden aliases.
+ * `name` repeats the key `children` holds, because `BuiltCommand.name` is `string | null` for the
+ * root and the routed path a child extends holds strings alone.
+ */
+export interface RoutedChild {
+    command: BuiltCommand;
+    name: string;
+}
+/**
+ * A group registers no action, so its `dispatch` is `undefined` and selection rejects it.
+ * `children` is keyed by canonical name, so every candidate list and every walk of the graph reads
+ * it, and `routes` adds the hidden aliases, so routing alone resolves them.
+ */
+export interface BuiltCommand {
+    aliases: readonly string[];
+    arguments: readonly ArgumentSlot[];
+    children: ReadonlyMap<string, BuiltCommand>;
+    dispatch: ((input: DispatchInput) => unknown) | undefined;
+    inputs: readonly InputDeclaration[];
+    name: string | null;
+    options: ReturnType<typeof compileOptions>;
+    routes: ReadonlyMap<string, RoutedChild>;
+}
+/** Phantom key. It marks a Command value, so only a Command can be attached as a child. */
+export declare const commandValue: unique symbol;
+/**
+ * Every authoring call a Command can publish. A Command's type state is a subset of these names,
+ * and each call removes the names it invalidates. A Command attaches children at any depth, so
+ * `command()` belongs to every Command and to the unnamed root alike.
+ */
+export type CommandMethod = 'action' | 'alias' | 'argument' | 'command' | 'option';
+/** One Command declares arguments or attaches children, so the first call removes the other. */
+export type AfterArgument<State> = Exclude<State, 'command'>;
+/** The same rule read from the other side. */
+export type AfterCommand<State> = Exclude<State, 'argument'>;
+/** The action is the last declaration call, so no declaration call survives it. */
+export type AfterAction = never;
+/** A declaration made after the action, kept in authoring order so build reports the first. */
+type LateDeclaration = {
+    alias: string;
+    kind: 'alias';
+} | {
+    child: object;
+    kind: 'child';
+} | {
+    input: InputDeclaration;
+    kind: 'input';
+};
+/**
+ * The names one `alias()` call declares. Each call keeps its own group, so a call that names none,
+ * which the types reject and a JavaScript author can still write, reports as the call it is.
+ */
+type AliasDeclaration = readonly string[];
+/** The attachable shape of a Command, without its inferred declaration types. */
+interface AttachedCommand {
+    readonly name: string | null;
+    build(context: BuildContext): BuiltCommand;
+}
+/**
+ * One graph build's shared state. `globals` compiles once and every Command reads it. `owners`
+ * records the name of the parent that claimed each node, so a second parent holding the same value
+ * is building a graph with more than one path to that node, not a tree. The build is a depth-first
+ * walk in attachment order, and a parent claims each child as the walk reaches it, so the first
+ * owner is the parent whose attachment the walk meets first.
+ */
+interface BuildContext {
+    globals: BuiltGlobals;
+    owners: Map<AttachedCommand, string | null>;
+}
+/**
+ * Everything one Command declaration holds. The transitions below copy it with fields replaced, and
+ * the Command and Application builders share them, so one declaration call has one implementation.
+ * Absent globals stay `undefined`, so every declaration without globals agrees on identity.
+ */
+export interface CommandState<Args, Options, Globals> {
+    actions: readonly Action<Args, Globals & Options>[];
+    aliases: readonly AliasDeclaration[];
+    bind: (values: ValidatedInputs) => {
+        args: Args;
+        options: Options;
+    };
+    children: readonly object[];
+    globals: GlobalOptions<Globals> | undefined;
+    inputs: readonly InputDeclaration[];
+    late: readonly LateDeclaration[];
+    name: string | null;
+}
+/** The state every declaration starts from. The unnamed root and each named Command share it. */
+export declare function freshState<Globals>(name: string | null, globals: GlobalOptions<Globals> | undefined): CommandState<{}, {}, Globals>;
+/** The declared value joins `args` under its literal name, typed by its own config. */
+export declare function declareArgument<Args, Options, Globals, Name extends string, Config extends ArgumentConfig>(state: CommandState<Args, Options, Globals>, input: ArgumentInput<Name, Config>): CommandState<Args & Record<Name, ArgumentValue<Config>>, Options, Globals>;
+/** The declared value joins `options` under its literal name, typed by its own config. */
+export declare function declareOption<Args, Options, Globals, Name extends string, Config extends OptionConfig>(state: CommandState<Args, Options, Globals>, input: OptionInput<Name, Config>): CommandState<Args, Options & Record<Name, OptionValue<Config>>, Globals>;
+/** One call's names stay one group, so the empty call the types reject still reports as one. */
+export declare function declareAlias<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, names: AliasDeclaration): CommandState<Args, Options, Globals>;
+export declare function declareAction<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, handler: Action<Args, Globals & Options>): CommandState<Args, Options, Globals>;
+/** Attaching is a declaration call too, so the receiver keeps the children it already had. */
+export declare function attachChild<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, child: object): CommandState<Args, Options, Globals>;
+/** Validates one declaration against the shared globals table and compiles it for dispatch. */
+export declare function buildCommand<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, context: BuildContext): BuiltCommand;
+/** The globals table and the owners record each compile once per invocation and the whole graph shares them. */
+export declare function buildGraph<Args, Options, Globals>(root: CommandState<Args, Options, Globals>): {
+    globals: BuiltGlobals;
+    root: BuiltCommand;
+};
+export declare class CommandBuilder<Args, Options, Globals, State extends CommandMethod = CommandMethod> {
+    #private;
+    readonly [commandValue]: true;
+    readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals>;
+    constructor(state: CommandState<Args, Options, Globals>);
+    get name(): string | null;
+    argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>>;
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args, Options & Record<Name, OptionValue<Config>>, Globals, State>;
+    /**
+     * Hidden aliases are other bare tokens that route to this Command. They invalidate no call, and
+     * the tuple rest parameter rejects a call that names none.
+     */
+    alias(...names: [string, ...string[]]): Command<Args, Options, Globals, State>;
+    /** A child arrives in any type state, because its own action is the call that finished it. */
+    command(child: Command<unknown, unknown, Globals>): Command<Args, Options, Globals, AfterCommand<State>>;
+    /** The action is the last declaration call, so the value it returns publishes `AfterAction`. */
+    action(handler: Action<Args, Globals & Options>): Command<Args, Options, Globals>;
+    build(context: BuildContext): BuiltCommand;
+}
+/**
+ * The authoring surface of a Command in one type state. Every call returns a new declaration value,
+ * leaves its receiver unchanged, and publishes only the calls that are still valid after it. The
+ * declarations themselves stay private, so no consumer can reach them. `State` lists the authoring
+ * calls a value still offers. It defaults to the state after `action()`, which publishes the fewest
+ * calls, so `Command<A, O, G>` accepts a Command in any state, a finished one included.
+ */
+export type Command<Args = {}, Options = {}, Globals = {}, State extends CommandMethod = AfterAction> = Pick<CommandBuilder<Args, Options, Globals, State>, typeof commandValue | typeof declaredTypes | State>;
+interface CommandConstructor {
+    new (name: string): Command<{}, {}, {}, CommandMethod>;
+    new <Globals>(name: string, globals: GlobalOptions<Globals>): Command<{}, {}, Globals, CommandMethod>;
+}
+/** The public constructor requires a name and narrows the globals type to the supplied value. */
+export declare const Command: CommandConstructor;
+/** Every declaration in the graph, so defaults are validated before any token is read. */
+export declare function collectInputs(command: BuiltCommand): InputDeclaration[];
+/** Bare tokens, names or aliases, select children until a Command has none; a hyphen commits. */
+export declare function route(root: BuiltCommand, tokens: readonly string[]): {
+    command: BuiltCommand;
+    path: string[];
+    tokens: string[];
+};
+/** Consumes globals, routes to a Command, then validates globals and locals in one pass. */
+export declare function selectCommand(graph: {
+    globals: BuiltGlobals;
+    root: BuiltCommand;
+}, invocation: {
+    defaults: DefaultValues;
+    host: Host;
+}): Promise<{
+    dispatch: (input: DispatchInput) => unknown;
+    passthrough: string[];
+    values: ValidatedInputs;
+}>;
+export {};