naracli 0.1.0

package/src/cli/types.ts

@@ -0,0 +1,207 @@
+/**
+ * CLI-specific types and interfaces
+ */
+
+import { PublicKey } from "@solana/web3.js";
+
+/**
+ * Global options available on all commands
+ */
+export interface GlobalOptions {
+  /** RPC endpoint URL */
+  rpcUrl?: string;
+  /** Path to wallet keypair JSON file */
+  wallet?: string;
+  /** Output in JSON format */
+  json?: boolean;
+}
+
+/**
+ * Config create command options
+ */
+export interface ConfigCreateOptions extends GlobalOptions {
+  /** Fee claimer wallet address */
+  feeClaimer?: string;
+  /** Leftover token receiver wallet address */
+  leftoverReceiver?: string;
+  /** Total token supply */
+  totalSupply?: number;
+  /** Initial market cap */
+  initialMcap?: number;
+  /** Migration market cap */
+  migrationMcap?: number;
+  /** Export unsigned transaction */
+  exportTx?: boolean;
+}
+
+/**
+ * Pool create command options
+ */
+export interface PoolCreateOptions extends GlobalOptions {
+  /** Token name */
+  name: string;
+  /** Token symbol */
+  symbol: string;
+  /** Metadata URI */
+  uri: string;
+  /** DBC config address */
+  dbcConfig: string;
+  /** Pool creator address */
+  creator?: string;
+  /** Export unsigned transaction */
+  exportTx?: boolean;
+}
+
+/**
+ * Pool create with buy command options
+ */
+export interface PoolCreateWithBuyOptions extends PoolCreateOptions {
+  /** Initial buy amount in SOL */
+  amount: number;
+  /** Buyer address */
+  buyer?: string;
+  /** Token receiver address */
+  receiver?: string;
+  /** Slippage in basis points */
+  slippage?: number;
+}
+
+/**
+ * Pool info command options
+ */
+export interface PoolInfoOptions extends GlobalOptions {
+  /** Token address */
+  tokenAddress: string;
+}
+
+/**
+ * Swap buy command options
+ */
+export interface SwapBuyOptions extends GlobalOptions {
+  /** Token address */
+  tokenAddress: string;
+  /** Amount in SOL */
+  amount: number;
+  /** Slippage in basis points */
+  slippage?: number;
+  /** Swap mode */
+  mode?: string;
+  /** Export unsigned transaction */
+  exportTx?: boolean;
+}
+
+/**
+ * Swap sell command options
+ */
+export interface SwapSellOptions extends GlobalOptions {
+  /** Token address */
+  tokenAddress: string;
+  /** Amount in tokens */
+  amount: number;
+  /** Token decimals */
+  decimals?: number;
+  /** Slippage in basis points */
+  slippage?: number;
+  /** Swap mode */
+  mode?: string;
+  /** Export unsigned transaction */
+  exportTx?: boolean;
+}
+
+/**
+ * Swap quote command options
+ */
+export interface SwapQuoteOptions extends GlobalOptions {
+  /** Token address */
+  tokenAddress: string;
+  /** Amount */
+  amount: number;
+  /** Direction: buy or sell */
+  direction: string;
+  /** Token decimals (for sell only) */
+  decimals?: number;
+  /** Slippage in basis points */
+  slippage?: number;
+}
+
+/**
+ * Migrate launch command options
+ */
+export interface MigrateLaunchOptions extends GlobalOptions {
+  /** Token address */
+  tokenAddress: string;
+  /** Export unsigned transaction */
+  exportTx?: boolean;
+}
+
+/**
+ * Migrate create locker command options
+ */
+export interface MigrateCreateLockerOptions extends GlobalOptions {
+  /** Token address */
+  tokenAddress: string;
+  /** Export unsigned transaction */
+  exportTx?: boolean;
+}
+
+/**
+ * Migrate check command options
+ */
+export interface MigrateCheckOptions extends GlobalOptions {
+  /** Token address */
+  tokenAddress: string;
+}
+
+/**
+ * Wallet balance command options
+ */
+export interface WalletBalanceOptions extends GlobalOptions {
+  /** Wallet address (optional, defaults to current wallet) */
+  address?: string;
+}
+
+/**
+ * Token balance command options
+ */
+export interface TokenBalanceOptions extends GlobalOptions {
+  /** Token address */
+  tokenAddress: string;
+  /** Owner address (optional, defaults to current wallet) */
+  owner?: string;
+}
+
+/**
+ * Transaction status command options
+ */
+export interface TxStatusOptions extends GlobalOptions {
+  /** Transaction signature */
+  signature: string;
+}
+
+/**
+ * Transfer SOL command options
+ */
+export interface TransferSolOptions extends GlobalOptions {
+  /** Recipient address */
+  to: string;
+  /** Amount in SOL */
+  amount: number;
+  /** Export unsigned transaction */
+  exportTx?: boolean;
+}
+
+/**
+ * Transfer token command options
+ */
+export interface TransferTokenOptions extends GlobalOptions {
+  /** Token address */
+  tokenAddress: string;
+  /** Recipient address */
+  to: string;
+  /** Amount in tokens */
+  amount: number;
+  /** Token decimals */
+  decimals?: number;
+  /** Export unsigned transaction */
+  exportTx?: boolean;
+}

