@agentlighthouse/cli 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentLighthouse contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @agentlighthouse/cli
+
+Command-line interface for AgentLighthouse, a local-first agent-readiness scanner.
+
+The package provides the `agentlighthouse` binary:
+
+```bash
+agentlighthouse scan .
+agentlighthouse baseline create . --output agentlighthouse-baseline.json
+agentlighthouse scan . --baseline agentlighthouse-baseline.json --report-dir agentlighthouse-reports
+```
+
+The package is prepared for public alpha packaging, but npm publishing is not part of this repository change. For source development, use the root workspace commands documented in the repository README.

package/dist/commands/baseline.d.ts

@@ -0,0 +1,12 @@
+import type { ScanProfile } from "@agentlighthouse/core";
+export interface BaselineCreateOptions {
+    output?: string;
+    profile?: ScanProfile;
+}
+export interface BaselineValidateOptions {
+    json?: boolean;
+}
+export declare function runBaselineCreateCommand(targetPath: string, options: BaselineCreateOptions): Promise<void>;
+export declare function runBaselineValidateCommand(baselinePath: string, options?: BaselineValidateOptions): Promise<void>;
+export declare function runBaselineSummaryCommand(baselinePath: string): Promise<void>;
+//# sourceMappingURL=baseline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../../src/commands/baseline.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIzD,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,0BAA0B,CAC9C,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnF"}

package/dist/commands/baseline.js

@@ -0,0 +1,55 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { renderJsonReport, scanProject } from "@agentlighthouse/core";
+import { resolveFromInvocationCwd } from "../pathing.js";
+import { readScanResultFile } from "./compare.js";
+export async function runBaselineCreateCommand(targetPath, options) {
+    const output = options.output ?? "agentlighthouse-baseline.json";
+    const outputPath = resolveFromInvocationCwd(output);
+    const result = await scanProject(resolveFromInvocationCwd(targetPath), {
+        profile: options.profile
+    });
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, renderJsonReport(result), "utf8");
+    process.stdout.write([
+        "AgentLighthouse baseline created.",
+        `Output: ${output}`,
+        `Score: ${result.score}/100`,
+        `Confidence: ${result.scoreConfidence} (${result.scoreConfidenceScore}/100)`,
+        `Coverage: ${result.coverage.coveragePercent}%`,
+        `Profile: ${result.profile}`,
+        "",
+        "A baseline is a normal scan-result JSON file. Commit or update it intentionally when the team accepts the current agent-readiness state."
+    ].join("\n") + "\n");
+}
+export async function runBaselineValidateCommand(baselinePath, options = {}) {
+    void options;
+    const result = await readScanResultFile(baselinePath);
+    process.stdout.write(`${baselineSummary(result, baselinePath)}\n`);
+}
+export async function runBaselineSummaryCommand(baselinePath) {
+    const result = await readScanResultFile(baselinePath);
+    process.stdout.write(`${baselineSummary(result, baselinePath)}\n`);
+}
+function baselineSummary(result, baselinePath) {
+    const severityCounts = result.findings.reduce((counts, finding) => {
+        counts[finding.severity] = (counts[finding.severity] ?? 0) + 1;
+        return counts;
+    }, {});
+    return [
+        `AgentLighthouse baseline: ${baselinePath}`,
+        `Scan ID: ${result.scanId}`,
+        `Project: ${result.projectName ?? result.detectedProject.name ?? result.scannedPath}`,
+        `Score: ${result.score}/100`,
+        `Confidence: ${result.scoreConfidence} (${result.scoreConfidenceScore}/100)`,
+        `Coverage: ${result.coverage.coveragePercent}%`,
+        `Profile: ${result.profile}`,
+        `Completed: ${result.completedAt}`,
+        `AgentLighthouse version: ${result.agentLighthouseVersion}`,
+        `Scoring model: ${result.scoringModelVersion}`,
+        `Findings: ${result.findings.length}`,
+        `Severity counts: ${Object.entries(severityCounts)
+            .map(([severity, count]) => `${severity}=${count}`)
+            .join(", ")}`
+    ].join("\n");
+}

package/dist/commands/compare.d.ts

