fix(workflows): render gate show_file contents in the interactive prompt

[doquanghuy]

Description

Closes #2809.

The built-in gate step accepts a show_file config field. The value was read, template-expanded, and stored in output["show_file"], but its contents were never displayed at the interactive prompt — the operator was asked to approve/reject without seeing the referenced file.

This renders show_file inside the interactive gate prompt, before the options. A missing, undecodable, or invalid path degrades to a short one-line notice instead of raising, so a misconfigured path never breaks the prompt.

What changed

• New GateStep._compose_prompt(message, show_file) folds the show_file material (a path header plus its contents) into the displayed message. GateStep._prompt(message, options) keeps its existing two-argument contract and simply renders the (possibly multi-line) message inside the gate box — display data does not widen the interactive seam, so stubbing _prompt in tests stays stable.
• New GateStep._read_show_file(...) reads the file as UTF-8, caps output at MAX_SHOW_FILE_LINES, and returns a (could not read file: …) / (file is empty) notice on error/empty/invalid-path (OSError, UnicodeDecodeError, ValueError) instead of raising.
• All show_file-derived strings that reach the terminal — the displayed path, each file line, and the read-error notice — are stripped of C0 control characters (_sanitize_for_display) so neither file contents nor the path can inject ANSI escape sequences. The file is still opened with the original path.
• A non-string message (e.g. a YAML numeric literal) is coerced to str for display.

Compatibility

• Non-interactive (PAUSED) path is unchanged — the file is not read when stdin is not a TTY.
• Exit codes, on_reject handling, and resume semantics are unchanged.
• Gates without show_file produce byte-identical output for the common single-line message; a multi-line message is now boxed on every line (previously continuation lines fell outside the box).

Testing

• Tested locally with uv run specify --help
• uv sync --extra test && uv run pytest — green
• Tested with a sample project (if applicable)

Tests in tests/test_workflows.py::TestGateStep cover: interactive rendering of show_file contents; missing / empty / oversized (truncated) / invalid-path files degrading to a notice; control-character stripping of both file contents and the displayed path; non-string message rendering; and the non-interactive path PAUSING and preserving output["show_file"] without reading the file. Gate tests force stdin determinism by rebinding the gate module's sys reference (no process-wide mutation).

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

Used Claude to trace the bug in gate/__init__.py, draft the fix and tests, and write this PR body. The behaviour was reproduced and the diff reviewed locally before submission.

[Copilot]

Pull request overview

This PR fixes the built-in workflow gate step so that a configured show_file is actually rendered in the interactive prompt, allowing operators to review the referenced file contents before choosing approve/reject. It adds a bounded, non-throwing file-read helper and extends test coverage around the interactive/non-interactive behaviors.

Changes:

• Render show_file contents inside the interactive gate prompt (before the options).
• Add _read_show_file() helper that caps output length and degrades to a one-line notice on read/decode errors.
• Add targeted tests covering interactive rendering, missing files, non-interactive pause behavior, empty files, and truncation.

Show a summary per file

File	Description
src/specify_cli/workflows/steps/gate/__init__.py	Passes show_file into the gate prompt and safely renders file contents with truncation/error notices.
tests/test_workflows.py	Adds regression tests for interactive rendering and safe behavior across missing/empty/large files and non-interactive runs.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 2/2 changed files
• Comments generated: 1

[doquanghuy]

Thanks @copilot — fixed in the latest push.

show_file is now coerced to str after template evaluation (and for any non-string literal), so a single-expression template that resolves to a non-string (e.g. a number from a prior step) is rendered instead of being silently skipped. The now-redundant isinstance(show_file, str) guard at the prompt was simplified to if show_file:. Added a test covering a templated show_file that resolves to a non-string.

uv run pytest green (3313 passed, 40 skipped); ruff check src/ clean.

@mnriem ready for another look when you have a moment.

[Copilot]

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 1

[doquanghuy]

Pushed a fix that also brings the branch up to date with main.

CI failure (the merge-time TypeError). main grew test_gate_abort_still_halts_with_continue_on_error, which stubs GateStep._prompt with a two-argument lambda. This PR had widened _prompt to take show_file as a third positional argument, so the stubbed call blew up once the branch met main.

