AGENTS.md

Ephemeral Environment Rules

This agent runs in a short‑lived environment. Any uncommitted or unpushed work will be permanently lost.

Mandatory

1. Commit frequently — after every logical step.

2. Push immediately after every commit (retry up to 3 times).

3. Never leave unpushed commits.

4. Use the correct branch:

   • PR work → PR head branch
   • Issue work → fix/<id>-short-desc or feat/<id>-short-desc
   • Otherwise → current branch unless instructed

5. Keep commits small and atomic. Prefer multiple small commits.

6. Do not commit secrets.

7. Before ending work: run git status and ensure everything is committed and pushed.

Rule of thumb: If runner stops right now, no meaningful work should be lost.

Project Overview

Rash is a declarative shell scripting language using Ansible-like YAML syntax, compiled to a single Rust binary. It's designed for container entrypoints, IoT devices, and local scripting with zero dependencies.

Build Commands

make build              # Debug build
make test               # Lint + unit tests + integration tests
make lint               # fmt --check + clippy -D warnings
make lint-fix           # Auto-fix formatting and clippy issues

Code Conventions

• Zero clippy warnings enforced with -D warnings
• No unwrap()/expect() outside of tests - use ? with contextual errors
• Function size: Keep under ~60 lines
• Every new module feature needs both unit tests and an example

Testing

# Run specific Rust test
cargo test -p rash_core test_name

# Run integration test script
cargo run --bin rash test/path/to/test.rh