@vainplex/shieldapi-cli 1.3.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vainplex/shieldapi-cli",
-  "version": "1.3.1",
+  "version": "2.0.0",
   "description": "Security intelligence from your terminal. Pay-per-request with USDC.",
   "type": "module",
   "bin": {
@@ -12,6 +12,9 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
   "engines": {
     "node": ">=18"
   },

package/src/commands/checkPrompt.js

@@ -0,0 +1,101 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { apiRequestPost } from '../lib/api.js';
+import { resolveWallet } from '../lib/wallet.js';
+import { riskBadge, sectionHeader } from '../lib/formatter.js';
+import { EXIT } from '../lib/exit.js';
+
+export async function checkPromptCommand(prompt, opts) {
+  const spinner = opts.quiet ? null : ora({ text: 'Analyzing prompt for injection patterns...', stream: process.stderr }).start();
+
+  try {
+    let inputPrompt = prompt;
+
+    // Read from stdin if --stdin flag
+    if (opts.stdin || !prompt) {
+      const chunks = [];
+      for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+      }
+      inputPrompt = Buffer.concat(chunks).toString('utf-8').trim();
+    }
+
+    if (!inputPrompt) {
+      if (spinner) spinner.fail('No prompt provided');
+      process.exitCode = EXIT.USAGE;
+      return;
+    }
+
+    const body = {
+      prompt: inputPrompt,
+      ...(opts.context && { context: opts.context }),
+    };
+
+    const wallet = opts.demo ? null : resolveWallet(opts);
+    const data = await apiRequestPost('check-prompt', body, {
+      demo: opts.demo,
+      wallet,
+    });
+
+    if (spinner) spinner.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatCheckPrompt(data, inputPrompt);
+    }
+
+    // Exit code: 0=clean, 1=injection detected
+    process.exitCode = data.isInjection ? 1 : 0;
+  } catch (err) {
+    if (spinner) spinner.fail(err.message);
+    process.exitCode = EXIT.API_ERROR;
+  }
+}
+
+function formatCheckPrompt(data, prompt) {
+  console.log();
+
+  if (data.isInjection) {
+    console.log(chalk.red.bold('⚠️  PROMPT INJECTION DETECTED'));
+    console.log();
+    console.log(`   Confidence: ${chalk.red.bold(Math.round(data.confidence * 100) + '%')}`);
+    console.log(`   Category: ${chalk.yellow(data.category)}`);
+    console.log(`   Patterns Checked: ${data.patternsChecked}`);
+    console.log(`   Scan Duration: ${data.scanDuration}ms`);
+
+    if (data.patterns?.length > 0) {
+      sectionHeader('Detected Patterns');
+      console.log();
+
+      for (const p of data.patterns) {
+        console.log(`   🔴 ${chalk.bold(p.type)}`);
+        console.log(`      ${p.description}`);
+        if (p.evidence) {
+          const truncated = p.evidence.length > 100 
+            ? p.evidence.slice(0, 100) + '...'
+            : p.evidence;
+          console.log(`      ${chalk.gray('Evidence:')} ${chalk.dim(truncated)}`);
+        }
+      }
+    }
+
+    if (data.decodedContent) {
+      sectionHeader('Decoded Content');
+      console.log(`   ${chalk.dim(data.decodedContent.slice(0, 200))}`);
+    }
+  } else {
+    console.log(chalk.green.bold('✅ No injection detected'));
+    console.log();
+    console.log(`   Confidence: ${chalk.green('0%')}`);
+    console.log(`   Patterns Checked: ${data.patternsChecked}`);
+    console.log(`   Scan Duration: ${data.scanDuration}ms`);
+  }
+
+  if (data.demo) {
+    console.log();
+    console.log(chalk.yellow('   ⚠️  Demo mode — results limited. Pay with x402 for full analysis.'));
+  }
+
+  console.log();
+}

package/src/commands/domain.js

@@ -1,35 +1,18 @@
-import ora from 'ora';
-import chalk from 'chalk';
-import { apiRequest } from '../lib/api.js';
-import { resolveWallet } from '../lib/wallet.js';
+import { runCommand } from '../lib/command.js';
 import { formatDomain } from '../lib/formatter.js';
