niceeval 0.13.3 → 0.13.4-canary.39

package/dist/cli/contribution.cjs

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliFeatureError = exports.CliCommandCompositionError = void 0;
+exports.composeCliCommands = composeCliCommands;
+exports.composeCliOptionSchema = composeCliOptionSchema;
+exports.locateCliRoot = locateCliRoot;
+exports.projectCliArgvWithoutRoot = projectCliArgvWithoutRoot;
+exports.matchCliFeatureCommand = matchCliFeatureCommand;
+exports.renderFeatureCommandIndex = renderFeatureCommandIndex;
+const effect_1 = require("effect");
+class CliCommandCompositionError extends Error {
+    _tag = "CliCommandCompositionError";
+}
+exports.CliCommandCompositionError = CliCommandCompositionError;
+/** Feature-owned typed failure consumed by the one CLI failure boundary. */
+class CliFeatureError extends effect_1.Data.TaggedError("CliFeatureError") {
+}
+exports.CliFeatureError = CliFeatureError;
+const COMMAND_NAME = /^[a-z][a-z0-9-]*$/u;
+const OPTION_NAME = /^[a-z][a-z0-9-]*$/u;
+function sameOptionShape(left, right) {
+    const leftOptional = left.optionalValue;
+    const rightOptional = right.optionalValue;
+    return left.type === right.type &&
+        left.multiple === right.multiple &&
+        left.short === right.short &&
+        (leftOptional === undefined
+            ? rightOptional === undefined
+            : rightOptional !== undefined &&
+                leftOptional.default === rightOptional.default &&
+                leftOptional.separated === rightOptional.separated &&
+                (leftOptional.values === undefined
+                    ? rightOptional.values === undefined
+                    : rightOptional.values !== undefined &&
+                        leftOptional.values.length === rightOptional.values.length &&
+                        leftOptional.values.every((value, index) => value === rightOptional.values[index])));
+}
+function validateOptionSchema(name, options) {
+    if (!Object.isFrozen(options)) {
+        throw new CliCommandCompositionError(`CLI feature command ${name} must freeze its option schema`);
+    }
+    const shortNames = new Set();
+    for (const [optionName, option] of Object.entries(options)) {
+        if (!OPTION_NAME.test(optionName)) {
+            throw new CliCommandCompositionError(`Invalid CLI option name ${JSON.stringify(optionName)} for ${name}`);
+        }
+        if (!Object.isFrozen(option) || option.help === undefined || !Object.isFrozen(option.help)) {
+            throw new CliCommandCompositionError(`CLI option --${optionName} for ${name} must be immutable`);
+        }
+        if ((option.type !== "string" && option.type !== "boolean") || (option.multiple !== undefined && option.multiple !== true)) {
+            throw new CliCommandCompositionError(`Invalid parser shape for CLI option --${optionName} on ${name}`);
+        }
+        if (option.optionalValue !== undefined) {
+            const optional = option.optionalValue;
+            if (option.type !== "boolean" || option.multiple !== undefined || option.short !== undefined || !Object.isFrozen(optional)) {
+                throw new CliCommandCompositionError(`CLI option --${optionName} on ${name} has an invalid optional-value shape`);
+            }
+            if (optional.default !== true && (typeof optional.default !== "string" || optional.default.length === 0)) {
+                throw new CliCommandCompositionError(`CLI option --${optionName} on ${name} requires a non-empty optional-value default`);
+            }
+            if (optional.values !== undefined) {
+                if (!Object.isFrozen(optional.values) || optional.values.length === 0 ||
+                    optional.values.some((value) => value.length === 0) ||
+                    new Set(optional.values).size !== optional.values.length ||
+                    (typeof optional.default === "string" && !optional.values.includes(optional.default))) {
+                    throw new CliCommandCompositionError(`CLI option --${optionName} on ${name} requires a frozen, unique optional-value vocabulary containing its default`);
+                }
+            }
+        }
+        if (option.short !== undefined) {
+            if (!/^[A-Za-z0-9]$/u.test(option.short) || shortNames.has(option.short)) {
+                throw new CliCommandCompositionError(`Invalid or duplicate short option ${JSON.stringify(option.short)} on ${name}`);
+            }
+            shortNames.add(option.short);
+        }
+        if (option.help.summary.trim() === "" || (option.help.visibility !== "public" && option.help.visibility !== "hidden")) {
+            throw new CliCommandCompositionError(`CLI option --${optionName} on ${name} requires valid help metadata`);
+        }
+    }
+}
+/** Validate once at the composition edge and preserve the caller's deterministic help order. */
+function composeCliCommands(contributions) {
+    const occupied = new Set();
+    const result = [];
+    for (const contribution of contributions) {
+        if (!Object.isFrozen(contribution)) {
+            throw new CliCommandCompositionError(`CLI feature command ${contribution.name} must be immutable`);
+        }
+        if (!COMMAND_NAME.test(contribution.name)) {
+            throw new CliCommandCompositionError(`Invalid CLI feature command name: ${JSON.stringify(contribution.name)}`);
+        }
+        if (contribution.summary.trim() === "") {
+            throw new CliCommandCompositionError(`CLI feature command ${contribution.name} requires a summary`);
+        }
+        validateOptionSchema(contribution.name, contribution.options);
+        if (occupied.has(contribution.name)) {
+            throw new CliCommandCompositionError(`Duplicate CLI root command: ${contribution.name}`);
+        }
+        occupied.add(contribution.name);
+        result.push(Object.freeze(contribution));
+    }
+    // Composition must reject parser conflicts even before a caller asks for the
+    // aggregate schema used by the root parser.
+    composeCliOptionSchema(result);
+    return Object.freeze(result);
+}
+/**
+ * Merge feature-owned schemas at the composition edge. Reusing an option name is
+ * only sound when Node will parse it with exactly the same syntax in every owner.
+ */
+function composeCliOptionSchema(contributions, applicationOptions = {}) {
+    const options = {};
+    const owners = new Map();
+    const shortOwners = new Map();
+    for (const [name, option] of Object.entries(applicationOptions)) {
+        options[name] = Object.freeze({ ...option });
+        owners.set(name, "application");
+        if (option.short !== undefined)
+            shortOwners.set(option.short, { name, owner: "application" });
+    }
+    for (const contribution of contributions) {
+        validateOptionSchema(contribution.name, contribution.options);
+        for (const [name, option] of Object.entries(contribution.options)) {
+            const existing = options[name];
+            if (existing !== undefined && !sameOptionShape(existing, option)) {
+                throw new CliCommandCompositionError(`Conflicting CLI option --${name}: ${owners.get(name)} and ${contribution.name} declare different parser shapes`);
+            }
+            if (existing === undefined) {
+                options[name] = option;
+                owners.set(name, contribution.name);
+            }
+            if (option.short !== undefined) {
+                const priorShort = shortOwners.get(option.short);
+                if (priorShort !== undefined && priorShort.name !== name) {
+                    throw new CliCommandCompositionError(`Conflicting CLI short option -${option.short}: --${priorShort.name} (${priorShort.owner}) and --${name} (${contribution.name})`);
+                }
+                shortOwners.set(option.short, { name, owner: contribution.name });
+            }
+        }
+    }
+    return Object.freeze(options);
+}
+/** First positional Node token identifies the root without rewriting the raw argv. */
+function locateCliRoot(tokens) {
+    const token = tokens.find((candidate) => candidate.kind === "positional");
+    return token === undefined ? undefined : Object.freeze({ index: token.index, name: token.value });
+}
+/** Delete exactly the command token: flags before/after it and `--` retain byte order. */
+function projectCliArgvWithoutRoot(argv, root) {
+    if (root.index < 0 || root.index >= argv.length || argv[root.index] !== root.name) {
+        throw new CliCommandCompositionError(`CLI root token ${JSON.stringify(root.name)} has an invalid argv index`);
+    }
+    return Object.freeze(argv.filter((_, index) => index !== root.index));
+}
+function precedingGlobalHelpOrVersion(tokens, root) {
+    return tokens.some((token) => token.kind === "option" && token.index < root.index &&
+        (token.name === "help" || token.name === "version"));
+}
+/** Route one indexed root token while keeping application help/version formal capabilities. */
+function matchCliFeatureCommand(argv, parsed, contributions) {
+    const root = locateCliRoot(parsed.tokens);
+    if (root === undefined)
+        return undefined;
+    const command = contributions.find((candidate) => candidate.name === root.name);
+    if (command === undefined)
+        return undefined;
+    const applicationHelp = parsed.tokens.some((token) => token.kind === "option" && token.name === "help" &&
+        (token.index < root.index || !Object.hasOwn(command.options, "help")));
+    if (applicationHelp)
+        return Object.freeze({ kind: "application-option", option: "help", root });
+    const applicationVersion = parsed.tokens.some((token) => token.kind === "option" && token.name === "version" &&
+        (token.index < root.index || !Object.hasOwn(command.options, "version")));
+    if (applicationVersion)
+        return Object.freeze({ kind: "application-option", option: "version", root });
+    if (precedingGlobalHelpOrVersion(parsed.tokens, root)) {
+        throw new CliCommandCompositionError("Application help/version routing lost its owner");
+    }
+    return Object.freeze({ kind: "command", command, argv: projectCliArgvWithoutRoot(argv, root), root });
+}
+function renderFeatureCommandIndex(contributions) {
+    if (contributions.length === 0)
+        return "";
+    return `\nFeature commands:\n${contributions.map(({ name, summary }) => `  niceeval ${name.padEnd(12)} ${summary}`).join("\n")}\n`;
+}
+//# sourceMappingURL=contribution.cjs.map

