@vyuhlabs/dxkit 0.7.0 → 0.8.0

package/README.md

@@ -21,61 +21,51 @@ Running `init` auto-detects your tech stack and generates a complete `.claude/`
 
 ```
 .claude/
-  settings.json          # Permissions, deny list, hooks
-  agents/                # Active agents (auto-trigger)
+  settings.json          # Permissions, deny list, learning hooks
+  agents/                # Active agents (auto-trigger on matching questions)
     knowledge-bot.md     # Answers codebase questions
     onboarding.md        # Interactive onboarding buddy
     quality-reviewer.md  # Reviews code before committing
-  agents-available/      # Dormant agents (activate on demand)
+    doc-writer.md        # Audits and writes documentation
+  agents-available/      # Dormant agents (activate with /enable-agent)
     codebase-explorer.md # Deep architecture analysis
     code-reviewer.md     # PR review and security audit
     test-writer.md       # Writes tests for existing code
+    test-gap-finder.md   # Identifies untested critical code
+    dependency-mapper.md # Maps import chains and blast radius
+    health-auditor.md    # 6-dimension codebase health audit
+    vulnerability-scanner.md # Dependency + code security scan
+    dev-report.md        # Developer activity + quality attribution
     debugger.md          # Root cause analysis
-  commands/              # Slash commands
-    ask.md               # /ask — Query the codebase
-    quality.md           # /quality — Run linters
-    test.md              # /test — Run tests with coverage
-    check.md             # /check — Full pre-commit validation
-    fix.md               # /fix — Auto-fix issues
-    learn.md             # /learn — Capture gotchas/conventions
-    onboarding.md        # /onboarding — Start onboarding
-    help.md              # /help — List everything
-    session-start.md     # /session-start — Begin dev session
-    session-end.md       # /session-end — Checkpoint + evolve skills
-    ...
+  commands/              # 24 slash commands (see below)
   skills/                # Domain knowledge
     codebase/            # Auto-generated architecture overview
     learned/             # Evolving gotchas, conventions, deny list
-    quality/             # Quality check patterns
-    ...
-  rules/                 # Path-scoped rules (per language)
+  rules/                 # Path-scoped rules (per language + framework)
 CLAUDE.md                # Main context file for Claude Code
 .ai/
   sessions/              # Session checkpoints
+  reports/               # Generated reports (health, vulnerabilities, etc.)
+.github/
+  workflows/
+    pr-review.yml        # Automated PR review (opt-in)
 ```
 
 ## Supported Languages
 
-| Language | Detection | Linters | Tests | Coverage |
-|---|---|---|---|---|
-| Node.js / TypeScript | `package.json` | ESLint, Prettier, tsc | Auto-detected (Jest, Mocha, Vitest, Ava) | framework-specific |
-| Python | `pyproject.toml`, `setup.py`, `*.py` | ruff, mypy | pytest | pytest-cov |
-| Go | `go.mod` | golangci-lint, go vet | go test | go cover |
-| C# | `*.csproj`, `*.sln` | dotnet format, Roslyn | dotnet test | coverlet |
-| Rust | `Cargo.toml` | clippy, rustfmt | cargo test | tarpaulin |
+| Language | Detection | Linters | Test Runner |
+|---|---|---|---|
+| Node.js / TypeScript | `package.json` | ESLint, Prettier, tsc | Auto-detected (Jest, Mocha, Vitest, Ava, Tap) |
+| Python | `pyproject.toml`, `setup.py`, `*.py` | ruff, mypy | pytest |
+| Go | `go.mod` | golangci-lint, go vet | go test |
+| C# | `*.csproj`, `*.sln` | dotnet format, Roslyn | dotnet test |
+| Rust | `Cargo.toml` | clippy, rustfmt | cargo test |
 
-## Supported Tools
-
-Auto-detected and integrated when present:
-
-- **Google Cloud** (gcloud) — SDK commands, security rules
-- **Infisical** — Secrets management, never-leak rules
-- **Pulumi** — IaC with preview-before-apply safety
-- **Docker** — Container commands
+Multi-language repos fully supported — detects and generates rules/commands for all languages present.
 
 ## Supported Frameworks
 
-Auto-detected with framework-specific rules:
+Auto-detected with framework-specific path-scoped rules:
 
 - **LoopBack** — Controller/model/repository patterns, decorator conventions
 - **Express** — Middleware/routing conventions, error handling patterns
@@ -83,9 +73,16 @@ Auto-detected with framework-specific rules:
 - **FastAPI**, **Django**, **Flask** — Detected (rules coming soon)
 - **Gin**, **Echo**, **Fiber** — Detected (rules coming soon)
 
