Merge branch 'main' into spofford/windows

Author: adamspofford-dfinity

.claude/CLAUDE.md

@@ -125,7 +125,9 @@ These constants are defined in `crates/icp/src/prelude.rs` as `LOCAL` and `IC` a
 #### Identity & Canister IDs
 
 - **Identities**: Stored in `~/.config/icp/identity/` as PEM files (Secp256k1 or Ed25519)
-- **Canister IDs**: Persisted in `.icp/data/<network-name>/canister_ids.json` within project directories
+- **Canister IDs**: Persisted in `.icp/{cache,data}/mappings/<environment>.ids.json` within project directories
+  - Managed networks (local) use `.icp/cache/mappings/`
+  - Connected networks (mainnet) use `.icp/data/mappings/`
 
 Store management is in `crates/icp/src/store_id.rs`.
 
@@ -193,8 +195,18 @@ The project includes JSON schemas for manifest validation:
 
 ### Docs generation
 
-- The cli reference is generated in `docs/cli-reference.md`.
-- Regenerate the cli reference when commands changes by running: `./scripts/generate-cli-docs.sh`
+- The CLI reference is generated in `docs/reference/cli.md`.
+- Regenerate the CLI reference when commands change by running: `./scripts/generate-cli-docs.sh`
+
+### Documentation Structure
+
+Documentation follows the Diátaxis framework:
+
+- `docs/tutorial.md` — Learning-oriented first deployment guide
+- `docs/guides/` — Task-oriented how-to guides
+- `docs/concepts/` — Understanding-oriented explanations
+- `docs/reference/` — Information-oriented technical specifications
+- `docs/migration/` — Migration guides (e.g., from dfx)
 
 ### Paths
 

CHANGELOG.md

@@ -4,8 +4,9 @@
 * feat: `icp canister metadata <canister> <metadata section>` now fetches metadata sections from specified canisters
 * fix: Validate explicit canister paths and throw an error if `canister.yaml` is not found
 * feat!: Rename the implicit "mainnet" network to "ic"
-  * The corresponding environment "ic" is defined implicitly which can be overwritten by user configuration
+  * The corresponding environment "ic" is defined implicitly which can be overwritten by user configuration.
   * The `--mainnet` and `--ic` flags are removed. Use `-n/--network ic`, `-e/--environment ic` instead.
+* feat: Allow overriding the implicit `local` network and environment.
 
 # v0.1.0-beta.3
 

README.md

@@ -1,112 +1,83 @@
 # icp-cli
 
-A command-line interface for developing and deploying applications on the Internet Computer Protocol (ICP).
+A command-line tool for building and deploying applications on the Internet Computer.
 
-## Usage
+## Quick Start
 
-See the [command line reference](docs/cli-reference.md).
+```bash
+# Install via Homebrew (macOS)
+brew install dfinity/tap/icp-cli
 
-## Installing
+# Create and deploy a project
+icp new my-project && cd my-project
+icp network start -d
+icp deploy
 
-For now, you have to build icp-cli locally in order to use it.
+# Show the status of your canisters
+icp canister status
 
-### Prerequisites
+# Call a function on your canister
+# icp canister call <canister-name> greet '("World")'
+# The ones generated from the templates are typically called `backend`
 
-- **Rust**: Install Rust using [rustup](https://rustup.rs/). The project uses Rust 2024 edition.
-- **mops**: Required if you want to build Motoko canisters. See [mops.one](https://cli.mops.one/).
+icp canister call backend greet '("World")'
+```
 
-### Building
+See the [Installation Guide](docs/guides/installation.md) for all installation methods including building from source.
 
-```bash
-# Build all crates in the workspace
-cargo build
+## For dfx Users
 
-# Add target directory to your path
-export PATH=$(pwd)/target/debug:$PATH
+If you're coming from dfx (the previous Internet Computer SDK), see the **[Migration Guide](docs/migration/from-dfx.md)** for command mappings, workflow differences, and how to migrate existing projects.
 
-# Check that you can run
-icp help
-```
-
-### [Optional] Add motoko tools to the path
+## Documentation
 
