@praneeth_54/agentdoctor 1.1.1 → 2.0.1

package/dist/platform/firewall/evaluate.d.ts

@@ -0,0 +1,57 @@
+import type { AgentActionRequest, FirewallDecision, FirewallVerdict, PlatformSeverity } from "../types.js";
+export interface FirewallPolicyRule {
+    id: string;
+    actionTypes?: AgentActionRequest["type"][];
+    match?: {
+        commandContains?: string[];
+        commandPatterns?: string[];
+        pathPrefix?: string[];
+        pathContains?: string[];
+    };
+    decision: FirewallDecision;
+    reason: string;
+    riskLevel: PlatformSeverity;
+}
+export interface FirewallPolicyDocument {
+    version: "2.0";
+    defaultDecision: FirewallDecision;
+    /** When true and policy file is invalid, deny all actions instead of falling back to defaults. */
+    failClosed?: boolean;
+    /**
+     * When set, shell actions that are not already blocked must match at least one allowlist entry
+     * (substring match, case-insensitive) or they receive require-approval.
+     */
+    shellAllowlist?: string[];
+    rules: FirewallPolicyRule[];
+}
+export interface PolicyLoadResult {
+    policy: FirewallPolicyDocument;
+    source: "file" | "default" | "fail-closed-deny" | "composed";
+    validationError?: string;
+    composeSources?: Array<"builtin" | "repo">;
+}
+declare const EVALUATE_ONLY = "Evaluate-only: no commands are executed and no agents are intercepted.";
+declare const DEFAULT_POLICY: FirewallPolicyDocument;
+export declare function validateFirewallPolicy(raw: unknown): {
+    ok: boolean;
+    policy?: FirewallPolicyDocument;
+    error?: string;
+};
+/**
+ * Load local action-policy document.
+ * Layers: composed builtin pack + `.agentdoctor/policy.json` (fail-closed on malformed repo policy),
+ * then optional platform `firewall-policy.json` overlay (highest precedence when valid).
+ * Invalid platform file + failClosed → deny-all.
+ * Invalid platform file + default → composed policy (or DEFAULT_POLICY when compose unavailable).
+ */
+export declare function loadFirewallPolicy(root: string, options?: {
+    failClosed?: boolean;
+}): Promise<PolicyLoadResult>;
+/**
+ * Module C — Action Policy Evaluator (compatibility: firewall).
+ * Evaluates policies only; never executes the requested action and does not intercept agents.
+ */
+export declare function evaluateAgentAction(root: string, action: AgentActionRequest, options?: {
+    failClosed?: boolean;
+}): Promise<FirewallVerdict>;
+export { DEFAULT_POLICY, EVALUATE_ONLY };

package/dist/platform/firewall/evaluate.js