-## Commands
+## Supported Tools
+
+Auto-detected and integrated when present:
+
+- **Google Cloud** (gcloud) — SDK commands, security rules
+- **Infisical** — Secrets management, never-leak rules
+- **Pulumi** — IaC with preview-before-apply safety
+- **Docker** — Container commands
 
-After init, these slash commands are available in Claude Code:
+## Commands (24)
 
 ### Development Workflow
 | Command | Description |
@@ -99,19 +96,28 @@ After init, these slash commands are available in Claude Code:
 | Command | Description |
 |---|---|
 | `/quality` | Run language-specific linters + AI review |
-| `/test` | Run tests (auto-detected runner: Jest, Mocha, Vitest, etc.) |
+| `/test` | Run tests (auto-detected runner) |
 | `/check` | Full pre-commit validation (quality + tests + AI review) |
 | `/fix` | Auto-fix formatting and lint issues |
 | `/build` | Build the project |
 | `/setup-hooks` | Install git pre-commit/pre-push hooks |
 | `/test-gaps` | Find critical untested code paths |
 
+### Analysis & Reports
+| Command | Description | Report |
+|---|---|---|
+| `/health` | 6-dimension codebase health audit | `.ai/reports/health-audit-*.md` |
+| `/vulnerabilities` | Dependency + code vulnerability scan | `.ai/reports/vulnerability-scan-*.md` |
+| `/dev-report` | Developer activity + security attribution | `.ai/reports/developer-report-*.md` |
+| `/docs audit` | Documentation gap analysis | `.ai/reports/docs-audit-*.md` |
+| `/deps` | Dependency map + blast radius | `.ai/reports/dependency-map-*.md` |
+| `/export-pdf` | Convert markdown reports to PDF | `.ai/reports/*.pdf` |
+
 ### Exploration & Onboarding
 | Command | Description |
 |---|---|
-| `/onboarding` | Interactive onboarding for new developers |
+| `/onboarding` | Interactive onboarding buddy for new developers |
 | `/explore-codebase` | Deep architecture exploration |
-| `/deps` | Map dependencies ("what breaks if I change X?") |
 | `/help` | List all commands and agents |
 
 ### Operations
@@ -124,21 +130,41 @@ After init, these slash commands are available in Claude Code:
 
 ## Agents
 
-### Active by Default
+### Active by Default (4)
 These agents auto-trigger when Claude detects a matching question:
 
 - **knowledge-bot** — "How does auth work?" "Where are payments handled?"
 - **onboarding** — "I'm new, help me get started" "What does this project do?"
 - **quality-reviewer** — "Review my changes" "Check quality before I commit"
+- **doc-writer** — "What needs documentation?" "Help me write docs"
 
-### Dormant (activate with `/enable-agent`)
+### Dormant (9) — activate with `/enable-agent`
 - **codebase-explorer** — Deep architecture analysis, generates documentation
 - **code-reviewer** — PR review and security audit (read-only)
 - **test-writer** — Writes tests for existing code
 - **test-gap-finder** — Identifies critical untested code paths, prioritized by risk
 - **dependency-mapper** — Maps import chains and blast radius of changes
+- **health-auditor** — Comprehensive codebase health audit (scores 6 dimensions)
+- **vulnerability-scanner** — Dependency + code vulnerability analysis
+- **dev-report** — Developer activity, quality patterns, security attribution
 - **debugger** — Systematic root cause analysis
 
+## Reports
+
+All analysis commands save timestamped reports to `.ai/reports/`:
+
+```bash
+.ai/reports/
+  health-audit-2026-03-30.md          # Scores: tests, quality, docs, security, DX
+  vulnerability-scan-2026-03-30.md     # CVEs, hardcoded secrets, dependency risks
+  developer-report-2026-03-30.md       # Team activity, ownership, security attribution
+  test-gaps-2026-03-30.md              # Critical untested code, prioritized by risk
+  docs-audit-2026-03-30.md             # Documentation gaps and recommendations
+  dependency-map-2026-03-30.md         # Import chains, most-depended-on files
+```
+
+Convert to PDF: `/export-pdf all` or `/export-pdf .ai/reports/health-audit-2026-03-30.md`
+
 ## Learning System
 
 DXKit includes a continuous learning system that improves over time:
@@ -146,14 +172,14 @@ DXKit includes a continuous learning system that improves over time:
 1. **Stop Hook** — After each conversation, Claude is reminded to capture learnings
 2. **`/learn` command** — Explicitly save gotchas, conventions, or things to avoid
 3. **`/session-end`** — Creates checkpoint and evolves skill files
-4. **Evolving files** — These files are append-only and never overwritten:
+4. **Evolving files** — Append-only, never overwritten even with `--force`:
    - `.claude/skills/learned/references/gotchas.md`
    - `.claude/skills/learned/references/conventions.md`
    - `.claude/skills/learned/references/deny-recommendations.md`
 
 ## PR Review Automation
 