package/dist/cli/contribution.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribution.js","sourceRoot":"","sources":["contribution.ts"],"names":[],"mappings":"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","sourcesContent":["import { Data, type Effect } from \"effect\";\nimport type { CliOptionDefinition, CliParsedToken, CliParsedTokens } from \"./application.ts\";\n/** A feature-owned root command. Commands are immutable values, not services or registrations. */\nexport interface CliCommandContribution<R, E> {\n    readonly name: string;\n    readonly summary: string;\n    /** Complete parser schema for options this root command actually owns. */\n    readonly options: Readonly<Record<string, CliOptionDefinition>>;\n    readonly run: (argv: readonly string[]) => Effect.Effect<number, E, R>;\n}\nexport class CliCommandCompositionError extends Error {\n    readonly _tag = \"CliCommandCompositionError\";\n}\n/** Feature-owned typed failure consumed by the one CLI failure boundary. */\nexport class CliFeatureError extends Data.TaggedError(\"CliFeatureError\")<{\n    readonly feature: string;\n    readonly operation: string;\n    readonly cause: unknown;\n    readonly exitCode: number;\n    /** Feature-owned terminal text; the root only writes it once. */\n    readonly display?: string;\n}> {\n}\nconst COMMAND_NAME = /^[a-z][a-z0-9-]*$/u;\nconst OPTION_NAME = /^[a-z][a-z0-9-]*$/u;\nfunction sameOptionShape(left: CliOptionDefinition, right: CliOptionDefinition): boolean {\n    const leftOptional = left.optionalValue;\n    const rightOptional = right.optionalValue;\n    return left.type === right.type &&\n        left.multiple === right.multiple &&\n        left.short === right.short &&\n        (leftOptional === undefined\n            ? rightOptional === undefined\n            : rightOptional !== undefined &&\n                leftOptional.default === rightOptional.default &&\n                leftOptional.separated === rightOptional.separated &&\n                (leftOptional.values === undefined\n                    ? rightOptional.values === undefined\n                    : rightOptional.values !== undefined &&\n                        leftOptional.values.length === rightOptional.values.length &&\n                        leftOptional.values.every((value, index) => value === rightOptional.values![index])));\n}\nfunction validateOptionSchema(name: string, options: Readonly<Record<string, CliOptionDefinition>>): void {\n    if (!Object.isFrozen(options)) {\n        throw new CliCommandCompositionError(`CLI feature command ${name} must freeze its option schema`);\n    }\n    const shortNames = new Set<string>();\n    for (const [optionName, option] of Object.entries(options)) {\n        if (!OPTION_NAME.test(optionName)) {\n            throw new CliCommandCompositionError(`Invalid CLI option name ${JSON.stringify(optionName)} for ${name}`);\n        }\n        if (!Object.isFrozen(option) || option.help === undefined || !Object.isFrozen(option.help)) {\n            throw new CliCommandCompositionError(`CLI option --${optionName} for ${name} must be immutable`);\n        }\n        if ((option.type !== \"string\" && option.type !== \"boolean\") || (option.multiple !== undefined && option.multiple !== true)) {\n            throw new CliCommandCompositionError(`Invalid parser shape for CLI option --${optionName} on ${name}`);\n        }\n        if (option.optionalValue !== undefined) {\n            const optional = option.optionalValue;\n            if (option.type !== \"boolean\" || option.multiple !== undefined || option.short !== undefined || !Object.isFrozen(optional)) {\n                throw new CliCommandCompositionError(`CLI option --${optionName} on ${name} has an invalid optional-value shape`);\n            }\n            if (optional.default !== true && (typeof optional.default !== \"string\" || optional.default.length === 0)) {\n                throw new CliCommandCompositionError(`CLI option --${optionName} on ${name} requires a non-empty optional-value default`);\n            }\n            if (optional.values !== undefined) {\n                if (!Object.isFrozen(optional.values) || optional.values.length === 0 ||\n                    optional.values.some((value) => value.length === 0) ||\n                    new Set(optional.values).size !== optional.values.length ||\n                    (typeof optional.default === \"string\" && !optional.values.includes(optional.default))) {\n                    throw new CliCommandCompositionError(`CLI option --${optionName} on ${name} requires a frozen, unique optional-value vocabulary containing its default`);\n                }\n            }\n        }\n        if (option.short !== undefined) {\n            if (!/^[A-Za-z0-9]$/u.test(option.short) || shortNames.has(option.short)) {\n                throw new CliCommandCompositionError(`Invalid or duplicate short option ${JSON.stringify(option.short)} on ${name}`);\n            }\n            shortNames.add(option.short);\n        }\n        if (option.help.summary.trim() === \"\" || (option.help.visibility !== \"public\" && option.help.visibility !== \"hidden\")) {\n            throw new CliCommandCompositionError(`CLI option --${optionName} on ${name} requires valid help metadata`);\n        }\n    }\n}\n/** Validate once at the composition edge and preserve the caller's deterministic help order. */\nexport function composeCliCommands<R, E>(contributions: readonly CliCommandContribution<R, E>[]): readonly CliCommandContribution<R, E>[] {\n    const occupied = new Set<string>();\n    const result: CliCommandContribution<R, E>[] = [];\n    for (const contribution of contributions) {\n        if (!Object.isFrozen(contribution)) {\n            throw new CliCommandCompositionError(`CLI feature command ${contribution.name} must be immutable`);\n        }\n        if (!COMMAND_NAME.test(contribution.name)) {\n            throw new CliCommandCompositionError(`Invalid CLI feature command name: ${JSON.stringify(contribution.name)}`);\n        }\n        if (contribution.summary.trim() === \"\") {\n            throw new CliCommandCompositionError(`CLI feature command ${contribution.name} requires a summary`);\n        }\n        validateOptionSchema(contribution.name, contribution.options);\n        if (occupied.has(contribution.name)) {\n            throw new CliCommandCompositionError(`Duplicate CLI root command: ${contribution.name}`);\n        }\n        occupied.add(contribution.name);\n        result.push(Object.freeze(contribution));\n    }\n    // Composition must reject parser conflicts even before a caller asks for the\n    // aggregate schema used by the root parser.\n    composeCliOptionSchema(result);\n    return Object.freeze(result);\n}\n/**\n * Merge feature-owned schemas at the composition edge. Reusing an option name is\n * only sound when Node will parse it with exactly the same syntax in every owner.\n */\nexport function composeCliOptionSchema<R, E>(contributions: readonly CliCommandContribution<R, E>[], applicationOptions: Readonly<Record<string, CliOptionDefinition>> = {}): Readonly<Record<string, CliOptionDefinition>> {\n    const options: Record<string, CliOptionDefinition> = {};\n    const owners = new Map<string, string>();\n    const shortOwners = new Map<string, {\n        readonly name: string;\n        readonly owner: string;\n    }>();\n    for (const [name, option] of Object.entries(applicationOptions)) {\n        options[name] = Object.freeze({ ...option });\n        owners.set(name, \"application\");\n        if (option.short !== undefined)\n            shortOwners.set(option.short, { name, owner: \"application\" });\n    }\n    for (const contribution of contributions) {\n        validateOptionSchema(contribution.name, contribution.options);\n        for (const [name, option] of Object.entries(contribution.options)) {\n            const existing = options[name];\n            if (existing !== undefined && !sameOptionShape(existing, option)) {\n                throw new CliCommandCompositionError(`Conflicting CLI option --${name}: ${owners.get(name)} and ${contribution.name} declare different parser shapes`);\n            }\n            if (existing === undefined) {\n                options[name] = option;\n                owners.set(name, contribution.name);\n            }\n            if (option.short !== undefined) {\n                const priorShort = shortOwners.get(option.short);\n                if (priorShort !== undefined && priorShort.name !== name) {\n                    throw new CliCommandCompositionError(`Conflicting CLI short option -${option.short}: --${priorShort.name} (${priorShort.owner}) and --${name} (${contribution.name})`);\n                }\n                shortOwners.set(option.short, { name, owner: contribution.name });\n            }\n        }\n    }\n    return Object.freeze(options);\n}\nexport interface CliRootToken {\n    readonly index: number;\n    readonly name: string;\n}\n/** First positional Node token identifies the root without rewriting the raw argv. */\nexport function locateCliRoot(tokens: readonly CliParsedToken[]): CliRootToken | undefined {\n    const token = tokens.find((candidate) => candidate.kind === \"positional\");\n    return token === undefined ? undefined : Object.freeze({ index: token.index, name: token.value });\n}\n/** Delete exactly the command token: flags before/after it and `--` retain byte order. */\nexport function projectCliArgvWithoutRoot(argv: readonly string[], root: CliRootToken): readonly string[] {\n    if (root.index < 0 || root.index >= argv.length || argv[root.index] !== root.name) {\n        throw new CliCommandCompositionError(`CLI root token ${JSON.stringify(root.name)} has an invalid argv index`);\n    }\n    return Object.freeze(argv.filter((_, index) => index !== root.index));\n}\nfunction precedingGlobalHelpOrVersion(tokens: readonly CliParsedToken[], root: CliRootToken): boolean {\n    return tokens.some((token) => token.kind === \"option\" && token.index < root.index &&\n        (token.name === \"help\" || token.name === \"version\"));\n}\nexport type CliFeatureRoute<R, E> = Readonly<{\n    readonly kind: \"application-option\";\n    readonly option: \"help\" | \"version\";\n    readonly root: CliRootToken;\n}> | Readonly<{\n    readonly kind: \"command\";\n    readonly command: CliCommandContribution<R, E>;\n    readonly argv: readonly string[];\n    readonly root: CliRootToken;\n}>;\n/** Route one indexed root token while keeping application help/version formal capabilities. */\nexport function matchCliFeatureCommand<R, E>(argv: readonly string[], parsed: CliParsedTokens, contributions: readonly CliCommandContribution<R, E>[]): CliFeatureRoute<R, E> | undefined {\n    const root = locateCliRoot(parsed.tokens);\n    if (root === undefined)\n        return undefined;\n    const command = contributions.find((candidate) => candidate.name === root.name);\n    if (command === undefined)\n        return undefined;\n    const applicationHelp = parsed.tokens.some((token) => token.kind === \"option\" && token.name === \"help\" &&\n        (token.index < root.index || !Object.hasOwn(command.options, \"help\")));\n    if (applicationHelp)\n        return Object.freeze({ kind: \"application-option\", option: \"help\", root });\n    const applicationVersion = parsed.tokens.some((token) => token.kind === \"option\" && token.name === \"version\" &&\n        (token.index < root.index || !Object.hasOwn(command.options, \"version\")));\n    if (applicationVersion)\n        return Object.freeze({ kind: \"application-option\", option: \"version\", root });\n    if (precedingGlobalHelpOrVersion(parsed.tokens, root)) {\n        throw new CliCommandCompositionError(\"Application help/version routing lost its owner\");\n    }\n    return Object.freeze({ kind: \"command\", command, argv: projectCliArgvWithoutRoot(argv, root), root });\n}\nexport function renderFeatureCommandIndex<R, E>(contributions: readonly CliCommandContribution<R, E>[]): string {\n    if (contributions.length === 0)\n        return \"\";\n    return `\\nFeature commands:\\n${contributions.map(({ name, summary }) => `  niceeval ${name.padEnd(12)} ${summary}`).join(\"\\n\")}\\n`;\n}\n"]}

