edsger 0.55.4 → 0.56.0

package/dist/phases/quality-benchmark/tool-catalog.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Authoritative tool catalog for the quality-benchmark phase.
+ *
+ * Every tool the LLM is permitted to probe / install / execute is listed
+ * here. Commands are templates with placeholders resolved at runtime by
+ * `tool-runner.ts`:
+ *   %REPO_ROOT%   - absolute path to the repo checkout
+ *   %PKG_MANAGER% - detected JS package manager (npm/pnpm/yarn)
+ *   %SCAN_DIR%    - per-run scratch dir for tool outputs
+ *
+ * Keep this in sync with `rubric.md` § "Tool Catalog". The LLM receives
+ * the rubric text in its system prompt, and the runtime enforces the
+ * catalog by refusing to execute commands not registered here.
+ */
+import type { ToolCatalogEntry } from './types';
+export declare const TOOL_CATALOG: readonly ToolCatalogEntry[];
+/** Index for O(1) lookups by tool id. */
+export declare const TOOL_CATALOG_BY_ID: ReadonlyMap<string, ToolCatalogEntry>;
+/** All tool ids the LLM is allowed to invoke. */
+export declare const ALL_TOOL_IDS: readonly string[];
+/** All install commands — used to whitelist Bash invocations during Phase 2.5. */
+export declare const ALL_INSTALL_COMMANDS: readonly string[];
+/**
+ * Pick the catalog entries relevant to a detected context. This is advisory:
+ * the runtime still allows any catalog entry to run, but most callers should
+ * narrow first to avoid wasted probing.
+ */
+export declare function selectToolsForContext(input: {
+    languages: readonly string[];
+    package_managers?: readonly string[];
+    frameworks?: readonly string[];
+    files_present?: readonly string[];
+}): ToolCatalogEntry[];

package/dist/phases/quality-benchmark/tool-catalog.js