-DXKit generates a GitHub Action (`.github/workflows/pr-review.yml`) that automatically reviews PRs using Claude Code. Enable it by:
+DXKit generates a GitHub Action that automatically reviews PRs using Claude Code:
 
 1. Set `ENABLE_AI_REVIEW=true` as a GitHub Actions variable
 2. Add `ANTHROPIC_API_KEY` to repo secrets
@@ -162,33 +188,21 @@ Reviews appear as PR comments with issues rated as critical/warning/suggestion.
 
 ## Smart Detection
 
-DXKit goes beyond language detection:
-
-- **Test runner** — Detects Jest, Mocha, Vitest, Ava, Tap, pytest, go test from package.json scripts and dependencies
-- **Framework** — Detects LoopBack, Express, NestJS, FastAPI, Gin, etc. and generates framework-specific rules
-- **Test presence** — Counts test files vs source files and warns about minimal test coverage
-- **Multi-language** — Detects Python from `.py` files even without `pyproject.toml` (common in mixed repos)
+- **Test runner** — Detects Jest, Mocha, Vitest, Ava, Tap, pytest, go test from scripts and dependencies
+- **Framework** — Detects LoopBack, Express, NestJS, FastAPI, Gin, etc. with framework-specific rules
+- **Test presence** — Counts test files vs source files, warns about minimal coverage
+- **Multi-language** — Detects all languages including Python from `.py` files (no config file required)
+- **Language breakdown** — Shows file count per language in codebase skill for accurate analysis
 
 ## CLI Reference
 
 ```bash
-# Initialize (auto-detect stack)
-npx @vyuhlabs/dxkit init --detect
-
-# Initialize (interactive)
-npx @vyuhlabs/dxkit init
-
-# Initialize (everything, no prompts)
-npx @vyuhlabs/dxkit init --full --yes
-
-# Re-generate after config changes (preserves evolved files)
-npx @vyuhlabs/dxkit update
-
-# Re-generate with codebase rescan
-npx @vyuhlabs/dxkit update --rescan
-
-# Verify setup
-npx @vyuhlabs/dxkit doctor
+npx @vyuhlabs/dxkit init --detect        # Auto-detect, minimal prompts
+npx @vyuhlabs/dxkit init                  # Interactive
+npx @vyuhlabs/dxkit init --full --yes     # Everything, no prompts
+npx @vyuhlabs/dxkit update               # Re-generate (preserves evolved files)
+npx @vyuhlabs/dxkit update --rescan      # Re-run codebase analysis
+npx @vyuhlabs/dxkit doctor               # Verify setup
 ```
 
 ### Init Options
@@ -203,56 +217,44 @@ npx @vyuhlabs/dxkit doctor
 | `--name <n>` | Override project name |
 | `--no-scan` | Skip codebase analysis |
 
-## Example: Adding to an Existing Node.js Project
+## Example: Node.js/TypeScript Project
 
 ```bash
-cd my-express-app
+cd my-loopback-app
 npx @vyuhlabs/dxkit init --detect --yes
 ```
 
-This generates:
-- `CLAUDE.md` with Node.js-specific context
-- `.claude/commands/quality.md` with `npx eslint .` and `npx tsc --noEmit`
-- `.claude/commands/test.md` with auto-detected test runner and framework
-- `.claude/rules/` with Node.js + framework-specific conventions
-- `.claude/skills/codebase/SKILL.md` with auto-scanned architecture overview
-- `.github/workflows/pr-review.yml` for automated PR review
-- 3 active agents + 7 dormant agents
+Output:
+```
+✓ Languages: node
+✓ Framework: loopback
+✓ Tests: mocha (npm test)
+✓ Created: 61 files
+```
 
 Then in Claude Code:
 ```
-/help                              # See everything available
-/ask How does the auth middleware work?  # Ask about the codebase
-/quality                           # Run ESLint + TypeScript checks
-/onboarding                        # Get oriented as a new developer
+/help                                    # See everything
+/ask How does the auth middleware work?   # Codebase Q&A
+/health                                  # Full health audit
+/vulnerabilities                         # Security scan
+/dev-report                              # Team activity report
+/quality                                 # ESLint + AI review
+/onboarding                              # New developer guide
 ```
 
-## Example: Adding to a Python + Go Monorepo
+## Example: Multi-Language Repo (Python + Go + TypeScript)
 
 ```bash
 cd my-monorepo
 npx @vyuhlabs/dxkit init --detect --yes
 ```
 
