docguard-cli 0.5.1

package/docs/commands.md

@@ -0,0 +1,239 @@
+# Commands Reference
+
+DocGuard v0.5.0 — 13 commands, zero dependencies.
+
+## The AI Loop
+
+```
+diagnose (identify + fix)  →  AI executes  →  guard (verify)
+```
+
+`diagnose` is the primary command. `guard` is the CI gate.
+
+---
+
+## Primary Commands
+
+### `docguard diagnose` (alias: `dx`)
+
+**The AI orchestrator.** Runs all validators, maps every failure to an AI fix prompt, outputs a remediation plan.
+
+```bash
+npx docguard diagnose                # Human-readable remediation plan
+npx docguard diagnose --format json  # Structured for automation
+npx docguard diagnose --format prompt # Raw AI prompt (all issues combined)
+```
+
+**JSON output includes:**
+- `issues[]` — severity, validator, message, fix command
+- `fixCommands[]` — unique commands to run
+- `score` — current CDD maturity score
+- `grade` — letter grade (A+ to F)
+
+### `docguard guard`
+
+**Identify issues.** Validate project against canonical docs. Use for CI gates and pre-commit hooks.
+
+```bash
+npx docguard guard                   # Text output
+npx docguard guard --format json     # Structured JSON
+npx docguard guard --verbose         # Show all check details
+```
+
+**Exit codes:** `0` (pass), `1` (errors), `2` (warnings)
+
+When issues are found, guard outputs: `Run docguard diagnose to get AI fix prompts.`
+
+**JSON output includes:**
+```json
+{
+  "project": "my-app",
+  "profile": "standard",
+  "status": "WARN",
+  "passed": 37,
+  "total": 40,
+  "validators": [
+    { "name": "Structure", "status": "pass", "passed": 8, "total": 8, "errors": [], "warnings": [] }
+  ]
+}
+```
+
+### `docguard score`
+
+**CDD maturity score** (0-100) with category breakdown.
+
+```bash
+npx docguard score                   # Visual bar chart
+npx docguard score --format json     # Structured JSON
+npx docguard score --tax             # Documentation tax estimate
+```
+
+**`--tax` output:**
+```
+📋 Documentation Tax Estimate
+─────────────────────────────────
+Tracked docs:        7 files
+Active profile:      standard
+Est. maintenance:    ~5 min/week
+Tax-to-value ratio:  LOW
+```
+
+**Grades:** A+ (95+), A (80+), B (65+), C (50+), D (30+), F (<30)
+
+---
+
+## Setup Commands
+
+### `docguard init`
+
+**Initialize CDD documentation** from templates.
+
+```bash
+npx docguard init                           # Full CDD (standard profile)
+npx docguard init --profile starter         # Minimal: ARCHITECTURE + CHANGELOG
+npx docguard init --profile enterprise      # Everything + strict validators
+npx docguard init --dir /path/to/project    # Specify directory
+npx docguard init --skip-prompts            # No AI prompt output
+```
+
+**Profiles:**
+
+| Profile | Docs Created | Validators |
+|---------|-------------|------------|
+| `starter` | ARCHITECTURE, CHANGELOG, AGENTS, DRIFT-LOG | structure, docsSync, changelog |
+| `standard` | All 5 canonical + tracking | Most validators (default) |
+| `enterprise` | All docs | All validators + freshness |
+
+### `docguard generate`
+
+**Reverse-engineer docs from existing code.** Scans your codebase and creates pre-filled documentation.
+
+```bash
+npx docguard generate
+npx docguard generate --dir /path/to/project
+```
+
+**Detects:** Next.js, React, Vue, Angular, Express, Fastify, Hono, Django, FastAPI, SvelteKit, and more.
+
+### `docguard audit`
+
+**Scan and report** which CDD documents exist, are missing, or need attention.
+
+```bash
+npx docguard audit
+```
+
+---
+
+## AI Integration Commands
+
+### `docguard fix`
+
+**Find issues and generate AI fix instructions.**
+
+```bash
+npx docguard fix                    # Human-readable issue list
+npx docguard fix --format json      # Machine-readable for VS Code/CI
+npx docguard fix --format prompt    # AI-ready prompt
+npx docguard fix --auto             # Create missing skeleton files
+```
+
+### `docguard fix --doc <name>`
+
+**Generate a deep AI research prompt** for a specific document.
+
+```bash
+npx docguard fix --doc architecture
+npx docguard fix --doc data-model
+npx docguard fix --doc security
+npx docguard fix --doc test-spec
+npx docguard fix --doc environment
+```
+
+**Output includes:** TASK, PURPOSE, RESEARCH STEPS (what to grep/read), WRITE THE DOCUMENT (expected sections).
+
+### `docguard agents`
+
+**Generate agent-specific config files** from AGENTS.md.
+
+```bash
+npx docguard agents
+npx docguard agents --list
+```
+
+---
+
+## DevOps Commands
+
+### `docguard ci`
+
+**Single command for CI/CD pipelines.** Runs guard + score internally (no subprocess).
+
+```bash
+npx docguard ci                              # Basic check
+npx docguard ci --threshold 70               # Fail below score 70
+npx docguard ci --threshold 80 --fail-on-warning  # Strict mode
+npx docguard ci --format json                # JSON for GitHub Actions
+```
+
+### `docguard hooks`
+
+**Install git hooks** for automatic validation.
+
+```bash
+npx docguard hooks              # Install all hooks
+npx docguard hooks --list       # Show installed hooks
+npx docguard hooks --remove     # Remove hooks
+```
+
+**Hooks installed:**
+- `pre-commit` → runs `docguard guard`
+- `pre-push` → runs `docguard score` with threshold
+- `commit-msg` → validates conventional commit format
+
+### `docguard watch`
+
+**Live watch mode** — re-runs guard on file changes.
+
+```bash
+npx docguard watch              # Watch and re-run guard
+npx docguard watch --auto-fix   # Also output AI fix prompts on failure
+```
+
+### `docguard badge`
+
+**Generate shields.io badges** for README.
+
+```bash
+npx docguard badge
+npx docguard badge --format json
+```
+
+### `docguard diff`
+
+**Show gaps** between documentation and actual codebase.
+
+```bash
+npx docguard diff
+```
+
+---
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--dir <path>` | Project directory (default: current directory) |
+| `--format <type>` | Output format: `text` (default), `json`, `prompt` |
+| `--verbose` | Show detailed output |
+| `--profile <name>` | Compliance profile: `starter`, `standard`, `enterprise` |
+| `--tax` | Show documentation tax estimate (with `score`) |
+| `--auto-fix` | Output AI fix prompts on failure (with `watch`) |
+| `--skip-prompts` | Suppress AI prompts after init |
+| `--auto` | Auto-fix issues (with `fix` command) |
+| `--doc <name>` | Target specific document (with `fix` command) |
+| `--threshold <n>` | Minimum score for CI pass (with `ci` command) |
+| `--fail-on-warning` | Fail CI on warnings (with `ci` command) |
+| `--force` | Overwrite existing files |
+| `--help` | Show help |
+| `--version` | Show version |

package/docs/configuration.md

@@ -0,0 +1,96 @@
+# Configuration
+
+DocGuard is configured via `.docguard.json` in the project root. If no config file exists, sensible defaults are used with auto-detection.
+
+## Full Reference
+
+```json
+{
+  "projectName": "my-project",
+  "version": "0.5",
+  "profile": "standard",
+  "projectType": "webapp",
+
+  "requiredFiles": {
+    "canonical": [
+      "docs-canonical/ARCHITECTURE.md",
+      "docs-canonical/DATA-MODEL.md",
+      "docs-canonical/SECURITY.md",
+      "docs-canonical/TEST-SPEC.md",
+      "docs-canonical/ENVIRONMENT.md"
+    ],
+    "agentFile": ["AGENTS.md", "CLAUDE.md"],
+    "changelog": "CHANGELOG.md",
+    "driftLog": "DRIFT-LOG.md"
+  },
+
+  "projectTypeConfig": {
+    "needsEnvVars": true,
+    "needsEnvExample": true,
+    "needsE2E": true,
+    "needsDatabase": true,
+    "testFramework": "vitest",
+    "runCommand": "npm run dev"
+  },
+
+  "validators": {
+    "structure": true,
+    "docsSync": true,
+    "drift": true,
+    "changelog": true,
+    "architecture": true,
+    "testSpec": true,
+    "security": true,
+    "environment": true,
+    "freshness": true
+  }
+}
+```
+
+## Profile Field
+
+The `profile` field sets a baseline preset. User config overrides profile defaults.
+
+| Profile | Description | Validators Enabled |
+|---------|-------------|-------------------|
+| `starter` | Minimal CDD — ARCHITECTURE + CHANGELOG | structure, docsSync, changelog |
+| `standard` | Full CDD — all 5 canonical docs (default) | Most validators |
+| `enterprise` | Strict — all docs + all validators | All validators + freshness |
+
+See [Profiles](./profiles.md) for details.
+
+## Validators
+
+| Validator | Default | What It Checks |
+|-----------|---------|----------------|
+| `structure` | `true` | `docs-canonical/` exists, required files present, expected sections |
+| `docsSync` | `true` | AGENTS.md references DocGuard workflow |
+| `drift` | `true` | DRIFT-LOG.md exists and has entries when code deviates |
+| `changelog` | `true` | CHANGELOG.md has [Unreleased] section, version entries |
+| `architecture` | varies | Component map, layer boundaries, import graph analysis |
+| `testSpec` | `true` | Test framework, coverage, critical flows documented |
+| `security` | varies | Auth, secrets, RBAC documentation |
+| `environment` | `true` | Setup steps, env vars, prerequisites, .env.example |
+| `freshness` | varies | Docs updated recently relative to code changes (git-based) |
+
+## Project Type Detection
+
+DocGuard auto-detects your project type from `package.json`:
+
+| Signal | Detected Type |
+|--------|--------------|
+| `bin` field | `cli` |
+| `next`, `react`, `vue`, `angular`, `svelte` | `webapp` |
+| `express`, `fastify`, `hono`, `koa` | `api` |
+| `main`, `exports`, `module` | `library` |
+| `manage.py` | `webapp` (Django) |
+| `pyproject.toml` | `library` (Python) |
+
+## Project Type Defaults
+
+| Type | Env Vars | .env.example | E2E | Database |
+|------|----------|-------------|-----|----------|
+| `cli` | ✗ | ✗ | ✗ | ✗ |
+| `library` | ✗ | ✗ | ✗ | ✗ |
+| `webapp` | ✓ | ✓ | ✓ | ✓ |
+| `api` | ✓ | ✓ | ✗ | ✓ |

package/docs/faq.md

@@ -0,0 +1,155 @@
+# Frequently Asked Questions
+
+## General
+
+### What is DocGuard?
+
+DocGuard is an AI-native CLI tool that enforces Canonical-Driven Development (CDD). It ensures your project documentation stays accurate, comprehensive, and in sync with your code — using AI to write and maintain the docs.
+
+### What is CDD?
+
+Canonical-Driven Development is a methodology where documentation is the source of truth. Instead of writing code first and documenting later (which leads to "document rot"), CDD enforces that documentation exists, is structured, and stays fresh.
+
+### Does DocGuard write documentation for me?
+
+**No — but it tells AI what to write.** DocGuard generates structured research prompts that AI agents execute. The AI reads your codebase, writes the documentation, and DocGuard verifies it's correct. Your role: review what the AI wrote.
+
+### What's the difference between DocGuard and just writing docs manually?
+
+DocGuard adds three things:
+1. **Structure** — Enforces consistent doc templates across all projects
+2. **Enforcement** — Validates docs exist, have required sections, stay fresh
+3. **AI automation** — Generates prompts so AI writes the docs, not humans
+
+---
+
+## Commands
+
+### What's the most important command?
+
+**`docguard diagnose`** — it's the primary command. It runs all checks, identifies every issue, and generates AI fix prompts in a single output. Start here.
+
+### What's the difference between `guard` and `diagnose`?
+
+| Command | Purpose | When to use |
+|---------|---------|-------------|
+| `guard` | Identify issues (pass/fail gate) | CI pipelines, pre-commit hooks |
+| `diagnose` | Identify + generate fix prompts | Development, AI agents, fixing docs |
+
+`diagnose` runs `guard` internally and adds the fix layer on top.
+
+### What's the difference between `fix` and `diagnose`?
+
+`fix` generates prompts for individual documents (`fix --doc architecture`). `diagnose` runs everything at once and outputs a combined remediation plan. Use `diagnose` for a full health check; use `fix --doc` when you know exactly which doc needs work.
+
+### What does `generate` do that `init` doesn't?
+
+`init` creates empty skeleton templates. `generate` scans your existing codebase and creates pre-filled docs with real content (detected components, routes, env vars, etc.).
+
+---
+
+## Profiles
+
+### What profile should I use?
+
+| Situation | Profile |
+|-----------|---------|
+| Side project, tutorial, prototype | `starter` |
+| Team project, active development | `standard` (default) |
+| Regulated, enterprise, compliance | `enterprise` |
+
+### Can I switch profiles later?
+
+Yes. Change the `"profile"` field in `.docguard.json` and run `docguard diagnose` to see what's missing.
+
+### Can I override specific validators within a profile?
+
+Yes. Profile sets the baseline, your config overrides:
+
+```json
+{
+  "profile": "starter",
+  "validators": {
+    "freshness": true
+  }
+}
+```
+
+---
+
+## Document Tax
+
+### What is "document tax"?
+
+The time and effort required to maintain documentation. Too little documentation leads to "document rot" (stale, useless docs). Too much enforcement creates "document tax" (developers spend more time on docs than code).
+
+### How does DocGuard avoid document tax?
+
+1. **AI writes the docs** — human cost drops to near-zero
+2. **Compliance profiles** — choose the right level for your project
+3. **`score --tax`** — measures your actual maintenance cost
+4. **Smart enforcement** — only flags when relevant code changed
+
+### What does `score --tax` show?
+
+```
+📋 Documentation Tax Estimate
+─────────────────────────────────
+Tracked docs:        7 files
+Active profile:      standard
+Est. maintenance:    ~5 min/week
+Tax-to-value ratio:  LOW
+```
+
+If tax is HIGH, consider using `starter` profile or letting AI handle more.
+
+---
+
+## CI/CD
+
+### How do I add DocGuard to CI?
+
+```bash
+npx docguard ci --format json --threshold 70
+```
+
+Exit code 0 = pass, 1 = fail. Use `--threshold` to set minimum score.
+
+### Is there a GitHub Action?
+
+Yes — DocGuard ships a template at `templates/ci/github-actions.yml`. Copy it to `.github/workflows/` or use the reusable action in `action.yml`.
+
+### Does DocGuard block commits?
+
+Only if you install hooks (`docguard hooks`). Without hooks, it's advisory only.
+
+---
+
+## Technical
+
+### Does DocGuard have dependencies?
+
+**Zero.** Pure Node.js, no npm dependencies. Works with Node.js 18+.
+
+### Does it work with non-JavaScript projects?
+
+Yes. DocGuard validates documentation structure, not code. It works with any project that has a `docs-canonical/` directory. Some validators (architecture import analysis) are JavaScript-focused, but the core CDD framework is language-agnostic.
+
+### Does DocGuard read my code?
+
+Yes — for features like `generate`, `diff`, and `architecture` validation. It reads local files only. No data is sent anywhere.
+
+### Can I disable validators I don't need?
+
+Yes. In `.docguard.json`:
+
+```json
+{
+  "validators": {
+    "security": false,
+    "freshness": false
+  }
+}
+```
+
+Or use a profile that has them disabled by default (like `starter`).

package/docs/installation.md

@@ -0,0 +1,81 @@
+# Installation
+
+## Requirements
+
+- **Node.js** ≥ 18
+- **git** (optional — needed for freshness validation)
+
+## Install via npx (Recommended)
+
+No installation needed. Run directly:
+
+```bash
+npx docguard --help
+```
+
+This downloads and runs DocGuard on demand. Always uses the latest version.
+
+## Install as Dev Dependency
+
+For projects that want a pinned version:
+
+```bash
+npm install --save-dev docguard
+```
+
+Then use via npm scripts in `package.json`:
+
+```json
+{
+  "scripts": {
+    "guard": "docguard guard",
+    "score": "docguard score",
+    "lint:docs": "docguard ci --threshold 70"
+  }
+}
+```
+
+## Install Globally
+
+```bash
+npm install -g docguard
+```
+
+Then use anywhere:
+
+```bash
+docguard guard
+docguard score
+```
+
+## Verify Installation
+
+```bash
+npx docguard --version
+```
+
+Should output `DocGuard v0.4.0` (or current version).
+
+## CI/CD Installation
+
+In GitHub Actions or similar:
+
+```yaml
+- name: Run DocGuard
+  run: npx docguard ci --threshold 70
+```
+
+No separate install step needed — `npx` handles it.
+
+## Upgrading
+
+```bash
+# If installed as dev dependency
+npm update docguard
+
+# If installed globally
+npm update -g docguard
+
+# If using npx — always runs latest automatically
+npx docguard@latest --version
+```

package/docs/profiles.md

@@ -0,0 +1,103 @@
+# Compliance Profiles
+
+DocGuard supports three compliance profiles to match different project needs.
+
+## The Problem: Document Tax
+
+Requiring all 5 canonical docs for a weekend side project is overkill. Requiring only ARCHITECTURE.md for a regulated enterprise app is dangerous. Profiles solve this.
+
+## Profiles
+
+### `starter` — For side projects and prototypes
+
+```bash
+npx docguard init --profile starter
+```
+
+**Creates:** ARCHITECTURE.md, CHANGELOG.md, AGENTS.md, DRIFT-LOG.md
+
+**Validators enabled:** structure, docsSync, changelog
+
+**Validators disabled:** drift, architecture, testSpec, security, environment, freshness
+
+**Use when:** Solo projects, hackathons, learning projects, anything where "some docs" beats "no docs."
+
+### `standard` — For team projects (default)
+
+```bash
+npx docguard init                    # default profile
+npx docguard init --profile standard # explicit
+```
+
+**Creates:** All 5 canonical docs + AGENTS.md + CHANGELOG.md + DRIFT-LOG.md
+
+**Validators enabled:** structure, docsSync, drift, changelog, testSpec, environment, freshness
+
+**Validators disabled:** architecture (deep import analysis), security (secrets scanning)
+
+**Use when:** Active team projects, repos with 3+ contributors, anything that will live longer than a sprint.
+
+### `enterprise` — For regulated and critical projects
+
+```bash
+npx docguard init --profile enterprise
+```
+
+**Creates:** All 5 canonical docs + all tracking files
+
+**Validators enabled:** ALL — including architecture (import graph), security (secrets), and freshness
+
+**Use when:** Regulated industries, SOC2/HIPAA compliance, mission-critical production systems, enterprise monorepos.
+
+## Setting a Profile
+
+### At init time
+
+```bash
+npx docguard init --profile starter
+```
+
+### In `.docguard.json`
+
+```json
+{
+  "profile": "enterprise"
+}
+```
+
+### Overriding specific validators
+
+Profiles set defaults, but you can override anything:
+
+```json
+{
+  "profile": "starter",
+  "validators": {
+    "freshness": true
+  }
+}
+```
+
+This uses the starter baseline but enables freshness checks.
+
+## Graduating Between Profiles
+
+As your project grows:
+
+```
+starter  →  standard  →  enterprise
+```
+
+1. Start with `starter` — just ARCHITECTURE + CHANGELOG
+2. When your team grows, switch to `standard` — add all 5 docs
+3. When you need compliance, switch to `enterprise` — enable all validators
+
+Change the `"profile"` field in `.docguard.json` and run `docguard diagnose` to see what's missing.
+
+## Measuring the Cost
+
+```bash
+npx docguard score --tax
+```
+
+Shows estimated weekly maintenance time. If the tax is HIGH, consider downgrading your profile. If LOW, you might benefit from upgrading.