solidity-argus 0.1.7 → 0.2.0

package/src/hooks/tool-tracking-hook.ts

@@ -1,5 +1,6 @@
-import type { AuditState, FindingSeverity } from "../state/types"
+import type { AuditState, FindingSeverity, FuzzCounterexample, SoloditResult } from "../state/types"
 import type { FindingStore } from "../state/finding-store"
+import { createFindingStore } from "../state/finding-store"
 
 type ToolHookInput = {
   tool: string
@@ -165,16 +166,91 @@ function processContractAnalyzerResult(
   }
 }
 
+function processFuzzResult(
+  parsed: Record<string, unknown>,
+  state: AuditState
+): void {
+  const counterexamples = parsed.counterexamples
+  if (!Array.isArray(counterexamples) || counterexamples.length === 0) return
+
+  const totalRuns =
+    typeof parsed.totalRuns === "number" ? parsed.totalRuns : 0
+
+  state.fuzzCounterexamples ??= []
+
+  for (const raw of counterexamples) {
+    const ce = toRecord(raw)
+    if (!ce) continue
+
+    const testName = ce.testName
+    if (typeof testName !== "string") continue
+
+    const rawInputs = toRecord(ce.inputs)
+    const inputs = rawInputs ? Object.values(rawInputs).map(String) : []
+
+    const entry: FuzzCounterexample = {
+      testName,
+      inputs,
+      runs: totalRuns,
+      timestamp: Date.now(),
+    }
+
+    if (typeof ce.revertReason === "string") {
+      entry.revertReason = ce.revertReason
+    }
+
+    state.fuzzCounterexamples.push(entry)
+  }
+}
+
+function processSoloditResult(
+  parsed: Record<string, unknown>,
+  state: AuditState
+): void {
+  const query = typeof parsed.query === "string" ? parsed.query : ""
+  const results = Array.isArray(parsed.results) ? parsed.results : []
+  const totalFound =
+    typeof parsed.totalFound === "number" ? parsed.totalFound : results.length
+
+  const topResults: SoloditResult["topResults"] = results
+    .slice(0, 5)
+    .map((raw) => {
+      const r = toRecord(raw)
+      return {
+        title: typeof r?.title === "string" ? r.title : "",
+        severity: typeof r?.severity === "string" ? r.severity : "",
+        url: typeof r?.url === "string" ? r.url : "",
+        protocol: typeof r?.protocol === "string" ? r.protocol : "",
+      }
+    })
+
+  state.soloditResults ??= []
+  state.soloditResults.push({
+    query,
+    timestamp: Date.now(),
+    resultCount: totalFound,
+    topResults,
+  })
+}
+
+/**
+ * Records a tool execution in the audit state.
+ *
+ * Multiple entries per tool name are allowed — if the same tool runs multiple times
+ * (e.g., argus_slither_analyze on different targets), each execution is recorded
+ * with its own findingsCount.
+ *
+ * Timing limitation: startTime and endTime are both set to Date.now() because this
+ * hook fires in the tool.execute.after phase, after execution has already completed.
+ * We cannot capture the actual start time. This is a known limitation of the hook
+ * architecture. For accurate timing, the hook would need to fire in tool.execute.before
+ * and tool.execute.after phases separately.
+ */
 function recordToolExecution(
   state: AuditState,
   toolName: string,
   findingsCount: number
 ): void {
-  const alreadyRecorded = state.toolsExecuted.some(
-    (execution) => execution.tool === toolName
-  )
-  if (alreadyRecorded) return
-
   const now = Date.now()
   state.toolsExecuted.push({
     tool: toolName,
@@ -193,14 +269,33 @@ function recordToolExecution(
  * Findings are deduplicated via the FindingStore (by check+file+lines).
  */
 export function createToolTrackingHook(
-  auditState: AuditState,
-  store: FindingStore
+  getAuditState: () => AuditState | null
 ): (input: ToolHookInput) => Promise<void> {
+  const storesByState = new WeakMap<AuditState, FindingStore>()
+
+  function resolveStateAndStore(): { state: AuditState; store: FindingStore } | null {
+    const state = getAuditState()
+    if (!state) return null
+
+    let store = storesByState.get(state)
+    if (!store) {
+      store = createFindingStore(state)
+      storesByState.set(state, store)
+    }
+
+    return { state, store }
+  }
+
   return async (input: ToolHookInput): Promise<void> => {
     if (!input.tool.startsWith("argus_")) {
       return
     }
 
+    const resolved = resolveStateAndStore()
+    if (!resolved) return
+
+    const { state: auditState, store } = resolved
+
     let parsed: unknown
     try {
       parsed = JSON.parse(input.result)
@@ -223,9 +318,13 @@ export function createToolTrackingHook(
       case "argus_analyze_contract":
         processContractAnalyzerResult(record, auditState)
         break
+      case "argus_solodit_search":
+        processSoloditResult(record, auditState)
+        break
       case "argus_forge_test":
+        break
       case "argus_forge_fuzz":
-        // No findings to extract — counterexamples are informational
+        processFuzzResult(record, auditState)
         break
     }
 

package/src/hooks/types.ts

@@ -4,7 +4,6 @@
  */
 
 export type HookName =
-  | "system-prompt"
   | "compaction"
   | "tool-tracking"
   | "event"

package/src/index.ts

@@ -1,20 +1,40 @@
 import type { Plugin } from "@opencode-ai/plugin"
-import { spawn } from "node:child_process"
 import { loadArgusConfig } from "./config/loader"
 import { createHookGuard } from "./hooks/hook-system"
 import { createTools } from "./create-tools"
 import { createHooks } from "./create-hooks"
 import { createManagers } from "./create-managers"
 import { createPluginInterface } from "./plugin-interface"
+import { checkSoloditHealth } from "./utils/solodit-health"
+import { createLogger } from "./shared/logger"
 
-function startSoloditMcp(port: number): void {
-  const child = spawn("npx", ["-y", "@lyuboslavlyubenov/solodit-mcp"], {
-    stdio: "ignore",
-    detached: false,
+async function startSoloditMcp(port: number): Promise<void> {
+  const logger = createLogger()
+
+  // Health check before spawn: if already reachable, skip spawn
+  const health = await checkSoloditHealth(port, true)
+  if (health.reachable) {
+    logger.debug(`Solodit MCP already running on port ${port} — skipping spawn`)
+    return
+  }
+
+  const child = Bun.spawn(["npx", "-y", "@lyuboslavlyubenov/solodit-mcp"], {
+    stdin: "ignore",
+    stdout: "ignore",
+    stderr: "ignore",
     env: { ...process.env, PORT: String(port) },
   })
   child.unref()
-  child.on("error", () => {})
+
+  // Health check after spawn: wait 2s, then ping
+  setTimeout(async () => {
+    const health = await checkSoloditHealth(port, true)
+    if (!health.reachable) {
+      logger.debug(`Solodit MCP not yet reachable on port ${port} — will retry on first use`)
+    } else {
+      logger.debug(`Solodit MCP healthy on port ${port}`)
+    }
+  }, 2000)
 }
 
 const ArgusPlugin: Plugin = async (ctx) => {
@@ -22,6 +42,8 @@ const ArgusPlugin: Plugin = async (ctx) => {
   const config = loadArgusConfig(projectDir)
 
   if (config.solodit?.enabled !== false) {
+    // Fire-and-forget: startSoloditMcp is now async but we don't await
+    // to avoid blocking plugin initialization
     startSoloditMcp(config.solodit?.port ?? 3000)
   }
 

package/src/knowledge/retry.ts

@@ -0,0 +1,53 @@
+export interface RetryOptions<T> {
+  maxAttempts: number;
+  baseDelayMs: number;
+  shouldRetry: (error: unknown) => boolean;
+  onRetry?: (attempt: number, error: unknown) => void;
+  _valueType?: T;
+}
+
+export interface RetryResult<T> {
+  success: boolean;
+  value?: T;
+  error?: unknown;
+  attempts: number;
+}
+
+function sleep(delayMs: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions<T>
+): Promise<RetryResult<T>> {
+  const maxAttempts = options.maxAttempts > 0 ? options.maxAttempts : 1;
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const value = await fn();
+      return { success: true, value, attempts: attempt };
+    } catch (error) {
+      lastError = error;
+      const canRetry = attempt < maxAttempts && options.shouldRetry(error);
+
+      if (!canRetry) {
+        return { success: false, error, attempts: attempt };
+      }
+
+      if (options.onRetry) {
+        options.onRetry(attempt, error);
+      }
+
+      const delay = options.baseDelayMs * 2 ** (attempt - 1);
+      await sleep(delay);
+    }
+  }
+
+  return {
+    success: false,
+    error: lastError,
+    attempts: maxAttempts,
+  };
+}

package/src/knowledge/scvd-client.ts

@@ -150,6 +150,24 @@ function parseStats(raw: unknown): ScvdStats {
   };
 }
 
+export class ScvdNetworkError extends Error {
+  override readonly name = "ScvdNetworkError" as const;
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export class ScvdApiError extends Error {
+  override readonly name = "ScvdApiError" as const;
+  readonly httpStatus: number;
+
+  constructor(httpStatus: number, message?: string) {
+    super(message ?? `SCVD API error: HTTP ${httpStatus}`);
+    this.httpStatus = httpStatus;
+  }
+}
+
 export class ScvdClient {
   private readonly baseUrl: string;
   private readonly signal?: AbortSignal;
@@ -167,11 +185,14 @@ export class ScvdClient {
       response = await fetch(url, { signal: this.signal });
     } catch (error) {
       const message = error instanceof Error ? error.message : "unknown network error";
-      throw new Error(`Failed to fetch SCVD stats from ${url}: ${message}`);
+      throw new ScvdNetworkError(`Failed to fetch SCVD stats from ${url}: ${message}`);
     }
 
     if (!response.ok) {
-      throw new Error(`Failed to fetch SCVD stats from ${url}: HTTP ${response.status}`);
+      throw new ScvdApiError(
+        response.status,
+        `Failed to fetch SCVD stats from ${url}: HTTP ${response.status}`
+      );
     }
 
     const body = (await response.json()) as unknown;
@@ -198,17 +219,23 @@ export class ScvdClient {
     const query = searchParams.toString();
     const url = `${this.baseUrl}/findings${query.length > 0 ? `?${query}` : ""}`;
 
+    let response: Response;
     try {
-      const response = await fetch(url, { signal: this.signal });
-      if (!response.ok) {
-        return [];
-      }
+      response = await fetch(url, { signal: this.signal });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "unknown network error";
+      throw new ScvdNetworkError(`Failed to fetch SCVD findings from ${url}: ${message}`);
+    }
 
-      const body = (await response.json()) as unknown;
-      return parseFindings(body);
-    } catch {
-      return []; // network error — treat as empty page
+    if (!response.ok) {
+      throw new ScvdApiError(
+        response.status,
+        `SCVD API error: HTTP ${response.status} for ${url}`
+      );
     }
+
+    const body = (await response.json()) as unknown;
+    return parseFindings(body);
   }
 
   async fetchAllFindings(onProgress?: (count: number) => void): Promise<ScvdFinding[]> {

package/src/knowledge/scvd-errors.ts

@@ -0,0 +1,89 @@
+export type SyncError = {
+  status: "error";
+  success: false;
+  reason: "network" | "api" | "parse";
+  message: string;
+  error: string;
+  httpStatus?: number;
+  newFindings: 0;
+  totalIndexed: 0;
+  lastSync: string;
+  attempts?: number;
+};
+
+export type SyncSuccess = {
+  status: "success";
+  success: true;
+  newFindings: number;
+  totalIndexed: number;
+  lastSync: string;
+  error?: undefined;
+  attempts?: number;
+};
+
+export type SyncStale = {
+  status: "stale";
+  success: false;
+  newFindings: 0;
+  totalIndexed: 0;
+  lastSync: string;
+  error?: undefined;
+  daysSinceSync: number;
+  attempts?: number;
+};
+
+export type SyncOutcome = SyncSuccess | SyncError | SyncStale;
+
+export function createNetworkError(message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "network",
+    message,
+    error: message,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  };
+}
+
+export function createApiError(httpStatus: number, message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "api",
+    message,
+    error: message,
+    httpStatus,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  };
+}
+
+export function createParseError(message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "parse",
+    message,
+    error: message,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  };
+}
+
+export function createSyncSuccess(
+  data: Omit<SyncSuccess, "status" | "success" | "error"> & { attempts?: number }
+): SyncSuccess {
+  return {
+    status: "success",
+    success: true,
+    ...data,
+  };
+}
+
+export function isRetryableError(outcome: SyncOutcome): boolean {
+  return outcome.status === "error" && outcome.reason === "network";
+}

package/src/knowledge/scvd-index.ts

@@ -10,15 +10,42 @@ export interface ScvdIndexEntry {
   repoUrl: string;
 }
 
+export interface ScvdIndexMetadata {
+  lastSuccess: string | null;
+  lastAttempt: string | null;
+  errorCount: number;
+  lastError: string | null;
+  lastErrorReason: string | null;
+}
+
 export interface ScvdIndex {
   version: number;
   lastSync: string;
   totalFindings: number;
   entries: ScvdIndexEntry[];
+  metadata?: ScvdIndexMetadata;
 }
 
 const INDEX_VERSION = 1;
 const DEFAULT_LIMIT = 10;
+let syncInProgress = false;
+
+export function acquireSyncLock(): boolean {
+  if (syncInProgress) {
+    return false;
+  }
+
+  syncInProgress = true;
+  return true;
+}
+
+export function releaseSyncLock(): void {
+  syncInProgress = false;
+}
+
+export function isSyncLocked(): boolean {
+  return syncInProgress;
+}
 
 function normalizeKeywordInput(value: string): string[] {
   return value
@@ -96,8 +123,10 @@ export function searchIndex(
 }
 
 export async function saveIndex(index: ScvdIndex, filePath: string): Promise<void> {
-  const json = JSON.stringify(index, null, 2);
-  await Bun.write(filePath, json);
+  const tmpPath = `${filePath}.tmp.${Date.now()}`;
+  await Bun.write(tmpPath, JSON.stringify(index, null, 2));
+  const { renameSync } = await import("node:fs");
+  renameSync(tmpPath, filePath);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -142,6 +171,20 @@ function parseEntry(value: unknown): ScvdIndexEntry | null {
   };
 }
 
+function parseNullableString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function parseMetadata(raw: Record<string, unknown>): ScvdIndexMetadata {
+  return {
+    lastSuccess: parseNullableString(raw.lastSuccess),
+    lastAttempt: parseNullableString(raw.lastAttempt),
+    errorCount: typeof raw.errorCount === "number" ? raw.errorCount : 0,
+    lastError: parseNullableString(raw.lastError),
+    lastErrorReason: parseNullableString(raw.lastErrorReason),
+  };
+}
+
 export async function loadIndex(filePath: string): Promise<ScvdIndex | null> {
   const file = Bun.file(filePath);
   const exists = await file.exists();
@@ -174,10 +217,17 @@ export async function loadIndex(filePath: string): Promise<ScvdIndex | null> {
     .map(parseEntry)
     .filter((entry): entry is ScvdIndexEntry => entry !== null);
 
-  return {
+  const index: ScvdIndex = {
     version,
     lastSync,
     totalFindings,
     entries,
   };
+
+  const rawMetadata = raw.metadata;
+  if (isRecord(rawMetadata)) {
+    index.metadata = parseMetadata(rawMetadata);
+  }
+
+  return index;
 }