solidity-argus 0.1.0

package/src/agents/sentinel-prompt.ts

@@ -0,0 +1,133 @@
+
+export const SENTINEL_PROMPT = `You are **Sentinel**, the Tactical Guardian — a specialized subagent of Argus Panoptes. You are the "hands" of the audit, responsible for rigorous execution, static analysis, and dynamic verification. While Argus strategizes, you hunt.
+
+## IDENTITY & ROLE
+
+You combine the precision of a static analyzer with the creativity of a white-hat hacker. You do not just run tools; you interpret their output, filter false positives, and prove vulnerabilities through code.
+
+Your core responsibilities are:
+1.  **Static Analysis**: Scanning codebases for known vulnerabilities and code quality issues.
+2.  **Pattern Matching**: Identifying complex vulnerability patterns that standard tools miss.
+3.  **Dynamic Testing**: Writing and executing tests to reproduce bugs (Proof of Concept).
+4.  **Fuzzing**: Stress-testing logic with random inputs to find edge cases.
+
+## WORKFLOW
+
+You operate in a loop of **Scan -> Analyze -> Verify**.
+
+1.  **Broad Scan**:
+    - Start with \`argus_slither_analyze\` to get a high-level overview of potential issues.
+    - Use \`argus_check_patterns\` to scan for specific dangerous patterns (e.g., read-only reentrancy).
+
+2.  **Deep Analysis**:
+    - For interesting contracts, use \`argus_analyze_contract\` to understand their structure, inheritance, and risk indicators.
+    - Manually review the code highlighted by Slither or pattern checks.
+
+3.  **Targeted Verification**:
+    - If you suspect a bug, write a reproduction test case.
+    - Use \`argus_forge_test\` to run this test.
+    - If the logic is complex (e.g., math, state transitions), use \`argus_forge_fuzz\` to hammer it with inputs.
+
+4.  **Reporting**:
+    - Format your findings strictly according to the Output Format section.
+    - Report back to Argus with confirmed findings.
+
+## TOOL USAGE GUIDE
+
+You have access to a specific set of tools. Use them effectively.
+
+### 1. \`argus_slither_analyze\`
+**Purpose**: Fast, broad static analysis.
+**When to use**: At the start of an engagement or when analyzing a new file.
+**Arguments**:
+- \`target\` (string): Path to the directory (e.g., ".") or specific file.
+- \`detectors\` (string[]): Optional list of specific detectors to run.
+- \`exclude\` (string[]): Optional list of detectors to ignore.
+**Interpretation**:
+- Slither produces many false positives. **Verify every finding.**
+- Look for "High" impact issues first, but don't ignore "Informational" ones—they often hint at sloppy coding practices.
+
+### 2. \`argus_analyze_contract\`
+**Purpose**: Structural profiling of a contract.
+**When to use**: Before writing tests or when you need to understand inheritance and state variables.
+**Arguments**:
+- \`file_path\` (string): The absolute or relative path to the .sol file.
+**Interpretation**:
+- Use the output to map out the "Attack Surface".
+- Pay attention to \`riskIndicators\` (e.g., \`uses-delegatecall\`, \`uses-assembly\`).
+
+### 3. \`argus_check_patterns\`
+**Purpose**: Regex-based pattern matching for specific vulnerabilities.
+**When to use**: To find issues that Slither might miss, or to check for specific attack vectors (e.g., "reentrancy", "access-control").
+**Arguments**:
+- \`target\` (string): Path to file or directory.
+- \`patterns\` (string[]): Optional list of pattern categories.
+**Interpretation**:
+- These are raw matches. Context is everything. A match for \`tx.origin\` is only a bug if used for authorization.
+
+### 4. \`argus_forge_test\`
+**Purpose**: Run Foundry tests to confirm vulnerabilities.
+**When to use**: To prove a bug exists (PoC) or to verify a fix.
+**Arguments**:
+- \`target\` (string): Path to the test file or directory (default ".").
+- \`match_test\` (string): Name of the specific test function to run (e.g., "testExploit"). **Crucial for speed.**
+- \`match_contract\` (string): Name of the contract to test.
+- \`verbosity\` (number): 1-5. Use 3 or 4 to see traces.
+**Interpretation**:
+- If the test passes (and it was meant to fail/exploit), the bug might not exist, or the test is wrong.
+- Analyze the stack trace in the output to understand *why* it reverted.
+
+### 5. \`argus_forge_fuzz\`
+**Purpose**: Property-based testing (fuzzing).
+**When to use**: For arithmetic, complex state transitions, or invariant checking.
+**Arguments**:
+- \`target\` (string): Path to test file.
+- \`match_test\` (string): The fuzz test function (must have arguments).
+- \`runs\` (number): Number of runs (default 256). Increase to 1000+ for deep bugs.
+**Interpretation**:
+- Look at the \`counterexamples\`. They tell you exactly what inputs broke the code.
+
+## OUTPUT FORMAT
+
+Return your findings to Argus in this structured Markdown format. Do not deviate.
+
+\`\`\`markdown
+## Finding: [SEVERITY] {Title}
+**Severity**: {Critical|High|Medium|Low|Informational}
+**Location**: {File}:{StartLine}-{EndLine}
+**Description**:
+{Clear explanation of the vulnerability. How does it happen? Why is it bad?}
+
+**Impact**:
+{Specific impact: Loss of funds, frozen funds, broken access control, etc.}
+
+**Proof of Concept**:
+{Describe the steps or provide the test code used to verify this.}
+
+**Recommendation**:
+{How to fix it. Be specific (e.g., "Add a reentrancy guard", "Use SafeMath").}
+\`\`\`
+
+## ESCALATION & FALLBACK
+
+1.  **Escalation**:
+    - If you find a **Critical** vulnerability (e.g., direct fund theft), stop and report it immediately.
+    - If you are unsure if a behavior is a bug or a feature, flag it as "Needs Review" and describe the ambiguity.
+
+2.  **Fallback Procedures**:
+    - **Slither fails**: It happens. Fall back to \`argus_analyze_contract\` and read the code manually. Use \`argus_check_patterns\` to catch low-hanging fruit.
+    - **Forge fails**: If you cannot run tests (e.g., compilation errors in the project), rely on "Mental Execution". Trace the code logic step-by-step in your analysis. State clearly: "Verified via manual analysis (tests unavailable)."
+
+## EXECUTION MINDSET
+
+- **Trust Code, Not Comments**: Comments often lie or are outdated. Read the implementation.
+- **Think Adversarially**: How would *you* break this?
+- **Verify Assumptions**: Does that modifier actually do what it says? Is that external call safe?
+- **Be Precise**: A vague finding is useless. Point to the line, the variable, the specific interaction.
+
+You are the Sentinel. The code cannot hide its secrets from you.
+`;
+
+export function getSentinelPrompt(): string {
+  return SENTINEL_PROMPT;
+}

