@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/styles.test.ts

@@ -0,0 +1,46 @@
+// The stylesheet holds no rule for a class nothing renders: a dead rule
+// reads as part of the design system, and the next person keeps it.
+import { readFileSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+import { describe, expect, it } from "vitest"
+
+const SRC = import.meta.dirname
+
+function sourceText(dir: string): string {
+  let text = ""
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) text += sourceText(path)
+    else if (/\.tsx?$/.test(entry.name) && !/\.test\.tsx?$/.test(entry.name)) {
+      text += `${readFileSync(path, "utf8")}\n`
+    }
+  }
+  return text
+}
+
+/** Class names the components build from a prefix and a value. */
+const COMPOSED = [
+  // Badge.tsx: `badge-${tone}`, the mode tones among them.
+  /^badge-(query|update|composite|oneway)$/,
+  // ScenarioCard.tsx: `safety-step-${step.status}`.
+  /^safety-step-(pass|fail|info)$/,
+]
+
+describe("styles.css", () => {
+  it("styles only classes the source names", () => {
+    const css = readFileSync(join(SRC, "styles.css"), "utf8").replace(
+      /\/\*[\s\S]*?\*\//g,
+      ""
+    )
+    const classes = new Set(
+      [...css.matchAll(/\.(-?[_a-zA-Z][\w-]*)/g)].map((m) => m[1]!)
+    )
+    const source = sourceText(SRC)
+    const unused = [...classes].filter(
+      (name) =>
+        !COMPOSED.some((pattern) => pattern.test(name)) &&
+        !new RegExp(`(?<![\\w-])${name}(?![\\w-])`).test(source)
+    )
+    expect(unused.sort()).toEqual([])
+  })
+})

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

@@ -0,0 +1,86 @@
+import { principal, serviceMethods } from "@meantjs/schema"
+import { encodeArgs } from "@meantjs/schema/codec"
+import { cleanup, render, screen, waitFor } from "@testing-library/react"
+import { renderToString } from "react-dom/server"
+import { afterEach, describe, expect, it } from "vitest"
+import { actor as icrc1Actor } from "../canisters/icrc1.ts"
+import type { MethodInfo } from "../interface/types.ts"
+import { fromHex, sha256Hex, toHex } from "../lib/hex.ts"
+import { CallPreview } from "./CallPreview.tsx"
+
+afterEach(cleanup)
+
+const transfer: MethodInfo = (() => {
+  const found = serviceMethods(icrc1Actor).get("icrc1_transfer")
+  if (found === undefined) throw new Error("icrc1_transfer")
+  return found
+})()
+
+const value = {
+  to: { owner: principal("2vxsx-fae"), subaccount: null },
+  fee: null,
+  memo: null,
+  from_subaccount: null,
+  created_at_time: null,
+  amount: 150_000_000n,
+}
+
+function encoded(values: readonly unknown[]): Uint8Array {
+  const result = encodeArgs(transfer.args, values)
+  if (!result.ok) throw new Error(result.issues[0]?.message)
+  return result.bytes
+}
+
+describe("CallPreview", () => {
+  it("shows the Candid text, size, SHA-256 and hex of the exact bytes", async () => {
+    const bytes = encoded([value])
+    render(<CallPreview method={transfer} values={[value]} bytes={bytes} />)
+
+    const text = screen.getByLabelText("Arguments as Candid text").textContent
+    expect(text).toContain("amount = 150_000_000 : nat")
+    expect(text).toContain('owner = principal "2vxsx-fae"')
+    expect(screen.getByText(`${bytes.length} bytes`)).toBeTruthy()
+    expect(screen.getByText("icrc1_transfer")).toBeTruthy()
+    expect(screen.getByText("update").className).toContain("badge-update")
+    expect(
+      screen.getByText(`Argument bytes (hex, ${bytes.length} bytes)`)
+    ).toBeTruthy()
+    expect(screen.getByText(toHex(bytes))).toBeTruthy()
+
+    const digest = await sha256Hex(bytes)
+    await waitFor(() =>
+      expect(screen.getByTestId("call-sha256").textContent).toBe(digest)
+    )
+  })
+
+  it("renders 'computing…' on the server, so hydration matches", () => {
+    const bytes = encoded([value])
+    const html = renderToString(
+      <CallPreview method={transfer} values={[value]} bytes={bytes} />
+    )
+    expect(html).toContain("computing…")
+    expect(html).toContain(toHex(bytes))
+  })
+
+  it("prints the bytes, and warns when the form's values say otherwise", () => {
+    const bytes = encoded([value])
+    render(
+      <CallPreview
+        method={transfer}
+        values={[{ ...value, amount: 1n }]}
+        bytes={bytes}
+      />
+    )
+    expect(screen.getByText(/values and the encoded bytes differ/)).toBeTruthy()
+    expect(
+      screen.getByLabelText("Arguments as Candid text").textContent
+    ).toContain("amount = 150_000_000 : nat")
+  })
+
+  it("warns when the bytes are not the method's arguments", () => {
+    const empty = fromHex("4449444c0000")
+    if (empty === undefined) throw new Error("hex")
+    render(<CallPreview method={transfer} values={[value]} bytes={empty} />)
+    expect(screen.getByText(/do not decode as icrc1_transfer/)).toBeTruthy()
+  })
+})

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

