automate.ax 0.1.3

package/dist/cli/usage.js

@@ -0,0 +1,468 @@
+import { bold } from "ansis";
+import { toKebabCase } from "remeda";
+import { commandNames } from "./command-names.js";
+import { accent, dimmed } from "./lib/io.js";
+const COMMAND_GROUPS = [
+    {
+        heading: "ACCOUNT",
+        commands: [commandNames.login, commandNames.logout, commandNames.me],
+    },
+    {
+        heading: "RESOURCES",
+        commands: [
+            commandNames.org.root,
+            commandNames.project.root,
+            commandNames.invite,
+            commandNames.upgrade,
+        ],
+    },
+    {
+        heading: "AUTOMATIONS",
+        commands: [commandNames.deploy],
+    },
+    {
+        heading: "OTHER",
+        commands: [commandNames.accept, commandNames.debug],
+    },
+];
+/**
+ * Prints CLI help with Automate.ax's own accent color and grouped root commands.
+ *
+ * @param cmd - Command definition to render.
+ * @param parent - Parent definition for a nested command.
+ */
+export const showUsage = async (cmd, parent) => {
+    // This is also used by Citty for routing errors. Keep usage on stdout for
+    // now, matching Citty's callback shape, while the error line goes to stderr.
+    console.log((await renderUsage(cmd, parent)) + "\n");
+};
+/**
+ * Renders command usage text without Citty's built-in cyan styling.
+ *
+ * @param cmd - Command definition to render.
+ * @param parent - Parent definition for a nested command.
+ */
+async function renderUsage(cmd, parent) {
+    if (!parent && (await resolveMeta(cmd)).name === commandNames.root) {
+        return renderRootUsage(cmd);
+    }
+    return renderCommandUsage(cmd, parent);
+}
+/**
+ * Renders the top-level help screen with commands grouped by user intent.
+ *
+ * @param cmd - Root command definition to render.
+ */
+async function renderRootUsage(cmd) {
+    const meta = await resolveMeta(cmd);
+    const commandName = meta.name ?? commandNames.root;
+    const optionRows = createOptionRows(await resolveArgs(cmd));
+    const subCommands = await resolveSubCommands(cmd);
+    const lines = [
+        dimmed `${meta.description ?? "Automate.ax CLI"} (${commandName}${meta.version ? ` v${meta.version}` : ""})`,
+        "",
+        `${bold.underline `USAGE`} ${renderCommandUsageLine(commandName, `${optionRows.length > 0 ? "[OPTIONS] " : ""}<command>`)}`,
+        "",
+    ];
+    if (optionRows.length > 0) {
+        lines.push(bold.underline `OPTIONS`, "", formatRows(optionRows), "");
+    }
+    lines.push(bold.underline `COMMANDS`, "");
+    const groupedCommands = new Set(COMMAND_GROUPS.flatMap((group) => group.commands));
+    const groupRows = await Promise.all(COMMAND_GROUPS.map(async (group) => ({
+        ...group,
+        rows: await commandRows(group.commands, subCommands),
+    })));
+    const otherRows = await commandRows(Object.keys(subCommands).filter((name) => !groupedCommands.has(name)), subCommands);
+    const rootWidth = getMaxLabelWidth([
+        ...groupRows.flatMap(({ rows }) => rows),
+        ...otherRows,
+    ]);
+    for (const group of COMMAND_GROUPS) {
+        const rows = groupRows.find(({ heading }) => heading === group.heading)?.rows ?? [];
+        if (rows.length === 0)
+            continue;
+        lines.push(dimmed(group.heading));
+        lines.push(formatRows(rows, rootWidth));
+        lines.push("");
+    }
+    if (otherRows.length > 0) {
+        lines.push(dimmed `OTHER`);
+        lines.push(formatRows(otherRows, rootWidth));
+        lines.push("");
+    }
+    lines.push(`${accent `${commandName} <command> --help`} for more information about a command.`);
+    return lines.join("\n");
+}
+/**
+ * Renders non-root command help while preserving Citty's layout conventions.
+ *
+ * @param cmd - Command definition to render.
+ * @param parent - Parent definition used to qualify the command name.
+ */
+async function renderCommandUsage(cmd, parent) {
+    const meta = await resolveMeta(cmd);
+    const parentMeta = parent ? await resolveMeta(parent) : {};
+    const commandName = renderCommandName(meta, parentMeta);
+    const optionRows = [];
+    const positionalRows = [];
+    const usageParts = [];
+    for (const arg of await resolveArgs(cmd)) {
+        if (arg.type === "positional") {
+            const name = renderPositionalName(arg);
+            const required = arg.required !== false && arg.default === undefined;
+            positionalRows.push(createRow(renderPositionalLabel(name), renderDescription(arg, required)));
+            usageParts.push(required ? `<${name}>` : `[${name}]`);
+            continue;
+        }
+        optionRows.push(...createOptionRows([arg]));
+        if (arg.required === true && arg.default === undefined) {
+            usageParts.push(`--${toKebabCase(arg.name)}${renderValueHint(arg)}`);
+        }
+    }
+    const commandRows = await commandRowsForSubCommands(await resolveSubCommands(cmd));
+    if (commandRows.length > 0) {
+        usageParts.push("<command>");
+    }
+    const version = meta.version ?? parentMeta.version;
+    const lines = [
+        dimmed `${meta.description ?? ""} (${commandName}${version ? ` v${version}` : ""})`,
+        "",
+        `${bold.underline `USAGE`} ${renderCommandUsageLine(commandName, [
+            optionRows.length > 0 || positionalRows.length > 0 ? "[OPTIONS]" : "",
+            usageParts.join(" "),
+        ]
+            .filter(Boolean)
+            .join(" "))}`,
+        "",
+    ];
+    if (positionalRows.length > 0) {
+        lines.push(bold.underline `ARGUMENTS`, "", formatRows(positionalRows), "");
+    }
+    if (optionRows.length > 0) {
+        lines.push(bold.underline `OPTIONS`, "", formatRows(optionRows), "");
+    }
+    if (commandRows.length > 0) {
+        lines.push(bold.underline `COMMANDS`, "", formatRows(commandRows), "");
+        lines.push(`${accent `${commandName} <command> --help`} for more information about a command.`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Builds display rows for non-positional options and their negated forms.
+ *
+ * @param args - Arguments whose options should be displayed.
+ */
+function createOptionRows(args) {
+    const optionRows = [];
+    for (const arg of args) {
+        if (arg.type === "positional")
+            continue;
+        optionRows.push(createRow(renderOptionLabel(arg), renderOptionDescription(arg, arg.required === true && arg.default === undefined)));
+        if (shouldRenderNegativeFlag(arg)) {
+            optionRows.push(createRow(renderFlagLabel(`--no-${toKebabCase(arg.name)}`), renderNegativeDescription(arg)));
+        }
+    }
+    return optionRows;
+}
+/**
+ * Resolves command metadata, including lazy Citty values.
+ *
+ * @param cmd - Command-like value containing optional metadata.
+ * @param cmd.meta - Static or lazy metadata to resolve.
+ */
+async function resolveMeta(cmd) {
+    return cmd.meta ? await resolveValue(cmd.meta) : {};
+}
+/**
+ * Resolves command args and normalizes aliases to arrays.
+ *
+ * @param cmd - Command whose argument definitions should be resolved.
+ */
+async function resolveArgs(cmd) {
+    if (!cmd.args)
+        return [];
+    return Object.entries(await resolveValue(cmd.args)).map(([name, arg]) => ({
+        ...arg,
+        name,
+        alias: "alias" in arg
+            ? typeof arg.alias === "string"
+                ? [arg.alias]
+                : (arg.alias ?? [])
+            : [],
+    }));
+}
+/**
+ * Resolves visible subcommands by name.
+ *
+ * @param cmd - Command whose child definitions should be resolved.
+ */
+async function resolveSubCommands(cmd) {
+    return Object.fromEntries((await Promise.all(Object.entries(cmd.subCommands ? await resolveValue(cmd.subCommands) : {}).map(async ([name, subCommand]) => {
+        const command = await resolveValue(subCommand);
+        return (await resolveMeta(command)).hidden
+            ? null
+            : [name, command];
+    }))).filter((entry) => entry != null));
+}
+/**
+ * Resolves Citty values that may be lazy or async.
+ *
+ * @param value - Static, promised, or lazily computed value.
+ */
+async function resolveValue(value) {
+    if (isAwaitable(value)) {
+        return await value();
+    }
+    return await value;
+}
+/**
+ * Narrows Citty resolvables that use lazy functions.
+ *
+ * @param value - Resolvable value to inspect.
+ */
+function isAwaitable(value) {
+    return typeof value === "function";
+}
+/**
+ * Builds display rows for requested subcommand names.
+ *
+ * @param names - Subcommand names to include, in display order.
+ * @param subCommands - Resolved subcommands indexed by name.
+ */
+async function commandRows(names, subCommands) {
+    return (await Promise.all(names.map(async (name) => {
+        const command = subCommands[name];
+        if (!command)
+            return null;
+        const meta = await resolveMeta(command);
+        if (meta.hidden)
+            return null;
+        return createRow(name, meta.description ?? "");
+    }))).filter((row) => row != null);
+}
+/**
+ * Builds display rows for all visible child commands.
+ *
+ * @param subCommands - Resolved subcommands indexed by name.
+ */
+async function commandRowsForSubCommands(subCommands) {
+    return commandRows(Object.keys(subCommands), subCommands);
+}
+/**
+ * Formats two-column CLI rows with right-aligned command labels.
+ *
+ * @param rows - Styled label and description rows to format.
+ * @param width - Display width reserved for the label column.
+ */
+function formatRows(rows, width = getMaxLabelWidth(rows)) {
+    return rows
+        .map(({ description, label, width: labelWidth }) => {
+        const descriptionIndent = " ".repeat(2 + width + 2);
+        const [firstDescription = "", ...rest] = description.split("\n");
+        return [
+            `  ${" ".repeat(width - labelWidth)}${label}  ${firstDescription}`,
+            ...rest.map((line) => `${descriptionIndent}${line}`),
+        ].join("\n");
+    })
+        .join("\n");
+}
+/**
+ * Creates an accent-styled row while preserving plain label width.
+ *
+ * @param label - Plain label to accent or an already styled syntax label.
+ * @param description - Description displayed beside the label.
+ */
+function createRow(label, description) {
+    if (typeof label !== "string") {
+        return {
+            description,
+            label: label.text,
+            width: label.width,
+        };
+    }
+    return {
+        description,
+        label: accent(label),
+        width: label.length,
+    };
+}
+/**
+ * Finds max display width for row labels.
+ *
+ * @param rows - Rows whose label widths should be compared.
+ */
+function getMaxLabelWidth(rows) {
+    return Math.max(...rows.map((row) => row.width));
+}
+/**
+ * Renders a usage line as command plus dimmed syntax placeholders.
+ *
+ * @param command - Command invocation to accent.
+ * @param syntax - Optional usage syntax appended in dimmed text.
+ */
+function renderCommandUsageLine(command, syntax = "") {
+    return [accent(command), syntax ? dimmed ` ${syntax}` : ""].join("");
+}
+/**
+ * Renders help with the primary binary name, even for nested commands.
+ *
+ * @param meta - Metadata for the command being rendered.
+ * @param parentMeta - Metadata for its immediate parent command.
+ */
+function renderCommandName(meta, parentMeta) {
+    const name = meta.name ?? commandNames.root;
+    if (!parentMeta.name)
+        return name;
+    if (parentMeta.name === commandNames.root)
+        return `${parentMeta.name} ${name}`;
+    return `${commandNames.root} ${parentMeta.name} ${name}`;
+}
+/**
+ * Renders a positional label as placeholder syntax.
+ *
+ * @param label - Plain positional placeholder.
+ */
+function renderPositionalLabel(label) {
+    return {
+        text: dimmed(label),
+        width: label.length,
+    };
+}
+/**
+ * Renders positional arg names as readable CLI placeholders.
+ *
+ * @param arg - Positional argument definition.
+ */
+function renderPositionalName(arg) {
+    return (arg.valueHint ?? toKebabCase(arg.name)).toUpperCase();
+}
+/**
+ * Renders option names with dimmed punctuation and placeholders.
+ *
+ * @param arg - Option definition, including aliases and value hints.
+ */
+function renderOptionLabel(arg) {
+    const labels = [
+        ...arg.alias.map((alias) => `-${alias}`),
+        `--${toKebabCase(arg.name)}`,
+    ];
+    const lastIndex = labels.length - 1;
+    return joinSyntaxLabels(labels.map((label, index) => index === lastIndex
+        ? concatSyntaxLabels(renderFlagLabel(label), renderValueHintLabel(arg))
+        : renderFlagLabel(label)), { text: dimmed `, `, width: 2 });
+}
+/**
+ * Renders a flag name in accent color.
+ *
+ * @param label - Plain flag name.
+ */
+function renderFlagLabel(label) {
+    return {
+        text: accent(label),
+        width: label.length,
+    };
+}
+/**
+ * Renders option value hints as dimmed syntax.
+ *
+ * @param arg - Option definition used to derive the placeholder.
+ */
+function renderValueHintLabel(arg) {
+    const hint = renderValueHint(arg);
+    return {
+        text: dimmed(hint),
+        width: hint.length,
+    };
+}
+/**
+ * Joins syntax labels with styled separator text.
+ *
+ * @param labels - Styled syntax fragments to join.
+ * @param separator - Styled separator placed between fragments.
+ */
+function joinSyntaxLabels(labels, separator) {
+    return {
+        text: labels.map((label) => label.text).join(separator.text),
+        width: labels.reduce((width, label) => width + label.width, 0) +
+            separator.width * Math.max(0, labels.length - 1),
+    };
+}
+/**
+ * Concatenates syntax labels without separators.
+ *
+ * @param labels - Styled syntax fragments to concatenate.
+ */
+function concatSyntaxLabels(...labels) {
+    return {
+        text: labels.map((label) => label.text).join(""),
+        width: labels.reduce((width, label) => width + label.width, 0),
+    };
+}
+/**
+ * Renders value placeholders for options and positionals.
+ *
+ * @param arg - Argument definition used to derive the placeholder.
+ */
+function renderValueHint(arg) {
+    if (arg.valueHint) {
+        return `=<${arg.valueHint}>`;
+    }
+    if (!arg.type || arg.type === "positional" || arg.type === "boolean") {
+        return "";
+    }
+    if (arg.type === "enum" && arg.options?.length) {
+        return `=<${arg.options.join("|")}>`;
+    }
+    return `=<${toKebabCase(arg.name)}>`;
+}
+/**
+ * Renders descriptions plus required/default hints.
+ *
+ * @param arg - Argument whose description and default should be rendered.
+ * @param required - Whether to append a required marker.
+ */
+function renderDescription(arg, required) {
+    return [
+        arg.description,
+        required ? dimmed `(Required)` : "",
+        arg.default === undefined ? "" : dimmed `(Default: ${arg.default})`,
+    ]
+        .filter(Boolean)
+        .join(" ");
+}
+/**
+ * Renders option descriptions with defaults on their own indented line.
+ *
+ * @param arg - Option whose description and default should be rendered.
+ * @param required - Whether to append a required marker.
+ */
+function renderOptionDescription(arg, required) {
+    return [
+        [arg.description, required ? dimmed `(Required)` : ""]
+            .filter(Boolean)
+            .join(" "),
+        arg.default === undefined ? "" : dimmed `(Default: ${arg.default})`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+/**
+ * Renders descriptions for boolean negation flags.
+ *
+ * @param arg - Boolean option with an optional custom negation description.
+ */
+function renderNegativeDescription(arg) {
+    if ("negativeDescription" in arg && arg.negativeDescription) {
+        return arg.negativeDescription;
+    }
+    return `Negate ${accent `--${toKebabCase(arg.name)}`}`;
+}
+/**
+ * Shows real Citty-supported negation for every boolean flag.
+ *
+ * @param arg - Argument to test for a generated negated form.
+ */
+function shouldRenderNegativeFlag(arg) {
+    return arg.type === "boolean" && !/^no[-A-Z]/.test(arg.name);
+}