@praneeth_54/agentdoctor 2.1.0 → 3.0.1

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,36 @@
+import { type ProjectOwnershipClass } from "../../project/ownership.js";
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+/** Why a decision document is attributed to the current project. */
+export type DecisionSourceKind = "adr_file" | "decision_ledger" | "architecture_document" | "internal_note" | "unknown";
+export interface DecisionRecord {
+    id: string;
+    title: string;
+    status?: string;
+    /** Wire-compat provenance channel. */
+    source: "adr-file" | "ledger";
+    sourceKind: DecisionSourceKind;
+    truth: TruthLabel;
+    /** Explicit meaning for UI — never “architecture proven correct”. */
+    truthMeaning: string;
+    projectRoot: string;
+    ownership: ProjectOwnershipClass;
+    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" | "sourceKind" | "truthMeaning" | "projectRoot" | "ownership"> & {
+    source?: DecisionRecord["source"];
+    sourceKind?: DecisionSourceKind;
+    truth?: TruthLabel;
+    truthMeaning?: string;
+    ownership?: ProjectOwnershipClass;
+}): Promise<DecisionRecord>;
+export declare function loadDecisionLedger(rootInput: string): Promise<DecisionLedgerResult>;
+export declare function resolveDecisionPath(rootInput: string, candidate: string): string;

package/dist/product/decisions/ledger.js

