refactor: migrate CLI to NestJS architecture with test suite and UX improvements

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.env.example

@@ -1,23 +1,81 @@
-# Private keys for each chain type
-EVM_PRIVATE_KEY=0x...
-TVM_PRIVATE_KEY=...
-SVM_PRIVATE_KEY=...
-
-# RPC endpoints (optional - defaults provided)
-EVM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/...
-TVM_RPC_URL=https://api.trongrid.io
-SVM_RPC_URL=https://api.mainnet-beta.solana.com
-
-# Quote Service Configuration (optional)
-# Use solver-v2 endpoint (takes precedence over quote service)
-SOLVER_URL=https://solver.example.com
-
-# Use preprod quote service (only applies if SOLVER_URL not set)
-# QUOTES_API_URL=any_value
-# QUOTES_PREPROD=any_value
-
-# Portal contract addresses per chain (optional - defaults provided)
-PORTAL_ADDRESS_ETH=0x...
-PORTAL_ADDRESS_OPTIMISM=0x...
-PORTAL_ADDRESS_TRON=...
-PORTAL_ADDRESS_SOLANA=...
+# =============================================================================
+# Routes CLI — Environment Configuration
+# =============================================================================
+# Copy this file to .env and fill in the values for your setup.
+#
+# REQUIRED variables must be set before publishing to the corresponding chain.
+# OPTIONAL variables override built-in defaults; omitting them is safe.
+#
+# Private key format summary:
+#   EVM  — 0x followed by 64 hexadecimal characters (66 chars total)
+#   TVM  — 64 hexadecimal characters WITHOUT the 0x prefix (64 chars)
+#   SVM  — base58 string, JSON array [1,2,...], or comma-separated bytes
+# =============================================================================
+
+
+# =============================================================================
+# REQUIRED: Private Keys
+# Set the key for each chain type you intend to publish intents on.
+# =============================================================================
+
+# EVM chains (Ethereum, Base, Optimism, Arbitrum, Polygon, BSC, Ronin, etc.)
+# Format : 0x + 64 hexadecimal characters (66 characters total)
+# Example: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+EVM_PRIVATE_KEY=
+
+# TVM chain (Tron mainnet / Tron Shasta testnet)
+# Format : 64 hexadecimal characters WITHOUT the 0x prefix (64 characters)
+# NOTE   : Do NOT use your TRX wallet address (starts with T); use the raw hex key
+# Example: ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
+TVM_PRIVATE_KEY=
+
+# SVM chain (Solana mainnet / Solana Devnet)
+# Three accepted formats (choose one):
+#
+#   Base58 string (default export from Phantom, Solana CLI `solana-keygen`):
+#     SVM_PRIVATE_KEY=5K5K5K...base58EncodedKey
+#
+#   JSON byte array (Solana CLI keypair file format):
+#     SVM_PRIVATE_KEY=[1,2,3,4,...,64]
+#
+#   Comma-separated byte values:
+#     SVM_PRIVATE_KEY=1,2,3,4,...,64
+SVM_PRIVATE_KEY=
+
+
+# =============================================================================
+# OPTIONAL: RPC Endpoint Overrides
+# Each chain has a built-in default RPC URL. Set these to use a private
+# or rate-limit-free endpoint (Alchemy, Infura, QuickNode, etc.).
+# =============================================================================
+
+# EVM chains — override per chain using EVM_RPC_URL_{CHAIN_ID}:
+# EVM_RPC_URL_1=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY      # Ethereum
+# EVM_RPC_URL_10=https://opt-mainnet.g.alchemy.com/v2/YOUR_KEY     # Optimism
+# EVM_RPC_URL_8453=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY  # Base
+# EVM_RPC_URL_42161=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY  # Arbitrum
+
+# Tron — default: https://api.trongrid.io
+# TVM_RPC_URL=https://api.trongrid.io
+
+# Solana — default: https://api.mainnet-beta.solana.com
+# SVM_RPC_URL=https://api.mainnet-beta.solana.com
+
+
+# =============================================================================
+# OPTIONAL: Quote Service Selection
+# Controls which pricing endpoint is used for route quotes.
+#
+# Priority order (highest first):
+#   1. SOLVER_URL     — solver-v2 API at {SOLVER_URL}/api/v2/quote/reverse
+#   2. QUOTES_PREPROD — preprod service at https://quotes-preprod.eco.com/...
+#   3. (default)      — production service at https://quotes.eco.com/...
+#
+# Unset all three to use the default production service.
+# =============================================================================
+
+# Solver v2 endpoint (takes precedence over all other quote service settings)
+# SOLVER_URL=https://your-solver.example.com
+
+# Set to any non-empty value to force the preprod quote service (ignored if SOLVER_URL is set)
+# QUOTES_PREPROD=true

.github/workflows/ci.yml

@@ -0,0 +1,93 @@
+name: CI
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [main]
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm test:coverage
+      - run: pnpm build
+      - run: pnpm audit --audit-level=moderate
+  e2e:
+    runs-on: ubuntu-latest
+    needs: quality
+    env:
+      FORK_RPC_URL: ${{ secrets.BASE_RPC_URL }}
+      FORK_BLOCK_NUMBER: '28000000'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - name: Run E2E tests (Anvil managed by Jest global setup/teardown)
+        run: pnpm test:e2e:ci
+  release:
+    runs-on: ubuntu-latest
+    needs: quality
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - name: Publish to npm
+        run: pnpm publish --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+  docs:
+    runs-on: ubuntu-latest
+    needs: quality
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - name: Generate API docs
+        run: pnpm docs
+      - uses: actions/configure-pages@v4
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/api
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/security.yml

@@ -0,0 +1,30 @@
+name: Security Scan
+on:
+  schedule:
+    - cron: '0 2 * * *'
+  push:
+    branches: [main]
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm audit --audit-level=high
+  secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: trufflesecurity/trufflehog@main
+        with:
+          path: ./
+          base: ${{ github.event.repository.default_branch }}
+          head: HEAD
+          extra_args: --debug --only-verified

.gitignore

@@ -3,6 +3,10 @@ node_modules/
 
 # Build output
 dist/
+bundle/
+
+# Generated docs
+docs/api/
 
 # Environment files
 .env
@@ -33,3 +37,4 @@ coverage/
 
 CLAUDE.md
 thoughts/
+.worktrees/

.husky/pre-commit

@@ -1 +1,2 @@
 npx lint-staged
+pnpm typecheck

.node-version

@@ -0,0 +1 @@
+18

.nvmrc

@@ -0,0 +1 @@
+18