@praneeth_54/agentdoctor 1.1.1 → 2.0.0

package/dist/platform/time-machine/compare.js

@@ -0,0 +1,62 @@
+import { spawnSync } from "node:child_process";
+import { resolveRepoRoot } from "../../utils/path.js";
+function git(root, args) {
+    const r = spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 });
+    return { ok: r.status === 0, out: typeof r.stdout === "string" ? r.stdout : "" };
+}
+/**
+ * Module J — Repository time machine (git-backed).
+ */
+export async function compareCommits(options) {
+    const root = resolveRepoRoot(options.root);
+    const left = options.left.trim();
+    const right = options.right.trim();
+    if (!isSafeGitRef(left) || !isSafeGitRef(right)) {
+        return {
+            root,
+            left,
+            right,
+            changedFiles: [],
+            summary: "Invalid git ref",
+            limitations: ["Refs must be non-empty and must not start with '-'"],
+        };
+    }
+    const probe = git(root, ["rev-parse", "--is-inside-work-tree"]);
+    if (!probe.ok || probe.out.trim() !== "true") {
+        return {
+            root,
+            left,
+            right,
+            changedFiles: [],
+            summary: "Git not available",
+            limitations: ["Requires a git repository"],
+        };
+    }
+    const diff = git(root, ["diff", "--name-only", `${left}...${right}`]);
+    const files = diff.ok
+        ? diff.out
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .filter(Boolean)
+        : [];
+    return {
+        root,
+        left,
+        right,
+        changedFiles: files,
+        summary: `${files.length} path(s) differ between ${left} and ${right}`,
+        limitations: [
+            "Architecture/risk trend overlays are extension points; this MVP lists path diffs",
+        ],
+    };
+}
+function isSafeGitRef(ref) {
+    return Boolean(ref) && !ref.includes("\0") && !ref.startsWith("-") && !/[\r\n]/.test(ref);
+}
+export async function listRecentCommits(rootInput, limit = 20) {
+    const root = resolveRepoRoot(rootInput);
+    const log = git(root, ["log", `-${limit}`, "--pretty=format:%H %s"]);
+    if (!log.ok)
+        return [];
+    return log.out.split(/\r?\n/).filter(Boolean);
+}

package/dist/platform/tokens/plan.d.ts

@@ -0,0 +1,28 @@
+import type { RepositoryGraph } from "../types.js";
+export interface ContextPlan {
+    root: string;
+    budgetTokens: number;
+    estimatedTokens: number;
+    selected: Array<{
+        path: string;
+        tokens: number;
+        relevance: number;
+        reason: string;
+    }>;
+    excluded: Array<{
+        path: string;
+        reason: string;
+    }>;
+    recommendations: string[];
+    limitations: string[];
+}
+/**
+ * Module L — Token / context optimization.
+ * Never includes secret-like paths.
+ */
+export declare function planContext(options: {
+    root: string;
+    graph: RepositoryGraph;
+    query: string;
+    budgetTokens?: number;
+}): Promise<ContextPlan>;

package/dist/platform/tokens/plan.js

