Merge pull request #409 from proto-kit/feat/cli-extended-functionality

Feat/cli extended functionality

Author: stanlou

package-lock.json

@@ -0,0 +1,197 @@
+# Proto-Kit CLI
+
+A comprehensive command-line interface for managing Proto-Kit applications, environments, and blockchain interactions.
+
+## Installation
+
+```bash
+npm install @proto-kit/cli
+```
+
+Or use with npx:
+
+```bash
+npx @proto-kit/cli <command>
+```
+
+## Commands Overview
+
+### Environment Management
+
+Creates a new environment configuration with an interactive guided wizard.
+
+```bash
+npm protokit wizard
+```
+
+This command walks you through setting up:
+- Network configuration
+- Key management
+- Environment variables
+- Deployment settings
+
+### Bridge Operations
+
+#### `bridge deposit <tokenId> <fromKey> <toKey> <amount>`
+Deposits tokens to the bridge contract.
+
+**Parameters:**
+- `tokenId` - Token identifier
+- `fromKey` - Sender's private key (or environment variable name)
+- `toKey` - Recipient's public key (or environment variable name)  
+- `amount` - Amount to deposit
+
+**Example:**
+```bash
+npm protokit bridge deposit 1 SENDER_KEY RECIPIENT_KEY 100
+```
+
+#### `bridge redeem <tokenId> <toKey> <amount>`
+Redeems tokens from the bridge contract.
+
+**Parameters:**
+- `tokenId` - Token identifier
+- `toKey` - Recipient's public key (or environment variable name)
+- `amount` - Amount to redeem
+
+**Example:**
+```bash
+npm protokit bridge redeem 1 RECIPIENT_KEY 100
+```
+
+#### `bridge withdraw <tokenId> <senderKey> <amount>`
+Withdraws tokens from the bridge.
+
+**Parameters:**
+- `tokenId` - Token identifier
+- `senderKey` - Sender's private key (or environment variable name)
+- `amount` - Amount to withdraw
+
+**Example:**
+```bash
+npm protokit bridge withdraw 1 SENDER_KEY 100
+```
+
+### Settlement Deployment
+
+#### `settlement deploy`
+Deploys settlement contracts to the network.
+
+```bash
+npm protokit settlement deploy
+```
+
+#### `settlement token-deploy <tokenSymbol> <feepayerKey> <receiverPublicKey> [mintAmount]`
+Deploys custom fungible tokens for settlement operations.
+
+**Parameters:**
+- `tokenSymbol` - Symbol for the token
+- `feepayerKey` - Private key for paying deployment fees
+- `receiverPublicKey` - Public key to receive initially minted tokens
+- `[mintAmount]` - Initial amount to mint (default: 0)
+
+**Example:**
+```bash
+npm protokit settlement token-deploy USDC FEEPAYER_KEY RECEIVER_KEY 1000
+```
+
+### Lightnet Utilities
+
+#### `lightnet:wait-for-network`
+Waits for the lightnet network to be ready before proceeding with other operations.
+
+```bash
+npm protokit lightnet wait
+```
+
+#### `lightnet:faucet <publicKey>`
+Sends MINA from the lightnet faucet to the specified account.
+
+**Parameters:**
+- `publicKey` - Destination public key (or environment variable name)
+
+**Example:**
+```bash
+npm protokit lightnet:faucet B62qnzbXQcUoQFnjvF4Kog6KfNsuuSoo7LSLvomPeak2CLvEYiUqT
+```
+
+#### `lightnet:initialize`
+Complete lightnet setup that performs:
+1. Waits for network readiness
+2. Funds test accounts from faucet
+3. Deploys settlement contracts
+
+```bash
+npm protokit lightnet initialize
+```
+
+### Developer Tools
+
+#### `generate-keys [count]`
+Generates private/public key pairs for development and testing.
+
+**Parameters:**
+- `[count]` - Number of key pairs to generate (default: 1)
+
+**Example:**
+```bash
+# Generate 1 key pair
+npm protokit generate-keys
+
+# Generate 5 key pairs
+npm protokit generate-keys 5
+```
+
+**Output format:**
+```
+Key Pair 1:
+Private Key: EKE8...
+Public Key: B62q...
+
+Key Pair 2:
+Private Key: EKF9...
+Public Key: B62r...
+```
+
+#### `explorer:start`
+Starts the Proto-Kit explorer web interface.
+
+**Options:**
+- `-p, --port` - Port to run on (default: 5003)
+- `--indexer-url` - GraphQL endpoint URL for the indexer
+
+**Examples:**
+```bash
+# Start on default port 5003
+npm protokit explorer start
+
+# Start on custom port with indexer URL
+npm protokit explorer start -p 3000 --indexer-url http://localhost:8081/graphql
+```
+
+## Environment Variable Configuration
+
+The CLI supports three methods for passing environment variables and configuration:
+
+### Option 1: `--env-path` (File-based)
+Load environment variables from a `.env` file:
+
+```bash
+npm protokit settlement deploy --env-path ./my-config/.env
+```
+
+### Option 2: `--set KEY=value` (Inline)
+Pass environment variables directly as command-line arguments. Can be used multiple times:
+
+```bash
+npm protokit settlement deploy \
+  --set PROTOKIT_SETTLEMENT_CONTRACT_PRIVATE_KEY=EK... \
+  MINA_NETWORK_URL=https://lightnet.lokinet.dev/graphql
+```
+
+### Option 3: `--env {envName}` (Named Environment)
+Use a pre-configured environment by name:
+
+```bash
+npm protokit settlement deploy --env sovereign
+```

