ai-rulez 1.0.0-rc9 → 1.1.0

package/README.md

@@ -1,61 +1,239 @@
-# ai-rulez
+# ai-rulez ⚡
 
-CLI tool for managing AI assistant rules across Claude, Cursor, Windsurf and other AI-powered development environments.
+> **Lightning-fast CLI tool (written in Go) for managing AI assistant rules**
 
-This npm package provides the `ai-rulez` command-line tool, which is written in Go for optimal performance and distributed as platform-specific binaries.
+Generate configuration files for Claude, Cursor, Windsurf, and other AI assistants from a single, centralized configuration.
 
-## Installation
+## 🚀 Features
+
+- ⚡ **Blazing Fast**: Written in Go for maximum performance
+- 🔧 **Multi-Assistant Support**: Generate configs for Claude (CLAUDE.md), Cursor (.cursorrules), Windsurf (.windsurfrules), and more
+- 📝 **Single Source of Truth**: Maintain all your AI rules in one YAML configuration
+- 🎯 **Smart Templates**: Built-in templates with custom template support
+- 🔍 **Validation**: Comprehensive configuration validation
+- 🔄 **Git Integration**: Perfect for pre-commit hooks and CI/CD
+- 📦 **Node.js Integration**: Easy installation via npm
+
+## 📦 Installation
+
+### npm (Recommended)
 
 ```bash
+# Global installation
 npm install -g ai-rulez
+
+# Local project installation
+npm install --save-dev ai-rulez
 ```
 
-The package will automatically download the appropriate binary for your platform during installation.
+The npm package automatically downloads and manages the Go binary for your platform.
 
-## Usage
+### Other Installation Methods
 
