@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/forms/useMethodForm.ts

@@ -0,0 +1,251 @@
+import type { AnyFieldSchema } from "@meantjs/schema"
+import { useEffect, useState } from "react"
+import type { MethodInfo } from "../interface/types.ts"
+import { nowNanos } from "./convert.ts"
+import {
+  argPath,
+  checkCall,
+  draftFromValue,
+  fillNanos,
+  initialDraft,
+  isAtOrBelow,
+  isBytes,
+  isUnsetTime,
+  mapDrafts,
+  type CallCheck,
+  type Draft,
+  type DraftNote,
+} from "./engine.ts"
+import type { HintResolver } from "./hints.ts"
+
+/** The state of one method's form. */
+export interface FormState {
+  /** The arguments the drafts were made for. */
+  readonly args: readonly AnyFieldSchema[]
+  readonly drafts: readonly Draft[]
+  /** Paths whose issues show (blurred once). */
+  readonly touched: ReadonlySet<string>
+  /** A submit was attempted: every issue shows. */
+  readonly showAll: boolean
+  /** Paths set to the time of sending, and set again on submit. */
+  readonly autoNow: ReadonlySet<string>
+  /** "Now" defaults are applied after mount: never during a render. */
+  readonly nowPending: boolean
+  /** The field to focus after a failed submit. */
+  readonly focusPath?: string
+}
+
+interface Seed {
+  readonly method: MethodInfo
+  readonly initialValues: readonly unknown[] | undefined
+}
+
+const NO_PATHS: ReadonlySet<string> = new Set()
+
+function freshState(
+  method: MethodInfo,
+  values: readonly unknown[] | undefined,
+  notes?: DraftNote[]
+): FormState {
+  return {
+    args: method.args,
+    drafts: method.args.map((schema, i) =>
+      values !== undefined && values[i] !== undefined
+        ? draftFromValue(schema, values[i], { notes, path: argPath(i) })
+        : initialDraft(schema)
+    ),
+    touched: NO_PATHS,
+    showAll: false,
+    autoNow: NO_PATHS,
+    nowPending: true,
+  }
+}
+
+/** The same method: the same object, or the same name over the same schemas. */
+function sameMethod(a: MethodInfo, b: MethodInfo): boolean {
+  return (
+    a === b ||
+    (a.name === b.name &&
+      a.args.length === b.args.length &&
+      a.args.every((schema, i) => schema === b.args[i]))
+  )
+}
+
+/**
+ * Structural equality of argument values (bigint, bytes, arrays, plain
+ * objects), so a parent that decodes its prefill again on every render does
+ * not reset the form on every render.
+ */
+export function sameValue(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (
+    typeof a !== "object" ||
+    typeof b !== "object" ||
+    a === null ||
+    b === null
+  )
+    return false
+  if (isBytes(a) || isBytes(b)) {
+    return (
+      isBytes(a) &&
+      isBytes(b) &&
+      a.length === b.length &&
+      a.every((byte, i) => byte === b[i])
+    )
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return (
+      Array.isArray(a) &&
+      Array.isArray(b) &&
+      a.length === b.length &&
+      a.every((v, i) => sameValue(v, b[i]))
+    )
+  }
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  return (
+    ka.length === kb.length &&
+    ka.every(
+      (k) =>
+        Object.hasOwn(b, k) &&
+        sameValue(
+          (a as Record<string, unknown>)[k],
+          (b as Record<string, unknown>)[k]
+        )
+    )
+  )
+}
+
+function sameSeed(a: Seed, method: MethodInfo, values: Seed["initialValues"]) {
+  return (
+    sameMethod(a.method, method) &&
+    (a.initialValues === values || sameValue(a.initialValues, values))
+  )
+}
+
+/** Whether `path` is one of `paths` or sits below one of them. */
+const coveredBy = (paths: ReadonlySet<string>, path: string): boolean => {
+  for (const p of paths) if (isAtOrBelow(path, p)) return true
+  return false
+}
+
+/**
+ * The form's state: drafts, touch state, "now" fields. A new method or new
+ * prefill values (by structure) start a fresh form.
+ */
+export function useMethodForm(
+  method: MethodInfo,
+  initialValues: readonly unknown[] | undefined,
+  hints: HintResolver | undefined
+) {
+  const [seed, setSeed] = useState<Seed>({ method, initialValues })
+  const [state, setState] = useState<FormState>(() =>
+    freshState(method, initialValues)
+  )
+  // Derived from props, during render (React re-renders at once, before
+  // committing): no effect, so the old method's drafts never paint.
+  let current = state
+  if (!sameSeed(seed, method, initialValues)) {
+    current = freshState(method, initialValues)
+    setSeed({ method, initialValues })
+    setState(current)
+  }
+
+  // "Now" defaults read the clock, so they wait for the browser: the server
+  // and the hydrating render produce the same HTML.
+  useEffect(() => {
+    if (!current.nowPending) return
+    setState((s) => {
+      if (!s.nowPending) return s
+      const auto = new Set(s.autoNow)
+      const now = nowNanos()
+      const drafts = mapDrafts(s.args, s.drafts, (at) => {
+        const hint = hints?.({
+          path: at.path,
+          key: at.key,
+          schema: at.schema,
+          method: method.name,
+        })
+        if (hint?.nowByDefault !== true || !isUnsetTime(at.draft))
+          return undefined
+        auto.add(at.path)
+        return fillNanos(at.schema, at.draft, now)
+      })
+      return { ...s, drafts, autoNow: auto, nowPending: false }
+    })
+  }, [current.nowPending, hints, method.name])
+
+  const update = (patch: (s: FormState) => FormState) => setState(patch)
+
+  return {
+    state: current,
+    setArg(index: number, draft: Draft) {
+      update((s) => ({
+        ...s,
+        drafts: s.drafts.map((d, i) => (i === index ? draft : d)),
+      }))
+    },
+    touch(path: string) {
+      update((s) =>
+        s.touched.has(path)
+          ? s
+          : { ...s, touched: new Set(s.touched).add(path) }
+      )
+    },
+    isAutoNow: (path: string) => coveredBy(current.autoNow, path),
+    setAutoNow(path: string, on: boolean) {
+      update((s) => {
+        const auto = new Set(
+          [...s.autoNow].filter((p) => !isAtOrBelow(path, p))
+        )
+        if (on) auto.add(path)
+        return { ...s, autoNow: auto }
+      })
+    },
+    /**
+     * Values from outside (JSON import): fresh drafts, issues hidden again.
+     * Returns what could not be used as given, and was replaced.
+     */
+    load(values: readonly unknown[]): DraftNote[] {
+      const notes: DraftNote[] = []
+      setState(freshState(method, values, notes))
+      return notes
+    },
+    reset() {
+      setState(freshState(method, initialValues))
+    },
+    /**
+     * The check a submit sends: the current drafts (never a deferred
+     * render's), with "time of sending" fields set to now. On failure every
+     * issue shows and the first invalid field takes the focus.
+     */
+    submit(): CallCheck {
+      let drafts = current.drafts
+      if (current.autoNow.size > 0) {
+        const now = nowNanos()
+        drafts = mapDrafts(current.args, drafts, (at) =>
+          current.autoNow.has(at.path) &&
+          !(at.draft.k === "opt" && !at.draft.present)
+            ? fillNanos(at.schema, at.draft, now)
+            : undefined
+        )
+      }
+      const check = checkCall(current.args, drafts)
+      update((s) => ({
+        ...s,
+        drafts,
+        showAll: s.showAll || !check.ok,
+        focusPath: check.ok ? undefined : check.issues[0]?.path,
+      }))
+      return check
+    },
+    focused() {
+      update((s) =>
+        s.focusPath === undefined ? s : { ...s, focusPath: undefined }
+      )
+    },
+    focusOn(path: string) {
+      update((s) => ({ ...s, focusPath: path }))
+    },
+  }
+}

