rust-script

# rust-script Operate Rust scripting with Cargo-native scripts first, `rust-script` fallback second. ## Default Mode Use Cargo script mode: ```sh <CARGO_SCRIPT_CMD> path/to/script.rs -- arg1 arg2 ``` Use this for: - single-file scripts with compile-time guarantees - explicit Cargo invocation across supported platforms - dependency management in embedded manifest frontmatter - script workflows close to regular Cargo projects Use `rust-script` only when user explicitly needs stable-only scripting ergonomics. ## Choose `<CARGO_SCRIPT_CMD>` Set command prefix by toolchain model: - Rustup-managed toolchains: - `CARGO_SCRIPT_CMD='cargo +nightly -Zscript'` - Nightly cargo already in PATH (common in Nix): - `CARGO_SCRIPT_CMD='cargo -Zscript'` Detection hint: - if `cargo -Zscript ...` works, prefer it - if `cargo +nightly` errors with `no such command: +nightly`, do not use `+nightly` ## Fast Decision Tree 1. User asks for Rust scripting + accepts nightly: - choose `<CARGO_SCRIPT_CMD>` - prefer frontmatter manifest (`---cargo ... ---`) 2. User wants stable-only and no nightly: - use `rust-script` fallback - explain tradeoff vs Cargo-native scripts 3. User asks about publishing/installing script file directly: - explain current limitation (`package`/`publish` unsupported; `install --path file.rs` unsupported) - suggest converting to normal package (`cargo new --bin`) ## Core Rules - Always pass `-Zscript` before script path - For extensionless executable scripts, call with path (`./tool`), not bare token (`tool`) - For script args that look like Cargo flags, use `--` separator when needed - Prefer explicit edition in frontmatter to avoid default-edition warning churn - Treat Cargo scripts as single-file bin packages, not workspace members ## Engineering Discipline - Keep scripts boring: parse external input once, return contextual errors, and add dependencies or abstractions only for a concrete script need - Use the standard library for a small script; add `anyhow` for ergonomic contextual errors or `clap` when argument parsing outgrows a few flags - Do not add async, a framework, or a production-service stack by default. Use async only for concurrent I/O that benefits from it - Treat `unsafe`, FFI, manual `Send`/`Sync`, and custom lock-free code as an escalation out of script scope; move the risky core to a normal Cargo package and prove it there ## Required follow-up reads |Need|Read|When| |---|---|---| |Cargo script runbook|`references/cargo-script-workflow.md`|Building or debugging a Cargo-native script| |Supported command surface|`references/command-support-matrix.md`|Before uncommon Cargo commands| |Exact error recovery|`references/error-catalog.md`|A known command fails| |Current stabilization state|`references/upstream-status.md`|Behavior may have changed upstream| |Stable fallback|`references/rust-script-fallback.md`|Nightly is unavailable or rejected| |Minimal scripts, frontmatter, verification, and sources|`references/contracts-and-verification.md`|Creating or validating a Cargo-native script| |Error, type, async, test, or unsafe design inside a script|`references/scripting-engineering.md`|Applying Rust engineering checks without turning a script into a service| |Opinionated production-Rust patterns|`references/advanced/rust/README.md`, then its matching reference|A script is becoming package-scale or needs deep async, CLI, web, type-state, test, concurrency, or safety guidance; repository policy and toolchain constraints take precedence| |Undefined-behavior investigation|`references/advanced/rust-ub/README.md`, then its matching reference|Auditing unsafe code with Miri, sanitizers, Loom, or the UB taxonomy| |Cross-language code-smell or logging review|`references/advanced/engineering/code-smells.md`, `references/advanced/engineering/logging.md`|Reviewing structure or observability beyond Rust-specific mechanics| |Legacy `rust-script` CLI|`reference/cli.md`|Exact fallback flags or environment variables are needed| |Starter source|`templates/script.rs`, `templates/async.rs`|Creating a matching script| ## Agent Operating Procedure 1. Detect user intent: - Cargo-native script mode or `rust-script` fallback 2. Validate command shape: - `-Zscript` position, path form, `--manifest-path` usage 3. Apply known limits: - block unsupported flows early (`package`, `publish`, `install --path file.rs`, path dependency on script) 4. Provide fix-ready command: - return exact corrected command, no vague advice 5. If behavior seems new/regressed: - check `references/upstream-status.md` - then confirm live state with `gh issue view`