@@ -0,0 +1,148 @@
+import { decodeArgs } from "@meantjs/schema/codec"
+import { useMemo, type JSX } from "react"
+import { ModeBadge } from "../components/Badge.tsx"
+import { CopyButton } from "../components/CopyButton.tsx"
+import type { MethodInfo } from "../interface/types.ts"
+import { formatByteSize, groupDigits } from "../lib/format.ts"
+import { toHex } from "../lib/hex.ts"
+import { candidArgsText } from "./candid-text.ts"
+import { useSha256 } from "./use-sha256.ts"
+
+export interface CallPreviewProps {
+  method: MethodInfo
+  values: readonly unknown[]
+  /** The exact encoded argument bytes. */
+  bytes: Uint8Array
+}
+
+/**
+ * What a call will send: its Candid text, size, SHA-256 and the hex bytes
+ * (collapsible). The Candid text is printed from the bytes themselves,
+ * decoded against the method's argument types, so it shows what is sent,
+ * not what the form believes it holds.
+ */
+export function CallPreview({
+  method,
+  values,
+  bytes,
+}: CallPreviewProps): JSX.Element {
+  const hex = useMemo(() => toHex(bytes), [bytes])
+  const preview = useMemo(
+    () => previewText(method, values, bytes),
+    [method, values, bytes]
+  )
+  const sha256 = useSha256(bytes)
+  const size = bytes.length
+
+  return (
+    <div className="call-preview stack-sm">
+      <dl className="kv kv-compact">
+        <dt>Method</dt>
+        <dd className="row row-sm">
+          <code className="mono break-all">{method.name}</code>
+          <ModeBadge mode={method.mode} />
+        </dd>
+        <dt>Size</dt>
+        <dd className="tabular">
+          {groupDigits(size)} {size === 1 ? "byte" : "bytes"}
+          {size >= 1024 ? ` (${formatByteSize(size)})` : null}
+        </dd>
+        <dt>SHA-256</dt>
+        <dd className="row row-sm">
+          {sha256 === undefined ? (
+            <span className="subtle">computing…</span>
+          ) : (
+            <>
+              <code className="mono break-all" data-testid="call-sha256">
+                {sha256}
+              </code>
+              <CopyButton text={sha256} label="Copy the SHA-256" iconOnly />
+            </>
+          )}
+        </dd>
+      </dl>
+
+      <div className="stack-xs">
+        <div className="row row-between">
+          <span className="text-sm muted">Arguments as Candid text</span>
+          {preview.text === undefined ? null : (
+            <CopyButton
+              text={preview.text}
+              a11yLabel="Copy the arguments as Candid text"
+            />
+          )}
+        </div>
+        {preview.warning === undefined ? null : (
+          <div className="notice notice-warn" role="status">
+            <p>{preview.warning}</p>
+          </div>
+        )}
+        {preview.text === undefined ? null : (
+          <pre
+            className="code value-code"
+            tabIndex={0}
+            aria-label="Arguments as Candid text"
+          >
+            {preview.text}
+          </pre>
+        )}
+      </div>
+
+      <details className="disclosure call-preview-bytes">
+        <summary>
+          Argument bytes (hex, {groupDigits(size)}{" "}
+          {size === 1 ? "byte" : "bytes"})
+        </summary>
+        <div className="disclosure-body">
+          <code className="mono break-all call-preview-hex">{hex}</code>
+          <div className="row row-end">
+            <CopyButton text={hex} a11yLabel="Copy the argument bytes as hex" />
+          </div>
+        </div>
+      </details>
+    </div>
+  )
+}
+
+interface PreviewText {
+  readonly text?: string
+  readonly warning?: string
+}
+
+function previewText(
+  method: MethodInfo,
+  values: readonly unknown[],
+  bytes: Uint8Array
+): PreviewText {
+  const fromValues = attempt(() =>
+    candidArgsText(method.args, values, { width: 80 })
+  )
+  const decoded = decodeArgs(method.args, bytes)
+  if (!decoded.ok) {
+    const issue = decoded.issues[0]
+    return {
+      text: fromValues,
+      warning: `These bytes do not decode as ${method.name}'s arguments${issue === undefined ? "" : ` (${issue.path}: ${issue.message})`}. The text below is the form's values, not the bytes.`,
+    }
+  }
+  const fromBytes = attempt(() =>
+    candidArgsText(method.args, decoded.values, { width: 80 })
+  )
+  if (fromBytes === undefined) return { text: fromValues }
+  if (fromValues !== undefined && fromValues !== fromBytes) {
+    return {
+      text: fromBytes,
+      warning:
+        "The form's values and the encoded bytes differ. The text below is decoded from the bytes, which are what will be sent.",
+    }
+  }
+  return { text: fromBytes }
+}
+
+function attempt(compute: () => string): string | undefined {
+  try {
+    return compute()
+  } catch {
+    return undefined
+  }
+}

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

