@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/mcp/src/interface/compile.test.ts

@@ -0,0 +1,155 @@
+// The compile steps over the real compiler, in its worker (offline).
+import { readFile } from "node:fs/promises"
+import { serviceMethods } from "@meantjs/schema"
+import { afterAll, describe, expect, it } from "vitest"
+import {
+  compileInterface,
+  MAX_DID_BYTES,
+  MAX_METHODS,
+  projectionOf,
+  tooLarge,
+  type CompiledInterface,
+} from "./compile.ts"
+import { createWorkerCli } from "./compile-worker.ts"
+
+const icrc1Did = await readFile(
+  new URL("./fixtures/icrc1.did", import.meta.url),
+  "utf8"
+)
+
+const cli = createWorkerCli()
+afterAll(() => cli.close())
+
+async function compiled(did: string): Promise<CompiledInterface> {
+  const result = await compileInterface(cli, did)
+  if (!result.ok) throw new Error(`${result.code}: ${result.message}`)
+  return result
+}
+
+describe("compileInterface", () => {
+  it("compiles a .did to its service schema, methods in name order with their docs", async () => {
+    const result = await compiled(`
+      service : {
+        /// Says hello.
+        greet : (name : text) -> (text) query;
+        count : () -> (nat);
+        peek : () -> (nat) composite_query;
+      }
+    `)
+    expect(result.interfaceId).toMatch(
+      /^candid-core:interface:v1:sha256:[0-9a-f]{64}$/
+    )
+    expect([...serviceMethods(result.actor).keys()].sort()).toEqual([
+      "count",
+      "greet",
+      "peek",
+    ])
+    expect([...result.methods.keys()]).toEqual(["count", "greet", "peek"])
+    const greet = result.methods.get("greet")
+    expect(greet).toMatchObject({
+      name: "greet",
+      mode: "query",
+      doc: "Says hello.",
+    })
+    expect(greet?.args).toHaveLength(1)
+    expect(greet?.results).toHaveLength(1)
+    expect(result.methods.get("count")).not.toHaveProperty("doc")
+    expect(result.methods.get("peek")?.mode).toBe("composite_query")
+    expect(result.omitted).toEqual([])
+  })
+
+  it("takes a service class's methods, and gives the same interface id for the same .did", async () => {
+    const a = await compiled(icrc1Did)
+    const b = await compiled(`${icrc1Did}\n// a comment changes no identity\n`)
+    expect(a.methods.size).toBe(10)
+    expect(a.methods.get("icrc1_transfer")?.mode).toBe("update")
+    expect(b.interfaceId).toBe(a.interfaceId)
+  })
+
+  it("orders methods by code point, not by UTF-16 code unit", async () => {
+    const result = await compiled(
+      'service : { "\u{1F600}" : () -> (); "Ａ" : () -> (); a : () -> () }'
+    )
+    // U+FF21 sorts before U+1F600, whose first code unit (0xD83D) is lower.
+    expect([...result.methods.keys()]).toEqual(["a", "Ａ", "\u{1F600}"])
+  })
+
+  it("reports what the schema loader left out, and why", async () => {
+    const result = await compiled(
+      "type T = record { _1_ : nat }; service : { m : (T) -> (); n : () -> () }"
+    )
+    expect([...result.methods.keys()]).toEqual(["n"])
+    expect(result.omitted).toEqual([
+      { kind: "declaration", name: "T", reason: "reserved_field_name" },
+      { kind: "method", name: "m", reason: "references_omitted", via: "T" },
+    ])
+  })
+
+  it("counts the cap in UTF-8 bytes", () => {
+    const fits = "é".repeat(MAX_DID_BYTES / 2)
+    expect(tooLarge(fits)).toBeUndefined()
+    expect(tooLarge(`${fits}x`)).toMatchObject({ code: "too_large" })
+  })
+
+  it("refuses an interface of more than MAX_METHODS methods as too large", async () => {
+    const service = (n: number) =>
+      `service : {${Array.from({ length: n }, (_, i) => `m${i} : () -> ();`).join("")}}`
+    expect(await compileInterface(cli, service(MAX_METHODS))).toMatchObject({
+      ok: true,
+    })
+    expect(await compileInterface(cli, service(MAX_METHODS + 1))).toMatchObject(
+      {
+        ok: false,
+        code: "too_large",
+        message: `The interface has ${MAX_METHODS + 1} methods; the server loads at most ${MAX_METHODS}.`,
+      }
+    )
+  })
+
+  it("keeps a hostile method name as data", async () => {
+    const result = await compiled(
+      'service : { "__proto__" : () -> (); "<img src=x onerror=alert(1)>" : () -> () query }'
+    )
+    expect([...result.methods.keys()]).toEqual([
+      "<img src=x onerror=alert(1)>",
+      "__proto__",
+    ])
+    expect(Object.getPrototypeOf(result.methods.get("__proto__"))).toBe(
+      Object.prototype
+    )
+  })
+
+  it("returns the compiler's diagnostics for a .did that does not compile", async () => {
+    const result = await compileInterface(cli, "service : { broken")
+    expect(result).toMatchObject({ ok: false, code: "compile_failed" })
+    if (result.ok) return
+    expect(result.diagnostics?.[0]?.code).toBe("did_parse_error")
+  })
+
+  it("says no_interface for a .did without a service", async () => {
+    expect(await compileInterface(cli, "type T = nat;")).toMatchObject({
+      ok: false,
+      code: "no_interface",
+    })
+  })
+})
+
+describe("projectionOf", () => {
+  it("projects onto the methods named, in name order", async () => {
+    const result = await projectionOf(cli, icrc1Did, [
+      "icrc1_transfer",
+      "icrc1_balance_of",
+    ])
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.methods).toEqual(["icrc1_balance_of", "icrc1_transfer"])
+    expect(result.did).toContain("icrc1_transfer")
+    expect(result.did).not.toContain("icrc1_symbol")
+  })
+
+  it("names an unknown method", async () => {
+    const result = await projectionOf(cli, icrc1Did, ["no_such_method"])
+    expect(result).toMatchObject({ ok: false })
+    if (!result.ok) expect(result.message).toMatch(/unknown_method/)
+  })
+})