packages/cli/README.md

@@ -2,19 +2,58 @@
 import { spawn } from "child_process";
 import path from "path";
 import { fileURLToPath } from "url";
+import { createRequire } from "module";
+import fs from "fs";
 import process from "process";
 
+const require = createRequire(import.meta.url);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+function resolveTsNodeEsm() {
+  const searchPaths = [process.cwd(), __dirname];
+
+  for (const base of searchPaths) {
+    try {
+      const pkgPath = require.resolve("ts-node/package.json", {
+        paths: [base],
+      });
+      const tsNodeDir = path.dirname(pkgPath);
+      const esmPath = path.join(tsNodeDir, "esm.mjs");
+      if (fs.existsSync(esmPath)) return esmPath;
+    } catch (_) {
+      // continue
+    }
+  }
+  return "ts-node/esm";
+}
+
 const args = process.argv.slice(2);
 
 if (!process.env.TS_NODE_LOADER_ACTIVE) {
   const env = { ...process.env };
   env.TS_NODE_LOADER_ACTIVE = "1";
+
+  // Configure ts-node for proper ESM/CJS interop
+  env.TS_NODE_ESMODULEINTEROP = "true";
+  env.TS_NODE_ALLOWJS = "true";
+  env.TS_NODE_EXPERIMENTALMODULES = "true";
+  env.TS_NODE_COMPILER_OPTIONS = JSON.stringify({
+    module: "ESNext",
+    moduleResolution: "node",
+    allowSyntheticDefaultImports: true,
+    esModuleInterop: true,
+    allowJs: true,
+    target: "ES2020",
+    experimentalDecorators: true,
+    emitDecoratorMetadata: true,
+    strictNullChecks: true,
+  });
+
+  const tsNodeEsm = resolveTsNodeEsm();
   env.NODE_OPTIONS = [
     env.NODE_OPTIONS || "",
-    "--loader ts-node/esm",
+    `--loader ${tsNodeEsm}`,
     "--experimental-vm-modules",
     "--experimental-wasm-modules",
     "--es-module-specifier-resolution=node",

packages/cli/bin/protokit-cli.js

@@ -4,7 +4,7 @@
   "type": "module",
   "main": "./bin/protokit-cli.js",
   "bin": {
-    "proto-kit": "./bin/protokit-cli.js"
+    "protokit": "./bin/protokit-cli.js"
   },
   "publishConfig": {
     "access": "public"
@@ -21,21 +21,31 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "yargs": "17.7.2",
+    "@inquirer/figures": "^2.0.3",
+    "dotenv": "^17.2.3",
+    "inquirer": "^9.3.0",
+    "kleur": "^4.1.5",
+    "mina-fungible-token": "^1.1.0",
+    "reflect-metadata": "^0.1.13",
+    "spectaql": "3.0.5",
     "ts-node": "^10.9.1",
-    "spectaql": "3.0.5"
+    "yargs": "17.7.2"
   },
   "peerDependencies": {
     "@proto-kit/api": "*",
     "@proto-kit/common": "*",
+    "@proto-kit/explorer": "*",
     "@proto-kit/library": "*",
     "@proto-kit/module": "*",
     "@proto-kit/protocol": "*",
     "@proto-kit/sdk": "*",
     "@proto-kit/sequencer": "*",
-    "o1js": "^2.10.0"
+    "@proto-kit/stack": "*",
+    "o1js": "^2.10.0",
+    "tsyringe": "^4.10.0"
   },
   "devDependencies": {
+    "@types/inquirer": "^9.0.9",
     "@types/node": "^20.19.24",
     "@types/yargs": "17.0.32"
   }

packages/cli/package.json

@@ -0,0 +1,23 @@
+import { CommandModule } from "yargs";
+
+export const bridgeCommand: CommandModule = {
+  command: "bridge <subcommand>",
+  describe: "Bridge operations",
+  builder: async (yargs) => {
+    const { depositCommand } = await import("./deposit");
+    const { redeemCommand } = await import("./redeem");
+    const { withdrawCommand } = await import("./withdraw");
+
+    return yargs
+      .command(depositCommand)
+      .command(redeemCommand)
+      .command(withdrawCommand)
+      .demandCommand(
+        1,
+        "You must specify a subcommand. Use --help to see available options."
+      );
+  },
+  handler: () => {
+    console.log("Use a subcommand. See --help for available options.");
+  },
+};

packages/cli/src/commands/bridge/bridge.ts

@@ -0,0 +1,50 @@
+import { CommandModule } from "yargs";
+
+import { addEnvironmentOptions } from "../../utils/environmentOptions";
+
+interface DepositArgs {
+  tokenId: string;
+  fromKey: string;
+  toKey: string;
+  amount: number;
+  "env-path"?: string;
+  env?: string;
+  set?: string[];
+}
+
+export const depositCommand: CommandModule<{}, DepositArgs> = {
+  command: "deposit <tokenId> <fromKey> <toKey> <amount>",
+  describe:
+    "Deposit tokens to the bridge\n\nRequires: PROTOKIT_CUSTOM_TOKEN_PRIVATE_KEY (for custom tokens), PROTOKIT_CUSTOM_TOKEN_BRIDGE_PRIVATE_KEY, PROTOKIT_MINA_BRIDGE_CONTRACT_PRIVATE_KEY",
+  builder: (yarg) =>
+    addEnvironmentOptions(
+      yarg
+        .positional("tokenId", { type: "string", demandOption: true })
+        .positional("fromKey", { type: "string", demandOption: true })
+        .positional("toKey", { type: "string", demandOption: true })
+        .positional("amount", { type: "number", demandOption: true })
+    ),
+  handler: async (args) => {
+    try {
+      const { default: deposit } = await import("../../scripts/bridge/deposit");
+      const { parseEnvArgs } = await import("../../utils/loadEnv");
+      await deposit(
+        {
+          envPath: args["env-path"],
+          env: args.env!,
+          envVars: parseEnvArgs(args.set ?? []),
+        },
+        {
+          tokenId: args.tokenId,
+          fromKey: args.fromKey,
+          toKey: args.toKey,
+          amount: args.amount,
+        }
+      );
+      process.exit(0);
+    } catch (error) {
+      console.error("Failed to deposit to bridge:", error);
+      process.exit(1);
+    }
+  },
+};