@alpacakit/channels 0.1.0-beta.19

package/dist/cli-model.d.ts

@@ -0,0 +1,240 @@
+import { type CLI_BOOLEAN_MODE, CLI_HELP_USAGE_KIND, type CLI_OPTION_KIND, CLI_OPTION_VALUE_MODE } from "./cli-values.js";
+import type { ParameterRequirementDescription } from "./introspection.js";
+import type { ChannelSegmentOverride, EntryChannelBinding, EntryTreeEndpoint } from "./model.js";
+import { CHANNEL } from "./values.js";
+export declare const CLI_ARG_KIND: {
+    readonly option: "option";
+    readonly positional: "positional";
+};
+export declare const CLI_VALUE_COERCION: {
+    readonly json: "json";
+    readonly jsonOrString: "json_or_string";
+};
+export declare const CLI_ROUTER_RESULT_KIND: {
+    readonly resolved: "resolved";
+    readonly unknownCommand: "unknown_command";
+    readonly incompleteCommand: "incomplete_command";
+    readonly invalidInput: "invalid_input";
+    readonly invalidParameter: "invalid_parameter";
+    readonly internalError: "internal_error";
+};
+export type CliBooleanMode = (typeof CLI_BOOLEAN_MODE)[keyof typeof CLI_BOOLEAN_MODE];
+export type CliOptionValueMode = (typeof CLI_OPTION_VALUE_MODE)[keyof typeof CLI_OPTION_VALUE_MODE];
+export type CliValueCoercion = (typeof CLI_VALUE_COERCION)[keyof typeof CLI_VALUE_COERCION];
+export type CliLongOptionFlag = `--${string}`;
+export type CliOptionFlag = `-${string}`;
+/** CLI segment-token path. Surface locations always use canonical tokens. */
+export type CliCommandPath = readonly string[];
+export type CliArgBindingInput<Name extends string = string> = {
+    readonly kind: typeof CLI_ARG_KIND.option;
+    readonly parameterName: Name;
+    /** Defaults to `--<kebab-case parameter name>` when omitted. */
+    readonly flags?: readonly CliOptionFlag[];
+    /** Displayed after the option flag. Defaults from `parameterName`. */
+    readonly valueName?: string;
+    /** Overrides the default scalar coercion performed for CLI strings. */
+    readonly coercion?: CliValueCoercion;
+    readonly booleanMode?: CliBooleanMode;
+    readonly negated?: true;
+    readonly repeatMode?: typeof CLI_OPTION_VALUE_MODE.commaOrRepeat;
+} | {
+    readonly kind: typeof CLI_ARG_KIND.positional;
+    readonly parameterName: Name;
+    /** Defaults to the upper snake-cased parameter name when omitted. */
+    readonly valueName?: string;
+    /** Overrides the default scalar coercion performed for CLI strings. */
+    readonly coercion?: CliValueCoercion;
+    /** Defaults to `false` when omitted. */
+    readonly variadic?: boolean;
+};
+export type CliArgBinding<Name extends string = string> = {
+    readonly kind: typeof CLI_ARG_KIND.option;
+    readonly parameterName: Name;
+    readonly flags: readonly CliOptionFlag[];
+    readonly valueName: string;
+    /**
+     * Whether `valueName` was authored rather than derived. Boolean-flag
+     * options reject an authored value name at compile time, so the
+     * provenance must survive normalization instead of being inferred from
+     * the (always-populated) `valueName`.
+     */
+    readonly valueNameAuthored: boolean;
+    readonly coercion: CliValueCoercion | null;
+    readonly booleanMode: CliBooleanMode | null;
+    readonly negated: boolean;
+    readonly repeatable: boolean;
+} | {
+    readonly kind: typeof CLI_ARG_KIND.positional;
+    readonly parameterName: Name;
+    readonly valueName: string;
+    readonly coercion: CliValueCoercion | null;
+    readonly variadic: boolean;
+};
+export type CliEntryBinding<Name extends string = string> = {
+    readonly parameters: readonly CliArgBinding<Name>[];
+    readonly help: CliCommandHelp;
+};
+export type CliSegment = {
+    readonly token: string;
+    readonly aliases: readonly string[];
+    readonly help: CliGroupHelp;
+};
+export type CliHelpExample = {
+    readonly title: string;
+    readonly useWhen: string;
+    readonly command: string;
+    readonly expectedResult: readonly string[];
+};
+export type CliHelpExampleInput = {
+    readonly title: string;
+    readonly useWhen: string;
+    readonly command: string;
+    readonly expectedResult?: readonly string[];
+};
+export type CliHelpOptionSection = {
+    readonly heading: string;
+    readonly description: string | null;
+    readonly parameterNames: readonly string[];
+};
+export type CliHelpOptionSectionInput<ParameterName extends string = string> = {
+    readonly heading: string;
+    readonly description?: string;
+    readonly parameterNames: readonly ParameterName[];
+};
+export type CliHelpUsageList = readonly [string, ...string[]];
+export type CliHelpUsage = {
+    readonly kind: typeof CLI_HELP_USAGE_KIND.derived;
+} | {
+    readonly kind: typeof CLI_HELP_USAGE_KIND.authored;
+    readonly values: CliHelpUsageList;
+};
+export type CliCommandHelp = {
+    readonly usage: CliHelpUsage;
+    readonly examples: readonly CliHelpExample[];
+    readonly optionSections: readonly CliHelpOptionSection[];
+};
+export type CliCommandHelpInput<OptionParameterName extends string = string> = {
+    readonly usages?: CliHelpUsageList;
+    readonly examples?: readonly CliHelpExampleInput[];
+    readonly optionSections?: readonly CliHelpOptionSectionInput<OptionParameterName>[];
+};
+export type CliGroupHelp = {
+    readonly subcommandHint: string | null;
+    readonly examples: readonly CliHelpExample[];
+};
+export type CliGroupHelpInput = {
+    readonly subcommandHint?: string;
+    readonly examples?: readonly CliHelpExampleInput[];
+};
+type CliOptionParameterName<Bindings extends readonly CliArgBindingInput[]> = Extract<Bindings[number], {
+    readonly kind: typeof CLI_ARG_KIND.option;
+}>["parameterName"];
+export declare function bindCliEntry<const Bindings extends readonly CliArgBindingInput[]>(binding: {
+    readonly parameters: Bindings;
+    readonly help?: CliCommandHelpInput<CliOptionParameterName<Bindings>>;
+}): EntryChannelBinding<typeof CHANNEL.cli, Bindings[number]["parameterName"]>;
+export declare function overrideCliSegment(segment: {
+    readonly token: string;
+    readonly aliases?: readonly string[];
+    readonly help?: CliGroupHelpInput;
+}): ChannelSegmentOverride;
+type CliHelpOptionBase = {
+    readonly parameterName: string;
+    readonly flags: readonly CliOptionFlag[];
+    readonly description: string;
+    readonly requirement: ParameterRequirementDescription;
+};
+export type CliHelpOption = CliHelpOptionBase & ({
+    readonly kind: typeof CLI_OPTION_KIND.booleanFlag;
+    readonly negativeFlags: readonly CliLongOptionFlag[];
+} | {
+    readonly kind: typeof CLI_OPTION_KIND.value;
+    readonly valueName: string;
+    readonly valueMode: CliOptionValueMode;
+});
+/**
+ * Render-ready option grouping. Unlike `CliHelpOptionSection`, this projected
+ * read model contains the referenced options themselves, so renderers never
+ * need to join authored parameter names back to the flat option list.
+ */
+export type CliHelpOptionGroup = {
+    /** `null` identifies the unsectioned option group. */
+    readonly heading: string | null;
+    readonly description: string | null;
+    readonly options: readonly CliHelpOption[];
+};
+export type CliHelpPositional = {
+    readonly parameterName: string;
+    readonly valueName: string;
+    readonly description: string;
+    readonly requirement: ParameterRequirementDescription;
+    readonly variadic: boolean;
+};
+export type CliHelpSurface = {
+    readonly name: string;
+    readonly token: string | null;
+    readonly aliases: readonly string[];
+    readonly description: string;
+    readonly optionGroups: readonly CliHelpOptionGroup[];
+    readonly positionals: readonly CliHelpPositional[];
+    readonly children: readonly CliHelpSurface[];
+    readonly remarks: readonly string[];
+    readonly relatedDocs: readonly string[];
+    readonly usages: CliHelpUsageList;
+    readonly examples: readonly CliHelpExample[];
+    readonly subcommandHint: string | null;
+};
+export type CliHelpRenderContext = {
+    /** Full selected command name, including the executable and command path. */
+    readonly programName: string;
+    /** Root executable name used to prefix authored invocation examples. */
+    readonly executableName: string;
+    /** Canonical CLI segment-token path for the supplied surface. */
+    readonly path: CliCommandPath;
+    readonly withDescription: boolean;
+};
+export type CliHelpRender = (surface: CliHelpSurface, context: CliHelpRenderContext) => string;
+export type CliHelpSurfaceLocation = {
+    readonly surface: CliHelpSurface;
+    readonly path: CliCommandPath;
+};
+export type CliRouterResult = {
+    readonly kind: typeof CLI_ROUTER_RESULT_KIND.resolved;
+    readonly path: readonly string[];
+    readonly endpoint: EntryTreeEndpoint;
+    readonly projection: unknown;
+} | {
+    readonly kind: typeof CLI_ROUTER_RESULT_KIND.unknownCommand;
+    readonly path: readonly string[];
+    readonly token: string;
+} | {
+    readonly kind: typeof CLI_ROUTER_RESULT_KIND.incompleteCommand;
+    readonly path: readonly string[];
+} | {
+    readonly kind: typeof CLI_ROUTER_RESULT_KIND.invalidInput;
+    readonly path: readonly string[];
+    readonly issues: readonly string[];
+} | {
+    readonly kind: typeof CLI_ROUTER_RESULT_KIND.invalidParameter;
+    readonly path: readonly string[];
+    readonly parameterName: string;
+    readonly issues: readonly string[];
+} | {
+    readonly kind: typeof CLI_ROUTER_RESULT_KIND.internalError;
+    readonly path: readonly string[];
+    readonly error: unknown;
+};
+export type CliResolvedEndpointResult<Endpoint extends EntryTreeEndpoint> = Omit<Extract<CliRouterResult, {
+    readonly kind: typeof CLI_ROUTER_RESULT_KIND.resolved;
+}>, "endpoint" | "projection"> & {
+    readonly endpoint: Endpoint;
+    readonly projection: ReturnType<Endpoint["entry"]["project"]>;
+};
+export declare function isCliResolvedEndpoint<const Endpoint extends EntryTreeEndpoint>(result: CliRouterResult, endpoint: Endpoint): result is CliResolvedEndpointResult<Endpoint>;
+export interface CliRouter {
+    readonly help: CliHelpSurface;
+    readonly endpoints: readonly EntryTreeEndpoint[];
+    resolve(argv: readonly string[]): CliRouterResult;
+}
+export {};
+//# sourceMappingURL=cli-model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli-model.d.ts","sourceRoot":"","sources":["../src/cli-model.ts"],"names":[],"mappings":"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"}