package/dist/cli/contribution.d.cts

@@ -0,0 +1,55 @@
+import { type Effect } from "effect";
+import type { CliOptionDefinition, CliParsedToken, CliParsedTokens } from "./application.cjs";
+/** A feature-owned root command. Commands are immutable values, not services or registrations. */
+export interface CliCommandContribution<R, E> {
+    readonly name: string;
+    readonly summary: string;
+    /** Complete parser schema for options this root command actually owns. */
+    readonly options: Readonly<Record<string, CliOptionDefinition>>;
+    readonly run: (argv: readonly string[]) => Effect.Effect<number, E, R>;
+}
+export declare class CliCommandCompositionError extends Error {
+    readonly _tag = "CliCommandCompositionError";
+}
+declare const CliFeatureError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CliFeatureError";
+} & Readonly<A>;
+/** Feature-owned typed failure consumed by the one CLI failure boundary. */
+export declare class CliFeatureError extends CliFeatureError_base<{
+    readonly feature: string;
+    readonly operation: string;
+    readonly cause: unknown;
+    readonly exitCode: number;
+    /** Feature-owned terminal text; the root only writes it once. */
+    readonly display?: string;
+}> {
+}
+/** Validate once at the composition edge and preserve the caller's deterministic help order. */
+export declare function composeCliCommands<R, E>(contributions: readonly CliCommandContribution<R, E>[]): readonly CliCommandContribution<R, E>[];
+/**
+ * Merge feature-owned schemas at the composition edge. Reusing an option name is
+ * only sound when Node will parse it with exactly the same syntax in every owner.
+ */
+export declare function composeCliOptionSchema<R, E>(contributions: readonly CliCommandContribution<R, E>[], applicationOptions?: Readonly<Record<string, CliOptionDefinition>>): Readonly<Record<string, CliOptionDefinition>>;
+export interface CliRootToken {
+    readonly index: number;
+    readonly name: string;
+}
+/** First positional Node token identifies the root without rewriting the raw argv. */
+export declare function locateCliRoot(tokens: readonly CliParsedToken[]): CliRootToken | undefined;
+/** Delete exactly the command token: flags before/after it and `--` retain byte order. */
+export declare function projectCliArgvWithoutRoot(argv: readonly string[], root: CliRootToken): readonly string[];
+export type CliFeatureRoute<R, E> = Readonly<{
+    readonly kind: "application-option";
+    readonly option: "help" | "version";
+    readonly root: CliRootToken;
+}> | Readonly<{
+    readonly kind: "command";
+    readonly command: CliCommandContribution<R, E>;
+    readonly argv: readonly string[];
+    readonly root: CliRootToken;
+}>;
+/** Route one indexed root token while keeping application help/version formal capabilities. */
+export declare function matchCliFeatureCommand<R, E>(argv: readonly string[], parsed: CliParsedTokens, contributions: readonly CliCommandContribution<R, E>[]): CliFeatureRoute<R, E> | undefined;
+export declare function renderFeatureCommandIndex<R, E>(contributions: readonly CliCommandContribution<R, E>[]): string;
+export {};