@@ -0,0 +1,597 @@
+/**
+ * Authoritative tool catalog for the quality-benchmark phase.
+ *
+ * Every tool the LLM is permitted to probe / install / execute is listed
+ * here. Commands are templates with placeholders resolved at runtime by
+ * `tool-runner.ts`:
+ *   %REPO_ROOT%   - absolute path to the repo checkout
+ *   %PKG_MANAGER% - detected JS package manager (npm/pnpm/yarn)
+ *   %SCAN_DIR%    - per-run scratch dir for tool outputs
+ *
+ * Keep this in sync with `rubric.md` § "Tool Catalog". The LLM receives
+ * the rubric text in its system prompt, and the runtime enforces the
+ * catalog by refusing to execute commands not registered here.
+ */
+// ---------------------------------------------------------------------------
+// JavaScript / TypeScript
+// ---------------------------------------------------------------------------
+const eslint = {
+    id: 'eslint',
+    label: 'ESLint',
+    category: 'lint',
+    applies_to: ['js', 'ts'],
+    probe: 'npx --no eslint --version',
+    install: null, // project-local only
+    install_prereq: 'npx',
+    command: 'npx --no eslint . --format json --ext .js,.jsx,.ts,.tsx --no-error-on-unmatched-pattern',
+    timeout_minutes: 5,
+    parser: 'eslint',
+    subscores: ['code_quality.lint'],
+    tolerate_nonzero_exit: true,
+    requires: {
+        file_present: [
+            '.eslintrc.js',
+            '.eslintrc.cjs',
+            '.eslintrc.json',
+            '.eslintrc.yml',
+            'eslint.config.js',
+            'eslint.config.mjs',
+        ],
+    },
+};
+const tscTypecheck = {
+    id: 'tsc-typecheck',
+    label: 'TypeScript typecheck',
+    category: 'typecheck',
+    applies_to: ['ts'],
+    probe: 'npx --no tsc --version',
+    install: null,
+    install_prereq: 'npx',
+    command: 'npx --no tsc --noEmit --pretty false',
+    timeout_minutes: 5,
+    parser: 'tsc',
+    subscores: ['code_quality.lint'],
+    tolerate_nonzero_exit: true,
+    requires: { file_present: ['tsconfig.json'] },
+};
+const jscpd = {
+    id: 'jscpd',
+    label: 'jscpd (duplication)',
+    category: 'duplication',
+    applies_to: ['js', 'ts', 'py', 'java', 'go', 'cs', 'ruby'],
+    probe: 'command -v jscpd',
+    install: null, // always use npx
+    install_prereq: 'npx',
+    command: 'npx --yes jscpd %REPO_ROOT% --reporters json --output %SCAN_DIR%/jscpd --min-lines 5 --min-tokens 50 --silent',
+    timeout_minutes: 10,
+    parser: 'jscpd',
+    subscores: ['code_quality.duplication'],
+    tolerate_nonzero_exit: true,
+};
+const madge = {
+    id: 'madge',
+    label: 'madge (circular deps)',
+    category: 'cycles',
+    applies_to: ['js', 'ts'],
+    probe: 'command -v madge',
+    install: null,
+    install_prereq: 'npx',
+    command: 'npx --yes madge --circular --json --extensions js,jsx,ts,tsx %REPO_ROOT%',
+    timeout_minutes: 3,
+    parser: 'madge',
+    subscores: ['architecture.circular_deps'],
+    tolerate_nonzero_exit: true,
+};
+const depcheck = {
+    id: 'depcheck',
+    label: 'depcheck (unused deps)',
+    category: 'dep-unused',
+    applies_to: ['js', 'ts'],
+    probe: 'command -v depcheck',
+    install: null,
+    install_prereq: 'npx',
+    command: 'npx --yes depcheck --json',
+    timeout_minutes: 3,
+    parser: 'depcheck',
+    subscores: ['dependency_health.unused'],
+    tolerate_nonzero_exit: true,
+};
+const npmAudit = {
+    id: 'npm-audit',
+    label: 'npm audit',
+    category: 'dep-vuln',
+    applies_to: ['js', 'ts'],
+    probe: 'command -v npm',
+    install: null,
+    install_prereq: null,
+    command: 'npm audit --json',
+    timeout_minutes: 3,
+    parser: 'npm-audit',
+    subscores: ['security.dep_vulns'],
+    tolerate_nonzero_exit: true,
+    requires: { package_manager: ['npm'] },
+};
+const pnpmAudit = {
+    id: 'pnpm-audit',
+    label: 'pnpm audit',
+    category: 'dep-vuln',
+    applies_to: ['js', 'ts'],
+    probe: 'command -v pnpm',
+    install: null,
+    install_prereq: null,
+    command: 'pnpm audit --json',
+    timeout_minutes: 3,
+    parser: 'pnpm-audit',
+    subscores: ['security.dep_vulns'],
+    tolerate_nonzero_exit: true,
+    requires: { package_manager: ['pnpm'] },
+};
+const yarnAudit = {
+    id: 'yarn-audit',
+    label: 'yarn audit',
+    category: 'dep-vuln',
+    applies_to: ['js', 'ts'],
+    probe: 'command -v yarn',
+    install: null,
+    install_prereq: null,
+    command: 'yarn npm audit --json',
+    timeout_minutes: 3,
+    parser: 'yarn-audit',
+    subscores: ['security.dep_vulns'],
+    tolerate_nonzero_exit: true,
+    requires: { package_manager: ['yarn'] },
+};
+const npmOutdated = {
+    id: 'npm-outdated',
+    label: 'npm outdated',
+    category: 'dep-outdated',
+    applies_to: ['js', 'ts'],
+    probe: 'command -v npm',
+    install: null,
+    install_prereq: null,
+    command: 'npm outdated --json',
+    timeout_minutes: 3,
+    parser: 'npm-outdated',
+    subscores: ['dependency_health.freshness'],
+    tolerate_nonzero_exit: true,
+    requires: { package_manager: ['npm'] },
+};
+const licenseChecker = {
+    id: 'license-checker',
+    label: 'license-checker',
+    category: 'dep-license',
+    applies_to: ['js', 'ts'],
+    probe: 'command -v license-checker',
+    install: null,
+    install_prereq: 'npx',
+    command: 'npx --yes license-checker --json --production',
+    timeout_minutes: 3,
+    parser: 'license-checker',
+    subscores: ['dependency_health.license'],
+};
+// ---------------------------------------------------------------------------
+// Python
+// ---------------------------------------------------------------------------
+const ruff = {
+    id: 'ruff',
+    label: 'ruff',
+    category: 'lint',
+    applies_to: ['py'],
+    probe: 'command -v ruff',
+    install: 'pipx install "ruff>=0.4,<1.0"',
+    install_prereq: 'pipx',
+    command: 'ruff check %REPO_ROOT% --output-format json --no-cache',
+    timeout_minutes: 3,
+    parser: 'ruff',
+    subscores: ['code_quality.lint'],
+    tolerate_nonzero_exit: true,
+};
+const mypy = {
+    id: 'mypy',
+    label: 'mypy',
+    category: 'typecheck',
+    applies_to: ['py'],
+    probe: 'command -v mypy',
+    install: 'pipx install "mypy>=1.8,<2.0"',
+    install_prereq: 'pipx',
+    command: 'mypy %REPO_ROOT% --no-error-summary --show-error-codes --no-color-output',
+    timeout_minutes: 5,
+    parser: 'mypy',
+    subscores: ['code_quality.lint'],
+    tolerate_nonzero_exit: true,
+};
+const bandit = {
+    id: 'bandit',
+    label: 'bandit (Python SAST)',
+    category: 'sast',
+    applies_to: ['py'],
+    probe: 'command -v bandit',
+    install: 'pipx install "bandit>=1.7,<2.0"',
+    install_prereq: 'pipx',
+    command: 'bandit -r %REPO_ROOT% -f json -q',
+    timeout_minutes: 5,
+    parser: 'bandit',
+    subscores: ['security.sast'],
+    tolerate_nonzero_exit: true,
+};
+const pipAudit = {
+    id: 'pip-audit',
+    label: 'pip-audit',
+    category: 'dep-vuln',
+    applies_to: ['py'],
+    probe: 'command -v pip-audit',
+    install: 'pipx install "pip-audit>=2.7,<3.0"',
+    install_prereq: 'pipx',
+    command: 'pip-audit --format json',
+    timeout_minutes: 5,
+    parser: 'pip-audit',
+    subscores: ['security.dep_vulns'],
+    tolerate_nonzero_exit: true,
+};
+const radon = {
+    id: 'radon',
+    label: 'radon (Python complexity)',
+    category: 'complexity',
+    applies_to: ['py'],
+    probe: 'command -v radon',
+    install: 'pipx install "radon>=6.0,<7.0"',
+    install_prereq: 'pipx',
+    command: 'radon cc -j %REPO_ROOT%',
+    timeout_minutes: 3,
+    parser: 'radon',
+    subscores: ['code_quality.complexity'],
+};
+const vulture = {
+    id: 'vulture',
+    label: 'vulture (Python dead code)',
+    category: 'dead-code',
+    applies_to: ['py'],
+    probe: 'command -v vulture',
+    install: 'pipx install "vulture>=2.10,<3.0"',
+    install_prereq: 'pipx',
+    command: 'vulture %REPO_ROOT% --min-confidence 80',
+    timeout_minutes: 3,
+    parser: 'vulture',
+    subscores: ['code_quality.dead_code'],
+    tolerate_nonzero_exit: true,
+};
+// ---------------------------------------------------------------------------
+// Go
+// ---------------------------------------------------------------------------
+const golangciLint = {
+    id: 'golangci-lint',
+    label: 'golangci-lint',
+    category: 'lint',
+    applies_to: ['go'],
+    probe: 'command -v golangci-lint',
+    install: 'go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.60.3',
+    install_prereq: 'go',
+    command: 'golangci-lint run --out-format json ./...',
+    timeout_minutes: 10,
+    parser: 'golangci-lint',
+    subscores: ['code_quality.lint'],
+    tolerate_nonzero_exit: true,
+};
+const gosec = {
+    id: 'gosec',
+    label: 'gosec',
+    category: 'sast',
+    applies_to: ['go'],
+    probe: 'command -v gosec',
+    install: 'go install github.com/securego/gosec/v2/cmd/gosec@v2.21.4',
+    install_prereq: 'go',
+    command: 'gosec -fmt json -quiet ./...',
+    timeout_minutes: 5,
+    parser: 'gosec',
+    subscores: ['security.sast'],
+    tolerate_nonzero_exit: true,
+};
+const govulncheck = {
+    id: 'govulncheck',
+    label: 'govulncheck',
+    category: 'dep-vuln',
+    applies_to: ['go'],
+    probe: 'command -v govulncheck',
+    install: 'go install golang.org/x/vuln/cmd/govulncheck@latest',
+    install_prereq: 'go',
+    command: 'govulncheck -json ./...',
+    timeout_minutes: 5,
+    parser: 'govulncheck',
+    subscores: ['security.dep_vulns'],
+    tolerate_nonzero_exit: true,
+};
+const gocyclo = {
+    id: 'gocyclo',
+    label: 'gocyclo',
+    category: 'complexity',
+    applies_to: ['go'],
+    probe: 'command -v gocyclo',
+    install: 'go install github.com/fzipp/gocyclo/cmd/gocyclo@latest',
+    install_prereq: 'go',
+    command: 'gocyclo -over 15 -json %REPO_ROOT%',
+    timeout_minutes: 3,
+    parser: 'gocyclo',
+    subscores: ['code_quality.complexity'],
+    tolerate_nonzero_exit: true,
+};
+const goModOutdated = {
+    id: 'go-mod-outdated',
+    label: 'go list -m -u',
+    category: 'dep-outdated',
+    applies_to: ['go'],
+    probe: 'command -v go',
+    install: null,
+    install_prereq: null,
+    command: 'go list -m -u -mod=mod -json all',
+    timeout_minutes: 3,
+    parser: 'go-mod-outdated',
+    subscores: ['dependency_health.freshness'],
+    tolerate_nonzero_exit: true,
+};
+// ---------------------------------------------------------------------------
+// Rust
+// ---------------------------------------------------------------------------
+const clippy = {
+    id: 'clippy',
+    label: 'cargo clippy',
+    category: 'lint',
+    applies_to: ['rust'],
+    probe: 'command -v cargo',
+    install: null,
+    install_prereq: null,
+    command: 'cargo clippy --message-format json --all-targets -- -D warnings',
+    timeout_minutes: 10,
+    parser: 'clippy',
+    subscores: ['code_quality.lint'],
+    tolerate_nonzero_exit: true,
+};
+const cargoAudit = {
+    id: 'cargo-audit',
+    label: 'cargo audit',
+    category: 'dep-vuln',
+    applies_to: ['rust'],
+    probe: 'command -v cargo-audit',
+    install: 'cargo install --locked cargo-audit',
+    install_prereq: 'cargo',
+    command: 'cargo audit --json',
+    timeout_minutes: 5,
+    parser: 'cargo-audit',
+    subscores: ['security.dep_vulns'],
+    tolerate_nonzero_exit: true,
+};
+const cargoDeny = {
+    id: 'cargo-deny',
+    label: 'cargo deny',
+    category: 'dep-license',
+    applies_to: ['rust'],
+    probe: 'command -v cargo-deny',
+    install: 'cargo install --locked cargo-deny',
+    install_prereq: 'cargo',
+    command: 'cargo deny check --format json',
+    timeout_minutes: 5,
+    parser: 'cargo-deny',
+    subscores: ['dependency_health.license', 'security.dep_vulns'],
+    tolerate_nonzero_exit: true,
+};
+const cargoOutdated = {
+    id: 'cargo-outdated',
+    label: 'cargo outdated',
+    category: 'dep-outdated',
+    applies_to: ['rust'],
+    probe: 'command -v cargo-outdated',
+    install: 'cargo install --locked cargo-outdated',
+    install_prereq: 'cargo',
+    command: 'cargo outdated --format json',
+    timeout_minutes: 5,
+    parser: 'cargo-outdated',
+    subscores: ['dependency_health.freshness'],
+    tolerate_nonzero_exit: true,
+};
+// ---------------------------------------------------------------------------
+// Ruby
+// ---------------------------------------------------------------------------
+const rubocop = {
+    id: 'rubocop',
+    label: 'RuboCop',
+    category: 'lint',
+    applies_to: ['ruby'],
+    probe: 'command -v rubocop',
+    install: 'gem install --user-install rubocop --version "~> 1.65"',
+    install_prereq: 'gem',
+    command: 'rubocop --format json',
+    timeout_minutes: 5,
+    parser: 'rubocop',
+    subscores: ['code_quality.lint'],
+    tolerate_nonzero_exit: true,
+};
+const brakeman = {
+    id: 'brakeman',
+    label: 'Brakeman (Rails SAST)',
+    category: 'sast',
+    applies_to: ['ruby'],
+    probe: 'command -v brakeman',
+    install: 'gem install --user-install brakeman',
+    install_prereq: 'gem',
+    command: 'brakeman -f json -q --no-progress',
+    timeout_minutes: 10,
+    parser: 'brakeman',
+    subscores: ['security.sast'],
+    tolerate_nonzero_exit: true,
+    requires: { framework: ['rails'] },
+};
+const bundlerAudit = {
+    id: 'bundler-audit',
+    label: 'bundler-audit',
+    category: 'dep-vuln',
+    applies_to: ['ruby'],
+    probe: 'command -v bundle-audit',
+    install: 'gem install --user-install bundler-audit',
+    install_prereq: 'gem',
+    command: 'bundle-audit check --format json',
+    timeout_minutes: 5,
+    parser: 'bundler-audit',
+    subscores: ['security.dep_vulns'],
+    tolerate_nonzero_exit: true,
+};
+// ---------------------------------------------------------------------------
+// Multi-language / polyglot
+// ---------------------------------------------------------------------------
+const semgrep = {
+    id: 'semgrep',
+    label: 'Semgrep',
+    category: 'sast',
+    applies_to: ['js', 'ts', 'py', 'go', 'rust', 'java', 'ruby', 'c', 'cpp'],
+    probe: 'command -v semgrep',
+    install: 'pipx install "semgrep>=1.40,<2.0"',
+    install_prereq: 'pipx',
+    command: 'semgrep --config auto --json --quiet --metrics off --timeout 300',
+    timeout_minutes: 15,
+    parser: 'semgrep',
+    subscores: ['security.sast', 'performance.n_plus_one'],
+    tolerate_nonzero_exit: true,
+};
+const gitleaks = {
+    id: 'gitleaks',
+    label: 'gitleaks',
+    category: 'secrets',
+    applies_to: ['all'],
+    probe: 'command -v gitleaks',
+    install: 'go install github.com/zricethezav/gitleaks/v8@latest',
+    install_prereq: 'go',
+    command: 'gitleaks detect --no-banner --report-format json --report-path - --redact',
+    timeout_minutes: 5,
+    parser: 'gitleaks',
+    subscores: ['security.secrets_hygiene'],
+    tolerate_nonzero_exit: true,
+};
+const osvScanner = {
+    id: 'osv-scanner',
+    label: 'osv-scanner',
+    category: 'dep-vuln',
+    applies_to: ['all'],
+    probe: 'command -v osv-scanner',
+    install: 'go install github.com/google/osv-scanner/cmd/osv-scanner@latest',
+    install_prereq: 'go',
+    command: 'osv-scanner --format json --recursive %REPO_ROOT%',
+    timeout_minutes: 10,
+    parser: 'osv-scanner',
+    subscores: ['security.dep_vulns'],
+    tolerate_nonzero_exit: true,
+};
+const scc = {
+    id: 'scc',
+    label: 'scc (LOC stats)',
+    category: 'loc-stats',
+    applies_to: ['all'],
+    probe: 'command -v scc',
+    install: 'go install github.com/boyter/scc/v3@latest',
+    install_prereq: 'go',
+    command: 'scc --format json %REPO_ROOT%',
+    timeout_minutes: 3,
+    parser: 'scc',
+    subscores: ['maintainability.file_distribution'],
+};
+const lizard = {
+    id: 'lizard',
+    label: 'lizard (complexity)',
+    category: 'complexity',
+    applies_to: ['js', 'ts', 'py', 'java', 'c', 'cpp', 'go', 'rust', 'swift'],
+    probe: 'command -v lizard',
+    install: 'pipx install "lizard>=1.17,<2.0"',
+    install_prereq: 'pipx',
+    command: 'lizard %REPO_ROOT% --xml -t 1 -C 15 -L 80',
+    timeout_minutes: 5,
+    parser: 'lizard',
+    subscores: ['code_quality.complexity', 'maintainability.cognitive_load'],
+};
+// ---------------------------------------------------------------------------
+// Catalog assembly
+// ---------------------------------------------------------------------------
+export const TOOL_CATALOG = [
+    // JS/TS
+    eslint,
+    tscTypecheck,
+    jscpd,
+    madge,
+    depcheck,
+    npmAudit,
+    pnpmAudit,
+    yarnAudit,
+    npmOutdated,
+    licenseChecker,
+    // Python
+    ruff,
+    mypy,
+    bandit,
+    pipAudit,
+    radon,
+    vulture,
+    // Go
+    golangciLint,
+    gosec,
+    govulncheck,
+    gocyclo,
+    goModOutdated,
+    // Rust
+    clippy,
+    cargoAudit,
+    cargoDeny,
+    cargoOutdated,
+    // Ruby
+    rubocop,
+    brakeman,
+    bundlerAudit,
+    // Polyglot
+    semgrep,
+    gitleaks,
+    osvScanner,
+    scc,
+    lizard,
+];
+/** Index for O(1) lookups by tool id. */
+export const TOOL_CATALOG_BY_ID = new Map(TOOL_CATALOG.map((t) => [t.id, t]));
+/** All tool ids the LLM is allowed to invoke. */
+export const ALL_TOOL_IDS = TOOL_CATALOG.map((t) => t.id);
+/** All install commands — used to whitelist Bash invocations during Phase 2.5. */
+export const ALL_INSTALL_COMMANDS = TOOL_CATALOG.map((t) => t.install).filter((c) => c !== null);
+/**
+ * Pick the catalog entries relevant to a detected context. This is advisory:
+ * the runtime still allows any catalog entry to run, but most callers should
+ * narrow first to avoid wasted probing.
+ */
+export function selectToolsForContext(input) {
+    const langSet = new Set(input.languages.map((l) => l.toLowerCase()));
+    const pmSet = new Set((input.package_managers ?? []).map((p) => p.toLowerCase()));
+    const frameworkSet = new Set((input.frameworks ?? []).map((f) => f.toLowerCase()));
+    const fileSet = new Set(input.files_present ?? []);
+    return TOOL_CATALOG.filter((tool) => {
+        // Language gate
+        const langMatch = tool.applies_to.includes('all') ||
+            tool.applies_to.some((tag) => langSet.has(tag));
+        if (!langMatch) {
+            return false;
+        }
+        // Package-manager gate
+        if (tool.requires?.package_manager?.length) {
+            const anyMatch = tool.requires.package_manager.some((pm) => pmSet.has(pm));
+            if (!anyMatch) {
+                return false;
+            }
+        }
+        // Framework gate
+        if (tool.requires?.framework?.length) {
+            const anyMatch = tool.requires.framework.some((fw) => frameworkSet.has(fw));
+            if (!anyMatch) {
+                return false;
+            }
+        }
+        // File-presence gate
+        if (tool.requires?.file_present?.length) {
+            const anyMatch = tool.requires.file_present.some((f) => fileSet.has(f));
+            if (!anyMatch) {
+                return false;
+            }
+        }
+        return true;
+    });
+}

