@agentlighthouse/core 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,451 @@
+import { analyzeMcp } from "./analyzers/mcp.js";
+import { analyzeOpenApi } from "./analyzers/openapi.js";
+import { ReadinessAnalyzer } from "./analyzers/readiness.js";
+import { analyzeTaskBenchmarks } from "./analyzers/tasks.js";
+import { compareScanResults } from "./comparison/compare.js";
+import { resolveConfig, resolveProfile } from "./config/profile.js";
+import { detectProject, detectedArtifacts } from "./detection/project.js";
+import { enrichFindingLocations } from "./findings/locations.js";
+import { StarterArtifactGenerator } from "./generators/artifacts.js";
+import { runCommandProbes } from "./probes/commands.js";
+import { LocalFilesystemScanner } from "./scanners/filesystem.js";
+import { calibrateScore } from "./scoring/calibration.js";
+import { TransparentScoringModel } from "./scoring/model.js";
+export const agentLighthouseVersion = "0.1.0-alpha.0";
+export * from "./schemas/types.js";
+export * from "./analyzers/mcp.js";
+export * from "./analyzers/openapi.js";
+export * from "./analyzers/readiness.js";
+export * from "./analyzers/tasks.js";
+export * from "./changes/files.js";
+export * from "./config/profile.js";
+export * from "./comparison/compare.js";
+export * from "./detection/project.js";
+export * from "./findings/helpers.js";
+export * from "./findings/locations.js";
+export * from "./generators/artifacts.js";
+export * from "./probes/commands.js";
+export * from "./reporters/cli.js";
+export * from "./reporters/comparison.js";
+export * from "./reporters/github-summary.js";
+export * from "./reporters/json.js";
+export * from "./reporters/markdown.js";
+export * from "./reporters/pr-summary.js";
+export * from "./reporters/sarif.js";
+export * from "./reporters/shared.js";
+export * from "./scanners/filesystem.js";
+export * from "./scoring/model.js";
+export async function scanProject(projectPath, options = {}) {
+    const startedAt = new Date();
+    const scanner = new LocalFilesystemScanner();
+    const scoring = new TransparentScoringModel();
+    const warnings = [];
+    const errors = [];
+    let signals = await scanner.scan(projectPath, options);
+    const config = resolveConfig(signals);
+    const profile = resolveProfile(signals, options).profile;
+    const probes = {
+        ...config.probes,
+        ...options.probes,
+        allowedScripts: options.probes?.allowedScripts ?? config.probes?.allowedScripts
+    };
+    const analyzer = new ReadinessAnalyzer(profile);
+    const detectedProject = detectProject(signals);
+    const openApi = analyzeOpenApi(signals);
+    const mcp = analyzeMcp(signals);
+    const commandProbeRun = await runCommandProbes(signals, detectedProject, {
+        ...options,
+        probes
+    });
+    const findings = enrichFindingLocations(signals, [
+        ...analyzer.analyze(signals),
+        ...openApi.findings,
+        ...mcp.findings,
+        ...analyzeTaskBenchmarks(signals),
+        ...commandProbeRun.findings
+    ]);
+    const scored = scoring.score(findings, signals);
+    const artifacts = detectedArtifacts(signals);
+    const calibrated = calibrateScore({
+        rawScore: scored.score,
+        findings,
+        signals,
+        detectedProject,
+        detectedArtifacts: artifacts,
+        profile
+    });
+    const completedAt = new Date();
+    signals = {
+        ...signals,
+        warnings: [...signals.warnings, ...warnings],
+        errors: [...signals.errors, ...errors]
+    };
+    return {
+        scanId: createScanId(signals.rootPath, startedAt),
+        scannedPath: signals.rootPath,
+        startedAt: startedAt.toISOString(),
+        completedAt: completedAt.toISOString(),
+        durationMs: completedAt.getTime() - startedAt.getTime(),
+        agentLighthouseVersion,
+        profile,
+        ...scored,
+        ...calibrated,
+        projectName: signals.projectName,
+        findings,
+        scoreInterpretation: interpretScore({
+            score: calibrated.score,
+            signals,
+            apiAnalysis: openApi.analysis,
+            mcpAnalysis: mcp.analysis,
+            commandProbes: commandProbeRun.summary
+        }),
+        apiAnalysis: openApi.analysis,
+        mcpAnalysis: mcp.analysis,
+        commandProbes: commandProbeRun.summary,
+        detectedProject,
+        detectedArtifacts: artifacts,
+        scanStats: {
+            ...signals.scanStats,
+            findingCount: findings.length
+        },
+        ignoredPaths: signals.ignoredPaths,
+        warnings: signals.warnings,
+        errors: signals.errors,
+        projectPath: signals.rootPath,
+        scannedAt: completedAt.toISOString(),
+        recommendedActions: scored.recommendations,
+        signals
+    };
+}
+export async function generateStarterArtifacts(projectPath, options = {}) {
+    const scanner = new LocalFilesystemScanner();
+    const generator = new StarterArtifactGenerator();
+    const signals = await scanner.scan(projectPath, options);
+    return generator.generate(signals);
+}
+function createScanId(projectPath, startedAt) {
+    const input = `${projectPath}:${startedAt.toISOString()}`;
+    let hash = 0;
+    for (let index = 0; index < input.length; index += 1) {
+        hash = (hash * 31 + input.charCodeAt(index)) >>> 0;
+    }
+    return `scan_${hash.toString(16).padStart(8, "0")}`;
+}
+function interpretScore(input) {
+    const humanSignals = [
+        input.signals.artifacts["README.md"]?.exists ? "README present" : undefined,
+        input.signals.docsMarkdownFiles.length > 0
+            ? `${input.signals.docsMarkdownFiles.length} Markdown doc file(s)`
+            : undefined,
+        input.signals.packageJson ? "package metadata present" : undefined,
+        input.apiAnalysis.specFiles.length > 0 ? "OpenAPI spec present" : undefined,
+        input.mcpAnalysis.detected ? "MCP files or dependencies present" : undefined
+    ].filter((signal) => Boolean(signal));
+    const agentSignals = [
+        input.signals.artifacts["AGENTS.md"]?.exists ? "AGENTS.md present" : undefined,
+        input.signals.artifacts["CLAUDE.md"]?.exists ? "CLAUDE.md present" : undefined,
+        input.signals.artifacts["llms.txt"]?.exists ? "llms.txt present" : undefined,
+        input.signals.artifacts[".cursor/rules"]?.exists ? "Cursor rules present" : undefined,
+        input.signals.artifacts[".github/copilot-instructions.md"]?.exists
+            ? "Copilot instructions present"
+            : undefined,
+        input.signals.benchmarkFiles.length > 0 ? "agent task benchmark present" : undefined
+    ].filter((signal) => Boolean(signal));
+    const verifiabilitySignals = [
+        input.signals.packageJson?.scripts.test ? "test script declared" : undefined,
+        input.signals.packageJson?.scripts.lint ? "lint script declared" : undefined,
+        input.signals.packageJson?.scripts.typecheck ? "typecheck script declared" : undefined,
+        input.apiAnalysis.operationsWithExamples > 0
+            ? `${input.apiAnalysis.operationsWithExamples} API operation(s) have examples`
+            : undefined,
+        input.commandProbes.enabled
+            ? `${input.commandProbes.passed}/${input.commandProbes.attempted} command probes passed`
+            : "command probes not run"
+    ].filter((signal) => Boolean(signal));
+    return {
+        agentReadinessScore: input.score,
+        humanReadableProjectSignals: {
+            score: boundedScore(humanSignals.length * 20 + Math.min(input.apiAnalysis.operationCount, 5) * 3),
+            summary: "Human-readable project signals describe conventional repo, docs, examples, and API context.",
+            signals: humanSignals
+        },
+        agentSpecificContextLayer: {
+            score: boundedScore(agentSignals.length * 17),
+            summary: "Agent-specific context is the machine-readable layer that helps coding agents work safely.",
+            signals: agentSignals
+        },
+        verifiability: {
+            score: boundedScore(verifiabilitySignals.filter((signal) => signal !== "command probes not run").length * 20 +
+                (input.commandProbes.enabled ? 15 : 0)),
+            summary: "Verifiability measures whether setup, tests, examples, and workflows can be checked.",
+            signals: verifiabilitySignals
+        }
+    };
+}
+function boundedScore(value) {
+    return Math.max(0, Math.min(100, Math.round(value)));
+}
+export const sampleScanResult = {
+    scanId: "scan_demo",
+    scannedPath: "/sample/agent-ready-project",
+    startedAt: "2026-05-20T00:00:00.000Z",
+    completedAt: "2026-05-20T00:00:00.120Z",
+    durationMs: 120,
+    agentLighthouseVersion,
+    profile: "devtool",
+    projectName: "sample-agent-ready-project",
+    scoringModelVersion: "0.1.0",
+    score: 72,
+    rawScore: 82,
+    scoreConfidence: "medium",
+    scoreConfidenceScore: 76,
+    coverage: {
+        evaluatedChecks: 12,
+        skippedChecks: 0,
+        notApplicableChecks: 2,
+        notEvaluatedChecks: 3,
+        evaluatedCategories: [
+            "agent_instructions",
+            "documentation",
+            "setup_and_tests",
+            "security_and_privacy",
+            "freshness_and_consistency"
+        ],
+        missingCategories: ["examples", "task_benchmarks"],
+        coveragePercent: 80
+    },
+    scoringCaps: [
+        {
+            id: "cap.no-task-benchmarks",
+            maxScore: 90,
+            reason: "No realistic agent task benchmark file was found."
+        }
+    ],
+    scoreInterpretation: {
+        agentReadinessScore: 72,
+        humanReadableProjectSignals: {
+            score: 75,
+            summary: "Human-readable project signals describe conventional repo, docs, examples, and API context.",
+            signals: ["README present", "package metadata present", "OpenAPI spec present"]
+        },
+        agentSpecificContextLayer: {
+            score: 51,
+            summary: "Agent-specific context is the machine-readable layer that helps coding agents work safely.",
+            signals: ["AGENTS.md present", "agent task benchmark present"]
+        },
+        verifiability: {
+            score: 60,
+            summary: "Verifiability measures whether setup, tests, examples, and workflows can be checked.",
+            signals: ["test script declared", "command probes not run"]
+        }
+    },
+    summary: "Useful foundation, but 2 high-priority readiness issue(s) should be fixed.",
+    subscores: [
+        { id: "agent_instructions", label: "Agent Instructions", score: 78, findingsCount: 2 },
+        { id: "documentation", label: "Documentation", score: 82, findingsCount: 1 },
+        { id: "api_and_tooling", label: "API & Tooling", score: 65, findingsCount: 2 },
+        { id: "examples_and_tasks", label: "Examples & Tasks", score: 55, findingsCount: 1 },
+        { id: "security_and_privacy", label: "Security & Privacy", score: 80, findingsCount: 1 },
+        {
+            id: "freshness_and_consistency",
+            label: "Freshness & Consistency",
+            score: 90,
+            findingsCount: 0
+        }
+    ],
+    findings: [
+        {
+            id: "setup.missing-test-script",
+            ruleId: "setup.missing-test-script",
+            title: "No test script in package.json",
+            severity: "high",
+            category: "setup_and_tests",
+            description: "Agents cannot reliably run tests without a package script.",
+            evidence: ['package.json scripts does not include "test".'],
+            recommendation: "Add a package.json test script or document the equivalent command clearly.",
+            affectedFile: "package.json",
+            suggestedFixType: "add_script"
+        },
+        {
+            id: "TASK_BENCHMARK_MISSING",
+            ruleId: "TASK_BENCHMARK_MISSING",
+            title: "Missing agent task benchmark file",
+            severity: "medium",
+            category: "task_benchmarks",
+            description: "The project has no task benchmark describing realistic agent workflows.",
+            evidence: ["No benchmark file was found."],
+            recommendation: "Add a benchmark file with realistic developer tasks.",
+            affectedFile: "agentlighthouse.tasks.yaml",
+            suggestedFixType: "create_file"
+        },
+        {
+            id: "security.agent-secret-guidance-missing",
+            ruleId: "security.agent-secret-guidance-missing",
+            title: "Instructions do not tell agents how to handle secrets",
+            severity: "medium",
+            category: "security_and_privacy",
+            description: "Agent-facing instructions should state how to avoid exposing secrets or private data.",
+            evidence: ["No secret/privacy guidance was detected in AGENTS.md."],
+            recommendation: "Add a security section explaining secret handling and external LLM constraints.",
+            affectedFile: "AGENTS.md",
+            suggestedFixType: "add_section"
+        }
+    ],
+    recommendations: [
+        "Add or document setup, test, lint, and typecheck commands.",
+        "Add task benchmarks for the top developer workflows agents should complete.",
+        "Document secret-handling and privacy rules for agent workflows."
+    ],
+    apiAnalysis: {
+        specFiles: ["openapi.yaml"],
+        operationCount: 8,
+        operationsWithExamples: 4,
+        operationsMissingDescriptions: 2,
+        destructiveOperations: ["openapi.yaml: DELETE /v1/widgets/{id} (deleteWidget)"],
+        authSchemes: ["bearerAuth"],
+        weakOperations: ["openapi.yaml: POST /v1/widgets (createWidget)"],
+        highRiskOperations: ["openapi.yaml: DELETE /v1/widgets/{id} (deleteWidget)"]
+    },
+    mcpAnalysis: {
+        detected: false,
+        files: [],
+        toolCount: 0,
+        toolsWithSchemas: 0,
+        toolsWithExamples: 0,
+        ambiguousTools: [],
+        destructiveTools: [],
+        privacySensitiveTools: [],
+        weakTools: []
+    },
+    commandProbes: {
+        enabled: false,
+        attempted: 0,
+        skipped: 3,
+        passed: 0,
+        failed: 0,
+        timedOut: 0,
+        results: []
+    },
+    detectedProject: {
+        type: "node_typescript",
+        name: "sample-agent-ready-project",
+        confidence: 0.9,
+        evidence: ["package.json plus TypeScript config or source files detected."],
+        packageManager: "pnpm",
+        frameworks: ["TypeScript", "Vitest"]
+    },
+    detectedArtifacts: [
+        {
+            path: "AGENTS.md",
+            exists: true,
+            kind: "file",
+            role: "Primary coding-agent instructions",
+            quality: "partial",
+            notes: ["Includes setup commands.", "Missing security/privacy guidance."]
+        },
+        {
+            path: "llms.txt",
+            exists: false,
+            kind: "missing",
+            role: "LLM-readable project map",
+            quality: "missing",
+            notes: ["Artifact exists but no text content was available for quality checks."]
+        }
+    ],
+    scanStats: {
+        filesScanned: 42,
+        textFilesRead: 38,
+        bytesRead: 42000,
+        docsMarkdownFileCount: 3,
+        openApiFileCount: 0,
+        benchmarkFileCount: 0,
+        findingCount: 3
+    },
+    ignoredPaths: ["node_modules"],
+    errors: [],
+    warnings: [],
+    projectPath: "/sample/agent-ready-project",
+    scannedAt: "2026-05-20T00:00:00.120Z",
+    recommendedActions: [
+        "Add or document setup, test, lint, and typecheck commands.",
+        "Add task benchmarks for the top developer workflows agents should complete.",
+        "Document secret-handling and privacy rules for agent workflows."
+    ],
+    signals: {
+        rootPath: "/sample/agent-ready-project",
+        projectName: "sample-agent-ready-project",
+        scannedFiles: ["README.md", "package.json", "AGENTS.md"],
+        artifacts: {
+            "AGENTS.md": { path: "AGENTS.md", exists: true, kind: "file", sizeBytes: 600 },
+            "CLAUDE.md": { path: "CLAUDE.md", exists: false, kind: "missing" },
+            "llms.txt": { path: "llms.txt", exists: false, kind: "missing" },
+            "README.md": { path: "README.md", exists: true, kind: "file", sizeBytes: 2000 },
+            ".cursor/rules": { path: ".cursor/rules", exists: false, kind: "missing" },
+            ".github/copilot-instructions.md": {
+                path: ".github/copilot-instructions.md",
+                exists: false,
+                kind: "missing"
+            },
+            ".agentlighthouseignore": { path: ".agentlighthouseignore", exists: true, kind: "file" }
+        },
+        docsMarkdownFiles: ["docs/ARCHITECTURE.md"],
+        openApiFiles: [],
+        mcpFiles: [],
+        configFiles: ["package.json"],
+        benchmarkFiles: [],
+        ignoredPaths: ["node_modules"],
+        warnings: [],
+        errors: [],
+        scanStats: {
+            filesScanned: 42,
+            textFilesRead: 38,
+            bytesRead: 42000,
+            docsMarkdownFileCount: 1,
+            openApiFileCount: 0,
+            benchmarkFileCount: 0
+        },
+        packageJson: {
+            path: "package.json",
+            name: "sample-agent-ready-project",
+            packageManager: "pnpm@10.33.0",
+            scripts: { build: "tsc" },
+            dependencies: [],
+            devDependencies: []
+        },
+        textByPath: {}
+    }
+};
+export const sampleComparisonResult = compareScanResults({
+    ...sampleScanResult,
+    scanId: "scan_demo_baseline",
+    completedAt: "2026-05-19T00:00:00.120Z",
+    score: 63,
+    scoreConfidence: "low",
+    scoreConfidenceScore: 55,
+    coverage: {
+        ...sampleScanResult.coverage,
+        coveragePercent: 51
+    },
+    findings: [
+        ...sampleScanResult.findings,
+        {
+            ...sampleScanResult.findings[0],
+            id: "llms.missing",
+            ruleId: "llms.missing",
+            title: "Missing llms.txt",
+            severity: "medium",
+            category: "agent_instructions",
+            description: "The baseline lacked an LLM-readable project map.",
+            evidence: ["llms.txt was not found at the repository root."],
+            recommendation: "Create llms.txt with links to README, docs, architecture, and examples.",
+            affectedFile: "llms.txt",
+            suggestedFixType: "create_file"
+        }
+    ]
+}, sampleScanResult, {
+    changedFiles: [
+        { path: "package.json", status: "modified", source: "explicit" },
+        { path: "AGENTS.md", status: "modified", source: "explicit" },
+        { path: "llms.txt", status: "added", source: "explicit" }
+    ]
+});

