@silverassist/agents-toolkit 2.0.0

package/templates/shared/instructions/testing-standards.instructions.md

@@ -0,0 +1,264 @@
+---
+description: PHPUnit testing standards, conventions, and patterns for Silver Assist WordPress plugins using WP_UnitTestCase
+name: Testing Standards
+applyTo: "tests/**/*.php"
+---
+
+# PHPUnit Testing Standards — Silver Assist Plugins
+
+**Applies to**: All test files in Silver Assist WordPress plugins
+
+---
+
+## Must-Follow Rules
+
+### 1. Base Class: All Tests Extend TestCase (WP_UnitTestCase)
+
+```php
+use SilverAssist\PluginName\Tests\Helpers\TestCase;
+
+class MyTest extends TestCase {
+    // Tests here.
+}
+```
+
+### 2. Lifecycle Methods Use WordPress snake_case
+
+Since TestCase extends WP_UnitTestCase, use WordPress-style snake_case:
+
+```php
+// ✅ CORRECT — WordPress snake_case (WP_UnitTestCase).
+public function set_up(): void
+public function tear_down(): void
+public static function set_up_before_class(): void
+public static function tear_down_after_class(): void
+
+// ❌ WRONG — PHPUnit camelCase (don't use with WP_UnitTestCase).
+public function setUp(): void
+public function tearDown(): void
+```
+
+### 3. Test Method Naming — camelCase
+
+```php
+// ✅ CORRECT — Descriptive camelCase test names.
+public function testStartRequestCreatesLogEntry(): void
+public function testSearchMatchesSenderName(): void
+
+// ❌ WRONG — Vague names.
+public function testMethod(): void
+public function testItWorks(): void
+```
+
+### 4. Database Queries: Use %i for Table Names
+
+```php
+// ✅ CORRECT
+$wpdb->prepare( 'SELECT * FROM %i WHERE id = %d', $table_name, $id );
+
+// ❌ WRONG — Variable interpolation.
+$wpdb->prepare( "SELECT * FROM {$table_name} WHERE id = %d", $id );
+```
+
+### 5. Skip When Dependencies Missing
+
+```php
+public function set_up(): void {
+    parent::set_up();
+
+    if ( ! class_exists( 'WPCF7_ContactForm' ) ) {
+        $this->markTestSkipped( 'Contact Form 7 not loaded' );
+        return; // IMPORTANT: always return after skip.
+    }
+}
+```
+
+### 6. Always Clean Up Resources
+
+```php
+public function tear_down(): void {
+    $this->service = null;
+    parent::tear_down();
+}
+```
+
+### 7. Use PHPDoc Group Annotations
+
+```php
+/**
+ * Tests for ClassName.
+ *
+ * @group unit
+ * @group logging
+ * @covers \SilverAssist\PluginName\Service\ClassName
+ */
+class ClassNameTest extends TestCase {
+}
+```
+
+---
+
+## Test Structure Template
+
+```php
+<?php
+/**
+ * Tests for ClassName.
+ *
+ * @package SilverAssist\PluginName\Tests\Unit
+ */
+
+namespace SilverAssist\PluginName\Tests\Unit\Service\Category;
+
+use SilverAssist\PluginName\Tests\Helpers\TestCase;
+use SilverAssist\PluginName\Service\Category\ClassName;
+
+/**
+ * ClassName test case.
+ *
+ * @group unit
+ * @group service
+ * @covers \SilverAssist\PluginName\Service\Category\ClassName
+ */
+class ClassNameTest extends TestCase {
+
+    /**
+     * Instance under test.
+     *
+     * @var ClassName|null
+     */
+    private ?ClassName $instance = null;
+
+    /**
+     * Set up test fixtures.
+     */
+    public function set_up(): void {
+        parent::set_up();
+        $this->instance = new ClassName();
+    }
+
+    /**
+     * Tear down test fixtures.
+     */
+    public function tear_down(): void {
+        $this->instance = null;
+        parent::tear_down();
+    }
+
+    /**
+     * Test that method returns expected value.
+     */
+    public function testMethodReturnsExpectedValue(): void {
+        $result = $this->instance->method( 'input' );
+        $this->assertSame( 'expected', $result );
+    }
+}
+```
+
+---
+
+## Data Provider Pattern
+
+```php
+/**
+ * Data provider for search tests.
+ *
+ * @return array<string, array{item: array<string, mixed>, search: string, expected: bool}>
+ */
+public static function searchDataProvider(): array {
+    return [
+        'exact match' => [
+            'item'     => [ 'name' => 'John Doe' ],
+            'search'   => 'john',
+            'expected' => true,
+        ],
+        'no match' => [
+            'item'     => [ 'name' => 'John Doe' ],
+            'search'   => 'jane',
+            'expected' => false,
+        ],
+    ];
+}
+
+/**
+ * @dataProvider searchDataProvider
+ * @param array<string, mixed> $item     Item to search.
+ * @param string               $search   Search term.
+ * @param bool                 $expected Expected result.
+ */
+public function testSearchMatching( array $item, string $search, bool $expected ): void {
+    $result = $this->instance->matches_search( $item, $search );
+    $this->assertSame( $expected, $result );
+}
+```
+
+---
+
+## Assertion Best Practices
+
+```php
+// ✅ Use specific assertions.
+$this->assertSame( 'expected', $actual );        // Strict type + value.
+$this->assertEquals( 5, $count );                // Value equality.
+$this->assertTrue( $result );
+$this->assertNull( $value );
+$this->assertCount( 3, $array );
+$this->assertArrayHasKey( 'key', $array );
+$this->assertInstanceOf( ClassName::class, $obj );
+
+// ❌ Avoid generic assertions.
+$this->assertTrue( $result === 'expected' );     // Use assertSame.
+$this->assertTrue( count( $array ) === 3 );      // Use assertCount.
+```
+
+### Add Assertion Messages
+
+```php
+$this->assertSame(
+    3,
+    $result['total'],
+    'Should count 3 total errors (700, 701, 703)'
+);
+```
+
+---
+
+## WordPress Factory Pattern
+
+```php
+public function testWithFactory(): void {
+    $user_id = $this->factory->user->create( [
+        'role' => 'administrator',
+    ] );
+
+    $post_id = $this->factory->post->create( [
+        'post_author' => $user_id,
+        'post_title'  => 'Test Post',
+    ] );
+
+    wp_set_current_user( $user_id );
+    $this->assertTrue( current_user_can( 'manage_options' ) );
+}
+```
+
+---
+
+## Running Tests
+
+```bash
+# Run all tests.
+vendor/bin/phpunit
+
+# Run specific test file.
+vendor/bin/phpunit tests/Unit/Service/ClassNameTest.php
+
+# Run specific test method.
+vendor/bin/phpunit --filter testMethodName
+
+# Run tests by group.
+vendor/bin/phpunit --group unit
+vendor/bin/phpunit --group integration
+
+# Run with coverage.
+vendor/bin/phpunit --coverage-text
+```

