nextjs-hackathon-stack 0.1.38 → 0.1.40

package/dist/index.js

@@ -308,6 +308,16 @@ async function scaffold(projectName, skipInstall, skipMcp = false, template = "e
         spinner2.stop(`Failed to add component: ${component}`);
       }
     }
+    spinner2.start("Installing shadcn/ui skill");
+    try {
+      execSync("pnpm dlx skills add shadcn/ui", {
+        cwd: targetDir,
+        stdio: "pipe"
+      });
+      spinner2.stop("shadcn/ui skill installed");
+    } catch {
+      spinner2.stop("shadcn/ui skill install failed \u2014 run manually: pnpm dlx skills add shadcn/ui");
+    }
   }
   spinner2.start("Creating initial commit");
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextjs-hackathon-stack",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "Scaffold a full-stack Next.js hackathon starter",
   "type": "module",
   "bin": {

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

@@ -23,9 +23,19 @@ readonly: false
 Follow `components.mdc` for shadcn/ui, Tailwind v4, and accessibility standards.
 
 ## Component Discovery
-- Before building UI, check if a shadcn/ui component exists: `shadcn search <query>` or `shadcn docs <component>`
-- Install missing components with `shadcn add <component>` — never manually create files in `@/shared/components/ui/`
-- The shadcn skill (`npx skills add shadcn/ui`) provides project context automatically via `components.json`
+
+This project has the **shadcn MCP server** configured. Prefer MCP tools over CLI:
+
+| Task | MCP tool | CLI fallback |
+|------|----------|--------------|
+| Search for a component | `shadcn_search <query>` | `shadcn search <query>` |
+| Read component docs | `shadcn_docs <component>` | `shadcn docs <component>` |
+| Install a component | `shadcn_install <component>` | `shadcn add <component>` |
+| Check for upstream changes | `shadcn_diff <component>` | `shadcn diff <component>` |
+
+**Workflow**: Before building any UI, use `shadcn_search` or `shadcn_docs` to check if a component already exists. Install missing components via MCP or CLI — never manually create files in `@/shared/components/ui/`.
+
+The shadcn skill (`pnpm dlx skills add shadcn/ui`) is installed during scaffolding and provides project context automatically via `components.json`.
 
 ## Component Pattern
 ```tsx
@@ -64,6 +74,12 @@ All user-initiated actions that modify the database must show a toast (success o
 - For `useActionState` forms: use a `useEffect` on state changes to trigger toasts
 - Exception: if the action redirects to another page, no success toast is needed
 
+## Debugging with next-browser
+
+`@vercel/next-browser` — terminal access to a running Next.js app for PPR analysis, component tree inspection, network monitoring, and screenshots.
+
+Install: `npx skills add vercel-labs/next-browser`
+
 ## Guardrails
 - Write RTL tests for every component
 - Verify a11y before marking work done

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

@@ -2,11 +2,11 @@
 name: technical-lead
 description: Orchestrator and architecture owner. Default entry point for all requests — breaks down tasks, delegates to specialists, and validates architecture. Triggers: new feature planning, architecture questions, task breakdown, multi-agent coordination, refactor planning.
 model: inherit
-# Note: `model: inherit` means this agent uses whatever model the user selected.
-# For security-critical reviews, consider switching to a more capable model explicitly.
 readonly: false
 ---
 
+<!-- model: inherit means this agent uses whatever model the user selected. For security-critical reviews, consider switching to a more capable model explicitly. -->
+
 # Technical Lead Agent
 
 ## First Step — Load Context via MCP Memory
@@ -87,12 +87,6 @@ Review against project rules (`coding-standards.mdc`, `architecture.mdc`, `data-
 - [ ] TanStack Query is NOT used for mutations (Risk 1)
 - [ ] Every DB mutation shows toast feedback to the user (success or error via `sonner`)
 
-## Debugging with next-browser
-
-`@vercel/next-browser` — terminal access to a running Next.js app for PPR analysis, component tree inspection, network monitoring, and screenshots.
-
-Install: `npx skills add vercel-labs/next-browser`
-
 ## Guardrails
 - Reject any PR without test coverage
 - Reject any `any` type usage

package/template/.cursor/mcp.json

@@ -3,6 +3,10 @@
     "memory": {
       "command": "memory",
       "args": ["server"]
+    },
+    "shadcn": {
+      "command": "npx",
+      "args": ["shadcn@latest", "mcp"]
     }
   }
 }

