solforge 0.1.0 → 0.1.2

package/README.md

@@ -13,6 +13,7 @@
 - 🌐 **Port management** - Automatic port allocation and conflict resolution
 - 📝 **Configuration-driven** - JSON-based configuration for reproducible environments
 - 🎨 **Beautiful CLI** - Colorful, intuitive command-line interface
+- 🌐 **REST API** - Background API server for programmatic access to validator operations
 
 ## 🚀 Quick Start
 
@@ -26,7 +27,7 @@
 
 ```bash
 # Clone the repository
-git clone <repository-url>
+git clone https://github.com/nitishxyz/solforge.git
 cd solforge
 
 # Install dependencies
@@ -43,16 +44,19 @@ 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
@@ -63,15 +67,40 @@ bun run install:binary
    solforge stop --all
    ```
 
+### API Server
+
+SolForge automatically starts a REST API server alongside your validator, providing programmatic access to validator operations:
+
+```bash
+# API server starts automatically with the validator
+solforge start
+
+# API available at http://127.0.0.1:3000/api
+curl http://127.0.0.1:3000/api/health
+
+# Mint tokens via API
+curl -X POST http://127.0.0.1:3000/api/tokens/USDC/mint \
+  -H "Content-Type: application/json" \
+  -d '{"walletAddress": "YOUR_WALLET_ADDRESS", "amount": 1000}'
+
+# Get wallet balances
+curl http://127.0.0.1:3000/api/wallet/YOUR_WALLET_ADDRESS/balances
+```
+
+For complete API documentation, see [API Documentation](docs/API.md).
+
 ## 📖 Documentation
 
 ### 📚 Additional Documentation
+
+- [API Documentation](docs/API.md) - REST API endpoints and usage examples
 - [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
@@ -79,12 +108,14 @@ 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
@@ -93,9 +124,11 @@ 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
@@ -103,6 +136,7 @@ solforge list
 ```
 
 Shows:
+
 - Validator ID and name
 - Process ID (PID)
 - RPC and Faucet ports
@@ -111,6 +145,7 @@ Shows:
 - Connection URLs
 
 #### `solforge stop [validator-id] [options]`
+
 Stop running validators.
 
 ```bash
@@ -121,10 +156,12 @@ 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
@@ -135,12 +172,14 @@ 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
@@ -148,6 +187,7 @@ solforge status
 ```
 
 #### `solforge add-program [options]`
+
 Add a program to your configuration.
 
 ```bash
@@ -157,22 +197,39 @@ 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.
+#### `solforge mint [options]`
+
+Interactively mint tokens to any wallet address.
 
 ```bash
-solforge transfer                                    # Use default RPC
-solforge transfer --rpc-url http://localhost:8899   # Custom RPC
+solforge mint                                        # Interactive mode
+solforge mint --symbol USDC --wallet <address> --amount 1000  # CLI mode
+solforge mint --rpc-url http://localhost:8899       # Custom RPC
 ```
 
 **Options:**
+
 - `--rpc-url <url>` - RPC URL to use (default: "http://127.0.0.1:8899")
+- `--symbol <symbol>` - Token symbol to mint
+- `--wallet <address>` - Wallet address to mint to
+- `--amount <amount>` - Amount to mint
+
+**Interactive Mode:**
+When run without arguments, `solforge mint` will:
+
+- Display available cloned tokens
+- Allow you to select which token to mint
+- Prompt for recipient wallet address
+- Prompt for amount to mint
+- Handle SPL token account creation automatically
 
 #### `solforge reset`
+
 Reset localnet ledger (coming soon).
 
 ```bash
@@ -232,8 +289,9 @@ Here's the complete schema:
 For detailed configuration options and examples, see the [Configuration Guide](docs/CONFIGURATION.md).
 
 **Quick Reference:**
+
 - `name` - Project name
-- `description` - Project description  
+- `description` - Project description
 - `tokens[]` - Tokens to clone from mainnet
 - `programs[]` - Programs to clone from mainnet
 - `localnet` - Validator settings (ports, logging, etc.)
@@ -241,6 +299,7 @@ For detailed configuration options and examples, see the [Configuration Guide](d
 ## 🎯 Use Cases
 
 ### DeFi Development
+
 Clone popular DeFi tokens and programs to test your application:
 
 ```json
@@ -253,7 +312,7 @@ Clone popular DeFi tokens and programs to test your application:
       "mintAmount": 10000000
     },
     {
-      "symbol": "USDT", 
+      "symbol": "USDT",
       "mainnetMint": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
       "mintAmount": 10000000
     }
