solforge: Instructions file for Codex

Development Guidelines for SolForge

Core Principles

1. Keep It Modular

• No huge files: If a file exceeds 200 lines, consider splitting it
• Single responsibility: Each module should do one thing well
• Clear boundaries: Well-defined interfaces between modules

2. Keep It Simple

• Straightforward code: Prefer clarity over cleverness
• Minimal abstractions: Only abstract when there's clear benefit
• Explicit over implicit: Make intentions clear in code

3. Keep It Fast

• Performance matters: This is a performance-critical tool
• Measure first: Profile before optimizing
• Memory conscious: Avoid unnecessary allocations

Technology Rules

Package Manager

• ALWAYS use Bun: No npm, yarn, pnpm, or anything else
• Commands:
  • bun install (not npm install)
  • bun run (not npm run)
  • bun test (not jest/vitest)
  • bun build (not webpack/esbuild)

Runtime

• Bun exclusively: Use Bun-native APIs when available
• Prefer Bun.serve() over Express
• Use Bun.file() over fs.readFile()
• Use bun:test for testing

Code Style

File Naming

• kebab-case: All files use kebab-case
  • ✅ rpc-server.ts
  • ✅ get-account-info.ts
  • ❌ rpcServer.ts
  • ❌ GetAccountInfo.ts

Directory Structure

packages/server/src/
├── methods/
│   ├── account/           # When account.ts gets too big
│   │   ├── get-account-info.ts
│   │   ├── get-balance.ts
│   │   ├── get-multiple-accounts.ts
│   │   └── index.ts
│   ├── transaction/       # When transaction.ts gets too big
│   │   ├── send-transaction.ts
│   │   ├── simulate-transaction.ts
│   │   └── index.ts
│   └── index.ts

File Size Guidelines

• < 100 lines: Ideal file size
• 100-200 lines: Acceptable
• > 200 lines: Consider splitting
• > 300 lines: Must split

When to Split Files

If account.ts or transaction.ts grows large:

1. Create a directory with the same name
2. Split into individual method files
3. Create an index.ts that exports everything
4. Update imports to maintain compatibility