solidity-argus 0.1.8 → 0.3.0

package/src/knowledge/scvd-sync.ts

@@ -1,85 +1,261 @@
-import type { ScvdClient } from "./scvd-client";
-import { buildIndex, loadIndex, saveIndex } from "./scvd-index";
-
-export interface SyncResult {
-  success: boolean;
-  newFindings: number;
-  totalIndexed: number;
-  lastSync: string;
-  error?: string;
+import { createLogger } from "../shared/logger"
+import { withRetry } from "./retry"
+import type { ScvdClient } from "./scvd-client"
+import { ScvdApiError, ScvdNetworkError } from "./scvd-client"
+import {
+  createApiError,
+  createNetworkError,
+  createParseError,
+  createSyncSuccess,
+  isRetryableError,
+  type SyncError,
+  type SyncOutcome,
+} from "./scvd-errors"
+import {
+  acquireSyncLock,
+  buildIndex,
+  loadIndex,
+  releaseSyncLock,
+  type ScvdIndex,
+  type ScvdIndexMetadata,
+  saveIndex,
+} from "./scvd-index"
+
+export type SyncResult = SyncOutcome
+
+const RETRY_MAX_ATTEMPTS = 3
+const RETRY_BASE_DELAY_MS = 1000
+
+function buildErrorResult(error: unknown): SyncError {
+  const message = error instanceof Error ? error.message : "Unknown sync error"
+
+  if (error instanceof ScvdNetworkError) {
+    return createNetworkError(message)
+  }
+  if (error instanceof ScvdApiError) {
+    return createApiError(error.httpStatus, message)
+  }
+  return createParseError(message)
 }
 
-function buildErrorResult(error: unknown): SyncResult {
-  const message = error instanceof Error ? error.message : "Unknown sync error";
-  return {
-    success: false,
-    newFindings: 0,
-    totalIndexed: 0,
-    lastSync: new Date().toISOString(),
-    error: message,
-  };
+function shouldRetrySyncError(error: unknown): boolean {
+  if (!(error instanceof ScvdNetworkError)) {
+    return false
+  }
+
+  return isRetryableError(buildErrorResult(error))
+}
+
+function errorReasonFromResult(result: SyncError): string {
+  return result.reason
+}
+
+async function persistErrorMetadata(indexPath: string, errorResult: SyncError): Promise<void> {
+  const existing = await loadIndex(indexPath)
+  if (!existing) return
+
+  const now = new Date().toISOString()
+  const prevMetadata = existing.metadata
+  existing.metadata = {
+    lastSuccess: prevMetadata?.lastSuccess ?? null,
+    lastAttempt: now,
+    errorCount: (prevMetadata?.errorCount ?? 0) + 1,
+    lastError: errorResult.message,
+    lastErrorReason: errorReasonFromResult(errorResult),
+  }
+  await saveIndex(existing, indexPath)
+}
+
+async function syncAllUnlocked(client: ScvdClient, indexPath: string): Promise<SyncResult> {
+  const fetchResult = await withRetry(() => client.fetchAllFindings(), {
+    maxAttempts: RETRY_MAX_ATTEMPTS,
+    baseDelayMs: RETRY_BASE_DELAY_MS,
+    shouldRetry: shouldRetrySyncError,
+  })
+
+  if (!fetchResult.success) {
+    const errorResult = buildErrorResult(fetchResult.error)
+    errorResult.attempts = fetchResult.attempts
+    await persistErrorMetadata(indexPath, errorResult)
+    return errorResult
+  }
+
+  if (fetchResult.value === undefined) {
+    const errorResult = createParseError("SCVD sync returned no findings payload")
+    errorResult.attempts = fetchResult.attempts
+    await persistErrorMetadata(indexPath, errorResult)
+    return errorResult
+  }
+
+  const findings = fetchResult.value
+  const index = buildIndex(findings)
+  const now = new Date().toISOString()
+  index.metadata = {
+    lastSuccess: now,
+    lastAttempt: now,
+    errorCount: 0,
+    lastError: null,
+    lastErrorReason: null,
+  }
+  await saveIndex(index, indexPath)
+
+  return createSyncSuccess({
+    newFindings: findings.length,
+    totalIndexed: index.totalFindings,
+    lastSync: index.lastSync,
+    attempts: fetchResult.attempts,
+  })
 }
 
 export async function syncAll(client: ScvdClient, indexPath: string): Promise<SyncResult> {
-  try {
-    const findings = await client.fetchAllFindings();
-    const index = buildIndex(findings);
-    await saveIndex(index, indexPath);
+  const logger = createLogger()
 
-    return {
-      success: true,
-      newFindings: findings.length,
-      totalIndexed: index.totalFindings,
-      lastSync: index.lastSync,
-    };
+  if (!acquireSyncLock()) {
+    return createParseError("Sync already in progress")
+  }
+
+  logger.debug("[sync] starting", "source=scvd mode=full")
+
+  try {
+    const result = await syncAllUnlocked(client, indexPath)
+    if (result.success) {
+      logger.debug(
+        "[sync] complete",
+        `source=scvd newFindings=${result.newFindings} totalIndexed=${result.totalIndexed}`,
+      )
+    } else {
+      const reason = result.status === "error" ? result.reason : result.status
+      logger.debug("[sync] failed", `source=scvd reason=${reason}`)
+    }
+    return result
   } catch (error) {
-    return buildErrorResult(error);
+    const errorResult = buildErrorResult(error)
+    logger.debug("[sync] failed", `source=scvd reason=${errorResult.reason}`)
+    await persistErrorMetadata(indexPath, errorResult).catch(() => {
+      logger.debug("Failed to persist sync error metadata")
+    })
+    return errorResult
+  } finally {
+    releaseSyncLock()
   }
 }
 
-export async function syncIncremental(
-  client: ScvdClient,
-  indexPath: string
-): Promise<SyncResult> {
+export async function syncIncremental(client: ScvdClient, indexPath: string): Promise<SyncResult> {
+  const logger = createLogger()
+
+  if (!acquireSyncLock()) {
+    return createParseError("Sync already in progress")
+  }
+
+  logger.debug("[sync] starting", "source=scvd mode=incremental")
+
   try {
-    const [stats, existingIndex] = await Promise.all([
-      client.fetchStats(),
+    const [statsResult, existingIndex] = await Promise.all([
+      withRetry(() => client.fetchStats(), {
+        maxAttempts: RETRY_MAX_ATTEMPTS,
+        baseDelayMs: RETRY_BASE_DELAY_MS,
+        shouldRetry: shouldRetrySyncError,
+      }),
       loadIndex(indexPath),
-    ]);
+    ])
+
+    if (!statsResult.success) {
+      const errorResult = buildErrorResult(statsResult.error)
+      errorResult.attempts = statsResult.attempts
+      await persistErrorMetadata(indexPath, errorResult).catch(() => {
+        logger.debug("Failed to persist sync error metadata")
+      })
+      return errorResult
+    }
+
+    if (statsResult.value === undefined) {
+      const errorResult = createParseError("SCVD sync returned no stats payload")
+      errorResult.attempts = statsResult.attempts
+      await persistErrorMetadata(indexPath, errorResult).catch(() => {
+        logger.debug("Failed to persist sync error metadata")
+      })
+      return errorResult
+    }
+
+    const stats = statsResult.value
 
     if (existingIndex && existingIndex.totalFindings === stats.total) {
-      return {
-        success: true,
+      return createSyncSuccess({
         newFindings: 0,
         totalIndexed: existingIndex.totalFindings,
         lastSync: existingIndex.lastSync,
-      };
+      })
     }
 
-    return await syncAll(client, indexPath);
+    return await syncAllUnlocked(client, indexPath)
   } catch (error) {
-    return buildErrorResult(error);
+    const errorResult = buildErrorResult(error)
+    await persistErrorMetadata(indexPath, errorResult).catch(() => {
+      logger.debug("Failed to persist sync error metadata")
+    })
+    return errorResult
+  } finally {
+    releaseSyncLock()
   }
 }
+const STALE_THRESHOLD_DAYS = 7
+
+export function isSyncStale(
+  index: ScvdIndex | null,
+  thresholdDays: number = STALE_THRESHOLD_DAYS,
+): boolean {
+  if (!index || !index.lastSync) return true
+  const lastSyncDate = new Date(index.lastSync)
+  const now = new Date()
+  const diffMs = now.getTime() - lastSyncDate.getTime()
+  const diffDays = diffMs / (1000 * 60 * 60 * 24)
+  return diffDays > thresholdDays
+}
 
 export async function getSyncStatus(indexPath: string): Promise<{
-  lastSync: string | null;
-  totalFindings: number;
-  healthy: boolean;
+  lastSync: string | null
+  totalFindings: number
+  healthy: boolean
+  stale: boolean
+  metadata: ScvdIndexMetadata | null
+  hint?: string
 }> {
-  const index = await loadIndex(indexPath);
+  const logger = createLogger()
+  const index = await loadIndex(indexPath)
 
   if (!index) {
     return {
       lastSync: null,
       totalFindings: 0,
       healthy: false,
-    };
+      stale: true,
+      metadata: null,
+      hint: "SCVD data is missing. Run argus_sync_knowledge to populate.",
+    }
+  }
+
+  const stale = isSyncStale(index)
+
+  if (stale) {
+    const lastSyncDate = new Date(index.lastSync)
+    const daysSince = Math.floor((Date.now() - lastSyncDate.getTime()) / (1000 * 60 * 60 * 24))
+    logger.debug("[sync] stale", `source=scvd daysSince=${daysSince}`)
+
+    return {
+      lastSync: index.lastSync,
+      totalFindings: index.totalFindings,
+      healthy: true,
+      stale: true,
+      metadata: index.metadata ?? null,
+      hint: "SCVD data is stale. Run argus_sync_knowledge to update.",
+    }
   }
 
   return {
     lastSync: index.lastSync,
     totalFindings: index.totalFindings,
     healthy: true,
-  };
+    stale: false,
+    metadata: index.metadata ?? null,
+  }
 }

package/src/knowledge/source-manifest.ts

@@ -0,0 +1,102 @@
+export type SourceMode = "baked-in" | "on-demand" | "hybrid"
+
+export interface SourceManifest {
+  name: string
+  mode: SourceMode
+  url: string
+  license: string
+  updateCadence: string
+  lastUpdated?: string
+  hash?: string
+  version?: string
+}
+
+export class IngestionRegistry {
+  private sources = new Map<string, SourceManifest>()
+
+  register(manifest: SourceManifest): void {
+    this.sources.set(manifest.name, manifest)
+  }
+
+  get(name: string): SourceManifest | null {
+    return this.sources.get(name) ?? null
+  }
+
+  list(): SourceManifest[] {
+    return Array.from(this.sources.values())
+  }
+
+  getByMode(mode: SourceMode): SourceManifest[] {
+    return Array.from(this.sources.values()).filter((m) => m.mode === mode)
+  }
+}
+
+export function createDefaultRegistry(): IngestionRegistry {
+  const registry = new IngestionRegistry()
+
+  registry.register({
+    name: "cyfrin",
+    mode: "baked-in",
+    url: "https://github.com/Cyfrin/audit-checklist",
+    license: "unspecified",
+    updateCadence: "per-release",
+  })
+
+  registry.register({
+    name: "kadenzipfel",
+    mode: "baked-in",
+    url: "https://github.com/kadenzipfel/smart-contract-vulnerabilities",
+    license: "MIT",
+    updateCadence: "per-release",
+  })
+
+  registry.register({
+    name: "defifofum",
+    mode: "baked-in",
+    url: "https://github.com/DeFiFoFum/fofum-solidity-skills",
+    license: "MIT",
+    updateCadence: "per-release",
+  })
+
+  registry.register({
+    name: "smartbugs",
+    mode: "baked-in",
+    url: "https://github.com/smartbugs/smartbugs-curated",
+    license: "Apache-2.0",
+    updateCadence: "per-release",
+  })
+
+  registry.register({
+    name: "sunweb3sec",
+    mode: "baked-in",
+    url: "https://github.com/SunWeb3Sec/DeFiHackLabs",
+    license: "reference-only",
+    updateCadence: "per-release",
+  })
+
+  registry.register({
+    name: "scvd",
+    mode: "hybrid",
+    url: "https://api.scvd.dev",
+    license: "CC0",
+    updateCadence: "on-sync",
+  })
+
+  registry.register({
+    name: "trailofbits",
+    mode: "hybrid",
+    url: "https://github.com/trailofbits/solidity-security-research",
+    license: "varies",
+    updateCadence: "on-install",
+  })
+
+  registry.register({
+    name: "solodit",
+    mode: "on-demand",
+    url: "https://solodit.xyz",
+    license: "varies",
+    updateCadence: "per-request",
+  })
+
+  return registry
+}

package/src/managers/index.ts

@@ -1 +1 @@
-export type { BackgroundManager, AuditStateManager, Managers } from "./types";
+export type { AuditStateManager, BackgroundManager, Managers } from "./types"

package/src/managers/types.ts

@@ -1,4 +1,4 @@
-import type { AuditState } from "../state/types";
+import type { AuditState } from "../state/types"
 
 /**
  * BackgroundManager interface
@@ -12,32 +12,32 @@ export interface BackgroundManager {
    * @param options - Optional configuration (priority, timeout, etc.)
    * @returns taskId - Unique identifier for tracking this task
    */
-  dispatch(agentName: string, prompt: string, options?: { priority?: number }): string;
+  dispatch(agentName: string, prompt: string, options?: { priority?: number }): string
 
   /**
    * Cancel a running background task
    * @param taskId - The task ID to cancel
    */
-  cancel(taskId: string): void;
+  cancel(taskId: string): void
 
   /**
    * Get the result of a completed background task
    * @param taskId - The task ID to retrieve results for
    * @returns Promise resolving to the task result
    */
-  getResult(taskId: string): Promise<unknown>;
+  getResult(taskId: string): Promise<unknown>
 
   /**
    * Register a callback to be invoked when a task completes
    * @param callback - Function called with (taskId, result) when task finishes
    */
-  onComplete(callback: (taskId: string, result: unknown) => void): void;
+  onComplete(callback: (taskId: string, result: unknown) => void): void
 
   /**
    * Get the number of currently active/running tasks
    * @returns Number of active tasks
    */
-  getActiveCount(): number;
+  getActiveCount(): number
 }
 
 /**
@@ -49,30 +49,35 @@ export interface AuditStateManager {
    * Load audit state from persistent storage
    * @returns Promise resolving to AuditState or null if not found
    */
-  load(): Promise<AuditState | null>;
+  load(): Promise<AuditState | null>
 
   /**
    * Save audit state to persistent storage
    * @param state - The AuditState to persist
    */
-  save(state: AuditState): Promise<void>;
+  save(state: AuditState): Promise<void>
 
   /**
    * Get the current in-memory audit state
    * @returns The current AuditState or null if not loaded
    */
-  get(): AuditState | null;
+  get(): AuditState | null
 
   /**
    * Update the audit state with a partial patch
    * @param patch - Partial AuditState object with fields to update
    */
-  update(patch: Partial<AuditState>): Promise<void>;
+  update(patch: Partial<AuditState>): Promise<void>
 
   /**
    * Reset the audit state (clear all data)
    */
-  reset(): Promise<void>;
+  reset(): Promise<void>
+
+  /**
+   * Archive current state (if meaningful) then reset
+   */
+  archive(): Promise<void>
 }
 
 /**
@@ -80,6 +85,6 @@ export interface AuditStateManager {
  * Container for all manager instances
  */
 export type Managers = {
-  backgroundManager: BackgroundManager;
-  auditStateManager: AuditStateManager;
-};
+  backgroundManager: BackgroundManager
+  auditStateManager: AuditStateManager
+}