Rather than patch the stub, I kept _prompt at its original (message, options) contract and compose the show_file material into the displayed message in execute() (new _compose_prompt helper; _prompt now renders a multi-line message inside the gate box). Display data no longer widens the interactive seam, so stubbing _prompt stays stable and future review material can be added without breaking callers — i.e. this class of failure can't recur.

Copilot's open note. _read_show_file now also catches ValueError, so a path the OS rejects outright (e.g. an embedded NUL byte, which Path.open raises before any I/O) degrades to the (could not read file: …) notice instead of crashing the prompt. Added a regression test.

Local: full uv run pytest green, ruff check src/ clean, gate suite + the previously-failing test pass.

@mnriem ready for another look when you have a moment.

[Copilot]

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 7

[doquanghuy]

Pushed 06bcd43 addressing Copilot's latest review.

• Test robustness (5 comments). All gate tests now swap the gate module's sys.stdin for a fixed-isatty stub via a shared _force_gate_stdin(monkeypatch, tty=…) helper, mirroring test_gate_abort_still_halts_with_continue_on_error, instead of setattr on sys.stdin.isatty (which isn't assignable under some pytest capture modes). The non-interactive tests now force a non-TTY so they can't go interactive or hang in a real terminal, and test_non_interactive_show_file_still_pauses_without_reading hard-fails if _read_show_file is called — proving the file isn't read on the PAUSED path.
• _compose_prompt typing. It now coerces with str(message) (annotated message: object) and always returns a str, matching the docstring, whether or not show_file is set; the redundant coercion in _prompt was removed.
• Multi-line note. The per-line boxing is byte-identical for single-line messages (the normal case) and corrects multi-line messages (continuation lines are now inside the box rather than falling outside it). Detail in the thread.

Full uv run pytest green (3353 passed), ruff check clean.

@mnriem ready for another look when you have a moment.

[Copilot]

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 2

[doquanghuy]

Pushed 4d52dd9 addressing Copilot's latest review.

• ANSI injection via show_file. _read_show_file now strips C0 control characters (except tab) from each line, so a referenced file containing ANSI escapes (e.g. \x1b[2J) can't clear the screen or spoof the prompt/options. Sanitizing at the read boundary covers every rendering. New test_read_show_file_strips_control_chars.
• Deterministic gate tests. Added an autouse fixture on TestGateStep defaulting all gate tests to a non-TTY stdin, so none can drop into the interactive prompt and block on input() under a real TTY; interactive tests opt back in via _force_gate_stdin(tty=True).

Full uv run pytest green (3354 passed), ruff check clean.

@mnriem ready for another look when you have a moment.

[Copilot]

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 1

[doquanghuy]

Pushed 8b653d7 addressing Copilot's note: _force_gate_stdin now rebinds the gate module's sys reference to a delegating stand-in (fixed-isatty stdin, every other attribute proxied to the real sys) rather than mutating process-wide sys.stdin, so the patch stays local to the gate module. The one other test using the same swap now shares the helper, so the pattern exists in exactly one place. Full uv run pytest green (3354 passed), ruff clean. @mnriem ready for another look.

[Copilot]

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 2

[doquanghuy]

Pushed 4f6f843 + refreshed the PR description for Copilot's two notes. (1) The displayed show_file path (header line and the read-error notice) is now sanitized too, not just the file contents — all routed through a single _sanitize_for_display helper; the file is still opened with the raw path. New test_compose_prompt_sanitizes_show_file_path. (2) Rewrote What changed to describe the actual _compose_prompt design (_prompt keeps its (message, options) contract). Full uv run pytest green (3355 passed), ruff clean. @mnriem ready for another look.

[Copilot]

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 1

[doquanghuy]

Pushed 3905fbc: the gate _CONTROL_CHARS class now also strips LF and the C1 range ([\x00-\x08\x0a-\x1f\x7f-\x9f], tab still kept), closing the newline-in-path and \x9b/CSI gaps Copilot flagged. One-line regex change; extended the existing path test to cover them. Full uv run pytest green (3355 passed), ruff clean. @mnriem ready for another look.

[Copilot]

Copilot's findings

• Files reviewed: 2/2 changed files
• Comments generated: 0 new