solforge 0.2.2 → 0.2.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 nitishxyz
+Copyright (c) 2024-2025 nitishxyz
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE. 
+SOFTWARE. 

package/README.md

@@ -1,523 +1,90 @@
-# SolForge – Lightning-Fast Solana Development Server
-
-A blazing-fast, drop-in replacement for `solana-test-validator` built on LiteSVM. Get a full Solana development environment running in under 1 second with comprehensive RPC support and zero configuration.
-
-## 🚀 Why SolForge?
-
-| Feature           | solana-test-validator | SolForge         |
-| ----------------- | --------------------- | ---------------- |
-| **Startup Time**  | 10-30 seconds         | < 1 second       |
-| **Memory Usage**  | 500MB+                | ~50MB            |
-| **Configuration** | Complex setup         | Zero config      |
-| **Airdrops**      | Rate limited          | Unlimited        |
-| **Database**      | Full ledger           | Ephemeral SQLite |
-
-## ✨ Features
-
-- ⚡ **Sub-second startup** with LiteSVM in-memory execution
-- 🔄 **Drop-in replacement** for solana-test-validator
-- 💧 **Unlimited airdrops** via real faucet transfers
-- 🗃️ **Smart persistence** with ephemeral SQLite + Drizzle
-- 🔌 **WebSocket support** for signature subscriptions
-- 🧰 **Universal compatibility** with Solana CLI, Anchor, @solana/kit, web3.js
-- 📊 **Rich RPC coverage** (90+ methods implemented)
-- 🖥️ **Built-in GUI dashboard** for airdrops, mints, and asset management
-- 🎯 **CLI tools** for tokens, programs, and accounts
-
-## 📦 Installation & Quick Start
-
-### Option 1: From Source (Recommended)
-
-```bash
-# Clone and install
-git clone https://github.com/nitishxyz/solforge
-cd solforge
-bun install
-
-# Start the server
-bun start
-# or with debug logging
-DEBUG_RPC_LOG=1 bun start
-```
-
-### Option 2: Compiled Binary (Coming Soon)
-
-```bash
-# Download and run
-curl -L https://github.com/nitishxyz/solforge/releases/latest/download/solforge-$(uname -s)-$(uname -m) -o solforge
-chmod +x solforge
-./solforge  # first run guides you through setup
-```
-
-### Option 3: CLI Development
-
-```bash
-# Use the CLI directly
-bun src/cli/main.ts start
-bun src/cli/main.ts config init  # Create sf.config.json
-```
-
-## 🎯 Usage Examples
-
-### With Solana CLI
-
-```bash
-# Connect to SolForge
-solana config set -u http://localhost:8899
-
-# Get unlimited airdrops
-solana airdrop 1000
-
-# Deploy programs normally
-solana program deploy ./program.so
-```
-
-### With @solana/kit
-
-```typescript
-import { createSolanaRpc, generateKeyPairSigner, lamports } from "@solana/kit";
-
-const rpc = createSolanaRpc("http://localhost:8899");
-
-// Get account balance
-const { value: balance } = await rpc.getBalance(address).send();
-
-// Request airdrops (no limits!)
-const signature = await rpc
-  .requestAirdrop(
-    address,
-    lamports(1_000_000_000n), // 1 SOL
-  )
-  .send();
-```
-
-### With web3.js
-
-```typescript
-import { Connection, PublicKey, LAMPORTS_PER_SOL } from "@solana/web3.js";
-
-const connection = new Connection("http://localhost:8899");
-
-// Get account info
-const accountInfo = await connection.getAccountInfo(publicKey);
-
-// Send transaction
-const signature = await connection.sendTransaction(transaction, [keypair]);
-```
-
-### With Anchor
-
-```typescript
-// anchor.toml - use default settings
-[provider]
-cluster = \"http://127.0.0.1:8899\"
-wallet = \"~/.config/solana/id.json\"
-
-// Deploy and test normally
-anchor build
-anchor deploy
-anchor test --skip-local-validator  # SolForge is already running
-```
-
-## 🖥️ GUI Dashboard
-
-Solforge ships a dark-mode dashboard that starts alongside the RPC server. By default it listens on `http://127.0.0.1:42069` and provides:
-
-- Quick airdrops and SPL mints via a faucet-aware form.
-- Live RPC metrics (slot, block height, transaction count, blockhash, faucet balance).
-- Tables of cloned programs and token mints with one-click modals to import additional assets.
-
-### Launching the Dashboard
-
-```bash
-# Run the interactive CLI (starts RPC + GUI)
-bun src/cli/main.ts
-
-# Or start directly
-bun src/cli/main.ts start
-
-# Open the dashboard
-open http://127.0.0.1:42069
-```
-
-### GUI API Endpoints
-
-The GUI server exposes REST endpoints backed by the same JSON-RPC methods:
-
-| Method & Path             | Description                          |
-| ------------------------- | ------------------------------------ |
-| `GET /api/status`         | Aggregated RPC stats + faucet info   |
-| `GET /api/programs`       | List the registered programs         |
-| `GET /api/tokens`         | Detailed SPL mint metadata           |
-| `POST /api/airdrop`       | Proxy to `requestAirdrop`            |
-| `POST /api/mint`          | Proxy to `solforgeMintTo`            |
-| `POST /api/clone/program` | Proxy to program clone helpers       |
-| `POST /api/clone/token`   | Proxy to token clone helpers         |
-
-Override the GUI port via `sf.config.json` (`gui.port`) or `SOLFORGE_GUI_PORT`.
-
-Run `bun run build:css` before `bun run build:bin` to embed the latest Tailwind styles in the standalone binary.
-
-
-## 🔧 Configuration
-
-SolForge works with zero configuration, but can be customized via environment variables or config file.
-
-### Environment Variables
-
-```bash
-# Server settings
-export RPC_PORT=8899              # HTTP port (WS uses port+1)
-export DEBUG_RPC_LOG=1            # Log all RPC calls
-
-# Database
-export SOLFORGE_DB_MODE=ephemeral # or 'persistent'
-export SOLFORGE_DB_PATH=.solforge/db.db
-
-# Faucet
-export SOLFORGE_FAUCET_LAMPORTS=1000000000000000  # 1M SOL
-```
-
-### Config File (sf.config.json)
-
-```bash
-# Generate default config
-bun src/cli/main.ts config init
-
-# Edit configuration
-bun src/cli/main.ts config set server.rpcPort 9000
-bun src/cli/main.ts config get server.db.mode
-```
-
-```json
-{
-  \"server\": {
-    \"rpcPort\": 8899,
-    \"wsPort\": 8900,
-    \"db\": {
-      \"mode\": \"ephemeral\",
-      \"path\": \".solforge/db.db\"
-    }
-  },
-  \"svm\": {
-    \"initialLamports\": \"1000000000000000\",
-    \"faucetSOL\": 1000
-  },
-  \"clone\": {
-    \"endpoint\": \"https://api.mainnet-beta.solana.com\",
-    \"programs\": [],
-    \"tokens\": [],
-    \"programAccounts\": []
-  },
-  \"gui\": {
-    \"enabled\": true,
-    \"port\": 42069
-  },
-  \"bootstrap\": {
-    \"airdrops\": []
-  }
-}
-```
-
-## 🛠️ CLI Tools
-
-SolForge includes powerful CLI tools for development:
-
-```bash
-# Airdrop SOL to any address
-bun src/cli/main.ts airdrop --to <pubkey> --sol 100
-
-# Interactive token minting
-bun src/cli/main.ts mint
-
-# Clone mainnet programs and data
-bun src/cli/main.ts program clone <program-id>
-bun src/cli/main.ts token clone <mint-address>
-
-# Manage configuration
-bun src/cli/main.ts config init
-bun src/cli/main.ts config set server.rpcPort 9000
-```
-
-## 📡 RPC Method Coverage
-
-### ✅ Fully Implemented (90+ methods)
-
-**Account Operations**
-
-- `getAccountInfo`, `getMultipleAccounts`, `getBalance`
-- `getParsedAccountInfo`, `getProgramAccounts`
-
-**Transaction Operations**
-
-- `sendTransaction`, `simulateTransaction`, `getTransaction`
-- `getSignatureStatuses`, `getSignaturesForAddress`
-
-**Block & Slot Operations**
-
-- `getLatestBlockhash`, `getBlock`, `getBlocks`, `getBlockHeight`
-- `getSlot`, `getSlotLeader`, `getSlotLeaders`
-
-**System & Network**
-
-- `getHealth`, `getVersion`, `getGenesisHash`, `getEpochInfo`
-- `getSupply`, `getInflationRate`, `getVoteAccounts`
-
-**Fee Operations**
-
-- `getFeeForMessage`, `getFees`, `getRecentPrioritizationFees`
-
-**WebSocket Subscriptions**
-
-- `signatureSubscribe/Unsubscribe` ✅ (real-time notifications)
-- Other subscriptions (stubbed but functional)
-
-### ⚠️ Minimal/Stubbed
-
-- Token-specific RPCs (returns defaults unless indexed)
-- Some advanced cluster RPCs (simplified for local dev)
-
-## 💾 Data & Persistence
-
-### Ephemeral Mode (Default)
-
-- SQLite database recreated on each restart
-- Perfect for testing and development
-- Stores full transaction history during session
-
-### Persistent Mode
-
-```bash
-# Enable persistent storage
-export SOLFORGE_DB_MODE=persistent
-bun start
-```
-
-### Database Schema
-
-```sql
--- Transactions with full metadata
-CREATE TABLE transactions (
-  signature TEXT PRIMARY KEY,
-  slot INTEGER,
-  raw_transaction BLOB,  -- Full transaction data
-  logs TEXT,            -- JSON array of logs
-  status TEXT,          -- success/error
-  fee INTEGER,
-  timestamp INTEGER
-);
-
--- Account snapshots
-CREATE TABLE accounts (
-  address TEXT PRIMARY KEY,
-  lamports INTEGER,
-  owner TEXT,
-  data_len INTEGER,
-  last_slot INTEGER
-);
-
--- Address to signature mapping
-CREATE TABLE address_signatures (
-  address TEXT,
-  signature TEXT,
-  slot INTEGER
-);
-```
-
-## 🔌 WebSocket Support
-
-```javascript
-const ws = new WebSocket("ws://localhost:8900");
-
-// Subscribe to signature updates
-ws.send(
-  JSON.stringify({
-    jsonrpc: "2.0",
-    id: 1,
-    method: "signatureSubscribe",
-    params: ["<signature>", { commitment: "confirmed" }],
-  }),
-);
-
-// Receive real-time notifications
-ws.onmessage = (event) => {
-  const response = JSON.parse(event.data);
-  console.log("Signature update:", response);
-};
-```
-
-## 🧪 Testing & Validation
-
-```bash
-# Run comprehensive test suite
-bun run test-client.ts
-
-# Test specific functionality
-bun test
-
-# Validate against real programs
-anchor test --skip-local-validator
-```
-
-## 🏗️ Architecture Overview
-
-```
-SolForge
-├── 🧠 LiteSVM Core           # In-memory execution engine
-├── 🌐 HTTP Server            # JSON-RPC over HTTP
-├── 🔌 WebSocket Server       # Real-time subscriptions
-├── 🗃️ SQLite + Drizzle       # Ephemeral data indexing
-├── 💧 Smart Faucet          # Unlimited SOL distribution
-└── 🎯 CLI Tools             # Developer utilities
-```
-
-### Key Components
-
-- **`index.ts`**: Main server entry point
-- **`server/`**: HTTP and WebSocket servers
-- **`server/methods/`**: Modular RPC implementations
-- **`src/cli/`**: Command-line interface
-- **`src/config/`**: Configuration management
-- **`src/db/`**: Database schema and operations
-
-## 🤝 Development
-
-### Adding New RPC Methods
-
-1. Create method file: `server/methods/your-method.ts`
-2. Implement the `RpcMethodHandler` interface
-3. Export from `server/methods/index.ts`
-4. Add to `rpcMethods` object
-
-```typescript
-// server/methods/your-method.ts
-import type { RpcMethodHandler } from \"../types\";
-
-export const yourMethod: RpcMethodHandler = (id, params, context) => {
-  try {
-    const result = context.svm.someOperation();
-    return context.createSuccessResponse(id, result);
-  } catch (error: any) {
-    return context.createErrorResponse(id, -32603, \"Internal error\");
-  }
-};
-```
-
-### Project Structure
-
-```
-solforge/
-├── index.ts                     # Main entry point
-├── server/                      # Core server
-│   ├── rpc-server.ts           # HTTP server
-│   ├── ws-server.ts            # WebSocket server
-│   ├── methods/                # RPC method implementations
-│   │   ├── account/           # Account methods
-│   │   ├── transaction/       # Transaction methods
-│   │   └── index.ts          # Method registry
-│   └── lib/                   # Utilities
-├── src/                       # CLI and config
-│   ├── cli/                  # Command-line interface
-│   ├── config/               # Configuration management
-│   └── db/                   # Database operations
-├── test-client.ts            # Integration tests
-└── docs/                     # Documentation
-```
-
-### Development Guidelines
-
-- Use **Bun exclusively** (no npm/yarn/node)
-- Keep files **under 200 lines** (split when larger)
-- Follow **kebab-case** for filenames
-- Write **comprehensive tests**
-- Use **TypeScript strictly**
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-**Server won't start**
-
-```bash
-# Check if port is in use
-lsof -i :8899
-
-# Use different port
-RPC_PORT=9000 bun start
-```
-
-**Anchor deploy fails**
-
-```bash
-# Ensure relaxed validation (default)
-# Check logs with debug mode
-DEBUG_RPC_LOG=1 bun start
-```
-
-**WebSocket connection issues**
-
-```bash
-# WebSocket runs on RPC_PORT + 1
-# Default: ws://localhost:8900
-```
-
-**Airdrop not working**
-
-```bash
-# Check faucet was created
-ls .solforge/faucet.json
-
-# Manual airdrop via CLI
-bun src/cli/main.ts airdrop --to <address> --sol 10
-```
-
-## 🔮 Roadmap
-
-### v0.3.0 - Enhanced RPC Coverage
-
-- [ ] Complete token RPC implementations
-- [ ] Advanced subscription support
-- [ ] Improved error handling
-
-### v0.4.0 - Developer Experience
-
-- [ ] Web-based dashboard
-- [ ] Time-travel debugging
-- [ ] Snapshot/restore functionality
-
-### v0.5.0 - Production Features
-
-- [ ] Clustering support
-- [ ] Metrics and monitoring
-- [ ] Plugin architecture
-
-## 📄 License
-
-MIT License - see LICENSE file for details.
-
-## 🤝 Contributing
-
-We welcome contributions! Please see:
-
-- [AGENTS.md](./AGENTS.md) - Development guidelines
-- [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) - Architecture details
-- [SOLFORGE.md](./SOLFORGE.md) - Vision and roadmap
-
-## 🙏 Acknowledgments
-
-Built with ❤️ using:
-
-- [LiteSVM](https://github.com/litesvm/litesvm) - Fast Solana VM
-- [Bun](https://bun.sh) - Lightning-fast JavaScript runtime
-- [Drizzle](https://drizzle.team) - TypeScript SQL toolkit
-
----
-
-**⚡ Ready to build on Solana at lightning speed?**
-
-```bash
-git clone https://github.com/nitishxyz/solforge
-cd solforge && bun install && bun start
-```
-
-_Happy coding! 🦀_
+# SolForge – Fast, Friendly Solana Localnet
+
+SolForge is a drop‑in, sub‑second Solana localnet powered by LiteSVM. It starts fast, works with the standard Solana toolchain, and includes a tiny GUI for everyday tasks.
+
+Highlights
+- Sub‑second startup and low memory usage
+- Works with Solana CLI, Anchor, web3.js, and @solana/kit
+- Unlimited faucet airdrops, simple persistence, WS subscriptions
+- 90+ JSON‑RPC methods implemented (common dev flows covered)
+- Built‑in GUI: airdrops, SPL mints, quick status
+
+Install
+- One‑liner: curl -fsSL https://install.solforge.sh | sh
+- Manual: download a release binary from GitHub and put it on PATH
+
+Quick Start
+- Start localnet: `solforge start`
+- RPC: `http://127.0.0.1:8899`, WS: `ws://127.0.0.1:8900`
+- GUI: `http://127.0.0.1:42069`
+
+CLI Basics
+- Help: `solforge --help`
+- Version: `solforge --version`
+
+Commands
+- `start` / `rpc start`: Start RPC (and WS, GUI)
+- `config init|get|set`: Manage `sf.config.json`
+- `airdrop --to <pubkey> --sol <amount>`: Faucet airdrop
+- `mint`: Interactive SPL minting helper
+- `token clone|create|adopt-authority`: SPL token tools
+- `program clone|load|accounts clone`: Program + account helpers
+
+Solana CLI
+- Point to SolForge: `solana config set -u http://127.0.0.1:8899`
+- Airdrop freely: `solana airdrop 1000`
+- Deploy as usual: `solana program deploy ./program.so`
+
+Anchor
+- `anchor.toml` provider.cluster = `"http://127.0.0.1:8899"`
+- `anchor test --skip-local-validator`
+
+@solana/kit
+```
+const rpc = createSolanaRpc("http://127.0.0.1:8899");
+await rpc.getBalance(pubkey).send();
+await rpc.requestAirdrop(pubkey, lamports(1_000_000_000n)).send();
+```
+
+Configuration
+- File: `sf.config.json` (generate with `solforge config init`)
+- Server: ports, DB mode (ephemeral/persistent), DB path
+- SVM: initial lamports, faucet SOL
+- Clone: mainnet endpoint, programs/tokens/accounts to import
+- GUI: enable and port
+
+Environment Variables
+- `RPC_PORT`: HTTP port (default 8899); WS is port+1
+- `DEBUG_RPC_LOG=1`: Log all RPC calls
+- `SOLFORGE_DB_MODE=ephemeral|persistent`
+- `SOLFORGE_DB_PATH=.solforge/db.db`
+- `SOLFORGE_GUI_PORT`: GUI port (default 42069)
+
+GUI
+- Runs with the RPC by default at `http://127.0.0.1:42069`
+- Shows status (slot, block height, txs, blockhash, faucet)
+- Quick forms: airdrop SOL, mint SPL tokens
+
+From Source
+- Requires Bun
+- `bun install`
+- `bun src/cli/main.ts start`
+- `bun run build:bin` builds standalone binaries
+
+Repo Map
+- CLI entry (Node shim): `cli.cjs`:1
+- CLI router: `src/cli/main.ts`:1
+- RPC bootstrap: `src/rpc/start.ts`:1
+- Config schema: `src/config/index.ts`:1
+- JSON‑RPC methods (server): `server/methods/index.ts`:1
+
+Uninstall
+- Remove the `solforge` binary from your PATH (eg. `~/.local/bin` or `/usr/local/bin`).
+
+Troubleshooting
+- Port in use: set `RPC_PORT` or change `server.rpcPort` in `sf.config.json`
+- GUI not loading: set `SOLFORGE_GUI_PORT` or disable via config
+- Slow startup: delete `.solforge/db.db` (if using persistent mode)
+
+License
+- MIT — see `LICENSE` for details.

package/cli.cjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// SolForge CLI bootstrapper
+// - Prefers a prebuilt vendor binary (downloaded via postinstall or on first run)
+// - Falls back to Bun-based TS entry if available
+
+const fs = require("node:fs");
+const path = require("node:path");
+const https = require("node:https");
+const { spawn } = require("node:child_process");
+
+function pkg() {
+  // Resolve package.json next to this file regardless of install location
+  const p = path.join(__dirname, "package.json");
+  try { return require(p); } catch { return { version: "" }; }
+}
+
+function assetName() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === "darwin" && a === "arm64") return "solforge-darwin-arm64";
+  if (p === "darwin" && a === "x64") return "solforge-darwin-x64";
+  if (p === "linux" && a === "x64") return "solforge-linux-x64";
+  if (p === "linux" && a === "arm64") return "solforge-linux-arm64";
+  if (p === "win32" && a === "x64") return "solforge-windows-x64.exe";
+  return null;
+}
+
+function vendorPath() {
+  const name = assetName();
+  if (!name) return null;
+  return path.join(__dirname, "vendor", name);
+}
+
+function download(url, outPath) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, (res) => {
+      if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location) {
+        return resolve(download(res.headers.location, outPath));
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode}`));
+      }
+      const file = fs.createWriteStream(outPath, { mode: process.platform === "win32" ? undefined : 0o755 });
+      res.pipe(file);
+      file.on("finish", () => file.close(() => resolve()));
+      file.on("error", reject);
+    });
+    req.on("error", reject);
+  });
+}
+
+async function ensureBinary() {
+  const vp = vendorPath();
+  if (!vp) return null;
+  if (fs.existsSync(vp)) return vp;
+
+  // Respect opt-out
+  if (String(process.env.SOLFORGE_SKIP_DOWNLOAD || "").toLowerCase() === "true") {
+    return null;
+  }
+
+  const { version, repository } = pkg();
+  const repo = process.env.SOLFORGE_REPO || (repository && (typeof repository === "string" ? repository.replace(/^github:/, "") : (repository.url && (repository.url.match(/github\.com[:/](.+?)\.git$/) || [])[1]))) || "nitishxyz/solforge";
+  if (!version) return null;
+  const asset = path.basename(vp);
+  const url = `https://github.com/${repo}/releases/download/v${version}/${asset}`;
+
+  try {
+    fs.mkdirSync(path.dirname(vp), { recursive: true });
+    await download(url, vp);
+    if (process.platform !== "win32") {
+      try { fs.chmodSync(vp, 0o755); } catch {}
+    }
+    return fs.existsSync(vp) ? vp : null;
+  } catch {
+    return null;
+  }
+}
+
+function run(cmd, args) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: "inherit" });
+    child.on("exit", (code) => resolve(typeof code === "number" ? code : 0));
+  });
+}
+
+(async () => {
+  // Fast path for --version/--help without booting the app
+  const args = process.argv.slice(2);
+  if (args.includes("-v") || args.includes("--version") || args[0] === "version") {
+    console.log(pkg().version || "");
+    process.exit(0);
+  }
+  if (args.includes("-h") || args.includes("--help") || args[0] === "help") {
+    console.log(`
+solforge <command>
+
+Commands:
+  (no command)        Run setup then start RPC & WS servers
+  rpc start           Start RPC & WS servers
+  start               Alias for 'rpc start'
+  config init         Create sf.config.json in CWD
+  config get <key>    Read a config value (dot path)
+  config set <k> <v>  Set a config value
+  airdrop --to <pubkey> --sol <amount>  Airdrop SOL via RPC faucet
+  mint                 Interactive: pick mint, receiver, amount
+  token clone <mint>  Clone SPL token mint + accounts
+  program clone <programId>              Clone program code (and optionally accounts)
+  program accounts clone <programId>     Clone accounts owned by program
+
+Options:
+  -h, --help          Show help
+  -v, --version       Show version
+`);
+    process.exit(0);
+  }
+
+  const vp = await ensureBinary();
+  if (vp) {
+    const code = await run(vp, process.argv.slice(2));
+    process.exit(code);
+  }
+  // Fallback: try to run TS entry via Bun
+  const bun = process.env.SOLFORGE_BUN || "bun";
+  const entry = path.join(__dirname, "src", "cli", "main.ts");
+  const code = await run(bun, [entry, ...process.argv.slice(2)]);
+  if (code !== 0) {
+    console.error("solforge: failed to run binary and Bun fallback. Install Bun or ensure a release asset exists.");
+  }
+  process.exit(code);
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solforge",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "module": "index.ts",
   "type": "module",
   "private": false,
@@ -13,11 +13,11 @@
     "url": "https://github.com/nitishxyz/solforge/issues"
   },
   "bin": {
-    "solforge": "bin/solforge"
+    "solforge": "cli.cjs"
   },
   "files": [
-    "bin",
-    "dist",
+    "cli.cjs",
+    "scripts",
     "src",
     "server",
     "docs",
@@ -25,23 +25,24 @@
     "LICENSE"
   ],
   "scripts": {
-    "lint": "biome check",
-    "cli": "bun src/cli/main.ts",
-    "postinstall": "node scripts/postinstall.cjs || true",
-    "build:gui": "bun build src/gui/src/main.tsx --outdir src/gui/public/build --target=browser --minify",
-    "build:css": "bunx tailwindcss -i src/gui/src/index.css -o src/gui/public/app.css --minify",
     "build": "bun run build:bin",
     "build:bin": "bun run build:css && bun run build:gui && bun build --compile src/cli/main.ts --outfile dist/solforge",
+    "build:bin:all": "bun run build:bin:darwin-arm64 && bun run build:bin:darwin-x64 && bun run build:bin:linux-x64 && bun run build:bin:linux-arm64 && bun run build:bin:windows-x64",
     "build:bin:darwin-arm64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-darwin-arm64 src/cli/main.ts --outfile dist/solforge-darwin-arm64",
     "build:bin:darwin-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-darwin-x64 src/cli/main.ts --outfile dist/solforge-darwin-x64",
-    "build:bin:linux-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-linux-x64 src/cli/main.ts --outfile dist/solforge-linux-x64",
     "build:bin:linux-arm64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-linux-arm64 src/cli/main.ts --outfile dist/solforge-linux-arm64",
+    "build:bin:linux-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-linux-x64 src/cli/main.ts --outfile dist/solforge-linux-x64",
     "build:bin:windows-x64": "bun run build:css && bun run build:gui && bun build --compile --target=bun-windows-x64 src/cli/main.ts --outfile dist/solforge-windows-x64.exe",
-    "build:bin:all": "bun run build:bin:darwin-arm64 && bun run build:bin:darwin-x64 && bun run build:bin:linux-x64 && bun run build:bin:linux-arm64 && bun run build:bin:windows-x64",
-    "prepack": "chmod +x bin/solforge || true"
+    "build:css": "bunx tailwindcss -i src/gui/src/index.css -o src/gui/public/app.css --minify",
+    "build:gui": "bun build src/gui/src/main.tsx --outdir src/gui/public/build --target=browser --minify",
+    "cli": "bun src/cli/main.ts",
+    "lint": "biome check",
+    "postinstall": "node scripts/postinstall.cjs || true",
+    "prepack": "chmod +x cli.cjs || true"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.4",
+    "@types/aws-lambda": "8.10.152",
     "@types/bun": "latest",
     "@types/react": "^19.1.13",
     "@types/react-dom": "^19.1.9",
@@ -64,6 +65,7 @@
     "drizzle-orm": "^0.44.5",
     "litesvm": "^0.3.3",
     "react": "^19.1.1",
-    "react-dom": "^19.1.1"
+    "react-dom": "^19.1.1",
+    "sst": "3.17.13"
   }
 }