@@ -0,0 +1,89 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolveRepoRoot, isPathInsideRoot } from "../../utils/path.js";
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+const SECRETISH = /\.env|id_rsa|credentials|secrets\//i;
+/**
+ * Module L — Token / context optimization.
+ * Never includes secret-like paths.
+ */
+export async function planContext(options) {
+    const root = resolveRepoRoot(options.root);
+    const budget = options.budgetTokens ?? 8_000;
+    const q = options.query.toLowerCase();
+    const selected = [];
+    const excluded = [];
+    let used = 0;
+    const candidates = options.graph.nodes
+        .filter((n) => (n.kind === "file" || n.kind === "doc" || n.kind === "config") && n.path)
+        .map((n) => n.path)
+        .sort();
+    for (const rel of candidates) {
+        if (rel.includes("\0") || path.isAbsolute(rel) || rel.split(/[/\\]/).includes("..")) {
+            excluded.push({ path: rel, reason: "Unsafe path rejected" });
+            continue;
+        }
+        if (SECRETISH.test(rel)) {
+            excluded.push({ path: rel, reason: "Secret-like path excluded" });
+            continue;
+        }
+        const relevance = (rel.toLowerCase().includes(q) ? 0.6 : 0) +
+            (/\.(ts|tsx|md)$/i.test(rel) ? 0.2 : 0.05) +
+            (rel.startsWith("src/") ? 0.15 : 0);
+        if (relevance < 0.25) {
+            excluded.push({ path: rel, reason: "Low relevance to query" });
+            continue;
+        }
+        try {
+            const absolute = path.resolve(root, rel);
+            if (!isPathInsideRoot(root, absolute)) {
+                excluded.push({ path: rel, reason: "Path escapes repository root" });
+                continue;
+            }
+            const st = await fs.stat(absolute);
+            const lst = await fs.lstat(absolute);
+            if (lst.isSymbolicLink()) {
+                excluded.push({ path: rel, reason: "Symlink excluded" });
+                continue;
+            }
+            if (st.size > 100_000) {
+                excluded.push({ path: rel, reason: "File too large for context budget" });
+                continue;
+            }
+            const text = await fs.readFile(absolute, "utf8");
+            const tokens = estimateTokens(text);
+            if (used + tokens > budget) {
+                excluded.push({ path: rel, reason: "Would exceed token budget" });
+                continue;
+            }
+            selected.push({
+                path: rel,
+                tokens,
+                relevance,
+                reason: relevance >= 0.6 ? "Path matches query" : "Likely relevant source/doc",
+            });
+            used += tokens;
+        }
+        catch {
+            excluded.push({ path: rel, reason: "Unreadable" });
+        }
+    }
+    selected.sort((a, b) => b.relevance - a.relevance || a.path.localeCompare(b.path));
+    return {
+        root,
+        budgetTokens: budget,
+        estimatedTokens: used,
+        selected,
+        excluded: excluded.slice(0, 200),
+        recommendations: [
+            used > budget * 0.9 ? "Increase budget or narrow query" : "Budget headroom available",
+            "Prefer Project Brain claims over dumping entire directories",
+        ],
+        limitations: [
+            "Token estimate is chars/4 heuristic",
+            "Relevance is lexical, not embedding-based",
+        ],
+    };
+}

package/dist/platform/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * AgentDoctor 2.0 platform contracts.
+ * Local-first: no mandatory cloud, DB, or API keys.
+ */
+export type EvidenceKind = "verified" | "inferred" | "unknown";
+export interface EvidenceRef {
+    kind: EvidenceKind;
+    path?: string;
+    detail: string;
+    line?: number;
+}
+export type PlatformSeverity = "critical" | "high" | "medium" | "low" | "info";
+export interface PlatformFinding {
+    id: string;
+    module: string;
+    severity: PlatformSeverity;
+    title: string;
+    message: string;
+    recommendation: string;
+    confidence: number;
+    evidence: EvidenceRef[];
+    falsePositiveWarning?: string;
+}
+export interface GraphNode {
+    id: string;
+    kind: "file" | "directory" | "function" | "class" | "module" | "api" | "test" | "dependency" | "doc" | "config" | "service" | "commit" | "owner";
+    label: string;
+    path?: string;
+    meta?: Record<string, string | number | boolean>;
+}
+export interface GraphEdge {
+    id: string;
+    from: string;
+    to: string;
+    kind: string;
+    evidence: EvidenceKind;
+}
+export interface RepositoryGraph {
+    root: string;
+    generatedAt: string;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    limitations: string[];
+}
+export type FirewallDecision = "allow" | "block" | "require-approval" | "sandbox-only" | "deny-network" | "deny-secrets";
+export type AgentActionType = "shell" | "file-create" | "file-modify" | "file-delete" | "git" | "package-install" | "database" | "network" | "docker" | "infra" | "secret-access" | "config-change" | "deploy";
+export interface AgentActionRequest {
+    actionId: string;
+    agentId: string;
+    userId?: string;
+    timestamp: string;
+    type: AgentActionType;
+    params: Record<string, string>;
+    repositoryRoot: string;
+}
+export interface FirewallVerdict {
+    actionId: string;
+    decision: FirewallDecision;
+    reason: string;
+    riskLevel: PlatformSeverity;
+    policyId?: string;
+    approvalStatus: "not-required" | "pending" | "approved" | "denied";
+    executionResult: "not-executed";
+}
+export type LocalRole = "admin" | "developer" | "reviewer" | "auditor" | "readonly";
+export interface PlatformSnapshot {
+    version: "2.0";
+    root: string;
+    generatedAt: string;
+    graph: RepositoryGraph;
+    findings: PlatformFinding[];
+    readiness: ReadinessReport;
+    testImpact?: TestImpactSnapshot;
+    limitations: string[];
+}
+/** Persisted subset of Module H test-impact analysis. */
+export interface TestImpactSnapshot {
+    gitAvailable: boolean;
+    changedFiles: string[];
+    recommendedTests: Array<{
+        testPath: string;
+        reason: string;
+        confidence: number;
+        evidence: EvidenceKind;
+        exists: boolean;
+        relatedModules: string[];
+    }>;
+    relatedModules: string[];
+    missingTestWarnings: Array<{
+        sourceFile: string;
+        message: string;
+        relatedModules: string[];
+    }>;
+    uncoveredAreas: string[];
+    skipRisk: string;
+    limitations: string[];
+}
+export interface ReadinessCategory {
+    id: string;
+    title: string;
+    score: number;
+    evidence: EvidenceRef[];
+    gaps: string[];
+    recommendations: string[];
+}
+export interface ReadinessReport {
+    root: string;
+    categories: ReadinessCategory[];
+    overallNote: string;
+    limitations: string[];
+}

