create-tigra 2.5.0 → 2.6.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/create-tigra.js +5 -2
- package/package.json +1 -1
- package/template/_claude/commands/create-client.md +1 -1
- package/template/_claude/rules/client/01-project-structure.md +8 -0
- package/template/_claude/rules/client/04-design-system.md +162 -45
- package/template/_claude/rules/client/core.md +8 -6
- package/template/_claude/rules/global/completion-reports.md +178 -0
- package/template/_claude/rules/global/core.md +6 -0
- package/template/client/.env.example.production +5 -0
- package/template/client/README.md +1 -1
- package/template/client/src/app/error.tsx +1 -1
- package/template/client/src/app/globals.css +33 -85
- package/template/client/src/app/layout.tsx +6 -6
- package/template/client/src/app/page.tsx +10 -3
- package/template/client/src/components/common/ThemeSwitcher.tsx +112 -0
- package/template/client/src/components/layout/Header.tsx +1 -1
- package/template/client/src/features/auth/components/AuthInitializer.tsx +1 -1
- package/template/client/src/features/auth/components/LoginForm.tsx +1 -1
- package/template/client/src/features/auth/components/RegisterForm.tsx +1 -1
- package/template/client/src/features/auth/services/auth.service.ts +0 -4
- package/template/client/src/lib/constants/api-endpoints.ts +0 -2
- package/template/client/src/styles/fonts/inter-jetbrains.css +16 -0
- package/template/client/src/styles/themes/electric-indigo.css +90 -0
- package/template/client/src/styles/themes/ocean-teal.css +90 -0
- package/template/client/src/styles/themes/rose-pink.css +90 -0
- package/template/client/src/styles/themes/warm-orange.css +90 -0
- package/template/server/prisma/schema.prisma +0 -1
- package/template/server/src/modules/admin/admin.controller.ts +3 -9
- package/template/server/src/modules/admin/admin.routes.ts +7 -0
- package/template/server/src/modules/admin/admin.schemas.ts +13 -0
- package/template/server/src/modules/auth/auth.repo.ts +9 -8
- package/template/server/postman_collection.json +0 -666
package/bin/create-tigra.js
CHANGED
|
@@ -12,6 +12,9 @@ import crypto from 'crypto';
|
|
|
12
12
|
const __filename = fileURLToPath(import.meta.url);
|
|
13
13
|
const __dirname = path.dirname(__filename);
|
|
14
14
|
|
|
15
|
+
const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
|
|
16
|
+
const VERSION = packageJson.version;
|
|
17
|
+
|
|
15
18
|
const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
|
|
16
19
|
|
|
17
20
|
// Files that contain template variables and need replacement
|
|
@@ -126,11 +129,11 @@ async function main() {
|
|
|
126
129
|
program
|
|
127
130
|
.name('create-tigra')
|
|
128
131
|
.description('Create a production-ready full-stack app with Next.js + Fastify + Prisma + Redis')
|
|
129
|
-
.version(
|
|
132
|
+
.version(VERSION)
|
|
130
133
|
.argument('[project-name]', 'Name for your new project')
|
|
131
134
|
.action(async (projectNameArg) => {
|
|
132
135
|
console.log();
|
|
133
|
-
console.log(chalk.bold(' Create Tigra') + chalk.dim(
|
|
136
|
+
console.log(chalk.bold(' Create Tigra') + chalk.dim(` v${VERSION}`));
|
|
134
137
|
console.log();
|
|
135
138
|
|
|
136
139
|
let projectName = projectNameArg;
|
package/package.json
CHANGED
|
@@ -463,7 +463,7 @@ export function Providers({ children }: { children: React.ReactNode }): React.Re
|
|
|
463
463
|
|
|
464
464
|
#### `src/app/layout.tsx`
|
|
465
465
|
Root layout:
|
|
466
|
-
- Import and use `next/font` (Inter
|
|
466
|
+
- Import and use `next/font/google` (fonts defined by the active font preset — default: Inter + JetBrains Mono)
|
|
467
467
|
- `<html lang="en" suppressHydrationWarning>`
|
|
468
468
|
- Wrap children in `<Providers>`
|
|
469
469
|
- Default metadata with app name
|
|
@@ -32,6 +32,14 @@ src/
|
|
|
32
32
|
│ ├── store/ # <domain>Slice.ts (if needed)
|
|
33
33
|
│ ├── types/ # <domain>.types.ts
|
|
34
34
|
│ └── actions/ # <domain>.actions.ts (Server Actions)
|
|
35
|
+
├── styles/
|
|
36
|
+
│ ├── themes/ # Color theme presets (switch in globals.css import)
|
|
37
|
+
│ │ ├── warm-orange.css # Default — earthy, warm
|
|
38
|
+
│ │ ├── electric-indigo.css
|
|
39
|
+
│ │ ├── ocean-teal.css
|
|
40
|
+
│ │ └── rose-pink.css
|
|
41
|
+
│ └── fonts/ # Font presets (switch in globals.css import)
|
|
42
|
+
│ └── inter-jetbrains.css # Default — Inter + JetBrains Mono
|
|
35
43
|
├── hooks/ # Global hooks (useDebounce, useLocalStorage, useMediaQuery)
|
|
36
44
|
├── lib/
|
|
37
45
|
│ ├── api/ # axios.config.ts, api.types.ts
|
|
@@ -14,60 +14,177 @@ Clean, airy, "expensive" look inspired by Linear, Vercel, Stripe, Arc. Every vis
|
|
|
14
14
|
|
|
15
15
|
This project uses **Tailwind CSS v4** with **OKLCH color space** and the `@theme inline` directive (not the legacy `tailwind.config.ts`).
|
|
16
16
|
|
|
17
|
+
**Key differences from Tailwind v3:**
|
|
18
|
+
- No `tailwind.config.ts` — all config is CSS-based via `@theme inline`
|
|
19
|
+
- Colors use **OKLCH** (perceptually uniform) not HSL
|
|
20
|
+
- `@custom-variant dark` replaces `darkMode: 'class'`
|
|
21
|
+
- No `@layer base { :root { } }` — variables defined on `:root` via theme preset files
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Theme Preset System (Color Management)
|
|
26
|
+
|
|
27
|
+
**ALL color variables live in theme preset files, NOT in `globals.css`.** This is the single source of truth for the entire app's color palette.
|
|
28
|
+
|
|
29
|
+
### How It Works
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
src/
|
|
33
|
+
├── app/globals.css ← imports ONE theme preset (switch here)
|
|
34
|
+
└── styles/themes/
|
|
35
|
+
├── warm-orange.css ← Earthy, warm (default)
|
|
36
|
+
├── electric-indigo.css ← Modern, bold, tech-forward
|
|
37
|
+
├── ocean-teal.css ← Calm, professional
|
|
38
|
+
└── rose-pink.css ← Elegant, creative
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`globals.css` imports the active theme via a single line:
|
|
42
|
+
|
|
17
43
|
```css
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
@custom-variant dark (&:is(.dark *));
|
|
24
|
-
|
|
25
|
-
@theme inline {
|
|
26
|
-
--color-background: var(--background);
|
|
27
|
-
--color-foreground: var(--foreground);
|
|
28
|
-
--font-sans: var(--font-geist-sans);
|
|
29
|
-
--font-mono: var(--font-geist-mono);
|
|
30
|
-
/* ... maps all semantic tokens to Tailwind */
|
|
31
|
-
}
|
|
44
|
+
@import "../styles/themes/warm-orange.css";
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**To switch the entire palette**: change that ONE import line. That's it. Every color in the app updates instantly — light mode, dark mode, charts, sidebar, everything.
|
|
32
48
|
|
|
49
|
+
### Theme Preset Structure
|
|
50
|
+
|
|
51
|
+
Each preset file defines ALL semantic color variables for both `:root` (light) and `.dark` (dark mode):
|
|
52
|
+
|
|
53
|
+
```css
|
|
33
54
|
:root {
|
|
34
55
|
--radius: 0.625rem;
|
|
35
|
-
--background: oklch(
|
|
36
|
-
--foreground: oklch(
|
|
37
|
-
--primary: oklch(
|
|
38
|
-
--primary-foreground: oklch(
|
|
39
|
-
|
|
40
|
-
--secondary-foreground: oklch(0.205 0 0);
|
|
41
|
-
--muted: oklch(0.97 0 0);
|
|
42
|
-
--muted-foreground: oklch(0.556 0 0);
|
|
43
|
-
--accent: oklch(0.97 0 0);
|
|
44
|
-
--accent-foreground: oklch(0.205 0 0);
|
|
45
|
-
--destructive: oklch(0.577 0.245 27.325);
|
|
46
|
-
--border: oklch(0.922 0 0);
|
|
47
|
-
--input: oklch(0.922 0 0);
|
|
48
|
-
--ring: oklch(0.45 0.2 260);
|
|
49
|
-
--success: oklch(0.52 0.17 155);
|
|
50
|
-
--success-foreground: oklch(1 0 0);
|
|
51
|
-
--warning: oklch(0.75 0.18 75);
|
|
52
|
-
--warning-foreground: oklch(0.2 0 0);
|
|
53
|
-
--info: oklch(0.55 0.15 240);
|
|
54
|
-
--info-foreground: oklch(1 0 0);
|
|
55
|
-
--chart-1 through --chart-5 /* Data visualization colors */
|
|
56
|
-
--sidebar, --sidebar-foreground, etc. /* Sidebar-specific tokens */
|
|
56
|
+
--background: oklch(...);
|
|
57
|
+
--foreground: oklch(...);
|
|
58
|
+
--primary: oklch(...);
|
|
59
|
+
--primary-foreground: oklch(...);
|
|
60
|
+
/* ... all ~35 semantic tokens */
|
|
57
61
|
}
|
|
58
62
|
|
|
59
63
|
.dark {
|
|
60
|
-
--background: oklch(
|
|
61
|
-
--foreground: oklch(
|
|
64
|
+
--background: oklch(...);
|
|
65
|
+
--foreground: oklch(...);
|
|
66
|
+
--primary: oklch(...);
|
|
62
67
|
/* ... dark mode overrides for all tokens */
|
|
63
68
|
}
|
|
64
69
|
```
|
|
65
70
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
+
### Creating a Custom Theme
|
|
72
|
+
|
|
73
|
+
1. Copy any existing preset file (e.g., `warm-orange.css`)
|
|
74
|
+
2. Rename it (e.g., `my-brand.css`)
|
|
75
|
+
3. Edit the OKLCH values to match your brand palette
|
|
76
|
+
4. Update the import in `globals.css`: `@import "../styles/themes/my-brand.css";`
|
|
77
|
+
|
|
78
|
+
### Available Presets
|
|
79
|
+
|
|
80
|
+
| Preset | Accent | Vibe | Inspired by |
|
|
81
|
+
|--------|--------|------|-------------|
|
|
82
|
+
| `warm-orange.css` | Terracotta orange | Earthy, warm, approachable | Claude |
|
|
83
|
+
| `electric-indigo.css` | Deep indigo-violet | Modern, bold, tech-forward | Linear, Figma |
|
|
84
|
+
| `ocean-teal.css` | Deep teal-cyan | Calm, professional, trustworthy | Stripe, Vercel |
|
|
85
|
+
| `rose-pink.css` | Soft rose-magenta | Elegant, creative, premium | Dribbble, Notion |
|
|
86
|
+
|
|
87
|
+
### CRITICAL RULES — Color Management
|
|
88
|
+
|
|
89
|
+
1. **NEVER add or modify color variables directly in `globals.css`.** All `:root` and `.dark` color variables belong in the active theme preset file only.
|
|
90
|
+
2. **NEVER hardcode OKLCH/hex/rgb values in components.** Always use semantic tokens (`bg-primary`, `text-foreground`).
|
|
91
|
+
3. **To change the brand palette**: switch the import in `globals.css` or edit the active preset file. Never scatter color values across multiple files.
|
|
92
|
+
4. **New semantic tokens**: If you need a new color token (rare), add it to ALL preset files to keep them in sync.
|
|
93
|
+
5. **The `@theme inline` block in `globals.css` maps CSS vars to Tailwind** — it does NOT define colors. Colors come from the preset.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Font Preset System (Font Management)
|
|
98
|
+
|
|
99
|
+
**Font families are defined in font preset files, NOT hardcoded in components.** This mirrors the color theme preset system — switch the entire font pairing by changing one import.
|
|
100
|
+
|
|
101
|
+
### How It Works
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
src/
|
|
105
|
+
├── app/
|
|
106
|
+
│ ├── layout.tsx ← loads fonts via next/font/google
|
|
107
|
+
│ └── globals.css ← imports ONE font preset (switch here)
|
|
108
|
+
└── styles/fonts/
|
|
109
|
+
└── inter-jetbrains.css ← Default (Inter + JetBrains Mono)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Three Semantic Font Roles
|
|
113
|
+
|
|
114
|
+
| Role | CSS Variable | Tailwind Class | Default Font |
|
|
115
|
+
|------|-------------|----------------|--------------|
|
|
116
|
+
| Body text | `--font-sans-value` | `font-sans` | Inter |
|
|
117
|
+
| Headings | `--font-heading-value` | `font-heading` | Inter |
|
|
118
|
+
| Code/mono | `--font-mono-value` | `font-mono` | JetBrains Mono |
|
|
119
|
+
|
|
120
|
+
### How to Switch Fonts
|
|
121
|
+
|
|
122
|
+
Switching fonts requires two changes:
|
|
123
|
+
|
|
124
|
+
**Step 1 — Update font imports in `layout.tsx`:**
|
|
125
|
+
|
|
126
|
+
```tsx
|
|
127
|
+
// Change these imports to your desired fonts
|
|
128
|
+
import { Roboto, Fira_Code } from 'next/font/google';
|
|
129
|
+
|
|
130
|
+
const roboto = Roboto({
|
|
131
|
+
variable: '--font-roboto',
|
|
132
|
+
subsets: ['latin'],
|
|
133
|
+
weight: ['400', '500', '600', '700'],
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
const firaCode = Fira_Code({
|
|
137
|
+
variable: '--font-fira-code',
|
|
138
|
+
subsets: ['latin'],
|
|
139
|
+
});
|
|
140
|
+
|
|
141
|
+
// Update the className to use new variables
|
|
142
|
+
<body className={`${roboto.variable} ${firaCode.variable} font-sans antialiased`}>
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
**Step 2 — Update the font preset file (or create a new one):**
|
|
146
|
+
|
|
147
|
+
```css
|
|
148
|
+
/* styles/fonts/roboto-fira.css */
|
|
149
|
+
:root {
|
|
150
|
+
--font-sans-value: var(--font-roboto);
|
|
151
|
+
--font-heading-value: var(--font-roboto);
|
|
152
|
+
--font-mono-value: var(--font-fira-code);
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Then update the import in `globals.css`:
|
|
157
|
+
```css
|
|
158
|
+
@import "../styles/fonts/roboto-fira.css";
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Font Preset Structure
|
|
162
|
+
|
|
163
|
+
Each preset maps raw font variables (set by `next/font/google` in `layout.tsx`) to semantic roles:
|
|
164
|
+
|
|
165
|
+
```css
|
|
166
|
+
:root {
|
|
167
|
+
--font-sans-value: var(--font-inter); /* body text */
|
|
168
|
+
--font-heading-value: var(--font-inter); /* headings */
|
|
169
|
+
--font-mono-value: var(--font-jetbrains-mono); /* code */
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Creating a Custom Font Preset
|
|
174
|
+
|
|
175
|
+
1. Choose your fonts from [Google Fonts](https://fonts.google.com)
|
|
176
|
+
2. Update `layout.tsx` — import fonts via `next/font/google`, set CSS variable names
|
|
177
|
+
3. Create a new preset file in `src/styles/fonts/` (or edit the existing one)
|
|
178
|
+
4. Map your font variables to the three semantic roles
|
|
179
|
+
5. Update the import in `globals.css` to point to your preset
|
|
180
|
+
|
|
181
|
+
### CRITICAL RULES — Font Management
|
|
182
|
+
|
|
183
|
+
1. **NEVER hardcode font-family values in components.** Always use Tailwind classes (`font-sans`, `font-heading`, `font-mono`).
|
|
184
|
+
2. **ALL font-family mappings live in the font preset file**, not in `globals.css` or components.
|
|
185
|
+
3. **To change fonts**: update `layout.tsx` imports + update the font preset file. Never scatter font-family values across the codebase.
|
|
186
|
+
4. **The `@theme inline` block in `globals.css` maps preset variables to Tailwind** — it does NOT define fonts. Fonts come from the preset.
|
|
187
|
+
5. **Fonts are loaded via `next/font/google`** — this self-hosts fonts automatically at build time. No external requests at runtime, no manual file downloads needed.
|
|
71
188
|
|
|
72
189
|
---
|
|
73
190
|
|
|
@@ -117,7 +234,7 @@ This project uses **Tailwind CSS v4** with **OKLCH color space** and the `@theme
|
|
|
117
234
|
1. **Never hardcode**: No `bg-blue-500`, no `bg-[#3b82f6]`, no `style={{ color }}`. Always semantic tokens.
|
|
118
235
|
2. **Semantic names by purpose**: `bg-destructive` not `bg-red`.
|
|
119
236
|
3. **Always pair bg + foreground**: `bg-primary text-primary-foreground` for contrast.
|
|
120
|
-
4. **Single source of truth**: Change colors
|
|
237
|
+
4. **Single source of truth**: Change colors ONLY in the active theme preset file (`src/styles/themes/*.css`). Never in `globals.css`, never in components.
|
|
121
238
|
5. **90% monochrome**: 90% of UI uses `background`, `foreground`, `muted`, `border`. Color is the exception.
|
|
122
239
|
6. **Opacity for hierarchy**: Use `bg-primary/10`, `bg-primary/5` for tinted backgrounds.
|
|
123
240
|
|
|
@@ -138,7 +255,7 @@ This project uses **Tailwind CSS v4** with **OKLCH color space** and the `@theme
|
|
|
138
255
|
|
|
139
256
|
## Typography
|
|
140
257
|
|
|
141
|
-
- **Font**: Inter
|
|
258
|
+
- **Font**: Defined by the active font preset (default: Inter for sans/heading, JetBrains Mono for mono). See "Font Preset System" above for how to switch.
|
|
142
259
|
- **Headings**: `text-wrap: balance`, `leading-tight`. Mobile-first responsive sizes:
|
|
143
260
|
- H1: `text-2xl md:text-3xl lg:text-4xl`
|
|
144
261
|
- H2: `text-xl md:text-2xl`
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
| Creating files, folders, feature modules | `01-project-structure.md` |
|
|
10
10
|
| Building components, writing types/interfaces | `02-components-and-types.md` |
|
|
11
11
|
| Fetching data, managing state, calling APIs, forms | `03-data-and-state.md` |
|
|
12
|
-
| Choosing colors, styling, typography, spacing, motion | `04-design-system.md` |
|
|
12
|
+
| Choosing colors, styling, typography, spacing, motion, **theme presets**, **font presets** | `04-design-system.md` |
|
|
13
13
|
| Auth tokens, env vars, security headers | `05-security.md` |
|
|
14
14
|
| UX psychology, cognitive load, a11y, performance | `06-ux-checklist.md` |
|
|
15
15
|
|
|
@@ -36,8 +36,10 @@ State: Server data (SSR) → Server Components
|
|
|
36
36
|
1. **Mobile-first**: All Tailwind classes start at mobile. Desktop is the enhancement (`md:`, `lg:`). Touch targets min 44x44px. No functionality behind hover-only states.
|
|
37
37
|
2. **Server Components by default.** Only add `'use client'` when you need hooks, state, or event handlers.
|
|
38
38
|
3. **Component limits**: Max 250 lines, max 5 props, max 3 JSX nesting levels.
|
|
39
|
-
4. **No hardcoded colors**: Use Tailwind semantic tokens (`bg-primary`, `text-foreground`). Never hex/rgb.
|
|
40
|
-
5. **No
|
|
41
|
-
6. **
|
|
42
|
-
7. **
|
|
43
|
-
8. **
|
|
39
|
+
4. **No hardcoded colors**: Use Tailwind semantic tokens (`bg-primary`, `text-foreground`). Never hex/rgb. **All color variables live in theme preset files (`src/styles/themes/*.css`), NOT in `globals.css` or components.** To change the palette, switch the import in `globals.css` or edit the active preset. Read `04-design-system.md` → "Theme Preset System" for details.
|
|
40
|
+
5. **No hardcoded fonts**: Use Tailwind font classes (`font-sans`, `font-heading`, `font-mono`). Never hardcode `font-family` in components. **Font families are defined in font preset files (`src/styles/fonts/*.css`).** To change fonts, update the `next/font/google` imports in `layout.tsx` and the font preset file. Read `04-design-system.md` → "Font Preset System" for details.
|
|
41
|
+
6. **No inline styles**: Tailwind only. Use `cn()` for conditional classes.
|
|
42
|
+
7. **Import order**: React/Next → third-party → UI → local → hooks → services → types → utils.
|
|
43
|
+
8. **Forms**: Validate with Zod. Always validate client-side AND server-side.
|
|
44
|
+
9. **Security**: Never inject raw HTML without sanitization. Never prefix secrets with `NEXT_PUBLIC_`.
|
|
45
|
+
10. **Deployment**: Never remove `output: "standalone"` from `next.config.ts`. When adding `NEXT_PUBLIC_*` env vars, also add them as `ARG` + `ENV` in the Dockerfile builder stage. Read `07-deployment.md` for details.
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
> **SCOPE**: These rules apply to the **entire workspace** (server + client). Always active.
|
|
2
|
+
|
|
3
|
+
# Task Completion Reports
|
|
4
|
+
|
|
5
|
+
When you finish a task, phase, or multi-step implementation, you MUST provide a structured completion report. Freeform paragraphs like "Fixed issues and completed remaining tasks" are not acceptable. The report must give the user a clear, scannable picture of everything that changed, why, and what to do next.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## When to Report
|
|
10
|
+
|
|
11
|
+
| Situation | Report required? |
|
|
12
|
+
|-----------|-----------------|
|
|
13
|
+
| Completed a full task or feature | **Yes — Full Report** |
|
|
14
|
+
| Completed a phase in a multi-phase plan | **Yes — Phase Report** (subset of Full Report) |
|
|
15
|
+
| Fixed a bug | **Yes — Bug Fix Report** |
|
|
16
|
+
| Small config change, typo fix, single-file edit | **No** — a 1-2 sentence explanation is fine |
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Full Report Template
|
|
21
|
+
|
|
22
|
+
Use this structure after completing a feature or multi-phase task. Omit sections that don't apply (e.g., skip "Database Changes" if no migrations were created), but never omit "Files Changed" or "How to Test".
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
## Summary
|
|
26
|
+
[1-3 sentences: what was built/changed and why]
|
|
27
|
+
|
|
28
|
+
## Files Changed
|
|
29
|
+
|
|
30
|
+
### Created
|
|
31
|
+
- `path/to/file.ts` — [purpose: what this file does]
|
|
32
|
+
|
|
33
|
+
### Modified
|
|
34
|
+
- `path/to/file.ts` — [what changed and why]
|
|
35
|
+
|
|
36
|
+
### Deleted
|
|
37
|
+
- `path/to/file.ts` — [why it was removed]
|
|
38
|
+
|
|
39
|
+
## New API Endpoints (if applicable)
|
|
40
|
+
| Method | Path | Auth | Description |
|
|
41
|
+
|--------|------|------|-------------|
|
|
42
|
+
|
|
43
|
+
## Database Changes (if applicable)
|
|
44
|
+
- Migration: `YYYYMMDD_name` — [what it does]
|
|
45
|
+
- New tables: [list]
|
|
46
|
+
- Modified tables: [what changed]
|
|
47
|
+
- Indexes added: [list]
|
|
48
|
+
|
|
49
|
+
## Environment Variables (if applicable)
|
|
50
|
+
| Variable | Required | Where | Description |
|
|
51
|
+
|----------|----------|-------|-------------|
|
|
52
|
+
[Where = .env / .env.example / Dockerfile ARG / Coolify]
|
|
53
|
+
|
|
54
|
+
## Dependencies Added (if applicable)
|
|
55
|
+
| Package | Purpose |
|
|
56
|
+
|---------|---------|
|
|
57
|
+
- Note if any require system-level installs (apk add)
|
|
58
|
+
|
|
59
|
+
## Key Decisions & Trade-offs
|
|
60
|
+
[Explain non-obvious choices. Why was approach A chosen over B? What assumptions were made? What are the limitations?]
|
|
61
|
+
|
|
62
|
+
## Deployment & Production Impact (if applicable)
|
|
63
|
+
[This section is REQUIRED whenever changes affect deployment, infrastructure, or production behavior. Include ALL that apply:]
|
|
64
|
+
|
|
65
|
+
### Dockerfile Changes
|
|
66
|
+
- [New ARG/ENV added, new COPY lines, new apk packages, port changes, etc.]
|
|
67
|
+
|
|
68
|
+
### Environment / Coolify Configuration
|
|
69
|
+
- [New env vars that must be set in Coolify/hosting platform]
|
|
70
|
+
- [Build arguments that must be added]
|
|
71
|
+
- [Volume mounts needed]
|
|
72
|
+
|
|
73
|
+
### Database Migration Required
|
|
74
|
+
- [Migration name and what it does]
|
|
75
|
+
- [Must run `prisma migrate deploy` before/after deploying]
|
|
76
|
+
- [Any data migration or backfill needed]
|
|
77
|
+
|
|
78
|
+
### Infrastructure Changes
|
|
79
|
+
- [New external services required (Redis, S3, third-party APIs)]
|
|
80
|
+
- [DNS/domain changes needed]
|
|
81
|
+
- [SSL/certificate changes]
|
|
82
|
+
- [New cron jobs or background workers]
|
|
83
|
+
|
|
84
|
+
### Deployment Order
|
|
85
|
+
- [If server and client must be deployed in a specific order, state it]
|
|
86
|
+
- [If a migration must run before the new code deploys, state it]
|
|
87
|
+
|
|
88
|
+
### Rollback Plan
|
|
89
|
+
- [What happens if this deployment fails — is it safe to roll back?]
|
|
90
|
+
- [Are the database changes backwards-compatible with the previous code version?]
|
|
91
|
+
|
|
92
|
+
## Breaking Changes (if any)
|
|
93
|
+
- [What breaks, what to update, and how]
|
|
94
|
+
|
|
95
|
+
## Manual Steps Required
|
|
96
|
+
1. [Ordered list of things the user must do before this works]
|
|
97
|
+
- e.g., "Add GEMINI_API_KEY to .env"
|
|
98
|
+
- e.g., "Run npm run prisma:migrate dev"
|
|
99
|
+
|
|
100
|
+
## How to Test
|
|
101
|
+
1. [Step-by-step verification the user can follow]
|
|
102
|
+
- Be specific: exact commands, exact Postman steps, exact URLs
|
|
103
|
+
- Include expected responses where helpful
|
|
104
|
+
|
|
105
|
+
## Known Limitations / TODOs (if any)
|
|
106
|
+
- [Things not yet implemented, edge cases not handled, future improvements needed]
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## Phase Report Template
|
|
112
|
+
|
|
113
|
+
Use this when completing one phase of a multi-phase plan. Shorter than a Full Report but still structured.
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
## Phase N Complete: [Phase Title]
|
|
117
|
+
|
|
118
|
+
### What was done
|
|
119
|
+
- [Bullet list of concrete changes]
|
|
120
|
+
|
|
121
|
+
### Files Changed
|
|
122
|
+
- `path/to/file.ts` — [what and why]
|
|
123
|
+
|
|
124
|
+
### Key Decisions
|
|
125
|
+
- [Any non-obvious choices made during this phase]
|
|
126
|
+
|
|
127
|
+
### Blockers or Concerns
|
|
128
|
+
- [Anything that might affect subsequent phases]
|
|
129
|
+
|
|
130
|
+
### Phase Status
|
|
131
|
+
- [x] Phase N complete
|
|
132
|
+
- [ ] Phase N+1: [title] — next
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Bug Fix Report Template
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
## Bug Fix: [Short description]
|
|
141
|
+
|
|
142
|
+
### Root Cause
|
|
143
|
+
[What was actually wrong — not just the symptom, but the underlying cause]
|
|
144
|
+
|
|
145
|
+
### Fix Applied
|
|
146
|
+
- `path/to/file.ts` — [what changed]
|
|
147
|
+
|
|
148
|
+
### Why This Fix
|
|
149
|
+
[Why this approach was chosen. What other approaches were considered and rejected.]
|
|
150
|
+
|
|
151
|
+
### How to Verify
|
|
152
|
+
1. [Steps to confirm the fix works]
|
|
153
|
+
|
|
154
|
+
### Regression Risk
|
|
155
|
+
- [Could this fix break anything else? What was checked?]
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## Rules
|
|
161
|
+
|
|
162
|
+
1. **Structure over prose.** Use the templates above. Tables, bullet points, and headers — not paragraphs.
|
|
163
|
+
2. **Every file gets a "why".** Don't just list `file.ts` — explain what changed and why. "Added creditBalance: 0 to mocks" → "Added `creditBalance: 0` to user mocks in `setup.ts` because the new credits module added this required field to the User model, and existing test fixtures would fail validation without it."
|
|
164
|
+
3. **Be specific in "How to Test".** Not "use Postman to test." Instead: "1. POST `{{baseUrl}}/auth/login` with test credentials. 2. POST `{{baseUrl}}/generations` with body `{ templateId: '...', image: <file> }`. 3. Expected: 201 with `{ success: true, data: { id, status: 'pending' } }`."
|
|
165
|
+
4. **Explain decisions, not just actions.** "Used upsert for seed data" → "Used `upsert` instead of `create` for seed data so the seed script is idempotent — running it twice won't throw duplicate key errors."
|
|
166
|
+
5. **Surface what the user needs to do.** If the user must add an env var, run a migration, install something, or restart a service — put it in "Manual Steps Required" prominently. Don't bury it in a paragraph.
|
|
167
|
+
6. **Honest about limitations.** If something is incomplete, has edge cases, or needs future work — say so in "Known Limitations." Don't pretend everything is perfect.
|
|
168
|
+
7. **Scale to the task.** A 5-phase feature gets a full report with every section. A single service method gets a shorter report. Use judgment, but always use the structured format.
|
|
169
|
+
8. **Deployment impact is never optional.** If ANY of the following changed, the "Deployment & Production Impact" section is REQUIRED — no exceptions:
|
|
170
|
+
- New or modified environment variables
|
|
171
|
+
- New npm packages with native dependencies
|
|
172
|
+
- Database schema changes (new tables, columns, indexes)
|
|
173
|
+
- Dockerfile modifications needed
|
|
174
|
+
- New external service dependencies (APIs, Redis, S3, etc.)
|
|
175
|
+
- Port, entry point, or health check changes
|
|
176
|
+
- File upload/storage changes requiring volume mounts
|
|
177
|
+
- Changes to build process or build arguments
|
|
178
|
+
If none of these apply, explicitly state: "No deployment impact — no infrastructure, env, or database changes."
|
|
@@ -66,6 +66,12 @@ When the user asks to create, scaffold, or start a new server or client project,
|
|
|
66
66
|
|
|
67
67
|
---
|
|
68
68
|
|
|
69
|
+
## Task Completion Reports
|
|
70
|
+
|
|
71
|
+
After completing any task, phase, or bug fix, you MUST provide a structured completion report — not freeform paragraphs. **Read `completion-reports.md`** for the required templates and rules. This includes deployment/production impact analysis whenever infrastructure, env vars, database, or Docker changes are involved.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
69
75
|
## Code Review Checklist
|
|
70
76
|
|
|
71
77
|
Before considering work done, verify:
|
|
@@ -18,7 +18,7 @@ Open [http://localhost:3000](http://localhost:3000) with your browser to see the
|
|
|
18
18
|
|
|
19
19
|
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
|
|
20
20
|
|
|
21
|
-
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [
|
|
21
|
+
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Inter](https://fonts.google.com/specimen/Inter) and [JetBrains Mono](https://fonts.google.com/specimen/JetBrains+Mono). Fonts are managed via the font preset system in `src/styles/fonts/` — see the design system rules for how to switch fonts.
|
|
22
22
|
|
|
23
23
|
## Learn More
|
|
24
24
|
|
|
@@ -13,7 +13,7 @@ export default function GlobalError({
|
|
|
13
13
|
reset: () => void;
|
|
14
14
|
}): React.ReactElement {
|
|
15
15
|
return (
|
|
16
|
-
<div className="flex min-h-
|
|
16
|
+
<div className="flex min-h-dvh flex-col items-center justify-center p-8 text-center">
|
|
17
17
|
<AlertCircle className="mb-4 h-12 w-12 text-destructive" />
|
|
18
18
|
<h2 className="mb-2 text-2xl font-bold">Something went wrong</h2>
|
|
19
19
|
<p className="mb-4 text-muted-foreground">
|