solguard-cli 0.1.0

package/lib/solguard/scanEngine.js

@@ -0,0 +1,283 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import { normalizeRiskScore } from "./reportBuilder.js";
+
+const HELIUS_KEY = process.env.HELIUS_API_KEY;
+const RPC_URL = `https://mainnet.helius-rpc.com/?api-key=${HELIUS_KEY}`;
+
+let _conn = null;
+function getConnection() {
+  if (!_conn) _conn = new Connection(RPC_URL, "confirmed");
+  return _conn;
+}
+
+export function isValidSolanaAddress(address) {
+  return typeof address === "string" && /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(address);
+}
+
+async function fetchAsset(mintAddress) {
+  try {
+    const res = await fetch(RPC_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: "solguard",
+        method: "getAsset",
+        params: { id: mintAddress },
+      }),
+    });
+    const j = await res.json();
+    return j?.result || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+async function checkAuthorities(connection, mintPubkey) {
+  const info = await connection.getParsedAccountInfo(mintPubkey);
+  const parsed = info?.value?.data?.parsed;
+  if (!parsed || parsed.type !== "mint") {
+    throw new Error("Address is not a valid SPL token mint");
+  }
+  const inf = parsed.info;
+  const mintAuth = inf.mintAuthority || null;
+  const freezeAuth = inf.freezeAuthority || null;
+  const decimals = inf.decimals;
+  const supplyRaw = inf.supply;
+
+  const riskFlags = [];
+  if (mintAuth) riskFlags.push("Mint authority not revoked — developer can mint unlimited new tokens.");
+  if (freezeAuth) riskFlags.push("Freeze authority active — developer can freeze any holder wallet.");
+
+  return {
+    mintAuthority: mintAuth ? "ACTIVE" : "REVOKED",
+    freezeAuthority: freezeAuth ? "ACTIVE" : "REVOKED",
+    mintAuthorityAddress: mintAuth,
+    freezeAuthorityAddress: freezeAuth,
+    decimals,
+    supplyRaw,
+    riskFlags,
+  };
+}
+
+async function fetchHolderConcentration(connection, mintPubkey, supplyBig) {
+  const MAX_ATTEMPTS = 5;
+  let lastError = null;
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      const largest = await connection.getTokenLargestAccounts(mintPubkey);
+      const accounts = largest?.value || [];
+      if (accounts.length > 0 && supplyBig > 0n) {
+        const topRaw = BigInt(accounts[0]?.amount || "0");
+        let sum10 = 0n;
+        for (const a of accounts.slice(0, 10)) sum10 += BigInt(a.amount || "0");
+        const topHolderPercent = Number((topRaw * 10000n) / supplyBig) / 100;
+        const top10Percent = Number((sum10 * 10000n) / supplyBig) / 100;
+        if (attempt > 1) {
+          console.log(`[scanEngine] getTokenLargestAccounts succeeded on attempt ${attempt} for ${mintPubkey.toBase58()}`);
+        }
+        return {
+          topHolderPercent,
+          top10Percent,
+          holderDataAvailable: true,
+          holderDataError: null,
+          topAccountsSampled: accounts.length,
+        };
+      }
+      lastError = "getTokenLargestAccounts returned no accounts";
+    } catch (e) {
+      lastError = e?.message || "getTokenLargestAccounts failed";
+      console.warn(`[scanEngine] getTokenLargestAccounts attempt ${attempt}/${MAX_ATTEMPTS} failed for ${mintPubkey.toBase58()}: ${lastError}`);
+    }
+    if (attempt < MAX_ATTEMPTS) {
+      await new Promise((r) => setTimeout(r, 800 * attempt));
+    }
+  }
+
+  console.error(`[scanEngine] Holder concentration unavailable for ${mintPubkey.toBase58()}: ${lastError}`);
+  return {
+    topHolderPercent: null,
+    top10Percent: null,
+    holderDataAvailable: false,
+    holderDataError: lastError,
+    topAccountsSampled: 0,
+  };
+}
+
+async function detectBundle(connection, mintPubkey) {
+  const riskFlags = [];
+  let suspiciousWalletCount = 0;
+  let earlySlotClustering = false;
+
+  let supplyBig = 0n;
+  let totalSupply = 0;
+  try {
+    const supplyRes = await connection.getTokenSupply(mintPubkey);
+    supplyBig = BigInt(supplyRes?.value?.amount || "0");
+    totalSupply = Number(supplyRes?.value?.uiAmountString || supplyRes?.value?.uiAmount || 0);
+  } catch (e) {
+    console.warn(`[scanEngine] getTokenSupply failed for ${mintPubkey.toBase58()}:`, e?.message);
+  }
+
+  const holder = supplyBig > 0n
+    ? await fetchHolderConcentration(connection, mintPubkey, supplyBig)
+    : {
+        topHolderPercent: null,
+        top10Percent: null,
+        holderDataAvailable: false,
+        holderDataError: supplyBig > 0n ? null : "Token supply unavailable",
+        topAccountsSampled: 0,
+      };
+
+  const topHolderPercent = holder.topHolderPercent;
+  const top10Percent = holder.top10Percent;
+
+  try {
+    const sigs = await connection.getSignaturesForAddress(mintPubkey, { limit: 200 });
+    const bySlot = {};
+    for (const s of sigs) {
+      bySlot[s.slot] = (bySlot[s.slot] || 0) + 1;
+    }
+    const clusteredSlots = Object.entries(bySlot).filter(([, n]) => n >= 5);
+    if (clusteredSlots.length >= 1) {
+      earlySlotClustering = true;
+      suspiciousWalletCount = clusteredSlots.reduce((s, [, n]) => s + n, 0);
+    }
+  } catch (e) {
+    console.warn(`[scanEngine] signature clustering failed for ${mintPubkey.toBase58()}:`, e?.message);
+  }
+
+  const supplyPercent = holder.holderDataAvailable ? top10Percent : null;
+
+  if (holder.holderDataAvailable && topHolderPercent > 20) {
+    riskFlags.push(`Top wallet holds ${topHolderPercent.toFixed(1)}% of total supply.`);
+  }
+  if (holder.holderDataAvailable && top10Percent > 50) {
+    riskFlags.push(`Top 10 wallets control ${top10Percent.toFixed(1)}% of supply — high concentration risk.`);
+  }
+  if (!holder.holderDataAvailable) {
+    riskFlags.push(`Holder concentration unverified — ${holder.holderDataError || "RPC could not return largest accounts"}.`);
+  }
+  if (earlySlotClustering) riskFlags.push("Suspicious transaction clustering detected — possible coordinated bundle/snipe.");
+
+  return {
+    detected: earlySlotClustering || (holder.holderDataAvailable && top10Percent > 50),
+    walletCount: suspiciousWalletCount,
+    supplyPercent,
+    topHolderPercent,
+    top10Percent,
+    holderDataAvailable: holder.holderDataAvailable,
+    holderDataError: holder.holderDataError,
+    topAccountsSampled: holder.topAccountsSampled,
+    earlySlotClustering,
+    riskFlags,
+    totalSupply,
+  };
+}
+
+async function verifyLiquidityLock(connection, mintAddress, asset) {
+  const riskFlags = [];
+  // MVP heuristic: rely on Helius asset data if available
+  // Real LP burn checking requires Raydium pool lookup which is complex; gracefully fallback
+  let poolFound = false;
+  let lpBurned = false;
+  let burnPercent = 0;
+  let liquidityUsd = null;
+
+  // Try DexScreener as fallback for liquidity info
+  try {
+    const res = await fetch(`https://api.dexscreener.com/latest/dex/tokens/${mintAddress}`, { cache: "no-store" });
+    if (res.ok) {
+      const j = await res.json();
+      const pairs = j?.pairs || [];
+      if (pairs.length > 0) {
+        poolFound = true;
+        // pick most liquid pair
+        pairs.sort((a, b) => (b.liquidity?.usd || 0) - (a.liquidity?.usd || 0));
+        liquidityUsd = pairs[0]?.liquidity?.usd || 0;
+        if (liquidityUsd < 10000) {
+          riskFlags.push(`Low liquidity pool (~$${Math.round(liquidityUsd).toLocaleString()}) — high slippage and exit risk.`);
+        }
+      }
+    }
+  } catch (e) {}
+
+  if (!poolFound) {
+    riskFlags.push("No active DEX liquidity pool detected for this token.");
+  } else {
+    // We cannot easily check LP burn on-chain in MVP; flag as unverified rather than false alarm
+    riskFlags.push("LP burn status unverified — manually check Raydium/Orca pool for burned LP tokens.");
+  }
+
+  return { poolFound, lpBurned, burnPercent, liquidityUsd, riskFlags };
+}
+
+function calculateRiskScore(authority, bundle, liquidity) {
+  let score = 0;
+  if (authority.freezeAuthority === "ACTIVE") score += 30;
+  if (authority.mintAuthority === "ACTIVE") score += 20;
+  if (bundle.detected) score += 25;
+  if (bundle.holderDataAvailable) {
+    if (bundle.topHolderPercent > 20) score += 10;
+    if (bundle.topHolderPercent > 50) score += 15;
+    if (bundle.top10Percent > 70) score += 10;
+  }
+  if (liquidity.poolFound && liquidity.liquidityUsd !== null && liquidity.liquidityUsd < 10000) score += 15;
+  if (!liquidity.poolFound) score += 5;
+
+  const allFlags = [
+    ...(authority.riskFlags || []),
+    ...(bundle.riskFlags || []),
+    ...(liquidity.riskFlags || []),
+  ];
+  score = Math.min(100, score);
+
+  let level = "LOW";
+  if (score >= 76) level = "CRITICAL";
+  else if (score >= 51) level = "HIGH";
+  else if (score >= 26) level = "MEDIUM";
+
+  return { score, level, factors: allFlags };
+}
+
+export async function runTokenScan(mintAddress) {
+  if (!isValidSolanaAddress(mintAddress)) {
+    throw new Error("Invalid Solana token address format.");
+  }
+  const connection = getConnection();
+  const mintPubkey = new PublicKey(mintAddress);
+
+  const [authority, bundle, asset] = await Promise.all([
+    checkAuthorities(connection, mintPubkey),
+    detectBundle(connection, mintPubkey),
+    fetchAsset(mintAddress),
+  ]);
+  const liquidity = await verifyLiquidityLock(connection, mintAddress, asset);
+
+  const meta = asset?.content?.metadata || {};
+  const tokenInfo = asset?.token_info || {};
+  const metadata = {
+    name: meta.name || tokenInfo.symbol || null,
+    symbol: meta.symbol || tokenInfo.symbol || null,
+    decimals: tokenInfo.decimals ?? authority.decimals,
+    image: asset?.content?.links?.image || asset?.content?.files?.[0]?.uri || null,
+    description: meta.description || null,
+    totalSupply: authority.supplyRaw,
+    mintAddress,
+  };
+
+  const { score, level, factors } = calculateRiskScore(authority, bundle, liquidity);
+
+  return {
+    tokenAddress: mintAddress,
+    metadata,
+    authorityCheck: authority,
+    bundleDetection: bundle,
+    liquidityLock: liquidity,
+    riskScore: normalizeRiskScore(score),
+    riskLevel: level,
+    riskFactors: factors,
+    scannedAt: new Date().toISOString(),
+  };
+}

