solidity-argus 0.1.0

package/src/knowledge/scvd-sync.ts

@@ -0,0 +1,85 @@
+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;
+}
+
+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,
+  };
+}
+
+export async function syncAll(client: ScvdClient, indexPath: string): Promise<SyncResult> {
+  try {
+    const findings = await client.fetchAllFindings();
+    const index = buildIndex(findings);
+    await saveIndex(index, indexPath);
+
+    return {
+      success: true,
+      newFindings: findings.length,
+      totalIndexed: index.totalFindings,
+      lastSync: index.lastSync,
+    };
+  } catch (error) {
+    return buildErrorResult(error);
+  }
+}
+
+export async function syncIncremental(
+  client: ScvdClient,
+  indexPath: string
+): Promise<SyncResult> {
+  try {
+    const [stats, existingIndex] = await Promise.all([
+      client.fetchStats(),
+      loadIndex(indexPath),
+    ]);
+
+    if (existingIndex && existingIndex.totalFindings === stats.total) {
+      return {
+        success: true,
+        newFindings: 0,
+        totalIndexed: existingIndex.totalFindings,
+        lastSync: existingIndex.lastSync,
+      };
+    }
+
+    return await syncAll(client, indexPath);
+  } catch (error) {
+    return buildErrorResult(error);
+  }
+}
+
+export async function getSyncStatus(indexPath: string): Promise<{
+  lastSync: string | null;
+  totalFindings: number;
+  healthy: boolean;
+}> {
+  const index = await loadIndex(indexPath);
+
+  if (!index) {
+    return {
+      lastSync: null,
+      totalFindings: 0,
+      healthy: false,
+    };
+  }
+
+  return {
+    lastSync: index.lastSync,
+    totalFindings: index.totalFindings,
+    healthy: true,
+  };
+}

package/src/managers/index.ts

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

package/src/managers/types.ts

@@ -0,0 +1,85 @@
+import type { AuditState } from "../state/types";
+
+/**
+ * BackgroundManager interface
+ * Handles dispatching and managing background agent tasks
+ */
+export interface BackgroundManager {
+  /**
+   * Dispatch an agent task to run in the background
+   * @param agentName - Name of the agent to dispatch (e.g., "sentinel", "pythia")
+   * @param prompt - The prompt/instruction for the agent
+   * @param options - Optional configuration (priority, timeout, etc.)
+   * @returns taskId - Unique identifier for tracking this task
+   */
+  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;
+
+  /**
+   * 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>;
+
+  /**
+   * 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;
+
+  /**
+   * Get the number of currently active/running tasks
+   * @returns Number of active tasks
+   */
+  getActiveCount(): number;
+}
+
+/**
+ * AuditStateManager interface
+ * Handles persistence and retrieval of audit state
+ */
+export interface AuditStateManager {
+  /**
+   * Load audit state from persistent storage
+   * @returns Promise resolving to AuditState or null if not found
+   */
+  load(): Promise<AuditState | null>;
+
+  /**
+   * Save audit state to persistent storage
+   * @param state - The AuditState to persist
+   */
+  save(state: AuditState): Promise<void>;
+
+  /**
+   * Get the current in-memory audit state
+   * @returns The current AuditState or null if not loaded
+   */
+  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>;
+
+  /**
+   * Reset the audit state (clear all data)
+   */
+  reset(): Promise<void>;
+}
+
+/**
+ * Managers type
+ * Container for all manager instances
+ */
+export type Managers = {
+  backgroundManager: BackgroundManager;
+  auditStateManager: AuditStateManager;
+};

package/src/plugin-interface.ts

@@ -0,0 +1,38 @@
+import type { Hooks as PluginHooks, ToolDefinition } from "@opencode-ai/plugin"
+import type { Hooks } from "./create-hooks"
+
+export type PluginReturn = {
+  tool: Record<string, ToolDefinition>
+} & Partial<Omit<PluginHooks, "tool">>
+
+export function createPluginInterface(args: {
+  tools: Record<string, ToolDefinition>
+  hooks: Hooks
+}): PluginReturn {
+  const { tools, hooks } = args
+
+  const result: PluginReturn = {
+    tool: tools,
+    config: hooks.config,
+  }
+
+  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"]) {
+    result["tool.execute.after"] = hooks["tool.execute.after"]
+  }
+
+  if (hooks.event) {
+    result.event = hooks.event
+  }
+
+  return result
+}

