@owasp-aghast/aghast 0.8.0-beta.0

package/dist/index.js

@@ -0,0 +1,754 @@
+/**
+ * CLI entry point for aghast.
+ * Usage: aghast scan <repository-path> --config-dir <path> [options]
+ */
+import 'dotenv/config';
+import { readFile, writeFile, stat, mkdir, readdir } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { runMultiScanWithCost } from './scan-runner.js';
+import { loadDefaultPricing, mergePricing, formatCostSourceLabel } from './cost-calculator.js';
+import { saveScanRecord, queryScanHistory } from './scan-history.js';
+import { createProviderByName, getProviderNames, DEFAULT_PROVIDER_NAME } from './provider-registry.js';
+import { loadCheckRegistry, discoverCheckFolders, resolveChecks, filterChecksForRepository, validateCheck, loadCheckDetails, } from './check-library.js';
+import { analyzeRepository } from './repository-analyzer.js';
+import { loadRuntimeConfig } from './runtime-config.js';
+import { logProgress, logDebug, setLogLevel, createTimer, isValidLogLevel, initFileHandler, closeAllHandlers, getAvailableLogTypes } from './logging.js';
+import { MOCK_MODEL_NAME, DEFAULT_MODEL } from './types.js';
+import { getFormatter } from './formatters/index.js';
+import { verifySemgrepInstalled } from './semgrep-runner.js';
+import { verifyOpenAntInstalled } from './openant-runner.js';
+import { MockAgentProvider } from './mock-agent-provider.js';
+import { ERROR_CODES, formatError, formatFatalError } from './error-codes.js';
+import { DEFAULT_OUTPUT_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_LOG_TYPE } from './defaults.js';
+import { colorStatus } from './colors.js';
+import { getCheckType } from './check-types.js';
+import { getDiscovery, getRegisteredDiscoveries } from './discovery.js';
+import { createRequire } from 'node:module';
+const TAG = 'aghast';
+async function createMockProvider() {
+    // AGHAST_MOCK_AI='true' → default empty response; AGHAST_MOCK_AI=<path> → read from that file
+    const mockAiValue = process.env.AGHAST_MOCK_AI;
+    let rawResponse = '{"issues": []}';
+    if (mockAiValue && mockAiValue !== 'true') {
+        try {
+            rawResponse = await readFile(resolve(mockAiValue), 'utf-8');
+        }
+        catch (err) {
+            throw new Error(`Failed to read AGHAST_MOCK_AI response file: ${mockAiValue}`, { cause: err });
+        }
+    }
+    // Optional mock token usage for testing cost/budget pipelines.
+    // Format: AGHAST_MOCK_TOKENS="<input>,<output>" (e.g. "1000,500")
+    // When AGHAST_LOCAL_CLAUDE=true, inject a mock reportedCost so that the
+    // coveredBySubscription path (banner "equivalent", label) is exercisable in tests.
+    let tokenUsage;
+    const mockTokensRaw = process.env.AGHAST_MOCK_TOKENS;
+    if (mockTokensRaw) {
+        const parts = mockTokensRaw.split(',').map((s) => Number(s.trim()));
+        if (parts.length === 2 && parts.every((n) => Number.isFinite(n) && n >= 0)) {
+            const useLocalClaude = process.env.AGHAST_LOCAL_CLAUDE === 'true';
+            tokenUsage = {
+                inputTokens: parts[0],
+                outputTokens: parts[1],
+                totalTokens: parts[0] + parts[1],
+                ...(useLocalClaude ? {
+                    reportedCost: {
+                        amountUsd: (parts[0] + parts[1]) / 1_000_000,
+                        source: 'claude-agent-sdk',
+                        coveredBySubscription: true,
+                    },
+                } : {}),
+            };
+        }
+    }
+    const provider = new MockAgentProvider({ rawResponse, tokenUsage });
+    await provider.initialize({});
+    return provider;
+}
+const SCAN_HELP = `Usage: aghast scan <repo-path> --config-dir <path> [options]
+
+Run security checks against a repository.
+
+Arguments:
+  <repo-path>                Path to the repository to scan
+
+General options:
+  --config-dir <path>        Config directory containing checks-config.json,
+                             checks/ folder, and optionally runtime-config.json.
+                             Required unless AGHAST_CONFIG_DIR is set.
+  --output <path>            Output file path for results
+                             (default: <repo-path>/security_checks_results.<ext>)
+  --output-format json|sarif Output format (default: json)
+  --fail-on-check-failure    Exit with code 1 if any check FAILs or ERRORs
+  --debug                    Shorthand for --log-level debug
+  --log-level <level>        Console log level: error, warn, info, debug, trace
+                             (default: info)
+  --log-file <path>          Write all log output to a file (always at trace level
+                             unless overridden by --log-type)
+  --log-type <type>          Log file handler type (default: file).
+                             Available types: file
+  --model <model>            AI model override (e.g. claude-sonnet-4-20250514)
+  --agent-provider <name>    Agent provider name (default: claude-code)
+  --generic-prompt <file>    Generic prompt template filename in prompts/ dir
+  --diff-ref <ref>           Git ref to diff against (e.g. HEAD~1, main, SHA).
+                             Auto-activates diff filtering on every check whose
+                             discovery supports it, unless the check opts out
+                             via checkTarget.diffFilter: false.
+  --diff-file <path>         Path to pre-generated unified diff file
+                             (alternative to --diff-ref)
+  --budget-limit-cost <usd>  Abort the scan when accumulated cost exceeds this
+                             USD value. Warns at 80%, aborts at 100%
+  --budget-limit-tokens <n>  Abort the scan when accumulated tokens exceed n.
+                             Warns at 80%, aborts at 100%
+
+Environment variables:
+  ANTHROPIC_API_KEY           API key for Claude (required for AI-based checks)
+  AGHAST_CONFIG_DIR           Default config directory (CLI --config-dir takes precedence)
+  AGHAST_AI_MODEL             AI model override (CLI --model takes precedence)
+  AGHAST_GENERIC_PROMPT       Generic prompt template filename (CLI --generic-prompt takes precedence)
+  AGHAST_DEBUG                Set to "true" to enable debug output (same as --debug)
+  AGHAST_LOG_LEVEL            Console log level (CLI --log-level takes precedence)
+  AGHAST_LOG_FILE             Log file path (CLI --log-file takes precedence)
+  AGHAST_LOG_TYPE             Log file handler type (CLI --log-type takes precedence)
+  AGHAST_DIFF_REF             Git ref to diff against (CLI --diff-ref takes precedence)
+
+Examples:
+  aghast scan ./my-repo --config-dir ./my-checks
+  aghast scan ./my-repo --config-dir ./my-checks --output results.sarif --output-format sarif
+  aghast scan ./my-repo --config-dir ./my-checks --fail-on-check-failure --debug
+  aghast scan ./my-repo --config-dir ./my-checks --log-file scan.log --log-level warn
+  aghast scan ./my-repo --config-dir ./my-checks --model claude-sonnet-4-20250514`;
+function parseArgs(args) {
+    if (args.length < 1 || args[0] === '--help' || args[0] === '-h') {
+        console.log(SCAN_HELP);
+        process.exit(0);
+    }
+    // First positional arg is repo-path
+    const firstArg = args[0];
+    const repositoryPath = firstArg && !firstArg.startsWith('--') ? resolve(firstArg) : undefined;
+    const startIdx = repositoryPath ? 1 : 0;
+    let configDir;
+    let outputFormat;
+    let outputPath;
+    const failOnCheckFailure = args.includes('--fail-on-check-failure');
+    const debug = args.includes('--debug');
+    let logLevel;
+    let logFile;
+    let logType;
+    let runtimeConfigPath;
+    let model;
+    let agentProvider;
+    let genericPrompt;
+    let diffRef;
+    let diffFile;
+    let budgetLimitCost;
+    let budgetLimitTokens;
+    for (let i = startIdx; i < args.length; i++) {
+        switch (args[i]) {
+            case '--config-dir': {
+                configDir = args[i + 1];
+                if (!configDir) {
+                    console.error(formatError(ERROR_CODES.E1001, '--config-dir requires a path argument'));
+                    process.exit(1);
+                }
+                configDir = resolve(configDir);
+                i++;
+                break;
+            }
+            case '--output': {
+                outputPath = args[i + 1];
+                if (!outputPath) {
+                    console.error(formatError(ERROR_CODES.E1001, '--output requires a path argument'));
+                    process.exit(1);
+                }
+                outputPath = resolve(outputPath);
+                i++;
+                break;
+            }
+            case '--output-format': {
+                outputFormat = args[i + 1];
+                if (!outputFormat) {
+                    console.error(formatError(ERROR_CODES.E1001, '--output-format requires a format argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--runtime-config': {
+                runtimeConfigPath = args[i + 1];
+                if (!runtimeConfigPath) {
+                    console.error(formatError(ERROR_CODES.E1001, '--runtime-config requires a path argument'));
+                    process.exit(1);
+                }
+                runtimeConfigPath = resolve(runtimeConfigPath);
+                i++;
+                break;
+            }
+            case '--model': {
+                model = args[i + 1];
+                if (!model) {
+                    console.error(formatError(ERROR_CODES.E1001, '--model requires a model name argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--agent-provider': {
+                agentProvider = args[i + 1];
+                if (!agentProvider) {
+                    console.error(formatError(ERROR_CODES.E1001, '--agent-provider requires a provider name argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--generic-prompt': {
+                genericPrompt = args[i + 1];
+                if (!genericPrompt) {
+                    console.error(formatError(ERROR_CODES.E1001, '--generic-prompt requires a filename argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--log-level': {
+                logLevel = args[i + 1];
+                if (!logLevel) {
+                    console.error(formatError(ERROR_CODES.E1001, '--log-level requires a level argument (error, warn, info, debug, trace)'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--log-file': {
+                logFile = args[i + 1];
+                if (!logFile) {
+                    console.error(formatError(ERROR_CODES.E1001, '--log-file requires a path argument'));
+                    process.exit(1);
+                }
+                logFile = resolve(logFile);
+                i++;
+                break;
+            }
+            case '--log-type': {
+                logType = args[i + 1];
+                if (!logType) {
+                    console.error(formatError(ERROR_CODES.E1001, '--log-type requires a type argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--diff-ref': {
+                diffRef = args[i + 1];
+                if (!diffRef) {
+                    console.error(formatError(ERROR_CODES.E1001, '--diff-ref requires a git ref argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--diff-file': {
+                diffFile = args[i + 1];
+                if (!diffFile) {
+                    console.error(formatError(ERROR_CODES.E1001, '--diff-file requires a path argument'));
+                    process.exit(1);
+                }
+                diffFile = resolve(diffFile);
+                i++;
+                break;
+            }
+            case '--budget-limit-cost': {
+                const raw = args[i + 1];
+                if (!raw) {
+                    console.error(formatError(ERROR_CODES.E1001, '--budget-limit-cost requires a number argument (USD)'));
+                    process.exit(1);
+                }
+                const n = Number(raw);
+                if (!Number.isFinite(n) || n <= 0) {
+                    console.error(formatError(ERROR_CODES.E1001, `--budget-limit-cost must be a positive number (got "${raw}")`));
+                    process.exit(1);
+                }
+                budgetLimitCost = n;
+                i++;
+                break;
+            }
+            case '--budget-limit-tokens': {
+                const raw = args[i + 1];
+                if (!raw) {
+                    console.error(formatError(ERROR_CODES.E1001, '--budget-limit-tokens requires a number argument'));
+                    process.exit(1);
+                }
+                const n = Number(raw);
+                if (!Number.isFinite(n) || n <= 0 || !Number.isInteger(n)) {
+                    console.error(formatError(ERROR_CODES.E1001, `--budget-limit-tokens must be a positive integer (got "${raw}")`));
+                    process.exit(1);
+                }
+                budgetLimitTokens = n;
+                i++;
+                break;
+            }
+            // --fail-on-check-failure and --debug are handled above via includes()
+        }
+    }
+    return {
+        repositoryPath, configDir, outputPath, outputFormat,
+        failOnCheckFailure, debug, logLevel, logFile, logType,
+        runtimeConfigPath, model, agentProvider, genericPrompt,
+        diffRef, diffFile,
+        budgetLimitCost, budgetLimitTokens,
+    };
+}
+async function createProvider(useMock, agentProviderName, modelOverride) {
+    if (useMock) {
+        logProgress(TAG, `Mock provider enabled via AGHAST_MOCK_AI=${process.env.AGHAST_MOCK_AI}`);
+        const provider = await createMockProvider();
+        // Honour --model in mock mode so cost-calculation tests can target a known
+        // pricing entry. Defaults to MOCK_MODEL_NAME.
+        const effectiveModel = modelOverride ?? MOCK_MODEL_NAME;
+        provider.setModel?.(effectiveModel);
+        return { provider, modelName: effectiveModel };
+    }
+    const provider = createProviderByName(agentProviderName);
+    await provider.initialize({
+        apiKey: process.env.ANTHROPIC_API_KEY,
+        model: modelOverride,
+    });
+    const modelName = provider.getModelName?.() ?? DEFAULT_MODEL;
+    return { provider, modelName };
+}
+/**
+ * Validate that the config directory has the required structure.
+ * Returns early with a clear error message if anything is missing.
+ */
+async function validateConfigDir(configDir) {
+    // Check checks-config.json exists
+    const registryPath = resolve(configDir, 'checks-config.json');
+    try {
+        await stat(registryPath);
+    }
+    catch {
+        console.error(formatError(ERROR_CODES.E2002, `Config directory is missing checks-config.json: ${registryPath}`));
+        console.error(`  Use 'aghast new-check --config-dir ${configDir}' to bootstrap a config directory.`);
+        process.exit(1);
+    }
+    // Check checks/ directory exists
+    const checksPath = resolve(configDir, 'checks');
+    try {
+        const checksStat = await stat(checksPath);
+        if (!checksStat.isDirectory()) {
+            console.error(formatError(ERROR_CODES.E2002, `${checksPath} exists but is not a directory`));
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(formatError(ERROR_CODES.E2002, `Config directory is missing checks/ folder: ${checksPath}`));
+        console.error(`  Use 'aghast new-check --config-dir ${configDir}' to add checks.`);
+        process.exit(1);
+    }
+    // Check that checks/ has at least one subfolder
+    const entries = await readdir(checksPath);
+    if (entries.length === 0) {
+        console.error(formatError(ERROR_CODES.E2003, `No checks found in ${checksPath}`));
+        console.error(`  Use 'aghast new-check --config-dir ${configDir}' to add checks.`);
+        process.exit(1);
+    }
+}
+export async function runScan(args) {
+    const globalTimer = createTimer();
+    const parsed = parseArgs(args);
+    // --config-dir is required (CLI flag > AGHAST_CONFIG_DIR env var)
+    const rawConfigDir = parsed.configDir || process.env.AGHAST_CONFIG_DIR;
+    if (!rawConfigDir) {
+        console.error(formatError(ERROR_CODES.E2001, "--config-dir is required (or set AGHAST_CONFIG_DIR). Use 'aghast new-check --config-dir <path>' to create a config directory."));
+        process.exit(1);
+    }
+    const configDir = resolve(rawConfigDir);
+    // Validate config directory structure
+    await validateConfigDir(configDir);
+    // Load runtime configuration
+    let runtimeConfig;
+    try {
+        runtimeConfig = await loadRuntimeConfig(configDir, parsed.runtimeConfigPath);
+    }
+    catch (err) {
+        console.error(formatError(ERROR_CODES.E2005, err instanceof Error ? err.message : String(err)));
+        process.exit(1);
+    }
+    // Resolve log level: --log-level > AGHAST_LOG_LEVEL > runtime config > --debug/AGHAST_DEBUG > default
+    const debug = parsed.debug || process.env.AGHAST_DEBUG === 'true';
+    const resolvedLogLevel = parsed.logLevel ?? (process.env.AGHAST_LOG_LEVEL || undefined) ?? runtimeConfig.logging?.level ?? (debug ? 'debug' : DEFAULT_LOG_LEVEL);
+    if (resolvedLogLevel !== 'silent' && !isValidLogLevel(resolvedLogLevel)) {
+        console.error(formatError(ERROR_CODES.E1001, `Invalid log level "${resolvedLogLevel}". Valid levels: error, warn, info, debug, trace`));
+        process.exit(1);
+    }
+    setLogLevel(resolvedLogLevel);
+    // Resolve log file: --log-file > AGHAST_LOG_FILE > runtime config
+    const resolvedLogFile = parsed.logFile ?? (process.env.AGHAST_LOG_FILE || undefined) ?? (runtimeConfig.logging?.logFile ? resolve(runtimeConfig.logging.logFile) : undefined);
+    if (resolvedLogFile) {
+        const resolvedLogType = parsed.logType ?? (process.env.AGHAST_LOG_TYPE || undefined) ?? runtimeConfig.logging?.logType ?? DEFAULT_LOG_TYPE;
+        const availableTypes = getAvailableLogTypes();
+        if (!availableTypes.includes(resolvedLogType)) {
+            console.error(formatError(ERROR_CODES.E1001, `Unknown log type "${resolvedLogType}". Available types: ${availableTypes.join(', ')}`));
+            process.exit(1);
+        }
+        initFileHandler(resolve(resolvedLogFile), resolvedLogType);
+    }
+    // Resolve repository path — required
+    if (!parsed.repositoryPath) {
+        console.error(formatError(ERROR_CODES.E1003, '<repo-path> is required'));
+        process.exit(1);
+    }
+    // Validate repository path exists and is a directory
+    try {
+        const repoStat = await stat(parsed.repositoryPath);
+        if (!repoStat.isDirectory()) {
+            console.error(formatError(ERROR_CODES.E4001, `Repository path is not a directory: ${parsed.repositoryPath}`));
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            console.error(formatError(ERROR_CODES.E4001, `Repository path does not exist: ${parsed.repositoryPath}`));
+            process.exit(1);
+        }
+        throw err;
+    }
+    // Resolve output format: CLI > runtime config > default
+    const resolvedOutputFormat = parsed.outputFormat ?? runtimeConfig.reporting?.outputFormat ?? DEFAULT_OUTPUT_FORMAT;
+    // Resolve formatter early — fail fast on unknown format
+    const formatter = getFormatter(resolvedOutputFormat);
+    // Treat AGHAST_MOCK_AI=false (or empty) as disabled; any other truthy value enables mock mode
+    const mockAiEnv = process.env.AGHAST_MOCK_AI;
+    const useMock = !!(mockAiEnv && mockAiEnv !== 'false');
+    // ─── Load and filter checks BEFORE AI validation ───
+    // Checks always live in <config-dir>/checks/
+    const checksDirs = [resolve(configDir, 'checks')];
+    // Resolve generic prompt: CLI > env > runtime config > default (handled in buildPrompt)
+    const genericPrompt = parsed.genericPrompt ?? process.env.AGHAST_GENERIC_PROMPT ?? runtimeConfig.genericPrompt;
+    logDebug(TAG, `Config dir: ${configDir}, checks dir: ${checksDirs[0]}`);
+    // Two-layer config loading
+    const registry = await loadCheckRegistry(configDir);
+    const checkFolders = await discoverCheckFolders(checksDirs);
+    if (checkFolders.size === 0) {
+        console.error(formatError(ERROR_CODES.E2003, `No valid checks found in ${checksDirs[0]}. Each check needs a <id>/<id>.json file.`));
+        process.exit(1);
+    }
+    const allChecks = await resolveChecks(registry, checkFolders);
+    // Analyze repository to get remote URL for check filtering
+    const effectiveRepoPath = parsed.repositoryPath;
+    const repoAnalysis = await analyzeRepository(effectiveRepoPath);
+    const repoUrl = repoAnalysis?.repository.remoteUrl ?? effectiveRepoPath;
+    const matchingChecks = filterChecksForRepository(allChecks, repoUrl);
+    logProgress(TAG, `Found ${matchingChecks.length} matching checks (of ${allChecks.length} total)`);
+    if (matchingChecks.length === 0) {
+        logProgress(TAG, 'No matching checks found for this repository');
+    }
+    // Validate and load check details
+    const checksWithDetails = [];
+    for (const check of matchingChecks) {
+        // instructionsFile is already absolute from resolveChecks — validate against ''
+        const validation = await validateCheck(check, '');
+        if (!validation.valid) {
+            logProgress(TAG, `Skipping invalid check "${check.id}": ${validation.errors.join(', ')}`);
+            continue;
+        }
+        // checkTarget rules already resolved by resolveChecks — no additional path resolution needed
+        // Checks that don't require instructions use synthetic details (unless they provided one optionally).
+        // Built-in analysis modes (false-positive-validation, general-vuln-discovery) also don't need instructions.
+        const builtInMode = check.checkTarget?.analysisMode === 'false-positive-validation'
+            || check.checkTarget?.analysisMode === 'general-vuln-discovery';
+        if ((!getCheckType(check.checkTarget?.type).needsInstructions || builtInMode) && !check.instructionsFile) {
+            checksWithDetails.push({
+                check,
+                details: { id: check.id, name: check.name, overview: '', content: '' },
+            });
+            continue;
+        }
+        const details = await loadCheckDetails(check, '');
+        // Fall back to JSON definition name if markdown has no ### heading
+        if (details.name === 'Unknown Check') {
+            details.name = check.name;
+        }
+        checksWithDetails.push({ check, details });
+    }
+    // ─── Validate --generic-prompt with mixed discovery types ───
+    if (genericPrompt) {
+        const discoveryTypes = new Set();
+        for (const c of checksWithDetails) {
+            const d = c.check.checkTarget?.discovery;
+            if (d)
+                discoveryTypes.add(d);
+        }
+        if (discoveryTypes.size > 1) {
+            console.error(formatError(ERROR_CODES.E2004, `--generic-prompt cannot be used when checks have different discovery types (found: ${[...discoveryTypes].join(', ')}). Each discovery type uses its own default generic prompt.`));
+            process.exit(1);
+        }
+    }
+    // ─── Determine which prerequisites are needed ───
+    const needsAI = checksWithDetails.some(c => getCheckType(c.check.checkTarget?.type).needsAI);
+    const needsSemgrep = checksWithDetails.some(c => c.check.checkTarget?.discovery === 'semgrep');
+    const needsOpenant = checksWithDetails.some(c => c.check.checkTarget?.discovery === 'openant');
+    // ─── Resolve diff source ───
+    // Precedence: CLI --diff-ref/--diff-file > AGHAST_DIFF_REF > runtime config diffRef.
+    // (Check-level diffRef is applied per-check inside the scan runner.)
+    const resolvedDiffRef = parsed.diffRef ?? (process.env.AGHAST_DIFF_REF || undefined) ?? runtimeConfig.diffRef;
+    const resolvedDiffFile = parsed.diffFile;
+    // OpenAnt is needed for diff filtering. Required whenever a diff source is
+    // available and at least one check has a discovery that supports the filter
+    // and hasn't opted out.
+    const hasRuntimeDiffSource = resolvedDiffRef !== undefined || resolvedDiffFile !== undefined;
+    const hasAnyCheckLevelDiffRef = checksWithDetails.some(c => c.check.checkTarget?.diffRef !== undefined);
+    const diffSourceAvailable = hasRuntimeDiffSource || hasAnyCheckLevelDiffRef;
+    // Drive supportedDiscovery off the registry rather than a hardcoded list —
+    // new discoveries pick up their own behaviour via supportsDiffFilter without
+    // this gate having to be kept in sync.
+    const registeredDiscoveries = new Set(getRegisteredDiscoveries());
+    const needsDiffFilter = diffSourceAvailable && checksWithDetails.some(c => {
+        const ct = c.check.checkTarget;
+        if (!ct?.discovery || !registeredDiscoveries.has(ct.discovery))
+            return false;
+        const supportedDiscovery = getDiscovery(ct.discovery).supportsDiffFilter;
+        const optedIn = ct.diffFilter !== false;
+        const hasSource = hasRuntimeDiffSource || ct.diffRef !== undefined;
+        return supportedDiscovery && optedIn && hasSource;
+    });
+    // ─── Conditional agent provider setup ───
+    const agentProviderName = parsed.agentProvider ?? runtimeConfig.agentProvider?.name ?? DEFAULT_PROVIDER_NAME;
+    if (needsAI && !useMock) {
+        // Validate agent provider name before checking credentials (config errors before auth errors)
+        if (!getProviderNames().includes(agentProviderName)) {
+            console.error(formatError(ERROR_CODES.E3002, `Unknown agent provider "${agentProviderName}". Supported providers: ${getProviderNames().join(', ')}`));
+            process.exit(1);
+        }
+        // Validate provider-specific prerequisites (API keys, binaries, etc.)
+        try {
+            const tempProvider = createProviderByName(agentProviderName);
+            tempProvider.checkPrerequisites?.();
+        }
+        catch (err) {
+            console.error(formatError(ERROR_CODES.E3001, err instanceof Error ? err.message : String(err)));
+            process.exit(1);
+        }
+    }
+    // Resolve model precedence: CLI --model > env AGHAST_AI_MODEL > runtime config > default
+    const modelOverride = parsed.model ?? process.env.AGHAST_AI_MODEL ?? runtimeConfig.agentProvider?.model;
+    let provider;
+    let modelName;
+    if (needsAI) {
+        ({ provider, modelName } = await createProvider(useMock, agentProviderName, modelOverride));
+        logProgress(TAG, `Using model: ${modelName}`);
+    }
+    // ─── Conditional Semgrep verification (needed for semgrep discovery) ───
+    if (needsSemgrep && !process.env.AGHAST_MOCK_SEMGREP) {
+        try {
+            await verifySemgrepInstalled();
+        }
+        catch (err) {
+            console.error(formatError(ERROR_CODES.E5001, err instanceof Error ? err.message : String(err)));
+            process.exit(1);
+        }
+    }
+    // ─── Conditional OpenAnt verification ───
+    // `openant` discovery is a hard requirement: without OpenAnt there are no
+    // targets. Diff filtering on other discoveries is a soft requirement: if
+    // OpenAnt is missing we fall back to a depth-0 filter (file+line overlap
+    // only, no call-graph flow) and log a clear warning so the mode is visible.
+    let openantAvailable = true;
+    if (needsOpenant && !process.env.AGHAST_OPENANT_DATASET) {
+        try {
+            await verifyOpenAntInstalled();
+        }
+        catch (err) {
+            console.error(formatError(ERROR_CODES.E6001, err instanceof Error ? err.message : String(err)));
+            process.exit(1);
+        }
+    }
+    else if (needsDiffFilter && !process.env.AGHAST_OPENANT_DATASET) {
+        try {
+            await verifyOpenAntInstalled();
+        }
+        catch {
+            openantAvailable = false;
+            logProgress(TAG, 'OpenAnt is not installed — diff filter will run in depth-0 mode ' +
+                '(findings kept only if their file and line range appear in the diff; ' +
+                'direct callers/callees of changed code are NOT included). ' +
+                'Install OpenAnt (https://github.com/knostic/OpenAnt/) or set ' +
+                'AGHAST_OPENANT_DATASET to a prebuilt dataset for depth-1 filtering with call-graph flow.');
+        }
+    }
+    // ─── Pricing + budget setup ───
+    const defaultPricing = await loadDefaultPricing();
+    const pricing = mergePricing(defaultPricing, runtimeConfig.pricing);
+    const budgetLimits = (() => {
+        const cliCost = parsed.budgetLimitCost;
+        const cliTokens = parsed.budgetLimitTokens;
+        const cfg = runtimeConfig.budget;
+        if (cliCost === undefined && cliTokens === undefined && !cfg)
+            return undefined;
+        const out = {};
+        const perScan = { ...(cfg?.perScan ?? {}) };
+        if (cliCost !== undefined)
+            perScan.maxCostUsd = cliCost;
+        if (cliTokens !== undefined)
+            perScan.maxTokens = cliTokens;
+        if (perScan.maxCostUsd !== undefined || perScan.maxTokens !== undefined) {
+            out.perScan = perScan;
+        }
+        if (cfg?.perPeriod && cfg.perPeriod.window && cfg.perPeriod.maxCostUsd !== undefined) {
+            out.perPeriod = { window: cfg.perPeriod.window, maxCostUsd: cfg.perPeriod.maxCostUsd };
+        }
+        if (cfg?.thresholds)
+            out.thresholds = cfg.thresholds;
+        return Object.keys(out).length > 0 ? out : undefined;
+    })();
+    // Pre-load history for period budget checks (skip when no period limit set)
+    let scanHistoryForBudget;
+    if (budgetLimits?.perPeriod) {
+        try {
+            scanHistoryForBudget = await queryScanHistory();
+        }
+        catch (err) {
+            logDebug(TAG, `Could not load scan history for budget check: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    try {
+        const outcome = await runMultiScanWithCost({
+            repositoryPath: effectiveRepoPath,
+            checks: checksWithDetails,
+            agentProvider: provider,
+            modelName: needsAI ? modelName : undefined,
+            repositoryInfo: repoAnalysis?.repository,
+            agentProviderName: needsAI ? (useMock ? 'mock' : agentProviderName) : undefined,
+            configDir,
+            genericPrompt,
+            diffRef: resolvedDiffRef,
+            diffFile: resolvedDiffFile,
+            openantAvailable,
+            pricing,
+            budgetLimits,
+            scanHistory: scanHistoryForBudget,
+            isLocalClaude: process.env.AGHAST_LOCAL_CLAUDE === 'true',
+        });
+        const results = outcome.results;
+        // Resolve output path: --output flag > runtime config dir > default
+        let resolvedOutputPath;
+        if (parsed.outputPath) {
+            resolvedOutputPath = parsed.outputPath;
+        }
+        else if (runtimeConfig.reporting?.outputDirectory) {
+            const dir = resolve(runtimeConfig.reporting.outputDirectory);
+            resolvedOutputPath = resolve(dir, 'security_checks_results' + formatter.fileExtension);
+        }
+        else {
+            resolvedOutputPath = resolve(effectiveRepoPath, 'security_checks_results' + formatter.fileExtension);
+        }
+        await mkdir(dirname(resolvedOutputPath), { recursive: true });
+        await writeFile(resolvedOutputPath, formatter.format(results), 'utf-8');
+        // Summary output
+        const statusIcon = results.summary.failedChecks > 0
+            ? 'ISSUES DETECTED'
+            : results.summary.flaggedChecks > 0
+                ? 'REVIEW REQUIRED'
+                : results.summary.errorChecks > 0
+                    ? 'SCAN ERROR'
+                    : 'NO ISSUES DETECTED';
+        console.log('');
+        console.log('='.repeat(60));
+        console.log(`AGHAST Scan Complete: ${colorStatus(statusIcon)}`);
+        console.log('='.repeat(60));
+        console.log(`  Total checks:  ${results.summary.totalChecks}`);
+        console.log(`  Passed:        ${results.summary.passedChecks}`);
+        console.log(`  Failed:        ${results.summary.failedChecks}`);
+        console.log(`  Flagged:       ${results.summary.flaggedChecks}`);
+        console.log(`  Errors:        ${results.summary.errorChecks}`);
+        console.log(`  Total issues:  ${results.summary.totalIssues}`);
+        if (results.tokenUsage) {
+            const tu = results.tokenUsage;
+            const cacheSegments = [
+                tu.cacheReadInputTokens !== undefined ? ` cache-read: ${tu.cacheReadInputTokens.toLocaleString()}` : '',
+                tu.cacheCreationInputTokens !== undefined ? ` cache-write: ${tu.cacheCreationInputTokens.toLocaleString()}` : '',
+                tu.reasoningTokens !== undefined ? ` reasoning: ${tu.reasoningTokens.toLocaleString()}` : '',
+            ].filter(Boolean).join(',');
+            const tokenDetail = `(in: ${tu.inputTokens.toLocaleString()}, out: ${tu.outputTokens.toLocaleString()}${cacheSegments ? ',' + cacheSegments : ''})`;
+            console.log(`  Tokens:        ${tu.totalTokens.toLocaleString()} ${tokenDetail}`);
+        }
+        if (outcome.totalCostUsd > 0 || outcome.costSource === 'estimated-unpriced') {
+            const label = formatCostSourceLabel(outcome.costSource, outcome.costReportedBy, outcome.costCoveredBySubscription);
+            const equiv = outcome.costCoveredBySubscription ? ' equivalent' : '';
+            console.log(`  Cost:          $${outcome.totalCostUsd.toFixed(4)}${equiv}  ${label}`);
+        }
+        console.log(`  Duration:      ${globalTimer.elapsedStr()}`);
+        console.log(`  Results:       ${resolvedOutputPath}`);
+        console.log('='.repeat(60));
+        // Persist the scan record to history (best-effort — never blocks exit).
+        // We DO save the record even when the scan was aborted by budget: per-period
+        // budgets aggregate over historical scans, so the partial cost incurred
+        // before the abort must be recorded — otherwise a user could repeatedly
+        // hit the budget abort and still consume more total spend than the period
+        // limit allows.
+        try {
+            const record = {
+                scanId: results.scanId,
+                startedAt: results.startTime,
+                endedAt: results.endTime,
+                durationMs: results.executionTime,
+                repository: effectiveRepoPath,
+                repositoryUrl: repoAnalysis?.repository.remoteUrl,
+                models: outcome.models.length > 0 ? outcome.models : (modelName ? [modelName] : []),
+                tokenUsage: results.tokenUsage,
+                totalCost: outcome.totalCostUsd,
+                currency: outcome.currency,
+                costSource: outcome.costSource,
+                costReportedBy: outcome.costReportedBy,
+                costCoveredBySubscription: outcome.costCoveredBySubscription,
+                checks: results.summary.totalChecks,
+                issues: results.summary.totalIssues,
+            };
+            await saveScanRecord(record);
+        }
+        catch (err) {
+            logDebug(TAG, `Failed to save scan history: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // A budget abort is a deliberate failure mode the user opted into via
+        // --budget-limit-* / runtime config — it must always exit non-zero (and
+        // surface E7001 to stderr) regardless of --fail-on-check-failure. Doing
+        // otherwise would silently drop the abort signal in CI pipelines that
+        // rely on the exit code as a guardrail.
+        //
+        // Emit through both stderr (for terminal users / CI logs) AND the logging
+        // system (so --log-file captures the abort reason — console.error bypasses
+        // registered log handlers).
+        if (outcome.budgetAborted) {
+            const reason = outcome.budgetAbortReason ?? 'Budget limit exceeded';
+            console.error(formatError(ERROR_CODES.E7001, reason));
+            logProgress(TAG, `Scan aborted by budget: ${reason}`);
+        }
+        // Exit code based on --fail-on-check-failure flag or runtime config (spec Section 9.3),
+        // OR a budget abort.
+        const failOnCheckFailure = parsed.failOnCheckFailure || runtimeConfig.failOnCheckFailure === true;
+        const shouldFail = outcome.budgetAborted ||
+            (failOnCheckFailure && (results.summary.failedChecks > 0 || results.summary.errorChecks > 0));
+        await closeAllHandlers();
+        process.exit(shouldFail ? 1 : 0);
+    }
+    finally {
+        // Clean up provider resources (e.g. OpenCode server process)
+        if (provider && 'cleanup' in provider && typeof provider.cleanup === 'function') {
+            await provider.cleanup();
+        }
+    }
+}
+// Auto-run when executed directly (npm run scan / tsx src/index.ts), but not when imported by cli.ts.
+if (!process.env._AGHAST_CLI) {
+    runScan(process.argv.slice(2)).catch(async (err) => {
+        const require = createRequire(import.meta.url);
+        const pkg = require('../package.json');
+        console.error('');
+        console.error(formatFatalError(err instanceof Error ? err.message : String(err), pkg.version));
+        logDebug(TAG, 'Error details', err);
+        await closeAllHandlers();
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map