feat: declare canister dependencies from another icp project

[lwshang]

Summary

Adds a top-level dependencies: block to icp.yaml so a project can depend on another icp project vendored into it (typically as a git submodule). icp deploy then deploys the dependency's canisters into the same environment and wires their IDs into your canisters as PUBLIC_CANISTER_ID:<alias>:<canister> environment variables.

# app/icp.yaml
dependencies:
  - name: openemail          # local alias
    path: ./vendor/openemail # dir containing the dependency's icp.yaml
    canisters: [backend]     # which of its canisters to expose (omit for all)

Running icp deploy in app/ builds/creates/installs the app's canisters and the dependency's, then injects e.g. PUBLIC_CANISTER_ID:openemail:backend into the app's canisters. The dependency's icp.yaml stays self-contained and can still be deployed on its own.

Behavior

• Deploy-all, expose-subset. The whole dependency is always deployed (its canisters may call each other, and icp-cli has no intra-project "requires" graph). canisters: only filters which dependency IDs are exposed to the parent.
• Per-project env-var views. Each canister sees the view its owning project expects: its own canisters by their local names, plus declared dependencies under their aliases. So a dependency's canisters behave identically whether deployed standalone or as a dependency, and the parent only sees the dependency canisters it selected. (A dependency-free project is unchanged: every canister still sees every sibling.)
• Shared dependencies de-duplicate by resolved directory. In the "umbrella" layout — sibling submodules service-a, service-b, and openemail, where both services depend on ../openemail — the two edges resolve to the same directory, so openemail is deployed once and shared by both.
• Store keys are path-based. Because two projects can each define a canister with the same name, imported canisters are keyed by their path relative to the project root (e.g. vendor/openemail:backend). Aliases drive only env-var names. Cycles are detected.

Implementation

Commit-by-commit:

1. feat(manifest) — the dependencies: manifest type + JSON schema.
2. feat(project) — recursive consolidation: import-all, path-based store keys, diamond de-dup by canonical directory, cycle detection, per-project PUBLIC_CANISTER_ID bindings, : name/alias validation, and translation of dependency canisters' name-based controller refs.
3. feat(deploy) — inject env vars from each canister's per-project bindings; percent-encode namespaced names in the artifact store so they are valid filenames.
4. fix(url) — namespaced canister names fall back to the principal host when printing URLs (not valid DNS labels).
5. docs(deps) — examples/icp-project-dependency, an integration test, canister-discovery docs, CHANGELOG.
6. test(deps) — examples/icp-project-dependency-shared (umbrella layout) + a shared-dependency integration test.

Testing

• Unit tests for consolidation: single-project flat behavior, import + exposure subset, umbrella diamond → single shared instance, cycle detection, and every validation error.
• Two integration tests deploy to a real managed network and assert the injected env vars (single-dependency and the shared/umbrella layout, verifying both services resolve openemail:backend to the same shared canister).
• No regressions across the canister_settings, deploy, bundle, build, and project suites; fmt/clippy clean.

Not in scope (design leaves room for these)

Pinned/already-deployed dependencies (an additive per-network pin:), candid/binding generation (each canister sources its own bindings), and per-canister depends_on.

🤖 Generated with Claude Code