package/examples/canister-studio/src/interface/browser.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from "vitest"
+
+const init = vi.fn()
+const didToModule = vi.fn(async () => ({
+  ok: true as const,
+  module: "// module",
+  omitted: [],
+}))
+vi.mock("@meantjs/cli", () => ({ init, didToModule }))
+
+describe("the browser compiler", () => {
+  it("tries again after an init that failed, instead of failing until a reload", async () => {
+    const { moduleInBrowser } = await import("./browser.ts")
+    init.mockRejectedValueOnce(new Error("WASM download interrupted"))
+    const first = await moduleInBrowser("service : {}")
+    expect(first.ok).toBe(false)
+
+    init.mockResolvedValueOnce(undefined)
+    const second = await moduleInBrowser("service : {}")
+    expect(second).toEqual({ ok: true, module: "// module" })
+    expect(init).toHaveBeenCalledTimes(2)
+  })
+})

package/examples/canister-studio/src/interface/browser.ts

@@ -0,0 +1,153 @@
+// Client only: the Meant compiler in the browser, for a pasted .did
+// (the playground), for compatibility checks against pasted text, and for
+// reading a live canister when server functions cannot run (StackBlitz).
+// `@meantjs/cli` is imported lazily: its 1.9 MB WASM loads on first use
+// and never enters the main chunk.
+import type { CompatibilityReport } from "@meantjs/cli"
+import { sha256Hex } from "../lib/hex.ts"
+import {
+  compatibilityOf,
+  compileInterface,
+  moduleOf,
+  projectionOf,
+  type CandidCli,
+} from "./compile.ts"
+import { createLiveInterfaceLoader, type LiveLoader } from "./live-loader.ts"
+import { agentCandidSource, createMetadataAgent } from "./read-candid.ts"
+import type { InterfacePayload } from "./types.ts"
+
+let cli: Promise<CandidCli> | undefined
+
+// In a browser, `init()` with no argument fetches the WASM from the URL the
+// bundler gave it.
+function browserCli(): Promise<CandidCli> {
+  // A failed import or init (an interrupted WASM download) is not kept:
+  // the next call tries again instead of failing until a reload.
+  cli ??= import("@meantjs/cli")
+    .then(async (lib) => {
+      await lib.init()
+      return lib
+    })
+    .catch((error: unknown) => {
+      cli = undefined
+      throw error
+    })
+  return cli
+}
+
+/** Compiles a pasted .did in the browser; the payload's source is `pasted`. */
+export async function compileDidInBrowser(
+  did: string
+): Promise<InterfacePayload> {
+  try {
+    const compiled = await compileInterface(await browserCli(), did)
+    if (!compiled.ok) {
+      return compiled.diagnostics === undefined
+        ? {
+            ok: false,
+            canisterId: "",
+            code: compiled.code,
+            message: compiled.message,
+          }
+        : {
+            ok: false,
+            canisterId: "",
+            code: compiled.code,
+            message: compiled.message,
+            diagnostics: compiled.diagnostics,
+          }
+    }
+    return {
+      ok: true,
+      canisterId: "",
+      source: { kind: "pasted", certified: false },
+      did,
+      didSha256: await sha256Hex(new TextEncoder().encode(did)),
+      envelopeJson: compiled.envelopeJson,
+      docs: compiled.docs,
+      fetchedAt: 0,
+      cache: "miss",
+      interfaceId: compiled.interfaceId,
+      compiledIn: "browser",
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      canisterId: "",
+      code: "compile_failed",
+      message: `The compiler could not run in this browser: ${messageOf(error)}`,
+    }
+  }
+}
+
+/** `checkCompatible(written, live)` in the browser. */
+export async function checkCompatibleInBrowser(
+  written: string,
+  live: string
+): Promise<CompatibilityReport | { ok: false; message: string }> {
+  try {
+    return await compatibilityOf(await browserCli(), written, live)
+  } catch (error) {
+    return {
+      ok: false,
+      message: `The compiler could not run in this browser: ${messageOf(error)}`,
+    }
+  }
+}
+
+/** `didToModule(did)` in the browser. */
+export async function moduleInBrowser(
+  did: string
+): Promise<{ ok: true; module: string } | { ok: false; message: string }> {
+  try {
+    const result = await moduleOf(await browserCli(), did)
+    return result.ok ? { ok: true, module: result.module } : result
+  } catch (error) {
+    return {
+      ok: false,
+      message: `The compiler could not run in this browser: ${messageOf(error)}`,
+    }
+  }
+}
+
+/** `projectDid(did, methods)` in the browser: a pasted .did, projected. */
+export async function projectInBrowser(
+  did: string,
+  methods: readonly string[]
+): Promise<
+  { ok: true; did: string; methods: string[] } | { ok: false; message: string }
+> {
+  try {
+    return await projectionOf(await browserCli(), did, methods)
+  } catch (error) {
+    return {
+      ok: false,
+      message: `The compiler could not run in this browser: ${messageOf(error)}`,
+    }
+  }
+}
+
+let loader: LiveLoader | undefined
+
+/**
+ * A live canister's interface read from this browser: the same certified
+ * `read_state` (the agent verifies the certificate here against the mainnet
+ * root key), the same tmp hack fallback and labels, compiled with the
+ * browser's WASM. For when the `fetchInterface` server function cannot be
+ * reached; the payload says `compiledIn: "browser"`. Never throws.
+ */
+export function readInterfaceInBrowser(
+  canisterId: string,
+  options?: { retry?: boolean }
+): Promise<InterfacePayload> {
+  loader ??= createLiveInterfaceLoader({
+    source: agentCandidSource(createMetadataAgent()),
+    compile: async (did) => compileInterface(await browserCli(), did),
+    compiledIn: "browser",
+  })
+  return loader.load(canisterId, options)
+}
+
+function messageOf(error: unknown): string {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 300)
+}

