Something went wrong. Try again.
A nicer S3 CLI
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126import { GLOBAL_OPTIONS, namesOf, type ArgSpec, type CommandSpec, type OptionSpec } from './command.ts';import { bold, dim, cyan, visibleLength } from './output.ts';
// Help, from the command tree: `s3cli --help` is the overview, `s3cli get// --help` is everything about downloading, and `--json` turns either into a// description a program can read — options, types, choices, arguments, and// the subcommands beneath — so an agent can discover the whole interface// without parsing prose. In the shell the same help is given, without the// `s3cli` in front: the shell's root is named ''.
function commandName(path: CommandSpec[]): string { return [path[0]!.name, ...path.slice(1).map((command) => command.name)].filter(Boolean).join(' ');}
function optionFlag(spec: OptionSpec): string { const short = spec.short ? `-${spec.short}, ` : ' '; const value = spec.type === 'boolean' ? '' : ` <${spec.value ?? (spec.choices ? spec.choices.join('|') : spec.type === 'number' ? 'n' : 'value')}>`; return `${short}--${spec.name}${value}`;}
function optionText(spec: OptionSpec): string { const extra: string[] = []; if (spec.choices && spec.value) extra.push(`one of: ${spec.choices.join(', ')}`); if (spec.type === 'list') extra.push('repeatable'); if (spec.default !== undefined && spec.type !== 'boolean') extra.push(`default: ${spec.default}`); if (spec.setting) extra.push(`setting: ${spec.setting}`); return `${spec.description}${extra.length ? dim(` (${extra.join('; ')})`) : ''}`;}
function rows(entries: [string, string][], indent = 2): string[] { const width = Math.min(34, Math.max(...entries.map(([left]) => visibleLength(left))) + 2); return entries.map(([left, right]) => (visibleLength(left) + 2 > width ? `${' '.repeat(indent)}${left}\n${' '.repeat(indent + width)}${right}` : `${' '.repeat(indent)}${left}${' '.repeat(width - visibleLength(left))}${right}`));}
function argUsage(arg: ArgSpec): string { const name = `<${arg.name}>${arg.variadic ? '...' : ''}`; return arg.required ? name : `[${name}]`;}
export function usageLine(path: CommandSpec[]): string { const command = path[path.length - 1]!; const name = commandName(path); if (!command.run) return `${name} <command> [options]`; const args = (command.args ?? []).map(argUsage).join(' '); return `${name}${command.options?.length ? ' [options]' : ''}${args ? ` ${args}` : ''}`;}
export function helpText(path: CommandSpec[]): string { const command = path[path.length - 1]!; const root = path.length === 1; const lines: string[] = [];
lines.push(root ? `${bold(path[0]!.name || 's3cli shell')} — ${command.summary}.` : `${bold(commandName(path))} — ${command.summary}`); if (command.description) lines.push('', ...command.description.trim().split('\n')); lines.push('', bold('Usage'), ` ${usageLine(path)}`); if (command.default) lines.push(` ${commandName(path)} ${dim(`(same as '${commandName(path)} ${command.default}')`)}`); const aliases = namesOf(command).slice(1); if (aliases.length) lines.push(` ${dim(`also: ${aliases.map((alias) => [path[0]!.name, ...path.slice(1, -1).map((c) => c.name), alias].filter(Boolean).join(' ')).join(', ')}`)}`);
const subs = (command.subcommands ?? []).filter((sub) => !sub.hidden); if (subs.length) { const groups = new Map<string, CommandSpec[]>(); for (const sub of subs) { const group = sub.group ?? 'Commands'; groups.set(group, [...(groups.get(group) ?? []), sub]); } for (const [group, members] of groups) { lines.push('', bold(group)); lines.push(...rows(members.map((sub) => [cyan(sub.name), sub.summary]))); } }
if (command.args?.length && command.run) { lines.push('', bold('Arguments'), ...rows(command.args.map((arg) => [argUsage(arg), arg.description]))); }
const own = (command.options ?? []).filter((spec) => !spec.hidden); if (own.length && command.run) lines.push('', bold('Options'), ...rows(own.map((spec) => [optionFlag(spec), optionText(spec)]))); lines.push('', bold(root ? 'Options' : 'Global options'), ...rows(GLOBAL_OPTIONS.map((spec) => [optionFlag(spec), optionText(spec)])));
if (command.examples?.length) lines.push('', bold('Examples'), ...command.examples.map((example) => ` ${example.startsWith('#') ? dim(example) : `$ ${example}`}`));
if (subs.length) lines.push('', dim(`Add --help to any command for its details, e.g. '${[commandName(path), subs[0]!.name].filter(Boolean).join(' ')} --help'.`)); if (root && path[0]!.name) { lines.push(dim('Add --json to any command for machine-readable output (help included).')); lines.push(dim('Exit codes: 0 ok, 1 error, 2 usage, 3 no usable keys, 4 not found, 5 rate limited, 6 needs input.')); } return `${lines.join('\n')}\n`;}
/** The command (and everything beneath it) as data. */export function helpJson(path: CommandSpec[], deep = true): unknown { const command = path[path.length - 1]!; const option = (spec: OptionSpec) => ({ name: spec.name, flag: `--${spec.name}`, ...(spec.short ? { short: `-${spec.short}` } : {}), type: spec.type, ...(spec.value ? { value: spec.value } : {}), ...(spec.choices ? { choices: spec.choices } : {}), ...(spec.default !== undefined ? { default: spec.default } : {}), ...(spec.setting ? { setting: spec.setting } : {}), description: spec.description, }); return { command: commandName(path), summary: command.summary, ...(command.description ? { description: command.description.trim() } : {}), ...(command.aliases?.length ? { aliases: command.aliases } : {}), usage: usageLine(path), ...(command.run ? { arguments: (command.args ?? []).map((arg) => ({ name: arg.name, required: Boolean(arg.required), variadic: Boolean(arg.variadic), description: arg.description })), options: (command.options ?? []).filter((spec) => !spec.hidden).map(option), } : {}), ...(path.length === 1 ? { globalOptions: GLOBAL_OPTIONS.map(option) } : {}), ...(command.default ? { default: command.default } : {}), ...(command.examples?.length ? { examples: command.examples } : {}), ...(command.subcommands?.length ? { subcommands: command.subcommands.filter((sub) => !sub.hidden).map((sub) => (deep ? helpJson([...path, sub], true) : { command: commandName([...path, sub]), summary: sub.summary })), } : {}), };}