@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/components/interface/CompatibilityTab.tsx

@@ -0,0 +1,190 @@
+import type { CompatibilityReport } from "@meantjs/cli"
+import { useId, useState, type ReactElement } from "react"
+import { checkCompatibleInBrowser } from "../../interface/browser.ts"
+import { checkLiveCompatibility } from "../../interface/functions.ts"
+import { loadLivePayload } from "../../interface/load.ts"
+import { serverResult } from "../../interface/server-result.ts"
+import type {
+  CanisterInterface,
+  InterfaceSource,
+} from "../../interface/types.ts"
+import { ActionButton } from "../ActionButton.tsx"
+import { Notice } from "../Notice.tsx"
+import { ProvenanceBadge } from "../ProvenanceBadge.tsx"
+import { Spinner } from "../Spinner.tsx"
+import { useTask, type TaskState } from "../use-task.ts"
+import { CompatReport } from "./CompatReport.tsx"
+
+interface Checked {
+  report: CompatibilityReport
+  liveSource: InterfaceSource
+}
+
+/**
+ * The live interface, for a check: the page's own for a canister read live,
+ * a fresh live read for a typed one (whose page shows the committed .did),
+ * from the browser when the server function cannot run.
+ */
+async function liveInterface(
+  iface: CanisterInterface
+): Promise<{ did: string; source: InterfaceSource }> {
+  if (iface.source.kind !== "typed" && iface.did !== undefined) {
+    return { did: iface.did, source: iface.source }
+  }
+  const payload = await loadLivePayload(iface.canisterId)
+  if (!payload.ok) throw new Error(`${payload.code}: ${payload.message}`)
+  return { did: payload.did, source: payload.source }
+}
+
+/** A pasted .did against the live interface, checked in the browser. */
+async function checkPasted(
+  written: string,
+  iface: CanisterInterface
+): Promise<Checked> {
+  const live = await liveInterface(iface)
+  const report = await checkCompatibleInBrowser(written, live.did)
+  if (!report.ok) throw new Error(report.message)
+  return { report, liveSource: live.source }
+}
+
+/** A typed canister's committed .did against the live one, checked on the server. */
+async function checkCommitted(iface: CanisterInterface): Promise<Checked> {
+  const result = await serverResult(
+    checkLiveCompatibility({ data: { canisterId: iface.canisterId } })
+  )
+  if (!result.ok) throw new Error(result.message)
+  return { report: result.report, liveSource: result.source }
+}
+
+/**
+ * Is a written interface still good against the canister? Typed canisters
+ * check their committed .did against the live one, on the server; any
+ * canister checks a pasted .did, in the browser (`checkCompatible`, with the
+ * compiler's WASM loaded on first use).
+ */
+export function CompatibilityTab({
+  iface,
+}: {
+  iface: CanisterInterface
+}): ReactElement {
+  const typed = iface.source.kind === "typed" && iface.registry !== undefined
+  return (
+    <div className="stack-xl">
+      <p className="text-sm muted">
+        The live service must be a Candid subtype of the written one: every
+        written method still there, with the same mode, arguments it accepts and
+        results the written types can read. Methods only the live service has
+        are fine.
+      </p>
+      {typed && <CommittedCheck iface={iface} />}
+      <PastedCheck iface={iface} />
+    </div>
+  )
+}
+
+function CommittedCheck({ iface }: { iface: CanisterInterface }): ReactElement {
+  const task = useTask<Checked>()
+  const state = task.state
+  return (
+    <section className="stack" aria-labelledby="compat-committed-title">
+      <h3 id="compat-committed-title" className="section-title">
+        Committed .did against mainnet
+      </h3>
+      <p className="text-sm muted">
+        The server reads the canister’s live interface and checks that the .did
+        the typed module was generated from still describes it.
+      </p>
+      <div className="row">
+        <ActionButton
+          className="btn btn-primary"
+          unavailable={state.status === "running"}
+          onClick={() => task.run(() => checkCommitted(iface))}
+        >
+          {state.status === "done" ? "Check again" : "Check against mainnet"}
+        </ActionButton>
+        {state.status === "running" && (
+          <Spinner size="sm" label="Checking compatibility" />
+        )}
+      </div>
+      <CheckOutcome state={state} writtenLabel="committed .did" />
+    </section>
+  )
+}
+
+function PastedCheck({ iface }: { iface: CanisterInterface }): ReactElement {
+  const ids = useId()
+  const [written, setWritten] = useState("")
+  const task = useTask<Checked>()
+  const state = task.state
+  return (
+    <section className="stack" aria-labelledby="compat-pasted-title">
+      <h3 id="compat-pasted-title" className="section-title">
+        Your .did against mainnet
+      </h3>
+      <div className="field">
+        <label htmlFor={`${ids}-did`} className="field-label">
+          Written .did (a full interface or the subset your app calls)
+        </label>
+        <textarea
+          id={`${ids}-did`}
+          className="textarea mono iface-compat-input"
+          spellCheck={false}
+          placeholder={
+            "service : {\n  icrc1_balance_of : (record { owner : principal; subaccount : opt blob }) -> (nat) query;\n}"
+          }
+          value={written}
+          onChange={(event) => {
+            setWritten(event.target.value)
+            task.reset()
+          }}
+        />
+        <p className="field-hint">
+          Checked in your browser; the text is never sent anywhere.
+        </p>
+      </div>
+      <div className="row">
+        <ActionButton
+          className="btn btn-primary"
+          unavailable={written.trim() === "" || state.status === "running"}
+          onClick={() => task.run(() => checkPasted(written, iface))}
+        >
+          Check
+        </ActionButton>
+        {state.status === "running" && (
+          <Spinner size="sm" label="Checking compatibility" />
+        )}
+      </div>
+      <CheckOutcome state={state} writtenLabel="written .did" />
+    </section>
+  )
+}
+
+function CheckOutcome({
+  state,
+  writtenLabel,
+}: {
+  state: TaskState<Checked>
+  writtenLabel: string
+}): ReactElement | null {
+  if (state.status === "failed") {
+    return (
+      <Notice tone="danger" title="The check did not run">
+        <p className="break-all">{state.message}</p>
+      </Notice>
+    )
+  }
+  if (state.status !== "done") return null
+  return (
+    <div className="stack-sm">
+      <p className="row-sm text-sm muted">
+        <span>Live interface:</span>
+        <ProvenanceBadge source={state.value.liveSource} size="md" />
+      </p>
+      <CompatReport
+        report={state.value.report}
+        writtenLabel={writtenLabel}
+        liveLabel="live interface"
+      />
+    </div>
+  )
+}

