gkt-node 3.3.0

package/assets/.agent/skills/docs-architect/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: docs-architect
+description: Creates comprehensive technical documentation from existing
+  codebases. Analyzes architecture, design patterns, and implementation details
+  to produce long-form technical manuals and ebooks. Use PROACTIVELY for system
+  documentation, architecture guides, or technical deep-dives.
+metadata:
+  model: sonnet
+---
+
+## Use this skill when
+
+- Working on docs architect tasks or workflows
+- Needing guidance, best practices, or checklists for docs architect
+
+## Do not use this skill when
+
+- The task is unrelated to docs architect
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a technical documentation architect specializing in creating comprehensive, long-form documentation that captures both the what and the why of complex systems.
+
+## Core Competencies
+
+1. **Codebase Analysis**: Deep understanding of code structure, patterns, and architectural decisions
+2. **Technical Writing**: Clear, precise explanations suitable for various technical audiences
+3. **System Thinking**: Ability to see and document the big picture while explaining details
+4. **Documentation Architecture**: Organizing complex information into digestible, navigable structures
+5. **Visual Communication**: Creating and describing architectural diagrams and flowcharts
+
+## Documentation Process
+
+1. **Discovery Phase**
+   - Analyze codebase structure and dependencies
+   - Identify key components and their relationships
+   - Extract design patterns and architectural decisions
+   - Map data flows and integration points
+
+2. **Structuring Phase**
+   - Create logical chapter/section hierarchy
+   - Design progressive disclosure of complexity
+   - Plan diagrams and visual aids
+   - Establish consistent terminology
+
+3. **Writing Phase**
+   - Start with executive summary and overview
+   - Progress from high-level architecture to implementation details
+   - Include rationale for design decisions
+   - Add code examples with thorough explanations
+
+## Output Characteristics
+
+- **Length**: Comprehensive documents (10-100+ pages)
+- **Depth**: From bird's-eye view to implementation specifics
+- **Style**: Technical but accessible, with progressive complexity
+- **Format**: Structured with chapters, sections, and cross-references
+- **Visuals**: Architectural diagrams, sequence diagrams, and flowcharts (described in detail)
+
+## Key Sections to Include
+
+1. **Executive Summary**: One-page overview for stakeholders
+2. **Architecture Overview**: System boundaries, key components, and interactions
+3. **Design Decisions**: Rationale behind architectural choices
+4. **Core Components**: Deep dive into each major module/service
+5. **Data Models**: Schema design and data flow documentation
+6. **Integration Points**: APIs, events, and external dependencies
+7. **Deployment Architecture**: Infrastructure and operational considerations
+8. **Performance Characteristics**: Bottlenecks, optimizations, and benchmarks
+9. **Security Model**: Authentication, authorization, and data protection
+10. **Appendices**: Glossary, references, and detailed specifications
+
+## Best Practices
+
+- Always explain the "why" behind design decisions
+- Use concrete examples from the actual codebase
+- Create mental models that help readers understand the system
+- Document both current state and evolutionary history
+- Include troubleshooting guides and common pitfalls
+- Provide reading paths for different audiences (developers, architects, operations)
+
+## Output Format
+
+Generate documentation in Markdown format with:
+- Clear heading hierarchy
+- Code blocks with syntax highlighting
+- Tables for structured data
+- Bullet points for lists
+- Blockquotes for important notes
+- Links to relevant code files (using file_path:line_number format)
+
+Remember: Your goal is to create documentation that serves as the definitive technical reference for the system, suitable for onboarding new team members, architectural reviews, and long-term maintenance.

package/assets/.agent/skills/e2e-testing-patterns/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: e2e-testing-patterns
+description: Master end-to-end testing with Playwright and Cypress to build reliable test suites that catch bugs, improve confidence, and enable fast deployment. Use when implementing E2E tests, debugging flaky tests, or establishing testing standards.
+---
+
+# E2E Testing Patterns
+
+Build reliable, fast, and maintainable end-to-end test suites that provide confidence to ship code quickly and catch regressions before users do.
+
+## Use this skill when
+
+- Implementing end-to-end test automation
+- Debugging flaky or unreliable tests
+- Testing critical user workflows
+- Setting up CI/CD test pipelines
+- Testing across multiple browsers
+- Validating accessibility requirements
+- Testing responsive designs
+- Establishing E2E testing standards
+
+## Do not use this skill when
+
+- You only need unit or integration tests
+- The environment cannot support stable UI automation
+- You cannot provision safe test accounts or data
+
+## Instructions
+
+1. Identify critical user journeys and success criteria.
+2. Build stable selectors and test data strategies.
+3. Implement tests with retries, tracing, and isolation.
+4. Run in CI with parallelization and artifact capture.
+
+## Safety
+
+- Avoid running destructive tests against production.
+- Use dedicated test data and scrub sensitive output.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed E2E patterns and templates.