@@ -0,0 +1,66 @@
+import type { JSX } from "react"
+import type { MethodInfo } from "../interface/types.ts"
+import type { TokenUnits } from "../lib/format.ts"
+import { candidArgsText } from "./candid-text.ts"
+import { ValueInspector } from "./Inspector.tsx"
+import { toDisplayJson } from "./json.ts"
+import { isTagOnly, replySchemas } from "./schema.ts"
+import { showsAmounts, TagBadge, ValueNode } from "./tree.tsx"
+
+export interface ErrValueViewProps {
+  method: MethodInfo
+  /** A `canister_err` ReactorError's `err` payload. */
+  err: unknown
+  /** A ledger's units, for amounts in the payload (`InsufficientFunds`). */
+  units?: TokenUnits
+}
+
+/**
+ * A `canister_err` payload, viewed with the Err arm's schema: the canister
+ * answered, and its answer was the Err arm of the method's result.
+ */
+export function ErrValueView({
+  method,
+  err,
+  units,
+}: ErrValueViewProps): JSX.Element {
+  const shape = replySchemas(method)
+  if (shape.kind !== "result") {
+    // canister_err comes only from an Ok/Err result; anything else is shown
+    // as it arrived.
+    return (
+      <div className="stack-xs">
+        <p className="subtle text-xs">
+          <code className="mono">{method.name}</code> has no Err result arm; the
+          payload as JSON:
+        </p>
+        <pre className="code value-code">{toDisplayJson(err)}</pre>
+      </div>
+    )
+  }
+  const bare = isTagOnly(shape.err)
+  const sent = bare ? { tag: shape.errTag } : { tag: shape.errTag, value: err }
+  return (
+    <ValueInspector
+      label="Err payload"
+      hasUnits={units !== undefined && showsAmounts(shape.err, false)}
+      candidNote={`The reply message: the canister answered ${shape.errTag}.`}
+      renderTree={(raw) => (
+        <div className="value-result">
+          <TagBadge tag={shape.errTag} />
+          {bare ? null : (
+            <ValueNode
+              schema={shape.err}
+              value={err}
+              ctx={{ units, unitsAtRoot: false, raw }}
+              path="$"
+              depth={0}
+            />
+          )}
+        </div>
+      )}
+      candid={() => candidArgsText(method.results, [sent], { width: 80 })}
+      json={() => toDisplayJson(err)}
+    />
+  )
+}

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

