@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/mcp/src/candid/schema-walk.ts

@@ -0,0 +1,189 @@
+// Schema reading helpers shared by the JSON walks, the JSON Schema writer and
+// the Candid text printers, over @meantjs/schema's public API only. Ported
+// from canister-studio's lib/schema.ts.
+import {
+  resolveSchema,
+  type AnyFieldSchema,
+  type ResolvedNode,
+} from "@meantjs/schema"
+
+export type RecordNode = Extract<ResolvedNode, { kind: "record" }>
+export type TupleNode = Extract<ResolvedNode, { kind: "tuple" }>
+export type VariantNode = Extract<ResolvedNode, { kind: "variant" }>
+export type OptNode = Extract<ResolvedNode, { kind: "opt" }>
+export type FuncNode = Extract<ResolvedNode, { kind: "func" }>
+export type ServiceNode = Extract<ResolvedNode, { kind: "service" }>
+
+// Generated modules build a fresh node on every `rec` body() call: memoizing
+// on the schema object gives one node per declaration, so a walk can tell a
+// recursive type by identity. Loaded schemas are already one node per type.
+const resolved = new WeakMap<object, ResolvedNode>()
+
+/**
+ * The schema with every `rec` followed: what `.kind` can be read on.
+ *
+ * @throws TypeError on what is not a schema, and on a `rec` chain that never
+ * ends (`resolveSchema`'s programmer errors).
+ */
+export function resolve(schema: AnyFieldSchema): ResolvedNode {
+  let node = resolved.get(schema)
+  if (node === undefined) {
+    node = resolveSchema(schema)
+    resolved.set(schema, node)
+  }
+  return node
+}
+
+// The erased node types carry `any` children (RecordSchema<any>.fields is
+// `any`): these accessors name their real shape once.
+
+/** A record's fields in schema order (Candid label-id order). */
+export function fieldsOf(
+  node: RecordNode
+): readonly (readonly [string, AnyFieldSchema])[] {
+  return Object.entries(node.fields as Record<string, AnyFieldSchema>)
+}
+
+/** A tuple's element schemas. */
+export function elementsOf(node: TupleNode): readonly AnyFieldSchema[] {
+  return node.elements as readonly AnyFieldSchema[]
+}
+
+/** A variant's arms in schema order. */
+export function armsOf(
+  node: VariantNode
+): readonly (readonly [string, AnyFieldSchema])[] {
+  return Object.entries(node.arms as Record<string, AnyFieldSchema>)
+}
+
+/** The schema of field `key`, read as an own property ("toString" is a field name too). */
+export function fieldOf(
+  node: RecordNode,
+  key: string
+): AnyFieldSchema | undefined {
+  return getOwn(node.fields as Record<string, AnyFieldSchema>, key)
+}
+
+/** The arm schema of `tag`, read as an own property ("toString" is a valid tag). */
+export function armOf(
+  node: VariantNode,
+  tag: string
+): AnyFieldSchema | undefined {
+  return getOwn(node.arms as Record<string, AnyFieldSchema>, tag)
+}
+
+/** A service's methods, each resolved to its func node, in schema order. */
+export function methodsOf(
+  node: ServiceNode
+): readonly (readonly [string, ResolvedNode])[] {
+  return Object.entries(node.methods).map(([name, method]) => [
+    name,
+    resolve(method),
+  ])
+}
+
+/** Whether a variant arm carries no payload (its type is `null`). */
+export function isTagOnly(arm: AnyFieldSchema): boolean {
+  const node = resolve(arm)
+  return node.kind === "primitive" && node.primitive === "null"
+}
+
+/** Whether a schema's values include no value at all (`empty`). */
+export function isEmptyType(schema: AnyFieldSchema): boolean {
+  const node = resolve(schema)
+  return node.kind === "primitive" && node.primitive === "empty"
+}
+
+/**
+ * Whether a resolved node's domain admits `null`: an opt over one of these
+ * boxes its present value as `{ some }`. The rule `isBoxedOpt` states, applied
+ * to a node already resolved.
+ */
+export function admitsNull(node: ResolvedNode): boolean {
+  return (
+    node.kind === "opt" ||
+    (node.kind === "primitive" &&
+      (node.primitive === "null" || node.primitive === "reserved"))
+  )
+}
+
+/** Whether an opt node's present value is boxed (`opt opt T`, `opt null`, `opt reserved`). */
+export function isBoxed(node: OptNode): boolean {
+  return admitsNull(resolve(node.inner))
+}
+
+/**
+ * `obj[key] = v` with key "__proto__" sets the prototype instead of an own
+ * property, and validate() then reports missing_field. Candid allows any
+ * label, so every keyed write of a value or a schema map goes through this.
+ */
+export function setOwn<T>(obj: Record<string, T>, key: string, value: T): void {
+  Object.defineProperty(obj, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  })
+}
+
+/** Own-property read: `fields["toString"]` must not find Object.prototype's. */
+export function getOwn<T>(
+  obj: Readonly<Record<string, T>>,
+  key: string
+): T | undefined {
+  return Object.hasOwn(obj, key) ? obj[key] : undefined
+}
+
+/**
+ * Whether `key` is an own enumerable property of `obj`: what validate and the
+ * encoder count as present, and what JSON.parse creates.
+ */
+export function hasOwnEnumerable(obj: object, key: string): boolean {
+  return Object.prototype.propertyIsEnumerable.call(obj, key)
+}
+
+// The %TypedArray%.prototype[@@toStringTag] getter reads the internal slot:
+// "Uint8Array" for a genuine Uint8Array from any realm (a Node Buffer
+// included) and undefined for a prototype forgery. The check validate uses.
+const typedArrayTag = Object.getOwnPropertyDescriptor(
+  Object.getPrototypeOf(Uint8Array.prototype) as object,
+  Symbol.toStringTag
+)?.get
+
+/** Whether a value is a `Uint8Array`, as `@meantjs/schema` recognizes a blob. */
+export function isBytes(value: unknown): value is Uint8Array {
+  return typedArrayTag?.call(value) === "Uint8Array"
+}
+
+/** A non-null object that is not an array or bytes: a record, variant or box. */
+export function isPlainObject(
+  value: unknown
+): value is Record<string, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !isBytes(value)
+  )
+}
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+/** A child's path in the codec's grammar: `$.to.owner`, `$["a b"]`, `$[3]`. */
+export function childPath(path: string, seg: string | number): string {
+  if (typeof seg === "number") return `${path}[${seg}]`
+  return IDENT.test(seg) ? `${path}.${seg}` : `${path}[${JSON.stringify(seg)}]`
+}
+
+/**
+ * The numeric id of a key `_N_`, the schema's spelling of an unnamed Candid
+ * label (a copy of `@meantjs/schema`'s internal `numericKeyId`).
+ */
+export function numericLabelId(key: string): number | undefined {
+  const match = /^_([0-9]+)_$/.exec(key)
+  const digits = match?.[1]
+  if (digits === undefined) return undefined
+  if (digits.length > 1 && digits.startsWith("0")) return undefined
+  const id = Number(digits)
+  return Number.isSafeInteger(id) && id < 4_294_967_296 ? id : undefined
+}