@@ -0,0 +1,226 @@
+import type { ChangedFile, ComparisonResult, Severity } from "@agentlighthouse/core";
+export type CompareFormat = "text" | "json" | "markdown" | "pr-summary";
+export interface CompareCommandOptions {
+    baseline?: string;
+    current?: string;
+    format?: CompareFormat;
+    output?: string;
+    failOnRegression?: boolean;
+    failOnScoreDrop?: string;
+    failOnCoverageDrop?: string;
+    failOnConfidenceDrop?: string;
+    failOnNewSeverity?: Severity;
+    failOnNewCritical?: boolean;
+    failOnNewHigh?: boolean;
+    changedFiles?: string;
+    gitBase?: string;
+    gitHead?: string;
+    failOnNewChangedSeverity?: Severity;
+    failOnNewChangedCritical?: boolean;
+    failOnNewChangedHigh?: boolean;
+    failOnPrRegression?: boolean;
+}
+export declare function runCompareCommand(options: CompareCommandOptions): Promise<void>;
+export declare function readScanResultFile(filePath: string): Promise<{
+    projectName: string;
+    ignoredPaths: string[];
+    warnings: string[];
+    errors: string[];
+    scanStats: {
+        filesScanned: number;
+        textFilesRead: number;
+        bytesRead: number;
+        docsMarkdownFileCount: number;
+        openApiFileCount: number;
+        benchmarkFileCount: number;
+        findingCount: number;
+    };
+    score: number;
+    summary: string;
+    signals: {
+        rootPath: string;
+        projectName: string;
+        scannedFiles: string[];
+        artifacts: Record<string, {
+            path: string;
+            exists: boolean;
+            kind: "file" | "directory" | "missing";
+            sizeBytes?: number | undefined;
+            contentPreview?: string | undefined;
+        }>;
+        docsMarkdownFiles: string[];
+        openApiFiles: string[];
+        mcpFiles: string[];
+        configFiles: string[];
+        benchmarkFiles: string[];
+        ignoredPaths: string[];
+        warnings: string[];
+        errors: string[];
+        scanStats: {
+            filesScanned: number;
+            textFilesRead: number;
+            bytesRead: number;
+            docsMarkdownFileCount: number;
+            openApiFileCount: number;
+            benchmarkFileCount: number;
+        };
+        textByPath: Record<string, string>;
+        packageJson?: {
+            path: string;
+            scripts: Record<string, string>;
+            dependencies: string[];
+            devDependencies: string[];
+            name?: string | undefined;
+            packageManager?: string | undefined;
+        } | undefined;
+    };
+    durationMs: number;
+    scanId: string;
+    scannedPath: string;
+    startedAt: string;
+    completedAt: string;
+    agentLighthouseVersion: string;
+    profile: "default" | "devtool" | "api" | "mcp" | "docs" | "library" | "internal";
+    scoringModelVersion: string;
+    rawScore: number;
+    scoreConfidence: "high" | "medium" | "low";
+    scoreConfidenceScore: number;
+    coverage: {
+        evaluatedChecks: number;
+        skippedChecks: number;
+        notApplicableChecks: number;
+        notEvaluatedChecks: number;
+        evaluatedCategories: ("agent_instructions" | "documentation" | "api_schema" | "mcp_tools" | "examples" | "setup_and_tests" | "security_and_privacy" | "task_benchmarks" | "repo_structure" | "freshness_and_consistency")[];
+        missingCategories: ("agent_instructions" | "documentation" | "api_schema" | "mcp_tools" | "examples" | "setup_and_tests" | "security_and_privacy" | "task_benchmarks" | "repo_structure" | "freshness_and_consistency")[];
+        coveragePercent: number;
+    };
+    scoringCaps: {
+        id: string;
+        maxScore: number;
+        reason: string;
+    }[];
+    scoreInterpretation: {
+        agentReadinessScore: number;
+        humanReadableProjectSignals: {
+            score: number;
+            summary: string;
+            signals: string[];
+        };
+        agentSpecificContextLayer: {
+            score: number;
+            summary: string;
+            signals: string[];
+        };
+        verifiability: {
+            score: number;
+            summary: string;
+            signals: string[];
+        };
+    };
+    subscores: {
+        id: string;
+        label: string;
+        score: number;
+        findingsCount: number;
+    }[];
+    findings: {
+        id: string;
+        ruleId: string;
+        title: string;
+        severity: "critical" | "high" | "medium" | "low" | "info";
+        category: "agent_instructions" | "documentation" | "api_schema" | "mcp_tools" | "examples" | "setup_and_tests" | "security_and_privacy" | "task_benchmarks" | "repo_structure" | "freshness_and_consistency";
+        description: string;
+        evidence: string[];
+        recommendation: string;
+        suggestedFixType: "create_file" | "update_file" | "add_section" | "add_script" | "add_example" | "review_manually" | "none";
+        locationKey?: string | undefined;
+        subject?: string | undefined;
+        fingerprint?: string | undefined;
+        identityParts?: string[] | undefined;
+        affectedFile?: string | undefined;
+        location?: {
+            file: string;
+            sourceKind: "mcp" | "unknown" | "markdown" | "openapi" | "task" | "config" | "project";
+            symbol?: string | undefined;
+            startLine?: number | undefined;
+            startColumn?: number | undefined;
+            endLine?: number | undefined;
+            endColumn?: number | undefined;
+            locationKey?: string | undefined;
+            subject?: string | undefined;
+        } | undefined;
+        agentFailureMode?: string | undefined;
+        fixExample?: string | undefined;
+        docsLinks?: string[] | undefined;
+    }[];
+    recommendations: string[];
+    apiAnalysis: {
+        specFiles: string[];
+        operationCount: number;
+        operationsWithExamples: number;
+        operationsMissingDescriptions: number;
+        destructiveOperations: string[];
+        authSchemes: string[];
+        weakOperations: string[];
+        highRiskOperations: string[];
+    };
+    mcpAnalysis: {
+        detected: boolean;
+        files: string[];
+        toolCount: number;
+        toolsWithSchemas: number;
+        toolsWithExamples: number;
+        ambiguousTools: string[];
+        destructiveTools: string[];
+        privacySensitiveTools: string[];
+        weakTools: string[];
+    };
+    commandProbes: {
+        passed: number;
+        failed: number;
+        skipped: number;
+        enabled: boolean;
+        attempted: number;
+        timedOut: number;
+        results: {
+            status: "passed" | "failed" | "timed_out" | "skipped";
+            command: string;
+            script: string;
+            exitCode: number | null;
+            durationMs: number;
+            reason?: string | undefined;
+            stdoutExcerpt?: string | undefined;
+            stderrExcerpt?: string | undefined;
+        }[];
+    };
+    detectedProject: {
+        type: "unknown" | "node_typescript" | "node_javascript" | "python" | "rust" | "go" | "docs_only" | "openapi_project" | "mcp_project";
+        evidence: string[];
+        name: string;
+        packageManager: "unknown" | "go" | "pnpm" | "npm" | "yarn" | "bun" | "pip" | "poetry" | "cargo";
+        confidence: number;
+        frameworks: string[];
+    };
+    detectedArtifacts: {
+        path: string;
+        exists: boolean;
+        kind: "file" | "directory" | "missing";
+        role: string;
+        quality: "unknown" | "missing" | "thin" | "partial" | "strong";
+        notes: string[];
+    }[];
+    projectPath?: string | undefined;
+    scannedAt?: string | undefined;
+    recommendedActions?: string[] | undefined;
+}>;
+export declare function readChangedFiles(options: Pick<CompareCommandOptions, "changedFiles" | "gitBase" | "gitHead">): Promise<ChangedFile[] | undefined>;
+export declare function renderComparisonResult(result: ComparisonResult, format: CompareFormat, options: {
+    status: "passed" | "failed";
+    reasons: string[];
+    reportPaths: string[];
+}): string;
+export declare function evaluateComparisonGates(result: ComparisonResult, options: CompareCommandOptions): {
+    failed: boolean;
+    reasons: string[];
+};
+//# sourceMappingURL=compare.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../src/commands/compare.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGrF,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,CAAC;AAIxE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,QAAQ,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB,CAAC,EAAE,QAAQ,CAAC;IACpC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqCrF;AAED,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;qBAmN450C,CAAC;0BAAgD,CAAC;;;;;;;;;;;;;;;;;;;mBAAslB,CAAC;;;;;gBAAsK,CAAC;0BAAgD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAAi0E,CAAC;eAAqC,CAAC;mBAAyC,CAAC;qBAA2C,CAAC;oBAA4C,CAAC;gBAAsC,CAAC;;;kBAAoJ,CAAC;qBAA2C,CAAC;uBAA6C,CAAC;mBAAyC,CAAC;qBAA2C,CAAC;uBAA6C,CAAC;mBAAyC,CAAC;;wBAAqE,CAAC;kBAAwC,CAAC;iBAAuC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA2kC,CAAC;yBAA+C,CAAC;yBAA+C,CAAC;;;;;;;;;;;;;;;;;;;;;;GA9Kvi/C;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,IAAI,CAAC,qBAAqB,EAAE,cAAc,GAAG,SAAS,GAAG,SAAS,CAAC,GAC3E,OAAO,CAAC,WAAW,EAAE,GAAG,SAAS,CAAC,CAgDpC;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE;IAAE,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,GACjF,MAAM,CAWR;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,qBAAqB,GAC7B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAwFxC"}

