create-guren-app 1.0.0 → 1.2.0

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.
Files changed (27) hide show
  1. package/dist/cli.js +27 -5
  2. package/package.json +1 -1
  3. package/templates/api-only/.env.example +3 -0
  4. package/templates/api-only/config/database.ts +13 -1
  5. package/templates/api-only/package.json +1 -0
  6. package/templates/api-only/tsconfig.json +1 -1
  7. package/templates/default/.env.example +3 -0
  8. package/templates/default/.guren/api-client.gen.ts +1 -1
  9. package/templates/default/app/Http/Controllers/HomeController.ts +1 -1
  10. package/templates/default/config/database.ts +13 -1
  11. package/templates/default/package.json +1 -0
  12. package/templates/default/resources/js/app.tsx +1 -1
  13. package/templates/default/tsconfig.json +1 -1
  14. package/templates/default-ssr/resources/js/ssr.tsx +1 -1
  15. package/templates/default/.claude/agents/code-review.md +0 -130
  16. package/templates/default/.claude/agents/test-writer.md +0 -192
  17. package/templates/default/.claude/rules/controllers-http.md +0 -95
  18. package/templates/default/.claude/rules/orm-models.md +0 -118
  19. package/templates/default/.claude/rules/routes-codegen.md +0 -96
  20. package/templates/default/.claude/rules/testing.md +0 -93
  21. package/templates/default/.claude/skills/db-manage/SKILL.md +0 -97
  22. package/templates/default/.claude/skills/dev-workflow/SKILL.md +0 -74
  23. package/templates/default/.claude/skills/feature/SKILL.md +0 -195
  24. package/templates/default/.claude/skills/guren-api/SKILL.md +0 -431
  25. package/templates/default/.claude/skills/scaffold/SKILL.md +0 -83
  26. package/templates/default/.mcp.json +0 -8
  27. package/templates/default/CLAUDE.md +0 -173