package/packages/mcp/src/interface/compile.ts

@@ -0,0 +1,281 @@
+// The compile steps: a .did to the schemas the server calls with. Each takes
+// the `@meantjs/cli` functions as an argument (the worker's, in the server;
+// a counting or failing wrapper, in tests), so this module never loads the
+// 1.9 MB WASM itself.
+import type {
+  checkCompatible,
+  Diagnostic,
+  didToContract,
+  didToModule,
+  projectDid,
+} from "@meantjs/cli"
+import {
+  serviceMethods,
+  type AnySchema,
+  type ServiceMethod,
+} from "@meantjs/schema"
+import { schemaFromContract } from "@meantjs/schema/contract"
+import { CompileDeadlineError } from "./compile-worker.ts"
+import { methodDocsFromModule } from "./docs.ts"
+import type {
+  CanisterInterface,
+  InterfaceErrorCode,
+  MethodInfo,
+} from "./types.ts"
+
+/** The `@meantjs/cli` functions the compile steps use. */
+export interface CandidCli {
+  didToContract: typeof didToContract
+  didToModule: typeof didToModule
+  projectDid: typeof projectDid
+  checkCompatible: typeof checkCompatible
+}
+
+/**
+ * The largest .did read from a canister or a file. The largest public
+ * interface on mainnet (Internet Identity) is about 100 KB and compiles in
+ * 30 ms. The cap does not bound compile time by itself: a hostile .did at
+ * the cap (19,500 methods `m0 : () -> ();`) compiles in 2.5 s, 5 s with a
+ * `///` comment, and its projection takes 4.7 s. The worker's deadline
+ * bounds each compiler call.
+ */
+export const MAX_DID_BYTES = 256 * 1024
+
+/**
+ * The most methods an interface may have. Internet Identity, the largest on
+ * mainnet, has 113. Past this the schemas and the tool list grow with the
+ * canister's whim (19,500 methods made a 906 KB envelope), so a larger
+ * interface is refused as too large.
+ */
+export const MAX_METHODS = 1_000
+
+/** At most this many compiler diagnostics are returned. */
+const MAX_DIAGNOSTICS = 20
+/** And each message is cut to this many characters. */
+const MAX_MESSAGE = 300
+
+export type CompileFailure = {
+  readonly ok: false
+  readonly code: Extract<
+    InterfaceErrorCode,
+    "compile_failed" | "no_interface" | "too_large" | "timeout"
+  >
+  readonly message: string
+  readonly diagnostics?: readonly { code: string; message: string }[]
+}
+
+/** A compiled interface: the schemas, shared by every canister with the .did. */
+export type CompiledInterface = {
+  readonly ok: true
+  /** `candid-core:interface:v1:sha256:…`: equal ids, the same interface. */
+  readonly interfaceId: string
+  readonly actor: AnySchema
+  readonly methods: ReadonlyMap<string, MethodInfo>
+  readonly omitted: CanisterInterface["omitted"]
+  /** The length of the envelope's JSON text, which the loader's cache weighs. */
+  readonly envelopeLength: number
+}
+
+/** The UTF-8 size of a text, which is what the cap counts. */
+export function utf8Length(text: string): number {
+  return Buffer.byteLength(text, "utf8")
+}
+
+/** The cap check, as the failure it gives (or `undefined` within the cap). */
+export function tooLarge(did: string): CompileFailure | undefined {
+  const bytes = utf8Length(did)
+  if (bytes <= MAX_DID_BYTES) return undefined
+  return {
+    ok: false,
+    code: "too_large",
+    message: `The interface is ${bytes} bytes; the server compiles at most ${MAX_DID_BYTES} bytes.`,
+  }
+}
+
+/**
+ * Compiles a .did to the schemas the server calls with: checks that
+ * `schemaFromContract` accepts the envelope, that it declares a service and
+ * that it has at most `MAX_METHODS` methods, and reads its method docs. Never
+ * throws for a bad .did: the compiler's diagnostics come back as a
+ * `compile_failed` failure, a compile stopped at its deadline as `timeout`.
+ * A compiler that cannot run at all still throws.
+ */
+export async function compileInterface(
+  cli: CandidCli,
+  did: string
+): Promise<CompiledInterface | CompileFailure> {
+  const large = tooLarge(did)
+  if (large !== undefined) return large
+
+  const envelope = await beforeDeadline(() => cli.didToContract(did))
+  if ("deadline" in envelope) {
+    return { ok: false, code: "timeout", message: envelope.message }
+  }
+  if (!("contract" in envelope)) {
+    return {
+      ok: false,
+      code: "compile_failed",
+      message: "The interface's Candid did not compile.",
+      diagnostics: summarize(envelope.diagnostics),
+    }
+  }
+  // On this thread, unlike the compile: it took 26 ms on the largest
+  // envelope the compiler accepts within the cap.
+  const built = schemaFromContract(envelope)
+  if (!built.ok) {
+    return {
+      ok: false,
+      code: "compile_failed",
+      message: "The compiled interface was refused by the schema loader.",
+      diagnostics: summarize(built.issues),
+    }
+  }
+  if (built.actor === undefined) {
+    return {
+      ok: false,
+      code: "no_interface",
+      message: "The Candid declares no service, so there is nothing to call.",
+    }
+  }
+  const table = serviceMethods(built.actor)
+  if (table.size > MAX_METHODS) {
+    return {
+      ok: false,
+      code: "too_large",
+      message: `The interface has ${table.size} methods; the server loads at most ${MAX_METHODS}.`,
+    }
+  }
+  return {
+    ok: true,
+    interfaceId: interfaceIdOf(envelope.contract),
+    actor: built.actor,
+    methods: methodsOf(table, await docsOf(cli, did)),
+    omitted: built.omitted.map((o) => ({ ...o })),
+    envelopeLength: JSON.stringify(envelope).length,
+  }
+}
+
+// The methods of a service, in name order (code point, as the compiler
+// orders them), each with its doc when it has one.
+function methodsOf(
+  table: ReadonlyMap<string, ServiceMethod>,
+  docs: ReadonlyMap<string, string>
+): Map<string, MethodInfo> {
+  const methods = [...table.values()].sort((a, b) =>
+    byCodePoint(a.name, b.name)
+  )
+  return new Map(
+    methods.map((m): [string, MethodInfo] => {
+      const doc = docs.get(m.name)
+      return [
+        m.name,
+        {
+          name: m.name,
+          mode: m.mode,
+          args: m.args,
+          results: m.results,
+          ...(doc === undefined ? {} : { doc }),
+        },
+      ]
+    })
+  )
+}
+
+/** `projectDid(did, methods)`, as a result that never throws for a bad .did. */
+export async function projectionOf(
+  cli: CandidCli,
+  did: string,
+  methods: readonly string[]
+): Promise<
+  { ok: true; did: string; methods: string[] } | { ok: false; message: string }
+> {
+  const large = tooLarge(did)
+  if (large !== undefined) return { ok: false, message: large.message }
+  const result = await beforeDeadline(() => cli.projectDid(did, methods))
+  if ("deadline" in result) return { ok: false, message: result.message }
+  if (!result.ok) {
+    return {
+      ok: false,
+      message: failureMessage("The projection failed", result.diagnostics),
+    }
+  }
+  return { ok: true, did: result.did, methods: result.methods }
+}
+
+// A compiler call, or the message of the deadline that stopped it. Any
+// other error (a compiler that cannot run) is thrown on.
+async function beforeDeadline<T>(
+  call: () => Promise<T>
+): Promise<T | { deadline: true; message: string }> {
+  try {
+    return await call()
+  } catch (error) {
+    if (error instanceof CompileDeadlineError) {
+      return { deadline: true, message: error.message }
+    }
+    throw error
+  }
+}
+
+// A failure's diagnostics, bounded in count and length.
+function summarize(
+  items: readonly Pick<Diagnostic, "code" | "message">[]
+): { code: string; message: string }[] {
+  return items.slice(0, MAX_DIAGNOSTICS).map(({ code, message }) => ({
+    code,
+    message: message.slice(0, MAX_MESSAGE),
+  }))
+}
+
+// "<lead>: code: message; …", naming at most three diagnostics.
+function failureMessage(
+  lead: string,
+  diagnostics: readonly Diagnostic[]
+): string {
+  const first = diagnostics
+    .slice(0, 3)
+    .map((d) => `${d.code}: ${d.message.slice(0, MAX_MESSAGE)}`)
+  const more =
+    diagnostics.length > 3 ? ` (and ${diagnostics.length - 3} more)` : ""
+  return first.length === 0 ? `${lead}.` : `${lead}: ${first.join("; ")}${more}`
+}
+
+// Docs come only from line comments (`///` or `//`): without one there are
+// none, and the second compile (didToModule) is skipped. Docs are extras: a
+// module that does not generate in time costs them, not the interface.
+async function docsOf(
+  cli: CandidCli,
+  did: string
+): Promise<ReadonlyMap<string, string>> {
+  if (!did.includes("//")) return new Map()
+  const result = await beforeDeadline(() => cli.didToModule(did))
+  return "deadline" in result || !result.ok
+    ? new Map()
+    : methodDocsFromModule(result.module)
+}
+
+// `ContractEnvelope.contract` is typed `unknown` on purpose (its shape
+// versions independently); this reads one string from it, defensively.
+function interfaceIdOf(contract: unknown): string {
+  if (typeof contract !== "object" || contract === null) return ""
+  const identities: unknown = Reflect.get(contract, "identities")
+  if (typeof identities !== "object" || identities === null) return ""
+  const id: unknown = Reflect.get(identities, "interface")
+  return typeof id === "string" ? id : ""
+}
+
+// Code-point order, not `<` (UTF-16 code units, which put an astral
+// character before U+E000..U+FFFF) and not localeCompare.
+function byCodePoint(a: string, b: string): number {
+  const x = a[Symbol.iterator]()
+  const y = b[Symbol.iterator]()
+  for (;;) {
+    const p = x.next()
+    const q = y.next()
+    if (p.done === true || q.done === true) {
+      return p.done === true ? (q.done === true ? 0 : -1) : 1
+    }
+    const d = (p.value.codePointAt(0) ?? 0) - (q.value.codePointAt(0) ?? 0)
+    if (d !== 0) return d
+  }
+}