package/packages/mcp/src/candid/type-text.test.ts

@@ -0,0 +1,179 @@
+import { c, type Schema } from "@meantjs/schema"
+import { describe, expect, it } from "vitest"
+import { signatureText, typeText } from "./type-text.ts"
+
+const Account = c.rec(() =>
+  c.record({ owner: c.principal, subaccount: c.opt(c.blob()) })
+)
+const TransferArg = c.rec(() =>
+  c.record({
+    to: Account,
+    fee: c.opt(c.nat),
+    memo: c.opt(c.blob()),
+    from_subaccount: c.opt(c.blob()),
+    created_at_time: c.opt(c.nat64),
+    amount: c.nat,
+  })
+)
+const TransferError = c.rec(() =>
+  c.variant({
+    BadFee: c.record({ expected_fee: c.nat }),
+    TooOld: c.null,
+    GenericError: c.record({ error_code: c.nat, message: c.text }),
+  })
+)
+const TransferResult = c.rec(() => c.variant({ Ok: c.nat, Err: TransferError }))
+
+type List = { head: bigint; tail: List | null }
+const List: Schema<List> = c.rec(() =>
+  c.record({ head: c.nat, tail: c.opt(List) })
+)
+
+describe("typeText", () => {
+  it("writes every kind structurally", () => {
+    expect(typeText(c.nat)).toBe("nat")
+    expect(typeText(c.blob())).toBe("blob")
+    expect(typeText(c.vec(c.nat8))).toBe("vec nat8")
+    expect(typeText(c.unit())).toBe("record {}")
+    expect(typeText(c.opt(c.opt(c.text)))).toBe("opt opt text")
+    expect(typeText(c.tuple([c.text, c.nat]))).toBe("record { text; nat }")
+    expect(typeText(Account)).toBe(
+      "record { owner : principal; subaccount : opt blob }"
+    )
+    expect(typeText(c.variant({ Ok: c.nat, Pending: c.null }))).toBe(
+      "variant { Ok : nat; Pending }"
+    )
+    expect(typeText(c.func([c.nat], [c.text], "query"))).toBe(
+      "func (nat) -> (text) query"
+    )
+    expect(
+      typeText(
+        c.service({
+          name: c.func([], [c.text], "query"),
+          go: c.func([c.nat], [], "update"),
+        })
+      )
+    ).toBe("service { name : () -> (text) query; go : (nat) -> () }")
+    expect(typeText(c.service({}))).toBe("service {}")
+    expect(typeText(c.reserved)).toBe("reserved")
+    expect(typeText(c.empty)).toBe("empty")
+  })
+
+  it("quotes names that are not identifiers and numbers unnamed labels", () => {
+    expect(
+      typeText(
+        c.record({ type: c.nat, "a b": c.text, _7_: c.bool, ok_1: c.null })
+      )
+    ).toBe('record { "type" : nat; "a b" : text; 7 : bool; ok_1 : null }')
+    expect(typeText(c.service({ query: c.func([], [], "oneway") }))).toBe(
+      'service { "query" : () -> () oneway }'
+    )
+    expect(typeText(c.record({ "evil\u202e": c.nat }))).toBe(
+      'record { "evil\\u{202e}" : nat }'
+    )
+  })
+
+  it("writes a recursive occurrence as …", () => {
+    expect(typeText(List)).toBe("record { head : nat; tail : opt … }")
+    type Tree = { tag: "leaf"; value: bigint } | { tag: "node"; value: Tree[] }
+    const Tree: Schema<Tree> = c.rec(() =>
+      c.variant({ leaf: c.nat, node: c.vec(Tree) })
+    )
+    expect(typeText(Tree)).toBe("variant { leaf : nat; node : vec … }")
+    // A type used twice side by side is not recursion.
+    expect(typeText(c.record({ from: Account, to: Account }))).toBe(
+      "record { from : record { owner : principal; subaccount : opt blob }; to : record { owner : principal; subaccount : opt blob } }"
+    )
+  })
+
+  it("cuts deep parts to … to fit maxChars, keeping the outer shape", () => {
+    const full = typeText(TransferArg)
+    expect(full).toBe(
+      "record { to : record { owner : principal; subaccount : opt blob }; fee : opt nat; memo : opt blob; from_subaccount : opt blob; created_at_time : opt nat64; amount : nat }"
+    )
+    const shallow = typeText(TransferArg, { maxChars: 140 })
+    expect(shallow).toBe(
+      "record { to : record { … }; fee : opt nat; memo : opt blob; from_subaccount : opt blob; created_at_time : opt nat64; amount : nat }"
+    )
+    // Not even every top-level field fits: as many as fit, then `…`.
+    const cut = typeText(TransferArg, { maxChars: 120 })
+    expect(cut).toBe(
+      "record { to : record { … }; fee : opt nat; memo : opt blob; from_subaccount : opt blob; created_at_time : opt nat64; … }"
+    )
+    expect(cut.length).toBeLessThanOrEqual(120)
+    expect(typeText(TransferArg, { maxChars: 20 })).toBe("record { … }")
+  })
+
+  it("cuts the text itself when even the outer shape is too long", () => {
+    const text = typeText(TransferArg, { maxChars: 8 })
+    expect(text).toBe("record …")
+    expect(text.length).toBe(8)
+  })
+
+  it("refuses a maxChars that is not a positive integer", () => {
+    expect(() => typeText(c.nat, { maxChars: 0 })).toThrow(TypeError)
+    expect(() => typeText(c.nat, { maxChars: 1.5 })).toThrow(TypeError)
+  })
+
+  it("stays within maxChars on a type that grows without end", () => {
+    // A hand-built schema whose rec makes a fresh node every time: no
+    // identity repeats, so only the character budget stops it.
+    const endless = (): Schema<unknown> =>
+      c.rec(() => c.opt(c.vec(endless()))) as unknown as Schema<unknown>
+    const text = typeText(endless(), { maxChars: 60 })
+    expect(text.length).toBeLessThanOrEqual(60)
+    expect(text.endsWith("…")).toBe(true)
+  })
+
+  it("keeps a wide type's cost bounded", () => {
+    const fields = Object.fromEntries(
+      Array.from({ length: 5000 }, (_, i) => [`field_${i}`, TransferArg])
+    )
+    const text = typeText(c.record(fields), { maxChars: 100 })
+    expect(text.length).toBeLessThanOrEqual(100)
+    expect(text.startsWith("record { field_0 : record { … }; ")).toBe(true)
+  })
+})
+
+describe("signatureText", () => {
+  it("writes arguments, results and the mode", () => {
+    expect(signatureText({ args: [], results: [c.nat], mode: "query" })).toBe(
+      "() -> (nat) query"
+    )
+    expect(
+      signatureText({
+        args: [c.nat, c.opt(c.text)],
+        results: [],
+        mode: "update",
+      })
+    ).toBe("(nat, opt text) -> ()")
+    expect(
+      signatureText({ args: [], results: [], mode: "composite_query" })
+    ).toBe("() -> () composite_query")
+    expect(signatureText({ args: [c.text], results: [], mode: "oneway" })).toBe(
+      "(text) -> () oneway"
+    )
+  })
+
+  it("writes icrc1_transfer, cutting nested groups to fit", () => {
+    const method = {
+      args: [TransferArg],
+      results: [TransferResult],
+      mode: "update" as const,
+    }
+    expect(signatureText(method)).toBe(
+      "(record { to : record { owner : principal; subaccount : opt blob }; fee : opt nat; memo : opt blob; from_subaccount : opt blob; created_at_time : opt nat64; amount : nat }) -> (variant { Ok : nat; Err : variant { BadFee : record { expected_fee : nat }; TooOld; GenericError : record { error_code : nat; message : text } } })"
+    )
+    expect(signatureText(method, { maxChars: 260 })).toBe(
+      "(record { to : record { … }; fee : opt nat; memo : opt blob; from_subaccount : opt blob; created_at_time : opt nat64; amount : nat }) -> (variant { Ok : nat; Err : variant { … } })"
+    )
+    const cut = signatureText(method, { maxChars: 120 })
+    expect(cut).toBe(
+      "(record { to : record { … }; fee : opt nat; memo : opt blob; … }) -> (variant { Ok : nat; Err : variant { … } })"
+    )
+    expect(cut.length).toBeLessThanOrEqual(120)
+    expect(signatureText(method, { maxChars: 40 })).toBe(
+      "(record { … }) -> (variant { … })"
+    )
+  })
+})

