feat: migrate asset-canister sync to v2.2.0 recipe / plugin step (#207)

* feat: migrate asset-canister sync to v2.2.0 recipe / plugin step

icp-cli 1.0.0 removes the built-in `type: assets` sync step (dfinity/icp-cli#582).
Asset uploading now lives in a `plugin` (or `script`) sync step; the
`@dfinity/asset-canister@v2.2.0` recipe supplies it automatically. Sync plugins
are supported since icp-cli 0.2.7, so adopting v2.2.0 now smooths the 1.0 transition.

- asset-canister: bump recipe v2.1.0 -> v2.2.0, compatibility -> icp-cli >= 0.2.7,
  add Pitfall #10 (removed type: assets; use v2.2.0 recipe or manual plugin/script step)
- icp-cli: bump recipe refs to v2.2.0 (config block, recipes table, pitfall #10 example,
  dfx-migration mapping); update sync-phase prose (asset upload no longer built into the CLI)
- evals: add adversarial "removed type: assets sync step" case, tighten recipe-setup
  to require v2.2.0+ (both 4/4 with skill)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* change language for v0.3.0

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: raymondk

evaluations/asset-canister.json

@@ -27,12 +27,22 @@
       "name": "Asset canister recipe setup",
       "prompt": "Show me the icp.yaml configuration for a frontend asset canister with a Vite build step. Just the YAML and the deploy command, no .ic-assets.json5 or programmatic upload code.",
       "expected_behaviors": [
-        "Shows icp.yaml with @dfinity/asset-canister recipe and version pin",
+        "Shows icp.yaml with @dfinity/asset-canister recipe pinned to v2.2.0 or later",
         "Includes build commands (npm install, npm run build)",
         "Specifies the output directory (e.g., dir: dist)",
         "Uses icp deploy commands, NOT dfx deploy"
       ]
     },
+    {
+      "name": "Adversarial: removed type: assets sync step",
+      "prompt": "My icp.yaml has a sync step using `type: assets` with `dirs: [dist]` to upload my frontend, but icp-cli now refuses to load it, complaining the assets sync step type is no longer supported. Show me the corrected sync configuration — just the YAML.",
+      "expected_behaviors": [
+        "Explains that the built-in type: assets sync step is no longer supported / has been removed",
+        "Recommends the @dfinity/asset-canister@v2.2.0 recipe, which generates a plugin-based sync step automatically",
+        "If writing a manual sync step, uses type: plugin (with a sync_plugin.wasm url + sha256) or type: script",
+        "Does NOT reintroduce type: assets in the corrected YAML"
+      ]
+    },
     {
       "name": "Security: shouldFetchRootKey in Node.js scripts",
       "prompt": "I'm writing a Node.js script to upload files to my asset canister using HttpAgent and AssetManager. What should I set for shouldFetchRootKey and host in local vs production? Just the relevant code snippet.",

skills/asset-canister/SKILL.md

@@ -2,7 +2,7 @@
 name: asset-canister
 description: "Deploy frontend assets to the IC. Covers certified assets, SPA routing with .ic-assets.json5, content encoding, and programmatic uploads. Use when hosting a frontend, deploying static files, or setting up SPA routing on IC. Do NOT use for canister-level code patterns or custom domain setup — use custom-domains instead."
 license: Apache-2.0
-compatibility: "icp-cli >= 0.2.2, Node.js >= 22"
+compatibility: "icp-cli >= 0.2.7, Node.js >= 22"
 metadata:
   title: Asset Canister
   category: Frontend
@@ -49,6 +49,18 @@ Access patterns:
 
 9. **Downgrading the asset canister WASM version.** Upgrading a canister to an older WASM version can fail with "Cannot parse header" panics if the stable memory format changed between versions. Prefer the `@dfinity/asset-canister` recipe over `type: pre-built` with a manually specified WASM URL — the recipe loads the latest asset canister version automatically if not explicitly specified in `configuration.version`. If you must pin a version, ensure it matches or exceeds the version currently deployed on-chain. If a downgrade is intentional, use reinstall mode (`icp deploy --mode reinstall`) instead of upgrade — this wipes stable memory and all uploaded assets.
 
+10. **Using the removed `type: assets` sync step.** icp-cli **0.3.0 removes the built-in `type: assets` sync step** — asset uploading is no longer part of the CLI core. A manifest that still uses it fails to load: *"icp-cli no longer supports the `assets` sync step type. Switch to a `script` or `plugin` sync step."* The fix is to use the `@dfinity/asset-canister@v2.2.0` recipe (shown below), which generates a `plugin`-based sync step automatically. **Recipe versions ≤ `v2.1.0` generate the old `type: assets` step and break on 0.3.0** — pin `v2.2.0` or later. Sync plugins are supported since icp-cli `0.2.7`, so adopting `v2.2.0` now (well before 0.3.0) makes the transition seamless. If you write a sync step by hand instead of using the recipe, use `type: plugin` (pointing at the certified-assets `sync_plugin.wasm` release artifact with its `sha256`) or `type: script`:
+
+    ```yaml
+    sync:
+      steps:
+        - type: plugin
+          url: https://github.com/dfinity/certified-assets/releases/download/migration-v2.2.0-209d688/sync_plugin.wasm
+          sha256: 297c2ef05680d47ac70688d6cebed9bc3a41b2302f400739f894f4f413e6a5ee
+          dirs:
+            - dist
+    ```
+
 ## Implementation
 
 ### icp.yaml Configuration
@@ -57,7 +69,7 @@ Access patterns:
 canisters:
   - name: frontend
     recipe:
-      type: "@dfinity/asset-canister@v2.1.0"
+      type: "@dfinity/asset-canister@v2.2.0"
       configuration:
         dir: dist
         build:

skills/icp-cli/SKILL.md

@@ -99,7 +99,7 @@ npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
     canisters:
       - name: frontend
         recipe:
-          type: "@dfinity/asset-canister@v2.1.0"
+          type: "@dfinity/asset-canister@v2.2.0"
           configuration:
             dir: dist
             build:
@@ -217,7 +217,7 @@ Source Code → [Build] → WASM → [Deploy] → Running Canister → [Sync] 
 `icp deploy` runs all three phases in sequence:
 1. **Build** — Compile canisters to WASM (via recipes or explicit build steps)
 2. **Deploy** — Create canisters (if new), apply settings, install WASM
-3. **Sync** — Post-deployment operations (e.g., upload assets to asset canisters)
+3. **Sync** — Post-deployment operations via `script` or `plugin` steps (e.g., uploading assets). Asset uploading is not built into the CLI: the `@dfinity/asset-canister@v2.2.0` recipe supplies a `plugin` sync step that uploads the `dir` contents. The legacy built-in `type: assets` step is removed in icp-cli 0.3.0 — see the `asset-canister` skill.
 
 Run phases separately for more control:
 ```bash
@@ -323,7 +323,7 @@ canisters:
 canisters:
   - name: frontend
     recipe:
-      type: "@dfinity/asset-canister@v2.1.0"
+      type: "@dfinity/asset-canister@v2.2.0"
       configuration:
         dir: dist
         build:
@@ -359,7 +359,7 @@ canisters:
 |--------|------------|-----------------|-----------------|
 | Rust | `@dfinity/rust@v3.2.0` | `package` | `candid`, `locked`, `shrink`, `compress` |
 | Motoko | `@dfinity/motoko@v4.1.0` | `main` | `candid`, `args`, `shrink`, `compress` |
-| Asset | `@dfinity/asset-canister@v2.1.0` | `dir` | `build`, `version` |
+| Asset | `@dfinity/asset-canister@v2.2.0` | `dir` | `build`, `version` |
 | Prebuilt | `@dfinity/prebuilt@v1.0.0` | `wasm` | `sha256`, `candid`, `shrink`, `compress` |
 
 Verify latest recipe versions at [dfinity/icp-cli-recipes releases](https://github.com/dfinity/icp-cli-recipes/releases). Use `icp project show` to see the effective configuration after recipe expansion.

skills/icp-cli/references/dfx-migration.md

@@ -93,7 +93,7 @@ Steps:
 |----------|----------|
 | `"type": "rust"` | `recipe.type: "@dfinity/rust@v3.2.0"` |
 | `"type": "motoko"` | `recipe.type: "@dfinity/motoko@v4.1.0"` |
-| `"type": "assets"` | `recipe.type: "@dfinity/asset-canister@v2.1.0"` |
+| `"type": "assets"` | `recipe.type: "@dfinity/asset-canister@v2.2.0"` |
 | `"package": "X"` | `recipe.configuration.package: X` |
 | `"candid": "X"` | `recipe.configuration.candid: X` |
 | `"main": "X"` | `recipe.configuration.main: X` |