package/dist/cli/contribution.d.mts

@@ -0,0 +1,55 @@
+import { type Effect } from "effect";
+import type { CliOptionDefinition, CliParsedToken, CliParsedTokens } from "./application.mjs";
+/** A feature-owned root command. Commands are immutable values, not services or registrations. */
+export interface CliCommandContribution<R, E> {
+    readonly name: string;
+    readonly summary: string;
+    /** Complete parser schema for options this root command actually owns. */
+    readonly options: Readonly<Record<string, CliOptionDefinition>>;
+    readonly run: (argv: readonly string[]) => Effect.Effect<number, E, R>;
+}
+export declare class CliCommandCompositionError extends Error {
+    readonly _tag = "CliCommandCompositionError";
+}
+declare const CliFeatureError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CliFeatureError";
+} & Readonly<A>;
+/** Feature-owned typed failure consumed by the one CLI failure boundary. */
+export declare class CliFeatureError extends CliFeatureError_base<{
+    readonly feature: string;
+    readonly operation: string;
+    readonly cause: unknown;
+    readonly exitCode: number;
+    /** Feature-owned terminal text; the root only writes it once. */
+    readonly display?: string;
+}> {
+}
+/** Validate once at the composition edge and preserve the caller's deterministic help order. */
+export declare function composeCliCommands<R, E>(contributions: readonly CliCommandContribution<R, E>[]): readonly CliCommandContribution<R, E>[];
+/**
+ * Merge feature-owned schemas at the composition edge. Reusing an option name is
+ * only sound when Node will parse it with exactly the same syntax in every owner.
+ */
+export declare function composeCliOptionSchema<R, E>(contributions: readonly CliCommandContribution<R, E>[], applicationOptions?: Readonly<Record<string, CliOptionDefinition>>): Readonly<Record<string, CliOptionDefinition>>;
+export interface CliRootToken {
+    readonly index: number;
+    readonly name: string;
+}
+/** First positional Node token identifies the root without rewriting the raw argv. */
+export declare function locateCliRoot(tokens: readonly CliParsedToken[]): CliRootToken | undefined;
+/** Delete exactly the command token: flags before/after it and `--` retain byte order. */
+export declare function projectCliArgvWithoutRoot(argv: readonly string[], root: CliRootToken): readonly string[];
+export type CliFeatureRoute<R, E> = Readonly<{
+    readonly kind: "application-option";
+    readonly option: "help" | "version";
+    readonly root: CliRootToken;
+}> | Readonly<{
+    readonly kind: "command";
+    readonly command: CliCommandContribution<R, E>;
+    readonly argv: readonly string[];
+    readonly root: CliRootToken;
+}>;
+/** Route one indexed root token while keeping application help/version formal capabilities. */
+export declare function matchCliFeatureCommand<R, E>(argv: readonly string[], parsed: CliParsedTokens, contributions: readonly CliCommandContribution<R, E>[]): CliFeatureRoute<R, E> | undefined;
+export declare function renderFeatureCommandIndex<R, E>(contributions: readonly CliCommandContribution<R, E>[]): string;
+export {};