package/lib/solguard/verdictValidation.js

@@ -0,0 +1,44 @@
+/** Detect model outputs that leak prompts or dump raw scan fields instead of a verdict. */
+export function isInvalidAiVerdict(text) {
+  if (!text || typeof text !== "string") return true;
+  const t = text.trim();
+  if (t.length < 12 || t.length > 420) return true;
+
+  const lower = t.toLowerCase();
+  const leakPhrases = [
+    "we need to produce",
+    "must reference specific",
+    "must be plain english",
+    "must not truncate",
+    "must be a single",
+    "ending with a period",
+    "do not start with",
+    "do not truncate",
+    "do not use asterisks",
+    "no bullet points",
+    "write exactly one",
+    "output rules",
+    "we have data:",
+    "risk factors:",
+  ];
+  if (leakPhrases.some((p) => lower.includes(p))) return true;
+
+  const fieldHits = (lower.match(/risk score:|freeze authority:|mint authority:|bundle detected:|top holder:|top 10 holders:|liquidity (pool|usd):/g) || []).length;
+  if (fieldHits >= 2) return true;
+
+  return false;
+}
+
+/** Trim incomplete trailing fragment; prefer last full sentence. */
+export function ensureCompleteSentence(text) {
+  if (!text) return text;
+  const trimmed = text.trim().replace(/\s+/g, " ");
+  if (/[.!?]["']?$/.test(trimmed)) return trimmed;
+  const punct = Math.max(
+    trimmed.lastIndexOf(". "),
+    trimmed.lastIndexOf("! "),
+    trimmed.lastIndexOf("? ")
+  );
+  if (punct > 20) return trimmed.slice(0, punct + 1).trim();
+  return trimmed.endsWith(".") ? trimmed : `${trimmed}.`;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "solguard-cli",
+  "version": "0.1.0",
+  "description": "Run SolGuard security agents from your terminal — free credits via SolGuard API or premium local BYOK",
+  "type": "module",
+  "bin": {
+    "solguard-cli": "./bin/solguard-cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "prepublishOnly": "node scripts/bundle-lib.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "@solana/web3.js": "^1.98.4",
+    "openai": "^6.45.0"
+  },
+  "keywords": [
+    "solguard",
+    "solana",
+    "security",
+    "cli",
+    "audit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/solguard/solguard"
+  }
+}

package/src/api.js

@@ -0,0 +1,88 @@
+const TIMEOUT_MS = 120_000;
+
+async function request(baseUrl, path, { method = "GET", token, body } = {}) {
+  const url = `${baseUrl.replace(/\/$/, "")}${path}`;
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), TIMEOUT_MS);
+  try {
+    const headers = { "Content-Type": "application/json" };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    let res;
+    try {
+      res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: ctl.signal,
+      });
+    } catch (e) {
+      const hint =
+        baseUrl.includes("localhost")
+          ? "Is the dev server running? Try: npm run dev"
+          : "For local dev: npm run dev, then SOLGUARD_API=http://localhost:3000/api node bin/solguard-cli.js";
+      const err = new Error(`Could not reach SolGuard API at ${baseUrl} (${e?.cause?.code || e?.message || "network error"}). ${hint}`);
+      err.cause = e;
+      throw err;
+    }
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const err = new Error(data?.error || `HTTP ${res.status} from ${url}`);
+      err.status = res.status;
+      err.body = data;
+      throw err;
+    }
+    return data;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function registerCli(baseUrl, cliInstallId) {
+  return request(baseUrl, "/auth/cli", {
+    method: "POST",
+    body: { cliInstallId },
+  });
+}
+
+export async function fetchConfig(baseUrl) {
+  return request(baseUrl, "/config");
+}
+
+export async function fetchServices(baseUrl) {
+  const data = await request(baseUrl, "/services");
+  return data.services || [];
+}
+
+export async function fetchServiceDetail(baseUrl, serviceId) {
+  return request(baseUrl, `/services/${encodeURIComponent(serviceId)}`);
+}
+
+export async function fetchMe(baseUrl, token) {
+  return request(baseUrl, "/me", { token });
+}
+
+export async function runAgentFree(baseUrl, token, agentId, inputs, paymentMethod) {
+  return request(baseUrl, `/agents/${encodeURIComponent(agentId)}/run`, {
+    method: "POST",
+    token,
+    body: { inputs, paymentMethod },
+  });
+}
+
+export async function ensureAuth(config) {
+  if (config.token) {
+    try {
+      const me = await fetchMe(config.baseUrl, config.token);
+      return { ...config, credits: me.credits, userId: me.id };
+    } catch (e) {
+      if (e.status !== 401) throw e;
+    }
+  }
+  const reg = await registerCli(config.baseUrl, config.cliInstallId);
+  return {
+    ...config,
+    token: reg.token,
+    credits: reg.user?.credits ?? 0,
+    userId: reg.user?.id,
+  };
+}

