feat(cli): enforce operator init distro

[joshuajbouw]

Linked Issue

Closes #1253

Summary

Adds a neutral embedding boundary for distributions that ship Astrid Runtime. A
launcher can select the distro used by astrid init without copying Astrid's
argument grammar, and Astrid rejects a simultaneous caller --distro override.

Standalone Astrid remains distro-neutral and still requires an explicit distro
when no launcher selection is present.

Changes

• resolve ASTRID_ENFORCED_DISTRO at init dispatch
• reject caller --distro whenever an embedding launcher supplies the environment value
• preserve standalone Astrid's explicit --distro requirement when the value is absent
• fail closed on empty or non-UTF-8 enforced-distro values
• retain checked distro provisioning, separate operator/target principal handling, and the --grant-capsules path
• cover neutral, enforced, override-rejection, malformed-value, leading-global-option, operator-vs-target, and enforced-distro-plus-capsule-grant cases
• import the CLI parser trait required by the dispatch regression module
• document the additive embedding hook under [Unreleased]
• correct init and distro apply help/errors to list only supported source forms
• split distro-specific parser/help regressions into a test module so cli.rs stays under the source-file cap
• pin the exact distro-source help contract so unsupported bare-name guidance cannot return unnoticed
• reject explicitly empty init and distro apply sources at the shared dispatch boundary

Security boundary

ASTRID_ENFORCED_DISTRO is process input, not a privileged Astrid security
boundary. An embedding launcher must overwrite any inherited value before
executing Astrid. A caller invoking standalone Astrid can set its own process
environment; the hook selects product composition but grants no Astrid authority.

Verification

• exact signed restack head: fd4f4a92578b06c76f5253025683b529e883f5ec
• base: merged main at f255e5fe53fc1f7131888706273e59ff3b54d4c5
• the three implementation commits are patch-identical to reviewed preview ac74f152; all seven commits carry GPG signatures
• cargo fmt --all -- --check
• cargo metadata --locked --no-deps --format-version 1
• git diff --check origin/main..HEAD
• cargo test -p astrid distro -- --nocapture (86 passed)
• cargo test -p astrid cli:: -- --nocapture (14 passed)
• cargo test -p astrid dispatch::tests:: -- --nocapture (9 passed)
• cargo test -p astrid commands::init::tests::distro_source_resolution -- --nocapture (4 passed)
• cargo clippy -p astrid --all-targets --all-features -- -D warnings
• file-size policy: cli.rs 955 lines; cli_distro_tests.rs 101 lines under the test cap
• independent exact-head review requested; refreshed GitHub CI is the final execution gate

Checklist

• Linked to an issue
• CHANGELOG.md updated under [Unreleased]

No release is created or published by this change.

[Copilot]

Pull request overview

This PR adds an operator-controlled boundary for astrid init so embedded distributions can enforce an init distro via ASTRID_ENFORCED_DISTRO, preventing callers from overriding it while preserving standalone Astrid’s requirement for an explicit --distro when no operator value is present.

Changes:

• Resolve ASTRID_ENFORCED_DISTRO during astrid init dispatch and reject any CLI --distro override when it’s set.
• Add targeted unit tests for neutral/enforced/override-rejection and malformed operator values, plus a CLI parsing regression for leading global options.
• Document the new operator hook in the changelog under [Unreleased].

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
crates/astrid-cli/src/dispatch.rs	Adds ASTRID_ENFORCED_DISTRO resolution logic for init and unit tests covering enforced/neutral/invalid cases.
crates/astrid-cli/src/cli.rs	Adds a parsing regression test ensuring global options before init don’t interfere with --distro.
CHANGELOG.md	Documents the new operator-enforced init distro hook under [Unreleased].

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[joshuajbouw]

@copilot review exact head be84f92

[Copilot]

@copilot review exact head be84f92

Reviewed be84f92. One compile error found and fixed (commit fix(cli): import clap::Parser in dispatch test module):

crates/astrid-cli/src/dispatch.rs, test module — Cli::try_parse_from requires clap::Parser to be in scope. The dispatch.rs test module imported super::* but not the trait, so the operator_distro_and_targeted_capsule_grants_compose test failed to compile with E0599. Added use clap::Parser; alongside use super::*;, matching how the cli.rs test module is structured.

cargo test -p astrid — 476 tests, all passing. cargo +nightly fmt --all -- --check — clean.

[joshuajbouw]

@copilot review exact head 2981acc

[Copilot]

@copilot review exact head 2981acc

Reviewed 2981acc. This head is the accepted one-line fix: use clap::Parser; added to the dispatch.rs test module. No issues found.

cargo test -p astrid — 476 tests, all passing. cargo +nightly fmt --all -- --check — clean.

[joshuajbouw]

@copilot review exact head 1a55953

[Copilot]

@copilot review exact head 1a55953

Reviewed 1a55953. The new commit adds operator_distro_and_targeted_capsule_grants_compose as a standalone test — it parses the CLI, resolves the enforced distro, and asserts --target-principal and --grant-capsules compose correctly. No issues found.

cargo test -p astrid — 477 tests, all passing. cargo +nightly fmt --all -- --check — clean.

[joshuajbouw]

@copilot review exact head 684d069

[Copilot]

@copilot review exact head 684d069

Reviewed 684d069. This head corrects distro source guidance throughout — help text, error messages, and test values now consistently use @owner/repo, URL, local Distro.toml, and .shuttle instead of the legacy "name, @org/repo, path" phrasing. A new test distro_help_lists_only_supported_sources_and_the_launcher_exception asserts the rendered help contains every supported form and rejects bare names. No issues found.

cargo test -p astrid cli::tests:: — 14 passed. cargo test -p astrid dispatch::tests:: — 9 passed. cargo +nightly fmt --all -- --check — clean.

[joshuajbouw]

@copilot review exact head 8a701c9

[Copilot]

@copilot review exact head 8a701c9

Reviewed 8a701c9. The commit moves the four distro-specific CLI contract tests (grant_capsules_allows_an_operator_enforced_distro, distro_help_lists_only_supported_sources_and_the_launcher_exception, init_parses_target_separately_from_operator, global_options_before_init_preserve_the_requested_distro) out of cli.rs into a new cli_distro_tests.rs file, keeping cli.rs under the source-file cap. The new file is included via #[path = "cli_distro_tests.rs"] mod distro_tests; and the tests run under cli::distro_tests::. The refactored distro_help_lists_only_supported_sources_and_the_launcher_exception test also gains coverage of apply help text (asserting ASTRID_ENFORCED_DISTRO is absent there), which is a net improvement over the previous version. No issues found.

cargo test -p astrid cli:: — 14 passed. cargo test -p astrid dispatch::tests:: — 9 passed. cargo +nightly fmt --all -- --check — clean.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.