package/dist/commands/compare.js

@@ -0,0 +1,198 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { compareScanResults, parseChangedFilesText, parseGitNameStatus, renderComparisonCliReport, renderComparisonJsonReport, renderComparisonMarkdownReport, renderComparisonPrSummaryReport, scanResultSchema, severityRank } from "@agentlighthouse/core";
+import { resolveFromInvocationCwd } from "../pathing.js";
+const execFileAsync = promisify(execFile);
+export async function runCompareCommand(options) {
+    if (!options.baseline) {
+        throw new Error("Missing --baseline <file>.");
+    }
+    if (!options.current) {
+        throw new Error("Missing --current <file>.");
+    }
+    const format = options.format ?? "text";
+    if (!["text", "json", "markdown", "pr-summary"].includes(format)) {
+        throw new Error(`Unsupported format "${format}". Use text, json, markdown, or pr-summary.`);
+    }
+    const baseline = await readScanResultFile(options.baseline);
+    const current = await readScanResultFile(options.current);
+    const changedFiles = await readChangedFiles(options);
+    const comparison = compareScanResults(baseline, current, { changedFiles });
+    const gateResult = evaluateComparisonGates(comparison, options);
+    const outputOption = options.output;
+    const outputPath = outputOption ? resolveFromInvocationCwd(outputOption) : undefined;
+    const rendered = renderComparisonResult(comparison, format, {
+        status: gateResult.failed ? "failed" : "passed",
+        reasons: gateResult.reasons,
+        reportPaths: outputOption ? [outputOption] : []
+    });
+    if (outputPath) {
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, rendered, "utf8");
+    }
+    process.stdout.write(`${rendered}\n`);
+    if (gateResult.failed) {
+        for (const reason of gateResult.reasons) {
+            process.stderr.write(`${reason}\n`);
+        }
+        process.exitCode = 1;
+    }
+}
+export async function readScanResultFile(filePath) {
+    const resolved = resolveFromInvocationCwd(filePath);
+    let raw;
+    try {
+        raw = await readFile(resolved, "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read scan result JSON at ${filePath}. Expected a file produced by: agentlighthouse scan . --format json --output ${filePath}. ${message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON in ${filePath}. Expected AgentLighthouse scan-result JSON. Recreate it with: agentlighthouse scan . --format json --output ${filePath}. ${message}`);
+    }
+    if (parsed && typeof parsed === "object" && "comparisonId" in parsed && !("scanId" in parsed)) {
+        throw new Error(`${filePath} is a comparison report, not a scan-result JSON file. Use files produced by: agentlighthouse scan . --format json --output current.json`);
+    }
+    const result = scanResultSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`${filePath} is not a valid AgentLighthouse scan-result JSON file. Expected fields include scanId, score, coverage, findings, and scoringModelVersion. Recreate it with: agentlighthouse scan . --format json --output ${filePath}`);
+    }
+    if (result.data.scoringModelVersion !== "0.1.0") {
+        throw new Error(`${filePath} uses unsupported scoring model ${result.data.scoringModelVersion}. This CLI supports scoring model 0.1.0. Regenerate the file with this CLI version.`);
+    }
+    return result.data;
+}
+export async function readChangedFiles(options) {
+    const hasExplicit = Boolean(options.changedFiles);
+    const hasGit = Boolean(options.gitBase || options.gitHead);
+    if (hasExplicit && hasGit) {
+        throw new Error("Use either --changed-files or --git-base/--git-head, not both.");
+    }
+    if (options.changedFiles) {
+        const resolved = resolveFromInvocationCwd(options.changedFiles);
+        try {
+            return parseChangedFilesText(await readFile(resolved, "utf8"), "explicit");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Could not read changed-files list at ${options.changedFiles}. Create one with: git diff --name-status origin/main...HEAD > changed-files.txt. ${message}`);
+        }
+    }
+    if (options.gitBase || options.gitHead) {
+        if (!options.gitBase || !options.gitHead) {
+            throw new Error("Both --git-base and --git-head are required for git changed-file detection.");
+        }
+        try {
+            const { stdout } = await execFileAsync("git", ["diff", "--name-status", "-z", `${options.gitBase}...${options.gitHead}`], {
+                cwd: process.cwd(),
+                encoding: "utf8",
+                maxBuffer: 1024 * 1024
+            });
+            const files = parseGitNameStatus(stdout, "git");
+            if (files.length === 0) {
+                process.stderr.write(`Git diff ${options.gitBase}...${options.gitHead} returned no changed files; PR impact sections will be empty.\n`);
+            }
+            return files;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Unable to read changed files from git refs ${options.gitBase}...${options.gitHead}: ${message}`);
+        }
+    }
+    return undefined;
+}
+export function renderComparisonResult(result, format, options) {
+    if (format === "json") {
+        return renderComparisonJsonReport(result);
+    }
+    if (format === "markdown") {
+        return renderComparisonMarkdownReport(result, options);
+    }
+    if (format === "pr-summary") {
+        return renderComparisonPrSummaryReport(result, options);
+    }
+    return renderComparisonCliReport(result);
+}
+export function evaluateComparisonGates(result, options) {
+    const reasons = [];
+    const scoreDrop = parseOptionalNumber(options.failOnScoreDrop, "fail-on-score-drop");
+    const coverageDrop = parseOptionalNumber(options.failOnCoverageDrop, "fail-on-coverage-drop");
+    const confidenceDrop = parseOptionalNumber(options.failOnConfidenceDrop, "fail-on-confidence-drop");
+    const newSeverity = options.failOnNewCritical
+        ? "critical"
+        : options.failOnNewHigh
+            ? "high"
+            : options.failOnNewSeverity;
+    const newChangedSeverity = options.failOnNewChangedCritical
+        ? "critical"
+        : options.failOnNewChangedHigh
+            ? "high"
+            : options.failOnNewChangedSeverity;
+    if (options.failOnRegression && result.summary.regressionDetected) {
+        reasons.push(`AgentLighthouse comparison verdict is ${result.summary.verdict}.`);
+    }
+    if (scoreDrop !== undefined && result.deltas.scoreDelta <= -scoreDrop) {
+        reasons.push(`AgentLighthouse score dropped by ${Math.abs(result.deltas.scoreDelta)} point(s), meeting threshold ${scoreDrop}.`);
+    }
+    if (coverageDrop !== undefined && result.deltas.coverageDelta <= -coverageDrop) {
+        reasons.push(`AgentLighthouse coverage dropped by ${Math.abs(result.deltas.coverageDelta)} point(s), meeting threshold ${coverageDrop}.`);
+    }
+    if (confidenceDrop !== undefined && result.deltas.confidenceDelta <= -confidenceDrop) {
+        reasons.push(`AgentLighthouse confidence score dropped by ${Math.abs(result.deltas.confidenceDelta)} point(s), meeting threshold ${confidenceDrop}.`);
+    }
+    if (newSeverity) {
+        if (!["critical", "high", "medium", "low", "info"].includes(newSeverity)) {
+            throw new Error(`Unsupported fail-on-new-severity "${newSeverity}".`);
+        }
+        const threshold = severityRank(newSeverity);
+        const newFindings = result.findings.new.filter((finding) => severityRank(finding.severity) >= threshold);
+        if (newFindings.length > 0) {
+            reasons.push(`AgentLighthouse found ${newFindings.length} new finding(s) at or above ${newSeverity} severity.`);
+        }
+    }
+    if (newChangedSeverity) {
+        if (!["critical", "high", "medium", "low", "info"].includes(newChangedSeverity)) {
+            throw new Error(`Unsupported fail-on-new-changed-severity "${newChangedSeverity}".`);
+        }
+        if (!result.prImpact) {
+            reasons.push("Changed-file gate requested, but no changed-file information was supplied. Use --changed-files or --git-base/--git-head.");
+        }
+        else {
+            const threshold = severityRank(newChangedSeverity);
+            const changedFindings = result.prImpact.newFindingsOnChangedFiles.filter((finding) => severityRank(finding.severity) >= threshold);
+            if (changedFindings.length > 0) {
+                reasons.push(`AgentLighthouse found ${changedFindings.length} new finding(s) at or above ${newChangedSeverity} severity on changed files.`);
+            }
+        }
+    }
+    if (options.failOnPrRegression) {
+        if (!result.prImpact) {
+            reasons.push("PR regression gate requested, but no changed-file information was supplied. Use --changed-files or --git-base/--git-head.");
+        }
+        else {
+            const changedHighRisk = result.prImpact.newFindingsOnChangedFiles.filter((finding) => severityRank(finding.severity) >= severityRank("high"));
+            if (result.deltas.scoreDelta < 0 || changedHighRisk.length > 0) {
+                reasons.push(`AgentLighthouse PR regression detected: score delta ${result.deltas.scoreDelta}, ${changedHighRisk.length} new high/critical finding(s) on changed files.`);
+            }
+        }
+    }
+    return { failed: reasons.length > 0, reasons };
+}
+function parseOptionalNumber(value, optionName) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Invalid ${optionName} value "${value}".`);
+    }
+    return parsed;
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,7 @@
+export interface InitCommandOptions {
+    dryRun?: boolean;
+    force?: boolean;
+    yes?: boolean;
+}
+export declare function runInitCommand(targetPath: string, options: InitCommandOptions): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAkDf"}

package/dist/commands/init.js

@@ -0,0 +1,56 @@
+import { access, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { generateStarterArtifacts } from "@agentlighthouse/core";
+import { resolveFromInvocationCwd } from "../pathing.js";
+export async function runInitCommand(targetPath, options) {
+    const rootPath = resolveFromInvocationCwd(targetPath);
+    const artifacts = await generateStarterArtifacts(rootPath);
+    const created = [];
+    const skipped = [];
+    const wouldCreate = [];
+    const overwritten = [];
+    for (const artifact of artifacts) {
+        const absolutePath = path.join(rootPath, artifact.path);
+        const exists = await fileExists(absolutePath);
+        if (options.dryRun) {
+            wouldCreate.push(`${artifact.path}${exists && options.force ? " (overwrite)" : exists ? " (skip existing)" : ""}`);
+            continue;
+        }
+        if (exists && !options.force) {
+            skipped.push(artifact.path);
+            continue;
+        }
+        await mkdir(path.dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, artifact.content, "utf8");
+        if (exists) {
+            overwritten.push(artifact.path);
+        }
+        else {
+            created.push(artifact.path);
+        }
+    }
+    if (options.dryRun) {
+        process.stdout.write(`AgentLighthouse init dry run for ${rootPath}\n${wouldCreate.map((file) => `- ${file}`).join("\n")}\n`);
+        return;
+    }
+    process.stdout.write(`AgentLighthouse init completed for ${rootPath}\n`);
+    if (created.length > 0) {
+        process.stdout.write(`Created:\n${created.map((file) => `- ${file}`).join("\n")}\n`);
+    }
+    if (overwritten.length > 0) {
+        process.stdout.write(`Overwritten:\n${overwritten.map((file) => `- ${file}`).join("\n")}\n`);
+    }
+    if (skipped.length > 0) {
+        process.stdout.write(`Skipped existing files:\n${skipped.map((file) => `- ${file}`).join("\n")}\n`);
+        process.stdout.write("Use --force to overwrite existing starter artifacts.\n");
+    }
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/scan.d.ts

@@ -0,0 +1,38 @@
+import type { ScanProfile, ScoreConfidenceLevel, Severity } from "@agentlighthouse/core";
+import type { CompareFormat } from "./compare.js";
+export type ScanFormat = "text" | "json" | "markdown" | "sarif" | "pr-summary";
+export interface ScanCommandOptions {
+    json?: boolean;
+    format?: ScanFormat;
+    profile?: ScanProfile;
+    probe?: string[];
+    runProbes?: boolean;
+    output?: string;
+    failUnder?: string;
+    failOnSeverity?: Severity;
+    minConfidence?: ScoreConfidenceLevel;
+    githubStepSummary?: boolean;
+    include?: string[];
+    exclude?: string[];
+    color?: boolean;
+    baseline?: string;
+    comparisonOutput?: string;
+    comparisonFormat?: CompareFormat;
+    changedFiles?: string;
+    gitBase?: string;
+    gitHead?: string;
+    failOnRegression?: boolean;
+    failOnScoreDrop?: string;
+    failOnCoverageDrop?: string;
+    failOnConfidenceDrop?: string;
+    failOnNewSeverity?: Severity;
+    failOnNewCritical?: boolean;
+    failOnNewHigh?: boolean;
+    failOnNewChangedSeverity?: Severity;
+    failOnNewChangedCritical?: boolean;
+    failOnNewChangedHigh?: boolean;
+    failOnPrRegression?: boolean;
+    reportDir?: string;
+}
+export declare function runScanCommand(targetPath: string, options: ScanCommandOptions): Promise<void>;
+//# sourceMappingURL=scan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/commands/scan.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzF,OAAO,KAAK,EAAyB,aAAa,EAAE,MAAM,cAAc,CAAC;AAQzE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAAC;AAE/E,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC1B,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,aAAa,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,QAAQ,CAAC;IAC7B,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wBAAwB,CAAC,EAAE,QAAQ,CAAC;IACpC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAwIf"}

package/dist/commands/scan.js

@@ -0,0 +1,250 @@
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { compareScanResults, confidenceRank, renderCliReport, renderGithubStepSummary, renderJsonReport, renderMarkdownReport, renderPrSummaryReport, renderSarifReport, scanProject, severityRank } from "@agentlighthouse/core";
+import { resolveFromInvocationCwd } from "../pathing.js";
+import { evaluateComparisonGates, readChangedFiles, readScanResultFile, renderComparisonResult } from "./compare.js";
+export async function runScanCommand(targetPath, options) {
+    const scanPath = resolveFromInvocationCwd(targetPath);
+    const format = options.json ? "json" : (options.format ?? "text");
+    if (!["text", "json", "markdown", "sarif", "pr-summary"].includes(format)) {
+        throw new Error(`Unsupported format "${format}". Use text, json, markdown, sarif, or pr-summary.`);
+    }
+    if (options.comparisonFormat &&
+        !["text", "json", "markdown", "pr-summary"].includes(options.comparisonFormat)) {
+        throw new Error(`Unsupported comparison-format "${options.comparisonFormat}". Use text, json, markdown, or pr-summary.`);
+    }
+    if (!options.baseline && hasComparisonOnlyOptions(options)) {
+        throw new Error("Comparison options require --baseline <file>. Example: agentlighthouse scan . --baseline agentlighthouse-baseline.json --comparison-output agentlighthouse-delta.md");
+    }
+    if (options.profile &&
+        !["default", "devtool", "api", "mcp", "docs", "library", "internal"].includes(options.profile)) {
+        throw new Error(`Unsupported profile "${options.profile}".`);
+    }
+    if (options.failOnSeverity &&
+        !["critical", "high", "medium", "low", "info"].includes(options.failOnSeverity)) {
+        throw new Error(`Unsupported fail-on-severity "${options.failOnSeverity}".`);
+    }
+    if (options.minConfidence && !["low", "medium", "high"].includes(options.minConfidence)) {
+        throw new Error(`Unsupported min-confidence "${options.minConfidence}".`);
+    }
+    const probes = new Set(options.probe ?? []);
+    if ([...probes].some((probe) => probe !== "commands")) {
+        throw new Error(`Unsupported probe. Use --probe commands.`);
+    }
+    const result = await scanProject(scanPath, {
+        include: options.include ?? [],
+        exclude: options.exclude ?? [],
+        profile: options.profile,
+        probes: {
+            commands: options.runProbes === true || probes.has("commands")
+        }
+    });
+    const failUnder = options.failUnder ? Number.parseInt(options.failUnder, 10) : undefined;
+    if (options.failUnder && Number.isNaN(failUnder)) {
+        throw new Error(`Invalid fail-under score "${options.failUnder}".`);
+    }
+    const gateResult = evaluateGates(result, {
+        failUnder,
+        failOnSeverity: options.failOnSeverity,
+        minConfidence: options.minConfidence
+    });
+    const outputOption = options.output;
+    const outputPath = outputOption ? resolveFromInvocationCwd(outputOption) : undefined;
+    const reportPaths = outputOption ? [outputOption] : [];
+    const bundlePaths = [];
+    if (options.reportDir) {
+        bundlePaths.push(...(await writeReportBundle(options.reportDir, result)));
+    }
+    const comparison = options.baseline
+        ? compareScanResults(await readScanResultFile(options.baseline), result, {
+            changedFiles: await readChangedFiles(options)
+        })
+        : undefined;
+    const comparisonGateResult = comparison
+        ? evaluateComparisonGates(comparison, comparisonOptions(options))
+        : { failed: false, reasons: [] };
+    const allReasons = [...gateResult.reasons, ...comparisonGateResult.reasons];
+    const failed = gateResult.failed || comparisonGateResult.failed;
+    const comparisonOutputOption = options.comparisonOutput;
+    const comparisonOutputPath = comparisonOutputOption
+        ? resolveFromInvocationCwd(comparisonOutputOption)
+        : undefined;
+    const comparisonFormat = options.comparisonFormat ?? "pr-summary";
+    const rendered = renderResult(result, format, options.color ?? true, {
+        status: failed ? "failed" : "passed",
+        reasons: allReasons,
+        reportPaths: [...reportPaths, ...bundlePaths]
+    });
+    if (outputPath) {
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, rendered, "utf8");
+    }
+    if (comparison && options.reportDir) {
+        bundlePaths.push(...(await writeComparisonBundle(options.reportDir, comparison, {
+            status: failed ? "failed" : "passed",
+            reasons: comparisonGateResult.reasons
+        })));
+    }
+    if (comparison && comparisonOutputPath) {
+        const comparisonRendered = renderComparisonResult(comparison, comparisonFormat, {
+            status: failed ? "failed" : "passed",
+            reasons: comparisonGateResult.reasons,
+            reportPaths: comparisonOutputOption ? [comparisonOutputOption] : []
+        });
+        await mkdir(path.dirname(comparisonOutputPath), { recursive: true });
+        await writeFile(comparisonOutputPath, comparisonRendered, "utf8");
+    }
+    process.stdout.write(`${rendered}\n`);
+    if (comparison) {
+        const comparisonRendered = renderComparisonResult(comparison, comparisonFormat, {
+            status: failed ? "failed" : "passed",
+            reasons: comparisonGateResult.reasons,
+            reportPaths: [
+                ...(comparisonOutputOption ? [comparisonOutputOption] : []),
+                ...bundlePaths.filter((file) => file.includes("comparison"))
+            ]
+        });
+        process.stdout.write(`${comparisonRendered}\n`);
+    }
+    if (options.reportDir) {
+        process.stdout.write(`AgentLighthouse report bundle written to ${options.reportDir}\n`);
+    }
+    if (options.githubStepSummary) {
+        await writeGithubStepSummary(result, {
+            status: failed ? "failed" : "passed",
+            reasons: allReasons,
+            reportPaths: [...reportPaths, ...bundlePaths]
+        });
+    }
+    if (failed) {
+        for (const reason of allReasons) {
+            process.stderr.write(`${reason}\n`);
+        }
+        process.exitCode = 1;
+    }
+}
+function hasComparisonOnlyOptions(options) {
+    return Boolean(options.comparisonOutput ||
+        options.changedFiles ||
+        options.gitBase ||
+        options.gitHead ||
+        options.failOnRegression ||
+        options.failOnScoreDrop ||
+        options.failOnCoverageDrop ||
+        options.failOnConfidenceDrop ||
+        options.failOnNewSeverity ||
+        options.failOnNewCritical ||
+        options.failOnNewHigh ||
+        options.failOnNewChangedSeverity ||
+        options.failOnNewChangedCritical ||
+        options.failOnNewChangedHigh ||
+        options.failOnPrRegression);
+}
+function comparisonOptions(options) {
+    return {
+        failOnRegression: options.failOnRegression,
+        failOnScoreDrop: options.failOnScoreDrop,
+        failOnCoverageDrop: options.failOnCoverageDrop,
+        failOnConfidenceDrop: options.failOnConfidenceDrop,
+        failOnNewSeverity: options.failOnNewSeverity,
+        failOnNewCritical: options.failOnNewCritical,
+        failOnNewHigh: options.failOnNewHigh,
+        failOnNewChangedSeverity: options.failOnNewChangedSeverity,
+        failOnNewChangedCritical: options.failOnNewChangedCritical,
+        failOnNewChangedHigh: options.failOnNewChangedHigh,
+        failOnPrRegression: options.failOnPrRegression
+    };
+}
+async function writeReportBundle(reportDir, result) {
+    const resolved = resolveFromInvocationCwd(reportDir);
+    await mkdir(resolved, { recursive: true });
+    const files = [
+        ["scan.json", renderJsonReport(result)],
+        ["scan.md", renderMarkdownReport(result)],
+        ["scan.sarif", renderSarifReport(result)],
+        [
+            "pr-summary.md",
+            renderPrSummaryReport(result, {
+                reportPaths: [
+                    path.posix.join(reportDir, "scan.json"),
+                    path.posix.join(reportDir, "scan.md"),
+                    path.posix.join(reportDir, "scan.sarif")
+                ]
+            })
+        ]
+    ];
+    for (const [fileName, contents] of files) {
+        await writeFile(path.join(resolved, fileName), contents, "utf8");
+    }
+    return files.map(([fileName]) => path.posix.join(reportDir, fileName));
+}
+async function writeComparisonBundle(reportDir, comparison, options) {
+    const resolved = resolveFromInvocationCwd(reportDir);
+    await mkdir(resolved, { recursive: true });
+    const files = [
+        [
+            "comparison.json",
+            renderComparisonResult(comparison, "json", bundleComparisonOptions(options))
+        ],
+        [
+            "comparison.md",
+            renderComparisonResult(comparison, "markdown", bundleComparisonOptions(options))
+        ],
+        [
+            "comparison-pr-summary.md",
+            renderComparisonResult(comparison, "pr-summary", bundleComparisonOptions(options))
+        ]
+    ];
+    for (const [fileName, contents] of files) {
+        await writeFile(path.join(resolved, fileName), contents, "utf8");
+    }
+    return files.map(([fileName]) => path.posix.join(reportDir, fileName));
+}
+function bundleComparisonOptions(options) {
+    return {
+        status: options.status,
+        reasons: options.reasons,
+        reportPaths: []
+    };
+}
+function renderResult(result, format, color, options) {
+    if (format === "json") {
+        return renderJsonReport(result);
+    }
+    if (format === "markdown") {
+        return renderMarkdownReport(result);
+    }
+    if (format === "sarif") {
+        return renderSarifReport(result);
+    }
+    if (format === "pr-summary") {
+        return renderPrSummaryReport(result, options);
+    }
+    return renderCliReport(result, color);
+}
+function evaluateGates(result, options) {
+    const reasons = [];
+    if (options.failUnder !== undefined && result.score < options.failUnder) {
+        reasons.push(`AgentLighthouse score ${result.score} is below fail-under threshold ${options.failUnder}.`);
+    }
+    if (options.failOnSeverity) {
+        const threshold = severityRank(options.failOnSeverity);
+        const blocking = result.findings.filter((finding) => severityRank(finding.severity) >= threshold);
+        if (blocking.length > 0) {
+            reasons.push(`AgentLighthouse found ${blocking.length} finding(s) at or above ${options.failOnSeverity} severity.`);
+        }
+    }
+    if (options.minConfidence &&
+        confidenceRank(result.scoreConfidence) < confidenceRank(options.minConfidence)) {
+        reasons.push(`AgentLighthouse confidence ${result.scoreConfidence} is below minimum ${options.minConfidence}.`);
+    }
+    return { failed: reasons.length > 0, reasons };
+}
+async function writeGithubStepSummary(result, options) {
+    const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+    if (!summaryPath) {
+        process.stderr.write("GITHUB_STEP_SUMMARY is not set; skipping GitHub step summary output.\n");
+        return;
+    }
+    await appendFile(summaryPath, `${renderGithubStepSummary(result, options)}\n`, "utf8");
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runBaselineCreateCommand, runBaselineSummaryCommand, runBaselineValidateCommand } from "./commands/baseline.js";
+import { runCompareCommand } from "./commands/compare.js";
+import { runInitCommand } from "./commands/init.js";
+import { runScanCommand } from "./commands/scan.js";
+const program = new Command();
+program
+    .name("agentlighthouse")
+    .description("Lighthouse for AI agents: scan projects for agent-readiness.")
+    .version("0.1.0-alpha.0");
+program
+    .command("scan")
+    .argument("[path]", "Project path to scan", ".")
+    .option("--json", "Print JSON output")
+    .option("--format <format>", "Output format: text, json, markdown, sarif, or pr-summary", "text")
+    .option("--profile <profile>", "Scan profile: default, devtool, api, mcp, docs, library, or internal")
+    .option("--probe <probe...>", "Opt-in probes to run, currently: commands")
+    .option("--run-probes", "Run all safe opt-in probes")
+    .option("--output <file>", "Write report output to a file")
+    .option("--report-dir <dir>", "Write scan and comparison report bundle files to a directory")
+    .option("--baseline <file>", "Compare this scan against a baseline scan-result JSON")
+    .option("--comparison-format <format>", "Comparison output format when --baseline is used: text, json, markdown, or pr-summary", "pr-summary")
+    .option("--comparison-output <file>", "Write comparison output when --baseline is used")
+    .option("--changed-files <file>", "Classify baseline comparison using a changed-files list")
+    .option("--git-base <ref>", "Read changed files from git diff using this base ref")
+    .option("--git-head <ref>", "Read changed files from git diff using this head ref")
+    .option("--fail-under <score>", "Exit with code 1 when score is below the threshold")
+    .option("--fail-on-severity <severity>", "Exit with code 1 when any finding is at or above severity: critical, high, medium, low, or info")
+    .option("--min-confidence <confidence>", "Exit with code 1 when score confidence is below: low, medium, or high")
+    .option("--github-step-summary", "Append a concise Markdown summary to GITHUB_STEP_SUMMARY")
+    .option("--fail-on-regression", "With --baseline, exit when comparison regresses")
+    .option("--fail-on-score-drop <points>", "With --baseline, exit when score drops by points")
+    .option("--fail-on-coverage-drop <points>", "With --baseline, exit when coverage drops by points")
+    .option("--fail-on-confidence-drop <points>", "With --baseline, exit when confidence score drops by points")
+    .option("--fail-on-new-severity <severity>", "With --baseline, exit when any new finding is at or above severity")
+    .option("--fail-on-new-critical", "With --baseline, exit when a new critical finding appears")
+    .option("--fail-on-new-high", "With --baseline, exit when a new high/critical finding appears")
+    .option("--fail-on-new-changed-severity <severity>", "With --baseline and changed files, exit when new changed-file findings meet severity")
+    .option("--fail-on-new-changed-critical", "With --baseline and changed files, exit when a new critical changed-file finding appears")
+    .option("--fail-on-new-changed-high", "With --baseline and changed files, exit when a new high/critical changed-file finding appears")
+    .option("--fail-on-pr-regression", "With --baseline and changed files, exit on score drop or new high/critical changed-file findings")
+    .option("--include <glob...>", "Only include paths containing these patterns")
+    .option("--exclude <glob...>", "Exclude paths matching these patterns")
+    .option("--no-color", "Disable terminal color")
+    .description("Scan a local project directory.")
+    .addHelpText("after", `
+
+Examples:
+  agentlighthouse scan .
+  agentlighthouse scan . --format markdown --output agentlighthouse-report.md
+  agentlighthouse scan . --report-dir agentlighthouse-reports
+  agentlighthouse scan . --baseline agentlighthouse-baseline.json --comparison-output agentlighthouse-delta.md
+  agentlighthouse scan . --baseline agentlighthouse-baseline.json --git-base origin/main --git-head HEAD --fail-on-pr-regression
+`)
+    .action((targetPath, options) => {
+    runScanCommand(targetPath, options).catch(handleError);
+});
+program
+    .command("compare")
+    .requiredOption("--baseline <file>", "Baseline scan result JSON")
+    .requiredOption("--current <file>", "Current scan result JSON")
+    .option("--format <format>", "Output format: text, json, markdown, or pr-summary", "text")
+    .option("--output <file>", "Write comparison report output to a file")
+    .option("--fail-on-regression", "Exit with code 1 when any regression is detected")
+    .option("--fail-on-score-drop <points>", "Exit with code 1 when score drops by at least points")
+    .option("--fail-on-coverage-drop <points>", "Exit with code 1 when coverage drops by at least points")
+    .option("--fail-on-confidence-drop <points>", "Exit with code 1 when confidence score drops by at least points")
+    .option("--fail-on-new-severity <severity>", "Exit with code 1 when any new finding is at or above severity")
+    .option("--fail-on-new-critical", "Exit with code 1 when a new critical finding appears")
+    .option("--fail-on-new-high", "Exit with code 1 when a new high or critical finding appears")
+    .option("--changed-files <file>", "Classify comparison findings using an explicit changed-files list")
+    .option("--git-base <ref>", "Read changed files from git diff using this base ref")
+    .option("--git-head <ref>", "Read changed files from git diff using this head ref")
+    .option("--fail-on-new-changed-severity <severity>", "Exit with code 1 when a new finding at or above severity appears on changed files")
+    .option("--fail-on-new-changed-critical", "Exit with code 1 when a new critical finding appears on changed files")
+    .option("--fail-on-new-changed-high", "Exit with code 1 when a new high or critical finding appears on changed files")
+    .option("--fail-on-pr-regression", "Exit with code 1 when score drops or new high/critical findings appear on changed files")
+    .description("Compare two saved AgentLighthouse JSON scan reports.")
+    .addHelpText("after", `
+
+Examples:
+  agentlighthouse compare --baseline baseline.json --current current.json
+  agentlighthouse compare --baseline baseline.json --current current.json --format markdown --output delta.md
+  agentlighthouse compare --baseline baseline.json --current current.json --changed-files changed-files.txt --fail-on-new-changed-high
+`)
+    .action((options) => {
+    runCompareCommand(options).catch(handleError);
+});
+program
+    .command("init")
+    .argument("[path]", "Project path where starter artifacts should be created", ".")
+    .option("--dry-run", "Show what would be generated without writing files")
+    .option("--force", "Overwrite existing starter artifacts")
+    .option("--yes", "Assume yes for non-destructive generation")
+    .description("Generate safe starter agent-readiness artifacts without overwriting by default.")
+    .addHelpText("after", `
+
+Examples:
+  agentlighthouse init .
+  agentlighthouse init . --dry-run
+`)
+    .action((targetPath, options) => {
+    runInitCommand(targetPath, options).catch(handleError);
+});
+const baseline = program
+    .command("baseline")
+    .description("Create, validate, and summarize baselines.");
+baseline
+    .command("create")
+    .argument("[path]", "Project path to scan for the baseline", ".")
+    .option("--output <file>", "Baseline output path", "agentlighthouse-baseline.json")
+    .option("--profile <profile>", "Scan profile: default, devtool, api, mcp, docs, library, or internal")
+    .description("Create a baseline scan-result JSON file.")
+    .addHelpText("after", `
+
+Examples:
+  agentlighthouse baseline create .
+  agentlighthouse baseline create . --output agentlighthouse-baseline.json
+`)
+    .action((targetPath, options) => {
+    runBaselineCreateCommand(targetPath, options).catch(handleError);
+});
+baseline
+    .command("validate")
+    .argument("<file>", "Baseline scan-result JSON file")
+    .description("Validate that a baseline file is an AgentLighthouse scan-result JSON.")
+    .addHelpText("after", `
+
+Examples:
+  agentlighthouse baseline validate agentlighthouse-baseline.json
+`)
+    .action((baselinePath, options) => {
+    runBaselineValidateCommand(baselinePath, options).catch(handleError);
+});
+baseline
+    .command("summary")
+    .argument("<file>", "Baseline scan-result JSON file")
+    .description("Print score, confidence, coverage, profile, and finding counts for a baseline.")
+    .addHelpText("after", `
+
+Examples:
+  agentlighthouse baseline summary agentlighthouse-baseline.json
+`)
+    .action((baselinePath) => {
+    runBaselineSummaryCommand(baselinePath).catch(handleError);
+});
+program
+    .command("version")
+    .description("Print the AgentLighthouse CLI version.")
+    .action(() => {
+    process.stdout.write(`${program.version()}\n`);
+});
+program.parse();
+function handleError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`AgentLighthouse error: ${message}\n`);
+    process.exitCode = 1;
+}

package/dist/pathing.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveFromInvocationCwd(targetPath: string): string;
+//# sourceMappingURL=pathing.d.ts.map

package/dist/pathing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathing.d.ts","sourceRoot":"","sources":["../src/pathing.ts"],"names":[],"mappings":"AAEA,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAKnE"}

package/dist/pathing.js

@@ -0,0 +1,7 @@
+import path from "node:path";
+export function resolveFromInvocationCwd(targetPath) {
+    if (path.isAbsolute(targetPath)) {
+        return targetPath;
+    }
+    return path.resolve(process.env.INIT_CWD ?? process.cwd(), targetPath);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@agentlighthouse/cli",
+  "version": "0.1.0-alpha.0",
+  "description": "AgentLighthouse command-line interface.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PainDeMie64/agentlighthouse.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/PainDeMie64/agentlighthouse#readme",
+  "bugs": {
+    "url": "https://github.com/PainDeMie64/agentlighthouse/issues"
+  },
+  "keywords": [
+    "agent-readiness",
+    "cli",
+    "ci",
+    "sarif",
+    "github-actions",
+    "openapi",
+    "mcp"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "!dist/.tsbuildinfo",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "agentlighthouse": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@agentlighthouse/core": "workspace:^",
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}