From 4cf03dd0cda28d5baf42f193606aa6e811e4317d Mon Sep 17 00:00:00 2001 From: Ivan Grynenko Date: Wed, 20 Aug 2025 19:57:13 +1000 Subject: [PATCH 1/2] docs: add lessons learned from curl piping issues and versioning documentation - Document curl piping issues and solutions from v1.0.6 - Explain versioning system and release process - Document .cursor/UPDATE.md file purpose - Add testing recommendations for piped execution - Update project organization documentation --- CLAUDE.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index aac9eff..a19eeab 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,6 +38,10 @@ php install.php --debug --core # Test installation to custom directory php install.php --all --destination=my/custom/path + +# Test installation via curl (non-interactive) +curl -s https://raw.githubusercontent.com/ivangrynenko/cursor-rules/main/install.php | php -- --ws +cat install.php | php -- --core # Test piped input locally ``` ### Linting and Code Quality @@ -47,10 +51,12 @@ php install.php --all --destination=my/custom/path ## Architecture and Code Structure ### Project Organization -- **install.php**: Main installer script (v1.0.4) - Uses builder and strategy patterns for rule set installation +- **install.php**: Main installer script (current version defined by CURSOR_RULES_VERSION constant) - **.cursor/rules/**: Contains 56 MDC rule files organized by category +- **.cursor/UPDATE.md**: Version history file tracking all releases and changes (created by installer) - **.tests/**: Bash test scripts for installer validation - **.github/workflows/**: CI/CD pipeline using GitHub Actions for PHP 8.3 +- **AGENTS.md**: Comprehensive guide for using Cursor Rules (created by installer) ### Rule Categories 1. **Core Rules** (7 files): Git standards, testing guidelines, README maintenance @@ -73,7 +79,69 @@ php install.php --all --destination=my/custom/path 2. Script detects if running interactively or with parameters 3. Creates .cursor/rules directory structure 4. Downloads and installs selected rule files from GitHub -5. Creates UPDATE.md file to track version +5. Creates/updates .cursor/UPDATE.md file to track version history +6. Creates/updates AGENTS.md documentation (unless --yes flag overwrites) + +## Versioning System + +### Version Management +- **Version Constant**: Defined in install.php as `CURSOR_RULES_VERSION` +- **Version History**: Tracked in .cursor/UPDATE.md file +- **Release Process**: + 1. Update CURSOR_RULES_VERSION constant in install.php + 2. Add version entry to .cursor/UPDATE.md with date and changes + 3. Create GitHub release matching the version number + 4. Tag the release in git + +### .cursor/UPDATE.md File Purpose +The UPDATE.md file serves as a version history log that: +- Tracks all changes made in each version +- Documents new features, bug fixes, and improvements +- Records the date of each release +- Lists affected files and their impact +- Notes any breaking changes +- Gets created/updated automatically by the installer in user projects +- Helps users understand what changed between versions + +## Known Issues and Solutions + +### Curl Piping Issues (Fixed in v1.0.6) +When piping the installer through curl, several PHP-specific behaviors can cause problems: + +**Problem**: Script hangs when using `curl ... | php` commands +**Root Causes**: +1. `$_SERVER['PHP_SELF']` becomes "Standard input code" instead of script name when piped +2. PHP continues waiting for STDIN input even after script completion +3. Arguments may not parse correctly when using `--` separator with piped input + +**Solutions Implemented**: +1. **Entry Point Detection**: Check for both normal execution and "Standard input code" + ```php + if (basename(__FILE__) === basename($_SERVER['PHP_SELF'] ?? '') || + ($_SERVER['PHP_SELF'] ?? '') === 'Standard input code') + ``` + +2. **STDIN Cleanup**: Always close STDIN before exit to prevent hanging + ```php + if (defined('STDIN') && is_resource(STDIN)) { + fclose(STDIN); + } + ``` + +3. **Argument Parsing**: Handle both with and without `--` separator + ```php + if (!stream_isatty(STDIN) && $_SERVER['PHP_SELF'] === 'Standard input code') { + // Parse arguments from argv when piped + } + ``` + +### Testing Coverage Gaps +**Issue**: Test suite only covered direct PHP execution, not curl piping scenarios +**Recommendation**: Add tests for: +- `curl ... | php` execution paths +- `cat install.php | php` scenarios +- Argument parsing with and without `--` separator +- STDIN handling in different contexts ## Important Considerations From c2e1f114329acf43ea69053c694b2bbbc54f4046 Mon Sep 17 00:00:00 2001 From: Ivan Grynenko Date: Wed, 20 Aug 2025 20:07:58 +1000 Subject: [PATCH 2/2] fix: address PR review feedback - correct entry point detection and UPDATE.md documentation - Added missing check for 'Standard input code' in entry point detection to properly handle curl piping - Corrected documentation to accurately describe UPDATE.md as an installation receipt (not version history) - Ensures consistency between documentation and actual implementation Addresses review comments from @gemini-code-assist on PR #13 --- CLAUDE.md | 24 ++++++++++++------------ install.php | 4 +++- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a19eeab..a666b96 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -53,7 +53,7 @@ cat install.php | php -- --core # Test piped input locally ### Project Organization - **install.php**: Main installer script (current version defined by CURSOR_RULES_VERSION constant) - **.cursor/rules/**: Contains 56 MDC rule files organized by category -- **.cursor/UPDATE.md**: Version history file tracking all releases and changes (created by installer) +- **.cursor/UPDATE.md**: Installation receipt file tracking installed version and configuration (created by installer) - **.tests/**: Bash test scripts for installer validation - **.github/workflows/**: CI/CD pipeline using GitHub Actions for PHP 8.3 - **AGENTS.md**: Comprehensive guide for using Cursor Rules (created by installer) @@ -79,29 +79,29 @@ cat install.php | php -- --core # Test piped input locally 2. Script detects if running interactively or with parameters 3. Creates .cursor/rules directory structure 4. Downloads and installs selected rule files from GitHub -5. Creates/updates .cursor/UPDATE.md file to track version history +5. Creates/overwrites .cursor/UPDATE.md file as an installation receipt 6. Creates/updates AGENTS.md documentation (unless --yes flag overwrites) ## Versioning System ### Version Management - **Version Constant**: Defined in install.php as `CURSOR_RULES_VERSION` -- **Version History**: Tracked in .cursor/UPDATE.md file +- **Version History**: Tracked in GitHub releases and repository documentation - **Release Process**: 1. Update CURSOR_RULES_VERSION constant in install.php - 2. Add version entry to .cursor/UPDATE.md with date and changes + 2. Update version history in repository documentation 3. Create GitHub release matching the version number 4. Tag the release in git ### .cursor/UPDATE.md File Purpose -The UPDATE.md file serves as a version history log that: -- Tracks all changes made in each version -- Documents new features, bug fixes, and improvements -- Records the date of each release -- Lists affected files and their impact -- Notes any breaking changes -- Gets created/updated automatically by the installer in user projects -- Helps users understand what changed between versions +The UPDATE.md file serves as an installation receipt that: +- Records the version of cursor-rules that was installed +- Documents the installation date and time +- Lists the number of rule files installed +- Shows the installation type (core, web-stack, Python, etc.) +- Records any tag filters that were applied +- Gets created/overwritten by the installer on each run +- Helps users identify which version and configuration they have installed ## Known Issues and Solutions diff --git a/install.php b/install.php index 7e1b3e6..d11e07a 100644 --- a/install.php +++ b/install.php @@ -987,7 +987,9 @@ function show_help(): void { } // If this script is being run directly, execute the installation. -if (basename(__FILE__) === basename($_SERVER['PHP_SELF'] ?? '')) { +// Also handle execution when piped through curl (PHP_SELF becomes "Standard input code") +if (basename(__FILE__) === basename($_SERVER['PHP_SELF'] ?? '') || + ($_SERVER['PHP_SELF'] ?? '') === 'Standard input code') { // Default options $options = [ 'debug' => false,