package/src/shared/binary-utils.ts

@@ -0,0 +1,63 @@
+import { execSync } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+export function hasBinary(name: string): boolean {
+  try {
+    execSync(`which ${name}`, { stdio: "ignore", timeout: 3_000 });
+    return true;
+  } catch (_e) {
+    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];
+  }
+
+  const solFiles = [target];
+  if (existsSync(target) && target.endsWith(".sol")) {
+    solFiles.push(target);
+  } else {
+    const srcDir = join(target, "src");
+    if (existsSync(srcDir)) {
+      try {
+        const files = execSync(`find "${srcDir}" -name "*.sol" -maxdepth 3`, {
+          encoding: "utf-8",
+          timeout: 5_000,
+        })
+          .trim()
+          .split("\n")
+          .filter(Boolean);
+        solFiles.push(...files);
+      } catch (_findErr) {
+      }
+    }
+  }
+
+  for (const file of solFiles) {
+    if (!existsSync(file) || !file.endsWith(".sol")) continue;
+    try {
+      const content = readFileSync(file, "utf-8");
+      const pragma = content.match(/pragma\s+solidity\s+[\^~>=<]*\s*([\d.]+)/);
+      if (pragma?.[1]) return pragma[1];
+    } catch (_readErr) {
+    }
+  }
+  return undefined;
+}
+
+export function extractContractNames(filePath: string): string[] {
+  if (!existsSync(filePath)) 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[];
+  } catch (_e) {
+    return [];
+  }
+}

package/src/shared/deep-merge.ts

@@ -0,0 +1,71 @@
+export function deepMerge(target: any, source: any): any {
+  // If source is undefined, return target as-is
+  if (source === undefined) {
+    return target;
+  }
+
+  // If either is not an object, return source (override)
+  if (
+    typeof target !== "object" ||
+    target === null ||
+    typeof source !== "object" ||
+    source === null
+  ) {
+    return source;
+  }
+
+  // If both are arrays, concatenate and deduplicate
+  if (Array.isArray(target) && Array.isArray(source)) {
+    const merged = [...target, ...source];
+    // Deduplicate by filtering unique values
+    return Array.from(new Set(merged));
+  }
+
+  // If target is array but source is not, return source
+  if (Array.isArray(target) && !Array.isArray(source)) {
+    return source;
+  }
+
+  // If source is array but target is not, return source
+  if (!Array.isArray(target) && Array.isArray(source)) {
+    return source;
+  }
+
+  // Both are plain objects, merge recursively
+  const result = { ...target };
+
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const sourceValue = source[key];
+
+      // Skip undefined values from source
+      if (sourceValue === undefined) {
+        continue;
+      }
+
+      // If both are objects (and not arrays), recurse
+      if (
+        typeof result[key] === "object" &&
+        result[key] !== null &&
+        !Array.isArray(result[key]) &&
+        typeof sourceValue === "object" &&
+        sourceValue !== null &&
+        !Array.isArray(sourceValue)
+      ) {
+        result[key] = deepMerge(result[key], sourceValue);
+      } else if (
+        Array.isArray(result[key]) &&
+        Array.isArray(sourceValue)
+      ) {
+        // Both are arrays, concatenate and deduplicate
+        const merged = [...result[key], ...sourceValue];
+        result[key] = Array.from(new Set(merged));
+      } else {
+        // Override with source value
+        result[key] = sourceValue;
+      }
+    }
+  }
+
+  return result;
+}

