@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/components/modes.ts

@@ -0,0 +1,31 @@
+import type { MethodMode } from "@meantjs/schema"
+import type { CanisterInterface } from "../interface/types.ts"
+
+/** The order modes are listed in everywhere: reads first, then writes. */
+export const MODE_ORDER: readonly MethodMode[] = [
+  "query",
+  "composite_query",
+  "update",
+  "oneway",
+]
+
+export const MODE_LABEL: Readonly<Record<MethodMode, string>> = {
+  query: "query",
+  composite_query: "composite query",
+  update: "update",
+  oneway: "oneway",
+}
+
+/** How many methods of each mode, in the studio's mode order. */
+export function modeCounts(
+  methods: CanisterInterface["methods"]
+): { mode: MethodMode; count: number }[] {
+  const counts = new Map<MethodMode, number>()
+  for (const method of methods) {
+    counts.set(method.mode, (counts.get(method.mode) ?? 0) + 1)
+  }
+  return MODE_ORDER.flatMap((mode) => {
+    const count = counts.get(mode) ?? 0
+    return count === 0 ? [] : [{ mode, count }]
+  })
+}

package/examples/canister-studio/src/components/playground/MethodPicker.tsx

@@ -0,0 +1,67 @@
+import { useRef, type KeyboardEvent, type ReactElement } from "react"
+import type { MethodInfo } from "../../interface/types.ts"
+import { ModeBadge } from "../Badge.tsx"
+
+/**
+ * The playground's method list: local state, not URLs (a pasted interface
+ * has no page of its own). One tab stop; arrow keys move and select.
+ */
+export function MethodPicker({
+  methods,
+  selected,
+  onSelect,
+}: {
+  methods: readonly MethodInfo[]
+  selected: string | undefined
+  onSelect(name: string): void
+}): ReactElement {
+  const listRef = useRef<HTMLUListElement>(null)
+
+  const move = (event: KeyboardEvent<HTMLUListElement>): void => {
+    const index = methods.findIndex((method) => method.name === selected)
+    let next: number | undefined
+    if (event.key === "ArrowDown")
+      next = Math.min(index + 1, methods.length - 1)
+    else if (event.key === "ArrowUp") next = Math.max(index - 1, 0)
+    else if (event.key === "Home") next = 0
+    else if (event.key === "End") next = methods.length - 1
+    const target = next === undefined ? undefined : methods[next]
+    if (target === undefined) return
+    event.preventDefault()
+    onSelect(target.name)
+    listRef.current
+      ?.querySelectorAll<HTMLButtonElement>("button")
+      [next ?? 0]?.focus()
+  }
+
+  return (
+    <ul
+      ref={listRef}
+      className="list-plain method-list-groups"
+      aria-label="Methods"
+      onKeyDown={move}
+    >
+      {methods.map((method, i) => {
+        const isSelected = method.name === selected
+        return (
+          <li key={method.name}>
+            <button
+              type="button"
+              className="method-list-item"
+              aria-pressed={isSelected}
+              tabIndex={
+                isSelected || (selected === undefined && i === 0) ? 0 : -1
+              }
+              onClick={() => onSelect(method.name)}
+            >
+              <span className="mono truncate method-list-name">
+                {method.name}
+              </span>
+              <ModeBadge mode={method.mode} />
+            </button>
+          </li>
+        )
+      })}
+    </ul>
+  )
+}

package/examples/canister-studio/src/components/playground/PlaygroundForms.tsx

