docs: update copilot-instructions.md with latest project information

.github/copilot-instructions.md

@@ -5,22 +5,27 @@ This repository contains a monorepo of popular components for the Hyperf PHP fra
 ## Project Overview
 
 - **Repository**: friendsofhyperf/components
-- **Type**: Monorepo containing 50+ Hyperf components
+- **Type**: Monorepo containing 49 Hyperf components
 - **PHP Version**: >=8.1
 - **Framework**: Hyperf >=3.1.0
+- **Testing Framework**: Pest (PHPUnit under the hood)
 - **License**: MIT
 - **Main Author**: Deeka Wong (huangdijia@gmail.com)
 
 ## Repository Structure
 
 ```
 /
-├── bin/                    # Utility scripts
+├── bin/                    # Utility scripts (split, docs, JSON normalization)
 ├── docs/                   # Multi-language documentation (VitePress)
-├── src/                    # Component source code (50+ components)
-├── tests/                  # Test suites
+├── src/                    # Component source code (49 components)
+├── tests/                  # Pest test suites mirroring src/ structure
+├── types/                  # PHP stubs for type hints
 ├── composer.json           # Main composer configuration
-└── package.json           # Documentation build configuration
+├── package.json            # Documentation translation scripts
+├── AGENTS.md               # Repository guidelines for AI agents
+├── CLAUDE.md               # Claude Code guidelines
+└── .github/                # GitHub workflows and copilot instructions
 ```
 
 ## Component Architecture
@@ -39,14 +44,55 @@ src/{component-name}/
 ```
 
 ### Key Components Include:
-- **Cache**: Enhanced caching functionality
-- **Http Client**: HTTP client utilities
-- **Elasticsearch**: Elasticsearch integration
-- **Notification**: Multi-channel notifications
-- **Model Factory**: Database model factories
-- **Telescope**: Application debugging and monitoring
-- **Tinker**: Interactive REPL
-- **Validation**: Enhanced validation features
+
+**Development Tools:**
+- **telescope**: Application debugging and monitoring
+- **tinker**: Interactive REPL
+- **ide-helper**: IDE auto-completion support
+- **pretty-console**: Enhanced console output
+- **web-tinker**: Web-based REPL interface
+
+**Database & Models:**
+- **model-factory**: Database model factories
+- **model-observer**: Model event observers
+- **model-scope**: Query scopes for models
+- **model-hashids**: Hashids for model IDs
+- **fast-paginate**: Optimized pagination
+- **compoships**: Multi-column relationships
+- **mysql-grammar-addon**: MySQL grammar extensions
+
+**Caching & Storage:**
+- **cache**: Enhanced caching functionality
+- **lock**: Distributed locking
+- **redis-subscriber**: Redis pub/sub support
+
+**HTTP & API:**
+- **http-client**: HTTP client utilities
+- **oauth2-server**: OAuth2 server implementation
+- **openai-client**: OpenAI API client
+
+**Notifications & Mail:**
+- **notification**: Multi-channel notifications
+- **notification-mail**: Email notifications
+- **notification-easysms**: SMS notifications via EasySms
+- **mail**: Email sending functionality
+
+**Search:**
+- **elasticsearch**: Elasticsearch integration
+- **telescope-elasticsearch**: Telescope with Elasticsearch storage
+
+**Security:**
+- **encryption**: Encryption utilities
+- **purifier**: HTML purification
+- **recaptcha**: Google reCAPTCHA integration
+- **validated-dto**: Data transfer object validation
+
+**Infrastructure:**
+- **confd**: Configuration from external sources
+- **config-consul**: Consul configuration center
+- **facade**: Laravel-style facades
+- **sentry**: Sentry error tracking integration
+- **ipc-broadcaster**: Inter-process communication
 
 ## Development Conventions
 
@@ -64,11 +110,15 @@ Each component typically includes a `ConfigProvider.php` file that defines:
 - Follows PSR-12 coding standards
 - Uses PHP-CS-Fixer for code formatting (`.php-cs-fixer.php`)
 - PHPStan for static analysis (`phpstan.neon.dist`)
+- All files include `declare(strict_types=1)`
+- 4-space indentation, short array syntax
 
 ### Testing
-- Uses PHPUnit for testing (`phpunit.xml.dist`)
-- Test files located in `tests/` directory
-- Follows Hyperf testing patterns
+- Uses Pest testing framework (`phpunit.xml.dist`)
+- Test files located in `tests/` directory mirroring `src/` structure
+- Tests are grouped by component using `->group()` modifier
+- Run specific component tests with `--group` flag
+- Follows AAA pattern (Arrange, Act, Assert)
 
 ## Documentation Structure
 
@@ -87,17 +137,25 @@ Documentation is available in multiple languages:
 ## Build and Deployment
 
 ### Scripts Available:
+- `bin/regenerate-readme.sh` - Generate component README files
 - `bin/generate-repository-doc.sh` - Generate component documentation
 - `bin/doc-translate` - PHP-based translation script
-- `bin/doc-translate.github-model.js` - AI-powered translation
+- `bin/doc-translate.js` - Node.js AI-powered translation
+- `bin/doc-translate.github-model.js` - GitHub model translation
 - `bin/split-docs.sh` - Deploy documentation to separate repository
+- `bin/split.sh` - Split components to individual repositories
+- `bin/composer-json-fixer` - Fix component composer.json files
+- `bin/pending-repositories.sh` - Check pending repository changes
+- `bin/pending-composer-json` - Check pending composer.json changes
 
 ### GitHub Actions:
-- `tests.yaml` - Run test suite
+- `tests.yaml` - Run test suite (lint, unit, type coverage)
 - `docs-split.yaml` - Deploy documentation
 - `docs-translate.yaml` - Auto-translate documentation
 - `release.yaml` - Handle releases
 - `split.yaml` - Split components to individual repositories
+- `update-changelog.yml` - Update changelog
+- `cnb.yaml` - CNB workflow
 
 ## Development Workflow
 
@@ -119,23 +177,28 @@ Documentation is available in multiple languages:
 ### Configuration Provider Template:
 ```php
 <?php