package/dist/cli-model.js

@@ -0,0 +1,89 @@
+import { CLI_HELP_USAGE_KIND, CLI_OPTION_VALUE_MODE, defaultCliOptionFlag, defaultCliValueName, } from "./cli-values.js";
+import { createChannelSegmentOverride, createEntryChannelBinding, PAYLOAD_KIND, registerChannelPayload, } from "./tree-internal.js";
+import { CHANNEL } from "./values.js";
+export const CLI_ARG_KIND = {
+    option: "option",
+    positional: "positional",
+};
+export const CLI_VALUE_COERCION = {
+    json: "json",
+    jsonOrString: "json_or_string",
+};
+export const CLI_ROUTER_RESULT_KIND = {
+    resolved: "resolved",
+    unknownCommand: "unknown_command",
+    incompleteCommand: "incomplete_command",
+    invalidInput: "invalid_input",
+    invalidParameter: "invalid_parameter",
+    internalError: "internal_error",
+};
+export function bindCliEntry(binding) {
+    const payload = {
+        parameters: binding.parameters.map(normalizeCliArgBinding),
+        help: normalizeCliCommandHelp(binding.help),
+    };
+    registerChannelPayload(PAYLOAD_KIND.cliBinding, payload);
+    return createEntryChannelBinding(CHANNEL.cli, payload);
+}
+export function overrideCliSegment(segment) {
+    const payload = {
+        token: segment.token,
+        aliases: segment.aliases ?? [],
+        help: normalizeCliGroupHelp(segment.help),
+    };
+    registerChannelPayload(PAYLOAD_KIND.cliSegment, payload);
+    return createChannelSegmentOverride(CHANNEL.cli, payload);
+}
+function normalizeCliArgBinding(input) {
+    if (input.kind === CLI_ARG_KIND.option) {
+        return {
+            kind: input.kind,
+            parameterName: input.parameterName,
+            flags: input.flags ?? [defaultCliOptionFlag(input.parameterName)],
+            valueName: input.valueName ?? defaultCliValueName(input.parameterName),
+            valueNameAuthored: input.valueName !== undefined,
+            coercion: input.coercion ?? null,
+            booleanMode: input.booleanMode ?? null,
+            negated: input.negated ?? false,
+            repeatable: input.repeatMode === CLI_OPTION_VALUE_MODE.commaOrRepeat,
+        };
+    }
+    return {
+        kind: input.kind,
+        parameterName: input.parameterName,
+        valueName: input.valueName ?? defaultCliValueName(input.parameterName),
+        coercion: input.coercion ?? null,
+        variadic: input.variadic ?? false,
+    };
+}
+function normalizeCliCommandHelp(input) {
+    return {
+        usage: input?.usages === undefined
+            ? { kind: CLI_HELP_USAGE_KIND.derived }
+            : { kind: CLI_HELP_USAGE_KIND.authored, values: input.usages },
+        examples: normalizeCliHelpExamples(input?.examples),
+        optionSections: (input?.optionSections ?? []).map((section) => ({
+            heading: section.heading,
+            description: section.description ?? null,
+            parameterNames: section.parameterNames,
+        })),
+    };
+}
+function normalizeCliGroupHelp(input) {
+    return {
+        subcommandHint: input?.subcommandHint ?? null,
+        examples: normalizeCliHelpExamples(input?.examples),
+    };
+}
+function normalizeCliHelpExamples(examples) {
+    return (examples ?? []).map((example) => ({
+        title: example.title,
+        useWhen: example.useWhen,
+        command: example.command,
+        expectedResult: example.expectedResult ?? [],
+    }));
+}
+export function isCliResolvedEndpoint(result, endpoint) {
+    return (result.kind === CLI_ROUTER_RESULT_KIND.resolved &&
+        result.endpoint === endpoint);
+}