@@ -0,0 +1,133 @@
+import { useId, useState, type ReactElement, type ReactNode } from "react"
+import { CopyButton } from "../components/CopyButton.tsx"
+
+export type InspectorView = "tree" | "candid" | "json"
+
+const VIEWS: readonly (readonly [InspectorView, string])[] = [
+  ["tree", "Tree"],
+  ["candid", "Candid"],
+  ["json", "JSON"],
+]
+
+export interface ValueInspectorProps {
+  /** Names the value in labels: "reply", "Err payload". */
+  label: string
+  /** The tree view, given whether token amounts show in base units. */
+  renderTree(raw: boolean): ReactNode
+  /** The Candid text; computed only for that view or a copy. May throw. */
+  candid(): string
+  /** The display JSON; computed only for that view or a copy. */
+  json(): string
+  /** Offer the "Raw amounts" switch (the tree formats amounts in units). */
+  hasUnits?: boolean
+  /** A short note under the toolbar: what the Candid text stands for. */
+  candidNote?: string
+}
+
+/**
+ * One value three ways (a Tree, its Candid text, display JSON) with a copy
+ * button for the text. The Candid view is exact; the JSON view is lossy on
+ * purpose (bigints as strings, blobs as hex).
+ */
+export function ValueInspector({
+  label,
+  renderTree,
+  candid,
+  json,
+  hasUnits = false,
+  candidNote,
+}: ValueInspectorProps): ReactElement {
+  const [view, setView] = useState<InspectorView>("tree")
+  const [raw, setRaw] = useState(false)
+  const bodyId = useId()
+
+  return (
+    <div className="value-inspector">
+      <div className="value-toolbar">
+        <div
+          className="segmented"
+          role="group"
+          aria-label={`Show the ${label} as`}
+        >
+          {VIEWS.map(([id, title]) => (
+            <button
+              key={id}
+              type="button"
+              aria-pressed={view === id}
+              aria-controls={bodyId}
+              onClick={() => setView(id)}
+            >
+              {title}
+            </button>
+          ))}
+        </div>
+        <div className="value-toolbar-actions">
+          {hasUnits && view === "tree" ? (
+            <label className="switch-label text-xs">
+              <input
+                type="checkbox"
+                className="switch"
+                checked={raw}
+                onChange={(event) => setRaw(event.target.checked)}
+              />
+              Raw amounts
+            </label>
+          ) : null}
+          <CopyButton
+            text={view === "json" ? json : candid}
+            a11yLabel={
+              view === "json"
+                ? `Copy the ${label} as JSON`
+                : `Copy the ${label} as Candid text`
+            }
+          />
+        </div>
+      </div>
+      <div id={bodyId} className="value-body">
+        {view === "tree" ? (
+          renderTree(raw)
+        ) : (
+          <TextView
+            compute={view === "candid" ? candid : json}
+            note={view === "candid" ? candidNote : undefined}
+            label={label}
+          />
+        )}
+      </div>
+    </div>
+  )
+}
+
+function TextView({
+  compute,
+  note,
+  label,
+}: {
+  compute: () => string
+  note?: string
+  label: string
+}): ReactElement {
+  let text: string
+  try {
+    text = compute()
+  } catch (error) {
+    return (
+      <div className="notice notice-warn" role="status">
+        <p className="notice-title">
+          The {label} does not have the type&apos;s shape
+        </p>
+        <p className="mono break-all">
+          {error instanceof Error ? error.message : String(error)}
+        </p>
+      </div>
+    )
+  }
+  return (
+    <div className="stack-xs">
+      {note === undefined ? null : <p className="subtle text-xs">{note}</p>}
+      <pre className="code value-code" tabIndex={0} aria-label={label}>
+        {text}
+      </pre>
+    </div>
+  )
+}