@vyuhlabs/dxkit 2.4.8 → 2.5.1

package/templates/AGENTS.md.template

@@ -0,0 +1,137 @@
+# {{PROJECT_NAME}}
+
+{{PROJECT_DESCRIPTION}}
+
+## How to use this file
+
+`AGENTS.md` is the open-standard project-context file read by AI coding agents (Claude Code, Codex, Cursor, Aider, …). It describes what this project is, how to run common commands, and the safety rules that apply.
+
+For agent-specific config, see the editor-specific files alongside this one — `CLAUDE.md` (Claude Code), `.cursor/rules` (Cursor), etc. — which point back here for shared context.
+
+## What dxkit does in this repo
+
+This repo is managed by [`@vyuhlabs/dxkit`](https://github.com/vyuh-labs/dxkit). dxkit measures code health across 6 dimensions, captures a per-finding baseline, and gates PRs on net-new regressions.
+
+Six skills are installed under `.claude/skills/` (Claude Code auto-discovers via skill frontmatter):
+
+- **dxkit-learn** — explains dxkit concepts (baselines, dimensions, scanners)
+- **dxkit-init** — interactive setup walkthrough
+- **dxkit-config** — edit `.dxkit-ignore`, `.vyuh-dxkit.json`, policy
+- **dxkit-hooks** — install / troubleshoot git hooks
+- **dxkit-reports** — run analyzers, explain output, dashboard
+- **dxkit-action** — prioritize + fix + verify + re-baseline
+
+Reach for the relevant skill when working in this repo. They wrap the `vyuh-dxkit` CLI with workflow guidance.
+
+{{#IF_PYTHON}}
+## Python {{PYTHON_VERSION}}
+
+- **Tests**: `pytest`
+- **Lint/format**: `ruff check .` / `ruff format .`
+- **Type check**: `mypy src/`
+- **Package config**: `pyproject.toml`
+{{/IF_PYTHON}}
+
+{{#IF_GO}}
+## Go {{GO_VERSION}}
+
+- **Tests**: `go test ./...`
+- **Lint**: `golangci-lint run`
+- **Format**: `gofmt -w .` / `goimports -w .`
+- **Module**: `go.mod`
+{{/IF_GO}}
+
+{{#IF_NODE}}
+## Node.js {{NODE_VERSION}}
+
+- **Tests**: `npm test`
+- **Build**: `npm run build`
+- **Lint/format**: `npx eslint .` / `npx prettier --write .`
+- **Package config**: `package.json`, `tsconfig.json`
+{{/IF_NODE}}
+
+{{#IF_NEXTJS}}
+## Next.js
+
+- **Directory**: `frontend/`
+- **Dev server**: `cd frontend && npm run dev`
+- **Build**: `cd frontend && npm run build`
+- **Lint**: `cd frontend && npm run lint`
+{{/IF_NEXTJS}}
+
+{{#IF_RUST}}
+## Rust {{RUST_VERSION}}
+
+- **Tests**: `cargo test`
+- **Build**: `cargo build` / `cargo build --release`
+- **Lint**: `cargo clippy`
+- **Format**: `cargo fmt`
+- **Package**: `Cargo.toml`
+{{/IF_RUST}}
+
+{{#IF_CSHARP}}
+## C# {{CSHARP_VERSION}}
+
+- **Tests**: `dotnet test`
+- **Build**: `dotnet build` / `dotnet publish -c Release`
+- **Format**: `dotnet format`
+- **Solution**: `*.sln`, projects under `*.csproj`
+{{/IF_CSHARP}}
+
+{{#IF_KOTLIN}}
+## Kotlin {{KOTLIN_VERSION}}
+
+- **Tests**: `./gradlew test`
+- **Build**: `./gradlew build`
+- **Lint**: `detekt`
+- **Package**: `build.gradle.kts` / `settings.gradle.kts`
+{{/IF_KOTLIN}}
+
+{{#IF_JAVA}}
+## Java {{JAVA_VERSION}}
+
+- **Tests**: `mvn test` / `./gradlew test`
+- **Build**: `mvn package` / `./gradlew build`
+- **Lint**: `pmd`
+- **Package**: `pom.xml` / `build.gradle`
+{{/IF_JAVA}}
+
+{{#IF_RUBY}}
+## Ruby {{RUBY_VERSION}}
+
+- **Tests**: `bundle exec rspec` / `bundle exec rails test`
+- **Lint**: `bundle exec rubocop`
+- **Coverage**: SimpleCov (loaded from `spec_helper.rb`)
+- **Package**: `Gemfile`
+{{/IF_RUBY}}
+
+## dxkit commands
+
+| Purpose | Command |
+|---|---|
+| Overall health (6 dimensions) | `npx vyuh-dxkit health` |
+| Deep security scan | `npx vyuh-dxkit vulnerabilities` |
+| Test coverage gaps | `npx vyuh-dxkit test-gaps` |
+| Code quality + slop | `npx vyuh-dxkit quality` |
+| Bill of materials | `npx vyuh-dxkit bom` |
+| Dashboard (HTML) | `npx vyuh-dxkit dashboard` |
+| Guardrail check (baseline diff) | `npx vyuh-dxkit guardrail check` |
+| Doctor (verify setup) | `npx vyuh-dxkit doctor` |
+
+The pre-push hook runs `guardrail check` automatically — blocks net-new regressions before they leave your machine.
+
+## Security rules — never violate
+
+1. **Never output, log, or commit secrets** — no API keys, tokens, passwords, or credentials in code, commits, or files Claude writes
+2. **Never read `.env` directly** — to confirm a variable exists, grep for the variable name only
+3. **Never pass secrets as CLI arguments** — they appear in process lists and shell history
+4. **Never include secrets in build args or Dockerfiles**
+5. **Sensitive files are gitignored**: `.env`, `.env.*`, `.env.secrets`, `.claude/settings.local.json`
+6. **Before committing**: verify no secrets in staged files (`git diff --cached`)
+
+## Conventions
+
+- Run `npx vyuh-dxkit health` before opening a PR
+- For changes to risky areas (auth, payments, data mutations), write tests first
+- Capture surprising behaviors as comments in `.dxkit-ignore` or the relevant skill file
+- Pre-push hook will block net-new regressions — fix them in the same PR or accept-as-baseline with a commit message explaining why

package/templates/CLAUDE.md.template

@@ -1,255 +1,26 @@
-# {{PROJECT_NAME}}
+# {{PROJECT_NAME}} — Claude Code config
 
-{{PROJECT_DESCRIPTION}}
+Project context lives in [`AGENTS.md`](./AGENTS.md) (open-standard, read by every coding agent). This file is Claude-Code-specific config that points at it.
 
-## Architecture
+Whenever Claude Code starts a session in this repo, it reads BOTH files: this one (Claude-specific shortcuts) and `AGENTS.md` (project prose).
 
-- Monorepo with make-based task runner
-- Configuration driven by `.project.yaml` (single source of truth)
-- Quality checks, testing, and formatting enforced via `make check`
+## dxkit skills
 
-## Quick Reference
+Six dxkit-specific skills are installed under `.claude/skills/`. Claude Code auto-discovers them via their frontmatter `description` fields:
 
-### Setup & Diagnostics
-- `make setup` - Interactive setup for new developers
-- `make doctor` - Diagnose common setup issues
-- `make info` - Show project configuration dashboard
-- `make config` - Interactive configuration editor
+- `dxkit-learn` — explain what dxkit does, what scores mean, what scanners run
+- `dxkit-init` — walk through `vyuh-dxkit init` flag choices
+- `dxkit-config` — edit `.dxkit-ignore` / `.vyuh-dxkit.json` / policy
+- `dxkit-hooks` — install / troubleshoot git hooks
+- `dxkit-reports` — run analyzers + read output
+- `dxkit-action` — prioritize + fix + verify + re-baseline
 
-### Code Quality
-- `make quality` - Run all quality checks (report: tmp/reports/quality-report.md)
-- `make quality-fix` - Auto-fix issues
-- `make lint` - Lint all code
-- `make format` - Format all code
-- `make fix` - Fix all auto-fixable issues (quality-fix + format)
-- `make check` - Full pre-commit check (validate + quality + test)
+When the user asks about dxkit concepts or wants to run an analyzer, reach for the matching skill before improvising.
 
-### Testing
-- `make test` - Run all tests (report: tmp/reports/test-report.md)
-- `make test-unit` - Fast unit tests only
-- `make test-coverage` - Detailed coverage report
-- Coverage threshold: {{COVERAGE_THRESHOLD}}%
+## Per-language rules
 
-### Build & Development
-- `make build` - Build all services
-- `make clean` - Remove build artifacts
-- `make dev` - Start all services (docker-compose up)
-- `make stop` - Stop all services
+`.claude/rules/<lang>.md` files carry per-language conventions for any active language pack. They're loaded automatically.
 
-### Session Workflow
-- `make session-start` - Start AI-assisted development session
-- `make session-end` - End session and create checkpoint
-- `make session-commit` - Commit with quality checks
-- `make session-push` - Push to remote
-- `make session-pr` - Create PR with auto-generated content
+## Security rules + per-language commands
 
-{{#IF_INFISICAL}}
-### Secrets Management
-- `make secrets-pull` - Pull secrets from Infisical to .env
-- `make secrets-show` - Show Infisical configuration (no secrets displayed)
-{{/IF_INFISICAL}}
-
-### Configuration
-- `make lang-list` - Show enabled languages
-- `make lang-add LANG=<name>` - Enable a language
-- `make lang-remove LANG=<name>` - Disable a language
-- `make sync` - Sync .project.yaml to language config files
-
-### Code Generation
-- `make generate` - Generate all code
-- `make validate` - Validate generated code is up-to-date
-
-{{#IF_PYTHON}}
-## Python {{PYTHON_VERSION}}
-
-- **Source:** `src/` or `services/python/`
-- **Linter/Formatter:** ruff (config: `ruff.toml`, `pyproject.toml`)
-- **Type checker:** mypy
-- **Tests:** pytest (config: `pytest.ini`)
-- **Package config:** `pyproject.toml`
-- Run quality: `.project/scripts/quality/lint-python.sh`
-{{/IF_PYTHON}}
-
-{{#IF_GO}}
-## Go {{GO_VERSION}}
-
-- **Source:** `services/go/`
-- **Linter:** golangci-lint (config: `.golangci.yml`)
-- **Formatter:** gofmt + goimports
-- **Tests:** `go test ./...`
-- **Module:** `go.mod`
-- Run quality: `.project/scripts/quality/lint-go.sh`
-{{/IF_GO}}
-
-{{#IF_NODE}}
-## Node.js {{NODE_VERSION}}
-
-- **Package:** `package.json`, `tsconfig.json`
-- **Linter:** ESLint
-- **Formatter:** Prettier
-- **Tests:** npm test
-{{/IF_NODE}}
-
-{{#IF_NEXTJS}}
-## Next.js
-
-- **Directory:** `frontend/`
-- **Stack:** App Router + TypeScript + Tailwind CSS
-- **Build:** `cd frontend && npm run build`
-- **Lint:** `cd frontend && npm run lint`
-{{/IF_NEXTJS}}
-
-{{#IF_RUST}}
-## Rust {{RUST_VERSION}}
-
-- **Package:** `Cargo.toml`
-- **Linter:** clippy
-- **Formatter:** rustfmt
-- **Tests:** `cargo test`
-{{/IF_RUST}}
-
-{{#IF_CSHARP}}
-## C# {{CSHARP_VERSION}}
-
-- **Source:** `src/` or `services/csharp/`
-- **Solution:** `*.sln`
-- **Project:** `*.csproj`
-- **Linter/Analyzer:** Roslyn Analyzers, StyleCop Analyzers
-- **Formatter:** `dotnet format`
-- **Tests:** `dotnet test` (xUnit)
-{{/IF_CSHARP}}
-
-{{#IF_GCLOUD}}
-## Google Cloud
-
-- **Auth:** `gcloud auth login` (interactive setup via `make setup`)
-- **Project:** Set in `.env` as `GOOGLE_CLOUD_PROJECT`
-- **SDK:** Installed via devcontainer post-create script
-{{/IF_GCLOUD}}
-
-{{#IF_PULUMI}}
-## Pulumi
-
-- **Auth:** `pulumi login`
-- **Workflow:** Always `pulumi preview` before `pulumi up`
-- **Secrets:** Use `pulumi config set --secret` for sensitive values
-{{/IF_PULUMI}}
-
-## Claude Code Integration
-
-### Skills (`.claude/skills/`)
-Domain-specific context loaded on demand. Check skill descriptions before starting work.
-- `.claude/skills/learned/references/gotchas.md` - Known project gotchas
-- `.claude/skills/learned/references/conventions.md` - Team conventions
-
-### Commands (`.claude/commands/`)
-Slash commands for common workflows. Run `/help` to list all with descriptions.
-- `/session-start` - Start dev session
-- `/session-end` - End session with checkpoint
-- `/ask <question>` - Ask about the codebase
-- `/explore-codebase` - Deep architecture exploration
-- `/onboarding` - Generate first-day developer guide
-- `/enable-agent <name>` - Activate a dormant agent
-- `/help` - List all commands and agents
-- `/quality` - Run quality checks (language-aware)
-- `/setup-hooks` - Install git pre-commit/pre-push hooks
-- `/learn` - Capture a gotcha, convention, or thing to avoid
-- `/test` - Run tests
-- `/setup-pr-review` - Set up automated PR review with Claude Code
-- `/test-gaps` - Find critical untested code paths
-- `/deps` - Map dependencies ("what breaks if I change X?")
-- `/health` - Comprehensive codebase health audit
-- `/vulnerabilities` - Scan dependencies and code for security issues
-- `/dev-report` - Developer activity and code quality report
-- `/docs` - Audit, write, or improve documentation
-- `/plan` - Generate improvement plans with KPIs from reports (fix loop)
-- `/execute-plan` - Execute a plan task by task with session management
-- `/feature` - Design and plan a new feature
-- `/build-feature` - Build a feature from a plan with tests
-- `/dashboard` - Generate HTML dashboard from all reports
-- `/stealth-mode` - Gitignore DXKit files + install smart scoped git hooks
-- `/export-pdf` - Convert markdown reports to PDF
-- `/fix-issue <number>` - Investigate and fix a GitHub issue
-
-### Rules (`.claude/rules/`)
-Language-specific conventions that activate automatically when editing matching files.
-
-### Agents
-**Active** (`.claude/agents/`) — auto-triggered when your question matches:
-- `knowledge-bot` — Answers codebase questions with file:line references (sonnet, read-only)
-- `onboarding` — Interactive onboarding buddy for new developers (sonnet, read-only)
-- `quality-reviewer` — Reviews changed code for issues before committing (sonnet)
-- `doc-writer` — Audits docs, identifies gaps, writes/improves documentation (sonnet)
-
-**Dormant** (`.claude/agents-available/`) — activate with `/enable-agent <name>`:
-- `codebase-explorer` — Deep architecture analysis, generates codebase skill (sonnet, read-only)
-- `code-reviewer` — Read-only PR review and security audit (sonnet, no write access)
-- `test-writer` — Writes tests for existing code (sonnet)
-- `test-gap-finder` — Identifies critical untested code paths (sonnet, read-only)
-- `dependency-mapper` — Maps import chains and blast radius (sonnet, read-only)
-- `health-auditor` — Comprehensive codebase health audit (sonnet, read-only)
-- `vulnerability-scanner` — Dependency and code vulnerability analysis (sonnet)
-- `dev-report` — Developer activity, quality patterns, security attribution (sonnet)
-- `dashboard-builder` — Generates HTML dashboard from all reports (sonnet)
-- `strategic-planner` — Analyzes reports, proposes KPIs, generates improvement plans (sonnet)
-- `plan-executor` — Executes plans task by task with session checkpoints (sonnet)
-- `feature-planner` — Designs new features, generates implementation plans (sonnet)
-- `feature-builder` — Implements features from plans with tests and conventions (sonnet)
-- `hooks-configurator` — Configures scoped git hooks from DXKit commands (sonnet)
-- `doc-writer` — Audits docs, identifies gaps, writes/improves documentation (sonnet)
-- `debugger` — Traces root causes systematically (sonnet, no file edits)
-
-## AI-Assisted Development Workflow
-
-```
-# 1. Start a session
-/session-start
-
-# 2. Create a feature branch
-git checkout -b feature/your-feature
-
-# 3. Ask questions as you go
-/ask How does the auth middleware work?
-
-# 4. Develop — Claude has full project context via skills
-
-# 5. Run checks before committing
-/quality
-/test
-
-# 6. Commit and push
-git add -A && git commit -m "feat: your feature"
-git push -u origin feature/your-feature
-
-# 7. End session (creates checkpoint + evolves skills)
-/session-end
-```
-
-## Security
-
-**Critical rules — never violate these:**
-
-1. **Never output, log, or commit secrets** — no API keys, tokens, passwords, or credentials in code, commits, checkpoints, or skill files
-2. **Never read `.env` directly** — use `make secrets-show` (which masks values) to check configuration
-3. **Never pass secrets as CLI arguments** — they appear in process lists and shell history
-4. **Never include secrets in build args or Dockerfiles**
-5. **Sensitive files are gitignored:** `.env`, `.env.*`, `.env.secrets`, `.claude/settings.local.json`
-6. **Before committing:** verify no secrets in staged files (`git diff --cached`)
-{{#IF_INFISICAL}}
-7. **Infisical tokens:** never output `INFISICAL_TOKEN` values; use `make secrets-show` to verify config
-{{/IF_INFISICAL}}
-{{#IF_GCLOUD}}
-8. **GCP credentials:** never output `gcloud auth print-access-token` or service account JSON keys
-{{/IF_GCLOUD}}
-
-## Conventions
-
-- Run quality checks before committing (`/quality` or `make quality`)
-- Use `/session-start` to begin work, `/session-end` to checkpoint
-- All code changes should pass quality + test checks
-{{#IF_PRECOMMIT}}
-- Pre-commit hooks run automatically on `git commit`
-{{/IF_PRECOMMIT}}
-- Keep session checkpoints in `.ai/sessions/<developer>/<date>/`
-- Skills evolve over time — gotchas and conventions are captured during `/session-end`
-- Check `/help` for all available commands and agents
+See [`AGENTS.md`](./AGENTS.md). All shared project context lives there so other agents (Codex / Cursor / Aider) get the same instructions Claude does.

package/dist/codebase-scanner.d.ts

@@ -1,36 +0,0 @@
-export interface CodebaseAnalysis {
-    entryPoints: {
-        file: string;
-        type: string;
-    }[];
-    directories: {
-        path: string;
-        purpose: string;
-    }[];
-    testPatterns: {
-        framework: string;
-        location: string;
-        pattern: string;
-    }[];
-    apiEndpoints: {
-        method: string;
-        path: string;
-        file: string;
-    }[];
-    configFiles: {
-        file: string;
-        purpose: string;
-    }[];
-    conventions: {
-        pattern: string;
-        description: string;
-    }[];
-    fileCount: number;
-    testFileCount: number;
-    sourceFileCount: number;
-    languageBreakdown: Record<string, number>;
-}
-export declare function scanCodebase(cwd: string): CodebaseAnalysis;
-export declare function renderCodebaseSkill(analysis: CodebaseAnalysis): string;
-export declare function renderArchitectureRef(analysis: CodebaseAnalysis): string;
-//# sourceMappingURL=codebase-scanner.d.ts.map

package/dist/codebase-scanner.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"codebase-scanner.d.ts","sourceRoot":"","sources":["../src/codebase-scanner.ts"],"names":[],"mappings":"AAoDA,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9C,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjD,YAAY,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzE,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC/D,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACjD,WAAW,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AA6eD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAmD1D;AAID,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAgGtE;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAmDxE"}