-Create an `ai_rules.yaml` configuration file in your project:
+- **pip**: `pip install ai-rulez`
+- **Go**: `go install github.com/Goldziher/ai-rulez@latest`
+- **Homebrew**: `brew install goldziher/tap/ai-rulez` *(coming soon)*
+- **Direct Download**: Download from [GitHub Releases](https://github.com/Goldziher/ai-rulez/releases)
+
+## 🎯 Quick Start
+
+1. **Create a configuration file** (`ai-rulez.yaml`):
 
 ```yaml
 metadata:
-  name: my-project
-  version: 1.0.0
+  name: "My AI Rules"
+  version: "1.0.0"
 
 rules:
-  - name: code-style
-    content: Follow the project's established coding conventions
-  - name: testing
-    content: Write comprehensive tests for all new features
+  - name: "Code Style"
+    priority: 10
+    content: |
+      - Use TypeScript strict mode
+      - Prefer functional components
+      - Use meaningful variable names
+
+  - name: "Testing"
+    priority: 5
+    content: |
+      - Write unit tests for all functions
+      - Use describe/it pattern
+      - Aim for 80% code coverage
 
 outputs:
-  - file: .cursorrules
-  - file: CLAUDE.md
+  - file: "CLAUDE.md"
+    template: "claude"
+  - file: ".cursorrules"
+    template: "cursor"
+  - file: ".windsurfrules" 
+    template: "windsurf"
+```
+
+2. **Generate configuration files**:
+
+```bash
+ai-rulez generate
 ```
 
-Then generate your AI assistant configuration files:
+This creates `CLAUDE.md`, `.cursorrules`, and `.windsurfrules` with your rules properly formatted for each AI assistant.
+
+## 🛠️ Commands
 
 ```bash
-# Generate files
+# Generate all configuration files
 ai-rulez generate
 
 # Validate configuration
 ai-rulez validate
 
-# Initialize a new configuration
-ai-rulez init
+# Generate recursively in subdirectories
+ai-rulez generate --recursive
+
+# Preview output without writing files
+ai-rulez generate --dry-run
+
+# Show help
+ai-rulez --help
 ```
 
-## Platform Support
+## 🔄 Git Integration
+
+### Pre-commit Hook
+
+Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/Goldziher/ai-rulez
+    rev: v1.0.0
+    hooks:
+      - id: ai-rulez-generate
+```
+
+### Lefthook
+
+Add to your `lefthook.yml`:
+
+```yaml
+pre-commit:
+  commands:
+    ai-rulez:
+      run: ai-rulez generate
+      files: git diff --cached --name-only
+      glob: "*.{ai-rulez,ai_rulez}.{yml,yaml}"
+```
+
+### npm Scripts
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "ai-rulez": "ai-rulez generate",
+    "ai-rulez:validate": "ai-rulez validate",
+    "ai-rulez:watch": "ai-rulez generate --recursive"
+  }
+}
+```
+
+## 📚 Configuration
+
+The tool looks for configuration files in this order:
+- `.ai-rulez.yaml`
+- `ai-rulez.yaml` 
+- `.ai_rulez.yaml`
+- `ai_rulez.yaml`
+
+### Configuration Schema
+
+```yaml
+metadata:
+  name: string          # Required: Project name
+  version: string       # Required: Version
+  description: string   # Optional: Description
+
+rules:
+  - name: string        # Required: Rule name
+    priority: number    # Required: Priority (1-10)
+    content: string     # Required: Rule content
+
+sections:              # Optional: Organize rules into sections
+  - title: string      # Required: Section title
+    priority: number   # Required: Section priority
+    content: string    # Required: Section content
+
+outputs:               # Required: At least one output
+  - file: string       # Required: Output filename
+    template: string   # Required: Template name or path
+
+includes:              # Optional: Include other config files
+  - path/to/other.yaml
+```
+
+## 🎨 Templates
+
+Built-in templates:
+- `claude` - CLAUDE.md format
+- `cursor` - .cursorrules format  
+- `windsurf` - .windsurfrules format
+- `default` - Generic format
+
+Custom templates use Go template syntax with access to `.Rules`, `.Sections`, `.Metadata`, etc.
+
+## 🔧 Advanced Usage
+
+### Environment Variables
+
+- `AI_RULEZ_CONFIG` - Override config file path
+- `AI_RULEZ_DEBUG` - Enable debug output
+
+### Node.js API
+
+```javascript
+const { execSync } = require('child_process');
+
+// Run ai-rulez programmatically
+try {
+  const output = execSync('ai-rulez generate --dry-run', { encoding: 'utf8' });
+  console.log(output);
+} catch (error) {
+  console.error('ai-rulez failed:', error.message);
+}
+```
+
+### npm Scripts Integration
+
+```json
+{
+  "scripts": {
+    "precommit": "ai-rulez generate",
+    "lint": "eslint . && ai-rulez validate",
+    "build": "npm run ai-rulez && npm run compile"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "ai-rulez generate"
+    }
+  }
+}
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see our [Contributing Guide](https://github.com/Goldziher/ai-rulez/blob/main/CONTRIBUTING.md).
+
+## 📄 License
 
-Pre-built binaries are available for:
-- macOS (Intel and Apple Silicon)
-- Linux (x64, ARM64, and x86)
-- Windows (x64 and x86)
+MIT License - see [LICENSE](https://github.com/Goldziher/ai-rulez/blob/main/LICENSE)
 
-## Documentation
+## 🔗 Links
 
-For complete documentation, examples, and source code, visit the [GitHub repository](https://github.com/Goldziher/ai-rulez).
+- [GitHub Repository](https://github.com/Goldziher/ai-rulez)
+- [Documentation](https://github.com/Goldziher/ai-rulez#readme)
+- [Issues](https://github.com/Goldziher/ai-rulez/issues)
+- [Releases](https://github.com/Goldziher/ai-rulez/releases)
+- [PyPI Package](https://pypi.org/project/ai-rulez/)
 
-## License
+---
 
-MIT
+**Note**: This npm package is a wrapper around the Go binary. The actual tool is written in Go for maximum performance and cross-platform compatibility.

package/install.js

@@ -1,12 +1,46 @@
 const fs = require('fs');
 const path = require('path');
 const https = require('https');
-const { exec } = require('child_process');
+const http = require('http');
+const crypto = require('crypto');
+const { exec, spawn } = require('child_process');
 const { promisify } = require('util');
 
 const execAsync = promisify(exec);
 
 const REPO_NAME = 'Goldziher/ai-rulez';
+const DOWNLOAD_TIMEOUT = 30000; // 30 seconds
+const MAX_RETRIES = 3;
+const RETRY_DELAY = 2000; // 2 seconds
+
+async function calculateSHA256(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    
+    stream.on('data', (data) => hash.update(data));
+    stream.on('end', () => resolve(hash.digest('hex')));
+    stream.on('error', reject);
+  });
+}
+
+async function getExpectedChecksum(checksumPath, filename) {
+  try {
+    const checksumContent = fs.readFileSync(checksumPath, 'utf8');
+    const lines = checksumContent.split('\n');
+    
+    for (const line of lines) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length >= 2 && parts[1] === filename) {
+        return parts[0];
+      }
+    }
+    return null;
+  } catch (error) {
+    console.warn('Warning: Could not parse checksums file:', error.message);
+    return null;
+  }
+}
 
 function getPlatform() {
   const platform = process.platform;
@@ -28,13 +62,17 @@ function getPlatform() {
   const mappedPlatform = platformMap[platform];
   const mappedArch = archMap[arch];
   
-  if (!mappedPlatform || !mappedArch) {
-    throw new Error(`Unsupported platform: ${platform} ${arch}`);
+  if (!mappedPlatform) {
+    throw new Error(`Unsupported operating system: ${platform}. Supported platforms: darwin (macOS), linux, win32 (Windows)`);
+  }
+  
+  if (!mappedArch) {
+    throw new Error(`Unsupported architecture: ${arch}. Supported architectures: x64, arm64, ia32`);
   }
   
-  // Windows ARM64 is not supported in our builds
+  
   if (mappedPlatform === 'windows' && mappedArch === 'arm64') {
-    throw new Error('Windows ARM64 is not supported');
+    throw new Error('Windows ARM64 is not currently supported. Please use x64 or ia32 version.');
   }
   
   return {
@@ -47,81 +85,264 @@ function getBinaryName(platform) {
   return platform === 'windows' ? 'ai-rulez.exe' : 'ai-rulez';
 }
 
-async function downloadBinary(url, dest) {
+async function downloadBinary(url, dest, retryCount = 0) {
   return new Promise((resolve, reject) => {
     const file = fs.createWriteStream(dest);
+    const protocol = url.startsWith('https') ? https : http;
     
-    https.get(url, (response) => {
+    const request = protocol.get(url, { timeout: DOWNLOAD_TIMEOUT }, (response) => {
       if (response.statusCode === 302 || response.statusCode === 301) {
-        // Handle redirect
-        https.get(response.headers.location, (redirectResponse) => {
-          redirectResponse.pipe(file);
-          file.on('finish', () => {
-            file.close();
-            resolve();
-          });
-        }).on('error', reject);
-      } else if (response.statusCode === 200) {
-        response.pipe(file);
-        file.on('finish', () => {
-          file.close();
-          resolve();
-        });
-      } else {
-        reject(new Error(`Failed to download: ${response.statusCode}`));
+        file.close();
+        try { fs.unlinkSync(dest); } catch {} // Clean up partial file
+        downloadBinary(response.headers.location, dest, retryCount)
+          .then(resolve)
+          .catch(reject);
+        return;
+      }
+      
+      if (response.statusCode !== 200) {
+        file.close();
+        try { fs.unlinkSync(dest); } catch {} // Clean up partial file
+        const error = new Error(`HTTP ${response.statusCode}: ${response.statusMessage}`);
+        
+        if (retryCount < MAX_RETRIES) {
+          console.log(`Download failed, retrying in ${RETRY_DELAY/1000}s... (${retryCount + 1}/${MAX_RETRIES})`);
+          setTimeout(() => {
+            downloadBinary(url, dest, retryCount + 1)
+              .then(resolve)
+              .catch(reject);
+          }, RETRY_DELAY);
+          return;
+        }
+        
+        reject(error);
+        return;
+      }
+      
+      let downloadedBytes = 0;
+      response.on('data', (chunk) => {
+        downloadedBytes += chunk.length;
+      });
+      
+      response.pipe(file);
+      
+      file.on('finish', () => {
+        file.close();
+        if (downloadedBytes === 0) {
+          try { fs.unlinkSync(dest); } catch {}
+          reject(new Error('Downloaded file is empty'));
+          return;
+        }
+        console.log(`Downloaded ${downloadedBytes} bytes`);
+        resolve();
+      });
+      
+      file.on('error', (err) => {
+        file.close();
+        try { fs.unlinkSync(dest); } catch {}
+        reject(err);
+      });
+    });
+    
+    request.on('timeout', () => {
+      request.destroy();
+      file.close();
+      try { fs.unlinkSync(dest); } catch {}
+      
+      if (retryCount < MAX_RETRIES) {
+        console.log(`Download timeout, retrying in ${RETRY_DELAY/1000}s... (${retryCount + 1}/${MAX_RETRIES})`);
+        setTimeout(() => {
+          downloadBinary(url, dest, retryCount + 1)
+            .then(resolve)
+            .catch(reject);
+        }, RETRY_DELAY);
+        return;
       }
-    }).on('error', reject);
+      
+      reject(new Error('Download timeout after multiple retries'));
+    });
+    
+    request.on('error', (err) => {
+      file.close();
+      try { fs.unlinkSync(dest); } catch {}
+      
+      if (retryCount < MAX_RETRIES) {
+        console.log(`Download error, retrying in ${RETRY_DELAY/1000}s... (${retryCount + 1}/${MAX_RETRIES})`);
+        setTimeout(() => {
+          downloadBinary(url, dest, retryCount + 1)
+            .then(resolve)
+            .catch(reject);
+        }, RETRY_DELAY);
+        return;
+      }
+      
+      reject(err);
+    });
   });
 }
 
 async function extractArchive(archivePath, extractDir, platform) {
   if (platform === 'windows') {
-    // Use PowerShell to extract zip on Windows
-    await execAsync(`powershell -command "Expand-Archive -Path '${archivePath}' -DestinationPath '${extractDir}' -Force"`);
+    // Use safer PowerShell execution with proper escaping
+    const escapedArchivePath = archivePath.replace(/'/g, "''");
+    const escapedExtractDir = extractDir.replace(/'/g, "''");
+    
+    const powershellCommand = [
+      'powershell.exe',
+      '-NoProfile',
+      '-ExecutionPolicy', 'Bypass',
+      '-Command',
+      `Expand-Archive -LiteralPath '${escapedArchivePath}' -DestinationPath '${escapedExtractDir}' -Force`
+    ];
+    
+    await new Promise((resolve, reject) => {
+      const child = spawn(powershellCommand[0], powershellCommand.slice(1), {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true
+      });
+      
+      let stderr = '';
+      child.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+      
+      child.on('close', (code) => {
+        if (code === 0) {
+          resolve();
+        } else {
+          reject(new Error(`PowerShell extraction failed with code ${code}: ${stderr}`));
+        }
+      });
+      
+      child.on('error', reject);
+    });
   } else {
-    // Use tar for Unix-like systems
-    await execAsync(`tar -xzf "${archivePath}" -C "${extractDir}"`);
+    // Use spawn instead of exec for better security and error handling
+    await new Promise((resolve, reject) => {
+      const child = spawn('tar', ['-xzf', archivePath, '-C', extractDir], {
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+      
+      let stderr = '';
+      child.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+      
+      child.on('close', (code) => {
+        if (code === 0) {
+          resolve();
+        } else {
+          reject(new Error(`tar extraction failed with code ${code}: ${stderr}`));
+        }
+      });
+      
+      child.on('error', reject);
+    });
   }
 }
 
 async function install() {
   try {
+    // Check Node.js version compatibility
+    const nodeVersion = process.version;
+    const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0]);
+    if (majorVersion < 20) {
+      console.error(`Error: Node.js ${nodeVersion} is not supported. Please upgrade to Node.js 20 or later.`);
+      process.exit(1);
+    }
+    
     const { os, arch } = getPlatform();
     const binaryName = getBinaryName(os);
     
-    // Get version from package.json
+    
     const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
     const version = packageJson.version;
     
-    // Construct download URL
+    
     const archiveExt = os === 'windows' ? 'zip' : 'tar.gz';
     const archiveName = `ai-rulez_${version}_${os}_${arch}.${archiveExt}`;
     const downloadUrl = `https://github.com/${REPO_NAME}/releases/download/v${version}/${archiveName}`;
+    const checksumUrl = `https://github.com/${REPO_NAME}/releases/download/v${version}/checksums.txt`;
     
     console.log(`Downloading ai-rulez ${version} for ${os}/${arch}...`);
     console.log(`URL: ${downloadUrl}`);
     
-    // Create bin directory
+    
     const binDir = path.join(__dirname, 'bin');
     if (!fs.existsSync(binDir)) {
       fs.mkdirSync(binDir, { recursive: true });
     }
     
-    // Download archive
+    
     const archivePath = path.join(__dirname, archiveName);
+    
+    // Download checksums first for verification
+    console.log('Downloading checksums...');
+    const checksumPath = path.join(__dirname, 'checksums.txt');
+    try {
+      await downloadBinary(checksumUrl, checksumPath);
+    } catch (checksumError) {
+      console.warn('Warning: Could not download checksums, skipping verification');
+    }
+    
     await downloadBinary(downloadUrl, archivePath);
     
-    // Extract archive
+    // Verify checksum if available
+    if (fs.existsSync(checksumPath)) {
+      console.log('Verifying checksum...');
+      const expectedHash = await getExpectedChecksum(checksumPath, archiveName);
+      if (expectedHash) {
+        const actualHash = await calculateSHA256(archivePath);
+        if (actualHash !== expectedHash) {
+          throw new Error(`Checksum verification failed. Expected: ${expectedHash}, Got: ${actualHash}`);
+        }
+        console.log('✓ Checksum verified');
+      }
+      fs.unlinkSync(checksumPath);
+    }
+    
+    
     console.log('Extracting binary...');
     await extractArchive(archivePath, binDir, os);
     
-    // Make binary executable on Unix-like systems
+    
+    const binaryPath = path.join(binDir, binaryName);
+    if (!fs.existsSync(binaryPath)) {
+      throw new Error(`Binary not found after extraction: ${binaryPath}`);
+    }
+    
+    
     if (os !== 'windows') {
-      const binaryPath = path.join(binDir, binaryName);
       fs.chmodSync(binaryPath, 0o755);
     }
     
-    // Clean up archive
+    // Verify binary is executable
+    try {
+      await new Promise((resolve, reject) => {
+        const testCommand = os === 'windows' ? [binaryPath, '--version'] : [binaryPath, '--version'];
+        const child = spawn(testCommand[0], testCommand.slice(1), {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          timeout: 5000
+        });
+        
+        child.on('close', (code) => {
+          // Any exit code is fine, we just want to verify it can execute
+          resolve();
+        });
+        
+        child.on('error', (err) => {
+          if (err.code === 'ENOENT') {
+            reject(new Error('Downloaded binary is not executable'));
+          } else {
+            resolve(); // Other errors are OK for version check
+          }
+        });
+      });
+    } catch (verifyError) {
+      console.warn('Warning: Could not verify binary execution:', verifyError.message);
+    }
+    
+    
     fs.unlinkSync(archivePath);
     
     console.log(`✅ ai-rulez ${version} installed successfully for ${os}/${arch}!`);
@@ -134,7 +355,20 @@ async function install() {
   }
 }
 