package/template/.cursor/rules/coding-standards.mdc

@@ -10,10 +10,29 @@ globs: ["src/**/*.ts", "src/**/*.tsx"]
 - **Zero `any`** — use `unknown` + type guards or proper generics. `@typescript-eslint/no-explicit-any: error`
 - **Zero comments in production code** — code must be self-documenting through naming. Test AAA labels (`// Arrange`, `// Act`, `// Assert`) are required in tests.
 - **Zero magic numbers/strings** — use typed constants
-- **No `console.log`** in production code — `no-console: warn`
+- **No `console.log`** in production code — `no-console: "error"`
 - **No `!` non-null assertions** — use proper null checks
 - **No `eslint-disable` inline comments** — fix the code instead. If a rule conflict is truly unavoidable (e.g. third-party API with no non-deprecated alternative), add a file-level override in `eslint.config.ts` with a `// TODO` comment explaining why.
 
+## AI Agent Lint Pre-Flight
+
+Before writing any code, internalize these rules. The project runs `eslint --max-warnings 0` — any violation blocks commits. These are the patterns that most commonly trip AI code generation:
+
+- **`no-console: "error"`** — never use `console.*` in production code. Use proper error handling (`throw`) or `ActionResult` error returns.
+- **`strict-boolean-expressions`** — never write `if (value)` for non-boolean types. Use explicit checks:
+  - `string`: `if (str !== "")`
+  - `number`: `if (n !== 0)`
+  - `T | null | undefined`: `if (value !== null && value !== undefined)`
+  - `T[]`: `if (array.length > 0)`
+  - JSX: `{condition !== null && condition !== undefined && <Component />}`
+- **`naming-convention`** — `camelCase` for variables/functions, `PascalCase` for types/interfaces/React components, `UPPER_CASE` allowed for constants. Never use `snake_case` except in `property` selectors (DB columns, JSON keys).
+- **`no-floating-promises`** — always `await` or prefix with `void` for fire-and-forget.
+- **`restrict-template-expressions`** — never interpolate non-string/number values directly: `` `${someObject}` `` → `` `${someObject.toString()}` ``.
+- **`no-unnecessary-condition`** — never check conditions that the type system proves always truthy/falsy.
+- **`no-unsafe-*`** — never pass `any`-typed values to typed parameters. Narrow with Zod or type guards first.
+
+> **Rule of thumb**: If unsure whether a pattern is valid, read `eslint.config.ts` before writing.
+
 ## TDD
 
 Follow the RED → GREEN → REFACTOR cycle. See `testing.mdc` for the full rules and iron rules. Summary: never write implementation without a prior failing test.

package/template/.cursor/rules/components.mdc

@@ -1,6 +1,7 @@
 ---
 description: shadcn/ui and Tailwind v4 component standards.
 globs: ["src/**/components/**"]
+alwaysApply: false
 ---
 
 # Component Standards
@@ -11,12 +12,13 @@ globs: ["src/**/components/**"]
 - Extend with `className` prop via `cn()` utility
 - New York style, CSS variables for theming
 
