@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/vite-wallet/README.md

@@ -0,0 +1,107 @@
+# ICP wallet on ic-reactor 4
+
+A React and Vite wallet on a local icp-cli network: the NNS ICP ledger, a
+Rust `backend` canister of its own (a profile and an address book per
+caller), and Internet Identity. One client per tab,
+`createClient({ network: "env", auth })`, and TanStack Query's own hooks with
+the options the client builds. Every scenario below is a small file whose
+header names the rule it shows, and each has tests.
+
+## Scenarios
+
+| #   | Scenario                                                                                                                                                                                                                                                 | Files                                                                                  | See it                                                                                                 |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| 1   | `network: "env"`; the backend as `{ name: "backend" }` from the `ic_env` cookie the Vite plugin sets (with its `/api` proxy), the ledger by `{ id }`                                                                                                     | `src/client.ts`, `src/use-canisters.ts`, `src/EnvironmentPanel.tsx`                    | "Network and canisters": the origin, the id the client resolved, the cookie                            |
+| 2   | Internet Identity through `@icp-sdk/auth` 10's `AuthClient`, built from the network the client hands its `auth` factory: the local II on a local page                                                                                                    | `src/client.ts`                                                                        | "Sign in with Internet Identity": a window on the local II, which asks for a seed index, not a passkey |
+| 3   | A sign-in of the app's own as an `AuthLike` (dev account, local only) beside II behind one `auth`; a switch shows the next account nothing of the last                                                                                                   | `src/auth/dev-accounts.ts`, `src/auth/wallet-auth.ts`, `src/SignIn.tsx`, `src/App.tsx` | "Sign in with a dev account", "New dev account", then switch back and forth                            |
+| 4   | Balance with `skipToken` while signed out and `refetchInterval` spread onto the client's options                                                                                                                                                         | `src/Balance.tsx`                                                                      | `pnpm faucet <principal>` in a terminal: the balance changes within 3 s                                |
+| 5   | Send ICP: `parseUnits` input, the fee, a `memo` per transfer and `created_at_time`, typed `canister_err`, and `mayHaveExecuted` (outcome unknown, the client's re-read, "send the same transfer again", offered by `client.resendOf` to its sender only) | `src/SendIcp.tsx`, `src/transfer.ts`                                                   | Send; type `1e3` (refused before sending); send more than you hold (`InsufficientFunds`)               |
+| 6   | Profile reads and writes as the caller; a write while signed out is refused `unauthenticated`                                                                                                                                                            | `src/Profile.tsx`                                                                      | Save a name; save a long one (the backend's `Err`); sign out and save                                  |
+| 7   | Optimistic add and remove that keep the client's `onMutate` and `onSettled`, rolled back on `canister_err` or a failure; the list is a certified read, since a contact decides where a payment goes                                                      | `src/optimistic-contacts.ts`, `src/AddressBook.tsx`, `src/use-canisters.ts`            | Add a contact; add the same name in another case (`DuplicateName`: shown, then rolled back)            |
+| 8   | Paying a contact: which reads the write changes (the ledger's, not the backend's)                                                                                                                                                                        | `src/SendToContact.tsx`                                                                | "Pay": your balance and the contact's both change                                                      |
+| 9   | A production build of the same code                                                                                                                                                                                                                      | `vite.config.ts`                                                                       | `pnpm build && pnpm preview`, http://localhost:5185                                                    |
+| 10  | The production build on an asset canister: a Content-Security-Policy that runs the app's own files only, a `Cross-Origin-Opener-Policy` that keeps the II window, the `hardened` headers, and the raw host redirected                                    | `public/.ic-assets.json5`, `icp.yaml`                                                  | `pnpm icp:deploy`, then http://frontend.local.localhost:8000 (and `curl -sI` on it)                    |
+
+The unknown outcome of scenario 5 and the trap of scenario 7 need a fault a
+local network does not make on demand: the tests inject them.
+
+## Run it
+
+You need Node 22.18 or later, and for the backend the Rust toolchain with the
+`wasm32-unknown-unknown` target and `ic-wasm` on your PATH (what icp-cli's
+Rust recipe calls). icp-cli 1.2.0 itself is a devDependency of this example.
+From the repository root, `pnpm install` and `pnpm build`, then:
+
+```sh
+cd examples/vite-wallet
+pnpm icp:start                   # local network on port 8000, with II and the NNS
+pnpm icp:deploy                  # builds and deploys the backend and the app
+pnpm faucet <principal> [amount] # sends local ICP (10 by default) to a principal
+pnpm dev                         # http://localhost:5175
+pnpm icp:stop                    # when you are done
+```
+
+Open http://localhost:5175, sign in with a dev account, and copy the
+`pnpm faucet ...` line the Balance panel shows into a terminal. The faucet
+sends from icp-cli's anonymous identity, which every local network funds.
+Dev accounts live in the tab's sessionStorage: a reload keeps them, a new tab
+starts with none. The balance is read again every 3 s while the tab is
+visible (TanStack Query pauses `refetchInterval` in a hidden tab, and reads
+again when it is shown).
+
+`pnpm icp:deploy` also builds the app and serves it from an asset canister
+at http://frontend.local.localhost:8000, with the response headers of
+`public/.ic-assets.json5` (scenario 10); the docs guide "Deploy to a
+frontend canister" says what each one does. Sign in there with a dev
+account: the asset canister's `ic_env` cookie names no Internet Identity, so
+the II button opens mainnet's, not the local one.
+
+"Sign in with Internet Identity" opens the local II in a new window. It is a
+test build that makes no passkey: choose Create, then "Create with passkey",
+name the identity, and answer its "Enter seed index" prompt with a number.
+Continue returns you to the wallet, signed in, and the session survives a
+reload. Next time, Continue as the identity it remembers and give the same
+number: the principal is the same.
+
+## Test it
+
+```sh
+pnpm test       # every scenario, on createTestClient(): no replica, no network
+pnpm typecheck
+pnpm build
+pnpm gen:check  # fails if src/canisters/ is stale
+```
+
+The tests run a real client over the in-memory replica of
+`@ic-reactor/core/testing`, with the ledger and the backend mocked per caller
+(`src/test/test-wallet.tsx`), in jsdom, whose page carries an `ic_env` cookie
+like the plugin's. `src/canisters/` is generated from `backend/backend.did` and
+`ledger.did` by `@ic-reactor/vite-plugin` on every `vite dev` and `vite build`
+(`pnpm gen` runs `meant gen` by hand), committed, and never edited. `ledger.did`
+is the projection of the mainnet ICP ledger's interface to the five methods the
+wallet calls (the ledger entry's `methods` in `vite.config.ts`), as the plugin
+wrote it from the live canister. It is committed, so builds read it and make no
+request. `IC_REACTOR_FETCH=ledger` writes it again from the canister, and
+`IC_REACTOR_VERIFY=ledger pnpm build` checks it against the live ledger.
+
+## The env network in production
+
+`vite build` writes static files, and the code does not change for a deployed
+page: with `network: "env"` it calls its own origin's `/api`, which an asset
+canister's domain (`<id>.icp0.io`) serves as the dev server's proxy does
+locally. What changes is the cookie. An asset canister sets an `ic_env`
+cookie too. On `<id>.icp0.io`, a public suffix no other canister can set a
+cookie for, ic-reactor believes its canister ids (never its root key); on
+`<id>.ic0.app` and a custom domain it does not, because a sibling subdomain
+can write a cookie there, so `{ name: "backend" }` stays unresolved and its
+calls are refused before sending (`invalid_args`, code
+`canister_id_unresolved`). For a build that works on every domain, give it
+the id instead, as
+`{ id: import.meta.env.VITE_BACKEND_ID }`. `allowEnvConfig: true` is safe only
+on `<id>.icp0.io`, a public suffix, or a custom domain whose every subdomain is
+yours; on `ic0.app` `createClient` refuses it, because any other canister's
+page can set the cookie there. Even with it, the cookie's root key is not
+used on mainnet. The root key
+there is mainnet's, built into the agent; nothing is fetched. Internet
+Identity is mainnet's (the `AuthClient` defaults), and the dev account is not
+offered.

package/examples/vite-wallet/backend/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "backend"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+candid = "0.10.24"
+ic-cdk = "0.19.0"
+serde = { version = "1.0.228", features = ["derive"] }

package/examples/vite-wallet/backend/backend.did

@@ -0,0 +1,37 @@
+// The wallet's own canister: per caller, a profile name and an address book.
+// Every method reads or writes the caller's own entry. The anonymous
+// principal has none, and every write it sends is refused.
+
+type Contact = record {
+  name : text;
+  owner : principal;
+};
+
+type Profile = record {
+  name : text;
+};
+
+// Why a write was refused. ic-reactor rejects such a reply as a
+// `canister_err`, with this value in its `err`.
+type Refusal = variant {
+  // The caller is the anonymous principal.
+  Anonymous;
+  // The name is empty, longer than 32 characters, or has a control character.
+  InvalidName : text;
+  // The address book already has a contact of this name.
+  DuplicateName : text;
+  // The address book has no contact of this name.
+  NotFound : text;
+  // The address book holds at most this many contacts.
+  Full : nat32;
+};
+
+service : {
+  // The caller's profile, or null before their first set_name.
+  get_profile : () -> (opt Profile) query;
+  set_name : (text) -> (variant { Ok : Profile; Err : Refusal });
+  // The caller's contacts, in the order they were added.
+  contacts : () -> (vec Contact) query;
+  add_contact : (Contact) -> (variant { Ok; Err : Refusal });
+  remove_contact : (text) -> (variant { Ok; Err : Refusal });
+}

package/examples/vite-wallet/backend/src/lib.rs

@@ -0,0 +1,133 @@
+//! The wallet's backend: per caller, a profile name and an address book.
+//!
+//! The interface is written out by hand in `backend.did`, which the build
+//! embeds as the `candid:service` metadata and the app generates its module
+//! from, so a method added here must be added there too.
+//!
+//! State lives on the heap and starts over on an upgrade: enough for a local
+//! demo, not for a canister that keeps users' data.
+
+use std::cell::RefCell;
+use std::collections::BTreeMap;
+
+use candid::{CandidType, Deserialize, Principal};
+
+#[derive(CandidType, Deserialize, Clone)]
+struct Contact {
+    name: String,
+    owner: Principal,
+}
+
+#[derive(CandidType, Deserialize, Clone)]
+struct Profile {
+    name: String,
+}
+
+/// Why a write was refused: the `Err` arm of every write's result.
+#[derive(CandidType, Deserialize)]
+enum Refusal {
+    Anonymous,
+    InvalidName(String),
+    DuplicateName(String),
+    NotFound(String),
+    Full(u32),
+}
+
+#[derive(Default)]
+struct Entry {
+    profile: Option<Profile>,
+    contacts: Vec<Contact>,
+}
+
+const MAX_NAME_CHARS: usize = 32;
+const MAX_CONTACTS: u32 = 20;
+
+thread_local! {
+    static ENTRIES: RefCell<BTreeMap<Principal, Entry>> = RefCell::default();
+}
+
+/// The caller, unless it is the anonymous principal, which owns nothing here.
+fn signed_caller() -> Result<Principal, Refusal> {
+    let caller = ic_cdk::api::msg_caller();
+    if caller == Principal::anonymous() {
+        Err(Refusal::Anonymous)
+    } else {
+        Ok(caller)
+    }
+}
+
+/// `name` without surrounding spaces, or why it is refused.
+fn checked_name(name: &str) -> Result<String, Refusal> {
+    let name = name.trim();
+    let length = name.chars().count();
+    if length == 0 || length > MAX_NAME_CHARS || name.chars().any(char::is_control) {
+        return Err(Refusal::InvalidName(format!(
+            "a name is 1 to {MAX_NAME_CHARS} characters, with no control characters"
+        )));
+    }
+    Ok(name.to_string())
+}
+
+#[ic_cdk::query]
+fn get_profile() -> Option<Profile> {
+    let caller = ic_cdk::api::msg_caller();
+    ENTRIES.with_borrow(|entries| entries.get(&caller)?.profile.clone())
+}
+
+#[ic_cdk::update]
+fn set_name(name: String) -> Result<Profile, Refusal> {
+    let caller = signed_caller()?;
+    let profile = Profile {
+        name: checked_name(&name)?,
+    };
+    ENTRIES.with_borrow_mut(|entries| {
+        entries.entry(caller).or_default().profile = Some(profile.clone());
+    });
+    Ok(profile)
+}
+
+#[ic_cdk::query]
+fn contacts() -> Vec<Contact> {
+    let caller = ic_cdk::api::msg_caller();
+    ENTRIES.with_borrow(|entries| {
+        entries
+            .get(&caller)
+            .map(|entry| entry.contacts.clone())
+            .unwrap_or_default()
+    })
+}
+
+#[ic_cdk::update]
+fn add_contact(contact: Contact) -> Result<(), Refusal> {
+    let caller = signed_caller()?;
+    let name = checked_name(&contact.name)?;
+    ENTRIES.with_borrow_mut(|entries| {
+        let book = &mut entries.entry(caller).or_default().contacts;
+        if book.iter().any(|c| c.name.to_lowercase() == name.to_lowercase()) {
+            return Err(Refusal::DuplicateName(name));
+        }
+        if book.len() >= MAX_CONTACTS as usize {
+            return Err(Refusal::Full(MAX_CONTACTS));
+        }
+        book.push(Contact {
+            name,
+            owner: contact.owner,
+        });
+        Ok(())
+    })
+}
+
+#[ic_cdk::update]
+fn remove_contact(name: String) -> Result<(), Refusal> {
+    let caller = signed_caller()?;
+    ENTRIES.with_borrow_mut(|entries| {
+        let book = &mut entries.entry(caller).or_default().contacts;
+        let before = book.len();
+        book.retain(|c| c.name != name);
+        if book.len() == before {
+            Err(Refusal::NotFound(name))
+        } else {
+            Ok(())
+        }
+    })
+}

package/examples/vite-wallet/icp.yaml

@@ -0,0 +1,44 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/dfinity/icp-cli/refs/tags/v1.2.0/docs/schemas/icp-yaml-schema.json
+
+# The wallet's local canisters, for the icp-cli 1.2.0 this example installs
+# (`pnpm icp:start`, `pnpm icp:deploy`, `pnpm icp:stop`).
+
+canisters:
+  # The app's own canister. A project canister, so `icp deploy` gives it an
+  # id and @ic-reactor/vite-plugin puts that id in the ic_env cookie as
+  # PUBLIC_CANISTER_ID:backend: the app calls it as { name: "backend" }.
+  - name: backend
+    recipe:
+      type: "@dfinity/rust@v3.2.0"
+      configuration:
+        package: backend
+        candid: backend/backend.did
+        locked: true
+
+  # The app itself, built by Vite and served by an asset canister with the
+  # headers of public/.ic-assets.json5, at http://frontend.local.localhost:8000.
+  # Its ic_env cookie names the backend, as the Vite plugin's does in dev.
+  - name: frontend
+    recipe:
+      type: "@dfinity/asset-canister@v2.3.0"
+      configuration:
+        version: 0.30.2
+        build:
+          - pnpm run build
+        dir: dist
+
+networks:
+  # The implicit `local` network, with its network launcher pinned like
+  # e2e/icp.yaml's: left at "latest", `icp network start` asks the GitHub API
+  # which release that is, unauthenticated, and fails with "403 rate limit
+  # exceeded" when many starts share an address. An exact version is
+  # downloaded straight from its release.
+  - name: local
+    mode: managed
+    version: v16.0.0-2026-09-18-03-28
+    # Internet Identity, at http://id.ai.localhost:8000, for the
+    # "Internet Identity" sign-in.
+    ii: true
+    # The NNS, whose ICP ledger (ryjl3-tyaaa-aaaaa-aaaba-cai, the same id as
+    # on mainnet) holds the wallet's balances.
+    nns: true

package/examples/vite-wallet/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light dark" />
+    <title>ICP wallet on ic-reactor 4</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/vite-wallet/ledger.did

@@ -0,0 +1,54 @@
+// Subaccount is an arbitrary 32-byte byte array.
+// Ledger uses subaccounts to compute the source address, which enables one
+// principal to control multiple ledger accounts.
+type SubAccount = blob;
+type Icrc1BlockIndex = nat;
+// Number of nanoseconds since the UNIX epoch in UTC timezone.
+type Icrc1Timestamp = nat64;
+type Icrc1Tokens = nat;
+type Account = record {
+  owner : principal;
+  subaccount : opt SubAccount;
+};
+type TransferArg = record {
+  to : Account;
+  fee : opt Icrc1Tokens;
+  memo : opt blob;
+  from_subaccount : opt SubAccount;
+  created_at_time : opt Icrc1Timestamp;
+  amount : Icrc1Tokens;
+};
+type Icrc1TransferError = variant {
+  GenericError : record {
+    message : text;
+    error_code : nat;
+  };
+  TemporarilyUnavailable;
+  BadBurn : record {
+    min_burn_amount : Icrc1Tokens;
+  };
+  Duplicate : record {
+    duplicate_of : Icrc1BlockIndex;
+  };
+  BadFee : record {
+    expected_fee : Icrc1Tokens;
+  };
+  CreatedInFuture : record {
+    ledger_time : nat64;
+  };
+  TooOld;
+  InsufficientFunds : record {
+    balance : Icrc1Tokens;
+  };
+};
+type Icrc1TransferResult = variant {
+  Ok : Icrc1BlockIndex;
+  Err : Icrc1TransferError;
+};
+service : {
+  icrc1_balance_of : (Account) -> (Icrc1Tokens) query;
+  icrc1_decimals : () -> (nat8) query;
+  icrc1_fee : () -> (Icrc1Tokens) query;
+  icrc1_symbol : () -> (text) query;
+  icrc1_transfer : (TransferArg) -> (Icrc1TransferResult);
+}

package/examples/vite-wallet/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "vite-wallet",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "gen": "meant gen backend/backend.did ledger.did -o src/canisters",
+    "gen:check": "meant gen backend/backend.did ledger.did -o src/canisters --check",
+    "icp:start": "icp network start -d",
+    "icp:deploy": "icp deploy",
+    "icp:status": "icp network status",
+    "icp:stop": "icp network stop",
+    "faucet": "node scripts/faucet.ts"
+  },
+  "dependencies": {
+    "@meantjs/schema": "0.6.0",
+    "@ic-reactor/core": "^4.1.1",
+    "@ic-reactor/react": "^4.1.1",
+    "@icp-sdk/auth": "^10.0.1",
+    "@icp-sdk/core": "^6.1.0",
+    "@tanstack/react-query": "^5.102.8",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@meantjs/cli": "0.5.1",
+    "@ic-reactor/vite-plugin": "^4.1.1",
+    "@icp-sdk/icp-cli": "1.2.0",
+    "@noble/curves": "^2.2.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.5.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "jsdom": "30.0.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.4",
+    "vitest": "^5.0.0"
+  }
+}

package/examples/vite-wallet/public/.ic-assets.json5

@@ -0,0 +1,26 @@
+// The response headers of every file the frontend canister serves. Vite
+// copies public/ into dist/, `icp deploy frontend` uploads dist/, and the
+// asset canister reads this file from there. The docs guide "Deploy to a
+// frontend canister" explains each line, and e2e/ checks what is served.
+[
+  {
+    match: "**/*",
+    // The asset canister's own security headers: Strict-Transport-Security,
+    // X-Frame-Options, X-Content-Type-Options, Referrer-Policy and a
+    // Permissions-Policy that turns off every feature it lists. "hardened"
+    // says that the headers below replace its Content-Security-Policy.
+    security_policy: "hardened",
+    headers: {
+      // The app's own scripts, styles, fonts and images only; calls to the
+      // page's origin ("env") and to icp-api.io ("ic"); no frame, plugin,
+      // <base> or form submission; and never framed itself.
+      "Content-Security-Policy": "default-src 'none'; script-src 'self'; connect-src 'self' https://icp-api.io; img-src 'self' data:; style-src 'self'; font-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+      // Not "same-origin": the Internet Identity window answers the page
+      // that opened it.
+      "Cross-Origin-Opener-Policy": "same-origin-allow-popups",
+    },
+    // <id>.raw.icp0.io serves pages no gateway checks: send them to
+    // <id>.icp0.io instead.
+    allow_raw_access: false,
+  },
+]

package/examples/vite-wallet/scripts/faucet-args.test.ts

@@ -0,0 +1,30 @@
+// What `pnpm faucet` accepts before it moves any ICP.
+import { describe, expect, it } from "vitest"
+import { readFaucetArgs } from "./faucet-args.ts"
+
+const ME = "psith-oknjz-x73tv-7x3p4-a2sji-7o6lo-g2754-yfgfl-3vlqe-irrrt-4ae"
+
+describe("the faucet's arguments", () => {
+  it("sends 10 ICP unless told how much", () => {
+    expect(readFaucetArgs([ME])).toEqual({ ok: true, to: ME, amount: "10" })
+    expect(readFaucetArgs([ME, "0.5"])).toEqual({
+      ok: true,
+      to: ME,
+      amount: "0.5",
+    })
+  })
+
+  it.each([
+    [[], "Usage: pnpm faucet <principal> [amount in ICP]"],
+    [[ME, "1", "2"], "Usage: pnpm faucet <principal> [amount in ICP]"],
+    [["me"], "Not a principal: me"],
+    [[ME, "1e3"], "Not an ICP amount: 1e3 (plain digits, at most 8 decimals)"],
+    [
+      [ME, "0.000000001"],
+      "Not an ICP amount: 0.000000001 (plain digits, at most 8 decimals)",
+    ],
+    [[ME, "0"], "Send more than zero."],
+  ])("refuses %j", (args, reason) => {
+    expect(readFaucetArgs(args)).toEqual({ ok: false, reason })
+  })
+})

package/examples/vite-wallet/scripts/faucet-args.ts

@@ -0,0 +1,41 @@
+// What `pnpm faucet <principal> [amount]` was asked for, checked before any
+// ICP moves: a principal made with `principal()` (never cast), and an amount
+// read with `parseUnits` (no exponent, no grouping, at most 8 decimals).
+import { principal, type Principal } from "@meantjs/schema"
+import { parseUnits } from "@ic-reactor/core"
+
+/** ICP's decimals, which `icp token transfer` amounts are written in. */
+const ICP_DECIMALS = 8
+
+export const DEFAULT_AMOUNT = "10"
+
+export type FaucetRequest =
+  | { readonly ok: true; readonly to: Principal; readonly amount: string }
+  | { readonly ok: false; readonly reason: string }
+
+export function readFaucetArgs(args: readonly string[]): FaucetRequest {
+  const [to, amount = DEFAULT_AMOUNT, ...rest] = args
+  if (to === undefined || rest.length > 0) {
+    return {
+      ok: false,
+      reason: "Usage: pnpm faucet <principal> [amount in ICP]",
+    }
+  }
+  let receiver: Principal
+  try {
+    receiver = principal(to)
+  } catch {
+    return { ok: false, reason: `Not a principal: ${to}` }
+  }
+  let units: bigint
+  try {
+    units = parseUnits(amount, ICP_DECIMALS)
+  } catch {
+    return {
+      ok: false,
+      reason: `Not an ICP amount: ${amount} (plain digits, at most ${ICP_DECIMALS} decimals)`,
+    }
+  }
+  if (units === 0n) return { ok: false, reason: "Send more than zero." }
+  return { ok: true, to: receiver, amount }
+}

package/examples/vite-wallet/scripts/faucet.ts

@@ -0,0 +1,41 @@
+// `pnpm faucet <principal> [amount]`: sends local ICP (10 unless told) to a
+// principal, such as a dev account the wallet shows, so it has something to
+// send. Run it from this directory, with the local network up
+// (`pnpm icp:start`).
+//
+// It runs `icp token transfer` as icp-cli's anonymous identity, the default
+// identity of a fresh icp-cli, which every local network funds with ICP when
+// it starts; whatever identity is your default, it is left alone. The icp-cli
+// of this example's devDependencies (1.2.0) runs it, not one on your PATH.
+import { execFileSync } from "node:child_process"
+import { createRequire } from "node:module"
+import { readFaucetArgs } from "./faucet-args.ts"
+
+const request = readFaucetArgs(process.argv.slice(2))
+if (!request.ok) {
+  console.error(request.reason)
+  process.exit(1)
+}
+
+const icp = createRequire(import.meta.url).resolve(
+  "@icp-sdk/icp-cli/bin/icp.js"
+)
+const args = [
+  "token",
+  "transfer",
+  request.amount,
+  request.to,
+  "--identity",
+  "anonymous",
+  "--environment",
+  "local",
+]
+console.log(`icp ${args.join(" ")}`)
+try {
+  execFileSync(process.execPath, [icp, ...args], { stdio: "inherit" })
+} catch {
+  console.error(
+    "The transfer failed. Is the local network running (pnpm icp:start)?"
+  )
+  process.exit(1)
+}