myxce/.kiro/specs/xce-test-rc-file/requirements.md

Requirements Document

Introduction

Every xce_test invocation starts from a blank slate: users repeatedly retype the same set masters .../set secret ... commands (and sometimes mistype them) before they can do anything useful against a cluster. This feature adds an rc file, auto-executed at startup through xce_test's existing command path, so a user's usual settings and starting context are applied automatically — the same convenience shells (.bashrc), gdb (.gdbinit), and readline (.inputrc) already provide. It reuses execute_line/preprocess_and_run as-is; no new scripting syntax is introduced.

Boundary Context

• In scope: rc-file discovery at a fixed, XDG-compliant path; loading and executing the rc file's commands through the existing command-execution path before the interactive/scripted read loop starts, for both interactive and scripted/piped sessions; a --norc flag to skip rc-file loading for a given invocation; failure handling for a bad rc-file command that reuses the session's existing abort-on-failure/continue-on-error and exit-code-verdict machinery.
• Out of scope: a --rcfile <path> custom-location override (deferred — can be added later as an orthogonal flag); any new scripting syntax or primitive beyond what execute_line already supports; a per-project/cwd rc file; any legacy dotfile convention (e.g. ~/.xce_testrc) — there is no prior rc-file feature to stay compatible with; xce_test creating, writing, or scaffolding the rc file or its directory — it only reads a file the user already created; any change to the auto-variable, exit-code-verdict, or shell-escape mechanisms already shipped by xce-test-e2e-primitives.
• Adjacent expectations: this feature relies on $XDG_CONFIG_HOME/$HOME already being set correctly in the operator's environment, and on the XDG Base Directory Specification's own defined fallback (~/.config when $XDG_CONFIG_HOME is unset or empty) — xce_test does not manage, create, or validate permissions on that directory. Every command inside the rc file is an ordinary xce_test command and remains subject to that command's own existing validation (e.g. set masters still requires valid peer syntax). xce_test is already the harness underneath other existing automation (the xce-test-ha and xce-test-resources skills' soak/verification scripts, and other specs' testsuite/*.sh integration scripts) that invoke it with no rc file present today and no awareness this feature exists — Requirement 1.3's "no rc file → unchanged behavior" guarantee must hold for these existing callers, not just for a new rc-file user, so this feature does not require any prior caller of xce_test to opt in or adapt.

Requirements

Requirement 1: RC File Discovery and Loading

Objective: As a user who repeatedly retypes (and sometimes mistypes) the same setup commands every xce_test session, I want xce_test to automatically run a personal rc file at startup, so that my usual settings and starting context are applied without manual repetition.

Acceptance Criteria

1. The xce_test process shall, before executing the first line from its interactive or scripted read loop, look for an rc file at $XDG_CONFIG_HOME/xce_test/rc, or at ~/.config/xce_test/rc when $XDG_CONFIG_HOME is unset or empty.
2. If the rc file exists, then the xce_test process shall execute each of its lines through the same command path used for a line typed at the prompt or read from a piped script.
3. If the rc file does not exist, then the xce_test process shall proceed directly to its normal read loop without reporting an error.
4. The xce_test process shall perform rc-file discovery and loading the same way regardless of whether the session is interactive (TTY) or scripted/piped.
5. When the rc file changes the active context (worker/scheduler/client) or a setting (e.g. masters, secret, myname), the xce_test session shall carry that context and those settings forward into the read loop that follows.

Requirement 2: Opt-Out via --norc

Objective: As a user who needs a run with no local rc-file state (for example, a CI/soak script that requires a clean, reproducible environment), I want a flag that skips rc-file loading entirely, so that my run's behavior never depends on what happens to be in my rc file.

Acceptance Criteria

1. When xce_test is invoked with --norc, the xce_test process shall skip rc-file discovery and loading entirely and proceed directly to its normal read loop.
2. The xce_test process's process-level help output shall document the --norc flag.
3. Where --norc is not given, the xce_test process shall perform rc-file discovery and loading as described in Requirement 1.

Requirement 3: RC File Failure Handling

Objective: As a user or script author, I want a failing command inside my rc file to be reported and handled exactly like any other failing command, so that a typo neither locks me out of the tool nor runs silently unnoticed.

Acceptance Criteria

1. If a command in the rc file fails, then the xce_test process shall report that failure the same way it reports the failure of any other command.
2. While the session is running in its default interactive continue-on-error mode, if a command in the rc file fails, the xce_test process shall continue executing the remaining rc-file commands and then proceed to the normal interactive prompt.
3. While the session is running in its default scripted/piped abort-on-first-failure mode, if a command in the rc file fails, the xce_test process shall stop processing further input — including the remainder of the rc file and any piped script commands — and exit with a nonzero status.
4. The xce_test process shall apply the same session-verdict and exit-code accounting to a failing rc-file command that it applies to any other failing command.