package/dist/cli-presentation.d.ts

@@ -0,0 +1,23 @@
+import { CLI_ROUTER_RESULT_KIND, type CliCommandPath, type CliHelpExample, type CliHelpOption, type CliHelpRenderContext, type CliHelpSurface, type CliHelpSurfaceLocation, type CliRouterResult } from "./cli-model.js";
+import type { ParameterRequirementDescription } from "./introspection.js";
+export type CliHelpOptionDescription = {
+    readonly names: string;
+    readonly description: string;
+};
+export declare function findCliHelpSurface(root: CliHelpSurface, commandPath: CliCommandPath): CliHelpSurface | null;
+export declare function findCliHelpSurfaceLocation(root: CliHelpSurface, commandPath: CliCommandPath): CliHelpSurfaceLocation | null;
+export declare function renderCliHelp(surface: CliHelpSurface, context: CliHelpRenderContext): string;
+export declare function listCliHelpSurfaces(root: CliHelpSurface): readonly CliHelpSurfaceLocation[];
+export declare function describeCliHelpOption(option: CliHelpOption): CliHelpOptionDescription;
+export declare function appendCliCommandPart(command: string, part: string): string;
+export declare function formatDefaultCliSubcommandHint(programName: string): string;
+export declare function formatCliRouterError(result: Extract<CliRouterResult, {
+    readonly kind: typeof CLI_ROUTER_RESULT_KIND.unknownCommand | typeof CLI_ROUTER_RESULT_KIND.incompleteCommand | typeof CLI_ROUTER_RESULT_KIND.invalidInput | typeof CLI_ROUTER_RESULT_KIND.invalidParameter;
+}>): string;
+export declare function formatCliHelpParameterDescription(input: {
+    readonly description: string;
+    readonly requirement: ParameterRequirementDescription;
+    readonly additionalDetails: readonly string[];
+}): string;
+export declare function renderCliHelpExamples(examples: readonly CliHelpExample[], executableName: string): readonly string[];
+//# sourceMappingURL=cli-presentation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli-presentation.d.ts","sourceRoot":"","sources":["../src/cli-presentation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAE3B,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AAiD1E,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,cAAc,GAC1B,cAAc,GAAG,IAAI,CAEvB;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,cAAc,GAC1B,sBAAsB,GAAG,IAAI,CAe/B;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,oBAAoB,GAC5B,MAAM,CAWR;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,cAAc,GACnB,SAAS,sBAAsB,EAAE,CAanC;AAqJD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,GACpB,wBAAwB,CAuB1B;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1E;AAED,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,CACb,eAAe,EACf;IACE,QAAQ,CAAC,IAAI,EACT,OAAO,sBAAsB,CAAC,cAAc,GAC5C,OAAO,sBAAsB,CAAC,iBAAiB,GAC/C,OAAO,sBAAsB,CAAC,YAAY,GAC1C,OAAO,sBAAsB,CAAC,gBAAgB,CAAC;CACpD,CACF,GACA,MAAM,CAcR;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,+BAA+B,CAAC;IACtD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C,GAAG,MAAM,CAUT;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,cAAc,EAAE,MAAM,GACrB,SAAS,MAAM,EAAE,CAiBnB"}