-## shadcn CLI
-- Install the shadcn skill for AI-aware context: `npx skills add shadcn/ui`
-- Before writing component code, run `shadcn docs <component>` to get up-to-date API and usage patterns
-- Use `shadcn search <query>` to discover available components
-- Install components with `shadcn add <component>` — never copy-paste component source manually
-- Use `shadcn diff` to check for upstream changes to already-installed components
+## shadcn/ui (MCP + CLI)
+- **MCP tools** (preferred): `shadcn_search`, `shadcn_docs`, `shadcn_install`, `shadcn_diff`
+- Before writing component code, use `shadcn_docs <component>` to get up-to-date API and usage patterns
+- Use `shadcn_search <query>` to discover available components
+- Install components with `shadcn_install` or `shadcn add <component>` — never copy-paste component source manually
+- Use `shadcn_diff <component>` to check for upstream changes to already-installed components
+- The shadcn skill (`pnpm dlx skills add shadcn/ui`) is installed during scaffolding — provides project context automatically
 
 ## Tailwind v4
 - CSS-native config via `@theme {}` in CSS

package/template/.cursor/rules/data-fetching.mdc

@@ -1,6 +1,7 @@
 ---
-description: TanStack Query vs RSC data fetching boundaries. RISK 1. Applied when working on components, pages, queries, hooks, or actions.
+description: TanStack Query vs RSC data fetching boundaries. Applied when working on components, pages, queries, hooks, or actions.
 globs: ["src/**/components/**", "src/**/queries/**", "src/**/hooks/**", "src/**/actions/**", "src/app/**"]
+alwaysApply: false
 ---
 
 # Data Fetching Rules (Risk 1: TanStack Query + RSC Boundary)

package/template/.cursor/rules/forms.mdc

@@ -1,6 +1,7 @@
 ---
-description: React Hook Form + Server Actions pattern. RISK 4.
-globs: ["**/*form*", "**/*.action.ts"]
+description: React Hook Form + Server Actions pattern. Client-side validation via zodResolver + server-side revalidation in the action.
+globs: ["src/**/*form*", "src/**/*.action.ts"]
+alwaysApply: false
 ---
 
 # Forms Pattern (Risk 4: RHF + Server Actions)

package/template/.cursor/rules/migrations.mdc

@@ -1,6 +1,7 @@
 ---
 description: Migration files are auto-generated by Drizzle CLI. NEVER create, edit, or delete them directly.
 globs: ["src/shared/db/migrations/**"]
+alwaysApply: false
 ---
 
 # Migration Files — Generated Artifacts

package/template/.cursor/rules/nextjs.mdc

@@ -1,6 +1,7 @@
 ---
 description: Next.js 16.2 App Router patterns.
 globs: ["src/app/**"]
+alwaysApply: false
 ---
 
 # Next.js 16.2 Rules

package/template/.cursor/rules/security.mdc

@@ -1,6 +1,7 @@
 ---
 description: Security rules (OWASP, auth, RLS, XSS, CSP). Applied to server code, API routes, actions, auth, and config.
 globs: ["src/**/actions/**", "src/**/api/**", "src/**/lib/supabase/**", "src/app/**/route.ts", "src/app/**/proxy.ts", "*.config.*"]
+alwaysApply: false
 ---
 
 # Security Rules

package/template/.cursor/rules/supabase.mdc

@@ -1,6 +1,7 @@
 ---
-description: Supabase + Drizzle rules. RISK 2 (schema drift).
+description: Supabase + Drizzle rules. Schema changes require migration — never edit migration files directly.
 globs: ["src/shared/db/**", "src/shared/lib/supabase/**"]
+alwaysApply: false
 ---
 
 # Supabase + Drizzle Rules (Risk 2: Zod Schema Drift)

package/template/.cursor/rules/testing.mdc

@@ -1,6 +1,7 @@
 ---
 description: TDD, Vitest, and Playwright testing standards.
 globs: ["**/*.test.*", "**/e2e/**"]
+alwaysApply: false
 ---
 
 # Testing Standards
@@ -49,7 +50,7 @@ Rules:
 - Mock external dependencies only (HTTP calls, Supabase, DB)
 - Test behavior, not implementation details
 - Colocate tests with source: `features/auth/__tests__/`
