From f39e5e80db20568f92c3d8e6f40f7f61802be226 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:52:17 +0800 Subject: [PATCH] refactor(cli): own shell completion behind new CLI parity goldens (#11662) * test(cli): capture CLI parity goldens before replacing incur * test(cli): cover completion groups, aliases and hand-built enums in the parity goldens * refactor(cli): own the shell completion protocol instead of incur's Completions (#11665) * test(cli): keep root help goldens stable for longer names and let recording add cases --- src/cli/bashCompletionRegistration.ts | 38 -- src/cli/completionProtocol.ts | 311 ++++++++++++ src/cli/completions.ts | 29 +- tests/boundary/cli/cliParityGoldens.test.ts | 444 ++++++++++++++++++ ...ion.test.ts => completionProtocol.test.ts} | 2 +- .../complete-bash-after-separator.txt | 6 + .../complete-bash-aliased-option-value.txt | 6 + ...omplete-bash-boolean-before-subcommand.txt | 6 + .../complete-bash-command-prefix.txt | 6 + .../complete-bash-completion-shells.txt | 6 + .../cli-parity/complete-bash-enum-values.txt | 6 + .../complete-bash-format-values.txt | 6 + .../complete-bash-global-prefix.txt | 6 + .../cli-parity/complete-bash-group-prefix.txt | 6 + .../complete-bash-hand-built-enum-values.txt | 6 + .../complete-bash-mcp-subcommands.txt | 6 + .../complete-bash-option-prefix.txt | 6 + .../complete-bash-short-aliases.txt | 6 + .../complete-fish-described-commands.txt | 9 + .../complete-nushell-described-commands.txt | 6 + .../complete-zsh-described-commands.txt | 9 + .../cli-parity/complete-zsh-format-values.txt | 12 + .../complete-zsh-mcp-doctor-options.txt | 10 + .../fixtures/cli-parity/completions-bash.txt | 39 ++ .../fixtures/cli-parity/completions-fish.txt | 8 + .../cli-parity/completions-nushell.txt | 11 + .../cli-parity/completions-unknown-shell.txt | 7 + tests/fixtures/cli-parity/completions-zsh.txt | 18 + .../error-delimited-without-columns.txt | 7 + .../cli-parity/error-empty-command.txt | 14 + .../cli-parity/error-extra-positional.txt | 8 + .../cli-parity/error-format-invalid.txt | 7 + .../cli-parity/error-format-missing.txt | 7 + .../cli-parity/error-invalid-number.txt | 10 + .../cli-parity/error-jsonl-not-collection.txt | 7 + .../cli-parity/error-missing-flag-value.txt | 8 + .../cli-parity/error-missing-positional.txt | 10 + .../error-refined-number-full-output.txt | 7 + .../cli-parity/error-refined-number-json.txt | 7 + .../cli-parity/error-refined-number-md.txt | 20 + .../cli-parity/error-refined-number.txt | 11 + .../error-sensitive-output-value.txt | 7 + .../cli-parity/error-sensitive-positional.txt | 8 + tests/fixtures/cli-parity/error-separator.txt | 8 + .../cli-parity/error-unknown-command.txt | 14 + .../cli-parity/error-unknown-flag.txt | 8 + .../error-unknown-mcp-subcommand.txt | 12 + .../cli-parity/help-completions-bare.txt | 20 + .../fixtures/cli-parity/help-completions.txt | 20 + .../cli-parity/help-contract-command.txt | 31 ++ .../cli-parity/help-contract-defaults.txt | 34 ++ .../help-contract-long-description.txt | 39 ++ .../help-contract-optional-positional.txt | 35 ++ .../help-hand-built-capture-process.txt | 26 + .../cli-parity/help-hand-built-doctor.txt | 29 ++ .../help-hand-built-environment-build.txt | 35 ++ .../cli-parity/help-hand-built-guidance.txt | 30 ++ .../cli-parity/help-hand-built-setup.txt | 37 ++ tests/fixtures/cli-parity/help-mcp-add.txt | 27 ++ tests/fixtures/cli-parity/help-mcp-doctor.txt | 17 + tests/fixtures/cli-parity/help-mcp.txt | 24 + tests/fixtures/cli-parity/help-root-bare.txt | 43 ++ tests/fixtures/cli-parity/help-root-short.txt | 43 ++ .../cli-parity/help-root-with-format.txt | 43 ++ tests/fixtures/cli-parity/help-root.txt | 43 ++ tests/fixtures/cli-parity/help-update.txt | 23 + tests/fixtures/cli-parity/llms-command.txt | 15 + .../fixtures/cli-parity/llms-full-command.txt | 23 + tests/fixtures/cli-parity/output-csv.txt | 9 + .../cli-parity/output-full-output-json.txt | 7 + .../cli-parity/output-full-output.txt | 15 + .../cli-parity/output-json-equals.txt | 7 + .../cli-parity/output-json-switch.txt | 7 + tests/fixtures/cli-parity/output-json.txt | 7 + tests/fixtures/cli-parity/output-md.txt | 25 + tests/fixtures/cli-parity/output-timings.txt | 11 + .../cli-parity/output-token-count.txt | 7 + .../cli-parity/output-token-limit.txt | 8 + .../cli-parity/output-token-offset.txt | 9 + tests/fixtures/cli-parity/output-toon.txt | 15 + tests/fixtures/cli-parity/output-tsv.txt | 9 + tests/fixtures/cli-parity/output-yaml.txt | 18 + .../cli-parity/schema-command-json.txt | 7 + tests/fixtures/cli-parity/schema-command.txt | 55 +++ .../cli-parity/version-after-command.txt | 7 + tests/fixtures/cli-parity/version.txt | 7 + 86 files changed, 2027 insertions(+), 51 deletions(-) delete mode 100644 src/cli/bashCompletionRegistration.ts create mode 100644 src/cli/completionProtocol.ts create mode 100644 tests/boundary/cli/cliParityGoldens.test.ts rename tests/boundary/cli/{bashCompletionRegistration.test.ts => completionProtocol.test.ts} (95%) create mode 100644 tests/fixtures/cli-parity/complete-bash-after-separator.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-aliased-option-value.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-boolean-before-subcommand.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-command-prefix.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-completion-shells.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-enum-values.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-format-values.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-global-prefix.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-group-prefix.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-hand-built-enum-values.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-mcp-subcommands.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-option-prefix.txt create mode 100644 tests/fixtures/cli-parity/complete-bash-short-aliases.txt create mode 100644 tests/fixtures/cli-parity/complete-fish-described-commands.txt create mode 100644 tests/fixtures/cli-parity/complete-nushell-described-commands.txt create mode 100644 tests/fixtures/cli-parity/complete-zsh-described-commands.txt create mode 100644 tests/fixtures/cli-parity/complete-zsh-format-values.txt create mode 100644 tests/fixtures/cli-parity/complete-zsh-mcp-doctor-options.txt create mode 100644 tests/fixtures/cli-parity/completions-bash.txt create mode 100644 tests/fixtures/cli-parity/completions-fish.txt create mode 100644 tests/fixtures/cli-parity/completions-nushell.txt create mode 100644 tests/fixtures/cli-parity/completions-unknown-shell.txt create mode 100644 tests/fixtures/cli-parity/completions-zsh.txt create mode 100644 tests/fixtures/cli-parity/error-delimited-without-columns.txt create mode 100644 tests/fixtures/cli-parity/error-empty-command.txt create mode 100644 tests/fixtures/cli-parity/error-extra-positional.txt create mode 100644 tests/fixtures/cli-parity/error-format-invalid.txt create mode 100644 tests/fixtures/cli-parity/error-format-missing.txt create mode 100644 tests/fixtures/cli-parity/error-invalid-number.txt create mode 100644 tests/fixtures/cli-parity/error-jsonl-not-collection.txt create mode 100644 tests/fixtures/cli-parity/error-missing-flag-value.txt create mode 100644 tests/fixtures/cli-parity/error-missing-positional.txt create mode 100644 tests/fixtures/cli-parity/error-refined-number-full-output.txt create mode 100644 tests/fixtures/cli-parity/error-refined-number-json.txt create mode 100644 tests/fixtures/cli-parity/error-refined-number-md.txt create mode 100644 tests/fixtures/cli-parity/error-refined-number.txt create mode 100644 tests/fixtures/cli-parity/error-sensitive-output-value.txt create mode 100644 tests/fixtures/cli-parity/error-sensitive-positional.txt create mode 100644 tests/fixtures/cli-parity/error-separator.txt create mode 100644 tests/fixtures/cli-parity/error-unknown-command.txt create mode 100644 tests/fixtures/cli-parity/error-unknown-flag.txt create mode 100644 tests/fixtures/cli-parity/error-unknown-mcp-subcommand.txt create mode 100644 tests/fixtures/cli-parity/help-completions-bare.txt create mode 100644 tests/fixtures/cli-parity/help-completions.txt create mode 100644 tests/fixtures/cli-parity/help-contract-command.txt create mode 100644 tests/fixtures/cli-parity/help-contract-defaults.txt create mode 100644 tests/fixtures/cli-parity/help-contract-long-description.txt create mode 100644 tests/fixtures/cli-parity/help-contract-optional-positional.txt create mode 100644 tests/fixtures/cli-parity/help-hand-built-capture-process.txt create mode 100644 tests/fixtures/cli-parity/help-hand-built-doctor.txt create mode 100644 tests/fixtures/cli-parity/help-hand-built-environment-build.txt create mode 100644 tests/fixtures/cli-parity/help-hand-built-guidance.txt create mode 100644 tests/fixtures/cli-parity/help-hand-built-setup.txt create mode 100644 tests/fixtures/cli-parity/help-mcp-add.txt create mode 100644 tests/fixtures/cli-parity/help-mcp-doctor.txt create mode 100644 tests/fixtures/cli-parity/help-mcp.txt create mode 100644 tests/fixtures/cli-parity/help-root-bare.txt create mode 100644 tests/fixtures/cli-parity/help-root-short.txt create mode 100644 tests/fixtures/cli-parity/help-root-with-format.txt create mode 100644 tests/fixtures/cli-parity/help-root.txt create mode 100644 tests/fixtures/cli-parity/help-update.txt create mode 100644 tests/fixtures/cli-parity/llms-command.txt create mode 100644 tests/fixtures/cli-parity/llms-full-command.txt create mode 100644 tests/fixtures/cli-parity/output-csv.txt create mode 100644 tests/fixtures/cli-parity/output-full-output-json.txt create mode 100644 tests/fixtures/cli-parity/output-full-output.txt create mode 100644 tests/fixtures/cli-parity/output-json-equals.txt create mode 100644 tests/fixtures/cli-parity/output-json-switch.txt create mode 100644 tests/fixtures/cli-parity/output-json.txt create mode 100644 tests/fixtures/cli-parity/output-md.txt create mode 100644 tests/fixtures/cli-parity/output-timings.txt create mode 100644 tests/fixtures/cli-parity/output-token-count.txt create mode 100644 tests/fixtures/cli-parity/output-token-limit.txt create mode 100644 tests/fixtures/cli-parity/output-token-offset.txt create mode 100644 tests/fixtures/cli-parity/output-toon.txt create mode 100644 tests/fixtures/cli-parity/output-tsv.txt create mode 100644 tests/fixtures/cli-parity/output-yaml.txt create mode 100644 tests/fixtures/cli-parity/schema-command-json.txt create mode 100644 tests/fixtures/cli-parity/schema-command.txt create mode 100644 tests/fixtures/cli-parity/version-after-command.txt create mode 100644 tests/fixtures/cli-parity/version.txt diff --git a/src/cli/bashCompletionRegistration.ts b/src/cli/bashCompletionRegistration.ts deleted file mode 100644 index 327b82226f..0000000000 --- a/src/cli/bashCompletionRegistration.ts +++ /dev/null @@ -1,38 +0,0 @@ -/** Register Incur's dynamic Bash protocol, including macOS system Bash 3.2. */ -export const bashCompletionScript = (name: string): string => { - const id = name.replace(/[^a-zA-Z0-9_]/gu, "_"); - const command = `'${name.replaceAll("'", "'\\''")}'`; - return `_incur_complete_${id}() { - local IFS=$'\\013' - local _COMPLETE_INDEX=\${COMP_CWORD} - local _completions _output - if ! _output=$( - export COMPLETE="bash" - export _COMPLETE_INDEX="$_COMPLETE_INDEX" - ${command} -- "\${COMP_WORDS[@]}" - ); then - unset COMPREPLY - return - fi - # Split the protocol records without expanding pathname patterns. - read -r -d '' -a _completions < <(printf '%s\\0' "$_output") - local _nospace=false - local _nospace_marker=$'\\001' - local _c - COMPREPLY=() - for _c in "\${_completions[@]}"; do - if [[ "$_c" == *"$_nospace_marker" ]]; then - _nospace=true - COMPREPLY+=("\${_c%"$_nospace_marker"}") - else - COMPREPLY+=("$_c") - fi - done - if [[ $_nospace == true ]] && type compopt >/dev/null 2>&1; then - compopt -o nospace - fi - return 0 -} -complete -o default -o bashdefault -o nosort -F _incur_complete_${id} ${command} 2>/dev/null || - complete -o default -o bashdefault -F _incur_complete_${id} ${command}`; -}; diff --git a/src/cli/completionProtocol.ts b/src/cli/completionProtocol.ts new file mode 100644 index 0000000000..a131ea5f06 --- /dev/null +++ b/src/cli/completionProtocol.ts @@ -0,0 +1,311 @@ +import { z } from "zod"; + +/** + * REA's shell completion protocol: the hook script each shell sources, the + * candidates for the words before the cursor, and their per-shell encoding. + * A hook calls back into the binary as `COMPLETE= rea -- `. + * Function names keep the `_incur_complete_` prefix so hooks that users + * already installed keep working. + */ + +/** Shells with a completion hook. */ +export type CompletionShell = "bash" | "zsh" | "fish" | "nushell"; + +/** One node of the command tree that completion walks. */ +export interface CompletionCommand { + readonly description?: string | undefined; + readonly options?: z.ZodObject | undefined; + /** Short alias by option key, such as `{ yes: "y" }`. */ + readonly alias?: Readonly> | undefined; + /** A group selects a nested command map instead of running. */ + readonly _group?: true | undefined; + readonly commands?: ReadonlyMap | undefined; + /** A group's own options, used while the group is the active scope. */ + readonly root?: CompletionCommand | undefined; + /** An alias entry names its canonical sibling in `target`. */ + readonly _alias?: true | undefined; + readonly target?: string | undefined; +} + +/** Options that apply to every command in the active scope. */ +export interface CompletionGlobals { + readonly schema: z.ZodObject; + readonly alias?: Readonly> | undefined; +} + +export interface CompletionCandidate { + readonly value: string; + readonly description?: string | undefined; + /** A group keeps the cursor on the word so a subcommand can follow. */ + readonly noSpace?: true | undefined; +} + +const identifier = (name: string): string => + name.replace(/[^a-zA-Z0-9_]/gu, "_"); + +/** Register the dynamic Bash protocol, including macOS system Bash 3.2. */ +export const bashCompletionScript = (name: string): string => { + const id = identifier(name); + const command = `'${name.replaceAll("'", "'\\''")}'`; + return `_incur_complete_${id}() { + local IFS=$'\\013' + local _COMPLETE_INDEX=\${COMP_CWORD} + local _completions _output + if ! _output=$( + export COMPLETE="bash" + export _COMPLETE_INDEX="$_COMPLETE_INDEX" + ${command} -- "\${COMP_WORDS[@]}" + ); then + unset COMPREPLY + return + fi + # Split the protocol records without expanding pathname patterns. + read -r -d '' -a _completions < <(printf '%s\\0' "$_output") + local _nospace=false + local _nospace_marker=$'\\001' + local _c + COMPREPLY=() + for _c in "\${_completions[@]}"; do + if [[ "$_c" == *"$_nospace_marker" ]]; then + _nospace=true + COMPREPLY+=("\${_c%"$_nospace_marker"}") + else + COMPREPLY+=("$_c") + fi + done + if [[ $_nospace == true ]] && type compopt >/dev/null 2>&1; then + compopt -o nospace + fi + return 0 +} +complete -o default -o bashdefault -o nosort -F _incur_complete_${id} ${command} 2>/dev/null || + complete -o default -o bashdefault -F _incur_complete_${id} ${command}`; +}; + +const zshCompletionScript = (name: string): string => { + const id = identifier(name); + return `#compdef ${name} +_incur_complete_${id}() { + local completions=("\${(@f)$( + export _COMPLETE_INDEX=$(( CURRENT - 1 )) + export COMPLETE="zsh" + "${name}" -- "\${words[@]}" 2>/dev/null + )}") + if [[ -n $completions ]]; then + _describe 'values' completions -S '' + fi +} +compdef _incur_complete_${id} ${name}`; +}; + +const fishCompletionScript = (name: string): string => + `complete --keep-order --exclusive --command ${name} \\ + --arguments "(COMPLETE=fish ${name} -- (commandline --current-process --tokenize --cut-at-cursor) (commandline --current-token))"`; + +const nushellCompletionScript = (name: string): string => { + const id = identifier(name); + return `# External completer for ${name} +# Add to $env.config.completions.external.completer or use in a dispatch completer. +let _incur_complete_${id} = {|spans| + COMPLETE=nushell ${name} -- ...$spans | from json +}`; +}; + +/** The hook script a shell evaluates to register completion for `name`. */ +export const completionScript = ( + shell: CompletionShell, + name: string, +): string => { + switch (shell) { + case "bash": + return bashCompletionScript(name); + case "zsh": + return zshCompletionScript(name); + case "fish": + return fishCompletionScript(name); + case "nushell": + return nushellCompletionScript(name); + } +}; + +const kebab = (key: string): string => + key.replace(/[A-Z]/gu, (character) => `-${character.toLowerCase()}`); + +/** Strip wrappers (optional, default, nullable, ...) to the declared value type. */ +const declaredType = (field: z.ZodType): z.ZodType => { + let current = field; + for ( + let inner = innerType(current); + inner !== undefined; + inner = innerType(current) + ) + current = inner; + return current; +}; + +const innerType = (field: z.ZodType): z.ZodType | undefined => { + const inner: unknown = Reflect.get(field._zod.def, "innerType"); + return inner instanceof z.ZodType ? inner : undefined; +}; + +const isFlagOption = (field: z.ZodType): boolean => + field.meta()?.count === true || declaredType(field) instanceof z.ZodBoolean; + +const enumValues = (field: z.ZodType): readonly string[] | undefined => { + const type = declaredType(field); + return type instanceof z.ZodEnum + ? type.options.map((value) => String(value)) + : undefined; +}; + +/** Resolve `--foo-bar`, `--fooBar` or a short alias to its option key. */ +const optionKey = ( + token: string, + options: z.ZodObject, + alias: Readonly> | undefined, +): string | undefined => { + const keys = Object.keys(options.shape); + if (token.startsWith("--")) { + const raw = token.slice(2); + return ( + keys.find((key) => kebab(key) === raw) ?? + (keys.includes(raw) ? raw : undefined) + ); + } + if (token.length === 2 && alias !== undefined) + return Object.entries(alias).find(([, short]) => short === token[1])?.[0]; + return undefined; +}; + +const flagCandidates = ( + current: string, + options: z.ZodObject, + alias: Readonly> | undefined, + candidates: CompletionCandidate[], +): void => { + const shape = options.shape as Record; + const add = (value: string, key: string) => { + if ( + value.startsWith(current) && + !candidates.some((candidate) => candidate.value === value) + ) + candidates.push({ value, description: shape[key]?.description }); + }; + for (const key of Object.keys(shape)) add(`--${kebab(key)}`, key); + for (const [key, short] of Object.entries(alias ?? {})) add(`-${short}`, key); +}; + +/** + * Value candidates for the option before the cursor. `undefined` means the + * previous word is not a value-taking option of this scope; an empty list + * means it takes a free-form value. + */ +const valueCandidates = ( + previous: string, + current: string, + options: z.ZodObject, + alias: Readonly> | undefined, +): CompletionCandidate[] | undefined => { + const key = optionKey(previous, options, alias); + if (key === undefined) return undefined; + const field = (options.shape as Record)[key]!; + const values = enumValues(field); + if (values !== undefined) + return values + .filter((value) => value.startsWith(current)) + .map((value) => ({ value })); + return isFlagOption(field) ? undefined : []; +}; + +/** + * Candidates for `words[index]`. Earlier words select the command scope; + * a dash-prefixed cursor word lists options, a word after a value-taking + * option lists its enum values, and otherwise subcommands are listed in + * registration order. + */ +export const completeWords = ( + commands: ReadonlyMap, + words: readonly string[], + index: number, + globals: CompletionGlobals, +): CompletionCandidate[] => { + const current = words[index] ?? ""; + let scope: { + commands: ReadonlyMap; + leaf: CompletionCommand | undefined; + } = { commands, leaf: undefined }; + for (const token of words.slice(0, index)) { + if (token.startsWith("-")) continue; + let entry = scope.commands.get(token); + if (entry?._alias === true && entry.target !== undefined) + entry = scope.commands.get(entry.target); + if (entry === undefined) continue; + if (entry._group === true && entry.commands !== undefined) + scope = { commands: entry.commands, leaf: entry.root }; + else { + scope = { commands: new Map(), leaf: entry }; + break; + } + } + const { leaf } = scope; + const candidates: CompletionCandidate[] = []; + if (current.startsWith("-")) { + if (leaf?.options !== undefined) + flagCandidates(current, leaf.options, leaf.alias, candidates); + flagCandidates(current, globals.schema, globals.alias, candidates); + return candidates; + } + const previous = index > 0 ? words[index - 1]! : ""; + if (previous.startsWith("-")) { + const values = + (leaf?.options === undefined + ? undefined + : valueCandidates(previous, current, leaf.options, leaf.alias)) ?? + valueCandidates(previous, current, globals.schema, globals.alias); + if (values !== undefined) return values; + } + for (const [name, entry] of scope.commands) + if (entry._alias !== true && name.startsWith(current)) + candidates.push({ + value: name, + description: entry.description, + ...(entry._group === true ? { noSpace: true as const } : {}), + }); + return candidates; +}; + +/** + * Encode candidates for one shell: bash `\v`-separated values (a group ends + * with `\x01`), zsh `value:description` lines (`:` escaped in values), fish + * `value\tdescription` lines, nushell a JSON array of records. + */ +export const formatCompletions = ( + shell: CompletionShell, + candidates: readonly CompletionCandidate[], +): string => { + switch (shell) { + case "bash": + return candidates + .map(({ value, noSpace }) => (noSpace ? `${value}\x01` : value)) + .join("\v"); + case "zsh": + return candidates + .map(({ value, description }) => { + const escaped = value.replaceAll(":", "\\:"); + return description ? `${escaped}:${description}` : escaped; + }) + .join("\n"); + case "fish": + return candidates + .map(({ value, description }) => + description ? `${value}\t${description}` : value, + ) + .join("\n"); + case "nushell": + return JSON.stringify( + candidates.map(({ value, description }) => + description ? { value, description } : { value }, + ), + ); + } +}; diff --git a/src/cli/completions.ts b/src/cli/completions.ts index b29e5d15be..837cf2a604 100644 --- a/src/cli/completions.ts +++ b/src/cli/completions.ts @@ -1,4 +1,4 @@ -import { Cli, Completions } from "incur"; +import { Cli } from "incur"; import { z } from "zod"; import { @@ -11,11 +11,15 @@ import { splitIncurBuiltinArguments, } from "../cliBuiltinArguments.js"; import { CLI_OUTPUT_FORMATS, parseCliOutputArguments } from "../cliOutput.js"; -import { bashCompletionScript } from "./bashCompletionRegistration.js"; +import { + completeWords, + completionScript, + formatCompletions, + type CompletionCommand, +} from "./completionProtocol.js"; import { MCP_SUBCOMMANDS } from "./mcpBuiltinCommands.js"; import { MCP_DOCTOR_ALIAS, MCP_DOCTOR_OPTIONS } from "../mcpDoctorOptions.js"; -type Commands = Parameters[0]; type CompletionCli = Parameters[0]; type ServeOptions = NonNullable[1]>; const ROOT_FLAGS = new Set(["--mcp", "--update", "--version"]); @@ -82,8 +86,12 @@ const standardGlobals = (root: boolean): z.ZodObject => ); /** Pinned Incur builtins are not exported in its registered command map. */ -const completionCommands = (cli: CompletionCli): Commands => { - const commands: Commands = new Map(Cli.toCommands.get(cli)); +const completionCommands = ( + cli: CompletionCli, +): ReadonlyMap => { + const commands = new Map( + Cli.toCommands.get(cli) as ReadonlyMap, + ); commands.set("mcp", { _group: true, description: "Register as MCP server", @@ -98,15 +106,13 @@ const completionCommands = (cli: CompletionCli): Commands => { return commands; }; -/** One tree owns command scope; the framework retains option/enum binding and shell formatting. */ +/** One tree owns command scope; completionProtocol owns candidates and shell encoding. */ export const createCliCompletions = ( cli: CompletionCli, environment: Readonly, ) => { const script = (shell: (typeof CLI_COMPLETION_SHELLS)[number]) => - shell === "bash" - ? bashCompletionScript(cli.name) - : Completions.register(shell, cli.name); + completionScript(shell, cli.name); return (arguments_: readonly string[], options: ServeOptions): boolean => { const write = options.stdout ?? ((text: string) => process.stdout.write(text)); @@ -130,9 +136,8 @@ export const createCliCompletions = ( if (before.includes("--")) return true; const input = [cli.name, ...before, words[index] ?? ""]; const doctor = before[0] === "mcp" && before[1] === "doctor"; - const candidates = Completions.complete( + const candidates = completeWords( completionCommands(cli), - undefined, input, input.length - 1, { @@ -143,7 +148,7 @@ export const createCliCompletions = ( alias: doctor ? MCP_DOCTOR_ALIAS : { help: "h" }, }, ); - const result = Completions.format(shell, candidates); + const result = formatCompletions(shell, candidates); if (result !== "") write(result); return true; } diff --git a/tests/boundary/cli/cliParityGoldens.test.ts b/tests/boundary/cli/cliParityGoldens.test.ts new file mode 100644 index 0000000000..3841fab663 --- /dev/null +++ b/tests/boundary/cli/cliParityGoldens.test.ts @@ -0,0 +1,444 @@ +import { mkdir, readdir, readFile, writeFile } from "node:fs/promises"; +import { afterAll, beforeAll, describe, expect } from "vitest"; + +import { PRODUCT_IDENTITY } from "../../../src/identity.js"; +import { cliTest } from "../../support/cli/cliFixture.js"; +import { + createTestWorkspace, + removeTestWorkspace, + type TestWorkspace, +} from "../../support/workspace/workspaceFixture.js"; + +/** + * Parity goldens for the CLI layer REA is moving off incur (#11654). Each case + * runs the compiled `rea` and compares its exit code, stdout and stderr with a + * reviewed file in tests/fixtures/cli-parity. A replacement of the parser, + * help, completions, formatter or dispatch must keep every file unchanged + * unless the owner approves the difference. + * + * Record after an approved change with + * `REA_RECORD_CLI_PARITY=1 npm run test:focused -- tests/boundary/cli/cliParityGoldens.test.ts` + * and review the diff. + */ + +const GOLDEN_DIRECTORY = new URL("../../fixtures/cli-parity/", import.meta.url); +const RECORD = process.env.REA_RECORD_CLI_PARITY === "1"; + +/** Bytes whose entropy, length and digest the output cases select. */ +const SAMPLE = Buffer.from("REA\x00\x01\x02parity-golden\n", "latin1"); +const SENSITIVE = "secret-literal"; + +interface ParityCase { + readonly name: string; + readonly arguments: (workspace: TestWorkspace) => readonly string[]; + /** Shell completion protocol requests. */ + readonly complete?: "bash" | "zsh" | "fish" | "nushell"; +} + +const sample = (workspace: TestWorkspace) => workspace.path("sample.bin"); +const entropy = ( + workspace: TestWorkspace, + ...rest: readonly string[] +): readonly string[] => ["inspect-byte-entropy", sample(workspace), ...rest]; +const SELECTION = [ + "--filter-output", + "normalized_result.window,normalized_result.blocks,normalized_result.thresholds", +] as const; +const BLOCKS = ["--filter-output", "normalized_result.blocks"] as const; +const WINDOW = ["--filter-output", "normalized_result.window"] as const; +const fixed = + (...arguments_: readonly string[]) => + (): readonly string[] => + arguments_; +const completion = ( + shell: NonNullable, + name: string, + ...words: readonly string[] +): ParityCase => ({ + name: `complete-${shell}-${name}`, + complete: shell, + arguments: fixed("--", "rea", ...words), +}); + +const CASES: readonly ParityCase[] = [ + // Help and manifests + { name: "help-root-bare", arguments: fixed() }, + { name: "help-root", arguments: fixed("--help") }, + { name: "help-root-short", arguments: fixed("-h") }, + { + name: "help-root-with-format", + arguments: fixed("--help", "--format", "json"), + }, + { name: "version", arguments: fixed("--version") }, + { + name: "version-after-command", + arguments: fixed("inspect-byte-entropy", "--version"), + }, + { + name: "help-contract-command", + arguments: fixed("inspect-byte-entropy", "--help"), + }, + { + name: "help-contract-optional-positional", + arguments: fixed("instructions", "--help"), + }, + { + name: "help-contract-long-description", + arguments: fixed("decompile", "--help"), + }, + { name: "help-contract-defaults", arguments: fixed("read-bytes", "--help") }, + { name: "help-hand-built-setup", arguments: fixed("setup", "--help") }, + { name: "help-hand-built-doctor", arguments: fixed("doctor", "--help") }, + { name: "help-hand-built-guidance", arguments: fixed("guidance", "--help") }, + { + name: "help-hand-built-capture-process", + arguments: fixed("capture-process", "--help"), + }, + { + name: "help-hand-built-environment-build", + arguments: fixed("environment-build", "--help"), + }, + { name: "help-update", arguments: fixed("update", "--help") }, + { name: "help-mcp", arguments: fixed("mcp", "--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") }, + { name: "help-completions-bare", arguments: fixed("completions") }, + { + name: "schema-command", + arguments: fixed("inspect-byte-entropy", "--schema"), + }, + { + name: "schema-command-json", + arguments: fixed("inspect-byte-entropy", "--schema", "--format", "json"), + }, + { name: "llms-command", arguments: fixed("inspect-byte-entropy", "--llms") }, + { + name: "llms-full-command", + arguments: fixed("inspect-byte-entropy", "--llms-full"), + }, + + // Completion scripts and the completion protocol + { name: "completions-bash", arguments: fixed("completions", "bash") }, + { name: "completions-zsh", arguments: fixed("completions", "zsh") }, + { name: "completions-fish", arguments: fixed("completions", "fish") }, + { name: "completions-nushell", arguments: fixed("completions", "nushell") }, + { + name: "completions-unknown-shell", + arguments: fixed("completions", "powershell"), + }, + completion("bash", "command-prefix", "inspect-byte-e"), + completion("bash", "option-prefix", "inspect-byte-entropy", "--bl"), + completion("bash", "mcp-subcommands", "mcp", ""), + completion("bash", "completion-shells", "completions", ""), + completion("bash", "format-values", "inspect-byte-entropy", "--format", ""), + completion("bash", "enum-values", "instructions", "--target-format", ""), + completion("bash", "global-prefix", "inspect-byte-entropy", "--tok"), + completion("bash", "group-prefix", "mc"), + completion("bash", "short-aliases", "setup", "-"), + completion( + "bash", + "hand-built-enum-values", + "setup", + "--tool-catalog-profile", + "", + ), + completion("bash", "aliased-option-value", "mcp", "add", "-c", ""), + completion( + "bash", + "boolean-before-subcommand", + "inspect-byte-entropy", + "--json", + "", + ), + completion("bash", "after-separator", "inspect-byte-entropy", "--", ""), + completion("zsh", "mcp-doctor-options", "mcp", "doctor", "--"), + completion("zsh", "described-commands", "inspect-pe-"), + completion("zsh", "format-values", "inspect-byte-entropy", "--format", ""), + completion("fish", "described-commands", "inspect-pe-"), + completion("nushell", "described-commands", "inspect-pe-"), + + // Command resolution and argument errors + { name: "error-unknown-command", arguments: fixed("no-such-command") }, + { name: "error-empty-command", arguments: fixed("") }, + { name: "error-unknown-mcp-subcommand", arguments: fixed("mcp", "bogus") }, + { + name: "error-missing-positional", + arguments: fixed("inspect-byte-entropy"), + }, + { name: "error-extra-positional", arguments: (w) => entropy(w, "extra") }, + { + name: "error-unknown-flag", + arguments: (w) => entropy(w, "--no-such-flag"), + }, + { + name: "error-missing-flag-value", + arguments: (w) => entropy(w, "--block-size"), + }, + { + name: "error-invalid-number", + arguments: (w) => entropy(w, "--block-size", "abc"), + }, + { + name: "error-refined-number", + arguments: (w) => entropy(w, "--block-size", "100"), + }, + { + name: "error-refined-number-json", + arguments: (w) => entropy(w, "--block-size", "100", "--format", "json"), + }, + { + name: "error-refined-number-md", + arguments: (w) => entropy(w, "--block-size", "100", "--format", "md"), + }, + { + name: "error-refined-number-full-output", + arguments: (w) => + entropy(w, "--block-size", "100", "--json", "--full-output"), + }, + { + name: "error-separator", + arguments: (w) => entropy(w, "--", "--block-size"), + }, + { + name: "error-format-invalid", + arguments: (w) => entropy(w, "--format", "bogus"), + }, + { name: "error-format-missing", arguments: (w) => entropy(w, "--format") }, + { + name: "error-delimited-without-columns", + arguments: (w) => entropy(w, ...BLOCKS, "--format", "csv"), + }, + { + name: "error-jsonl-not-collection", + arguments: (w) => entropy(w, ...BLOCKS, "--format", "jsonl"), + }, + { + name: "error-sensitive-output-value", + arguments: (w) => [ + "inspect-web-network-capture", + w.path("capture.har"), + "--format", + SENSITIVE, + "--sensitive-value", + SENSITIVE, + ], + }, + { + name: "error-sensitive-positional", + arguments: (w) => [ + "inspect-web-network-capture", + w.path("capture.har"), + "har", + SENSITIVE, + "--sensitive-value", + SENSITIVE, + ], + }, + + // Output formats, filtering and global output controls + { name: "output-toon", arguments: (w) => entropy(w, ...SELECTION) }, + { + name: "output-json", + arguments: (w) => entropy(w, ...SELECTION, "--format", "json"), + }, + { + name: "output-json-switch", + arguments: (w) => entropy(w, ...SELECTION, "--json"), + }, + { + name: "output-json-equals", + arguments: (w) => + entropy(w, `--filter-output=${SELECTION[1]}`, "--format=json"), + }, + { + name: "output-yaml", + arguments: (w) => entropy(w, ...SELECTION, "--format", "yaml"), + }, + { + name: "output-md", + arguments: (w) => entropy(w, ...SELECTION, "--format", "md"), + }, + { + name: "output-csv", + arguments: (w) => + entropy( + w, + ...BLOCKS, + "--columns", + "offset,length,entropy", + "--format", + "csv", + ), + }, + { + name: "output-tsv", + arguments: (w) => + entropy(w, ...BLOCKS, "--columns", "offset,entropy", "--format", "tsv"), + }, + { + name: "output-full-output", + arguments: (w) => entropy(w, ...WINDOW, "--full-output"), + }, + { + name: "output-full-output-json", + arguments: (w) => entropy(w, ...WINDOW, "--full-output", "--json"), + }, + { + name: "output-token-count", + arguments: (w) => entropy(w, ...WINDOW, "--token-count"), + }, + { + name: "output-token-limit", + arguments: (w) => entropy(w, ...SELECTION, "--token-limit", "5"), + }, + { + name: "output-token-offset", + arguments: (w) => + entropy(w, ...SELECTION, "--token-limit", "5", "--token-offset", "5"), + }, + { + name: "output-timings", + arguments: (w) => entropy(w, ...WINDOW, "--timings"), + }, +]; + +/** Rows of the root command list kept in the golden; the rest are elided. */ +const ROOT_HELP_ROWS: ReadonlySet = new Set([ + "address-to-file-offset", + "build-reconstruction-obligation-ledger", + "decompile", + "inspect-byte-entropy", + "setup", + "xrefs", +]); +const ELIDED_ROWS = " "; + +/** + * The root command list grows with every new command. Check its layout here + * (sorted, every description starting two columns after the longest name) + * and keep only sample rows in the golden, written with a two-space gap + * instead of the measured padding, so adding a command, including one with a + * longer name, does not change the goldens. + */ +const elideRootCommandRows = (stdout: string): string => { + const lines = stdout.split("\n"); + const start = lines.indexOf("Commands:"); + if (start < 0) return stdout; + const end = lines.indexOf("", start); + const rows = lines.slice(start + 1, end); + const parsed = rows.map((row) => /^ {2}(\S+)( +)\S/u.exec(row)); + expect(parsed.every((match) => match !== null)).toBe(true); + const names = parsed.map((match) => match![1]!); + expect(names).toEqual([...names].sort()); + const width = Math.max(...names.map((name) => name.length)); + for (const match of parsed) + expect(match![1]!.length + match![2]!.length).toBe(width + 2); + const kept: string[] = []; + rows.forEach((row, index) => { + if (ROOT_HELP_ROWS.has(names[index]!)) + kept.push(` ${names[index]!} ${row.slice(width + 4)}`); + else if (kept.at(-1) !== ELIDED_ROWS) kept.push(ELIDED_ROWS); + }); + return [...lines.slice(0, start + 1), ...kept, ...lines.slice(end)].join( + "\n", + ); +}; + +/** Visible, reviewable text for protocol control bytes. */ +const visible = (text: string): string => + text.replace( + // oxlint-disable-next-line no-control-regex -- the completion protocol separates records with control bytes. + /[\x00-\x08\x0b-\x1f\x7f]/gu, + (character) => + `<0x${character.charCodeAt(0).toString(16).padStart(2, "0")}>`, + ); + +const normalize = (text: string, workspace: TestWorkspace): string => + visible( + text + .split(workspace.root) + .join("") + .split(`rea@${PRODUCT_IDENTITY.packageVersion}`) + .join("rea@") + .replace(/^\d+\.\d+\.\d+(?:-[\w.]+)?\n$/u, (line) => + line === `${PRODUCT_IDENTITY.packageVersion}\n` ? "\n" : line, + ) + .replace(/(duration"?:\s*"?)\d+ms/gu, "$1ms") + .replace(/("command_ms":)\d+/gu, "$1"), + ); + +const render = ( + testCase: ParityCase, + workspace: TestWorkspace, + result: { exitCode: number | null; stdout: string; stderr: string }, +): string => { + const command = testCase + .arguments(workspace) + .map((argument) => + argument === "" || /\s/u.test(argument) + ? JSON.stringify(argument) + : argument, + ); + const stdout = testCase.name.startsWith("help-root") + ? elideRootCommandRows(result.stdout) + : result.stdout; + return [ + `$ ${testCase.complete === undefined ? "" : `COMPLETE=${testCase.complete} `}rea ${command.join(" ")}`.trimEnd(), + `exit: ${result.exitCode}`, + "--- stdout", + `${normalize(stdout, workspace)}`, + "--- stderr", + `${normalize(result.stderr, workspace)}`, + "", + ] + .join("\n") + .split(workspace.root) + .join(""); +}; + +describe("CLI parity goldens", () => { + // One workspace and environment for the file, so the shared CLI process + // serves every non-completion case instead of restarting per case. + let workspace: TestWorkspace; + beforeAll(async () => { + workspace = await createTestWorkspace("rea-cli-parity-"); + await workspace.write("sample.bin", SAMPLE); + }); + afterAll(async () => { + await removeTestWorkspace(workspace.root); + }); + + // Recording writes the files of new cases, so only orphans fail then. + cliTest("every golden belongs to a case", async () => { + const files = (await readdir(GOLDEN_DIRECTORY)).filter((file) => + file.endsWith(".txt"), + ); + const expected = CASES.map(({ name }) => `${name}.txt`).sort(); + if (RECORD) + expect(files.filter((file) => !expected.includes(file))).toEqual([]); + else expect(files.sort()).toEqual(expected); + }); + + cliTest.for(CASES)("$name", async (testCase, { cli }) => { + const result = await cli.run({ + arguments: testCase.arguments(workspace), + cwd: workspace.root, + environment: { + ...workspace.environment, + ...(testCase.complete === undefined + ? {} + : { COMPLETE: testCase.complete }), + }, + ...(testCase.complete === undefined ? {} : { freshProcess: true }), + }); + const actual = render(testCase, workspace, result); + const golden = new URL(`${testCase.name}.txt`, GOLDEN_DIRECTORY); + if (RECORD) { + await mkdir(GOLDEN_DIRECTORY, { recursive: true }); + await writeFile(golden, actual, "utf8"); + return; + } + expect(actual).toBe(await readFile(golden, "utf8")); + }); +}); diff --git a/tests/boundary/cli/bashCompletionRegistration.test.ts b/tests/boundary/cli/completionProtocol.test.ts similarity index 95% rename from tests/boundary/cli/bashCompletionRegistration.test.ts rename to tests/boundary/cli/completionProtocol.test.ts index 3d7596b7a5..1aa711413c 100644 --- a/tests/boundary/cli/bashCompletionRegistration.test.ts +++ b/tests/boundary/cli/completionProtocol.test.ts @@ -2,7 +2,7 @@ import { execFile } from "node:child_process"; import { promisify } from "node:util"; import { expect, it } from "vitest"; -import { bashCompletionScript } from "../../../src/cli/bashCompletionRegistration.js"; +import { bashCompletionScript } from "../../../src/cli/completionProtocol.js"; const execute = promisify(execFile); diff --git a/tests/fixtures/cli-parity/complete-bash-after-separator.txt b/tests/fixtures/cli-parity/complete-bash-after-separator.txt new file mode 100644 index 0000000000..e3d537fd92 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-after-separator.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea inspect-byte-entropy -- "" +exit: 0 +--- stdout + +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-aliased-option-value.txt b/tests/fixtures/cli-parity/complete-bash-aliased-option-value.txt new file mode 100644 index 0000000000..aaf9ccfca1 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-aliased-option-value.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea mcp add -c "" +exit: 0 +--- stdout + +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-boolean-before-subcommand.txt b/tests/fixtures/cli-parity/complete-bash-boolean-before-subcommand.txt new file mode 100644 index 0000000000..c7f1b728f2 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-boolean-before-subcommand.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea inspect-byte-entropy --json "" +exit: 0 +--- stdout + +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-command-prefix.txt b/tests/fixtures/cli-parity/complete-bash-command-prefix.txt new file mode 100644 index 0000000000..8db8a582c9 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-command-prefix.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea inspect-byte-e +exit: 0 +--- stdout +inspect-byte-entropy +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-completion-shells.txt b/tests/fixtures/cli-parity/complete-bash-completion-shells.txt new file mode 100644 index 0000000000..afb54a9d2a --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-completion-shells.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea completions "" +exit: 0 +--- stdout +bash<0x0b>zsh<0x0b>fish<0x0b>nushell +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-enum-values.txt b/tests/fixtures/cli-parity/complete-bash-enum-values.txt new file mode 100644 index 0000000000..485227119c --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-enum-values.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea instructions --target-format "" +exit: 0 +--- stdout +dos-com<0x0b>raw-binary<0x0b>gamecube-dol +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-format-values.txt b/tests/fixtures/cli-parity/complete-bash-format-values.txt new file mode 100644 index 0000000000..7d66cdcfd2 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-format-values.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea inspect-byte-entropy --format "" +exit: 0 +--- stdout +toon<0x0b>json<0x0b>yaml<0x0b>md<0x0b>jsonl<0x0b>csv<0x0b>tsv +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-global-prefix.txt b/tests/fixtures/cli-parity/complete-bash-global-prefix.txt new file mode 100644 index 0000000000..3e801f3475 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-global-prefix.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea inspect-byte-entropy --tok +exit: 0 +--- stdout +--token-limit<0x0b>--token-offset<0x0b>--token-count +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-group-prefix.txt b/tests/fixtures/cli-parity/complete-bash-group-prefix.txt new file mode 100644 index 0000000000..cd3650834d --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-group-prefix.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea mc +exit: 0 +--- stdout +mcp<0x01> +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-hand-built-enum-values.txt b/tests/fixtures/cli-parity/complete-bash-hand-built-enum-values.txt new file mode 100644 index 0000000000..3978a9602d --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-hand-built-enum-values.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea setup --tool-catalog-profile "" +exit: 0 +--- stdout +full<0x0b>hot-cold +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-mcp-subcommands.txt b/tests/fixtures/cli-parity/complete-bash-mcp-subcommands.txt new file mode 100644 index 0000000000..e6373e6692 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-mcp-subcommands.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea mcp "" +exit: 0 +--- stdout +add<0x0b>doctor +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-option-prefix.txt b/tests/fixtures/cli-parity/complete-bash-option-prefix.txt new file mode 100644 index 0000000000..f8cbfbce41 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-option-prefix.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea inspect-byte-entropy --bl +exit: 0 +--- stdout +--block-size +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-bash-short-aliases.txt b/tests/fixtures/cli-parity/complete-bash-short-aliases.txt new file mode 100644 index 0000000000..08f83baaca --- /dev/null +++ b/tests/fixtures/cli-parity/complete-bash-short-aliases.txt @@ -0,0 +1,6 @@ +$ COMPLETE=bash rea -- rea setup - +exit: 0 +--- stdout +--yes<0x0b>--install-hopper<0x0b>--desktop-build<0x0b>--install-agentenv<0x0b>--client<0x0b>--skill-client<0x0b>--tool-families<0x0b>--tool-catalog-profile<0x0b>--all-detected<0x0b>--skill<0x0b>--dry-run<0x0b>--accessible<0x0b>-y<0x0b>--format<0x0b>--filter-output<0x0b>--columns<0x0b>--token-limit<0x0b>--token-offset<0x0b>--full-output<0x0b>--llms<0x0b>--llms-full<0x0b>--help<0x0b>--schema<0x0b>--json<0x0b>--token-count<0x0b>--timings<0x0b>-h +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-fish-described-commands.txt b/tests/fixtures/cli-parity/complete-fish-described-commands.txt new file mode 100644 index 0000000000..a2386bb70e --- /dev/null +++ b/tests/fixtures/cli-parity/complete-fish-described-commands.txt @@ -0,0 +1,9 @@ +$ COMPLETE=fish rea -- rea inspect-pe- +exit: 0 +--- stdout +inspect-pe-load-config Inspect PE TLS callbacks and load configuration without executing the image +inspect-pe-certificates Inspect PE Authenticode certificate table identities without verifying signatures +inspect-pe-imports Inspect PE import and delay-load table identities without executing the image +inspect-pe-resources Inspect PE resource identities, payload ranges, hashes and icon-group relationships +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-nushell-described-commands.txt b/tests/fixtures/cli-parity/complete-nushell-described-commands.txt new file mode 100644 index 0000000000..0767b519b8 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-nushell-described-commands.txt @@ -0,0 +1,6 @@ +$ COMPLETE=nushell rea -- rea inspect-pe- +exit: 0 +--- stdout +[{"value":"inspect-pe-load-config","description":"Inspect PE TLS callbacks and load configuration without executing the image"},{"value":"inspect-pe-certificates","description":"Inspect PE Authenticode certificate table identities without verifying signatures"},{"value":"inspect-pe-imports","description":"Inspect PE import and delay-load table identities without executing the image"},{"value":"inspect-pe-resources","description":"Inspect PE resource identities, payload ranges, hashes and icon-group relationships"}] +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-zsh-described-commands.txt b/tests/fixtures/cli-parity/complete-zsh-described-commands.txt new file mode 100644 index 0000000000..1338bc3c7a --- /dev/null +++ b/tests/fixtures/cli-parity/complete-zsh-described-commands.txt @@ -0,0 +1,9 @@ +$ COMPLETE=zsh rea -- rea inspect-pe- +exit: 0 +--- stdout +inspect-pe-load-config:Inspect PE TLS callbacks and load configuration without executing the image +inspect-pe-certificates:Inspect PE Authenticode certificate table identities without verifying signatures +inspect-pe-imports:Inspect PE import and delay-load table identities without executing the image +inspect-pe-resources:Inspect PE resource identities, payload ranges, hashes and icon-group relationships +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-zsh-format-values.txt b/tests/fixtures/cli-parity/complete-zsh-format-values.txt new file mode 100644 index 0000000000..f20fa1bafe --- /dev/null +++ b/tests/fixtures/cli-parity/complete-zsh-format-values.txt @@ -0,0 +1,12 @@ +$ COMPLETE=zsh rea -- rea inspect-byte-entropy --format "" +exit: 0 +--- stdout +toon +json +yaml +md +jsonl +csv +tsv +--- stderr + diff --git a/tests/fixtures/cli-parity/complete-zsh-mcp-doctor-options.txt b/tests/fixtures/cli-parity/complete-zsh-mcp-doctor-options.txt new file mode 100644 index 0000000000..d2c10d0b09 --- /dev/null +++ b/tests/fixtures/cli-parity/complete-zsh-mcp-doctor-options.txt @@ -0,0 +1,10 @@ +$ COMPLETE=zsh rea -- rea mcp doctor -- +exit: 0 +--- stdout +--format:Output format +--json:Emit the report as JSON +--full-output:Show the full output envelope +--help:Show help +--timings +--- stderr + diff --git a/tests/fixtures/cli-parity/completions-bash.txt b/tests/fixtures/cli-parity/completions-bash.txt new file mode 100644 index 0000000000..e138c42c2e --- /dev/null +++ b/tests/fixtures/cli-parity/completions-bash.txt @@ -0,0 +1,39 @@ +$ rea completions bash +exit: 0 +--- stdout +_incur_complete_rea() { + local IFS=$'\013' + local _COMPLETE_INDEX=${COMP_CWORD} + local _completions _output + if ! _output=$( + export COMPLETE="bash" + export _COMPLETE_INDEX="$_COMPLETE_INDEX" + 'rea' -- "${COMP_WORDS[@]}" + ); then + unset COMPREPLY + return + fi + # Split the protocol records without expanding pathname patterns. + read -r -d '' -a _completions < <(printf '%s\0' "$_output") + local _nospace=false + local _nospace_marker=$'\001' + local _c + COMPREPLY=() + for _c in "${_completions[@]}"; do + if [[ "$_c" == *"$_nospace_marker" ]]; then + _nospace=true + COMPREPLY+=("${_c%"$_nospace_marker"}") + else + COMPREPLY+=("$_c") + fi + done + if [[ $_nospace == true ]] && type compopt >/dev/null 2>&1; then + compopt -o nospace + fi + return 0 +} +complete -o default -o bashdefault -o nosort -F _incur_complete_rea 'rea' 2>/dev/null || + complete -o default -o bashdefault -F _incur_complete_rea 'rea' + +--- stderr + diff --git a/tests/fixtures/cli-parity/completions-fish.txt b/tests/fixtures/cli-parity/completions-fish.txt new file mode 100644 index 0000000000..1d331a0d97 --- /dev/null +++ b/tests/fixtures/cli-parity/completions-fish.txt @@ -0,0 +1,8 @@ +$ rea completions fish +exit: 0 +--- stdout +complete --keep-order --exclusive --command rea \ + --arguments "(COMPLETE=fish rea -- (commandline --current-process --tokenize --cut-at-cursor) (commandline --current-token))" + +--- stderr + diff --git a/tests/fixtures/cli-parity/completions-nushell.txt b/tests/fixtures/cli-parity/completions-nushell.txt new file mode 100644 index 0000000000..54f6146a77 --- /dev/null +++ b/tests/fixtures/cli-parity/completions-nushell.txt @@ -0,0 +1,11 @@ +$ rea completions nushell +exit: 0 +--- stdout +# External completer for rea +# Add to $env.config.completions.external.completer or use in a dispatch completer. +let _incur_complete_rea = {|spans| + COMPLETE=nushell rea -- ...$spans | from json +} + +--- stderr + diff --git a/tests/fixtures/cli-parity/completions-unknown-shell.txt b/tests/fixtures/cli-parity/completions-unknown-shell.txt new file mode 100644 index 0000000000..91242e2419 --- /dev/null +++ b/tests/fixtures/cli-parity/completions-unknown-shell.txt @@ -0,0 +1,7 @@ +$ rea completions powershell +exit: 1 +--- stdout +Error (INVALID_SHELL): Unknown shell 'powershell'. Supported: bash, fish, nushell, zsh + +--- stderr + diff --git a/tests/fixtures/cli-parity/completions-zsh.txt b/tests/fixtures/cli-parity/completions-zsh.txt new file mode 100644 index 0000000000..81ae16aa26 --- /dev/null +++ b/tests/fixtures/cli-parity/completions-zsh.txt @@ -0,0 +1,18 @@ +$ rea completions zsh +exit: 0 +--- stdout +#compdef rea +_incur_complete_rea() { + local completions=("${(@f)$( + export _COMPLETE_INDEX=$(( CURRENT - 1 )) + export COMPLETE="zsh" + "rea" -- "${words[@]}" 2>/dev/null + )}") + if [[ -n $completions ]]; then + _describe 'values' completions -S '' + fi +} +compdef _incur_complete_rea rea + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-delimited-without-columns.txt b/tests/fixtures/cli-parity/error-delimited-without-columns.txt new file mode 100644 index 0000000000..7b446813f2 --- /dev/null +++ b/tests/fixtures/cli-parity/error-delimited-without-columns.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.blocks --format csv +exit: 1 +--- stdout +{"ok":false,"error":{"code":"UNSUPPORTED_OUTPUT_COMBINATION","message":"CSV/TSV output requires --filter-output and --columns ; nested Evidence is not flattened."}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-empty-command.txt b/tests/fixtures/cli-parity/error-empty-command.txt new file mode 100644 index 0000000000..afc1b817ae --- /dev/null +++ b/tests/fixtures/cli-parity/error-empty-command.txt @@ -0,0 +1,14 @@ +$ rea "" +exit: 1 +--- stdout +code: COMMAND_NOT_FOUND +message: '' is not a command for 'rea'. Did you mean 'mcp'? +cta: + description: "Suggested commands:" + commands[2]: + - command: rea mcp + - command: rea --help + description: see all available commands + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-extra-positional.txt b/tests/fixtures/cli-parity/error-extra-positional.txt new file mode 100644 index 0000000000..e45dc5a219 --- /dev/null +++ b/tests/fixtures/cli-parity/error-extra-positional.txt @@ -0,0 +1,8 @@ +$ rea inspect-byte-entropy /sample.bin extra +exit: 1 +--- stdout +code: UNKNOWN +message: "Unexpected positional arguments: \"extra\". Use 'rea inspect-byte-entropy --help' for the declared argument shape." + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-format-invalid.txt b/tests/fixtures/cli-parity/error-format-invalid.txt new file mode 100644 index 0000000000..ea52ee5af2 --- /dev/null +++ b/tests/fixtures/cli-parity/error-format-invalid.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --format bogus +exit: 1 +--- stdout +{"ok":false,"error":{"code":"INVALID_OUTPUT_VALUE","message":"Invalid format: \"bogus\". Expected one of: toon, json, yaml, md, jsonl, csv, tsv"}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-format-missing.txt b/tests/fixtures/cli-parity/error-format-missing.txt new file mode 100644 index 0000000000..fb0a80eec1 --- /dev/null +++ b/tests/fixtures/cli-parity/error-format-missing.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --format +exit: 1 +--- stdout +{"ok":false,"error":{"code":"MISSING_OUTPUT_VALUE","message":"--format requires a value, as in --format or --format=."}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-invalid-number.txt b/tests/fixtures/cli-parity/error-invalid-number.txt new file mode 100644 index 0000000000..4e0e3a55ff --- /dev/null +++ b/tests/fixtures/cli-parity/error-invalid-number.txt @@ -0,0 +1,10 @@ +$ rea inspect-byte-entropy /sample.bin --block-size abc +exit: 1 +--- stdout +code: VALIDATION_ERROR +message: "REA could not read the command arguments. Check the named argument and its expected type, then try again." +fieldErrors[1]{code,missing,path,expected,received,message}: + invalid_union,false,blockSize,"","",Invalid input + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-jsonl-not-collection.txt b/tests/fixtures/cli-parity/error-jsonl-not-collection.txt new file mode 100644 index 0000000000..581e012651 --- /dev/null +++ b/tests/fixtures/cli-parity/error-jsonl-not-collection.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.blocks --format jsonl +exit: 1 +--- stdout +{"$rea":"jsonl/v1","type":"error","ok":false,"result":{"code":"invalid_request","category":"invalid_input","message":"The --filter-output selection normalized_result.blocks is not a JSON Lines record collection: normalized_result.blocks is an array. JSON Lines needs a top-level array, or exactly one rows, items, records, or occurrences array directly in the result, under page, or under normalized_result.","retryable":false,"remediation":{"action":"Use --format json for the complete document, or select one record collection with --filter-output."},"recovery":{"kind":"inspect_input_contract","operation":"inspect-byte-entropy"},"details":{"operation":"inspect-byte-entropy","issues":[{"path":["filter-output"],"reason":"invalid_value","message":"The --filter-output selection normalized_result.blocks is not a JSON Lines record collection: normalized_result.blocks is an array.","observed":[{"path":["normalized_result","blocks"],"shape":"array"}]}]}}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-missing-flag-value.txt b/tests/fixtures/cli-parity/error-missing-flag-value.txt new file mode 100644 index 0000000000..ace92157d2 --- /dev/null +++ b/tests/fixtures/cli-parity/error-missing-flag-value.txt @@ -0,0 +1,8 @@ +$ rea inspect-byte-entropy /sample.bin --block-size +exit: 1 +--- stdout +code: UNKNOWN +message: "Missing value for flag: --block-size" + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-missing-positional.txt b/tests/fixtures/cli-parity/error-missing-positional.txt new file mode 100644 index 0000000000..3915f92f5c --- /dev/null +++ b/tests/fixtures/cli-parity/error-missing-positional.txt @@ -0,0 +1,10 @@ +$ rea inspect-byte-entropy +exit: 1 +--- stdout +code: VALIDATION_ERROR +message: "REA could not read the command arguments. Check the named argument and its expected type, then try again." +fieldErrors[1]{code,missing,path,expected,received,message}: + invalid_type,true,path,string,"","Invalid input: expected string, received undefined" + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-refined-number-full-output.txt b/tests/fixtures/cli-parity/error-refined-number-full-output.txt new file mode 100644 index 0000000000..8648ab9e8e --- /dev/null +++ b/tests/fixtures/cli-parity/error-refined-number-full-output.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --block-size 100 --json --full-output +exit: 1 +--- stdout +{"ok":false,"error":{"code":"VALIDATION_ERROR","message":"REA could not read the command arguments. Check the named argument and its expected type, then try again.","fieldErrors":[{"code":"too_small","missing":false,"path":"blockSize","expected":"","received":"","message":"Too small: expected number to be >=256"},{"code":"custom","missing":false,"path":"blockSize","expected":"","received":"","message":"Block size must be a power of two."}]},"meta":{"command":"inspect-byte-entropy","duration":"ms"}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-refined-number-json.txt b/tests/fixtures/cli-parity/error-refined-number-json.txt new file mode 100644 index 0000000000..af5023d479 --- /dev/null +++ b/tests/fixtures/cli-parity/error-refined-number-json.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --block-size 100 --format json +exit: 1 +--- stdout +{"code":"VALIDATION_ERROR","message":"REA could not read the command arguments. Check the named argument and its expected type, then try again.","fieldErrors":[{"code":"too_small","missing":false,"path":"blockSize","expected":"","received":"","message":"Too small: expected number to be >=256"},{"code":"custom","missing":false,"path":"blockSize","expected":"","received":"","message":"Block size must be a power of two."}]} + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-refined-number-md.txt b/tests/fixtures/cli-parity/error-refined-number-md.txt new file mode 100644 index 0000000000..ac3b4c8795 --- /dev/null +++ b/tests/fixtures/cli-parity/error-refined-number-md.txt @@ -0,0 +1,20 @@ +$ rea inspect-byte-entropy /sample.bin --block-size 100 --format md +exit: 1 +--- stdout +## code + +VALIDATION_ERROR + +## message + +REA could not read the command arguments. Check the named argument and its expected type, then try again. + +## fieldErrors + +| code | missing | path | expected | received | message | +|-----------|---------|-----------|----------|----------|-----------------------------------------------| +| too_small | false | blockSize | | | Too small: expected number to be >=256 | +| custom | false | blockSize | | | Block size must be a power of two. | + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-refined-number.txt b/tests/fixtures/cli-parity/error-refined-number.txt new file mode 100644 index 0000000000..0d9e83dbc4 --- /dev/null +++ b/tests/fixtures/cli-parity/error-refined-number.txt @@ -0,0 +1,11 @@ +$ rea inspect-byte-entropy /sample.bin --block-size 100 +exit: 1 +--- stdout +code: VALIDATION_ERROR +message: "REA could not read the command arguments. Check the named argument and its expected type, then try again." +fieldErrors[2]{code,missing,path,expected,received,message}: + too_small,false,blockSize,"","","Too small: expected number to be >=256" + custom,false,blockSize,"","",Block size must be a power of two. + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-sensitive-output-value.txt b/tests/fixtures/cli-parity/error-sensitive-output-value.txt new file mode 100644 index 0000000000..d7322374b5 --- /dev/null +++ b/tests/fixtures/cli-parity/error-sensitive-output-value.txt @@ -0,0 +1,7 @@ +$ rea inspect-web-network-capture /capture.har --format secret-literal --sensitive-value secret-literal +exit: 1 +--- stdout +{"ok":false,"error":{"code":"INVALID_OUTPUT_VALUE","message":"Invalid format: \"[REDACTED]\". Expected one of: toon, json, yaml, md, jsonl, csv, tsv"}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-sensitive-positional.txt b/tests/fixtures/cli-parity/error-sensitive-positional.txt new file mode 100644 index 0000000000..6e22c1892b --- /dev/null +++ b/tests/fixtures/cli-parity/error-sensitive-positional.txt @@ -0,0 +1,8 @@ +$ rea inspect-web-network-capture /capture.har har secret-literal --sensitive-value secret-literal +exit: 1 +--- stdout +code: UNKNOWN +message: "Unexpected positional arguments: \"[REDACTED]\". Use 'rea inspect-web-network-capture --help' for the declared argument shape." + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-separator.txt b/tests/fixtures/cli-parity/error-separator.txt new file mode 100644 index 0000000000..7ff270c2ad --- /dev/null +++ b/tests/fixtures/cli-parity/error-separator.txt @@ -0,0 +1,8 @@ +$ rea inspect-byte-entropy /sample.bin -- --block-size +exit: 1 +--- stdout +code: UNKNOWN +message: "Unknown flag: --" + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-unknown-command.txt b/tests/fixtures/cli-parity/error-unknown-command.txt new file mode 100644 index 0000000000..6607a4c185 --- /dev/null +++ b/tests/fixtures/cli-parity/error-unknown-command.txt @@ -0,0 +1,14 @@ +$ rea no-such-command +exit: 1 +--- stdout +code: COMMAND_NOT_FOUND +message: 'no-such-command' is not a command for 'rea'. Did you mean 'cutter-command'? +cta: + description: "Suggested commands:" + commands[2]: + - command: rea cutter-command + - command: rea --help + description: see all available commands + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-unknown-flag.txt b/tests/fixtures/cli-parity/error-unknown-flag.txt new file mode 100644 index 0000000000..d56ccf6637 --- /dev/null +++ b/tests/fixtures/cli-parity/error-unknown-flag.txt @@ -0,0 +1,8 @@ +$ rea inspect-byte-entropy /sample.bin --no-such-flag +exit: 1 +--- stdout +code: UNKNOWN +message: "Unknown flag: --no-such-flag" + +--- stderr + diff --git a/tests/fixtures/cli-parity/error-unknown-mcp-subcommand.txt b/tests/fixtures/cli-parity/error-unknown-mcp-subcommand.txt new file mode 100644 index 0000000000..6107fd84ee --- /dev/null +++ b/tests/fixtures/cli-parity/error-unknown-mcp-subcommand.txt @@ -0,0 +1,12 @@ +$ rea mcp bogus +exit: 1 +--- stdout +code: COMMAND_NOT_FOUND +message: 'bogus' is not a command for 'rea mcp'. +cta: + description: "Suggested command:" + commands[1]{command,description}: + rea mcp --help,see all available commands + +--- stderr + diff --git a/tests/fixtures/cli-parity/help-completions-bare.txt b/tests/fixtures/cli-parity/help-completions-bare.txt new file mode 100644 index 0000000000..39dfec1e35 --- /dev/null +++ b/tests/fixtures/cli-parity/help-completions-bare.txt @@ -0,0 +1,20 @@ +$ rea completions +exit: 0 +--- stdout +rea completions — Generate shell completion script + +Usage: rea completions + +Arguments: + shell Shell to generate completions for + +Setup: + bash eval "$(rea completions bash)" # add to ~/.bashrc + fish rea completions fish | source # add to ~/.config/fish/config.fish + nushell see `rea completions nushell` # add to config.nu + zsh eval "$(rea completions zsh)" # add to ~/.zshrc + +Zsh: initialize completion with `autoload -Uz compinit; compinit` before evaluating the zsh hook. If your shell already runs compinit, place the hook after it. + +--- stderr + diff --git a/tests/fixtures/cli-parity/help-completions.txt b/tests/fixtures/cli-parity/help-completions.txt new file mode 100644 index 0000000000..d7f63949eb --- /dev/null +++ b/tests/fixtures/cli-parity/help-completions.txt @@ -0,0 +1,20 @@ +$ rea completions --help +exit: 0 +--- stdout +rea completions — Generate shell completion script + +Usage: rea completions + +Arguments: + shell Shell to generate completions for + +Setup: + bash eval "$(rea completions bash)" # add to ~/.bashrc + fish rea completions fish | source # add to ~/.config/fish/config.fish + nushell see `rea completions nushell` # add to config.nu + zsh eval "$(rea completions zsh)" # add to ~/.zshrc + +Zsh: initialize completion with `autoload -Uz compinit; compinit` before evaluating the zsh hook. If your shell already runs compinit, place the hook after it. + +--- stderr + diff --git a/tests/fixtures/cli-parity/help-contract-command.txt b/tests/fixtures/cli-parity/help-contract-command.txt new file mode 100644 index 0000000000..7cc2ed97d5 --- /dev/null +++ b/tests/fixtures/cli-parity/help-contract-command.txt @@ -0,0 +1,31 @@ +$ rea inspect-byte-entropy --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/help-contract-defaults.txt b/tests/fixtures/cli-parity/help-contract-defaults.txt new file mode 100644 index 0000000000..0ae089a8e0 --- /dev/null +++ b/tests/fixtures/cli-parity/help-contract-defaults.txt @@ -0,0 +1,34 @@ +$ rea read-bytes --help +exit: 0 +--- stdout +rea read-bytes — Read provider memory bytes; Ghidra memory may include loader fixups and differ from file bytes + +Usage: rea read-bytes
[options] + +Arguments: + path Local executable path + address Exact provider memory address + +Options: + --length Requested byte count (default: 256) + --target-format Explicit interpretation: dos-com or raw-binary (headerless), or gamecube-dol (GameCube/Wii DOL, never auto-detected); omission preserves header-based detection + --architecture <6502|x86|x86_64|arm|arm64|m68k> Caller-supplied CPU family; required with --target-format raw-binary, must be omitted with gamecube-dol + --entry-point Caller-supplied load and entry address (0xhex); required with --target-format raw-binary, optional with gamecube-dol (must equal the DOL header entry) + --provider Bind deep analysis to a provider ID or use deterministic auto selection + +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/help-contract-long-description.txt b/tests/fixtures/cli-parity/help-contract-long-description.txt new file mode 100644 index 0000000000..3f97804213 --- /dev/null +++ b/tests/fixtures/cli-parity/help-contract-long-description.txt @@ -0,0 +1,39 @@ +$ rea decompile --help +exit: 0 +--- stdout +rea 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. + +Usage: rea decompile [address] [options] + +Arguments: + path App or program path + address Procedure name or address. Supply at least one of the positional address or --procedure. Alternatively, use --file-offset alone. + +Options: + --analysis Request a new independent decompile, bypassing project and snapshot results. Use only when the routed provider's procedure_pseudo_code capability declares independent_decompile; otherwise the request is refused. This may use different analysis context. + --detail Deliver complete Evidence, or a summary with --evidence_output (default: complete) + --snapshot Load and update a local analysis snapshot + --target-format Explicit interpretation: dos-com or raw-binary (headerless), or gamecube-dol (GameCube/Wii DOL, never auto-detected); omission preserves header-based detection + --architecture <6502|x86|x86_64|arm|arm64|m68k> Caller-supplied CPU family; required with --target-format raw-binary, must be omitted with gamecube-dol + --entry-point Caller-supplied load and entry address (0xhex); required with --target-format raw-binary, optional with gamecube-dol (must equal the DOL header entry) + --provider Bind deep analysis to a provider ID or use deterministic auto selection + --evidence_output Save complete Evidence as a bundle; required for summary delivery. Never overwrites. + --procedure Procedure name or address; use --procedure= for leading dashes. Supply at least one of the positional address or --procedure. Alternatively, use --file-offset alone. + --file-offset Ghidra source-file byte offset; mapped internally to an analysis address. Supply at least one of the positional address or --procedure. Alternatively, use --file-offset alone. + +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/help-contract-optional-positional.txt b/tests/fixtures/cli-parity/help-contract-optional-positional.txt new file mode 100644 index 0000000000..4b4bb678bb --- /dev/null +++ b/tests/fixtures/cli-parity/help-contract-optional-positional.txt @@ -0,0 +1,35 @@ +$ rea instructions --help +exit: 0 +--- stdout +rea instructions — Read every raw instruction without decompiling. Supply at least one of the positional address or --procedure. Equal values are accepted; conflicts fail. + +Usage: rea instructions [address] [options] + +Arguments: + path App or program path + address Procedure name or address. Supply at least one of the positional address or --procedure. + +Options: + --snapshot Load and update a local analysis snapshot + --target-format Explicit interpretation: dos-com or raw-binary (headerless), or gamecube-dol (GameCube/Wii DOL, never auto-detected); omission preserves header-based detection + --architecture <6502|x86|x86_64|arm|arm64|m68k> Caller-supplied CPU family; required with --target-format raw-binary, must be omitted with gamecube-dol + --entry-point Caller-supplied load and entry address (0xhex); required with --target-format raw-binary, optional with gamecube-dol (must equal the DOL header entry) + --provider Bind deep analysis to a provider ID or use deterministic auto selection + --procedure Procedure name or address; use --procedure= for leading dashes. Supply at least one of the positional address or --procedure. + +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/help-hand-built-capture-process.txt b/tests/fixtures/cli-parity/help-hand-built-capture-process.txt new file mode 100644 index 0000000000..9d68855017 --- /dev/null +++ b/tests/fixtures/cli-parity/help-hand-built-capture-process.txt @@ -0,0 +1,26 @@ +$ rea capture-process --help +exit: 0 +--- stdout +rea capture-process — Capture one caller-selected process scenario + +Usage: rea capture-process + +Arguments: + scenario Scenario JSON path + +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/help-hand-built-doctor.txt b/tests/fixtures/cli-parity/help-hand-built-doctor.txt new file mode 100644 index 0000000000..1d64a5006a --- /dev/null +++ b/tests/fixtures/cli-parity/help-hand-built-doctor.txt @@ -0,0 +1,29 @@ +$ rea doctor --help +exit: 0 +--- stdout +rea doctor — Check whether REA is ready + +Usage: rea doctor [options] + +Options: + --target Optional app path to check + --client Agent registration whose readiness is required; repeatable + --provider Deep-analysis provider, or desktop_build for a desktop build host, whose readiness is required + --skill Require the installed REA skill identity to be aligned + +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/help-hand-built-environment-build.txt b/tests/fixtures/cli-parity/help-hand-built-environment-build.txt new file mode 100644 index 0000000000..4eaf96ee23 --- /dev/null +++ b/tests/fixtures/cli-parity/help-hand-built-environment-build.txt @@ -0,0 +1,35 @@ +$ rea environment-build --help +exit: 0 +--- stdout +rea environment-build — Build an agent environment bundle from a recorded capture in one offline step: inspect a HAR (or read capture Evidence), project the environment manifest, derive the state, report which tools the environment answers from state, which replay and why each write is withheld, then write the bundle environment-export writes + +Usage: rea environment-build [directory] [options] + +Arguments: + capture A .har file, or capture Evidence JSON from inspect-web-network-capture (HAR) or capture-browser-scenario + directory Bundle directory to create; must be absent or empty, nothing is overwritten; omit only with --dry-run + +Options: + --name Env folder and env id (kebab-case); default the manifest's name, or the capture file's name when the origin is a loopback or IP address + --template-rule Opt-in template rule; repeat to select several. Replaces the default after-uid-literal, opaque-token, sibling-variance and prefix-variance + --format-rules-only Apply only the four format rules, the views' own default + --package-tarball Packed rea-agents tarball (npm pack) copied into the env folder and installed by the Dockerfile instead of the registry package pinned to this version + --dry-run Run every stage and report, but write nothing + --capture-timeout-ms Capture wall-clock deadline in milliseconds (default 30000), from decoder start through process exit. Omitted means 30000 and applies on the next capture. deadlineExpired returns no partial capture. Does not raise the separately selected max_input_bytes, max_reply_bytes or max_nesting_depth budgets. + +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/help-hand-built-guidance.txt b/tests/fixtures/cli-parity/help-hand-built-guidance.txt new file mode 100644 index 0000000000..ba3dcf3f41 --- /dev/null +++ b/tests/fixtures/cli-parity/help-hand-built-guidance.txt @@ -0,0 +1,30 @@ +$ rea guidance --help +exit: 0 +--- stdout +rea guidance — Search or read the installed REA workflow guidance + +Usage: rea guidance [options] + +Options: + --action Guidance action to perform: search or read (default: search) + --query Required with search; all non-generic query words must match + --locator Required with --action read; locator returned by search + --limit Maximum search matches; search only, defaults to 8 + --cursor Continue a search page; search only + +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/help-hand-built-setup.txt b/tests/fixtures/cli-parity/help-hand-built-setup.txt new file mode 100644 index 0000000000..aceecb9766 --- /dev/null +++ b/tests/fixtures/cli-parity/help-hand-built-setup.txt @@ -0,0 +1,37 @@ +$ rea setup --help +exit: 0 +--- stdout +rea setup — Configure agent integrations and optional analysis providers + +Usage: rea setup [options] + +Options: + --yes, -y Approve user-owned setup actions without prompting + --install-hopper Also approve Hopper installation with --yes + --desktop-build Prepare this host for desktop builds: pack REA's build-computer runtime and record the build settings in the selected registrations + --install-agentenv With --desktop-build, also install the agentenv-framework release bundles target with uv + --client Agent integration to configure; repeat for multiple agents + --skill-client Existing client skill destination to update; repeatable + --tool-families Comma-separated tool families this registration advertises; omit to preserve the saved selection, or advertise every tool if none is saved. To restore every tool, remove REA_MCP_TOOL_FAMILIES from the client's registration and restart the client. + --tool-catalog-profile MCP catalog: full advertises every in-scope tool; hot-cold loads tools on demand and requires client catalog refresh. Omit to preserve the saved profile, or use full if none is saved. Restart the client after changing it. + --all-detected Configure every detected supported agent + --skill Override the bundled skill included with agent integrations + --dry-run Print the resolved plan without applying it + --accessible Use sequential accessible setup prompts + +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/help-mcp-add.txt b/tests/fixtures/cli-parity/help-mcp-add.txt new file mode 100644 index 0000000000..9d11be3050 --- /dev/null +++ b/tests/fixtures/cli-parity/help-mcp-add.txt @@ -0,0 +1,27 @@ +$ rea mcp add --help +exit: 0 +--- stdout +rea mcp add — Register exact stdio launcher arguments in selected client settings, with backups and verified publication. + +Usage: rea mcp add [options] + +Options: + --agent Select client IDs or documented aliases; repeat --agent to select more than one. + --command, -c Stdio launcher text: space-separated words, single/double quote fragments, literal backslashes. Empty quoted arguments are preserved; NUL is rejected. HTTP(S) URL sources are unsupported; configure remote transports in client settings. + --no-global Write only project-scoped client settings; reject selections requiring global writes. + +No package acquisition or server execution. --no-global never writes global settings. + +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-mcp-doctor.txt b/tests/fixtures/cli-parity/help-mcp-doctor.txt new file mode 100644 index 0000000000..56bb577c6d --- /dev/null +++ b/tests/fixtures/cli-parity/help-mcp-doctor.txt @@ -0,0 +1,17 @@ +$ rea mcp doctor --help +exit: 0 +--- stdout +rea mcp doctor — Validate MCP adapter startup and tool listing + +Usage: rea mcp doctor [options] + +Options: + --format Output format + --json Emit the report as JSON + --full-output Show the full output envelope + --help, -h Show help + +Checks this REA adapter using the current runtime; does not verify a client's registered command or launch environment. This entry accepts only the options above. + +--- stderr + diff --git a/tests/fixtures/cli-parity/help-mcp.txt b/tests/fixtures/cli-parity/help-mcp.txt new file mode 100644 index 0000000000..50784c0b41 --- /dev/null +++ b/tests/fixtures/cli-parity/help-mcp.txt @@ -0,0 +1,24 @@ +$ rea mcp --help +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 new file mode 100644 index 0000000000..6016e3ad9e --- /dev/null +++ b/tests/fixtures/cli-parity/help-root-bare.txt @@ -0,0 +1,43 @@ +$ rea +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-root-short.txt b/tests/fixtures/cli-parity/help-root-short.txt new file mode 100644 index 0000000000..a9deec34b8 --- /dev/null +++ b/tests/fixtures/cli-parity/help-root-short.txt @@ -0,0 +1,43 @@ +$ rea -h +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-root-with-format.txt b/tests/fixtures/cli-parity/help-root-with-format.txt new file mode 100644 index 0000000000..ae5ad9f274 --- /dev/null +++ b/tests/fixtures/cli-parity/help-root-with-format.txt @@ -0,0 +1,43 @@ +$ rea --help --format json +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-root.txt b/tests/fixtures/cli-parity/help-root.txt new file mode 100644 index 0000000000..598d23e296 --- /dev/null +++ b/tests/fixtures/cli-parity/help-root.txt @@ -0,0 +1,43 @@ +$ rea --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-update.txt b/tests/fixtures/cli-parity/help-update.txt new file mode 100644 index 0000000000..4545ab46a7 --- /dev/null +++ b/tests/fixtures/cli-parity/help-update.txt @@ -0,0 +1,23 @@ +$ rea update --help +exit: 0 +--- stdout +rea update — Update this REA installation and verify the installed release + +Usage: rea update + +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/llms-command.txt b/tests/fixtures/cli-parity/llms-command.txt new file mode 100644 index 0000000000..5a86692b55 --- /dev/null +++ b/tests/fixtures/cli-parity/llms-command.txt @@ -0,0 +1,15 @@ +$ rea inspect-byte-entropy --llms +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/llms-full-command.txt b/tests/fixtures/cli-parity/llms-full-command.txt new file mode 100644 index 0000000000..665c6ff7d9 --- /dev/null +++ b/tests/fixtures/cli-parity/llms-full-command.txt @@ -0,0 +1,23 @@ +$ rea inspect-byte-entropy --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/output-csv.txt b/tests/fixtures/cli-parity/output-csv.txt new file mode 100644 index 0000000000..8e6892ca5c --- /dev/null +++ b/tests/fixtures/cli-parity/output-csv.txt @@ -0,0 +1,9 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.blocks --columns offset,length,entropy --format csv +exit: 0 +--- stdout +# rea-delimited-v1 {"version":1,"format":"csv","command":"inspect-byte-entropy","duration":"ms","selected_path":["normalized_result","blocks"],"coverage":null,"source_coverage":null,"source_complete":null,"view":null,"limitations":["Entropy does not prove encryption; compressed and encrypted bytes cannot be distinguished by this measure.","Entropy is rounded to four decimal places; thresholds classify those reported values. Small blocks can underestimate entropy.","The file-wide hash and entropy cover the entire file; blocks and runs cover only the selected window. Empty input has entropy 0 by convention."],"unknowns":null,"provenance":{},"pagination":{}}<0x0d> +offset,length,entropy<0x0d> +0,20,4.3219<0x0d> + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-full-output-json.txt b/tests/fixtures/cli-parity/output-full-output-json.txt new file mode 100644 index 0000000000..e2385ea210 --- /dev/null +++ b/tests/fixtures/cli-parity/output-full-output-json.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window --full-output --json +exit: 0 +--- stdout +{"ok":true,"data":{"normalized_result":{"window":{"offset":0,"length":20}}},"meta":{"command":"inspect-byte-entropy","duration":"ms"}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-full-output.txt b/tests/fixtures/cli-parity/output-full-output.txt new file mode 100644 index 0000000000..4e22dcc569 --- /dev/null +++ b/tests/fixtures/cli-parity/output-full-output.txt @@ -0,0 +1,15 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window --full-output +exit: 0 +--- stdout +ok: true +data: + normalized_result: + window: + offset: 0 + length: 20 +meta: + command: inspect-byte-entropy + duration: ms + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-json-equals.txt b/tests/fixtures/cli-parity/output-json-equals.txt new file mode 100644 index 0000000000..4cda9011a0 --- /dev/null +++ b/tests/fixtures/cli-parity/output-json-equals.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output=normalized_result.window,normalized_result.blocks,normalized_result.thresholds --format=json +exit: 0 +--- stdout +{"normalized_result":{"blocks":[{"offset":0,"length":20,"entropy":4.3219}],"thresholds":{"high":7.2,"low":1},"window":{"offset":0,"length":20}}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-json-switch.txt b/tests/fixtures/cli-parity/output-json-switch.txt new file mode 100644 index 0000000000..515938b730 --- /dev/null +++ b/tests/fixtures/cli-parity/output-json-switch.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window,normalized_result.blocks,normalized_result.thresholds --json +exit: 0 +--- stdout +{"normalized_result":{"blocks":[{"offset":0,"length":20,"entropy":4.3219}],"thresholds":{"high":7.2,"low":1},"window":{"offset":0,"length":20}}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-json.txt b/tests/fixtures/cli-parity/output-json.txt new file mode 100644 index 0000000000..125a902422 --- /dev/null +++ b/tests/fixtures/cli-parity/output-json.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window,normalized_result.blocks,normalized_result.thresholds --format json +exit: 0 +--- stdout +{"normalized_result":{"blocks":[{"offset":0,"length":20,"entropy":4.3219}],"thresholds":{"high":7.2,"low":1},"window":{"offset":0,"length":20}}} + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-md.txt b/tests/fixtures/cli-parity/output-md.txt new file mode 100644 index 0000000000..68cc02eb16 --- /dev/null +++ b/tests/fixtures/cli-parity/output-md.txt @@ -0,0 +1,25 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window,normalized_result.blocks,normalized_result.thresholds --format md +exit: 0 +--- stdout +## normalized_result.blocks + +| offset | length | entropy | +|--------|--------|---------| +| 0 | 20 | 4.3219 | + +## normalized_result.thresholds + +| Key | Value | +|------|-------| +| high | 7.2 | +| low | 1 | + +## normalized_result.window + +| Key | Value | +|--------|-------| +| offset | 0 | +| length | 20 | + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-timings.txt b/tests/fixtures/cli-parity/output-timings.txt new file mode 100644 index 0000000000..d6114aa5b0 --- /dev/null +++ b/tests/fixtures/cli-parity/output-timings.txt @@ -0,0 +1,11 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window --timings +exit: 0 +--- stdout +normalized_result: + window: + offset: 0 + length: 20 + +--- stderr +{"rea_timings":{"version":1,"command_ms":}} + diff --git a/tests/fixtures/cli-parity/output-token-count.txt b/tests/fixtures/cli-parity/output-token-count.txt new file mode 100644 index 0000000000..66010062a1 --- /dev/null +++ b/tests/fixtures/cli-parity/output-token-count.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window --token-count +exit: 0 +--- stdout +13 + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-token-limit.txt b/tests/fixtures/cli-parity/output-token-limit.txt new file mode 100644 index 0000000000..6635b11e22 --- /dev/null +++ b/tests/fixtures/cli-parity/output-token-limit.txt @@ -0,0 +1,8 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window,normalized_result.blocks,normalized_result.thresholds --token-limit 5 +exit: 0 +--- stdout +normalized_result: +[truncated: showing tokens 0–5 of 42] + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-token-offset.txt b/tests/fixtures/cli-parity/output-token-offset.txt new file mode 100644 index 0000000000..7acdccd03d --- /dev/null +++ b/tests/fixtures/cli-parity/output-token-offset.txt @@ -0,0 +1,9 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window,normalized_result.blocks,normalized_result.thresholds --token-limit 5 --token-offset 5 +exit: 0 +--- stdout + + blocks[1]{offset +[truncated: showing tokens 5–10 of 42] + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-toon.txt b/tests/fixtures/cli-parity/output-toon.txt new file mode 100644 index 0000000000..cde5225e0b --- /dev/null +++ b/tests/fixtures/cli-parity/output-toon.txt @@ -0,0 +1,15 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window,normalized_result.blocks,normalized_result.thresholds +exit: 0 +--- stdout +normalized_result: + blocks[1]{offset,length,entropy}: + 0,20,4.3219 + thresholds: + high: 7.2 + low: 1 + window: + offset: 0 + length: 20 + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-tsv.txt b/tests/fixtures/cli-parity/output-tsv.txt new file mode 100644 index 0000000000..c697d8b654 --- /dev/null +++ b/tests/fixtures/cli-parity/output-tsv.txt @@ -0,0 +1,9 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.blocks --columns offset,entropy --format tsv +exit: 0 +--- stdout +# rea-delimited-v1 {"version":1,"format":"tsv","command":"inspect-byte-entropy","duration":"ms","selected_path":["normalized_result","blocks"],"coverage":null,"source_coverage":null,"source_complete":null,"view":null,"limitations":["Entropy does not prove encryption; compressed and encrypted bytes cannot be distinguished by this measure.","Entropy is rounded to four decimal places; thresholds classify those reported values. Small blocks can underestimate entropy.","The file-wide hash and entropy cover the entire file; blocks and runs cover only the selected window. Empty input has entropy 0 by convention."],"unknowns":null,"provenance":{},"pagination":{}} +offset entropy +0 4.3219 + +--- stderr + diff --git a/tests/fixtures/cli-parity/output-yaml.txt b/tests/fixtures/cli-parity/output-yaml.txt new file mode 100644 index 0000000000..908739ff46 --- /dev/null +++ b/tests/fixtures/cli-parity/output-yaml.txt @@ -0,0 +1,18 @@ +$ rea inspect-byte-entropy /sample.bin --filter-output normalized_result.window,normalized_result.blocks,normalized_result.thresholds --format yaml +exit: 0 +--- stdout +normalized_result: + blocks: + - offset: 0 + length: 20 + entropy: 4.3219 + thresholds: + high: 7.2 + low: 1 + window: + offset: 0 + length: 20 + + +--- stderr + diff --git a/tests/fixtures/cli-parity/schema-command-json.txt b/tests/fixtures/cli-parity/schema-command-json.txt new file mode 100644 index 0000000000..232421abc3 --- /dev/null +++ b/tests/fixtures/cli-parity/schema-command-json.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy --schema --format json +exit: 0 +--- stdout +{"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.txt b/tests/fixtures/cli-parity/schema-command.txt new file mode 100644 index 0000000000..14730063c4 --- /dev/null +++ b/tests/fixtures/cli-parity/schema-command.txt @@ -0,0 +1,55 @@ +$ rea inspect-byte-entropy --schema +exit: 0 +--- stdout +args: + type: object + properties: + path: + type: string + minLength: 1 + pattern: "^[^\\x00]*$" + description: Local file + required[1]: path + additionalProperties: false +options: + type: object + properties: + blockSize: + default: 4096 + anyOf[2]: + - 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[2]: + - type: integer + minimum: 0 + maximum: 9007199254740991 + - type: string + pattern: "^[0-9]+$" + description: Window start as a decimal file byte offset + length: + anyOf[2]: + - 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[1]: timings + additionalProperties: false + +--- stderr + diff --git a/tests/fixtures/cli-parity/version-after-command.txt b/tests/fixtures/cli-parity/version-after-command.txt new file mode 100644 index 0000000000..f2e3834494 --- /dev/null +++ b/tests/fixtures/cli-parity/version-after-command.txt @@ -0,0 +1,7 @@ +$ rea inspect-byte-entropy --version +exit: 0 +--- stdout + + +--- stderr + diff --git a/tests/fixtures/cli-parity/version.txt b/tests/fixtures/cli-parity/version.txt new file mode 100644 index 0000000000..d4ed686c1d --- /dev/null +++ b/tests/fixtures/cli-parity/version.txt @@ -0,0 +1,7 @@ +$ rea --version +exit: 0 +--- stdout + + +--- stderr +