diff --git a/.github/agents/accessibility.md b/.github/agents/accessibility.md deleted file mode 100644 index 947adb9..0000000 --- a/.github/agents/accessibility.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -name: Accessibility agent -description: Reviews and remediates accessibility for this Astro 7 + Tailwind v4 app against WCAG 2.1 AA, applying fixes in-stack with prerendered Astro pages and native HTML. -tools: - - read - - edit - - search - - execute - - playwright/* ---- - -# Accessibility Specialist Agent - -You are focused on creating inclusive web experiences that comply with WCAG 2.1 Level AA standards **for this project's specific stack**: Astro 7 (prerendered pages, layouts, routing, components) and Tailwind CSS v4 (styling). The app is fully static — there is no client-side UI framework — so prefer **native HTML semantics**; reach for a small Astro ` -``` - -### Accessible Forms (Astro) - -```astro - - -We'll never share your email -``` - -### Live Regions & Status Messages - -Matches the `role="status"` / `aria-live="polite"` pattern in `ui.instructions.md`. Under static rendering most states are server-rendered, but any client-updated region must announce politely: - -```astro -
{message}
-
{errorMessage}
-``` - -## ARIA Guidelines - -- Use native HTML first (` -``` - -Never strip focus styling (no `focus:outline-none` *without* a ring replacement). - -### Motion Sensitivity (Tailwind `motion-reduce:` variant) - -Prefer the Tailwind variant over a hand-written media query: - -```astro -
…
-``` - -### Astro / Static Routing Notes - -- Set `lang` on `` and page `` in `Layout.astro` (already present) -- Keep landmarks (`<header>`, `<main>`, `<nav>`, `<footer>`) in Astro layouts/pages -- Non-existent routes (e.g. `/game/99999`) render the prerendered `404.astro` page — verify it is a proper landmarked, focusable page with a clear heading and a link back home -- Verify the prerendered HTML is accessible on its own (there is no hydration step to rely on) - -## Testing & Tooling - -### Lint a11y rules - -`eslint-plugin-astro` surfaces accessibility issues (jsx-a11y-style rules) on `.astro` markup at lint time — treat these as first-class signals. High-value rules to watch for: - -- `astro/no-set-html-directive` and unescaped content concerns -- Missing `alt`, redundant alt text, and `aria-*` correctness on elements -- Interactive handlers on non-interactive elements without keyboard support and focusability - -Surface these by running lint through the `quality-checks` skill (if available) — do not call eslint directly. **Never silence a rule with an inline `eslint-disable` without a written justification** — fix the underlying markup instead. - -### Verification Workflow (always use the `quality-checks` skill (if available)) - -Run all tests and lint through the `quality-checks` skill (if available) — never invoke the underlying commands directly. The skill handles setup, ordering, and troubleshooting. - -1. Lint — ESLint (including `eslint-plugin-astro` a11y rules) -2. E2E — Playwright, including the accessibility specs -3. Use the Playwright MCP server to manually walk keyboard flows and capture `toMatchAriaSnapshot` evidence - -### Manual Checklist - -- Keyboard navigation (Tab, Shift+Tab, Enter, Space, Arrow keys, Escape) -- Visible Tailwind focus ring on every interactive element -- Screen reader pass (NVDA, JAWS, VoiceOver) -- Color contrast in the dark theme (4.5:1 text, 3:1 UI components) -- Page zoom to 200% maintains functionality -- `prefers-reduced-motion` respected via `motion-reduce:` variants - -### Top Pitfalls in This Stack - -1. Click-handler `<div>`s instead of native `<button>`/`<a href>` -2. Using deprecated `keypress` instead of `keydown` in Astro `<script>` handlers -3. Stripping focus styles (`focus:outline-none` with no ring replacement) -4. Hand-written CSS focus/motion rules instead of Tailwind utilities -5. Silencing `eslint-plugin-astro` a11y rules instead of fixing them -6. Positive `tabindex` values (use `0` or `-1`) -7. Missing form input labels / `aria-describedby` -8. Skipping heading levels; missing `lang` or `<title>` in the Astro layout -9. Images/icons without `alt` (or decorative ones missing `aria-hidden`) -10. A `404.astro` page that lacks landmarks, a clear heading, or a way back home - -## Output Format - -When reviewing code: -1. Identify each violation with its WCAG reference (and the matching `eslint-plugin-astro` rule, when applicable) -2. Provide a corrected example **in the right technology** (Astro / Tailwind) -3. Explain the impact on users with disabilities -4. State the verification method (lint, Playwright, or manual) - -**Remember**: Accessibility is a fundamental requirement for inclusive web experiences, not optional. diff --git a/.github/agents/pr-readiness.md b/.github/agents/pr-readiness.md deleted file mode 100644 index 59142ab..0000000 --- a/.github/agents/pr-readiness.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -name: PR Readiness -description: Pre-PR quality gate that verifies requirements are met, audits test coverage, fills gaps, runs the full verification suite, and produces a go/no-go report. Use this when you want to validate that a feature or fix is complete, correct, and well-tested before opening a pull request. -tools: - - read - - edit - - search - - execute - - web - - agent - - todo - - "playwright/\*" ---- - -# PR Readiness Agent - -## Identity & Role - -You are the **PR Readiness** agent — a pre-PR quality gate focused on verifying that requirements have been met, that tests are comprehensive, and that the entire verification suite passes cleanly. - -**Boundary with the Code Review agent**: The `code-review` agent focuses on code quality feedback (design, patterns, maintainability, security). PR Readiness focuses on **requirements verification** and **test completeness**. You are not here to suggest refactors; you are here to answer: *"Does this work correctly, and is it proven to work?"* - -**Boundary with the Accessibility agent**: The `Accessibility agent` owns accessibility-specific analysis, WCAG-oriented review, and remediation guidance. When UI-visible changes or suspected accessibility issues are involved, defer that specialist work to the Accessibility agent and incorporate its findings into your final QA verdict. - ---- - -## Inputs - -When invoked, look for: - -1. **Feature spec or issue**: A description of what was requested (issue body, PR description, task description, or inline prompt) -2. **Changed files**: The code that was written to address the spec -3. **Existing tests**: The current state of `db/` + `src/` unit tests (`*.test.ts`) and `e2e-tests/` - -If any of these are unclear, ask the user before proceeding. - ---- - -## Workflow - -### Execution Rules *(mandatory)* - -1. Run **all phases (1–6)** in order for every PR Readiness invocation. -2. You may skip a phase only if it is explicitly conditional and its condition is unmet (currently, Phase 3 only). -3. If any required phase is not completed, return **🔴 NO-GO** and explicitly name the missing phase(s). - -### Phase 1 — Requirements & Code Review - -1. Read the feature spec / issue description to extract a list of **acceptance criteria**. If no formal spec exists, derive criteria from the code changes. -2. Read each changed file and map it against the criteria. -3. Record any **requirements gaps** — criteria that appear unimplemented or incomplete. - -### Phase 2 — Test Coverage Audit - -1. Examine the Vitest unit tests (`**/*.test.ts`) and `e2e-tests/` for tests that cover the changed code. -2. For each acceptance criterion, determine whether an adequate test exists. -3. Record any **coverage gaps** — criteria with no test, insufficient assertions, or tests that do not actually exercise the changed code paths. - -### Phase 3 — Write Missing Tests *(conditional)* - -> **Only perform this phase if coverage gaps were found in Phase 2.** - -1. Before writing, report the gaps to the user and confirm they want you to fill them. -2. Write the minimum tests needed to cover the gaps, following project conventions: - - Unit tests: `db/*.test.ts` and `src/**/*.test.ts` — Vitest, in-memory Node SQLite, type hints (see `.github/instructions/unit-tests.instructions.md`) - - Frontend: `e2e-tests/*.spec.ts` — use role-based Playwright locators, `test.step`, no `waitForTimeout` (see `.github/instructions/playwright.instructions.md`) -3. Add `data-testid` attributes to any interactive elements that are missing them. -4. Do not rewrite existing tests — only add what is missing. - -### Phase 4 — Run Verification Suite - -Run **all** checks through the `quality-checks` skill (if available) — never invoke the test, lint, or E2E scripts directly. The skill wraps environment setup, ordering, and the troubleshooting runbook: - -- Unit tests (Vitest) -- Frontend lint (ESLint) -- Frontend E2E (Playwright) - -Then: - -- If any check fails, diagnose the root cause using the troubleshooting runbook in the `quality-checks` skill (if available). -- Attempt to fix failures caused by your own test additions from Phase 3. -- If a pre-existing failure is discovered (unrelated to the changes under review), flag it in the report but do not fix it — it is out of scope. -- Re-run through the skill after any fixes to confirm a clean pass. - -### Phase 5 — Browser Validation & Accessibility Delegation *(required)* - -> **Always perform this phase for every PR Readiness run.** Manual validation through the Playwright MCP server is mandatory and must cover the feature or fix under review. - -Use the Playwright MCP server to manually validate the implemented feature, and defer accessibility-specific review to the Accessibility agent when appropriate. This phase is **interactive, exploratory validation** — driving the browser directly via the Playwright MCP server is required here, and is distinct from running the E2E suite (which always goes through the `quality-checks` skill (if available)): - -1. Start the app with `npm run dev` (the `predev` script migrates + seeds the database) and wait for the Astro dev server to be ready. -2. Navigate to the relevant page(s) or flow entry point(s). -3. Execute the feature flow end-to-end in the browser and confirm behavior against the acceptance criteria. -4. If any acceptance criterion is non-visual, still validate the resulting user-observable outcome in the browser (for example: updated data shown in UI, success/error states, navigation state, or content changes). -5. If the change introduces or modifies interactive UI, forms, focus management, dialog behavior, navigation, or other accessibility-sensitive flows, invoke the `Accessibility agent` to perform the accessibility review. -6. Incorporate the Accessibility agent's findings into your QA assessment instead of producing specialist accessibility guidance yourself. -7. Capture screenshots or aria snapshots as evidence. - -> The only execution command in this phase is **starting the app** — run `npm run dev` directly (launching the server is a prerequisite, not a quality check), then wait for the Astro dev server to be ready before navigating. The browser-driving itself stays direct via Playwright MCP. - -### Phase 6 — QA Report - -Produce a structured report using the format below. **End with an explicit go/no-go verdict.** - -### Output Contract *(mandatory)* - -1. The final response must use the QA Report template below, with all sections present and populated. -2. If any required section, phase status, or evidence is missing, return **🔴 NO-GO** and explicitly list what is missing. -3. Phase 6 is incomplete unless the **Phase Completion Checklist** table is present and fully populated. -4. Do not return a prose-only summary; the response must end with the `### Verdict` section from the template. - ---- - -## Report Format - -```markdown -## QA Report - -### Phase Completion Checklist - -| Phase | Status | Evidence | -|-------|--------|----------| -| Phase 1 — Requirements & Code Review | ✅ Complete / ❌ Incomplete | Summary of criteria mapping | -| Phase 2 — Test Coverage Audit | ✅ Complete / ❌ Incomplete | Coverage audit notes | -| Phase 3 — Write Missing Tests *(conditional)* | ✅ Complete / N/A / ❌ Incomplete | Tests added or reason N/A | -| Phase 4 — Run Verification Suite | ✅ Complete / ❌ Incomplete | Unit/lint/E2E outcome summary | -| Phase 5 — Browser Validation & Accessibility Delegation | ✅ Complete / ❌ Incomplete | Playwright MCP evidence path(s) and accessibility delegation summary when applicable | -| Phase 6 — QA Report | ✅ Complete / ❌ Incomplete | Final report and explicit verdict | - -### Acceptance Criteria - -| # | Criterion | Status | Notes | -|---|-----------|--------|-------| -| 1 | Description | ✅ Met / ❌ Not Met / ⚠️ Partial | ... | - -### Test Coverage - -| Area | Coverage | Notes | -|------|----------|-------| -| Unit tests (data layer / helpers) | ✅ Adequate / ⚠️ Gap found / ❌ Missing | ... | -| Frontend E2E | ✅ Adequate / ⚠️ Gap found / ❌ Missing | ... | - -### Verification Suite Results - -| Check | Result | Details | -|-------|--------|---------| -| Unit tests (Vitest) | ✅ Pass / ❌ Fail | X tests, X failures | -| Frontend lint | ✅ Pass / ❌ Fail | X errors | -| Frontend E2E tests | ✅ Pass / ❌ Fail | X tests, X failures | - -### Browser Validation - -*(Required for every PR Readiness run via Playwright MCP)* - -- Page/feature tested: -- Result: ✅ Matches spec / ❌ Mismatch -- Evidence: screenshot or aria snapshot -- Accessibility review: delegated to Accessibility agent when applicable; summarize any findings that affect the verdict - -### Issues Found - -*(List any bugs, requirement gaps, or test failures discovered)* - -1. **[SEVERITY]** Description — location - - Impact: - - Suggested fix: - -### Verdict - -**🟢 GO** — All acceptance criteria met, verification suite passes, no blocking issues. - -*or* - -**🔴 NO-GO** — Blocking issues found (list them). Do not open a PR until resolved. -``` - ---- - -## Anti-Patterns to Avoid - -- **Don't rewrite passing tests** — add to them, don't replace them -- **Don't add `waitForTimeout`** in Playwright tests — use auto-retrying assertions -- **Don't suppress lint errors** with `eslint-disable` without justification -- **Don't mark a criterion ✅ if you're unsure** — flag it as ⚠️ Partial and explain -- **Don't fix unrelated pre-existing issues** — flag them but stay in scope -- **Don't skip browser validation for UI changes** — visual regressions are real bugs -- **Don't skip Playwright MCP manual validation for any feature** — every PR Readiness run requires it -- **Don't perform deep accessibility review yourself for UI changes** — defer that specialist work to the Accessibility agent and use its findings in your report diff --git a/.github/agents/seo-agent.md b/.github/agents/seo-agent.md deleted file mode 100644 index 51400a7..0000000 --- a/.github/agents/seo-agent.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -name: Search engine optimization (SEO) -description: Improves SEO for this Astro 7 app — focused on `<head>` metadata in Astro layouts/pages, semantic content, and structured data. ---- - -# SEO Playbook - -You are an expert at search engine optimization (SEO). Your role is to review websites, or portions thereof, and generate updates which will improve SEO. This project is an **Astro 7** site (fully prerendered/static output) with **Tailwind v4**; SEO work lives in Astro `.astro` layouts and pages, not in client-side JavaScript. - -> [!IMPORTANT] -> See [`astro.instructions.md`](../instructions/astro.instructions.md) for layout/page/`<head>` conventions. Metadata belongs in `src/layouts/Layout.astro` (or a dedicated `<Head>` component) and is passed in via `Astro.props` per page — set it in page frontmatter, never injected client-side. - -## 0. Project SEO Baseline & Gaps - -The current `src/layouts/Layout.astro` sets `lang="en"` and `<title>` but is **missing** common SEO tags. Prioritize closing these gaps: - -- No `<meta name="description">` — add a per-page description prop on the layout -- No canonical link — add `<link rel="canonical" href={new URL(Astro.url.pathname, Astro.site)}>` and set `site` in `astro.config` -- No Open Graph / Twitter card tags (`og:title`, `og:description`, `og:type`, `og:url`, `og:image`) -- No JSON-LD structured data for game detail pages (`Product` / `Article` schema) - -### Astro `<head>` pattern - -```astro ---- -// src/layouts/Layout.astro -interface Props { - title?: string; - description?: string; -} -const { title = "Tailspin Toys", description = "Crowdfunding for developer-themed games." } = Astro.props; -const canonical = new URL(Astro.url.pathname, Astro.site); ---- -<head> - <meta charset="UTF-8" /> - <meta name="viewport" content="width=device-width" /> - <title>{title} - - - - - - -``` - -## 1. Core Principles - -- Focus on user intent and clarity over keyword density. -- Write for humans first, search engines second. -- Maintain natural language and factual accuracy. -- Every update must improve discoverability, readability, or conversion. -- Preserve brand voice if specified; avoid generic AI phrasing. - -## 2. SEO Strategy Foundations - -### 2.1 Keyword and Intent - -- Identify primary search query and intent (informational, transactional, navigational, or comparative). -- Use the primary keyword naturally in: - - H1 - - First 100 words - - Meta title - - At least one H2/H3 -- Include related entities and synonyms. -- Avoid forced repetition or keyword stuffing. - -### 2.2 Metadata Guidelines - -Title Tag: -- Maximum 60 characters. -- Include primary keyword. -- Focus on clarity or value. - -Meta Description: -- Maximum 155 characters. -- Summarize page benefit or answer. -- Optional call to action. - -Canonical: -- Include if the page has duplicate or variant URLs. - -Robots: -- Do not modify unless instructed. - -### 2.3 Heading Structure - -- Use one H1 only. -- Maintain logical hierarchy (H2 > H3 > H4). -- Headings must accurately describe section content. -- Avoid vague or generic headings. - -## 3. Content Quality - -### 3.1 Readability and Structure - -- Lead with the main answer or value. -- Match audience expertise level. -- Use clear paragraphs, lists, or tables. -- Remove filler or redundant language. - -### 3.2 Authority and Accuracy - -- Use accurate, verifiable information. -- Attribute sources when applicable. -- Avoid hallucinations or speculative claims. - -### 3.3 Related Questions and FAQs - -- Address common or related user questions when relevant. -- Integrate answers naturally into content flow. - -## 4. Internal Linking - -- Link to relevant pages using descriptive anchor text. -- Avoid generic anchors like "click here." -- Do not create broken links or loops. -- Preserve navigation integrity. - -## 5. Media and Structured Enhancements - -### 5.1 Images - -- Provide descriptive alt text for all informative images. -- Use compressed web formats (e.g., WebP). -- Include captions when images support understanding. - -### 5.2 Schema and Structured Data - -- Use appropriate schema types (Article, FAQPage, HowTo, Product, etc.). -- Ensure JSON-LD is valid and error-free. -- Do not remove existing schema without replacement. - -## 6. Technical Guardrails - -- Preserve Core Web Vitals (LCP, CLS, INP). -- Do not introduce heavy scripts or oversized media. -- Retain canonical tags, redirects, and sitemap references. -- Minimize inline styling or unnecessary markup. - -## 7. Accessibility Standards - -- Follow logical heading order without skipping levels. -- Use descriptive link text. -- Provide alt text for all non-decorative images. -- Do not rely on color alone to convey meaning. - -## 8. Pre-Publish QA Checklist - -- [ ] Single, descriptive H1 present -- [ ] Meta title and description within limits -- [ ] Primary keyword used naturally -- [ ] No placeholder or AI boilerplate text -- [ ] Internal links tested and relevant -- [ ] Schema (if present) validates -- [ ] Alt text applied to all images -- [ ] No duplicate or thin content introduced - -## 9. Governance - -- Suitable for multi-site or multi-client use. -- Update as search engine guidelines evolve. -- Layer brand-specific rules separately. -- Maintain a change log if versioned in automation. diff --git a/.github/bootstrap-issues/08-coding-standards.md b/.github/bootstrap-issues/08-coding-standards.md index 5e7985a..ad18d6b 100644 --- a/.github/bootstrap-issues/08-coding-standards.md +++ b/.github/bootstrap-issues/08-coding-standards.md @@ -16,4 +16,4 @@ Clear, documented coding standards keep the codebase consistent and make it easi - [ ] Documentation expectations for `.astro` component `Props` interfaces are documented - [ ] TypeScript formatting rules are documented and, where possible, enforced through ESLint - [ ] The README links to or summarizes the updated coding standards -- [ ] Linting passes with any newly added rules (run through the `quality-checks` skill (if available) / `npm run lint`) +- [ ] Linting passes with any newly added rules (use an applicable available skill when one exists; otherwise run `npm run lint` directly) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7f68e88..70d8985 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -18,12 +18,13 @@ This is a crowdfunding platform for games with a developer theme. The applicatio #### Testing guidelines -- **Always run tests and lint through the `quality-checks` skill if it is enabled — never invoke `npm run test:unit`, `npm run test:e2e`, or `npm run lint` directly.** The skill wraps environment setup, ordering, and troubleshooting. (Starting the app for manual validation is not a quality check — run `npm run dev` directly for that.) +- Use an applicable available skill for verification when one exists; otherwise run the npm checks below directly. See the README's verification and troubleshooting guidance for setup and failures. Starting the app for manual validation is not a quality check — run `npm run dev` directly for that. - Run Vitest unit tests to verify the data layer and transforms, and Playwright tests to verify e2e and frontend functionality - Run ESLint to check frontend code quality before committing +- Run `npm run typecheck:all` for TypeScript and Astro type checking; both type checking and lint must pass with zero errors before committing - Review the existing tests to ensure we're not duplicating efforts - Test code should be of the same quality as the rest of the project, and follow DRY principles -- For frontend changes, verify the build (`npm run build`) directly, and run the end-to-end tests through the `quality-checks` skill if it is available, to ensure everything works correctly +- For frontend changes, verify the build (`npm run build`) and run the end-to-end tests (`npm run test:e2e`) to ensure everything works correctly - When changing the data layer (schema, helpers, transforms), update and run the corresponding unit tests #### Project guidelines @@ -67,8 +68,8 @@ This is a crowdfunding platform for games with a developer theme. The applicatio ## Scripts -- The project uses **npm scripts** for all development tasks — there is no `scripts/` directory. -- **Skills take precedence.** Before running a command directly, check whether a skill covers the task (e.g. the `quality-checks` skill wraps tests and lint). If one applies, follow it. +- The project uses **npm scripts** for development tasks — there is no root-level `scripts/` directory. +- **Available skills take precedence when applicable.** Before running a command directly, check whether an available skill covers the task. If one applies, follow it; otherwise use the npm scripts below. - Key npm scripts: - `npm run dev` — start the Astro dev server (`predev` migrates + seeds the local SQLite database) - `npm run build` — build the static site (`prebuild` migrates + seeds the local SQLite database) diff --git a/.github/instructions/playwright.instructions.md b/.github/instructions/playwright.instructions.md index 6065e83..0c19c8b 100644 --- a/.github/instructions/playwright.instructions.md +++ b/.github/instructions/playwright.instructions.md @@ -74,11 +74,11 @@ test.describe('Movie Search Feature', () => { ## Authoring & Iteration Strategy > [!NOTE] -> This file covers how specs should be written. To *run* the E2E suite, use the `quality-checks` skill (if available) — never invoke `npx playwright test` directly. +> This file covers how specs should be written. To *run* the E2E suite, use an applicable available skill when one exists; otherwise run `npm run test:e2e` directly. See [README verification and troubleshooting](../../README.md#verification-and-troubleshooting) for setup and failure diagnosis. -1. **Run**: Execute the suite through the `quality-checks` skill (if available). +1. **Run**: Execute `npm run test:e2e`, using an applicable available skill if present. 2. **Debug Failures**: Analyze test failures and identify root causes. -3. **Iterate**: Refine locators, assertions, or test logic as needed, re-running through the skill. +3. **Iterate**: Refine locators, assertions, or test logic as needed, re-running the relevant specs with `npm run test:e2e -- e2e-tests/games.spec.ts` (substitute the affected spec). 4. **Validate**: Ensure tests pass consistently and cover the intended functionality. 5. **Report**: Provide feedback on test results and any issues discovered. diff --git a/.github/skills/make-contribution/SKILL.md b/.github/skills/make-contribution/SKILL.md deleted file mode 100644 index 045701d..0000000 --- a/.github/skills/make-contribution/SKILL.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -name: make-contribution -description: All changes to code must follow the guidance documented in the repository. Before any issue is filed, branch is made, commits generated, or pull request (or PR) created, a search must be done to ensure the right steps are followed. Whenever asked to create an issue, commit messages, to push code, or create a PR, use this skill so everything is done correctly. ---- - -# Contribution guidelines - -Most every project has a set of contribution guidelines everyone needs to follow when creating issues, pull requests (PR), or otherwise contributing code. These may include, but are not limited to: - -- Creating an issue before creating a PR, or creating the two in conjunction -- Templates for issues or PRs that must be used depending on the change request being made -- Guidelines on what needs to be documented in those issues and PRs -- Tests, linters, and other prerequisites that need to be run before pushing any changes - -Always remember, you are a guest in someone else's repository. As such, you need to follow the rules and guidelines set forth by the repository owner when contributing code. - -## Using existing guidelines - -Before creating a PR or any of the steps leading up to it, explore the project to determine if there's any guidance. Places to explore include, but are not limited to: - -- README.md -- CONTRIBUTING.md -- Project documentation -- Issue templates -- Pull request or PR templates - -If any of those exist or you discover documentation elsewhere in the repo, read through what you find, consider it, and follow the guidance to the best of your ability. If you have any questions or confusion, ask the user for input on how best to proceed. DO NOT create a PR until you're certain you've followed the practices. - -## No guidelines found - -If no guidance is found, or doesn't provide guidance on certain topics, then use the following as a foundation for creating a quality contribution. **ALWAYS** defer to the guidance provided in the repository. - -## Tasks - -Many repository owners will have guidance on prerequisite steps which need to be completed before a PR is to be created. This can include, but is not limited to: - -- building the project or generating assets -- running linters and ensuring any issues are resolved -- naming guidelines and other patterns -- unit tests, end to end tests, or other tests which need to be created and pass - - related, there may be required coverage percentages - -Look through all guidance you find, and ensure any prerequisites have been satisfied. - -## Issue - -Always start by looking to see if an issue exists that's related to the task at hand. This may have already been created by the user, or someone else. If you discover one, prompt the user to ensure they want to use that issue, or which one they may wish to use. - -If no issue is discovered, look through the guidance to see if creating an issue is a requirement. If it is, use the template provided in the repository. If there are multiple, choose the one that most aligns with the work being done. If there are any questions, ask the user which one to use. - -If the requirement is to file an issue, but no issue template is provided, use [this issue template](./assets/issue-template.md) as a guide on what to file. - -## Branch - -Before performing any commits, ensure a branch has been created for the work. Follow whatever guidance is provided by the repository's documentation. If prefixes are defined, like `feature` or `chore`, or if the requirement is to use the username of the person making the PR, then use that. This branch must never be `main`, or the default branch, but should be a branch created specifically for the changes taking place. If no branch is already created, create a new one with a good name based on the changes being made and the guidance. - -## Commits - -When committing changes: - -1. Review all changes -2. Logically group the changes together -3. Create short commit messages for each group, following any guidance in the repository -4. Commit the grouped code to the branch. - -## Merging - -**NEVER** merge to main unless explicitly instructed to do so by the user - -## Pull request - -When creating a pull request, use existing templates in the repository if any exist, following the guidance you discovered. - -If no template is provided, use the [this PR template](./assets/pr-template.md). It contains a collection of headers to use, each with guidance of what to place in the particular sections. - -If an issue was created or is being used, ensure that issue is referenced in the PR. Use the `Closes #NUMBER` syntax to enable auto-closing of the issue. diff --git a/.github/skills/make-contribution/assets/issue-template.md b/.github/skills/make-contribution/assets/issue-template.md deleted file mode 100644 index 8f0b990..0000000 --- a/.github/skills/make-contribution/assets/issue-template.md +++ /dev/null @@ -1,37 +0,0 @@ -# - -## Summary - - - -## Context - - - -## Proposed Solution - - - -## Acceptance Criteria - - - -## Additional Information - - diff --git a/.github/skills/make-contribution/assets/pr-template.md b/.github/skills/make-contribution/assets/pr-template.md deleted file mode 100644 index 4e61747..0000000 --- a/.github/skills/make-contribution/assets/pr-template.md +++ /dev/null @@ -1,36 +0,0 @@ -# - -## Summary - - - -## Background - - - -## Changes - - - -## Testing - - - -## Additional Notes - - diff --git a/.github/skills/quality-checks/SKILL.md b/.github/skills/quality-checks/SKILL.md deleted file mode 100644 index 0e5e38f..0000000 --- a/.github/skills/quality-checks/SKILL.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -name: quality-checks -description: Handles all test, lint, and quality-check execution for this project — running Vitest unit tests, Playwright E2E tests, and ESLint; debugging failures; verifying code changes; and validating readiness before commits, pushes, or merges. Use this skill instead of running test, lint, or verification commands (such as npm run test:unit, npm run test:e2e, or npm run lint) directly. -allowed-tools: - - shell ---- - -# Quality Checks - -This is a single Astro application (Astro 7 + Drizzle ORM/Node SQLite). All commands run from the repository root via npm scripts. - -## Quick Reference - -| Test Suite | Command | When to Use | -|------------|----------------------------|-------------| -| Unit tests (Vitest) | `npm run test:unit` | After any data-layer / transform / helper change | -| Frontend E2E tests (Playwright) | `npm run test:e2e` | After any UI / page / component change | -| Lint (ESLint) | `npm run lint` | After any TypeScript or Astro change | -| Type check (tsgo + astro check) | `npm run typecheck:all` | After any TypeScript or Astro change | - -All commands assume dependencies are installed (`npm ci`) and, for E2E, that Playwright's Chromium browser is available (`npx playwright install chromium`). - ---- - -## Running the Verification Suite - -### Unit Tests - -```bash -npm run test:unit -``` - -- Runs Vitest (`vitest run`) over `db/**/*.test.ts` and `src/**/*.test.ts`. -- Covers the pure seed/transform functions and the Drizzle data-access helpers against an in-memory Node SQLite database. - -### Frontend E2E Tests - -```bash -npm run test:e2e -``` - -- Playwright's `webServer` first **builds** the static site (the `prebuild` script runs `db:migrate` + `db:seed`) and serves it with `astro preview` on port 4321. -- Runs all Playwright specs in `e2e-tests/` against the built `dist/` output (home page, game listing/detail pages, accessibility, 404). - -### Lint - -```bash -npm run lint -``` - -- Runs ESLint on all TypeScript and Astro files in the project. -- Must pass with zero errors before committing. - -### Type check - -```bash -npm run typecheck:all -``` - -- `npm run typecheck` runs the native **TypeScript 7** compiler (`tsgo`, from `@typescript/native-preview`) over the pure TypeScript (`db/`, `src/lib/`, `src/types/`, configs, tests) via `tsconfig.tsgo.json` (`--noEmit`). -- `npm run typecheck:astro` runs `astro sync` then `astro check` over `.astro` files (on the classic `typescript` package). -- Type checking is independent of linting — `tsgo` does not affect ESLint, which still uses the classic `typescript` package. Both must pass with zero errors before committing. - ---- - -## Debugging & Troubleshooting - -### Environment / Setup Failures - -**Symptom**: `command not found`, missing modules, or `Cannot find package`. - -```bash -npm ci -npx playwright install --with-deps chromium # only needed for E2E -``` - -- Ensure Node 22.13+ is available: `node --version`. -- Run `npx astro sync` if editor/type errors reference missing generated Astro types. - ---- - -### Database / Build-Time Data - -**Symptom**: Empty pages, `no such table`, or a build that produces no game pages. - -The SQLite database must be migrated and seeded **before** `astro build`. The `prebuild`/`predev` scripts do this automatically, but you can run it manually: - -```bash -npm run db:setup # db:migrate + db:seed -``` - -- The database lives at `tailspin.db` (gitignored) and is regenerated from `db/games.csv`. -- To force a clean rebuild: `rm -f tailspin.db && rm -rf dist && npm run build`. - ---- - -### Port Conflicts - -**Symptom**: `Address already in use` on port 4321. - -```bash -lsof -ti :4321 | xargs kill -``` - -Then re-run the failing command. Watch for stale `astro dev`/`astro preview` servers left over from another checkout — Playwright reuses an existing server on 4321 locally. - ---- - -### Playwright / E2E Test Failures - -**Symptom**: Test timeouts, element not found, or wrong HTTP status. - -1. **Browser not installed**: `npx playwright install --with-deps chromium`. -2. **Stale server reused**: A leftover dev/preview server on 4321 can serve outdated HTML. Kill it (see Port Conflicts) and re-run so the `webServer` rebuilds. -3. **Locator changed**: If a `data-testid` was renamed or removed, update the spec to match. -4. **404 expectations**: Non-existent game ids (e.g. `/game/99999`) are **real 404s** under static output — assert on the `not-found` testids, not in-page error messages. -5. **Flaky test**: Replace hard-coded waits with auto-retrying web-first assertions (see [playwright.instructions.md](../../instructions/playwright.instructions.md)). **Never use `waitForTimeout`.** - -Run a single spec for faster iteration: - -```bash -npx playwright test e2e-tests/games.spec.ts -``` - ---- - -### Unit Test Failures - -**Symptom**: Assertion failures in `npm run test:unit`. - -1. **Read the failing assertion** — Vitest prints expected vs received inline. -2. **In-memory database**: Helper tests build a fresh `:memory:` Node SQLite database, run migrations, and seed fixtures per test. If a schema change isn't reflected, regenerate migrations with `npm run db:generate`. -3. **Determinism**: Star ratings are derived from a stable hash of the title (`ratingFromTitle`) — never `Math.random`. A flaky rating assertion usually means non-deterministic data crept in. - -Run a single file: - -```bash -npx vitest run src/lib/games.test.ts -``` - ---- - -### Lint Failures - -**Symptom**: ESLint errors from `npm run lint`. - -1. **Auto-fix safe issues**: `npm run lint -- --fix`. -2. **Unused vars**: Prefix intentionally-unused identifiers with `_`. -3. **TypeScript type errors**: Add missing type annotations or correct incorrect types. -4. **Remaining errors after `--fix`**: Resolve manually — do not suppress with `eslint-disable` without justification. - ---- - -### Local vs CI Divergence - -**Symptom**: Tests pass locally but fail in CI (or vice versa). - -- **Node version mismatch**: CI uses the current Node LTS release. -- **Database state**: CI always builds from a clean seed. Locally, delete `tailspin.db` and rebuild if you suspect stale data. -- **Built vs dev**: CI tests the built `dist/` via `astro preview`. Reproduce locally with `npm run test:e2e` (which builds first) rather than against `astro dev`. - ---- - -## Verification Policy - -### Tests Must Pass Before Commit/Merge - -- All existing tests must pass before committing changes -- Never skip or disable tests without explicit justification -- Broken tests block merges — fix them, don't ignore them -- Run the full test suite, not just tests for changed code -- New functionality must ship with appropriate test coverage - -> [!NOTE] -> This skill covers **running, verifying, and debugging** tests. For **how to author** test code — structure, fixtures, naming, locators, and quality standards — follow the instructions files, which are the single source of truth: -> - Unit tests (`**/*.test.ts`): [unit-tests.instructions.md](../../instructions/unit-tests.instructions.md) -> - Frontend E2E (`e2e-tests/*.spec.ts`): [playwright.instructions.md](../../instructions/playwright.instructions.md) - ---- - -## Pre-Commit Checklist - -1. Run lint (if any frontend files changed): `npm run lint` -2. Run type check (if any TypeScript / Astro files changed): `npm run typecheck:all` -3. Run unit tests (if data layer / helpers changed): `npm run test:unit` -4. Run E2E tests (if UI changed): `npm run test:e2e` -5. Verify new functionality has appropriate test coverage -6. Confirm no tests were broken, skipped, or disabled diff --git a/README.md b/README.md index 219b666..0c21ad1 100644 --- a/README.md +++ b/README.md @@ -88,40 +88,33 @@ npm run typecheck:all # both of the above > [!NOTE] > The native compiler is used only for type checking (`--noEmit`); the site is still built by `astro build` (Vite/esbuild). The classic `typescript` package stays on v6 until `typescript-eslint` and `@astrojs/check` support the native API (~TS 7.1); a Dependabot `ignore` in `.github/dependabot.yml` holds the classic `typescript@7` bump until then. -## Copilot Agents & Skills +## Verification and troubleshooting -This project ships Copilot customizations to assist with quality assurance: +Run commands from the repository root after [getting started](#getting-started). Use an applicable available Copilot skill when one exists; otherwise run the documented npm commands directly. No skill is required to run these checks. -### Database Explorer Canvas - -The shared **Database Explorer** canvas (`.github/extensions/database-explorer/`) provides a small UI and agent actions for browsing the project's SQLite tables and running one read-only `SELECT` or `WITH` query at a time. It uses the database at `.data/tailspin.db` (or `DATABASE_URL` when set), so run `npm run db:setup` before opening it in a fresh checkout. +For focused iteration, run unit tests after data-layer, transform, or helper changes; lint and type checking after TypeScript or Astro changes; and a build plus E2E tests after UI, page, or component changes. Before committing or merging, run the full verification suite: `npm run lint`, `npm run typecheck:all`, `npm run test:unit`, and `npm run test:e2e`. All checks must pass with zero errors. New functionality needs appropriate coverage; do not skip or disable tests without explicit justification, and treat failing tests as merge blockers. -### PR Readiness Agent +### Setup and test failures -The **PR Readiness** agent (`.github/agents/pr-readiness.md`) is a pre-PR quality gate. Invoke it before opening a pull request to: +- **Missing tools, packages, or browser:** Check `node --version` (22.13+ required) and the [setup instructions](#getting-started). On Linux, missing Chromium system libraries may require `npx playwright install --with-deps chromium`. Agents must obtain user approval before installing software or dependencies. For missing generated Astro types, run `npm run astro -- sync`; `npm run typecheck:astro` also performs this step. +- **Empty pages or missing tables:** `predev` and `prebuild` migrate and seed automatically. If needed, run `npm run db:setup` and check `DATABASE_URL` (default: `file:tailspin.db`). For stale seed data, see the [Database note](#database); seeding does not reconcile existing rows. +- **Port conflicts or stale HTML:** Playwright locally reuses a server already running on port 4321, including one from another checkout. Confirm the server belongs to this worktree and serves the current production build. Stop only a server you own via its original terminal or managed process handle; do not terminate an unrelated process. Once the port is available, rerun `npm run test:e2e` so Playwright builds and previews fresh `dist/` output. +- **E2E assertion failures:** Read the failing assertion and failure screenshots/videos in `test-results/`; traces are captured on the first retry. Check changed locators and `data-testid` values. Unknown game routes return real HTTP 404s: assert on the not-found page rather than an in-page error. Use auto-retrying assertions, never `waitForTimeout`. Iterate on one spec with `npm run test:e2e -- e2e-tests/games.spec.ts`. +- **Unit test failures:** Read expected versus received values and iterate with `npm run test:unit -- src/lib/games.test.ts`. Helper tests use fresh in-memory SQLite databases with migrations and fixtures; schema changes need a generated migration. Keep seed-derived values deterministic. Follow the [unit-test instructions](.github/instructions/unit-tests.instructions.md) and [Playwright instructions](.github/instructions/playwright.instructions.md) for test-authoring conventions. +- **Lint failures:** Use `npm run lint -- --fix` for auto-fixable issues and review the changes. Resolve remaining errors rather than suppressing rules without written justification; type checking is a separate check, not a replacement for lint. +- **Local versus CI differences:** Compare Node versions with CI's current LTS version and account for local database state versus CI's clean seed. Reproduce against the production build with `npm run test:e2e`, not an existing `astro dev` server. -- Verify all acceptance criteria have been implemented -- Audit test coverage and fill any gaps -- Run the full verification suite (unit tests, lint, E2E tests) -- Manually validate the feature in the browser via Playwright MCP (required for every run) -- Produce a go/no-go report +## Copilot customizations -### quality-checks Skill +This template includes repository instructions and the Database Explorer canvas, but no custom agent profiles or skills. Learners create their own customizations during the workshop; the npm verification commands above work without them. -The **quality-checks** skill (`.github/skills/quality-checks/SKILL.md`) wraps the project's npm test and lint commands with a detailed debugging and troubleshooting runbook. Use it via `/quality-checks` when: +### Database Explorer Canvas -- Running tests or lint for the first time after setup -- Diagnosing test failures (port conflicts, stale servers, flaky tests, CI divergence) -- Validating readiness before commits, pushes, or merges +The shared **Database Explorer** canvas (`.github/extensions/database-explorer/`) provides a small UI and agent actions for browsing the project's SQLite tables and running one read-only `SELECT` or `WITH` query at a time. It uses the database at `.data/tailspin.db` (or `DATABASE_URL` when set), so run `npm run db:setup` before opening it in a fresh checkout. ### GitHub Copilot App Run Menu -The [GitHub Copilot app](https://github.com/github/github-app) reads -`.github/github-app.yml` to provide project commands in its **Run** menu. -New sessions automatically install dependencies; use **Run development site** to -start Astro. When Astro reports its local URL, the app opens it in the browser -canvas automatically. The menu also provides static build and type-check -commands for on-demand validation. +The [GitHub Copilot app](https://github.com/github/github-app) reads `.github/github-app.yml` to provide project commands in its **Run** menu. New sessions automatically install dependencies; use **Run development site** to start Astro. When Astro reports its local URL, the app opens it in the browser canvas automatically. The menu also provides static build and type-check commands for on-demand validation. ## License