-import { exitCodeFromResult, exitCodeFromError } from '../lib/exit.js';
+import { isValidDomain } from '../lib/validator.js';
 
 /**
  * Check domain reputation.
  */
 export async function domainCommand(domain, opts) {
-  const spinner = opts.quiet ? null : ora({ text: `Checking domain: ${domain}`, stream: process.stderr }).start();
-
-  try {
-    const wallet = opts.demo ? null : resolveWallet(opts);
-
-    const data = await apiRequest('check-domain', { domain }, {
-      demo: opts.demo,
-      wallet,
-    });
-
-    spinner?.stop();
-
-    if (opts.json) {
-      console.log(JSON.stringify(data, null, 2));
-    } else {
-      formatDomain(data);
-    }
-
-    process.exitCode = exitCodeFromResult(data);
-  } catch (err) {
-    spinner?.fail(err.message);
-    process.exitCode = exitCodeFromError(err);
-  }
+  await runCommand({
+    endpoint: 'check-domain',
+    paramName: 'domain',
+    paramValue: domain,
+    formatFn: formatDomain,
+    spinnerText: `Checking domain: ${domain}`,
+    validateFn: isValidDomain,
+    validateMsg: `Invalid domain: "${domain}". Provide a domain without protocol (e.g. example.com).`,
+  }, opts);
 }

package/src/commands/email.js

@@ -1,35 +1,18 @@
-import ora from 'ora';
-import chalk from 'chalk';
-import { apiRequest } from '../lib/api.js';
-import { resolveWallet } from '../lib/wallet.js';
+import { runCommand } from '../lib/command.js';
 import { formatEmail } from '../lib/formatter.js';
-import { exitCodeFromResult, exitCodeFromError } from '../lib/exit.js';
+import { isValidEmail } from '../lib/validator.js';
 
 /**
  * Check an email address for breaches.
  */
 export async function emailCommand(email, opts) {
-  const spinner = opts.quiet ? null : ora({ text: `Checking email: ${email}`, stream: process.stderr }).start();
-
-  try {
-    const wallet = opts.demo ? null : resolveWallet(opts);
-
-    const data = await apiRequest('check-email', { email }, {
-      demo: opts.demo,
-      wallet,
-    });
-
-    spinner?.stop();
-
-    if (opts.json) {
-      console.log(JSON.stringify(data, null, 2));
-    } else {
-      formatEmail(data, email);
-    }
-
-    process.exitCode = exitCodeFromResult(data);
-  } catch (err) {
-    spinner?.fail(err.message);
-    process.exitCode = exitCodeFromError(err);
-  }
+  await runCommand({
+    endpoint: 'check-email',
+    paramName: 'email',
+    paramValue: email,
+    formatFn: formatEmail,
+    spinnerText: `Checking email: ${email}`,
+    validateFn: isValidEmail,
+    validateMsg: `Invalid email: "${email}". Expected format: user@example.com.`,
+  }, opts);
 }

package/src/commands/hash.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import chalk from 'chalk';
+import { EXIT } from '../lib/exit.js';
 
 /**
  * Compute SHA-1 hash locally (offline, no API call).
@@ -16,4 +17,6 @@ export async function hashCommand(password, opts) {
     console.log(`   Length: ${password.length} characters`);
     console.log();
   }
+
+  process.exitCode = EXIT.SAFE;
 }

package/src/commands/health.js

@@ -1,5 +1,4 @@
 import ora from 'ora';
-import chalk from 'chalk';
 import { apiRequest } from '../lib/api.js';
 import { formatHealth } from '../lib/formatter.js';
 import { EXIT } from '../lib/exit.js';

package/src/commands/ip.js

@@ -1,35 +1,18 @@
-import ora from 'ora';
-import chalk from 'chalk';
-import { apiRequest } from '../lib/api.js';
-import { resolveWallet } from '../lib/wallet.js';
+import { runCommand } from '../lib/command.js';
 import { formatIp } from '../lib/formatter.js';
-import { exitCodeFromResult, exitCodeFromError } from '../lib/exit.js';
+import { isValidIPv4 } from '../lib/validator.js';
 
 /**
  * Check IP reputation.
  */
 export async function ipCommand(ip, opts) {
-  const spinner = opts.quiet ? null : ora({ text: `Checking IP: ${ip}`, stream: process.stderr }).start();
-
-  try {
-    const wallet = opts.demo ? null : resolveWallet(opts);
-
-    const data = await apiRequest('check-ip', { ip }, {
-      demo: opts.demo,
-      wallet,
-    });
-
-    spinner?.stop();
-
-    if (opts.json) {
-      console.log(JSON.stringify(data, null, 2));
-    } else {
-      formatIp(data);
-    }
-
-    process.exitCode = exitCodeFromResult(data);
-  } catch (err) {
-    spinner?.fail(err.message);
-    process.exitCode = exitCodeFromError(err);
-  }
+  await runCommand({
+    endpoint: 'check-ip',
+    paramName: 'ip',
+    paramValue: ip,
+    formatFn: formatIp,
+    spinnerText: `Checking IP: ${ip}`,
+    validateFn: isValidIPv4,
+    validateMsg: `Invalid IPv4 address: "${ip}". Expected format: 1.2.3.4.`,
+  }, opts);
 }

