sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy/ src/ Cli/ components/ view/ Help.tsx
/** @jsxRuntime automatic */
/** @jsxImportSource @alchemy.run/sigil */
/** Branded help screens + the CliOutput formatter that renders them. */
import { stripVTControlCharacters } from "node:util";
import * as CliOutput from "effect/cli/CliOutput";
import type { HelpDoc } from "effect/cli/HelpDoc";
import * as Option from "effect/Option";
import type { JSX } from "react";
import packageJson from "../../../../package.json" with { type: "json" };
import type { Interaction } from "../../../Interaction.ts";
import { ANSI_BOLD, ANSI_DIM, ansiFg, paint, truncate } from "../../../Util/Terminal.ts";
import { glyphsFor, theme } from "../../../Util/Theme.ts";
import { Box, Heading, Text, useGlyphs } from "../ui/index.ts";
import { formatView } from "./Format.tsx";
import { Logo } from "./Logo.tsx";
const commandLabel = (command: { readonly name: string; readonly alias?: string | undefined }) =>
command.alias ? `${command.name}, ${command.alias}` : command.name;
/** Shell-like highlighting shared by usage lines, examples, and help hints. */
function CommandText({ command }: { readonly command: string }): JSX.Element {
const tokens = command.match(/\s+|"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+/g) ?? [command];
let word = 0;
let valueAfterFlag = false;
return (
<Text>
{tokens.map((token, index) => {
if (/^\s+$/.test(token)) return token;
const currentWord = word++;
const isFlag = token.startsWith("-");
const isPlaceholder =
(token.startsWith("<") && token.endsWith(">")) ||
(token.startsWith("[") && token.endsWith("]"));
const isQuoted =
(token.startsWith('"') && token.endsWith('"')) ||
(token.startsWith("'") && token.endsWith("'"));
const isValue = valueAfterFlag || isQuoted;
valueAfterFlag = isFlag;
return (
<Text
key={`${index}:${token}`}
bold={currentWord <= 1 || isFlag}
color={
currentWord === 0
? theme.color.accent
: isFlag
? theme.color.info
: isPlaceholder
? theme.color.warning
: isValue
? theme.color.success
: currentWord === 1
? theme.color.accentBright
: undefined
}
>
{token}
</Text>
);
})}
</Text>
);
}
/** One aligned help row: fixed-width bold label cell + description. */
type RowProps = {
label: JSX.Element | string;
description: string;
width: number;
};
function Row({ label, description, width }: RowProps) {
return (
<Box paddingLeft={2}>
<Box width={width} flexShrink={0}>
{typeof label === "string" ? (
<Text bold tone="emphasis">
{label}
</Text>
) : (
label
)}
</Box>
<Text>{description}</Text>
</Box>
);
}
function BrandLine(): JSX.Element {
const glyphs = useGlyphs();
return (
<Text>
<Text tone="brand">{glyphs.selected}</Text>{" "}
<Text bold tone="emphasis">
alchemy
</Text>{" "}
<Text tone="muted">— Infrastructure as Effects</Text>
</Text>
);
}
/**
* Branded help for every command. The root gets a brand header and shows
* only `--help`/`--version` (as OPTIONS); subcommands list all global flags.
*/
type SubHelpProps = {
doc: HelpDoc;
root?: boolean;
};
function SubHelp({ doc, root = false }: SubHelpProps): JSX.Element {
const commands = doc.subcommands?.flatMap((group) => group.commands) ?? [];
const flags = doc.flags ?? [];
const globalFlags = root
? (doc.globalFlags ?? []).filter((flag) => flag.name === "help" || flag.name === "version")
: (doc.globalFlags ?? []);
const args = doc.args ?? [];
const flagLabel = (flag: (typeof flags)[number]) => {
const aliases = flag.aliases.length > 0 ? `, ${flag.aliases.join(", ")}` : "";
return `--${flag.name}${aliases}`;
};
const argLabel = (arg: (typeof args)[number]) =>
arg.required ? `<${arg.name}>` : `[${arg.name}]`;
// width from labels only — enum types (--log-level's choice list) would
// otherwise blow the column out; long types truncate inside the cell
const nameWidth =
Math.min(
30,
Math.max(
12,
...commands.map((c) => commandLabel(c).length),
...[...flags, ...globalFlags].map((f) => flagLabel(f).length),
...args.map((a) => argLabel(a).length),
),
) + 4;
type FlagRowProps = { readonly flag: (typeof flags)[number] };
function FlagRow({ flag }: FlagRowProps) {
const label = flagLabel(flag);
const typeRoom = nameWidth - label.length - 2;
return (
<Row
width={nameWidth}
description={Option.getOrElse(flag.description, () => "")}
label={
<Text>
<Text bold color={theme.color.info}>
--{flag.name}
</Text>
{flag.aliases.map((alias) => (
<Text key={alias} color={theme.color.info}>
, {alias}
</Text>
))}
{flag.type === "boolean" || typeRoom < 8 ? null : (
<Text color={theme.color.warning}> {truncate(flag.type, typeRoom)}</Text>
)}
</Text>
}
/>
);
}
return (
<Box flexDirection="column" flexShrink={root ? 0 : 1}>
{root ? <BrandLine /> : null}
{doc.description === "" ? null : (
<Box marginTop={root ? 1 : 0}>
<Text>{doc.description}</Text>
</Box>
)}
<Box marginTop={doc.description === "" && !root ? 0 : 1}>
<Heading glyph={false}>USAGE</Heading>
</Box>
<Text>
{" "}
<Text tone="brand">Loading Sailfork
lt;/Text> <CommandText command={doc.usage} />
</Text>
{args.length === 0 ? null : (
<>
<Box marginTop={1}>
<Heading glyph={false}>ARGUMENTS</Heading>
</Box>
{args.map((arg) => (
<Row
key={arg.name}
width={nameWidth}
label={
<Text bold color={theme.color.warning}>
{argLabel(arg)}
</Text>
}
description={Option.getOrElse(arg.description, () => "")}
/>
))}
</>
)}
{commands.length === 0 ? null : (
<>
<Box marginTop={1}>
<Heading glyph={false}>COMMANDS</Heading>
</Box>
{commands.map((command) => (
<Row
key={command.name}
width={nameWidth}
label={
<Text>
<Text bold color={theme.color.accentBright}>
{command.name}
</Text>
{command.alias === undefined ? null : (
<Text color={theme.color.info}>, {command.alias}</Text>
)}
</Text>
}
description={command.description || ""}
/>
))}
</>
)}
{flags.length === 0 ? null : (
<>
<Box marginTop={1}>
<Heading glyph={false}>FLAGS</Heading>
</Box>
{flags.map((flag) => (
<FlagRow key={flag.name} flag={flag} />
))}
</>
)}
{globalFlags.length === 0 ? null : (
<>
<Box marginTop={1}>
<Heading glyph={false}>{root ? "OPTIONS" : "GLOBAL FLAGS"}</Heading>
</Box>
{globalFlags.map((flag) => (
<FlagRow key={flag.name} flag={flag} />
))}
</>
)}
{doc.examples === undefined || doc.examples.length === 0 ? null : (
<>
<Box marginTop={1}>
<Heading glyph={false}>EXAMPLES</Heading>
</Box>
{doc.examples.map((example) => (
<Text key={example.command}>
{" "}
<Text tone="brand">Loading Sailfork
lt;/Text> <CommandText command={example.command} />
</Text>
))}
</>
)}
{commands.length === 0 ? null : (
<Box marginTop={1}>
<Text>
<Text color={theme.color.muted}>Run '</Text>
<CommandText
command={`${doc.usage.replace(/\s*<subcommand>.*$/, "")} <command> --help`}
/>
<Text color={theme.color.muted}>' for more information on a command.</Text>
</Text>
</Box>
)}
</Box>
);
}
const formatSubHelp = (cli: Interaction["Service"], doc: HelpDoc) => {
const termCols = cli.terminal.columns;
return formatView(
<Box width={termCols}>
<SubHelp doc={doc} />
</Box>,
cli.terminal,
{ columns: termCols },
);
};
/** Hide the logo entirely when it can't be at least this many columns wide. */
const MIN_LOGO_COLS = 20;
const formatRootHelp = (cli: Interaction["Service"], doc: HelpDoc) => {
const termCols = cli.terminal.columns;
// First pass: render the text alone to measure its exact footprint (post
// ANSI codes and wrapping), then size the logo into the leftover space.
const text = formatView(
<Box width={termCols}>
<SubHelp doc={doc} root />
</Box>,
cli.terminal,
{ columns: termCols },
);
// The braille logo is mojibake without Unicode support.
if (!cli.terminal.unicode) return text;
const lines = text.split("\n");
const textWidth = Math.max(
...lines.map((line) => stripVTControlCharacters(line).trimEnd().length),
);
const textHeight = lines.length;
// Fill the free space beside the text: a logo of C columns is C/2 rows
// tall (braille cell is 1:2). Reserve two rows for the wordmark caption.
const logoCols = Math.min(termCols - textWidth - 2, (textHeight - 2) * 2);
if (logoCols < MIN_LOGO_COLS) return text;
return formatView(
<Box flexDirection="row" width={termCols}>
<SubHelp doc={doc} root />
<Box flexGrow={1} flexDirection="column" justifyContent="center" alignItems="center">
<Logo cols={logoCols} />
<Box marginTop={1}>
<Text>
<Text bold color={theme.color.accent}>
ALCHEMY
</Text>{" "}
<Text tone="muted">v{packageJson.version}</Text>
</Text>
</Box>
</Box>
</Box>,
cli.terminal,
{ columns: termCols },
);
};
export const brandedCliFormatter = (cli: Interaction["Service"]): CliOutput.Formatter => {
const fallback = CliOutput.defaultFormatter();
const glyphs = glyphsFor(cli.terminal.unicode);
const formatErrorLine = (message: string) =>
`${paint(ansiFg(theme.color.danger), `${glyphs.error} error:`)} ${message}`;
return {
formatCliError: fallback.formatCliError,
formatHelpDoc: (doc) =>
doc.usage.startsWith("alchemy <subcommand>")
? formatRootHelp(cli, doc)
: formatSubHelp(cli, doc),
formatVersion: (name, version) =>
`${paint(ansiFg(theme.color.brand), glyphs.selected)} ${paint(ANSI_BOLD, name)} ${paint(ANSI_DIM, `v${version}`)}`,
formatError: (error) => `\n${formatErrorLine(error.message)}`,
formatErrors: (errors) => {
if (errors.length === 0) return "";
if (errors.length === 1) return `\n${formatErrorLine(errors[0].message)}`;
return `\n${formatErrorLine(`${errors.length} problems`)}\n${errors
.map((error) => ` ${paint(ANSI_DIM, glyphs.bullet)} ${error.message}`)
.join("\n")}`;
},
};
};