refactor(compile): structure generated ado-proxy and az wrapper scripts

[jamesadevine]

Summary

Closes #1833.

start_ado_proxy_step was a ~200-line body built by format!, and render_az_wrapper a ~120-line interpolated standalone executable. Neither was reviewable as shell — and reviewing them as shell is the only way to know they are correct.

The unreadability came from the escaping, not from bash: \n\ continuations to fake multi-line source, doubled braces to survive format! itself (a Docker Go-template read {{{{.State.Status}}}}), and an escaped quote for every quoted word. So bash stays; the escaping goes.

The approach

A new src/compile/shell/ module. A script is a raw-string const co-located with its producer, registered by shell_script!, with substitution restricted to a typed, shell-quoted prelude:

shell_script! {
    /// Greppable: search `mkfifo` and you land on the producer.
    START_ADO_PROXY {
        interpreter: Bash,
        bindings: [PROXY_CONTAINER, AGENT_TEMP],
        externals: [],
        fragments: [resolve_org],
        body: r#"
set -euo pipefail
# ado-aw:fragment resolve_org
PROXY_DIR=$(mktemp -d "$AGENT_TEMP/ado-proxy.XXXXXX")
docker inspect -f 'state={{.State.Status}}' "$PROXY_CONTAINER"
"#,
    }
}

• One injection position. A value can only be the right-hand side of a prelude assignment, so it can never alter the structure of the script. Typed binders (text, number, boolean, words, ado_macro, ado_path, document) each validate their own shape.
• Declared surface. Every variable a body reads is a binding (compiler-supplied) or an external (runtime-supplied). Enforced at render and by a registry-wide test.
• Credentials cannot be bindings — the prelude is committed to the repo. They stay on EnvValue::secret, which ADO masks.
• Single-hop editing. The shell stays in the file that produces it: grep the shell, land on the producer.

Issue #1833 specifics

start_ado_proxy_step is decomposed into eight registered phases (work directory, policy, material minting, material assembly, container start, handover, destruction, readiness) spliced into an outline at # ado-aw:fragment markers.

It remains one atomic Bash task. The phases are Rust-level and shell-level structure, not additional ADO steps, so the bearer, CA private key and leaf keys still never touch a runner path, argv, environment or container layer. All 15 credential-custody tests pass unchanged.

The container's nested sh -c entrypoint — previously an opaque string shellcheck could not see into — is now its own registered Sh script and is linted for the first time.

Lint coverage was the real gap

Coverage used to depend on fixture reachability: a generator no fixture exercised was linted by nothing. That was exactly the ado-proxy lifecycle and the az wrapper — several hundred lines of unlinted shell.

There are now two levels:

Level	What it proves
src/compile/shell/lint.rs — every registered script in isolation	the shell is correct
tests/bash_lint_tests.rs — bodies in compiled YAML	the shell is emitted

A composed script is linted with its phases spliced in, so cross-phase variable flow — the one new risk decomposition introduces — is checked rather than assumed.

ado-aw export-bash-scripts --output <dir> materialises all 87 scripts as reviewable .sh files with provenance headers.

Bugs found and fixed

Three of these were the tooling distorting the source rather than the source being wrong:

• referenced_vars demanded a declaration for awk's $NF inside single quotes. An agent had renamed it to $n to comply; the original expression is restored and the checker now skips single-quoted spans.
• PATH was stub-assigned, tripping SC2123 — a bug the real script does not have.
• The export header pushed shebangs off line 1 (SC1128), so exported sh scripts were unrunnable. Caught only by shellchecking the exported files independently of the harness that generates them.
• -v /tmp/ado-aw-lib:... duplicated the AZ_WRAPPER_DIR constant in the proxy container mount; now bound.

Scope note

Also migrated: the az wrapper, every extensions/ generator, the four runtimes, cache_memory, common.rs, filter_ir.rs, engine.rs, and the supply-chain payload staging helpers (which carried explicit "SAFETY: unescaped interpolation" comments — now enforced rather than requested). bash() and dedent() are deleted.

safe_outputs/create_pull_request.rs is deliberately not migrated. It has 38 \n\ continuations and no shell at all — they are Markdown PR-description text, and its 13 git calls are argv-based. Wrapping them would have added a shell that is not there today.

tests/generated_shell_guard.rs prevents regression, and a test proves the guard distinguishes an inline body from a format! display name — a guard that only ever passes is indistinguishable from one that does nothing.

Test plan

All run locally against shellcheck 0.10.0 with ENFORCE_BASH_LINT=1:

• cargo test — 2981 unit + all integration suites green
• cargo clippy --all-targets — zero warnings, zero errors
• cargo test --test bash_lint_tests — shellcheck over every bash body in compiled YAML
• cargo test --bin ado-aw compile::shell — registry-wide shellcheck plus declared-surface, fragment-marker and shell-name guards
• cargo test --test generated_shell_guard — regression guard
• Independent verification: exported all 87 scripts and ran shellcheck on them as standalone files, outside the in-process harness — 0 findings. This is what caught the shebang bug; a harness that generates and then checks its own input can agree with itself while both are wrong.
• Credential custody: the 15 ado_proxy_* tests (bearer/CA-key never under /tmp, stdin-only handover, key destruction after handover, single-task startup) all pass unchanged.

Emitted YAML bytes change (a binding prelude is added and literals become variable references); behaviour and step ordering do not. Rebased onto main, resolving conflicts with #1858 (hidden export-command docs) and #1843 (Azure DevOps MCP version override — its override path is preserved and still asserted).

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
1 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.