package/packages/mcp/src/candid/type-text.ts

@@ -0,0 +1,238 @@
+// Compact Candid type text for tool descriptions and messages:
+//   record { owner : principal; subaccount : opt blob }
+//   (record { … }) -> (variant { Ok : nat; Err : variant { … } })
+// Structural: declaration names are not in a schema, so a type is spelled out.
+// A recursive occurrence is `…`; so is whatever does not fit `maxChars`.
+import type { AnyFieldSchema, MethodMode, ServiceMethod } from "@meantjs/schema"
+import { candidLabel, candidName } from "./candid-text.ts"
+import {
+  armsOf,
+  elementsOf,
+  fieldsOf,
+  isTagOnly,
+  methodsOf,
+  resolve,
+} from "./schema-walk.ts"
+
+export interface TypeTextOptions {
+  /** The longest text returned, in UTF-16 code units. */
+  readonly maxChars?: number
+}
+
+/** `maxChars` when none is given: a type in a message or a description. */
+export const DEFAULT_TYPE_CHARS = 200
+/** `maxChars` when none is given: a method's whole signature. */
+export const DEFAULT_SIGNATURE_CHARS = 1000
+
+// The deepest brace nesting written before parts become `…`.
+const MAX_NESTING = 32
+
+/** A type as compact Candid text: `record { owner : principal; subaccount : opt blob }`. */
+export function typeText(
+  schema: AnyFieldSchema,
+  options?: TypeTextOptions
+): string {
+  const max = charLimit(options?.maxChars, DEFAULT_TYPE_CHARS)
+  return fit((writer) => writer.type(schema, 0), max)
+}
+
+/** A method's signature: `(record { … }) -> (nat) query`. */
+export function signatureText(
+  method: Pick<ServiceMethod, "args" | "results" | "mode">,
+  options?: TypeTextOptions
+): string {
+  const max = charLimit(options?.maxChars, DEFAULT_SIGNATURE_CHARS)
+  return fit(
+    (writer) => writer.signature(method.args, method.results, method.mode, 0),
+    max
+  )
+}
+
+function charLimit(given: number | undefined, fallback: number): number {
+  if (given === undefined) return fallback
+  if (!Number.isSafeInteger(given) || given < 1) {
+    throw new TypeError(`maxChars must be a positive integer, got ${given}`)
+  }
+  return given
+}
+
+/**
+ * The whole text when it fits; else the deepest nesting that fits, every
+ * group below it written `{ … }`. When not even the top level's items fit,
+ * as many of them as fit, then `…`; else the outline, cut at `max`. Each try
+ * stops writing once past its limit, so a try costs about `max` characters.
+ */
+function fit(write: (writer: TypeWriter) => void, max: number): string {
+  for (let nesting = MAX_NESTING; nesting >= 1; nesting--) {
+    const writer = new TypeWriter(nesting, max, false, 0)
+    write(writer)
+    if (!writer.over) return writer.text()
+  }
+  // A signature's arguments are cut before its results are written: leave
+  // them headroom, more on each try, until the results fit too. A writer that
+  // went past its limit skipped parts, so only one that did not is taken.
+  let headroom = 0
+  for (let attempt = 0; attempt < 6; attempt++) {
+    const writer = new TypeWriter(1, max, true, headroom)
+    write(writer)
+    if (!writer.over && writer.shortBy === 0) return writer.text()
+    const short = writer.over ? writer.text().length - max : writer.shortBy
+    if (headroom >= max) break
+    headroom = Math.max(headroom * 2, headroom + short)
+  }
+  const outline = new TypeWriter(0, max, false, 0)
+  write(outline)
+  const text = outline.text()
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`
+}
+
+class TypeWriter {
+  private parts: string[] = []
+  private length = 0
+  /**
+   * How many characters a group lacked for even its first item, which a cut
+   * then lost: the outline says more than such a text.
+   */
+  shortBy = 0
+  // Characters the open groups still need: their closing brackets.
+  private reserved = 0
+  // Characters to leave free while a signature's arguments are written.
+  private room = 0
+  // Nodes being written: meeting one again is recursion.
+  private readonly active = new Set<object>()
+
+  /**
+   * `nesting`: the brace depth below which a group is `{ … }`. `cut`: end a
+   * group with `…` at the first item that would pass `limit`, instead of
+   * writing on past it. `headroom`: what a signature's arguments leave free
+   * for its results.
+   */
+  constructor(
+    private readonly nesting: number,
+    private readonly limit: number,
+    private readonly cut: boolean,
+    private readonly headroom: number
+  ) {}
+
+  get over(): boolean {
+    return this.length > this.limit
+  }
+
+  text(): string {
+    return this.parts.join("")
+  }
+
+  private put(text: string): void {
+    this.parts.push(text)
+    this.length += text.length
+  }
+
+  type(schema: AnyFieldSchema, depth: number): void {
+    if (this.over) return
+    const node = resolve(schema)
+    switch (node.kind) {
+      case "primitive":
+        return this.put(node.primitive)
+      case "blob":
+        return this.put("blob")
+      case "unit":
+        return this.put("record {}")
+    }
+    if (this.active.has(node)) return this.put("…")
+    this.active.add(node)
+    try {
+      switch (node.kind) {
+        case "opt":
+          this.put("opt ")
+          return this.type(node.inner, depth)
+        case "vec":
+          this.put("vec ")
+          return this.type(node.inner, depth)
+        case "record":
+          return this.group("record", fieldsOf(node), depth, ([key, field]) => {
+            this.put(`${candidLabel(key)} : `)
+            this.type(field, depth + 1)
+          })
+        case "tuple":
+          return this.group("record", elementsOf(node), depth, (element) =>
+            this.type(element, depth + 1)
+          )
+        case "variant":
+          return this.group("variant", armsOf(node), depth, ([tag, arm]) => {
+            this.put(candidLabel(tag))
+            if (isTagOnly(arm)) return
+            this.put(" : ")
+            this.type(arm, depth + 1)
+          })
+        case "func":
+          if (depth >= this.nesting) return this.put("func …")
+          this.put("func ")
+          return this.signature(node.args, node.results, node.mode, depth + 1)
+        case "service":
+          return this.group("service", methodsOf(node), depth, ([name, fn]) => {
+            this.put(`${candidName(name)} : `)
+            if (fn.kind === "func") {
+              this.signature(fn.args, fn.results, fn.mode, depth + 1)
+            } else {
+              this.type(fn, depth + 1)
+            }
+          })
+      }
+    } finally {
+      this.active.delete(node)
+    }
+  }
+
+  signature(
+    args: readonly AnyFieldSchema[],
+    results: readonly AnyFieldSchema[],
+    mode: MethodMode,
+    depth: number
+  ): void {
+    if (depth === 0) this.room = this.headroom
+    this.items("(", args, ", ", ")", (arg) => this.type(arg, depth))
+    this.room = 0
+    this.put(" -> ")
+    this.items("(", results, ", ", ")", (result) => this.type(result, depth))
+    if (mode !== "update") this.put(` ${mode}`)
+  }
+
+  private group<T>(
+    keyword: string,
+    items: readonly T[],
+    depth: number,
+    item: (entry: T) => void
+  ): void {
+    if (items.length === 0) return this.put(`${keyword} {}`)
+    if (depth >= this.nesting) return this.put(`${keyword} { … }`)
+    this.items(`${keyword} { `, items, "; ", " }", item)
+  }
+
+  private items<T>(
+    open: string,
+    items: readonly T[],
+    separator: string,
+    close: string,
+    item: (entry: T) => void
+  ): void {
+    this.put(open)
+    this.reserved += close.length
+    for (let i = 0; i < items.length && !this.over; i++) {
+      const parts = this.parts.length
+      const length = this.length
+      if (i > 0) this.put(separator)
+      item(items[i] as T)
+      // Keep room for this group's `; …` and every open group's bracket.
+      const short = this.length + this.reserved + 3 + this.room - this.limit
+      if (this.cut && short > 0) {
+        if (i === 0) this.shortBy = Math.max(this.shortBy, short)
+        this.parts = this.parts.slice(0, parts)
+        this.length = length
+        this.put(i > 0 ? `${separator}…` : "…")
+        break
+      }
+    }
+    this.reserved -= close.length
+    this.put(close)
+  }
+}