@@ -0,0 +1,359 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { platformDir, writeJsonArtifact } from "../store.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { composePolicy } from "../../policy/compose.js";
+const EVALUATE_ONLY = "Evaluate-only: no commands are executed and no agents are intercepted.";
+const DEFAULT_POLICY = {
+    version: "2.0",
+    defaultDecision: "require-approval",
+    failClosed: false,
+    shellAllowlist: [
+        "npm test",
+        "npm run test",
+        "npm --version",
+        "npm -v",
+        "vitest",
+        "eslint",
+        "tsc",
+        "prettier",
+    ],
+    rules: [
+        {
+            id: "block-secret-paths",
+            actionTypes: ["file-modify", "file-delete", "file-create", "secret-access"],
+            match: {
+                pathContains: [
+                    ".env",
+                    "id_rsa",
+                    "id_ed25519",
+                    "credentials",
+                    "secrets/",
+                    ".pem",
+                    "service-account",
+                ],
+            },
+            decision: "block",
+            reason: "Secret-sensitive path",
+            riskLevel: "critical",
+        },
+        {
+            id: "deny-prod-deploy",
+            actionTypes: ["deploy", "infra"],
+            decision: "block",
+            reason: "Production/infra changes require out-of-band process",
+            riskLevel: "critical",
+        },
+        {
+            id: "network-default-deny",
+            actionTypes: ["network"],
+            decision: "deny-network",
+            reason: "Network access denied by default",
+            riskLevel: "high",
+        },
+        {
+            id: "package-install-approval",
+            actionTypes: ["package-install"],
+            decision: "require-approval",
+            reason: "Package installs change supply chain",
+            riskLevel: "high",
+        },
+        {
+            id: "allow-safe-dev-paths",
+            actionTypes: ["file-modify", "file-create"],
+            match: { pathPrefix: ["src/", "tests/", "docs/"] },
+            decision: "allow",
+            reason: "Allowlisted development paths",
+            riskLevel: "low",
+        },
+    ],
+};
+const BUILTIN_SHELL_BLOCKS = [
+    {
+        id: "builtin-rm-recursive",
+        patterns: [
+            /\brm\s+(-[^\s]*f[^\s]*r|-[^\s]*r[^\s]*f|--recursive)\b/i,
+            /\brm\s+-rf\b/i,
+            /\brm\s+-fr\b/i,
+        ],
+        reason: "Recursive deletion pattern",
+    },
+    {
+        id: "builtin-disk-format",
+        patterns: [/\bmkfs(\.\w+)?\b/i, /\bdd\s+if=/i, /\bshred\b/i],
+        reason: "Disk-formatting / destructive device write pattern",
+    },
+    {
+        id: "builtin-fork-bomb",
+        patterns: [/:\(\)\s*\{\s*:\|:&\s*\}\s*;?\s*:/, /\bfork\s*\(\s*\)\s*while/i],
+        reason: "Fork-bomb pattern",
+    },
+    {
+        id: "builtin-deploy",
+        patterns: [
+            /\b(kubectl\s+apply|helm\s+upgrade|terraform\s+apply|pulumi\s+up)\b/i,
+            /\b(aws\s+s3\s+sync|gcloud\s+deploy|az\s+deployment)\b/i,
+            /\bdocker\s+push\b/i,
+            /\bnpm\s+publish\b/i,
+        ],
+        reason: "Deployment / publish command pattern",
+    },
+    {
+        id: "builtin-network-exfil",
+        patterns: [
+            /\bcurl\b.*\b(-d|--data|--upload-file|-T)\b/i,
+            /\bwget\b.*\b(--post-data|--body-data)\b/i,
+            /\bnc\s+-l\b/i,
+            /\bcurl\b.*\bhttps?:\/\/[^\s]*(webhook|exfil|pastebin|evil)/i,
+        ],
+        reason: "Network exfiltration-style pattern",
+    },
+];
+function isFirewallDecision(value) {
+    return (value === "allow" ||
+        value === "block" ||
+        value === "require-approval" ||
+        value === "sandbox-only" ||
+        value === "deny-network" ||
+        value === "deny-secrets");
+}
+export function validateFirewallPolicy(raw) {
+    if (!raw || typeof raw !== "object")
+        return { ok: false, error: "policy must be an object" };
+    const doc = raw;
+    if (doc.version !== "2.0")
+        return { ok: false, error: 'policy.version must be "2.0"' };
+    if (!Array.isArray(doc.rules))
+        return { ok: false, error: "policy.rules must be an array" };
+    if (!isFirewallDecision(doc.defaultDecision)) {
+        return { ok: false, error: "policy.defaultDecision is invalid" };
+    }
+    for (const [i, rule] of doc.rules.entries()) {
+        if (!rule || typeof rule !== "object") {
+            return { ok: false, error: `rules[${i}] must be an object` };
+        }
+        const r = rule;
+        if (typeof r.id !== "string" || !r.id)
+            return { ok: false, error: `rules[${i}].id required` };
+        if (!isFirewallDecision(r.decision)) {
+            return { ok: false, error: `rules[${i}].decision invalid` };
+        }
+    }
+    if (doc.shellAllowlist !== undefined && !Array.isArray(doc.shellAllowlist)) {
+        return { ok: false, error: "shellAllowlist must be an array of strings" };
+    }
+    return {
+        ok: true,
+        policy: {
+            version: "2.0",
+            defaultDecision: doc.defaultDecision,
+            failClosed: Boolean(doc.failClosed),
+            ...(Array.isArray(doc.shellAllowlist)
+                ? { shellAllowlist: doc.shellAllowlist.filter((s) => typeof s === "string") }
+                : {}),
+            rules: doc.rules,
+        },
+    };
+}
+function denyAllPolicy(reason) {
+    return {
+        version: "2.0",
+        defaultDecision: "block",
+        failClosed: true,
+        rules: [
+            {
+                id: "fail-closed-deny-all",
+                decision: "block",
+                reason,
+                riskLevel: "critical",
+            },
+        ],
+    };
+}
+/**
+ * Load local action-policy document.
+ * Layers: composed builtin pack + `.agentdoctor/policy.json` (fail-closed on malformed repo policy),
+ * then optional platform `firewall-policy.json` overlay (highest precedence when valid).
+ * Invalid platform file + failClosed → deny-all.
+ * Invalid platform file + default → composed policy (or DEFAULT_POLICY when compose unavailable).
+ */
+export async function loadFirewallPolicy(root, options) {
+    const resolved = resolveRepoRoot(root);
+    const composed = await composePolicy({ root: resolved });
+    if (composed.validationError && composed.failClosed) {
+        return {
+            policy: composed.policy,
+            source: "fail-closed-deny",
+            validationError: composed.validationError,
+            composeSources: composed.sources,
+        };
+    }
+    const file = path.join(platformDir(resolved), "firewall-policy.json");
+    try {
+        const raw = await fs.readFile(file, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            const failClosed = options?.failClosed === true || composed.failClosed;
+            if (failClosed) {
+                return {
+                    policy: denyAllPolicy("Malformed policy JSON; fail-closed deny"),
+                    source: "fail-closed-deny",
+                    validationError: "Malformed JSON",
+                    composeSources: composed.sources,
+                };
+            }
+            return {
+                policy: composed.policy,
+                source: "composed",
+                validationError: "Malformed platform firewall-policy.json; using composed policy",
+                composeSources: composed.sources,
+            };
+        }
+        const validated = validateFirewallPolicy(parsed);
+        if (!validated.ok || !validated.policy) {
+            const fileWantsFailClosed = parsed &&
+                typeof parsed === "object" &&
+                parsed.failClosed === true;
+            const failClosed = options?.failClosed === true || fileWantsFailClosed || composed.failClosed;
+            if (failClosed) {
+                return {
+                    policy: denyAllPolicy(`Invalid policy: ${validated.error}`),
+                    source: "fail-closed-deny",
+                    ...(validated.error ? { validationError: validated.error } : {}),
+                    composeSources: composed.sources,
+                };
+            }
+            return {
+                policy: composed.policy,
+                source: "composed",
+                ...(validated.error
+                    ? { validationError: `Invalid platform policy; using composed (${validated.error})` }
+                    : {}),
+                composeSources: composed.sources,
+            };
+        }
+        // Platform file rules first (highest precedence), then composed builtin+repo rules.
+        const merged = {
+            version: "2.0",
+            defaultDecision: validated.policy.defaultDecision,
+            failClosed: validated.policy.failClosed === true || composed.policy.failClosed === true,
+            ...(validated.policy.shellAllowlist
+                ? { shellAllowlist: validated.policy.shellAllowlist }
+                : composed.policy.shellAllowlist
+                    ? { shellAllowlist: composed.policy.shellAllowlist }
+                    : {}),
+            rules: [...validated.policy.rules, ...composed.policy.rules],
+        };
+        return {
+            policy: merged,
+            source: "file",
+            composeSources: composed.sources,
+        };
+    }
+    catch {
+        // No platform file: prefer repo-composed policy when `.agentdoctor/policy.json` exists.
+        // Otherwise seed DEFAULT_POLICY (includes allow-safe-dev-paths). Do not treat packName
+        // alone as a reason to skip DEFAULT_POLICY — compose always names a builtin pack.
+        if (composed.sources.includes("repo")) {
+            return {
+                policy: composed.policy,
+                source: "composed",
+                composeSources: composed.sources,
+            };
+        }
+        await writeJsonArtifact(resolved, "firewall-policy.json", DEFAULT_POLICY);
+        return { policy: DEFAULT_POLICY, source: "default", composeSources: composed.sources };
+    }
+}
+function ruleMatches(rule, action) {
+    if (rule.actionTypes && !rule.actionTypes.includes(action.type))
+        return false;
+    const cmd = action.params.command ?? "";
+    const target = action.params.path ?? action.params.target ?? "";
+    const match = rule.match;
+    if (!match)
+        return true;
+    if (match.commandContains?.length) {
+        if (!match.commandContains.some((p) => cmd.toLowerCase().includes(p.toLowerCase()))) {
+            return false;
+        }
+    }
+    if (match.commandPatterns?.length) {
+        if (!match.commandPatterns.some((p) => {
+            try {
+                return new RegExp(p, "i").test(cmd);
+            }
+            catch {
+                return false;
+            }
+        })) {
+            return false;
+        }
+    }
+    if (match.pathPrefix?.length) {
+        if (!match.pathPrefix.some((p) => target.startsWith(p)))
+            return false;
+    }
+    if (match.pathContains?.length) {
+        if (!match.pathContains.some((p) => target.toLowerCase().includes(p.toLowerCase()))) {
+            return false;
+        }
+    }
+    return true;
+}
+function matchBuiltinShell(cmd) {
+    for (const rule of BUILTIN_SHELL_BLOCKS) {
+        if (rule.patterns.some((re) => re.test(cmd))) {
+            return { id: rule.id, reason: rule.reason };
+        }
+    }
+    return null;
+}
+function verdict(actionId, decision, reason, riskLevel, policyId) {
+    return {
+        actionId,
+        decision,
+        reason: `${reason}. ${EVALUATE_ONLY}`,
+        riskLevel,
+        ...(policyId ? { policyId } : {}),
+        approvalStatus: decision === "require-approval" ? "pending" : "not-required",
+        executionResult: "not-executed",
+    };
+}
+/**
+ * Module C — Action Policy Evaluator (compatibility: firewall).
+ * Evaluates policies only; never executes the requested action and does not intercept agents.
+ */
+export async function evaluateAgentAction(root, action, options) {
+    const loaded = await loadFirewallPolicy(root, options);
+    if (action.type === "shell") {
+        const cmd = action.params.command ?? "";
+        const builtin = matchBuiltinShell(cmd);
+        if (builtin) {
+            return verdict(action.actionId, "block", builtin.reason, "critical", builtin.id);
+        }
+    }
+    for (const rule of loaded.policy.rules) {
+        if (!ruleMatches(rule, action))
+            continue;
+        return verdict(action.actionId, rule.decision, rule.reason, rule.riskLevel, rule.id);
+    }
+    if (action.type === "shell" && loaded.policy.shellAllowlist?.length) {
+        const cmd = (action.params.command ?? "").toLowerCase();
+        const allowed = loaded.policy.shellAllowlist.some((entry) => cmd.includes(entry.toLowerCase()));
+        if (!allowed) {
+            return verdict(action.actionId, "require-approval", "Shell command not on local allowlist", "medium", "shell-allowlist");
+        }
+        return verdict(action.actionId, "allow", "Shell command matches local allowlist", "low", "shell-allowlist");
+    }
+    const reason = loaded.source === "fail-closed-deny"
+        ? `Fail-closed deny (${loaded.validationError ?? "invalid policy"})`
+        : loaded.source === "default" && loaded.validationError
+            ? `No specific rule matched; default policy applied (fallback after: ${loaded.validationError})`
+            : "No specific rule matched; default policy applied";
+    return verdict(action.actionId, loaded.policy.defaultDecision, reason, loaded.source === "fail-closed-deny" ? "critical" : "medium", loaded.source === "fail-closed-deny" ? "fail-closed-deny-all" : "default");
+}
+export { DEFAULT_POLICY, EVALUATE_ONLY };

