@praneeth_54/agentdoctor 0.1.2-beta → 0.1.4-beta

package/CHANGELOG.md

@@ -11,7 +11,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Deterministic readiness scoring
 - Safe automatic fixes
-- Packaged GitHub Action
+
+## [0.1.4-beta] — 2026-08-02
+
+Backward-compatible distribution release: first-class GitHub Action packaging. CLI and scanner behavior are unchanged from 0.1.3-beta.
+
+### Added
+
+- Composite GitHub Action (`action.yml`) that installs the published `@praneeth_54/agentdoctor` package and emits a workspace-contained JSON report
+- CI `action-smoke` matrix covering normal/nested output paths and rejection of traversal, parent-symlink escape, final-file symlink, and directory output targets
+- README GitHub Action usage section and ROADMAP update for CI packaging
+
+### Compatibility
+
+- No scanner, rule, or JSON finding-schema changes
+- Scoring remains unavailable (`scoringAvailable: false`)
+- `--min-score` remains accepted but ignored until scoring ships
+- Default Action `version` input is `0.1.4-beta` (exact npm version or `latest` / `beta` dist-tags)
+
+## [0.1.3-beta] — 2026-07-29
+
+Backward-compatible security-signal and detection-quality patch.
+
+### Security
+
+- Repositories without supported agent configuration no longer receive an unqualified clean result when relevant repository-risk findings exist
+- Agent exposure and repository risk remain semantically distinct (`affectedAgents` is empty when exposure is not asserted)
+- Additive `agentSecurityAnalysis` field: `full` | `limited`
+- Environment templates (`.env.example`, `.env.sample`, `.env.template`, `.env.dist`) receive informational treatment
+- Common environment backup filenames (`.env_backup`, `.env_old`, `.env_local`) receive conservative warning treatment
+
+### Detection
+
+- Prevent false Django detection from arbitrary nested `settings.py` files
+- Detect nested FastAPI projects using dependency + `app/main.py` structure evidence
+- Detect React from nested project manifests
+- Prevent Poetry detection from generic non-Poetry `pyproject.toml` files (for example hatchling)
+- Improve multi-stack terminal summaries for multi-project repositories
+
+### Testing
+
+- Added Excepta FastAPI/React/Flutter and security-semantics fixtures/tests
+- Total test suite is now 122 tests
+- Three real-world regression families validated (ProxyShield, Flutter/Laravel multi-app, Excepta)
 
 ## [0.1.2-beta] — 2026-07-29
 
@@ -81,7 +123,9 @@ First public beta.
 - Not a complete secret scanner
 - Git “tracked secret” detection deferred
 