@@ -0,0 +1,112 @@
+import { useAuth } from "@ic-reactor/react"
+import { useMemo, useState, type ReactElement } from "react"
+import { MethodRunner } from "../../calls/MethodRunner.tsx"
+import { MethodForm } from "../../forms/MethodForm.tsx"
+import { heuristicHints } from "../../forms/hints.ts"
+import type { CanisterInterface, MethodInfo } from "../../interface/types.ts"
+import { CallPreview } from "../../values/CallPreview.tsx"
+import { ModeBadge } from "../Badge.tsx"
+import { EmptyState } from "../EmptyState.tsx"
+import { MethodPicker } from "./MethodPicker.tsx"
+
+interface Encoded {
+  method: string
+  values: unknown[]
+  bytes: Uint8Array
+}
+
+/**
+ * A form per method of the pasted interface. Without a target canister the
+ * form only encodes (the exact Candid message, its text and hash); with one,
+ * the method runs against mainnet through the same runner the canister pages
+ * use.
+ */
+export function PlaygroundForms({
+  iface,
+  target,
+}: {
+  iface: CanisterInterface
+  /** A valid canister id, or nothing (encode only). */
+  target: string | undefined
+}): ReactElement {
+  const auth = useAuth()
+  const [selected, setSelected] = useState<string | undefined>(
+    iface.methods[0]?.name
+  )
+  const [encoded, setEncoded] = useState<Encoded | undefined>(undefined)
+  const hints = useMemo(() => heuristicHints(), [])
+  const method: MethodInfo | undefined =
+    selected === undefined ? undefined : iface.method(selected)
+
+  if (iface.methods.length === 0) {
+    return (
+      <EmptyState title="No methods">
+        <p>The interface declares a service without methods.</p>
+      </EmptyState>
+    )
+  }
+
+  return (
+    <div className="layout-sidebar pg-forms">
+      <aside className="sidebar">
+        <MethodPicker
+          methods={iface.methods}
+          selected={method?.name}
+          onSelect={(name) => {
+            setSelected(name)
+            setEncoded(undefined)
+          }}
+        />
+      </aside>
+      <div className="content stack-lg">
+        {method === undefined ? (
+          <p className="muted">Pick a method.</p>
+        ) : (
+          <>
+            <header className="method-heading">
+              <div className="row">
+                <h3 className="method-heading-name mono break-all">
+                  {method.name}
+                </h3>
+                <ModeBadge mode={method.mode} size="lg" />
+              </div>
+              {method.doc !== undefined && method.doc !== "" && (
+                <p className="method-heading-doc text-sm muted">{method.doc}</p>
+              )}
+            </header>
+            {target === undefined ? (
+              <>
+                <MethodForm
+                  key={method.name}
+                  method={method}
+                  hints={hints}
+                  submitLabel="Encode"
+                  callerPrincipal={
+                    auth.status === "signed-in" ? auth.principal : undefined
+                  }
+                  onSubmit={({ values, bytes }) =>
+                    setEncoded({ method: method.name, values, bytes })
+                  }
+                />
+                {encoded !== undefined && encoded.method === method.name && (
+                  <CallPreview
+                    method={method}
+                    values={encoded.values}
+                    bytes={encoded.bytes}
+                  />
+                )}
+              </>
+            ) : (
+              <MethodRunner
+                key={`${target}\u0000${method.name}`}
+                iface={iface}
+                method={method}
+                hints={hints}
+              />
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  )
+}

package/examples/canister-studio/src/components/playground/PlaygroundTools.tsx

@@ -0,0 +1,219 @@
+import type { CompatibilityReport } from "@meantjs/cli"
+import { useEffect, useState, type ReactElement } from "react"
+import {
+  checkCompatibleInBrowser,
+  moduleInBrowser,
+  projectInBrowser,
+} from "../../interface/browser.ts"
+import { loadLivePayload } from "../../interface/load.ts"
+import type {
+  CanisterInterface,
+  InterfaceSource,
+} 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 { CompatReport } from "../interface/CompatReport.tsx"
+import { Notice } from "../Notice.tsx"
+import { ProvenanceBadge } from "../ProvenanceBadge.tsx"
+import { Spinner } from "../Spinner.tsx"
+import { useTask } from "../use-task.ts"
+
+/** The TypeScript module `didToModule` writes for the pasted .did. */
+export function PlaygroundModule({ did }: { did: string }): ReactElement {
+  const task = useTask<string>()
+  const { run } = task
+  useEffect(() => {
+    run(async () => {
+      const result = await moduleInBrowser(did)
+      if (!result.ok) throw new Error(result.message)
+      return result.module
+    })
+  }, [run, did])
+  const state = task.state
+  if (state.status === "failed") {
+    return (
+      <Notice tone="danger" title="No module">
+        <p className="break-all">{state.message}</p>
+      </Notice>
+    )
+  }
+  if (state.status !== "done") {
+    return (
+      <div className="row text-sm muted">
+        <Spinner size="sm" label="Generating" />
+        <span>Generating the module in your browser…</span>
+      </div>
+    )
+  }
+  return (
+    <Code
+      text={state.value}
+      label="typescript"
+      showSize
+      download={{
+        filename: "service.ts",
+        type: "text/typescript;charset=utf-8",
+      }}
+      maxHeight="70vh"
+      ariaLabel="Generated TypeScript module"
+    />
+  )
+}
+
+/** Some methods of the pasted .did, as a self-contained .did. */
+export function PlaygroundProject({
+  iface,
+  did,
+}: {
+  iface: CanisterInterface
+  did: string
+}): ReactElement {
+  const [chosen, setChosen] = useState<ReadonlySet<string>>(() => new Set())
+  const task = useTask<string>()
+  const state = task.state
+
+  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()
+  }
+
+  return (
+    <div className="stack-lg">
+      <fieldset className="fieldset iface-project-methods">
+        <legend>
+          Methods ({groupDigits(chosen.size)} of{" "}
+          {groupDigits(iface.methods.length)} chosen)
+        </legend>
+        <ul className="list-plain iface-project-list">
+          {iface.methods.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">{method.name}</span>
+                <ModeBadge mode={method.mode} />
+              </label>
+            </li>
+          ))}
+        </ul>
+      </fieldset>
+      <div className="row">
+        <ActionButton
+          className="btn btn-primary"
+          unavailable={chosen.size === 0 || state.status === "running"}
+          onClick={() =>
+            task.run(async () => {
+              const names = iface.methods
+                .map((method) => method.name)
+                .filter((name) => chosen.has(name))
+              const result = await projectInBrowser(did, names)
+              if (!result.ok) throw new Error(result.message)
+              return result.did
+            })
+          }
+        >
+          Project
+        </ActionButton>
+        {state.status === "running" && <Spinner size="sm" label="Projecting" />}
+      </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}
+          label="candid"
+          showSize
+          download={{ filename: "service.projected.did" }}
+          maxHeight="60vh"
+          ariaLabel="Projected Candid interface"
+        />
+      )}
+    </div>
+  )
+}
+
+interface LiveCheck {
+  report: CompatibilityReport
+  source: InterfaceSource
+}
+
+/**
+ * The pasted .did against the target canister's live interface (read on the
+ * server, or in the browser where server functions cannot run; checked in
+ * the browser): can an app written against the paste call this canister?
+ */
+export function PlaygroundCompat({
+  did,
+  target,
+}: {
+  did: string
+  target: string | undefined
+}): ReactElement {
+  const task = useTask<LiveCheck>()
+  const state = task.state
+  if (target === undefined) {
+    return (
+      <p className="text-sm muted">
+        Enter a target canister above to check the pasted .did against its live
+        interface.
+      </p>
+    )
+  }
+  return (
+    <div className="stack">
+      <div className="row">
+        <ActionButton
+          className="btn btn-primary"
+          unavailable={state.status === "running"}
+          onClick={() =>
+            task.run(async () => {
+              const live = await loadLivePayload(target)
+              if (!live.ok) throw new Error(`${live.code}: ${live.message}`)
+              const report = await checkCompatibleInBrowser(did, live.did)
+              if (!report.ok) throw new Error(report.message)
+              return { report, source: live.source }
+            })
+          }
+        >
+          Check against <span className="mono">{target}</span>
+        </ActionButton>
+        {state.status === "running" && (
+          <Spinner size="sm" label="Checking compatibility" />
+        )}
+      </div>
+      {state.status === "failed" && (
+        <Notice tone="danger" title="The check did not run">
+          <p className="break-all">{state.message}</p>
+        </Notice>
+      )}
+      {state.status === "done" && (
+        <div className="stack-sm">
+          <p className="row-sm text-sm muted">
+            <span>Live interface:</span>
+            <ProvenanceBadge source={state.value.source} size="md" />
+          </p>
+          <CompatReport
+            report={state.value.report}
+            writtenLabel="pasted .did"
+            liveLabel="live interface"
+          />
+        </div>
+      )}
+    </div>
+  )
+}