package/dist/cli-presentation.js

@@ -0,0 +1,265 @@
+import { CLI_ROUTER_RESULT_KIND, } from "./cli-model.js";
+import { CLI_OPTION_KIND, CLI_OPTION_VALUE_MODE } from "./cli-values.js";
+import { PARAMETER_REQUIREMENT_KIND } from "./values.js";
+const CLI_HELP_TEXT = {
+    argumentsHeading: "Arguments:",
+    commandArgument: "<command>",
+    commandsHeading: "Commands:",
+    commaOrRepeatDetail: "comma-separated or repeatable",
+    defaultDetailPrefix: "default:",
+    examplesHeading: "Examples:",
+    expectedResultHeading: "Expected result:",
+    incompleteCommandPrefix: "Incomplete command:",
+    invalidInputLabel: "Invalid input",
+    invalidParameterPrefix: "Invalid",
+    nextStepsHeading: "Next steps:",
+    optionsHeading: "Options:",
+    optionalDetail: "optional",
+    relatedDocumentationHeading: "Related documentation:",
+    remarksHeading: "Remarks:",
+    repeatableDetail: "repeatable",
+    requiredDetail: "required",
+    unknownCommandPrefix: "Unknown command:",
+    usageHeading: "Usage:",
+    useWhenPrefix: "Use when",
+};
+const CLI_OPTION_VALUE_MODE_DETAILS = {
+    [CLI_OPTION_VALUE_MODE.replace]: [],
+    [CLI_OPTION_VALUE_MODE.repeat]: [CLI_HELP_TEXT.repeatableDetail],
+    [CLI_OPTION_VALUE_MODE.commaOrRepeat]: [CLI_HELP_TEXT.commaOrRepeatDetail],
+};
+const CLI_HELP_LAYOUT = {
+    columnSeparator: "\t",
+    commandPartSeparator: " ",
+    detailSeparator: ", ",
+    emptyLine: "",
+    issueSeparator: "; ",
+    itemIndent: "  ",
+    lineSeparator: "\n",
+    nestedItemIndent: "    ",
+    resultIndent: "      ",
+    sectionSeparator: "\n\n",
+};
+export function findCliHelpSurface(root, commandPath) {
+    return findCliHelpSurfaceLocation(root, commandPath)?.surface ?? null;
+}
+export function findCliHelpSurfaceLocation(root, commandPath) {
+    let current = root;
+    const path = [];
+    for (const token of commandPath) {
+        const child = current.children.find((candidate) => candidate.token === token || candidate.aliases.includes(token));
+        if (!child) {
+            return null;
+        }
+        current = child;
+        path.push(child.token ?? child.name);
+    }
+    return { surface: current, path };
+}
+export function renderCliHelp(surface, context) {
+    return joinCliHelpSections([
+        createCliHelpSummarySection(surface, context.programName),
+        createCliHelpCommandsSection(surface),
+        createCliHelpArgumentsSection(surface),
+        createCliHelpOptionsSection(surface),
+        createCliHelpRemarksSection(surface),
+        createCliHelpExamplesSection(surface, context.executableName),
+        createCliHelpDocumentationSection(surface),
+        createCliHelpNextStepsSection(surface, context.programName),
+    ]);
+}
+export function listCliHelpSurfaces(root) {
+    const locations = [];
+    const pending = [{ surface: root, path: [] }];
+    for (const current of pending) {
+        locations.push(current);
+        pending.push(...current.surface.children.map((child) => ({
+            surface: child,
+            path: [...current.path, child.token ?? child.name],
+        })));
+    }
+    return locations;
+}
+function joinCliHelpSections(sections) {
+    return sections
+        .flatMap((section) => (section === null ? [] : [section]))
+        .map((section) => section.join(CLI_HELP_LAYOUT.lineSeparator))
+        .join(CLI_HELP_LAYOUT.sectionSeparator);
+}
+function createCliHelpSummarySection(surface, programName) {
+    return [
+        ...surface.usages.map((usage) => `${CLI_HELP_TEXT.usageHeading} ${appendCliCommandPart(programName, usage)}`),
+        CLI_HELP_LAYOUT.emptyLine,
+        surface.description,
+    ];
+}
+function createCliHelpCommandsSection(surface) {
+    if (surface.children.length === 0) {
+        return null;
+    }
+    return [
+        CLI_HELP_TEXT.commandsHeading,
+        ...surface.children.map((child) => {
+            const names = [child.token ?? child.name, ...child.aliases].join(CLI_HELP_LAYOUT.detailSeparator);
+            return `${CLI_HELP_LAYOUT.itemIndent}${names}${CLI_HELP_LAYOUT.columnSeparator}${child.description}`;
+        }),
+    ];
+}
+function createCliHelpArgumentsSection(surface) {
+    if (surface.positionals.length === 0) {
+        return null;
+    }
+    return [
+        CLI_HELP_TEXT.argumentsHeading,
+        ...surface.positionals.map((positional) => `${CLI_HELP_LAYOUT.itemIndent}${positional.valueName}${CLI_HELP_LAYOUT.columnSeparator}${formatCliHelpParameterDescription({
+            description: positional.description,
+            requirement: positional.requirement,
+            additionalDetails: [],
+        })}`),
+    ];
+}
+function createCliHelpOptionsSection(surface) {
+    if (surface.optionGroups.length === 0) {
+        return null;
+    }
+    return [CLI_HELP_TEXT.optionsHeading, ...renderCliHelpOptions(surface)];
+}
+function createCliHelpRemarksSection(surface) {
+    if (surface.remarks.length === 0) {
+        return null;
+    }
+    return [
+        CLI_HELP_TEXT.remarksHeading,
+        ...surface.remarks.map((remark) => `${CLI_HELP_LAYOUT.itemIndent}${remark}`),
+    ];
+}
+function createCliHelpExamplesSection(surface, programName) {
+    if (surface.examples.length === 0) {
+        return null;
+    }
+    return [
+        CLI_HELP_TEXT.examplesHeading,
+        ...renderCliHelpExamples(surface.examples, programName),
+    ];
+}
+function createCliHelpDocumentationSection(surface) {
+    if (surface.relatedDocs.length === 0) {
+        return null;
+    }
+    return [
+        CLI_HELP_TEXT.relatedDocumentationHeading,
+        ...surface.relatedDocs.map((documentId) => `${CLI_HELP_LAYOUT.itemIndent}${documentId}`),
+    ];
+}
+function createCliHelpNextStepsSection(surface, programName) {
+    if (surface.children.length === 0) {
+        return null;
+    }
+    return [
+        CLI_HELP_TEXT.nextStepsHeading,
+        `${CLI_HELP_LAYOUT.itemIndent}${surface.subcommandHint ?? formatDefaultCliSubcommandHint(programName)}`,
+    ];
+}
+function renderCliHelpOptions(surface) {
+    return surface.optionGroups.flatMap((group) => {
+        const indent = group.heading === null
+            ? CLI_HELP_LAYOUT.itemIndent
+            : CLI_HELP_LAYOUT.nestedItemIndent;
+        return [
+            ...(group.heading === null
+                ? []
+                : [`${CLI_HELP_LAYOUT.itemIndent}${group.heading}`]),
+            ...(group.description === null
+                ? []
+                : [`${CLI_HELP_LAYOUT.nestedItemIndent}${group.description}`]),
+            ...group.options.map((option) => renderCliHelpOption(option, indent)),
+        ];
+    });
+}
+function renderCliHelpOption(option, indent) {
+    const description = describeCliHelpOption(option);
+    return `${indent}${description.names}${CLI_HELP_LAYOUT.columnSeparator}${description.description}`;
+}
+export function describeCliHelpOption(option) {
+    switch (option.kind) {
+        case CLI_OPTION_KIND.booleanFlag:
+            return {
+                names: [...option.flags, ...option.negativeFlags].join(CLI_HELP_LAYOUT.detailSeparator),
+                description: formatCliHelpParameterDescription({
+                    description: option.description,
+                    requirement: option.requirement,
+                    additionalDetails: [],
+                }),
+            };
+        case CLI_OPTION_KIND.value:
+            return {
+                names: `${option.flags.join(CLI_HELP_LAYOUT.detailSeparator)} <${option.valueName}>`,
+                description: formatCliHelpParameterDescription({
+                    description: option.description,
+                    requirement: option.requirement,
+                    additionalDetails: CLI_OPTION_VALUE_MODE_DETAILS[option.valueMode],
+                }),
+            };
+    }
+}
+export function appendCliCommandPart(command, part) {
+    return part.length === 0
+        ? command
+        : `${command}${CLI_HELP_LAYOUT.commandPartSeparator}${part}`;
+}
+export function formatDefaultCliSubcommandHint(programName) {
+    return `Run \`${programName} ${CLI_HELP_TEXT.commandArgument} --help\` for subcommand details.`;
+}
+export function formatCliRouterError(result) {
+    switch (result.kind) {
+        case CLI_ROUTER_RESULT_KIND.unknownCommand:
+            return `${CLI_HELP_TEXT.unknownCommandPrefix} ${[
+                ...result.path,
+                result.token,
+            ].join(CLI_HELP_LAYOUT.commandPartSeparator)}.`;
+        case CLI_ROUTER_RESULT_KIND.incompleteCommand:
+            return `${CLI_HELP_TEXT.incompleteCommandPrefix} ${result.path.join(CLI_HELP_LAYOUT.commandPartSeparator)}.`;
+        case CLI_ROUTER_RESULT_KIND.invalidInput:
+            return `${CLI_HELP_TEXT.invalidInputLabel}: ${result.issues.join(CLI_HELP_LAYOUT.issueSeparator)}`;
+        case CLI_ROUTER_RESULT_KIND.invalidParameter:
+            return `${CLI_HELP_TEXT.invalidParameterPrefix} ${result.parameterName}: ${result.issues.join(CLI_HELP_LAYOUT.issueSeparator)}`;
+    }
+}
+export function formatCliHelpParameterDescription(input) {
+    const [presenceDetail, ...defaultDetails] = formatParameterRequirementDetails(input.requirement);
+    const details = [
+        presenceDetail,
+        ...input.additionalDetails,
+        ...defaultDetails,
+    ];
+    return `${input.description} (${details.join(CLI_HELP_LAYOUT.detailSeparator)})`;
+}
+export function renderCliHelpExamples(examples, executableName) {
+    return examples.flatMap((example, index) => [
+        ...(index === 0 ? [] : [CLI_HELP_LAYOUT.emptyLine]),
+        `${CLI_HELP_LAYOUT.itemIndent}${example.title}:`,
+        `${CLI_HELP_LAYOUT.nestedItemIndent}${CLI_HELP_TEXT.useWhenPrefix} ${example.useWhen}`,
+        CLI_HELP_LAYOUT.emptyLine,
+        `${CLI_HELP_LAYOUT.nestedItemIndent}${appendCliCommandPart(executableName, example.command)}`,
+        ...(example.expectedResult.length === 0
+            ? []
+            : [
+                CLI_HELP_LAYOUT.emptyLine,
+                `${CLI_HELP_LAYOUT.nestedItemIndent}${CLI_HELP_TEXT.expectedResultHeading}`,
+                ...example.expectedResult.map((line) => `${CLI_HELP_LAYOUT.resultIndent}${line}`),
+            ]),
+    ]);
+}
+function formatParameterRequirementDetails(requirement) {
+    switch (requirement.kind) {
+        case PARAMETER_REQUIREMENT_KIND.required:
+            return [CLI_HELP_TEXT.requiredDetail];
+        case PARAMETER_REQUIREMENT_KIND.optional:
+            return [CLI_HELP_TEXT.optionalDetail];
+        case PARAMETER_REQUIREMENT_KIND.optionalWithDefault:
+            return [
+                CLI_HELP_TEXT.optionalDetail,
+                `${CLI_HELP_TEXT.defaultDetailPrefix} ${JSON.stringify(requirement.defaultValue)}`,
+            ];
+    }
+}

