solforge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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. 

package/README.md

@@ -0,0 +1,441 @@
+# SolForge
+
+**SolForge** is a powerful Solana localnet orchestration tool that simplifies the process of setting up and managing local Solana development environments. It allows you to clone mainnet programs and tokens to your local validator, making it easy to develop and test Solana applications with real-world data.
+
+## ✨ Features
+
+- 🚀 **One-command setup** - Initialize and start a localnet with a single command
+- 🔄 **Mainnet cloning** - Clone tokens and programs from Solana mainnet to your localnet
+- 🎯 **Multi-validator support** - Run multiple validators simultaneously with different configurations
+- 💰 **Token management** - Mint tokens with custom amounts and distribute to specific wallets
+- 🔧 **Program deployment** - Deploy and manage Solana programs on your localnet
+- 📊 **Process management** - Monitor, start, stop, and manage validator processes
+- 🌐 **Port management** - Automatic port allocation and conflict resolution
+- 📝 **Configuration-driven** - JSON-based configuration for reproducible environments
+- 🎨 **Beautiful CLI** - Colorful, intuitive command-line interface
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) runtime
+- [Solana CLI tools](https://docs.solana.com/cli/install-solana-cli-tools) installed and configured
+- Node.js 18+ (for compatibility)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd solforge
+
+# Install dependencies
+bun install
+
+# Build the project
+bun run build
+
+# Install globally (optional)
+bun run build:binary
+bun run install:binary
+```
+
+### Basic Usage
+
+1. **Initialize a new project**:
+   ```bash
+   solforge init
+   ```
+
+2. **Start your localnet**:
+   ```bash
+   solforge start
+   ```
+
+3. **Check status**:
+   ```bash
+   solforge status
+   solforge list
+   ```
+
+4. **Stop when done**:
+   ```bash
+   solforge stop --all
+   ```
+
+## 📖 Documentation
+
+### 📚 Additional Documentation
+- [Configuration Guide](docs/CONFIGURATION.md) - Detailed configuration options and examples
+- [Troubleshooting Guide](#-troubleshooting) - Common issues and solutions
+
+### Commands
+
+#### `solforge init`
+Initialize a new `sf.config.json` configuration file in the current directory.
+
+```bash
+solforge init
+```
+
+This command will prompt you for:
+- Project name
+- Description
+- RPC port (default: 8899)
+- Whether to include USDC token
+
+#### `solforge start [options]`
+Start a localnet validator with the current configuration.
+
+```bash
+solforge start                # Start with default settings
+solforge start --debug        # Start with debug logging
+```
+
+**Options:**
+- `--debug` - Enable debug logging to see detailed command output
+
+#### `solforge list`
+List all running validators with detailed information.
+
+```bash
+solforge list
+```
+
+Shows:
+- Validator ID and name
+- Process ID (PID)
+- RPC and Faucet ports
+- Uptime
+- Status
+- Connection URLs
+
+#### `solforge stop [validator-id] [options]`
+Stop running validators.
+
+```bash
+solforge stop                 # Interactive selection
+solforge stop <validator-id>  # Stop specific validator
+solforge stop --all           # Stop all validators
+solforge stop --kill          # Force kill (SIGKILL)
+```
+
+**Options:**
+- `--all` - Stop all running validators
+- `--kill` - Force kill the validator (SIGKILL instead of SIGTERM)
+
+#### `solforge kill [validator-id] [options]`
+Force kill running validators with interactive selection.
+
+```bash
+solforge kill                 # Interactive selection with validator list
+solforge kill <validator-id>  # Kill specific validator
+solforge kill --all           # Kill all validators
+```
+
+**Interactive Mode:**
+When run without arguments, `solforge kill` will:
+- Display a table of all running validators
+- Allow you to select which validator to kill using arrow keys
+- Provide options to kill individual validators, all validators, or cancel
+- No need to copy/paste validator IDs from `solforge list`
+
+#### `solforge status`
+Show overall localnet status and configuration summary.
+
+```bash
+solforge status
+```
+
+#### `solforge add-program [options]`
+Add a program to your configuration.
+
+```bash
+solforge add-program                                    # Interactive mode
+solforge add-program --program-id <address>             # Non-interactive
+solforge add-program --program-id <address> --name <name>
+```
+
+**Options:**
+- `--program-id <address>` - Mainnet program ID to clone and deploy
+- `--name <name>` - Friendly name for the program
+- `--no-interactive` - Run in non-interactive mode
+
+#### `solforge transfer [options]`
+Interactively transfer tokens from mint authority to any address.
+
+```bash
+solforge transfer                                    # Use default RPC
+solforge transfer --rpc-url http://localhost:8899   # Custom RPC
+```
+
+**Options:**
+- `--rpc-url <url>` - RPC URL to use (default: "http://127.0.0.1:8899")
+
+#### `solforge reset`
+Reset localnet ledger (coming soon).
+
+```bash
+solforge reset
+```
+
+### Configuration File (`sf.config.json`)
+
+The configuration file defines your localnet setup. For detailed configuration options, see the [Configuration Guide](docs/CONFIGURATION.md).
+
+Here's the complete schema:
+
+```json
+{
+  "name": "my-localnet",
+  "description": "Local Solana development environment",
+  "tokens": [
+    {
+      "symbol": "USDC",
+      "mainnetMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      "mintAuthority": "./keypairs/mint-authority.json",
+      "mintAmount": 1000000,
+      "cloneMetadata": true,
+      "recipients": [
+        {
+          "wallet": "YourWalletPublicKeyHere",
+          "amount": 1000000000
+        }
+      ]
+    }
+  ],
+  "programs": [
+    {
+      "name": "Token Metadata",
+      "mainnetProgramId": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
+      "cluster": "mainnet-beta",
+      "upgradeable": false,
+      "dependencies": []
+    }
+  ],
+  "localnet": {
+    "airdropAmount": 100,
+    "faucetAccounts": ["YourWalletPublicKeyHere"],
+    "port": 8899,
+    "faucetPort": 9900,
+    "reset": true,
+    "logLevel": "info",
+    "bindAddress": "127.0.0.1",
+    "limitLedgerSize": 100000,
+    "rpc": "https://api.mainnet-beta.solana.com"
+  }
+}
+```
+
+#### Configuration Schema
+
+For detailed configuration options and examples, see the [Configuration Guide](docs/CONFIGURATION.md).
+
+**Quick Reference:**
+- `name` - Project name
+- `description` - Project description  
+- `tokens[]` - Tokens to clone from mainnet
+- `programs[]` - Programs to clone from mainnet
+- `localnet` - Validator settings (ports, logging, etc.)
+
+## 🎯 Use Cases
+
+### DeFi Development
+Clone popular DeFi tokens and programs to test your application:
+
+```json
+{
+  "name": "defi-testing",
+  "tokens": [
+    {
+      "symbol": "USDC",
+      "mainnetMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+      "mintAmount": 10000000
+    },
+    {
+      "symbol": "USDT", 
+      "mainnetMint": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
+      "mintAmount": 10000000
+    }
+  ],
+  "programs": [
+    {
+      "name": "Jupiter",
+      "mainnetProgramId": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"
+    }
+  ]
+}
+```
+
+### NFT Development
+Set up an environment for NFT projects:
+
+```json
+{
+  "name": "nft-development",
+  "programs": [
+    {
+      "name": "Token Metadata",
+      "mainnetProgramId": "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s"
+    },
+    {
+      "name": "Candy Machine",
+      "mainnetProgramId": "cndy3Z4yapfJBmL3ShUp5exZKqR3z33thTzeNMm2gRZ"
+    }
+  ]
+}
+```
+
+### Multi-Environment Testing
+Run multiple validators for different test scenarios:
+
+```bash
+# Terminal 1 - DeFi environment
+cd defi-project
+solforge start
+
+# Terminal 2 - NFT environment  
+cd nft-project
+solforge start
+
+# Check both
+solforge list
+```
+
+## 🔧 Development
+
+### Project Structure
+
+```
+src/
+├── commands/          # CLI command implementations
+│   ├── init.ts        # Initialize configuration
+│   ├── start.ts       # Start validator
+│   ├── stop.ts        # Stop validator
+│   ├── list.ts        # List validators
+│   ├── status.ts      # Show status
+│   ├── add-program.ts # Add programs
+│   └── transfer.ts    # Transfer tokens
+├── config/            # Configuration management
+│   └── manager.ts     # Config file operations
+├── services/          # Core services
+│   ├── validator.ts   # Validator management
+│   ├── token-cloner.ts    # Token cloning logic
+│   ├── program-cloner.ts  # Program cloning logic
+│   ├── port-manager.ts    # Port allocation
+│   └── process-registry.ts # Process tracking
+├── types/             # TypeScript definitions
+│   └── config.ts      # Configuration schemas
+├── utils/             # Utility functions
+│   └── shell.ts       # Shell command helpers
+└── index.ts           # CLI entry point
+```
+
+### Build Commands
+
+```bash
+# Development
+bun run dev            # Watch mode development
+
+# Building
+bun run build          # Build for Node.js
+bun run build:binary   # Build standalone binary
+
+# Testing & Quality
+bun test               # Run tests
+bun run lint           # Lint code
+bun run format         # Format code
+
+# Installation
+bun run install:binary # Install binary to ~/.local/bin
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes
+4. Run tests and linting: `bun test && bun run lint`
+5. Commit your changes: `git commit -m 'Add amazing feature'`
+6. Push to the branch: `git push origin feature/amazing-feature`
+7. Open a Pull Request
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Port already in use**
+```bash
+# Check what's using the port
+lsof -i :8899
+
+# Use a different port in sf.config.json
+{
+  "localnet": {
+    "port": 8900,
+    "faucetPort": 9901
+  }
+}
+```
+
+**Validator won't start**
+```bash
+# Check Solana CLI is installed
+solana --version
+
+# Check configuration
+solforge status
+
+# Start with debug logging
+solforge start --debug
+```
+
+**Token cloning fails**
+- Ensure RPC URL in config is accessible
+- Check mainnet mint address is correct
+- Verify network connectivity
+
+**Program deployment fails**
+- Ensure program ID exists on specified cluster
+- Check if program has dependencies that need to be deployed first
+- Verify sufficient SOL for deployment
+
+### Debug Mode
+
+Use `--debug` flag to see detailed command output:
+
+```bash
+solforge start --debug
+```
+
+This shows:
+- Exact solana-test-validator commands
+- Program deployment steps
+- Token cloning operations
+- Error details
+
+### Logs and Data
+
+SolForge stores data in:
+- `~/.solforge/` - Process registry and metadata
+- `.solforge/` - Local working directory for current project
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🤝 Support
+
+- 🐛 **Issues**: [GitHub Issues](https://github.com/your-repo/solforge/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/your-repo/solforge/discussions)
+- 📧 **Email**: your-email@example.com
+
+## 🙏 Acknowledgments
+
+- [Solana Labs](https://solana.com) for the amazing blockchain platform
+- [Bun](https://bun.sh) for the fast JavaScript runtime
+- The Solana developer community for inspiration and feedback
+
+---
+
+**Happy building on Solana! 🚀**

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "solforge",
+  "version": "0.1.0",
+  "description": "Solana localnet orchestration tool for cloning mainnet programs and tokens",
+  "module": "index.ts",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "solforge": "./bin/solforge"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "tsconfig.json",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "build": "bun build src/index.ts --outdir ./dist --target bun",
+    "build:binary": "bun build src/index.ts --compile --outfile ./dist/solforge",
+    "build:npm": "mkdir -p bin && bun build src/index.ts --compile --outfile ./bin/solforge",
+    "install:binary": "mkdir -p ~/.local/bin && cp ./dist/solforge ~/.local/bin/solforge && chmod +x ~/.local/bin/solforge",
+    "build:install": "bun run build:binary && bun run install:binary",
+    "postinstall": "node scripts/postinstall.cjs",
+    "prepublishOnly": "rm -rf bin/",
+    "start": "bun run dist/index.js",
+    "test": "bun test",
+    "lint": "bunx @biomejs/biome check src/",
+    "format": "bunx @biomejs/biome format src/ --write"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.3",
+    "@solana/spl-token": "^0.4.1",
+    "@solana/web3.js": "^1.87.6",
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "inquirer": "^9.2.12",
+    "ora": "^8.0.1",
+    "ws": "^8.16.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.10.6",
+    "@types/express": "^4.17.21",
+    "@types/cors": "^2.8.17",
+    "@types/ws": "^8.5.10",
+    "@types/inquirer": "^9.0.7",
+    "@biomejs/biome": "^1.4.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "keywords": [
+    "solana",
+    "localnet",
+    "blockchain",
+    "development",
+    "tooling"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nitishxyz/solforge.git"
+  },
+  "author": "nitishxyz",
+  "license": "MIT"
+}

package/scripts/postinstall.cjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const { execSync } = require("child_process");
+
+const PACKAGE_NAME = "solforge";
+const VERSION = require("../package.json").version;
+
+// Platform mapping
+const PLATFORM_MAP = {
+  "darwin-x64": "darwin-x64",
+  "darwin-arm64": "darwin-arm64",
+  "linux-x64": "linux-x64",
+  "linux-arm64": "linux-arm64",
+  "win32-x64": "win32-x64.exe",
+};
+
+function getPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+  const key = `${platform}-${arch}`;
+
+  if (!PLATFORM_MAP[key]) {
+    console.error(`Unsupported platform: ${platform}-${arch}`);
+    console.error("Supported platforms:", Object.keys(PLATFORM_MAP).join(", "));
+    process.exit(1);
+  }
+
+  return PLATFORM_MAP[key];
+}
+
+function downloadBinary(url, destination) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destination);
+
+    https
+      .get(url, (response) => {
+        if (response.statusCode === 200) {
+          response.pipe(file);
+          file.on("finish", () => {
+            file.close();
+            fs.chmodSync(destination, 0o755); // Make executable
+            resolve();
+          });
+        } else if (response.statusCode === 302 || response.statusCode === 301) {
+          // Handle redirects
+          downloadBinary(response.headers.location, destination)
+            .then(resolve)
+            .catch(reject);
+        } else {
+          reject(new Error(`Failed to download: ${response.statusCode}`));
+        }
+      })
+      .on("error", reject);
+  });
+}
+
+async function install() {
+  try {
+    const platform = getPlatform();
+    const binDir = path.join(__dirname, "..", "bin");
+    const binaryName =
+      process.platform === "win32" ? "solforge.exe" : "solforge";
+    const binaryPath = path.join(binDir, binaryName);
+
+    // Create bin directory
+    if (!fs.existsSync(binDir)) {
+      fs.mkdirSync(binDir, { recursive: true });
+    }
+
+    // Try to build locally first (if Bun is available)
+    try {
+      console.log("Attempting to build locally with Bun...");
+      execSync(`bun build src/index.ts --compile --outfile ${binaryPath}`, {
+        cwd: path.join(__dirname, ".."),
+        stdio: "pipe",
+      });
+      console.log("✅ Built successfully with local Bun");
+      return;
+    } catch (e) {
+      console.log("Local Bun build failed, downloading pre-built binary...");
+    }
+
+    // Download pre-built binary from GitHub releases
+    const downloadUrl = `https://github.com/nitishxyz/solforge/releases/download/v${VERSION}/solforge-${platform}`;
+
+    console.log(`Downloading ${PACKAGE_NAME} binary for ${platform}...`);
+    console.log(`URL: ${downloadUrl}`);
+
+    await downloadBinary(downloadUrl, binaryPath);
+    console.log("✅ Binary downloaded and installed successfully");
+  } catch (error) {
+    console.error("❌ Installation failed:", error.message);
+    console.error("\nFallback options:");
+    console.error("1. Install Bun and run: bun install -g solforge");
+    console.error("2. Clone the repo and build manually");
+    process.exit(1);
+  }
+}
+
+install();