package/src/shared/file-utils.ts

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { stripJsoncComments } from "./jsonc-parser";
+
+export type ConfigFormat = "json" | "jsonc" | "none";
+
+export interface ConfigFileInfo {
+  path: string | null;
+  format: ConfigFormat;
+}
+
+export function detectConfigFile(basePath: string): ConfigFileInfo {
+  const candidates = [
+    { path: join(basePath, ".opencode", "solidity-argus.jsonc"), format: "jsonc" as const },
+    { path: join(basePath, ".opencode", "solidity-argus.json"), format: "json" as const },
+    { path: join(basePath, "solidity-argus.jsonc"), format: "jsonc" as const },
+    { path: join(basePath, "solidity-argus.json"), format: "json" as const },
+    { path: join(basePath, "config.jsonc"), format: "jsonc" as const },
+    { path: join(basePath, "config.json"), format: "json" as const },
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate.path)) {
+      return {
+        path: candidate.path,
+        format: candidate.format,
+      };
+    }
+  }
+
+  return {
+    path: null,
+    format: "none",
+  };
+}
+
+export function readJsoncFile(filePath: string): Record<string, any> | null {
+  try {
+    if (!existsSync(filePath)) {
+      return null;
+    }
+
+    const content = readFileSync(filePath, "utf-8");
+
+    if (!content.trim()) {
+      return null;
+    }
+
+    const stripped = stripJsoncComments(content);
+    const parsed = JSON.parse(stripped);
+
+    return parsed;
+  } catch (_error) {
+    return null;
+  }
+}

package/src/shared/index.ts

@@ -0,0 +1,5 @@
+export { createLogger, type Logger, type LoggerConfig } from "./logger";
+export { deepMerge } from "./deep-merge";
+export { stripJsoncComments } from "./jsonc-parser";
+export { detectConfigFile, readJsoncFile, type ConfigFormat, type ConfigFileInfo } from "./file-utils";
+export { hasBinary, parseSolcVersion, extractContractNames } from "./binary-utils";

package/src/shared/jsonc-parser.ts

@@ -0,0 +1,39 @@
+export function stripJsoncComments(jsonc: string): string {
+  let result = jsonc;
+
+  result = result.replace(/\/\*[\s\S]*?\*\//g, "");
+
+  const lines = result.split("\n");
+  result = lines
+    .map((line) => {
+      let inString = false;
+      let escaped = false;
+      let lastCommentIndex = -1;
+
+      for (let i = 0; i < line.length; i++) {
+        if (escaped) {
+          escaped = false;
+          continue;
+        }
+        if (line[i] === "\\") {
+          escaped = true;
+          continue;
+        }
+        if (line[i] === '"') {
+          inString = !inString;
+        }
+        if (!inString && line[i] === "/" && line[i + 1] === "/") {
+          lastCommentIndex = i;
+          break;
+        }
+      }
+
+      if (lastCommentIndex === -1) return line;
+      return line.substring(0, lastCommentIndex);
+    })
+    .join("\n");
+
+  result = result.replace(/,(\s*[}\]])/g, "$1");
+
+  return result;
+}

package/src/shared/logger.ts

@@ -0,0 +1,36 @@
+export interface LoggerConfig {
+  debug?: boolean;
+}
+
+export interface Logger {
+  info(...args: any[]): void;
+  debug(...args: any[]): void;
+  error(...args: any[]): void;
+  warn(...args: any[]): void;
+}
+
+export function createLogger(config: LoggerConfig = {}): Logger {
+  const { debug = false } = config;
+
+  const prefix = "[argus]";
+
+  return {
+    info(...args: any[]): void {
+      console.error(prefix, ...args);
+    },
+
+    debug(...args: any[]): void {
+      if (debug) {
+        console.error(prefix, ...args);
+      }
+    },
+
+    error(...args: any[]): void {
+      console.error(prefix, ...args);
+    },
+
+    warn(...args: any[]): void {
+      console.error(prefix, ...args);
+    },
+  };
+}

package/src/state/audit-state.ts

@@ -0,0 +1,27 @@
+import { randomUUID } from "crypto";
+import type { AuditState } from "./types";
+import { createFindingStore, type FindingStore } from "./finding-store";
+
+/**
+ * Factory function to create a new audit state instance (NOT singleton)
+ * Each call creates a fresh state with a unique session ID
+ */
+export function createAuditState(projectDir: string): {
+  state: AuditState;
+  store: FindingStore;
+} {
+  const state: AuditState = {
+    sessionId: randomUUID(),
+    projectDir,
+    contractsReviewed: [],
+    findings: [],
+    toolsExecuted: [],
+    currentPhase: "reconnaissance",
+    scope: [],
+    startTime: Date.now(),
+  };
+
+  const store = createFindingStore(state);
+
+  return { state, store };
+}

package/src/state/finding-store.ts