package/dist/cli/contribution.d.ts

@@ -0,0 +1,55 @@
+import { type Effect } from "effect";
+import type { CliOptionDefinition, CliParsedToken, CliParsedTokens } from "./application.js";
+/** A feature-owned root command. Commands are immutable values, not services or registrations. */
+export interface CliCommandContribution<R, E> {
+    readonly name: string;
+    readonly summary: string;
+    /** Complete parser schema for options this root command actually owns. */
+    readonly options: Readonly<Record<string, CliOptionDefinition>>;
+    readonly run: (argv: readonly string[]) => Effect.Effect<number, E, R>;
+}
+export declare class CliCommandCompositionError extends Error {
+    readonly _tag = "CliCommandCompositionError";
+}
+declare const CliFeatureError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CliFeatureError";
+} & Readonly<A>;
+/** Feature-owned typed failure consumed by the one CLI failure boundary. */
+export declare class CliFeatureError extends CliFeatureError_base<{
+    readonly feature: string;
+    readonly operation: string;
+    readonly cause: unknown;
+    readonly exitCode: number;
+    /** Feature-owned terminal text; the root only writes it once. */
+    readonly display?: string;
+}> {
+}
+/** Validate once at the composition edge and preserve the caller's deterministic help order. */
+export declare function composeCliCommands<R, E>(contributions: readonly CliCommandContribution<R, E>[]): readonly CliCommandContribution<R, E>[];
+/**
+ * Merge feature-owned schemas at the composition edge. Reusing an option name is
+ * only sound when Node will parse it with exactly the same syntax in every owner.
+ */
+export declare function composeCliOptionSchema<R, E>(contributions: readonly CliCommandContribution<R, E>[], applicationOptions?: Readonly<Record<string, CliOptionDefinition>>): Readonly<Record<string, CliOptionDefinition>>;
+export interface CliRootToken {
+    readonly index: number;
+    readonly name: string;
+}
+/** First positional Node token identifies the root without rewriting the raw argv. */
+export declare function locateCliRoot(tokens: readonly CliParsedToken[]): CliRootToken | undefined;
+/** Delete exactly the command token: flags before/after it and `--` retain byte order. */
+export declare function projectCliArgvWithoutRoot(argv: readonly string[], root: CliRootToken): readonly string[];
+export type CliFeatureRoute<R, E> = Readonly<{
+    readonly kind: "application-option";
+    readonly option: "help" | "version";
+    readonly root: CliRootToken;
+}> | Readonly<{
+    readonly kind: "command";
+    readonly command: CliCommandContribution<R, E>;
+    readonly argv: readonly string[];
+    readonly root: CliRootToken;
+}>;
+/** Route one indexed root token while keeping application help/version formal capabilities. */
+export declare function matchCliFeatureCommand<R, E>(argv: readonly string[], parsed: CliParsedTokens, contributions: readonly CliCommandContribution<R, E>[]): CliFeatureRoute<R, E> | undefined;
+export declare function renderFeatureCommandIndex<R, E>(contributions: readonly CliCommandContribution<R, E>[]): string;
+export {};

