@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/values/leaves.tsx

@@ -0,0 +1,309 @@
+import type { MethodMode } from "@meantjs/schema"
+import {
+  defaultStringifySearch,
+  Link,
+  useRouter,
+  type AnyRouter,
+} from "@tanstack/react-router"
+import { useMemo, useState, type MouseEvent, type ReactElement } from "react"
+import {
+  formatNanos,
+  formatTokens,
+  groupDigits,
+  shortPrincipal,
+  type TokenUnits,
+} from "../lib/format.ts"
+import { toHex } from "../lib/hex.ts"
+import { isCanisterId } from "../lib/ids.ts"
+import { ModeBadge } from "../components/Badge.tsx"
+import { CopyButton } from "../components/CopyButton.tsx"
+import { isNanosTimestamp } from "./hints.ts"
+import { toDisplayJson } from "./json.ts"
+
+// The leaf renderers of the value tree. Every string from a canister goes
+// into the page as a text node (React escapes it); nothing here sets HTML.
+
+export interface PrincipalValueProps {
+  text: string
+  /** Table cells show the short form; the full text is in the title. */
+  compact?: boolean
+  /** A service reference reads "service" before the principal. */
+  service?: boolean
+  /** Replaces the "Open as canister" link with a button calling this. */
+  onOpenCanister?: (id: string) => void
+}
+
+/** Principal text, monospace, with copy and (for a canister id) an open link. */
+export function PrincipalValue({
+  text,
+  compact = false,
+  service = false,
+  onOpenCanister,
+}: PrincipalValueProps): ReactElement {
+  const canister = isCanisterId(text)
+  const openLabel = compact ? "Open" : "Open as canister"
+  return (
+    <span className="value-principal">
+      {service ? <span className="subtle">service</span> : null}
+      <code className="mono break-all" title={compact ? text : undefined}>
+        {compact ? shortPrincipal(text) : text}
+      </code>
+      <CopyButton
+        text={text}
+        label={service ? "Copy service principal" : "Copy principal"}
+        iconOnly
+        className="value-copy"
+      />
+      {canister && onOpenCanister !== undefined ? (
+        <button
+          type="button"
+          className="btn btn-ghost btn-sm"
+          aria-label={`Open as canister: ${text}`}
+          onClick={() => onOpenCanister(text)}
+        >
+          {openLabel}
+        </button>
+      ) : null}
+      {canister && onOpenCanister === undefined ? (
+        <Link
+          to="/canister/$canisterId"
+          params={{ canisterId: text }}
+          className="value-open"
+          aria-label={`Open as canister: ${text}`}
+        >
+          {openLabel}
+        </Link>
+      ) : null}
+    </span>
+  )
+}
+
+export interface BigValueProps {
+  value: bigint
+  primitive: string
+  /** The field this number sits under, for the timestamp hint. */
+  fieldKey?: string
+  /** Set when this number is a token amount in these units. */
+  units?: TokenUnits
+  /** Show base units even when `units` is set. */
+  raw: boolean
+}
+
+/** A nat/int (any width held as a bigint): grouped, in token units when hinted. */
+export function BigValue({
+  value,
+  primitive,
+  fieldKey,
+  units,
+  raw,
+}: BigValueProps): ReactElement {
+  const grouped = groupDigits(value)
+  const tokens =
+    units !== undefined && !raw ? tokenText(value, units) : undefined
+  const time =
+    fieldKey !== undefined && isNanosTimestamp(fieldKey, value)
+      ? formatNanos(value)
+      : undefined
+  return (
+    <span className="value-number">
+      {tokens === undefined ? (
+        <span className="mono tabular" title={primitive}>
+          {grouped}
+        </span>
+      ) : (
+        <span
+          className="mono tabular value-amount"
+          title={`${grouped} base units (${primitive})`}
+        >
+          {tokens}
+        </span>
+      )}
+      {time === undefined ? null : (
+        <span className="value-time subtle">{time}</span>
+      )}
+    </span>
+  )
+}
+
+function tokenText(value: bigint, units: TokenUnits): string | undefined {
+  try {
+    return formatTokens(value, units.decimals, units.symbol)
+  } catch {
+    // Decimals outside 0-255 (a hint from a misbehaving ledger): show raw.
+    return undefined
+  }
+}
+
+const LONG_TEXT = 160
+
+/** Text from a canister: as text, isolated for bidi, long text in a block. */
+export function TextValue({
+  text,
+  compact = false,
+}: {
+  text: string
+  compact?: boolean
+}): ReactElement {
+  if (text === "") return <span className="chip">empty text</span>
+  const long = text.length > LONG_TEXT || text.includes("\n")
+  if (long && !compact) {
+    return (
+      <pre className="code code-wrap value-text-block">
+        <bdi>{text}</bdi>
+      </pre>
+    )
+  }
+  return (
+    <span className="value-text" title={long ? text : undefined}>
+      <bdi>{long ? `${text.slice(0, LONG_TEXT)}…` : text}</bdi>
+    </span>
+  )
+}
+
+const BLOB_PREVIEW_BYTES = 64
+const COMPACT_BLOB_BYTES = 8
+// Past this size a blob is data (a module, a certificate), not text.
+const UTF8_PREVIEW_MAX_BYTES = 4096
+
+/** A blob: length, hex (first 64 bytes, all on request), UTF-8 when printable. */
+export function BlobValue({
+  bytes,
+  compact = false,
+}: {
+  bytes: Uint8Array
+  compact?: boolean
+}): ReactElement {
+  const [expanded, setExpanded] = useState(false)
+  const limit = compact ? COMPACT_BLOB_BYTES : BLOB_PREVIEW_BYTES
+  const cut = !expanded && bytes.length > limit
+  const hex = useMemo(
+    () => toHex(cut ? bytes.subarray(0, limit) : bytes),
+    [bytes, cut, limit]
+  )
+  const text = useMemo(
+    () =>
+      compact || bytes.length > UTF8_PREVIEW_MAX_BYTES
+        ? undefined
+        : utf8Preview(bytes),
+    [bytes, compact]
+  )
+  const zero = useMemo(() => bytes.every((b) => b === 0), [bytes])
+  if (bytes.length === 0) return <span className="chip">empty blob</span>
+  return (
+    <span className="value-blob">
+      <span className="badge">
+        {bytes.length} {bytes.length === 1 ? "byte" : "bytes"}
+      </span>
+      {zero ? <span className="chip">all zero</span> : null}
+      <code className="mono break-all value-hex">
+        {hex}
+        {cut ? "…" : null}
+      </code>
+      {cut && !compact ? (
+        <button
+          type="button"
+          className="btn btn-ghost btn-sm"
+          onClick={() => setExpanded(true)}
+        >
+          Show all {bytes.length} bytes
+        </button>
+      ) : null}
+      <CopyButton
+        text={() => toHex(bytes)}
+        label="Copy the bytes as hex"
+        iconOnly
+        className="value-copy"
+      />
+      {text === undefined ? null : (
+        <span className="value-utf8 muted">
+          UTF-8: <bdi className="value-text">{text}</bdi>
+        </span>
+      )}
+    </span>
+  )
+}
+
+/**
+ * The bytes as text when they are valid UTF-8 with nothing but printable
+ * characters (tab and newlines allowed), else `undefined`.
+ */
+export function utf8Preview(bytes: Uint8Array): string | undefined {
+  let text: string
+  try {
+    // ignoreBOM: a leading EF BB BF is part of the bytes, kept in the text
+    // (U+FEFF), as the form's text mode keeps it.
+    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+      bytes
+    )
+  } catch {
+    return undefined
+  }
+  if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/.test(text)) {
+    return undefined
+  }
+  return text.length > LONG_TEXT ? `${text.slice(0, LONG_TEXT)}…` : text
+}
+
+/**
+ * A func reference: `func "<principal>".<method>`, with a link that opens
+ * that method on that canister. The link carries a search param, so it is a
+ * built href navigated through the router (the method page's search schema
+ * belongs to the routes, not to this viewer).
+ */
+export function FuncRefValue({
+  principal,
+  method,
+  mode,
+}: {
+  principal: string
+  method: string
+  mode: MethodMode
+}): ReactElement {
+  // Optional: the viewer also renders outside a router (tests, previews).
+  const router: AnyRouter | undefined = useRouter({ warn: false })
+  const canister = isCanisterId(principal)
+  const href = `/canister/${encodeURIComponent(principal)}${defaultStringifySearch({ method })}`
+
+  function open(event: MouseEvent<HTMLAnchorElement>): void {
+    if (router === undefined || event.button !== 0) return
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+    event.preventDefault()
+    void router.navigate({ href })
+  }
+
+  return (
+    <span className="value-func">
+      <span className="subtle">func</span>
+      <code className="mono break-all">
+        {principal}.<bdi>{method}</bdi>
+      </code>
+      <ModeBadge mode={mode} />
+      {canister ? (
+        <a
+          className="value-open"
+          href={href}
+          onClick={open}
+          aria-label={`Open method: ${method} on ${principal}`}
+        >
+          Open method
+        </a>
+      ) : null}
+    </span>
+  )
+}
+
+/** A value that does not have its schema's shape: said plainly, with its JSON. */
+export function MismatchValue({
+  expected,
+  value,
+}: {
+  expected: string
+  value: unknown
+}): ReactElement {
+  return (
+    <span className="value-mismatch">
+      <span className="badge badge-warn">expected {expected}</span>
+      <code className="mono break-all">{toDisplayJson(value)}</code>
+    </span>
+  )
+}