package/scripts/install.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env sh
+set -e
+
+# SolForge installer (downloads GitHub release binary)
+# Usage: curl -fsSL https://sh.solforge.sh | sh
+# Optional: SOLFORGE_VERSION=v0.2.3 curl -fsSL https://sh.solforge.sh | sh
+
+REPO="nitishxyz/solforge"
+BIN_NAME="solforge"
+VERSION="${SOLFORGE_VERSION:-latest}"
+
+info() { printf "\033[1;34m[i]\033[0m %s\n" "$*"; }
+warn() { printf "\033[1;33m[!]\033[0m %s\n" "$*"; }
+err()  { printf "\033[1;31m[x]\033[0m %s\n" "$*" 1>&2; }
+
+# Detect downloader
+http_get() {
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL "$1"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -qO- "$1"
+  else
+    err "Need 'curl' or 'wget' to download binaries"
+    exit 1
+  fi
+}
+
+http_down() {
+  dest="$2"
+  if command -v curl >/dev/null 2>&1; then
+    curl -fL --progress-bar -o "$dest" "$1"
+  else
+    wget -qO "$dest" "$1"
+  fi
+}
+
+# OS/arch detection
+uname_s=$(uname -s 2>/dev/null || echo unknown)
+uname_m=$(uname -m 2>/dev/null || echo unknown)
+
+case "$uname_s" in
+  Linux)  os="linux" ;;
+  Darwin) os="darwin" ;;
+  *) err "Unsupported OS: $uname_s"; exit 1 ;;
+esac
+
+case "$uname_m" in
+  x86_64|amd64) arch="x64" ;;
+  arm64|aarch64) arch="arm64" ;;
+  *) err "Unsupported architecture: $uname_m"; exit 1 ;;
+esac
+
+asset="${BIN_NAME}-${os}-${arch}"
+ext=""
+filename="$asset$ext"
+
+# Build URL
+if [ "$VERSION" = "latest" ]; then
+  base="https://github.com/$REPO/releases/latest/download"
+else
+  base="https://github.com/$REPO/releases/download/$VERSION"
+fi
+
+url="$base/$filename"
+
+info "Installing $BIN_NAME ($os/$arch) from: $url"
+
+# Download
+tmpdir=${TMPDIR:-/tmp}
+tmpfile="$tmpdir/$filename"
+http_down "$url" "$tmpfile"
+
+# Make executable
+chmod +x "$tmpfile"
+
+# Choose install dir
+install_dir="/usr/local/bin"
+if [ ! -w "$install_dir" ]; then
+  if command -v sudo >/dev/null 2>&1; then
+    sudo_cmd="sudo"
+  else
+    sudo_cmd=""
+  fi
+fi
+
+if [ -n "$sudo_cmd" ] && [ -d "$install_dir" ] && [ ! -w "$install_dir" ]; then
+  info "Moving binary to $install_dir (requires sudo)"
+  $sudo_cmd mv "$tmpfile" "$install_dir/$BIN_NAME"
+else
+  # Fallback to user bin
+  user_bin="$HOME/.local/bin"
+  mkdir -p "$user_bin"
+  info "Moving binary to $user_bin"
+  mv "$tmpfile" "$user_bin/$BIN_NAME"
+  install_dir="$user_bin"
+fi
+
+# Verify
+if "$install_dir/$BIN_NAME" --version >/dev/null 2>&1; then
+  ver=$("$install_dir/$BIN_NAME" --version 2>/dev/null || true)
+  info "$BIN_NAME installed: $ver"
+else
+  warn "Installed, but failed to run --version"
+fi
+
+# PATH hint
+case ":$PATH:" in
+  *":$install_dir:"*) :;;
+  *) warn "Add $install_dir to your PATH to use '$BIN_NAME'" ;;
+esac
+
+info "Done. Run: $BIN_NAME --help"

