@praneeth_54/agentdoctor 3.0.1 → 3.0.3

package/dist/cli/ask-progress.js

@@ -0,0 +1,85 @@
+import { colors, symbolFail, symbolOk } from "../utils/colors.js";
+const STAGE_LABELS = {
+    understand: "Understanding question",
+    search: "Searching project knowledge",
+    retrieve: "Retrieving relevant evidence",
+    verify: "Verifying evidence",
+    prepare: "Preparing answer",
+};
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/**
+ * Human-readable ask progress. Stages must be driven by real operations.
+ * Animation uses setInterval only for frame updates while work is in flight —
+ * never to invent delay.
+ */
+export function createAskProgress(options = {}) {
+    const enabled = options.enabled !== false;
+    const stream = options.stream ?? process.stderr;
+    const tty = options.isTTY ??
+        Boolean(stream && typeof stream === "object" && "isTTY" in stream && stream.isTTY);
+    let frame = 0;
+    let timer;
+    let activeLabel;
+    let stopped = false;
+    const clearLine = () => {
+        if (!tty || !enabled)
+            return;
+        stream.write("\r\x1b[K");
+    };
+    const stopSpin = () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+        clearLine();
+    };
+    const renderSpin = () => {
+        if (!tty || !enabled || !activeLabel || stopped)
+            return;
+        const glyph = SPINNER_FRAMES[frame % SPINNER_FRAMES.length];
+        frame += 1;
+        stream.write(`\r${colors.cyan(glyph)} ${activeLabel}...`);
+    };
+    const writeDone = (ok, label, detail) => {
+        if (!enabled || stopped)
+            return;
+        const mark = ok ? symbolOk() : symbolFail();
+        const suffix = detail ? colors.dim(` — ${detail}`) : "";
+        stream.write(`${mark} ${label}${suffix}\n`);
+    };
+    return {
+        stage(id, state, detail) {
+            if (!enabled || stopped)
+                return;
+            const label = STAGE_LABELS[id];
+            if (state === "start") {
+                stopSpin();
+                activeLabel = label;
+                if (tty) {
+                    frame = 0;
+                    renderSpin();
+                    timer = setInterval(renderSpin, 80);
+                    timer.unref?.();
+                }
+                else {
+                    stream.write(`${label}...\n`);
+                }
+                return;
+            }
+            stopSpin();
+            activeLabel = undefined;
+            writeDone(state === "ok", state === "ok" && id === "prepare" ? "Answer ready" : label, detail);
+        },
+        stop() {
+            stopSpin();
+            activeLabel = undefined;
+            stopped = true;
+        },
+    };
+}
+export function silentAskProgress() {
+    return {
+        stage() { },
+        stop() { },
+    };
+}

package/dist/cli/commands/chat.d.ts

