solforge 0.1.4 → 0.1.6

package/README.md

@@ -1,5 +1,8 @@
 # SolForge
 
+[![npm version](https://badge.fury.io/js/solforge.svg)](https://badge.fury.io/js/solforge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 **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
@@ -15,15 +18,27 @@
 - 🎨 **Beautiful CLI** - Colorful, intuitive command-line interface
 - 🌐 **REST API** - Background API server for programmatic access to validator operations
 
-## 🚀 Quick Start
+## 📦 Installation
 
 ### 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)
+- Node.js 18+ or [Bun](https://bun.sh) runtime
 
-### Installation
+### Install from npm (Recommended)
+
+```bash
+# Install globally with npm
+npm install -g solforge
+
+# Or with bun
+bun install -g solforge
+
+# Or with yarn
+yarn global add solforge
+```
+
+### Install from Source
 
 ```bash
 # Clone the repository
@@ -33,14 +48,20 @@ cd solforge
 # Install dependencies
 bun install
 
-# Build the project
-bun run build
+# Build and install globally
+bun run build:npm
+npm install -g .
+```
 
-# Install globally (optional)
-bun run build:binary
-bun run install:binary
+### Verify Installation
+
+```bash
+solforge --version
+solforge --help
 ```
 
+## 🚀 Quick Start
+
 ### Basic Usage
 
 1. **Initialize a new project**:
@@ -78,8 +99,8 @@ 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 \
+# Mint tokens via API (using mint address)
+curl -X POST http://127.0.0.1:3000/api/tokens/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/mint \
   -H "Content-Type: application/json" \
   -d '{"walletAddress": "YOUR_WALLET_ADDRESS", "amount": 1000}'
 
@@ -121,11 +142,14 @@ Start a localnet validator with the current configuration.
 ```bash
 solforge start                # Start with default settings
 solforge start --debug        # Start with debug logging
+solforge start --network      # Make API server accessible over network
+solforge start --debug --network  # Debug mode + network access
 ```
 
 **Options:**
 
 - `--debug` - Enable debug logging to see detailed command output
+- `--network` - Make API server accessible over network (binds to 0.0.0.0 instead of 127.0.0.1)
 
 #### `solforge list`
 
@@ -228,6 +252,25 @@ When run without arguments, `solforge mint` will:
 - Prompt for amount to mint
 - Handle SPL token account creation automatically
 
+#### `solforge api-server [options]`
+
+Start the API server as a standalone service (without validator).
+
+```bash
+solforge api-server                                    # Start on default port 3000
+solforge api-server --port 8080                       # Custom port
+solforge api-server --host 0.0.0.0                    # Network accessible
+solforge api-server --rpc-url http://localhost:8899   # Custom RPC
+```
+
+**Options:**
+
+- `-p, --port <port>` - Port for API server (default: 3000)
+- `--host <host>` - Host to bind to (default: 127.0.0.1, use 0.0.0.0 for network access)
+- `--rpc-url <url>` - Validator RPC URL (default: http://127.0.0.1:8899)
+- `--faucet-url <url>` - Validator faucet URL (default: http://127.0.0.1:9900)
+- `--work-dir <dir>` - Work directory (default: ./.solforge)
+
 #### `solforge reset`
 
 Reset localnet ledger (coming soon).

package/package.json

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

package/src/api-server-entry.ts

@@ -9,6 +9,7 @@ async function main() {
     // Parse command line arguments
     const args = process.argv.slice(2);
     const portIndex = args.indexOf("--port");
+    const hostIndex = args.indexOf("--host");
     const configIndex = args.indexOf("--config");
     const rpcIndex = args.indexOf("--rpc-url");
     const faucetIndex = args.indexOf("--faucet-url");
@@ -27,12 +28,14 @@ async function main() {
       !args[workDirIndex + 1]
     ) {
       console.error(
-        "Usage: api-server-entry --port <port> --config <config-path> --rpc-url <url> --faucet-url <url> --work-dir <dir>"
+        "Usage: api-server-entry --port <port> --config <config-path> --rpc-url <url> --faucet-url <url> --work-dir <dir> [--host <host>]"
       );
       process.exit(1);
     }
 
     const port = parseInt(args[portIndex + 1]!);
+    const host =
+      hostIndex !== -1 && args[hostIndex + 1] ? args[hostIndex + 1] : undefined;
     const configPath = args[configIndex + 1]!;
     const rpcUrl = args[rpcIndex + 1]!;
     const faucetUrl = args[faucetIndex + 1]!;
@@ -45,6 +48,7 @@ async function main() {
     // Create and start API server
     const apiServer = new APIServer({
       port,
+      host,
       validatorRpcUrl: rpcUrl,
       validatorFaucetUrl: faucetUrl,
       config,

package/src/commands/start.ts

@@ -21,7 +21,10 @@ function generateValidatorId(name: string): string {
   return `${safeName}-${timestamp}-${randomSuffix}`;
 }
 
-export async function startCommand(debug: boolean = false): Promise<void> {
+export async function startCommand(
+  debug: boolean = false,
+  network: boolean = false
+): Promise<void> {
   // Check prerequisites
   const tools = await checkSolanaTools();
   if (!tools.solana) {
@@ -360,7 +363,8 @@ export async function startCommand(debug: boolean = false): Promise<void> {
       const workDir = join(currentDir, ".solforge");
 
       // Start API server in background using runCommand with nohup
-      const apiServerCommand = `nohup bun run "${apiServerScript}" --port ${apiServerPort} --config "${configPath}" --rpc-url "http://127.0.0.1:${config.localnet.port}" --faucet-url "http://127.0.0.1:${config.localnet.faucetPort}" --work-dir "${workDir}" > /dev/null 2>&1 &`;
+      const hostFlag = network ? ` --host "0.0.0.0"` : "";
+      const apiServerCommand = `nohup bun run "${apiServerScript}" --port ${apiServerPort} --config "${configPath}" --rpc-url "http://127.0.0.1:${config.localnet.port}" --faucet-url "http://127.0.0.1:${config.localnet.faucetPort}" --work-dir "${workDir}"${hostFlag} > /dev/null 2>&1 &`;
 
       const startResult = await runCommand("sh", ["-c", apiServerCommand], {
         silent: !debug,
@@ -373,8 +377,9 @@ export async function startCommand(debug: boolean = false): Promise<void> {
 
         // Test if the API server is responding
         try {
+          const healthCheckHost = network ? "0.0.0.0" : "127.0.0.1";
           const response = await fetch(
-            `http://127.0.0.1:${apiServerPort}/api/health`
+            `http://${healthCheckHost}:${apiServerPort}/api/health`
           );
           if (response.ok) {
             apiResult = { success: true };
@@ -385,7 +390,10 @@ export async function startCommand(debug: boolean = false): Promise<void> {
               { silent: true, debug: false }
             );
             if (pidResult.success && pidResult.stdout.trim()) {
-              apiServerPid = parseInt(pidResult.stdout.trim().split("\n")[0]);
+              const pidLine = pidResult.stdout.trim().split("\n")[0];
+              if (pidLine) {
+                apiServerPid = parseInt(pidLine);
+              }
             }
           } else {
             apiResult = {
@@ -436,7 +444,7 @@ export async function startCommand(debug: boolean = false): Promise<void> {
       status: "running",
       apiServerPort: apiResult.success ? apiServerPort : undefined,
       apiServerUrl: apiResult.success
-        ? `http://127.0.0.1:${apiServerPort}`
+        ? `http://${network ? "0.0.0.0" : "127.0.0.1"}:${apiServerPort}`
         : undefined,
       apiServerPid: apiResult.success ? apiServerPid : undefined,
     };
@@ -457,9 +465,17 @@ export async function startCommand(debug: boolean = false): Promise<void> {
       )
     );
     if (apiResult.success) {
+      const displayHost = network ? "0.0.0.0" : "127.0.0.1";
       console.log(
-        chalk.cyan(`🚀 API Server: http://127.0.0.1:${apiServerPort}/api`)
+        chalk.cyan(`🚀 API Server: http://${displayHost}:${apiServerPort}/api`)
       );
+      if (network) {
+        console.log(
+          chalk.yellow(
+            "   🌐 Network mode enabled - API server accessible from other devices"
+          )
+        );
+      }
     }
 
     // Airdrop SOL to mint authority if tokens were cloned
@@ -563,30 +579,31 @@ export async function startCommand(debug: boolean = false): Promise<void> {
       chalk.gray("  - Run `solforge stop --all` to stop all validators")
     );
     if (apiResult.success) {
+      const endpointHost = network ? "0.0.0.0" : "127.0.0.1";
       console.log(chalk.blue("\n🔌 API Endpoints:"));
       console.log(
         chalk.gray(
-          `  - GET  http://127.0.0.1:${apiServerPort}/api/tokens - List cloned tokens`
+          `  - GET  http://${endpointHost}:${apiServerPort}/api/tokens - List cloned tokens`
         )
       );
       console.log(
         chalk.gray(
-          `  - GET  http://127.0.0.1:${apiServerPort}/api/programs - List cloned programs`
+          `  - GET  http://${endpointHost}:${apiServerPort}/api/programs - List cloned programs`
         )
       );
       console.log(
         chalk.gray(
-          `  - POST http://127.0.0.1:${apiServerPort}/api/tokens/{symbol}/mint - Mint tokens`
+          `  - POST http://${endpointHost}:${apiServerPort}/api/tokens/{mintAddress}/mint - Mint tokens`
         )
       );
       console.log(
         chalk.gray(
-          `  - POST http://127.0.0.1:${apiServerPort}/api/airdrop - Airdrop SOL`
+          `  - POST http://${endpointHost}:${apiServerPort}/api/airdrop - Airdrop SOL`
         )
       );
       console.log(
         chalk.gray(
-          `  - GET  http://127.0.0.1:${apiServerPort}/api/wallet/{address}/balances - Get balances`
+          `  - GET  http://${endpointHost}:${apiServerPort}/api/wallet/{address}/balances - Get balances`
         )
       );
     }

package/src/index.ts

@@ -47,6 +47,7 @@ program
   .command("start")
   .description("Start localnet with current sf.config.json")
   .option("--debug", "Enable debug logging to see commands and detailed output")
+  .option("--network", "Make API server accessible over network (binds to 0.0.0.0 instead of 127.0.0.1)")
   .action(async (options) => {
     const configPath = findConfig();
     if (!configPath) {
@@ -57,7 +58,7 @@ program
       process.exit(1);
     }
 
-    await startCommand(options.debug || false);
+    await startCommand(options.debug || false, options.network || false);
   });
 
 program
@@ -86,6 +87,76 @@ program
     await killCommand(validatorId, options);
   });
 
+program
+  .command("api-server")
+  .description("Start API server standalone")
+  .option("-p, --port <port>", "Port for API server", "3000")
+  .option("--host <host>", "Host to bind to (default: 127.0.0.1, use 0.0.0.0 for network access)")
+  .option("--rpc-url <url>", "Validator RPC URL", "http://127.0.0.1:8899")
+  .option("--faucet-url <url>", "Validator faucet URL", "http://127.0.0.1:9900")
+  .option("--work-dir <dir>", "Work directory", "./.solforge")
+  .action(async (options) => {
+    const configPath = findConfig();
+    if (!configPath) {
+      console.error(
+        chalk.red("❌ No sf.config.json found in current directory")
+      );
+      console.log(chalk.yellow("💡 Run `solforge init` to create one"));
+      process.exit(1);
+    }
+
+    // Import API server components
+    const { APIServer } = await import("./services/api-server.js");
+    const { configManager } = await import("./config/manager.js");
+
+    try {
+      await configManager.load(configPath);
+      const config = configManager.getConfig();
+
+      const apiServer = new APIServer({
+        port: parseInt(options.port),
+        host: options.host,
+        validatorRpcUrl: options.rpcUrl,
+        validatorFaucetUrl: options.faucetUrl,
+        config,
+        workDir: options.workDir,
+      });
+
+      const result = await apiServer.start();
+      if (result.success) {
+        console.log(chalk.green("✅ API Server started successfully!"));
+        
+        // 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);
+    }
+  });
+
 program
   .command("add-program")
   .description("Add a program to sf.config.json")

package/src/services/api-server.ts

@@ -16,6 +16,7 @@ import type { ClonedToken } from "./token-cloner.js";
 
 export interface APIServerConfig {
   port: number;
+  host?: string;
   validatorRpcUrl: string;
   validatorFaucetUrl: string;
   config: Config;
@@ -121,9 +122,9 @@ export class APIServer {
     });
 
     // Mint tokens to a wallet
-    router.post("/tokens/:symbol/mint", async (req, res) => {
+    router.post("/tokens/:mintAddress/mint", async (req, res) => {
       try {
-        const { symbol } = req.params;
+        const { mintAddress } = req.params;
         const { walletAddress, amount } = req.body;
 
         if (!walletAddress || !amount) {
@@ -132,6 +133,15 @@ export class APIServer {
           });
         }
 
+        // Validate mint address
+        try {
+          new PublicKey(mintAddress);
+        } catch {
+          return res.status(400).json({
+            error: "Invalid mint address",
+          });
+        }
+
         // Validate wallet address
         try {
           new PublicKey(walletAddress);
@@ -149,7 +159,7 @@ export class APIServer {
         }
 
         const result = await this.mintTokenToWallet(
-          symbol,
+          mintAddress,
           walletAddress,
           amount
         );
@@ -326,17 +336,19 @@ export class APIServer {
   }
 
   private async mintTokenToWallet(
-    symbol: string,
+    mintAddress: string,
     walletAddress: string,
     amount: number
   ): Promise<any> {
     const clonedTokens = await this.getClonedTokens();
     const token = clonedTokens.find(
-      (t) => t.config.symbol.toLowerCase() === symbol.toLowerCase()
+      (t) => t.config.mainnetMint === mintAddress
     );
 
     if (!token) {
-      throw new Error(`Token ${symbol} not found in cloned tokens`);
+      throw new Error(
+        `Token with mint address ${mintAddress} not found in cloned tokens`
+      );
     }
 
     // Use the shared minting function from the mint command
@@ -462,15 +474,16 @@ export class APIServer {
   async start(): Promise<{ success: boolean; error?: string }> {
     return new Promise((resolve) => {
       try {
-        this.server = this.app.listen(this.config.port, "127.0.0.1", () => {
+        const host = this.config.host || "127.0.0.1";
+        this.server = this.app.listen(this.config.port, host, () => {
           console.log(
             chalk.green(
-              `🚀 API Server started on http://127.0.0.1:${this.config.port}`
+              `🚀 API Server started on http://${host}:${this.config.port}`
             )
           );
           console.log(
             chalk.gray(
-              `   📋 Endpoints available at http://127.0.0.1:${this.config.port}/api`
+              `   📋 Endpoints available at http://${host}:${this.config.port}/api`
             )
           );
           resolve({ success: true });