nextjs-hackathon-stack 0.1.40 → 0.1.42

package/template/.opencode/agents/test-qa.md

@@ -0,0 +1,103 @@
+---
+name: test-qa
+description: Testing specialist. Use when writing tests, enforcing TDD workflow, fixing coverage gaps, or debugging test failures. Always write tests BEFORE implementation. Triggers: writing tests, TDD workflow, coverage gaps, test failures, mock setup.
+mode: subagent
+model: inherit
+---
+
+# Test & QA Agent
+
+## First Step — Load Context via MCP Memory
+
+1. Read `package.json` to get the project name (`<project-name>`)
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:patterns"]` and `query: "test mock supabase"` — canonical test references and mock setup
+3. **Fallback**: if the memory service is unavailable or returns no results, read `.opencode/memory/architecture-snapshot.md` directly
+
+After reading test patterns, save findings to MCP memory:
+```
+store_memory({
+  content: "Test pattern: <description of what was found>",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:patterns", "category:pattern", "pattern:test"]
+  }
+})
+```
+
+Import `makeChain` and `makeSupabaseMock` from `@/shared/test-utils/supabase-mock` — never recreate the mock chain from scratch.
+
+## TDD Workflow
+
+1. **RED** — write failing test that describes the desired behavior
+2. **GREEN** — write minimum code to make test pass
+3. **REFACTOR** — clean up while keeping tests green
+4. **VERIFY** — run `pnpm test:coverage` and confirm thresholds met
+
+## Verification Gates (mandatory — show output, do not just claim)
+
+| Gate | Command | Expected output |
+|------|---------|-----------------|
+| After RED | `pnpm test:unit` | All new tests **FAIL** (red) |
+| After GREEN | `pnpm test:unit` | All tests **PASS** (green) |
+| After VERIFY | `pnpm test:coverage` | ≥95% statements/functions/lines, ≥90% branches |
+
+**Never say "tests pass" or "tests fail" without showing the actual output.**
+**Do NOT write any implementation code until the RED gate output confirms failures.**
+
+## Coverage Requirement
+```
+branches: 90%
+functions: 95%
+lines: 95%
+statements: 95%
+```
+
+Use `/* v8 ignore next */` for genuinely unreachable defensive branches only.
+
+## Supabase Mock Pattern
+
+Always use the shared helpers — never inline mock chain construction:
+
+```typescript
+import { makeChain, makeSupabaseMock } from "@/shared/test-utils/supabase-mock";
+
+// Unauthenticated
+const { mockClient } = makeSupabaseMock({ user: null });
+
+// Authenticated + DB success
+const { mockClient, mockFrom } = makeSupabaseMock({ user: { id: "user-1" } });
+mockFrom.mockReturnValue(makeChain({ data: [...], error: null }));
+
+// DB error
+mockFrom.mockReturnValue(makeChain({ error: { message: "db error" } }));
+```
+
+## Test Plan Compliance
+
+When the Technical Lead provides a test plan, follow it:
+- Use the specified test files, `describe` block names, and mock setup
+- Flag missing edge cases to the TL **before** adding unplanned tests
+- If the plan is ambiguous, ask for clarification rather than guessing
+
+## AAA Pattern
+
+Every test must use the Arrange-Act-Assert pattern with labeled comments:
+
+```typescript
+it("should do X when Y", () => {
+  // Arrange
+  const input = ...;
+
+  // Act
+  const result = doSomething(input);
+
+  // Assert
+  expect(result).toBe(expected);
+});
+```
+
+## Guardrails
+- Never write implementation without a failing test first
+- Never mock internal project code — only external deps
+- Verify all edge cases: empty states, errors, loading states
+- AAA pattern with labeled comments in every test

package/template/.opencode/memory/architecture-snapshot.md