package/scripts/postinstall.cjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/*
+  SolForge postinstall: fetch the platform-specific prebuilt binary from GitHub Releases.
+  - Skips if SOLFORGE_SKIP_DOWNLOAD=true
+  - Falls back silently on errors (CLI will still work via Bun if installed)
+*/
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+
+function log(msg) {
+  console.log(`[solforge] ${msg}`);
+}
+function warn(msg) {
+  console.warn(`[solforge] ${msg}`);
+}
+
+if (String(process.env.SOLFORGE_SKIP_DOWNLOAD || "").toLowerCase() === "true") {
+  log("Skipping binary download due to SOLFORGE_SKIP_DOWNLOAD=true");
+  process.exit(0);
+}
+
+function assetName() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === "darwin" && a === "arm64") return "solforge-darwin-arm64";
+  if (p === "darwin" && a === "x64") return "solforge-darwin-x64";
+  if (p === "linux" && a === "x64") return "solforge-linux-x64";
+  if (p === "linux" && a === "arm64") return "solforge-linux-arm64";
+  if (p === "win32" && a === "x64") return "solforge-windows-x64.exe";
+  return null;
+}
+
+function getRepo() {
+  try {
+    const pkg = require(path.join(__dirname, "..", "package.json"));
+    if (pkg.repository) {
+      if (typeof pkg.repository === "string") return pkg.repository.replace(/^github:/, "");
+      if (pkg.repository.url) {
+        const m = pkg.repository.url.match(/github\.com[:/](.+?)\.git$/);
+        if (m) return m[1];
+      }
+    }
+  } catch {}
+  return process.env.SOLFORGE_REPO || "nitishxyz/solforge";
+}
+
+function getVersion() {
+  try {
+    const pkg = require(path.join(__dirname, "..", "package.json"));
+    return pkg.version;
+  } catch {
+    return process.env.npm_package_version || "";
+  }
+}
+
+const name = assetName();
+if (!name) {
+  warn(`No prebuilt binary for ${process.platform}/${process.arch}; skipping`);
+  process.exit(0);
+}
+
+const version = getVersion();
+if (!version) {
+  warn("Unable to determine package version; skipping binary download");
+  process.exit(0);
+}
+
+const repo = getRepo();
+const url = `https://github.com/${repo}/releases/download/v${version}/${name}`;
+
+const vendorDir = path.join(__dirname, "..", "vendor");
+const outPath = path.join(vendorDir, name);
+
+if (fs.existsSync(outPath)) {
+  log(`Binary already present at vendor/${name}`);
+  process.exit(0);
+}
+
+fs.mkdirSync(vendorDir, { recursive: true });
+
+function download(to, from, cb, redirects = 0) {
+  const req = https.get(from, (res) => {
+    if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location && redirects < 5) {
+      return download(to, res.headers.location, cb, redirects + 1);
+    }
+    if (res.statusCode !== 200) {
+      return cb(new Error(`HTTP ${res.statusCode} for ${from}`));
+    }
+    const file = fs.createWriteStream(to, { mode: 0o755 });
+    res.pipe(file);
+    file.on("finish", () => file.close(cb));
+  });
+  req.on("error", (err) => cb(err));
+}
+
+log(`Fetching ${name} for v${version}...`);
+download(outPath, url, (err) => {
+  if (err) {
+    warn(`Could not download prebuilt binary: ${err.message}`);
+    warn("CLI will fall back to running via Bun if available.");
+    try { fs.unlinkSync(outPath); } catch {}
+    process.exit(0);
+  }
+  if (process.platform !== "win32") {
+    try { fs.chmodSync(outPath, 0o755); } catch {}
+  }
+  log(`Installed vendor/${name}`);
+});
+