package/src/cli/utils/output.ts

@@ -0,0 +1,110 @@
+/**
+ * Output formatting utilities
+ */
+
+/**
+ * Format output based on mode
+ * @param data Data to output
+ * @param jsonMode Whether to output in JSON format
+ */
+export function formatOutput(data: any, jsonMode: boolean = false): void {
+  if (jsonMode) {
+    console.log(JSON.stringify(data, null, 2));
+  } else {
+    // Human-readable output
+    formatHumanReadable(data);
+  }
+}
+
+/**
+ * Format data in human-readable format
+ * @param data Data to format
+ */
+function formatHumanReadable(data: any): void {
+  if (typeof data === "object" && data !== null) {
+    for (const [key, value] of Object.entries(data)) {
+      const label = formatLabel(key);
+
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        console.log(`\n${label}:`);
+        formatHumanReadable(value);
+      } else {
+        console.log(`${label}: ${formatValue(value)}`);
+      }
+    }
+  } else {
+    console.log(data);
+  }
+}
+
+/**
+ * Format object key as human-readable label
+ * @param key Object key
+ * @returns Formatted label
+ */
+function formatLabel(key: string): string {
+  // Convert camelCase to Title Case
+  const words = key.replace(/([A-Z])/g, " $1").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/**
+ * Format value for display
+ * @param value Value to format
+ * @returns Formatted value string
+ */
+function formatValue(value: any): string {
+  if (value === null || value === undefined) {
+    return "N/A";
+  }
+
+  if (typeof value === "boolean") {
+    return value ? "Yes" : "No";
+  }
+
+  if (typeof value === "number") {
+    // Format large numbers with commas
+    if (value >= 1000) {
+      return value.toLocaleString();
+    }
+    return value.toString();
+  }
+
+  if (Array.isArray(value)) {
+    return value.join(", ");
+  }
+
+  return value.toString();
+}
+
+/**
+ * Print success message
+ * @param message Success message
+ */
+export function printSuccess(message: string): void {
+  console.log(`✅ ${message}`);
+}
+
+/**
+ * Print error message
+ * @param message Error message
+ */
+export function printError(message: string): void {
+  console.error(`❌ Error: ${message}`);
+}
+
+/**
+ * Print info message
+ * @param message Info message
+ */
+export function printInfo(message: string): void {
+  console.log(`ℹ️  ${message}`);
+}
+
+/**
+ * Print warning message
+ * @param message Warning message
+ */
+export function printWarning(message: string): void {
+  console.log(`⚠️  ${message}`);
+}

package/src/cli/utils/transaction.ts

@@ -0,0 +1,146 @@
+/**
+ * Transaction handling utilities
+ */
+
+import {
+  sendAndConfirmTransaction,
+  Transaction,
+  VersionedTransaction,
+  Keypair,
+} from "@solana/web3.js";
+import { NaraSDK } from "../../client";
+import { printInfo, printSuccess } from "./output";
+
+/**
+ * Result of transaction handling
+ */
+export interface TransactionResult {
+  /** Transaction signature (if sent) */
+  signature?: string;
+  /** Base64-encoded transaction (if exported) */
+  base64?: string;
+}
+
+/**
+ * Handle transaction signing and sending or exporting
+ *
+ * @param sdk NaraSDK SDK instance
+ * @param transaction Transaction or VersionedTransaction
+ * @param signers Array of keypairs to sign with
+ * @param exportMode Whether to export unsigned transaction
+ * @returns Transaction result with signature or base64
+ */
+export async function handleTransaction(
+  sdk: NaraSDK,
+  transaction: Transaction | VersionedTransaction,
+  signers: Keypair[],
+  exportMode: boolean = false
+): Promise<TransactionResult> {
+  if (exportMode) {
+    // Export unsigned transaction as base64
+    return exportTransaction(transaction);
+  }
+
+  // Sign and send transaction
+  return await signAndSendTransaction(sdk, transaction, signers);
+}
+
+/**
+ * Export unsigned transaction as base64
+ * @param transaction Transaction to export
+ * @returns Base64-encoded transaction
+ */
+function exportTransaction(
+  transaction: Transaction | VersionedTransaction
+): TransactionResult {
+  try {
+    const serialized = transaction.serialize({
+      requireAllSignatures: false,
+      verifySignatures: false,
+    });
+    const base64 = Buffer.from(serialized).toString("base64");
+
+    return { base64 };
+  } catch (error: any) {
+    throw new Error(`Failed to serialize transaction: ${error.message}`);
+  }
+}
+
+/**
+ * Sign and send transaction
+ * @param sdk NaraSDK SDK instance
+ * @param transaction Transaction to sign and send
+ * @param signers Keypairs to sign with
+ * @returns Transaction signature
+ */
+async function signAndSendTransaction(
+  sdk: NaraSDK,
+  transaction: Transaction | VersionedTransaction,
+  signers: Keypair[]
+): Promise<TransactionResult> {
+  const connection = sdk.getConnection();
+
+  try {
+    printInfo("Signing transaction...");
+
+    let signature: string;
+
+    if (transaction instanceof VersionedTransaction) {
+      // Handle VersionedTransaction
+      transaction.sign(signers);
+
+      printInfo("Sending transaction...");
+      signature = await connection.sendTransaction(transaction, {
+        maxRetries: 3,
+      });
+
+      printInfo("Confirming transaction...");
+      await connection.confirmTransaction(signature, "confirmed");
+    } else {
+      // Handle regular Transaction
+      printInfo("Sending transaction...");
+      signature = await sendAndConfirmTransaction(
+        connection,
+        transaction,
+        signers,
+        {
+          commitment: "confirmed",
+          skipPreflight: true,
+        }
+      );
+    }
+
+    return { signature };
+  } catch (error: any) {
+    throw new Error(`Transaction failed: ${error.message}`);
+  }
+}
+
+/**
+ * Print transaction result
+ * @param result Transaction result
+ * @param jsonMode Whether to output in JSON format
+ */
+export function printTransactionResult(
+  result: TransactionResult,
+  jsonMode: boolean = false
+): void {
+  if (result.signature) {
+    if (jsonMode) {
+      console.log(JSON.stringify({ signature: result.signature }, null, 2));
+    } else {
+      printSuccess("Transaction successful!");
+      console.log(`Signature: ${result.signature}`);
+      console.log(
+        `View on Solscan: https://solscan.io/tx/${result.signature}?cluster=devnet`
+      );
+    }
+  } else if (result.base64) {
+    if (jsonMode) {
+      console.log(JSON.stringify({ transaction: result.base64 }, null, 2));
+    } else {
+      printSuccess("Transaction exported!");
+      console.log(`\nBase64 transaction:\n${result.base64}`);
+    }
+  }
+}

package/src/cli/utils/validation.ts

@@ -0,0 +1,120 @@
+/**
+ * Input validation utilities
+ */
+
+import { PublicKey } from "@solana/web3.js";
+
+/**
+ * Validate that a string is a valid Solana public key
+ * @param address Address string to validate
+ * @returns PublicKey if valid
+ * @throws Error if invalid
+ */
+export function validatePublicKey(address: string): PublicKey {
+  try {
+    return new PublicKey(address);
+  } catch (error) {
+    throw new Error(`Invalid Solana address: ${address}`);
+  }
+}
+
+/**
+ * Validate that a value is a positive number
+ * @param value Value to validate
+ * @param name Parameter name for error message
+ * @returns Parsed number if valid
+ * @throws Error if invalid
+ */
+export function validatePositiveNumber(
+  value: string | number,
+  name: string
+): number {
+  const num = typeof value === "string" ? parseFloat(value) : value;
+
+  if (isNaN(num)) {
+    throw new Error(`${name} must be a valid number`);
+  }
+
+  if (num <= 0) {
+    throw new Error(`${name} must be greater than 0`);
+  }
+
+  return num;
+}
+
+/**
+ * Validate that a value is a non-negative number
+ * @param value Value to validate
+ * @param name Parameter name for error message
+ * @returns Parsed number if valid
+ * @throws Error if invalid
+ */
+export function validateNonNegativeNumber(
+  value: string | number,
+  name: string
+): number {
+  const num = typeof value === "string" ? parseFloat(value) : value;
+
+  if (isNaN(num)) {
+    throw new Error(`${name} must be a valid number`);
+  }
+
+  if (num < 0) {
+    throw new Error(`${name} must be non-negative`);
+  }
+
+  return num;
+}
+
+/**
+ * Validate swap mode string
+ * @param mode Mode string
+ * @returns Validated mode string
+ * @throws Error if invalid
+ */
+export function validateSwapMode(mode: string): string {
+  const validModes = ["exact-in", "partial-fill", "exact-out"];
+  const normalized = mode.toLowerCase();
+
+  if (!validModes.includes(normalized)) {
+    throw new Error(
+      `Invalid swap mode: ${mode}. Must be one of: ${validModes.join(", ")}`
+    );
+  }
+
+  return normalized;
+}
+
+/**
+ * Validate direction string
+ * @param direction Direction string
+ * @returns Validated direction string
+ * @throws Error if invalid
+ */
+export function validateDirection(direction: string): string {
+  const validDirections = ["buy", "sell"];
+  const normalized = direction.toLowerCase();
+
+  if (!validDirections.includes(normalized)) {
+    throw new Error(
+      `Invalid direction: ${direction}. Must be one of: ${validDirections.join(
+        ", "
+      )}`
+    );
+  }
+
+  return normalized;
+}
+
+/**
+ * Validate required option
+ * @param value Option value
+ * @param name Option name
+ * @throws Error if value is undefined
+ */
+export function validateRequired<T>(value: T | undefined, name: string): T {
+  if (value === undefined || value === null) {
+    throw new Error(`${name} is required`);
+  }
+  return value;
+}

package/src/cli/utils/wallet.ts

@@ -0,0 +1,72 @@
+/**
+ * Wallet loading utilities
+ */
+
+import { Keypair } from "@solana/web3.js";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { DEFAULT_RPC_URL, DEFAULT_WALLET_PATH as _DEFAULT_WALLET_PATH } from "../../constants";
+
+/**
+ * Resolve wallet path (expand ~ to home directory)
+ */
+const DEFAULT_WALLET_PATH = _DEFAULT_WALLET_PATH.startsWith("~")
+  ? join(homedir(), _DEFAULT_WALLET_PATH.slice(1))
+  : _DEFAULT_WALLET_PATH;
+
+/**
+ * Load wallet keypair from file
+ *
+ * Priority:
+ * 1. CLI flag (walletPath parameter)
+ * 2. Default path (~/.config/nara/id.json)
+ * 3. Error if neither exists
+ *
+ * @param walletPath Optional path to wallet keypair JSON file
+ * @returns Keypair
+ * @throws Error if wallet cannot be loaded
+ */
+export async function loadWallet(walletPath?: string): Promise<Keypair> {
+  // Use provided path or default path
+  const path = walletPath || DEFAULT_WALLET_PATH;
+
+  try {
+    const fs = await import("node:fs/promises");
+    const file = await fs.readFile(path, "utf-8");
+    const data = JSON.parse(file);
+
+    // Handle both array format [1,2,3,...] and object format
+    if (Array.isArray(data)) {
+      return Keypair.fromSecretKey(new Uint8Array(data));
+    } else if (data.secretKey) {
+      return Keypair.fromSecretKey(new Uint8Array(data.secretKey));
+    } else {
+      throw new Error(
+        "Invalid wallet file format. Expected array or object with secretKey field."
+      );
+    }
+  } catch (error: any) {
+    if (!walletPath) {
+      // If using default path and it doesn't exist, provide helpful error message
+      throw new Error(
+        `Wallet not found. Please create a wallet at ${DEFAULT_WALLET_PATH} or use --wallet flag to specify a different path.`
+      );
+    } else {
+      throw new Error(`Failed to load wallet from ${path}: ${error.message}`);
+    }
+  }
+}
+
+/**
+ * Get RPC URL from options
+ *
+ * Priority:
+ * 1. CLI flag (rpcUrl parameter)
+ * 2. Default (from constants)
+ *
+ * @param rpcUrl Optional RPC URL from CLI flag
+ * @returns RPC URL
+ */
+export function getRpcUrl(rpcUrl?: string): string {
+  return rpcUrl || DEFAULT_RPC_URL;
+}