+
+declare(strict_types=1);
+
 namespace FriendsOfHyperf\ComponentName;
 
 class ConfigProvider
 {
     public function __invoke(): array
     {
         return [
-            'dependencies' => [],
-            'commands' => [],
-            'listeners' => [],
-            'annotations' => [
+            'dependencies' => [],    // DI container bindings
+            'commands' => [],        // Console commands
+            'listeners' => [],       // Event listeners
+            'aspects' => [],         // AOP aspects
+            'annotations' => [       // Annotation scanning
                 'scan' => [
                     'paths' => [
                         __DIR__,
                     ],
                 ],
             ],
+            'publish' => [],         // Publishable assets
         ];
     }
 }
@@ -167,11 +230,13 @@ class ConfigProvider
 ## Common Dependencies
 
 The project commonly uses:
-- Hyperf framework components
-- Symfony components for console, HTTP foundation
-- Laravel components for certain utilities
-- Guzzle for HTTP clients
+- Hyperf framework components (hyperf/framework, hyperf/di, hyperf/command, etc.)
+- Symfony components (console, http-foundation, process, var-dumper, uid)
+- Laravel utilities (serializable-closure)
 - Carbon for date/time handling
+- Guzzle for HTTP operations (via hyperf/guzzle)
+- Ramsey UUID for UUID generation
+- PSR interfaces for interoperability
 
 ## Installation Instructions
 
@@ -187,10 +252,27 @@ composer require friendsofhyperf/components
 
 ## Testing Conventions
 
+- Use Pest for all new tests
 - Test files should be in `tests/` directory
-- Use Hyperf testing utilities
+- Tests are grouped by component (e.g., `->group('telescope')`)
+- Use descriptive test names and data providers
+- Keep unit tests deterministic (no network calls)
 - Mock external dependencies appropriately
 - Follow AAA pattern (Arrange, Act, Assert)
+- Run `composer test:types` to ensure type coverage
+
+### Running Specific Tests:
+```bash
+# Run tests for a specific component
+vendor/bin/pest --group=telescope
+vendor/bin/pest --group=http-client
+
+# Run a specific test file
+vendor/bin/pest tests/HttpClient/PendingRequestTest.php
+
+# Run a specific test method
+vendor/bin/pest --filter=test_method_name
+```
 
 ## Documentation Standards
 
@@ -208,6 +290,13 @@ composer require friendsofhyperf/components
 5. Update documentation
 6. Submit pull request
 
+### Commit Convention
+Use Conventional Commits format:
+- `feat(cache): add redis tagging`
+- `fix(tinker): handle empty input`
+- `docs(telescope): update installation guide`
+- `refactor(http-client): simplify retry logic`
+
 ## Deployment and Release
 
 - Components are split into individual repositories
@@ -221,6 +310,25 @@ When working with this codebase, prioritize:
 3. Comprehensive documentation
 4. Test coverage
 5. Performance considerations for framework components
+6. Coroutine safety (Swoole/Swow compatibility)
+
+## Coroutine Safety
+
+All code must be coroutine-safe. Avoid:
+- Global state without proper context management
+- Blocking I/O operations
+- Non-coroutine-safe third-party libraries without wrappers
+
+Use Hyperf's context API for request-scoped data:
+```php
+use Hyperf\Context\Context;
+
+// Store in context
+Context::set('key', $value);
+
+// Retrieve from context
+Context::get('key');
+```
 
 ## Working with the Codebase
 
@@ -238,11 +346,13 @@ However, if some tool calls depend on previous calls to inform dependent values
 
 ### Testing Strategy
 - Run existing tests before making changes to understand baseline
-- Create focused tests for new functionality
-- Use PHPUnit following Hyperf testing patterns
-- Mock external dependencies appropriately
+- Create focused tests for new functionality using Pest
+- Use Pest's `uses()` helper to apply base test case
+- Group tests by component using `->group()` modifier
+- Mock external dependencies appropriately (ValidatorFactory, ConfigInterface, etc.)
 - Run tests iteratively after each change
 - Don't remove or edit unrelated tests
+- Ensure `composer test:types` stays green before pushing
 
 ### Error Handling
 - Check for and handle PHP errors appropriately
@@ -261,13 +371,20 @@ However, if some tool calls depend on previous calls to inform dependent values
 
 ### Build and Test Commands
 Common commands for this repository:
-- `composer install` - Install PHP dependencies
-- `composer test` - Run all tests (lint, unit, types)
-- `composer cs-fix` - Run PHP-CS-Fixer
-- `composer analyse` - Run PHPStan analysis
+- `composer install` - Install PHP dependencies (requires PHP ≥8.1)
+- `composer test` - Run all tests (lint, unit, type coverage)
+- `composer test:unit` - Run Pest unit tests only
+- `composer test:lint` - Run PHP-CS-Fixer checks (dry run)
+- `composer test:types` - Run type coverage analysis
+- `composer cs-fix` - Auto-fix code style issues
+- `composer analyse` - Run PHPStan static analysis
+- `composer analyse:types` - Run stricter type analysis
+- `composer json-fix` - Normalize composer.json files
+- `composer gen:readme` - Generate README files
 - `cd docs && pnpm install` - Install documentation dependencies
 - `cd docs && pnpm run docs:dev` - Run documentation dev server
 - `cd docs && pnpm run docs:build` - Build documentation
+- `npm run docs:translate` - Translate documentation (from root)
 
 ### Reporting Progress
 - Use `report_progress` early to outline your plan