@praneeth_54/agentdoctor 2.0.1 → 3.0.0

package/dist/mcp/intelligence/handlers.js

@@ -11,6 +11,9 @@ import { redactSecrets } from "../../platform/security/redact.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 import { CONTRACTS_VERSION } from "../../contracts/index.js";
 import { assertSafeRepoTarget } from "./path-safety.js";
+import { buildProjectDna } from "../../product/dna/build.js";
+import { buildSoftwareMap } from "../../product/map/software-map.js";
+import { analyzeWhatIf } from "../../product/whatif/engine.js";
 function requireString(args, key) {
     const value = args[key];
     if (typeof value !== "string")
@@ -362,3 +365,28 @@ export async function handleGraphQueryTool(rootInput, args) {
         ],
     });
 }
+export async function handleProjectDnaTool(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const dna = await buildProjectDna(root);
+    return redactDeep({ ok: true, dna, limitations: dna.limitations });
+}
+export async function handleSoftwareMapTool(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const map = await buildSoftwareMap(root);
+    return redactDeep({ ok: true, map, limitations: map.limitations });
+}
+export async function handleWhatIfTool(rootInput, args) {
+    const root = resolveRepoRoot(rootInput);
+    const target = requireString(args, "target");
+    if (!target) {
+        return invalidArgument("target required (repo-relative path or symbol)");
+    }
+    try {
+        assertSafeRepoTarget(root, target);
+    }
+    catch {
+        return pathEscape();
+    }
+    const report = await analyzeWhatIf(root, target);
+    return redactDeep({ ok: true, report, limitations: report.limitations });
+}

package/dist/mcp/intelligence/registry.d.ts

