solguard-cli 0.1.0 → 0.1.1

package/README.md

@@ -1,69 +1,75 @@
-# solguard-cli
-
-Run SolGuard security agents from your terminal.
-
-## Install / run
-
-```bash
-npx solguard-cli
-```
-
-No global install required. Works with `npm install -g solguard-cli` as well.
-
-Requires **Node.js 18+**.
-
-## Modes
-
-| Mode | Description |
-|------|-------------|
-| **Free** | Uses SolGuard API + your 2 signup credits (same as website). Identity: anonymous `cliInstallId` in `~/.solguard/config.json`. |
-| **Premium (Beta)** | Bring your own OpenAI, Anthropic, or Gemini key — runs **locally** on your machine. Key never sent to SolGuard. Six services supported. |
-
-## Config
-
-`~/.solguard/config.json` (mode `600` on Unix):
-
-```json
-{
-  "cliInstallId": "<uuid>",
-  "token": "<jwt>",
-  "baseUrl": "https://www.solguard.space/api",
-  "savedKeys": {}
-}
-```
-
-## Premium local (Beta)
-
-- **BYOK LLM required:** Cyber Security Consultant, Solana Token Verification
-- **Local only (no API key):** Wallet Verification, dApp Frontend Scan, OpenClaw Audit, Smart Contract Audit
-- **On-chain agents:** set `HELIUS_API_KEY` in your environment
-
-## Local development
-
-1. Start the API: `npm run dev` (from repo root)
-2. Run the CLI — it auto-detects `http://localhost:3000/api` when the dev server is up
-
-Or set explicitly:
-
-```powershell
-$env:SOLGUARD_API = "http://localhost:3000/api"
-node bin/solguard-cli.js
-```
-
-## Publish (maintainers)
-
-```bash
-npm login
-cd packages/solguard-cli
-npm publish --access public
-```
-
-**Do not publish without explicit approval.**
-
-## QA
-
-```bash
-node scripts/qa-cli-auth.mjs http://localhost:3000/api
-node scripts/qa-cli-local-premium.mjs
-```
-
+# solguard-cli
+
+Run SolGuard security agents from your terminal.
+
+## Install / run
+
+```bash
+npx solguard-cli
+```
+
+No global install required. Works with `npm install -g solguard-cli` as well.
+
+Requires **Node.js 18+**.
+
+## Modes
+
+| Mode | Description |
+|------|-------------|
+| **Local (recommended)** | Runs on your machine. No SolGuard free credits. Bring your own OpenAI / Anthropic / Gemini key for AI agents. |
+| **Free** | Optional — uses SolGuard API + signup credits (same as website). |
+
+Local mode does **not** call the SolGuard backend for execution. Keys stay on your machine (`~/.solguard/config.json`).
+
+## Services (local)
+
+- Cyber Security Consultant (BYOK LLM)
+- Solana Token Verification (BYOK LLM + Helius for on-chain)
+- Smart Contract Security Audit (Helius)
+- Wallet Verification (Helius)
+- Web3 dApp Frontend Verification
+- OpenClaw AI Agent Verification
+
+## Config
+
+`~/.solguard/config.json` (mode `600` on Unix):
+
+```json
+{
+  "cliInstallId": "<uuid>",
+  "token": "<jwt>",
+  "baseUrl": "https://www.solguard.space/api",
+  "savedKeys": {}
+}
+```
+
+## Local tips
+
+- **BYOK LLM:** Cyber Security Consultant, Solana Token Verification
+- **On-chain agents:** set `HELIUS_API_KEY` in your environment
+- Free mode only: needs network access to `https://www.solguard.space/api`
+
+## Local development
+
+```powershell
+$env:SOLGUARD_API = "http://localhost:3000/api"
+node bin/solguard-cli.js
+```
+
+Local **premium** mode works without the API. Free mode needs `npm run dev`.
+
+## Publish (maintainers)
+
+```bash
+npm login
+cd packages/solguard-cli
+npm publish --access public
+```
+
+Bump `version` in `package.json` before republishing.
+
+## QA
+
+```bash
+node scripts/qa-cli-local-premium.mjs
+```

