myxce/.kiro/specs/xce-test-cli-ux/requirements.md

Requirements Document

Introduction

xce_test (src/controller/testsuite/test.c) is the REPL/scripting client engineers use — both interactively and via piped scripts — to drive controller, worker, scheduler, and HA soak/E2E testing. A /cli-ux review found that its interrupt handling, flag validation, and output-stream discipline do not give scripted callers a reliable pass/fail signal, and give interactive users no way to recover from a stuck command without losing their session. This feature makes xce_test's command-line surface predictable and fail-loud: a mistyped flag, a stuck RPC, or a misrouted error message should never be silently absorbed or misreported. xce_test's existing exit-code/auto-variable verdict machinery (xce-test-e2e-primitives, implemented) and its per-command help <cmd> texts are unaffected and are the foundation this feature builds on.

Boundary Context

• In scope: process-level -h/--help/--version behavior; uniform rejection of unrecognized or malformed command-line flags across every xce_test command; consistent routing of error/diagnostic text to stderr and command-result data to stdout; Ctrl-C (SIGINT) behavior that cancels the in-flight operation or the current input line instead of silently doing nothing or exiting the session; a machine-readable output mode for the tabular listing commands (workerlist, joblist, reslist); command-not-found guidance that tells the user when a command exists in a different context; adding a long-form flag equivalent, consistently named per concept, for every command's existing short-only flags; command-name tab completion at the interactive prompt.
• Out of scope: the xce_test → xce_harness-style rename (tracked separately, to be done later); any change to controller/worker/scheduler wire protocol or RPC semantics; the auto-variable, exit-code-verdict, or shell-escape (!) mechanisms already shipped by xce-test-e2e-primitives; a full curses/TUI mode; color/theming; a .xce_testrc auto-executed startup-file feature (tracked as a separate, later task); changing what a successful command's result data actually contains; renaming, removing, or changing the meaning of any existing short flag (e.g. resolving -m's four different meanings, or -c's three, by reassigning a letter) — that is a breaking change to every script already using these flags and is deferred to a future, explicitly-scoped decision, not bundled into this feature; tab completion of flag values (jobids, hostnames, resource names) — only command-name completion is in scope; a per-command -h/--help flag handled by each cmd_* function individually — the existing in-session help <cmd> command already serves this need and is not being duplicated.
• Adjacent expectations: xce-test-e2e-primitives explicitly deferred structured/JSON output as out of its boundary — this feature now owns that gap for the listing commands only (jobsub/joblist's existing $jobid/$jobcount auto-variable capture is unaffected and remains the scripted way to read those specific values). Cancelling a client-side wait on Ctrl-C does not need to cancel the request on the controller/worker/scheduler side — the daemon's own RPC handling and timeouts are unaffected. Existing scripts that parse the current human-readable table output must keep working unchanged when the new machine-readable mode is not requested. Requirement 4's process-level -h/--help and the existing in-session help <cmd> command remain the sole help surfaces — Requirement 7's long-form flags are additive documentation of an existing command's own flags, not a new help mechanism.

Requirements

Requirement 1: Responsive Interrupt Handling

Objective: As an operator running xce_test interactively against a live or degraded HA cluster, I want Ctrl-C to cancel whatever is currently happening instead of silently doing nothing or exiting my whole session, so that I can recover control during a stuck command without losing my session state.

Acceptance Criteria

1. When the operator presses Ctrl-C while a command is blocked awaiting a cluster RPC reply, the xce_test session shall abandon the wait immediately, without waiting for the RPC's own timeout to elapse, and return control to the prompt.
2. When the operator presses Ctrl-C at the command prompt with no command in flight, the xce_test session shall discard the currently-typed input line and redisplay the prompt.
3. If a command is interrupted by Ctrl-C, then the xce_test session shall report that command as failed, consistent with how any other failing command is reported.
4. The xce_test session shall exit only as a direct result of an explicit quit command, an EOF at the top-level prompt, or an abort-on-failure condition in scripted mode — never as a side effect of a single Ctrl-C keypress.
5. While a command is being interrupted by Ctrl-C, the xce_test session shall leave the active worker/scheduler/client context and its underlying connection intact.

Requirement 2: Fail-Loud Flag Validation

Objective: As an author of HA soak/E2E test scripts driven through xce_test, I want every command to reject a flag it doesn't recognize or that is missing a required value, so that a typo in a script fails loudly instead of silently running with an unintended default.

Acceptance Criteria

1. When any xce_test command is invoked with a flag it does not recognize, the xce_test session shall reject the command, report the invalid flag, and return a nonzero result, instead of running the command while ignoring that flag.
2. When any xce_test command is invoked with a flag that requires a value but none is given, the xce_test session shall reject the command and report which flag is missing its value, instead of proceeding with an empty or default value.
3. The xce_test session shall apply Acceptance Criteria 1 and 2 uniformly across every command that accepts flags — no command shall silently ignore an unrecognized or malformed flag.
4. When the xce_test session rejects a command for an invalid or malformed flag, the xce_test session shall include that command's usage summary in the error output.

Requirement 3: Consistent Error and Output Stream Routing

Objective: As an author of scripts that pipe or redirect xce_test's output, I want every error and diagnostic message on stderr and every command result on stdout, so that I can reliably separate machine-parseable results from human diagnostics no matter which command fails.

Acceptance Criteria

1. The xce_test session shall write every error, warning, or diagnostic message to stderr.
2. The xce_test session shall write a command's successful result data to stdout only.
3. The xce_test session shall apply Acceptance Criteria 1 and 2 uniformly across every command and every error path, including flag-validation errors, RPC failures, and internal errors.
4. While xce_test's stdout and stderr are redirected to different destinations (a script or pipe), the xce_test session shall route a given message to the same stream it would use in an interactive TTY session.

Requirement 4: Process-Level Help and Version Discovery

Objective: As a new or infrequent user of xce_test, I want -h/--help and --version to behave the way they do in other command-line tools, so that I can learn how to use xce_test without already knowing its internals.

Acceptance Criteria

1. When xce_test is invoked with -h or --help, the xce_test process shall print usage help and exit without starting the interactive/scripted command session.
2. When xce_test is invoked with --version, the xce_test process shall print its version information and exit without starting the interactive/scripted command session.
3. The xce_test process's -h/--help output shall describe the in-session help command as the way to list and learn available commands.

Requirement 5: Machine-Readable Output for Listing Commands

Objective: As an author of an automated soak/E2E script, I want the tabular listing commands to offer a structured, machine-parseable output mode, so that my script can reliably extract fields without depending on fixed-width column alignment.

Acceptance Criteria

1. Where a machine-readable output mode is requested for workerlist, joblist, or reslist, the xce_test session shall emit each record in a structured, parseable format (for example, JSON) containing the same fields as that command's human-readable table.
2. When no machine-readable output mode is requested, the xce_test session shall continue to print the existing human-readable table for workerlist, joblist, and reslist, unchanged.
3. The xce_test session shall not truncate or misalign a field's value in machine-readable output regardless of the field value's length.
4. The xce_test session shall document, via help <cmd>, how to request the machine-readable output mode for each command that supports it.

Requirement 6: Context-Aware Command-Not-Found Guidance

Objective: As a user new to xce_test's top/worker/scheduler/client context tree, I want an unrecognized command to tell me if it exists in a different context, so that I can find where to run it without trial and error.

Acceptance Criteria

1. When a typed command is not found in the active context, and a command of that exact name exists in a different context, the xce_test session shall report the command as not found in the current context and identify the context where it does exist.
2. When a typed command is not found in the active context and does not exist in any context, the xce_test session shall report it as not found without naming an unrelated context.
3. The xce_test session shall not change the active context or execute any command as a result of a not-found lookup.

Requirement 7: Long-Form, Cross-Command-Consistent Flags

Objective: As a user or script author who has learned one xce_test command's flags, I want a long-form equivalent of every flag, named the same way for the same concept across every command that accepts it, so that muscle memory from one command doesn't mislead me in another and my scripts can be self-documenting.

Acceptance Criteria

1. The xce_test session shall provide a long-form flag equivalent for every flag that is currently available only as a short (single-letter) flag.
2. The xce_test session shall use the same long-form flag name for the same real-world concept (for example: a target host, a command line to run, a resource name, a job identifier) in every command that accepts that concept, regardless of what short letter each command already uses for it.
3. When a long-form flag equivalent is added for an existing short flag, the xce_test session shall leave that short flag's accepted values, default, and behavior unchanged.
4. The xce_test process's help output for a command (help <cmd>) shall list both the short and long form of each of that command's flags.

Requirement 8: Command-Name Tab Completion

Objective: As an interactive user, I want tab completion for command names at the prompt, so that I can discover and enter commands without memorizing the full command table or re-running help.

Acceptance Criteria

1. While the session is interactive and the operator presses tab while typing a command name, the xce_test session shall offer completions drawn only from the command names valid in the currently active context.
2. When the partially-typed text unambiguously matches exactly one command name in the active context, pressing tab shall complete it in full.
3. When the partially-typed text matches more than one command name in the active context, pressing tab shall list the matching candidates without altering the input line.
4. The xce_test session shall not offer a command name as a completion candidate when that command is not valid in the currently active context.