-Detects both languages and generates:
-- Quality commands with ruff + mypy (Python) and golangci-lint (Go)
-- Test commands with pytest + go test
-- Path-scoped rules for both `.py` and `.go` files
-- Language-specific coverage enforcement
-
-## How It Works
-
-1. **Detection** — Scans for config files (`package.json`, `go.mod`, `pyproject.toml`, etc.) to determine languages and tools
-2. **Template Processing** — Processes `.md.template` files through a conditional template engine, stripping irrelevant language sections
-3. **Codebase Scanning** — Analyzes source files to find entry points, API routes, test patterns, and conventions
-4. **Generation** — Writes files non-destructively (never overwrites without `--force`, evolving files always preserved)
-5. **Manifest** — Saves state to `.vyuh-dxkit.json` for `update` and `doctor` commands
-
-## Non-Destructive by Design
-
-- Files that already exist are **skipped** (use `--force` to overwrite)
-- Evolving files (`gotchas.md`, `conventions.md`, `deny-recommendations.md`) are **never overwritten**, even with `--force`
-- The manifest (`.vyuh-dxkit.json`) tracks what was generated for safe updates
+Generates:
+- Quality commands with `npx eslint .` + `ruff check .` + `golangci-lint run`
+- Test commands with `npm test` + `pytest` + `go test`
+- Path-scoped rules for `.ts`, `.py`, and `.go` files
+- Language breakdown in codebase skill: "TypeScript: 200, Python: 50, Go: 30"
 
 ## AI-Assisted Development Workflow
 
@@ -262,11 +264,20 @@ git checkout -b feature/my-feature      # Create branch
 /ask How does the payment flow work?    # Understand the code
 # ... develop with full context ...
 /quality                                # Lint + AI review
-/test                                   # Tests with coverage
+/test                                   # Tests
+/learn auth tokens expire after 24h     # Capture gotcha
 git add -A && git commit                # Commit
 /session-end                            # Checkpoint + evolve skills
 ```
 
+## How It Works
+
+1. **Detection** — Scans for config files, source files, and tools to determine languages, frameworks, and test runners
+2. **Template Processing** — Processes `.md.template` files through a conditional engine, generating language-specific commands
+3. **Codebase Scanning** — Analyzes source files to find entry points, API routes (including LoopBack/Express/FastAPI decorators), test patterns, and language breakdown
+4. **Generation** — Writes 60+ files non-destructively (never overwrites without `--force`, evolving files always preserved)
+5. **Manifest** — Saves state to `.vyuh-dxkit.json` for `update` and `doctor` commands
+
 ## License
 
 MIT

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 import { ResolvedConfig } from './types';
-export declare const VERSION = "0.7.0";
+export declare const VERSION = "0.8.0";
 export declare const DEFAULT_VERSIONS: {
     python: string;
     go: string;

package/dist/constants.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EVOLVING_FILES = exports.DEFAULT_COVERAGE = exports.DEFAULT_VERSIONS = exports.VERSION = void 0;
 exports.buildVariables = buildVariables;
 exports.buildConditions = buildConditions;
-exports.VERSION = '0.7.0';
+exports.VERSION = '0.8.0';
 exports.DEFAULT_VERSIONS = {
     python: '3.12',
     go: '1.24.0',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyuhlabs/dxkit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "AI-native developer experience toolkit for any repository",
   "license": "MIT",
   "bin": {

package/templates/.claude/commands/export-pdf.md

@@ -0,0 +1,30 @@
+---
+description: Convert a markdown report to PDF
+argument-hint: "[file-path or 'all' for all reports]"
+---
+
+Convert markdown report(s) to PDF.
+
+## Arguments
+- `$ARGUMENTS`
+- If empty or "all", convert all reports in `.ai/reports/`
+- If a file path, convert that specific file
+
+## How to Convert
+
+Try these tools in order (use whichever is available):
+
+1. **md-to-pdf** (Node.js): `npx md-to-pdf <file.md>` — creates `<file.pdf>` alongside it
+2. **pandoc**: `pandoc <file.md> -o <file.pdf> --pdf-engine=wkhtmltopdf`
+3. **If neither is available**, install md-to-pdf: `npx md-to-pdf <file.md>`
+
+## For "all" reports
+```
+for f in .ai/reports/*.md; do
+  npx md-to-pdf "$f"
+done
+```
+
+## Output
+- PDFs are saved alongside the markdown files in `.ai/reports/`
+- Report which files were converted and their paths

package/templates/CLAUDE.md.template

@@ -162,6 +162,7 @@ Slash commands for common workflows. Run `/help` to list all with descriptions.
 - `/vulnerabilities` - Scan dependencies and code for security issues
 - `/dev-report` - Developer activity and code quality report
 - `/docs` - Audit, write, or improve documentation
+- `/export-pdf` - Convert markdown reports to PDF
 - `/fix-issue <number>` - Investigate and fix a GitHub issue
 
 ### Rules (`.claude/rules/`)