lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(xce-test-cli-ux): commit requirements/design/tasks spec-phase artifacts

Browse source 
Captures the spec-authoring work from earlier in this session: expanded
requirements.md (Requirements 8-13 added during discussion: detailed
help content, destructive-command confirmation, actionable flag
suggestions, bug-1711/bug-1557 fixes, and the source command), plus
the corresponding spec.json phase/approval updates. design.md and
tasks.md were already committed alongside the first implementation
task (0748f10c); this closes the gap so the full spec-authoring
history is captured in version control, matching the approvals the
user already gave interactively during this session's requirements
review, design review, and task-plan generation.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019jaMf9QEwpugH2W9KAuc7f
This commit is contained in:
Rongsong Shen 2026-09-09 11:40:26 +00:00
parent 4d1f247674
commit 7d0ac6f6eb
No known key found for this signature in database
GPG key ID: 5BCDAAE0123E9FE2
3 changed files with 212 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

95
.kiro/specs/xce-test-cli-ux/requirements.md
View file

@ -6,9 +6,9 @@
## 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.
- **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`); 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; detailed, consistent per-command help content (purpose description, full flag documentation, an example, and related-command/context notes) in `help <cmd>` output; a confirmation prompt, bypassable via a per-command flag, a session-scoped confirmation toggle, or non-interactive mode, before executing a destructive command; suggesting the likely-intended flag when an unrecognized flag closely matches exactly one flag the command accepts; correcting bug-1711's display defects — the "UNKOWN"/"matchs"/"sequentail" text typos, `reslist`'s inconsistent column justification and unlabeled hex Flags column, `joblist`'s raw-epoch timestamps and its mintasks/maxtasks pair mislabeled as a single "NTasks" column, `joblist`'s missing raw-state fallback for an ambiguous RUN+EXIT state, and `getconf`'s silently-empty group/config sections; correcting `join`'s stale byte-scale `maxmem` default (bug-1557) so its documented default in help text is also a correct one; an in-session `source <file>` command for composing reusable command sequences from files, including nested sourcing with cycle detection.
- **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; a full error-code taxonomy with reference URLs — this tool has no external documentation site to link to, so actionable error output is limited to a same-command flag-name suggestion; a persistent, configurable default for skipping destructive-command confirmation that survives across separate xce_test invocations (e.g. a config file or environment variable) — Requirement 9's bypass mechanisms (a per-command flag and a session-scoped confirmation toggle) both reset to confirmation-on at the start of every new xce_test process; **context-aware command-not-found guidance** — telling the user that an unrecognized command exists in a different context (considered, then deliberately dropped): both command dispatch and `help <cmd>` lookups are scoped to the active context only, and an unrecognized name is reported as not found there without checking any other context.
- **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 6's long-form flags and Requirement 8's expanded content are additive documentation of an existing command's own flags and behavior, not a new help mechanism. Requirement 9's session-scoped confirmation toggle (9.6-9.7) is how a `source`d file (Requirement 13) runs destructive commands unattended without per-command bypass flags — a script author sets the toggle explicitly before or within the sourced file, rather than `source` implicitly granting or blocking confirmation bypass on its own.
## Requirements
@ -19,7 +19,7 @@
#### 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.
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, except a destructive command's confirmation prompt (Requirement 9.9), which is reported as not run rather than failed.
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.
@ -58,20 +58,11 @@
#### 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.
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, except where Requirement 11 supersedes this Acceptance Criterion for a specific defect it corrects (`reslist`'s column justification and Flags formatting; `joblist`'s timestamp formatting, NTasks column, and state fallback).
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
### Requirement 6: 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.
@ -81,7 +72,7 @@
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
### Requirement 7: 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`.
@ -90,3 +81,75 @@
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.
### Requirement 8: Detailed, Consistent Per-Command Help Content
**Objective:** As a user or script author running `help <cmd>`, I want every command's help text to consistently include what the command does, every flag it accepts, an example, and how it relates to other commands, so that I don't have to read the source to use it correctly.
#### Acceptance Criteria
1. The xce_test session's `help <cmd>` output shall include a one-to-two sentence description of the command's purpose, in addition to its usage syntax line.
2. For every flag a command accepts, the xce_test session's `help <cmd>` output shall state both the short and long form of that flag (per Requirement 6), whether it is required, and its default value if one exists.
3. The xce_test session's `help <cmd>` output shall include at least one concrete example invocation for every command that accepts flags or arguments.
4. Where invoking a command sets scripting state read elsewhere (for example, an auto-variable) or the command is commonly paired with another command, the xce_test session's `help <cmd>` output shall name that related state or command.
5. The xce_test session shall apply Acceptance Criteria 1-4 uniformly to every command's help text — no command's help text is exempt.
6. Where a command's behavior, output, or the entity it acts on differs depending on the active context (for example, which entity's data a shared command like `waldump` reads), the xce_test session's `help <cmd>` output shall describe the behavior specific to the currently active context, not a generic description that omits the context-specific difference.
7. When `help <cmd>` is given a name that is not a command in the active context, the xce_test session shall report it as not found in the active context without checking whether that name exists as a command in a different context.
### Requirement 9: Confirmation for Destructive Commands
**Objective:** As an operator running xce_test interactively against a live or degraded HA cluster, I want a destructive command to ask for confirmation before it executes, so that a typo or a misremembered jobid doesn't take an unintended, irreversible action on the cluster.
#### Acceptance Criteria
1. When a destructive command is invoked interactively without an explicit bypass flag, the xce_test session shall prompt the operator to confirm before executing it.
2. When the operator declines the confirmation prompt, the xce_test session shall abort the command without executing it and report it as not run, distinct from reporting it as failed.
3. The xce_test session shall provide a long-form bypass flag (for example, `--yes`) on every destructive command to skip the confirmation prompt.
4. When xce_test's input is not from an interactive TTY, or the bypass flag is given, the xce_test session shall execute the destructive command without prompting.
5. The xce_test session shall treat the following, and only the following, as destructive commands subject to Acceptance Criteria 1-4 and 6-9: `jobkill` (client context); `shutdown` (client context); `qctrl` invoked with `-i` or `-c` (client context); `hostctrl` invoked with `-c` (client context); and `upgradeconfig` (client context). `qctrl` invoked with `-a`/`-o` and `hostctrl` invoked with `-o` are reversal/reactivation actions and shall not require confirmation. `jstart`/`jfinish`/`jfail` (worker context) are excluded — they simulate a fake worker's own job-lifecycle facts for test purposes and do not warrant a confirmation prompt. This determination applies identically regardless of whether the qualifying flag (`-i`/`-c`/`-a`/`-o`) is given in its short or long form (Requirement 6).
6. The xce_test session shall provide a session-scoped confirmation toggle, in the same style as its existing `-e`/`+e`/continue-on-error toggle, defaulting to confirmation-on.
7. While the session-scoped confirmation toggle is set to skip confirmation, the xce_test session shall execute every destructive command without prompting, regardless of TTY state, until the toggle is set back to confirmation-on — so that a script, including one run via `source` (Requirement 13), can explicitly opt in to unattended execution of destructive commands without needing a per-command bypass flag on each one.
8. The xce_test session shall write the confirmation prompt text to stderr, consistent with Requirement 3's routing of non-result text.
9. When the operator presses Ctrl-C while a confirmation prompt is displayed, the xce_test session shall treat it the same as declining the prompt (Acceptance Criterion 2), shall not execute the destructive command, and shall report it as not run rather than failed — a deliberate exception to Requirement 1.3's general Ctrl-C-as-failure rule, since declining a destructive action is a safe outcome, not an error.
### Requirement 10: Actionable Error Messages for Invalid Flags
**Objective:** As a user or script author who mistypes a flag, I want the rejection message to suggest the flag I probably meant, so that I can fix the invocation without re-reading the command's full help text.
#### Acceptance Criteria
1. When an unrecognized flag closely matches exactly one flag the command accepts (for example, a common misspelling or that flag's short/long counterpart), the xce_test session shall name that flag as the likely intended one in its rejection message, in addition to the usage summary already required by Requirement 2.4.
2. When an unrecognized flag does not closely match any flag the command accepts, the xce_test session shall report it as unrecognized without guessing, consistent with Requirement 2.1.
3. The xce_test session shall apply Acceptance Criteria 1-2 uniformly across every command that accepts flags.
### Requirement 11: Correctness Fixes for Existing Output and Help-Text Defects (bug-1711)
**Objective:** As a user of xce_test's listing commands and help text, I want its existing display defects — typos, an inconsistent table format, silently-empty sections, and a missing state-display fallback — fixed, so that its output is trustworthy and internally consistent instead of accumulating small surprises.
#### Acceptance Criteria
1. The xce_test session shall report an unrecognized worker status bit using correctly spelled text ("UNKNOWN"), not "UNKOWN".
2. When `help <cmd>` is given an unknown topic, the xce_test session shall report it using grammatically correct text ("No commands match `%s'"), not "No commands matchs `%s'" — this is a text-grammar fix only and does not add the cross-context lookup excluded by Requirement 8.7.
3. The xce_test session's `runtasks` command shall label its default single-task launch type as "sequential", not "sequentail", wherever that value is displayed.
4. The xce_test session's `reslist` command shall left-justify its Name and Description text columns, consistent with `workerlist`'s equivalent columns, and shall label and prefix its Flags column as hexadecimal (for example, `0x%x`), consistent with this file's `state_raw` convention.
5. The xce_test session's `joblist` command shall format its SubmitTime, StartTime, and FinishTime columns using this file's existing human-readable time formatting (as `ctrlstatus` already does), not raw Unix epoch seconds.
6. The xce_test session's `joblist` command shall present its hidden mintasks/maxtasks pair as two distinct, correctly labeled columns rather than a single ambiguous "NTasks" column.
7. The xce_test session's `joblist` command shall report an ambiguous RUN+EXIT job state using a raw-state fallback, consistent with the fallback `print_jobinfo` already applies for that same ambiguity.
8. The xce_test session's `getconf` command shall either print the actual contents of its User Groups, Host Groups, and Configs sections, or, if a section is not yet implemented, print an explicit "(not implemented)" marker — never a header followed by silent nothing that is indistinguishable from a genuinely empty cluster.
### Requirement 12: Correct join's Stale maxmem Default (bug-1557)
**Objective:** As an operator using `join` to simulate a worker joining without a real `xcecd`, I want its default `maxmem` value to represent a sane amount of memory in the codebase's current bytes-canonical unit, so that a worker joined without `-m` doesn't silently report 64 bytes of RAM.
#### Acceptance Criteria
1. When the `join` command is invoked without a maxmem flag, the xce_test session shall default the simulated worker's maxmem to 64 * 1024 * 1024 (64 MB expressed in bytes), consistent with this codebase's bytes-canonical convention for maxmem.
2. The xce_test session's help text for `join` shall document this corrected default value, consistent with Requirement 8.2's requirement to state each flag's default.
### Requirement 13: In-Session Script Sourcing
**Objective:** As an interactive or scripted xce_test user, I want a `source <file>` command that reads and executes another file's commands within the current session, so that I can compose reusable command sequences without restarting the process or resorting to shell-level concatenation.
#### Acceptance Criteria
1. When the user runs `source <file>`, the xce_test session shall read and execute each line of that file as if it had been typed at the current prompt, in order.
2. When `source <file>` is invoked and the file does not exist or cannot be read, the xce_test session shall report the error and shall not treat any line of that file as executed.
3. When a command sourced from a file fails, the xce_test session shall apply the same abort-on-failure/continue-on-error behavior (per the session's current `-e`/`+e`/`continue-on-error` setting) to that file's remaining lines as it applies to the top-level input stream.
4. The xce_test session shall support invoking `source` from within a sourced file, so that one script file can compose others.
5. When a `source` command would create a cycle (a file sourcing itself, directly or transitively), the xce_test session shall detect this, reject the command, and report an error, instead of hanging or exhausting resources.
6. The xce_test session shall document `source`'s usage, behavior, and interaction with the continue-on-error/abort-on-failure setting in `help source`, consistent with Requirement 8.
7. The xce_test session shall evaluate Requirement 9's TTY-based confirmation-prompt condition (Acceptance Criterion 4) against the top-level session's own standard input, not against whether a command's text currently originates from a sourced file — so a destructive command inside a `source`d file in an otherwise-interactive session still prompts for confirmation unless the session-scoped confirmation toggle (Requirement 9.6-9.7) is set to skip it.