@@ -1,5 +1,5 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-export declare const INTELLIGENCE_MCP_TOOL_NAMES: readonly ["repo_overview", "codebase_search", "symbol_lookup", "dependency_lookup", "call_graph_lookup", "test_impact", "refactor_impact", "code_health", "architecture_info", "architecture_check", "knowledge_retrieve", "policy_evaluate", "change_analyze", "proof_inspect", "evidence_inspect", "graph_query"];
+export declare const INTELLIGENCE_MCP_TOOL_NAMES: readonly ["repo_overview", "codebase_search", "symbol_lookup", "dependency_lookup", "call_graph_lookup", "test_impact", "refactor_impact", "code_health", "architecture_info", "architecture_check", "knowledge_retrieve", "policy_evaluate", "change_analyze", "proof_inspect", "evidence_inspect", "graph_query", "project_dna", "software_map", "what_if"];
 export type IntelligenceMcpToolName = (typeof INTELLIGENCE_MCP_TOOL_NAMES)[number];
 export declare function listIntelligenceMcpTools(): Tool[];
 export declare function invokeIntelligenceMcpTool(root: string, name: string, args: Record<string, unknown>): Promise<{

package/dist/mcp/intelligence/registry.js

@@ -1,4 +1,4 @@
-import { handleArchitectureCheckTool, handleArchitectureTool, handleCallGraphLookup, handleChangeAnalyzeTool, handleCodeHealthTool, handleCodebaseSearch, handleDependencyLookup, handleEvidenceInspectTool, handleGraphQueryTool, handleKnowledgeTool, handlePolicyEvalTool, handleProofInspectTool, handleRefactorImpactTool, handleRepoOverview, handleSymbolLookup, handleTestImpactTool, } from "./handlers.js";
+import { handleArchitectureCheckTool, handleArchitectureTool, handleCallGraphLookup, handleChangeAnalyzeTool, handleCodeHealthTool, handleCodebaseSearch, handleDependencyLookup, handleEvidenceInspectTool, handleGraphQueryTool, handleKnowledgeTool, handlePolicyEvalTool, handleProofInspectTool, handleRefactorImpactTool, handleRepoOverview, handleSymbolLookup, handleTestImpactTool, handleProjectDnaTool, handleSoftwareMapTool, handleWhatIfTool, } from "./handlers.js";
 export const INTELLIGENCE_MCP_TOOL_NAMES = [
     "repo_overview",
     "codebase_search",
@@ -16,6 +16,9 @@ export const INTELLIGENCE_MCP_TOOL_NAMES = [
     "proof_inspect",
     "evidence_inspect",
     "graph_query",
+    "project_dna",
+    "software_map",
+    "what_if",
 ];
 const emptyObjectSchema = {
     type: "object",
@@ -166,6 +169,26 @@ export function listIntelligenceMcpTools() {
                 additionalProperties: false,
             },
         },
+        {
+            name: "project_dna",
+            description: "READ: Deterministic project DNA fingerprint (languages, frameworks, monorepo). No shell.",
+            inputSchema: emptyObjectSchema,
+        },
+        {
+            name: "software_map",
+            description: "READ: Navigable software map tree from discovery heuristics. No shell.",
+            inputSchema: emptyObjectSchema,
+        },
+        {
+            name: "what_if",
+            description: "READ: What-if impact analysis for a repo-relative path or symbol (graph-backed). Path validated.",
+            inputSchema: {
+                type: "object",
+                properties: { target: { type: "string" } },
+                required: ["target"],
+                additionalProperties: false,
+            },
+        },
     ];
 }
 export async function invokeIntelligenceMcpTool(root, name, args) {
@@ -203,6 +226,12 @@ export async function invokeIntelligenceMcpTool(root, name, args) {
                 return { structured: await handleEvidenceInspectTool(root, args), isError: false };
             case "graph_query":
                 return { structured: await handleGraphQueryTool(root, args), isError: false };
+            case "project_dna":
+                return { structured: await handleProjectDnaTool(root), isError: false };
+            case "software_map":
+                return { structured: await handleSoftwareMapTool(root), isError: false };
+            case "what_if":
+                return { structured: await handleWhatIfTool(root, args), isError: false };
             default:
                 return {
                     structured: {

package/dist/product/api/doctor.d.ts

@@ -0,0 +1,14 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface ApiEndpointFinding {
+    method: string;
+    pathPattern: string;
+    framework: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface ApiDoctorReport {
+    root: string;
+    endpoints: ApiEndpointFinding[];
+    limitations: string[];
+}
+export declare function analyzeApiSurface(rootInput: string): Promise<ApiDoctorReport>;

package/dist/product/api/doctor.js

@@ -0,0 +1,185 @@
+import { lineNumberAt, loadProjectSourceFiles } from "../evidence-scan.js";
+import { discoverOpenApiEndpoints } from "./openapi.js";
+const ROUTE_PATTERNS = [
+    {
+        framework: "express",
+        regex: /\.(?:get|post|put|patch|delete|all)\(\s*['"`]([^'"`]+)['"`]/gi,
+        pathGroup: 1,
+    },
+    {
+        framework: "express-router",
+        regex: /router\.(?:get|post|put|patch|delete|all)\(\s*['"`]([^'"`]+)['"`]/gi,
+        pathGroup: 1,
+    },
+    {
+        framework: "fastify",
+        regex: /fastify\.(?:get|post|put|patch|delete)\(\s*['"`]([^'"`]+)['"`]/gi,
+        pathGroup: 1,
+    },
+    {
+        framework: "nestjs",
+        regex: /@(Get|Post|Put|Patch|Delete|All)\(\s*['"`]([^'"`]+)['"`]?\s*\)/g,
+        methodGroup: 1,
+        pathGroup: 2,
+    },
+    {
+        framework: "nestjs",
+        regex: /@(Get|Post|Put|Patch|Delete|All)\(\)/g,
+        methodGroup: 1,
+        pathGroup: 0,
+    },
+    {
+        framework: "laravel",
+        regex: /Route::(get|post|put|patch|delete|any)\(\s*['"]([^'"]+)['"]/gi,
+        methodGroup: 1,
+        pathGroup: 2,
+    },
+    {
+        framework: "flask",
+        regex: /@(?:app|bp|blueprint)\.(?:route|get|post|put|patch|delete)\(\s*['"]([^'"]+)['"]/gi,
+        pathGroup: 1,
+    },
+    {
+        framework: "flask",
+        regex: /@(?:app|bp)\.(get|post|put|patch|delete)\(\s*['"]([^'"]+)['"]/gi,
+        methodGroup: 1,
+        pathGroup: 2,
+    },
+];
+function inferMethodFromMatch(full, pattern, groups) {
+    const methodRaw = pattern.methodGroup !== undefined ? groups[pattern.methodGroup] : undefined;
+    if (methodRaw) {
+        return methodRaw.toUpperCase();
+    }
+    const lower = full.toLowerCase();
+    for (const m of ["get", "post", "put", "patch", "delete", "all"]) {
+        if (lower.includes(`.${m}(`) || lower.includes(`@${m}`) || lower.includes(`::${m}(`)) {
+            return m === "all" ? "ALL" : m.toUpperCase();
+        }
+    }
+    return pattern.defaultMethod ?? "UNKNOWN";
+}
+function scanFile(relativePath, content) {
+    const findings = [];
+    for (const pattern of ROUTE_PATTERNS) {
+        pattern.regex.lastIndex = 0;
+        let match;
+        while ((match = pattern.regex.exec(content)) !== null) {
+            const pathGroup = pattern.pathGroup;
+            let pathPattern = pathGroup > 0 ? (match[pathGroup] ?? "") : "/";
+            if (!pathPattern && pattern.framework === "nestjs")
+                pathPattern = "/";
+            if (!pathPattern)
+                continue;
+            const method = inferMethodFromMatch(match[0], pattern, match);
+            const line = lineNumberAt(content, match.index);
+            findings.push({
+                method,
+                pathPattern,
+                framework: pattern.framework,
+                truth: "INFERRED",
+                evidence: [
+                    {
+                        path: relativePath,
+                        line,
+                        excerpt: match[0].trim().slice(0, 160),
+                    },
+                ],
+            });
+        }
+    }
+    return findings;
+}
+function scanGraphqlSurface(relativePath, content) {
+    const findings = [];
+    const typeQueryRe = /type\s+Query\s*\{/g;
+    let match;
+    while ((match = typeQueryRe.exec(content)) !== null) {
+        findings.push({
+            method: "GRAPHQL",
+            pathPattern: "Query",
+            framework: "graphql-sdl",
+            truth: "INFERRED",
+            evidence: [
+                {
+                    path: relativePath,
+                    line: lineNumberAt(content, match.index),
+                    excerpt: match[0].trim(),
+                },
+            ],
+        });
+    }
+    const gqlRe = /gql`\s*([\s\S]*?)`/g;
+    while ((match = gqlRe.exec(content)) !== null) {
+        const inner = match[1] ?? "";
+        const opMatch = /(?:query|mutation|subscription)\s+(\w+)/i.exec(inner);
+        const opName = opMatch?.[1] ?? "anonymous";
+        findings.push({
+            method: "GRAPHQL",
+            pathPattern: opName,
+            framework: "graphql-tag",
+            truth: "INFERRED",
+            evidence: [
+                {
+                    path: relativePath,
+                    line: lineNumberAt(content, match.index),
+                    excerpt: match[0].trim().slice(0, 160),
+                },
+            ],
+        });
+    }
+    return findings;
+}
+const SOURCE_FILTER = (rel) => {
+    const lower = rel.toLowerCase();
+    if (lower.endsWith(".graphql") || lower.endsWith(".gql"))
+        return true;
+    if (lower.endsWith(".php") && (lower.includes("routes/") || lower.includes("route")))
+        return true;
+    if (lower.endsWith(".py") &&
+        (lower.includes("routes") || lower.includes("views") || lower.includes("app"))) {
+        return true;
+    }
+    if (lower.endsWith(".ts") ||
+        lower.endsWith(".tsx") ||
+        lower.endsWith(".js") ||
+        lower.endsWith(".jsx")) {
+        return (lower.includes("route") ||
+            lower.includes("controller") ||
+            lower.includes("api/") ||
+            lower.includes("server") ||
+            lower.includes("app.module") ||
+            lower.includes("graphql") ||
+            lower.includes("schema"));
+    }
+    return false;
+};
+export async function analyzeApiSurface(rootInput) {
+    const { root, files, limitations: scanLimits, } = await loadProjectSourceFiles(rootInput, SOURCE_FILTER);
+    const limitations = [
+        "Endpoint discovery uses regex on route declarations; middleware, prefixes, and global mounts are not resolved.",
+        "Dynamic route paths and framework-specific route files may be missed.",
+        "GraphQL schema extraction (PARTIAL): static SDL `type Query` and gql` template literals only — not live gateway introspection.",
+        ...scanLimits,
+    ];
+    const endpoints = [];
+    for (const file of files) {
+        endpoints.push(...scanFile(file.relativePath, file.content));
+        endpoints.push(...scanGraphqlSurface(file.relativePath, file.content));
+    }
+    const openApi = await discoverOpenApiEndpoints(root);
+    limitations.push(...openApi.limitations);
+    endpoints.push(...openApi.endpoints);
+    const seen = new Set();
+    const deduped = endpoints.filter((e) => {
+        const key = `${e.method}:${e.pathPattern}:${e.framework}:${e.evidence[0]?.path}:${e.evidence[0]?.line}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    deduped.sort((a, b) => a.pathPattern === b.pathPattern
+        ? a.method.localeCompare(b.method)
+        : a.pathPattern.localeCompare(b.pathPattern));
+    return { root, endpoints: deduped, limitations };
+}

package/dist/product/api/openapi.d.ts

@@ -0,0 +1,7 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+import type { ApiEndpointFinding } from "./doctor.js";
+export declare function discoverOpenApiEndpoints(rootInput: string, maxFileSizeBytes?: number): Promise<{
+    endpoints: ApiEndpointFinding[];
+    limitations: string[];
+}>;
+export type { TruthLabel, ProductEvidence };

package/dist/product/api/openapi.js

@@ -0,0 +1,122 @@
+import path from "node:path";
+import { detectProject } from "../../detectors/project.js";
+import { readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+const OPENAPI_NAMES = new Set([
+    "openapi.json",
+    "openapi.yaml",
+    "openapi.yml",
+    "swagger.json",
+    "swagger.yaml",
+    "swagger.yml",
+]);
+function basenameLower(rel) {
+    return path.basename(rel).toLowerCase();
+}
+function extractJsonOpenApiPaths(content, relativePath) {
+    let doc;
+    try {
+        doc = JSON.parse(content);
+    }
+    catch {
+        return [];
+    }
+    const paths = doc.paths;
+    if (!paths || typeof paths !== "object")
+        return [];
+    const out = [];
+    for (const [pathPattern, methods] of Object.entries(paths)) {
+        if (!methods || typeof methods !== "object")
+            continue;
+        for (const method of Object.keys(methods)) {
+            const lower = method.toLowerCase();
+            if (!["get", "post", "put", "patch", "delete", "head", "options", "trace"].includes(lower)) {
+                continue;
+            }
+            out.push({
+                method: lower.toUpperCase(),
+                pathPattern,
+                framework: "openapi",
+                truth: "VERIFIED",
+                evidence: [{ path: relativePath, excerpt: `paths.${pathPattern}.${lower}` }],
+            });
+        }
+    }
+    return out;
+}
+/** Minimal YAML path/method extraction without a YAML library */
+function extractYamlOpenApiPaths(content, relativePath) {
+    const out = [];
+    const lines = content.split(/\r?\n/);
+    let inPaths = false;
+    let currentPath = null;
+    const methodRe = /^\s{2,6}(get|post|put|patch|delete|head|options|trace):\s*$/i;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^paths:\s*$/.test(line.trim())) {
+            inPaths = true;
+            currentPath = null;
+            continue;
+        }
+        if (!inPaths)
+            continue;
+        if (/^[a-zA-Z]/.test(line) && !line.startsWith(" ")) {
+            break;
+        }
+        const pathKey = /^\s{2}(\/[^\s:]+):\s*$/.exec(line);
+        if (pathKey) {
+            currentPath = pathKey[1];
+            continue;
+        }
+        const methodMatch = methodRe.exec(line);
+        if (methodMatch && currentPath) {
+            const method = methodMatch[1].toUpperCase();
+            out.push({
+                method,
+                pathPattern: currentPath,
+                framework: "openapi",
+                truth: "VERIFIED",
+                evidence: [{ path: relativePath, line: i + 1, excerpt: line.trim() }],
+            });
+        }
+    }
+    return out;
+}
+export async function discoverOpenApiEndpoints(rootInput, maxFileSizeBytes = 512 * 1024) {
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const limitations = [
+        "OpenAPI discovery reads static spec files only — mounted servers and merged specs are not resolved.",
+    ];
+    const endpoints = [];
+    for (const entry of detection.discovery.files) {
+        const rel = entry.relativePath.replace(/\\/g, "/");
+        if (!OPENAPI_NAMES.has(basenameLower(rel)))
+            continue;
+        const text = await readTextFile(path.join(root, rel), maxFileSizeBytes);
+        if (text === null)
+            continue;
+        const lower = basenameLower(rel);
+        if (lower.endsWith(".json")) {
+            endpoints.push(...extractJsonOpenApiPaths(text, rel));
+        }
+        else {
+            endpoints.push(...extractYamlOpenApiPaths(text, rel));
+            if (!endpoints.length) {
+                limitations.push(`YAML spec ${rel} had no paths block detected (minimal parser)`);
+            }
+        }
+    }
+    const seen = new Set();
+    const deduped = endpoints.filter((e) => {
+        const key = `${e.method}:${e.pathPattern}:${e.evidence[0]?.path}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    deduped.sort((a, b) => a.pathPattern === b.pathPattern
+        ? a.method.localeCompare(b.method)
+        : a.pathPattern.localeCompare(b.pathPattern));
+    return { endpoints: deduped, limitations };
+}

package/dist/product/approval/model.d.ts

@@ -0,0 +1,30 @@
+export type ApprovalState = "pending" | "approved" | "denied" | "expired";
+export type ApprovalRisk = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+export interface ApprovalRecord {
+    id: string;
+    action: string;
+    reason: string;
+    resources: string[];
+    risk: ApprovalRisk;
+    requirement?: string;
+    state: ApprovalState;
+    actor?: string;
+    createdAt: string;
+    decidedAt?: string;
+    /** Must be true from trusted CLI/MCP session layer — never accept caller approved=true alone */
+    approvedByHuman: boolean;
+}
+export interface ApprovalEvaluationInput {
+    record: Omit<ApprovalRecord, "id" | "createdAt" | "state" | "approvedByHuman">;
+    /** Explicit human gate from CLI `--approve` or authenticated session layer */
+    approvedByHuman?: boolean;
+    actor?: string;
+}
+export interface ApprovalEvaluationResult {
+    record: ApprovalRecord;
+    allowed: boolean;
+    message: string;
+    limitations: string[];
+}
+export declare function evaluateApprovalRecord(input: ApprovalEvaluationInput): ApprovalEvaluationResult;
+export declare function formatApprovalRecordSummary(record: ApprovalRecord): string;

package/dist/product/approval/model.js

@@ -0,0 +1,64 @@
+const LIMITATIONS = [
+    "ApprovalRecord is an explicit abstraction — MCP/model callers cannot set approvedByHuman=true without a trusted session.",
+    "CLI passes approvedByHuman via --approve; dashboard chat does not grant approval.",
+    "This module does not persist approvals — use change ledger / audit trails separately.",
+];
+function newId() {
+    return `apr_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export function evaluateApprovalRecord(input) {
+    const approvedByHuman = input.approvedByHuman === true;
+    const now = new Date().toISOString();
+    const base = {
+        id: newId(),
+        action: input.record.action,
+        reason: input.record.reason,
+        resources: [...input.record.resources],
+        risk: input.record.risk,
+        ...(input.record.requirement !== undefined ? { requirement: input.record.requirement } : {}),
+        state: "pending",
+        ...(input.actor !== undefined ? { actor: input.actor } : {}),
+        createdAt: now,
+        approvedByHuman,
+    };
+    if (!approvedByHuman) {
+        return {
+            record: { ...base, state: "pending", approvedByHuman: false },
+            allowed: false,
+            message: "Human approval required — approvedByHuman must be true from trusted CLI/MCP session (not from model output).",
+            limitations: LIMITATIONS,
+        };
+    }
+    if (input.record.risk === "CRITICAL" && !input.record.reason.trim()) {
+        return {
+            record: { ...base, state: "denied", approvedByHuman: true, decidedAt: now },
+            allowed: false,
+            message: "CRITICAL actions require a non-empty reason even when approvedByHuman is true.",
+            limitations: LIMITATIONS,
+        };
+    }
+    return {
+        record: {
+            ...base,
+            state: "approved",
+            approvedByHuman: true,
+            decidedAt: now,
+        },
+        allowed: true,
+        message: "Explicit human approval recorded.",
+        limitations: LIMITATIONS,
+    };
+}
+export function formatApprovalRecordSummary(record) {
+    return [
+        `Approval ${record.id}`,
+        `Action: ${record.action}`,
+        `Risk: ${record.risk}`,
+        `State: ${record.state}`,
+        `approvedByHuman: ${record.approvedByHuman}`,
+        record.requirement ? `Requirement: ${record.requirement}` : "",
+        record.resources.length ? `Resources: ${record.resources.join(", ")}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/product/approval/session.d.ts

@@ -0,0 +1,49 @@
+import type { ApprovalRisk } from "./model.js";
+/**
+ * Trusted approval grants — MCP/agent writes must present a grant token
+ * issued by CLI `--approve` or an authenticated session, not a bare approved=true.
+ */
+export interface ApprovalGrant {
+    token: string;
+    root: string;
+    action: string;
+    resources: string[];
+    risk: ApprovalRisk;
+    planHash: string;
+    actor: string;
+    createdAt: string;
+    expiresAt: string;
+    consumed: boolean;
+    scope: "write" | "execute" | "write+execute";
+}
+export declare function hashPlanPayload(payload: string): string;
+/** Stable plan hash for a file write operation (path + content). */
+export declare function hashFileWritePlan(action: string, relativePath: string, content: string): string;
+export declare function issueApprovalGrant(options: {
+    root: string;
+    action: string;
+    resources: string[];
+    risk: ApprovalRisk;
+    planHash: string;
+    actor?: string;
+    scope?: ApprovalGrant["scope"];
+    ttlMs?: number;
+}): Promise<ApprovalGrant>;
+export interface ConsumeApprovalResult {
+    ok: boolean;
+    reason: string;
+    grant?: ApprovalGrant;
+}
+/**
+ * Validate and optionally consume a grant token for a write/execute action.
+ * Bare `approved: true` without a valid token is NEVER sufficient.
+ */
+export declare function consumeApprovalGrant(options: {
+    root: string;
+    token: string | undefined;
+    action: string;
+    resources: string[];
+    /** Required for MCP/agent writes — binds token to exact operation payload */
+    requirePlanHash: string;
+    consume?: boolean;
+}): Promise<ConsumeApprovalResult>;