package/examples/canister-studio/src/values/schema.test.ts

@@ -0,0 +1,123 @@
+import { c, serviceMethods } from "@meantjs/schema"
+import { describe, expect, it } from "vitest"
+import { actor as minterActor } from "../canisters/ckbtc_minter.ts"
+import { actor as icrc1Actor } from "../canisters/icrc1.ts"
+import { isAmountMethod, isAmountName, isNanosTimestamp } from "./hints.ts"
+import {
+  childPath,
+  displayLabel,
+  orderedFields,
+  replySchemas,
+  resolve,
+} from "./schema.ts"
+
+const icrc1 = serviceMethods(icrc1Actor)
+const minter = serviceMethods(minterActor)
+
+describe("replySchemas", () => {
+  it("names the shape of what a call resolves with", () => {
+    expect(replySchemas({ results: [] }).kind).toBe("none")
+    expect(replySchemas({ results: [c.nat, c.text] }).kind).toBe("many")
+    const name = icrc1.get("icrc1_name")
+    expect(name && replySchemas(name)).toEqual({
+      kind: "one",
+      schema: name?.results[0],
+    })
+  })
+
+  it("picks the Ok and Err arms of a result variant", () => {
+    const transfer = icrc1.get("icrc1_transfer")
+    if (!transfer) throw new Error("icrc1_transfer")
+    const shape = replySchemas(transfer)
+    if (shape.kind !== "result") throw new Error(shape.kind)
+    expect([shape.okTag, shape.errTag]).toEqual(["Ok", "Err"])
+    expect(resolve(shape.ok)).toMatchObject({
+      kind: "primitive",
+      primitive: "nat",
+    })
+    expect(resolve(shape.err).kind).toBe("variant")
+
+    const lower = replySchemas({
+      results: [c.variant({ ok: c.null, err: c.text })],
+    })
+    expect(lower.kind === "result" && [lower.okTag, lower.errTag]).toEqual([
+      "ok",
+      "err",
+    ])
+  })
+
+  it("leaves other variants (and mixed spellings) as one value", () => {
+    expect(
+      replySchemas({ results: [c.variant({ Ok: c.nat, err: c.text })] }).kind
+    ).toBe("one")
+    const retrieve = minter.get("retrieve_btc")
+    expect(retrieve && replySchemas(retrieve).kind).toBe("result")
+  })
+})
+
+describe("record display helpers", () => {
+  it("orders required fields first, each group in schema order", () => {
+    const node = resolve(
+      c.record({
+        fee: c.opt(c.nat),
+        to: c.principal,
+        memo: c.opt(c.blob()),
+        amount: c.nat,
+      })
+    )
+    if (node.kind !== "record") throw new Error(node.kind)
+    expect(orderedFields(node).map(([key]) => key)).toEqual([
+      "to",
+      "amount",
+      "fee",
+      "memo",
+    ])
+  })
+
+  it("labels unnamed fields by number and builds codec paths", () => {
+    expect(displayLabel("_7_")).toBe("#7")
+    expect(displayLabel("_07_")).toBe("_07_")
+    expect(displayLabel("owner")).toBe("owner")
+    expect(childPath("$", "owner")).toBe("$.owner")
+    expect(childPath("$", "has space")).toBe('$["has space"]')
+    expect(childPath("$.a", 3)).toBe("$.a[3]")
+  })
+})
+
+describe("display hints", () => {
+  it("knows token amounts by their last word", () => {
+    for (const name of [
+      "amount",
+      "minter_fee",
+      "expected_allowance",
+      "icrc1:fee",
+      "e8s",
+      "balance",
+      "total_supply",
+    ]) {
+      expect(isAmountName(name), name).toBe(true)
+    }
+    for (const name of [
+      "fee_collector_block",
+      "decimals",
+      "block_index",
+      "icrc1:decimals",
+    ]) {
+      expect(isAmountName(name), name).toBe(false)
+    }
+    expect(isAmountMethod("icrc1_balance_of")).toBe(true)
+    expect(isAmountMethod("icrc1_total_supply")).toBe(true)
+    expect(isAmountMethod("get_deposit_fee")).toBe(true)
+    expect(isAmountMethod("icrc1_transfer")).toBe(false)
+    expect(isAmountMethod("icrc1_decimals")).toBe(false)
+  })
+
+  it("knows IC timestamps by name and range", () => {
+    const now = 1_760_000_000_000_000_000n
+    expect(isNanosTimestamp("created_at_time", now)).toBe(true)
+    expect(isNanosTimestamp("timestamp_nanos", now)).toBe(true)
+    expect(isNanosTimestamp("expires_at", now)).toBe(true)
+    expect(isNanosTimestamp("created_at_time", 1_760_000_000n)).toBe(false)
+    expect(isNanosTimestamp("amount", now)).toBe(false)
+  })
+})

