diff --git a/src/cli/cliShell.ts b/src/cli/cliShell.ts index 2be9bb85bd..5d67bc785a 100644 --- a/src/cli/cliShell.ts +++ b/src/cli/cliShell.ts @@ -1,5 +1,4 @@ import { Cli } from "incur"; -import { z } from "zod"; import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import type { FridaInstrumentationPort } from "../ports/frida/FridaInstrumentationPort.js"; @@ -28,6 +27,11 @@ import { } from "./cliResultOutput.js"; import { completionHelpNote, createCliCompletions } from "./completions.js"; import { excludeDeclaredSensitiveArguments } from "./explicitSensitiveArguments.js"; +import { + CLI_CUSTOM_GLOBAL_OPTIONS, + CLI_DESCRIPTION, + serveDiscovery, +} from "./discovery.js"; import { reportUnknownMcpSubcommand } from "./mcpBuiltinCommands.js"; import { serveMcpRegistration } from "./mcpRegistration.js"; import { presentOmittableDefaults } from "./omittableDefaults.js"; @@ -95,13 +99,8 @@ export const createCliShell = (options: CliShellOptions): CliInstance => { ); const timedCli = Cli.create(PRODUCT_IDENTITY.cliBinary, { version: PRODUCT_IDENTITY.packageVersion, - description: "Reverse engineer anything from your terminal or agent.", - globals: z.object({ - timings: z - .boolean() - .default(false) - .describe("Write measured command timing to stderr."), - }), + description: CLI_DESCRIPTION, + globals: CLI_CUSTOM_GLOBAL_OPTIONS, mcp: { instructions: "Ask what software, artifact, protocol, or behavior the user wants to understand, then choose the available investigation capabilities that can produce evidence.", @@ -146,6 +145,13 @@ export const createCliShell = (options: CliShellOptions): CliInstance => { ); presentOmittableDefaults(cli); + // Discovery reads the arguments the dispatcher would, after result output + // has adapted them, so its documents are counted and buffered alike. + const dispatch = cli.serve.bind(cli); + cli.serve = (arguments_ = process.argv.slice(2), serveOptions) => + serveDiscovery(cli, arguments_, serveOptions ?? {}) + ? Promise.resolve() + : dispatch(arguments_, serveOptions); if (options.resultOutput !== undefined) streamCliCommandResults(cli, options.resultOutput); const serveStrict = validateCliArguments(cli); diff --git a/src/cli/commandManifests.ts b/src/cli/commandManifests.ts new file mode 100644 index 0000000000..74a6a69333 --- /dev/null +++ b/src/cli/commandManifests.ts @@ -0,0 +1,193 @@ +/* + * The --llms index, the --llms-full manifest and the --schema document are + * adapted from Incur's manifest and skill generators. + * Copyright (c) 2025-present weth, LLC + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to + * deal in the Software without restriction, including without limitation the + * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or + * sell copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS + * IN THE SOFTWARE. + */ +import { z } from "zod"; + +import type { CliCommandEntry } from "./commandRegistry.js"; + +/** The manifests' format version, which callers may already check. */ +const MANIFEST_VERSION = "incur.v1"; + +type JsonSchema = Record & { + readonly type?: unknown; + readonly properties?: Readonly>; + readonly required?: readonly string[]; + readonly default?: unknown; + readonly deprecated?: unknown; +}; + +/** + * A command input as JSON Schema, without `$schema`. Bigints and dates are + * strings, and unrepresentable types accept anything. + */ +export const commandInputJsonSchema = (schema: z.ZodType): JsonSchema => { + const result = z.toJSONSchema(schema, { + unrepresentable: "any", + override: (context) => { + const type = context.zodSchema._zod.def.type; + if (type === "bigint" || type === "date") + context.jsonSchema.type = "string"; + }, + }) as JsonSchema; + delete result.$schema; + return result; +}; + +/** The JSON type a manifest table shows, with integers shown as numbers. */ +const tableType = (property: JsonSchema | undefined): string => { + const type = property?.type; + if (typeof type !== "string") return "unknown"; + return type === "integer" ? "number" : type; +}; + +const shape = (schema: z.ZodObject): Readonly> => + schema.shape as Readonly>; + +/** `rea [optional] `. */ +const signature = (cli: string, { name, definition }: CliCommandEntry) => { + const base = `${cli} ${name}`; + if (definition.args === undefined) return base; + const json = commandInputJsonSchema(definition.args); + const required = new Set(json.required ?? []); + const names = Object.keys(shape(definition.args)).map((key) => { + const label = json.properties?.[key]?.type === "array" ? `${key}...` : key; + return required.has(key) ? `<${label}>` : `[${label}]`; + }); + return `${base} ${names.join(" ")}`; +}; + +/** The `--llms` Markdown index: one row per command. */ +export const formatLlmsIndex = ( + cli: string, + commands: readonly CliCommandEntry[], + description: string, +): string => + [ + `# ${cli}`, + "", + description, + "", + "| Command | Description |", + "|---------|-------------|", + ...commands.map( + (command) => + `| \`${signature(cli, command)}\` | ${command.definition.description ?? ""} |`, + ), + "", + `Run \`${cli} --llms-full\` for full manifest. Run \`${cli} --schema\` for argument details.`, + ].join("\n"); + +const commandBody = (cli: string, { name, definition }: CliCommandEntry) => { + const heading = + definition.description === undefined || definition.description === "" + ? `# ${cli} ${name}` + : `# ${cli} ${name}\n\n${definition.description}`; + const sections = [heading]; + if (definition.args !== undefined) { + const json = commandInputJsonSchema(definition.args); + const required = new Set(json.required ?? []); + const rows = Object.entries(shape(definition.args)).map( + ([key, field]) => + `| \`${key}\` | \`${tableType(json.properties?.[key])}\` | ${required.has(key) ? "yes" : "no"} | ${field.description ?? ""} |`, + ); + sections.push( + `## Arguments\n\n| Name | Type | Required | Description |\n|------|------|----------|-------------|\n${rows.join("\n")}`, + ); + } + if (definition.options !== undefined) { + const json = commandInputJsonSchema(definition.options); + const rows = Object.entries(shape(definition.options)).map( + ([key, field]) => { + const property = json.properties?.[key]; + const fallback = + property?.default === undefined ? "" : String(property.default); + const text = field.description ?? ""; + const description = + property?.deprecated === true ? `**Deprecated.** ${text}` : text; + return `| \`--${key}\` | \`${tableType(property)}\` | ${fallback === "" ? "" : `\`${fallback}\``} | ${description} |`; + }, + ); + sections.push( + `## Options\n\n| Flag | Type | Default | Description |\n|------|------|---------|-------------|\n${rows.join("\n")}`, + ); + } + return sections.join("\n\n"); +}; + +/** The `--llms-full` Markdown manifest: each command's arguments and options. */ +export const formatLlmsFull = ( + cli: string, + commands: readonly CliCommandEntry[], +): string => commands.map((command) => commandBody(cli, command)).join("\n\n"); + +/** The `--llms` document for a structured format: names and descriptions. */ +export const llmsIndexManifest = ( + commands: readonly CliCommandEntry[], + globals: z.ZodObject, +) => ({ + version: MANIFEST_VERSION, + commands: commands.map(({ name, definition }) => ({ + name, + ...(definition.description ? { description: definition.description } : {}), + })), + globals: commandInputJsonSchema(globals), +}); + +/** The `--llms-full` document for a structured format: each command's input schemas. */ +export const llmsFullManifest = ( + commands: readonly CliCommandEntry[], + globals: z.ZodObject, +) => ({ + version: MANIFEST_VERSION, + commands: commands.map(({ name, definition }) => ({ + name, + ...(definition.description ? { description: definition.description } : {}), + ...(definition.args === undefined && definition.options === undefined + ? {} + : { + schema: { + ...(definition.args === undefined + ? {} + : { args: commandInputJsonSchema(definition.args) }), + ...(definition.options === undefined + ? {} + : { options: commandInputJsonSchema(definition.options) }), + }, + }), + })), + globals: commandInputJsonSchema(globals), +}); + +/** The `--schema` document of one command. */ +export const commandSchemaDocument = ( + { definition }: CliCommandEntry, + globals: z.ZodObject, +) => ({ + ...(definition.args === undefined + ? {} + : { args: commandInputJsonSchema(definition.args) }), + ...(definition.options === undefined + ? {} + : { options: commandInputJsonSchema(definition.options) }), + globals: commandInputJsonSchema(globals), +}); diff --git a/src/cli/commandSuggestion.ts b/src/cli/commandSuggestion.ts new file mode 100644 index 0000000000..4e7bf3d4cf --- /dev/null +++ b/src/cli/commandSuggestion.ts @@ -0,0 +1,74 @@ +/* + * The ranking is adapted from Incur's command suggestion. + * Copyright (c) 2025-present weth, LLC + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to + * deal in the Software without restriction, including without limitation the + * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or + * sell copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS + * IN THE SOFTWARE. + */ + +/** The edit distance between two strings. */ +const editDistance = (left: string, right: string): number => { + const row = Array.from({ length: right.length + 1 }, (_, index) => index); + for (let i = 1; i <= left.length; i += 1) { + let diagonal = row[0]!; + row[0] = i; + for (let j = 1; j <= right.length; j += 1) { + const above = row[j]!; + row[j] = + left[i - 1] === right[j - 1] + ? diagonal + : 1 + Math.min(diagonal, above, row[j - 1]!); + diagonal = above; + } + } + return row[right.length]!; +}; + +/** + * The command a mistyped name most likely meant, or undefined. Candidates + * that extend the input rank first, then ones that contain it, then ones + * within a small edit distance (2 for inputs of up to 4 characters, otherwise + * half the input's length). Within a tier the smallest distance wins, and the + * first candidate wins a tie. Case is ignored. + */ +export const suggestCommand = ( + input: string, + candidates: Iterable, +): string | undefined => { + const threshold = input.length <= 4 ? 2 : Math.floor(input.length / 2); + const lower = input.toLowerCase(); + let best: string | undefined; + let bestScore = Infinity; + for (const candidate of candidates) { + const name = candidate.toLowerCase(); + const distance = editDistance(lower, name); + const score = + name.startsWith(lower) && name !== lower + ? distance + : name.includes(lower) + ? 100 + distance + : distance <= threshold + ? 200 + distance + : undefined; + if (score !== undefined && score < bestScore) { + bestScore = score; + best = candidate; + } + } + return best; +}; diff --git a/src/cli/completions.ts b/src/cli/completions.ts index 713d292753..cc747d96c9 100644 --- a/src/cli/completions.ts +++ b/src/cli/completions.ts @@ -17,6 +17,7 @@ import { type CompletionCommand, } from "./completionProtocol.js"; import { cliCommands } from "./commandRegistry.js"; +import { COMPLETIONS_DESCRIPTION, MCP_GROUP_DESCRIPTION } from "./discovery.js"; import { MCP_SUBCOMMANDS } from "./mcpBuiltinCommands.js"; import type { CliInstance } from "./types.js"; import { MCP_DOCTOR_ALIAS, MCP_DOCTOR_OPTIONS } from "../mcpDoctorOptions.js"; @@ -100,12 +101,12 @@ const completionCommands = ( ); commands.set("mcp", { _group: true, - description: "Register as MCP server", + description: MCP_GROUP_DESCRIPTION, commands: MCP_SUBCOMMANDS, }); commands.set("completions", { _group: true, - description: "Generate shell completion script", + description: COMPLETIONS_DESCRIPTION, commands: new Map(CLI_COMPLETION_SHELLS.map((shell) => [shell, {}])), }); // REA uses sync:false, so the framework's skills integration is disabled. diff --git a/src/cli/discovery.ts b/src/cli/discovery.ts new file mode 100644 index 0000000000..a73e00a46a --- /dev/null +++ b/src/cli/discovery.ts @@ -0,0 +1,291 @@ +import { z } from "zod"; + +import { + parseCliGlobalArguments, + type CliGlobalArguments, +} from "../cliBuiltinArguments.js"; +import { + CLI_DOCUMENT_OUTPUT_FORMATS, + CLI_OUTPUT_FORMATS, + readCliOutputArguments, +} from "../cliOutput.js"; +import { PRODUCT_IDENTITY } from "../identity.js"; +import { formatCliOutput } from "./cliOutputFormatter.js"; +import { + commandSchemaDocument, + formatLlmsFull, + formatLlmsIndex, + llmsFullManifest, + llmsIndexManifest, +} from "./commandManifests.js"; +import { cliCommands, type CliCommandEntry } from "./commandRegistry.js"; +import { suggestCommand } from "./commandSuggestion.js"; +import { + formatCommandHelp, + formatCommandListHelp, + type HelpCommandRow, +} from "./help.js"; +import { MCP_SUBCOMMANDS } from "./mcpBuiltinCommands.js"; +import type { CliInstance } from "./types.js"; + +/** The root page's description of REA. */ +export const CLI_DESCRIPTION = + "Reverse engineer anything from your terminal or agent."; + +/** Global options REA defines beyond the standard output controls. */ +export const CLI_CUSTOM_GLOBAL_OPTIONS = z.object({ + timings: z + .boolean() + .default(false) + .describe("Write measured command timing to stderr."), +}); + +export const MCP_GROUP_DESCRIPTION = "Register as MCP server"; +export const COMPLETIONS_DESCRIPTION = "Generate shell completion script"; + +/** Shells in the order the completions page lists them. */ +const HELP_SHELLS = ["bash", "fish", "nushell", "zsh"] as const; + +const completionsHint = (name: string): string => { + const rows = [ + ["bash", `eval "$(${name} completions bash)"`, "# add to ~/.bashrc"], + [ + "fish", + `${name} completions fish | source`, + "# add to ~/.config/fish/config.fish", + ], + ["nushell", `see \`${name} completions nushell\``, "# add to config.nu"], + ["zsh", `eval "$(${name} completions zsh)"`, "# add to ~/.zshrc"], + ] as const; + const shellWidth = Math.max(...rows.map(([shell]) => shell.length)); + const commandWidth = Math.max(...rows.map(([, command]) => command.length)); + return `Setup:\n${rows + .map( + ([shell, command, comment]) => + ` ${shell.padEnd(shellWidth)} ${command.padEnd(commandWidth)} ${comment}`, + ) + .join("\n")}`; +}; + +/** The global options block of a page for a command that renders results. */ +const commandGlobalOptions = { + formats: CLI_OUTPUT_FORMATS, + custom: CLI_CUSTOM_GLOBAL_OPTIONS, +}; + +const rootPage = (cli: CliInstance): string => + formatCommandListHelp(cli.name, { + version: PRODUCT_IDENTITY.packageVersion, + description: CLI_DESCRIPTION, + commands: cliCommands(cli) + .map(({ name, definition }): HelpCommandRow => ({ + name, + description: definition.description, + })) + .sort((left, right) => left.name.localeCompare(right.name)), + globalOptions: { + ...commandGlobalOptions, + root: { + integrations: [ + { name: "completions", description: COMPLETIONS_DESCRIPTION }, + { + name: "mcp", + description: `${MCP_GROUP_DESCRIPTION} (${[...MCP_SUBCOMMANDS.keys()].join(", ")})`, + }, + ], + }, + }, + }); + +/** The position of an integration command: first, or after the CLI's own name. */ +const integrationIndex = ( + command: readonly string[], + name: string, + integration: string, +): number => + command[0] === integration + ? 0 + : command[0] === name && command[1] === integration + ? 1 + : -1; + +/** A document REA writes instead of running a command, and the status it ends with. */ +interface DiscoveryAnswer { + readonly text: string; + readonly exitCode: number; +} + +const answer = (text: string, exitCode = 0): DiscoveryAnswer => ({ + text: text.endsWith("\n") ? text : `${text}\n`, + exitCode, +}); + +const sortedCommands = (cli: CliInstance): readonly CliCommandEntry[] => + [...cliCommands(cli)].sort((left, right) => + left.name.localeCompare(right.name), + ); + +/** + * `--llms` and `--llms-full`: Markdown unless a structured format is chosen. + * A known command first scopes the manifest to that command. + */ +const llmsAnswer = ( + cli: CliInstance, + global: CliGlobalArguments, + full: boolean, +): DiscoveryAnswer => { + const { format, formatExplicit } = readCliOutputArguments(global); + const scoped = cliCommands(cli).find( + ({ name }) => name === global.command[0], + ); + const commands = scoped === undefined ? sortedCommands(cli) : [scoped]; + if (!formatExplicit || format === "md") + return answer( + full + ? formatLlmsFull(cli.name, commands) + : formatLlmsIndex(cli.name, commands, CLI_DESCRIPTION), + ); + return answer( + formatCliOutput( + full + ? llmsFullManifest(commands, CLI_CUSTOM_GLOBAL_OPTIONS) + : llmsIndexManifest(commands, CLI_CUSTOM_GLOBAL_OPTIONS), + format, + ), + ); +}; + +/** + * `--schema` for a command, or the error for an unknown one. Markdown stays + * with the dispatcher: it renders the document without Markdown escaping, + * unlike REA's renderer, and that difference awaits a decision (#11654). + */ +const schemaAnswer = ( + cli: CliInstance, + global: CliGlobalArguments, +): DiscoveryAnswer | undefined => { + const name = global.command[0]!; + const entry = cliCommands(cli).find((command) => command.name === name); + if (entry === undefined) { + const suggestion = suggestCommand( + name, + cliCommands(cli).map((command) => command.name), + ); + return answer( + `Error: '${name}' is not a command for '${cli.name}'.${suggestion === undefined ? "" : ` Did you mean '${suggestion}'?`}`, + 1, + ); + } + const { format, formatExplicit } = readCliOutputArguments(global); + if (formatExplicit && format === "md") return undefined; + return answer( + formatCliOutput( + commandSchemaDocument(entry, CLI_CUSTOM_GLOBAL_OPTIONS), + formatExplicit ? format : "toon", + ), + ); +}; + +/** + * The document an invocation asks for instead of running a command, or + * undefined. Precedence: the update check, `--update` without help and + * `--mcp` stay with the dispatcher; the LLM manifests answer next; then the + * integrations (`completions` shows its page for help or without a shell, + * `mcp` shows its page without a subcommand); then `--version` without help; + * then the root page for no command; then a command's page for help (help + * after an unknown command shows the root page); then `--schema`. + */ +const discoveryAnswer = ( + cli: CliInstance, + global: CliGlobalArguments, +): DiscoveryAnswer | undefined => { + const { command, flags } = global; + const help = flags.has("--help") || flags.has("-h"); + if ( + flags.has("--incur-update-check") || + (flags.has("--update") && !help) || + flags.has("--mcp") + ) + return undefined; + if (flags.has("--llms") || flags.has("--llms-full")) + return llmsAnswer(cli, global, flags.has("--llms-full")); + const completions = integrationIndex(command, cli.name, "completions"); + if (completions >= 0) + return help || command[completions + 1] === undefined + ? answer( + formatCommandHelp(`${cli.name} completions`, { + description: COMPLETIONS_DESCRIPTION, + args: z.object({ + shell: z + .enum(HELP_SHELLS) + .describe("Shell to generate completions for"), + }), + hint: completionsHint(cli.name), + }), + ) + : undefined; + const mcp = integrationIndex(command, cli.name, "mcp"); + if (mcp >= 0) { + const subcommand = command[mcp + 1]; + if (subcommand === undefined) + return answer( + formatCommandListHelp(`${cli.name} mcp`, { + description: MCP_GROUP_DESCRIPTION, + commands: [...MCP_SUBCOMMANDS].map(([name, { description }]) => ({ + name, + description, + })), + globalOptions: { formats: CLI_DOCUMENT_OUTPUT_FORMATS }, + }), + ); + // `mcp add` renders its own page; an unknown subcommand is an error. + return help && subcommand === "doctor" + ? answer( + formatCommandHelp(`${cli.name} mcp doctor`, { + description: MCP_SUBCOMMANDS.get("doctor")!.description, + }), + ) + : undefined; + } + if (flags.has("--version") && !help) + return answer(PRODUCT_IDENTITY.packageVersion); + if (command.length === 0) return answer(rootPage(cli)); + if (help) { + const entry = cliCommands(cli).find(({ name }) => name === command[0]); + if (entry === undefined) return answer(rootPage(cli)); + const { definition } = entry; + return answer( + formatCommandHelp(`${cli.name} ${entry.name}`, { + description: definition.description, + args: definition.args, + options: definition.options, + alias: definition.alias, + globalOptions: commandGlobalOptions, + }), + ); + } + if (flags.has("--schema")) return schemaAnswer(cli, global); + return undefined; +}; + +type ServeOptions = NonNullable[1]>; + +/** + * Answer help, `--version`, `--schema` and the LLM manifests, reading the + * arguments as the command dispatcher receives them. Returns false when the + * invocation asks for something else. + */ +export const serveDiscovery = ( + cli: CliInstance, + arguments_: readonly string[], + options: ServeOptions, +): boolean => { + const result = discoveryAnswer(cli, parseCliGlobalArguments(arguments_)); + if (result === undefined) return false; + (options.stdout ?? ((text: string) => process.stdout.write(text)))( + result.text, + ); + if (result.exitCode !== 0) + (options.exit ?? ((code: number) => process.exit(code)))(result.exitCode); + return true; +}; diff --git a/src/cli/help.ts b/src/cli/help.ts index 1202ec0608..d3582739ae 100644 --- a/src/cli/help.ts +++ b/src/cli/help.ts @@ -3,20 +3,39 @@ import { z } from "zod"; import { declaredOptionType, optionFlagName } from "./optionFields.js"; /** - * REA's command help text. The layout is the one the CLI has always printed: - * a `name — description` title, a usage line, aligned option rows with type - * placeholders and shown defaults, an optional hint, then the global options the - * entry accepts. + * REA's help text. The layout is the one the CLI has always printed: a + * `name — description` title, a usage line, aligned argument and option rows + * with type placeholders and shown defaults, an optional hint, then the global + * options the entry accepts. */ +/** A named entry in a command list. */ +export interface HelpCommandRow { + readonly name: string; + readonly description?: string | undefined; +} + /** The global options block of an entry that accepts them. */ export interface GlobalOptionsHelp { /** The `--format` values this entry accepts, in display order. */ readonly formats: readonly string[]; + /** Global options REA defines beyond the standard ones, such as `--timings`. */ + readonly custom?: z.ZodObject | undefined; + /** + * The root page also lists the integration commands and the flags that + * apply only before a command (`--mcp`, `--update`, `--version`). + */ + readonly root?: + | { readonly integrations: readonly HelpCommandRow[] } + | undefined; } export interface CommandHelp { readonly description?: string | undefined; + /** Printed as `name@version` in the title. */ + readonly version?: string | undefined; + /** Positionals, in argv order. */ + readonly args?: z.ZodObject | undefined; readonly options?: z.ZodObject | undefined; /** Short alias by option key, such as `{ help: "h" }`. */ readonly alias?: Readonly> | undefined; @@ -92,8 +111,32 @@ const optionRows = ( }, ); -/** The global options every command entry accepts, sorted by flag. */ -const globalOptionRows = ({ formats }: GlobalOptionsHelp): Row[] => +/** A command list's rows, in the order given. */ +const commandRows = (commands: readonly HelpCommandRow[]): string[] => { + const width = Math.max(...commands.map((command) => command.name.length)); + return commands.map((command) => + command.description === undefined || command.description === "" + ? ` ${command.name}` + : ` ${command.name}${" ".repeat(width - command.name.length)} ${command.description}`, + ); +}; + +/** ``, `[optional]` and `` placeholders, in argv order. */ +const synopsis = (name: string, args: z.ZodObject | undefined): string => + [ + name, + ...Object.entries( + (args?.shape ?? {}) as Readonly>, + ).map(([key, field]) => { + const type = typeName(field); + const label = + (type.includes("|") ? type : key) + (type === "array" ? "..." : ""); + return field._zod.optout === "optional" ? `[${label}]` : `<${label}>`; + }), + ].join(" "); + +/** The global options an entry accepts, sorted by flag. */ +const globalOptionRows = ({ formats, root }: GlobalOptionsHelp): Row[] => [ { label: "--filter-output ", @@ -116,24 +159,68 @@ const globalOptionRows = ({ formats }: GlobalOptionsHelp): Row[] => description: "Skip first n tokens of output", }, { label: "--full-output", description: "Show full output envelope" }, + ...(root === undefined + ? [] + : [ + { label: "--mcp", description: "Start as MCP stdio server" }, + { label: "--update", description: "Update to latest version" }, + { label: "--version", description: "Show version" }, + ]), ].sort((left, right) => left.label.localeCompare(right.label)); +/** Integrations, custom global options and global options, in that order. */ +const globalOptionsLines = (help: GlobalOptionsHelp | undefined): string[] => { + if (help === undefined) return []; + const lines: string[] = []; + if (help.root !== undefined) + lines.push("", "Integrations:", ...commandRows(help.root.integrations)); + const custom = + help.custom === undefined ? [] : optionRows(help.custom, undefined); + if (custom.length > 0) + lines.push("", "Custom Global Options:", ...alignedRows(custom)); + lines.push("", "Global Options:", ...alignedRows(globalOptionRows(help))); + return lines; +}; + +const title = (name: string, help: CommandHelp): string => { + const heading = help.version === undefined ? name : `${name}@${help.version}`; + return help.description === undefined + ? heading + : `${heading} — ${help.description}`; +}; + /** Render one command's help, without a trailing newline. */ export const formatCommandHelp = (name: string, help: CommandHelp): string => { const lines = [ - help.description === undefined ? name : `${name} — ${help.description}`, + title(name, help), "", - `Usage: ${name}${help.options === undefined ? "" : " [options]"}`, + `Usage: ${synopsis(name, help.args)}${help.options === undefined ? "" : " [options]"}`, ]; + const args = Object.entries( + (help.args?.shape ?? {}) as Readonly>, + ).map(([key, field]) => ({ + label: key, + description: field.description ?? "", + })); + if (args.length > 0) lines.push("", "Arguments:", ...alignedRows(args)); const options = help.options === undefined ? [] : optionRows(help.options, help.alias); if (options.length > 0) lines.push("", "Options:", ...alignedRows(options)); if (help.hint !== undefined) lines.push("", help.hint); - if (help.globalOptions !== undefined) - lines.push( - "", - "Global Options:", - ...alignedRows(globalOptionRows(help.globalOptions)), - ); + lines.push(...globalOptionsLines(help.globalOptions)); + return lines.join("\n"); +}; + +/** Render a page that lists commands (the root or a group), without a trailing newline. */ +export const formatCommandListHelp = ( + name: string, + help: Pick & { + readonly commands: readonly HelpCommandRow[]; + }, +): string => { + const lines = [title(name, help), "", `Usage: ${name} `]; + if (help.commands.length > 0) + lines.push("", "Commands:", ...commandRows(help.commands)); + lines.push(...globalOptionsLines(help.globalOptions)); return lines.join("\n"); }; diff --git a/tests/boundary/cli/cliParityGoldens.test.ts b/tests/boundary/cli/cliParityGoldens.test.ts index 2ecf9b356c..8906e4f9e7 100644 --- a/tests/boundary/cli/cliParityGoldens.test.ts +++ b/tests/boundary/cli/cliParityGoldens.test.ts @@ -146,6 +146,11 @@ const CASES: readonly ParityCase[] = [ }, { name: "help-update", arguments: fixed("update", "--help") }, { name: "help-mcp", arguments: fixed("mcp", "--help") }, + { name: "help-mcp-without-subcommand", arguments: fixed("mcp", "--json") }, + { + name: "help-after-unknown-command", + arguments: fixed("no-such-command", "--help"), + }, { name: "help-mcp-add", arguments: fixed("mcp", "add", "--help") }, { name: "help-mcp-doctor", arguments: fixed("mcp", "doctor", "--help") }, { name: "help-completions", arguments: fixed("completions", "--help") }, @@ -158,7 +163,44 @@ const CASES: readonly ParityCase[] = [ name: "schema-command-json", arguments: fixed("inspect-byte-entropy", "--schema", "--format", "json"), }, + { + name: "schema-command-md", + arguments: fixed("inspect-byte-entropy", "--schema", "--format", "md"), + }, + { + name: "schema-unknown-command", + arguments: fixed("inspect-byte-entropi", "--schema"), + }, { name: "llms-command", arguments: fixed("inspect-byte-entropy", "--llms") }, + { + name: "llms-command-json", + arguments: fixed("inspect-byte-entropy", "--llms", "--format", "json"), + }, + // Which discovery document wins when several are asked for. + { + name: "discovery-llms-over-help", + arguments: fixed("inspect-byte-entropy", "--llms", "--help"), + }, + { + name: "discovery-llms-over-version", + arguments: fixed("inspect-byte-entropy", "--llms", "--version"), + }, + { + name: "discovery-llms-full-over-llms", + arguments: fixed("inspect-byte-entropy", "--llms", "--llms-full"), + }, + { + name: "discovery-version-over-schema", + arguments: fixed("inspect-byte-entropy", "--schema", "--version"), + }, + { + name: "discovery-help-over-schema", + arguments: fixed("inspect-byte-entropy", "--schema", "--help"), + }, + { + name: "llms-full-command-yaml", + arguments: fixed("inspect-byte-entropy", "--llms-full", "--format", "yaml"), + }, { name: "llms-full-command", arguments: fixed("inspect-byte-entropy", "--llms-full"), @@ -428,7 +470,10 @@ const render = ( ? JSON.stringify(argument) : argument, ); - const stdout = /^(?:terminal-)?help-root/u.test(testCase.name) + // The root page, whichever invocation printed it, opens with `rea@`. + const stdout = result.stdout.startsWith( + `rea@${PRODUCT_IDENTITY.packageVersion} `, + ) ? elideRootCommandRows(result.stdout) : result.stdout; return [ diff --git a/tests/fixtures/cli-parity/discovery-help-over-schema.txt b/tests/fixtures/cli-parity/discovery-help-over-schema.txt new file mode 100644 index 0000000000..4ed69e1dec --- /dev/null +++ b/tests/fixtures/cli-parity/discovery-help-over-schema.txt @@ -0,0 +1,31 @@ +$ rea inspect-byte-entropy --schema --help +exit: 0 +--- stdout +rea inspect-byte-entropy — Inspect file-wide and block byte entropy without executing the file + +Usage: rea inspect-byte-entropy [options] + +Arguments: + path Local file + +Options: + --block-size Power-of-two block size from 256 to 65536 bytes (default: 4096) + --offset Window start as a decimal file byte offset (default: 0) + --length Window length in bytes; omit to extend through EOF + +Custom Global Options: + --timings Write measured command timing to stderr. + +Global Options: + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output + +--- stderr + diff --git a/tests/fixtures/cli-parity/discovery-llms-full-over-llms.txt b/tests/fixtures/cli-parity/discovery-llms-full-over-llms.txt new file mode 100644 index 0000000000..f03dd0fa9a --- /dev/null +++ b/tests/fixtures/cli-parity/discovery-llms-full-over-llms.txt @@ -0,0 +1,23 @@ +$ rea inspect-byte-entropy --llms --llms-full +exit: 0 +--- stdout +# rea inspect-byte-entropy + +Inspect file-wide and block byte entropy without executing the file + +## Arguments + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | `string` | yes | Local file | + +## Options + +| Flag | Type | Default | Description | +|------|------|---------|-------------| +| `--blockSize` | `unknown` | `4096` | Power-of-two block size from 256 to 65536 bytes | +| `--offset` | `unknown` | `0` | Window start as a decimal file byte offset | +| `--length` | `unknown` | | Window length in bytes; omit to extend through EOF | + +--- stderr + diff --git a/tests/fixtures/cli-parity/discovery-llms-over-help.txt b/tests/fixtures/cli-parity/discovery-llms-over-help.txt new file mode 100644 index 0000000000..ddbddb929c --- /dev/null +++ b/tests/fixtures/cli-parity/discovery-llms-over-help.txt @@ -0,0 +1,15 @@ +$ rea inspect-byte-entropy --llms --help +exit: 0 +--- stdout +# rea + +Reverse engineer anything from your terminal or agent. + +| Command | Description | +|---------|-------------| +| `rea inspect-byte-entropy ` | Inspect file-wide and block byte entropy without executing the file | + +Run `rea --llms-full` for full manifest. Run `rea --schema` for argument details. + +--- stderr + diff --git a/tests/fixtures/cli-parity/discovery-llms-over-version.txt b/tests/fixtures/cli-parity/discovery-llms-over-version.txt new file mode 100644 index 0000000000..bfa37c48e4 --- /dev/null +++ b/tests/fixtures/cli-parity/discovery-llms-over-version.txt @@ -0,0 +1,15 @@ +$ rea inspect-byte-entropy --llms --version +exit: 0 +--- stdout +# rea + +Reverse engineer anything from your terminal or agent. + +| Command | Description | +|---------|-------------| +| `rea inspect-byte-entropy ` | Inspect file-wide and block byte entropy without executing the file | + +Run `rea --llms-full` for full manifest. Run `rea --schema` for argument details. + +--- stderr + diff --git a/tests/fixtures/cli-parity/discovery-version-over-schema.txt b/tests/fixtures/cli-parity/discovery-version-over-schema.txt new file mode 100644 index 0000000000..25fe88eb21 --- /dev/null +++ b/tests/fixtures/cli-parity/discovery-version-over-schema.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy --schema --version +exit: 0 +--- stdout + + +--- stderr + diff --git a/tests/fixtures/cli-parity/help-after-unknown-command.txt b/tests/fixtures/cli-parity/help-after-unknown-command.txt new file mode 100644 index 0000000000..d2b0433d4e --- /dev/null +++ b/tests/fixtures/cli-parity/help-after-unknown-command.txt @@ -0,0 +1,43 @@ +$ rea no-such-command --help +exit: 0 +--- stdout +rea@ — Reverse engineer anything from your terminal or agent. + +Usage: rea + +Commands: + address-to-file-offset Map one analysis address to a file offset; memory bytes may differ and ranges may not be contiguous + + build-reconstruction-obligation-ledger Generate a deterministic Evidence-backed reconstruction obligation ledger page + + decompile Read one part of an app as code. Supply at least one of the positional address or --procedure. Alternatively, use --file-offset alone. Equal positional and --procedure values are accepted; conflicts fail. With Ghidra, a space-qualified address such as ram:0x... avoids file-offset fallback; inspect-native-load-image reports the observed default space. + + inspect-byte-entropy Inspect file-wide and block byte entropy without executing the file + + setup Configure agent integrations and optional analysis providers + + xrefs List bounded, untyped references to an analyzed address. For typed incoming references, use inspect-native-instruction at the target address where supported. Supply at least one of the positional address or --address. Equal values are accepted; conflicts fail. + +Integrations: + completions Generate shell completion script + mcp Register as MCP server (add, doctor) + +Custom Global Options: + --timings Write measured command timing to stderr. + +Global Options: + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --mcp Start as MCP stdio server + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output + --update Update to latest version + --version Show version + +--- stderr + diff --git a/tests/fixtures/cli-parity/help-contract-command.txt b/tests/fixtures/cli-parity/help-contract-command.txt index 7cc2ed97d5..05550949b3 100644 --- a/tests/fixtures/cli-parity/help-contract-command.txt +++ b/tests/fixtures/cli-parity/help-contract-command.txt @@ -17,15 +17,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/help-contract-defaults.txt b/tests/fixtures/cli-parity/help-contract-defaults.txt index 0ae089a8e0..cfceb0d6e0 100644 --- a/tests/fixtures/cli-parity/help-contract-defaults.txt +++ b/tests/fixtures/cli-parity/help-contract-defaults.txt @@ -20,15 +20,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/help-contract-long-description.txt b/tests/fixtures/cli-parity/help-contract-long-description.txt index 3f97804213..be2557ff35 100644 --- a/tests/fixtures/cli-parity/help-contract-long-description.txt +++ b/tests/fixtures/cli-parity/help-contract-long-description.txt @@ -25,15 +25,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/help-contract-optional-positional.txt b/tests/fixtures/cli-parity/help-contract-optional-positional.txt index 4b4bb678bb..86f4815b7c 100644 --- a/tests/fixtures/cli-parity/help-contract-optional-positional.txt +++ b/tests/fixtures/cli-parity/help-contract-optional-positional.txt @@ -21,15 +21,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/help-hand-built-capture-process.txt b/tests/fixtures/cli-parity/help-hand-built-capture-process.txt index 9d68855017..3bbaee8719 100644 --- a/tests/fixtures/cli-parity/help-hand-built-capture-process.txt +++ b/tests/fixtures/cli-parity/help-hand-built-capture-process.txt @@ -12,15 +12,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/help-hand-built-doctor.txt b/tests/fixtures/cli-parity/help-hand-built-doctor.txt index 1d64a5006a..db83d64864 100644 --- a/tests/fixtures/cli-parity/help-hand-built-doctor.txt +++ b/tests/fixtures/cli-parity/help-hand-built-doctor.txt @@ -15,15 +15,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/help-hand-built-environment-build.txt b/tests/fixtures/cli-parity/help-hand-built-environment-build.txt index 4eaf96ee23..8f5169227b 100644 --- a/tests/fixtures/cli-parity/help-hand-built-environment-build.txt +++ b/tests/fixtures/cli-parity/help-hand-built-environment-build.txt @@ -21,15 +21,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/help-hand-built-guidance.txt b/tests/fixtures/cli-parity/help-hand-built-guidance.txt index ba3dcf3f41..b7c513fa91 100644 --- a/tests/fixtures/cli-parity/help-hand-built-guidance.txt +++ b/tests/fixtures/cli-parity/help-hand-built-guidance.txt @@ -16,15 +16,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/help-hand-built-setup.txt b/tests/fixtures/cli-parity/help-hand-built-setup.txt index aceecb9766..f17093d9e7 100644 --- a/tests/fixtures/cli-parity/help-hand-built-setup.txt +++ b/tests/fixtures/cli-parity/help-hand-built-setup.txt @@ -23,15 +23,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/help-mcp-without-subcommand.txt b/tests/fixtures/cli-parity/help-mcp-without-subcommand.txt new file mode 100644 index 0000000000..5dfb59ad1d --- /dev/null +++ b/tests/fixtures/cli-parity/help-mcp-without-subcommand.txt @@ -0,0 +1,24 @@ +$ rea mcp --json +exit: 0 +--- stdout +rea mcp — Register as MCP server + +Usage: rea mcp + +Commands: + add Register as MCP server + doctor Validate MCP server startup and tool listing + +Global Options: + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output + +--- stderr + diff --git a/tests/fixtures/cli-parity/help-root-bare.txt b/tests/fixtures/cli-parity/help-root-bare.txt index 6016e3ad9e..0b74f7de62 100644 --- a/tests/fixtures/cli-parity/help-root-bare.txt +++ b/tests/fixtures/cli-parity/help-root-bare.txt @@ -26,18 +26,18 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --mcp Start as MCP stdio server - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output - --update Update to latest version - --version Show version + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --mcp Start as MCP stdio server + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output + --update Update to latest version + --version Show version --- stderr diff --git a/tests/fixtures/cli-parity/help-root-short.txt b/tests/fixtures/cli-parity/help-root-short.txt index a9deec34b8..111ddf5ee8 100644 --- a/tests/fixtures/cli-parity/help-root-short.txt +++ b/tests/fixtures/cli-parity/help-root-short.txt @@ -26,18 +26,18 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --mcp Start as MCP stdio server - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output - --update Update to latest version - --version Show version + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --mcp Start as MCP stdio server + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output + --update Update to latest version + --version Show version --- stderr diff --git a/tests/fixtures/cli-parity/help-root-with-format.txt b/tests/fixtures/cli-parity/help-root-with-format.txt index ae5ad9f274..49e10edc11 100644 --- a/tests/fixtures/cli-parity/help-root-with-format.txt +++ b/tests/fixtures/cli-parity/help-root-with-format.txt @@ -26,18 +26,18 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --mcp Start as MCP stdio server - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output - --update Update to latest version - --version Show version + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --mcp Start as MCP stdio server + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output + --update Update to latest version + --version Show version --- stderr diff --git a/tests/fixtures/cli-parity/help-root.txt b/tests/fixtures/cli-parity/help-root.txt index 598d23e296..286e27fd6f 100644 --- a/tests/fixtures/cli-parity/help-root.txt +++ b/tests/fixtures/cli-parity/help-root.txt @@ -26,18 +26,18 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --mcp Start as MCP stdio server - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output - --update Update to latest version - --version Show version + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --mcp Start as MCP stdio server + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output + --update Update to latest version + --version Show version --- stderr diff --git a/tests/fixtures/cli-parity/help-update.txt b/tests/fixtures/cli-parity/help-update.txt index 4545ab46a7..e443a592f9 100644 --- a/tests/fixtures/cli-parity/help-update.txt +++ b/tests/fixtures/cli-parity/help-update.txt @@ -9,15 +9,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/llms-command-json.txt b/tests/fixtures/cli-parity/llms-command-json.txt new file mode 100644 index 0000000000..6e28fcd57b --- /dev/null +++ b/tests/fixtures/cli-parity/llms-command-json.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy --llms --format json +exit: 0 +--- stdout +{"version":"incur.v1","commands":[{"name":"inspect-byte-entropy","description":"Inspect file-wide and block byte entropy without executing the file"}],"globals":{"type":"object","properties":{"timings":{"default":false,"description":"Write measured command timing to stderr.","type":"boolean"}},"required":["timings"],"additionalProperties":false}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/llms-full-command-yaml.txt b/tests/fixtures/cli-parity/llms-full-command-yaml.txt new file mode 100644 index 0000000000..88825e15dd --- /dev/null +++ b/tests/fixtures/cli-parity/llms-full-command-yaml.txt @@ -0,0 +1,62 @@ +$ rea inspect-byte-entropy --llms-full --format yaml +exit: 0 +--- stdout +version: incur.v1 +commands: + - name: inspect-byte-entropy + description: Inspect file-wide and block byte entropy without executing the file + schema: + args: + type: object + properties: + path: + type: string + minLength: 1 + pattern: ^[^\x00]*$ + description: Local file + required: + - path + additionalProperties: false + options: + type: object + properties: + blockSize: + default: 4096 + anyOf: + - type: integer + minimum: 256 + maximum: 65536 + - type: string + pattern: ^[0-9]+$ + description: Power-of-two block size from 256 to 65536 bytes + offset: + default: 0 + anyOf: + - type: integer + minimum: 0 + maximum: 9007199254740991 + - type: string + pattern: ^[0-9]+$ + description: Window start as a decimal file byte offset + length: + anyOf: + - type: integer + minimum: 0 + maximum: 9007199254740991 + - type: string + pattern: ^[0-9]+$ + description: Window length in bytes; omit to extend through EOF + additionalProperties: false +globals: + type: object + properties: + timings: + default: false + description: Write measured command timing to stderr. + type: boolean + required: + - timings + additionalProperties: false + +--- stderr + diff --git a/tests/fixtures/cli-parity/schema-command-md.txt b/tests/fixtures/cli-parity/schema-command-md.txt new file mode 100644 index 0000000000..79e622e503 --- /dev/null +++ b/tests/fixtures/cli-parity/schema-command-md.txt @@ -0,0 +1,95 @@ +$ rea inspect-byte-entropy --schema --format md +exit: 0 +--- stdout +## args.type + +object + +## args.properties.path + +| Key | Value | +|-------------|------------| +| type | string | +| minLength | 1 | +| pattern | ^[^\x00]*$ | +| description | Local file | + +## args.required + +path + +## args.additionalProperties + +false + +## options.type + +object + +## options.properties.blockSize.default + +4096 + +## options.properties.blockSize.anyOf + +| type | minimum | maximum | pattern | +|---------|---------|---------|----------| +| integer | 256 | 65536 | | +| string | | | ^[0-9]+$ | + +## options.properties.blockSize.description + +Power-of-two block size from 256 to 65536 bytes + +## options.properties.offset.default + +0 + +## options.properties.offset.anyOf + +| type | minimum | maximum | pattern | +|---------|---------|------------------|----------| +| integer | 0 | 9007199254740991 | | +| string | | | ^[0-9]+$ | + +## options.properties.offset.description + +Window start as a decimal file byte offset + +## options.properties.length.anyOf + +| type | minimum | maximum | pattern | +|---------|---------|------------------|----------| +| integer | 0 | 9007199254740991 | | +| string | | | ^[0-9]+$ | + +## options.properties.length.description + +Window length in bytes; omit to extend through EOF + +## options.additionalProperties + +false + +## globals.type + +object + +## globals.properties.timings + +| Key | Value | +|-------------|------------------------------------------| +| default | false | +| description | Write measured command timing to stderr. | +| type | boolean | + +## globals.required + +timings + +## globals.additionalProperties + +false + +--- stderr + diff --git a/tests/fixtures/cli-parity/schema-unknown-command.txt b/tests/fixtures/cli-parity/schema-unknown-command.txt new file mode 100644 index 0000000000..00eea6cf2f --- /dev/null +++ b/tests/fixtures/cli-parity/schema-unknown-command.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropi --schema +exit: 1 +--- stdout +Error: 'inspect-byte-entropi' is not a command for 'rea'. Did you mean 'inspect-byte-entropy'? + +--- stderr + diff --git a/tests/fixtures/cli-parity/terminal-help-command.txt b/tests/fixtures/cli-parity/terminal-help-command.txt index 49025f0b2f..713e4ba748 100644 --- a/tests/fixtures/cli-parity/terminal-help-command.txt +++ b/tests/fixtures/cli-parity/terminal-help-command.txt @@ -17,15 +17,15 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output --- stderr diff --git a/tests/fixtures/cli-parity/terminal-help-root-bare.txt b/tests/fixtures/cli-parity/terminal-help-root-bare.txt index 35c33f6a3e..2f12fb7889 100644 --- a/tests/fixtures/cli-parity/terminal-help-root-bare.txt +++ b/tests/fixtures/cli-parity/terminal-help-root-bare.txt @@ -26,18 +26,18 @@ Custom Global Options: --timings Write measured command timing to stderr. Global Options: - --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) - --format Output format - --full-output Show full output envelope - --help Show help - --llms, --llms-full Print LLM-readable manifest - --mcp Start as MCP stdio server - --schema Show JSON Schema for command - --token-count Print token count of output (instead of output) - --token-limit Limit output to n tokens - --token-offset Skip first n tokens of output - --update Update to latest version - --version Show version + --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3]) + --format Output format + --full-output Show full output envelope + --help Show help + --llms, --llms-full Print LLM-readable manifest + --mcp Start as MCP stdio server + --schema Show JSON Schema for command + --token-count Print token count of output (instead of output) + --token-limit Limit output to n tokens + --token-offset Skip first n tokens of output + --update Update to latest version + --version Show version --- stderr