package/examples/canister-studio/src/interface/cache.ts

@@ -0,0 +1,68 @@
+/**
+ * A least-recently-used map with a bound on its entry count and, optionally,
+ * on the total weight of its values (for example their size in bytes).
+ * Reading an entry with `get` makes it the most recent; adding one past
+ * either bound evicts the least recent until both hold again.
+ */
+export class Lru<K, V> {
+  readonly #map = new Map<K, V>()
+  readonly #maxEntries: number
+  readonly #maxWeight: number
+  readonly #weigh: (value: V) => number
+  #weight = 0
+
+  constructor(options: {
+    maxEntries: number
+    maxWeight?: number
+    weigh?: (value: V) => number
+  }) {
+    this.#maxEntries = options.maxEntries
+    this.#maxWeight = options.maxWeight ?? Number.POSITIVE_INFINITY
+    this.#weigh = options.weigh ?? (() => 0)
+  }
+
+  get size(): number {
+    return this.#map.size
+  }
+
+  get(key: K): V | undefined {
+    if (!this.#map.has(key)) return undefined
+    const value = this.#map.get(key) as V
+    this.#map.delete(key)
+    this.#map.set(key, value)
+    return value
+  }
+
+  /** Like `get`, without making the entry the most recent. */
+  peek(key: K): V | undefined {
+    return this.#map.get(key)
+  }
+
+  has(key: K): boolean {
+    return this.#map.has(key)
+  }
+
+  set(key: K, value: V): void {
+    this.delete(key)
+    this.#map.set(key, value)
+    this.#weight += this.#weigh(value)
+    while (
+      this.#map.size > 0 &&
+      (this.#map.size > this.#maxEntries || this.#weight > this.#maxWeight)
+    ) {
+      const oldest = this.#map.keys().next().value as K
+      this.delete(oldest)
+    }
+  }
+
+  delete(key: K): boolean {
+    if (!this.#map.has(key)) return false
+    this.#weight -= this.#weigh(this.#map.get(key) as V)
+    return this.#map.delete(key)
+  }
+
+  clear(): void {
+    this.#map.clear()
+    this.#weight = 0
+  }
+}

package/examples/canister-studio/src/interface/cli-cache.test.ts

@@ -0,0 +1,155 @@
+// @vitest-environment node
+// The compiler answers the server functions reuse: the TypeScript module, a
+// projection and a compatibility report each compile once per .did (and
+// method set), not once per request.
+import { afterAll, describe, expect, it, vi } from "vitest"
+import icpLedgerDid from "../../did/icp_ledger.did?raw"
+import icrc1Did from "../../did/icrc1.did?raw"
+import { cachingCli } from "./cli-cache.ts"
+import {
+  CompileDeadlineError,
+  compatibilityOf,
+  compileInterface,
+  moduleOf,
+  projectionOf,
+  type CandidCli,
+} from "./compile.ts"
+import { createWorkerCli } from "./compile.server.ts"
+
+const worker = createWorkerCli()
+
+afterAll(() => worker.close())
+
+/** The real compiler (in its worker), with a count of every call. */
+function counted() {
+  const calls = {
+    didToContract: 0,
+    didToModule: 0,
+    projectDid: 0,
+    checkCompatible: 0,
+  }
+  const cli: CandidCli = {
+    didToContract: (sources) => {
+      calls.didToContract++
+      return worker.didToContract(sources)
+    },
+    didToModule: (sources) => {
+      calls.didToModule++
+      return worker.didToModule(sources)
+    },
+    projectDid: (sources, methods) => {
+      calls.projectDid++
+      return worker.projectDid(sources, methods)
+    },
+    checkCompatible: (written, live) => {
+      calls.checkCompatible++
+      return worker.checkCompatible(written, live)
+    },
+  }
+  return { cli, calls }
+}
+
+describe("cachingCli", () => {
+  it("generates a .did's module once, docs and TypeScript tab alike", async () => {
+    const { cli, calls } = counted()
+    const cached = cachingCli(cli)
+    const did = "service : {\n  /// Says hi.\n  hi : () -> (text) query;\n}"
+    const compiled = await compileInterface(cached, did)
+    expect(compiled).toMatchObject({ ok: true, docs: { hi: "Says hi." } })
+    const first = await moduleOf(cached, did)
+    const again = await moduleOf(cached, did)
+    expect(first).toMatchObject({ ok: true })
+    expect(again).toEqual(first)
+    expect(calls.didToModule).toBe(1)
+    await moduleOf(cached, icrc1Did)
+    expect(calls.didToModule).toBe(2)
+  })
+
+  it("projects a .did once per set of methods, in any order", async () => {
+    const { cli, calls } = counted()
+    const cached = cachingCli(cli)
+    const first = await projectionOf(cached, icrc1Did, [
+      "icrc1_transfer",
+      "icrc1_fee",
+    ])
+    const same = await projectionOf(cached, icrc1Did, [
+      "icrc1_fee",
+      "icrc1_transfer",
+      "icrc1_fee",
+    ])
+    expect(same).toEqual(first)
+    expect(calls.projectDid).toBe(1)
+    await projectionOf(cached, icrc1Did, ["icrc1_fee"])
+    expect(calls.projectDid).toBe(2)
+  })
+
+  it("checks a pair of .did texts once, and shares a call in flight", async () => {
+    const { cli, calls } = counted()
+    const cached = cachingCli(cli)
+    const [a, b] = await Promise.all([
+      compatibilityOf(cached, icrc1Did, icpLedgerDid),
+      compatibilityOf(cached, icrc1Did, icpLedgerDid),
+    ])
+    await compatibilityOf(cached, icrc1Did, icpLedgerDid)
+    expect(a).toMatchObject({ ok: true, compatible: true })
+    expect(b).toEqual(a)
+    expect(calls.checkCompatible).toBe(1)
+  })
+
+  it("keeps no answer that threw", async () => {
+    let fail = true
+    const didToModule = vi.fn(
+      async (sources: Parameters<CandidCli["didToModule"]>[0]) => {
+        if (fail) throw new Error("the WASM trapped")
+        return worker.didToModule(sources)
+      }
+    )
+    const cached = cachingCli({ ...worker, didToModule })
+    await expect(cached.didToModule(icrc1Did)).rejects.toThrow(/trapped/)
+    fail = false
+    expect(await cached.didToModule(icrc1Did)).toMatchObject({ ok: true })
+    expect(didToModule).toHaveBeenCalledTimes(2)
+  })
+
+  it("refuses a .did whose compile ran past the deadline, whatever the method list, for a while", async () => {
+    let time = 0
+    const stopped = new CompileDeadlineError("stopped")
+    const projectDid = vi.fn<CandidCli["projectDid"]>(async () => {
+      throw stopped
+    })
+    const cached = cachingCli(
+      { ...worker, projectDid },
+      { now: () => time, slowTtlMs: 15_000 }
+    )
+    expect(await projectionOf(cached, icrc1Did, ["icrc1_fee"])).toEqual({
+      ok: false,
+      message: "stopped",
+    })
+    // Another method list, the module, the contract: none reach the worker.
+    expect(
+      await projectionOf(cached, icrc1Did, ["icrc1_symbol"])
+    ).toMatchObject({ ok: false, message: expect.stringMatching(/deadline/) })
+    expect(await moduleOf(cached, icrc1Did)).toMatchObject({ ok: false })
+    expect(await compileInterface(cached, icrc1Did)).toMatchObject({
+      ok: false,
+      code: "timeout",
+    })
+    expect(projectDid).toHaveBeenCalledTimes(1)
+    // Another .did is not held up.
+    expect(await moduleOf(cached, icpLedgerDid)).toMatchObject({ ok: true })
+
+    time += 15_000
+    await projectionOf(cached, icrc1Did, ["icrc1_symbol"])
+    expect(projectDid).toHaveBeenCalledTimes(2)
+  })
+
+  it("does not hold a .did against it when the queue was only full", async () => {
+    const projectDid = vi.fn<CandidCli["projectDid"]>(async () => {
+      throw new CompileDeadlineError("busy", { busy: true })
+    })
+    const cached = cachingCli({ ...worker, projectDid })
+    await projectionOf(cached, icrc1Did, ["icrc1_fee"])
+    await projectionOf(cached, icrc1Did, ["icrc1_fee"])
+    expect(projectDid).toHaveBeenCalledTimes(2)
+  })
+})