package/src/cli/main.ts

@@ -1,11 +1,17 @@
 // Minimal, fast CLI router with @clack/prompts for UX
 import * as p from "@clack/prompts";
+// Load version for --version in both bun script and compiled binary
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports
+import pkg from "../../package.json" assert { type: "json" };
 
 // Robust arg parsing for both bun script and compiled binary
 const known = new Set([
   "help",
   "-h",
   "--help",
+  "version",
+  "-v",
+  "--version",
   "rpc",
   "start",
   "config",
@@ -21,16 +27,21 @@ const argv = firstIdx >= 0 ? raw.slice(firstIdx) : [];
 async function main() {
 	const [cmd, sub, ...rest] = argv;
 
-	if (!cmd) {
-		const { runSolforge } = await import("./run-solforge");
-		await runSolforge();
-		return;
-	}
+  if (!cmd) {
+    const { runSolforge } = await import("./run-solforge");
+    await runSolforge();
+    return;
+  }
 
-	if (cmd === "help" || cmd === "-h" || cmd === "--help") {
-		printHelp();
-		return;
-	}
+  if (cmd === "help" || cmd === "-h" || cmd === "--help") {
+    printHelp();
+    return;
+  }
+
+  if (cmd === "version" || cmd === "-v" || cmd === "--version") {
+    printVersion();
+    return;
+  }
 
 	// Alias: solforge start -> solforge rpc start
 	if (cmd === "start") {
@@ -104,7 +115,7 @@ async function main() {
 }
 
 function printHelp() {
-	console.log(`
+  console.log(`
 solforge <command>
 
 Commands:
@@ -119,12 +130,22 @@ Commands:
   token clone <mint>  Clone SPL token mint + accounts
   program clone <programId>              Clone program code (and optionally accounts)
   program accounts clone <programId>     Clone accounts owned by program
+
+Options:
+  -h, --help          Show help
+  -v, --version       Show version
 `);
 }
 
 async function unknownCommand(parts: (string | undefined)[]) {
-	p.log.error(`Unknown command: ${parts.filter(Boolean).join(" ")}`);
-	printHelp();
+  p.log.error(`Unknown command: ${parts.filter(Boolean).join(" ")}`);
+  printHelp();
+}
+
+function printVersion() {
+	// Prefer package.json version if available
+	const v = (pkg as any)?.version ?? "";
+	console.log(String(v));
 }
 
 main();