@praneeth_54/agentdoctor 1.1.1 → 2.0.1

package/dist/plugins/runtime.d.ts

@@ -0,0 +1,36 @@
+export interface PluginAnalyzerNote {
+    pluginId: string;
+    severity: "info" | "warning";
+    message: string;
+}
+export interface PluginAnalyzerResult {
+    pluginId: string;
+    ok: boolean;
+    notes: PluginAnalyzerNote[];
+    error?: string;
+}
+export interface PluginAnalyzerContext {
+    repoRoot: string;
+    /** Relative paths the host already knows about — plugins must not scan arbitrary FS */
+    knownRelativePaths: readonly string[];
+}
+export type PluginAnalyzeFn = (ctx: PluginAnalyzerContext) => Promise<{
+    notes?: Array<{
+        severity?: string;
+        message: string;
+    }>;
+}> | {
+    notes?: Array<{
+        severity?: string;
+        message: string;
+    }>;
+};
+/**
+ * Run analyzer-capability plugins with per-plugin error isolation and timeouts.
+ * Declarative JSON entry (`hooks.json`) or JS/MJS `analyze` export.
+ * No network APIs are provided; crashes do not abort other plugins.
+ */
+export declare function runPluginAnalyzers(rootInput: string, options?: {
+    knownRelativePaths?: string[];
+    timeoutMs?: number;
+}): Promise<PluginAnalyzerResult[]>;