package/src/commands/password.js

@@ -51,14 +51,28 @@ function readStdin() {
     } else {
       // Piped mode: read all data from stdin
       let data = '';
+      let resolved = false;
       process.stdin.setEncoding('utf8');
       process.stdin.on('data', (chunk) => { data += chunk; });
-      process.stdin.on('end', () => resolve(data.trim()));
-      process.stdin.on('error', reject);
+      process.stdin.on('end', () => {
+        if (!resolved) {
+          resolved = true;
+          resolve(data.trim());
+        }
+      });
+      process.stdin.on('error', (err) => {
+        if (!resolved) {
+          resolved = true;
+          reject(err);
+        }
+      });
       setTimeout(() => {
-        process.stdin.destroy();
-        if (data) resolve(data.trim());
-        else reject(new Error('Stdin timeout — no input received'));
+        if (!resolved) {
+          resolved = true;
+          process.stdin.destroy();
+          if (data) resolve(data.trim());
+          else reject(new Error('Stdin timeout — no input received'));
+        }
       }, 10000);
     }
   });

package/src/commands/scan.js

@@ -13,6 +13,12 @@ export async function scanCommand(opts) {
   const params = {};
 
   if (opts.password) {
+    // Shell history warning (C2: scan --password leak)
+    if (!opts.quiet && process.stderr.isTTY) {
+      process.stderr.write(
+        chalk.yellow('⚠  Password may appear in shell history. Use `shieldapi password --stdin` for sensitive passwords.\n')
+      );
+    }
     params.password_hash = createHash('sha1').update(opts.password).digest('hex').toUpperCase();
   }
   if (opts.email) params.email = opts.email;

package/src/commands/scanSkill.js

@@ -0,0 +1,157 @@
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, extname, basename } from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { apiRequestPost } from '../lib/api.js';
+import { resolveWallet } from '../lib/wallet.js';
+import { riskBadge, sectionHeader, kvLine, formatNumber } from '../lib/formatter.js';
+import { EXIT } from '../lib/exit.js';
+
+const SCANNABLE_EXTENSIONS = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.sh', '.bash',
+  '.md', '.markdown', '.json', '.yml', '.yaml', '.toml', '.env',
+  '.bat', '.ps1', '.rb', '.go', '.rs', '.java',
+]);
+
+function loadSkillFiles(path) {
+  const files = [];
+  const stat = statSync(path);
+
+  if (stat.isFile()) {
+    const content = readFileSync(path, 'utf-8');
+    return [{ name: basename(path), content }];
+  }
+
+  if (stat.isDirectory()) {
+    const entries = readdirSync(path, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const fullPath = join(path, entry.name);
+      if (entry.isFile()) {
+        const ext = extname(entry.name).toLowerCase();
+        if (SCANNABLE_EXTENSIONS.has(ext) || entry.name === 'Dockerfile' || entry.name === 'Makefile') {
+          try {
+            const content = readFileSync(fullPath, 'utf-8');
+            if (content.length <= 100 * 1024) { // 100KB per file max
+              files.push({ name: entry.name, content });
+            }
+          } catch { /* skip unreadable files */ }
+        }
+      }
+    }
+  }
+
+  return files;
+}
+
+export async function scanSkillCommand(target, opts) {
+  const spinner = opts.quiet ? null : ora({ text: `Scanning skill: ${target || 'stdin'}`, stream: process.stderr }).start();
+
+  try {
+    let body = {};
+
+    if (target && existsSync(target)) {
+      // Local file or directory
+      const files = loadSkillFiles(target);
+      if (files.length === 0) {
+        if (spinner) spinner.fail('No scannable files found');
+        process.exitCode = EXIT.USAGE;
+        return;
+      }
+
+      // If there's a SKILL.md, use it as the skill field
+      const skillMd = files.find(f => f.name.toLowerCase() === 'skill.md');
+      if (skillMd) {
+        body.skill = skillMd.content;
+      }
+      body.files = files;
+      if (spinner) spinner.text = `Scanning ${files.length} files from ${target}`;
+    } else if (target) {
+      // Assume it's raw skill content or a skill name
+      body.skill = target;
+    } else {
+      if (spinner) spinner.fail('No target specified');
+      process.exitCode = EXIT.USAGE;
+      return;
+    }
+
+    const wallet = opts.demo ? null : resolveWallet(opts);
+    const data = await apiRequestPost('scan-skill', body, {
+      demo: opts.demo,
+      wallet,
+    });
+
+    if (spinner) spinner.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatScanSkill(data);
+    }
+
+    // Exit code: 0=clean, 1=findings, 2=critical
+    if (data.riskLevel === 'CLEAN') {
+      process.exitCode = 0;
+    } else if (data.riskLevel === 'CRITICAL') {
+      process.exitCode = 2;
+    } else {
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    if (spinner) spinner.fail(err.message);
+    process.exitCode = EXIT.API_ERROR;
+  }
+}
+
+function formatScanSkill(data) {
+  console.log();
+  console.log(chalk.bold.underline('🛡️  Skill Safety Scan Results'));
+  console.log();
+
+  // Risk badge
+  const badge = riskBadge(data.riskLevel?.toLowerCase(), data.riskScore);
+  console.log(`   Risk Level: ${badge}`);
+  console.log(`   Files Analyzed: ${data.filesAnalyzed || '?'}`);
+  console.log(`   Patterns Checked: ${formatNumber(data.totalPatterns || 0)}`);
+  console.log(`   Scan Duration: ${data.scanDuration}ms`);
+
+  if (data.findings?.length > 0) {
+    sectionHeader(`Findings (${data.findings.length})`);
+    console.log();
+
+    const bySeverity = { CRITICAL: [], HIGH: [], MEDIUM: [], LOW: [] };
+    for (const f of data.findings) {
+      (bySeverity[f.severity] || bySeverity.LOW).push(f);
+    }
+
+    for (const [sev, findings] of Object.entries(bySeverity)) {
+      if (findings.length === 0) continue;
+      const color = sev === 'CRITICAL' ? chalk.red.bold
+        : sev === 'HIGH' ? chalk.red
+        : sev === 'MEDIUM' ? chalk.yellow
+        : chalk.gray;
+      
+      for (const f of findings) {
+        console.log(`   ${color(`[${sev}]`)} ${f.description}`);
+        if (f.location) console.log(`      📍 ${chalk.gray(f.location)}`);
+        if (f.category) console.log(`      📂 ${chalk.gray(f.category)}`);
+      }
+    }
+  } else {
+    console.log();
+    console.log(chalk.green.bold('   ✅ No security issues detected'));
+  }
+
+  // Summary
+  if (data.summary) {
+    console.log();
+    console.log(`   ${chalk.gray(data.summary)}`);
+  }
+
+  if (data.demo) {
+    console.log();
+    console.log(chalk.yellow('   ⚠️  Demo mode — results limited. Pay with x402 for full scan.'));
+  }
+
+  console.log();
+}