package/dist/probes/commands.d.ts

@@ -0,0 +1,7 @@
+import type { CommandProbeSummary, DetectedProject, Finding, ProjectSignals, ScanOptions } from "../schemas/types.js";
+export interface CommandProbeRun {
+    summary: CommandProbeSummary;
+    findings: Finding[];
+}
+export declare function runCommandProbes(signals: ProjectSignals, detectedProject: DetectedProject, options?: ScanOptions): Promise<CommandProbeRun>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/probes/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/probes/commands.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,mBAAmB,EACnB,eAAe,EACf,OAAO,EACP,cAAc,EACd,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAM7B,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,EACvB,eAAe,EAAE,eAAe,EAChC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAsE1B"}

package/dist/probes/commands.js

@@ -0,0 +1,198 @@
+import { spawn } from "node:child_process";
+import { finding } from "../findings/helpers.js";
+const defaultAllowedScripts = ["test", "typecheck", "lint"];
+const sensitivePattern = /(api[_-]?key|token|secret|authorization)\s*[:=]\s*["']?[A-Za-z0-9_.-]{8,}/gi;
+export async function runCommandProbes(signals, detectedProject, options = {}) {
+    const probeOptions = options.probes;
+    if (!probeOptions?.commands) {
+        return {
+            summary: {
+                enabled: false,
+                attempted: 0,
+                skipped: plannedScripts(signals, probeOptions?.allowedScripts).length,
+                passed: 0,
+                failed: 0,
+                timedOut: 0,
+                results: []
+            },
+            findings: [
+                finding({
+                    id: "COMMAND_VERIFICATION_SKIPPED",
+                    title: "Command verification probes were skipped",
+                    severity: "info",
+                    category: "setup_and_tests",
+                    description: "Static analysis is default; project commands are not executed unless explicitly enabled.",
+                    evidence: ["Run with --probe commands or --run-probes to execute safe script probes."],
+                    recommendation: "Use command probes in trusted local or CI environments when you want executable verification.",
+                    agentFailureMode: "Without command probes, AgentLighthouse can tell agents what commands appear to exist, but not whether they currently pass.",
+                    fixExample: "agentlighthouse scan . --probe commands",
+                    suggestedFixType: "none"
+                })
+            ]
+        };
+    }
+    const scripts = plannedScripts(signals, probeOptions.allowedScripts);
+    const results = [];
+    for (const script of scripts) {
+        if (!signals.packageJson?.scripts[script]) {
+            results.push({
+                script,
+                command: commandForScript(detectedProject.packageManager, script),
+                status: "skipped",
+                exitCode: null,
+                durationMs: 0,
+                reason: "Script is not declared in package.json."
+            });
+            continue;
+        }
+        results.push(await runScript(signals.rootPath, commandForScript(detectedProject.packageManager, script), script, probeOptions.timeoutMs ?? 30_000));
+    }
+    const findings = findingsForResults(results);
+    return {
+        summary: {
+            enabled: true,
+            attempted: results.filter((result) => result.status !== "skipped").length,
+            skipped: results.filter((result) => result.status === "skipped").length,
+            passed: results.filter((result) => result.status === "passed").length,
+            failed: results.filter((result) => result.status === "failed").length,
+            timedOut: results.filter((result) => result.status === "timed_out").length,
+            results
+        },
+        findings
+    };
+}
+function plannedScripts(signals, allowedScripts) {
+    const allowed = allowedScripts && allowedScripts.length > 0 ? allowedScripts : defaultAllowedScripts;
+    void signals;
+    return [...new Set(allowed)].filter((script) => ["test", "typecheck", "lint", "build"].includes(script));
+}
+function commandForScript(packageManager, script) {
+    if (packageManager === "pnpm")
+        return `pnpm run ${script}`;
+    if (packageManager === "yarn")
+        return `yarn ${script}`;
+    if (packageManager === "bun")
+        return `bun run ${script}`;
+    return `npm run ${script}`;
+}
+async function runScript(cwd, command, script, timeoutMs) {
+    const startedAt = Date.now();
+    const [binary, ...args] = command.split(" ");
+    if (!binary) {
+        return {
+            script,
+            command,
+            status: "failed",
+            exitCode: null,
+            durationMs: 0,
+            reason: "Command could not be parsed."
+        };
+    }
+    return await new Promise((resolve) => {
+        const child = spawn(binary, args, { cwd, shell: false });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+        }, timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            resolve({
+                script,
+                command,
+                status: "failed",
+                exitCode: null,
+                durationMs: Date.now() - startedAt,
+                stderrExcerpt: sanitizeOutput(error.message)
+            });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timeout);
+            resolve({
+                script,
+                command,
+                status: timedOut ? "timed_out" : code === 0 ? "passed" : "failed",
+                exitCode: code,
+                durationMs: Date.now() - startedAt,
+                stdoutExcerpt: sanitizeOutput(stdout),
+                stderrExcerpt: sanitizeOutput(stderr)
+            });
+        });
+    });
+}
+function findingsForResults(results) {
+    const findings = [];
+    const missing = results.filter((result) => result.status === "skipped");
+    const failed = results.filter((result) => result.status === "failed");
+    const timedOut = results.filter((result) => result.status === "timed_out");
+    const redacted = results.filter((result) => [result.stdoutExcerpt, result.stderrExcerpt].some((excerpt) => excerpt?.includes("[redacted]")));
+    if (missing.length > 0) {
+        findings.push(finding({
+            id: "COMMAND_DECLARED_BUT_MISSING",
+            title: "Expected verification commands are missing",
+            severity: "medium",
+            category: "setup_and_tests",
+            description: "One or more expected safe scripts were not declared in package.json.",
+            evidence: missing.map((result) => result.script),
+            recommendation: "Add missing scripts or remove them from probe configuration.",
+            agentFailureMode: "A coding agent may be told to verify changes with a command that does not exist.",
+            fixExample: "Add scripts.test, scripts.typecheck, and scripts.lint where applicable.",
+            affectedFile: "package.json",
+            suggestedFixType: "add_script"
+        }));
+    }
+    if (failed.length > 0) {
+        findings.push(finding({
+            id: "COMMAND_PROBE_FAILED",
+            title: "Command probe failed",
+            severity: "high",
+            category: "setup_and_tests",
+            description: "A safe opt-in command probe exited unsuccessfully.",
+            evidence: failed.map((result) => `${result.command} exited ${result.exitCode}`),
+            recommendation: "Fix the failing command or document known prerequisites.",
+            agentFailureMode: "A coding agent may follow documented verification steps and hit unexplained failures.",
+            fixExample: "Make the script pass locally or document setup required before running it.",
+            suggestedFixType: "review_manually"
+        }));
+    }
+    if (timedOut.length > 0) {
+        findings.push(finding({
+            id: "COMMAND_PROBE_TIMEOUT",
+            title: "Command probe timed out",
+            severity: "medium",
+            category: "setup_and_tests",
+            description: "A safe opt-in command probe exceeded the configured timeout.",
+            evidence: timedOut.map((result) => `${result.command} timed out after ${result.durationMs}ms`),
+            recommendation: "Adjust probe timeout or split long-running checks into faster scripts.",
+            agentFailureMode: "A coding agent may not know whether verification hung or simply needs more time.",
+            fixExample: "Expose a fast smoke test script for agent and CI verification.",
+            suggestedFixType: "review_manually"
+        }));
+    }
+    if (redacted.length > 0) {
+        findings.push(finding({
+            id: "COMMAND_OUTPUT_REDACTED",
+            title: "Command probe output was redacted",
+            severity: "info",
+            category: "security_and_privacy",
+            description: "Probe output contained secret-like text and was redacted in the scan result.",
+            evidence: redacted.map((result) => result.command),
+            recommendation: "Ensure scripts do not print secrets or credentials.",
+            agentFailureMode: "A coding agent reviewing logs could accidentally expose sensitive values.",
+            fixExample: "Mask tokens in script output and use placeholders in examples.",
+            suggestedFixType: "review_manually"
+        }));
+    }
+    return findings;
+}
+function sanitizeOutput(value) {
+    return value.replace(sensitivePattern, "$1=[redacted]").slice(0, 1200);
+}

package/dist/reporters/cli.d.ts

@@ -0,0 +1,4 @@
+import type { ScanResult } from "../schemas/types.js";
+export { renderMarkdownReport } from "./markdown.js";
+export declare function renderCliReport(result: ScanResult, color?: boolean): string;
+//# sourceMappingURL=cli.d.ts.map

package/dist/reporters/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/reporters/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,UAAQ,GAAG,MAAM,CA2CzE"}