package/src/cli/cli-program.ts

@@ -0,0 +1,67 @@
+import type { CliCommand } from "./types";
+
+const HELP_TEXT = `argus — Solidity Security Auditor for OpenCode
+
+Commands:
+  doctor   Check Slither/Foundry installation and config health
+  init     Create solidity-argus config file
+  install  Configure argus plugin in opencode config
+`;
+
+export class CliProgram {
+  private commands: Map<string, CliCommand> = new Map();
+
+  registerCommand(command: CliCommand): void {
+    this.commands.set(command.name, command);
+  }
+
+  async dispatch(args: string[]): Promise<number> {
+    const subcommand = args[0];
+
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+      console.log(HELP_TEXT);
+      return 0;
+    }
+
+    const command = this.commands.get(subcommand);
+    if (!command) {
+      console.error(`Error: Unknown command '${subcommand}'. Run 'argus' for help.`);
+      return 1;
+    }
+
+    return command.execute(args.slice(1));
+  }
+}
+
+export function createCliProgram(): CliProgram {
+  const program = new CliProgram();
+
+  program.registerCommand({
+    name: "doctor",
+    description: "Check Slither/Foundry installation and config health",
+    execute: async () => {
+      console.log("argus doctor: not yet implemented");
+      return 0;
+    },
+  });
+
+  program.registerCommand({
+    name: "init",
+    description: "Create solidity-argus config file",
+    execute: async () => {
+      console.log("argus init: not yet implemented");
+      return 0;
+    },
+  });
+
+  program.registerCommand({
+    name: "install",
+    description: "Configure argus plugin in opencode config",
+    execute: async () => {
+      console.log("argus install: not yet implemented");
+      return 0;
+    },
+  });
+
+  return program;
+}

package/src/cli/commands/doctor.ts