package/dist/platform/graph/build.d.ts

@@ -0,0 +1,6 @@
+import type { RepositoryGraph } from "../types.js";
+/**
+ * Module A — Repository Intelligence (local graph MVP).
+ * Symbol extraction is heuristic (regex), not a full language AST.
+ */
+export declare function buildRepositoryGraph(rootInput: string): Promise<RepositoryGraph>;

package/dist/platform/graph/build.js

@@ -0,0 +1,189 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot, toPosixRelative } from "../../utils/path.js";
+const SKIP = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "coverage",
+    ".agentdoctor",
+    "vendor",
+    ".next",
+    "build",
+]);
+const CODE_EXT = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".php",
+    ".rb",
+]);
+function nodeId(kind, key) {
+    return `${kind}:${createHash("sha1").update(key).digest("hex").slice(0, 12)}`;
+}
+async function walk(root, dir, files, dirs, limit) {
+    if (files.length >= limit)
+        return;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIP.has(entry.name))
+            continue;
+        const absolute = path.join(dir, entry.name);
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            dirs.push(absolute);
+            await walk(root, absolute, files, dirs, limit);
+            continue;
+        }
+        if (entry.isFile())
+            files.push(absolute);
+    }
+}
+function extractSymbols(content, rel) {
+    const nodes = [];
+    const fnRe = /(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_][A-Za-z0-9_]*)|([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?:async\s*)?\(/g;
+    const classRe = /(?:export\s+)?class\s+([A-Za-z_][A-Za-z0-9_]*)/g;
+    let m;
+    while ((m = fnRe.exec(content))) {
+        const name = m[1] ?? m[2];
+        if (!name || name.length < 2)
+            continue;
+        nodes.push({
+            id: nodeId("function", `${rel}:${name}`),
+            kind: "function",
+            label: name,
+            path: rel,
+        });
+    }
+    while ((m = classRe.exec(content))) {
+        const name = m[1];
+        nodes.push({
+            id: nodeId("class", `${rel}:${name}`),
+            kind: "class",
+            label: name,
+            path: rel,
+        });
+    }
+    return nodes;
+}
+function extractImports(content, rel) {
+    const edges = [];
+    const dependencyNodes = [];
+    const importRe = /(?:import\s+.*?from\s+|require\()\s*['"]([^'"]+)['"]|from\s+['"]([^'"]+)['"]/g;
+    let m;
+    const fromId = nodeId("file", rel);
+    const seen = new Set();
+    while ((m = importRe.exec(content))) {
+        const spec = m[1] ?? m[2];
+        if (!spec)
+            continue;
+        const toId = nodeId("dependency", `${rel}->${spec}`);
+        edges.push({
+            id: nodeId("edge", `${fromId}->${toId}`),
+            from: fromId,
+            to: toId,
+            kind: "imports",
+            evidence: spec.startsWith(".") ? "verified" : "inferred",
+        });
+        if (!seen.has(toId)) {
+            seen.add(toId);
+            dependencyNodes.push({
+                id: toId,
+                kind: "dependency",
+                label: spec,
+                path: rel,
+                meta: { specifier: spec },
+            });
+        }
+    }
+    return { edges, dependencyNodes };
+}
+/**
+ * Module A — Repository Intelligence (local graph MVP).
+ * Symbol extraction is heuristic (regex), not a full language AST.
+ */
+export async function buildRepositoryGraph(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const files = [];
+    const dirs = [];
+    await walk(root, root, files, dirs, 2_000);
+    const nodes = [];
+    const edges = [];
+    const limitations = [
+        "Symbol extraction is regex-heuristic for common languages; not a full AST",
+        "Call-graph and multi-repo federation are extension points (not fully built)",
+    ];
+    for (const dir of dirs) {
+        const rel = toPosixRelative(root, dir) || ".";
+        nodes.push({
+            id: nodeId("directory", rel),
+            kind: "directory",
+            label: path.basename(dir),
+            path: rel,
+        });
+    }
+    for (const absolute of files) {
+        const rel = toPosixRelative(root, absolute);
+        const ext = path.extname(rel).toLowerCase();
+        const base = path.basename(rel).toLowerCase();
+        let kind = "file";
+        if (/\.(test|spec)\./i.test(rel) || rel.includes("__tests__"))
+            kind = "test";
+        else if (/\.(md|rst|txt)$/i.test(ext))
+            kind = "doc";
+        else if (/\.(yml|yaml|toml|json|env)$/i.test(ext) ||
+            base.startsWith("dockerfile") ||
+            base === "makefile")
+            kind = "config";
+        const fileId = nodeId("file", rel);
+        nodes.push({ id: fileId, kind, label: path.basename(rel), path: rel });
+        if (CODE_EXT.has(ext)) {
+            // open+fstat+read via readTextFile — avoids exists/stat→read TOCTOU
+            const content = await readTextFile(absolute, 256 * 1024);
+            if (content === null)
+                continue;
+            nodes.push(...extractSymbols(content, rel));
+            const { edges: importEdges, dependencyNodes } = extractImports(content, rel);
+            edges.push(...importEdges);
+            for (const dep of dependencyNodes) {
+                if (!nodes.some((n) => n.id === dep.id))
+                    nodes.push(dep);
+            }
+            if (/router\.|app\.(get|post|put|delete)|@app\.(get|post)/i.test(content)) {
+                nodes.push({
+                    id: nodeId("api", rel),
+                    kind: "api",
+                    label: `api:${path.basename(rel)}`,
+                    path: rel,
+                    meta: { evidence: "inferred" },
+                });
+            }
+        }
+    }
+    nodes.sort((a, b) => a.id.localeCompare(b.id));
+    edges.sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        root,
+        generatedAt: new Date().toISOString(),
+        nodes,
+        edges,
+        limitations,
+    };
+}

package/dist/platform/health/analyze.d.ts

@@ -0,0 +1,7 @@
+import type { PlatformFinding } from "../types.js";
+import type { RepositoryGraph } from "../types.js";
+/**
+ * Module B — Code health & risk (deterministic heuristics with evidence).
+ */
+export declare function analyzeCodeHealth(rootInput: string, graph: RepositoryGraph): Promise<PlatformFinding[]>;
+export declare function scoreFileRisk(findings: PlatformFinding[], filePath: string): number;