@praneeth_54/agentdoctor 2.0.0 → 2.0.1

package/dist/platform/tokens/plan.js

@@ -1,3 +1,4 @@
+import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveRepoRoot, isPathInsideRoot } from "../../utils/path.js";
@@ -42,29 +43,47 @@ export async function planContext(options) {
                 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;
+            // Open first (O_NOFOLLOW rejects symlinks), then fstat+read from the same fd — no TOCTOU.
+            const openFlags = typeof fsConstants.O_NOFOLLOW === "number"
+                ? fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW
+                : fsConstants.O_RDONLY;
+            let handle;
+            try {
+                handle = await fs.open(absolute, openFlags);
             }
-            if (st.size > 100_000) {
-                excluded.push({ path: rel, reason: "File too large for context budget" });
-                continue;
+            catch (error) {
+                const code = error && typeof error === "object" && "code" in error
+                    ? String(error.code)
+                    : "";
+                if (code === "ELOOP") {
+                    excluded.push({ path: rel, reason: "Symlink excluded" });
+                    continue;
+                }
+                throw error;
             }
-            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;
+            try {
+                const st = await handle.stat();
+                if (st.size > 100_000) {
+                    excluded.push({ path: rel, reason: "File too large for context budget" });
+                    continue;
+                }
+                const text = await handle.readFile("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;
+            }
+            finally {
+                await handle.close();
             }
-            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" });

package/dist/platform/types.d.ts

@@ -76,6 +76,7 @@ export interface PlatformSnapshot {
 /** Persisted subset of Module H test-impact analysis. */
 export interface TestImpactSnapshot {
     gitAvailable: boolean;
+    mode: "coverage-backed" | "heuristic";
     changedFiles: string[];
     recommendedTests: Array<{
         testPath: string;
@@ -93,6 +94,14 @@ export interface TestImpactSnapshot {
     }>;
     uncoveredAreas: string[];
     skipRisk: string;
+    coverage: {
+        format: string;
+        filesWithHits: number;
+        changedCoveredLines: number;
+        changedUncoveredLines: number;
+        coverageHits: number;
+        testAttribution: "coverage-map" | "hybrid-heuristic" | "none";
+    } | null;
     limitations: string[];
 }
 export interface ReadinessCategory {

package/dist/policy/compose.d.ts

@@ -0,0 +1,34 @@
+import type { FirewallPolicyDocument } from "../platform/firewall/evaluate.js";
+export interface ComposedPolicyResult {
+    policy: FirewallPolicyDocument;
+    sources: Array<"builtin" | "repo">;
+    packName: string | null;
+    validationError?: string;
+    failClosed: boolean;
+}
+/**
+ * Merge builtin (global pack) + repo `.agentdoctor/policy.json`.
+ * Precedence: repo rules are prepended (evaluated first); repo defaultDecision /
+ * failClosed / shellAllowlist override builtin when present.
+ * Malformed repo policy → fail-closed deny-all (never silently ignore).
+ */
+export declare function composePolicy(options: {
+    root: string;
+    packName?: string;
+}): Promise<ComposedPolicyResult>;
+export declare function explainComposedDecision(options: {
+    command: string;
+    decision: string;
+    reason: string;
+    policyId?: string | null;
+    sources: Array<"builtin" | "repo">;
+    failClosed: boolean;
+}): {
+    command: string;
+    decision: string;
+    reason: string;
+    policyId: string | null;
+    sources: Array<"builtin" | "repo">;
+    failClosed: boolean;
+    meaning: string;
+};

package/dist/policy/compose.js

@@ -0,0 +1,118 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getPolicyPack, POLICY_PACKS } from "./packs.js";
+import { resolveRepoRoot } from "../utils/path.js";
+const REPO_POLICY_PATH = ".agentdoctor/policy.json";
+function denyAll(reason) {
+    return {
+        version: "2.0",
+        defaultDecision: "block",
+        failClosed: true,
+        rules: [
+            {
+                id: "compose-fail-closed",
+                decision: "block",
+                reason,
+                riskLevel: "critical",
+            },
+        ],
+    };
+}
+function isFirewallPolicyDocument(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const doc = value;
+    if (doc.version !== "2.0")
+        return false;
+    if (typeof doc.defaultDecision !== "string")
+        return false;
+    if (!Array.isArray(doc.rules))
+        return false;
+    return true;
+}
+/**
+ * Merge builtin (global pack) + repo `.agentdoctor/policy.json`.
+ * Precedence: repo rules are prepended (evaluated first); repo defaultDecision /
+ * failClosed / shellAllowlist override builtin when present.
+ * Malformed repo policy → fail-closed deny-all (never silently ignore).
+ */
+export async function composePolicy(options) {
+    const root = resolveRepoRoot(options.root);
+    const packName = options.packName ?? "baseline-safe";
+    const builtin = getPolicyPack(packName) ?? POLICY_PACKS["baseline-safe"];
+    const sources = ["builtin"];
+    const repoPath = path.join(root, REPO_POLICY_PATH);
+    let raw = null;
+    try {
+        raw = await fs.readFile(repoPath, "utf8");
+    }
+    catch {
+        raw = null;
+    }
+    if (raw === null) {
+        return {
+            policy: structuredClone(builtin),
+            sources,
+            packName,
+            failClosed: Boolean(builtin.failClosed),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            policy: denyAll("Malformed repo .agentdoctor/policy.json; fail-closed"),
+            sources: ["builtin", "repo"],
+            packName,
+            validationError: "Malformed JSON",
+            failClosed: true,
+        };
+    }
+    if (!isFirewallPolicyDocument(parsed)) {
+        return {
+            policy: denyAll("Invalid repo .agentdoctor/policy.json shape; fail-closed"),
+            sources: ["builtin", "repo"],
+            packName,
+            validationError: "Invalid policy document",
+            failClosed: true,
+        };
+    }
+    sources.push("repo");
+    const repoRules = Array.isArray(parsed.rules) ? parsed.rules : [];
+    const merged = {
+        version: "2.0",
+        defaultDecision: parsed.defaultDecision ?? builtin.defaultDecision,
+        failClosed: parsed.failClosed === true || builtin.failClosed === true,
+        ...(parsed.shellAllowlist
+            ? { shellAllowlist: parsed.shellAllowlist }
+            : builtin.shellAllowlist
+                ? { shellAllowlist: builtin.shellAllowlist }
+                : {}),
+        // Repo rules first (higher precedence), then builtin.
+        rules: [...repoRules, ...builtin.rules],
+    };
+    return {
+        policy: merged,
+        sources,
+        packName,
+        failClosed: Boolean(merged.failClosed),
+    };
+}
+export function explainComposedDecision(options) {
+    const meaning = options.decision === "allow"
+        ? "Allowlisted or matched an allow rule — still evaluate-only unless agentdoctor run executes it."
+        : options.decision === "block" || options.decision === "deny-network"
+            ? "Would be blocked by the AgentDoctor-controlled runner if executed through it."
+            : "Requires human approval or further policy before controlled execution.";
+    return {
+        command: options.command,
+        decision: options.decision,
+        reason: options.reason,
+        policyId: options.policyId ?? null,
+        sources: options.sources,
+        failClosed: options.failClosed,
+        meaning,
+    };
+}

package/dist/policy/packs.js

@@ -21,11 +21,43 @@ export const POLICY_PACKS = {
             {
                 id: "pack-block-destructive",
                 actionTypes: ["shell"],
-                match: { commandContains: ["rm -rf", "git push --force", "drop table"] },
+                // Force-push is gated as require-approval (human gate), not a hard block —
+                // builtin shell blocks already cover rm -rf; keep drop table here.
+                match: { commandContains: ["rm -rf", "drop table"] },
                 decision: "block",
                 reason: "baseline-safe: destructive operation",
                 riskLevel: "critical",
             },
+            {
+                id: "pack-force-push-approval",
+                actionTypes: ["shell"],
+                match: { commandContains: ["git push --force", "git push -f"] },
+                decision: "require-approval",
+                reason: "baseline-safe: force-push requires approval",
+                riskLevel: "high",
+            },
+            {
+                id: "pack-allow-safe-dev-paths",
+                actionTypes: ["file-modify", "file-create"],
+                match: { pathPrefix: ["src/", "tests/", "docs/"] },
+                decision: "allow",
+                reason: "baseline-safe: allowlisted development paths",
+                riskLevel: "low",
+            },
+            {
+                id: "pack-deny-prod-deploy",
+                actionTypes: ["deploy", "infra"],
+                decision: "block",
+                reason: "baseline-safe: production/infra changes require out-of-band process",
+                riskLevel: "critical",
+            },
+            {
+                id: "pack-network-default-deny",
+                actionTypes: ["network"],
+                decision: "deny-network",
+                reason: "baseline-safe: network access denied by default",
+                riskLevel: "high",
+            },
         ],
     },
     "fail-closed-ci": {

package/dist/security/paths.d.ts

@@ -0,0 +1,21 @@
+export declare class PathEscapeError extends Error {
+    readonly code = "PATH_ESCAPE";
+    constructor(message?: string);
+}
+declare function tryDecodeUri(value: string): string | null;
+/**
+ * Lexical hostility checks shared by resolve/assert helpers.
+ * Does not leak the candidate path in thrown messages.
+ */
+export declare function rejectHostilePathInput(candidate: string): void;
+/**
+ * Resolve a user-supplied path and require it to remain inside the repository root.
+ * Rejects `..`, URI-encoded traversal, null bytes, Windows-drive absolutes, and
+ * symlink realpath escapes. Error messages never echo the hostile candidate.
+ */
+export declare function resolveSafeRepoPath(rootInput: string, candidate: string): string;
+/** Assert `candidate` resolves inside `root`; throws PathEscapeError otherwise. */
+export declare function assertInsideRepo(rootInput: string, candidate: string): void;
+/** Resolve safely and return a POSIX path relative to the repo root. */
+export declare function safeRelPath(rootInput: string, absoluteOrRel: string): string;
+export { tryDecodeUri as tryDecodeUriComponent };

package/dist/security/paths.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveRepoRoot, isPathInsideRoot, toPosixRelative } from "../utils/path.js";
+export class PathEscapeError extends Error {
+    code = "PATH_ESCAPE";
+    constructor(message = "path escapes repository root") {
+        super(message);
+        this.name = "PathEscapeError";
+    }
+}
+function tryDecodeUri(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null;
+    }
+}
+function hasTraversalSegment(value) {
+    const normalized = value.replace(/\\/g, "/");
+    if (normalized.includes("\0"))
+        return true;
+    // Reject any `..` occurrence (including encoded forms after decode and `....` tricks).
+    if (normalized.includes(".."))
+        return true;
+    return false;
+}
+function isWindowsDriveAbsolute(value) {
+    return /^[A-Za-z]:[\\/]/.test(value);
+}
+/**
+ * Lexical hostility checks shared by resolve/assert helpers.
+ * Does not leak the candidate path in thrown messages.
+ */
+export function rejectHostilePathInput(candidate) {
+    if (typeof candidate !== "string" || candidate.length === 0) {
+        throw new PathEscapeError("invalid path");
+    }
+    if (candidate.includes("\0")) {
+        throw new PathEscapeError("invalid path");
+    }
+    const decoded = tryDecodeUri(candidate);
+    if (decoded === null) {
+        throw new PathEscapeError("invalid path");
+    }
+    for (const form of decoded === candidate ? [candidate] : [candidate, decoded]) {
+        if (form.includes("\0") || hasTraversalSegment(form) || isWindowsDriveAbsolute(form)) {
+            throw new PathEscapeError("path escapes repository root");
+        }
+    }
+}
+function realpathOrSelf(target) {
+    try {
+        if (fs.existsSync(target)) {
+            return fs.realpathSync(target);
+        }
+    }
+    catch {
+        // fall through
+    }
+    return target;
+}
+function realpathRoot(root) {
+    try {
+        return fs.realpathSync(root);
+    }
+    catch {
+        return path.resolve(root);
+    }
+}
+/**
+ * Resolve a user-supplied path and require it to remain inside the repository root.
+ * Rejects `..`, URI-encoded traversal, null bytes, Windows-drive absolutes, and
+ * symlink realpath escapes. Error messages never echo the hostile candidate.
+ */
+export function resolveSafeRepoPath(rootInput, candidate) {
+    const root = resolveRepoRoot(rootInput);
+    rejectHostilePathInput(candidate);
+    const decoded = tryDecodeUri(candidate) ?? candidate;
+    const primary = decoded;
+    const absolute = path.isAbsolute(primary) ? path.normalize(primary) : path.resolve(root, primary);
+    // Lexical containment against the resolved (non-realpath) root first.
+    // On macOS, /var vs /private/var must not false-reject before realpath.
+    if (!isPathInsideRoot(root, absolute) && path.resolve(absolute) !== path.resolve(root)) {
+        throw new PathEscapeError("path escapes repository root");
+    }
+    const realRoot = realpathRoot(root);
+    const realTarget = realpathOrSelf(absolute);
+    // Symlink / realpath escape check (both sides realpath'd when possible).
+    if (!isPathInsideRoot(realRoot, realTarget) && realTarget !== realRoot) {
+        throw new PathEscapeError("path escapes repository root");
+    }
+    return realTarget;
+}
+/** Assert `candidate` resolves inside `root`; throws PathEscapeError otherwise. */
+export function assertInsideRepo(rootInput, candidate) {
+    resolveSafeRepoPath(rootInput, candidate);
+}
+/** Resolve safely and return a POSIX path relative to the repo root. */
+export function safeRelPath(rootInput, absoluteOrRel) {
+    const abs = resolveSafeRepoPath(rootInput, absoluteOrRel);
+    const root = realpathRoot(resolveRepoRoot(rootInput));
+    return toPosixRelative(root, abs);
+}
+export { tryDecodeUri as tryDecodeUriComponent };

package/dist/storage/postgres.d.ts

@@ -0,0 +1,26 @@
+import type { Pool } from "pg";
+import type { StorageProvider } from "../contracts/index.js";
+/**
+ * Postgres-backed StorageProvider via the `pg` package.
+ * Only usable when a real connection string works — not claimed as always-on enterprise storage.
+ */
+export declare class PostgresStorageProvider implements StorageProvider {
+    readonly kind: "postgres";
+    private readonly pool;
+    private ready;
+    constructor(pool: Pool);
+    private ensureSchema;
+    private withClient;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    close(): Promise<void>;
+}
+/**
+ * Create Postgres storage when a connection string is provided and the server accepts it.
+ * Returns `{ error }` on failure — do not claim Postgres is supported without a working URL.
+ */
+export declare function tryCreatePostgresStorage(connectionString: string): Promise<PostgresStorageProvider | {
+    error: string;
+}>;

package/dist/storage/postgres.js

@@ -0,0 +1,90 @@
+import pg from "pg";
+const { Pool: PgPool } = pg;
+/**
+ * Postgres-backed StorageProvider via the `pg` package.
+ * Only usable when a real connection string works — not claimed as always-on enterprise storage.
+ */
+export class PostgresStorageProvider {
+    kind = "postgres";
+    pool;
+    ready;
+    constructor(pool) {
+        this.pool = pool;
+        this.ready = this.ensureSchema();
+    }
+    async ensureSchema() {
+        await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS agentdoctor_kv (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `);
+    }
+    async withClient(fn) {
+        await this.ready;
+        const client = await this.pool.connect();
+        try {
+            return await fn(client);
+        }
+        finally {
+            client.release();
+        }
+    }
+    async get(key) {
+        return this.withClient(async (client) => {
+            const result = await client.query("SELECT value FROM agentdoctor_kv WHERE key = $1", [key]);
+            return result.rows[0]?.value ?? null;
+        });
+    }
+    async set(key, value) {
+        await this.withClient(async (client) => {
+            await client.query(`INSERT INTO agentdoctor_kv (key, value) VALUES ($1, $2)
+         ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value`, [key, value]);
+        });
+    }
+    async delete(key) {
+        await this.withClient(async (client) => {
+            await client.query("DELETE FROM agentdoctor_kv WHERE key = $1", [key]);
+        });
+    }
+    async list(prefix) {
+        return this.withClient(async (client) => {
+            const result = await client.query("SELECT key FROM agentdoctor_kv WHERE key LIKE $1 ORDER BY key", [`${prefix}%`]);
+            return result.rows.map((r) => r.key);
+        });
+    }
+    async close() {
+        await this.pool.end();
+    }
+}
+/**
+ * Create Postgres storage when a connection string is provided and the server accepts it.
+ * Returns `{ error }` on failure — do not claim Postgres is supported without a working URL.
+ */
+export async function tryCreatePostgresStorage(connectionString) {
+    if (!connectionString || typeof connectionString !== "string" || !connectionString.trim()) {
+        return { error: "Postgres connection string is empty" };
+    }
+    const pool = new PgPool({
+        connectionString: connectionString.trim(),
+        max: 2,
+        idleTimeoutMillis: 5_000,
+        connectionTimeoutMillis: 5_000,
+    });
+    try {
+        const client = await pool.connect();
+        try {
+            await client.query("SELECT 1");
+        }
+        finally {
+            client.release();
+        }
+        return new PostgresStorageProvider(pool);
+    }
+    catch (error) {
+        await pool.end().catch(() => undefined);
+        return {
+            error: `Failed to connect to Postgres: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}

package/dist/storage/provider.d.ts

@@ -18,13 +18,8 @@ export declare class MemoryStorageProvider implements StorageProvider {
     delete(key: string): Promise<void>;
     list(prefix: string): Promise<string[]>;
 }
-/**
- * SQLite provider — optional. Requires better-sqlite3 when enabled.
- * Without the dependency, construction throws a documented error (no fake DB).
- */
-export declare function tryCreateSqliteStorage(_root: string): Promise<StorageProvider | {
-    error: string;
-}>;
+export { tryCreateSqliteStorage, SqliteStorageProvider } from "./sqlite.js";
+export { tryCreatePostgresStorage, PostgresStorageProvider } from "./postgres.js";
 export interface WorkspaceRecord {
     id: string;
     name: string;

package/dist/storage/provider.js

@@ -1,7 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { resolveRepoRoot, isPathInsideRoot } from "../utils/path.js";
+import { isPathInsideRoot, resolveRepoRoot } from "../utils/path.js";
 import { atomicWriteTextFile } from "../utils/fs.js";
+import { rejectHostilePathInput, PathEscapeError } from "../security/paths.js";
 export class FilesystemStorageProvider {
     kind = "filesystem";
     root;
@@ -9,13 +10,25 @@ export class FilesystemStorageProvider {
         this.root = path.join(resolveRepoRoot(rootInput), subdir);
     }
     resolveKey(key) {
-        if (key.includes("\0") || key.split(/[/\\]/).includes("..") || path.isAbsolute(key)) {
-            throw new Error(`unsafe storage key: ${key}`);
+        if (path.isAbsolute(key)) {
+            throw new Error("unsafe storage key");
+        }
+        try {
+            // Do not use resolveSafeRepoPath here — it calls resolveRepoRoot() which
+            // walks up from the storage subdir and can false-reject valid keys.
+            rejectHostilePathInput(key);
+            const target = path.resolve(this.root, key);
+            if (!isPathInsideRoot(this.root, target)) {
+                throw new PathEscapeError("storage path escape");
+            }
+            return target;
+        }
+        catch (error) {
+            if (error instanceof PathEscapeError) {
+                throw new Error("storage path escape");
+            }
+            throw new Error("unsafe storage key");
         }
-        const target = path.resolve(this.root, key);
-        if (!isPathInsideRoot(this.root, target))
-            throw new Error("storage path escape");
-        return target;
     }
     async get(key) {
         try {
@@ -83,15 +96,8 @@ export class MemoryStorageProvider {
         return [...this.map.keys()].filter((k) => k.startsWith(prefix)).sort();
     }
 }
-/**
- * SQLite provider — optional. Requires better-sqlite3 when enabled.
- * Without the dependency, construction throws a documented error (no fake DB).
- */
-export async function tryCreateSqliteStorage(_root) {
-    return {
-        error: "SQLite storage is feature-flagged and requires optional dependency better-sqlite3 (not bundled). Use filesystem provider for local-first default.",
-    };
-}
+export { tryCreateSqliteStorage, SqliteStorageProvider } from "./sqlite.js";
+export { tryCreatePostgresStorage, PostgresStorageProvider } from "./postgres.js";
 export async function saveWorkspace(storage, workspace) {
     await storage.set(`workspaces/${workspace.id}.json`, `${JSON.stringify(workspace, null, 2)}\n`);
 }

package/dist/storage/sqlite.d.ts

@@ -0,0 +1,33 @@
+import type { StorageProvider } from "../contracts/index.js";
+type DatabaseSyncCtor = new (path: string) => {
+    exec(sql: string): void;
+    prepare(sql: string): {
+        get(...params: unknown[]): unknown;
+        run(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+    };
+    close(): void;
+};
+/**
+ * SQLite-backed StorageProvider using Node's built-in `node:sqlite` (DatabaseSync).
+ * Available on Node 22+; feature-detected at runtime.
+ */
+export declare class SqliteStorageProvider implements StorageProvider {
+    readonly kind: "sqlite";
+    private readonly db;
+    private readonly dbPath;
+    constructor(db: InstanceType<DatabaseSyncCtor>, dbPath: string);
+    get path(): string;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    list(prefix: string): Promise<string[]>;
+    close(): void;
+}
+/**
+ * Create SQLite storage at `.agentdoctor/storage.sqlite` when `node:sqlite` is available.
+ */
+export declare function tryCreateSqliteStorage(rootInput: string): Promise<SqliteStorageProvider | {
+    error: string;
+}>;
+export {};