solidity-argus 0.3.6 → 0.5.6

package/src/index.ts

@@ -6,14 +6,25 @@ import { createTools } from "./create-tools"
 import type { Dispatcher } from "./features/background-agent/background-manager"
 import { createHookGuard } from "./hooks/hook-system"
 import { createPluginInterface } from "./plugin-interface"
+import { createLogger } from "./shared/logger"
 import { startSoloditMcp } from "./solodit-lifecycle"
+import { DEFAULT_SOLODIT_PORT } from "./tools/solodit-search-tool"
+
+const logger = createLogger()
 
 const ArgusPlugin: Plugin = async (ctx) => {
   const projectDir = ctx.directory ?? process.cwd()
   const config = loadArgusConfig(projectDir)
 
+  const { ARGUS_PLUGIN_VERSION } = await import("./shared/plugin-metadata")
+  console.error(`[argus] v${ARGUS_PLUGIN_VERSION} loaded for ${projectDir}`)
+
   if (config.solodit?.enabled !== false) {
-    await startSoloditMcp(config.solodit?.port ?? 3000)
+    // MCP bootstrap must not block plugin load; the Solodit search tool falls
+    // back to direct HTTP when the local MCP is still coming up.
+    void startSoloditMcp(config.solodit?.port ?? DEFAULT_SOLODIT_PORT, {
+      waitForHealth: false,
+    })
   }
 
   const isHookEnabled = createHookGuard(config.disabled_hooks)
@@ -31,6 +42,9 @@ const ArgusPlugin: Plugin = async (ctx) => {
               return taskId
             }
           }
+          logger.warn(
+            `ctx.task returned unexpected shape (${typeof result}), using fabricated task ID`,
+          )
           return `task-${Date.now()}`
         }
       : undefined

package/src/knowledge/scvd-client.ts

@@ -15,11 +15,9 @@ export interface ScvdStats {
   last_updated: string
 }
 