package/examples/canister-studio/src/values/schema.ts

@@ -0,0 +1,78 @@
+import type { AnyFieldSchema } from "@meantjs/schema"
+import { isResultSchema } from "@meantjs/schema/validate"
+import type { MethodInfo } from "../interface/types.ts"
+import {
+  armOf,
+  fieldsOf,
+  getOwn,
+  orderFields,
+  resolve,
+  type RecordNode,
+} from "../lib/schema.ts"
+
+// Schema reading helpers of the viewers and the Candid text printer: the
+// shared ones (lib/schema.ts) re-exported, plus what only a reply needs.
+
+export {
+  armOf,
+  childPath,
+  displayLabel,
+  elementsOf,
+  fieldsOf,
+  isBytes,
+  isTagOnly,
+  numericLabelId,
+  resolve,
+  type RecordNode,
+  type TupleNode,
+  type VariantNode,
+} from "../lib/schema.ts"
+
+/** A record's fields for display: required first, as the forms order them. */
+export function orderedFields(
+  node: RecordNode
+): (readonly [string, AnyFieldSchema])[] {
+  return orderFields(fieldsOf(node))
+}
+
+/** Own-property read: a record field named "toString" is not the prototype's. */
+export function ownValue(value: object, key: string): unknown {
+  return getOwn(value as Record<string, unknown>, key)
+}
+
+/**
+ * Which schemas describe what a call resolves with. ic-reactor resolves
+ * `undefined` for no results, the value for one, the tuple for several, and
+ * the Ok payload when the one result is an Ok/Err variant (an Err rejects as
+ * a `canister_err` ReactorError whose `err` is the Err payload).
+ */
+export type ReplyShape =
+  | { readonly kind: "none" }
+  | { readonly kind: "one"; readonly schema: AnyFieldSchema }
+  | {
+      readonly kind: "result"
+      readonly ok: AnyFieldSchema
+      readonly err: AnyFieldSchema
+      readonly okTag: "Ok" | "ok"
+      readonly errTag: "Err" | "err"
+    }
+  | { readonly kind: "many"; readonly schemas: readonly AnyFieldSchema[] }
+
+export function replySchemas(method: Pick<MethodInfo, "results">): ReplyShape {
+  const { results } = method
+  const [first] = results
+  if (first === undefined) return { kind: "none" }
+  if (results.length > 1) return { kind: "many", schemas: results }
+  if (!isResultSchema(first)) return { kind: "one", schema: first }
+  const node = resolve(first)
+  if (node.kind !== "variant") return { kind: "one", schema: first }
+  // isResultSchema accepts exactly Ok/Err or ok/err, never a mix.
+  const capitalized = armOf(node, "Ok") !== undefined
+  const okTag = capitalized ? "Ok" : "ok"
+  const errTag = capitalized ? "Err" : "err"
+  const ok = armOf(node, okTag)
+  const err = armOf(node, errTag)
+  if (ok === undefined || err === undefined)
+    return { kind: "one", schema: first }
+  return { kind: "result", ok, err, okTag, errTag }
+}

package/examples/canister-studio/src/values/test-router.tsx

@@ -0,0 +1,21 @@
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRouter,
+  RouterProvider,
+} from "@tanstack/react-router"
+import { render, type RenderResult } from "@testing-library/react"
+import type { ReactElement } from "react"
+
+/**
+ * Renders `ui` as the only route of an in-memory router, so the viewers'
+ * `Link`s have a router to build their hrefs with. Test-only.
+ */
+export async function renderInRouter(ui: ReactElement): Promise<RenderResult> {
+  const router = createRouter({
+    routeTree: createRootRoute({ component: () => ui }),
+    history: createMemoryHistory({ initialEntries: ["/"] }),
+  })
+  await router.load()
+  return render(<RouterProvider router={router} />)
+}