@loomcli/core 0.4.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drew Butler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/application.d.ts

@@ -1,12 +1,13 @@
-import type { AfterAction, AttachmentConstraint, AfterArgument, AfterCommand, AfterResult, Command, CommandMethod, CommandState, ResultMethod } from './command.js';
+import type { AfterAction, AttachmentConstraint, AfterArgument, AfterCommand, AfterResult, ChildOwner, Command, CommandMethod, CommandNodeHandle, CommandState, ResultMethod } from './command.js';
 import type { ApplicationEnvironment, applicationEnvironment } from './environment.js';
 import type { ExtensionValue } from './extension.js';
 import type { GlobalsState } from './globals.js';
 import type { CommandGraph } from './inspect.js';
-import type { Plugin } from './plugin.js';
+import type { BuiltPlugin, Plugin } from './plugin.js';
 import type { RenderingPolicy } from './rendering.js';
-import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, MultipleConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, ResultViews, ResultViewsOf, RowViews, RunOptions, ValidateOmittedConstraint } from './types.js';
-import type { ViewOverride } from './view.js';
+import type { Translation, TranslatorRegistry } from './translators.js';
+import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, GlobalOmissionConstraint, PerValueConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, ResultViews, ResultViewsOf, RowViews, RunOptions, ValidateOmittedConstraint } from './types.js';
+import type { ViewContributions, ViewOverride } from './view.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.
@@ -14,14 +15,46 @@ import type { ViewOverride } from './view.js';
  * to no bare token, so it has no name to alias.
  */
 export type ApplicationMethod = Exclude<CommandMethod, 'alias'> | 'globalOption';
+/**
+ * The build fact file, `loom.packet.json`, that the entry imports and hands to the Application.
+ * `build` is typed `string`, because a JSON module types its members that way, and the Application
+ * constructor accepts `development` or `distributed` alone. Core ignores every other member.
+ */
+export interface Packet {
+    readonly build: string;
+}
 export interface ApplicationOptions<Plugins extends readonly Plugin[] = readonly Plugin[]> {
     rendering?: RenderingPolicy;
+    /** The packet that says whether this is a development build. With none, it is distributed. */
+    packet?: Packet;
     views?: readonly ViewOverride[];
+    translators?: readonly Translation[];
     plugins?: Plugins;
     extensions?: readonly ExtensionValue<'command'>[];
     description?: string;
     version?: string;
 }
+/**
+ * Everything an Application holds beside its root declaration and its globals, each part checked by
+ * the constructor or the call that set it.
+ */
+interface ApplicationConfig {
+    /** Whether the application's own `command()` or `action()` has run, which closes `globalOption()`. */
+    composed: boolean;
+    /** Whether the packet reads `development`, read once at construction. */
+    development: boolean;
+    /** Each installed plugin's view contributions, in installation order. */
+    contributors: readonly ViewContributions[];
+    facts: ApplicationFacts;
+    /** The parent that claimed each node the graph holds, so one value attaches at one point. */
+    owners: ReadonlyMap<CommandNodeHandle, ChildOwner>;
+    plugins: readonly BuiltPlugin[];
+    rendering: RenderingPolicy;
+    /** The application's translations, then each installed plugin's, in resolution order. */
+    translators: TranslatorRegistry;
+    /** The application's own view overrides. */
+    views: ViewContributions;
+}
 /**
  * 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.
@@ -30,19 +63,17 @@ declare class ApplicationBuilder<Args, Options, Globals, State extends Applicati
     #private;
     readonly [applicationEnvironment]: ApplicationEnvironment<Globals, Plugins>;
     readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals, Result>;
-    constructor(name: string, root: CommandState<Args, Options, Globals>, config: {
-        declared: DeclaredFacts;
-        views: unknown;
-        options?: unknown;
-        plugins: Plugins | undefined;
+    constructor(name: string, declared: {
+        config: ApplicationConfig;
         globals: GlobalsState<Globals>;
+        root: CommandState<Args, Options, Globals>;
     });
     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>, Plugins, Result>;
-    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, Plugins, Result>;
+    argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>, Plugins, Result>;
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Plugins, Result>;
     globalOption<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & (Name extends keyof Options ? {
         'This option name is already declared as a local option': Name;
-    } : unknown) & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args, Options, Globals & Record<Name, OptionValue<Config>>, State, Plugins, Result>;
+    } : unknown) & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>> & NoInfer<GlobalOmissionConstraint<Config>>): Application<Args, Options, Globals & Record<Name, OptionValue<Config>>, State, Plugins, Result>;
     /** Registering the action closes input authoring; extension configuration remains available. */
     action(handler: Action<Args, Globals & Options, Result>): Application<Args, Options, Globals, AfterAction, Plugins, Result>;
     /** A child arrives in any type state, because its own action is the call that finished it. */
@@ -69,27 +100,26 @@ declare class ApplicationBuilder<Args, Options, Globals, State extends Applicati
         default?: string;
     }): Application<Args, Options, Globals, State, Plugins, Result>;
     extend(...values: readonly ExtensionValue<'command'>[]): Application<Args, Options, Globals, State, Plugins, Result>;
+    /** The globals table the root's options and every joining subtree meet. */
+    private table;
     /**
-     * Root declaration calls preserve the Application configuration. 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.
+     * Root declaration calls preserve the Application configuration, with the parts a call changed.
+     * 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;
     /**
-     * Every rule that reads the declarations alone, in the order `run()` reads them: the
-     * application's own view overrides, the options slot, the installed list, each plugin's
-     * declarations, then the whole Command graph. The application's overrides are read and published
-     * first, because they need core's identities and nothing else, so every later declaration error
-     * reaches them, while a fault in that list itself reports through core's own text. The merged
-     * registry is published once the whole build has succeeded, so a build-time fault never resolves
-     * through a plugin's overrides, which build has not yet validated.
+     * The graph build, which applies the rules no earlier moment could know: the root's
+     * finished-Command rules and every lifecycle hook's contribution. The application's own overrides
+     * are published first, so a build fault reports through them. The merged registry is published
+     * once the build has succeeded, so a build fault never resolves through a plugin's overrides.
      */
     private prepare;
     /**
-     * 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.
+     * The built graph as plain, frozen data. It builds the graph as `run()` does and throws
+     * `DeclarationError` for the same build faults. 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>;
@@ -107,11 +137,10 @@ interface ApplicationConstructor {
     new (name: string): Application<{}, {}, {}, ApplicationMethod, readonly []>;
     new <const Plugins extends readonly Plugin[] = readonly []>(name: string, options: ApplicationOptions<Plugins>): Application<{}, {}, {}, ApplicationMethod, Plugins>;
 }
-/** The same facts as the constructor captured them, before any rule has read them. */
-interface DeclaredFacts {
-    rendering: unknown;
-    description: unknown;
-    version: unknown;
+/** The core facts one Application declares, validated at construction and reported by `inspect()`. */
+interface ApplicationFacts {
+    description: string | undefined;
+    version: string;
 }
 export declare const Application: ApplicationConstructor;
 export {};