jtsternberg Dot-Files .cursorrules file for PHP (stars: 5)

# CLI Script Conventions
New CLI scripts should be named like `bin/my-script`, and will be written preferably in PHP.

## Files
`bin/*`

## Language
`php`

## Patterns

### CLI Script Header Format
```php
#!/usr/bin/env php
<?php
namespace JT;
# =============================================================================
# {{description}}
# By Justin Sternberg <me@jtsternberg.com>
#
# Version {{version}}
#
# {{detailed_description}}
#
# Usage:
# {{command}} {{usage_example}}
#
# Examples:
# {{examples}}
# =============================================================================
```

### CLI Helpers Setup
```php
$cli = require_once dirname(__DIR__) . '/misc/helpers.php';
$helpyHelperton = $cli->getHelp();
```

### Single-Command Help Documentation

For when the command is a single command, with no sub-commands.

```php
$helpyHelperton
	->setScriptName('example')
	->setDescription('Description of example')
	->setSampleUsage('<arg1> <arg2> [<arg3>] [--flagWithValue=<value>] [--flag]')
	->buildDocs([
		'<arg1>'                  => 'Explanation of arg1',
		'<arg2>'                  => 'Explanation of arg2',
		'[<arg3>]'                => 'Explanation of arg3',
		'--flagWithValue=<value>' => 'Explanation of flagWithValue',
		'--flag'                  => 'Explanation of flag',
	]);

if ($helpyHelperton->batSignal) {
	$cli->msg($helpyHelperton->getHelp());
	exit(0);
}
```

### Sub-Command Help Documentation

For when the command only has sub-commands (not a primary command/function).

```php
$helpyHelperton
	->setScriptName('parentcommand')
	->setDescription('Description of parentcommand')
	->setup('parentcommand', [
		'subcommand' => [
			'<arg1> <arg2> [<arg3>] [--flagWithValue=<value>] [--flag]',
			'Description of subcommand',
'<arg1>          Explanation of arg1
<arg2>          Explanation of arg2
<arg3>          Explanation of arg3

--flagWithValue=<value>
                Longer explanation for flag with value
                Value can be one of: \'one\', \'two\', \'three\', \'four\'
                or yadda yadda yadda

--flag          Explanation of flag

-y, --yes       Will autoconfirm all prompts. Use to bla bla bla

--porcelain     Used to return clean output to other scripts.
-shh, --silent  Prevents outputting help/progress messages.',
		],
	]);

if ($helpyHelperton->batSignal) {
    $cli->msg($helpyHelperton->getHelp($cli->getArg(1)));
    exit(0);
}
```

### Primary command with sub-commands Help Documentation

For when the command is a primary command, with sub-commands.

```php
$helpyHelperton
	->setScriptName('primarycommand')
	->setDescription('Description of primarycommand')
	->setSampleUsage('<arg1> <arg2> [<arg3>] [--flagWithValue=<value>] [--flag]')
	->setupDefaultCommand([
		'<arg1>'                  => 'Explanation of arg1',
		'<arg2>'                  => 'Explanation of arg2',
		'[<arg3>]'                => 'Explanation of arg3',
		'--flagWithValue=<value>' => 'Explanation of flagWithValue',
		'--flag'                  => 'Explanation of flag',
	])
	->setup('primarycommand', [
		'subcommand' => [
			'<arg1> <arg2> [<arg3>] [--flagWithValue=<value>] [--flag]',
			'Description of subcommand',
'<arg1>          Explanation of arg1
<arg2>          Explanation of arg2
<arg3>          Explanation of arg3

--flagWithValue=<value>
                Longer explanation for flag with value
                Value can be one of: \'one\', \'two\', \'three\', \'four\'
                or yadda yadda yadda

--flag          Explanation of flag

-y, --yes       Will autoconfirm all prompts. Use to bla bla bla

--porcelain     Used to return clean output to other scripts.
-shh, --silent  Prevents outputting help/progress messages.',
		],
	]);

if ($helpyHelperton->batSignal) {
    $cli->msg($helpyHelperton->getHelp($cli->getArg(1)));
    exit(0);
}
```

## Conventions

### Namespace
- Use namespace JT for all CLI scripts

### Code Organization
- Use procedural PHP by default for simpler scripts
- Use classes when complexity warrants it (e.g. when script requires multiple methods or manages state)
- See `bin/localshellupdater` for procedural example
- See `bin/pr-description-generator` for class-based example

### Documentation
- Include comprehensive header documentation with usage and examples

### CLI Helper Methods
- Use `$cli` helper methods for:
  - Path handling (`convertPathToAbsolute`)
  - File operations (`writeToFile`)
  - Argument/flag parsing (`getArg`, `getFlag`)
  - Output messaging (`msg`, `err`)
  - User interaction:
    - `ask()` - CLI prompt with optional required response
    - `confirm()` - Yes/no confirmation prompt
    - `requestAnswer()` - Basic prompt for input
    - `isYes()`, `isNo()` - Check response values
  - Flag checking:
    - `hasFlag()`, `hasFlags()` - Check for --flag existence
    - `hasShortFlag()` - Check for -f style flags
    - `getFlag()` - Get value of --flag=value
  - Common state checks:
    - `isSilent()` - Check if --silent/--porcelain/-shh
    - `isVerbose()` - Check if --verbose/-v
    - `isAutoconfirm()` - Check if --yes/-y
  - Directory operations:
    - `getDirFiles()` - Get filtered directory contents
    - `filteredFileContentRows()` - Process file contents by line
  - Git operations via `$cli->git`:
    - See `helpers/git.php` for available methods
- Use `$helpyHelperton` for help documentation

### Color Conventions
- Red: errors
- Green: success
- Yellow: informational/warning

### Exit Codes
- 0: success
- 1: error

### File Operations
- File paths should be handled with `convertPathToAbsolute`
- File operations should use `writeToFile` with appropriate options

### Help Documentation
- Should be comprehensive and follow established patterns
- Scripts should validate required arguments
- Provide helpful error messages
- Error messages should include instructions for getting help

## Style Guidelines
- Use tabs for indentation (size: 3)
- Trim trailing whitespace
- Insert final newline
- Follow PSR-12 naming conventions
- Use meaningful variable names
- Include appropriate spacing around operators
- Group related code blocks with newlines
- Add comments for complex operations