package/assets/.agent/skills/e2e-testing-patterns/resources/implementation-playbook.md

@@ -0,0 +1,531 @@
+# E2E Testing Patterns Implementation Playbook
+
+This file contains detailed patterns, checklists, and code samples referenced by the skill.
+
+## Core Concepts
+
+### 1. E2E Testing Fundamentals
+
+**What to Test with E2E:**
+- Critical user journeys (login, checkout, signup)
+- Complex interactions (drag-and-drop, multi-step forms)
+- Cross-browser compatibility
+- Real API integration
+- Authentication flows
+
+**What NOT to Test with E2E:**
+- Unit-level logic (use unit tests)
+- API contracts (use integration tests)
+- Edge cases (too slow)
+- Internal implementation details
+
+### 2. Test Philosophy
+
+**The Testing Pyramid:**
+```
+        /\
+       /E2E\         ← Few, focused on critical paths
+      /─────\
+     /Integr\        ← More, test component interactions
+    /────────\
+   /Unit Tests\      ← Many, fast, isolated
+  /────────────\
+```
+
+**Best Practices:**
+- Test user behavior, not implementation
+- Keep tests independent
+- Make tests deterministic
+- Optimize for speed
+- Use data-testid, not CSS selectors
+
+## Playwright Patterns
+
+### Setup and Configuration
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+    testDir: './e2e',
+    timeout: 30000,
+    expect: {
+        timeout: 5000,
+    },
+    fullyParallel: true,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 2 : 0,
+    workers: process.env.CI ? 1 : undefined,
+    reporter: [
+        ['html'],
+        ['junit', { outputFile: 'results.xml' }],
+    ],
+    use: {
+        baseURL: 'http://localhost:3000',
+        trace: 'on-first-retry',
+        screenshot: 'only-on-failure',
+        video: 'retain-on-failure',
+    },
+    projects: [
+        { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+        { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+        { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+        { name: 'mobile', use: { ...devices['iPhone 13'] } },
+    ],
+});
+```
+
+### Pattern 1: Page Object Model
+
+```typescript
+// pages/LoginPage.ts
+import { Page, Locator } from '@playwright/test';
+
+export class LoginPage {
+    readonly page: Page;
+    readonly emailInput: Locator;
+    readonly passwordInput: Locator;
+    readonly loginButton: Locator;
+    readonly errorMessage: Locator;
+
+    constructor(page: Page) {
+        this.page = page;
+        this.emailInput = page.getByLabel('Email');
+        this.passwordInput = page.getByLabel('Password');
+        this.loginButton = page.getByRole('button', { name: 'Login' });
+        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.loginButton.click();
+    }
+
+    async getErrorMessage(): Promise<string> {
+        return await this.errorMessage.textContent() ?? '';
+    }
+}
+
+// Test using Page Object
+import { test, expect } from '@playwright/test';
+import { LoginPage } from './pages/LoginPage';
+
+test('successful login', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login('user@example.com', 'password123');
+
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByRole('heading', { name: 'Dashboard' }))
+        .toBeVisible();
+});
+
+test('failed login shows error', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login('invalid@example.com', 'wrong');
+
+    const error = await loginPage.getErrorMessage();
+    expect(error).toContain('Invalid credentials');
+});
+```
+
+### Pattern 2: Fixtures for Test Data
+
+```typescript
+// fixtures/test-data.ts
+import { test as base } from '@playwright/test';
+
+type TestData = {
+    testUser: {
+        email: string;
+        password: string;
+        name: string;
+    };
+    adminUser: {
+        email: string;
+        password: string;
+    };
+};
+
+export const test = base.extend<TestData>({
+    testUser: async ({}, use) => {
+        const user = {
+            email: `test-${Date.now()}@example.com`,
+            password: 'Test123!@#',
+            name: 'Test User',
+        };
+        // Setup: Create user in database
+        await createTestUser(user);
+        await use(user);
+        // Teardown: Clean up user
+        await deleteTestUser(user.email);
+    },
+
+    adminUser: async ({}, use) => {
+        await use({
+            email: 'admin@example.com',
+            password: process.env.ADMIN_PASSWORD!,
+        });
+    },
+});
+
+// Usage in tests
+import { test } from './fixtures/test-data';
+
+test('user can update profile', async ({ page, testUser }) => {
+    await page.goto('/login');
+    await page.getByLabel('Email').fill(testUser.email);
+    await page.getByLabel('Password').fill(testUser.password);
+    await page.getByRole('button', { name: 'Login' }).click();
+
+    await page.goto('/profile');
+    await page.getByLabel('Name').fill('Updated Name');
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    await expect(page.getByText('Profile updated')).toBeVisible();
+});
+```
+
+### Pattern 3: Waiting Strategies
+
+```typescript
+// ❌ Bad: Fixed timeouts
+await page.waitForTimeout(3000);  // Flaky!
+
+// ✅ Good: Wait for specific conditions
+await page.waitForLoadState('networkidle');
+await page.waitForURL('/dashboard');
+await page.waitForSelector('[data-testid="user-profile"]');
+
+// ✅ Better: Auto-waiting with assertions
+await expect(page.getByText('Welcome')).toBeVisible();
+await expect(page.getByRole('button', { name: 'Submit' }))
+    .toBeEnabled();
+
+// Wait for API response
+const responsePromise = page.waitForResponse(
+    response => response.url().includes('/api/users') && response.status() === 200
+);
+await page.getByRole('button', { name: 'Load Users' }).click();
+const response = await responsePromise;
+const data = await response.json();
+expect(data.users).toHaveLength(10);
+
+// Wait for multiple conditions
+await Promise.all([
+    page.waitForURL('/success'),
+    page.waitForLoadState('networkidle'),
+    expect(page.getByText('Payment successful')).toBeVisible(),
+]);
+```
+
+### Pattern 4: Network Mocking and Interception
+
+```typescript
+// Mock API responses
+test('displays error when API fails', async ({ page }) => {
+    await page.route('**/api/users', route => {
+        route.fulfill({
+            status: 500,
+            contentType: 'application/json',
+            body: JSON.stringify({ error: 'Internal Server Error' }),
+        });
+    });
+
+    await page.goto('/users');
+    await expect(page.getByText('Failed to load users')).toBeVisible();
+});
+
+// Intercept and modify requests
+test('can modify API request', async ({ page }) => {
+    await page.route('**/api/users', async route => {
+        const request = route.request();
+        const postData = JSON.parse(request.postData() || '{}');
+
+        // Modify request
+        postData.role = 'admin';
+
+        await route.continue({
+            postData: JSON.stringify(postData),
+        });
+    });
+
+    // Test continues...
+});
+
+// Mock third-party services
+test('payment flow with mocked Stripe', async ({ page }) => {
+    await page.route('**/api/stripe/**', route => {
+        route.fulfill({
+            status: 200,
+            body: JSON.stringify({
+                id: 'mock_payment_id',
+                status: 'succeeded',
+            }),
+        });
+    });
+
+    // Test payment flow with mocked response
+});
+```
+
+## Cypress Patterns
+
+### Setup and Configuration
+
+```typescript
+// cypress.config.ts
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+    e2e: {
+        baseUrl: 'http://localhost:3000',
+        viewportWidth: 1280,
+        viewportHeight: 720,
+        video: false,
+        screenshotOnRunFailure: true,
+        defaultCommandTimeout: 10000,
+        requestTimeout: 10000,
+        setupNodeEvents(on, config) {
+            // Implement node event listeners
+        },
+    },
+});
+```
+
+### Pattern 1: Custom Commands
+
+```typescript
+// cypress/support/commands.ts
+declare global {
+    namespace Cypress {
+        interface Chainable {
+            login(email: string, password: string): Chainable<void>;
+            createUser(userData: UserData): Chainable<User>;
+            dataCy(value: string): Chainable<JQuery<HTMLElement>>;
+        }
+    }
+}
+
+Cypress.Commands.add('login', (email: string, password: string) => {
+    cy.visit('/login');
+    cy.get('[data-testid="email"]').type(email);
+    cy.get('[data-testid="password"]').type(password);
+    cy.get('[data-testid="login-button"]').click();
+    cy.url().should('include', '/dashboard');
+});
+
+Cypress.Commands.add('createUser', (userData: UserData) => {
+    return cy.request('POST', '/api/users', userData)
+        .its('body');
+});
+
+Cypress.Commands.add('dataCy', (value: string) => {
+    return cy.get(`[data-cy="${value}"]`);
+});
+
+// Usage
+cy.login('user@example.com', 'password');
+cy.dataCy('submit-button').click();
+```
+
+### Pattern 2: Cypress Intercept
+
+```typescript
+// Mock API calls
+cy.intercept('GET', '/api/users', {
+    statusCode: 200,
+    body: [
+        { id: 1, name: 'John' },
+        { id: 2, name: 'Jane' },
+    ],
+}).as('getUsers');
+
+cy.visit('/users');
+cy.wait('@getUsers');
+cy.get('[data-testid="user-list"]').children().should('have.length', 2);
+
+// Modify responses
+cy.intercept('GET', '/api/users', (req) => {
+    req.reply((res) => {
+        // Modify response
+        res.body.users = res.body.users.slice(0, 5);
+        res.send();
+    });
+});
+
+// Simulate slow network
+cy.intercept('GET', '/api/data', (req) => {
+    req.reply((res) => {
+        res.delay(3000);  // 3 second delay
+        res.send();
+    });
+});
+```
+
+## Advanced Patterns
+
+### Pattern 1: Visual Regression Testing
+
+```typescript
+// With Playwright
+import { test, expect } from '@playwright/test';
+
+test('homepage looks correct', async ({ page }) => {
+    await page.goto('/');
+    await expect(page).toHaveScreenshot('homepage.png', {
+        fullPage: true,
+        maxDiffPixels: 100,
+    });
+});
+
+test('button in all states', async ({ page }) => {
+    await page.goto('/components');
+
+    const button = page.getByRole('button', { name: 'Submit' });
+
+    // Default state
+    await expect(button).toHaveScreenshot('button-default.png');
+
+    // Hover state
+    await button.hover();
+    await expect(button).toHaveScreenshot('button-hover.png');
+
+    // Disabled state
+    await button.evaluate(el => el.setAttribute('disabled', 'true'));
+    await expect(button).toHaveScreenshot('button-disabled.png');
+});
+```
+
+### Pattern 2: Parallel Testing with Sharding
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+    projects: [
+        {
+            name: 'shard-1',
+            use: { ...devices['Desktop Chrome'] },
+            grepInvert: /@slow/,
+            shard: { current: 1, total: 4 },
+        },
+        {
+            name: 'shard-2',
+            use: { ...devices['Desktop Chrome'] },
+            shard: { current: 2, total: 4 },
+        },
+        // ... more shards
+    ],
+});
+
+// Run in CI
+// npx playwright test --shard=1/4
+// npx playwright test --shard=2/4
+```
+
+### Pattern 3: Accessibility Testing
+
+```typescript
+// Install: npm install @axe-core/playwright
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('page should not have accessibility violations', async ({ page }) => {
+    await page.goto('/');
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+        .exclude('#third-party-widget')
+        .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+});
+
+test('form is accessible', async ({ page }) => {
+    await page.goto('/signup');
+
+    const results = await new AxeBuilder({ page })
+        .include('form')
+        .analyze();
+
+    expect(results.violations).toEqual([]);
+});
+```
+
+## Best Practices
+
+1. **Use Data Attributes**: `data-testid` or `data-cy` for stable selectors
+2. **Avoid Brittle Selectors**: Don't rely on CSS classes or DOM structure
+3. **Test User Behavior**: Click, type, see - not implementation details
+4. **Keep Tests Independent**: Each test should run in isolation
+5. **Clean Up Test Data**: Create and destroy test data in each test
+6. **Use Page Objects**: Encapsulate page logic
+7. **Meaningful Assertions**: Check actual user-visible behavior
+8. **Optimize for Speed**: Mock when possible, parallel execution
+
+```typescript
+// ❌ Bad selectors
+cy.get('.btn.btn-primary.submit-button').click();
+cy.get('div > form > div:nth-child(2) > input').type('text');
+
+// ✅ Good selectors
+cy.getByRole('button', { name: 'Submit' }).click();
+cy.getByLabel('Email address').type('user@example.com');
+cy.get('[data-testid="email-input"]').type('user@example.com');
+```
+
+## Common Pitfalls
+
+- **Flaky Tests**: Use proper waits, not fixed timeouts
+- **Slow Tests**: Mock external APIs, use parallel execution
+- **Over-Testing**: Don't test every edge case with E2E
+- **Coupled Tests**: Tests should not depend on each other
+- **Poor Selectors**: Avoid CSS classes and nth-child
+- **No Cleanup**: Clean up test data after each test
+- **Testing Implementation**: Test user behavior, not internals
+
+## Debugging Failing Tests
+
+```typescript
+// Playwright debugging
+// 1. Run in headed mode
+npx playwright test --headed
+
+// 2. Run in debug mode
+npx playwright test --debug
+
+// 3. Use trace viewer
+await page.screenshot({ path: 'screenshot.png' });
+await page.video()?.saveAs('video.webm');
+
+// 4. Add test.step for better reporting
+test('checkout flow', async ({ page }) => {
+    await test.step('Add item to cart', async () => {
+        await page.goto('/products');
+        await page.getByRole('button', { name: 'Add to Cart' }).click();
+    });
+
+    await test.step('Proceed to checkout', async () => {
+        await page.goto('/cart');
+        await page.getByRole('button', { name: 'Checkout' }).click();
+    });
+});
+
+// 5. Inspect page state
+await page.pause();  // Pauses execution, opens inspector
+```
+
+## Resources
+
+- **references/playwright-best-practices.md**: Playwright-specific patterns
+- **references/cypress-best-practices.md**: Cypress-specific patterns
+- **references/flaky-test-debugging.md**: Debugging unreliable tests
+- **assets/e2e-testing-checklist.md**: What to test with E2E
+- **assets/selector-strategies.md**: Finding reliable selectors
+- **scripts/test-analyzer.ts**: Analyze test flakiness and duration