ts-sdks AGENTS.md

AGENTS.md

This file provides guidance to AI agents working with code in this repository.

Overview

This repository contains the TypeScript SDK workspace for Suigar v2 on Sui. The current publishable packages are @suigar/sdk under packages/sdk and @suigar/mcp under packages/mcp. Both packages are ESM-only. The main public SDK integration surface is the suigar() client extension, which is used to build and serialize game transactions on top of @mysten/sui.

Common Commands

Setup and Build

# Initial setup
pnpm install

# Generate bindings and build the package
pnpm --dir packages/sdk run build

# Build without regenerating contract bindings
pnpm --dir packages/sdk run build:ci

# Build the MCP package and bundled MCP App
pnpm turbo run build --filter=@suigar/mcp

# Build and run the local stdio MCP server for manual client testing
pnpm turbo run build --filter=@suigar/mcp
node packages/mcp/dist/bin.mjs

# Regenerate Move contract bindings only
pnpm --dir packages/sdk run codegen

Testing

# Run the full test suite
pnpm --dir packages/sdk run test

# Run type checking
pnpm --dir packages/sdk run typecheck
pnpm --dir packages/mcp run typecheck

# Run a specific vitest file
pnpm --dir packages/sdk exec vitest run test/unit/transactions.test.ts

# Run a specific test name
pnpm --dir packages/sdk exec vitest run -t "builds a coinflip transaction with the configured package id"

Linting and Formatting

# Check lint and formatting
pnpm run lint

# Auto-fix lint and formatting issues
pnpm run lint:fix

Package Management

# Create a changeset
pnpm run changeset

# Apply version updates from changesets
pnpm run changeset:version

# Publish release changes
pnpm run release

Architecture

Repository Structure

• packages/sdk/ - @suigar/sdk package root
  • src/ - SDK source code
  • client.ts - suigar() extension registration and extension client implementation
  • transactions/ - transaction builders for standard and PvP games
  • contracts/ - generated Move bindings and BCS helpers
  • types/ - public option and config types
  • utils/ - public parser, constants, and numeric helpers exposed through @suigar/sdk/utils
  • helpers/ - internal config resolution, metadata encoding, and transaction support helpers
  • configs/ - network-scoped package ids, supported coin types, and price info object ids
• packages/sdk/test/unit/ - Vitest coverage for config resolution, cache helpers, and transaction builders
• packages/mcp/ - @suigar/mcp stdio MCP server and MCP App
  • src/server.ts - MCP server, tool registration, and app resource registration
  • src/tools.ts - SDK-backed tool handlers for config, metadata, and unsigned transaction building
  • src/app/ - Vite-built single-file MCP App UI
  • test/ - Vitest coverage for tools and app resource behavior
• packages/sdk/dist/ - generated build output
• tsconfig.shared.json - shared TypeScript compiler options for workspace packages
• playground/ - workspace-local Next.js integration playground