PolyForge

PolyForge is a Polygon-focused smart-contract playground that pairs a modern React UI with hardened platform utilities. This repository tracks the incremental delivery of Milestone 1, establishing robust configuration, error handling, logging, and metrics foundations for the broader application.

Key Capabilities

• Environment validation powered by Zod to guarantee required configuration before runtime.
• Chain configuration for Polygon Amoy (testnet) with typed guards for future network expansion.
• Custom error taxonomy covering validation, authentication, blockchain, compilation, and rate-limiting scenarios.
• Structured logging with JSON payloads, context propagation, metadata sanitisation, and production-safe transport handling.
• Metrics utility supporting timers, counters, gauges, batching, and auto-flush pipelines for observability dashboards.
• Comprehensive unit test coverage via Vitest across each foundational module.

Project Structure Highlights

polyForge/
├─ src/
│  ├─ config/
│  │  ├─ chains.ts         // Polygon network defaults
│  │  ├─ env.ts            // Zod-backed env loader
│  │  └─ env.test.ts       // Validation test suite
│  ├─ types/
│  │  └─ errors.ts         // PolyForge error hierarchy
│  └─ utils/
│     ├─ errorHandler.ts   // Error normalisation and UX messaging
│     ├─ logger.ts         // Structured logger implementation
│     ├─ logger.test.ts    // Logger behaviour coverage
│     ├─ metrics.ts        // Metrics collection + transport logic
│     └─ metrics.test.ts   // Metrics timer/counter/gauge tests
└─ vitest.setup.ts

Getting Started

Prerequisites

• Node.js 18+
• npm 9+

Installation

npm install

Development Scripts

npm run dev         # Start Vite dev server
npm run build       # Production build output
npm run lint        # ESLint with TypeScript + React rules
npm run lint:fix    # Autofix lint issues where possible
npm run format      # Prettier formatting
npm run format:check# Prettier verification
npm run typecheck   # Standalone TypeScript diagnostics
npm run test        # Vitest unit tests
npm run test:watch  # Vitest in watch mode
npm run validate    # Runs lint + typecheck + build

Configuration

Create a .env file (or copy .env.example) and populate the required credentials:

cp .env.example .env.local

Environment variables are validated at startup. Missing or malformed values trigger descriptive ValidationError instances so issues surface immediately.

Observability Utilities

• src/utils/logger.ts emits structured JSON logs, suppresses debug noise in production, and supports custom transports while shielding the app from transport failures.
• src/utils/errorHandler.ts converts thrown values into the PolyForge error taxonomy and supplies user-friendly messaging helpers.
• src/utils/metrics.ts enables timers, counters, and gauges with batching, interval-driven auto flush, transport hooks, and deterministic time providers for tests.

Each utility ships with exhaustive unit tests in the /src/utils directory to ensure reliability as the platform scales.

Testing

Vitest is configured with a JSDOM environment:

npm run test

For coverage or watch mode:

npm run test -- --coverage
npm run test -- --watch

Milestone 1 Progress

• ✅ Step 1.1 – Project initialisation & tooling
• ✅ Step 1.2 – Environment config & validation
• ✅ Step 1.3 – Error handling foundation
• ✅ Step 1.4 – Structured logging infrastructure
• ✅ Step 1.5 – Metrics collection and observability

Subsequent milestones will introduce state management, editor integration, compilation services, authentication, and deployment workflows. Track detailed implementation notes in memory-bank/PolyForge Implementation.md and delivery status in memory-bank/progress.md.