package/src/plugin-interface.ts

@@ -11,14 +11,25 @@ export function createPluginInterface(args: {
 }): PluginReturn {
   const { tools, hooks } = args
 
-   const result: PluginReturn = {
-     tool: tools,
-     config: hooks.config,
-   }
-
-   if (hooks["experimental.session.compacting"]) {
-    result["experimental.session.compacting"] =
-      hooks["experimental.session.compacting"]
+  const result: PluginReturn = {
+    tool: tools,
+    config: hooks.config,
+  }
+
+  if (hooks["chat.params"]) {
+    result["chat.params"] = hooks["chat.params"]
+  }
+
+  if (hooks["chat.message"]) {
+    result["chat.message"] = hooks["chat.message"]
+  }
+
+  if (hooks["experimental.chat.system.transform"]) {
+    result["experimental.chat.system.transform"] = hooks["experimental.chat.system.transform"]
+  }
+
+  if (hooks["experimental.session.compacting"]) {
+    result["experimental.session.compacting"] = hooks["experimental.session.compacting"]
   }
 
   if (hooks["tool.execute.after"]) {

package/src/shared/binary-utils.ts

@@ -1,63 +1,73 @@
-import { execSync } from "child_process";
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import { createLogger } from "./logger"
+
+const logger = createLogger()
 
 export function hasBinary(name: string): boolean {
   try {
-    execSync(`which ${name}`, { stdio: "ignore", timeout: 3_000 });
-    return true;
+    const result = Bun.spawnSync(["which", name], {
+      stdout: "ignore",
+      stderr: "ignore",
+      timeout: 5_000,
+    })
+    return result.exitCode === 0
   } catch (_e) {
-    return false;
+    return false
   }
 }
 
-export function parseSolcVersion(target: string): string | undefined {
-  const foundryToml = join(target, "foundry.toml");
-  if (existsSync(foundryToml)) {
-    const content = readFileSync(foundryToml, "utf-8");
-    const match = content.match(/solc\s*=\s*["']([^"']+)["']/);
-    if (match?.[1]) return match[1];
+export async function parseSolcVersion(target: string): Promise<string | undefined> {
+  const foundryToml = join(target, "foundry.toml")
+  if (await Bun.file(foundryToml).exists()) {
+    const content = await Bun.file(foundryToml).text()
+    const match = content.match(/solc\s*=\s*["']([^"']+)["']/)
+    if (match?.[1]) return match[1]
   }
 
-  const solFiles = [target];
-  if (existsSync(target) && target.endsWith(".sol")) {
-    solFiles.push(target);
+  const solFiles: string[] = []
+  if (target.endsWith(".sol") && (await Bun.file(target).exists())) {
+    solFiles.push(target)
   } else {
-    const srcDir = join(target, "src");
+    const srcDir = join(target, "src")
     if (existsSync(srcDir)) {
       try {
-        const files = execSync(`find "${srcDir}" -name "*.sol" -maxdepth 3`, {
-          encoding: "utf-8",
-          timeout: 5_000,
+        const proc = Bun.spawn(["find", srcDir, "-maxdepth", "3", "-name", "*.sol"], {
+          stdout: "pipe",
+          stderr: "pipe",
+          signal: AbortSignal.timeout(10_000),
         })
-          .trim()
-          .split("\n")
-          .filter(Boolean);
-        solFiles.push(...files);
+        const exitCode = await proc.exited
+        if (exitCode === 0) {
+          const output = await new Response(proc.stdout).text()
+          solFiles.push(...output.trim().split("\n").filter(Boolean))
+        }
       } catch (_findErr) {
+        logger.debug("find command failed for .sol files")
       }
     }
   }
 
   for (const file of solFiles) {
-    if (!existsSync(file) || !file.endsWith(".sol")) continue;
+    if (!file.endsWith(".sol") || !(await Bun.file(file).exists())) continue
     try {
-      const content = readFileSync(file, "utf-8");
-      const pragma = content.match(/pragma\s+solidity\s+[\^~>=<]*\s*([\d.]+)/);
-      if (pragma?.[1]) return pragma[1];
+      const content = await Bun.file(file).text()
+      const pragma = content.match(/pragma\s+solidity\s+[\^~>=<]*\s*([\d.]+)/)
+      if (pragma?.[1]) return pragma[1]
     } catch (_readErr) {
+      logger.debug("Failed to read .sol file for pragma detection")
     }
   }
-  return undefined;
+  return undefined
 }
 
-export function extractContractNames(filePath: string): string[] {
-  if (!existsSync(filePath)) return [];
+export async function extractContractNames(filePath: string): Promise<string[]> {
+  if (!(await Bun.file(filePath).exists())) return []
   try {
-    const content = readFileSync(filePath, "utf-8");
-    const matches = content.matchAll(/\b(?:contract|library|interface)\s+(\w+)/g);
-    return Array.from(matches, (m) => m[1]).filter(Boolean) as string[];
+    const content = await Bun.file(filePath).text()
+    const matches = content.matchAll(/\b(?:contract|library|interface)\s+(\w+)/g)
+    return Array.from(matches, (m) => m[1]).filter(Boolean) as string[]
   } catch (_e) {
-    return [];
+    return []
   }
 }