Skip to content

development.mdx

Latest commit

 

History

History
274 lines (220 loc) · 7.88 KB

development.mdx

File metadata and controls

274 lines (220 loc) · 7.88 KB
title Development Guide
description Set up your local development environment, run tests, and contribute to SINT Protocol.
sidebarTitle Development

Prerequisites

Tool Version Purpose
Node.js 20+ Runtime
pnpm 9+ Package manager (monorepo workspaces)
Git 2.40+ Version control
Docker 24+ Optional: PostgreSQL + Redis for persistence

Local Setup

```bash git clone https://github.com/sint-ai/sint-protocol.git cd sint-protocol ``` ```bash pnpm install ``` This installs dependencies for all 35 workspace projects (24 packages + 5 apps + 6 examples/tools). ```bash pnpm build ``` Uses Turborepo to build 34 tasks in parallel with dependency-aware ordering. ```bash pnpm test ``` Runs 1,363 tests across the entire monorepo. All tests should pass on a clean build. ```bash cd apps/gateway-server pnpm dev ``` Gateway starts on `http://localhost:4100` by default. Turborepo caches build outputs. Subsequent builds only recompile changed packages. Use `pnpm build --force` to bypass the cache.

Monorepo Structure

sint-protocol/
├── packages/          # 24 publishable packages
│   ├── core/          # @sint/core — types, schemas, constants
│   ├── capability-tokens/  # @sint/gate-capability-tokens
│   ├── policy-gateway/     # @sint/gate-policy-gateway
│   ├── evidence-ledger/    # @sint/gate-evidence-ledger
│   ├── persistence/        # @sint/persistence
│   ├── persistence-postgres/ # @sint/persistence-postgres
│   ├── client/             # @sint/client (TypeScript SDK)
│   ├── bridge-ros2/        # @sint/bridge-ros2
│   ├── bridge-mcp/         # @sint/bridge-mcp
│   ├── bridge-grpc/        # @sint/bridge-grpc
│   ├── bridge-a2a/         # @sint/bridge-a2a
│   ├── bridge-economy/     # @sint/bridge-economy
│   ├── bridge-mqtt-sparkplug/
│   ├── bridge-opcua/
│   ├── bridge-iot/
│   ├── bridge-mavlink/
│   ├── bridge-open-rmf/
│   ├── bridge-swarm/
│   ├── engine-hal/         # Hardware abstraction layer
│   ├── engine-system1/     # Fast reactive subsystem
│   ├── engine-system2/     # Deliberative planning subsystem
│   ├── engine-capsule-sandbox/
│   ├── avatar/             # CSML escalation for avatars
│   └── conformance-tests/  # Compliance test suite
├── apps/
│   ├── gateway-server/     # Hono HTTP server
│   ├── dashboard/          # Admin dashboard (React)
│   ├── sintctl/            # CLI tool
│   ├── sint-mcp/           # MCP bridge server
│   └── sint-mcp-scanner/   # MCP discovery tool
├── sdks/
│   ├── python/             # Python SDK (1,962 lines)
│   └── go/                 # Go SDK
├── examples/
│   └── notes-server/       # Example MCP server
├── docs/
│   └── whitepaper-v2.md    # Technical whitepaper
├── turbo.json              # Turborepo config
├── pnpm-workspace.yaml     # Workspace definition
└── package.json            # Root config + pnpm overrides

Running Specific Packages

Build a single package

pnpm --filter @sint/core build

Test a single package

pnpm --filter @sint/gate-capability-tokens test

Run the conformance test suite

cd packages/conformance-tests
pnpm test

The conformance suite includes 114 tests covering:

  • ROS2 control loop latency (P50/P95/P99 assertions)
  • Token lifecycle validation
  • Gateway policy evaluation
  • Evidence ledger integrity
  • Bridge protocol compliance

Environment Variables

Gateway Server

Variable Default Description
PORT 4100 HTTP server port
SINT_API_KEY (none) Admin endpoint authentication. Required in production.
SINT_STORE memory Evidence store: memory, postgres
SINT_CACHE memory Token cache: memory, redis
SINT_STRICT_BENCH false Enforce strict latency thresholds in conformance tests
DATABASE_URL (none) PostgreSQL connection string (when SINT_STORE=postgres)
REDIS_URL (none) Redis connection string (when SINT_CACHE=redis)

Docker Development

# Start PostgreSQL + Redis for persistence testing
docker compose up -d

# Run gateway with persistent storage
SINT_STORE=postgres SINT_CACHE=redis pnpm dev

Testing

Test Hierarchy

Suite Package Tests Focus
Unit @sint/gate-capability-tokens Ed25519 crypto, delegation Cryptographic correctness
Unit @sint/gate-policy-gateway Intercept pipeline Policy enforcement
Unit @sint/gate-evidence-ledger Hash chain, proof receipts Audit integrity
Unit @sint/client 12 tests SDK API surface
Integration conformance-tests 114 tests End-to-end protocol compliance
Performance conformance-tests ROS2 latency benchmark P50 < 10ms, P95 < 15ms

Running tests with coverage

pnpm test -- --coverage

Strict performance mode

SINT_STRICT_BENCH=true pnpm --filter @sint/conformance-tests test

In strict mode, P95 latency must stay under 10ms (default non-strict threshold is 15ms to accommodate CI load).

CI/CD

The repository uses GitHub Actions for continuous integration:

  • Build: Turborepo parallel build of all 34 tasks
  • Test: Full test suite (1,363 tests)
  • Audit: pnpm audit for dependency vulnerabilities
  • Lint: TypeScript strict mode across all packages
Always run `pnpm build && pnpm test` locally before pushing. The CI pipeline catches the same issues but takes longer.

Contributing

Fork `sint-ai/sint-protocol` on GitHub. ```bash git checkout -b feat/your-feature-name ``` Follow the existing code style. TypeScript strict mode is enforced. Add tests for new functionality. ```bash pnpm build && pnpm test ``` All 34 build tasks must succeed. All 1,363+ tests must pass. Open a PR against `sint-ai/sint-protocol:main`. Include a clear description of changes and any relevant issue numbers.

Code Style

  • TypeScript strict mode (strict: true in tsconfig.json)
  • ES modules ("type": "module" in all packages)
  • Vitest for testing
  • Zod for runtime validation
  • No any types in production code

Package Naming Convention

Pattern Example Description
@sint/core Core types Foundation types and schemas
@sint/gate-* @sint/gate-capability-tokens Security gate components
@sint/bridge-* @sint/bridge-ros2 Protocol bridge adapters
@sint/engine-* @sint/engine-hal Runtime engine components
@sint/persistence-* @sint/persistence-postgres Storage adapters

Useful Commands

# List all workspace packages
pnpm list --depth 0 -r

# Check for dependency vulnerabilities
pnpm audit

# Update all dependencies
pnpm update --recursive

# Generate a keypair (gateway must be running)
curl -X POST http://localhost:4100/v1/keypair

# Check gateway health
curl http://localhost:4100/v1/health

# View OpenAPI spec
curl http://localhost:4100/v1/openapi.json