package/examples/canister-studio/src/components/playground/sample.ts

@@ -0,0 +1,43 @@
+/**
+ * The playground's starting .did: a small service that touches every kind
+ * of field the forms handle (records, variants with and without payloads,
+ * options, vectors, blobs, principals, floats, tuples, a recursive type, a
+ * func reference) and every mode.
+ */
+export const SAMPLE_DID = `type Account = record { owner : principal; subaccount : opt blob };
+
+type Priority = variant {
+  Low;
+  Normal;
+  High;
+  Urgent : record { reason : text };
+};
+
+type Note = record {
+  id : nat64;
+  title : text;
+  body : opt text;
+  tags : vec text;
+  priority : Priority;
+  owner : Account;
+  attachment : opt blob;
+  score : float64;
+};
+
+// A binary tree of numbers: the forms expand it one level at a time.
+type Tree = variant { Leaf : nat; Node : record { left : Tree; right : Tree } };
+
+type Callback = func (nat64) -> () oneway;
+
+// A notes service: paste your own .did over it.
+service : {
+  // One note by id, if it exists.
+  get_note : (nat64) -> (opt Note) query;
+  list_notes : (record { offset : nat32; limit : nat8 }) -> (vec Note) query;
+  tag_counts : () -> (vec record { text; nat }) query;
+  sum_tree : (Tree) -> (nat) query;
+  add_note : (Note) -> (variant { Ok : nat64; Err : text });
+  subscribe : (Callback) -> ();
+  ping : () -> () oneway;
+}
+`