@@ -0,0 +1,83 @@
+import { execSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import type { CliCommand } from "../types"
+import { loadArgusConfig } from "../../config/loader"
+
+const GREEN = "\x1b[32m"
+const RED = "\x1b[31m"
+const YELLOW = "\x1b[33m"
+const RESET = "\x1b[0m"
+
+function checkBinary(name: string): { found: boolean; version: string | null } {
+  try {
+    const version = execSync(`${name} --version`, { timeout: 5000 })
+      .toString()
+      .trim()
+      .split("\n")[0] ?? null
+    return { found: true, version }
+  } catch {
+    return { found: false, version: null }
+  }
+}
+
+function checkSolidityProject(dir: string): string | null {
+  if (existsSync(join(dir, "foundry.toml"))) return "foundry"
+  if (existsSync(join(dir, "hardhat.config.js"))) return "hardhat"
+  if (existsSync(join(dir, "hardhat.config.ts"))) return "hardhat"
+  return null
+}
+
+export const doctorCommand: CliCommand = {
+  name: "doctor",
+  description: "Check tool dependencies and configuration",
+  async execute(args: string[]): Promise<number> {
+    const cwd = process.cwd()
+    let hasFailure = false
+
+    console.log("Argus Doctor\n")
+
+    const slither = checkBinary("slither")
+    if (slither.found) {
+      console.log(`${GREEN}✓${RESET} Slither: installed (${slither.version})`)
+    } else {
+      console.log(`${RED}✗${RESET} Slither: not found — pip install slither-analyzer`)
+      hasFailure = true
+    }
+
+    const forge = checkBinary("forge")
+    if (forge.found) {
+      console.log(`${GREEN}✓${RESET} Forge: installed (${forge.version})`)
+    } else {
+      console.log(`${RED}✗${RESET} Forge: not found — curl -L https://foundry.paradigm.xyz | bash`)
+      hasFailure = true
+    }
+
+    const projectType = checkSolidityProject(cwd)
+    if (projectType) {
+      console.log(`${GREEN}✓${RESET} Project: ${projectType} detected`)
+    } else {
+      console.log(`${YELLOW}⚠${RESET} Project: no Solidity project detected`)
+    }
+
+    try {
+      const config = loadArgusConfig(cwd)
+      console.log(`${GREEN}✓${RESET} Config: valid`)
+    } catch {
+      console.log(`${YELLOW}⚠${RESET} Config: using defaults`)
+    }
+
+    try {
+      const response = await fetch("https://api.scvd.dev", { signal: AbortSignal.timeout(5000) })
+      if (response.ok) {
+        console.log(`${GREEN}✓${RESET} SCVD API: reachable`)
+      } else {
+        console.log(`${YELLOW}⚠${RESET} SCVD API: returned ${response.status}`)
+      }
+    } catch {
+      console.log(`${YELLOW}⚠${RESET} SCVD API: unreachable`)
+    }
+
+    return hasFailure ? 1 : 0
+  },
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import type { CliCommand } from "../types"
+
+const GREEN = "\x1b[32m"
+const YELLOW = "\x1b[33m"
+const RESET = "\x1b[0m"
+
+const DEFAULT_CONFIG = {
+  agents: {},
+  tools: {},
+  knowledge: { scvd: { enabled: true }, autoSync: true },
+  reporting: { format: "markdown", severityThreshold: "low" },
+  solodit: { enabled: true },
+}
+
+export const initCommand: CliCommand = {
+  name: "init",
+  description: "Initialize Argus configuration for this project",
+  async execute(args: string[]): Promise<number> {
+    const cwd = process.cwd()
+    const configDir = join(cwd, ".opencode")
+    const configPath = join(configDir, "solidity-argus.json")
+
+    if (existsSync(configPath)) {
+      console.error(`${YELLOW}⚠${RESET} Config already exists: ${configPath}`)
+      console.error("  Remove it first if you want to reinitialize.")
+      return 1
+    }
+
+    mkdirSync(configDir, { recursive: true })
+    writeFileSync(configPath, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`)
+
+    const projectType = existsSync(join(cwd, "foundry.toml"))
+      ? "Foundry"
+      : existsSync(join(cwd, "hardhat.config.js")) || existsSync(join(cwd, "hardhat.config.ts"))
+        ? "Hardhat"
+        : "unknown"
+
+    console.log(`${GREEN}✓${RESET} Created ${configPath}`)
+    console.log(`  Project type: ${projectType}`)
+    console.log("  Run 'argus doctor' to check dependencies.")
+
+    return 0
+  },
+}

package/src/cli/commands/install.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { homedir } from "node:os"
+import type { CliCommand } from "../types"
+
+const GREEN = "\x1b[32m"
+const YELLOW = "\x1b[33m"
+const RESET = "\x1b[0m"
+
+export function findOpencodeConfig(homeOverride?: string): string | null {
+  const cwd = process.cwd()
+  const localPath = join(cwd, "opencode.json")
+  if (existsSync(localPath)) return localPath
+
+  const home = homeOverride ?? homedir()
+  const globalPath = join(home, ".config", "opencode", "opencode.json")
+  if (existsSync(globalPath)) return globalPath
+
+  return null
+}
+
+export const installCommand: CliCommand = {
+  name: "install",
+  description: "Register solidity-argus in your OpenCode config",
+  async execute(args: string[]): Promise<number> {
+    const configPath = findOpencodeConfig()
+
+    if (!configPath) {
+      console.error(`${YELLOW}⚠${RESET} opencode.json not found`)
+      console.error("  Create one first, or run: opencode init")
+      return 1
+    }
+
+    try {
+      const content = readFileSync(configPath, "utf-8")
+      const config = JSON.parse(content)
+      const plugins: string[] = config.plugin ?? []
+
+      if (plugins.includes("solidity-argus")) {
+        console.log(`${GREEN}✓${RESET} solidity-argus already registered in ${configPath}`)
+        return 0
+      }
+
+      plugins.push("solidity-argus")
+      config.plugin = plugins
+      writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`)
+
+      console.log(`${GREEN}✓${RESET} Added solidity-argus to ${configPath}`)
+      return 0
+    } catch (error) {
+      console.error(`${YELLOW}⚠${RESET} Failed to update ${configPath}`)
+      return 1
+    }
+  },
+}

package/src/cli/index.ts

@@ -0,0 +1,13 @@
+import { createCliProgram } from "./cli-program";
+
+async function main(): Promise<void> {
+  const program = createCliProgram();
+  const args = Bun.argv.slice(2);
+  const exitCode = await program.dispatch(args);
+  process.exit(exitCode);
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/cli/tui-prompts.ts

@@ -0,0 +1,75 @@
+const NON_INTERACTIVE =
+  !process.stdin.isTTY || process.env.CI === "true" || process.env.ARGUS_NON_INTERACTIVE === "true"
+
+export async function confirm(message: string, defaultValue = true): Promise<boolean> {
+  if (NON_INTERACTIVE) return defaultValue
+
+  const hint = defaultValue ? "[Y/n]" : "[y/N]"
+  process.stdout.write(`${message} ${hint} `)
+
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => {
+      process.stdin.removeAllListeners("data")
+      resolve(defaultValue)
+    }, 30_000)
+
+    process.stdin.once("data", (data) => {
+      clearTimeout(timeout)
+      const input = data.toString().trim().toLowerCase()
+      if (input === "") resolve(defaultValue)
+      else resolve(input === "y" || input === "yes")
+    })
+  })
+}
+
+export async function select(
+  message: string,
+  options: string[],
+  defaultIndex = 0,
+): Promise<string> {
+  if (NON_INTERACTIVE) return options[defaultIndex] ?? options[0] ?? ""
+
+  console.log(message)
+  for (let i = 0; i < options.length; i++) {
+    const marker = i === defaultIndex ? ">" : " "
+    console.log(`  ${marker} ${i + 1}. ${options[i]}`)
+  }
+
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => {
+      process.stdin.removeAllListeners("data")
+      resolve(options[defaultIndex] ?? options[0] ?? "")
+    }, 30_000)
+
+    process.stdin.once("data", (data) => {
+      clearTimeout(timeout)
+      const input = data.toString().trim()
+      const num = parseInt(input, 10)
+      if (num >= 1 && num <= options.length) {
+        resolve(options[num - 1] ?? options[0] ?? "")
+      } else {
+        resolve(options[defaultIndex] ?? options[0] ?? "")
+      }
+    })
+  })
+}
+
+export async function text(message: string, defaultValue = ""): Promise<string> {
+  if (NON_INTERACTIVE) return defaultValue
+
+  const hint = defaultValue ? ` [${defaultValue}]` : ""
+  process.stdout.write(`${message}${hint}: `)
+
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => {
+      process.stdin.removeAllListeners("data")
+      resolve(defaultValue)
+    }, 30_000)
+
+    process.stdin.once("data", (data) => {
+      clearTimeout(timeout)
+      const input = data.toString().trim()
+      resolve(input || defaultValue)
+    })
+  })
+}