package/src/config.js

@@ -0,0 +1,93 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import crypto from "crypto";
+
+export const DEFAULT_BASE_URL = "https://www.solguard.space/api";
+export const LOCAL_DEV_URL = "http://localhost:3000/api";
+
+/** 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");
+  if (flagIdx >= 0 && cliArgs[flagIdx + 1]) {
+    return cliArgs[flagIdx + 1].replace(/\/$/, "");
+  }
+  if (process.env.SOLGUARD_API) {
+    return process.env.SOLGUARD_API.replace(/\/$/, "");
+  }
+  if (config?.baseUrl && config.baseUrl !== DEFAULT_BASE_URL) {
+    return config.baseUrl.replace(/\/$/, "");
+  }
+  if (await probeApi(LOCAL_DEV_URL)) {
+    return LOCAL_DEV_URL;
+  }
+  return (config?.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+}
+
+async function probeApi(baseUrl) {
+  try {
+    const ctl = new AbortController();
+    const t = setTimeout(() => ctl.abort(), 2000);
+    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/health`, { signal: ctl.signal });
+    clearTimeout(t);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export function configDir() {
+  return path.join(os.homedir(), ".solguard");
+}
+
+export function configPath() {
+  return path.join(configDir(), "config.json");
+}
+
+export function loadConfig() {
+  try {
+    const raw = fs.readFileSync(configPath(), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function saveConfig(config) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = configPath();
+  fs.writeFileSync(file, JSON.stringify(config, null, 2), { mode: 0o600 });
+  try {
+    fs.chmodSync(dir, 0o700);
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Windows may not support chmod — best effort only
+  }
+}
+
+export function ensureConfig() {
+  let config = loadConfig();
+  if (!config) {
+    config = {
+      cliInstallId: crypto.randomUUID(),
+      token: null,
+      baseUrl: DEFAULT_BASE_URL,
+      savedKeys: {},
+    };
+    saveConfig(config);
+  }
+  if (!config.cliInstallId) {
+    config.cliInstallId = crypto.randomUUID();
+    saveConfig(config);
+  }
+  if (!config.baseUrl) config.baseUrl = DEFAULT_BASE_URL;
+  if (!config.savedKeys) config.savedKeys = {};
+  return config;
+}
+
+export function updateConfig(patch) {
+  const config = { ...ensureConfig(), ...patch };
+  saveConfig(config);
+  return config;
+}

package/src/inputs.js

@@ -0,0 +1,34 @@
+/** Input schemas keyed by primary agent id — mirrors lib/solguard/formSchemas.js (no Next.js imports). */
+export const AGENT_INPUTS = {
+  "solana-token-verification": [
+    { key: "tokenAddress", label: "Token Mint Address", placeholder: "e.g. DezXAZ8z7Pnr...", example: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" },
+  ],
+  "contract-security": [
+    { key: "tokenAddress", label: "Token Mint Address", placeholder: "e.g. DezXAZ8z7Pnr...", example: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" },
+  ],
+  "wallet-verification": [
+    { key: "walletAddress", label: "Wallet Address", placeholder: "Solana wallet pubkey", example: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM" },
+  ],
+  "website-security": [
+    { key: "url", label: "Website URL", placeholder: "https://example.com", example: "https://solana.com" },
+  ],
+  "ai-consultant": [
+    { key: "query", label: "Your Question", placeholder: "e.g. How do honeypot tokens lock liquidity?", example: "What is the most common Solana token rug-pull pattern?", multiline: true },
+  ],
+  "openclaw-ai-agent-verification": [
+    { key: "config", label: "Agent Config (JSON)", placeholder: '{"name":"support-agent","gateway":{"auth":"none"}}', example: '{"name":"support-agent","gateway":{"auth":"none"}}', multiline: true },
+  ],
+  "private-data-verification": [
+    { key: "cpdv_data", label: "Data to commit", placeholder: "Paste sensitive text or JSON…", example: "customer-record-8842:status=verified", multiline: true },
+  ],
+  "quantum-cryptography-verification": [
+    { key: "cqcv_data", label: "Data to encrypt", placeholder: "Paste text to encrypt…", example: "confidential-api-key-rotation-schedule", multiline: true },
+  ],
+};
+
+export function getInputsForAgent(agentId) {
+  return AGENT_INPUTS[agentId] || [];
+}
+
+export const CONSULTANT_AGENT_ID = "ai-consultant";
+export const CONSULTANT_SERVICE_ID = "cyber-consultant";

package/src/output.js

@@ -0,0 +1,82 @@
+const LEVEL_COLOR = {
+  LOW: "\x1b[32m",
+  MEDIUM: "\x1b[33m",
+  HIGH: "\x1b[91m",
+  CRITICAL: "\x1b[31m",
+};
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+
+function countElevated(findings = []) {
+  let elevated = 0;
+  for (const f of findings) {
+    const imp = (f.impact || "").toLowerCase();
+    if (imp.includes("+") && imp.includes("risk")) elevated++;
+  }
+  return elevated;
+}
+
+/** Build report text for terminal (also used after clack spinner so output isn't cleared). */
+export function formatReport(result, { creditsRemaining, mode } = {}) {
+  const r = result.result || result;
+  const level = r.riskLevel || "LOW";
+  const score = r.riskScore ?? "—";
+  const lines = [];
+
+  lines.push("━━━ SolGuard Report ━━━");
+  if (mode) lines.push(`Mode: ${mode}`);
+  lines.push(`RISK: ${level} (${score}/100)`);
+  lines.push("");
+
+  const fullResponse = r.rawEvidence?.fullResponse || r.evidence?.fullResponse;
+  const verdict = r.verdict || r.summary || "";
+
+  if (fullResponse) {
+    lines.push("RESPONSE");
+    lines.push(fullResponse.trim());
+    lines.push("");
+  } else if (verdict) {
+    lines.push("VERDICT");
+    lines.push(verdict.trim());
+    lines.push("");
+  }
+
+  const findings = r.keyFindings || [];
+  if (findings.length) {
+    const elevated = countElevated(findings);
+    lines.push(`KEY FINDINGS (${findings.length} checked${elevated ? `, ${elevated} elevated` : ""})`);
+    for (const f of findings.slice(0, 8)) {
+      const flag = (f.impact || "").includes("+") ? "!" : "·";
+      lines.push(`  ${flag} ${f.label}: ${f.value}`);
+    }
+    if (findings.length > 8) lines.push(`  … and ${findings.length - 8} more`);
+    lines.push("");
+  }
+
+  if (r.recommendations?.length) {
+    lines.push("RECOMMENDATIONS");
+    for (const rec of r.recommendations.slice(0, 5)) {
+      lines.push(`  → ${rec}`);
+    }
+    lines.push("");
+  }
+
+  if (creditsRemaining != null) {
+    lines.push(`Credits remaining: ${creditsRemaining}`);
+  }
+
+  return lines.join("\n");
+}
+
+export function printReport(result, opts = {}) {
+  const text = formatReport(result, opts);
+  console.log("");
+  console.log(text);
+  console.log("");
+}
+
+export function reportFilename() {
+  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  return `solguard-report-${ts}.json`;
+}