@@ -5,6 +5,12 @@ export declare function runAskCommand(options: {
     json?: boolean;
     /** Test-only: force mock provider */
     useMock?: boolean;
+    /** Test override: force progress enabled/disabled */
+    progressEnabled?: boolean;
+    /** Test override: progress stream */
+    progressStream?: NodeJS.WritableStream;
+    /** Test override: treat progress stream as TTY */
+    progressIsTTY?: boolean;
 }): Promise<ExitCode>;
 export declare function runChatCommand(options: {
     root?: string;

package/dist/cli/commands/chat.js

@@ -5,6 +5,7 @@ import { MockModelProvider, createModelProvider, loadAiConfig } from "../../ai/i
 import { EXIT_CODES } from "../../types/index.js";
 import { resolveCliProjectRoot } from "../safe-root.js";
 import { colors } from "../../utils/colors.js";
+import { createAskProgress } from "../ask-progress.js";
 function printBanner(options) {
     const lines = [
         "",
@@ -58,13 +59,21 @@ export async function runAskCommand(options) {
     }
     const root = gated.root;
     const provider = options.useMock ? new MockModelProvider() : createModelProvider(loadAiConfig());
+    const progressEnabled = options.progressEnabled ?? !options.json;
+    const progress = createAskProgress({
+        enabled: progressEnabled,
+        ...(options.progressStream ? { stream: options.progressStream } : {}),
+        ...(options.progressIsTTY !== undefined ? { isTTY: options.progressIsTTY } : {}),
+    });
     const chat = new ChatService({
         root,
         provider,
         persistAudit: !options.useMock,
+        progress,
     });
     try {
         const response = await chat.ask(options.question);
+        progress.stop();
         if (options.json) {
             process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
         }
@@ -78,7 +87,14 @@ export async function runAskCommand(options) {
         }
         return EXIT_CODES.SUCCESS;
     }
+    catch (error) {
+        progress.stop();
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`AgentDoctor error:\n${message}`);
+        return EXIT_CODES.INTERNAL_ERROR;
+    }
     finally {
+        progress.stop();
         await chat.end();
     }
 }

package/dist/cli/commands/start.js

@@ -2,16 +2,21 @@ import { EXIT_CODES } from "../../types/index.js";
 import { initBrainStore, rebuildBrain, getBrainStatus } from "../../core/brain-cli/service.js";
 import { discoverProjectRoots } from "../../product/discovery/roots.js";
 import { buildProjectDna, persistProjectDna } from "../../product/dna/build.js";
-import { resolveRepoRoot } from "../../utils/path.js";
 import { resolveCliProjectRoot } from "../safe-root.js";
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 export async function runStartCommand(options) {
     const prefer = options.select ?? options.root;
+    // Fail closed before discovery walks anything (home/Desktop refusal must be instant).
+    const gated = await resolveCliProjectRoot(prefer);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
     const discovery = await discoverProjectRoots({
-        cwd: prefer ? resolveRepoRoot(prefer) : process.cwd(),
-        ...(prefer ? { prefer: resolveRepoRoot(prefer) } : {}),
+        cwd: gated.root,
+        prefer: gated.root,
         ...(options.maxEntries !== undefined ? { maxEntries: options.maxEntries } : {}),
         autoSelect: !options.listOnly,
     });
@@ -26,13 +31,16 @@ export async function runStartCommand(options) {
         }
         process.stdout.write("Project candidates:\n");
         if (discovery.candidates.length === 0) {
-            process.stdout.write("  (none found — navigate into a project or pass a path)\n");
+            process.stdout.write(`  (none found under ${gated.root})\n`);
+            process.stdout.write("  Tip: open a project directory that contains source code or a manifest (package.json, composer.json, pyproject.toml, .git, …),\n");
+            process.stdout.write(`  or run: agentdoctor start ${gated.root}\n`);
+            process.stdout.write("  Related: agentdoctor dna .   # inspect what DNA sees in this folder\n");
             return EXIT_CODES.USAGE_ERROR;
         }
         for (const [i, c] of discovery.candidates.entries()) {
             process.stdout.write(`  [${i + 1}] ${c.root}\n      score=${c.score} markers=${c.markers.join(", ")} (${c.reason})\n`);
         }
-        process.stdout.write("\nRe-run with --select <path> to initialize that project.\n");
+        process.stdout.write("\nMultiple projects detected — re-run with --select <path> (or pass an explicit path).\n");
         return EXIT_CODES.SUCCESS;
     }
     const root = discovery.selected.root;
@@ -50,8 +58,9 @@ export async function runStartCommand(options) {
         printJson(payload);
     }
     else {
+        process.stdout.write(`✓ Project detected: ${dna.name}\n`);
+        process.stdout.write(`  Root: ${root}\n`);
         process.stdout.write(`AgentDoctor start\n`);
-        process.stdout.write(`  root: ${root}\n`);
         process.stdout.write(`  fingerprint: ${dna.fingerprint}\n`);
         process.stdout.write(`  type: ${dna.projectType}\n`);
         process.stdout.write(`  languages: ${dna.languages.join(", ") || "(none)"}\n`);

package/dist/cli/program.js

@@ -1255,7 +1255,8 @@ export function createProgram() {
         .argument("<question>", "Question about the project")
         .argument("[path]", "Repository path (default: current directory)")
         .option("--json", "Emit JSON response", false)
-        .action(async (question, pathArg, options) => {
+        .action(async (question, pathArg, _options, command) => {
+        const options = command.optsWithGlobals();
         process.exitCode = await runAskCommand({
             question,
             root: resolveTargetArgument(pathArg),

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 import type { AgentId } from "./types/index.js";
-export declare const PACKAGE_VERSION = "3.0.1";
+export declare const PACKAGE_VERSION = "3.0.3";
 export declare const DEFAULT_MAX_FILE_SIZE_BYTES: number;
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export declare const DEFAULT_IGNORE_DIRECTORIES: Set<string>;

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "3.0.1";
+export const PACKAGE_VERSION = "3.0.3";
 export const DEFAULT_MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024; // 2 MiB
 /** Directories skipped during normal discovery (unless a rule needs them later). */
 export const DEFAULT_IGNORE_DIRECTORIES = new Set([

package/dist/core/understanding/brain/storage/store.js

@@ -128,7 +128,6 @@ export class LocalBrainStore {
         await fs.mkdir(path.join(this.root, "deltas"), { recursive: true });
     }
     async readMeta() {
-        await this.ensureRoot();
         try {
             const raw = await fs.readFile(this.metaPath(), "utf8");
             const parsed = JSON.parse(raw);

package/dist/dashboard/server.js

@@ -20,7 +20,6 @@ import { listKnowledge } from "../knowledge/store.js";
 import { CONTRACTS_VERSION } from "../contracts/index.js";
 import { collectOpsHealth } from "../ops/health.js";
 import { listPolicyPacks } from "../policy/packs.js";
-import { sanitizeForOutput } from "../utils/path.js";
 import { createModelProvider, loadAiConfig } from "../ai/index.js";
 import { ChatService } from "../agent/chat/service.js";
 import { formatChatResponseForCli } from "../agent/chat/response.js";
@@ -43,11 +42,15 @@ import { analyzeFeatureIntelligence } from "../product/features/intelligence.js"
 import { buildSoftwareEvolutionTimeline } from "../product/evolution/timeline.js";
 import { queryMemory } from "../product/memory/institutional.js";
 import { loadDecisionLedger } from "../product/decisions/ledger.js";
+import { ProjectOwnershipError } from "../project/ownership.js";
+import { PathEscapeError } from "../security/paths.js";
 import { htmlPage } from "./page.js";
-function safeJsonError(error) {
-    const raw = error instanceof Error ? error.message : String(error);
-    const { text } = redactSecrets(sanitizeForOutput(raw));
-    return text.slice(0, 240);
+/** HTTP-safe client error — never returns Error.message/stack (CodeQL js/stack-trace-exposure). */
+function clientErrorMessage(error) {
+    if (error instanceof ProjectOwnershipError || error instanceof PathEscapeError) {
+        return "path outside project ownership";
+    }
+    return "internal error";
 }
 function pathnameLooksHostile(pathname) {
     const lower = pathname.toLowerCase();
@@ -386,11 +389,9 @@ export async function startDashboardServer(options) {
                     sendJson(res, 200, await analyzeWhatIf(root, target));
                 }
                 catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    const ownershipDenied = /ownership|escapes|path escape|PROJECT_OWNERSHIP/i.test(message) ||
-                        (error instanceof Error && error.name === "ProjectOwnershipError");
+                    const ownershipDenied = error instanceof ProjectOwnershipError || error instanceof PathEscapeError;
                     sendJson(res, ownershipDenied ? 400 : 500, {
-                        error: ownershipDenied ? "path outside project ownership" : message,
+                        error: ownershipDenied ? "path outside project ownership" : "what-if analysis failed",
                     });
                 }
                 return;
@@ -439,7 +440,7 @@ export async function startDashboardServer(options) {
             sendJson(res, 404, { error: "not found" });
         }
         catch (error) {
-            sendJson(res, 500, { error: safeJsonError(error) });
+            sendJson(res, 500, { error: clientErrorMessage(error) });
         }
     });
     await new Promise((resolve, reject) => {

package/dist/product/discovery/roots.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { DEFAULT_IGNORE_DIRECTORIES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
 import { isDirectory, pathExists } from "../../utils/fs.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 /** Markers that strongly suggest a software project root. */
@@ -19,6 +20,8 @@ const PROJECT_MARKERS = [
     "pubspec.yaml",
     ".git",
 ];
+/** Directory basenames that must never be treated as a project root candidate. */
+const FORBIDDEN_ROOT_BASENAMES = new Set([".private", "agentdoctoros"]);
 const SUSPICIOUS_DIR_NAMES = new Set([
     "desktop",
     "downloads",
@@ -32,9 +35,19 @@ const SUSPICIOUS_DIR_NAMES = new Set([
 function normalizeHome(home) {
     return path.resolve(home);
 }
+function pathsEqual(a, b) {
+    const left = path.resolve(a);
+    const right = path.resolve(b);
+    return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
 function isUnderHomeSubtree(abs, home, leaf) {
     const target = path.resolve(home, leaf);
     const resolved = path.resolve(abs);
+    if (process.platform === "win32") {
+        const t = target.toLowerCase();
+        const r = resolved.toLowerCase();
+        return r === t || r.startsWith(t + "\\");
+    }
     return resolved === target || resolved.startsWith(target + path.sep);
 }
 async function countEntriesShallow(dir, budget) {
@@ -92,7 +105,7 @@ export function classifyBroadUserScanRoot(cwdInput, homeInput) {
     const cwd = path.resolve(cwdInput);
     const home = normalizeHome(homeInput ?? os.homedir());
     const baselower = path.basename(cwd).toLowerCase();
-    if (cwd === home ||
+    if (pathsEqual(cwd, home) ||
         SUSPICIOUS_DIR_NAMES.has(baselower) ||
         isUnderHomeSubtree(cwd, home, "Desktop") ||
         isUnderHomeSubtree(cwd, home, "Downloads") ||
@@ -113,12 +126,11 @@ export async function discoverProjectRoots(options = {}) {
     const home = normalizeHome(os.homedir());
     const maxEntries = options.maxEntries ?? 25_000;
     const limitations = [
-        "Discovery uses shallow marker probes and bounded entry counts — not a full repository index.",
-        "Candidates are VERIFIED only when marker files/directories exist on disk.",
+        "Discovery uses shallow marker probes, bounded entry counts, and detectProject for cwd/prefer when classic markers are absent.",
+        "Candidates are VERIFIED only when marker files exist or detectProject finds languages/source under that root.",
     ];
     const broad = classifyBroadUserScanRoot(cwd, home);
     if (broad.blocked) {
-        const estimatedEntries = await countEntriesShallow(cwd, Math.min(maxEntries, 5_000));
         return {
             cwd,
             home,
@@ -126,7 +138,8 @@ export async function discoverProjectRoots(options = {}) {
             selected: null,
             blocked: true,
             blockReason: broad.reason,
-            estimatedEntries,
+            // Do not walk the tree — counting home/Desktop can hang CI (esp. Windows).
+            estimatedEntries: 0,
             limitations,
         };
     }
@@ -145,13 +158,19 @@ export async function discoverProjectRoots(options = {}) {
     }
     const candidates = [];
     const seen = new Set();
+    function rejectForbiddenRoot(resolved) {
+        const base = path.basename(resolved).toLowerCase();
+        return FORBIDDEN_ROOT_BASENAMES.has(base);
+    }
     async function consider(dir, reason) {
         const resolved = path.resolve(dir);
         if (seen.has(resolved))
             return;
         if (!(await isDirectory(resolved)))
             return;
-        if (resolved === home)
+        if (pathsEqual(resolved, home))
+            return;
+        if (rejectForbiddenRoot(resolved))
             return;
         const markers = await markersAt(resolved);
         if (markers.length === 0)
@@ -165,6 +184,46 @@ export async function discoverProjectRoots(options = {}) {
             reason,
         });
     }
+    /**
+     * When classic manifests/.git are absent, reuse the same detectProject path as DNA
+     * so `start` agrees with `dna` for valid software trees (e.g. language-only roots).
+     * Only applied to prefer/cwd — never to unbounded parent/child walks.
+     */
+    async function considerDetectProject(dir, reason) {
+        const resolved = path.resolve(dir);
+        if (seen.has(resolved))
+            return;
+        if (!(await isDirectory(resolved)))
+            return;
+        if (pathsEqual(resolved, home))
+            return;
+        if (rejectForbiddenRoot(resolved))
+            return;
+        if (classifyBroadUserScanRoot(resolved, home).blocked)
+            return;
+        let detection;
+        try {
+            detection = await detectProject(resolved);
+        }
+        catch {
+            return;
+        }
+        // detectProject returns ["unknown"] for empty trees — that is not a project signal.
+        const languages = detection.repository.languages.filter((l) => l !== "unknown");
+        const sourceFiles = detection.discovery.files.filter((f) => /\.(ts|tsx|js|jsx|mjs|cjs|py|php|go|rs|java|kt|kts|dart|rb|cs)$/i.test(f.relativePath)).length;
+        if (languages.length === 0 && sourceFiles === 0)
+            return;
+        seen.add(resolved);
+        const markers = languages.length > 0 ? languages.map((l) => `lang:${l}`) : [`source-files:${sourceFiles}`];
+        candidates.push({
+            root: resolved,
+            // Match strong marker score so a lone detectProject hit auto-selects like package.json.
+            score: languages.length > 0 ? 5 : 3,
+            markers,
+            truth: "VERIFIED",
+            reason,
+        });
+    }
     if (options.prefer) {
         await consider(options.prefer, "explicit prefer path");
     }
@@ -172,7 +231,7 @@ export async function discoverProjectRoots(options = {}) {
     // Walk up a few parents looking for markers (bounded).
     let parent = path.dirname(cwd);
     for (let i = 0; i < 4; i++) {
-        if (parent === home || parent === path.dirname(parent))
+        if (pathsEqual(parent, home) || parent === path.dirname(parent))
             break;
         await consider(parent, "parent directory with project markers");
         parent = path.dirname(parent);
@@ -185,16 +244,63 @@ export async function discoverProjectRoots(options = {}) {
                 continue;
             if (DEFAULT_IGNORE_DIRECTORIES.has(entry.name) || entry.name.startsWith("."))
                 continue;
+            if (FORBIDDEN_ROOT_BASENAMES.has(entry.name.toLowerCase()))
+                continue;
             await consider(path.join(cwd, entry.name), "child directory with project markers");
         }
     }
     catch {
         limitations.push("Could not list child directories for candidate discovery.");
     }
+    // detectProject fallback (same engine as DNA) for prefer/cwd when no classic markers
+    // apply to that path AND no ancestor marker candidate already covers it (nested Case B).
+    // Also skip when child classic-marker projects already exist — otherwise detectProject
+    // would absorb sibling packages into a multi-project parent (start always passes prefer=cwd).
+    const preferAbs = options.prefer ? path.resolve(options.prefer) : null;
+    function ancestorMarkerCovers(target) {
+        return candidates.find((c) => {
+            if (pathsEqual(c.root, target))
+                return true;
+            const rootWithSep = c.root.endsWith(path.sep) ? c.root : c.root + path.sep;
+            if (process.platform === "win32") {
+                return target.toLowerCase().startsWith(rootWithSep.toLowerCase());
+            }
+            return target.startsWith(rootWithSep);
+        });
+    }
+    function descendantMarkerCandidates(target) {
+        const targetWithSep = target.endsWith(path.sep) ? target : target + path.sep;
+        return candidates.filter((c) => {
+            if (pathsEqual(c.root, target))
+                return false;
+            if (process.platform === "win32") {
+                return c.root.toLowerCase().startsWith(targetWithSep.toLowerCase());
+            }
+            return c.root.startsWith(targetWithSep);
+        });
+    }
+    if (preferAbs) {
+        // Skip detectProject absorption when 2+ classic child projects exist (multi-project
+        // parent). A single nested foreign repo must not block prefer's own language tree.
+        if (!ancestorMarkerCovers(preferAbs) && descendantMarkerCandidates(preferAbs).length < 2) {
+            await considerDetectProject(preferAbs, "explicit prefer path (detectProject)");
+        }
+    }
+    else if (candidates.length === 0) {
+        await considerDetectProject(cwd, "current working directory (detectProject)");
+    }
     candidates.sort((a, b) => b.score - a.score || a.root.localeCompare(b.root));
     let selected = null;
-    if (options.prefer) {
-        selected = candidates.find((c) => c.root === path.resolve(options.prefer)) ?? null;
+    if (preferAbs) {
+        const exact = candidates.find((c) => pathsEqual(c.root, preferAbs));
+        const covered = ancestorMarkerCovers(preferAbs);
+        // Nested dir under a marker project → select the marker root, not the nested leaf.
+        if (covered && !pathsEqual(covered.root, preferAbs)) {
+            selected = covered;
+        }
+        else {
+            selected = exact ?? covered ?? null;
+        }
     }
     else if (options.autoSelect !== false) {
         const strong = candidates.filter((c) => c.score >= 5);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praneeth_54/agentdoctor",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "Engineering assurance for AI coding agents — repository intelligence, change evidence, safety controls, and MCP tools.",
   "type": "module",
   "bin": {