package/bin/solguard-cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import { runWizard } from "../src/wizard.js";
 
 /** Strip common API key patterns from error output. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "solguard-cli",
-  "version": "0.1.0",
-  "description": "Run SolGuard security agents from your terminal — free credits via SolGuard API or premium local BYOK",
+  "version": "0.1.1",
+  "description": "Run SolGuard security agents locally from your terminal (BYOK) — optional free SolGuard credits",
   "type": "module",
   "bin": {
     "solguard-cli": "./bin/solguard-cli.js"

package/src/config.js

@@ -6,6 +6,10 @@ import crypto from "crypto";
 export const DEFAULT_BASE_URL = "https://www.solguard.space/api";
 export const LOCAL_DEV_URL = "http://localhost:3000/api";
 
+function isLocalUrl(url) {
+  return /localhost|127\.0\.0\.1/i.test(url || "");
+}
+
 /** Resolve API base: --api flag > SOLGUARD_API env > config > local dev probe > production. */
 export async function resolveBaseUrl(config, cliArgs = process.argv.slice(2)) {
   const flagIdx = cliArgs.findIndex((a) => a === "--api" || a === "-a");
@@ -15,13 +19,16 @@ export async function resolveBaseUrl(config, cliArgs = process.argv.slice(2)) {
   if (process.env.SOLGUARD_API) {
     return process.env.SOLGUARD_API.replace(/\/$/, "");
   }
+  // Prefer a saved non-default URL, but never stick on dead localhost.
   if (config?.baseUrl && config.baseUrl !== DEFAULT_BASE_URL) {
-    return config.baseUrl.replace(/\/$/, "");
+    const saved = config.baseUrl.replace(/\/$/, "");
+    if (!isLocalUrl(saved)) return saved;
+    if (await probeApi(saved)) return saved;
   }
   if (await probeApi(LOCAL_DEV_URL)) {
     return LOCAL_DEV_URL;
   }
-  return (config?.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+  return DEFAULT_BASE_URL;
 }
 
 async function probeApi(baseUrl) {

package/src/localCatalog.js

@@ -0,0 +1,103 @@
+/**
+ * Built-in catalog for premium local runs — no SolGuard API required.
+ * Kept in sync with lib/solguard/services.js + formSchemas.js for the 6 local agents.
+ */
+
+export const LOCAL_SERVICES = [
+  {
+    id: "cyber-consultant",
+    name: "Cyber Security Consultant",
+    category: "Advisory",
+    primaryAgentId: "ai-consultant",
+    inputs: [
+      {
+        key: "query",
+        type: "text",
+        label: "Your Question",
+        placeholder: "e.g. How do honeypot tokens lock liquidity?",
+        example: "What is the most common Solana token rug-pull pattern in 2025?",
+        multiline: true,
+      },
+    ],
+  },
+  {
+    id: "solana-token-verification",
+    name: "Solana Token Verification",
+    category: "Token",
+    primaryAgentId: "solana-token-verification",
+    inputs: [
+      {
+        key: "tokenAddress",
+        label: "Token Mint Address",
+        placeholder: "e.g. DezXAZ8z7Pnr...",
+        example: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
+      },
+    ],
+  },
+  {
+    id: "smart-contract-audit",
+    name: "Smart Contract Security Audit",
+    category: "Contract",
+    primaryAgentId: "contract-security",
+    inputs: [
+      {
+        key: "tokenAddress",
+        label: "Token Mint Address",
+        placeholder: "e.g. DezXAZ8z7Pnr...",
+        example: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
+      },
+    ],
+  },
+  {
+    id: "wallet-verification",
+    name: "Wallet Verification",
+    category: "Wallet",
+    primaryAgentId: "wallet-verification",
+    inputs: [
+      {
+        key: "walletAddress",
+        label: "Wallet Address",
+        placeholder: "Solana wallet pubkey",
+        example: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
+      },
+    ],
+  },
+  {
+    id: "dapp-frontend-verification",
+    name: "Web3 dApp Frontend Verification",
+    category: "Web",
+    primaryAgentId: "website-security",
+    inputs: [
+      {
+        key: "url",
+        type: "url",
+        label: "Website URL",
+        placeholder: "https://example.com",
+        example: "https://solana.com",
+      },
+    ],
+  },
+  {
+    id: "openclaw-ai-agent-verification",
+    name: "OpenClaw AI Agent Verification",
+    category: "AI Agent",
+    primaryAgentId: "openclaw-ai-agent-verification",
+    inputs: [
+      {
+        key: "config",
+        type: "json",
+        label: "Agent Config (JSON)",
+        placeholder: '{"name":"support-agent","gateway":{"auth":"none"}}',
+        example: '{"name":"support-agent","gateway":{"auth":"none"}}',
+      },
+    ],
+  },
+];
+
+export function listLocalServices() {
+  return LOCAL_SERVICES;
+}
+
+export function getLocalService(serviceId) {
+  return LOCAL_SERVICES.find((s) => s.id === serviceId) || null;
+}

package/src/wizard.js

@@ -1,483 +1,225 @@
 import * as p from "@clack/prompts";
-
 import fs from "fs";
 
 import { ensureConfig, updateConfig, saveConfig, resolveBaseUrl } from "./config.js";
-
 import {
-
   ensureAuth,
-
   fetchConfig,
-
-  fetchServices,
-
-  fetchServiceDetail,
-
   fetchMe,
-
   runAgentFree,
-
 } from "./api.js";
-
-import { formatReport, printReport, reportFilename } from "./output.js";
-
+import { printReport, reportFilename } from "./output.js";
 import {
-
   listByokProviders,
-
   runAgentLocalPremium,
-
-  canRunLocalPremium,
-
   agentUsesByokLlm,
-
   localPremiumRequiresHelius,
-
 } from "./premium.js";
-
-
+import { listLocalServices } from "./localCatalog.js";
 
 function isCancel(v) {
-
   if (p.isCancel(v)) {
-
     p.cancel("Cancelled.");
-
     process.exit(0);
-
   }
-
   return v;
-
 }
 
-
-
 async function promptInputs(fields) {
-
   const inputs = {};
-
   for (const field of fields) {
-
     const opts = {
-
       message: field.label || field.key,
-
       placeholder: field.placeholder || field.example || "",
-
     };
-
     if (field.type === "json") {
-
       opts.message += " (paste JSON)";
-
     }
-
-    if (field.multiline || field.type === "text" || field.type === "json") {
-
-      let val = isCancel(await p.text({ ...opts, defaultValue: "" }));
-
-      while (!val?.trim()) {
-
-        p.log.warn("Please enter a value.");
-
-        val = isCancel(await p.text({ ...opts, defaultValue: "" }));
-
-      }
-
-      inputs[field.key] = val.trim();
-
-    } else {
-
-      let val = isCancel(await p.text({ ...opts, defaultValue: "" }));
-
-      while (!val?.trim()) {
-
-        p.log.warn("Please enter a value.");
-
-        val = isCancel(await p.text({ ...opts, defaultValue: "" }));
-
-      }
-
-      inputs[field.key] = val.trim();
-
+    let val = isCancel(await p.text({ ...opts, defaultValue: "" }));
+    while (!val?.trim()) {
+      p.log.warn("Please enter a value.");
+      val = isCancel(await p.text({ ...opts, defaultValue: "" }));
     }
-
+    inputs[field.key] = val.trim();
   }
-
   return inputs;
-
 }
 
-
-
 function showReport(report, opts) {
-
   p.log.step("Report");
-
   printReport(report, opts);
-
 }
 
-
-
 async function promptSaveReport(report) {
-
   const save = isCancel(
-
     await p.confirm({ message: "Save result to file?", initialValue: false })
-
   );
-
   if (!save) return;
-
   const name = reportFilename();
-
   fs.writeFileSync(name, JSON.stringify(report, null, 2), "utf8");
-
   p.log.success(`Saved to ${name}`);
-
 }
 
-
-
 async function promptByokCredentials(config) {
-
   const providers = listByokProviders();
-
   const providerId = isCancel(
-
     await p.select({
-
       message: "LLM provider",
-
       options: providers.map((pr) => ({ value: pr.id, label: pr.label })),
-
     })
-
   );
 
-
-
   let apiKey = config.savedKeys?.[providerId];
-
   if (apiKey) {
-
     const reuse = isCancel(
-
       await p.confirm({
-
         message: `Use saved ${providerId} key from ~/.solguard/config.json?`,
-
         initialValue: true,
-
       })
-
     );
-
     if (!reuse) apiKey = null;
-
   }
 
-
-
   if (!apiKey) {
-
     apiKey = isCancel(await p.password({ message: "API key (input hidden)" }));
-
     const saveKey = isCancel(
-
       await p.confirm({ message: "Save this key for future runs?", initialValue: false })
-
     );
-
     if (saveKey) {
-
       config.savedKeys = { ...config.savedKeys, [providerId]: apiKey };
-
       saveConfig(config);
-
       p.log.info("Key saved to ~/.solguard/config.json (mode 600)");
-
     }
-
   }
 
-
-
   return { providerId, apiKey };
-
 }
 
-
-
 function premiumModeLabel(agentId) {
-
   if (agentUsesByokLlm(agentId)) {
-
-    return "Premium (Beta) — your own API key (runs locally, key never sent to SolGuard)";
-
+    return "Local (recommended) — your own API key, no SolGuard credits";
   }
-
-  return "Premium (Beta) — run locally (no SolGuard backend)";
-
+  return "Local (recommended) — runs on your machine, no SolGuard credits";
 }
 
-
-
 export async function runWizard() {
-
   p.intro("SolGuard CLI · Beta");
-
-
+  p.log.info("Default: run locally on your machine. SolGuard free credits are optional.");
 
   let config = ensureConfig();
-
-  config.baseUrl = await resolveBaseUrl(config);
-
-  updateConfig({ baseUrl: config.baseUrl });
-
-
-
-  config = { ...config, ...(await ensureAuth(config)) };
-
-  updateConfig({ token: config.token });
-
-
-
-  if (config.baseUrl.includes("localhost")) {
-
-    p.log.info(`Using local API: ${config.baseUrl}`);
-
-  }
-
-
-
-  const remoteConfig = await fetchConfig(config.baseUrl);
-
-  const services = await fetchServices(config.baseUrl);
-
-
-
-  if (!services.length) {
-
-    p.log.error("No services returned from API.");
-
-    process.exit(1);
-
-  }
-
-
+  const services = listLocalServices();
 
   const serviceId = isCancel(
-
     await p.select({
-
       message: "Select a service",
-
       options: services.map((s) => ({
-
         value: s.id,
-
         label: s.name,
-
         hint: s.category,
-
       })),
-
     })
-
   );
 
-
-
   const service = services.find((s) => s.id === serviceId);
-
-  const detail = await fetchServiceDetail(config.baseUrl, serviceId);
-
   const agentId = service.primaryAgentId;
+  const inputFields = service.inputs || [];
 
-  const inputFields = detail?.agent?.inputs || [];
-
-  const supportsLocalPremium = canRunLocalPremium(agentId);
-
-
-
-  let mode = "free";
-
-  if (supportsLocalPremium) {
-
-    mode = isCancel(
-
-      await p.select({
-
-        message: "Run mode",
-
-        options: [
-
-          {
-
-            value: "free",
-
-            label: "Free — SolGuard credits (server-side execution)",
-
-            hint: `${config.credits ?? "?"} credits remaining`,
-
-          },
-
-          {
-
-            value: "premium",
-
-            label: premiumModeLabel(agentId),
-
-          },
-
-        ],
-
-      })
-
-    );
-
-  } else {
-
-    p.log.info("Premium local mode is not available for this service (requires SolGuard backend). Using free credits.");
-
-  }
-
-
+  const mode = isCancel(
+    await p.select({
+      message: "Run mode",
+      initialValue: "premium",
+      options: [
+        {
+          value: "premium",
+          label: premiumModeLabel(agentId),
+          hint: agentUsesByokLlm(agentId) ? "BYOK" : "offline rules / RPC",
+        },
+        {
+          value: "free",
+          label: "Free — SolGuard credits (server-side)",
+          hint: "uses your signup credits",
+        },
+      ],
+    })
+  );
 
   const inputs = await promptInputs(inputFields);
-
   const s = p.spinner();
-
-
-
   let report;
 
-
-
-  if (mode === "premium" && supportsLocalPremium) {
-
+  if (mode === "premium") {
     if (localPremiumRequiresHelius(agentId) && !process.env.HELIUS_API_KEY) {
-
       p.log.warn("HELIUS_API_KEY is not set — on-chain scans will fail. Export it before running.");
-
     }
 
-
-
     let providerId = null;
-
     let apiKey = null;
-
     if (agentUsesByokLlm(agentId)) {
-
       ({ providerId, apiKey } = await promptByokCredentials(config));
-
     }
 
-
-
-    s.start(agentUsesByokLlm(agentId)
-
-      ? "Running locally via your provider (no SolGuard backend call)…"
-
-      : "Running locally (no SolGuard backend call)…");
-
+    s.start(
+      agentUsesByokLlm(agentId)
+        ? "Running locally via your provider (no SolGuard credits)…"
+        : "Running locally (no SolGuard credits)…"
+    );
     try {
-
       const result = await runAgentLocalPremium(agentId, inputs, { provider: providerId, apiKey });
-
       if (result?.error) {
-
         s.stop("Failed");
-
         p.log.error(result.error);
-
         process.exit(1);
-
       }
-
       report = { agentId, agentName: service.name, result };
-
       s.stop("Done");
-
-      const modeLabel = providerId ? `Premium (${providerId}, local)` : "Premium (local)";
-
+      const modeLabel = providerId ? `Local (${providerId})` : "Local";
       showReport(report, { mode: modeLabel });
-
     } catch (e) {
-
       s.stop("Failed");
-
       throw e;
-
     }
-
   } else {
+    config.baseUrl = await resolveBaseUrl(config);
+    updateConfig({ baseUrl: config.baseUrl });
+    if (config.baseUrl.includes("localhost")) {
+      p.log.info(`Using local API: ${config.baseUrl}`);
+    }
 
+    config = { ...config, ...(await ensureAuth(config)) };
+    updateConfig({ token: config.token });
+
+    const remoteConfig = await fetchConfig(config.baseUrl);
     const paymentMethod = remoteConfig.testingModeFreeRuns ? "testing" : "credit";
 
     if (paymentMethod === "credit" && (config.credits ?? 0) <= 0) {
-
-      p.log.error("No free credits left. Try premium local mode or connect a wallet on solguard.space.");
-
+      p.log.error(
+        "No free credits left. Choose Local mode (your own API key) or top up on solguard.space."
+      );
       process.exit(1);
-
     }
 
-
-
     s.start("Running via SolGuard API…");
-
     try {
-
       report = await runAgentFree(config.baseUrl, config.token, agentId, inputs, paymentMethod);
-
       s.stop("Done");
-
       const me = await fetchMe(config.baseUrl, config.token);
-
       const creditsRemaining = me.credits;
-
       showReport(report, {
-
         mode: paymentMethod === "testing" ? "Free (testing mode)" : "Free (SolGuard credits)",
-
         creditsRemaining,
-
       });
-
       config.credits = creditsRemaining;
-
       updateConfig({ token: config.token, credits: creditsRemaining });
-
     } catch (e) {
-
       s.stop("Failed");
-
       if (e.status === 402) {
-
-        p.log.error("Payment required — no credits left.");
-
+        p.log.error("Payment required — no credits left. Use Local mode instead.");
         process.exit(1);
-
       }
-
       throw e;
-
     }
-
   }
 
-
-
   await promptSaveReport(report);
-
   p.outro("Done");
-
 }
-
-