package/dist/cli/contribution.js

@@ -0,0 +1,20 @@
+import { createRequire as __niceevalCreateRequire } from "node:module";
+const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
+const __niceevalCanonical = __niceevalRequire("./contribution.cjs");
+const __niceevalExport0 = __niceevalCanonical["CliCommandCompositionError"];
+export { __niceevalExport0 as CliCommandCompositionError };
+const __niceevalExport1 = __niceevalCanonical["CliFeatureError"];
+export { __niceevalExport1 as CliFeatureError };
+const __niceevalExport2 = __niceevalCanonical["composeCliCommands"];
+export { __niceevalExport2 as composeCliCommands };
+const __niceevalExport3 = __niceevalCanonical["composeCliOptionSchema"];
+export { __niceevalExport3 as composeCliOptionSchema };
+const __niceevalExport4 = __niceevalCanonical["locateCliRoot"];
+export { __niceevalExport4 as locateCliRoot };
+const __niceevalExport5 = __niceevalCanonical["matchCliFeatureCommand"];
+export { __niceevalExport5 as matchCliFeatureCommand };
+const __niceevalExport6 = __niceevalCanonical["projectCliArgvWithoutRoot"];
+export { __niceevalExport6 as projectCliArgvWithoutRoot };
+const __niceevalExport7 = __niceevalCanonical["renderFeatureCommandIndex"];
+export { __niceevalExport7 as renderFeatureCommandIndex };
+//# sourceMappingURL=contribution.js.map

package/dist/cli/contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contribution.js","sources":[],"names":[],"mappings":""}