package/examples/canister-studio/src/components/interface/ProjectTab.tsx

@@ -0,0 +1,196 @@
+import { useId, useState, type ReactElement } from "react"
+import {
+  MAX_METHOD_NAME_LENGTH,
+  MAX_PROJECT_METHODS,
+  projectInterface,
+} from "../../interface/functions.ts"
+import { NO_DID_HASH, serverResult } from "../../interface/server-result.ts"
+import type { CanisterInterface } from "../../interface/types.ts"
+import { groupDigits } from "../../lib/format.ts"
+import { ActionButton } from "../ActionButton.tsx"
+import { ModeBadge } from "../Badge.tsx"
+import { Code } from "../Code.tsx"
+import { safeFileName } from "../download.ts"
+import { Notice } from "../Notice.tsx"
+import { Spinner } from "../Spinner.tsx"
+import { useTask } from "../use-task.ts"
+
+interface Projection {
+  did: string
+  methods: string[]
+}
+
+/**
+ * Pick methods, get a self-contained .did with exactly those methods and
+ * every type they reach (`projectDid` on the server, from the canister's
+ * live interface, or a typed canister's committed one): the written side
+ * of a compatibility check, or the input of a small generated module.
+ */
+export function ProjectTab({
+  iface,
+}: {
+  iface: CanisterInterface
+}): ReactElement {
+  const ids = useId()
+  const [chosen, setChosen] = useState<ReadonlySet<string>>(() => new Set())
+  const [filter, setFilter] = useState("")
+  const task = useTask<Projection>()
+
+  const needle = filter.trim().toLowerCase()
+  const shown = iface.methods.filter(
+    (method) => needle === "" || method.name.toLowerCase().includes(needle)
+  )
+
+  const toggle = (name: string, on: boolean): void => {
+    setChosen((previous) => {
+      const next = new Set(previous)
+      if (on) next.add(name)
+      else next.delete(name)
+      return next
+    })
+    task.reset()
+  }
+
+  const setAll = (on: boolean): void => {
+    setChosen((previous) => {
+      const next = new Set(previous)
+      for (const method of shown) {
+        if (on) next.add(method.name)
+        else next.delete(method.name)
+      }
+      return next
+    })
+    task.reset()
+  }
+
+  const project = (): void => {
+    const methods = iface.methods
+      .map((method) => method.name)
+      .filter((name) => chosen.has(name))
+    const didSha256 = iface.didSha256
+    task.run(async () => {
+      if (didSha256 === undefined) throw new Error(NO_DID_HASH)
+      const result = await serverResult(
+        projectInterface({
+          data: { canisterId: iface.canisterId, didSha256, methods },
+        })
+      )
+      if (!result.ok) throw new Error(result.message)
+      return { did: result.did, methods: result.methods }
+    })
+  }
+
+  // The server function's validator refuses a request past these, so the
+  // button says why instead of sending one.
+  const refusal =
+    chosen.size === 0
+      ? "Choose at least one method."
+      : chosen.size > MAX_PROJECT_METHODS
+        ? `A projection takes at most ${groupDigits(MAX_PROJECT_METHODS)} methods.`
+        : [...chosen].some((name) => name.length > MAX_METHOD_NAME_LENGTH)
+          ? `A projection takes method names of at most ${groupDigits(MAX_METHOD_NAME_LENGTH)} characters.`
+          : undefined
+
+  const state = task.state
+  return (
+    <div className="stack-lg">
+      <p className="text-sm muted">
+        Choose the methods your app calls. The projection keeps their doc
+        comments and the declarations they reach, nothing else.
+      </p>
+      <fieldset className="fieldset iface-project-methods">
+        <legend>
+          Methods ({groupDigits(chosen.size)} of{" "}
+          {groupDigits(iface.methods.length)} chosen)
+        </legend>
+        <div className="row row-between">
+          <label htmlFor={`${ids}-filter`} className="sr-only">
+            Filter methods
+          </label>
+          <input
+            id={`${ids}-filter`}
+            type="search"
+            className="input grow iface-project-filter"
+            placeholder="Filter methods"
+            value={filter}
+            onChange={(event) => setFilter(event.target.value)}
+          />
+          <div className="row-sm">
+            <button
+              type="button"
+              className="btn btn-sm"
+              onClick={() => setAll(true)}
+            >
+              Choose {needle === "" ? "all" : "shown"}
+            </button>
+            <button
+              type="button"
+              className="btn btn-sm btn-ghost"
+              onClick={() => setAll(false)}
+            >
+              Clear {needle === "" ? "all" : "shown"}
+            </button>
+          </div>
+        </div>
+        <ul className="list-plain iface-project-list">
+          {shown.map((method) => (
+            <li key={method.name}>
+              <label className="iface-project-item">
+                <input
+                  type="checkbox"
+                  checked={chosen.has(method.name)}
+                  onChange={(event) =>
+                    toggle(method.name, event.target.checked)
+                  }
+                />
+                <span className="mono truncate grow" title={method.name}>
+                  {method.name}
+                </span>
+                <ModeBadge mode={method.mode} />
+              </label>
+            </li>
+          ))}
+        </ul>
+      </fieldset>
+      <div className="row">
+        <ActionButton
+          className="btn btn-primary"
+          onClick={project}
+          unavailable={refusal !== undefined || state.status === "running"}
+          aria-describedby={
+            refusal === undefined ? undefined : `${ids}-refusal`
+          }
+        >
+          {state.status === "running"
+            ? "Projecting…"
+            : `Project ${groupDigits(chosen.size)} ${chosen.size === 1 ? "method" : "methods"}`}
+        </ActionButton>
+        {refusal !== undefined && (
+          <span id={`${ids}-refusal`} className="text-sm muted">
+            {refusal}
+          </span>
+        )}
+        {state.status === "running" && (
+          <Spinner size="sm" label="Projecting the interface" />
+        )}
+      </div>
+      {state.status === "failed" && (
+        <Notice tone="danger" title="Projection failed">
+          <p className="break-all">{state.message}</p>
+        </Notice>
+      )}
+      {state.status === "done" && (
+        <Code
+          text={state.value.did}
+          label={`candid (${groupDigits(state.value.methods.length)} methods)`}
+          showSize
+          download={{
+            filename: `${safeFileName(iface.registry?.slug ?? iface.name)}.projected.did`,
+          }}
+          maxHeight="60vh"
+          ariaLabel="Projected Candid interface"
+        />
+      )}
+    </div>
+  )
+}

