@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/vite-plugin/tests/fetch.test.ts

@@ -0,0 +1,1196 @@
+/**
+ * Fetching: a canister with a `canisterId` whose `didFile` is not on disk has
+ * the file written from the live canister's certified `candid:service`, under
+ * a real `vite build` and a real `vite dev`, and then generated by the real
+ * `@meantjs/cli`.
+ *
+ * The canisters live on a fake replica on a local port (tests/fake-ic.ts),
+ * which signs its certificates with a root key of its own: a local host, so
+ * the plugin fetches that key from it as `createClient` would.
+ */
+import fs from "node:fs"
+import http from "node:http"
+import type { AddressInfo } from "node:net"
+import os from "node:os"
+import path from "node:path"
+import { spawn } from "node:child_process"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import type { Plugin } from "vite"
+import { fetchCandid, resolveNetwork } from "../src/fetch.js"
+import { fileIdentity } from "../src/file-identity.js"
+import { foldsCase } from "../src/generate.js"
+import { icReactor, type IcReactorPluginOptions } from "../src/index.js"
+import { startFakeIc } from "./fake-ic.js"
+import {
+  createApp,
+  LEDGER_DID,
+  PING_DID,
+  recordingLogger,
+  runBuild,
+  spawnedExited,
+  startDev,
+  type App,
+  type Running,
+} from "./support.js"
+
+// The real `spawn`, watched: the tests count the generator processes.
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>()
+  return { ...actual, spawn: vi.fn(actual.spawn) }
+})
+
+const LEDGER = fs.readFileSync(LEDGER_DID, "utf-8")
+const LEDGER_ID = "ryjl3-tyaaa-aaaaa-aaaba-cai"
+const MINTER_ID = "mqygn-kiaaa-aaaar-qaadq-cai"
+const PRIVATE_ID = "rrkah-fqaaa-aaaaa-aaaaq-cai"
+const MISSING_ID = "qoctq-giaaa-aaaaa-aaaea-cai"
+
+const generatorRuns = (): number =>
+  vi.mocked(spawn).mock.calls.filter(([, args]) => (args ?? [])[1] === "gen")
+    .length
+
+const closers: Array<() => Promise<unknown>> = []
+const apps: App[] = []
+
+beforeEach(() => {
+  vi.mocked(spawn).mockClear()
+})
+
+afterEach(async () => {
+  vi.unstubAllGlobals()
+  vi.unstubAllEnvs()
+  for (const close of closers.splice(0).reverse()) await close()
+  await spawnedExited(vi.mocked(spawn))
+  for (const app of apps.splice(0)) app.cleanup()
+})
+
+function newApp(files: Record<string, string>) {
+  const app = createApp(files, "real")
+  apps.push(app)
+  return app
+}
+
+async function fakeIc(canisters: Parameters<typeof startFakeIc>[0]) {
+  const ic = await startFakeIc(canisters)
+  closers.push(ic.close)
+  return ic
+}
+
+async function serve(root: string, options: IcReactorPluginOptions) {
+  const running: Running = await startDev(root, options)
+  closers.push(running.close)
+  return running
+}
+
+/** A `fetch` that refuses every request and remembers what it was asked. */
+function refuseNetwork(): string[] {
+  const asked: string[] = []
+  vi.stubGlobal(
+    "fetch",
+    vi.fn((input: unknown) => {
+      asked.push(String(input instanceof Request ? input.url : input))
+      return Promise.reject(
+        new TypeError("fetch failed: the test refuses the network")
+      )
+    })
+  )
+  return asked
+}
+
+/**
+ * A `fetch` that sends what is asked of `host` to `to` instead: a host that is
+ * not local, which the fake replica answers.
+ */
+function forward(host: string, to: string): void {
+  const real = globalThis.fetch
+  vi.stubGlobal(
+    "fetch",
+    vi.fn((input: string | URL | Request, init?: RequestInit) => {
+      const url = input instanceof Request ? input.url : String(input)
+      if (!url.startsWith(host)) {
+        return Promise.reject(new TypeError(`the test refuses ${url}`))
+      }
+      return real(to + url.slice(host.length), init)
+    })
+  )
+}
+
+/** A local URL that accepts connections and never answers. */
+async function silentHost(): Promise<string> {
+  const server = http.createServer(() => {})
+  await new Promise<void>((resolve) =>
+    server.listen(0, "127.0.0.1", () => resolve())
+  )
+  closers.push(
+    () =>
+      new Promise((resolve) => {
+        server.closeAllConnections()
+        server.close(resolve)
+      })
+  )
+  const { port } = server.address() as AddressInfo
+  return `http://127.0.0.1:${port}`
+}
+
+/** A local URL nothing listens on. */
+async function closedHost(): Promise<string> {
+  const server = http.createServer()
+  await new Promise<void>((resolve) =>
+    server.listen(0, "127.0.0.1", () => resolve())
+  )
+  const { port } = server.address() as AddressInfo
+  await new Promise((resolve) => server.close(resolve))
+  return `http://127.0.0.1:${port}`
+}
+
+/**
+ * One `vite build` plugin for a ledger canister on `host`, whose buildStart
+ * the test calls directly: as `vite build --watch` does on every rebuild, and
+ * Vite 6 and later once for each environment.
+ */
+function oneBuildPlugin(app: App, host: string) {
+  const plugin = icReactor({
+    canisters: {
+      ledger: {
+        didFile: "did/ledger.did",
+        canisterId: LEDGER_ID,
+        network: { host },
+      },
+    },
+  }) as Plugin & {
+    configResolved: (config: unknown) => void
+    buildStart: (this: unknown) => Promise<void>
+  }
+  const { logger, lines } = recordingLogger()
+  plugin.configResolved({ root: app.root, command: "build", logger })
+  const context = { addWatchFile: vi.fn(), error: vi.fn() }
+  return { buildStart: () => plugin.buildStart.call(context), context, lines }
+}
+
+const read = (app: App, file: string) =>
+  fs.readFileSync(path.join(app.root, file), "utf-8")
+const exists = (app: App, file: string) =>
+  fs.existsSync(path.join(app.root, file))
+
+/** What a build threw, as text. */
+async function buildError(app: App, options: IcReactorPluginOptions) {
+  const { result } = runBuild(app.root, options)
+  return result.then(
+    () => "",
+    (error: unknown) => (error instanceof Error ? error.message : String(error))
+  )
+}
+
+describe("a didFile on disk", () => {
+  it("is generated with no network request under vite build and vite dev", async () => {
+    const asked = refuseNetwork()
+    const app = newApp({ "did/ledger.did": LEDGER })
+    const options: IcReactorPluginOptions = {
+      canisters: {
+        ledger: {
+          didFile: "did/ledger.did",
+          canisterId: LEDGER_ID,
+          network: "ic",
+        },
+      },
+    }
+
+    const { result, lines } = runBuild(app.root, options)
+    await result
+    expect(lines).toContainEqual(
+      expect.stringContaining("generated ledger into src/canisters/ledger.ts")
+    )
+
+    const running = await serve(app.root, options)
+    expect(running.lines.filter((line) => line.startsWith("error:"))).toEqual(
+      []
+    )
+
+    expect(asked).toEqual([])
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+  })
+})
+
+describe("a missing didFile", () => {
+  it("is written from the certified candid:service and generated, and a second build makes no request", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = newApp({})
+    const options: IcReactorPluginOptions = {
+      canisters: {
+        ledger: {
+          didFile: "did/ledger.did",
+          canisterId: LEDGER_ID,
+          network: { host: ic.host },
+        },
+      },
+    }
+
+    const first = runBuild(app.root, options)
+    await first.result
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+    expect(exists(app, "src/canisters/ledger.ts")).toBe(true)
+    expect(first.lines).toContainEqual(
+      expect.stringContaining(
+        `wrote did/ledger.did from the certified candid:service of ${LEDGER_ID} on ${ic.host}`
+      )
+    )
+    // The root key from the local host, then the certified read.
+    expect(ic.requests).toEqual([
+      "GET /api/v2/status",
+      `POST /api/v3/canister/${LEDGER_ID}/read_state`,
+    ])
+
+    const second = runBuild(app.root, options)
+    await second.result
+    expect(ic.requests).toHaveLength(2)
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+  })
+
+  it("is fetched once for the entries that share it and name one canister", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = newApp({})
+    const network = { host: ic.host }
+    const { result } = runBuild(app.root, {
+      canisters: {
+        icp: { didFile: "icrc1.did", canisterId: LEDGER_ID, network },
+        icp_admin: {
+          didFile: "icrc1.did",
+          canisterId: LEDGER_ID,
+          network,
+          outDir: "src/admin",
+        },
+      },
+    })
+    await result
+    expect(ic.requests).toEqual([
+      "GET /api/v2/status",
+      `POST /api/v3/canister/${LEDGER_ID}/read_state`,
+    ])
+    expect(exists(app, "src/canisters/icrc1.ts")).toBe(true)
+    expect(exists(app, "src/admin/icrc1.ts")).toBe(true)
+  })
+
+  it("is written and generated once under vite dev, though the watcher reports the write", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = newApp({})
+    const { server, lines } = await serve(app.root, {
+      canisters: {
+        ledger: {
+          didFile: "did/ledger.did",
+          canisterId: LEDGER_ID,
+          network: { host: ic.host },
+        },
+      },
+    })
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+    expect(generatorRuns()).toBe(1)
+
+    const file = path.join(app.root, "did/ledger.did")
+    server.watcher.emit("add", file)
+    await new Promise((resolve) => setTimeout(resolve, 200))
+    expect(generatorRuns()).toBe(1)
+
+    // A save after it is the user's, and regenerates.
+    server.watcher.emit("change", file)
+    await vi.waitFor(() => expect(generatorRuns()).toBe(2))
+    expect(lines.filter((line) => line.startsWith("error:"))).toEqual([])
+  })
+})
+
+/** `app` with `linked`, a symlink to its `did` directory, made first. */
+function linkDid(app: App): App {
+  fs.mkdirSync(path.join(app.root, "did"), { recursive: true })
+  fs.symlinkSync(
+    path.join(app.root, "did"),
+    path.join(app.root, "linked"),
+    "junction"
+  )
+  return app
+}
+
+// Whether the temporary directory the apps are made in ignores case, as macOS
+// and Windows do by default and Linux does not.
+const IGNORES_CASE = foldsCase(fs.realpathSync(os.tmpdir())) === true
+
+describe("one didFile under two paths", () => {
+  it("through a symlinked directory is fetched once, and refused when its canisters differ", async () => {
+    const ic = await fakeIc({
+      [LEDGER_ID]: { candid: LEDGER },
+      [MINTER_ID]: { candid: PING_DID },
+    })
+    const network = { host: ic.host }
+    const linked = (app: App) => {
+      fs.mkdirSync(path.join(app.root, "did"))
+      fs.symlinkSync(
+        path.join(app.root, "did"),
+        path.join(app.root, "linked"),
+        "junction"
+      )
+      return app
+    }
+
+    // One canister: one fetch, and both entries generate from what it wrote.
+    const app = linked(newApp({}))
+    await runBuild(app.root, {
+      canisters: {
+        a: { didFile: "did/ledger.did", canisterId: LEDGER_ID, network },
+        b: {
+          didFile: "linked/ledger.did",
+          canisterId: LEDGER_ID,
+          network,
+          outDir: "src/b",
+        },
+      },
+    }).result
+    expect(ic.requests).toEqual([
+      "GET /api/v2/status",
+      `POST /api/v3/canister/${LEDGER_ID}/read_state`,
+    ])
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+    expect(read(app, "src/canisters/ledger.ts")).toContain("icrc1_transfer")
+    expect(read(app, "src/b/ledger.ts")).toContain("icrc1_transfer")
+
+    // Two canisters: whose interface the one file holds cannot be told.
+    const other = linked(newApp({}))
+    const message = await buildError(other, {
+      canisters: {
+        a: { didFile: "did/ledger.did", canisterId: LEDGER_ID, network },
+        b: {
+          didFile: "linked/ledger.did",
+          canisterId: MINTER_ID,
+          network,
+          outDir: "src/b",
+        },
+      },
+    })
+    expect(message).toContain(
+      `- a (did/ledger.did), b (linked/ledger.did): "a", "b" name did/ledger.did and linked/ledger.did, which are one file, ` +
+        `but not one canister to fetch it from (a: ${LEDGER_ID} on ${ic.host}; b: ${MINTER_ID} on ${ic.host})`
+    )
+    expect(ic.requests).toHaveLength(2)
+    expect(exists(other, "did/ledger.did")).toBe(false)
+  })
+
+  it("through a symlinked directory regenerates every entry when the watcher reports either name", async () => {
+    const app = newApp({ "did/ledger.did": LEDGER })
+    fs.symlinkSync(
+      path.join(app.root, "did"),
+      path.join(app.root, "linked"),
+      "junction"
+    )
+    const { server, lines } = await serve(app.root, {
+      canisters: {
+        a: { didFile: "did/ledger.did" },
+        b: { didFile: "linked/ledger.did", outDir: "src/b" },
+      },
+    })
+    // One generator process for each outDir.
+    expect(generatorRuns()).toBe(2)
+
+    server.watcher.emit("change", path.join(app.root, "linked/ledger.did"))
+    await vi.waitFor(() => expect(generatorRuns()).toBe(4))
+    expect(lines).toContainEqual(
+      expect.stringContaining("linked/ledger.did changed, regenerating a, b")
+    )
+    expect(lines.filter((line) => line.startsWith("error:"))).toEqual([])
+  })
+
+  // The watcher may report one file under any name of it: each of these
+  // reports it under the name the other entry gives it.
+  it("through a symlinked directory starts no run when the watcher reports the fetched write under the other name", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = linkDid(newApp({}))
+    const network = { host: ic.host }
+    const { server, lines } = await serve(app.root, {
+      canisters: {
+        a: { didFile: "did/ledger.did", canisterId: LEDGER_ID, network },
+        b: {
+          didFile: "linked/ledger.did",
+          canisterId: LEDGER_ID,
+          network,
+          outDir: "src/b",
+        },
+      },
+    })
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+    expect(generatorRuns()).toBe(2)
+
+    server.watcher.emit("add", path.join(app.root, "linked/ledger.did"))
+    await new Promise((resolve) => setTimeout(resolve, 200))
+    expect(generatorRuns()).toBe(2)
+    expect(lines.filter((line) => line.startsWith("error:"))).toEqual([])
+  })
+
+  it("through a symlinked directory fails every entry when the watcher reports the file deleted under either name", async () => {
+    const app = linkDid(newApp({}))
+    fs.writeFileSync(path.join(app.root, "did/ledger.did"), LEDGER)
+    const { server, lines } = await serve(app.root, {
+      canisters: {
+        a: { didFile: "did/ledger.did" },
+        b: { didFile: "linked/ledger.did", outDir: "src/b" },
+      },
+    })
+    expect(generatorRuns()).toBe(2)
+
+    fs.rmSync(path.join(app.root, "did/ledger.did"))
+    server.watcher.emit("unlink", path.join(app.root, "linked/ledger.did"))
+    await vi.waitFor(() =>
+      expect(lines).toContainEqual(
+        expect.stringContaining(
+          "- a (did/ledger.did), b (linked/ledger.did): the .did file was deleted"
+        )
+      )
+    )
+    expect(generatorRuns()).toBe(2)
+  })
+
+  it("through a symlinked directory starts one run for two saves reported under each name", async () => {
+    const app = linkDid(newApp({}))
+    fs.writeFileSync(path.join(app.root, "did/ledger.did"), LEDGER)
+    fs.writeFileSync(path.join(app.root, "did/ping.did"), PING_DID)
+    const { server, lines } = await serve(app.root, {
+      canisters: {
+        a: { didFile: "did/ledger.did" },
+        b: { didFile: "linked/ledger.did", outDir: "src/b" },
+        c: { didFile: "did/ping.did", outDir: "src/c" },
+      },
+    })
+    expect(generatorRuns()).toBe(3)
+
+    // Both before the queued run starts: the second joins it.
+    server.watcher.emit("change", path.join(app.root, "did/ledger.did"))
+    server.watcher.emit("change", path.join(app.root, "linked/ledger.did"))
+    // Runs go one after another, so once the run of a save queued after
+    // these has started, any second run for them would already have been.
+    server.watcher.emit("change", path.join(app.root, "did/ping.did"))
+    const regenerating = (file: string) =>
+      lines.filter((line) => line.includes(`${file} changed, regenerating`))
+    await vi.waitFor(() => expect(regenerating("ping.did")).toHaveLength(1), {
+      timeout: 10_000,
+    })
+    await vi.waitFor(() => expect(generatorRuns()).toBe(6))
+    expect(regenerating("ledger.did")).toHaveLength(1)
+    expect(lines.filter((line) => line.startsWith("error:"))).toEqual([])
+  })
+
+  it("through a symlink to a file is written through it, so an entry that names the target generates from the fetch", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = newApp({ "shared/ledger.did": PING_DID })
+    fs.mkdirSync(path.join(app.root, "did"))
+    fs.symlinkSync(
+      "../shared/ledger.did",
+      path.join(app.root, "did/ledger.did"),
+      "file"
+    )
+    const network = { host: ic.host }
+    vi.stubEnv("IC_REACTOR_FETCH", "all")
+    // @meantjs/cli 0.5.1 reads no .did through a symlink to a file, so
+    // "a" fails to generate, loudly, with did_source_not_found, as it would
+    // with no fetch at all: failOnError is off to look past it.
+    const { result, lines } = runBuild(app.root, {
+      failOnError: false,
+      canisters: {
+        a: { didFile: "did/ledger.did", canisterId: LEDGER_ID, network },
+        b: {
+          didFile: "shared/ledger.did",
+          canisterId: LEDGER_ID,
+          network,
+          outDir: "src/b",
+        },
+      },
+    })
+    await result
+    expect(ic.requests).toHaveLength(2)
+    expect(
+      fs.lstatSync(path.join(app.root, "did/ledger.did")).isSymbolicLink()
+    ).toBe(true)
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+    expect(read(app, "shared/ledger.did")).toBe(LEDGER)
+    expect(read(app, "src/b/ledger.ts")).toContain("icrc1_transfer")
+    expect(
+      lines.filter((line) => line.startsWith("error:")).join("\n")
+    ).toContain("- a (did/ledger.did): did_source_not_found")
+    expect(lines).not.toContainEqual(expect.stringContaining("- b ("))
+  })
+
+  it("through a directory symlink whose target is not made yet is one file, and refused when its canisters differ", async () => {
+    const ic = await fakeIc({
+      [LEDGER_ID]: { candid: LEDGER },
+      [MINTER_ID]: { candid: PING_DID },
+    })
+    const network = { host: ic.host }
+    // `linked` names `did`, which the fetch makes.
+    const dangling = (app: App) => {
+      fs.symlinkSync(
+        path.join(app.root, "did"),
+        path.join(app.root, "linked"),
+        "junction"
+      )
+      return app
+    }
+
+    const app = dangling(newApp({}))
+    await runBuild(app.root, {
+      canisters: {
+        a: { didFile: "did/ledger.did", canisterId: LEDGER_ID, network },
+        b: {
+          didFile: "linked/ledger.did",
+          canisterId: LEDGER_ID,
+          network,
+          outDir: "src/b",
+        },
+      },
+    }).result
+    expect(ic.requests).toHaveLength(2)
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+    expect(read(app, "src/canisters/ledger.ts")).toContain("icrc1_transfer")
+    expect(read(app, "src/b/ledger.ts")).toContain("icrc1_transfer")
+
+    const other = dangling(newApp({}))
+    const message = await buildError(other, {
+      canisters: {
+        a: { didFile: "did/ledger.did", canisterId: LEDGER_ID, network },
+        b: {
+          didFile: "linked/ledger.did",
+          canisterId: MINTER_ID,
+          network,
+          outDir: "src/b",
+        },
+      },
+    })
+    expect(message).toContain(
+      `"a", "b" name did/ledger.did and linked/ledger.did, which are one file, but not one canister to fetch it from`
+    )
+    expect(ic.requests).toHaveLength(2)
+    expect(exists(other, "did")).toBe(false)
+  })
+
+  // Skipped where the filesystem tells the two names apart, as Linux's does:
+  // there they are two files, and fetched as two.
+  it.skipIf(!IGNORES_CASE)(
+    "in another case is one file where the filesystem ignores case",
+    async () => {
+      const ic = await fakeIc({
+        [LEDGER_ID]: { candid: LEDGER },
+        [MINTER_ID]: { candid: PING_DID },
+      })
+      const network = { host: ic.host }
+
+      // One canister: one fetch, written once. (The generator itself, at
+      // @meantjs/cli 0.5.1, reads a .did by its exact case, so the entry
+      // that spells it in another case fails to generate, loudly, with
+      // did_source_not_found: failOnError is off to look past it.)
+      const app = newApp({})
+      await runBuild(app.root, {
+        failOnError: false,
+        canisters: {
+          upper: { didFile: "did/Ledger.did", canisterId: LEDGER_ID, network },
+          lower: {
+            didFile: "did/ledger.did",
+            canisterId: LEDGER_ID,
+            network,
+            outDir: "src/lower",
+          },
+        },
+      }).result
+      expect(ic.requests).toEqual([
+        "GET /api/v2/status",
+        `POST /api/v3/canister/${LEDGER_ID}/read_state`,
+      ])
+      expect(fs.readdirSync(path.join(app.root, "did"))).toEqual(["Ledger.did"])
+      expect(read(app, "did/Ledger.did")).toBe(LEDGER)
+      expect(read(app, "src/canisters/Ledger.ts")).toContain("icrc1_transfer")
+
+      // Two canisters, each with an outDir of its own: one would otherwise
+      // generate from the other's interface.
+      const other = newApp({})
+      const message = await buildError(other, {
+        canisters: {
+          upper: { didFile: "did/Ledger.did", canisterId: LEDGER_ID, network },
+          lower: {
+            didFile: "did/ledger.did",
+            canisterId: MINTER_ID,
+            network,
+            outDir: "src/lower",
+          },
+        },
+      })
+      expect(message).toContain(
+        `"upper", "lower" name did/Ledger.did and did/ledger.did, which are one file, but not one canister to fetch it from`
+      )
+      expect(ic.requests).toHaveLength(2)
+      expect(exists(other, "did")).toBe(false)
+    }
+  )
+})
+
+describe("canisters that name one didFile and different canisters", () => {
+  it("are refused with no fetch, and share the file once it is on disk", async () => {
+    const ic = await fakeIc({
+      [LEDGER_ID]: { candid: LEDGER },
+      [MINTER_ID]: { candid: LEDGER },
+    })
+    const app = newApp({})
+    const network = { host: ic.host }
+    const options: IcReactorPluginOptions = {
+      canisters: {
+        icp: { didFile: "icrc1.did", canisterId: LEDGER_ID, network },
+        ckbtc: { didFile: "icrc1.did", canisterId: MINTER_ID, network },
+      },
+    }
+
+    const message = await buildError(app, options)
+    expect(message).toContain("could not generate 2 of 2 canisters")
+    expect(message).toContain(
+      `- icp (icrc1.did), ckbtc (icrc1.did): "icp", "ckbtc" name icrc1.did but not one canister to fetch it from ` +
+        `(icp: ${LEDGER_ID} on ${ic.host}; ckbtc: ${MINTER_ID} on ${ic.host}): ` +
+        `which one's interface the file holds cannot be told, so it is not fetched. ` +
+        `Give each canister a didFile of its own, or write icrc1.did yourself`
+    )
+    expect(ic.requests).toEqual([])
+    expect(exists(app, "icrc1.did")).toBe(false)
+
+    // One canister on two networks is two sources as well.
+    const networks = await buildError(app, {
+      canisters: {
+        icp: { didFile: "icrc1.did", canisterId: LEDGER_ID, network },
+        icp_main: {
+          didFile: "icrc1.did",
+          canisterId: LEDGER_ID,
+          network: "ic",
+        },
+      },
+    })
+    expect(networks).toContain(
+      `(icp: ${LEDGER_ID} on ${ic.host}; icp_main: ${LEDGER_ID} on ic)`
+    )
+    expect(ic.requests).toEqual([])
+
+    // A network that is not one refuses its canister, and the fetch of the
+    // file it shares, naming the network as given.
+    const invalid = await buildError(app, {
+      canisters: {
+        icp: { didFile: "icrc1.did", canisterId: LEDGER_ID, network },
+        icp_typo: {
+          didFile: "icrc1.did",
+          canisterId: LEDGER_ID,
+          network: "mainnet" as never,
+        },
+      },
+    })
+    expect(invalid).toContain(
+      `- icp (icrc1.did), icp_typo (icrc1.did): "icp", "icp_typo" name icrc1.did, which is not fetched, ` +
+        `since "icp_typo" cannot be generated (icp_typo: network "mainnet" is not "ic", "local" or { host: "<http or https URL>" })`
+    )
+    expect(ic.requests).toEqual([])
+
+    // On disk, the file is theirs to share, and nothing is fetched.
+    fs.writeFileSync(path.join(app.root, "icrc1.did"), LEDGER)
+    await runBuild(app.root, options).result
+    expect(read(app, "src/canisters/icrc1.ts")).toContain("icrc1_transfer")
+    expect(ic.requests).toEqual([])
+
+    // Fetching it again names one of them, and is refused the same way.
+    vi.stubEnv("IC_REACTOR_FETCH", "icp")
+    expect(await buildError(app, options)).toContain(
+      `"icp", "ckbtc" name icrc1.did but not one canister to fetch it from`
+    )
+    expect(ic.requests).toEqual([])
+    expect(read(app, "icrc1.did")).toBe(LEDGER)
+  })
+})
+
+describe("fileIdentity", () => {
+  it("is one key for every spelling of a file, before and after it exists", () => {
+    const app = newApp({})
+    fs.mkdirSync(path.join(app.root, "did"))
+    fs.symlinkSync(
+      path.join(app.root, "did"),
+      path.join(app.root, "linked"),
+      "junction"
+    )
+    const at = (file: string) => path.join(app.root, file)
+    const folding = (file: string) => fileIdentity(at(file), () => true)
+    const exact = (file: string) => fileIdentity(at(file), () => false)
+
+    // Missing: through the symlink, and in another case where case folds.
+    expect(exact("linked/ledger.did")).toBe(exact("did/ledger.did"))
+    expect(folding("did/Ledger.did")).toBe(folding("did/ledger.did"))
+    expect(folding("linked/new/Ledger.did")).toBe(folding("did/new/ledger.did"))
+    expect(exact("did/Ledger.did")).not.toBe(exact("did/ledger.did"))
+    const before = folding("did/ledger.did")
+
+    // On disk, under the spelling it was written with.
+    fs.writeFileSync(at("did/Ledger.did"), PING_DID)
+    expect(folding("did/Ledger.did")).toBe(before)
+    expect(folding("linked/Ledger.did")).toBe(before)
+    expect(exact("linked/Ledger.did")).toBe(exact("did/Ledger.did"))
+
+    // Through symlinks whose targets are not made yet: a directory, and a
+    // file, each named as the target it will be.
+    fs.symlinkSync(at("later"), at("ahead"), "junction")
+    expect(exact("ahead/ledger.did")).toBe(exact("later/ledger.did"))
+    fs.symlinkSync("../later/x.did", at("did/x.did"), "file")
+    expect(exact("did/x.did")).toBe(exact("later/x.did"))
+    expect(exact("linked/x.did")).toBe(exact("later/x.did"))
+    fs.mkdirSync(at("later"))
+    fs.writeFileSync(at("later/x.did"), PING_DID)
+    expect(exact("ahead/x.did")).toBe(exact("did/x.did"))
+  })
+})
+
+describe("a fetch that fails", () => {
+  it("says which of unreachable, refused, absent and not found it was, naming the canister", async () => {
+    const ic = await fakeIc({
+      [PRIVATE_ID]: { private: true },
+      [LEDGER_ID]: { absent: true },
+    })
+    const down = await closedHost()
+    const app = newApp({})
+    const message = await buildError(app, {
+      canisters: {
+        offline: {
+          didFile: "did/offline.did",
+          canisterId: LEDGER_ID,
+          network: { host: down },
+        },
+        secret: {
+          didFile: "did/secret.did",
+          canisterId: PRIVATE_ID,
+          network: { host: ic.host },
+        },
+        bare: {
+          didFile: "did/bare.did",
+          canisterId: LEDGER_ID,
+          network: { host: ic.host },
+        },
+        gone: {
+          didFile: "did/gone.did",
+          canisterId: MISSING_ID,
+          network: { host: ic.host },
+        },
+      },
+    })
+
+    expect(message).toContain("could not generate 4 of 4 canisters")
+    const lineOf = (name: string) =>
+      message.split("\n").find((line) => line.includes(`- ${name} (`)) ?? ""
+
+    expect(lineOf("offline")).toContain(
+      `offline (did/offline.did): could not reach ${down} to read the candid:service of ${LEDGER_ID} (`
+    )
+    expect(lineOf("offline")).toContain("Check the connection and build again")
+
+    expect(lineOf("secret")).toContain(
+      `secret (did/secret.did): ${ic.host} refused to read the candid:service of ${PRIVATE_ID} (HTTP 403`
+    )
+    expect(lineOf("secret")).toContain(
+      "get the .did from the canister's developers and save it as did/secret.did"
+    )
+
+    expect(lineOf("bare")).toContain(
+      `bare (did/bare.did): ${LEDGER_ID} on ${ic.host} publishes no candid:service metadata`
+    )
+    expect(lineOf("bare")).toContain("save it as did/bare.did")
+
+    expect(lineOf("gone")).toContain(
+      `gone (did/gone.did): ${MISSING_ID} does not exist on ${ic.host}`
+    )
+    expect(lineOf("gone")).toContain("Check canisterId")
+
+    for (const file of ["offline", "secret", "bare", "gone"]) {
+      expect(exists(app, `did/${file}.did`)).toBe(false)
+    }
+  })
+
+  it("follows failOnError: logged, and the other canisters generated", async () => {
+    const ic = await fakeIc({ [PRIVATE_ID]: { private: true } })
+    const app = newApp({ "did/ping.did": PING_DID })
+    const { result, lines } = runBuild(app.root, {
+      failOnError: false,
+      canisters: {
+        ping: { didFile: "did/ping.did" },
+        secret: {
+          didFile: "did/secret.did",
+          canisterId: PRIVATE_ID,
+          network: { host: ic.host },
+        },
+      },
+    })
+    await result
+    const errors = lines.filter((line) => line.startsWith("error:"))
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain("could not generate 1 of 2 canisters")
+    expect(errors[0]).toContain("secret (did/secret.did)")
+    expect(exists(app, "src/canisters/ping.ts")).toBe(true)
+  })
+})
+
+describe("IC_REACTOR_FETCH", () => {
+  const OLD = "service : { old : () -> () };\n"
+
+  it("is the only thing that rewrites a didFile on disk", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = newApp({ "did/ledger.did": OLD })
+    const options: IcReactorPluginOptions = {
+      canisters: {
+        ledger: {
+          didFile: "did/ledger.did",
+          canisterId: LEDGER_ID,
+          network: { host: ic.host },
+        },
+      },
+    }
+
+    await runBuild(app.root, options).result
+    expect(ic.requests).toEqual([])
+    expect(read(app, "did/ledger.did")).toBe(OLD)
+
+    vi.stubEnv("IC_REACTOR_FETCH", "ledger")
+    const { result, lines } = runBuild(app.root, options)
+    await result
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+    expect(lines).toContainEqual(
+      expect.stringContaining(`rewrote did/ledger.did from the certified`)
+    )
+    expect(read(app, "src/canisters/ledger.ts")).toContain("icrc1_transfer")
+  })
+
+  it("takes all, and fails a named canister that has no canisterId", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = newApp({ "did/ledger.did": OLD, "did/ping.did": PING_DID })
+    const options: IcReactorPluginOptions = {
+      canisters: {
+        ledger: {
+          didFile: "did/ledger.did",
+          canisterId: LEDGER_ID,
+          network: { host: ic.host },
+        },
+        ping: { didFile: "did/ping.did" },
+      },
+    }
+
+    vi.stubEnv("IC_REACTOR_FETCH", "all")
+    await runBuild(app.root, options).result
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+
+    vi.stubEnv("IC_REACTOR_FETCH", "ping")
+    const message = await buildError(app, options)
+    expect(message).toContain(
+      "ping (did/ping.did): IC_REACTOR_FETCH asks to fetch its didFile again, but it names no canisterId"
+    )
+  })
+
+  // `vite build --watch` calls buildStart again on every rebuild, and Vite 6
+  // and later call it once for each environment: one plugin, two buildStarts.
+  it("is tried again at the next buildStart when it failed, and served once it succeeds", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = newApp({ "did/ledger.did": OLD })
+    // The network is down for the first buildStart only.
+    let down = true
+    const real = globalThis.fetch
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((input: string | URL | Request, init?: RequestInit) =>
+        down
+          ? Promise.reject(new TypeError("fetch failed: the network is down"))
+          : real(input, init)
+      )
+    )
+    vi.stubEnv("IC_REACTOR_FETCH", "ledger")
+    const { buildStart, context, lines } = oneBuildPlugin(app, ic.host)
+
+    await buildStart()
+    expect(context.error).toHaveBeenCalledTimes(1)
+    expect(String(context.error.mock.calls[0][0])).toContain(
+      `ledger (did/ledger.did): could not reach ${ic.host}`
+    )
+    expect(read(app, "did/ledger.did")).toBe(OLD)
+    expect(ic.requests).toEqual([])
+
+    down = false
+    await buildStart()
+    expect(context.error).toHaveBeenCalledTimes(1)
+    expect(read(app, "did/ledger.did")).toBe(LEDGER)
+    expect(lines).toContainEqual(
+      expect.stringContaining(`rewrote did/ledger.did from the certified`)
+    )
+    expect(read(app, "src/canisters/ledger.ts")).toContain("icrc1_transfer")
+    expect(ic.requests).toHaveLength(2)
+
+    // Served: the next buildStart reads the file it wrote.
+    await buildStart()
+    expect(ic.requests).toHaveLength(2)
+  })
+
+  it("is served once when the fetch matches the file on disk", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = newApp({ "did/ledger.did": LEDGER })
+    vi.stubEnv("IC_REACTOR_FETCH", "ledger")
+    const { buildStart, context, lines } = oneBuildPlugin(app, ic.host)
+
+    await buildStart()
+    expect(context.error).not.toHaveBeenCalled()
+    expect(lines).toContainEqual(
+      expect.stringContaining(`did/ledger.did matches the certified`)
+    )
+    expect(ic.requests).toHaveLength(2)
+
+    // Served: the next buildStart does not fetch it again.
+    await buildStart()
+    expect(context.error).not.toHaveBeenCalled()
+    expect(ic.requests).toHaveLength(2)
+  })
+
+  it("is served once for a didFile that is a symlink, which it writes through", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const app = newApp({ "shared/real.did": OLD })
+    fs.mkdirSync(path.join(app.root, "did"))
+    fs.symlinkSync(
+      "../shared/real.did",
+      path.join(app.root, "did/ledger.did"),
+      "file"
+    )
+    vi.stubEnv("IC_REACTOR_FETCH", "ledger")
+    const { buildStart, context } = oneBuildPlugin(app, ic.host)
+    // The fetch and the write succeed. @meantjs/cli 0.5.1 then reads no
+    // .did through a symlink to a file (did_source_not_found), as with no
+    // fetch at all: that is the only error allowed.
+    const onlyTheCliFailed = () => {
+      for (const [message] of context.error.mock.calls) {
+        expect(String(message)).toContain(
+          "- ledger (did/ledger.did): did_source_not_found"
+        )
+      }
+    }
+
+    await buildStart()
+    onlyTheCliFailed()
+    expect(ic.requests).toHaveLength(2)
+    expect(
+      fs.lstatSync(path.join(app.root, "did/ledger.did")).isSymbolicLink()
+    ).toBe(true)
+    expect(read(app, "shared/real.did")).toBe(LEDGER)
+
+    // Served: the file's key is the same after the write as before it.
+    await buildStart()
+    onlyTheCliFailed()
+    expect(ic.requests).toHaveLength(2)
+  })
+
+  // A read-only mode on a directory does not stop a write on Windows, so the
+  // write this test needs to fail succeeds there.
+  it.skipIf(process.platform === "win32")(
+    "is tried again at the next buildStart when the write failed",
+    async () => {
+      const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+      const app = newApp({ "did/ledger.did": OLD })
+      vi.stubEnv("IC_REACTOR_FETCH", "ledger")
+      const { buildStart, context, lines } = oneBuildPlugin(app, ic.host)
+      const dir = path.join(app.root, "did")
+
+      // did/ is read-only for the first buildStart only.
+      fs.chmodSync(dir, 0o555)
+      try {
+        await buildStart()
+      } finally {
+        fs.chmodSync(dir, 0o755)
+      }
+      expect(context.error).toHaveBeenCalledTimes(1)
+      expect(String(context.error.mock.calls[0][0])).toContain(
+        `ledger (did/ledger.did): fetched the certified candid:service of ${LEDGER_ID} on ${ic.host}, but could not write it to did/ledger.did: `
+      )
+      expect(read(app, "did/ledger.did")).toBe(OLD)
+      expect(ic.requests).toHaveLength(2)
+
+      await buildStart()
+      expect(context.error).toHaveBeenCalledTimes(1)
+      expect(read(app, "did/ledger.did")).toBe(LEDGER)
+      expect(lines).toContainEqual(
+        expect.stringContaining(`rewrote did/ledger.did from the certified`)
+      )
+      expect(ic.requests).toHaveLength(4)
+    }
+  )
+})
+
+describe("the root key", () => {
+  it("is fetched only from a local host", () => {
+    const fetches = (network: Parameters<typeof resolveNetwork>[0]) => {
+      const resolved = resolveNetwork(network)
+      return typeof resolved === "string" ? resolved : resolved.fetchRootKey
+    }
+    expect(fetches(undefined)).toBe(false)
+    expect(fetches("ic")).toBe(false)
+    expect(fetches({ host: "https://example.com" })).toBe(false)
+    expect(fetches({ host: "http://localhost.example.com" })).toBe(false)
+    expect(fetches({ host: "http://notlocalhost:8000" })).toBe(false)
+    expect(fetches({ host: "http://0.0.0.0:8000" })).toBe(false)
+    expect(fetches({ host: "http://127.0.0.1.example.com" })).toBe(false)
+    expect(fetches("local")).toBe(true)
+    expect(fetches({ host: "http://localhost:4943" })).toBe(true)
+    expect(fetches({ host: "http://app.localhost:8000" })).toBe(true)
+    expect(fetches({ host: "http://127.1.2.3:8000" })).toBe(true)
+    expect(fetches({ host: "http://[::1]:8000" })).toBe(true)
+  })
+
+  it("of a host that is not local is mainnet's, so its own certificate fails and nothing is written", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    const remote = "https://replica.example"
+    forward(remote, ic.host)
+    const app = newApp({})
+    const message = await buildError(app, {
+      canisters: {
+        ledger: {
+          didFile: "did/ledger.did",
+          canisterId: LEDGER_ID,
+          network: { host: remote },
+        },
+      },
+    })
+
+    // Its own key is never asked for: only the certified read.
+    expect(ic.requests).toEqual([
+      `POST /api/v3/canister/${LEDGER_ID}/read_state`,
+    ])
+    expect(message).toContain(
+      `ledger (did/ledger.did): the certificate ${remote} sent for the candid:service of ${LEDGER_ID} did not verify against mainnet's root key, since the root key of a host that is not local is never fetched from it (`
+    )
+    expect(message).toContain("or write did/ledger.did yourself")
+    expect(exists(app, "did/ledger.did")).toBe(false)
+  })
+})
+
+describe("a certificate", () => {
+  it("signed with another key than the root key fails the canister, and nothing is written", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER, forged: true } })
+    const app = newApp({ "did/ping.did": PING_DID })
+    const { result, lines } = runBuild(app.root, {
+      failOnError: false,
+      canisters: {
+        ping: { didFile: "did/ping.did" },
+        ledger: {
+          didFile: "did/ledger.did",
+          canisterId: LEDGER_ID,
+          network: { host: ic.host },
+        },
+      },
+    })
+    await result
+    const errors = lines.filter((line) => line.startsWith("error:"))
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain("could not generate 1 of 2 canisters")
+    expect(errors[0]).toContain(
+      `ledger (did/ledger.did): the certificate ${ic.host} sent for the candid:service of ${LEDGER_ID} did not verify against the root key fetched from ${ic.host} (`
+    )
+    expect(exists(app, "did/ledger.did")).toBe(false)
+    expect(exists(app, "src/canisters/ledger.ts")).toBe(false)
+    expect(exists(app, "src/canisters/ping.ts")).toBe(true)
+  })
+})
+
+describe("a fetched didFile that cannot be written", () => {
+  it("fails its own canisters only, naming the file, and the others generate", async () => {
+    const ic = await fakeIc({ [LEDGER_ID]: { candid: LEDGER } })
+    // `blocked` is a file, so no directory can be made there.
+    const app = newApp({ "did/ping.did": PING_DID, blocked: "" })
+    const { result, lines } = runBuild(app.root, {
+      failOnError: false,
+      canisters: {
+        ping: { didFile: "did/ping.did" },
+        ledger: {
+          didFile: "blocked/ledger.did",
+          canisterId: LEDGER_ID,
+          network: { host: ic.host },
+        },
+      },
+    })
+    await result
+    const errors = lines.filter((line) => line.startsWith("error:"))
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toContain("could not generate 1 of 2 canisters")
+    expect(errors[0]).toContain(
+      `ledger (blocked/ledger.did): fetched the certified candid:service of ${LEDGER_ID} on ${ic.host}, but could not write it to blocked/ledger.did: `
+    )
+    expect(exists(app, "src/canisters/ping.ts")).toBe(true)
+  })
+})
+
+describe("fetchCandid", () => {
+  const request = { canisterId: LEDGER_ID, didFile: "did/ledger.did" }
+
+  it("refuses a network that is not ic, local or a host, before any request", async () => {
+    const asked = refuseNetwork()
+    const result = await fetchCandid({
+      ...request,
+      network: "mainnet" as never,
+    })
+    expect(result).toEqual({
+      ok: false,
+      message: `network "mainnet" is not "ic", "local" or { host: "<http or https URL>" }`,
+    })
+    expect(asked).toEqual([])
+  })
+
+  // The plugin's options refuse such a value first; a fetch still says what
+  // it is rather than hand it to Principal.fromText, and never throws.
+  it("refuses a canisterId that is not text, or is empty, before any request", async () => {
+    const asked = refuseNetwork()
+    for (const [canisterId, shown] of [
+      [null, "null"],
+      ["", '""'],
+      [1n, "1n"],
+    ] as const) {
+      const result = await fetchCandid({
+        ...request,
+        canisterId: canisterId as never,
+        network: "ic",
+      })
+      expect(result).toEqual({
+        ok: false,
+        message: `canisterId is ${shown}, not a canister ID: give the canister's principal as text, or remove canisterId`,
+      })
+    }
+    expect(asked).toEqual([])
+  })
+
+  it("refuses a canisterId that is not a canister ID, before any request", async () => {
+    const asked = refuseNetwork()
+    const result = await fetchCandid({
+      ...request,
+      canisterId: "not-a-canister",
+      network: "ic",
+    })
+    expect(result.ok).toBe(false)
+    expect(!result.ok && result.message).toMatch(
+      /^canisterId "not-a-canister" is not a canister ID: /
+    )
+    expect(asked).toEqual([])
+  })
+
+  it("gives up when the network does not answer within the deadline", async () => {
+    const host = await silentHost()
+    const result = await fetchCandid({
+      ...request,
+      network: { host },
+      timeoutMs: 300,
+    })
+    expect(result.ok).toBe(false)
+    expect(!result.ok && result.message).toBe(
+      `${host} did not answer within 0.3s, so the candid:service of ${LEDGER_ID} could not be read. ` +
+        "Check the connection and build again, or write did/ledger.did yourself, and the plugin reads it instead of fetching."
+    )
+  })
+
+  it("says to start the local network when local cannot be reached", async () => {
+    refuseNetwork()
+    const result = await fetchCandid({ ...request, network: "local" })
+    expect(result.ok).toBe(false)
+    expect(!result.ok && result.message).toContain(
+      `could not reach http://127.0.0.1:8000 to read the candid:service of ${LEDGER_ID} on local (`
+    )
+    expect(!result.ok && result.message).toContain(
+      "Is the local network running? Start it with `icp network start`."
+    )
+  })
+})