Skip to content

docs: add lessons learned from curl piping issues #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ivangrynenko merged 2 commits into from
Aug 20, 2025
Merged

docs: add lessons learned from curl piping issues #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4cf03dd
docs: add lessons learned from curl piping issues and versioning docu…
ivangrynenko Aug 20, 2025
c2e1f11
fix: address PR review feedback - correct entry point detection and U…
ivangrynenko Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 70 additions & 2 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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**: 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)

### Rule Categories
1. **Core Rules** (7 files): Git standards, testing guidelines, README maintenance
Expand All @@ -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/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 GitHub releases and repository documentation
- **Release Process**:
1. Update CURSOR_RULES_VERSION constant in install.php
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 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

### 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')
```
Comment on lines +118 to +122
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Aug 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The documented solution for entry point detection does not seem to match the implementation in install.php. The documentation claims the fix is to use if (basename(__FILE__) === basename($_SERVER['PHP_SELF'] ?? '') || ($_SERVER['PHP_SELF'] ?? '') === 'Standard input code'), which would correctly handle piped execution.

However, the provided install.php at line 990 only has if (basename(__FILE__) === basename($_SERVER['PHP_SELF'] ?? '')). This condition will likely be false when the script is piped, preventing the main installation logic from running.

Please verify that the fix is correctly implemented and update the documentation or the code to be consistent. If the implementation is different, the documentation should reflect the actual 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

Expand Down
4 changes: 3 additions & 1 deletion install.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down