-// Only run install during postinstall
+
+// Export functions for testing
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    getPlatform,
+    getBinaryName,
+    downloadBinary,
+    extractArchive,
+    calculateSHA256,
+    getExpectedChecksum,
+    install
+  };
+}
+
 if (require.main === module) {
   install();
 }

package/package.json

@@ -1,18 +1,51 @@
 {
   "name": "ai-rulez",
-  "version": "1.0.0-rc9",
-  "description": "CLI tool for managing AI assistant rules - generate configuration files for Claude, Cursor, Windsurf and more",
-  "keywords": ["ai", "rules", "configuration", "claude", "cursor", "windsurf", "cli", "assistant", "copilot", "generator"],
+  "version": "1.1.0",
+  "description": "⚡ Lightning-fast CLI tool (written in Go) for managing AI assistant rules - generate configuration files for Claude, Cursor, Windsurf and more",
+  "keywords": [
+    "ai",
+    "ai-assistant", 
+    "ai-rules",
+    "claude",
+    "cursor", 
+    "windsurf",
+    "codeium",
+    "copilot",
+    "cli",
+    "cli-tool",
+    "configuration",
+    "config",
+    "rules",
+    "generator",
+    "golang",
+    "go",
+    "fast",
+    "development",
+    "developer-tools",
+    "automation",
+    "workflow", 
+    "productivity",
+    "pre-commit",
+    "git-hooks",
+    "lefthook",
+    "code-generation",
+    "ai-development",
+    "assistant-configuration"
+  ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/Goldziher/ai-rulez"
+    "url": "https://github.com/Goldziher/ai-rulez.git"
   },
-  "homepage": "https://github.com/Goldziher/ai-rulez",
+  "homepage": "https://github.com/Goldziher/ai-rulez#readme",
   "bugs": {
     "url": "https://github.com/Goldziher/ai-rulez/issues"
   },
   "license": "MIT",
-  "author": "Na'aman Hirschfeld <nhirschfeld@gmail.com>",
+  "author": {
+    "name": "Na'aman Hirschfeld",
+    "email": "nhirschfeld@gmail.com",
+    "url": "https://github.com/Goldziher"
+  },
   "bin": {
     "ai-rulez": "./bin/ai-rulez"
   },
@@ -21,10 +54,20 @@
   },
   "files": [
     "bin",
-    "install.js",
+    "install.js", 
     "README.md"
   ],
   "engines": {
     "node": ">=14.0.0"
-  }
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64", 
+    "arm64",
+    "ia32"
+  ]
 }