-- 100% coverage is non-negotiable
+- Coverage thresholds are non-negotiable (95% statements/functions/lines, 90% branches — see Iron Rule #3)
 
 ```typescript
 // ✅ AAA — tests behavior

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

@@ -59,4 +59,4 @@ pnpm typecheck
 - [ ] Input validation
 - [ ] Correct runtime (`edge` for AI, `nodejs` default for DB)
 - [ ] Tests written BEFORE implementation
-- [ ] 100% coverage
+- [ ] ≥95% statement/function/line coverage, ≥90% branch coverage

package/template/.cursor/skills/review-branch/SKILL.md

@@ -20,6 +20,8 @@ git diff develop...<branch-name>
 ### 2. Check Each Changed File
 Apply the full checklist from `references/review-checklist.md` — covers code quality, tests, architecture, security, performance, and accessibility.
 
+**You MUST check every changed file individually. Do not summarize or skip files. Show your analysis for each file before moving to the next.**
+
 ### 3. Generate Report
 ```
 ## Branch Review: <branch-name>

package/template/.cursor/skills/review-branch/references/review-checklist.md

@@ -10,8 +10,8 @@
 
 ## Tests
 - Tests written BEFORE implementation (TDD)
-- 100% coverage on new/changed files
-- 100% BRANCH coverage (every if/else/ternary/catch)
+- ≥95% statement/function/line coverage on new/changed files
+- ≥90% 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)

package/template/.cursor/skills/security-audit/SKILL.md

@@ -8,6 +8,8 @@ disable-model-invocation: true
 
 ## Process
 
+**You MUST execute every step below. Do not skip or summarize steps. Show your findings for each step before moving to the next.**
+
 Execute all 7 audit steps from `references/audit-steps.md`:
 1. Dependency audit (`pnpm audit`)
 2. Secret scan (hardcoded keys)

package/template/eslint.config.ts

@@ -29,7 +29,31 @@ export default tseslint.config(
       "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
       "@typescript-eslint/consistent-type-imports": "error",
       "@typescript-eslint/no-non-null-assertion": "error",
-      "no-console": "warn",
+      "no-console": "error",
+      "@typescript-eslint/strict-boolean-expressions": [
+        "error",
+        {
+          allowString: false,
+          allowNumber: false,
+          allowNullableObject: false,
+          allowNullableBoolean: false,
+          allowNullableString: false,
+          allowNullableNumber: false,
+          allowNullableEnum: false,
+          allowAny: false,
+        },
+      ],
+      "@typescript-eslint/naming-convention": [
+        "error",
+        { selector: "default", format: ["camelCase"], leadingUnderscore: "allow" },
+        { selector: "variable", format: ["camelCase", "UPPER_CASE", "PascalCase"], leadingUnderscore: "allow" },
+        { selector: "function", format: ["camelCase", "PascalCase"] },
+        { selector: "typeLike", format: ["PascalCase"] },
+        { selector: "enumMember", format: ["PascalCase"] },
+        { selector: "import", format: null },
+        { selector: "property", format: null },
+        { selector: "parameter", format: ["camelCase"], leadingUnderscore: "allow" },
+      ],
       "react/react-in-jsx-scope": "off",
       "react-hooks/rules-of-hooks": "error",
       "react-hooks/exhaustive-deps": "error",
@@ -51,6 +75,8 @@ export default tseslint.config(
     plugins: { vitest: vitestPlugin },
     rules: {
       ...vitestPlugin.configs.recommended.rules,
+      "@typescript-eslint/strict-boolean-expressions": "off",
+      "@typescript-eslint/naming-convention": "off",
     },
   },
   {
@@ -58,6 +84,8 @@ export default tseslint.config(
     plugins: { playwright: playwrightPlugin },
     rules: {
       ...playwrightPlugin.configs["flat/recommended"].rules,
+      "@typescript-eslint/strict-boolean-expressions": "off",
+      "@typescript-eslint/naming-convention": "off",
     },
   },
   {