@alpacakit/channels 0.1.0-beta.19

package/dist/binding-compiler.d.ts

@@ -0,0 +1,29 @@
+import type { ErasedEntryDefinition, ErasedParameterDefinition } from "./model.js";
+export declare const PARAMETER_BINDING_ISSUE_KIND: {
+    readonly duplicate: "duplicate";
+    readonly nonexistent: "nonexistent";
+    readonly requiredUnreachable: "required_unreachable";
+};
+export type ParameterBindingRow = {
+    readonly parameterName: string;
+};
+export type CompiledParameterBinding<Row extends ParameterBindingRow = ParameterBindingRow> = {
+    readonly row: Row;
+    readonly parameter: ErasedParameterDefinition;
+};
+export type ParameterBindingIssue = {
+    readonly kind: typeof PARAMETER_BINDING_ISSUE_KIND.duplicate;
+    readonly parameterName: string;
+} | {
+    readonly kind: typeof PARAMETER_BINDING_ISSUE_KIND.nonexistent;
+    readonly parameterName: string;
+} | {
+    readonly kind: typeof PARAMETER_BINDING_ISSUE_KIND.requiredUnreachable;
+    readonly parameterName: string;
+};
+export type ParameterBindingCompilation<Row extends ParameterBindingRow> = {
+    readonly bindings: readonly CompiledParameterBinding<Row>[];
+    readonly issues: readonly ParameterBindingIssue[];
+};
+export declare function compileParameterBindings<Row extends ParameterBindingRow>(entry: ErasedEntryDefinition, rows: readonly Row[]): ParameterBindingCompilation<Row>;
+//# sourceMappingURL=binding-compiler.d.ts.map

package/dist/binding-compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-compiler.d.ts","sourceRoot":"","sources":["../src/binding-compiler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,4BAA4B;;;;CAI/B,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,wBAAwB,CAClC,GAAG,SAAS,mBAAmB,GAAG,mBAAmB,IACnD;IACF,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,4BAA4B,CAAC,SAAS,CAAC;IAC7D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,4BAA4B,CAAC,WAAW,CAAC;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,4BAA4B,CAAC,mBAAmB,CAAC;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,CAAC;AAEN,MAAM,MAAM,2BAA2B,CAAC,GAAG,SAAS,mBAAmB,IAAI;IACzE,QAAQ,CAAC,QAAQ,EAAE,SAAS,wBAAwB,CAAC,GAAG,CAAC,EAAE,CAAC;IAC5D,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACnD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,GAAG,SAAS,mBAAmB,EACtE,KAAK,EAAE,qBAAqB,EAC5B,IAAI,EAAE,SAAS,GAAG,EAAE,GACnB,2BAA2B,CAAC,GAAG,CAAC,CAkClC"}

package/dist/binding-compiler.js

@@ -0,0 +1,40 @@
+import { findParameter } from "./internal.js";
+import { PARAMETER_REQUIREMENT_KIND } from "./values.js";
+export const PARAMETER_BINDING_ISSUE_KIND = {
+    duplicate: "duplicate",
+    nonexistent: "nonexistent",
+    requiredUnreachable: "required_unreachable",
+};
+export function compileParameterBindings(entry, rows) {
+    const bindings = [];
+    const issues = [];
+    const names = new Set();
+    for (const row of rows) {
+        if (names.has(row.parameterName)) {
+            issues.push({
+                kind: PARAMETER_BINDING_ISSUE_KIND.duplicate,
+                parameterName: row.parameterName,
+            });
+        }
+        names.add(row.parameterName);
+        const parameter = findParameter(entry.parameters, row.parameterName);
+        if (parameter === null) {
+            issues.push({
+                kind: PARAMETER_BINDING_ISSUE_KIND.nonexistent,
+                parameterName: row.parameterName,
+            });
+            continue;
+        }
+        bindings.push({ row, parameter });
+    }
+    for (const parameter of entry.parameters) {
+        if (parameter.requirement.kind === PARAMETER_REQUIREMENT_KIND.required &&
+            !names.has(parameter.name)) {
+            issues.push({
+                kind: PARAMETER_BINDING_ISSUE_KIND.requiredUnreachable,
+                parameterName: parameter.name,
+            });
+        }
+    }
+    return { bindings, issues };
+}