@@ -0,0 +1,126 @@
+import type { Finding, FindingSeverity, AuditState } from "./types";
+import { createHash } from "crypto";
+
+export interface FindingStore {
+  addFinding(finding: Omit<Finding, "id">): Finding;
+  getFindings(filter?: {
+    severity?: FindingSeverity;
+    source?: Finding["source"];
+  }): Finding[];
+  hasFinding(check: string, file: string, lines: [number, number]): boolean;
+  serialize(): string;
+}
+
+/**
+ * Creates a finding store with deduplication by check+file+lines
+ * Deduplication key: `${check}:${file}:${lines[0]}-${lines[1]}`
+ */
+export function createFindingStore(state: AuditState): FindingStore {
+  const findingMap = new Map<string, Finding>();
+
+  function generateId(
+    check: string,
+    file: string,
+    lines: [number, number]
+  ): string {
+    const key = `${check}:${file}:${lines[0]}-${lines[1]}`;
+    // Use deterministic hash for stable IDs
+    return createHash("sha256").update(key).digest("hex").substring(0, 16);
+  }
+
+  function addFinding(finding: Omit<Finding, "id">): Finding {
+    const id = generateId(finding.check, finding.file, finding.lines);
+
+    // Check if finding already exists (deduplication)
+    if (findingMap.has(id)) {
+      return findingMap.get(id)!;
+    }
+
+    const newFinding: Finding = {
+      ...finding,
+      id,
+    };
+
+    findingMap.set(id, newFinding);
+    state.findings.push(newFinding);
+
+    return newFinding;
+  }
+
+  function getFindings(filter?: {
+    severity?: FindingSeverity;
+    source?: Finding["source"];
+  }): Finding[] {
+    if (!filter) {
+      return Array.from(findingMap.values());
+    }
+
+    return Array.from(findingMap.values()).filter((finding) => {
+      if (filter.severity && finding.severity !== filter.severity) {
+        return false;
+      }
+      if (filter.source && finding.source !== filter.source) {
+        return false;
+      }
+      return true;
+    });
+  }
+
+  function hasFinding(
+    check: string,
+    file: string,
+    lines: [number, number]
+  ): boolean {
+    const id = generateId(check, file, lines);
+    return findingMap.has(id);
+  }
+
+  function serialize(): string {
+    const findings = Array.from(findingMap.values());
+    const contractCount = state.contractsReviewed.length;
+    const findingCount = findings.length;
+
+    // Count by severity
+    const severityCounts: Record<FindingSeverity, number> = {
+      Critical: 0,
+      High: 0,
+      Medium: 0,
+      Low: 0,
+      Informational: 0,
+    };
+
+    findings.forEach((finding) => {
+      severityCounts[finding.severity]++;
+    });
+
+    // Build severity string
+    const severityParts: string[] = [];
+    if (severityCounts.Critical > 0) {
+      severityParts.push(`${severityCounts.Critical} Critical`);
+    }
+    if (severityCounts.High > 0) {
+      severityParts.push(`${severityCounts.High} High`);
+    }
+    if (severityCounts.Medium > 0) {
+      severityParts.push(`${severityCounts.Medium} Medium`);
+    }
+    if (severityCounts.Low > 0) {
+      severityParts.push(`${severityCounts.Low} Low`);
+    }
+    if (severityCounts.Informational > 0) {
+      severityParts.push(`${severityCounts.Informational} Informational`);
+    }
+
+    const severityStr =
+      severityParts.length > 0 ? ` (${severityParts.join(", ")})` : "";
+
+    return `Contracts: ${contractCount}, Findings: ${findingCount}${severityStr}, Phase: ${state.currentPhase}`;
+  }
+
+  return {
+    addFinding,
+    getFindings,
+    hasFinding,
+    serialize,
+  };
+}

package/src/state/plugin-state.ts

@@ -0,0 +1,14 @@
+import type { ArgusConfig } from "../config/types";
+import type { Managers } from "../managers/types";
+
+/**
+ * PluginState interface
+ * Represents the complete state of the Argus plugin instance
+ * Includes configuration, project context, and manager instances
+ */
+export interface PluginState {
+  config: ArgusConfig;
+  projectDir: string;
+  managers: Managers;
+  isHookEnabled: (name: string) => boolean;
+}