package/src/cli/types.ts

@@ -0,0 +1,9 @@
+/**
+ * CLI Command interface
+ * Defines the contract for all CLI subcommands
+ */
+export interface CliCommand {
+  name: string;
+  description: string;
+  execute: (args: string[]) => Promise<number>;
+}

package/src/config/index.ts

@@ -0,0 +1,3 @@
+export { ArgusConfigSchema } from "./schema"
+export type { ArgusConfig } from "./types"
+export { loadArgusConfig } from "./loader"

package/src/config/loader.ts

@@ -0,0 +1,36 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { ArgusConfigSchema } from "./schema"
+import type { ArgusConfig } from "./types"
+import { detectConfigFile, readJsoncFile } from "../shared/file-utils"
+import { deepMerge } from "../shared/deep-merge"
+import { createLogger } from "../shared/logger"
+
+export function _mergeConfigs(
+  userRaw: Record<string, unknown> | null,
+  projectRaw: Record<string, unknown> | null,
+): ArgusConfig {
+  const logger = createLogger()
+  const merged = deepMerge(userRaw ?? {}, projectRaw ?? {})
+
+  const result = ArgusConfigSchema.safeParse(merged)
+  if (!result.success) {
+    logger.warn("Invalid argus config, using defaults:", result.error.message)
+    return ArgusConfigSchema.parse({})
+  }
+
+  return result.data
+}
+
+export function loadArgusConfig(projectDir: string): ArgusConfig {
+  const userConfigDir = join(homedir(), ".config", "opencode")
+  const userConfigInfo = detectConfigFile(userConfigDir)
+  const userRaw = userConfigInfo.path ? readJsoncFile(userConfigInfo.path) : null
+
+  const projectConfigInfo = detectConfigFile(projectDir)
+  const projectRaw = projectConfigInfo.path
+    ? readJsoncFile(projectConfigInfo.path)
+    : null
+
+  return _mergeConfigs(userRaw, projectRaw)
+}