package/examples/canister-studio/src/components/interface/TypeScriptTab.tsx

@@ -0,0 +1,114 @@
+import { useEffect, type ReactElement } from "react"
+import { generateModule } from "../../interface/functions.ts"
+import { typedModuleText } from "../../interface/load.ts"
+import { NO_DID_HASH, serverResult } from "../../interface/server-result.ts"
+import type { CanisterInterface } from "../../interface/types.ts"
+import { Code } from "../Code.tsx"
+import { safeFileName } from "../download.ts"
+import { Notice } from "../Notice.tsx"
+import { Spinner } from "../Spinner.tsx"
+import { useTask } from "../use-task.ts"
+
+interface ModuleText {
+  module: string
+  omitted: CanisterInterface["omitted"]
+  committed: boolean
+}
+
+/**
+ * The `@meantjs/schema` TypeScript module for the interface: for a
+ * typed canister the committed one, for any other the module `didToModule`
+ * writes on the server. Loaded when the tab opens.
+ */
+export function TypeScriptTab({
+  iface,
+}: {
+  iface: CanisterInterface
+}): ReactElement {
+  const task = useTask<ModuleText>()
+  const { run } = task
+  const typedModule =
+    iface.source.kind === "typed" ? iface.source.module : undefined
+  const didSha256 = iface.didSha256
+
+  useEffect(() => {
+    run(async () => {
+      if (typedModule !== undefined) {
+        return {
+          module: await typedModuleText(typedModule),
+          omitted: [],
+          committed: true,
+        }
+      }
+      if (didSha256 === undefined) throw new Error(NO_DID_HASH)
+      const result = await serverResult(
+        generateModule({ data: { canisterId: iface.canisterId, didSha256 } })
+      )
+      if (!result.ok) throw new Error(result.message)
+      return {
+        module: result.module,
+        omitted: result.omitted,
+        committed: false,
+      }
+    })
+  }, [run, typedModule, iface.canisterId, didSha256])
+
+  const fileName = `${safeFileName(iface.registry?.module ?? iface.registry?.slug ?? iface.name)}.ts`
+  const state = task.state
+  return (
+    <div className="stack">
+      <p className="text-sm muted">
+        {typedModule !== undefined
+          ? `The module the app imports: src/canisters/${typedModule}.ts, generated by meant gen from the committed .did. Its values double as schemas, and type Actor types client.canister().`
+          : "What meant gen would write for this interface: a type and a schema per Candid type, the service schema actor and type Actor. Save it as a .ts file and call the canister with typed methods."}
+      </p>
+      {(state.status === "idle" || state.status === "running") && (
+        <div className="row text-sm muted">
+          <Spinner size="sm" label="Generating the module" />
+          <span>
+            {typedModule !== undefined
+              ? "Loading the committed module…"
+              : "Generating the module on the server…"}
+          </span>
+        </div>
+      )}
+      {state.status === "failed" && (
+        <Notice tone="danger" title="No module">
+          <p className="break-all">{state.message}</p>
+        </Notice>
+      )}
+      {state.status === "done" && (
+        <>
+          {state.value.omitted.length > 0 && (
+            <Notice tone="warn" title="Left out of the module">
+              <ul className="list-plain stack-xs">
+                {state.value.omitted.map((entry) => (
+                  <li key={`${entry.kind}:${entry.name}`}>
+                    <code className="code-inline">{entry.name}</code>{" "}
+                    <span className="muted">
+                      ({entry.kind}: {entry.reason}
+                      {entry.via === undefined ? "" : `, via ${entry.via}`})
+                    </span>
+                  </li>
+                ))}
+              </ul>
+            </Notice>
+          )}
+          <Code
+            text={state.value.module}
+            label={
+              state.value.committed ? "typescript (committed)" : "typescript"
+            }
+            showSize
+            download={{
+              filename: fileName,
+              type: "text/typescript;charset=utf-8",
+            }}
+            maxHeight="70vh"
+            ariaLabel={`TypeScript module for ${iface.name}`}
+          />
+        </>
+      )}
+    </div>
+  )
+}