-const DEFAULT_PAGE_SIZE = 100
+import { isRecord } from "../shared/type-guards"
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null
-}
+const DEFAULT_PAGE_SIZE = 100
 
 function toStringArray(value: unknown): string[] {
   if (!Array.isArray(value)) {

package/src/knowledge/scvd-errors.ts

@@ -1,7 +1,7 @@
 export type SyncError = {
   status: "error"
   success: false
-  reason: "network" | "api" | "parse"
+  reason: "network" | "api" | "parse" | "lock"
   message: string
   error: string
   httpStatus?: number
@@ -74,6 +74,19 @@ export function createParseError(message: string): SyncError {
   }
 }
 
+export function createLockError(message: string): SyncError {
+  return {
+    status: "error",
+    success: false,
+    reason: "lock",
+    message,
+    error: message,
+    newFindings: 0,
+    totalIndexed: 0,
+    lastSync: new Date().toISOString(),
+  }
+}
+
 export function createSyncSuccess(
   data: Omit<SyncSuccess, "status" | "success" | "error"> & { attempts?: number },
 ): SyncSuccess {
@@ -84,6 +97,16 @@ export function createSyncSuccess(
   }
 }
 
+const RETRYABLE_HTTP_STATUSES = new Set([429, 502, 503, 504])
+
 export function isRetryableError(outcome: SyncOutcome): boolean {
-  return outcome.status === "error" && outcome.reason === "network"
+  if (outcome.status !== "error") return false
+  if (outcome.reason === "network") return true
+  if (
+    outcome.reason === "api" &&
+    outcome.httpStatus &&
+    RETRYABLE_HTTP_STATUSES.has(outcome.httpStatus)
+  )
+    return true
+  return false
 }

package/src/knowledge/scvd-index.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "../shared/type-guards"
 import type { ScvdFinding } from "./scvd-client"
 
 export interface ScvdIndexEntry {
@@ -127,10 +128,6 @@ export async function saveIndex(index: ScvdIndex, filePath: string): Promise<voi
   renameSync(tmpPath, filePath)
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null
-}
-
 function parseStringArray(value: unknown): string[] {
   if (!Array.isArray(value)) {
     return []
@@ -191,7 +188,12 @@ export async function loadIndex(filePath: string): Promise<ScvdIndex | null> {
     return null
   }
 
-  const raw = (await file.json()) as unknown
+  let raw: unknown
+  try {
+    raw = (await file.json()) as unknown
+  } catch {
+    return null
+  }
 
   if (!isRecord(raw)) {
     return null

package/src/knowledge/scvd-sync.ts

@@ -4,6 +4,7 @@ import type { ScvdClient } from "./scvd-client"
 import { ScvdApiError, ScvdNetworkError } from "./scvd-client"
 import {
   createApiError,
+  createLockError,
   createNetworkError,
   createParseError,
   createSyncSuccess,
@@ -39,11 +40,10 @@ function buildErrorResult(error: unknown): SyncError {
 }
 
 function shouldRetrySyncError(error: unknown): boolean {
-  if (!(error instanceof ScvdNetworkError)) {
-    return false
+  if (error instanceof ScvdNetworkError || error instanceof ScvdApiError) {
+    return isRetryableError(buildErrorResult(error))
   }
-
-  return isRetryableError(buildErrorResult(error))
+  return false
 }
 
 function errorReasonFromResult(result: SyncError): string {
@@ -111,7 +111,7 @@ export async function syncAll(client: ScvdClient, indexPath: string): Promise<Sy
   const logger = createLogger()
 
   if (!acquireSyncLock()) {
-    return createParseError("Sync already in progress")
+    return createLockError("Sync already in progress")
   }
 
   logger.debug("[sync] starting", "source=scvd mode=full")
@@ -144,7 +144,7 @@ export async function syncIncremental(client: ScvdClient, indexPath: string): Pr
   const logger = createLogger()
 
   if (!acquireSyncLock()) {
-    return createParseError("Sync already in progress")
+    return createLockError("Sync already in progress")
   }
 
   logger.debug("[sync] starting", "source=scvd mode=incremental")

package/src/managers/types.ts

@@ -46,13 +46,25 @@ export interface BackgroundManager {
  */
 export interface AuditStateManager {
   /**
-   * Load audit state from persistent storage
+   * Bind this manager to a specific OpenCode session.
+   * After binding, save/load operate on a session-scoped state file
+   * (.argus/sessions/state-{sessionId}.json) instead of the shared file.
+   * This prevents multi-instance contamination.
+   * @param sessionId - The OpenCode session ID (e.g., "ses_abc123")
+   */
+  bindSession(sessionId: string): void
+
+  /**
+   * Load audit state from persistent storage.
+   * If bound to a session, tries the session-scoped file first,
+   * then falls back to the most recent state file from any session.
    * @returns Promise resolving to AuditState or null if not found
    */
   load(): Promise<AuditState | null>
 
   /**
-   * Save audit state to persistent storage
+   * Save audit state to persistent storage.
+   * Writes to the session-scoped file if bound, otherwise the shared file.
    * @param state - The AuditState to persist
    */
   save(state: AuditState): Promise<void>
@@ -78,6 +90,12 @@ export interface AuditStateManager {
    * Archive current state (if meaningful) then reset
    */
   archive(): Promise<void>
+
+  /**
+   * Dispose the state manager, flushing pending state to disk and releasing resources.
+   * Safe to call multiple times; subsequent calls are no-ops.
+   */
+  dispose(): Promise<void>
 }
 
 /**

package/src/shared/agent-names.ts

@@ -0,0 +1,23 @@
+export const ARGUS_ORCHESTRATOR: ReadonlySet<string> = new Set(["argus"])
+export const ARGUS_SUBAGENTS: ReadonlySet<string> = new Set([
+  "sentinel",
+  "pythia",
+  "scribe",
+  "themis",
+])
+export const ARGUS_FAMILY: ReadonlySet<string> = new Set([
+  ...ARGUS_ORCHESTRATOR,
+  ...ARGUS_SUBAGENTS,
+])
+
+export function isArgusFamily(agent: string): boolean {
+  return ARGUS_FAMILY.has(agent)
+}
+
+export function isOrchestratorAgent(agent: string): boolean {
+  return ARGUS_ORCHESTRATOR.has(agent)
+}
+
+export function isSubagent(agent: string): boolean {
+  return ARGUS_SUBAGENTS.has(agent)
+}

package/src/shared/audit-artifact-resolver.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path"
+import { basename, join } from "node:path"
 import { defaultRootResolver } from "./path-root-resolver"
 
 export class ArtifactResolverError extends Error {
@@ -15,6 +15,9 @@ export interface AuditArtifactPaths {
   journalFile: string
   /** {projectDir}/.argus/runs/{runId}/findings.json */
   findingsFile: string
+  reportInputFile: string
+  /** {projectDir}/.argus/runs/{runId}/deduped-findings.json */
+  dedupedFindingsFile: string
   /** {projectDir}/.argus/reports */
   reportDir: string
   /** {projectDir}/.argus/runs/{runId}/evidence */
@@ -53,6 +56,8 @@ export function createAuditArtifactResolver(
     stateFile: join(writeRoot, "argus-state.json"),
     journalFile: join(runDir, "events.jsonl"),
     findingsFile: join(runDir, "findings.json"),
+    reportInputFile: join(runDir, "report-input.json"),
+    dedupedFindingsFile: join(runDir, "deduped-findings.json"),
     reportDir: join(writeRoot, "reports"),
     evidenceDir: join(runDir, "evidence"),
     archiveDir: join(writeRoot, "archives"),
@@ -66,10 +71,10 @@ export function createAuditArtifactResolver(
       return cachedPaths
     },
     reportFilePath(filename: string): string {
-      return join(cachedPaths.reportDir, filename)
+      return join(cachedPaths.reportDir, basename(filename))
     },
     evidenceFilePath(filename: string): string {
-      return join(cachedPaths.evidenceDir, filename)
+      return join(cachedPaths.evidenceDir, basename(filename))
     },
   }
 }

package/src/shared/audit-phases.ts

@@ -0,0 +1,12 @@
+import type { AuditPhase } from "../state/types"
+
+export const PHASE_ORDER: readonly AuditPhase[] = [
+  "reconnaissance",
+  "scanning",
+  "manual-review",
+  "attack-surface",
+  "research",
+  "testing",
+  "reporting",
+  "complete",
+] as const

package/src/shared/cache-paths.ts

@@ -0,0 +1,41 @@
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+
+const DEFAULT_CACHE_DIR = join(homedir(), ".cache", "solidity-argus")
+
+function normalizeOverride(value: string | undefined): string | null {
+  if (!value) {
+    return null
+  }
+
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+export function getArgusCacheDir(): string {
+  return normalizeOverride(process.env.ARGUS_CACHE_DIR) ?? DEFAULT_CACHE_DIR
+}
+
+export function getArgusLogFile(): string {
+  return normalizeOverride(process.env.ARGUS_LOG_FILE) ?? join(getArgusCacheDir(), "argus.log")
+}
+
+export function getArgusLogDir(): string {
+  return dirname(getArgusLogFile())
+}
+
+export function getScvdIndexPath(): string {
+  return join(getArgusCacheDir(), "scvd-index.json")
+}
+
+export function getTrailOfBitsCacheDir(): string {
+  return join(getArgusCacheDir(), "trailofbits-skills")
+}
+
+export function getGlobalRunIndexDir(): string {
+  return join(getArgusCacheDir(), "runs")
+}
+
+export function getGlobalRunIndexFile(): string {
+  return join(getGlobalRunIndexDir(), "index.jsonl")
+}

package/src/shared/drop-diagnostics.ts

@@ -76,9 +76,9 @@ export function createDropDiagnosticsCollector(
 
     const logMsg = `[${source}${tool ? `:${tool}` : ""}] ${code}${field ? ` (field: ${field})` : ""}: ${message}`
     if (level === "error") {
-      logger.warn(logMsg)
+      logger.error(logMsg)
     } else {
-      logger.info(logMsg)
+      logger.warn(logMsg)
     }
   }
 

package/src/shared/forge-errors.ts

@@ -0,0 +1,31 @@
+import type { ToolContext } from "@opencode-ai/plugin"
+
+export const FOUNDRY_NOT_FOUND_MESSAGE =
+  "Foundry not found. Install: curl -L https://foundry.paradigm.xyz | bash"
+
+/**
+ * Classify a caught error from a forge command execution into a user-facing
+ * error string.  Returns `undefined` when the error is not a recognized
+ * forge-specific failure and should be handled by the caller.
+ */
+export function classifyForgeError(
+  error: unknown,
+  context: ToolContext,
+  toolLabel: string,
+): string | undefined {
+  if (context.abort.aborted || (error instanceof DOMException && error.name === "AbortError")) {
+    return `${toolLabel} aborted`
+  }
+
+  const maybeError = error as Error & { code?: string }
+
+  if (maybeError.code === "ENOENT") {
+    return FOUNDRY_NOT_FOUND_MESSAGE
+  }
+
+  if (maybeError.code === "ETIMEDOUT" || maybeError.message?.toLowerCase().includes("timed out")) {
+    return `${toolLabel} timed out`
+  }
+
+  return undefined
+}

package/src/shared/forge-runner.ts

@@ -0,0 +1,30 @@
+export type ForgeCommandResult = {
+  stdout: string
+  stderr: string
+  exitCode: number
+}
+
+export async function runForgeCommand(
+  command: string[],
+  options: { signal?: AbortSignal; cwd?: string; env?: Record<string, string> },
+): Promise<ForgeCommandResult> {
+  const child = Bun.spawn(command, {
+    cwd: options.cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    signal: options.signal,
+    env: options.env,
+  })
+
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ])
+
+  return {
+    stdout,
+    stderr,
+    exitCode,
+  }
+}

package/src/shared/format-error.ts

@@ -0,0 +1,3 @@
+export function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/shared/index.ts

@@ -5,6 +5,15 @@ export {
   createAuditArtifactResolver,
 } from "./audit-artifact-resolver"
 export { extractContractNames, hasBinary, parseSolcVersion } from "./binary-utils"
+export {
+  getArgusCacheDir,
+  getArgusLogDir,
+  getArgusLogFile,
+  getGlobalRunIndexDir,
+  getGlobalRunIndexFile,
+  getScvdIndexPath,
+  getTrailOfBitsCacheDir,
+} from "./cache-paths"
 export { deepMerge } from "./deep-merge"
 export {
   type ConfigFileInfo,

package/src/shared/key-tools.ts

@@ -0,0 +1,39 @@
+/**
+ * Canonical list of key audit tools and mappings used by the reporting gate
+ * and report preflight to determine which tools must complete before report
+ * generation is allowed.
+ */
+
+/** Maps full tool names to short names used in the reporting gate. */
+export const TOOL_SHORT_NAMES: Record<string, string> = {
+  argus_slither_analyze: "slither",
+  argus_forge_test: "forge-test",
+  argus_check_patterns: "patterns",
+  argus_solodit_search: "solodit",
+  argus_analyze_contract: "analyzer",
+}
+
+/** The short names of tools that must complete before report generation. */
+export const KEY_TOOLS = ["slither", "forge-test", "patterns", "solodit", "analyzer"]
+
+/** Maps unavailable-tool short names to their KEY_TOOLS counterpart. */
+export const UNAVAILABLE_TO_KEY_TOOL: Record<string, string> = {
+  slither: "slither",
+  forge: "forge-test",
+  solodit: "solodit",
+}
+
+/**
+ * Compute which key tools have not yet been executed, excusing any that are
+ * declared unavailable.
+ */
+export function computeMissingKeyTools(
+  toolsExecuted: Array<{ tool: string }>,
+  unavailableTools?: string[],
+): string[] {
+  const executedShortNames = new Set(toolsExecuted.map((t) => TOOL_SHORT_NAMES[t.tool] ?? t.tool))
+  const excused = new Set(
+    (unavailableTools ?? []).map((t) => UNAVAILABLE_TO_KEY_TOOL[t]).filter(Boolean),
+  )
+  return KEY_TOOLS.filter((t) => !executedShortNames.has(t) && !excused.has(t))
+}

package/src/shared/logger.ts

@@ -1,6 +1,5 @@
 import { appendFileSync, existsSync, mkdirSync } from "node:fs"
-import { homedir } from "node:os"
-import { join } from "node:path"
+import { getArgusLogDir, getArgusLogFile } from "./cache-paths"
 
 export interface LoggerConfig {
   debug?: boolean
@@ -15,12 +14,13 @@ export interface Logger {
 
 type LogSink = (line: string) => void
 
-const LOG_DIR = join(homedir(), ".cache", "solidity-argus")
-const LOG_FILE = join(LOG_DIR, "argus.log")
+const LOG_DIR = getArgusLogDir()
+const LOG_FILE = getArgusLogFile()
 
 function ensureLogDir(): void {
-  if (!existsSync(LOG_DIR)) {
-    mkdirSync(LOG_DIR, { recursive: true })
+  const logDir = getArgusLogDir()
+  if (!existsSync(logDir)) {
+    mkdirSync(logDir, { recursive: true })
   }
 }
 
@@ -51,7 +51,7 @@ function createFileSink(): LogSink {
       dirReady = true
     }
     try {
-      appendFileSync(LOG_FILE, line)
+      appendFileSync(getArgusLogFile(), line)
     } catch {
       // if we can't write logs, we don't crash the plugin
     }

package/src/shared/path-containment.ts

@@ -0,0 +1,25 @@
+import { relative, resolve } from "node:path"
+
+export function isContained(child: string, root: string): boolean {
+  const resolvedChild = resolve(root, child)
+  const resolvedRoot = resolve(root)
+  const rel = relative(resolvedRoot, resolvedChild)
+  return !rel.startsWith("..")
+}
+
+export function assertContained(child: string, root: string): string {
+  const resolvedChild = resolve(root, child)
+  if (!isContained(resolvedChild, root)) {
+    throw new Error(`Path "${child}" resolves outside project root "${root}"`)
+  }
+  return resolvedChild
+}
+
+export function validateUrlScheme(url: string): boolean {
+  try {
+    const parsed = new URL(url)
+    return parsed.protocol === "http:" || parsed.protocol === "https:"
+  } catch {
+    return false
+  }
+}

package/src/shared/path-utils.ts

@@ -0,0 +1,11 @@
+import { isAbsolute, normalize, relative } from "node:path"
+
+export function normalizeFilePath(filePath: string, projectDir: string): string {
+  if (!filePath) return ""
+  const normalized = normalize(filePath)
+  if (isAbsolute(normalized)) {
+    const rel = relative(projectDir, normalized)
+    return rel.startsWith("..") ? normalized : rel
+  }
+  return normalized.replace(/^\.\//, "")
+}

package/src/shared/report-path-resolver.ts

@@ -37,11 +37,12 @@ export function formatReportDate(date: Date): string {
 }
 
 export function sanitizeContractName(name: string): string {
-  return name
+  const sanitized = name
     .replace(/\s+/g, "-")
     .replace(/[^a-zA-Z0-9-]/g, "")
     .replace(/-+/g, "-")
     .replace(/^-|-$/g, "")
+  return sanitized || "unnamed-contract"
 }
 
 export function resolveReportPath(options: ReportPathOptions): ResolvedReportPath {
@@ -57,7 +58,8 @@ export function resolveReportPath(options: ReportPathOptions): ResolvedReportPat
   const resolvedDate = date ?? new Date()
   const dateStr = formatReportDate(resolvedDate)
   const sanitizedName = sanitizeContractName(contractName)
-  const filename = `${sanitizedName}-security-audit-${dateStr}.md`
+  const runIdSuffix = runId ? `-${runId.substring(0, 8)}` : ""
+  const filename = `${sanitizedName}-security-audit-${dateStr}${runIdSuffix}.md`
   const filePath = join(outputDir, filename)
   const canonicalId = runId ?? filename
 

package/src/shared/safe-emit.ts

@@ -0,0 +1,24 @@
+import type { EventSink } from "../features/persistent-state/event-sink"
+import type { AuditEvent } from "../state/schemas"
+import { formatError } from "./format-error"
+import { createLogger } from "./logger"
+
+const logger = createLogger()
+
+export async function safeEmitToSink(
+  sink: EventSink | null,
+  event: AuditEvent,
+  options?: { failFast?: boolean },
+): Promise<void> {
+  if (!sink) return
+  try {
+    await sink.append(event)
+  } catch (error) {
+    const message = `Failed to emit ${event.type} event to sink: ${formatError(error)}`
+    logger.error(message)
+
+    if (options?.failFast) {
+      throw new Error(message)
+    }
+  }
+}

package/src/shared/token-utils.ts

@@ -0,0 +1,5 @@
+const CHARS_PER_TOKEN = 4
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN)
+}

package/src/shared/type-guards.ts

@@ -0,0 +1,8 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/** Type guard: returns true when value is a non-empty string (after trimming). */
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0
+}

package/src/shared/validation-constants.ts

@@ -0,0 +1,52 @@
+import type { ArgusAgentName, Finding, FindingSeverity } from "../state/types"
+import { ARGUS_FAMILY } from "./agent-names"
+
+export function countBySeverity(findings: Finding[]): Record<FindingSeverity, number> {
+  const counts: Record<FindingSeverity, number> = {
+    Critical: 0,
+    High: 0,
+    Medium: 0,
+    Low: 0,
+    Informational: 0,
+  }
+  for (const finding of findings) {
+    counts[finding.severity]++
+  }
+  return counts
+}
+
+export const VALID_SEVERITIES: ReadonlySet<FindingSeverity> = new Set([
+  "Critical",
+  "High",
+  "Medium",
+  "Low",
+  "Informational",
+])
+
+export const VALID_CONFIDENCES: ReadonlySet<Finding["confidence"]> = new Set([
+  "High",
+  "Medium",
+  "Low",
+])
+
+export const VALID_SOURCES: ReadonlySet<Finding["source"]> = new Set([
+  "slither",
+  "manual",
+  "pattern",
+  "scvd",
+  "solodit",
+  "fuzz",
+])
+
+export const VALID_AGENTS: ReadonlySet<ArgusAgentName> = new Set([
+  ...ARGUS_FAMILY,
+  "unknown",
+] as ArgusAgentName[])
+
+export const SEVERITY_RANK: Record<FindingSeverity, number> = {
+  Critical: 0,
+  High: 1,
+  Medium: 2,
+  Low: 3,
+  Informational: 4,
+}