Skip to content

fix(cli): support --cmd-file for batch commands (#1098) - #1150

Merged
h-a-n-a-s-h-i merged 1 commit into
storytold:mainfrom
Zaxaerith:fix/1098-cli-command-file
Oct 30, 2026
Merged

h-a-n-a-s-h-i merged 1 commit into
storytold:mainfrom
Zaxaerith:fix/1098-cli-command-file

Conversation

@Zaxaerith

@Zaxaerith Zaxaerith commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Problem

deckcraft-cli run requires each command in a separate --cmd argument. Large scripts exceed Windows' command-line length limit before the CLI can start, and JSON must also be quoted for the shell.

Implementation

  • Add repeatable run --cmd-file FILE, retaining command sources in argument order alongside existing --cmd values.
  • Read UTF-8 files one line at a time with the standard library. Skip blank lines and full-line # comments, trim surrounding whitespace, and accept CRLF and an optional initial UTF-8 BOM.
  • Extract the existing id[=JSON] parsing and Session::execute path into a small helper used by both sources. Bare command ids still receive an empty JSON object; inline command syntax, diagnostics and --print output are preserved.
  • Attach the file path to open errors and the physical, one-based line number to line-reading, JSON and execution errors.
  • Propagate the first error immediately, so later commands and final --save/--export actions are not reached.
  • Update CLI usage/details and the required minimal ROADMAP entry. No dependencies, engine changes or unrelated refactoring.

The existing input/sample selection, output-format validation, save and export paths remain in place.

Regression coverage added

Five integration tests in the existing CLI test module cover:

  • Multiple file commands executing in order, with bare ids and JSON parameters.
  • Unicode text, filenames containing spaces, embedded = and # inside JSON strings, skipped blank/comments, whitespace, BOM, CRLF and a final line without a newline.
  • Multiple command files interleaved with inline commands, plus saving/reopening the resulting synthetic native presentation.
  • Invalid JSON, unknown commands and an engine command failure reporting the correct file/line.
  • Fail-fast behavior: later file/inline commands do not create marker outputs, and existing final save/export targets remain unchanged.
  • Missing files, unreadable directory inputs, invalid UTF-8 and a missing --cmd-file argument.
  • Existing inline command syntax and error messages.

The existing help regression also checks the new option and ordering/failure documentation. Fixtures are generated temporary text files and a small synthetic native deck; no external presentation assets are needed.

Static review and verification

Reviewed ownership/lifetimes, command ordering, shared parser behavior, error propagation before final output actions, the engine command contracts used by the tests, and help/source consistency. git diff --check completed without findings.

No Rust compilation, Cargo tests, formatting checks, Clippy, xtask, WASM builds, or other platform builds were run locally. No dependencies were downloaded and no target directory was created. Regression tests have been added but not executed. Compilation and test results are pending upstream GitHub CI and maintainer review.

Before publication, #1098 was open and unassigned, its discussion contained no claim, and all 747 existing open/closed PRs were checked for equivalent work.

Limitations

  • Optional stdin support (--cmd -) is deferred; --cmd-file supplies the requested file-based route around command-line length limits.
  • This preserves repeated---cmd fail-fast semantics, not a transaction: earlier explicit command side effects are not rolled back.
  • Actual Windows behavior, formatting and test execution remain unverified locally.

Fixes #1098

Summary by CodeRabbit

  • New Features
    • The run command now accepts UTF-8 command files with --cmd-file, alongside inline --cmd options. Commands from both sources run in the order provided.
    • Command files support blank lines, full-line comments, CRLF line endings, and an optional UTF-8 BOM. Errors identify the file and, when relevant, the line number.
    • If a command fails, later commands do not run and the run stops before its final save or export.
  • Documentation
    • Updated run --help with command-file usage and an example combining file and inline commands.

@coderabbitai

coderabbitai Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
📥 Commits

Reviewing files that changed from the base of the PR and between 128cb0b and 6655a1d.

📒 Files selected for processing: 4
  • ROADMAP.md
  • apps/deckcraft-cli/src/help.rs
  • apps/deckcraft-cli/src/main.rs
  • apps/deckcraft-cli/tests/cli.rs

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

The run command now accepts UTF-8 command files through --cmd-file. File commands and inline --cmd commands execute in option order. Command-file errors include file and line context, and failures stop processing before final saves or exports.

Changes: CLI command-file input

Layer / File(s) Summary
Command sources and ordered execution
apps/deckcraft-cli/src/main.rs, apps/deckcraft-cli/src/help.rs, ROADMAP.md
run accepts repeated --cmd-file options and mixes them with --cmd in option order. Command files support UTF-8, CRLF, an optional leading BOM, blank lines, comments, and trimmed whitespace. File and line-related errors include path and line context.
Command-file behavior tests
apps/deckcraft-cli/tests/cli.rs
Integration tests cover command-file parsing, mixed source ordering, failure behavior, path and line reporting, and the existing inline-command syntax.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant RunCLI
  participant CommandFile
  participant CommandExecutor
  participant OutputFiles
  RunCLI->>CommandFile: Read command file
  CommandFile->>RunCLI: Provide command lines
  RunCLI->>CommandExecutor: Execute commands in source order
  CommandExecutor->>RunCLI: Return results or an error
  RunCLI->>OutputFiles: Save or export after successful execution
Loading

Suggested reviewers: echelon

Merge Risk: ⚪ Minimal · up to 6655a

Command-file failures stop later commands and final outputs as intended. No actionable merge blocker was identified.

Security architecture risk: ⚪ Minimal · up to 6655a

Command files use the same execution controls and permissions as existing inline commands. Errors stop subsequent commands and final outputs. No material security risk was identified in this change; batches retain the existing nontransactional behavior.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — A supplied command file has the same command authority as inline input, including document changes and file-writing commands available to the invoking process. Malicious content therefore requires the caller to select an attacker-controlled file; no additional privilege or remote entrypoint is introduced by this execution path.

Trust Boundaries and Controls

  • observed — Command-file contents are executable CLI input, not sandboxed document data. Both source types cross into Session through the same helper and retain command lookup, enablement checks and guarded execution. The PR does not weaken those controls.

Resilience and Maintainability Implications

  • observed — Fail-fast propagation contains later command effects, but it is not cleanup of earlier effects. Engine rollback restores the active document snapshot only under its existing outer-command and document-identity conditions; it does not provide batch-wide or filesystem rollback.
Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 64.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 3 files. (1 skipped: … Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main change: adding CLI support for --cmd-file batch commands.
Linked Issues check Passed Issue #1098 requires a file-based command source, one UTF-8 command per line, ignored blank and comment lines, mixed --cmd-file and --cmd values in option order, and fail-fast execution without fi…
Out of Scope Changes check Passed The reported changes are limited to ROADMAP.md, CLI help, apps/deckcraft-cli/src/main.rs, and CLI integration tests. The implementation supports the linked file-input objective and preserves exist…
Full details: Linked Issues check

Explanation

Issue #1098 requires a file-based command source, one UTF-8 command per line, ignored blank and comment lines, mixed --cmd-file and --cmd values in option order, and fail-fast execution without final save. The reviewed change adds repeatable run --cmd-file FILE support, shared parsing and execution, path and line diagnostics, and stops before later commands and save/export actions. The added CLI tests cover ordering, UTF-8 and line handling, errors, fail-fast behavior, and help text. Optional stdin support is not required by the issue.

Full details: Out of Scope Changes check

Explanation

The reported changes are limited to ROADMAP.md, CLI help, apps/deckcraft-cli/src/main.rs, and CLI integration tests. The implementation supports the linked file-input objective and preserves existing inline command behavior. The tests and documentation support that objective. The summary reports no dependencies, engine changes, or unrelated refactoring.

Full details: Docstring Coverage

Explanation

Docstring coverage is 64.29% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 3 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@Harrison-Booth

Copy link
Copy Markdown
Contributor

This now conflicts with main after the module split in #1433 (the files moved into modules; see docs/ path map PR 1468). If you would rather not, I can open a PR that credits you, keeps your commits and shows a git range-diff against this one, so you'll still get credit and have visible work.

@Zaxaerith

Copy link
Copy Markdown
Contributor Author

Thanks for the heads-up, and I really appreciate the offer!

I'd be happy to take you up on that. Please feel free to open a follow-up PR adapting the changes to the new module layout.

It would be great to preserve the original commit authorship where possible and link back to #1150. Including the range-diff you mentioned would also make the relationship between the two PRs clear.

Once the replacement PR is ready, I can close this one to avoid duplication.

Thanks again for your help!

@h-a-n-a-s-h-i
h-a-n-a-s-h-i merged commit 6a9f18a into storytold:main Oct 30, 2026
1 check passed
h-a-n-a-s-h-i pushed a commit that referenced this pull request Oct 30, 2026
fix(cli): support --cmd-file for batch commands (#1098), carried from #1150
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

run: accept commands from a file or stdin (Windows command line limit)

3 participants