CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7This is a repository for managing and distributing Cursor AI rules, particularly focused on web development with strong emphasis on PHP/Drupal, frontend frameworks, and security best practices. The project provides an interactive PHP installer that allows developers to selectively install rule sets into their projects.
8 
9## Common Development Tasks
10 
11### Running Tests
12```bash
13# Run all tests
14cd .tests && ./run-all-tests.sh
15 
16# Run individual test scripts
17cd .tests
18./test-copy.sh              # Test basic installation functionality
19./test-debug.sh             # Test debug mode
20./test-invalid-option.sh    # Test invalid option handling
21./test-conflicting-options.sh  # Test conflicting options
22./test-missing-files.sh     # Test missing file handling
23```
24 
25### Testing the Installer
26```bash
27# Test installation interactively
28php install.php
29 
30# Test with specific options
31php install.php --core           # Install core rules only
32php install.php --web-stack      # Install web stack rules (includes core)
33php install.php --python         # Install Python rules (includes core)
34php install.php --all            # Install all rules
35 
36# Test with debug mode
37php install.php --debug --core
38 
39# Test installation to custom directory
40php install.php --all --destination=my/custom/path
41 
42# Test installation via curl (non-interactive)
43curl -s https://raw.githubusercontent.com/ivangrynenko/cursor-rules/main/install.php | php -- --ws
44cat install.php | php -- --core   # Test piped input locally
45```
46 
47### Linting and Code Quality
48- PHP syntax validation: `php -l install.php`
49- No specific linting commands configured - consider adding phpcs/phpmd
50 
51## Architecture and Code Structure
52 
53### Project Organization
54- **install.php**: Main installer script (current version defined by CURSOR_RULES_VERSION constant)
55- **.cursor/rules/**: Contains 56 MDC rule files organized by category
56- **.cursor/UPDATE.md**: Installation receipt file tracking installed version and configuration (created by installer)
57- **.tests/**: Bash test scripts for installer validation
58- **.github/workflows/**: CI/CD pipeline using GitHub Actions for PHP 8.3
59- **AGENTS.md**: Comprehensive guide for using Cursor Rules (created by installer)
60 
61### Rule Categories
621. **Core Rules** (7 files): Git standards, testing guidelines, README maintenance
632. **Web Development Rules**:
64   - Frontend: JavaScript, React, Vue, Tailwind, accessibility
65   - Backend: PHP/Drupal standards, database
66   - Security: OWASP Top 10 implementations for Drupal
67   - DevOps: Docker, Lagoon, Vortex configurations
683. **Python Rules** (10 files): Security-focused rules following OWASP standards
69 
70### Key Design Patterns
71- **Installer Architecture**:
72  - Stateless design - each execution is independent
73  - Builder pattern for rule set construction
74  - Strategy pattern for interactive vs non-interactive modes
75  - Factory pattern for rule set management
76 
77### Installation Flow
781. User executes install.php (directly or via curl)
792. Script detects if running interactively or with parameters
803. Creates .cursor/rules directory structure
814. Downloads and installs selected rule files from GitHub
825. Creates/overwrites .cursor/UPDATE.md file as an installation receipt
836. Creates/updates AGENTS.md documentation (unless --yes flag overwrites)
84 
85## Versioning System
86 
87### Version Management
88- **Version Constant**: Defined in install.php as `CURSOR_RULES_VERSION`
89- **Version History**: Tracked in GitHub releases and repository documentation
90- **Release Process**:
91  1. Update CURSOR_RULES_VERSION constant in install.php
92  2. Update version history in repository documentation
93  3. Create GitHub release matching the version number
94  4. Tag the release in git
95 
96### .cursor/UPDATE.md File Purpose
97The UPDATE.md file serves as an installation receipt that:
98- Records the version of cursor-rules that was installed
99- Documents the installation date and time
100- Lists the number of rule files installed
101- Shows the installation type (core, web-stack, Python, etc.)
102- Records any tag filters that were applied
103- Gets created/overwritten by the installer on each run
104- Helps users identify which version and configuration they have installed
105 
106## Known Issues and Solutions
107 
108### Curl Piping Issues (Fixed in v1.0.6)
109When piping the installer through curl, several PHP-specific behaviors can cause problems:
110 
111**Problem**: Script hangs when using `curl ... | php` commands
112**Root Causes**:
1131. `$_SERVER['PHP_SELF']` becomes "Standard input code" instead of script name when piped
1142. PHP continues waiting for STDIN input even after script completion
1153. Arguments may not parse correctly when using `--` separator with piped input
116 
117**Solutions Implemented**:
1181. **Entry Point Detection**: Check for both normal execution and "Standard input code"
119```php
120   if (basename(__FILE__) === basename($_SERVER['PHP_SELF'] ?? '') || 
121       ($_SERVER['PHP_SELF'] ?? '') === 'Standard input code')
122```
123 
1242. **STDIN Cleanup**: Always close STDIN before exit to prevent hanging
125```php
126   if (defined('STDIN') && is_resource(STDIN)) {
127       fclose(STDIN);
128   }
129```
130 
1313. **Argument Parsing**: Handle both with and without `--` separator
132```php
133   if (!stream_isatty(STDIN) && $_SERVER['PHP_SELF'] === 'Standard input code') {
134       // Parse arguments from argv when piped
135   }
136```
137 
138### Testing Coverage Gaps
139**Issue**: Test suite only covered direct PHP execution, not curl piping scenarios
140**Recommendation**: Add tests for:
141- `curl ... | php` execution paths
142- `cat install.php | php` scenarios
143- Argument parsing with and without `--` separator
144- STDIN handling in different contexts
145 
146## Important Considerations
147 
148### When Adding New Rules
149- Follow MDC format (Markdown with custom rule syntax)
150- Place in appropriate category under .cursor/rules/
151- Update the rule arrays in install.php (core_rules, web_stack_rules, python_rules)
152- Add rule to README.md documentation table
153- Consider rule dependencies (e.g., web stack includes core rules)
154 
155### When Modifying the Installer
156- Maintain PHP 8.3+ compatibility
157- Preserve both interactive and non-interactive modes
158- Update CURSOR_RULES_VERSION constant when making changes
159- Ensure all tests pass before committing
160- Test with both local files and GitHub downloads
161 
162### Testing Guidelines
163- All tests are bash scripts in .tests/ directory
164- Tests use temporary directories to avoid affecting the actual installation
165- Each test should output clear success/failure messages
166- GitHub Actions runs all tests on push/PR to main branch
167 
168## Security Considerations
169- Never commit sensitive information or API keys
170- Rule files should not contain hardcoded credentials
171- Installer validates file permissions and directory creation
172- Downloaded files are fetched over HTTPS from GitHub
173 
174## Contributing
175- Follow conventional commits format (fix:, feat:, docs:, etc.)
176- Update relevant documentation when adding features
177- Ensure all tests pass before submitting PR
178- New rules should include clear descriptions and examples