package/examples/canister-studio/src/components/playground/target.test.tsx

@@ -0,0 +1,86 @@
+// The playground's optional target canister: a mistyped id must say so, not
+// be dropped while the forms quietly only encode.
+import { createTestClient } from "@ic-reactor/core/testing"
+import { ReactorProvider } from "@ic-reactor/react"
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+  Outlet,
+  RouterProvider,
+  type RouteComponent,
+} from "@tanstack/react-router"
+import { cleanup, fireEvent, render, screen } from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import { Route as PlaygroundRoute } from "../../routes/playground.tsx"
+
+let test: ReturnType<typeof createTestClient> | undefined
+afterEach(() => {
+  cleanup()
+  test?.client.dispose()
+  test = undefined
+})
+
+async function openPlayground(): Promise<HTMLInputElement> {
+  test = createTestClient({ network: "ic", signedIn: false })
+  const client = test.client
+  const root = createRootRoute({ component: Outlet })
+  const playground = createRoute({
+    getParentRoute: () => root,
+    path: "/playground",
+    validateSearch: PlaygroundRoute.options.validateSearch,
+    component: PlaygroundRoute.options.component as RouteComponent,
+  })
+  const router = createRouter({
+    routeTree: root.addChildren([playground]),
+    history: createMemoryHistory({ initialEntries: ["/playground"] }),
+  })
+  await router.load()
+  render(
+    <ReactorProvider client={() => client}>
+      <RouterProvider router={router} />
+    </ReactorProvider>
+  )
+  return (await screen.findByLabelText("Canister id")) as HTMLInputElement
+}
+
+const hintOf = (input: HTMLInputElement): string =>
+  document.getElementById(input.getAttribute("aria-describedby") ?? "")
+    ?.textContent ?? ""
+
+describe("the playground's target canister", () => {
+  it("says a mistyped id is not one when the field is left", async () => {
+    const input = await openPlayground()
+    fireEvent.change(input, { target: { value: "ryjl3-tyaaa-aaaaa-aaaba-ca" } })
+    // Still typing: no error yet, but no promise of a target either.
+    expect(input.getAttribute("aria-invalid")).toBe("false")
+    expect(hintOf(input)).toBe("Not a canister id yet: forms only encode.")
+    fireEvent.blur(input)
+    expect(input.getAttribute("aria-invalid")).toBe("true")
+    expect(hintOf(input)).toMatch(
+      /is not canonical principal text\. Until it is a canister id, forms only encode\.$/
+    )
+  })
+
+  it("refuses the management canister when the field is left", async () => {
+    const input = await openPlayground()
+    fireEvent.change(input, { target: { value: "aaaaa-aa" } })
+    fireEvent.blur(input)
+    expect(input.getAttribute("aria-invalid")).toBe("true")
+    expect(hintOf(input)).toMatch(/management canister/)
+  })
+
+  it("leaves an empty field, or a real id, without an error", async () => {
+    const input = await openPlayground()
+    fireEvent.blur(input)
+    expect(input.getAttribute("aria-invalid")).toBe("false")
+    expect(hintOf(input)).toMatch(/^Without one/)
+    fireEvent.change(input, {
+      target: { value: "ryjl3-tyaaa-aaaaa-aaaba-cai" },
+    })
+    fireEvent.blur(input)
+    expect(input.getAttribute("aria-invalid")).toBe("false")
+    expect(hintOf(input)).toBe("Forms call this canister on mainnet.")
+  })
+})

package/examples/canister-studio/src/components/primitives.test.tsx

