@monoes/monomindcli 2.15.3 → 2.15.4

package/org-skills/php-pro/references/testing-quality.md

@@ -0,0 +1,466 @@
+# Testing & Quality Assurance
+
+## PHPUnit with Strict Types
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Service;
+
+use App\Repository\UserRepositoryInterface;
+use App\Service\UserService;
+use App\Service\EmailService;
+use PHPUnit\Framework\TestCase;
+use PHPUnit\Framework\MockObject\MockObject;
+
+final class UserServiceTest extends TestCase
+{
+    private UserRepositoryInterface&MockObject $userRepository;
+    private EmailService&MockObject $emailService;
+    private UserService $userService;
+
+    protected function setUp(): void
+    {
+        $this->userRepository = $this->createMock(UserRepositoryInterface::class);
+        $this->emailService = $this->createMock(EmailService::class);
+        $this->userService = new UserService(
+            $this->userRepository,
+            $this->emailService
+        );
+    }
+
+    public function testCreateUserSuccessfully(): void
+    {
+        $email = 'test@example.com';
+        $password = 'SecurePass123!';
+
+        $this->userRepository
+            ->expects($this->once())
+            ->method('findByEmail')
+            ->with($email)
+            ->willReturn(null);
+
+        $this->userRepository
+            ->expects($this->once())
+            ->method('create')
+            ->willReturn($this->createUser($email));
+
+        $this->emailService
+            ->expects($this->once())
+            ->method('sendWelcomeEmail');
+
+        $user = $this->userService->createUser($email, $password);
+
+        $this->assertSame($email, $user->email);
+    }
+
+    public function testCreateUserThrowsExceptionWhenEmailExists(): void
+    {
+        $this->expectException(\DomainException::class);
+        $this->expectExceptionMessage('Email already exists');
+
+        $this->userRepository
+            ->method('findByEmail')
+            ->willReturn($this->createUser('test@example.com'));
+
+        $this->userService->createUser('test@example.com', 'password');
+    }
+
+    private function createUser(string $email): User
+    {
+        return new User(
+            id: 1,
+            email: $email,
+            password: password_hash('password', PASSWORD_ARGON2ID),
+        );
+    }
+}
+```
+
+## Data Providers
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Validator;
+
+use App\Validator\EmailValidator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+
+final class EmailValidatorTest extends TestCase
+{
+    #[Test]
+    #[DataProvider('validEmailProvider')]
+    public function itValidatesCorrectEmails(string $email): void
+    {
+        $validator = new EmailValidator();
+        $this->assertTrue($validator->isValid($email));
+    }
+
+    #[Test]
+    #[DataProvider('invalidEmailProvider')]
+    public function itRejectsInvalidEmails(string $email): void
+    {
+        $validator = new EmailValidator();
+        $this->assertFalse($validator->isValid($email));
+    }
+
+    public static function validEmailProvider(): array
+    {
+        return [
+            ['user@example.com'],
+            ['john.doe@company.co.uk'],
+            ['test+filter@domain.org'],
+        ];
+    }
+
+    public static function invalidEmailProvider(): array
+    {
+        return [
+            ['invalid'],
+            ['@example.com'],
+            ['user@'],
+            ['user space@example.com'],
+        ];
+    }
+}
+```
+
+## Laravel Feature Tests
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Feature;
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Illuminate\Foundation\Testing\WithFaker;
+use Tests\TestCase;
+
+final class UserControllerTest extends TestCase
+{
+    use RefreshDatabase, WithFaker;
+
+    public function testUserCanViewTheirProfile(): void
+    {
+        $user = User::factory()->create();
+
+        $response = $this->actingAs($user)->get('/api/users/me');
+
+        $response->assertOk()
+            ->assertJson([
+                'data' => [
+                    'id' => $user->id,
+                    'email' => $user->email,
+                ],
+            ]);
+    }
+
+    public function testUserCanUpdateTheirProfile(): void
+    {
+        $user = User::factory()->create();
+        $newName = $this->faker->name();
+
+        $response = $this->actingAs($user)->putJson('/api/users/me', [
+            'name' => $newName,
+        ]);
+
+        $response->assertOk();
+
+        $this->assertDatabaseHas('users', [
+            'id' => $user->id,
+            'name' => $newName,
+        ]);
+    }
+
+    public function testUnauthorizedUserCannotAccessProfile(): void
+    {
+        $response = $this->getJson('/api/users/me');
+
+        $response->assertUnauthorized();
+    }
+
+    public function testValidationFailsWithInvalidData(): void
+    {
+        $user = User::factory()->create();
+
+        $response = $this->actingAs($user)->putJson('/api/users/me', [
+            'email' => 'not-an-email',
+        ]);
+
+        $response->assertUnprocessable()
+            ->assertJsonValidationErrors(['email']);
+    }
+}
+```
+
+## Pest Testing (Modern Alternative)
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use App\Models\User;
+use App\Services\UserService;
+
+beforeEach(function () {
+    $this->userService = app(UserService::class);
+});
+
+it('creates a user successfully', function () {
+    $user = $this->userService->createUser(
+        email: 'test@example.com',
+        password: 'SecurePass123!'
+    );
+
+    expect($user)
+        ->toBeInstanceOf(User::class)
+        ->email->toBe('test@example.com');
+});
+
+it('validates email format', function (string $email, bool $valid) {
+    $validator = new EmailValidator();
+
+    expect($validator->isValid($email))->toBe($valid);
+})->with([
+    ['test@example.com', true],
+    ['invalid', false],
+    ['@example.com', false],
+]);
+
+test('authenticated user can view profile', function () {
+    $user = User::factory()->create();
+
+    $this->actingAs($user)
+        ->get('/api/users/me')
+        ->assertOk()
+        ->assertJson(['data' => ['email' => $user->email]]);
+});
+
+test('guest cannot access protected routes', function () {
+    $this->getJson('/api/users/me')
+        ->assertUnauthorized();
+});
+```
+
+## PHPStan Configuration
+
+```neon
+# phpstan.neon
+parameters:
+    level: 9
+    paths:
+        - src
+        - tests
+    excludePaths:
+        - src/bootstrap.php
+        - vendor
+    checkMissingIterableValueType: true
+    checkGenericClassInNonGenericObjectType: true
+    reportUnmatchedIgnoredErrors: true
+    tmpDir: var/cache/phpstan
+
+    ignoreErrors:
+        # Ignore specific Laravel magic
+        - '#Call to an undefined method Illuminate\\Database\\Eloquent\\Builder#'
+
+    type_coverage:
+        return_type: 100
+        param_type: 100
+        property_type: 100
+
+includes:
+    - vendor/phpstan/phpstan-strict-rules/rules.neon
+    - vendor/phpstan/phpstan-deprecation-rules/rules.neon
+```
+
+## PHPStan Annotations
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Repository;
+
+use App\Entity\User;
+use Doctrine\ORM\EntityRepository;
+
+/**
+ * @extends EntityRepository<User>
+ */
+final class UserRepository extends EntityRepository
+{
+    /**
+     * @return User[]
+     */
+    public function findActive(): array
+    {
+        return $this->createQueryBuilder('u')
+            ->where('u.status = :status')
+            ->setParameter('status', 'active')
+            ->getQuery()
+            ->getResult();
+    }
+
+    /**
+     * @param int[] $ids
+     * @return User[]
+     */
+    public function findByIds(array $ids): array
+    {
+        return $this->createQueryBuilder('u')
+            ->where('u.id IN (:ids)')
+            ->setParameter('ids', $ids)
+            ->getQuery()
+            ->getResult();
+    }
+}
+
+/**
+ * @template T
+ */
+final readonly class Result
+{
+    /**
+     * @param T $data
+     */
+    public function __construct(
+        public mixed $data,
+        public bool $success,
+    ) {}
+
+    /**
+     * @return T
+     */
+    public function getData(): mixed
+    {
+        return $this->data;
+    }
+}
+```
+
+## Mockery (Advanced Mocking)
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Unit\Service;
+
+use App\Repository\UserRepository;
+use App\Service\NotificationService;
+use Mockery;
+use Mockery\Adapter\Phpunit\MockeryPHPUnitIntegration;
+use PHPUnit\Framework\TestCase;
+
+final class NotificationServiceTest extends TestCase
+{
+    use MockeryPHPUnitIntegration;
+
+    public function testSendsNotificationToActiveUsers(): void
+    {
+        $repository = Mockery::mock(UserRepository::class);
+        $repository->shouldReceive('findActive')
+            ->once()
+            ->andReturn([
+                $this->createUser('user1@example.com'),
+                $this->createUser('user2@example.com'),
+            ]);
+
+        $service = new NotificationService($repository);
+        $result = $service->notifyActiveUsers('Important message');
+
+        $this->assertSame(2, $result->count());
+    }
+
+    public function testHandlesEmailServiceFailure(): void
+    {
+        $emailService = Mockery::mock(EmailService::class);
+        $emailService->shouldReceive('send')
+            ->once()
+            ->andThrow(new \RuntimeException('Email service down'));
+
+        $service = new NotificationService($emailService);
+
+        $this->expectException(\RuntimeException::class);
+        $service->sendNotification('test@example.com', 'Hello');
+    }
+
+    private function createUser(string $email): User
+    {
+        return new User(id: 1, email: $email, password: 'hashed');
+    }
+}
+```
+
+## Code Coverage
+
+```xml
+<!-- phpunit.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         failOnRisky="true"
+         failOnWarning="true"
+         stopOnFailure="false">
+    <testsuites>
+        <testsuite name="Unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="Feature">
+            <directory>tests/Feature</directory>
+        </testsuite>
+    </testsuites>
+    <coverage>
+        <include>
+            <directory suffix=".php">src</directory>
+        </include>
+        <exclude>
+            <directory>src/bootstrap</directory>
+            <file>src/Kernel.php</file>
+        </exclude>
+        <report>
+            <html outputDirectory="coverage/html"/>
+            <clover outputFile="coverage/clover.xml"/>
+        </report>
+    </coverage>
+    <php>
+        <env name="APP_ENV" value="testing"/>
+        <env name="DB_CONNECTION" value="sqlite"/>
+        <env name="DB_DATABASE" value=":memory:"/>
+    </php>
+</phpunit>
+```
+
+## Quick Reference
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| PHPUnit | Unit/Feature tests | `./vendor/bin/phpunit` |
+| Pest | Modern testing | `./vendor/bin/pest` |
+| PHPStan | Static analysis | `./vendor/bin/phpstan analyse` |
+| Psalm | Alternative static analysis | `./vendor/bin/psalm` |
+| PHP-CS-Fixer | Code style | `./vendor/bin/php-cs-fixer fix` |
+| PHPMD | Mess detector | `./vendor/bin/phpmd src text cleancode` |
+
+| Assertion | PHPUnit | Pest |
+|-----------|---------|------|
+| Equality | `$this->assertSame()` | `expect()->toBe()` |
+| Type | `$this->assertInstanceOf()` | `expect()->toBeInstanceOf()` |
+| Array | `$this->assertContains()` | `expect()->toContain()` |
+| Exception | `$this->expectException()` | `expect()->toThrow()` |
+| Count | `$this->assertCount()` | `expect()->toHaveCount()` |