package/src/commands/url.js

@@ -1,35 +1,18 @@
-import ora from 'ora';
-import chalk from 'chalk';
-import { apiRequest } from '../lib/api.js';
-import { resolveWallet } from '../lib/wallet.js';
+import { runCommand } from '../lib/command.js';
 import { formatUrl } from '../lib/formatter.js';
-import { exitCodeFromResult, exitCodeFromError } from '../lib/exit.js';
+import { isValidUrl } from '../lib/validator.js';
 
 /**
  * Check URL safety.
  */
 export async function urlCommand(url, opts) {
-  const spinner = opts.quiet ? null : ora({ text: `Checking URL: ${url}`, stream: process.stderr }).start();
-
-  try {
-    const wallet = opts.demo ? null : resolveWallet(opts);
-
-    const data = await apiRequest('check-url', { url }, {
-      demo: opts.demo,
-      wallet,
-    });
-
-    spinner?.stop();
-
-    if (opts.json) {
-      console.log(JSON.stringify(data, null, 2));
-    } else {
-      formatUrl(data);
-    }
-
-    process.exitCode = exitCodeFromResult(data);
-  } catch (err) {
-    spinner?.fail(err.message);
-    process.exitCode = exitCodeFromError(err);
-  }
+  await runCommand({
+    endpoint: 'check-url',
+    paramName: 'url',
+    paramValue: url,
+    formatFn: formatUrl,
+    spinnerText: `Checking URL: ${url}`,
+    validateFn: isValidUrl,
+    validateMsg: `Invalid URL: "${url}". Expected format: https://example.com.`,
+  }, opts);
 }