package/dist/cli-schema.d.ts

@@ -0,0 +1,4 @@
+import type { CliEntryBinding, CliSegment } from "./cli-model.js";
+export declare function isCliSegment(value: unknown): value is CliSegment;
+export declare function isCliEntryBinding(value: unknown): value is CliEntryBinding;
+//# sourceMappingURL=cli-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli-schema.d.ts","sourceRoot":"","sources":["../src/cli-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGlE,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E"}

package/dist/cli-schema.js

@@ -0,0 +1,7 @@
+import { isChannelPayload, PAYLOAD_KIND } from "./tree-internal.js";
+export function isCliSegment(value) {
+    return isChannelPayload(PAYLOAD_KIND.cliSegment, value);
+}
+export function isCliEntryBinding(value) {
+    return isChannelPayload(PAYLOAD_KIND.cliBinding, value);
+}

package/dist/cli-tree.d.ts

@@ -0,0 +1,4 @@
+import { type CliRouter } from "./cli-model.js";
+import type { EntryTreeDefinition } from "./model.js";
+export declare function createCliRouter(tree: EntryTreeDefinition): CliRouter;
+//# sourceMappingURL=cli-tree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli-tree.d.ts","sourceRoot":"","sources":["../src/cli-tree.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,SAAS,EAIf,MAAM,gBAAgB,CAAC;AAOxB,OAAO,KAAK,EACV,mBAAmB,EAIpB,MAAM,YAAY,CAAC;AAuDpB,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,SAAS,CAOpE"}