-[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v0.1.2-beta...HEAD
+[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v0.1.4-beta...HEAD
+[0.1.4-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.4-beta
+[0.1.3-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.3-beta
 [0.1.2-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.2-beta
 [0.1.1-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.1-beta
 [0.1.0-beta]: https://github.com/pranee54/AgentDoctor/releases/tag/v0.1.0-beta

package/README.md

@@ -1,41 +1,43 @@
 # AgentDoctor
 
 [![npm](https://img.shields.io/npm/v/@praneeth_54/agentdoctor)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
-[![License](https://img.shields.io/github/license/pranee54/AgentDoctor)](LICENSE)
-[![GitHub Stars](https://img.shields.io/github/stars/pranee54/AgentDoctor)](https://github.com/pranee54/AgentDoctor/stargazers)
+[![npm downloads](https://img.shields.io/npm/dm/@praneeth_54/agentdoctor)](https://www.npmjs.com/package/@praneeth_54/agentdoctor)
 [![CI](https://img.shields.io/github/actions/workflow/status/pranee54/AgentDoctor/ci.yml?branch=main&label=CI)](https://github.com/pranee54/AgentDoctor/actions)
 [![Node](https://img.shields.io/node/v/@praneeth_54/agentdoctor)](https://nodejs.org)
-[![Release](https://img.shields.io/badge/release-v0.1.2--beta-orange)](CHANGELOG.md)
+[![License](https://img.shields.io/github/license/pranee54/AgentDoctor)](LICENSE)
 
 **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.
+Audit coding-agent configuration before it becomes a repository problem.
+
+AgentDoctor is a local CLI that inspects project-level AI coding agent setup — Cursor, Claude Code, and Codex — for security, instructions, context, and MCP configuration. Deterministic static analysis. No API key. No code 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+                                                                         |
+Public beta (`0.1.x-beta`). Readiness scoring and automatic fixes are not available yet.
 
 ---
 
-## Demo
+## What you get
+
+![AgentDoctor scanning a repository and reporting coding-agent security findings](docs/images/cli-scan.png)
+
+_Real scan of the included `insecure-agent-project` fixture using AgentDoctor v0.1.4-beta._
 
 ```text
 $ npx @praneeth_54/agentdoctor
 
-AgentDoctor v0.1.2-beta
+🩺 AgentDoctor v0.1.4-beta
+
+Scanning repository...
 
 Repository
-  Framework: Next.js
-  Language: TypeScript
+  Framework: Node.js
+  Language: JavaScript
   Package manager: npm
-  Files scanned: 46
+  Files scanned: 7
 
 AI Coding Agents
 
@@ -48,59 +50,134 @@ Findings
 CRITICAL
 
   ✗ Sensitive environment file may enter agent context
-    .env.production
+    .env
     Affected: Claude Code, Codex
-    Fix: Exclude the file from agent context and keep it out of version control.
+    Fix: Add an agent-specific exclusion (for example .cursorignore or a
+         Claude Code Read deny rule), keep the file out of version control,
+         and rotate any credentials that may have been exposed.
+
+  ✗ Private key or credential file present in repository
+    test-private-key.pem
+    Affected: Claude Code, Codex, Cursor
 
 WARNING
 
-  ! Large instruction file
-    CLAUDE.md — 38 KB
+  ! Claude Code bypassPermissions mode enabled
+    .claude/settings.json
 
 Summary
 
-  1 critical
+  3 critical
   1 warning
   0 info
 
-Scoring is not included in this beta
+Scoring: not included in this release
 ```
 
+Abbreviated text example from the same fixture for accessibility and search. Secret values are never printed.
+
 ---
 
-## Why AgentDoctor exists
+## Why AgentDoctor?
+
+Repositories accumulate agent configuration quickly:
+
+- Multiple instruction formats (`.cursor/rules`, `CLAUDE.md`, `AGENTS.md`)
+- Stale path references in always-on instructions
+- Ignore differences between `.gitignore`, `.cursorignore`, and agent defaults
+- MCP filesystem scopes that are broader than intended
+- Generated directories and large logs that waste context
+- Credential-like files that may be readable by agents
+- Conflicting assumptions about what each agent can see
 
-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.
+Manually reviewing all of that across Cursor, Claude Code, and Codex is slow and inconsistent. AgentDoctor provides one deterministic local audit with stable rule IDs, evidence paths, and affected-agent information.
 
-| Tooling analogy | Domain                           |
+| 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.
+AgentDoctor analyzes configuration. It does not run agents, call an LLM, or modify your repository in this release.
 
 ---
 
-## Installation
+## Before / after
 
-### One-shot
+**Before**
+
+A repository may contain:
+
+```text
+.cursor/rules/
+AGENTS.md
+CLAUDE.md
+.claude/settings.json
+.mcp.json
+.env
+```
+
+Potential problems stay invisible until something leaks into model context, CI, or a teammate’s agent session:
+
+- environment or credential-like files reachable by agents
+- stale instruction path references
+- broad MCP filesystem access
+- oversized always-on context
+
+**Run**
 
 ```bash
-npx @praneeth_54/agentdoctor@0.1.2-beta
+npx @praneeth_54/agentdoctor
+```
+
+**After**
+
+You get deterministic findings with:
+
+- stable rule IDs (for example `security/env-file-exposure`)
+- evidence paths
+- affected agents when exposure claims are supported
+- conservative recommendations
+
+Automatic repair is **not** included in this beta. Findings tell you what to review; you decide what to change.
+
+---
+
+## Quick start
+
+### One-shot (recommended)
+
+```bash
+npx @praneeth_54/agentdoctor
+```
+
+Pin a beta version when you need a fixed install:
+
+```bash
+npx @praneeth_54/agentdoctor@0.1.4-beta
 ```
 
 ### Global (optional)
 
 ```bash
-npm install -g @praneeth_54/agentdoctor@0.1.2-beta
+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`.
+### Common commands
+
+```bash
+agentdoctor .
+agentdoctor . --json
+agentdoctor . --verbose
+agentdoctor explain security/env-file-exposure
+agentdoctor doctor
+```
+
+Package name: `@praneeth_54/agentdoctor` (npm blocks the unscoped name). CLI binary: `agentdoctor`. Requires **Node.js 20+**.
 
-### Library
+### Programmatic API
 
 ```bash
 npm install @praneeth_54/agentdoctor
@@ -111,218 +188,148 @@ import { scan } from "@praneeth_54/agentdoctor";
 
 const result = await scan({ cwd: process.cwd() });
 console.log(result.summary);
+console.log(result.agentSecurityAnalysis); // "full" | "limited"
 ```
 
 ---
 
-## Quick start
+## Supported agents
 
-```bash
-# Scan the current directory
-npx @praneeth_54/agentdoctor
+Project-level configuration only (repository files). Global user settings are not scanned.
 
-# Scan a path
-npx @praneeth_54/agentdoctor ./my-app
+| Agent           | What AgentDoctor inspects                                              |
+| --------------- | ---------------------------------------------------------------------- |
+| **Cursor**      | `.cursor/rules/*.mdc`, `.cursorignore`, Cursor MCP config, `AGENTS.md` |
+| **Claude Code** | `CLAUDE.md`, `.claude/settings*.json`, `.claude/rules`, MCP config     |
+| **Codex**       | `AGENTS.md` / overrides, project `.codex/` configuration               |
 
-# Machine-readable output
-npx @praneeth_54/agentdoctor --json
+Additional adapters are planned — see [ROADMAP.md](ROADMAP.md).
 
-# Extra detail (paths, timing, finding rationale)
-npx @praneeth_54/agentdoctor --verbose
+---
 
-# Explain a rule
-npx @praneeth_54/agentdoctor explain security/env-file-exposure
+## Finding categories
 
-# Environment health check
-npx @praneeth_54/agentdoctor doctor
-```
+| Category         | Examples                                                              |
+| ---------------- | --------------------------------------------------------------------- |
+| **Security**     | Env-file exposure, private-key filenames, broad MCP filesystem scopes |
+| **Context**      | Large instruction files, large logs, unignored generated directories  |
+| **Instructions** | Empty instructions, duplicate content, missing path references        |
+| **MCP**          | Malformed MCP config, high-risk filesystem path arguments             |
 
----
+Full catalog with severities and fixability: [docs/rules.md](docs/rules.md).
 
-## 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**        |
+Explain any rule:
 
----
+```bash
+npx @praneeth_54/agentdoctor explain security/env-file-exposure
+```
 
-## What it detects
+---
 
-### Supported agents
+## Privacy and trust
 
-| Agent       | Project-level detection                    |
-| ----------- | ------------------------------------------ |
-| Cursor      | Rules, ignore files, MCP, `AGENTS.md`      |
-| Claude Code | Instructions, settings, rules, MCP         |
-| Codex       | `AGENTS.md` / overrides, project `.codex/` |
+**Scans run locally on your machine.**
 
-### Finding categories
+AgentDoctor:
 
-Security, context efficiency, instruction quality, and MCP configuration. Full catalog: [docs/rules.md](docs/rules.md).
+- does not require an API key
+- does not upload repository contents by default
+- does not call an LLM for core scanning
+- does not execute MCP servers
+- does not execute project code
+- never prints secret values from files it flags by name
+- enforces repository boundary checks for path references and symlink escape
 
-Adapters are pluggable — additional agents can be registered without rewriting the scanner.
+This is still software that reads untrusted repository trees. Treat findings as guidance, not a security certification. AgentDoctor is **not** a complete secret-content scanner.
 
 ---
 
-## Architecture
+## CI usage
 
-```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
-└─────────────────┘
-```
+### GitHub Action
 
-Details: [docs/architecture.md](docs/architecture.md)
+Run AgentDoctor directly in a workflow:
 
----
+```yaml
+permissions:
+  contents: read
 
-## JSON output
+steps:
+  - uses: actions/checkout@v4
 
-```bash
-npx @praneeth_54/agentdoctor --json
-```
+  - name: Audit coding-agent configuration
+    id: agentdoctor
+    uses: pranee54/AgentDoctor@v0.1.4-beta
+    with:
+      path: .
+      output-file: agentdoctor-report.json
 
-```json
-{
-  "version": "0.1.2-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
-}
+  - name: Upload AgentDoctor report
+    uses: actions/upload-artifact@v4
+    with:
+      name: agentdoctor-report
+      path: ${{ steps.agentdoctor.outputs.report-path }}
 ```
 
-Exit codes: [docs/exit-codes.md](docs/exit-codes.md)
+The action installs the published `@praneeth_54/agentdoctor@0.1.4-beta` package, runs it with
+`--ci --json`, and writes the report inside the checked-out workspace. It sets up Node.js 20
+for the CLI. The optional `version` input accepts an exact npm version or the `latest` / `beta`
+dist-tag.
 
----
+### CLI
 
-## Privacy
+Use JSON directly in other CI systems:
 
-**Your code stays on your machine.**
-
-Normal scans do not:
+```bash
+npx @praneeth_54/agentdoctor --ci --json
+```
 
-- send source code to external services
-- require authentication
-- call an LLM
-- execute project code
-- start MCP servers
-- enable telemetry by default
+`--ci` runs non-interactively. Until readiness scoring ships, successful scans exit `0` even when findings exist, and `--min-score` is accepted but ignored.
 
-If anonymous telemetry is ever introduced, it will be opt-in.
+Exit codes: [docs/exit-codes.md](docs/exit-codes.md). Compatibility promises: [docs/compatibility.md](docs/compatibility.md).
 
 ---
 
-## 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.
+## Beta limitations
 
-**Will it modify my repository?**  
-Not in this release. `agentdoctor fix` is reserved for a future safe-fix mode.
+Honest limits of the current public beta:
 
-**Can I use it in CI?**  
-Yes — prefer `--json`. `--min-score` is ignored until readiness scoring ships.
+| Limitation                          | Status                                                          |
+| ----------------------------------- | --------------------------------------------------------------- |
+| Readiness scoring                   | Not available (`scores` is `null`, `scoringAvailable: false`)   |
+| `--min-score`                       | Accepted, ignored until scoring ships                           |
+| Automatic fixes (`agentdoctor fix`) | Stub only — does not modify files                               |
+| Secret-content scanning             | Filename / config heuristics only                               |
+| Detection style                     | Intentionally conservative; false security findings are avoided |
+| Agent coverage                      | Cursor, Claude Code, Codex project configs                      |
 
-**How do I understand a finding?**
-
-```bash
-npx @praneeth_54/agentdoctor explain <rule-id>
-```
+See [CHANGELOG.md](CHANGELOG.md) and [docs/release-notes-v0.1.4-beta.md](docs/release-notes-v0.1.4-beta.md).
 
 ---
 
-## Documentation
+## Architecture
 
-Start at [docs/README.md](docs/README.md).
+```text
+Discovery → Project detect → Agent adapters → Rule engine → Findings → Terminal / JSON
+```
 
-| 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             |
+Details: [docs/architecture.md](docs/architecture.md)
 
 ---
 
-## Roadmap
-
-See [ROADMAP.md](ROADMAP.md). Highlights:
+## Documentation
 
-1. Deterministic readiness scoring
-2. Conservative auto-fix for safe findings
-3. Packaged GitHub Action
-4. Additional agent adapters
+| Doc                                                                | Contents                       |
+| ------------------------------------------------------------------ | ------------------------------ |
+| [docs/README.md](docs/README.md)                                   | Documentation index            |
+| [docs/architecture.md](docs/architecture.md)                       | Scan pipeline                  |
+| [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              |
+| [docs/github-launch-checklist.md](docs/github-launch-checklist.md) | GitHub About / topics / launch |
+| [ROADMAP.md](ROADMAP.md)                                           | Near- and medium-term plans    |
+| [CHANGELOG.md](CHANGELOG.md)                                       | Release history                |
 
 ---
 
@@ -331,19 +338,29 @@ See [ROADMAP.md](ROADMAP.md). Highlights:
 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)
+2. Prefer [good first issues](docs/good-first-issues.md) ideas
+3. Report security issues via [SECURITY.md](SECURITY.md) — never paste real secrets into issues
 
 ```bash
 git clone https://github.com/pranee54/AgentDoctor.git
 cd AgentDoctor
 npm install
-npm run typecheck && npm run lint && npm test && npm run build
+npm run verify
 node dist/cli/index.js ./fixtures/clean-configured-project
 ```
 
 ---
 
+## Next steps
+
+- **Try it:** `npx @praneeth_54/agentdoctor`
+- **Report a false positive / false negative:** use the issue templates (include version, rule ID, anonymized evidence — no secrets)
+- **Propose a rule or adapter:** [feature request](.github/ISSUE_TEMPLATE/feature_request.md) / [rule proposal](.github/ISSUE_TEMPLATE/rule_proposal.md)
+- **Contribute:** [CONTRIBUTING.md](CONTRIBUTING.md)
+- **Useful?** Star or watch the repository so you see updates
+
+---
+
 ## License
 
 [MIT](LICENSE) © AgentDoctor Contributors

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const PACKAGE_VERSION = "0.1.2-beta";
+export declare const PACKAGE_VERSION = "0.1.4-beta";
 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 = "0.1.2-beta";
+export const PACKAGE_VERSION = "0.1.4-beta";
 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/rules/security/env-file-exposure.d.ts

@@ -1,2 +1,8 @@
 import type { RuleDefinition } from "../types.js";
+export type EnvFileKind = "runtime" | "template" | "backup";
+/**
+ * Classify environment-like filenames. Precision over recall.
+ * Does not inspect file contents.
+ */
+export declare function classifyEnvBasename(base: string): EnvFileKind | null;
 export declare const envFileExposureRule: RuleDefinition;