@@ -0,0 +1,141 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
+import { classifyRelativePathOwnership, isProjectOwnedRelativePath, verifiedDecisionTruthMeaning, } from "../../project/ownership.js";
+import { resolveSafeRepoPath } from "../../security/paths.js";
+import { pathExists, readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+function ledgerFile(root) {
+    return path.join(resolveRepoRoot(root), ".agentdoctor", "decisions", "entries.jsonl");
+}
+/**
+ * ADR-shaped paths under the current project-owned tree only.
+ * Nested foreign trees with an adr directory segment are excluded by ownership
+ * before this runs; this still refuses internal_docs / private paths as defense in depth.
+ */
+function isAdrPath(relativePath) {
+    if (!isProjectOwnedRelativePath(relativePath))
+        return false;
+    const norm = relativePath.replace(/\\/g, "/").toLowerCase();
+    const base = path.basename(relativePath);
+    return norm.startsWith("docs/adr/") || norm.startsWith("adr/") || /^adr[-_]\d+/i.test(base);
+}
+function parseAdr(projectRoot, relativePath, content) {
+    const lines = content.split(/\r?\n/);
+    let title = "";
+    let status;
+    for (const line of lines) {
+        if (!title && /^#\s+/.test(line)) {
+            title = line.replace(/^#\s+/, "").trim();
+        }
+        const statusMatch = /^\*\*Status\*\*:\s*(.+)$/i.exec(line.trim());
+        if (statusMatch)
+            status = statusMatch[1].trim();
+    }
+    if (!title)
+        return null;
+    const id = relativePath.replace(/[^\w./-]/g, "_");
+    const ownership = classifyRelativePathOwnership(relativePath);
+    return {
+        id,
+        title,
+        ...(status !== undefined ? { status } : {}),
+        source: "adr-file",
+        sourceKind: "adr_file",
+        truth: "VERIFIED",
+        truthMeaning: verifiedDecisionTruthMeaning(),
+        projectRoot,
+        ownership,
+        evidence: [{ path: relativePath, line: 1, excerpt: title.slice(0, 120) }],
+        bodyExcerpt: content.slice(0, 400),
+    };
+}
+export async function parseAdrDecisions(rootInput, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE_BYTES) {
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const decisions = [];
+    for (const entry of detection.discovery.files) {
+        const rel = entry.relativePath.replace(/\\/g, "/");
+        if (!isAdrPath(rel) || !rel.toLowerCase().endsWith(".md"))
+            continue;
+        const text = await readTextFile(path.join(root, rel), maxFileSizeBytes);
+        if (!text)
+            continue;
+        const parsed = parseAdr(root, rel, text);
+        if (parsed)
+            decisions.push(parsed);
+    }
+    decisions.sort((a, b) => a.id.localeCompare(b.id));
+    return decisions;
+}
+export async function appendDecisionLedgerEntry(rootInput, record) {
+    const root = resolveRepoRoot(rootInput);
+    const dir = path.dirname(ledgerFile(root));
+    await fs.mkdir(dir, { recursive: true });
+    const full = {
+        ...record,
+        source: record.source ?? "ledger",
+        sourceKind: record.sourceKind ?? "decision_ledger",
+        truth: record.truth ?? "VERIFIED",
+        truthMeaning: record.truthMeaning ?? verifiedDecisionTruthMeaning(),
+        projectRoot: root,
+        ownership: record.ownership ?? "project_owned",
+        recordedAt: record.recordedAt ?? new Date().toISOString(),
+    };
+    await fs.appendFile(ledgerFile(root), `${JSON.stringify(full)}\n`, "utf8");
+    return full;
+}
+export async function loadDecisionLedger(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const limitations = [
+        "ADR parsing reads markdown titles and Status lines only.",
+        "Only project-owned trees are scanned; nested repositories and private/validation checkouts are excluded.",
+        "VERIFIED means the ADR file was found and parsed — not that the architecture decision is independently proven correct.",
+        "Ledger JSONL entries are merged with discovered ADR files (deduped by id) when present and project-owned.",
+    ];
+    const fromAdr = await parseAdrDecisions(root);
+    const fromLedger = [];
+    const file = ledgerFile(root);
+    if (await pathExists(file)) {
+        const text = await fs.readFile(file, "utf8");
+        for (const line of text.split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            try {
+                const raw = JSON.parse(line);
+                const evidencePath = raw.evidence?.[0]?.path ?? raw.id;
+                if (!isProjectOwnedRelativePath(String(evidencePath)) &&
+                    !isProjectOwnedRelativePath(String(raw.id))) {
+                    limitations.push(`Skipped non-owned ledger entry: ${raw.id}`);
+                    continue;
+                }
+                fromLedger.push({
+                    ...raw,
+                    source: raw.source ?? "ledger",
+                    sourceKind: raw.sourceKind ?? "decision_ledger",
+                    truth: raw.truth ?? "VERIFIED",
+                    truthMeaning: raw.truthMeaning ?? verifiedDecisionTruthMeaning(),
+                    projectRoot: raw.projectRoot ?? root,
+                    ownership: raw.ownership ?? classifyRelativePathOwnership(String(evidencePath)),
+                });
+            }
+            catch {
+                limitations.push("Skipped malformed decision ledger line.");
+            }
+        }
+    }
+    const byId = new Map();
+    for (const d of [...fromAdr, ...fromLedger]) {
+        byId.set(d.id, d);
+    }
+    return {
+        root,
+        decisions: [...byId.values()].sort((a, b) => a.title.localeCompare(b.title)),
+        ledgerPath: ledgerFile(root),
+        limitations,
+    };
+}
+export function resolveDecisionPath(rootInput, candidate) {
+    return resolveSafeRepoPath(rootInput, candidate);
+}

package/dist/product/deps/analyze.d.ts

@@ -0,0 +1,46 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+import { type LockfilePackageVersion } from "./lockfiles.js";
+export interface DirectDependency {
+    name: string;
+    versionRange: string;
+    packageJsonPath: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface DuplicatePackageName {
+    name: string;
+    paths: string[];
+    truth: TruthLabel;
+}
+export interface UpgradeImpactHint {
+    dependency: string;
+    importers: string[];
+    truth: TruthLabel;
+}
+export interface DependencyAnalysisReport {
+    root: string;
+    monorepo: string;
+    directDependencies: DirectDependency[];
+    duplicateNames: DuplicatePackageName[];
+    lockfilesPresent: string[];
+    lockfilesParsed: string[];
+    transitiveFromLockfile: LockfilePackageVersion[];
+    upgradeImpact: UpgradeImpactHint[];
+    limitations: string[];
+}
+export declare function analyzeDependencies(rootInput: string, options?: {
+    graph?: {
+        nodes: Array<{
+            id: string;
+            kind: string;
+            label: string;
+            path?: string;
+        }>;
+        edges: Array<{
+            from: string;
+            to: string;
+            kind: string;
+        }>;
+    };
+    maxFileSizeBytes?: number;
+}): Promise<DependencyAnalysisReport>;