package/packages/mcp/src/interface/docs.test.ts

@@ -0,0 +1,105 @@
+// Method docs, read from modules the real compiler writes (in its worker,
+// offline).
+import { readFile } from "node:fs/promises"
+import { afterAll, describe, expect, it } from "vitest"
+import { createWorkerCli } from "./compile-worker.ts"
+import { methodDocsFromModule } from "./docs.ts"
+
+const icrc1Did = await readFile(
+  new URL("./fixtures/icrc1.did", import.meta.url),
+  "utf8"
+)
+
+const cli = createWorkerCli()
+afterAll(() => cli.close())
+
+async function moduleOf(did: string): Promise<string> {
+  const result = await cli.didToModule(did)
+  if (!result.ok) throw new Error(JSON.stringify(result.diagnostics))
+  return result.module
+}
+
+describe("methodDocsFromModule", () => {
+  it("reads each documented method of a module didToModule wrote", async () => {
+    const module = await moduleOf(`
+      type R = record { x : nat };
+      service : {
+        /// Adds one.
+        ///
+        /// A second paragraph, with */ and @param x in it.
+        inc : (by : nat, label : text) -> (nat);
+        bare : () -> () query;
+        /// The last one.
+        last : (R) -> (R) composite_query;
+      }
+    `)
+    expect(methodDocsFromModule(module)).toEqual(
+      new Map([
+        // The generator's own `@param by` / `@param label` lines are
+        // dropped; the comment's escaped `*\/` and `\@param` are read back.
+        ["inc", "Adds one.\n\nA second paragraph, with */ and @param x in it."],
+        ["last", "The last one."],
+      ])
+    )
+  })
+
+  it("reads `//` comments as docs, as the compiler does (the ckBTC minter's are)", async () => {
+    const module = await moduleOf(`
+      service : {
+        // Section "Minter Information" {{{
+        // Returns internal minter parameters.
+        get_minter_info : () -> (nat) query;
+        // }}} Section "Minter Information"
+
+        get_canister_status : () -> (nat);
+      }
+    `)
+    // A comment a blank line away from a method is not its doc.
+    expect(methodDocsFromModule(module)).toEqual(
+      new Map([
+        [
+          "get_minter_info",
+          'Section "Minter Information" {{{\nReturns internal minter parameters.',
+        ],
+      ])
+    )
+  })
+
+  it("finds none in the ICRC-1 .did, whose comments are on its types", async () => {
+    expect(methodDocsFromModule(await moduleOf(icrc1Did))).toEqual(new Map())
+  })
+
+  it("reads quoted and computed member names, __proto__ like any other", () => {
+    const module = [
+      "export type Actor = {",
+      "  /**",
+      "   * Spaced.",
+      "   */",
+      '  "hello world": (() => Promise<void>) & $.WithMode<"update">;',
+      "  /**",
+      "   * Escaped quote.",
+      "   */",
+      '  "say \\"hi\\"": (() => Promise<void>) & $.WithMode<"query">;',
+      "  /** A one-liner. */",
+      '  ["__proto__"]: (() => Promise<void>) & $.WithMode<"update">;',
+      "  /**",
+      "   * Constructor.",
+      "   */",
+      '  constructor: (() => Promise<void>) & $.WithMode<"update">;',
+      '  toString: (() => Promise<void>) & $.WithMode<"update">;',
+      "};",
+    ].join("\n")
+    expect(methodDocsFromModule(module)).toEqual(
+      new Map([
+        ["hello world", "Spaced."],
+        ['say "hi"', "Escaped quote."],
+        ["__proto__", "A one-liner."],
+        ["constructor", "Constructor."],
+      ])
+    )
+  })
+
+  it("gives nothing for text without an Actor type", () => {
+    expect(methodDocsFromModule("export const x = 1\n").size).toBe(0)
+  })
+})