package/dist/plugins/runtime.js

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { discoverPlugins } from "./sdk.js";
+import { isPathInsideRoot, resolveRepoRoot } from "../utils/path.js";
+/**
+ * Run analyzer-capability plugins with per-plugin error isolation and timeouts.
+ * Declarative JSON entry (`hooks.json`) or JS/MJS `analyze` export.
+ * No network APIs are provided; crashes do not abort other plugins.
+ */
+export async function runPluginAnalyzers(rootInput, options) {
+    const repoRoot = resolveRepoRoot(rootInput);
+    const plugins = await discoverPlugins(repoRoot);
+    const known = options?.knownRelativePaths ?? [];
+    const timeoutMs = options?.timeoutMs ?? 3_000;
+    const results = [];
+    for (const plugin of plugins) {
+        if (!plugin.ok) {
+            results.push({
+                pluginId: plugin.manifest.id,
+                ok: false,
+                notes: [],
+                error: plugin.errors.join("; ") || "invalid plugin",
+            });
+            continue;
+        }
+        if (!plugin.manifest.capabilities.includes("analyzer")) {
+            continue;
+        }
+        try {
+            results.push(await runOneAnalyzer(repoRoot, plugin.manifest, plugin.root, known, timeoutMs));
+        }
+        catch (error) {
+            results.push({
+                pluginId: plugin.manifest.id,
+                ok: false,
+                notes: [],
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return results.sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+}
+async function runOneAnalyzer(repoRoot, manifest, pluginRoot, knownRelativePaths, timeoutMs) {
+    const entry = manifest.entry ?? "hooks.json";
+    const entryPath = path.resolve(pluginRoot, entry);
+    if (!isPathInsideRoot(pluginRoot, entryPath)) {
+        return {
+            pluginId: manifest.id,
+            ok: false,
+            notes: [],
+            error: "plugin entry escapes plugin root",
+        };
+    }
+    const ctx = {
+        repoRoot,
+        knownRelativePaths,
+    };
+    if (entry.endsWith(".json")) {
+        const raw = JSON.parse(await fs.readFile(entryPath, "utf8"));
+        return normalizeNotes(manifest, raw.notes ?? []);
+    }
+    const mod = await withTimeout(import(pathToFileURL(entryPath).href), timeoutMs);
+    const analyze = mod.analyze ??
+        mod.default;
+    if (typeof analyze !== "function") {
+        return {
+            pluginId: manifest.id,
+            ok: false,
+            notes: [],
+            error: "plugin entry missing analyze() export",
+        };
+    }
+    const out = await withTimeout(Promise.resolve(analyze(ctx)), timeoutMs);
+    return normalizeNotes(manifest, out?.notes ?? []);
+}
+function normalizeNotes(manifest, notes) {
+    return {
+        pluginId: manifest.id,
+        ok: true,
+        notes: notes
+            .filter((n) => typeof n.message === "string" && n.message.trim().length > 0)
+            .map((n) => ({
+            pluginId: manifest.id,
+            severity: n.severity === "warning" ? "warning" : "info",
+            message: n.message.slice(0, 500),
+        })),
+    };
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`plugin timed out after ${ms}ms`)), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}

package/dist/plugins/sdk.d.ts

@@ -0,0 +1,29 @@
+export type PluginCapability = "rule" | "reporter" | "analyzer";
+export interface AgentDoctorPluginManifest {
+    id: string;
+    name: string;
+    version: string;
+    apiVersion: "2.0";
+    capabilities: PluginCapability[];
+    /** Declared only — runtime does not grant network/fs beyond the sandbox root. */
+    requestedPermissions?: Array<"read-repo" | "none">;
+    entry?: string;
+}
+export interface PluginLoadResult {
+    manifest: AgentDoctorPluginManifest;
+    root: string;
+    ok: boolean;
+    errors: string[];
+}
+export interface PluginSandbox {
+    repoRoot: string;
+    pluginRoot: string;
+}
+export declare function validatePluginManifest(raw: unknown): {
+    ok: boolean;
+    manifest?: AgentDoctorPluginManifest;
+    errors: string[];
+};
+/** Discover plugins under .agentdoctor/plugins/<id>/plugin.json (validated, no network). */
+export declare function discoverPlugins(rootInput: string): Promise<PluginLoadResult[]>;
+export declare function createPluginSandbox(repoRoot: string, pluginRoot: string): PluginSandbox;

package/dist/plugins/sdk.js

@@ -0,0 +1,114 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveRepoRoot, isPathInsideRoot } from "../utils/path.js";
+const ALLOWED_CAPABILITIES = new Set(["rule", "reporter", "analyzer"]);
+export function validatePluginManifest(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== "object") {
+        return { ok: false, errors: ["manifest must be an object"] };
+    }
+    const m = raw;
+    if (typeof m.id !== "string" || !m.id.trim())
+        errors.push("id required");
+    if (typeof m.name !== "string" || !m.name.trim())
+        errors.push("name required");
+    if (typeof m.version !== "string" || !m.version.trim())
+        errors.push("version required");
+    if (m.apiVersion !== "2.0")
+        errors.push('apiVersion must be "2.0"');
+    if (!Array.isArray(m.capabilities) || m.capabilities.length === 0) {
+        errors.push("capabilities required");
+    }
+    else {
+        for (const c of m.capabilities) {
+            if (!ALLOWED_CAPABILITIES.has(c)) {
+                errors.push(`unsupported capability: ${String(c)}`);
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const manifest = {
+        id: String(m.id),
+        name: String(m.name),
+        version: String(m.version),
+        apiVersion: "2.0",
+        capabilities: m.capabilities,
+    };
+    if (Array.isArray(m.requestedPermissions)) {
+        manifest.requestedPermissions = m.requestedPermissions;
+    }
+    if (typeof m.entry === "string") {
+        manifest.entry = m.entry;
+    }
+    return {
+        ok: true,
+        errors: [],
+        manifest,
+    };
+}
+/** Discover plugins under .agentdoctor/plugins/<id>/plugin.json (validated, no network). */
+export async function discoverPlugins(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const pluginsRoot = path.join(root, ".agentdoctor", "plugins");
+    let dirs = [];
+    try {
+        const entries = await fs.readdir(pluginsRoot, { withFileTypes: true });
+        dirs = entries.filter((e) => e.isDirectory()).map((e) => path.join(pluginsRoot, e.name));
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const dir of dirs) {
+        if (!isPathInsideRoot(pluginsRoot, dir))
+            continue;
+        const manifestPath = path.join(dir, "plugin.json");
+        try {
+            const raw = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+            const validated = validatePluginManifest(raw);
+            if (!validated.ok || !validated.manifest) {
+                results.push({
+                    manifest: {
+                        id: path.basename(dir),
+                        name: path.basename(dir),
+                        version: "0.0.0",
+                        apiVersion: "2.0",
+                        capabilities: ["analyzer"],
+                    },
+                    root: dir,
+                    ok: false,
+                    errors: validated.errors,
+                });
+                continue;
+            }
+            results.push({
+                manifest: validated.manifest,
+                root: dir,
+                ok: true,
+                errors: [],
+            });
+        }
+        catch (error) {
+            results.push({
+                manifest: {
+                    id: path.basename(dir),
+                    name: path.basename(dir),
+                    version: "0.0.0",
+                    apiVersion: "2.0",
+                    capabilities: ["analyzer"],
+                },
+                root: dir,
+                ok: false,
+                errors: [error instanceof Error ? error.message : String(error)],
+            });
+        }
+    }
+    return results.sort((a, b) => a.manifest.id.localeCompare(b.manifest.id));
+}
+export function createPluginSandbox(repoRoot, pluginRoot) {
+    return {
+        repoRoot: resolveRepoRoot(repoRoot),
+        pluginRoot: path.resolve(pluginRoot),
+    };
+}

package/dist/policy/compose.d.ts

@@ -0,0 +1,34 @@
+import type { FirewallPolicyDocument } from "../platform/firewall/evaluate.js";
+export interface ComposedPolicyResult {
+    policy: FirewallPolicyDocument;
+    sources: Array<"builtin" | "repo">;
+    packName: string | null;
+    validationError?: string;
+    failClosed: boolean;
+}
+/**
+ * Merge builtin (global pack) + repo `.agentdoctor/policy.json`.
+ * Precedence: repo rules are prepended (evaluated first); repo defaultDecision /
+ * failClosed / shellAllowlist override builtin when present.
+ * Malformed repo policy → fail-closed deny-all (never silently ignore).
+ */
+export declare function composePolicy(options: {
+    root: string;
+    packName?: string;
+}): Promise<ComposedPolicyResult>;
+export declare function explainComposedDecision(options: {
+    command: string;
+    decision: string;
+    reason: string;
+    policyId?: string | null;
+    sources: Array<"builtin" | "repo">;
+    failClosed: boolean;
+}): {
+    command: string;
+    decision: string;
+    reason: string;
+    policyId: string | null;
+    sources: Array<"builtin" | "repo">;
+    failClosed: boolean;
+    meaning: string;
+};

package/dist/policy/compose.js

@@ -0,0 +1,118 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getPolicyPack, POLICY_PACKS } from "./packs.js";
+import { resolveRepoRoot } from "../utils/path.js";
+const REPO_POLICY_PATH = ".agentdoctor/policy.json";
+function denyAll(reason) {
+    return {
+        version: "2.0",
+        defaultDecision: "block",
+        failClosed: true,
+        rules: [
+            {
+                id: "compose-fail-closed",
+                decision: "block",
+                reason,
+                riskLevel: "critical",
+            },
+        ],
+    };
+}
+function isFirewallPolicyDocument(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const doc = value;
+    if (doc.version !== "2.0")
+        return false;
+    if (typeof doc.defaultDecision !== "string")
+        return false;
+    if (!Array.isArray(doc.rules))
+        return false;
+    return true;
+}
+/**
+ * Merge builtin (global pack) + repo `.agentdoctor/policy.json`.
+ * Precedence: repo rules are prepended (evaluated first); repo defaultDecision /
+ * failClosed / shellAllowlist override builtin when present.
+ * Malformed repo policy → fail-closed deny-all (never silently ignore).
+ */
+export async function composePolicy(options) {
+    const root = resolveRepoRoot(options.root);
+    const packName = options.packName ?? "baseline-safe";
+    const builtin = getPolicyPack(packName) ?? POLICY_PACKS["baseline-safe"];
+    const sources = ["builtin"];
+    const repoPath = path.join(root, REPO_POLICY_PATH);
+    let raw = null;
+    try {
+        raw = await fs.readFile(repoPath, "utf8");
+    }
+    catch {
+        raw = null;
+    }
+    if (raw === null) {
+        return {
+            policy: structuredClone(builtin),
+            sources,
+            packName,
+            failClosed: Boolean(builtin.failClosed),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            policy: denyAll("Malformed repo .agentdoctor/policy.json; fail-closed"),
+            sources: ["builtin", "repo"],
+            packName,
+            validationError: "Malformed JSON",
+            failClosed: true,
+        };
+    }
+    if (!isFirewallPolicyDocument(parsed)) {
+        return {
+            policy: denyAll("Invalid repo .agentdoctor/policy.json shape; fail-closed"),
+            sources: ["builtin", "repo"],
+            packName,
+            validationError: "Invalid policy document",
+            failClosed: true,
+        };
+    }
+    sources.push("repo");
+    const repoRules = Array.isArray(parsed.rules) ? parsed.rules : [];
+    const merged = {
+        version: "2.0",
+        defaultDecision: parsed.defaultDecision ?? builtin.defaultDecision,
+        failClosed: parsed.failClosed === true || builtin.failClosed === true,
+        ...(parsed.shellAllowlist
+            ? { shellAllowlist: parsed.shellAllowlist }
+            : builtin.shellAllowlist
+                ? { shellAllowlist: builtin.shellAllowlist }
+                : {}),
+        // Repo rules first (higher precedence), then builtin.
+        rules: [...repoRules, ...builtin.rules],
+    };
+    return {
+        policy: merged,
+        sources,
+        packName,
+        failClosed: Boolean(merged.failClosed),
+    };
+}
+export function explainComposedDecision(options) {
+    const meaning = options.decision === "allow"
+        ? "Allowlisted or matched an allow rule — still evaluate-only unless agentdoctor run executes it."
+        : options.decision === "block" || options.decision === "deny-network"
+            ? "Would be blocked by the AgentDoctor-controlled runner if executed through it."
+            : "Requires human approval or further policy before controlled execution.";
+    return {
+        command: options.command,
+        decision: options.decision,
+        reason: options.reason,
+        policyId: options.policyId ?? null,
+        sources: options.sources,
+        failClosed: options.failClosed,
+        meaning,
+    };
+}

package/dist/policy/packs.d.ts

@@ -0,0 +1,9 @@
+import type { FirewallPolicyDocument } from "../platform/firewall/evaluate.js";
+/**
+ * Named policy packs for local evaluation. Packs are declarative documents —
+ * loading a pack does not enable runtime interception unless an AgentDoctor
+ * enforcement boundary (controlled runner / CI wrapper) is used.
+ */
+export declare const POLICY_PACKS: Record<string, FirewallPolicyDocument>;
+export declare function listPolicyPacks(): string[];
+export declare function getPolicyPack(name: string): FirewallPolicyDocument | null;

package/dist/policy/packs.js

@@ -0,0 +1,91 @@
+/**
+ * Named policy packs for local evaluation. Packs are declarative documents —
+ * loading a pack does not enable runtime interception unless an AgentDoctor
+ * enforcement boundary (controlled runner / CI wrapper) is used.
+ */
+export const POLICY_PACKS = {
+    "baseline-safe": {
+        version: "2.0",
+        defaultDecision: "require-approval",
+        failClosed: false,
+        shellAllowlist: ["npm test", "npm run test", "vitest", "eslint", "tsc", "prettier"],
+        rules: [
+            {
+                id: "pack-block-secrets",
+                actionTypes: ["file-modify", "file-delete", "secret-access"],
+                match: { pathContains: [".env", "id_rsa", "credentials", ".pem"] },
+                decision: "block",
+                reason: "baseline-safe: secret-sensitive path",
+                riskLevel: "critical",
+            },
+            {
+                id: "pack-block-destructive",
+                actionTypes: ["shell"],
+                // Force-push is gated as require-approval (human gate), not a hard block —
+                // builtin shell blocks already cover rm -rf; keep drop table here.
+                match: { commandContains: ["rm -rf", "drop table"] },
+                decision: "block",
+                reason: "baseline-safe: destructive operation",
+                riskLevel: "critical",
+            },
+            {
+                id: "pack-force-push-approval",
+                actionTypes: ["shell"],
+                match: { commandContains: ["git push --force", "git push -f"] },
+                decision: "require-approval",
+                reason: "baseline-safe: force-push requires approval",
+                riskLevel: "high",
+            },
+            {
+                id: "pack-allow-safe-dev-paths",
+                actionTypes: ["file-modify", "file-create"],
+                match: { pathPrefix: ["src/", "tests/", "docs/"] },
+                decision: "allow",
+                reason: "baseline-safe: allowlisted development paths",
+                riskLevel: "low",
+            },
+            {
+                id: "pack-deny-prod-deploy",
+                actionTypes: ["deploy", "infra"],
+                decision: "block",
+                reason: "baseline-safe: production/infra changes require out-of-band process",
+                riskLevel: "critical",
+            },
+            {
+                id: "pack-network-default-deny",
+                actionTypes: ["network"],
+                decision: "deny-network",
+                reason: "baseline-safe: network access denied by default",
+                riskLevel: "high",
+            },
+        ],
+    },
+    "fail-closed-ci": {
+        version: "2.0",
+        defaultDecision: "block",
+        failClosed: true,
+        shellAllowlist: ["npm test", "npm run verify", "vitest"],
+        rules: [
+            {
+                id: "ci-deny-network",
+                actionTypes: ["network"],
+                decision: "block",
+                reason: "fail-closed-ci: network blocked",
+                riskLevel: "high",
+            },
+            {
+                id: "ci-deny-deploy",
+                actionTypes: ["deploy", "infra"],
+                decision: "block",
+                reason: "fail-closed-ci: deploy blocked",
+                riskLevel: "critical",
+            },
+        ],
+    },
+};
+export function listPolicyPacks() {
+    return Object.keys(POLICY_PACKS);
+}
+export function getPolicyPack(name) {
+    return POLICY_PACKS[name] ?? null;
+}

package/dist/reporters/terminal/report.js

@@ -7,7 +7,39 @@ import { formatPackageManager, formatPackageManagers } from "../../detectors/pac
 import { colors, symbolFail, symbolInfo, symbolOk, symbolWarn } from "../../utils/colors.js";
 import { sanitizeTerminalText } from "../../security/redaction.js";
 const DEFAULT_FINDING_LIMIT = 12;
-const LIMITED_ANALYSIS_NOTE = "No supported coding-agent configuration detected; agent-specific security exposure checks are limited.";
+const LIMITED_ANALYSIS_NOTE = "Agent-specific exposure checks are limited (no supported agent config); repository hygiene still applied.";
+/** Agents with an implemented Safe Fix writer (detect-only agents are excluded). */
+const SAFE_FIX_AGENT_IDS = new Set([
+    "cursor",
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "aider",
+]);
+function renderAgentCoverageSummary(result) {
+    const configured = result.agents.filter((a) => a.configured);
+    const detectedOnly = result.agents.filter((a) => a.detected && !a.configured);
+    const withFix = configured.filter((a) => SAFE_FIX_AGENT_IDS.has(a.id));
+    const detectOnlyConfigured = configured.filter((a) => !SAFE_FIX_AGENT_IDS.has(a.id));
+    const lines = [];
+    lines.push("");
+    if (result.agentSecurityAnalysis === "limited") {
+        lines.push(colors.dim("  Coverage: 0 configured · universal hygiene still runs (limited agent analysis)"));
+        return lines;
+    }
+    const parts = [`${configured.length} configured`];
+    if (detectedOnly.length > 0) {
+        parts.push(`${detectedOnly.length} detected-only`);
+    }
+    if (withFix.length > 0) {
+        parts.push(`Safe Fix: ${withFix.map((a) => a.displayName).join(", ")}`);
+    }
+    if (detectOnlyConfigured.length > 0) {
+        parts.push(`detect-only (no Safe Fix writer): ${detectOnlyConfigured.map((a) => a.displayName).join(", ")}`);
+    }
+    lines.push(colors.dim(`  Coverage: ${parts.join(" · ")}`));
+    return lines;
+}
 function groupFindings(findings) {
     return {
         critical: findings.filter((f) => f.severity === "critical"),
@@ -152,6 +184,7 @@ export function renderTerminalReport(result, options = {}) {
             }
         }
     }
+    lines.push(...renderAgentCoverageSummary(result));
     lines.push("");
     const grouped = groupFindings(result.findings);
     const total = result.summary.total;
@@ -164,10 +197,10 @@ export function renderTerminalReport(result, options = {}) {
     }
     if (total === 0) {
         if (limited) {
-            lines.push(`  ${symbolWarn()} Nothing to audit yet — no Cursor, Claude Code, or Codex config found`);
+            lines.push(`  ${symbolOk()} No repository-hygiene findings — agent readiness not scored (no supported agent config)`);
             lines.push("");
-            lines.push(colors.dim("  Next: add project agent config (for example `.cursor/`, `CLAUDE.md` / `.claude/`, or `AGENTS.md`),"));
-            lines.push(colors.dim("  then re-run `agentdoctor` in this repository."));
+            lines.push(colors.dim("  Optional next: add project agent config (`.cursor/`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.windsurf/rules/`, `GEMINI.md`, or `.aider.conf.yml`)"));
+            lines.push(colors.dim("  so agent exposure checks run fully. CLI, Action, and Project Brain MCP still work without an agent."));
         }
         else {
             lines.push(`  ${symbolOk()} No findings`);
@@ -217,7 +250,7 @@ export function renderTerminalReport(result, options = {}) {
     lines.push("");
     if (result.scoringAvailable && result.scores) {
         if (limited) {
-            lines.push(`  Readiness: n/a — configure Cursor, Claude Code, or Codex before treating scores as agent readiness`);
+            lines.push(`  Readiness: n/a — configure a supported agent (Cursor, Claude Code, Codex, Copilot, Windsurf, Gemini CLI, or Aider) before treating scores as agent readiness`);
             lines.push(colors.dim(`  Numeric scores remain in JSON (overall ${result.scores.overall}/100) for repository-risk findings only`));
         }
         else {

package/dist/security/paths.d.ts

@@ -0,0 +1,21 @@
+export declare class PathEscapeError extends Error {
+    readonly code = "PATH_ESCAPE";
+    constructor(message?: string);
+}
+declare function tryDecodeUri(value: string): string | null;
+/**
+ * Lexical hostility checks shared by resolve/assert helpers.
+ * Does not leak the candidate path in thrown messages.
+ */
+export declare function rejectHostilePathInput(candidate: string): void;
+/**
+ * Resolve a user-supplied path and require it to remain inside the repository root.
+ * Rejects `..`, URI-encoded traversal, null bytes, Windows-drive absolutes, and
+ * symlink realpath escapes. Error messages never echo the hostile candidate.
+ */
+export declare function resolveSafeRepoPath(rootInput: string, candidate: string): string;
+/** Assert `candidate` resolves inside `root`; throws PathEscapeError otherwise. */
+export declare function assertInsideRepo(rootInput: string, candidate: string): void;
+/** Resolve safely and return a POSIX path relative to the repo root. */
+export declare function safeRelPath(rootInput: string, absoluteOrRel: string): string;
+export { tryDecodeUri as tryDecodeUriComponent };