@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/safety/RequestLog.tsx

@@ -0,0 +1,79 @@
+import type { JSX } from "react"
+import { shortPrincipal } from "../lib/format.ts"
+import type { LoggedRequest } from "./scenarios.ts"
+
+/** What happened to a request, in a few words. */
+function noteOf(request: LoggedRequest): string {
+  if (request.refused !== undefined) return request.refused
+  if (request.dropped === true) return "ran, reply lost"
+  if (request.endpoint === "read_state") return "state read (keys, certificate)"
+  return ""
+}
+
+/**
+ * The requests the in-memory replica received during a run, in order: what
+ * left the client, as the replica saw it after checking each signature.
+ */
+export function RequestLog(props: {
+  readonly requests: readonly LoggedRequest[]
+  readonly caption: string
+}): JSX.Element {
+  const { requests, caption } = props
+  if (requests.length === 0) {
+    return (
+      <p className="safety-log-empty">
+        <span className="badge badge-ok">0 requests</span> Nothing reached the
+        replica.
+      </p>
+    )
+  }
+  return (
+    <div className="table-wrap">
+      <table className="table table-compact safety-log">
+        <caption className="sr-only">{caption}</caption>
+        <thead>
+          <tr>
+            <th scope="col" className="num">
+              #
+            </th>
+            <th scope="col">Endpoint</th>
+            <th scope="col">Method</th>
+            <th scope="col">Caller</th>
+            <th scope="col">Note</th>
+          </tr>
+        </thead>
+        <tbody>
+          {requests.map((request, i) => (
+            // The log only grows during a run and is replaced as a whole, so
+            // the position is the request's identity.
+            <tr
+              key={i}
+              className={
+                request.refused !== undefined || request.dropped === true
+                  ? "safety-log-flagged"
+                  : undefined
+              }
+            >
+              <td className="num">{i + 1}</td>
+              <td>
+                <code className="code-inline">{request.endpoint}</code>
+              </td>
+              <td className="mono">{request.methodName ?? ""}</td>
+              <td
+                className="mono nowrap"
+                title={
+                  request.caller === undefined ? undefined : request.caller
+                }
+              >
+                {request.caller === undefined
+                  ? ""
+                  : shortPrincipal(request.caller)}
+              </td>
+              <td>{noteOf(request)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/examples/canister-studio/src/safety/SafetyLab.test.tsx

@@ -0,0 +1,89 @@
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  within,
+} from "@testing-library/react"
+import { renderToString } from "react-dom/server"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { SafetyLab } from "./SafetyLab.tsx"
+import { ScenarioCard } from "./ScenarioCard.tsx"
+import { SCENARIOS, type ScenarioResult } from "./scenarios.ts"
+
+// The other areas' components are tested where they live; doubles keep this
+// test about the lab.
+vi.mock("../calls/ErrorPanel.tsx", () => ({
+  ErrorPanel: (props: { error: unknown }) => (
+    <div data-testid="error-panel">
+      {props.error instanceof Error ? props.error.message : String(props.error)}
+    </div>
+  ),
+}))
+vi.mock("../values/ReplyView.tsx", () => ({
+  ReplyView: () => <div data-testid="reply-view" />,
+}))
+vi.mock("../forms/MethodForm.tsx", () => ({
+  MethodForm: () => <div data-testid="method-form" />,
+}))
+
+afterEach(cleanup)
+
+describe("SafetyLab", () => {
+  it("server-renders every card, none run, the same way every time", () => {
+    const first = renderToString(<SafetyLab />)
+    expect(renderToString(<SafetyLab />)).toBe(first)
+    for (const scenario of SCENARIOS) expect(first).toContain(scenario.title)
+    expect(first.match(/Not run/g)).toHaveLength(SCENARIOS.length)
+  })
+
+  it("runs a scenario on click and shows its verdict, checks and request log", async () => {
+    render(<SafetyLab />)
+    const card = screen
+      .getByRole("heading", { name: /Scenario 1:/ })
+      .closest("article")
+    if (card === null) throw new Error("no card")
+    fireEvent.click(within(card).getByRole("button", { name: "Run" }))
+    expect(await within(card).findByText("Pass")).toBeTruthy()
+    expect(
+      within(card).getByText("Verdict: ic-reactor did what this claims")
+    ).toBeTruthy()
+    // The verdict is announced too, from a live region present from the start.
+    expect(within(card).getByText(/^Scenario 1 passed\./)).toBeTruthy()
+    expect(within(card).getByText("0 requests")).toBeTruthy()
+    expect(within(card).getByTestId("error-panel").textContent).toMatch(
+      /needs a signed-in caller/
+    )
+    expect(screen.getByText("1 passed, 0 failed, 9 not run")).toBeTruthy()
+  })
+})
+
+describe("ScenarioCard", () => {
+  it("says loudly when ic-reactor behaves differently", () => {
+    const failed: ScenarioResult = {
+      verdict: {
+        pass: false,
+        summary: "ic-reactor behaved differently: kind.",
+      },
+      steps: [
+        { label: "kind", status: "fail", detail: 'expected "a", got "b"' },
+      ],
+      requests: [],
+    }
+    const [scenario] = SCENARIOS
+    if (scenario === undefined) throw new Error("no scenario")
+    render(
+      <ScenarioCard
+        number={1}
+        scenario={scenario}
+        state={{ status: "done", result: failed }}
+        blocked={false}
+        onRun={() => {}}
+      />
+    )
+    expect(screen.getByText("Fail")).toBeTruthy()
+    expect(screen.getByText("Verdict: FAILED")).toBeTruthy()
+    expect(screen.getByText("Check FAILED:")).toBeTruthy()
+    expect(screen.getByText('expected "a", got "b"')).toBeTruthy()
+  })
+})

package/examples/canister-studio/src/safety/SafetyLab.tsx

@@ -0,0 +1,140 @@
+import { useCallback, useRef, useState, type JSX } from "react"
+import { ActionButton } from "../components/ActionButton.tsx"
+import { loadLabRuntime } from "./mock-ledger.ts"
+import { ScenarioCard, type RunState } from "./ScenarioCard.tsx"
+import { LAB_SETUP, SCENARIOS, type Scenario } from "./scenarios.ts"
+
+const IDLE: RunState = { status: "idle" }
+
+type LabStatus =
+  | { readonly status: "ready" }
+  | { readonly status: "unavailable"; readonly message: string }
+
+/**
+ * The Safety lab: each scenario runs on click, in the browser, against a fresh
+ * `createTestClient()` (a mock ICRC-1 ledger on an in-memory replica that
+ * signs and certifies like the real one, so nothing goes over the network),
+ * and checks what ic-reactor did. The server renders the cards; nothing runs
+ * until a visitor asks.
+ */
+export function SafetyLab(): JSX.Element {
+  const [runs, setRuns] = useState<Readonly<Record<string, RunState>>>({})
+  const [lab, setLab] = useState<LabStatus>({ status: "ready" })
+  const [busy, setBusy] = useState(false)
+  // A synchronous guard as well as the state: two clicks in one frame must
+  // not start two runs.
+  const running = useRef(false)
+
+  const runScenarios = useCallback(
+    async (list: readonly Scenario[]): Promise<void> => {
+      if (running.current) return
+      const setRun = (id: string, state: RunState): void =>
+        setRuns((all) => ({ ...all, [id]: state }))
+      running.current = true
+      setBusy(true)
+      try {
+        await loadLabRuntime()
+        setLab({ status: "ready" })
+        for (const scenario of list) {
+          setRun(scenario.id, { status: "running" })
+          setRun(scenario.id, { status: "done", result: await scenario.run() })
+        }
+      } catch (cause) {
+        setLab({
+          status: "unavailable",
+          message: cause instanceof Error ? cause.message : String(cause),
+        })
+      } finally {
+        running.current = false
+        setBusy(false)
+      }
+    },
+    []
+  )
+
+  const done = SCENARIOS.flatMap((s) => {
+    const state = runs[s.id]
+    return state?.status === "done" ? [state.result.verdict.pass] : []
+  })
+  const passed = done.filter(Boolean).length
+  const failed = done.length - passed
+
+  return (
+    <div className="stack-lg safety-lab">
+      <section className="card" aria-labelledby="safety-intro-title">
+        <div className="card-body stack">
+          <h2 className="card-title" id="safety-intro-title">
+            How the lab works
+          </h2>
+          <p>
+            Every scenario creates a fresh test client from{" "}
+            <code className="code-inline">@ic-reactor/core/testing</code> in
+            this tab: a real ic-reactor client whose agent talks to an in-memory
+            replica. The replica checks each signature and certifies each reply
+            as the IC does, and runs a mock ICRC-1 ledger at the ckBTC ledger's
+            id, with balances, a fee and{" "}
+            <code className="code-inline">created_at_time</code> deduplication.
+            Nothing leaves the page.
+          </p>
+          <p>
+            Each run checks what ic-reactor did, step by step. If the library
+            ever behaves differently from what a card says, its verdict turns to
+            FAILED and names the check that did not hold.
+          </p>
+          <details className="disclosure">
+            <summary>The setup every scenario starts from</summary>
+            <div className="disclosure-body">
+              <pre className="code">
+                <code>{LAB_SETUP}</code>
+              </pre>
+            </div>
+          </details>
+          <div className="row row-between">
+            <ActionButton
+              className="btn btn-primary"
+              unavailable={busy}
+              onClick={() => void runScenarios(SCENARIOS)}
+            >
+              {busy && (
+                <span className="spinner spinner-sm" aria-hidden="true" />
+              )}
+              {busy ? "Running…" : "Run all scenarios"}
+            </ActionButton>
+            <p className="safety-tally" aria-live="polite">
+              {done.length === 0
+                ? `${SCENARIOS.length} scenarios, none run yet`
+                : `${passed} passed, ${failed} failed, ${SCENARIOS.length - done.length} not run`}
+            </p>
+          </div>
+          {lab.status === "unavailable" && (
+            <div className="notice notice-warn" role="alert">
+              <p className="notice-title">
+                The test client could not start in this browser
+              </p>
+              <p className="break-all">{lab.message}</p>
+              <p>
+                Each card still says what the scenario shows when it runs, under
+                Expected; <code className="code-inline">pnpm test</code> runs
+                every scenario headless.
+              </p>
+            </div>
+          )}
+        </div>
+      </section>
+
+      <ol className="list-plain stack-lg" aria-label="Scenarios">
+        {SCENARIOS.map((scenario, i) => (
+          <li key={scenario.id} id={scenario.id} className="safety-item">
+            <ScenarioCard
+              number={i + 1}
+              scenario={scenario}
+              state={runs[scenario.id] ?? IDLE}
+              blocked={busy}
+              onRun={() => void runScenarios([scenario])}
+            />
+          </li>
+        ))}
+      </ol>
+    </div>
+  )
+}

package/examples/canister-studio/src/safety/ScenarioCard.tsx

@@ -0,0 +1,262 @@
+import { isReactorError } from "@ic-reactor/core"
+import { useId, type JSX } from "react"
+import { ErrorPanel } from "../calls/ErrorPanel.tsx"
+import { ReplyView } from "../values/ReplyView.tsx"
+import { LabTransferForm } from "./LabTransferForm.tsx"
+import { LAB_UNITS, labMethod } from "./mock-ledger.ts"
+import { RequestLog } from "./RequestLog.tsx"
+import type {
+  Scenario,
+  ScenarioReply,
+  ScenarioResult,
+  ScenarioStep,
+} from "./scenarios.ts"
+
+/** Where a scenario's card is: never run, running, or run with its result. */
+export type RunState =
+  | { readonly status: "idle" }
+  | { readonly status: "running" }
+  | { readonly status: "done"; readonly result: ScenarioResult }
+
+export interface ScenarioCardProps {
+  readonly number: number
+  readonly scenario: Scenario
+  readonly state: RunState
+  /** Set while another run is going: one scenario runs at a time. */
+  readonly blocked: boolean
+  onRun(): void
+}
+
+/** One scenario: what it claims, the code it runs, a Run button, and what came back. */
+export function ScenarioCard(props: ScenarioCardProps): JSX.Element {
+  const { number, scenario, state, blocked, onRun } = props
+  const titleId = useId()
+  const running = state.status === "running"
+  return (
+    <article
+      className="card safety-card"
+      aria-labelledby={titleId}
+      aria-busy={running}
+    >
+      <header className="card-header safety-card-header">
+        <span className="safety-number" aria-hidden="true">
+          {number}
+        </span>
+        <h2 className="card-title safety-card-title" id={titleId}>
+          <span className="sr-only">Scenario {number}: </span>
+          {scenario.title}
+        </h2>
+        <VerdictBadge state={state} />
+      </header>
+      <div className="card-body stack">
+        <p>{scenario.narrative}</p>
+        <p className="safety-rule">
+          <span className="safety-rule-label">The rule</span>
+          {scenario.rule}
+        </p>
+        <p className="text-sm">
+          <strong>Expected: </strong>
+          <span className="muted">{scenario.expected}</span>
+        </p>
+        <details className="disclosure">
+          <summary>The code it runs</summary>
+          <div className="disclosure-body">
+            <pre className="code">
+              <code>{scenario.code}</code>
+            </pre>
+          </div>
+        </details>
+        <div className="row">
+          <button
+            type="button"
+            className="btn btn-primary"
+            onClick={onRun}
+            disabled={running || blocked}
+          >
+            {running && (
+              <span className="spinner spinner-sm" aria-hidden="true" />
+            )}
+            {running
+              ? "Running…"
+              : state.status === "done"
+                ? "Run again"
+                : "Run"}
+          </button>
+        </div>
+        {/* Present from the first render, so screen readers announce each verdict. */}
+        <p className="sr-only" aria-live="polite">
+          {state.status === "done"
+            ? `Scenario ${number} ${state.result.verdict.pass ? "passed" : "failed"}. ${state.result.verdict.summary}`
+            : ""}
+        </p>
+        {state.status === "done" && (
+          <ScenarioOutcome scenario={scenario} result={state.result} />
+        )}
+      </div>
+    </article>
+  )
+}
+
+function VerdictBadge(props: { readonly state: RunState }): JSX.Element {
+  const { state } = props
+  if (state.status === "idle") {
+    return <span className="badge safety-verdict">Not run</span>
+  }
+  if (state.status === "running") {
+    return <span className="badge badge-info safety-verdict">Running</span>
+  }
+  return state.result.verdict.pass ? (
+    <span className="badge badge-ok badge-dot safety-verdict">Pass</span>
+  ) : (
+    <span className="badge badge-err badge-dot safety-verdict">Fail</span>
+  )
+}
+
+function ScenarioOutcome(props: {
+  readonly scenario: Scenario
+  readonly result: ScenarioResult
+}): JSX.Element {
+  const { scenario, result } = props
+  return (
+    <div className="stack safety-outcome">
+      {result.verdict.pass ? (
+        <div className="notice notice-success">
+          <p className="notice-title">
+            Verdict: ic-reactor did what this claims
+          </p>
+          <p>{result.verdict.summary}</p>
+        </div>
+      ) : (
+        <div className="notice notice-danger">
+          <p className="notice-title">Verdict: FAILED</p>
+          <p>{result.verdict.summary}</p>
+        </div>
+      )}
+
+      <section className="stack-sm" aria-label="Steps and checks">
+        <h3 className="safety-subtitle">Steps and checks</h3>
+        <ol className="list-plain safety-steps">
+          {result.steps.map((step, i) => (
+            // Steps are recorded once per run and never reordered.
+            <StepItem key={i} step={step} />
+          ))}
+        </ol>
+      </section>
+
+      <section className="stack-sm" aria-label="Request log">
+        <h3 className="safety-subtitle">
+          Request log{" "}
+          <span className="muted text-sm">
+            ({result.requests.length}{" "}
+            {result.requests.length === 1 ? "request" : "requests"})
+          </span>
+        </h3>
+        <RequestLog
+          requests={result.requests}
+          caption={`Requests the replica received in scenario ${scenario.title}`}
+        />
+      </section>
+
+      {result.error !== undefined && (
+        <section className="stack-sm" aria-label="The error">
+          <h3 className="safety-subtitle">The ReactorError</h3>
+          <LabErrorPanel error={result.error} />
+        </section>
+      )}
+
+      {result.moreErrors?.map((more) => (
+        <section key={more.label} className="stack-sm" aria-label={more.label}>
+          <h3 className="safety-subtitle">{more.label}</h3>
+          <LabErrorPanel
+            error={more.error}
+            afterResend={more.afterResend === true}
+          />
+        </section>
+      ))}
+
+      {result.form !== undefined && (
+        <section className="stack-sm" aria-label="The arguments in a form">
+          <h3 className="safety-subtitle">The issues on a form</h3>
+          <p className="text-sm muted">
+            The studio's automatic form for icrc1_transfer, prefilled with the
+            refused argument. Fix the fields and send it to a fresh lab.
+          </p>
+          <LabTransferForm
+            method={result.form.method}
+            values={result.form.values}
+            error={result.error}
+          />
+        </section>
+      )}
+
+      {result.reply !== undefined && <LabReply reply={result.reply} />}
+    </div>
+  )
+}
+
+const STEP_MARKS: Readonly<
+  Record<ScenarioStep["status"], { mark: string; label: string }>
+> = {
+  pass: { mark: "✓", label: "Check held" },
+  fail: { mark: "✗", label: "Check FAILED" },
+  info: { mark: "→", label: "Step" },
+}
+
+function StepItem(props: { readonly step: ScenarioStep }): JSX.Element {
+  const { step } = props
+  const { mark, label } = STEP_MARKS[step.status]
+  return (
+    <li className={`safety-step safety-step-${step.status}`}>
+      <span className="safety-step-mark" aria-hidden="true">
+        {mark}
+      </span>
+      <span className="sr-only">{label}: </span>
+      <span className="safety-step-text">
+        <span>{step.label}</span>
+        {step.detail !== undefined && step.detail !== "" && (
+          <span className="safety-step-detail mono break-all">
+            {step.detail}
+          </span>
+        )}
+      </span>
+    </li>
+  )
+}
+
+/** ErrorPanel with the mock ledger's method, so a canister_err shows its typed Err payload. */
+function LabErrorPanel(props: {
+  readonly error: unknown
+  readonly afterResend?: boolean
+}): JSX.Element {
+  const method = isReactorError(props.error)
+    ? labMethod(props.error.method)
+    : undefined
+  return (
+    <ErrorPanel
+      error={props.error}
+      method={method}
+      units={LAB_UNITS}
+      earlierUnknown={props.afterResend}
+    />
+  )
+}
+
+function LabReply(props: {
+  readonly reply: ScenarioReply
+}): JSX.Element | null {
+  const { reply } = props
+  const method = labMethod(reply.method)
+  if (method === undefined) return null
+  return (
+    <section className="stack-sm" aria-label="The reply">
+      <h3 className="safety-subtitle">
+        Reply of <span className="mono">{reply.method}</span>
+      </h3>
+      <ReplyView
+        method={method}
+        reply={reply.value}
+        units={reply.tokens ? LAB_UNITS : undefined}
+      />
+    </section>
+  )
+}