-You might also need the Motoko compiler if you plan on building canisters with Motoko. The best way
-is to install mops, the motoko package manager, see: https://cli.mops.one/
+- **[Tutorial](docs/tutorial.md)** — Deploy your first canister
+- **[Guides](docs/guides/index.md)** — How to accomplish common tasks
+- **[Concepts](docs/concepts/index.md)** — Understand how icp-cli works
+- **[Reference](docs/reference/index.md)** — Complete CLI and configuration reference
 
-Reminder, when mops is installed the first time, you must initialize the toolchain with:
+## Examples
 
-```bash
-mops toolchain init
-```
+The [`examples/`](examples/) directory contains example projects to help you get started:
 
-### Examples
+- `icp-motoko/` — Motoko canister
+- `icp-rust/` — Rust canister
+- `icp-static-assets/` — Static website
+- `icp-environments/` — Multi-environment setup
 
-The `examples/` directory contains various project templates and configurations that demonstrate how to use the CLI with different project types:
+[View all examples →](examples/)
 
-- `icp-motoko/` - Motoko canister example
-- `icp-rust/` - Rust canister example  
-- `icp-static-assets/` - Static website deployment
-- `icp-multi-canister/` - Multi-canister project setup
-- And many more...
+## Prerequisites
 
-## Development
+**Language-specific toolchains** (install for the languages you'll use):
+- **Rust canisters** — [Rust](https://rustup.rs/) and `rustup target add wasm32-unknown-unknown`
+- **Motoko canisters** — [mops](https://cli.mops.one/) and `mops toolchain init`
 
-### Prerequisites
+## Getting Help
 
-- **Rust**: Install Rust using [rustup](https://rustup.rs/). The project uses Rust 2024 edition.
+- **[Documentation](docs/index.md)** — Guides, concepts, and reference
+- **[GitHub Issues](https://github.com/dfinity/icp-cli/issues)** — Bug reports and feature requests
+- **[Developer Forum](https://forum.dfinity.org/)** — Questions and discussions
+- **[Discord](https://discord.internetcomputer.org)** — Real-time community chat in #dx-feedback
 
-### Building
+## Contributing
 
-This is a Rust workspace with multiple crates. To build the project:
+Contributions are welcome! See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
 
 ```bash
-# Build all crates in the workspace
+# Build
 cargo build
 
-# Build in release mode for better performance
-cargo build --release
-
-# Build only the CLI binary
-cargo build --bin icp
-```
-
-The compiled binary will be available at `target/debug/icp` (or `target/release/icp` for release builds).
-
-### Running Tests
-
-```bash
+# Test
 cargo test
-```
-
-The network launcher binary is automatically downloaded on first test run. Some tests launch local networks and require available ports.
-
-### Generating CLI Documentation
 
-The project includes automatic CLI documentation generation using `clap_markdown`. To generate comprehensive documentation for all commands:
-
-```bash
-# Run the documentation generation script
+# Generate CLI docs
 ./scripts/generate-cli-docs.sh
-```
 
-This will:
-- Build the CLI in release mode
-- Generate complete markdown documentation at `docs/cli-reference.md`
-
-You can also generate documentation manually:
-
-```bash
-# Build the CLI first
-cargo build --release
-
-# Generate markdown documentation
-./target/release/icp --markdown-help > docs/cli-reference.md
+# Update the yaml file schemas
+./scripts/config-schemas.sh
 ```
 
-## Contributing
-
-Contributions are welcome! Please see the [contribution guide](./.github/CONTRIBUTING.md) for more information.
-
 ## License
 
-This project is licensed under the [Apache-2.0](./LICENSE) license.
+[Apache-2.0](LICENSE)

crates/icp/src/lib.rs

@@ -510,3 +510,169 @@ impl ProjectLoad for NoProjectLoader {
         Ok(false)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::canister::recipe::{Resolve, ResolveError};
+    use crate::manifest::{
+        ProjectRootLocate, ProjectRootLocateError,
+        canister::{BuildSteps, SyncSteps},
+        recipe::Recipe,
+    };
+    use camino_tempfile::Utf8TempDir;
+    use indoc::indoc;
+
+    struct MockProjectRootLocate {
+        path: PathBuf,
+    }
+
+    impl MockProjectRootLocate {
+        fn new(path: PathBuf) -> Self {
+            Self { path }
+        }
+    }
+
+    impl ProjectRootLocate for MockProjectRootLocate {
+        fn locate(&self) -> Result<PathBuf, ProjectRootLocateError> {
+            Ok(self.path.clone())
+        }
+    }
+
+    struct MockRecipeResolver;
+
+    #[async_trait]
+    impl Resolve for MockRecipeResolver {
+        async fn resolve(&self, _recipe: &Recipe) -> Result<(BuildSteps, SyncSteps), ResolveError> {
+            use crate::manifest::adapter::prebuilt::{
+                Adapter as PrebuiltAdapter, LocalSource, SourceField,
+            };
+            use crate::manifest::canister::BuildStep;
+
+            // Create a minimal BuildSteps with a dummy prebuilt step
+            let build_steps = BuildSteps {
+                steps: vec![BuildStep::Prebuilt(PrebuiltAdapter {
+                    source: SourceField::Local(LocalSource {
+                        path: "dummy.wasm".into(),
+                    }),
+                    sha256: None,
+                })],
+            };
+
+            Ok((build_steps, SyncSteps::default()))
+        }
+    }
+
+    #[tokio::test]
+    async fn test_load_minimal_project() {
+        // Create temp directory with icp.yaml
+        let temp_dir = Utf8TempDir::new().unwrap();
+        let project_dir = temp_dir.path();
+
+        // Write a minimal icp.yaml
+        let manifest_content = indoc! {r#"
+            canisters:
+              - name: backend
+                build:
+                  steps:
+                    - type: pre-built
+                      path: backend.wasm
+        "#};
+        std::fs::write(project_dir.join("icp.yaml"), manifest_content).unwrap();
+
+        // Create ProjectLoadImpl with mocks
+        let loader = ProjectLoadImpl {
+            project_root_locate: Arc::new(MockProjectRootLocate::new(project_dir.to_path_buf())),
+            recipe: Arc::new(MockRecipeResolver),
+        };
+
+        // Call load
+        let result = loader.load().await;
+
+        // Assert success and check project contents
+        assert!(result.is_ok());
+        let project = result.unwrap();
+        assert_eq!(project.dir, project_dir);
+        assert!(
+            project.canisters.contains_key("backend"),
+            "The backend canister was not found"
+        );
+        assert!(
+            project.environments.contains_key("local"),
+            "The default `local` environment was not injected"
+        );
+        assert!(
+            project.environments.contains_key("ic"),
+            "The default `ic` environment was not injected"
+        );
+        assert!(
+            project.networks.contains_key("local"),
+            "The default `local` network was not injected"
+        );
+        assert!(
+            project.networks.contains_key("ic"),
+            "The default `ic` network was not injected"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_load_project_local_override() {
+        // Create temp directory with icp.yaml
+        let temp_dir = Utf8TempDir::new().unwrap();
+        let project_dir = temp_dir.path();
+
+        // Write a minimal icp.yaml
+        let manifest_content = indoc! {r#"
+            networks:
+              - name: test-network
+                mode: connected
+                url: https://somenetwork.icp
+            environments:
+              - name: local
+                network: test-network
+            canisters:
+              - name: backend
+                build:
+                  steps:
+                    - type: pre-built
+                      path: backend.wasm
+        "#};
+        std::fs::write(project_dir.join("icp.yaml"), manifest_content).unwrap();
+
+        // Create ProjectLoadImpl with mocks
+        let loader = ProjectLoadImpl {
+            project_root_locate: Arc::new(MockProjectRootLocate::new(project_dir.to_path_buf())),
+            recipe: Arc::new(MockRecipeResolver),
+        };
+
+        // Call load
+        let result = loader.load().await;
+
+        // Assert success and check project contents
+        assert!(result.is_ok(), "The project did not load: {:?}", result);
+        let project = result.unwrap();
+        assert_eq!(project.dir, project_dir);
+        assert!(
+            project.canisters.contains_key("backend"),
+            "The backend canister was not found"
+        );
+        assert!(
+            project.environments.contains_key("local"),
+            "The default `local` environment was not injected"
+        );
+        let e = project.environments.get("local").unwrap();
+        assert_eq!(e.network.name, "test-network");
+        assert!(
+            project.environments.contains_key("ic"),
+            "The default `ic` environment was not injected"
+        );
+        assert!(
+            project.networks.contains_key("local"),
+            "The default `local` network was not injected"
+        );
+        assert!(
+            project.networks.contains_key("ic"),
+            "The default `ic` network was not injected"
+        );
+    }
+}