package/dist/cli-coercion.d.ts

@@ -0,0 +1,5 @@
+import type { JsonValue } from "@alpacakit/core";
+import { type CliValueCoercion } from "./cli-model.js";
+import type { ValueShape } from "./model.js";
+export declare function coerceCliArgvValue(shape: ValueShape, rawValue: unknown, coercion: CliValueCoercion | null): JsonValue | undefined;
+//# sourceMappingURL=cli-coercion.d.ts.map

package/dist/cli-coercion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-coercion.d.ts","sourceRoot":"","sources":["../src/cli-coercion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,OAAO,EACjB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAChC,SAAS,GAAG,SAAS,CAWvB"}

package/dist/cli-coercion.js

@@ -0,0 +1,51 @@
+import { CLI_VALUE_COERCION } from "./cli-model.js";
+import { VALUE_SHAPE_KIND } from "./values.js";
+export function coerceCliArgvValue(shape, rawValue, coercion) {
+    if (coercion !== null) {
+        return coerceExplicitCliValue(rawValue, coercion);
+    }
+    if (shape.kind === VALUE_SHAPE_KIND.array) {
+        const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+        return values.map((value) => coerceCliArgvScalarValue(shape.element, value));
+    }
+    return coerceCliArgvScalarValue(shape, rawValue);
+}
+function coerceCliArgvScalarValue(shape, value) {
+    if (shape.kind === VALUE_SHAPE_KIND.boolean) {
+        if (value === "true") {
+            return true;
+        }
+        if (value === "false") {
+            return false;
+        }
+    }
+    if (shape.kind === VALUE_SHAPE_KIND.positiveInteger &&
+        typeof value === "string" &&
+        /^[+-]?\d+$/.test(value)) {
+        return Number(value);
+    }
+    return value;
+}
+function coerceExplicitCliValue(rawValue, coercion) {
+    if (Array.isArray(rawValue)) {
+        return rawValue.map((value) => coerceExplicitCliScalar(value, coercion));
+    }
+    return coerceExplicitCliScalar(rawValue, coercion);
+}
+function coerceExplicitCliScalar(value, coercion) {
+    if (typeof value !== "string") {
+        return value;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        if (coercion === CLI_VALUE_COERCION.jsonOrString) {
+            return value;
+        }
+        throw new Error(`Invalid JSON value: ${errorMessage(error)}`);
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/cli-compiler.d.ts

@@ -0,0 +1,46 @@
+import { type CliEntryBinding, type CliLongOptionFlag, type CliOptionFlag, type CliOptionValueMode, type CliValueCoercion } from "./cli-model.js";
+import { CLI_OPTION_KIND, CLI_POSITIONAL_PLAN_KIND } from "./cli-values.js";
+import type { EntryTreeEndpoint, ErasedParameterDefinition } from "./model.js";
+export declare const CLI_OPTION_ACTION_KIND: {
+    readonly setBoolean: "set_boolean";
+    readonly readValue: "read_value";
+};
+type CompiledCliOptionBase = {
+    readonly parameter: ErasedParameterDefinition;
+    readonly flags: readonly CliOptionFlag[];
+    readonly coercion: CliValueCoercion | null;
+};
+export type CompiledCliOption = (CompiledCliOptionBase & {
+    readonly kind: typeof CLI_OPTION_KIND.booleanFlag;
+    readonly negativeFlags: readonly CliLongOptionFlag[];
+}) | (CompiledCliOptionBase & {
+    readonly kind: typeof CLI_OPTION_KIND.value;
+    readonly valueMode: CliOptionValueMode;
+    readonly valueName: string;
+});
+export type CompiledCliPositional = {
+    readonly kind: typeof CLI_POSITIONAL_PLAN_KIND.single | typeof CLI_POSITIONAL_PLAN_KIND.rest;
+    readonly parameter: ErasedParameterDefinition;
+    readonly valueName: string;
+    readonly coercion: CliValueCoercion | null;
+};
+export type CliOptionAction = {
+    readonly kind: typeof CLI_OPTION_ACTION_KIND.setBoolean;
+    readonly parameterName: string;
+    readonly value: boolean;
+} | {
+    readonly kind: typeof CLI_OPTION_ACTION_KIND.readValue;
+    readonly option: Extract<CompiledCliOption, {
+        readonly kind: typeof CLI_OPTION_KIND.value;
+    }>;
+};
+export type CompiledCliEndpoint = {
+    readonly endpoint: EntryTreeEndpoint;
+    readonly help: CliEntryBinding["help"];
+    readonly options: readonly CompiledCliOption[];
+    readonly positionals: readonly CompiledCliPositional[];
+    readonly optionByToken: ReadonlyMap<string, CliOptionAction>;
+};
+export declare function compileCliBinding(endpoint: EntryTreeEndpoint, binding: CliEntryBinding, location: string, issues: string[]): CompiledCliEndpoint;
+export {};
+//# sourceMappingURL=cli-compiler.d.ts.map

package/dist/cli-compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-compiler.d.ts","sourceRoot":"","sources":["../src/cli-compiler.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,eAAe,EAEf,wBAAwB,EACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAG/E,eAAO,MAAM,sBAAsB;;;CAGzB,CAAC;AAUX,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB,CAAC,qBAAqB,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,eAAe,CAAC,WAAW,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtD,CAAC,GACF,CAAC,qBAAqB,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,eAAe,CAAC,KAAK,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEP,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,IAAI,EACT,OAAO,wBAAwB,CAAC,MAAM,GACtC,OAAO,wBAAwB,CAAC,IAAI,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,sBAAsB,CAAC,UAAU,CAAC;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,sBAAsB,CAAC,SAAS,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,OAAO,CACtB,iBAAiB,EACjB;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,eAAe,CAAC,KAAK,CAAA;KAAE,CAChD,CAAC;CACH,CAAC;AAEN,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACvD,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC9D,CAAC;AAEF,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,mBAAmB,CAgDrB"}

package/dist/cli-compiler.js

@@ -0,0 +1,213 @@
+import { compileParameterBindings, PARAMETER_BINDING_ISSUE_KIND, } from "./binding-compiler.js";
+import { CLI_ARG_KIND, } from "./cli-model.js";
+import { CLI_BOOLEAN_MODE, CLI_OPTION_KIND, CLI_OPTION_VALUE_MODE, CLI_POSITIONAL_PLAN_KIND, } from "./cli-values.js";
+import { PARAMETER_REQUIREMENT_KIND, VALUE_SHAPE_KIND } from "./values.js";
+export const CLI_OPTION_ACTION_KIND = {
+    setBoolean: "set_boolean",
+    readValue: "read_value",
+};
+const CLI_COMPILER_SYNTAX = {
+    assignmentSeparator: "=",
+    invalidLongOptionPrefix: "---",
+    longOptionPrefix: "--",
+    negatedLongOptionPrefix: "--no-",
+    optionPrefix: "-",
+};
+export function compileCliBinding(endpoint, binding, location, issues) {
+    const compiledParameters = compileParameterBindings(endpoint.entry, binding.parameters);
+    issues.push(...compiledParameters.issues.map((issue) => formatCliParameterBindingIssue(location, issue)));
+    const options = [];
+    const positionals = [];
+    for (const compiled of compiledParameters.bindings) {
+        if (compiled.row.kind === CLI_ARG_KIND.option) {
+            options.push(compileCliOption({ row: compiled.row, parameter: compiled.parameter }, location, issues));
+        }
+        else {
+            positionals.push(compileCliPositional({ row: compiled.row, parameter: compiled.parameter }, location, issues));
+        }
+    }
+    for (const [index, positional] of positionals.entries()) {
+        if (positional.kind === CLI_POSITIONAL_PLAN_KIND.rest &&
+            index !== positionals.length - 1) {
+            issues.push(`${location}: variadic positional ${positional.parameter.name} must be last`);
+        }
+    }
+    return {
+        endpoint,
+        help: binding.help,
+        options,
+        positionals,
+        optionByToken: createCliOptionActionIndex(options, location, issues),
+    };
+}
+function compileCliOption(compiled, location, issues) {
+    const { row, parameter } = compiled;
+    const flags = row.flags;
+    if (flags.length === 0) {
+        issues.push(`${location}: option ${row.parameterName} must declare a flag`);
+    }
+    for (const flag of flags) {
+        if (!isReachableCliOptionFlag(flag)) {
+            issues.push(`${location}: option ${row.parameterName} declares unreachable CLI flag ${JSON.stringify(flag)}`);
+        }
+    }
+    if (row.valueName.length === 0) {
+        issues.push(`${location}: option ${row.parameterName} valueName must not be empty`);
+    }
+    switch (parameter.codec.shape.kind) {
+        case VALUE_SHAPE_KIND.boolean:
+            return compileCliBooleanOption(compiled, flags, location, issues);
+        case VALUE_SHAPE_KIND.array:
+            rejectBooleanChoices(row, location, issues);
+            return {
+                kind: CLI_OPTION_KIND.value,
+                parameter,
+                flags,
+                coercion: row.coercion,
+                valueName: row.valueName,
+                valueMode: row.repeatable
+                    ? CLI_OPTION_VALUE_MODE.commaOrRepeat
+                    : CLI_OPTION_VALUE_MODE.repeat,
+            };
+        case VALUE_SHAPE_KIND.positiveInteger:
+        case VALUE_SHAPE_KIND.string:
+        case VALUE_SHAPE_KIND.stringEnum:
+            rejectBooleanChoices(row, location, issues);
+            if (row.repeatable) {
+                issues.push(`${location}: repeatMode contradicts ${row.parameterName} codec shape`);
+            }
+            return {
+                kind: CLI_OPTION_KIND.value,
+                parameter,
+                flags,
+                coercion: row.coercion,
+                valueName: row.valueName,
+                valueMode: CLI_OPTION_VALUE_MODE.replace,
+            };
+    }
+}
+function isReachableCliOptionFlag(flag) {
+    return (flag.startsWith(CLI_COMPILER_SYNTAX.optionPrefix) &&
+        flag !== CLI_COMPILER_SYNTAX.optionPrefix &&
+        flag !== CLI_COMPILER_SYNTAX.longOptionPrefix &&
+        !flag.startsWith(CLI_COMPILER_SYNTAX.invalidLongOptionPrefix) &&
+        !flag.includes(CLI_COMPILER_SYNTAX.assignmentSeparator) &&
+        !/\s/.test(flag));
+}
+function compileCliBooleanOption(compiled, flags, location, issues) {
+    const { row, parameter } = compiled;
+    if (row.repeatable) {
+        issues.push(`${location}: repeatMode contradicts ${row.parameterName} codec shape`);
+    }
+    const booleanMode = row.booleanMode ??
+        (parameter.requirement.kind ===
+            PARAMETER_REQUIREMENT_KIND.optionalWithDefault
+            ? CLI_BOOLEAN_MODE.flag
+            : CLI_BOOLEAN_MODE.value);
+    if (booleanMode === CLI_BOOLEAN_MODE.value) {
+        if (row.negated) {
+            issues.push(`${location}: negated option ${row.parameterName} requires flag booleanMode`);
+        }
+        return {
+            kind: CLI_OPTION_KIND.value,
+            parameter,
+            flags,
+            coercion: row.coercion,
+            valueName: row.valueName,
+            valueMode: CLI_OPTION_VALUE_MODE.replace,
+        };
+    }
+    if (row.valueNameAuthored) {
+        issues.push(`${location}: valueName contradicts flag booleanMode for ${row.parameterName}`);
+    }
+    if (row.coercion !== null) {
+        issues.push(`${location}: coercion contradicts flag booleanMode for ${row.parameterName}`);
+    }
+    const negativeFlags = row.negated
+        ? flags.filter(isCliLongOptionFlag).map(negateCliLongOptionFlag)
+        : [];
+    if (row.negated && negativeFlags.length === 0) {
+        issues.push(`${location}: negated option ${row.parameterName} requires a long flag`);
+    }
+    return {
+        kind: CLI_OPTION_KIND.booleanFlag,
+        parameter,
+        flags,
+        coercion: null,
+        negativeFlags,
+    };
+}
+function isCliLongOptionFlag(flag) {
+    return flag.startsWith(CLI_COMPILER_SYNTAX.longOptionPrefix);
+}
+function negateCliLongOptionFlag(flag) {
+    return `${CLI_COMPILER_SYNTAX.negatedLongOptionPrefix}${flag.slice(CLI_COMPILER_SYNTAX.longOptionPrefix.length)}`;
+}
+function rejectBooleanChoices(row, location, issues) {
+    if (row.booleanMode !== null) {
+        issues.push(`${location}: booleanMode contradicts ${row.parameterName} codec shape`);
+    }
+    if (row.negated) {
+        issues.push(`${location}: negated contradicts ${row.parameterName} codec shape`);
+    }
+}
+function compileCliPositional(compiled, location, issues) {
+    const { row, parameter } = compiled;
+    if (row.variadic && parameter.codec.shape.kind !== VALUE_SHAPE_KIND.array) {
+        issues.push(`${location}: variadic positional ${row.parameterName} requires an array codec`);
+    }
+    if (row.valueName.length === 0) {
+        issues.push(`${location}: positional ${row.parameterName} valueName must not be empty`);
+    }
+    return {
+        kind: row.variadic
+            ? CLI_POSITIONAL_PLAN_KIND.rest
+            : CLI_POSITIONAL_PLAN_KIND.single,
+        parameter,
+        valueName: row.valueName,
+        coercion: row.coercion,
+    };
+}
+function createCliOptionActionIndex(options, location, issues) {
+    const actions = new Map();
+    for (const option of options) {
+        if (option.kind === CLI_OPTION_KIND.booleanFlag) {
+            for (const token of option.flags) {
+                registerCliOptionAction(actions, token, {
+                    kind: CLI_OPTION_ACTION_KIND.setBoolean,
+                    parameterName: option.parameter.name,
+                    value: true,
+                }, location, issues);
+            }
+            for (const token of option.negativeFlags) {
+                registerCliOptionAction(actions, token, {
+                    kind: CLI_OPTION_ACTION_KIND.setBoolean,
+                    parameterName: option.parameter.name,
+                    value: false,
+                }, location, issues);
+            }
+            continue;
+        }
+        for (const token of option.flags) {
+            registerCliOptionAction(actions, token, { kind: CLI_OPTION_ACTION_KIND.readValue, option }, location, issues);
+        }
+    }
+    return actions;
+}
+function registerCliOptionAction(actions, token, action, location, issues) {
+    if (actions.has(token)) {
+        issues.push(`${location}: duplicate CLI option flag ${token}`);
+        return;
+    }
+    actions.set(token, action);
+}
+function formatCliParameterBindingIssue(location, issue) {
+    switch (issue.kind) {
+        case PARAMETER_BINDING_ISSUE_KIND.duplicate:
+            return `${location}: duplicate binding for parameter ${issue.parameterName}`;
+        case PARAMETER_BINDING_ISSUE_KIND.nonexistent:
+            return `${location}: binding names nonexistent parameter ${issue.parameterName}`;
+        case PARAMETER_BINDING_ISSUE_KIND.requiredUnreachable:
+            return `${location}: required parameter ${issue.parameterName} is unreachable from CLI`;
+    }
+}

package/dist/cli-executor.d.ts

@@ -0,0 +1,25 @@
+import type { CLI_ROUTER_RESULT_KIND, CliResolvedEndpointResult, CliRouter, CliRouterResult } from "./cli-model.js";
+import type { EntryTreeEndpoint } from "./model.js";
+type ResolvedCliResult = Extract<CliRouterResult, {
+    readonly kind: typeof CLI_ROUTER_RESULT_KIND.resolved;
+}>;
+export type CliEndpointHandlerBinding<Endpoint extends EntryTreeEndpoint = EntryTreeEndpoint, Result = unknown> = {
+    readonly endpoint: Endpoint;
+    readonly handler: (input: CliResolvedEndpointResult<Endpoint>) => Result | Promise<Result>;
+};
+export type CliEndpointHandlerRegistration<Result = unknown> = {
+    readonly endpoint: EntryTreeEndpoint;
+    readonly handler: (...args: never[]) => Result | Promise<Result>;
+};
+export declare class CliExecutorDefinitionError extends Error {
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+export declare function handleCliEndpoint<const Endpoint extends EntryTreeEndpoint, Result>(endpoint: Endpoint, handler: (input: CliResolvedEndpointResult<Endpoint>) => Result | Promise<Result>): CliEndpointHandlerBinding<Endpoint, Result>;
+type CliHandlerResult<Bindings extends readonly CliEndpointHandlerRegistration[]> = Awaited<ReturnType<Bindings[number]["handler"]>>;
+export type CliExecutor<Bindings extends readonly CliEndpointHandlerRegistration[]> = {
+    execute(result: ResolvedCliResult): Promise<CliHandlerResult<Bindings>>;
+};
+export declare function createCliExecutor<const Bindings extends readonly CliEndpointHandlerRegistration[]>(router: CliRouter, bindings: Bindings): CliExecutor<Bindings>;
+export {};
+//# sourceMappingURL=cli-executor.d.ts.map

package/dist/cli-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-executor.d.ts","sourceRoot":"","sources":["../src/cli-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,yBAAyB,EACzB,SAAS,EACT,eAAe,EAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,KAAK,iBAAiB,GAAG,OAAO,CAC9B,eAAe,EACf;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,sBAAsB,CAAC,QAAQ,CAAA;CAAE,CAC1D,CAAC;AAEF,MAAM,MAAM,yBAAyB,CACnC,QAAQ,SAAS,iBAAiB,GAAG,iBAAiB,EACtD,MAAM,GAAG,OAAO,IACd;IACF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAChB,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,KACvC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,8BAA8B,CAAC,MAAM,GAAG,OAAO,IAAI;IAC7D,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAClE,CAAC;AAEF,qBAAa,0BAA2B,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE;gBAAzB,MAAM,EAAE,SAAS,MAAM,EAAE;CAI/C;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,CAAC,QAAQ,SAAS,iBAAiB,EACxC,MAAM,EAEN,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,CACP,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,KACvC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAC5B,yBAAyB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAE7C;AAED,KAAK,gBAAgB,CACnB,QAAQ,SAAS,SAAS,8BAA8B,EAAE,IACxD,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAErD,MAAM,MAAM,WAAW,CACrB,QAAQ,SAAS,SAAS,8BAA8B,EAAE,IACxD;IACF,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC;CACzE,CAAC;AAEF,wBAAgB,iBAAiB,CAC/B,KAAK,CAAC,QAAQ,SAAS,SAAS,8BAA8B,EAAE,EAChE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAsC9D"}

package/dist/cli-executor.js

@@ -0,0 +1,44 @@
+export class CliExecutorDefinitionError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid CLI executor definition:\n${issues.join("\n")}`);
+        this.issues = issues;
+        this.name = CliExecutorDefinitionError.name;
+    }
+}
+export function handleCliEndpoint(endpoint, handler) {
+    return { endpoint, handler };
+}
+export function createCliExecutor(router, bindings) {
+    const issues = [];
+    const routerEndpoints = new Set(router.endpoints);
+    const handlers = new Map();
+    for (const binding of bindings) {
+        if (!routerEndpoints.has(binding.endpoint)) {
+            issues.push(`handler endpoint ${binding.endpoint.entry.name} is not in the router`);
+        }
+        if (handlers.has(binding.endpoint)) {
+            issues.push(`duplicate handler for endpoint ${binding.endpoint.entry.name}`);
+        }
+        handlers.set(binding.endpoint, binding);
+    }
+    for (const endpoint of router.endpoints) {
+        if (!handlers.has(endpoint)) {
+            issues.push(`missing handler for endpoint ${endpoint.entry.name}`);
+        }
+    }
+    if (issues.length > 0) {
+        throw new CliExecutorDefinitionError(issues);
+    }
+    const execute = async (result) => {
+        const binding = handlers.get(result.endpoint);
+        if (!binding) {
+            throw new CliExecutorDefinitionError([
+                `missing handler for endpoint ${result.endpoint.entry.name}`,
+            ]);
+        }
+        const handler = binding.handler;
+        return await handler(result);
+    };
+    return { execute };
+}

package/dist/cli-help-projection.d.ts

@@ -0,0 +1,13 @@
+import type { CompiledCliEndpoint } from "./cli-compiler.js";
+import type { CliHelpExample, CliHelpSurface, CliSegment } from "./cli-model.js";
+import type { EntryTreeNode } from "./model.js";
+export declare function createCliHelpSurface(input: {
+    readonly node: EntryTreeNode;
+    readonly segment: CliSegment;
+    readonly endpoint: CompiledCliEndpoint | null;
+    readonly childHelp: readonly CliHelpSurface[];
+    readonly root: boolean;
+}): CliHelpSurface;
+export declare function validateCliCommandHelp(endpoint: CompiledCliEndpoint, location: string, issues: string[]): void;
+export declare function validateCliHelpExamples(examples: readonly CliHelpExample[], location: string, issues: string[]): void;
+//# sourceMappingURL=cli-help-projection.d.ts.map

package/dist/cli-help-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-help-projection.d.ts","sourceRoot":"","sources":["../src/cli-help-projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,cAAc,EAKd,cAAc,EAGd,UAAU,EACX,MAAM,gBAAgB,CAAC;AAOxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA4ChD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB,GAAG,cAAc,CAoBjB;AAkCD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,IAAI,CA2BN;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,IAAI,CAaN"}

package/dist/cli-help-projection.js

@@ -0,0 +1,159 @@
+import { CLI_HELP_USAGE_KIND, CLI_OPTION_KIND, CLI_POSITIONAL_PLAN_KIND, } from "./cli-values.js";
+import { describeParameterRequirement } from "./introspection.js";
+import { PARAMETER_REQUIREMENT_KIND } from "./values.js";
+const CLI_HELP_USAGE_SYNTAX = {
+    commandArgument: "<command>",
+    commandPartSeparator: " ",
+    emptyPart: "",
+    optionArgument: "[options]",
+    optionalClose: "]",
+    optionalOpen: "[",
+    requiredClose: ">",
+    requiredOpen: "<",
+    variadicSuffix: "...",
+};
+const CLI_HELP_VALIDATION_ISSUE = {
+    duplicateSectionParameter: (location, parameterName) => `${location}: help option parameter ${parameterName} appears more than once in option sections`,
+    emptyExampleCommand: "CLI help example command must not be empty",
+    emptyExampleTitle: "CLI help example title must not be empty",
+    nonOptionSectionParameter: (location, heading, parameterName) => `${location}: help option section ${JSON.stringify(heading)} names non-option parameter ${parameterName}`,
+};
+const GROUP_HELP_PROJECTION = {
+    examples: [],
+    options: [],
+    optionSections: [],
+    positionals: [],
+    usage: { kind: CLI_HELP_USAGE_KIND.derived },
+};
+export function createCliHelpSurface(input) {
+    const endpoint = projectCliEndpointHelp(input.endpoint);
+    const hasChildren = input.childHelp.length > 0;
+    return {
+        name: input.node.name,
+        token: input.root ? null : input.segment.token,
+        aliases: input.root ? [] : input.segment.aliases,
+        description: input.node.description,
+        remarks: input.node.documentation.remarks,
+        relatedDocs: input.node.documentation.relatedDocs,
+        optionGroups: projectCliHelpOptionGroups(endpoint.options, endpoint.optionSections),
+        positionals: endpoint.positionals,
+        usages: resolveCliUsages(endpoint, hasChildren),
+        examples: [...input.segment.help.examples, ...endpoint.examples],
+        subcommandHint: input.segment.help.subcommandHint,
+        children: input.childHelp,
+    };
+}
+function projectCliHelpOptionGroups(options, sections) {
+    const optionByParameterName = new Map(options.map((option) => [option.parameterName, option]));
+    const sectionedParameterNames = new Set(sections.flatMap((section) => section.parameterNames));
+    const groups = sections.map((section) => ({
+        heading: section.heading,
+        description: section.description,
+        // Section references are validated before the completed router is exposed.
+        options: section.parameterNames.map((parameterName) => optionByParameterName.get(parameterName)),
+    }));
+    const unsectionedOptions = options.filter((option) => !sectionedParameterNames.has(option.parameterName));
+    if (unsectionedOptions.length > 0) {
+        groups.push({
+            heading: null,
+            description: null,
+            options: unsectionedOptions,
+        });
+    }
+    return groups;
+}
+export function validateCliCommandHelp(endpoint, location, issues) {
+    const { help, options } = endpoint;
+    validateCliHelpExamples(help.examples, location, issues);
+    const optionNames = new Set(options.map((option) => option.parameter.name));
+    const sectionedNames = new Set();
+    for (const section of help.optionSections) {
+        for (const parameterName of section.parameterNames) {
+            if (!optionNames.has(parameterName)) {
+                issues.push(CLI_HELP_VALIDATION_ISSUE.nonOptionSectionParameter(location, section.heading, parameterName));
+            }
+            if (sectionedNames.has(parameterName)) {
+                issues.push(CLI_HELP_VALIDATION_ISSUE.duplicateSectionParameter(location, parameterName));
+            }
+            sectionedNames.add(parameterName);
+        }
+    }
+}
+export function validateCliHelpExamples(examples, location, issues) {
+    for (const example of examples) {
+        if (example.title.length === 0) {
+            issues.push(`${location}: ${CLI_HELP_VALIDATION_ISSUE.emptyExampleTitle}`);
+        }
+        if (example.command.length === 0) {
+            issues.push(`${location}: ${CLI_HELP_VALIDATION_ISSUE.emptyExampleCommand}`);
+        }
+    }
+}
+function projectCliEndpointHelp(endpoint) {
+    if (endpoint === null) {
+        return GROUP_HELP_PROJECTION;
+    }
+    return {
+        examples: endpoint.help.examples,
+        options: endpoint.options.map(cliHelpOptionFor),
+        optionSections: endpoint.help.optionSections,
+        positionals: endpoint.positionals.map(cliHelpPositionalFor),
+        usage: endpoint.help.usage,
+    };
+}
+function resolveCliUsages(endpoint, hasChildren) {
+    switch (endpoint.usage.kind) {
+        case CLI_HELP_USAGE_KIND.authored:
+            return endpoint.usage.values;
+        case CLI_HELP_USAGE_KIND.derived:
+            return [deriveCliUsage(endpoint, hasChildren)];
+    }
+}
+function deriveCliUsage(endpoint, hasChildren) {
+    const parts = [];
+    if (endpoint.options.length > 0) {
+        parts.push(CLI_HELP_USAGE_SYNTAX.optionArgument);
+    }
+    parts.push(...endpoint.positionals.map(formatCliUsagePositional));
+    if (hasChildren) {
+        parts.push(CLI_HELP_USAGE_SYNTAX.commandArgument);
+    }
+    return parts.join(CLI_HELP_USAGE_SYNTAX.commandPartSeparator);
+}
+function formatCliUsagePositional(positional) {
+    const name = `${positional.valueName}${positional.variadic
+        ? CLI_HELP_USAGE_SYNTAX.variadicSuffix
+        : CLI_HELP_USAGE_SYNTAX.emptyPart}`;
+    return positional.requirement.kind === PARAMETER_REQUIREMENT_KIND.required
+        ? `${CLI_HELP_USAGE_SYNTAX.requiredOpen}${name}${CLI_HELP_USAGE_SYNTAX.requiredClose}`
+        : `${CLI_HELP_USAGE_SYNTAX.optionalOpen}${name}${CLI_HELP_USAGE_SYNTAX.optionalClose}`;
+}
+function cliHelpOptionFor(option) {
+    const base = {
+        parameterName: option.parameter.name,
+        flags: option.flags,
+        description: option.parameter.description,
+        requirement: describeParameterRequirement(option.parameter.requirement),
+    };
+    return option.kind === CLI_OPTION_KIND.booleanFlag
+        ? {
+            ...base,
+            kind: CLI_OPTION_KIND.booleanFlag,
+            negativeFlags: option.negativeFlags,
+        }
+        : {
+            ...base,
+            kind: CLI_OPTION_KIND.value,
+            valueName: option.valueName,
+            valueMode: option.valueMode,
+        };
+}
+function cliHelpPositionalFor(positional) {
+    return {
+        parameterName: positional.parameter.name,
+        valueName: positional.valueName,
+        description: positional.parameter.description,
+        requirement: describeParameterRequirement(positional.parameter.requirement),
+        variadic: positional.kind === CLI_POSITIONAL_PLAN_KIND.rest,
+    };
+}