feat: target cloud engines by name with --engine

[raymondk]

Summary

icp deploy and icp canister create take --engine <name> to target a cloud engine by name. The name is resolved to the engine's subnet through the engine canister (q6cfj-fyaaa-aaaar-qb77q-cai on mainnet, ENGINE_CANISTER_ID overrides it), and the command then behaves exactly as --subnet would with that subnet.

• --engine <name> calls listVisibleEngines, drops deleted engines, fetches getEngineMetadata for the rest, and matches the input against an engine's name, its id, or name/slug.
• --engine <subnet-id> is --subnet <subnet-id>: a principal is taken to be the subnet itself, with no lookup.
• --engine conflicts with --subnet and --proxy, and on deploy with --no-create, exactly like --subnet.
• Errors are specific: a name nobody can see lists the engines the identity can see (or says it sees none), a name shared by several engines lists each with slug and id, an engine with no subnet yet is refused, and a network without the engine canister says so.
• On deploy a named engine is resolved before the build so a bad name fails fast.

Code

• crates/icp-cli/src/engine.rs (new): EngineSelector (the clap value type), resolve_subnet and its error enum, with unit tests against a fake CanisterCalls.
• icp-canister-interfaces::engine_canister: Candid types for Engine, EngineMetadata, EngineError and MetadataResult, taken from the canister's live candid:service on mainnet, plus the two method names.
• CallError::is_canister_not_found in icp-project: the check the engine-operator lookup already did, moved onto the error type so both lookups share it.

The engine canister id stays hard-coded (with the existing env override). A per-network setting is left for a follow-up.

Test plan

• Unit tests: cargo test -p icp-cli --bin icp engine, cargo test -p icp-canister-interfaces, cargo test -p icp-project (default and --no-default-features)
• Integration: canister_create_on_requested_engine (creates on the given subnet via --engine <subnet-id> on a multi-subnet local network, then checks the named-engine refusal where no engine canister exists), the clap conflict tests for both commands, and the existing Docker deploy_cloud_engine / canister_create_cloud_engine tests
• cargo clippy --all-targets, cargo fmt --check, wasm32 clippy for icp-project, scripts/check-no-host-reach.sh
• scripts/generate-cli-docs.sh regenerated docs/reference/cli.md
• Manual: icp deploy -e ic --engine <your engine> against mainnet with an identity that can see an engine

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Exact engine IDs can incorrectly produce ambiguity errors when they match another engine’s name.

Review effort: Balanced
Findings: 1

Open (1)

• Prioritize exact engine ID matches over name matches · New

What changed in this PR

Adds cloud-engine targeting by name to canister creation and deployment, reusing existing subnet placement behavior.

Changes:

• Adds --engine resolution, subnet-ID passthrough, and argument conflicts.
• Introduces engine registry interfaces and shared missing-canister detection.
• Adds tests and documents engine selection.

File	Description
docs/​reference/​environment-variables.md	Documents the registry override.
docs/​reference/​cli.md	Documents --engine options.
docs/​guides/​deploying-to-specific-subnets.md	Adds cloud-engine examples.
crates/​icp-project/​src/​operations/​create.rs	Uses shared missing-canister detection.
crates/​icp-project/​src/​calls.rs	Adds shared detection and tests.
crates/​icp-cli/​tests/​deploy_tests.rs	Tests argument conflicts.
crates/​icp-cli/​tests/​canister_create_tests.rs	Tests subnet passthrough and lookup errors.
crates/​icp-cli/​src/​main.rs	Registers the engine module.
crates/​icp-cli/​src/​engine.rs	Implements engine selection and resolver tests.
crates/​icp-cli/​src/​commands/​deploy.rs	Resolves engines before building.
crates/​icp-cli/​src/​commands/​canister/​create.rs	Integrates engine targeting.
crates/​icp-canister-interfaces/​src/​engine_canister.rs	Adds registry types and override tests.
CHANGELOG.md	Announces engine targeting.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.