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.
- package/dist/cli.js +27 -5
- package/package.json +1 -1
- package/templates/api-only/.env.example +3 -0
- package/templates/api-only/config/database.ts +13 -1
- package/templates/api-only/package.json +1 -0
- package/templates/api-only/tsconfig.json +1 -1
- package/templates/default/.env.example +3 -0
- package/templates/default/.guren/api-client.gen.ts +1 -1
- package/templates/default/app/Http/Controllers/HomeController.ts +1 -1
- package/templates/default/config/database.ts +13 -1
- package/templates/default/package.json +1 -0
- package/templates/default/resources/js/app.tsx +1 -1
- package/templates/default/tsconfig.json +1 -1
- package/templates/default-ssr/resources/js/ssr.tsx +1 -1
- package/templates/default/.claude/agents/code-review.md +0 -130
- package/templates/default/.claude/agents/test-writer.md +0 -192
- package/templates/default/.claude/rules/controllers-http.md +0 -95
- package/templates/default/.claude/rules/orm-models.md +0 -118
- package/templates/default/.claude/rules/routes-codegen.md +0 -96
- package/templates/default/.claude/rules/testing.md +0 -93
- package/templates/default/.claude/skills/db-manage/SKILL.md +0 -97
- package/templates/default/.claude/skills/dev-workflow/SKILL.md +0 -74
- package/templates/default/.claude/skills/feature/SKILL.md +0 -195
- package/templates/default/.claude/skills/guren-api/SKILL.md +0 -431
- package/templates/default/.claude/skills/scaffold/SKILL.md +0 -83
- package/templates/default/.mcp.json +0 -8
- 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
|
-
```
|