@paulojalowyj/openkit 0.1.1

package/.opencode/skills/webapp-testing/scripts/playwright_runner.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Skill: webapp-testing
+Script: playwright_runner.py
+Purpose: Run basic Playwright browser tests
+Usage: python playwright_runner.py <url> [--screenshot]
+Output: JSON with page info, health status, and optional screenshot path
+Note: Requires playwright (pip install playwright && playwright install chromium)
+Screenshots: Saved to system temp directory (auto-cleaned by OS)
+"""
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime
+
+# Fix Windows console encoding for Unicode output
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass  # Python < 3.7
+
+try:
+    from playwright.sync_api import sync_playwright
+    PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    PLAYWRIGHT_AVAILABLE = False
+
+
+def run_basic_test(url: str, take_screenshot: bool = False) -> dict:
+    """Run basic browser test on URL."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {
+            "error": "Playwright not installed",
+            "fix": "pip install playwright && playwright install chromium"
+        }
+    
+    result = {
+        "url": url,
+        "timestamp": datetime.now().isoformat(),
+        "status": "pending"
+    }
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            context = browser.new_context(
+                viewport={"width": 1280, "height": 720},
+                user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+            )
+            page = context.new_page()
+            
+            # Navigate
+            response = page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic info
+            result["page"] = {
+                "title": page.title(),
+                "url": page.url,
+                "status_code": response.status if response else None
+            }
+            
+            # Health checks
+            result["health"] = {
+                "loaded": response.ok if response else False,
+                "has_title": bool(page.title()),
+                "has_h1": page.locator("h1").count() > 0,
+                "has_links": page.locator("a").count() > 0,
+                "has_images": page.locator("img").count() > 0
+            }
+            
+            # Console errors
+            console_errors = []
+            page.on("console", lambda msg: console_errors.append(msg.text) if msg.type == "error" else None)
+            
+            # Performance metrics
+            result["performance"] = {
+                "dom_content_loaded": page.evaluate("window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart"),
+                "load_complete": page.evaluate("window.performance.timing.loadEventEnd - window.performance.timing.navigationStart")
+            }
+            
+            # Screenshot - uses system temp directory (cross-platform, auto-cleaned)
+            if take_screenshot:
+                # Cross-platform: Windows=%TEMP%, Linux/macOS=/tmp
+                screenshot_dir = os.path.join(tempfile.gettempdir(), "maestro_screenshots")
+                os.makedirs(screenshot_dir, exist_ok=True)
+                screenshot_path = os.path.join(screenshot_dir, f"screenshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+                page.screenshot(path=screenshot_path, full_page=True)
+                result["screenshot"] = screenshot_path
+                result["screenshot_note"] = "Saved to temp directory (auto-cleaned by OS)"
+            
+            # Element counts
+            result["elements"] = {
+                "links": page.locator("a").count(),
+                "buttons": page.locator("button").count(),
+                "inputs": page.locator("input").count(),
+                "images": page.locator("img").count(),
+                "forms": page.locator("form").count()
+            }
+            
+            browser.close()
+            
+            result["status"] = "success" if result["health"]["loaded"] else "failed"
+            result["summary"] = "[OK] Page loaded successfully" if result["status"] == "success" else "[X] Page failed to load"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+        result["summary"] = f"[X] Error: {str(e)[:100]}"
+    
+    return result
+
+
+def run_accessibility_check(url: str) -> dict:
+    """Run basic accessibility check."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {"error": "Playwright not installed"}
+    
+    result = {"url": url, "accessibility": {}}
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            page = browser.new_page()
+            page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic a11y checks
+            result["accessibility"] = {
+                "images_with_alt": page.locator("img[alt]").count(),
+                "images_without_alt": page.locator("img:not([alt])").count(),
+                "buttons_with_label": page.locator("button[aria-label], button:has-text('')").count(),
+                "links_with_text": page.locator("a:has-text('')").count(),
+                "form_labels": page.locator("label").count(),
+                "headings": {
+                    "h1": page.locator("h1").count(),
+                    "h2": page.locator("h2").count(),
+                    "h3": page.locator("h3").count()
+                }
+            }
+            
+            browser.close()
+            result["status"] = "success"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+    
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(json.dumps({
+            "error": "Usage: python playwright_runner.py <url> [--screenshot] [--a11y]",
+            "examples": [
+                "python playwright_runner.py https://example.com",
+                "python playwright_runner.py https://example.com --screenshot",
+                "python playwright_runner.py https://example.com --a11y"
+            ]
+        }, indent=2))
+        sys.exit(1)
+    
+    url = sys.argv[1]
+    take_screenshot = "--screenshot" in sys.argv
+    check_a11y = "--a11y" in sys.argv
+    
+    if check_a11y:
+        result = run_accessibility_check(url)
+    else:
+        result = run_basic_test(url, take_screenshot)
+    
+    print(json.dumps(result, indent=2))

package/.opencode/templates/DOCS-ACTION_ITEMS.md

@@ -0,0 +1,5 @@
+# ACTION_ITEMS
+
+| Priority | Item | Impact | Effort | Owner | Notes |
+|---|---|---|---|---|---|
+| P0 | | | | | |

package/.opencode/templates/DOCS-API.md

@@ -0,0 +1,11 @@
+# API
+
+## Surface
+
+| Type | Name | Location | Notes |
+|---|---|---|---|
+| CLI | | | |
+
+## Contracts
+
+- [Schema / examples]

package/.opencode/templates/DOCS-BACKEND.md

@@ -0,0 +1,10 @@
+# BACKEND
+
+## Endpoints
+
+| Method | Route | Handler | Auth | Notes |
+|---|---|---|---|---|
+
+## Jobs / Async
+
+- [Job]

package/.opencode/templates/DOCS-CONTEXT.md

@@ -0,0 +1,25 @@
+# CONTEXT
+
+**Created**: [YYYY-MM-DD]
+**Scope**: [Full | Backend | Frontend]
+
+## Executive Summary (10 bullets)
+
+- [Key fact 1]
+- [Key fact 2]
+
+## Repository Map
+
+| Area | Path(s) | Notes |
+|---|---|---|
+| CLI | | |
+| Backend | | |
+| Frontend | | |
+
+## Key Flows
+
+1. [Flow name]: [entry] -> [core] -> [outputs]
+
+## Evidence
+
+- `path/to/file.ext`: short snippet / reason

package/.opencode/templates/DOCS-DATABASE.md

@@ -0,0 +1,10 @@
+# DATABASE
+
+## Entities
+
+| Entity | Keys | Relations | Indexes |
+|---|---|---|---|
+
+## Migrations
+
+- [Tool] + [current head]

package/.opencode/templates/DOCS-FRONTEND.md

@@ -0,0 +1,11 @@
+# FRONTEND
+
+## Routes
+
+| Path | Guard | Component | Notes |
+|---|---|---|---|
+
+## Data Fetching
+
+| QueryKey | Endpoint | Cache | Notes |
+|---|---|---|---|

package/.opencode/templates/DOCS-QUALITY_GATES.md

@@ -0,0 +1,20 @@
+# QUALITY_GATES
+
+## Required
+
+- Lint
+- Type check
+- Tests
+- Security scan
+
+## Commands
+
+```bash
+# Examples (adjust to project stack)
+npm test
+python .opencode/scripts/checklist.py .
+```
+
+## CI Notes
+
+- [Non-interactive behavior]

package/.opencode/templates/DOCS-SECURITY.md

@@ -0,0 +1,17 @@
+# SECURITY
+
+## Threats
+
+- [Threat]
+
+## Controls
+
+- [Control]
+
+## Gaps
+
+- [Gap]
+
+## Prioritized Actions
+
+- [Action]

package/.opencode/templates/SDD-AcceptanceCriteria.md

@@ -0,0 +1,21 @@
+# Acceptance Criteria
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+
+## Functional Requirements
+
+- FR-001: [Requirement]
+- FR-002: [Requirement]
+- FR-003: [Requirement]
+
+## Edge Cases
+
+- [Edge case 1]
+- [Edge case 2]
+
+## Success Criteria (measurable)
+
+- SC-001: [Metric or measurable outcome]
+- SC-002: [Metric or measurable outcome]
+- SC-003: [Metric or measurable outcome]

package/.opencode/templates/SDD-Checklist.md

@@ -0,0 +1,27 @@
+# Specification and Plan Checklist
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+
+## Spec Quality
+
+- [ ] Problem statement is clear and scoped
+- [ ] User stories are prioritized and independently testable
+- [ ] Acceptance criteria are measurable and tech-agnostic
+- [ ] Edge cases are documented
+- [ ] Risks are documented
+
+## Plan Quality
+
+- [ ] Plan references requirements and stories
+- [ ] Data model defined (if applicable)
+- [ ] Contracts defined (if applicable)
+- [ ] Testing strategy defined
+- [ ] Risks mitigations listed
+
+## Tasks Quality
+
+- [ ] Tasks map to user stories
+- [ ] Tasks include file paths
+- [ ] Dependencies and parallel work marked
+- [ ] Verification steps defined

package/.opencode/templates/SDD-Contracts.md

@@ -0,0 +1,21 @@
+# Contracts
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+
+## Contract List
+
+| Name | Type | Inputs | Outputs | Notes |
+|------|------|--------|---------|-------|
+| [Contract name] | [API/Event/Job] | [Input summary] | [Output summary] | [Notes] |
+
+## Contract Details
+
+### [Contract Name]
+
+- **Type**: [API/Event/Job]
+- **Purpose**: [Why it exists]
+- **Inputs**: [Fields and constraints]
+- **Outputs**: [Fields and constraints]
+- **Errors**: [Error cases]
+- **Auth/Permissions**: [If applicable]

package/.opencode/templates/SDD-Plan.md

@@ -0,0 +1,45 @@
+# Implementation Plan
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+**Inputs**: docs/requirements/<feature>/
+
+## Summary
+
+[One paragraph summarizing the plan and the approach.]
+
+## Technical Context
+
+- **Project type**: [single/web/mobile]
+- **Target platform**: [e.g., web, iOS, API]
+- **Constraints**: [latency, scale, compliance]
+- **Dependencies**: [major components or services]
+
+## Architecture Overview
+
+[High-level flow, components, and integrations. No code-level details.]
+
+## Data Model (if applicable)
+
+- [Entity 1]: [fields, relationships]
+- [Entity 2]: [fields, relationships]
+
+## Contracts (if applicable)
+
+- [Endpoint/Event]: [purpose, input, output]
+
+## Testing Strategy
+
+- Contract tests: [scope]
+- Integration tests: [scope]
+- E2E tests: [scope]
+
+## Risks and Mitigations
+
+- [Risk]: [Mitigation]
+
+## Acceptance Mapping
+
+- FR-001 -> [Plan section]
+- FR-002 -> [Plan section]
+- FR-003 -> [Plan section]

package/.opencode/templates/SDD-ProblemStatement.md

@@ -0,0 +1,25 @@
+# Problem Statement
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+**Owner**: [Role or name]
+
+## Summary
+
+[One paragraph describing the problem and why it matters.]
+
+## Goals
+
+- [Goal 1]
+- [Goal 2]
+- [Goal 3]
+
+## Non-Goals
+
+- [Out of scope item 1]
+- [Out of scope item 2]
+
+## Assumptions
+
+- [Assumption 1]
+- [Assumption 2]

package/.opencode/templates/SDD-Quickstart.md

@@ -0,0 +1,23 @@
+# Quickstart
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+
+## Purpose
+
+[Short description of what this quickstart enables.]
+
+## Prerequisites
+
+- [Prerequisite 1]
+- [Prerequisite 2]
+
+## Steps
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Verification
+
+- [How to verify success]

package/.opencode/templates/SDD-Research.md

@@ -0,0 +1,24 @@
+# Research Notes
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+
+## Questions
+
+- [Question or unknown]
+- [Question or unknown]
+
+## Decisions
+
+| Decision | Rationale | Alternatives |
+|----------|-----------|--------------|
+| [Decision] | [Why] | [Alternatives considered] |
+
+## Assumptions
+
+- [Assumption]
+- [Assumption]
+
+## References
+
+- [Link or doc]

package/.opencode/templates/SDD-Risks.md

@@ -0,0 +1,16 @@
+# Risks
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+
+## Risk Register
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| [Risk 1] | [High/Med/Low] | [High/Med/Low] | [Mitigation] |
+| [Risk 2] | [High/Med/Low] | [High/Med/Low] | [Mitigation] |
+
+## Open Questions
+
+- [Question 1]
+- [Question 2]

package/.opencode/templates/SDD-Tasks.md

@@ -0,0 +1,41 @@
+# Tasks
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+**Inputs**: docs/requirements/<feature>/PLAN.md
+
+## Format
+
+- [ID] [P?] [Story] Description (include file paths)
+- [P] indicates parallelizable work
+
+## Phase 1 - Setup
+
+- [ ] T001 Create required directories and files
+- [ ] T002 [P] Configure linting or tooling changes (if required)
+
+## Phase 2 - Foundations
+
+- [ ] T010 Setup data model
+- [ ] T011 [P] Define contracts or interfaces
+
+## Phase 3 - User Story US1
+
+- [ ] T020 [US1] Implement core capability
+- [ ] T021 [US1] Add validations and errors
+- [ ] T022 [US1] Add tests (if required)
+
+## Phase 4 - User Story US2
+
+- [ ] T030 [US2] Implement capability
+- [ ] T031 [US2] Add tests (if required)
+
+## Phase 5 - Polish
+
+- [ ] T040 Documentation updates in docs/
+- [ ] T041 Performance or UX refinements
+
+## Verification
+
+- [ ] V001 Confirm acceptance criteria coverage
+- [ ] V002 Run relevant test suites

package/.opencode/templates/SDD-UserStories.md

@@ -0,0 +1,45 @@
+# User Stories
+
+**Feature**: [Feature name]
+**Created**: [YYYY-MM-DD]
+
+## Story Format
+
+As a [role], I want [capability] so that [benefit].
+
+## Stories (prioritized)
+
+### US1 - [Title] (Priority: P1)
+
+- **Story**: As a [role], I want [capability] so that [benefit].
+- **Why this priority**: [Reason]
+- **Independent test**: [How to validate this story alone]
+
+**Acceptance scenarios**:
+
+1. Given [context], when [action], then [outcome].
+2. Given [context], when [action], then [outcome].
+
+---
+
+### US2 - [Title] (Priority: P2)
+
+- **Story**: As a [role], I want [capability] so that [benefit].
+- **Why this priority**: [Reason]
+- **Independent test**: [How to validate this story alone]
+
+**Acceptance scenarios**:
+
+1. Given [context], when [action], then [outcome].
+
+---
+
+### US3 - [Title] (Priority: P3)
+
+- **Story**: As a [role], I want [capability] so that [benefit].
+- **Why this priority**: [Reason]
+- **Independent test**: [How to validate this story alone]
+
+**Acceptance scenarios**:
+
+1. Given [context], when [action], then [outcome].