package/templates/shared/instructions/tests.instructions.md

@@ -0,0 +1,103 @@
+---
+applyTo: "**/*.test.{ts,tsx}"
+---
+# Testing Standards
+
+## Test File Location
+
+Place tests in `__tests__/` folders next to the code:
+
+```
+components/
+└── button/
+    ├── index.tsx
+    └── __tests__/
+        └── button.test.tsx
+```
+
+## Test Structure
+
+Use `describe` and `it` blocks:
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Button } from '../index';
+
+describe('Button', () => {
+  const defaultProps = {
+    onClick: jest.fn(),
+    children: 'Click me',
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('rendering', () => {
+    it('renders children correctly', () => {
+      render(<Button {...defaultProps} />);
+      expect(screen.getByText('Click me')).toBeInTheDocument();
+    });
+  });
+
+  describe('behavior', () => {
+    it('calls onClick when clicked', async () => {
+      const user = userEvent.setup();
+      render(<Button {...defaultProps} />);
+      
+      await user.click(screen.getByRole('button'));
+      
+      expect(defaultProps.onClick).toHaveBeenCalledTimes(1);
+    });
+  });
+});
+```
+
+## Test Categories
+
+Include tests for:
+
+### Rendering
+- Component renders without crashing
+- All expected elements are present
+- Conditional rendering works
+
+### Props
+- Default props work correctly
+- Custom props are applied
+- Required props are validated
+
+### User Interactions
+- Click handlers work
+- Form inputs update
+- Keyboard navigation
+
+### Edge Cases
+- Empty data handled
+- Null/undefined handled
+- Error states displayed
+
+## Mocking
+
+```typescript
+// Mock a module
+jest.mock('@/lib/api', () => ({
+  fetchData: jest.fn(),
+}));
+
+// Mock a hook
+jest.mock('@/hooks/use-user', () => ({
+  useUser: () => ({ user: { name: 'Test' }, isLoading: false }),
+}));
+```
+
+## Assertions
+
+```typescript
+// Prefer specific assertions
+expect(screen.getByRole('button')).toBeInTheDocument();
+expect(screen.getByText('Hello')).toBeVisible();
+expect(element).toHaveClass('active');
+expect(handler).toHaveBeenCalledWith(expectedArgs);
+```

package/templates/shared/instructions/typescript.instructions.md

@@ -0,0 +1,106 @@
+---
+applyTo: "**/*.{ts,tsx}"
+---
+# TypeScript Code Style Standards
+
+## Export Rules
+
+**Components** use `export default`, everything else uses **named exports**:
+
+```typescript
+// ✅ Components: default export
+// components/auth/login-form/index.tsx
+export default function LoginForm() { }
+
+// ✅ Everything else: named exports
+// lib/utils.ts
+export function formatDate(date: Date): string { }
+export function validateEmail(email: string): boolean { }
+
+// types/user.ts
+export interface User { }
+export type UserRole = "admin" | "user";
+
+// actions/auth/login.ts
+export async function login(formData: FormData) { }
+
+// hooks/use-form.ts
+export function useForm() { }
+```
+
+## Avoid Nested Ternaries
+**❌ NEVER use nested ternary operators** - they reduce readability significantly.
+
+```typescript
+// ❌ INCORRECT: Nested ternaries
+const status = isLoading ? 'loading' : hasError ? 'error' : 'success';
+
+// ✅ CORRECT: Use if/else or early returns
+function getStatus(isLoading: boolean, hasError: boolean): string {
+  if (isLoading) return 'loading';
+  if (hasError) return 'error';
+  return 'success';
+}
+
+// ✅ CORRECT: Simple ternary is OK (no nesting)
+const greeting = isLoggedIn ? 'Welcome back!' : 'Please log in';
+```
+
+## Clarity Over Brevity
+
+**✅ PREFER explicit, readable code** over compact one-liners.
+
+```typescript
+// ❌ INCORRECT: Too compact, hard to understand
+const result = data?.items?.filter(i => i.active).map(i => i.id).join(',') || '';
+
+// ✅ CORRECT: Clear and maintainable
+const activeItems = data?.items?.filter(item => item.active) ?? [];
+const itemIds = activeItems.map(item => item.id);
+const result = itemIds.join(',');
+```
+
+## Object Destructuring
+
+**✅ ALWAYS use destructuring** for function parameters and object properties.
+
+```typescript
+// ✅ CORRECT: Destructure at the start
+function processData(data: DataType) {
+  const { name, email, phone, address } = data;
+  console.log(email);
+  sendEmail(email);
+}
+```
+
+## No `any` Type
+
+**❌ NEVER use `any`** - always define explicit types.
+
+```typescript
+// ❌ INCORRECT
+function processData(data: any) { ... }
+
+// ✅ CORRECT
+interface DataType {
+  name: string;
+  email: string;
+}
+function processData(data: DataType) { ... }
+```
+
+## JSDoc Comments
+
+**✅ ALWAYS add JSDoc** to public functions.
+
+```typescript
+/**
+ * Formats a date for display.
+ * @param date - The date to format
+ * @param locale - The locale (default: 'en-US')
+ * @returns Formatted date string
+ */
+export function formatDate(date: Date, locale = 'en-US'): string {
+  return date.toLocaleDateString(locale);
+}
+```

package/templates/shared/instructions/wordpress-plugin-architecture.instructions.md

@@ -0,0 +1,238 @@
+---
+description: WordPress plugin architecture standards for Silver Assist plugins including LoadableInterface, PSR-4, MVC pattern, singleton, and SilverAssist packages
+name: WordPress Plugin Architecture
+applyTo: "**/*.php"
+---
+
+# WordPress Plugin Architecture — Silver Assist Plugins
+
+---
+
+## Core Standards
+
+| Attribute | Value |
+|-----------|-------|
+| PHP | 8.2+ |
+| WordPress | 6.5+ |
+| Autoloading | PSR-4 (PascalCase files and directories) |
+| Standards | PHPCS (WordPress-Extra), PHPStan Level 8 |
+
+---
+
+## PSR-4 Autoloading
+
+Namespace `SilverAssist\PluginName\` maps to `includes/`:
+
+- PHP classes: `PascalCase.php` matching class name exactly
+- Directories: `PascalCase/` (e.g., `Core/`, `Admin/`, `Service/`)
+- Assets: `kebab-case.css`, `kebab-case.js`
+
+---
+
+## LoadableInterface Priority System
+
+All components implement `LoadableInterface` with three methods:
+
+```php
+interface LoadableInterface {
+    public function init(): void;
+    public function get_priority(): int;
+    public function should_load(): bool;
+}
+```
+
+Priority values:
+- **10**: Core components (Plugin, Activator, critical services)
+- **20**: Services (business logic, API clients)
+- **30**: Admin components (controllers, settings pages)
+- **40**: Utils & Assets (helpers, loggers)
+
+### Singleton Pattern
+
+```php
+class ServiceName implements LoadableInterface {
+    private static ?self $instance = null;
+
+    public static function instance(): self {
+        if ( null === self::$instance ) {
+            self::$instance = new self();
+        }
+        return self::$instance;
+    }
+
+    private function __construct() {}
+
+    public function init(): void {
+        // Register hooks.
+    }
+
+    public function get_priority(): int {
+        return 20;
+    }
+
+    public function should_load(): bool {
+        return true;
+    }
+}
+```
+
+### Component Loading (Plugin.php)
+
+```php
+private function get_components(): array {
+    return [
+        // Core — Priority 10.
+        \SilverAssist\PluginName\Core\Activator::class,
+        // Services — Priority 20.
+        \SilverAssist\PluginName\Service\ServiceName::class,
+        // Controllers — Priority 30.
+        \SilverAssist\PluginName\Controller\Admin\PageController::class,
+        // Utils — Priority 40.
+    ];
+}
+
+private function load_components(): void {
+    $components = [];
+    foreach ( $this->get_components() as $class ) {
+        if ( method_exists( $class, 'instance' ) ) {
+            $instance = $class::instance();
+            if ( $instance->should_load() ) {
+                $components[] = $instance;
+            }
+        }
+    }
+    usort( $components, fn( $a, $b ) => $a->get_priority() <=> $b->get_priority() );
+    foreach ( $components as $component ) {
+        $component->init();
+    }
+}
+```
+
+---
+
+## MVC Flow Pattern
+
+```
+User Request → Controller → Service → Repository/WordPress API
+                   ↓
+              View::render($data)  ← Static call with prepared data
+```
+
+| Layer | Responsibility | Can Depend On |
+|-------|---------------|---------------|
+| **Controller** | Handle requests, prepare data, coordinate | Services, Views |
+| **Service** | Business logic, data processing | Other Services, Repositories |
+| **View** | Render HTML (static class) | Only data passed as parameters |
+| **Model** | Data structures | Nothing |
+
+### CRITICAL: Views MUST NOT Instantiate Services
+
+```php
+// ✅ CORRECT — Controller prepares data, View receives it.
+class PageController {
+    public function render_page(): void {
+        $data = $this->service->get_data();
+        PageView::render( $data );
+    }
+}
+
+class PageView {
+    public static function render( array $data ): void {
+        // Only use data passed as parameters.
+    }
+}
+
+// ❌ WRONG — View instantiates Service.
+class PageView {
+    public static function render(): void {
+        $service = ServiceName::instance(); // ❌ Never do this.
+        $data = $service->get_data();
+    }
+}
+```
+
+---
+
+## Directory Structure
+
+```
+plugin-name/
+├── plugin-name.php              # Main plugin file
+├── composer.json
+├── phpcs.xml / phpstan.neon / phpunit.xml.dist
+├── includes/                    # PSR-4 classes
+│   ├── Core/                    # Priority 10
+│   │   ├── Plugin.php
+│   │   ├── Activator.php
+│   │   └── Interfaces/LoadableInterface.php
+│   ├── Service/                 # Priority 20
+│   ├── Controller/              # Priority 30
+│   ├── View/                    # Static HTML rendering
+│   ├── Model/                   # Domain models
+│   ├── Repository/              # Data access
+│   ├── Infrastructure/          # WordPress integrations
+│   └── Utils/                   # Priority 40
+├── assets/ (css/, js/)
+├── languages/
+├── scripts/
+├── tests/ (Unit/, Integration/, Helpers/)
+└── .github/ (workflows/, copilot-instructions.md)
+```
+
+---
+
+## SilverAssist Packages
+
+### wp-github-updater
+
+Enables automatic updates from GitHub releases:
+
+```php
+$config = new \SilverAssist\GitHubUpdater\UpdaterConfig(
+    plugin_basename: PLUGIN_BASENAME,
+    version: PLUGIN_VERSION,
+    github_repo: 'SilverAssist/plugin-slug',
+    plugin_file: PLUGIN_FILE
+);
+$config->init();
+```
+
+### wp-settings-hub
+
+Shared admin dashboard and settings infrastructure.
+
+---
+
+## Security Guards
+
+### File Header
+
+Every PHP file must start with:
+
+```php
+\defined( 'ABSPATH' ) || exit;
+```
+
+### Composer Autoloader Validation
+
+Main plugin file validates autoloader path to prevent path traversal:
+
+```php
+$autoload_path = PLUGIN_PATH . 'vendor/autoload.php';
+$real_autoload = realpath( $autoload_path );
+$real_plugin   = realpath( PLUGIN_PATH );
+
+if ( $real_autoload && $real_plugin && 0 === strpos( $real_autoload, $real_plugin ) ) {
+    require_once $real_autoload;
+}
+```
+
+### Plugin Header — Update URI
+
+**CRITICAL**: Must include `Update URI` header to prevent WordPress.org update conflicts:
+
+```php
+/**
+ * Update URI: https://github.com/SilverAssist/plugin-slug
+ */
+```