package/dist/platform/types.js

@@ -0,0 +1,5 @@
+/**
+ * AgentDoctor 2.0 platform contracts.
+ * Local-first: no mandatory cloud, DB, or API keys.
+ */
+export {};

package/dist/plugins/runtime.d.ts

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

package/dist/plugins/runtime.js

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

package/dist/plugins/sdk.d.ts

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

package/dist/plugins/sdk.js

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

package/dist/policy/packs.d.ts

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

package/dist/policy/packs.js

@@ -0,0 +1,59 @@
+/**
+ * Named policy packs for local evaluation. Packs are declarative documents —
+ * loading a pack does not enable runtime interception unless an AgentDoctor
+ * enforcement boundary (controlled runner / CI wrapper) is used.
+ */
+export const POLICY_PACKS = {
+    "baseline-safe": {
+        version: "2.0",
+        defaultDecision: "require-approval",
+        failClosed: false,
+        shellAllowlist: ["npm test", "npm run test", "vitest", "eslint", "tsc", "prettier"],
+        rules: [
+            {
+                id: "pack-block-secrets",
+                actionTypes: ["file-modify", "file-delete", "secret-access"],
+                match: { pathContains: [".env", "id_rsa", "credentials", ".pem"] },
+                decision: "block",
+                reason: "baseline-safe: secret-sensitive path",
+                riskLevel: "critical",
+            },
+            {
+                id: "pack-block-destructive",
+                actionTypes: ["shell"],
+                match: { commandContains: ["rm -rf", "git push --force", "drop table"] },
+                decision: "block",
+                reason: "baseline-safe: destructive operation",
+                riskLevel: "critical",
+            },
+        ],
+    },
+    "fail-closed-ci": {
+        version: "2.0",
+        defaultDecision: "block",
+        failClosed: true,
+        shellAllowlist: ["npm test", "npm run verify", "vitest"],
+        rules: [
+            {
+                id: "ci-deny-network",
+                actionTypes: ["network"],
+                decision: "block",
+                reason: "fail-closed-ci: network blocked",
+                riskLevel: "high",
+            },
+            {
+                id: "ci-deny-deploy",
+                actionTypes: ["deploy", "infra"],
+                decision: "block",
+                reason: "fail-closed-ci: deploy blocked",
+                riskLevel: "critical",
+            },
+        ],
+    },
+};
+export function listPolicyPacks() {
+    return Object.keys(POLICY_PACKS);
+}
+export function getPolicyPack(name) {
+    return POLICY_PACKS[name] ?? null;
+}