solidity-argus 0.1.8 → 0.2.0

package/src/knowledge/scvd-sync.ts

@@ -1,39 +1,140 @@
 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 { ScvdApiError, ScvdNetworkError } from "./scvd-client";
+import { createLogger } from "../shared/logger";
+import {
+  createApiError,
+  createNetworkError,
+  createParseError,
+  createSyncSuccess,
+  isRetryableError,
+  type SyncError,
+  type SyncOutcome,
+} from "./scvd-errors";
+import {
+  acquireSyncLock,
+  buildIndex,
+  loadIndex,
+  releaseSyncLock,
+  saveIndex,
+  type ScvdIndex,
+  type ScvdIndexMetadata,
+} from "./scvd-index";
+import { withRetry } from "./retry";
+
+export type SyncResult = SyncOutcome;
 
-function buildErrorResult(error: unknown): SyncResult {
+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";
-  return {
-    success: false,
-    newFindings: 0,
-    totalIndexed: 0,
-    lastSync: new Date().toISOString(),
-    error: message,
+
+  if (error instanceof ScvdNetworkError) {
+    return createNetworkError(message);
+  }
+  if (error instanceof ScvdApiError) {
+    return createApiError(error.httpStatus, message);
+  }
+  return createParseError(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(() => {});
+    return errorResult;
+  } finally {
+    releaseSyncLock();
   }
 }
 
@@ -41,32 +142,80 @@ 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(() => {});
+      return errorResult;
+    }
+
+    if (statsResult.value === undefined) {
+      const errorResult = createParseError("SCVD sync returned no stats payload");
+      errorResult.attempts = statsResult.attempts;
+      await persistErrorMetadata(indexPath, errorResult).catch(() => {});
+      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(() => {});
+    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;
+  stale: boolean;
+  metadata: ScvdIndexMetadata | null;
+  hint?: string;
 }> {
+  const logger = createLogger();
   const index = await loadIndex(indexPath);
 
   if (!index) {
@@ -74,6 +223,26 @@ export async function getSyncStatus(indexPath: string): Promise<{
       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.",
     };
   }
 
@@ -81,5 +250,7 @@ export async function getSyncStatus(indexPath: string): Promise<{
     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/plugin-interface.ts

@@ -16,7 +16,20 @@ export function createPluginInterface(args: {
      config: hooks.config,
    }
 
-   if (hooks["experimental.session.compacting"]) {
+   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"]
   }

package/src/shared/binary-utils.ts

@@ -29,6 +29,7 @@ export function parseSolcVersion(target: string): string | undefined {
         const files = execSync(`find "${srcDir}" -name "*.sol" -maxdepth 3`, {
           encoding: "utf-8",
           timeout: 5_000,
+          stdio: ["pipe", "pipe", "pipe"],
         })
           .trim()
           .split("\n")

package/src/shared/logger.ts

@@ -1,36 +1,97 @@
+import { appendFileSync, mkdirSync, existsSync } from "node:fs"
+import { join } from "node:path"
+import { homedir } from "node:os"
+
 export interface LoggerConfig {
-  debug?: boolean;
+  debug?: boolean
 }
 
 export interface Logger {
-  info(...args: any[]): void;
-  debug(...args: any[]): void;
-  error(...args: any[]): void;
-  warn(...args: any[]): void;
+  info(...args: unknown[]): void
+  debug(...args: unknown[]): void
+  error(...args: unknown[]): void
+  warn(...args: unknown[]): void
 }
 
-export function createLogger(config: LoggerConfig = {}): Logger {
-  const { debug = false } = config;
+type LogSink = (line: string) => void
+
+const LOG_DIR = join(homedir(), ".cache", "solidity-argus")
+const LOG_FILE = join(LOG_DIR, "argus.log")
+
+function ensureLogDir(): void {
+  if (!existsSync(LOG_DIR)) {
+    mkdirSync(LOG_DIR, { recursive: true })
+  }
+}
+
+function formatLine(level: string, args: unknown[]): string {
+  const ts = new Date().toISOString()
+  const msg = args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")
+  return `${ts} [${level}] ${msg}\n`
+}
+
+function createFileSink(): LogSink {
+  let dirReady = false
+  return (line: string) => {
+    if (!dirReady) {
+      ensureLogDir()
+      dirReady = true
+    }
+    try {
+      appendFileSync(LOG_FILE, line)
+    } catch {
+      // if we can't write logs, we don't crash the plugin
+    }
+  }
+}
+
+function createStderrSink(): LogSink {
+  return (line: string) => {
+    process.stderr.write(line)
+  }
+}
+
+function resolveSink(): LogSink {
+  const mode = process.env.ARGUS_LOG
+  if (mode === "stderr") return createStderrSink()
+  return createFileSink()
+}
+
+let sharedSink: LogSink | null = null
+
+function getSink(): LogSink {
+  if (!sharedSink) {
+    sharedSink = resolveSink()
+  }
+  return sharedSink
+}
 
-  const prefix = "[argus]";
+export function createLogger(config: LoggerConfig = {}): Logger {
+  const { debug = false } = config
 
   return {
-    info(...args: any[]): void {
-      console.error(prefix, ...args);
+    info(...args: unknown[]): void {
+      getSink()(formatLine("INFO", args))
     },
 
-    debug(...args: any[]): void {
+    debug(...args: unknown[]): void {
       if (debug) {
-        console.error(prefix, ...args);
+        getSink()(formatLine("DEBUG", args))
       }
     },
 
-    error(...args: any[]): void {
-      console.error(prefix, ...args);
+    error(...args: unknown[]): void {
+      getSink()(formatLine("ERROR", args))
     },
 
-    warn(...args: any[]): void {
-      console.error(prefix, ...args);
+    warn(...args: unknown[]): void {
+      getSink()(formatLine("WARN", args))
     },
-  };
+  }
 }
+
+export function resetLoggerSink(): void {
+  sharedSink = null
+}
+
+export { LOG_FILE, LOG_DIR }