@@ -268,6 +327,7 @@ Clone popular DeFi tokens and programs to test your application:
 ```
 
 ### NFT Development
+
 Set up an environment for NFT projects:
 
 ```json
@@ -287,6 +347,7 @@ Set up an environment for NFT projects:
 ```
 
 ### Multi-Environment Testing
+
 Run multiple validators for different test scenarios:
 
 ```bash
@@ -294,7 +355,7 @@ Run multiple validators for different test scenarios:
 cd defi-project
 solforge start
 
-# Terminal 2 - NFT environment  
+# Terminal 2 - NFT environment
 cd nft-project
 solforge start
 
@@ -365,6 +426,7 @@ bun run install:binary # Install binary to ~/.local/bin
 ### Common Issues
 
 **Port already in use**
+
 ```bash
 # Check what's using the port
 lsof -i :8899
@@ -379,6 +441,7 @@ lsof -i :8899
 ```
 
 **Validator won't start**
+
 ```bash
 # Check Solana CLI is installed
 solana --version
@@ -391,11 +454,13 @@ 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
@@ -409,6 +474,7 @@ solforge start --debug
 ```
 
 This shows:
+
 - Exact solana-test-validator commands
 - Program deployment steps
 - Token cloning operations
@@ -417,6 +483,7 @@ This shows:
 ### Logs and Data
 
 SolForge stores data in:
+
 - `~/.solforge/` - Process registry and metadata
 - `.solforge/` - Local working directory for current project
 
@@ -426,9 +493,7 @@ 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
+- 🐛 **Issues**: [GitHub Issues](https://github.com/nitishxyz/solforge/issues)
 
 ## 🙏 Acknowledgments
 
@@ -438,4 +503,4 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-**Happy building on Solana! 🚀**
+**Happy building on Solana! 🚀**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solforge",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Solana localnet orchestration tool for cloning mainnet programs and tokens",
   "module": "index.ts",
   "type": "module",

package/src/api-server-entry.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+import { APIServer } from "./services/api-server.js";
+import { configManager } from "./config/manager.js";
+import chalk from "chalk";
+
+async function main() {
+  try {
+    // Parse command line arguments
+    const args = process.argv.slice(2);
+    const portIndex = args.indexOf("--port");
+    const configIndex = args.indexOf("--config");
+    const rpcIndex = args.indexOf("--rpc-url");
+    const faucetIndex = args.indexOf("--faucet-url");
+    const workDirIndex = args.indexOf("--work-dir");
+
+    if (
+      portIndex === -1 ||
+      configIndex === -1 ||
+      rpcIndex === -1 ||
+      faucetIndex === -1 ||
+      workDirIndex === -1 ||
+      !args[portIndex + 1] ||
+      !args[configIndex + 1] ||
+      !args[rpcIndex + 1] ||
+      !args[faucetIndex + 1] ||
+      !args[workDirIndex + 1]
+    ) {
+      console.error(
+        "Usage: api-server-entry --port <port> --config <config-path> --rpc-url <url> --faucet-url <url> --work-dir <dir>"
+      );
+      process.exit(1);
+    }
+
+    const port = parseInt(args[portIndex + 1]!);
+    const configPath = args[configIndex + 1]!;
+    const rpcUrl = args[rpcIndex + 1]!;
+    const faucetUrl = args[faucetIndex + 1]!;
+    const workDir = args[workDirIndex + 1]!;
+
+    // Load configuration
+    await configManager.load(configPath);
+    const config = configManager.getConfig();
+
+    // Create and start API server
+    const apiServer = new APIServer({
+      port,
+      validatorRpcUrl: rpcUrl,
+      validatorFaucetUrl: faucetUrl,
+      config,
+      workDir,
+    });
+
+    const result = await apiServer.start();
+
+    if (result.success) {
+      console.log(chalk.green(`🚀 API Server started on port ${port}`));
+
+      // Keep the process alive
+      process.on("SIGTERM", async () => {
+        console.log(
+          chalk.yellow("📡 API Server received SIGTERM, shutting down...")
+        );
+        await apiServer.stop();
+        process.exit(0);
+      });
+
+      process.on("SIGINT", async () => {
+        console.log(
+          chalk.yellow("📡 API Server received SIGINT, shutting down...")
+        );
+        await apiServer.stop();
+        process.exit(0);
+      });
+
+      // Keep process alive
+      setInterval(() => {}, 1000);
+    } else {
+      console.error(
+        chalk.red(`❌ Failed to start API server: ${result.error}`)
+      );
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(
+      chalk.red(
+        `❌ API Server error: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      )
+    );
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(
+    chalk.red(
+      `❌ Fatal error: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    )
+  );
+  process.exit(1);
+});