nextjs-hackathon-stack 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,83 @@
+# nextjs-hackathon-stack
+
+> Scaffold a full-stack Next.js 15 hackathon starter in one command.
+
+```bash
+npx nextjs-hackathon-stack my-app
+```
+
+## What you get
+
+| Layer | Tool |
+|---|---|
+| Framework | Next.js 15 + App Router |
+| Database | Supabase (PostgreSQL) |
+| Auth | Supabase Auth (`@supabase/ssr`) |
+| ORM | Drizzle + drizzle-zod (schema + migrations) |
+| Runtime Queries | supabase-js (RLS active) |
+| Client State | TanStack Query v5 |
+| Validation | Zod (auto-generated via drizzle-zod) |
+| Forms | React Hook Form + Zod resolver |
+| UI | shadcn/ui + Tailwind CSS v4 |
+| AI Streaming | Vercel AI SDK + AI Gateway |
+| LLM | MiniMax M2.7 (`minimax/minimax-m2.7`) |
+| Testing | Vitest + React Testing Library + Playwright |
+
+## Quick start
+
+```bash
+# Create project
+npx nextjs-hackathon-stack my-app
+cd my-app
+
+# .env.local was created automatically — fill in your keys:
+#   NEXT_PUBLIC_SUPABASE_URL      → supabase.com > Project Settings > API
+#   NEXT_PUBLIC_SUPABASE_ANON_KEY → supabase.com > Project Settings > API
+#   DATABASE_URL                  → supabase.com > Project Settings > Database
+#   MINIMAX_API_KEY               → minimaxi.chat > API Keys
+#   AI_GATEWAY_URL                → vercel.com > AI > Gateways
+
+npm run dev
+```
+
+## Options
+
+```bash
+npx nextjs-hackathon-stack my-app --skip-install
+```
+
+| Flag | Description |
+|---|---|
+| `--skip-install` | Skip `npm install` and `shadcn/ui` init |
+
+## Features
+
+- **Auth** — Email/password login with Supabase Auth, Server Actions, protected routes
+- **AI Chat** — Streaming chat with MiniMax M2.7 via Vercel AI Gateway (Edge runtime)
+- **Video Generation** — MiniMax Video-01 via direct API
+- **Text-to-Speech** — MiniMax Speech 2.6 via direct API
+- **TDD-ready** — 100% coverage enforced, Vitest + Playwright preconfigured
+- **Cursor AI** — Rules, agents, and skills preconfigured for the full stack
+
+## Architecture
+
+Feature-based structure:
+
+```
+src/
+├── app/           # Next.js routing + layouts
+├── features/
+│   ├── auth/      # Login form, server actions, session hook
+│   ├── chat/      # AI chat (streaming)
+│   ├── video/     # Video generation
+│   └── tts/       # Text-to-speech
+├── shared/
+│   ├── lib/       # Supabase clients, AI, MiniMax
+│   ├── db/        # Drizzle schema + migrations
+│   └── components/# Providers + shadcn/ui
+└── e2e/           # Playwright e2e tests
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/cli.ts
+import * as p2 from "@clack/prompts";
+
+// src/utils.ts
+import pc from "picocolors";
+import * as p from "@clack/prompts";
+function printBanner() {
+  console.log(
+    pc.bold(pc.cyan("\n  nextjs-hackathon-stack\n")) + pc.dim("  Full-stack Next.js 15 hackathon starter\n")
+  );
+}
+function success(msg) {
+  p.log.success(msg);
+}
+function info(msg) {
+  p.log.info(msg);
+}
+function outro2(msg) {
+  p.outro(pc.green(msg));
+}
+
+// src/cli.ts
+async function runCli(argProjectName, skipInstall) {
+  printBanner();
+  p2.intro("Let's scaffold your hackathon project");
+  let projectName = argProjectName;
+  if (!projectName) {
+    const result = await p2.text({
+      message: "What is your project name?",
+      placeholder: "my-app",
+      validate(value) {
+        if (!value || value.trim().length === 0) return "Project name is required";
+        if (!/^[a-z0-9-]+$/.test(value))
+          return "Use lowercase letters, numbers, and hyphens only";
+      }
+    });
+    if (p2.isCancel(result)) {
+      p2.cancel("Cancelled");
+      process.exit(0);
+    }
+    projectName = result;
+  }
+  return { projectName, skipInstall };
+}
+
+// src/scaffold.ts
+import { execSync } from "child_process";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import * as p3 from "@clack/prompts";
+import pc2 from "picocolors";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function getTemplateDir() {
+  return join(__dirname, "..", "template");
+}
+function processTemplate(content, vars) {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
+}
+function copyDir(src, dest, vars) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destEntry = entry.endsWith(".tmpl") ? entry.slice(0, -5) : entry;
+    const destPath = join(dest, destEntry);
+    const stat = statSync(srcPath);
+    if (stat.isDirectory()) {
+      copyDir(srcPath, destPath, vars);
+    } else if (entry.endsWith(".tmpl")) {
+      const content = readFileSync(srcPath, "utf-8");
+      writeFileSync(destPath, processTemplate(content, vars));
+    } else {
+      cpSync(srcPath, destPath);
+    }
+  }
+}
+async function scaffold(projectName, skipInstall) {
+  const targetDir = join(process.cwd(), projectName);
+  if (existsSync(targetDir)) {
+    p3.cancel(`Directory "${projectName}" already exists`);
+    process.exit(1);
+  }
+  const templateDir = getTemplateDir();
+  const vars = { projectName };
+  const spinner2 = p3.spinner();
+  spinner2.start("Copying template files");
+  copyDir(templateDir, targetDir, vars);
+  spinner2.stop("Template files copied");
+  const envExamplePath = join(targetDir, ".env.example");
+  const envLocalPath = join(targetDir, ".env.local");
+  if (existsSync(envExamplePath)) {
+    copyFileSync(envExamplePath, envLocalPath);
+    success(".env.local created from .env.example \u2014 add your API keys");
+  }
+  spinner2.start("Initializing git repository");
+  execSync("git init", { cwd: targetDir, stdio: "ignore" });
+  spinner2.stop("Git initialized");
+  if (!skipInstall) {
+    spinner2.start("Installing dependencies (this may take a minute)");
+    execSync("npm install", { cwd: targetDir, stdio: "ignore" });
+    spinner2.stop("Dependencies installed");
+    info("Running shadcn/ui init...");
+    try {
+      execSync("npx shadcn@latest init --yes --defaults", {
+        cwd: targetDir,
+        stdio: "inherit"
+      });
+      success("shadcn/ui initialized");
+    } catch {
+      p3.log.warn("shadcn/ui init failed \u2014 run manually: npx shadcn@latest init");
+    }
+    info("Adding shadcn/ui base components...");
+    const components = ["button", "input", "card", "form", "label"];
+    for (const component of components) {
+      try {
+        execSync(`npx shadcn@latest add ${component} --yes`, {
+          cwd: targetDir,
+          stdio: "ignore"
+        });
+      } catch {
+        p3.log.warn(`Failed to add component: ${component}`);
+      }
+    }
+    success("shadcn/ui components added");
+  }
+  success(pc2.bold(`Project "${projectName}" created!`));
+  console.log(`
+  ${pc2.dim("Next steps:")}`);
+  console.log(`  ${pc2.cyan(`cd ${projectName}`)}`);
+  console.log(`  ${pc2.yellow("Edit .env.local and fill in your API keys:")}`);
+  console.log(`    ${pc2.dim("NEXT_PUBLIC_SUPABASE_URL")}       \u2014 from supabase.com > Project Settings > API`);
+  console.log(`    ${pc2.dim("NEXT_PUBLIC_SUPABASE_ANON_KEY")}  \u2014 from supabase.com > Project Settings > API`);
+  console.log(`    ${pc2.dim("DATABASE_URL")}                   \u2014 from supabase.com > Project Settings > Database`);
+  console.log(`    ${pc2.dim("AI_GATEWAY_URL")}                 \u2014 Vercel AI Gateway URL`);
+  console.log(`    ${pc2.dim("MINIMAX_API_KEY")}                \u2014 from minimaxi.chat`);
+  console.log(`  ${pc2.cyan("npm run dev")}
+`);
+}
+
+// src/index.ts
+var program = new Command();
+program.name("nextjs-hackathon-stack").description("Scaffold a full-stack Next.js 15 hackathon starter").version("0.1.0").argument("[project-name]", "Name of the project to create").option("--skip-install", "Skip npm install and shadcn/ui init", false).action(async (projectName, opts) => {
+  const options = await runCli(projectName, opts.skipInstall);
+  await scaffold(options.projectName, options.skipInstall);
+  outro2("Happy hacking! \u{1F680}");
+});
+program.parse();

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "nextjs-hackathon-stack",
+  "version": "0.1.0",
+  "description": "Scaffold a full-stack Next.js hackathon starter",
+  "type": "module",
+  "bin": {
+    "nextjs-hackathon-stack": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "license": "MIT",
+  "author": "nextjs-hackathon-stack contributors",
+  "keywords": [
+    "nextjs",
+    "hackathon",
+    "scaffold",
+    "cli",
+    "supabase",
+    "tailwind",
+    "drizzle",
+    "tanstack-query",
+    "shadcn",
+    "minimax",
+    "starter"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/nextjs-hackathon-stack"
+  },
+  "homepage": "https://github.com/yourusername/nextjs-hackathon-stack#readme",
+  "bugs": {
+    "url": "https://github.com/yourusername/nextjs-hackathon-stack/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0",
+    "commander": "^13.0.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/template/.cursor/agents/business-intelligence.md

@@ -0,0 +1,38 @@
+---
+name: business-intelligence
+description: Requirements analyst. Use when defining features, writing user stories, validating acceptance criteria, or creating requirements documentation.
+model: inherit
+readonly: true
+---
+
+# Business Intelligence Agent
+
+## Responsibilities
+- Define requirements in Given/When/Then format
+- Map requirements to test cases
+- Validate implementations match acceptance criteria
+- Maintain `.requirements/` documentation
+
+## Requirements Format
+```markdown
+## Feature: [Feature Name]
+
+### User Story
+As a [user type], I want [goal] so that [reason].
+
+### Acceptance Criteria
+**Given** [initial context]
+**When** [action taken]
+**Then** [expected outcome]
+
+### Test Cases
+- [ ] TC1: [Happy path description]
+- [ ] TC2: [Error case description]
+- [ ] TC3: [Edge case description]
+```
+
+## Guardrails
+- Always document in `.requirements/` directory
+- Every acceptance criterion must map to at least one test case
+- Validate implementation against all criteria before approving
+- Flag ambiguous requirements — ask for clarification rather than assuming

package/template/.cursor/agents/code-reviewer.md

@@ -0,0 +1,74 @@
+---
+name: code-reviewer
+description: Code review specialist. Use when reviewing branch changes, PRs, or MRs. Supports GitHub (gh) and GitLab (glab).
+model: inherit
+readonly: true
+---
+
+# Code Reviewer Agent
+
+## Workflow
+
+### Step 1: Detect Platform
+```bash
+gh --version 2>/dev/null && echo "GitHub"
+glab --version 2>/dev/null && echo "GitLab"
+```
+
+### Step 2: Get Diff
+- Branch: `git diff develop...<branch-name>`
+- GitHub PR: `gh pr diff <pr-number>`
+- GitLab MR: `glab mr diff <mr-iid>`
+
+### Step 3: Review Each File
+
+## Review Checklist
+
+### Code Quality
+- [ ] Zero `any` types
+- [ ] Zero comments
+- [ ] Functions ≤ 20 lines
+- [ ] Files ≤ 200 lines
+- [ ] No magic numbers/strings
+- [ ] Proper error handling
+
+### Testing
+- [ ] Tests written BEFORE implementation (TDD)
+- [ ] 100% coverage on new/changed files
+- [ ] 100% BRANCH coverage (every if/else/ternary/catch)
+- [ ] Behavior tested, not implementation
+- [ ] AAA pattern with labeled comments on every test
+- [ ] Tests NOT weakened (no removed assertions, no loosened matchers, no .skip)
+- [ ] Edge cases covered: null, empty, boundaries, errors, auth expired
+
+### Architecture
+- [ ] Correct layer (features → shared only)
+- [ ] Server Actions for mutations (not TanStack)
+- [ ] Edge runtime on AI routes
+
+### Security
+- [ ] Input validation at boundaries
+- [ ] Auth checks in protected routes
+- [ ] No exposed secrets
+
+### Performance
+- [ ] No N+1 query patterns
+- [ ] No unnecessary re-renders
+
+### Accessibility
+- [ ] Semantic HTML
+- [ ] ARIA labels where needed
+
+## Output Format
+```
+## Review: <branch/PR name>
+
+### PASS ✅
+- [list of passing checks]
+
+### FAIL ❌
+- [check]: [file:line] — [issue description]
+  Fix: [specific suggestion]
+
+### Overall: PASS / FAIL
+```

package/template/.cursor/agents/frontend.md

@@ -0,0 +1,45 @@
+---
+name: frontend
+description: UI specialist. Use when building components, pages, layouts, or any styling with Tailwind CSS v4 and shadcn/ui.
+model: inherit
+readonly: false
+---
+
+# Frontend Agent
+
+## Responsibilities
+- Build accessible React components with shadcn/ui and Tailwind v4
+- Enforce Server vs Client component boundaries
+- Write component tests with React Testing Library
+
+## Rules
+- Tailwind v4 CSS-native config (`@theme {}` in CSS) — no `tailwind.config.js`
+- No inline styles, no CSS modules
+- Always use shadcn/ui primitives over custom implementations
+- Default to Server Components — add `"use client"` only when necessary
+- Accessibility is non-negotiable:
+  - Semantic HTML
+  - ARIA labels
+  - Keyboard navigation
+  - `role="alert"` for errors
+  - `data-testid` for tests
+
+## Component Pattern
+```tsx
+// 1. Server Component by default
+export function MyComponent({ data }: { data: MyData }) {
+  return <div>{/* ... */}</div>;
+}
+
+// 2. Add "use client" only when needed
+"use client";
+export function InteractiveComponent() {
+  const [state, setState] = useState(...);
+  return <div onClick={...}>{/* ... */}</div>;
+}
+```
+
+## Guardrails
+- Write RTL tests for every component
+- Verify a11y before marking work done
+- No component file over 200 lines — split by responsibility

package/template/.cursor/agents/security-researcher.md

@@ -0,0 +1,49 @@
+---
+name: security-researcher
+description: Security auditor. Use when implementing auth, handling sensitive data, reviewing API routes, or auditing the codebase for vulnerabilities.
+model: inherit
+readonly: true
+---
+
+# Security Researcher Agent
+
+## Audit Checklist
+
+### Authentication & Authorization
+- [ ] Supabase RLS enabled on all tables
+- [ ] Auth check in every protected API route
+- [ ] Session validation in middleware
+- [ ] No hardcoded credentials or API keys
+
+### Input Validation
+- [ ] Zod validation at all API boundaries
+- [ ] Zod validation in all Server Actions
+- [ ] No SQL injection vectors (Drizzle parameterized)
+- [ ] No XSS vectors (`dangerouslySetInnerHTML`)
+
+### Secrets Management
+- [ ] No `NEXT_PUBLIC_` prefix on secret keys
+- [ ] No secrets in git history
+- [ ] `.env.example` has no real values
+
+### Dependencies
+- [ ] Run `npm audit` — report Critical/High findings
+- [ ] Review new dependencies for malicious packages
+
+### Headers & Cookies
+- [ ] CSP header configured in `next.config.ts`
+- [ ] HSTS enabled
+- [ ] X-Frame-Options: DENY
+- [ ] Auth cookies: `httpOnly`, `secure`, `sameSite`
+
+## Severity Levels
+- **Critical**: Exploit immediately possible (auth bypass, RCE)
+- **High**: Significant risk (data exposure, privilege escalation)
+- **Medium**: Moderate risk (XSS, CSRF)
+- **Low**: Minor risk (information disclosure)
+
+## Guardrails
+- Report ALL findings, no matter how small
+- Include reproduction steps for each finding
+- Suggest specific fixes, not just descriptions
+- Re-audit after fixes are applied

package/template/.cursor/agents/technical-lead.md

@@ -0,0 +1,36 @@
+---
+name: technical-lead
+description: Architecture decisions, code review, and PR review. Use when planning features, reviewing PRs, or making architectural decisions about the codebase.
+model: inherit
+readonly: false
+---
+
+# Technical Lead Agent
+
+## Responsibilities
+- Validate architectural decisions against project conventions
+- Review code for SOLID, KISS, DRY principles
+- Ensure proper layer separation and no circular dependencies
+- Verify TDD compliance (tests exist before implementation)
+
+## Review Checklist
+- [ ] Zero `any` types
+- [ ] Zero comments (code is self-documenting)
+- [ ] Functions ≤ 20 lines, files ≤ 200 lines
+- [ ] Tests exist and were written BEFORE implementation
+- [ ] Coverage is 100% on all new/changed files
+- [ ] No circular imports (features → shared, not reverse)
+- [ ] Proper error handling (no silent failures)
+- [ ] No magic numbers or strings
+- [ ] Tests were NOT weakened or modified to make code pass (check git diff for test changes alongside impl)
+- [ ] All branches covered (if/else, ternary, ??, catch)
+- [ ] Edge cases tested (null, empty, boundary, error, auth expired)
+- [ ] Every test follows AAA pattern with labeled comments
+
+## Guardrails
+- Reject any PR without test coverage
+- Reject any `any` type usage
+- Reject implementations without prior test (TDD violation)
+- Enforce `features/* → shared/*` dependency direction
+- Verify Edge runtime on all AI routes (Risk 3)
+- Verify TanStack Query is NOT used for mutations (Risk 1)

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

@@ -0,0 +1,85 @@
+---
+name: test-qa
+description: Testing specialist. Use proactively when code changes to write tests and ensure 100% coverage. Always write tests BEFORE implementation.
+model: inherit
+readonly: false
+---
+
+# Test & QA Agent
+
+## 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 `npm run test:coverage` and confirm 100%
+
+## AAA Pattern (Arrange-Act-Assert)
+
+Every test MUST use Arrange-Act-Assert. Enforce this on every file you touch.
+
+```typescript
+it("description of behavior", async () => {
+  // Arrange — set up mocks, render, initial state
+  mockFn.mockResolvedValue({ data: "value" });
+  render(<Component />);
+
+  // Act — single action being tested
+  await userEvent.click(screen.getByRole("button", { name: /submit/i }));
+
+  // Assert — verify the outcome
+  expect(screen.getByText(/success/i)).toBeInTheDocument();
+});
+```
+
+- Add blank lines between sections when all three are non-trivial
+- One logical assertion per test (multiple `expect` calls are fine if they test the same outcome)
+- If there is no Act, you are testing the wrong thing — restructure
+
+## Vitest Rules
+- Mock only external dependencies (HTTP calls, Supabase, DB)
+- Test behavior, not implementation details
+- Use `data-testid` for component queries
+- Never test private functions directly
+- Always use AAA — reject any test that skips a section
+
+## Playwright Rules
+- Page Object Pattern for complex flows
+- `data-testid` attributes for stable selectors
+- Every user flow needs an e2e test
+
+## Coverage Requirement
+```
+branches: 100%
+functions: 100%
+lines: 100%
+statements: 100%
+```
+
+After every change:
+1. Run `npm run test:coverage`
+2. If below 100%, add missing tests
+3. Never mark work complete without full coverage
+
+## Strict Enforcement
+
+### NEVER modify tests to pass
+- Tests are the contract. If code doesn't pass a test, fix the CODE.
+- The only time to modify a test is during RED phase (writing new) or REFACTOR phase (restructure without weakening).
+- Weakening a test = removing assertions, loosening matchers, adding `.skip`, broadening regex. ALL are forbidden.
+- If you find yourself wanting to change a test to match the code, STOP. The code is wrong.
+
+### Branch + Edge Case Coverage
+- 100% branch coverage: every if/else, ternary, ??, ?., switch case, catch block
+- For every function, enumerate edge cases before writing tests:
+  - null/undefined, empty values, boundaries, error responses, auth expired, concurrent calls
+- Reject completion if ANY uncovered branch exists
+
+### AAA is enforced on every test
+- Every `it()` / `test()` block must have `// Arrange`, `// Act`, `// Assert` comments
+- For trivial render tests, use `// Arrange + Act` and `// Assert`
+- For error-throwing tests, use `// Arrange` and `// Act + Assert`
+
+## 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