@@ -0,0 +1,127 @@
+# Architecture Snapshot
+
+> Auto-updated after each feature. Agents MUST read this before exploring the codebase.
+
+## Installed shadcn/ui Components
+
+button, card, input, label, spinner
+
+_Add new components here after `shadcn add <component>`_
+
+## DB Schema
+
+| Table | Columns |
+|-------|---------|
+| `profiles` | id (uuid PK), email (text unique), createdAt, updatedAt |
+| `todos` | id (uuid PK), userId (uuid), title (text), completed (bool), createdAt |
+
+_Add new tables here after `pnpm db:generate && pnpm db:migrate`_
+
+## Existing Features
+
+| Feature | Path | Description |
+|---------|------|-------------|
+| auth | `src/features/auth/` | Login/logout, cookie-based sessions via Supabase |
+| todos | `src/features/todos/` | CRUD todos with Supabase RLS |
+
+_Add new features here after implementation_
+
+## Canonical Pattern References
+
+Read these files to understand the project's proven patterns before writing new code:
+
+| Pattern | File |
+|---------|------|
+| Server Action | `src/features/todos/actions/todos.action.ts` |
+| Query (repository) | `src/features/todos/queries/todos.queries.ts` |
+| Client component | `src/features/todos/components/todo-list.tsx` |
+| Action test | `src/features/todos/__tests__/todos.action.test.ts` |
+| Component test | `src/features/todos/__tests__/todo-list.test.tsx` |
+| Supabase mock chain | `src/shared/test-utils/supabase-mock.ts` |
+
+## Key Rules (summary)
+
+- Runtime queries: Supabase client only — Drizzle is schema/migrations only
+- All mutations: Server Actions returning `ActionResult` from `@/shared/lib/action-result`
+- Auth check first in every Server Action: `supabase.auth.getUser()`
+- Toast feedback required for every mutation (success + error) via `sonner`
+- RLS must be enabled on every table before a feature is considered complete
+- UI text: Spanish | Code-level text: English (test descriptions, variable names)
+- Coverage threshold: 95% statements/functions/lines, 90% branches — use `/* v8 ignore next */` for genuinely unreachable defensive branches
+
+## Shared Utilities
+
+Reuse these before writing new helpers:
+
+| Utility | Location | Purpose |
+|---------|----------|---------|
+| `formFieldText(formData, key)` | `src/shared/lib/form-utils.ts` | Safe `FormData` text extraction — avoids `no-base-to-string` lint error |
+| `firstZodIssueMessage(error)` | `src/shared/lib/zod-utils.ts` | Extract first Zod validation error message |
+| `readUploadFileBuffer(file)` | `src/shared/lib/upload-utils.ts` | Read a `File`/`Blob` upload to `ArrayBuffer` safely |
+
+## Strict Rules Reference
+
+Read this before writing any code. These are the rules that most often cause post-hoc fix cycles.
+
+### TypeScript Compiler (`tsconfig.json`)
+
+`"strict": true` plus additional flags:
+
+| Flag | What it enforces | How to comply |
+|------|-----------------|---------------|
+| `noUncheckedIndexedAccess` | `arr[i]` / `obj[key]` return `T \| undefined` | Guard: `const val = arr[0]; if (val) { ... }` |
+| `exactOptionalPropertyTypes` | Cannot assign `undefined` to optional props | Omit the key entirely; never write `{ prop: undefined }` |
+| `noImplicitOverride` | Subclass overrides need `override` keyword | `override render() {}` |
+| `noFallthroughCasesInSwitch` | Every `case` needs `break`/`return`/`throw` | Add `break` to every case |
+| `noImplicitReturns` | Every code path must return | Add explicit `return` in all branches |
+| `noUnusedLocals` / `noUnusedParameters` | No unused vars/params | Prefix unused params with `_` |
+| `useUnknownInCatchVariables` | `catch (e)` → `e` is `unknown` | Narrow: `if (e instanceof Error)` before `.message` |
+
+### ESLint — Rules That Most Often Trip AI Agents
+
+Preset: `tseslint.configs.strictTypeChecked` + `stylisticTypeChecked`. Runs with `--max-warnings 0` (warnings = errors).
+
+**Unsafe-any family (all "error"):**
+- `no-unsafe-assignment`, `no-unsafe-member-access`, `no-unsafe-call`, `no-unsafe-return`, `no-unsafe-argument`
+- Never let `any` flow through. Cast `JSON.parse()` results. Type all mock returns explicitly.
+
+**Promise handling:**
+- `no-floating-promises`: Every Promise must be `await`ed, returned, or `void`-prefixed
+- `no-misused-promises`: Async functions in React event handlers need a `void` wrapper: `onClick={() => void handleSubmit()}`
+- `require-await`: `async` functions must contain `await`; remove `async` if not needed
+- `return-await`: Must use `return await` inside `try/catch`
+
+**Type safety:**
+- `no-explicit-any`: Use `unknown` and narrow; never use `any`
+- `no-non-null-assertion`: Cannot use `!` postfix; narrow with conditionals
+- `no-base-to-string`: Objects without `toString()` cannot appear in template literals or string concatenation — use `formFieldText()` for `FormData` values
+- `restrict-template-expressions`: Template literals only accept `string | number | boolean`
+- `no-unnecessary-condition`: Don't check conditions that are always truthy/falsy per types
+- `unbound-method`: Don't detach methods from objects; bind or use arrow functions
+- `only-throw-error`: Only throw `Error` instances, never strings or plain objects
+- `use-unknown-in-catch-callback-variable`: `.catch(err => ...)` — `err` must be `unknown`
+
+**Imports & style:**
+- `consistent-type-imports`: Use `import type { X }` for type-only imports
+- `import-x/order`: Imports grouped (builtin → external → internal → parent → sibling → index), alphabetized, blank lines between groups
+- `no-inferrable-types`: Don't annotate types TS can infer (`const count: number = 0` → `const count = 0`)
+- `prefer-optional-chain`: Use `?.` instead of `&&` chains
+- `prefer-nullish-coalescing`: Use `??` instead of `||` for nullable defaults
+- `consistent-type-definitions`: Prefer `interface` over `type` for object shapes
+- `array-type`: Use `T[]` not `Array<T>`
+
+**React-specific:**
+- `react-hooks/rules-of-hooks`: Hooks only at top level of components/custom hooks
+- `react-hooks/exhaustive-deps`: All reactive values must be in hook dependency arrays
+
+**Console:**
+- `no-console`: warn — but `--max-warnings 0` makes it an error. Only allowed in `**/error.tsx`.
+
+**Test files (`.test.ts`, `.test.tsx`):**
+- `vitest/expect-expect`: Every test must have an assertion
+- `vitest/no-identical-title`: Test titles must be unique
+- `vitest/no-conditional-expect`: No `expect()` inside conditionals
+
+### File-specific exceptions
+- `**/error.tsx`: `no-console` disabled (Next.js error boundaries)
+- `src/shared/lib/supabase/server.ts`, `middleware.ts`: `no-deprecated` disabled (Supabase SSR)

