@praneeth_54/agentdoctor 2.1.0 → 3.0.0

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>;

package/dist/product/approval/session.js

@@ -0,0 +1,134 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { atomicWriteTextFile } from "../../utils/fs.js";
+function grantsPath(root) {
+    return path.join(resolveRepoRoot(root), ".agentdoctor", "approvals", "grants.json");
+}
+async function loadGrants(root) {
+    try {
+        const raw = await fs.readFile(grantsPath(root), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed;
+    }
+    catch {
+        return [];
+    }
+}
+async function saveGrants(root, grants) {
+    const file = grantsPath(root);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await atomicWriteTextFile(file, `${JSON.stringify(grants, null, 2)}\n`);
+}
+export function hashPlanPayload(payload) {
+    return createHash("sha256").update(payload).digest("hex").slice(0, 32);
+}
+/** Stable plan hash for a file write operation (path + content). */
+export function hashFileWritePlan(action, relativePath, content) {
+    return hashPlanPayload(`${action}\n${relativePath}\n${content}`);
+}
+function normalizeResources(resources) {
+    return [...new Set(resources.map((r) => r.replace(/\\/g, "/").replace(/^\.\//, "")))].filter(Boolean);
+}
+function resourceCovers(granted, requested) {
+    if (granted === requested)
+        return true;
+    // Directory prefix grants (e.g. "src/" or "src") cover children — never bare "*".
+    const g = granted.endsWith("/") ? granted : `${granted}/`;
+    return requested.startsWith(g);
+}
+export async function issueApprovalGrant(options) {
+    const root = resolveRepoRoot(options.root);
+    const resources = normalizeResources(options.resources);
+    if (resources.length === 0) {
+        throw new Error("Approval grant requires at least one concrete resource path (wildcards alone rejected).");
+    }
+    if (resources.some((r) => r === "*" || r === "**")) {
+        throw new Error("Bare '*' resource grants are rejected — list concrete paths or directories.");
+    }
+    if (!options.planHash || options.planHash.length < 8) {
+        throw new Error("Approval grant requires a planHash binding the exact operation.");
+    }
+    const now = Date.now();
+    const grant = {
+        token: `agt_${randomBytes(24).toString("hex")}`,
+        root,
+        action: options.action,
+        resources,
+        risk: options.risk,
+        planHash: options.planHash,
+        actor: options.actor ?? "cli-human",
+        createdAt: new Date(now).toISOString(),
+        expiresAt: new Date(now + (options.ttlMs ?? 30 * 60_000)).toISOString(),
+        consumed: false,
+        scope: options.scope ?? "write+execute",
+    };
+    const grants = await loadGrants(root);
+    grants.push(grant);
+    await saveGrants(root, grants.slice(-200));
+    return grant;
+}
+/**
+ * Validate and optionally consume a grant token for a write/execute action.
+ * Bare `approved: true` without a valid token is NEVER sufficient.
+ */
+export async function consumeApprovalGrant(options) {
+    const root = resolveRepoRoot(options.root);
+    if (!options.token || typeof options.token !== "string" || !options.token.startsWith("agt_")) {
+        return {
+            ok: false,
+            reason: "Trusted approval token required (issue via CLI --approve / issueApprovalGrant). Bare approved=true is rejected.",
+        };
+    }
+    const requested = normalizeResources(options.resources);
+    if (requested.length === 0) {
+        return { ok: false, reason: "Consume requires at least one concrete resource path." };
+    }
+    if (!options.requirePlanHash) {
+        return { ok: false, reason: "Consume requires requirePlanHash bound to the exact operation." };
+    }
+    const grants = await loadGrants(root);
+    const idx = grants.findIndex((g) => g.token === options.token);
+    if (idx < 0) {
+        return { ok: false, reason: "Approval token not found for this project." };
+    }
+    const grant = grants[idx];
+    if (grant.consumed) {
+        return { ok: false, reason: "Approval token already consumed." };
+    }
+    if (Date.parse(grant.expiresAt) < Date.now()) {
+        return { ok: false, reason: "Approval token expired." };
+    }
+    if (path.resolve(grant.root) !== path.resolve(root)) {
+        return { ok: false, reason: "Approval token root mismatch." };
+    }
+    if (grant.action !== options.action) {
+        return {
+            ok: false,
+            reason: `Approval token action mismatch (granted=${grant.action}, requested=${options.action}).`,
+        };
+    }
+    if (grant.planHash !== options.requirePlanHash) {
+        return {
+            ok: false,
+            reason: "Approval token planHash mismatch — operation changed after approval.",
+        };
+    }
+    for (const res of requested) {
+        const ok = grant.resources.some((g) => resourceCovers(g, res));
+        if (!ok) {
+            return {
+                ok: false,
+                reason: `Resource not covered by approval grant: ${res}`,
+            };
+        }
+    }
+    if (options.consume !== false) {
+        grants[idx] = { ...grant, consumed: true };
+        await saveGrants(root, grants);
+    }
+    return { ok: true, reason: "Approval grant accepted", grant };
+}

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

@@ -0,0 +1,30 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface SchemaObjectFinding {
+    name: string;
+    kind: "table" | "collection" | "model" | "unknown";
+    source: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface SchemaDriftFinding {
+    name: string;
+    truth: TruthLabel;
+    note: string;
+    sources: string[];
+}
+export interface SchemaRelationFinding {
+    from: string;
+    to: string;
+    kind: "prisma-relation" | "sql-reference";
+    source: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface DatabaseDoctorReport {
+    root: string;
+    objects: SchemaObjectFinding[];
+    relations: SchemaRelationFinding[];
+    drift: SchemaDriftFinding[];
+    limitations: string[];
+}
+export declare function analyzeDatabaseSchema(rootInput: string, maxFileSizeBytes?: number): Promise<DatabaseDoctorReport>;

package/dist/product/database/doctor.js

@@ -0,0 +1,184 @@
+import path from "node:path";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
+import { readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { lineNumberAt } from "../evidence-scan.js";
+function parseLaravelMigration(content, relativePath) {
+    const out = [];
+    const createRe = /Schema::create\s*\(\s*['"]([^'"]+)['"]/g;
+    let m;
+    while ((m = createRe.exec(content)) !== null) {
+        out.push({
+            name: m[1],
+            kind: "table",
+            source: "laravel-migration",
+            truth: "VERIFIED",
+            evidence: [
+                {
+                    path: relativePath,
+                    line: lineNumberAt(content, m.index),
+                    excerpt: m[0].slice(0, 120),
+                },
+            ],
+        });
+    }
+    return out;
+}
+function parseSqlTables(content, relativePath) {
+    const out = [];
+    const re = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"']?(\w+)[`"']?/gi;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        out.push({
+            name: m[1],
+            kind: "table",
+            source: "sql",
+            truth: "VERIFIED",
+            evidence: [
+                {
+                    path: relativePath,
+                    line: lineNumberAt(content, m.index),
+                    excerpt: m[0].slice(0, 120),
+                },
+            ],
+        });
+    }
+    return out;
+}
+function parsePrismaRelations(content, relativePath) {
+    const out = [];
+    const modelBlocks = content.split(/^model\s+/gm).slice(1);
+    for (const block of modelBlocks) {
+        const modelName = /^(\w+)/.exec(block)?.[1];
+        if (!modelName)
+            continue;
+        const relRe = /^\s+(\w+)\s+\w+\??\s+@relation\s*\(\s*fields:\s*\[[^\]]+\]\s*,\s*references:\s*\[[^\]]+\]\s*,\s*[^)]*?\)/gm;
+        let m;
+        while ((m = relRe.exec(block)) !== null) {
+            const field = m[1];
+            out.push({
+                from: `${modelName}.${field}`,
+                to: "referenced-model",
+                kind: "prisma-relation",
+                source: "prisma",
+                truth: "VERIFIED",
+                evidence: [
+                    {
+                        path: relativePath,
+                        line: lineNumberAt(content, content.indexOf(m[0])),
+                        excerpt: m[0].trim().slice(0, 120),
+                    },
+                ],
+            });
+        }
+        const shorthand = /^\s+(\w+)\s+(\w+)\s+@relation/gm;
+        while ((m = shorthand.exec(block)) !== null) {
+            out.push({
+                from: `${modelName}.${m[1]}`,
+                to: m[2],
+                kind: "prisma-relation",
+                source: "prisma",
+                truth: "INFERRED",
+                evidence: [{ path: relativePath, excerpt: m[0].trim() }],
+            });
+        }
+    }
+    return out;
+}
+function parseSqlReferences(content, relativePath) {
+    const out = [];
+    const re = /FOREIGN\s+KEY\s*\(\s*[`"']?(\w+)[`"']?\s*\)\s*REFERENCES\s+[`"']?(\w+)[`"']?\s*\(\s*[`"']?(\w+)[`"']?\s*\)/gi;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        out.push({
+            from: m[1],
+            to: `${m[2]}.${m[3]}`,
+            kind: "sql-reference",
+            source: "sql",
+            truth: "VERIFIED",
+            evidence: [
+                {
+                    path: relativePath,
+                    line: lineNumberAt(content, m.index),
+                    excerpt: m[0].slice(0, 120),
+                },
+            ],
+        });
+    }
+    return out;
+}
+function parsePrismaModels(content, relativePath) {
+    const out = [];
+    const re = /^model\s+(\w+)\s*\{/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        out.push({
+            name: m[1],
+            kind: "model",
+            source: "prisma",
+            truth: "VERIFIED",
+            evidence: [
+                {
+                    path: relativePath,
+                    line: lineNumberAt(content, m.index),
+                    excerpt: m[0].trim(),
+                },
+            ],
+        });
+    }
+    return out;
+}
+function detectDrift(objects) {
+    const byName = new Map();
+    for (const o of objects) {
+        const key = o.name.toLowerCase();
+        if (!byName.has(key))
+            byName.set(key, []);
+        byName.get(key).push(o);
+    }
+    const drift = [];
+    for (const [name, group] of byName) {
+        const sources = [...new Set(group.map((g) => g.source))];
+        if (sources.length <= 1)
+            continue;
+        drift.push({
+            name,
+            truth: "UNKNOWN",
+            note: "Same object name appears in multiple schema sources; manual reconciliation required.",
+            sources,
+        });
+    }
+    return drift.sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function analyzeDatabaseSchema(rootInput, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE_BYTES) {
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const limitations = [
+        "Schema extraction is pattern-based on migrations/SQL/Prisma; runtime DB state is not inspected.",
+        "Drift is reported only when the same object name appears in disagreeing sources.",
+    ];
+    const objects = [];
+    const relations = [];
+    for (const entry of detection.discovery.files) {
+        const rel = entry.relativePath.replace(/\\/g, "/");
+        const lower = rel.toLowerCase();
+        const abs = path.join(root, rel);
+        const text = await readTextFile(abs, maxFileSizeBytes);
+        if (text === null)
+            continue;
+        if (lower.endsWith(".sql")) {
+            objects.push(...parseSqlTables(text, rel));
+            relations.push(...parseSqlReferences(text, rel));
+        }
+        else if (lower.includes("database/migrations/") && lower.endsWith(".php")) {
+            objects.push(...parseLaravelMigration(text, rel));
+        }
+        else if (lower.endsWith("schema.prisma") || lower.endsWith(".prisma")) {
+            objects.push(...parsePrismaModels(text, rel));
+            relations.push(...parsePrismaRelations(text, rel));
+        }
+    }
+    const drift = detectDrift(objects);
+    return { root, objects, relations, drift, limitations };
+}

package/dist/product/decisions/ledger.d.ts

@@ -0,0 +1,24 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface DecisionRecord {
+    id: string;
+    title: string;
+    status?: string;
+    source: "adr-file" | "ledger";
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+    recordedAt?: string;
+    bodyExcerpt?: string;
+}
+export interface DecisionLedgerResult {
+    root: string;
+    decisions: DecisionRecord[];
+    ledgerPath: string;
+    limitations: string[];
+}
+export declare function parseAdrDecisions(rootInput: string, maxFileSizeBytes?: number): Promise<DecisionRecord[]>;
+export declare function appendDecisionLedgerEntry(rootInput: string, record: Omit<DecisionRecord, "source" | "truth"> & {
+    source?: DecisionRecord["source"];
+    truth?: TruthLabel;
+}): Promise<DecisionRecord>;
+export declare function loadDecisionLedger(rootInput: string): Promise<DecisionLedgerResult>;
+export declare function resolveDecisionPath(rootInput: string, candidate: string): string;