package/{dist/src/orgrt/role-skills/pipeline-analyst.md → org-skills/pipeline-analyst/SKILL.md}

@@ -1,3 +1,11 @@
+---
+name: pipeline-analyst
+description: "Pipeline Analyst role best practices. Monitors pipeline health and forecast accuracy — tracking conversion, velocity, and data hygiene so leadership can trust the numbers driving revenue decisions."
+tags: ["sales"]
+tools: []
+license: Apache-2.0
+source: https://github.com/monoes/monomind
+---
 # Pipeline Analyst — Best Practices
 
 ## Focus

package/{dist/src/orgrt/role-skills/planner.md → org-skills/planner/SKILL.md}

@@ -1,3 +1,11 @@
+---
+name: planner
+description: "Planner role best practices. Breaks complex objectives into concrete, sequenced, assignable tasks with clear dependencies and success criteria — before anyone starts executing."
+tags: ["engineering"]
+tools: ["monograph_query","monograph_context","monograph_impact"]
+license: Apache-2.0
+source: https://github.com/monoes/monomind
+---
 # Planner — Best Practices
 
 ## Focus

package/org-skills/playwright-expert/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/org-skills/playwright-expert/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: playwright-expert
+description: "Use when writing E2E tests with Playwright, setting up test infrastructure, or debugging flaky browser tests. Invoke to write test scripts, create page objects, configure test fixtures, set up reporters, add CI integration, implement API mocking, or perform visual regression testing."
+tags: ["testing","frontend"]
+tools: []
+license: MIT
+source: https://github.com/Jeffallan/claude-skills
+source_path: "skills/playwright-expert"
+source_commit: 882ef55e377dbf9a4dbe496bb41ac6ccd0e555cf
+---
+# Playwright Expert
+
+E2E testing specialist with deep expertise in Playwright for robust, maintainable browser automation.
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify user flows to test
+2. **Setup** - Configure Playwright with proper settings
+3. **Write tests** - Use POM pattern, proper selectors, auto-waiting
+4. **Debug** - Run test → check trace → identify issue → fix → verify fix
+5. **Integrate** - Add to CI/CD pipeline
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Selectors | `references/selectors-locators.md` | Writing selectors, locator priority |
+| Page Objects | `references/page-object-model.md` | POM patterns, fixtures |
+| API Mocking | `references/api-mocking.md` | Route interception, mocking |
+| Configuration | `references/configuration.md` | playwright.config.ts setup |
+| Debugging | `references/debugging-flaky.md` | Flaky tests, trace viewer |
+
+## Constraints
+
+### MUST DO
+- Use role-based selectors when possible
+- Leverage auto-waiting (don't add arbitrary timeouts)
+- Keep tests independent (no shared state)
+- Use Page Object Model for maintainability
+- Enable traces/screenshots for debugging
+- Run tests in parallel
+
+### MUST NOT DO
+- Use `waitForTimeout()` (use proper waits)
+- Rely on CSS class selectors (brittle)
+- Share state between tests
+- Ignore flaky tests
+- Use `first()`, `nth()` without good reason
+
+## Code Examples
+
+### Selector: Role-based (correct) vs CSS class (brittle)
+
+```typescript
+// ✅ Role-based selector — resilient to styling changes
+await page.getByRole('button', { name: 'Submit' }).click();
+await page.getByLabel('Email address').fill('user@example.com');
+
+// ❌ CSS class selector — breaks on refactor
+await page.locator('.btn-primary.submit-btn').click();
+await page.locator('.email-input').fill('user@example.com');
+```
+
+### Page Object Model + Test File
+
+```typescript
+// pages/LoginPage.ts
+import { type Page, type Locator } from '@playwright/test';
+
+export class LoginPage {
+  readonly page: Page;
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.emailInput = page.getByLabel('Email address');
+    this.passwordInput = page.getByLabel('Password');
+    this.submitButton = page.getByRole('button', { name: 'Sign in' });
+    this.errorMessage = page.getByRole('alert');
+  }
+
+  async goto() {
+    await this.page.goto('/login');
+  }
+
+  async login(email: string, password: string) {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+}
+```
+
+```typescript
+// tests/login.spec.ts
+import { test, expect } from '@playwright/test';
+import { LoginPage } from '../pages/LoginPage';
+
+test.describe('Login', () => {
+  let loginPage: LoginPage;
+
+  test.beforeEach(async ({ page }) => {
+    loginPage = new LoginPage(page);
+    await loginPage.goto();
+  });
+
+  test('successful login redirects to dashboard', async ({ page }) => {
+    await loginPage.login('user@example.com', 'correct-password');
+    await expect(page).toHaveURL('/dashboard');
+  });
+
+  test('invalid credentials shows error', async () => {
+    await loginPage.login('user@example.com', 'wrong-password');
+    await expect(loginPage.errorMessage).toBeVisible();
+    await expect(loginPage.errorMessage).toContainText('Invalid credentials');
+  });
+});
+```
+
+### Debugging Workflow for Flaky Tests
+
+```typescript
+// 1. Run failing test with trace enabled
+// playwright.config.ts
+use: {
+  trace: 'on-first-retry',
+  screenshot: 'only-on-failure',
+}
+
+// 2. Re-run with retries to capture trace
+// npx playwright test --retries=2
+
+// 3. Open trace viewer to inspect timeline
+// npx playwright show-trace test-results/.../trace.zip
+
+// 4. Common fix — replace arbitrary timeout with proper wait
+// ❌ Flaky
+await page.waitForTimeout(2000);
+await page.getByRole('button', { name: 'Save' }).click();
+
+// ✅ Reliable — waits for element state
+await page.getByRole('button', { name: 'Save' }).waitFor({ state: 'visible' });
+await page.getByRole('button', { name: 'Save' }).click();
+
+// 5. Verify fix — run test 10x to confirm stability
+// npx playwright test --repeat-each=10
+```
+
+## Output Templates
+
+When implementing Playwright tests, provide:
+1. Page Object classes
+2. Test files with proper assertions
+3. Fixture setup if needed
+4. Configuration recommendations
+
+## Knowledge Reference
+
+Playwright, Page Object Model, auto-waiting, locators, fixtures, API mocking, trace viewer, visual comparisons, parallel execution, CI/CD integration
+
+[Documentation](https://jeffallan.github.io/claude-skills/skills/quality/playwright-expert/)