package/packages/mcp/src/interface/docs.ts

@@ -0,0 +1,86 @@
+// Method docs come from the module `didToModule` writes (the compiled
+// envelope has none): the comment lines just above a service method, `///`
+// or `//`, become the JSDoc above its `Actor` member. The generator writes
+// one member per line, indented two spaces, which is what this reads. It
+// keeps a comment only when the method name is not quoted in the .did, so
+// other methods have no docs to read.
+
+const ACTOR_START = "export type Actor = {"
+const ACTOR_END = "\n};"
+
+// A member's name: an identifier, a quoted name ("hello world"), or a
+// computed one (["__proto__"], which a plain key would turn into a prototype).
+const MEMBER =
+  /^ {2}(?:([A-Za-z_$][\w$]*)|("(?:[^"\\]|\\.)*")|\[("(?:[^"\\]|\\.)*")\]): /
+
+/**
+ * The doc text of each `Actor` method in a generated module, by Candid
+ * method name. Methods without a doc comment are absent. The generator's
+ * `@param` lines (argument names only) are dropped, and its escapes of `*\/`
+ * and `\@` in the original comment are undone. A Map: the names are canister
+ * text, `__proto__` included.
+ */
+export function methodDocsFromModule(moduleText: string): Map<string, string> {
+  const docs = new Map<string, string>()
+  const start = moduleText.indexOf(ACTOR_START)
+  if (start === -1) return docs
+  const end = moduleText.indexOf(ACTOR_END, start)
+  const block = moduleText.slice(
+    start + ACTOR_START.length,
+    end === -1 ? undefined : end
+  )
+
+  let pending: string[] | undefined
+  let inComment = false
+  for (const line of block.split("\n")) {
+    if (inComment) {
+      if (/^ {3}\*\/\s*$/.test(line)) {
+        inComment = false
+      } else {
+        pending?.push(line.replace(/^ {3}\* ?/, ""))
+      }
+      continue
+    }
+    if (/^ {2}\/\*\*\s*$/.test(line)) {
+      inComment = true
+      pending = []
+      continue
+    }
+    // A one-line doc is written on one line: `/** Text. */`.
+    const oneLine = /^ {2}\/\*\* (.*) \*\/\s*$/.exec(line)
+    if (oneLine !== null) {
+      pending = [oneLine[1] ?? ""]
+      continue
+    }
+    const member = MEMBER.exec(line)
+    if (member !== null) {
+      const name = memberName(member)
+      const text = pending === undefined ? "" : docText(pending)
+      if (name !== undefined && text !== "") docs.set(name, text)
+    }
+    pending = undefined
+  }
+  return docs
+}
+
+function memberName(match: RegExpExecArray): string | undefined {
+  const [, identifier, quoted, computed] = match
+  if (identifier !== undefined) return identifier
+  const literal = quoted ?? computed
+  if (literal === undefined) return undefined
+  try {
+    const name: unknown = JSON.parse(literal)
+    return typeof name === "string" ? name : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function docText(lines: readonly string[]): string {
+  const kept = lines
+    .filter((line) => !line.startsWith("@param"))
+    .map((line) => line.replaceAll("*\\/", "*/").replaceAll("\\@", "@"))
+  while (kept.length > 0 && kept[0]?.trim() === "") kept.shift()
+  while (kept.length > 0 && kept[kept.length - 1]?.trim() === "") kept.pop()
+  return kept.join("\n")
+}