package/src/config/schema.ts

@@ -0,0 +1,82 @@
+import { z } from "zod"
+
+const AgentConfigSchema = z.object({
+  model: z.string().optional(),
+  permission: z.record(z.string(), z.any()).optional(),
+  tools: z.record(z.string(), z.boolean()).optional(),
+})
+
+const ToolsConfigSchema = z.object({
+  slitherPath: z.string().optional(),
+  forgePath: z.string().optional(),
+})
+
+const ScvdConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  apiUrl: z.string().default("https://api.scvd.dev"),
+})
+
+const KnowledgeConfigSchema = z.object({
+  scvd: ScvdConfigSchema.default({
+    enabled: true,
+    apiUrl: "https://api.scvd.dev",
+  }),
+  autoSync: z.boolean().default(true),
+  customSkillsDir: z.string().optional(),
+})
+
+const ReportingConfigSchema = z.object({
+  format: z.enum(["markdown"]).default("markdown"),
+  severityThreshold: z
+    .enum(["critical", "high", "medium", "low", "informational"])
+    .default("low"),
+  gasAnalysis: z.boolean().default(false),
+})
+
+const SolditConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  port: z.number().default(3000),
+})
+
+const BackgroundConfigSchema = z.object({
+  max_concurrent: z.number().positive().default(3),
+})
+
+export const ArgusConfigSchema = z.object({
+  agents: z
+    .object({
+      argus: AgentConfigSchema.default({}),
+      sentinel: AgentConfigSchema.default({}),
+      pythia: AgentConfigSchema.default({}),
+      scribe: AgentConfigSchema.default({}),
+    })
+    .default({
+      argus: {},
+      sentinel: {},
+      pythia: {},
+      scribe: {},
+    }),
+  tools: ToolsConfigSchema.default({}),
+  knowledge: KnowledgeConfigSchema.default({
+    scvd: {
+      enabled: true,
+      apiUrl: "https://api.scvd.dev",
+    },
+    autoSync: true,
+  }),
+  reporting: ReportingConfigSchema.default({
+    format: "markdown",
+    severityThreshold: "low",
+    gasAnalysis: false,
+  }),
+  solodit: SolditConfigSchema.default({
+    enabled: true,
+    port: 3000,
+  }),
+  disabled_hooks: z.array(z.string()).default([]),
+  hooks: z.record(z.string(), z.any()).default({}),
+  cli: z.record(z.string(), z.any()).default({}),
+  background: BackgroundConfigSchema.default({
+    max_concurrent: 3,
+  }),
+})

package/src/config/types.ts

@@ -0,0 +1,4 @@
+import { z } from "zod"
+import { ArgusConfigSchema } from "./schema"
+
+export type ArgusConfig = z.infer<typeof ArgusConfigSchema>

package/src/constants/defaults.ts

@@ -0,0 +1,6 @@
+export const DEFAULT_MODELS = {
+  argus: "anthropic/claude-opus-4-6",
+  sentinel: "anthropic/claude-sonnet-4-6",
+  pythia: "anthropic/claude-sonnet-4-6",
+  scribe: "anthropic/claude-sonnet-4-6",
+} as const