package/src/index.js

@@ -1,3 +1,6 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { Command } from 'commander';
 import { passwordCommand } from './commands/password.js';
 import { emailCommand } from './commands/email.js';
@@ -7,6 +10,11 @@ import { urlCommand } from './commands/url.js';
 import { scanCommand } from './commands/scan.js';
 import { healthCommand } from './commands/health.js';
 import { hashCommand } from './commands/hash.js';
+import { scanSkillCommand } from './commands/scanSkill.js';
+import { checkPromptCommand } from './commands/checkPrompt.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
 
 export function run(argv) {
   const program = new Command();
@@ -14,11 +22,10 @@ export function run(argv) {
   program
     .name('shieldapi')
     .description('🛡️  ShieldAPI CLI — Security intelligence from your terminal. Pay-per-request with USDC.')
-    .version('1.3.1')
+    .version(pkg.version)
     .option('--wallet <key>', 'Private key for x402 payments (or set SHIELDAPI_WALLET_KEY)')
     .option('--json', 'Output raw JSON instead of formatted output')
     .option('--no-color', 'Disable colors')
-    .option('-y, --yes', 'Skip payment confirmation prompts')
     .option('-q, --quiet', 'Suppress non-essential output (spinners, warnings)');
 
   program
@@ -105,5 +112,28 @@ export function run(argv) {
       hashCommand(password, { ...globalOpts, ...cmdOpts });
     });
 
+  program
+    .command('scan-skill')
+    .description('Scan an AI skill or plugin for security issues (8 risk categories)')
+    .argument('[target]', 'Path to SKILL.md, directory, or raw skill content')
+    .option('--demo', 'Use demo mode (free, no wallet needed)')
+    .action((target, cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      scanSkillCommand(target, { ...globalOpts, ...cmdOpts });
+    });
+
+  program
+    .command('check-prompt')
+    .description('Check text for prompt injection patterns (200+ detectors)')
+    .argument('[prompt]', 'Text to analyze (or use --stdin)')
+    .option('--demo', 'Use demo mode (free, no wallet needed)')
+    .option('--stdin', 'Read prompt from stdin')
+    .option('--context <context>', 'Context hint: user-input, skill-prompt, system-prompt', 'user-input')
+    .action((prompt, cmdOpts, cmd) => {
+      const globalOpts = cmd.parent.opts();
+      checkPromptCommand(prompt, { ...globalOpts, ...cmdOpts });
+    });
+
   program.parse(argv);
+
 }

package/src/lib/api.js

@@ -73,3 +73,50 @@ export class ApiError extends Error {
     this.status = status;
   }
 }
+
+/**
+ * POST request for Phase 2 endpoints (scan-skill, check-prompt).
+ * Uses @x402/fetch for paid requests, plain fetch for demo.
+ */
+export async function apiRequestPost(endpoint, body = {}, { demo = false, wallet = null } = {}) {
+  const query = demo ? '?demo=true' : '';
+  const url = `${BASE_URL}/${endpoint}${query}`;
+
+  const fetchOptions = {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  };
+
+  if (demo || endpoint === 'health') {
+    const res = await fetch(url, fetchOptions);
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      throw new ApiError(res.status, body || res.statusText);
+    }
+    return res.json();
+  }
+
+  if (!wallet?.signer) {
+    throw new Error(
+      'No wallet configured. Use --wallet <key> or set SHIELDAPI_WALLET_KEY environment variable.'
+    );
+  }
+
+  const { x402Client } = await import('@x402/core/client');
+  const { registerExactEvmScheme } = await import('@x402/evm/exact/client');
+  const { wrapFetchWithPayment } = await import('@x402/fetch');
+
+  const client = new x402Client();
+  registerExactEvmScheme(client, { signer: wallet.signer });
+
+  const paidFetch = wrapFetchWithPayment(fetch, client);
+  const res = await paidFetch(url, fetchOptions);
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new ApiError(res.status, body || res.statusText);
+  }
+
+  return res.json();
+}