package/examples/canister-studio/src/components/interface/tools.test.tsx

@@ -0,0 +1,169 @@
+// The interface tools that call a server function: what they send, what
+// they refuse to send, and what they say when the server gives no result
+// (StackBlitz, where TanStack Start's client resolves such a call with
+// undefined). The server functions are mocked.
+import type { AnySchema } from "@meantjs/schema"
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import {
+  checkLiveCompatibility,
+  generateModule,
+  projectInterface,
+} from "../../interface/functions.ts"
+import type { CanisterInterface, MethodInfo } from "../../interface/types.ts"
+import { CompatibilityTab } from "./CompatibilityTab.tsx"
+import { ProjectTab } from "./ProjectTab.tsx"
+import { TypeScriptTab } from "./TypeScriptTab.tsx"
+
+vi.mock("../../interface/functions.ts", async () => {
+  const { MAX_METHODS } = await import("../../interface/compile.ts")
+  return {
+    MAX_PROJECT_METHODS: MAX_METHODS,
+    MAX_METHOD_NAME_LENGTH: 1024,
+    projectInterface: vi.fn(),
+    generateModule: vi.fn(),
+    checkLiveCompatibility: vi.fn(),
+    fetchInterface: vi.fn(),
+  }
+})
+
+const NO_RESULT = /This tool runs on the studio's server/
+const SOME_CANISTER = "qoctq-giaaa-aaaaa-aaaea-cai"
+const LONG_NAME = "x".repeat(1025)
+
+function method(name: string): MethodInfo {
+  return { name, mode: "query", args: [], results: [] }
+}
+
+const DID_SHA256 = "ab".repeat(32)
+
+function liveInterface(names: readonly string[]): CanisterInterface {
+  const methods = names.map(method)
+  const byName = new Map(methods.map((m) => [m.name, m]))
+  return {
+    canisterId: SOME_CANISTER,
+    name: SOME_CANISTER,
+    actor: {} as AnySchema,
+    methods,
+    method: (name) => byName.get(name),
+    source: { kind: "metadata", certified: true, moduleHash: null },
+    did: "service : {}",
+    didSha256: DID_SHA256,
+    omitted: [],
+  }
+}
+
+beforeEach(() => {
+  vi.mocked(projectInterface).mockReset()
+  vi.mocked(generateModule).mockReset()
+  vi.mocked(checkLiveCompatibility).mockReset()
+})
+
+afterEach(cleanup)
+
+describe("ProjectTab", () => {
+  it("refuses a method name the server function would refuse, and says why", () => {
+    render(<ProjectTab iface={liveInterface(["greet", LONG_NAME])} />)
+    fireEvent.click(
+      screen.getByRole("checkbox", { name: new RegExp(LONG_NAME) })
+    )
+    const button = screen.getByRole("button", { name: /Project 1 method/ })
+    expect(button.getAttribute("aria-disabled")).toBe("true")
+    const why = document.getElementById(
+      button.getAttribute("aria-describedby") ?? ""
+    )
+    expect(why?.textContent).toMatch(/method names of at most 1,024 characters/)
+    fireEvent.click(button)
+    expect(projectInterface).not.toHaveBeenCalled()
+  })
+
+  it("keeps the focus on Project while it runs, and runs it once", async () => {
+    type Answer = Awaited<ReturnType<typeof projectInterface>>
+    let answer: (value: Answer) => void = () => undefined
+    vi.mocked(projectInterface).mockReturnValue(
+      new Promise<Answer>((resolve) => {
+        answer = resolve
+      })
+    )
+    render(<ProjectTab iface={liveInterface(["greet", "count"])} />)
+    fireEvent.click(screen.getByRole("checkbox", { name: /greet/ }))
+    const button = screen.getByRole("button", { name: /Project 1 method/ })
+    button.focus()
+    fireEvent.click(button)
+    const running = await screen.findByRole("button", { name: "Projecting…" })
+    // The same element, never disabled: a disabled one drops the focus.
+    expect(running).toBe(button)
+    expect((running as HTMLButtonElement).disabled).toBe(false)
+    expect(running.getAttribute("aria-disabled")).toBe("true")
+    expect(document.activeElement).toBe(running)
+    fireEvent.click(running)
+    expect(projectInterface).toHaveBeenCalledTimes(1)
+    answer({ ok: true, did: "service : {}", methods: ["greet"] })
+    await screen.findByRole("button", { name: /Project 1 method/ })
+  })
+
+  it("names each method whole, where the picker cuts it short", () => {
+    const names = [
+      "get_account_identifier_balance",
+      "get_account_identifier_transactions",
+    ]
+    render(<ProjectTab iface={liveInterface(names)} />)
+    for (const name of names) expect(screen.getByTitle(name)).toBeTruthy()
+  })
+
+  it("says the tool needs the studio's server when the call gives no result", async () => {
+    vi.mocked(projectInterface).mockResolvedValue(
+      undefined as unknown as Awaited<ReturnType<typeof projectInterface>>
+    )
+    render(<ProjectTab iface={liveInterface(["greet", "count"])} />)
+    fireEvent.click(screen.getByRole("checkbox", { name: /greet/ }))
+    fireEvent.click(screen.getByRole("button", { name: /Project 1 method/ }))
+    expect(await screen.findByText(NO_RESULT)).toBeTruthy()
+    expect(projectInterface).toHaveBeenCalledWith({
+      data: {
+        canisterId: SOME_CANISTER,
+        didSha256: DID_SHA256,
+        methods: ["greet"],
+      },
+    })
+    expect(screen.queryByText(/reading 'ok'/)).toBeNull()
+  })
+})
+
+describe("TypeScriptTab", () => {
+  it("says the module needs the studio's server when the call gives no result", async () => {
+    vi.mocked(generateModule).mockResolvedValue(
+      undefined as unknown as Awaited<ReturnType<typeof generateModule>>
+    )
+    render(<TypeScriptTab iface={liveInterface(["greet"])} />)
+    expect(await screen.findByText(NO_RESULT)).toBeTruthy()
+  })
+})
+
+describe("CompatibilityTab", () => {
+  it("says the committed check needs the studio's server when the call gives no result", async () => {
+    vi.mocked(checkLiveCompatibility).mockResolvedValue(
+      undefined as unknown as Awaited<ReturnType<typeof checkLiveCompatibility>>
+    )
+    const { registryEntry } = await import("../../lib/registry.ts")
+    const registry = registryEntry("ryjl3-tyaaa-aaaaa-aaaba-cai")
+    if (registry === undefined) throw new Error("no ICP ledger entry")
+    const iface: CanisterInterface = {
+      ...liveInterface(["icrc1_fee"]),
+      canisterId: registry.id,
+      source: { kind: "typed", module: registry.module },
+      registry,
+    }
+    render(<CompatibilityTab iface={iface} />)
+    fireEvent.click(
+      screen.getByRole("button", { name: "Check against mainnet" })
+    )
+    await waitFor(() => expect(screen.getByText(NO_RESULT)).toBeTruthy())
+  })
+})