@ccdevkit/ccaudit 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,205 @@
+# ccaudit
+
+Audit tool for Claude Code projects. Runs compliance checks on code and agent actions from `.ccaudit/audits/` directories.
+
+## Installation
+
+```bash
+# Via npm (recommended)
+npm install -g @ccdevkit/ccaudit
+
+# Via Go
+go install github.com/ccdevkit/ccaudit/cmd/ccaudit@latest
+```
+
+## Quick Start
+
+```bash
+# List available audits
+ccaudit list
+
+# Run an audit
+ccaudit run security
+
+# Run with verbose output
+ccaudit run security -v
+```
+
+## Concepts
+
+### Audit
+
+An audit is a named collection of checks. An audit is defined by a directory in `.ccaudit/audits/{name}/` containing an `audit.yaml` file. The directory name becomes the audit name.
+
+```
+.ccaudit/audits/
+├── security/
+│   ├── audit.yaml       # Required - defines the audit
+│   ├── check-secrets.sh # Shell check
+│   └── check-xss.md     # Agent check
+└── quality/
+    └── audit.yaml
+```
+
+### Check
+
+A check is an individual verification test. Two types exist:
+
+**Shell checks** (`.sh` files): Execute shell scripts. Exit code 0 = pass, 1 = fail. Stdout on failure becomes the failure reason.
+
+```bash
+#!/bin/bash
+# ---
+# name: check-secrets
+# ---
+if grep -r "API_KEY=" .; then
+    echo "Hardcoded API key found"
+    exit 1
+fi
+exit 0
+```
+
+**Agent checks** (`.md` files): Use Claude to analyze code or agent actions. The markdown content is the audit prompt.
+
+```markdown
+---
+name: check-code-quality
+model: sonnet  # Optional: haiku (default), sonnet, opus
+---
+
+Review the code for:
+1. Complex functions that should be refactored
+2. Inconsistent error handling
+3. Missing input validation
+```
+
+### Check vs Audit
+
+- **Check**: Single verification (one `.sh` or `.md` file)
+- **Audit**: Collection of checks (directory with `audit.yaml`)
+
+Checks run sequentially and stop at first failure.
+
+## audit.yaml
+
+The `audit.yaml` file defines which checks an audit includes:
+
+```yaml
+includes:
+  - ../shared/*              # All checks from shared/ directory
+  - ../other-audit           # All checks from another audit (recursively)
+  - ./check-custom.sh        # Specific check file
+```
+
+Paths are relative to the audit directory. Wildcards (`*`, `?`, `[...]`) are supported.
+
+An audit with no `includes` runs all `.sh` and `.md` files in its own directory.
+
+## Configuration
+
+Settings file: `.ccaudit/settings.json` (project) or `~/.ccaudit/settings.json` (global)
+
+```json
+{
+  "claude_command": "claude"
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `claude_command` | `claude` | Command to invoke Claude CLI |
+
+## CLI Reference
+
+```
+ccaudit run <audit-name>    Execute an audit
+  -v, --verbose             Enable debug output
+  --output <mode>           Force output mode: interactive, plain, or hook
+
+ccaudit list                List available audits
+  -v, --verbose             Enable debug output
+```
+
+## Output Modes
+
+- **Interactive**: TUI with spinner and progress (default in terminal)
+- **Plain**: Text output (default when piped)
+- **Hook**: JSON output for Claude Code hook integration (auto-detected from stdin)
+
+## Claude Code Hook Integration
+
+Run ccaudit as a Claude Code hook to audit agent actions in real-time:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "command": "ccaudit run security"
+      }
+    ]
+  }
+}
+```
+
+Supported hook events: `PreToolUse`, `PostToolUse`, `Stop`, `UserPromptSubmit`
+
+When running as a hook:
+- Hook context is read from stdin (JSON with `hook_event_name`, `cwd`, `transcript_path`, etc.)
+- Agent checks gain access to MCP tools (`get_history`, `get_instructions`) for inspecting the audited session
+- Output is JSON on failure only
+
+## Check Frontmatter
+
+All checks require a `name` field in YAML frontmatter:
+
+Shell:
+```bash
+#!/bin/bash
+# ---
+# name: check-name
+# ---
+```
+
+Markdown:
+```markdown
+---
+name: check-name
+model: haiku  # Optional
+---
+```
+
+## Agent Check Behavior
+
+Agent checks run in read-only mode. They can use `Read`, `Glob`, `Grep`, and `Bash` (for read operations only).
+
+When running as a hook with transcript access, agent checks also have MCP tools to inspect the audited session's history and actions.
+
+Agent checks return structured JSON:
+```json
+{
+  "passed": false,
+  "reason": "Single failure explanation",
+  "failures": ["Issue 1", "Issue 2"],
+  "hint": "How to fix"
+}
+```
+
+## Project Structure
+
+```
+.ccaudit/
+├── settings.json           # Optional configuration
+└── audits/
+    ├── my-audit/
+    │   ├── audit.yaml      # Required
+    │   ├── check-foo.sh
+    │   └── check-bar.md
+    └── shared/
+        └── check-common.sh
+```
+
+## Exit Codes
+
+- `0`: All checks passed
+- `1`: At least one check failed or error occurred

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccdevkit/ccaudit",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Audit tool for Claude Code projects - runs compliance checks on code and agent actions",
   "bin": {
     "ccaudit": "bin/ccaudit"