@@ -1,118 +0,0 @@
1
- ---
2
- description: Guren ORM (@guren/orm) — model definition, queries, relations, pagination, mass assignment
3
- globs:
4
- - "app/Models/**"
5
- - "db/**"
6
- ---
7
-
8
- # ORM Models (@guren/orm)
9
-
10
- ## Defining a model
11
-
12
- ```typescript
13
- import { defineModel, type BelongsToRecord } from '@guren/orm'
14
- import { posts } from '../../db/schema.js'
15
-
16
- export type PostRecord = typeof posts.$inferSelect
17
-
18
- export class Post extends defineModel(posts) {
19
- static fillable = ['title', 'body', 'authorId']
20
- static override relationTypes: { author: BelongsToRecord<UserRecord> } = { author: null }
21
- }
22
- Post.belongsTo('author', () => import('./User.js').then((m) => m.User), 'authorId', 'id')
23
- ```
24
-
25
- `class Post extends Model<typeof posts> { static table = posts }` also works.
26
- Auth user models: `defineModel(users, { base: AuthenticatableModel })`.
27
-
28
- ## Statics
29
-
30
- `find(id)` → record | null · `findOrFail(id)` throws `ModelNotFoundException` (renders 404) ·
31
- `first(where?)` → record | null · `all()` · `create(data)` · `forceCreate(data)` ·
32
- `update(where, data)` · `forceUpdate(where, data)` · `delete(where)` ·
33
- `paginate(options?)` · `transaction(async (trx) => ...)`
34
-
35
- ## Where clauses
36
-
37
- ```typescript
38
- await Post.where({ status: 'active', authorId: 1 }).get() // object form = AND
39
- await Post.where({ id: [1, 2, 3] }).get() // array value = IN
40
- await Post.where('views', '>', 100).orWhere('featured', true).get()
41
- ```
42
-
43
- Operators (exact set): `=` `!=` `>` `<` `>=` `<=` `like` `in` `not in` `is null` `is not null`
44
-
45
- ## QueryBuilder chain
46
-
47
- `Post.where(...)` returns a `QueryBuilder`. Chainable:
48
- `where` / `orWhere` / `whereNull(field)` / `whereNotNull(field)` /
49
- `whereIn(field, values)` / `whereNotIn(field, values)` /
50
- `orderBy(field, 'asc' | 'desc')` (repeatable) / `limit(n)` / `offset(n)` /
51
- `with(...relations)` / `scope(name)`
52
-
53
- Terminate with: `get()` / `first()` / `firstOrFail()` / `count()` /
54
- `paginate(page?, perPage?)` or `paginate({ page, perPage })` /
55
- `update(data)` / `forceUpdate(data)` / `delete()`
56
-
57
- ## Pagination
58
-
59
- ```typescript
60
- const result = await Post.paginate({ page: 1, perPage: 15, where: {...}, orderBy: 'createdAt' })
61
- // PaginateOptions: { page? (1-based, default 1), perPage? (default 15), where?, orderBy? }
62
- // PaginatedResult: { data: TRecord[], meta: { total, perPage, currentPage, totalPages, hasMore, from, to } }
63
- ```
64
-
65
- For Inertia/HTTP pagination links wrap it with `paginate` from `@guren/core`:
66
- `paginate(result, { path, query?, fragment? })` — those three fields are `PaginatorOptions`.
67
-
68
- ## Relations — declaration signatures
69
-
70
- - `hasOne(name, related, foreignKey, localKey)`
71
- - `hasMany(name, related, foreignKey, localKey)`
72
- - `belongsTo(name, related, foreignKey, ownerKey)`
73
- - `belongsToMany(name, related, pivotTable, foreignPivotKey, relatedPivotKey, parentKey = 'id', relatedKey = 'id')` — 7 args; `pivotTable` is the Drizzle table
74
- - `hasManyThrough(name, related, through, firstKey, secondKey, localKey = 'id', secondLocalKey = 'id')`
75
- - `morphMany` / `morphTo` also exist
76
-
77
- `related` is a model class or lazy loader: `() => import('./Tag.js').then((m) => m.Tag)`.
78
-
79
- Typed relation results — declare `static relationTypes` using these exported types:
80
- `HasManyRecord<T>` = `T[]` · `HasOneRecord<T>` = `T | null` · `BelongsToRecord<T>` = `T | null` ·
81
- `BelongsToManyRecord<T>` = `T[]` · `HasManyThroughRecord<T>` = `T[]`
82
-
83
- ## Eager loading
84
-
85
- ```typescript
86
- await Post.with('tags') // Array<record & { tags: TagRecord[] }>; nested: with('author.posts')
87
- await Post.with(['author', 'tags'], { published: true }) // optional where filter
88
- await Post.findWith(1, 'tags') // single record + relations, or null
89
- await Post.findWithOrFail(1, ['author']) // throws ModelNotFoundException
90
- await Post.withCount('tags') // adds tagsCount: number (no nested names)
91
- await Post.withPaginate('tags', { page: 1 }) // PaginatedResult with relations
92
- ```
93
-
94
- ## No attach/detach/sync — use a pivot model
95
-
96
- ```typescript
97
- export class PostTag extends defineModel(postTags) {}
98
- await PostTag.create({ postId, tagId }) // attach
99
- await PostTag.delete({ postId, tagId }) // detach
100
- // sync: PostTag.delete({ postId }) then re-create the desired set
101
- ```
102
-
103
- ## No firstOrCreate / updateOrCreate — hand-roll it
104
-
105
- ```typescript
106
- const existing = await Tag.first({ name })
107
- const tag = existing ?? await Tag.create({ name })
108
- ```
109
-
110
- For concurrency safety add a unique index and catch the constraint error, or wrap in
111
- `Tag.transaction(async (trx) => ...)`.
112
-
113
- ## Mass assignment
114
-
115
- - With `static fillable = [...]` set, `create()`/`update()` **throw `MassAssignmentException`**
116
- on any unlisted input key (`static strictFillable = false` restores silent discarding)
117
- - Without `fillable`, keys in `static guarded` (default `['id']`) are silently stripped
118
- - `forceCreate()` / `forceUpdate()` bypass filtering — trusted server-side data only
@@ -1,96 +0,0 @@
1
- ---
2
- description: Guren routing & codegen — RouteContractOptions, schema binding, the Zod→ApiRoutes matrix, middleware
3
- globs:
4
- - "routes/**"
5
- - "app/Http/Validators/**"
6
- ---
7
-
8
- # Routes & Codegen
9
-
10
- ## Registering routes
11
-
12
- ```typescript
13
- import { Router, requireAuthenticated } from '@guren/core'
14
-
15
- export function registerWebRoutes(router: Router): void {
16
- router.get('/posts', [PostController, 'index']).name('posts.index')
17
- router.post('/posts', { name: 'posts.store', body: CreatePostSchema }, [PostController, 'store'])
18
-
19
- router.aliasMiddleware('auth', requireAuthenticated({ redirectTo: '/login' }))
20
- router.middleware('auth').group((group) => {
21
- group.get('/dashboard', [DashboardController, 'index'])
22
- })
23
- router.group('/admin', (admin) => { /* path-prefixed */ })
24
- }
25
- ```
26
-
27
- Options object (second arg) is `RouteContractOptions`:
28
- `name?` · `middlewares?: MiddlewareHandler[]` · `params?` / `query?` / `body?` / `output?`
29
- (Zod schemas) · `bind?: Record<string, BindableModel>` · plus OpenAPI metadata
30
- (`summary?`, `description?`, `tags?`, `operationId?`, `deprecated?`).
31
-
32
- Schemas attached here do double duty: requests are **validated automatically**
33
- (422 before the controller runs) and `bunx guren codegen` extracts them into typed manifests.
34
-
35
- `router.resource('/posts', PostController, { name?, param?, only?, except? })` registers
36
- index/create/store/show/edit/update/destroy (GET/POST/PUT/DELETE, `:id` param) named `posts.index` etc.
37
- Model binding: `bind: { id: Post }` + `this.model(Post)` in the controller.
38
-
39
- ## Route Schema Binding: concrete input → output
40
-
41
- ```typescript
42
- const CreatePostSchema = z.object({
43
- title: z.string().trim().min(1),
44
- body: z.string(),
45
- published: z.boolean().optional().default(false),
46
- tagIds: z.array(z.coerce.number().int()).optional(),
47
- })
48
- router.post('/posts', { name: 'posts.store', body: CreatePostSchema }, [PostController, 'store'])
49
- ```
50
-
51
- generates this entry in `.guren/api-client.gen.ts`:
52
-
53
- ```typescript
54
- export interface ApiRoutes {
55
- 'posts.store': {
56
- method: 'POST'
57
- path: '/posts'
58
- params: Record<string, never> // path params come from ':id' segments, typed string | number
59
- body: { title: string; body: string; published?: boolean; tagIds?: number[] }
60
- }
61
- }
62
- ```
63
-
64
- Only **named** routes are emitted. `output:` schemas add a `response:` field.
65
- Consume with `createApiClient<ApiRoutes>({ baseUrl })` → `client.request('posts.store', { body })`.
66
-
67
- ## Which Zod constructs survive type extraction
68
-
69
- Codegen walks schemas at runtime (Zod v3 and v4):
70
-
71
- - **Typed**: primitives (`string`/`number`/`boolean`/`bigint`/`date`), `literal`, `enum`,
72
- `array`, nested `object`, `union` / `discriminatedUnion`, `intersection`, `record`,
73
- `nullable` (`| null`)
74
- - **Unwrapped transparently**: `.optional()` and `.default()` (field becomes `key?:`),
75
- `.catch()`, `.readonly()`, `.brand()`, `.lazy()`
76
- - **Validation checks don't change the type**: `.min()`, `.max()`, `.trim()`, `.email()`,
77
- regex etc. stay `string`; `z.coerce.number()` is `number`
78
- - **Input side only**: `.transform()` / `.refine()` chains extract the schema's *input*
79
- type — transform output types are NOT reflected
80
- - **Degrades**: `tuple` → `unknown[]`, `z.nativeEnum()` → `string | number`,
81
- unrecognized constructs → `unknown`
82
-
83
- So `z.string().trim().min(1).optional().default('x')` survives as `key?: string`.
84
- If a generated type comes out as `unknown`, simplify the construct instead of reading `node_modules`.
85
-
86
- ## When to re-run codegen
87
-
88
- `bunx guren codegen` (or `bun run codegen`) regenerates `.guren/pages.gen.ts`,
89
- `routes.gen.ts`, `data.gen.ts`, `api-client.gen.ts`. Re-run after changing:
90
-
91
- - `routes/web.ts` (route names, paths, schemas)
92
- - page components' `interface Props` in `resources/js/pages/`
93
- - Resource classes in `app/Http/Resources/`
94
-
95
- `bun run dev` runs codegen on start, and the Vite plugin watches those paths and
96
- regenerates on change. In tests/CI, run it explicitly if generated types are stale.
@@ -1,93 +0,0 @@
1
- ---
2
- description: Guren testing (@guren/testing) — TestApp client methods and the full assertion surface
3
- globs:
4
- - "tests/**"
5
- ---
6
-
7
- # Testing (@guren/testing + bun:test)
8
-
9
- Requests run in-process through `app.fetch()` — no server, no port.
10
-
11
- ## Creating a TestApp
12
-
13
- ```typescript
14
- import { TestApp } from '@guren/testing'
15
-
16
- const app = await TestApp.create() // boots the real Application
17
- const app = await TestApp.create({ boot, providers, routes }) // all optional
18
- const app = TestApp.fromFetch(app.fetch) // wrap an existing fetch fn (not async)
19
- ```
20
-
21
- Both set `GUREN_TESTING=1` so `actingAs()` header auth is accepted.
22
-
23
- ## Client methods
24
-
25
- ```typescript
26
- app.get(path) // → PendingTestResponse (awaitable AND chainable)
27
- app.post(path, body?) // body auto-JSON-encoded unless FormData
28
- app.put(path, body?) / app.patch(path, body?) / app.delete(path, body?)
29
-
30
- app.actingAs(user) // returns a NEW TestApp with the user injected
31
- app.json() // returns a NEW TestApp with Accept: application/json
32
- app.withHeader(name, value) / app.withHeaders(record) // also return new TestApp
33
- const csrf = await app.withCsrf() // primes session + XSRF cookies; use for mutating requests hitting CSRF
34
- ```
35
-
36
- ## Chainable assertions (on PendingTestResponse)
37
-
38
- ```typescript
39
- await app.get('/posts').assertOk().assertJsonCount(3, 'data')
40
- ```
41
-
42
- Exact list:
43
- `assertStatus(code: number)` · `assertOk()` (200) · `assertCreated()` (201) ·
44
- `assertNoContent()` (204) · `assertRedirect(url?: string)` (3xx, optional Location match) ·
45
- `assertNotFound()` (404) · `assertForbidden()` (403) · `assertUnauthorized()` (401) ·
46
- `assertUnprocessable()` (422) ·
47
- `assertJson(expected: Record<string, unknown>)` (exact deep match) ·
48
- `assertJsonCount(count: number, key?: string)` ·
49
- `assertJsonStructure(keys: string[])` (top-level keys exist) ·
50
- `assertJsonPath(path: string, value: unknown)` (dot-path, deep equal) ·
51
- `assertInertia(component: string, props?: Record<string, unknown>)` ·
52
- `assertCookie(name: string, value?: string)` · `assertCookieMissing(name: string)` ·
53
- `assertHeader(name: string, value?: string)` · `assertHeaderMissing(name: string)`
54
-
55
- ## Awaited response (TestResponse)
56
-
57
- Awaiting yields a `TestResponse` with extras not available on the chain:
58
-
59
- ```typescript
60
- const res = await app.get('/posts')
61
- res.status // number
62
- res.headers // Headers
63
- await res.text() // body string
64
- await res.json<T>() // parsed body
65
- res.assertBadRequest() // 400
66
- res.assertServerError() // 500
67
- res.assertSuccessful() // any 2xx
68
- await res.assertJsonContains({ k: v }) // partial top-level match
69
- await res.assertBodyContains('text')
70
- ```
71
-
72
- ## Patterns
73
-
74
- ```typescript
75
- import { describe, test, expect, beforeAll } from 'bun:test'
76
-
77
- describe('PostController', () => {
78
- let app: TestApp
79
- beforeAll(async () => { app = await TestApp.create() })
80
-
81
- test('store validates input', async () => {
82
- await app.json().post('/posts', {}).assertUnprocessable()
83
- })
84
-
85
- test('store creates post for authed user', async () => {
86
- const csrf = await app.actingAs(user).withCsrf()
87
- await csrf.post('/posts', { title: 'Hi', body: '...' }).assertRedirect('/posts')
88
- })
89
- })
90
- ```
91
-
92
- Validation failures return 422 with `{ message, errors: Record<string, string[]> }` —
93
- assert with `assertJsonPath('errors.title.0', 'Title is required')`.
@@ -1,97 +0,0 @@
1
- ---
2
- name: db-manage
3
- description: Database management for Guren with safety checks. Handles migrations, rollbacks, seeding, resets, and container management. Use when user mentions "database", "migration", "migrate", "rollback", "seed", "reset", "db:up", "db:down", "db:reset", "fresh database", or database-related tasks.
4
- ---
5
-
6
- # Database Management Skill
7
-
8
- You are a database management assistant for the Guren framework.
9
-
10
- ## Your Role
11
-
12
- Help manage database operations safely with proper confirmations.
13
-
14
- ## Commands
15
-
16
- ### Status
17
- ```bash
18
- bunx guren db:status
19
- ```
20
-
21
- ### Migrate
22
- ```bash
23
- bun run db:migrate
24
- ```
25
- - First check database is running
26
- - Show pending migrations
27
-
28
- ### Undoing migrations
29
- Guren migrations are drizzle-kit generated and forward-only — `db:rollback` is
30
- not supported and will explain the alternatives:
31
- - Development: `bunx guren db:reset --seed` (drop everything, re-apply, re-seed)
32
- - Undo an uncommitted migration: delete its folder + journal entry, then `db:reset`
33
- - Production: write a new forward migration that reverses the change
34
-
35
- ### Status
36
- ```bash
37
- bunx guren db:status
38
- ```
39
- - Shows applied/pending state for every generated migration
40
-
41
- ### Fresh (destructive)
42
- ```bash
43
- bunx guren db:fresh
44
- bunx guren db:fresh --seed
45
- ```
46
- - DROPS ALL TABLES
47
- - Require explicit confirmation
48
- - Block in production
49
-
50
- ### Seed
51
- ```bash
52
- bun run db:seed
53
- ```
54
-
55
- ### Reset
56
-
57
- Full reset: stop container, start fresh, migrate, and seed.
58
-
59
- ```bash
60
- bun run db:down && bun run db:up && sleep 3 && bun run db:migrate && bun run db:seed
61
- ```
62
-
63
- - This destroys all existing data in the development database
64
- - The `sleep 3` ensures PostgreSQL is ready before migrations
65
- - ALWAYS confirm with user before running
66
- - If reset fails:
67
- 1. Check if Docker is running
68
- 2. Check if port 54322 is available
69
- 3. Review migration errors if migrations fail
70
-
71
- ### Create Migration
72
- ```bash
73
- bunx guren make:migration <name>
74
- ```
75
- Then provide schema template.
76
-
77
- ### Container Management
78
- ```bash
79
- bun run db:up # Start PostgreSQL
80
- bun run db:down # Stop
81
- bun run db:logs # View logs
82
- ```
83
-
84
- ## Safety Rules
85
-
86
- 1. **Destructive operations** (rollback, fresh, reset):
87
- - Always confirm with user
88
- - Show what will be affected
89
- - Warn about data loss
90
-
91
- 2. **Error handling:**
92
- - DB not running → suggest `bun run db:up`
93
- - Migration failed → show error, suggest rollback
94
-
95
- 3. **Production:**
96
- - Never run destructive commands without --force
97
- - Extra confirmation required
@@ -1,74 +0,0 @@
1
- ---
2
- name: dev-workflow
3
- description: Development workflow commands for a Guren application. Handles dev server startup, building, testing, type checking, and pre-deploy validation. Use when user says "build", "test", "typecheck", "type check", "run tests", "dev server", "start server", "deploy check", "pre-PR", "ready for PR", "ci check". For database operations like migrations, rollbacks, and seeding, use the db-manage skill instead.
4
- ---
5
-
6
- # Development Workflow Skill
7
-
8
- You are a development workflow assistant for a Guren application.
9
-
10
- ## Your Role
11
-
12
- Help users run dev server, builds, tests, type checks, and database operations with intelligent error diagnosis.
13
-
14
- ## Commands
15
-
16
- ### Dev Server
17
-
18
- Start the development server.
19
-
20
- ```bash
21
- bun run dev
22
- ```
23
-
24
- **Prerequisites check before starting:**
25
- 1. Database running? If not: `bun run db:up`
26
- 2. Migrations applied? If not: `bun run db:migrate`
27
-
28
- **After startup:**
29
- - App: `http://localhost:3333`
30
- - MCP endpoint: `http://localhost:3333/_guren/mcp` (dev only, auto-enabled)
31
-
32
- ### Build
33
-
34
- ```bash
35
- bun run build
36
- ```
37
-
38
- **On failure:** Identify the TypeScript/build error and suggest a fix.
39
-
40
- ### Test
41
-
42
- ```bash
43
- # Run all tests
44
- bun run test
45
-
46
- # Run specific test file
47
- bun test tests/controllers/PostController.test.ts
48
-
49
- # Run tests in a directory
50
- bun test tests/models/
51
- ```
52
-
53
- **On failure:** Identify the failing test file and test name, show the error, suggest fixes.
54
-
55
- ### Type Check
56
-
57
- ```bash
58
- bunx tsc --noEmit
59
- ```
60
-
61
- **On failure:** List each error with file:line, show the message, suggest fixes.
62
-
63
- ### Pre-Deploy Check
64
-
65
- Run all checks in order. **Stop and report on first failure:**
66
-
67
- ```bash
68
- bunx tsc --noEmit && bun run build && bun run test
69
- ```
70
-
71
- On success, confirm:
72
- - No type errors found
73
- - Build completed successfully
74
- - All tests passing
@@ -1,195 +0,0 @@
1
- ---
2
- name: feature
3
- description: Generate a complete CRUD feature with all related components in one workflow — Model, Controller, Views, Routes, Tests, Factory, Seeder, Resource. Use when user wants to build out an entire entity at once. Triggers include "full feature", "CRUD", "resource for", "complete setup", "everything for", "build out the X feature", "scaffold everything for", or mentions an entity name with the intent of creating all components (e.g., "I need a Product entity"). For creating a single component, use the scaffold skill instead.
4
- ---
5
-
6
- # Feature Skill
7
-
8
- You are a full-feature scaffolding assistant for the Guren framework.
9
-
10
- > When filling in generated code, follow the API rules in `.claude/rules/` (orm-models, controllers-http, routes-codegen, testing) — they carry the verified signatures.
11
-
12
- ## Your Role
13
-
14
- Generate all components needed for a complete CRUD feature in one workflow. This is the "batteries-included" approach — creating everything an entity needs to work end-to-end with full type safety.
15
-
16
- ## Workflow
17
-
18
- When given a feature name (e.g., "Post", "Product"):
19
-
20
- ### 1. Generate all components
21
-
22
- **Preferred:** Use `make:feature` which generates type-safe code with proper imports:
23
-
24
- ```bash
25
- bunx guren make:feature <Name> --fields "title:string,body:text,published:boolean"
26
- ```
27
-
28
- This generates Validator, Resource, Controller, Views (Index/Show/New/Edit), and Model in one step with:
29
- - Typed page props (no `any`)
30
- - `route()` helper for all URLs
31
- - `ApiRoutes` for form data types
32
- - `RouteErrors` for validation error types
33
-
34
- **Or generate individually:**
35
-
36
- ```bash
37
- bunx guren make:model <Name>
38
- bunx guren make:migration create_<names>_table
39
- bunx guren make:controller <Name>
40
- bunx guren make:view <names>/Index
41
- bunx guren make:view <names>/Show
42
- bunx guren make:view <names>/New
43
- bunx guren make:view <names>/Edit
44
- bunx guren make:route <names>
45
- bunx guren make:test controllers/<Name>Controller --runner=vitest
46
- bunx guren make:factory <Name> --model=<Name>
47
- bunx guren make:seeder <Name>
48
- bunx guren make:resource <Name> --model=<Name>
49
- ```
50
-
51
- When using individual commands, you must also create a Validator file manually at `app/Http/Validators/<Name>Validator.ts`:
52
-
53
- ```typescript
54
- import { z } from 'zod'
55
-
56
- export const <Name>PayloadSchema = z.object({
57
- // Define fields matching your schema
58
- title: z.string().trim().min(1),
59
- body: z.string().trim().min(1),
60
- })
61
-
62
- export type <Name>Payload = z.infer<typeof <Name>PayloadSchema>
63
-
64
- export const <Name>IdParamSchema = z.object({
65
- id: z.coerce.number().int().positive(),
66
- })
67
- ```
68
-
69
- This Validator is needed for both controller validation and route body schema binding.
70
-
71
- ### 2. Register routes with body schemas
72
-
73
- When registering routes in `routes/web.ts`, **always attach Zod body schemas** to mutation routes. This enables codegen to extract types for the frontend:
74
-
75
- ```typescript
76
- import <Name>Controller from '../app/Http/Controllers/<Name>Controller.js'
77
- import { <Name>PayloadSchema } from '../app/Http/Validators/<Name>Validator.js'
78
-
79
- router.group('/<names>', (<names>) => {
80
- <names>.get('/', [<Name>Controller, 'index']).name('<names>.index')
81
- <names>.get('/new', [<Name>Controller, 'create']).name('<names>.create')
82
- <names>.get('/:id', [<Name>Controller, 'show']).name('<names>.show')
83
- <names>.get('/:id/edit', [<Name>Controller, 'edit']).name('<names>.edit')
84
- <names>.post('/', { name: '<names>.store', body: <Name>PayloadSchema }, [<Name>Controller, 'store'])
85
- <names>.put('/:id', { name: '<names>.update', body: <Name>PayloadSchema }, [<Name>Controller, 'update'])
86
- })
87
- ```
88
-
89
- Where `<Name>` is PascalCase singular (e.g., `Post`) and `<names>` is kebab-case plural (e.g., `posts`).
90
-
91
- ### 3. Run codegen
92
-
93
- ```bash
94
- bunx guren codegen
95
- ```
96
-
97
- This generates typed route helpers and API client types in `.guren/`.
98
-
99
- ### 4. Report created files and next steps
100
-
101
- - Add table schema to `db/schema.ts`
102
- - Run migration: `bun run db:migrate`
103
-
104
- ## Type Safety Patterns
105
-
106
- Generated views follow these patterns for end-to-end type safety:
107
-
108
- ### Form pages (New/Edit) — derive types from ApiRoutes
109
-
110
- ```typescript
111
- import type { ApiRoutes } from '../../../../.guren/api-client.gen'
112
- import type { RouteErrors } from '@guren/inertia-client/typed-forms'
113
- import { route } from '../../../../.guren/routes.gen'
114
-
115
- type <Name>FormData = ApiRoutes['<names>.store']['body']
116
-
117
- // Form submission uses route() helper
118
- form.post(route('<names>.store'))
119
- form.put(route('<names>.update', { id: <name>.id }))
120
- ```
121
-
122
- ### List/Detail pages — typed props from Resource
123
-
124
- ```typescript
125
- import type { PaginatedPageProps } from '@guren/core'
126
- import type { <Name>ResourceData } from '../../../../app/Http/Resources/<Name>Resource.js'
127
- import { route } from '../../../../.guren/routes.gen'
128
-
129
- interface Props extends PaginatedPageProps<<Name>ResourceData> {}
130
-
131
- // Navigation uses route() helper
132
- <Link href={route('<names>.show', { id: <name>.id })}>
133
- ```
134
-
135
- ### Error types — RouteErrors with message field
136
-
137
- ```typescript
138
- interface Props {
139
- errors?: RouteErrors<<Name>FormData> & { message?: string }
140
- }
141
- ```
142
-
143
- ### Models — define fillable for mass assignment protection
144
-
145
- Always add `fillable` to generated models. This is the second defense layer after Zod validation — it prevents unintended fields from reaching the database even if the controller validation is bypassed or misconfigured:
146
-
147
- ```typescript
148
- export class <Name> extends defineModel(<names>) {
149
- static fillable = ['title', 'body', 'authorId'] // only these fields pass to create()/update()
150
- }
151
- ```
152
-
153
- For User models, also define `guarded` to explicitly protect sensitive fields:
154
-
155
- ```typescript
156
- export class User extends AuthenticatableModel<UserRecord> {
157
- static fillable = ['name', 'email', 'password']
158
- static guarded = ['id', 'passwordHash', 'rememberToken']
159
- }
160
- ```
161
-
162
- ## Generated Structure
163
-
164
- For feature "Post":
165
-
166
- ```
167
- app/
168
- ├── Http/Controllers/PostController.ts
169
- ├── Http/Resources/PostResource.ts
170
- ├── Http/Validators/PostValidator.ts
171
- └── Models/Post.ts
172
- db/
173
- ├── factories/PostFactory.ts
174
- ├── migrations/{timestamp}_create_posts_table.sql
175
- └── seeders/PostSeeder.ts
176
- resources/js/pages/posts/
177
- ├── Index.tsx ← typed props, route() links
178
- ├── Show.tsx ← typed props, route() links
179
- ├── New.tsx ← ApiRoutes form type, route() submit
180
- └── Edit.tsx ← ApiRoutes form type, RouteErrors, route() submit
181
- tests/controllers/PostController.test.ts
182
- ```
183
-
184
- ## Schema Example
185
-
186
- ```typescript
187
- // db/schema.ts
188
- export const posts = pgTable('posts', {
189
- id: serial('id').primaryKey(),
190
- title: varchar('title', { length: 255 }).notNull(),
191
- content: text('content'),
192
- createdAt: timestamp('created_at').defaultNow(),
193
- updatedAt: timestamp('updated_at').defaultNow(),
194
- })
195
- ```