package/src/lib/command.js

@@ -0,0 +1,54 @@
+import ora from 'ora';
+import chalk from 'chalk';
+import { apiRequest } from './api.js';
+import { resolveWallet } from './wallet.js';
+import { exitCodeFromResult, exitCodeFromError, EXIT } from './exit.js';
+
+/**
+ * Generic command runner that extracts common boilerplate from
+ * domain, email, ip, and url commands.
+ *
+ * @param {object} config
+ * @param {string} config.endpoint - API endpoint (e.g. 'check-domain')
+ * @param {string} config.paramName - Query parameter name (e.g. 'domain')
+ * @param {string} config.paramValue - The user-supplied value
+ * @param {function} config.formatFn - Formatter function (data, paramValue) => void
+ * @param {string} config.spinnerText - Text for the spinner
+ * @param {function} [config.validateFn] - Optional validator (value) => boolean
+ * @param {string} [config.validateMsg] - Error message if validation fails
+ * @param {object} opts - Merged global + command options
+ */
+export async function runCommand(config, opts) {
+  const { endpoint, paramName, paramValue, formatFn, spinnerText, validateFn, validateMsg } = config;
+
+  // Input validation (S2)
+  if (validateFn && !validateFn(paramValue)) {
+    process.stderr.write(chalk.red(`Error: ${validateMsg || 'Invalid input.'}\n`));
+    process.exitCode = EXIT.USAGE;
+    return;
+  }
+
+  const spinner = opts.quiet ? null : ora({ text: spinnerText, stream: process.stderr }).start();
+
+  try {
+    const wallet = opts.demo ? null : resolveWallet(opts);
+
+    const data = await apiRequest(endpoint, { [paramName]: paramValue }, {
+      demo: opts.demo,
+      wallet,
+    });
+
+    spinner?.stop();
+
+    if (opts.json) {
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      formatFn(data, paramValue);
+    }
+
+    process.exitCode = exitCodeFromResult(data);
+  } catch (err) {
+    spinner?.fail(err.message);
+    process.exitCode = exitCodeFromError(err);
+  }
+}

package/src/lib/validator.js

@@ -0,0 +1,47 @@
+/**
+ * Input validators for fast-fail before API calls.
+ */
+
+/**
+ * Check if string is a plausible email address.
+ * @param {string} s
+ * @returns {boolean}
+ */
+export function isValidEmail(s) {
+  if (!s || typeof s !== 'string') return false;
+  const parts = s.split('@');
+  if (parts.length !== 2) return false;
+  const [local, domain] = parts;
+  return local.length > 0 && domain.includes('.') && domain.length > 2;
+}
+
+/**
+ * Check if string is a valid IPv4 address.
+ * @param {string} s
+ * @returns {boolean}
+ */
+export function isValidIPv4(s) {
+  if (!s || typeof s !== 'string') return false;
+  return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(s);
+}
+
+/**
+ * Check if string is a valid domain (no protocol prefix, contains a dot).
+ * @param {string} s
+ * @returns {boolean}
+ */
+export function isValidDomain(s) {
+  if (!s || typeof s !== 'string') return false;
+  if (s.startsWith('http://') || s.startsWith('https://')) return false;
+  return s.includes('.') && s.length > 3 && !s.includes(' ');
+}
+
+/**
+ * Check if string is a valid URL (starts with http:// or https://).
+ * @param {string} s
+ * @returns {boolean}
+ */
+export function isValidUrl(s) {
+  if (!s || typeof s !== 'string') return false;
+  return s.startsWith('http://') || s.startsWith('https://');
+}

package/src/lib/wallet.js

@@ -31,7 +31,7 @@ export function createWallet(privateKey) {
 
     return { signer, address: account.address };
   } catch (err) {
-    throw new Error(`Invalid private key: ${err.message}`);
+    throw new Error('Invalid private key. Expected 64 hex characters (with or without 0x prefix).');
   }
 }