@praneeth_54/agentdoctor 0.1.0-beta

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- Publish as scoped package `@praneeth_54/agentdoctor` (unscoped `agentdoctor` blocked by npm as too similar to `agent-doctor`)
+
+### Fixed
+
+- Track fake credential fixtures required by CI (were excluded by `.gitignore`)
+- Align package and docs URLs with the public GitHub repository
+- Release workflow selects notes by tag and attaches the npm tarball
+- CLI help text matches shipped capabilities (`--min-score` no-op until scoring)
+
+### Planned
+
+- Deterministic readiness scoring
+- Safe automatic fixes
+- Packaged GitHub Action
+
+## [0.1.0-beta] — 2026-07-29
+
+First public beta.
+
+### Added
+
+- CLI: `scan` (default), `explain`, `doctor`, `fix` stub
+- Flags: `--json`, `--ci`, `--verbose`, `--min-score`, `--version`, `--help`
+- Repository detection (languages, frameworks, package managers, monorepos)
+- Agent adapters for Cursor, Claude Code, and Codex
+- Rule engine with security, context, instruction, and MCP findings
+- Stable rule IDs and cross-agent finding deduplication
+- Terminal and JSON reporters
+- Programmatic `scan()` API
+- Fixture-based unit and integration tests
+
+### Security
+
+- Conservative wording for exposure findings
+- Secret values never printed
+- Repository boundary enforcement for paths and symlinks
+- Control-character sanitization in output
+
+### Known limitations
+
+- Readiness scores are not yet available (`scoringAvailable: false`)
+- Automatic fixes are not applied
+- Not a complete secret scanner
+- Git “tracked secret” detection deferred
+
+[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v0.1.0-beta...HEAD
+[0.1.0-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.0-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentDoctor Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# AgentDoctor
+
+**Lighthouse for AI coding agents.**
+
+AgentDoctor audits a repository’s AI coding agent configuration — instructions, ignore rules, permissions, and MCP setup — using local static analysis. No API key. No upload by default.
+
+```bash
+npx @praneeth_54/agentdoctor
+```
+
+|                |                                                                                     |
+| -------------- | ----------------------------------------------------------------------------------- |
+| **What it is** | A CLI health check for agent config in your repo                                    |
+| **Why use it** | Catch misconfigurations, sensitive context exposure, and instruction problems early |
+| **Install**    | `npx @praneeth_54/agentdoctor` or `npm install -g @praneeth_54/agentdoctor`         |
+| **Requires**   | Node.js 20+                                                                         |
+
+[![CI](https://img.shields.io/github/actions/workflow/status/pranee54/AgentDoctor/ci.yml?branch=main&label=CI)](https://github.com/pranee54/AgentDoctor/actions)
+[![npm](https://img.shields.io/npm/v/@praneeth_54/agentdoctor?label=npm)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
+[![Node](https://img.shields.io/node/v/@praneeth_54/agentdoctor)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Release](https://img.shields.io/badge/release-v0.1.0--beta-orange)](CHANGELOG.md)
+
+---
+
+## Demo
+
+```text
+$ npx @praneeth_54/agentdoctor
+
+AgentDoctor v0.1.0-beta
+
+Repository
+  Framework: Next.js
+  Language: TypeScript
+  Package manager: npm
+  Files scanned: 46
+
+AI Coding Agents
+
+✓ Cursor       configured
+✓ Claude Code  configured
+✓ Codex        configured
+
+Findings
+
+CRITICAL
+
+  ✗ Sensitive environment file may enter agent context
+    .env.production
+    Affected: Claude Code, Codex
+    Fix: Exclude the file from agent context and keep it out of version control.
+
+WARNING
+
+  ! Large instruction file
+    CLAUDE.md — 38 KB
+
+Summary
+
+  1 critical
+  1 warning
+  0 info
+
+Scoring is not included in this beta
+```
+
+---
+
+## Why AgentDoctor exists
+
+Teams adopt AI coding agents quickly and accumulate project instructions, ignore rules, MCP servers, and permission settings. Those files are easy to misconfigure and hard to review consistently.
+
+| Tooling analogy | Domain                           |
+| --------------- | -------------------------------- |
+| Lighthouse      | Web pages                        |
+| `npm audit`     | Dependencies                     |
+| ESLint          | Source code                      |
+| **AgentDoctor** | **AI coding agent environments** |
+
+AgentDoctor analyzes configuration files. It does not run agents or edit your project.
+
+---
+
+## Installation
+
+### One-shot
+
+```bash
+npx @praneeth_54/agentdoctor
+```
+
+### Global (optional)
+
+```bash
+npm install -g @praneeth_54/agentdoctor
+agentdoctor
+```
+
+The published package name is `@praneeth_54/agentdoctor` (npm blocks the unscoped name `agentdoctor` as too similar to an existing package). The CLI binary remains `agentdoctor`.
+
+### Library
+
+```bash
+npm install @praneeth_54/agentdoctor
+```
+
+```ts
+import { scan } from "@praneeth_54/agentdoctor";
+
+const result = await scan({ cwd: process.cwd() });
+console.log(result.summary);
+```
+
+---
+
+## Quick start
+
+```bash
+# Scan the current directory
+npx @praneeth_54/agentdoctor
+
+# Scan a path
+npx @praneeth_54/agentdoctor ./my-app
+
+# Machine-readable output
+npx @praneeth_54/agentdoctor --json
+
+# Extra detail (paths, timing, finding rationale)
+npx @praneeth_54/agentdoctor --verbose
+
+# Explain a rule
+npx @praneeth_54/agentdoctor explain security/env-file-exposure
+
+# Environment health check
+npx @praneeth_54/agentdoctor doctor
+```
+
+---
+
+## Features
+
+| Capability                                              | Status  |
+| ------------------------------------------------------- | ------- |
+| Zero-config first run                                   | ✓       |
+| Works offline / no API key                              | ✓       |
+| Detects project-level agent configuration               | ✓       |
+| Deterministic security / context / instruction findings | ✓       |
+| Inspects supported MCP project configuration            | ✓       |
+| Stable JSON output for CI                               | ✓       |
+| `explain <rule>` documentation                          | ✓       |
+| Readiness scoring                                       | Planned |
+| Safe automatic fixes                                    | Planned |
+| Official GitHub Action package                          | Planned |
+
+### Feature comparison
+
+| Concern                                      | Manual review | Generic linters | AgentDoctor      |
+| -------------------------------------------- | ------------- | --------------- | ---------------- |
+| Agent instruction files present and usable   | Manual        | —               | ✓                |
+| Empty or duplicated instructions             | Manual        | —               | ✓                |
+| Sensitive filenames vs agent access patterns | Manual        | Partial         | ✓ (conservative) |
+| Broad MCP filesystem scopes                  | Manual        | —               | ✓                |
+| Large always-on instruction files            | Manual        | —               | ✓                |
+| Uploads repository by default                | —             | Sometimes       | **Never**        |
+
+---
+
+## What it detects
+
+### Supported agents
+
+| Agent       | Project-level detection                    |
+| ----------- | ------------------------------------------ |
+| Cursor      | Rules, ignore files, MCP, `AGENTS.md`      |
+| Claude Code | Instructions, settings, rules, MCP         |
+| Codex       | `AGENTS.md` / overrides, project `.codex/` |
+
+### Finding categories
+
+Security, context efficiency, instruction quality, and MCP configuration. Full catalog: [docs/rules.md](docs/rules.md).
+
+Adapters are pluggable — additional agents can be registered without rewriting the scanner.
+
+---
+
+## Architecture
+
+```text
+┌─────────────┐
+│  Discovery  │  bounded filesystem walk
+└──────┬──────┘
+       ▼
+┌─────────────────┐
+│ Project detect  │  language / framework / package manager
+└──────┬──────────┘
+       ▼
+┌─────────────────┐
+│ Agent adapters  │  Cursor · Claude Code · Codex
+└──────┬──────────┘
+       ▼
+┌─────────────────┐
+│  Rule engine    │  security · context · instructions · MCP
+└──────┬──────────┘
+       ▼
+┌─────────────────┐
+│    Findings     │  deterministic IDs · deduped · fixability metadata
+└──────┬──────────┘
+       ▼
+┌─────────────────┐
+│   Reporters     │  terminal · JSON
+└─────────────────┘
+```
+
+Details: [docs/architecture.md](docs/architecture.md)
+
+---
+
+## JSON output
+
+```bash
+npx @praneeth_54/agentdoctor --json
+```
+
+```json
+{
+  "version": "0.1.0-beta",
+  "repository": {
+    "primaryFramework": "nextjs",
+    "primaryLanguage": "typescript",
+    "filesScanned": 46
+  },
+  "agents": [
+    {
+      "id": "cursor",
+      "detected": true,
+      "configured": true,
+      "status": "configured"
+    }
+  ],
+  "findings": [
+    {
+      "id": "security/env-file-exposure:.env.production",
+      "ruleId": "security/env-file-exposure",
+      "category": "security",
+      "severity": "critical",
+      "title": "Sensitive environment file may enter agent context",
+      "affectedAgents": ["claude-code", "codex"],
+      "fixability": "review"
+    }
+  ],
+  "summary": { "critical": 1, "warning": 0, "info": 0, "total": 1 },
+  "scoringAvailable": false,
+  "scores": null
+}
+```
+
+Exit codes: [docs/exit-codes.md](docs/exit-codes.md)
+
+---
+
+## Privacy
+
+**Your code stays on your machine.**
+
+Normal scans do not:
+
+- send source code to external services
+- require authentication
+- call an LLM
+- execute project code
+- start MCP servers
+- enable telemetry by default
+
+If anonymous telemetry is ever introduced, it will be opt-in.
+
+---
+
+## FAQ
+
+**Does AgentDoctor require an API key?**  
+No. Core scanning is local and deterministic.
+
+**Is this a secret scanner?**  
+No. It uses conservative filename and configuration heuristics. It never prints secret values and does not claim complete coverage.
+
+**Will it modify my repository?**  
+Not in this release. `agentdoctor fix` is reserved for a future safe-fix mode.
+
+**Can I use it in CI?**  
+Yes — prefer `--json`. `--min-score` is ignored until readiness scoring ships.
+
+**How do I understand a finding?**
+
+```bash
+npx @praneeth_54/agentdoctor explain <rule-id>
+```
+
+---
+
+## Documentation
+
+Start at [docs/README.md](docs/README.md).
+
+| Doc                                            | Contents                    |
+| ---------------------------------------------- | --------------------------- |
+| [docs/architecture.md](docs/architecture.md)   | Pipeline and package layout |
+| [docs/rules.md](docs/rules.md)                 | Stable rule IDs             |
+| [docs/exit-codes.md](docs/exit-codes.md)       | Process exit codes          |
+| [docs/compatibility.md](docs/compatibility.md) | Beta compatibility promises |
+| [docs/development.md](docs/development.md)     | Local development           |
+| [ROADMAP.md](ROADMAP.md)                       | Near- and medium-term plans |
+| [CHANGELOG.md](CHANGELOG.md)                   | Release history             |
+
+---
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md). Highlights:
+
+1. Deterministic readiness scoring
+2. Conservative auto-fix for safe findings
+3. Packaged GitHub Action
+4. Additional agent adapters
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+1. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md)
+2. Set up locally with [docs/development.md](docs/development.md)
+3. Report security issues via [SECURITY.md](SECURITY.md)
+
+```bash
+git clone https://github.com/pranee54/AgentDoctor.git
+cd AgentDoctor
+npm install
+npm run typecheck && npm run lint && npm test && npm run build
+node dist/cli/index.js ./fixtures/clean-configured-project
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © AgentDoctor Contributors

package/dist/agents/claude/adapter.d.ts

@@ -0,0 +1 @@
+export { claudeAdapter, detectClaudeCode } from "./detector.js";

package/dist/agents/claude/adapter.js

@@ -0,0 +1 @@
+export { claudeAdapter, detectClaudeCode } from "./detector.js";

package/dist/agents/claude/detector.d.ts

@@ -0,0 +1,16 @@
+import type { AgentAdapter, AgentDetectionContext, AgentDetectionResult } from "../types.js";
+/**
+ * Claude Code project configuration detection.
+ *
+ * Official sources (code.claude.com docs):
+ * - Project instructions: `./CLAUDE.md` or `./.claude/CLAUDE.md`
+ * - Local (gitignored) instructions: `./CLAUDE.local.md`
+ * - Nested `CLAUDE.md` / `CLAUDE.local.md` in subdirectories (on-demand load)
+ * - Modular rules: .claude/rules/ markdown files (recursive)
+ * - Project settings: .claude/settings.json, .claude/settings.local.json
+ *
+ * We do NOT inspect ~/.claude or managed org policies — repository only.
+ * Claude Code does not read AGENTS.md directly (docs recommend importing via CLAUDE.md).
+ */
+export declare function detectClaudeCode(context: AgentDetectionContext): Promise<AgentDetectionResult>;
+export declare const claudeAdapter: AgentAdapter;

package/dist/agents/claude/detector.js

@@ -0,0 +1,225 @@
+import { AGENT_DISPLAY_NAMES } from "../../constants.js";
+import { deriveStatus, inspectRepoFile, pathExistsInsideRoot, toAgentConfigFile, tryParseJson, } from "../inspect.js";
+import { basenameOf, isRootLevel } from "../types.js";
+/**
+ * Claude Code project configuration detection.
+ *
+ * Official sources (code.claude.com docs):
+ * - Project instructions: `./CLAUDE.md` or `./.claude/CLAUDE.md`
+ * - Local (gitignored) instructions: `./CLAUDE.local.md`
+ * - Nested `CLAUDE.md` / `CLAUDE.local.md` in subdirectories (on-demand load)
+ * - Modular rules: .claude/rules/ markdown files (recursive)
+ * - Project settings: .claude/settings.json, .claude/settings.local.json
+ *
+ * We do NOT inspect ~/.claude or managed org policies — repository only.
+ * Claude Code does not read AGENTS.md directly (docs recommend importing via CLAUDE.md).
+ */
+export async function detectClaudeCode(context) {
+    const { root, discovery, maxFileSizeBytes } = context;
+    const configFiles = [];
+    const diagnostics = [];
+    const seen = new Set();
+    const metadata = {
+        claudeMdCount: 0,
+        claudeLocalCount: 0,
+        rulesCount: 0,
+        hasClaudeDirectory: false,
+        hasSettings: false,
+        hasLocalSettings: false,
+    };
+    const hasClaudeDir = await pathExistsInsideRoot(root, ".claude");
+    metadata.hasClaudeDirectory = hasClaudeDir;
+    async function addMarkdownInstruction(relativePath, kind) {
+        if (seen.has(relativePath)) {
+            return;
+        }
+        seen.add(relativePath);
+        const inspected = await inspectRepoFile(root, relativePath, maxFileSizeBytes);
+        const scope = relativePath === "CLAUDE.md" ||
+            relativePath === ".claude/CLAUDE.md" ||
+            relativePath === "CLAUDE.local.md"
+            ? "root"
+            : isRootLevel(relativePath)
+                ? "root"
+                : "nested";
+        configFiles.push(toAgentConfigFile(inspected, kind, {
+            legacy: false,
+            scope,
+        }));
+        if (kind === "claude-md") {
+            metadata.claudeMdCount = Number(metadata.claudeMdCount) + 1;
+        }
+        else if (kind === "claude-local-md") {
+            metadata.claudeLocalCount = Number(metadata.claudeLocalCount) + 1;
+        }
+        else {
+            metadata.rulesCount = Number(metadata.rulesCount) + 1;
+        }
+        if (!inspected.exists) {
+            return;
+        }
+        if (!inspected.readable && inspected.error) {
+            diagnostics.push({
+                code: "claude/unreadable-file",
+                severity: "warning",
+                message: `Could not read Claude Code file: ${inspected.error}`,
+                file: relativePath,
+            });
+        }
+        else if (inspected.empty) {
+            diagnostics.push({
+                code: "claude/empty-instruction",
+                severity: "info",
+                message: "Claude Code instruction file is empty",
+                file: relativePath,
+            });
+        }
+    }
+    async function addSettingsFile(relativePath, kind) {
+        if (seen.has(relativePath)) {
+            return;
+        }
+        seen.add(relativePath);
+        const inspected = await inspectRepoFile(root, relativePath, maxFileSizeBytes);
+        let parseError;
+        if (inspected.readable && inspected.text !== null && !inspected.empty) {
+            const parsed = tryParseJson(inspected.text);
+            if (!parsed.ok) {
+                parseError = parsed.error;
+                diagnostics.push({
+                    code: "claude/malformed-settings",
+                    severity: "warning",
+                    message: `${relativePath} could not be parsed: ${parsed.error}`,
+                    file: relativePath,
+                });
+            }
+            // Count setting keys only — do not surface setting values.
+            if (parsed.ok && parsed.data && typeof parsed.data === "object") {
+                metadata[`${kind}Keys`] = Object.keys(parsed.data).length;
+            }
+        }
+        else if (inspected.exists && inspected.empty) {
+            diagnostics.push({
+                code: "claude/empty-settings",
+                severity: "info",
+                message: `${relativePath} is empty`,
+                file: relativePath,
+            });
+        }
+        else if (inspected.exists && !inspected.readable && inspected.error) {
+            diagnostics.push({
+                code: "claude/unreadable-settings",
+                severity: "warning",
+                message: `Could not read ${relativePath}: ${inspected.error}`,
+                file: relativePath,
+            });
+        }
+        configFiles.push(toAgentConfigFile(inspected, kind, {
+            legacy: false,
+            scope: "root",
+            ...(parseError !== undefined ? { parseError } : {}),
+        }));
+        if (kind === "claude-settings") {
+            metadata.hasSettings = true;
+        }
+        else {
+            metadata.hasLocalSettings = true;
+        }
+    }
+    // Targeted root/project paths (may be empty and missing from discovery)
+    const targeted = [
+        "CLAUDE.md",
+        ".claude/CLAUDE.md",
+        "CLAUDE.local.md",
+        ".claude/settings.json",
+        ".claude/settings.local.json",
+    ];
+    for (const relative of targeted) {
+        if (await pathExistsInsideRoot(root, relative)) {
+            if (relative.endsWith("settings.json") || relative.endsWith("settings.local.json")) {
+                await addSettingsFile(relative, relative.endsWith("settings.local.json") ? "claude-settings-local" : "claude-settings");
+            }
+            else if (relative.endsWith("CLAUDE.local.md")) {
+                await addMarkdownInstruction(relative, "claude-local-md");
+            }
+            else {
+                await addMarkdownInstruction(relative, "claude-md");
+            }
+        }
+    }
+    // Nested CLAUDE.md / CLAUDE.local.md and .claude/rules from discovery
+    for (const file of discovery.files) {
+        const relative = file.relativePath;
+        const base = basenameOf(relative);
+        if (base === "CLAUDE.md") {
+            await addMarkdownInstruction(relative, "claude-md");
+            continue;
+        }
+        if (base === "CLAUDE.local.md") {
+            await addMarkdownInstruction(relative, "claude-local-md");
+            continue;
+        }
+        if (relative.includes(".claude/rules/") && base.endsWith(".md")) {
+            await addMarkdownInstruction(relative, "claude-rule-md");
+        }
+    }
+    const usableInstruction = configFiles.some((f) => f.readable &&
+        !f.empty &&
+        (f.kind === "claude-md" ||
+            f.kind === "claude-local-md" ||
+            f.kind === "claude-rule-md" ||
+            ((f.kind === "claude-settings" || f.kind === "claude-settings-local") &&
+                f.parseError === undefined)));
+    const detected = hasClaudeDir ||
+        Number(metadata.claudeMdCount) > 0 ||
+        Number(metadata.claudeLocalCount) > 0 ||
+        Number(metadata.rulesCount) > 0 ||
+        Boolean(metadata.hasSettings) ||
+        Boolean(metadata.hasLocalSettings);
+    const configured = usableInstruction;
+    const hasErrors = diagnostics.some((d) => d.severity === "error");
+    // Malformed settings alone without instructions → misconfigured if detected
+    const hasParseProblems = configFiles.some((f) => f.parseError !== undefined);
+    const status = deriveStatus({
+        detected,
+        configured,
+        hasErrors: hasErrors || (hasParseProblems && !configured),
+    });
+    const parts = [];
+    if (Number(metadata.claudeMdCount) > 0) {
+        parts.push("CLAUDE.md");
+    }
+    if (Number(metadata.rulesCount) > 0) {
+        parts.push(`${metadata.rulesCount} rule${Number(metadata.rulesCount) === 1 ? "" : "s"}`);
+    }
+    if (metadata.hasSettings || metadata.hasLocalSettings) {
+        parts.push("settings");
+    }
+    let summary;
+    if (!detected) {
+        summary = "not configured";
+    }
+    else if (configured) {
+        summary = parts.length > 0 ? parts.join(", ") : "configured";
+    }
+    else {
+        summary = "detected but not configured";
+    }
+    return {
+        id: "claude-code",
+        displayName: AGENT_DISPLAY_NAMES["claude-code"],
+        detected,
+        configured,
+        status,
+        summary,
+        configFiles,
+        configPaths: configFiles.map((f) => f.relativePath),
+        diagnostics,
+        metadata,
+    };
+}
+export const claudeAdapter = {
+    id: "claude-code",
+    displayName: AGENT_DISPLAY_NAMES["claude-code"],
+    detect: detectClaudeCode,
+};

package/dist/agents/codex/adapter.d.ts

@@ -0,0 +1 @@
+export { codexAdapter, detectCodex } from "./detector.js";

package/dist/agents/codex/adapter.js

@@ -0,0 +1 @@
+export { codexAdapter, detectCodex } from "./detector.js";