package/dist/phases/quality-benchmark/tool-runner.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Tool execution layer for the quality-benchmark phase.
+ *
+ * Three operations exposed to the rest of the phase (and ultimately to
+ * the LLM via the MCP server in `mcp-server.ts`):
+ *
+ *   probeTool(id, ctx)    -> { available, version, install_command }
+ *   installTool(id, ctx)  -> { installed, version, error }
+ *   executeTool(id, ctx)  -> { summary, run, parser_output }
+ *
+ * All commands come from the authoritative `TOOL_CATALOG` — callers may
+ * not pass arbitrary command strings. Outputs are saved to a per-run
+ * scratch directory so the LLM never has to ferry megabytes of JSON
+ * through its context; only the small `ParsedToolOutput` flows back.
+ *
+ * Safety rails enforced here (in addition to those documented in the
+ * rubric):
+ *   - All commands run with cwd = repo root (or an explicit override)
+ *   - Per-command timeout; SIGKILL on overrun
+ *   - No sudo / no system package managers (refused at install time)
+ *   - Captured outputs truncated at 16 MiB to bound disk usage
+ */
+import type { InstallerPrereq, ParsedToolOutput, ToolRunOutput, UnavailableTool } from './types';
+export interface RunnerContext {
+    /** Absolute path to the repo checkout. */
+    repo_root: string;
+    /** Detected package manager (npm/pnpm/yarn) for JS commands. */
+    package_manager?: string;
+    /** Per-run scratch dir (created lazily under ~/.edsger/quality-runs/<run-id>). */
+    scan_dir: string;
+    /** When false, install attempts are skipped (CLI --no-install). */
+    install_enabled: boolean;
+}
+export interface ProbeResult {
+    available: boolean;
+    version: string | null;
+    install_command: string | null;
+    install_prereq: InstallerPrereq;
+    reason?: 'not_found' | 'probe_failed';
+}
+export interface InstallResult {
+    installed: boolean;
+    version: string | null;
+    error?: string;
+}
+export interface ExecuteResult {
+    /** Standardised summary for LLM consumption. */
+    parsed: ParsedToolOutput;
+    /** Audit/metadata record stored in `quality_reports.tool_outputs`. */
+    run: ToolRunOutput;
+    /** True if the runner believes the parser succeeded. */
+    ok: boolean;
+}
+export declare function createRunnerContext(opts: {
+    repo_root: string;
+    package_manager?: string;
+    install_enabled?: boolean;
+    run_id?: string;
+    /** Override scan dir base (defaults to ~/.edsger/quality-runs). */
+    base_dir?: string;
+}): RunnerContext;
+export declare function probeTool(id: string, ctx: RunnerContext): Promise<ProbeResult>;
+export declare function probeInstaller(prereq: InstallerPrereq, ctx: RunnerContext): Promise<boolean>;
+export declare function installTool(id: string, ctx: RunnerContext): Promise<InstallResult>;
+export declare function executeTool(id: string, ctx: RunnerContext): Promise<ExecuteResult>;
+/** Convert a failed probe into the UnavailableTool record stored in DB. */
+export declare function probeToUnavailable(id: string, probe: ProbeResult, reason: UnavailableTool['reason']): UnavailableTool;
+/** Convert an install failure to UnavailableTool. */
+export declare function installFailureToUnavailable(id: string, res: InstallResult): UnavailableTool;