npm - ai-rulez - Versions diffs - 2.4.0 → 2.4.2 - Mend

ai-rulez 2.4.0 → 2.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +73 -459
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -6,537 +6,151 @@
 **AI-powered development governance. One config to rule them all.**
-## The Complete AI Development Platform
-AI-Rulez is the **definitive platform for AI-powered development governance**. Beyond just generating configuration files, it provides real-time rule enforcement, automated code quality assurance, and intelligent governance across your entire development workflow.
-### 🚀 Two Powerful Capabilities
-**1. Universal Configuration Management** - Write once, deploy everywhere
-**2. AI-Powered Rule Enforcement** - Real-time governance with automated fixes
+[![Go Version](https://img.shields.io/badge/Go-1.24%2B-00ADD8)](https://go.dev)
+[![NPM Version](https://img.shields.io/npm/v/ai-rulez)](https://www.npmjs.com/package/ai-rulez)
+[![PyPI Version](https://img.shields.io/pypi/v/ai-rulez)](https://pypi.org/project/ai-rulez/)
+[![Homebrew](https://img.shields.io/badge/Homebrew-tap-orange)](https://github.com/Goldziher/homebrew-tap)
-## Why AI-Rulez?
+**Documentation:** [goldziher.github.io/ai-rulez](https://goldziher.github.io/ai-rulez/)
-Modern development teams need more than just configuration management:
+---
-### ⚠️ **The Problem**
-- **Configuration Hell**: Each AI tool needs its own format (`.cursorrules`, `CLAUDE.md`, `.windsurfrules`, etc.)
-- **Rule Enforcement Gap**: No way to automatically validate that code follows your standards
-- **Team Inconsistency**: Different developers get different AI guidance
-- **Manual Quality Control**: Time-consuming code reviews for basic rule violations
-- **Reactive Governance**: Finding issues after they're already committed
+## Why ai-rulez
-### ✨ **The Solution**
-AI-Rulez provides **proactive development governance** with a single `ai-rulez.yaml` that:
-- **Generates configurations** for every AI tool automatically
-- **Enforces rules in real-time** using AI agents (Claude, Gemini, etc.)
-- **Applies automatic fixes** for code quality issues
-- **Integrates with your workflow** (Git hooks, CI/CD, pre-commit)
-- **Scales across teams** with consistent standards
+- One YAML file stays in sync with every AI assistant format (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, MCP configs, and more).
+- AI agents enforce your rules in real time with optional auto-fix and review loops.
+- Git hooks, CI, and MCP integrations keep governance in every stage of your workflow.
+- Works for individuals and teams with presets, remote includes, and monorepo support.
 <p align="center">
-  <img src="docs/assets/ai-rulez-python-demo.gif" alt="AI-Rulez Configuration Demo" width="100%">
-  <br><em>📝 Configuration Management (via npx ai-rulez)</em>
+  <img src="docs/assets/ai-rulez-python-demo.gif" alt="AI-Rulez Configuration Demo" width="90%">
 </p>
-<p align="center">
-  <img src="docs/assets/ai-rulez-enforce-demo.gif" alt="AI-Rulez Enforcement Demo" width="100%">
-  <br><em>🤖 AI-Powered Rule Enforcement (via uvx ai-rulez@latest)</em>
-</p>
+---
-[![Go Version](https://img.shields.io/badge/Go-1.24%2B-00ADD8)](https://go.dev)
-[![NPM Version](https://img.shields.io/npm/v/ai-rulez)](https://www.npmjs.com/package/ai-rulez)
-[![PyPI Version](https://img.shields.io/pypi/v/ai-rulez)](https://pypi.org/project/ai-rulez/)
-[![Homebrew](https://img.shields.io/badge/Homebrew-tap-orange)](https://github.com/Goldziher/homebrew-tap)
+## What You Get
-### 📖 **[Read the Full Documentation](https://goldziher.github.io/ai-rulez/)**
+- **Universal configuration management** – `ai-rulez` analyzes your repo and generates native configuration files for every assistant.
+- **AI-powered enforcement** – Run `ai-rulez enforce` to catch violations, apply fixes, and gate merges with configurable quality thresholds.
+- **Automation built-in** – Smart `.gitignore` updates, Git hook integration (lefthook, pre-commit, husky), and CI ready commands.
+- **MCP everywhere** – Automatically wire MCP servers into Claude CLI, Gemini CLI, Cursor, and other supported tools.
 ---
-## 🚀 Core Capabilities
+## Quick Start
-### 1. 📋 Universal Configuration Management
-Write once, deploy everywhere with intelligent AI-powered project analysis:
+### Configuration Management
 ```bash
-# AI analyzes your codebase and generates tailored config
-npx ai-rulez init "My Project" --preset popular
-```
-**Features:**
-- **AI Project Analysis**: Automatically detects your tech stack, patterns, and conventions
-- **Universal Output Generation**: One YAML → all AI tool formats (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, etc.)
-- **Smart Gitignore Management**: Automatically excludes generated files from version control
-- **MCP Integration**: Auto-configure MCP servers across CLI tools (Claude, Gemini, etc.)
-- **Team Collaboration**: Remote includes, local overrides, monorepo support
+# Analyze your project and scaffold configuration
+npx ai-rulez@latest init "My Project" --preset popular
-### 2. 🤖 AI-Powered Rule Enforcement
+# Generate all assistant configuration files
+npx ai-rulez@latest generate
+```
-Real-time governance with automated fixes using multiple AI agents:
+### Rule Enforcement
 ```bash
-# Check for violations with AI analysis
+# Check for violations (read-only)
 uvx ai-rulez@latest enforce --agent claude
-# Automatically apply fixes
+# Apply fixes or run multi-agent reviews
 uvx ai-rulez@latest enforce --agent claude --fix
-# Multi-agent review workflow
-uvx ai-rulez@latest enforce --agent gemini --review --review-agent claude
+uvx ai-rulez@latest enforce --agent gemini --review --review-iterations 2
 ```
-**Features:**
-- **Multi-Agent Support**: Claude, Gemini, AMP, Cursor, Codex, Continue.dev, Junie
-- **Automated Fixes**: AI suggests and applies code improvements
-- **Review Workflows**: Iterative improvement with quality thresholds
-- **Multiple Output Formats**: Table, JSON, CSV, summary reports
-- **CI/CD Integration**: Git hooks, pre-commit, workflow automation
-- **Quality Scoring**: 0-100% compliance with configurable thresholds
-## How It Works
+### Optional: Auto-Configure Git Hooks
-AI-Rulez operates as a **comprehensive AI development governance platform**:
+```bash
+# Detect pre-commit, lefthook, or husky and add ai-rulez validation
+npx ai-rulez@latest init --setup-hooks
+```
-1. **📝 Configuration Phase**: Your `ai-rulez.yml` serves as the single source of truth
-2. **🏗️ Generation Phase**: Automatically creates native files for every AI tool
-3. **🔍 Enforcement Phase**: AI agents continuously validate code against your rules
-4. **🛠️ Fix Phase**: Automatic corrections and improvements applied in real-time
-5. **📊 Reporting Phase**: Detailed compliance reports and quality metrics
+`--setup-hooks` adds the official hooks for the detected system and keeps existing configuration intact.
-Think of it as **CI/CD for code quality** - proactive governance instead of reactive fixes.
+---
-## Example: `ai-rulez.yml`
+## Example `ai-rulez.yaml`
 ```yaml
 $schema: https://github.com/Goldziher/ai-rulez/schema/ai-rules-v2.schema.json
 metadata:
   name: "My SaaS Platform"
-  version: "2.0.0"
-# Use presets for common configurations
 presets:
-  - "popular"  # Includes Claude, Cursor, Windsurf, Copilot, and Gemini
+  - "popular"  # Claude, Cursor, Windsurf, Copilot, Gemini
 rules:
   - name: "Go Code Standards"
     priority: high
-    content: "Follow standard Go project layout (cmd/, internal/, pkg/). Use meaningful package names and export only what is necessary."
+    content: "Follow standard Go project layout and export only what is necessary."
 sections:
   - name: "Project Structure"
     priority: critical
     content: |
       - `cmd/`: Main application entry point
-      - `internal/`: Private application code (business logic, data access)
+      - `internal/`: Private application code
       - `pkg/`: Public-facing libraries
 agents:
   - name: "go-developer"
-    description: "Go language expert for core development"
-    system_prompt: "You are an expert Go developer. Your key responsibilities include writing idiomatic Go, using proper error handling, and creating comprehensive tests."
+    description: "Expert Go developer focused on idiomatic code and tests."
-# MCP servers for direct AI tool integration
 mcp_servers:
   - name: "ai-rulez"
     command: "npx"
     args: ["-y", "ai-rulez@latest", "mcp"]
-    description: "AI-Rulez MCP server for configuration management"
-```
-Run `ai-rulez generate` → get all your configuration files, perfectly synchronized.
-## ⚡ Quick Start
-### 📋 Configuration Management
-```bash
-# 1. AI-powered project analysis and setup
-npx ai-rulez@latest init "My Project" --preset popular
-# 2. Generate all AI tool configuration files
-npx ai-rulez@latest generate
-# 3. Your AI tools now have comprehensive, project-specific context!
-```
-### 🤖 AI-Powered Rule Enforcement
-```bash
-# 1. Check for rule violations
-uvx ai-rulez@latest enforce --agent claude --format table
-# 2. Get detailed analysis and suggestions
-uvx ai-rulez@latest enforce --agent claude --format json
-# 3. Apply automatic fixes
-uvx ai-rulez@latest enforce --agent claude --fix
-# 4. Set up review workflow
-uvx ai-rulez@latest enforce --agent claude --review --review-iterations 2
+    description: "Configuration management server"
 ```
-**That's it!** You now have both intelligent configuration management AND real-time rule enforcement powered by AI.
 ---
-## 🗂️ .gitignore Management
-AI-Rulez manages your `.gitignore` to keep generated files out of version control.
+## Installation Options
-**Automatic updates:**
-```bash
-# During init (enabled by default)
-ai-rulez init --preset claude
-# During generate (optional)
-ai-rulez generate --update-gitignore
-# Disable if needed
-ai-rulez init --preset popular --no-gitignore
-```
-**What gets ignored:**
-- Generated markdown files (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`)
-- AI tool directories (`.claude/`, `.cursor/`, `.windsurf/`, `.clinerules/`, etc.)
-- Config files (`.mcp.json`, `.gemini/settings.json`)
-All entries are added under `# AI Rules generated files` without duplicates.
-**Best practice:** Commit `ai-rulez.yaml` and `.gitignore`, but not the generated AI configuration files.
+- **No install required**
+  - `npx ai-rulez@latest ...` for Node/JS environments
+  - `uvx ai-rulez@latest ...` for Python users
+  - `go run github.com/Goldziher/ai-rulez/cmd@latest ...` for Go projects
+- **Global installs**
+  - `brew install goldziher/tap/ai-rulez`
+  - `npm install -g ai-rulez`
+  - `pip install ai-rulez`
+  - `go install github.com/Goldziher/ai-rulez/cmd@latest`
 ---
-## 🤖 AI-Powered Rule Enforcement
-The killer feature that sets AI-Rulez apart: **real-time rule enforcement using AI agents**. No more manual code reviews for basic violations—let AI catch and fix issues automatically.
-### ✨ Key Benefits
-- **Proactive Quality Control**: Catch issues before they reach production
-- **Multi-Agent Support**: Claude, Gemini, AMP, Cursor, Codex—use the best AI for each task
-- **Automatic Fixes**: AI doesn't just find problems, it solves them
-- **Workflow Integration**: Git hooks, CI/CD, pre-commit—enforcement everywhere
-- **Team Consistency**: Same standards for everyone, from junior to senior devs
-### 🎯 Real-World Use Cases
-```bash
-# Prevent console.log in production builds
-ai-rulez enforce --agent claude --only-rules "no-console-output" --fix
-# Ensure all functions have proper error handling
-ai-rulez enforce --agent gemini --level strict --format json
-# Multi-agent review for critical code changes
-ai-rulez enforce --agent claude --review --review-agent gemini --review-threshold 95
-# Automated fixes in CI/CD pipeline
-ai-rulez enforce --agent claude --fix --format csv --output violations.csv
-```
-### 📊 Output Formats & Integration
-| Format | Use Case | Command |
-|--------|----------|---------|
-| **Table** | Human-readable terminal output | `--format table` |
-| **JSON** | API integration, detailed analysis | `--format json --pretty` |
-| **CSV** | Data analysis, reporting | `--format csv --output report.csv` |
-| **Summary** | Quick overview with scores | `--format summary` |
-### 🔄 Advanced Workflows
-**Review Pipeline**: Multi-agent validation with quality gates
-```bash
-ai-rulez enforce --agent claude --review --review-iterations 3 --review-threshold 85
-```
-**Fix & Verify**: Apply fixes and validate improvements
-```bash
-ai-rulez enforce --agent gemini --fix --review --require-improvement
-```
-**Team Standards**: Consistent enforcement across the entire codebase
-```bash
-ai-rulez enforce --include-files "src/**/*.{js,ts,py}" --level strict --agent claude
-```
-**Prefer manual setup?**
-```bash
-# Basic initialization without AI assistance
-ai-rulez init "My Project" --preset popular --no-agent
-# Add your project-specific context
-ai-rulez add rule "Tech Stack" --priority critical --content "This project uses Go and PostgreSQL."
-# Generate files
-ai-rulez generate
-```
-## MCP Server Integration
-`ai-rulez` provides seamless **Model Context Protocol (MCP)** integration, automatically configuring both file-based and CLI-based AI tools with your MCP servers.
-### Automatic CLI Configuration
-When you run `ai-rulez generate`, MCP servers are **automatically configured** for available CLI tools:
-```bash
-ai-rulez generate
-# ✅ Generated 3 file(s) successfully
-# ✅ Configured claude MCP server: ai-rulez
-# ✅ Configured gemini MCP server: database-tools
-```
-**Supported CLI tools:**
-- **Claude CLI**: `claude mcp add` with full env/transport support
-- **Gemini CLI**: `gemini mcp add` with automatic configuration
-### Hybrid Configuration
-`ai-rulez` supports both CLI and file-based configurations simultaneously:
-```yaml
-mcp_servers:
-  - name: "database-tools"
-    command: "uvx"
-    args: ["mcp-server-postgres"]
-    env:
-      DATABASE_URL: "postgresql://localhost/mydb"
-    targets:
-      - "@claude-cli"        # Configure Claude CLI
-      - "@gemini-cli"        # Configure Gemini CLI
-      - ".cursor/mcp.json"   # Generate Cursor config file
-```
-This single configuration:
-- ✅ Executes `claude mcp add` commands
-- ✅ Executes `gemini mcp add` commands
-- ✅ Generates `.cursor/mcp.json` file
-### Control Options
+## Git Hooks & Automation
-**Default behavior** (recommended):
-```bash
-ai-rulez generate
-# Configures all available CLI tools + generates files
-```
-**Disable CLI configuration** when needed:
-```bash
-ai-rulez generate --no-configure-cli-mcp
-# Only generates files, skips CLI tool configuration
-```
-**Target specific tools:**
-```yaml
-mcp_servers:
-  - name: "github-integration"
-    command: "npx"
-    args: ["@modelcontextprotocol/server-github"]
-    targets: ["@claude-cli"]  # Only configure Claude CLI
-```
-### Built-in MCP Server
-`ai-rulez` includes its own MCP server for configuration management:
-```bash
-# Start the ai-rulez MCP server
-ai-rulez mcp
-# Or configure it automatically via your ai-rulez.yaml
-mcp_servers:
-  - name: "ai-rulez"
-    command: "npx"
-    args: ["-y", "ai-rulez@latest", "mcp"]
-    description: "Configuration management server"
-```
-## AI-Powered Rule Enforcement
-AI-Rulez provides **real-time rule enforcement** using AI agents to automatically detect violations and apply fixes across your codebase.
-<p align="center">
-  <img src="docs/assets/ai-rulez-enforce-demo.gif" alt="AI-Rulez Enforcement Demo" width="100%">
-</p>
-### Basic Enforcement
-```bash
-# Check for violations (read-only by default)
-ai-rulez enforce
-# Automatically apply fixes
-ai-rulez enforce --fix
-# Use specific AI agent
-ai-rulez enforce --agent gemini --fix
-```
-### Advanced Enforcement Options
-```bash
-# Enforce with specific level
-ai-rulez enforce --level strict --agent claude
-# Review workflow with iterative improvement
-ai-rulez enforce --review --review-iterations 3 --review-threshold 85
+- **Official pre-commit hooks**
-# Multi-agent review (different agents for enforcement vs review)
-ai-rulez enforce --agent gemini --review --review-agent claude
+  ```yaml
+  repos:
+    - repo: https://github.com/Goldziher/ai-rulez
+      rev: v2.4.2
+      hooks:
+        - id: ai-rulez-validate
+        - id: ai-rulez-generate
+  ```
-# Target specific files and rules
-ai-rulez enforce --include-files "src/**/*.js" --only-rules "no-console-output"
-# Output formats for automation
-ai-rulez enforce --format json --output violations.json
-ai-rulez enforce --format csv --output report.csv
-```
-### Supported AI Agents
-AI-Rulez integrates with all major AI coding assistants:
-- **Claude** (`claude`) - Anthropic's AI assistant
-- **Gemini** (`gemini`) - Google's AI model
-- **Cursor** (`cursor`) - AI-powered code editor
-- **AMP** (`amp`) - Sourcegraph's AI assistant
-- **Codex** (`codex`) - OpenAI's code model
-- **Continue.dev** (`continue-dev`) - Open-source coding assistant
-- **Junie** (`junie`) - JetBrains AI assistant
-### Enforcement Levels
-- **`warn`**: Log violations but don't fail (default)
-- **`error`**: Fail on violations but don't auto-fix
-- **`fix`**: Automatically apply suggested fixes
-- **`strict`**: Fail immediately on any violation
-### Integration with Git Hooks
-Add enforcement to your Git workflow:
-```yaml
-# .lefthook.yml
-pre-commit:
-  commands:
-    ai-rulez-enforce:
-      run: ai-rulez enforce --level error --agent gemini
-      stage_fixed: true
-```
+- **CLI hook setup** – Run `ai-rulez init --setup-hooks` to auto-configure pre-commit, lefthook, or husky if they are present in your repo.
+- **No-Go requirement** – Hooks use `scripts/pre-commit/run-ai-rulez.sh`, which fetches the correct prebuilt binary on-demand (override with `AI_RULEZ_BINARY` if you already have one installed).
+- **CI/CD examples** – See the [Enforcement guide](https://goldziher.github.io/ai-rulez/enforcement/) for GitHub Actions, pipeline tips, and advanced workflows.
-```bash
-# Or with pre-commit hooks
-# .pre-commit-config.yaml
-repos:
-  - repo: local
-    hooks:
-      - id: ai-rulez-enforce
-        name: AI-Rulez Enforcement
-        entry: ai-rulez enforce --level error
-        language: system
-        pass_filenames: false
-```
-### Review Workflow
-The review system provides iterative code improvement:
-```bash
-# Enable review with quality scoring
-ai-rulez enforce --review --review-threshold 80
-# Multiple review iterations
-ai-rulez enforce --review --review-iterations 5
-# Auto-approve after reaching threshold
-ai-rulez enforce --review --review-auto-approve
-# Require improvement between iterations
-ai-rulez enforce --review --require-improvement
-```
-The AI reviewer analyzes:
-- ✅ Code quality and adherence to rules
-- ✅ Suggested fixes and their appropriateness
-- ✅ Overall improvement between iterations
-- ✅ Compliance with project standards
-## 📦 Installation
-Choose your installation method based on your primary use case:
-### 🚀 Quick Start (No Installation)
-**For Configuration Management** (project setup, file generation):
-```bash
-# Node.js - Best for web/JS projects
-npx ai-rulez@latest init "My Project" --preset popular
-npx ai-rulez@latest generate
-```
-**For Rule Enforcement** (AI-powered validation):
-```bash
-# Python - Latest features, fastest updates
-uvx ai-rulez@latest enforce --agent claude --fix
-uvx ai-rulez@latest enforce --agent gemini --review
-```
-**For Go Projects**:
-```bash
-go run github.com/Goldziher/ai-rulez/cmd@latest init
-```
-### 🔧 Global Installation
-For teams and frequent usage:
-**Homebrew (Recommended for macOS/Linux)**
-```bash
-brew install goldziher/tap/ai-rulez
-ai-rulez init "My Project"
-ai-rulez enforce --agent claude
-```
-**npm (Best for Node.js teams)**
-```bash
-npm install -g ai-rulez
-```
-**pip (Best for Python teams)**
-```bash
-pip install ai-rulez
-```
-**Go (For Go developers)**
-```bash
-go install github.com/Goldziher/ai-rulez/cmd@latest
-```
-## Pre-commit Hooks
-You can use `ai-rulez` with `pre-commit` to automatically validate and generate your AI configuration files.
+---
-Add the following to your `.pre-commit-config.yaml`:
+## More to Explore
-```yaml
-repos:
-  - repo: https://github.com/Goldziher/ai-rulez
-    rev: v2.2.1
-    hooks:
-      - id: ai-rulez-validate
-      - id: ai-rulez-generate
-```
+- [Quick Start](https://goldziher.github.io/ai-rulez/quick-start/) – Guided setup in minutes.
+- [CLI Reference](https://goldziher.github.io/ai-rulez/cli/) – All commands and flags.
+- [Configuration Guide](https://goldziher.github.io/ai-rulez/configuration/) – Advanced YAML features, includes, and presets.
+- [Enforcement Guide](https://goldziher.github.io/ai-rulez/enforcement/) – Multi-agent reviews, automation, and reporting.
+- [Migration Guide](https://goldziher.github.io/ai-rulez/migration-guide/) – Upgrading from v1.x.
 ---
-## Documentation
-- **[Quick Start Guide](https://goldziher.github.io/ai-rulez/quick-start/)**
-- **[Full CLI Reference](https://goldziher.github.io/ai-rulez/cli/)**
-- **[Configuration Guide](https://goldziher.github.io/ai-rulez/configuration/)**
-- **[Migration Guide](https://goldziher.github.io/ai-rulez/migration-guide/)** - Upgrading from v1.x to v2.0
 ## Contributing
-Contributions are welcome! Please see the [Contributing Guide](CONTRIBUTING.md) to get started.
+We welcome contributions! Read the [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and release process details.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "ai-rulez",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "⚡ One config to rule them all. Centralized AI assistant configuration management - generate rules for Claude, Cursor, Copilot, Windsurf and more from a single YAML file.",
   "keywords": [
     "ai",