@@ -0,0 +1,121 @@
+import { cleanup, fireEvent, render, screen } from "@testing-library/react"
+import { afterEach, describe, expect, it } from "vitest"
+import { useState } from "react"
+import { CacheKeyPanel } from "../calls/CacheKeyPanel.tsx"
+import { ModeBadge } from "./Badge.tsx"
+import { ProvenanceBadge } from "./ProvenanceBadge.tsx"
+import { Tabs } from "./Tabs.tsx"
+
+afterEach(cleanup)
+
+describe("ProvenanceBadge", () => {
+  it("says where an interface came from, loudly when uncertified", () => {
+    render(
+      <>
+        <ProvenanceBadge source={{ kind: "typed", module: "icrc1" }} />
+        <ProvenanceBadge
+          source={{ kind: "metadata", certified: true, moduleHash: null }}
+        />
+        <ProvenanceBadge
+          source={{ kind: "tmp_hack", certified: false, moduleHash: null }}
+        />
+      </>
+    )
+    expect(screen.getByText("Typed")).toBeTruthy()
+    expect(screen.getByText("Certified metadata")).toBeTruthy()
+    const uncertified = screen.getByText("UNCERTIFIED")
+    expect(uncertified.className).toContain("badge-err")
+    expect(uncertified.getAttribute("title")).toMatch(/nobody certified/)
+  })
+
+  it("never says a private canister has no metadata", () => {
+    render(
+      <ProvenanceBadge
+        source={{
+          kind: "tmp_hack",
+          certified: false,
+          moduleHash: null,
+          reason: "private",
+        }}
+      />
+    )
+    const title = screen.getByText("UNCERTIFIED").getAttribute("title") ?? ""
+    expect(title).toMatch(
+      /^Its candid:service metadata is readable by its controllers only/
+    )
+    expect(title).not.toMatch(/No metadata|No public/)
+  })
+})
+
+describe("ModeBadge", () => {
+  it("names the mode", () => {
+    render(<ModeBadge mode="composite_query" />)
+    expect(screen.getByText("composite query").className).toContain(
+      "badge-composite"
+    )
+  })
+})
+
+describe("CacheKeyPanel", () => {
+  it("shows every segment and highlights the caller's", () => {
+    const caller = "2vxsx-fae"
+    const { container } = render(
+      <CacheKeyPanel
+        queryKey={[
+          "ic-reactor",
+          "ic",
+          caller,
+          "ryjl3-tyaaa-aaaaa-aaaba-cai",
+          "icrc1_symbol",
+          "4449444c0000",
+          "certified",
+        ]}
+      />
+    )
+    const highlighted = container.querySelectorAll(".call-key-caller")
+    expect(highlighted).toHaveLength(1)
+    expect(highlighted[0]?.querySelector(".call-key-value")?.textContent).toBe(
+      caller
+    )
+    expect(container.textContent).toContain("ryjl3-tyaaa-aaaaa-aaaba-cai")
+    expect(container.textContent).toContain("The certified twin")
+  })
+})
+
+function TabsHarness() {
+  const [tab, setTab] = useState<"a" | "b" | "c">("a")
+  return (
+    <Tabs<"a" | "b" | "c">
+      label="Test tabs"
+      selected={tab}
+      onSelect={setTab}
+      tabs={[
+        { key: "a", label: "Alpha" },
+        { key: "b", label: "Beta", disabledReason: "Not now" },
+        { key: "c", label: "Gamma" },
+      ]}
+    >
+      <p>Panel {tab}</p>
+    </Tabs>
+  )
+}
+
+describe("Tabs", () => {
+  it("is one tab stop; arrows skip disabled tabs and select", () => {
+    render(<TabsHarness />)
+    const alpha = screen.getByRole("tab", { name: "Alpha" })
+    const gamma = screen.getByRole("tab", { name: "Gamma" })
+    expect(alpha.getAttribute("tabindex")).toBe("0")
+    expect(gamma.getAttribute("tabindex")).toBe("-1")
+    expect(screen.getByRole("tabpanel").getAttribute("aria-labelledby")).toBe(
+      alpha.id
+    )
+
+    fireEvent.keyDown(alpha, { key: "ArrowRight" })
+    expect(gamma.getAttribute("aria-selected")).toBe("true")
+    expect(screen.getByText("Panel c")).toBeTruthy()
+
+    fireEvent.keyDown(gamma, { key: "Home" })
+    expect(alpha.getAttribute("aria-selected")).toBe("true")
+  })
+})