# Copilot Instructions for Hen
## Build and test commands
### Root Rust workspace
- Full test suite: `cargo test`
- Run a single integration test file: `cargo test --test verify_cli`
- Run a single integration test: `cargo test --test verify_cli verify_reports_requests_and_required_inputs`
- Run a single unit test: `cargo test request::planner::tests::session_reuse_adds_implicit_dependency --lib`
- Build the release binary: `cargo build --release`
- Run the CLI from source: `cargo run -- run ./examples/lorem.hen all --non-interactive`
### Documentation site
- Build the Docusaurus site: `cd website && npm run build`
- Type-check the site: `cd website && npm run typecheck`
### VS Code extension
- Build the extension bundle: `cd editors/vscode-hen && npm run build`
- Package the extension: `cd editors/vscode-hen && npm run package`
## High-level architecture
- `src/main.rs` is the terminal entrypoint for the `hen` binary. It only parses CLI args and dispatches to `cli_run`, `cli_verify`, or `cli_inspect`.
- `src/automation.rs` is the main shared boundary for loading collections, verifying syntax, inspecting authoring structure, resolving prompt inputs, summarizing collections, and executing planned requests. If behavior must match across CLI commands or other non-interactive integrations, change `automation` first instead of duplicating logic in `cli_*`.
- `src/parser/` owns the `.hen` language: preprocessing/imports, pest grammar, prompt/context handling, named environments, OAuth blocks, redaction directives, declarations/schema syntax, protocol validation, and inspection/editor-support output.
- `src/request/` owns the executable model:
- `template.rs` expands authoring templates and mapped requests
- `planner.rs` builds the request DAG from explicit `> requires:` dependencies and implicit session ordering
- `runner.rs` executes the plan, supports concurrency, polling, interrupts, and emits execution events/traces
- `session.rs` stores runtime state for HTTP cookies plus SSE/WS/OAuth session lifecycles
- Tests are split between unit tests inside `src/**` and CLI-focused integration tests in `tests/`. Integration tests use `tests/support::TestWorkspace` to create temp workspaces, copy fixtures from `tests/fixtures`, and execute the compiled `hen` binary via `env!("CARGO_BIN_EXE_hen")`.
## Key conventions
- Treat `hen run`, `hen verify`, and `hen inspect` as separate surfaces with different guarantees:
- `run` executes requests
- `verify` validates without network or shell execution
- `inspect` is the machine-readable authoring/introspection surface used by editor tooling
- Request descriptions are planner identifiers, not just display text. Dependencies are resolved by description, so request names must stay unique and stable when editing fixtures, examples, or parser behavior.
- Reusing `session = ...` is not only shared runtime state; it also creates implicit ordering in the planner. Changes to session behavior affect execution order, not just cookies or connection reuse.
- Non-interactive callers are expected to provide prompt values up front. Prompt resolution is managed through `parser::context`, and `automation` installs a non-interactive prompt session for structured execution paths.
- Environment selection only overrides previously declared scalar preamble variables. Keep environment logic aligned with the resolution order documented in `README.md`: base scalars, selected environment, explicit inputs, prompt defaults, then runtime captures/exports.
- When changing machine-readable output, check the CLI output code (`cli_output.rs`, `report/`). The repo supports text, JSON, NDJSON, and JUnit output, and tests cover those formats under `tests/output_cli/` and `src/report/tests.rs`.
- When adding CLI behavior, keep `cli.rs` limited to argument shape and enums; put shared semantics in `automation` or `request`.
- When writing or updating integration tests, follow the existing `TestWorkspace` pattern instead of shelling out manually. Most CLI coverage uses small `.hen` fixtures plus assertions on stdout/stderr and exit codes.
- For docs-affecting changes to authoring behavior, update both `README.md` and `syntax-reference.md` when needed.
- In interactive terminal sessions, `cargo test` can block on prompt-related parser tests because stdin is a TTY. If you only need targeted validation while working in the CLI, prefer scoped test commands such as a single integration test file or a single unit test.