package/template/.opencode/skills/build-feature/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: build-feature
+description: Plan and implement a new feature following TDD — tech-lead planning, backend + frontend in parallel, review gate, and memory sync. Run in a fresh conversation after /discover-feature. Triggers: 'build feature', 'implement feature', 'start building', 'build from requirements'. NOT for: bug fixes, refactors, or API-only routes (use /create-api-route).
+compatibility: opencode
+---
+
+# Build Feature Skill
+
+> **Invoke as:** `/build-feature @.requirements/<feature-name>-<timestamp>.md`
+> Run in a **fresh conversation** (not the same one where you ran `/discover-feature`).
+
+## IMPORTANT: Fresh Conversation Required
+
+If this conversation already contains requirements gathering, **start a new conversation** first. Reusing the same context risks hitting the token limit mid-implementation.
+
+If context usage exceeds 60% at any point, stop and tell the user to continue in a new conversation referencing the current step.
+
+---
+
+## Process
+
+### Step 1 — Read the Requirements
+
+Read `.requirements/<feature-name>-<timestamp>.md`. Confirm the spec exists and has:
+- Acceptance criteria
+- Functional task list
+- Technical task list (with parallel groups)
+
+If no spec exists, tell the user to run `/discover-feature <description>` first.
+
+### Step 2 — Tech Lead: Load Architecture Context via MCP Memory
+
+Load project context with targeted queries (token-efficient):
+
+1. Read `package.json` to get the project name (`<project-name>`)
+2. `search_memory` with `tags: ["project:<project-name>", "domain:ui"]` — installed shadcn/ui components
+3. `search_memory` with `tags: ["project:<project-name>", "domain:database"]` — existing schema
+4. `search_memory` with `tags: ["project:<project-name>", "domain:features"]` — existing features and paths
+5. `search_memory` with `tags: ["project:<project-name>", "domain:patterns"]` — canonical pattern references
+6. `search_memory` with `tags: ["project:<project-name>", "domain:rules"]` — active lint/TS rules
+
+**Fallback**: if memory service is unavailable, read `.opencode/memory/architecture-snapshot.md` directly.
+
+After reading any codebase files, save findings to MCP memory:
+```
+store_memory({
+  content: "<what was learned>",
+  metadata: {
+    type: "architecture",
+    tags: ["project:<project-name>", "domain:<domain>", "category:<category>"]
+  }
+})
+```
+
+**Also read `eslint.config.ts` and `tsconfig.json`** to confirm active rules and compiler flags before writing any code.
+
+**Dependency pre-flight:**
+```bash
+pnpm ls drizzle-orm   # Confirm installed version
+pnpm typecheck        # Confirm baseline passes — fix pre-existing errors first
+```
+
+### Step 3 — Tech Lead: Planning (Get User Approval)
+
+Before any code is written, produce a technical plan and get user approval.
+
+Using the requirements + MCP memory context:
+
+1. **Map technical tasks to agents** (from the requirements file's Technical Task List):
+   - Identify which tasks can run in parallel (Group A + Group B from the plan)
+   - Identify which tasks are sequential (Group C gates)
+
+2. **Plan the test structure upfront**:
+   - List which test files will be created
+   - One `describe` block per acceptance criterion
+   - Which mocks are needed (`makeSupabaseMock`, HTTP mocks, etc.)
+   - Which edge cases map to which criteria
+
+3. **Identify reuse**:
+   - Which canonical patterns to copy (from MCP memory results)
+   - Which shadcn components are already installed vs need installing
+   - Which shared utilities apply (`formFieldText`, `firstZodIssueMessage`, etc.)
+
+4. **Present the plan to the user** and wait for approval before proceeding.
+
+> Present as: what backend will do, what frontend will do, which tests will be written, any risks or decisions needing user input.
+
+### Step 4 — Create Feature Structure
+
+```
+src/features/<feature-name>/
+├── components/
+├── actions/
+├── queries/
+├── hooks/
+├── api/
+├── lib/
+└── __tests__/
+```
+
+### Step 5 — Pre-Test Setup
+
+Update `vitest.config.ts` to exclude files that cannot be meaningfully tested in jsdom:
+- Drizzle schema files (`src/shared/db/*.schema.ts`)
+- Pure type-only files
+- Portal/browser-API-dependent UI wrappers (e.g., `src/shared/components/ui/sonner.tsx`)
+
+### Step 6 — TDD: RED Phase (@test-qa)
+
+Delegate to `@test-qa` to write ALL test files first — zero implementation code at this stage:
+- `__tests__/<component>.test.tsx` — component tests
+- `__tests__/use-<feature>.test.ts` — hook tests (if applicable)
+- `__tests__/<action>.action.test.ts` — action tests
+- `__tests__/<feature>.queries.test.ts` — query tests
+
+Provide `@test-qa` with the full test plan from Step 3 (files, `describe` names, mocks, edge cases).
+
+**BLOCKING GATE — do not proceed until this passes:**
+Run `pnpm test:unit` and paste the output. All new tests must **FAIL** (red). If any new test passes without implementation, the test is wrong — fix it before continuing.
+
+### Step 7 — TDD: GREEN Phase (parallel)
+
+Launch **@backend and @frontend in parallel** — they work on independent files:
+
+| @backend handles | @frontend handles |
+|-----------------|-------------------|
+| `actions/` | `components/` |
+| `queries/` | `page.tsx` |
+| `schema.ts` changes | shadcn component installs |
+| RLS policies | Loading/empty states |
+
+Do NOT serialize these — they touch different files.
+
+After each agent completes, they must save their findings to MCP memory.
+
+**Do NOT run intermediate verification between sub-tasks.** Complete all GREEN phase work, then verify in Step 9.
+
+**BLOCKING GATE — do not proceed until this passes:**
+Run `pnpm test:unit` and paste the output. All tests must **PASS** (green).
+
+### Step 8 — Refactor
+
+Clean up while keeping tests green.
+
+### Step 9 — Verify & Self-Check
+
+Run all three **together** (single pass) and paste output:
+```bash
+pnpm test:coverage   # Must meet thresholds: 95% statements/functions/lines, 90% branches
+pnpm lint            # Must pass with 0 warnings
+pnpm typecheck       # Must pass with 0 errors
+```
+
+If issues are found, fix **all** of them, then run the full trio again once.
+
+Before moving to the review gate, verify manually:
+- [ ] No `any` types: `grep -r ": any" src/features/<feature>/`
+- [ ] No `eslint-disable` comments
+- [ ] All UI text in Spanish, all `it()`/`describe()` text in English
+- [ ] No file over 200 lines
+- [ ] No function over 20 lines
+- [ ] AAA pattern (`// Arrange`, `// Act`, `// Assert`) in every test
+- [ ] `ActionResult` returned from every Server Action mutation
+- [ ] Toast feedback (`toast.success` / `toast.error`) for every mutation
+- [ ] RLS policies written for every new table
+
+### Step 10 — Review Gate (parallel)
+
+Launch **@code-reviewer and @security-researcher in parallel** on the changed files. Fix any findings before marking the feature complete.
+
+This step is not optional. The feature is not done until both reviewers pass.
+
+> **Note for time-critical work:** if the user explicitly says to skip the review gate, flag the skipped step so it can be done as a follow-up.
+
+### Step 11 — Update Architecture Snapshot & MCP Memory
+
+Update `.opencode/memory/architecture-snapshot.md`:
+- Add new DB tables to the schema table
+- Add new shadcn components to the installed list
+- Add the new feature to the Existing Features table
+- Add any new canonical pattern references
+
+Then run `/memory sync` to persist all changes to MCP memory so future sessions load context efficiently.
+
+Mark all functional and technical tasks in `.requirements/<feature-name>-<timestamp>.md` as complete.
+
+---
+
+## Common Issues
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| MCP memory returns no results | Memory not synced yet | Run `/memory sync` first, then retry |
+| Test passes without implementation (RED fails) | Test asserts on falsy/default values | Ensure the test expects a specific truthy result that only a real implementation can produce |
+| `pnpm typecheck` fails on schema file | Schema imported in test without mock | Add the schema file to `coverage.exclude` in `vitest.config.ts` |
+| Context exceeds 60% mid-build | Feature too large for one conversation | Stop, note the current step, start a new conversation referencing it |
+| `lint-staged` blocks commit | ESLint warnings treated as errors | Fix all warnings; never use `eslint-disable` inline |
+
+---
+
+## Guardrails
+- NEVER start implementation before the user approves the plan (Step 3)
+- NEVER start implementation before the RED gate is confirmed with actual test output
+- Coverage threshold: 95% statements/functions/lines, 90% branches
+- Follow `features/* → shared/*` dependency direction
+- RLS is mandatory for every new table — not a post-step
+- All agents must save codebase findings to MCP memory after reading files
+- Write lint-compliant code from the start — read the Strict Rules Reference before the first line of code

package/template/.opencode/skills/create-api-route/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: create-api-route
+description: Create a new Next.js API route with Zod validation, auth check, and TDD tests. Use when adding API endpoints to a feature. Triggers: 'create API route', 'add endpoint', 'new route handler', 'API endpoint'. NOT for: Server Actions (those go in features/*/actions/).
+compatibility: opencode
+---
+
+# Create API Route Skill
+
+## Process
+
+### 1. Define Schema
+```typescript
+const requestSchema = z.object({ /* fields */ });
+const responseSchema = z.object({ /* fields */ });
+type RequestBody = z.infer<typeof requestSchema>;
+```
+
+### 2. Write Test First (TDD)
+```typescript
+describe("POST /api/my-route", () => {
+  it("returns 400 on invalid input", async () => { ... });
+  it("returns 401 when unauthenticated", async () => { ... });
+  it("returns 200 with valid input", async () => { ... });
+});
+```
+
+Run test — must FAIL (RED).
+
+### 3. Implement Route
+```typescript
+// Determine runtime:
+// - AI routes: export const runtime = "edge"
+// - DB routes: no export (Node.js default)
+
+export async function POST(request: Request) {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return Response.json({ error: "Unauthorized" }, { status: 401 });
+
+  const body = await request.json() as unknown;
+  const parsed = requestSchema.safeParse(body);
+  if (!parsed.success) return Response.json({ error: "Invalid input" }, { status: 400 });
+
+  // business logic...
+
+  return Response.json(result);
+}
+```
+
+### 4. Verify
+```bash
+pnpm test:unit
+pnpm lint
+pnpm typecheck
+```
+
+## Checklist
+- [ ] Zod schema for request/response
+- [ ] Auth check (unless public endpoint)
+- [ ] Input validation
+- [ ] Correct runtime (`edge` for AI, `nodejs` default for DB)
+- [ ] Tests written BEFORE implementation
+- [ ] ≥95% statement/function/line coverage, ≥90% branch coverage