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,431 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: guren-api
|
|
3
|
-
description: Guren framework API documentation, code patterns, and examples. Covers all subsystems — Controllers, Models, Routes, Middleware, Authentication, Authorization, Events, Jobs, Queue, Mail, Cache, Validation, Broadcasting, Notifications, Storage, Scheduling, I18n, Encryption, Health Checks, Error Handling, Container/ServiceProvider, Console Commands, and API Resources. Use when user asks "how to", "how does", "example of", "what is", or needs help understanding any Guren API.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Guren API Documentation Skill
|
|
7
|
-
|
|
8
|
-
You are a documentation assistant for the Guren framework.
|
|
9
|
-
|
|
10
|
-
> The authoritative signature-level API reference lives in `.claude/rules/*.md` (auto-loaded per edited path); this skill is a subsystem tour for interactive Q&A.
|
|
11
|
-
|
|
12
|
-
## Your Role
|
|
13
|
-
|
|
14
|
-
Help users understand and use Guren framework APIs by providing examples, patterns, and source file locations.
|
|
15
|
-
|
|
16
|
-
## Core Subsystems
|
|
17
|
-
|
|
18
|
-
### Controllers
|
|
19
|
-
Source: `packages/server/src/mvc/Controller.ts`
|
|
20
|
-
|
|
21
|
-
```typescript
|
|
22
|
-
import { Controller } from '@guren/core'
|
|
23
|
-
import { pages } from '../../../.guren/pages.gen.js'
|
|
24
|
-
import { PostPayloadSchema, PostIdParamSchema } from '../Validators/PostValidator.js'
|
|
25
|
-
|
|
26
|
-
export default class PostController extends Controller {
|
|
27
|
-
async index() {
|
|
28
|
-
const posts = await Post.all()
|
|
29
|
-
return this.inertia(pages.posts.Index, { posts })
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
async show() {
|
|
33
|
-
const { id } = this.validateParams(PostIdParamSchema) // throws 422
|
|
34
|
-
const post = await Post.findOrFail(id) // throws 404
|
|
35
|
-
return this.inertia(pages.posts.Show, { post })
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
async store() {
|
|
39
|
-
const data = await this.validateBody(PostPayloadSchema) // throws 422
|
|
40
|
-
const user = await this.auth.userOrFail() // throws 401
|
|
41
|
-
const post = await Post.create({ ...data, authorId: user.id })
|
|
42
|
-
return this.redirect('/posts/' + post?.id)
|
|
43
|
-
}
|
|
44
|
-
}
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
> **Note:** Server-side controllers use URL string literals for redirects. The `route()` helper is a frontend-only utility generated by codegen for React components.
|
|
48
|
-
|
|
49
|
-
**Validation helpers** (Zod duck-type — any schema with `safeParse()` works):
|
|
50
|
-
- `this.validateBody<T>(schema): Promise<T>` — parse request body
|
|
51
|
-
- `this.validateQuery<T>(schema): T` — parse query parameters
|
|
52
|
-
- `this.validateParams<T>(schema): T` — parse route parameters
|
|
53
|
-
|
|
54
|
-
All throw `ValidationException` (HTTP 422) on failure.
|
|
55
|
-
|
|
56
|
-
**Auth helpers:**
|
|
57
|
-
- `this.auth.user<T>()` — returns user or null
|
|
58
|
-
- `this.auth.userOrFail<T>()` — returns user or throws `AuthenticationException` (401)
|
|
59
|
-
|
|
60
|
-
### Models
|
|
61
|
-
Source: `packages/orm/src/Model.ts`
|
|
62
|
-
|
|
63
|
-
```typescript
|
|
64
|
-
import { Model } from '@guren/orm'
|
|
65
|
-
import { posts } from '@/db/schema'
|
|
66
|
-
|
|
67
|
-
export class Post extends Model<typeof posts.$inferSelect> {
|
|
68
|
-
static table = posts
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
// Usage
|
|
72
|
-
await Post.find(1) // returns null if not found
|
|
73
|
-
await Post.findOrFail(1) // throws ModelNotFoundException (404)
|
|
74
|
-
await Post.where('published', true).get()
|
|
75
|
-
await Post.create({ title: 'Hello' })
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
`ModelNotFoundException` (source: `packages/orm/src/ModelNotFoundException.ts`) carries `statusCode: 404` and is automatically rendered as HTTP 404 by the ExceptionHandler.
|
|
79
|
-
|
|
80
|
-
**Mass assignment protection** — prevent injection of unintended fields via `create()` / `update()`:
|
|
81
|
-
|
|
82
|
-
```typescript
|
|
83
|
-
export class Post extends defineModel(posts) {
|
|
84
|
-
// Whitelist: only these fields are accepted (recommended)
|
|
85
|
-
static fillable = ['title', 'excerpt', 'body', 'authorId']
|
|
86
|
-
}
|
|
87
|
-
|
|
88
|
-
export class User extends AuthenticatableModel<UserRecord> {
|
|
89
|
-
static override table = users
|
|
90
|
-
// Whitelist for mass assignment
|
|
91
|
-
static fillable = ['name', 'email', 'password']
|
|
92
|
-
// Blacklist: these fields are always stripped (ignored when fillable is set)
|
|
93
|
-
static guarded = ['id', 'passwordHash', 'rememberToken']
|
|
94
|
-
}
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
- `fillable` (whitelist) — only listed fields pass through to `create()` / `update()`; unlisted input keys **throw `MassAssignmentException`** (set `static strictFillable = false` for silent discarding). Use `forceCreate()` / `forceUpdate()` for trusted server-side data.
|
|
98
|
-
- `guarded` (blacklist, default: `['id']`) — listed fields are silently stripped; ignored when `fillable` is set
|
|
99
|
-
- Both are enforced by `Model.filterFillable()`, called automatically before persistence
|
|
100
|
-
- Always define `fillable` on models that accept user input — this is the second defense layer after Zod validation
|
|
101
|
-
|
|
102
|
-
**Relationships** — declare once, eager-load anywhere:
|
|
103
|
-
|
|
104
|
-
```typescript
|
|
105
|
-
// app/Models/User.ts
|
|
106
|
-
export class User extends AuthenticatableModel<UserRecord> {
|
|
107
|
-
static override relationTypes: { posts: HasManyRecord<PostRecord> } = { posts: [] }
|
|
108
|
-
}
|
|
109
|
-
User.hasMany('posts', () => import('./Post.js').then((m) => m.Post), 'authorId', 'id')
|
|
110
|
-
|
|
111
|
-
// app/Models/Post.ts
|
|
112
|
-
export class Post extends defineModel(posts) {
|
|
113
|
-
static override relationTypes: { author: BelongsToRecord<UserRecord> } = { author: null }
|
|
114
|
-
}
|
|
115
|
-
Post.belongsTo('author', () => import('./User.js').then((m) => m.User), 'authorId', 'id')
|
|
116
|
-
|
|
117
|
-
// Eager loading (typed via relationTypes)
|
|
118
|
-
await User.with('posts') // users[0].posts: PostRecord[]
|
|
119
|
-
await User.with('posts.comments') // nested, dot notation
|
|
120
|
-
await User.where('active', true).with('posts').get() // QueryBuilder
|
|
121
|
-
await User.findWith(1, 'posts') // single record + relations
|
|
122
|
-
await User.withCount('posts') // users[0].postsCount: number (no rows loaded)
|
|
123
|
-
await Post.withPaginate('author', { page: 1 }) // paginated + relations
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
Also available: `hasOne`, `belongsToMany(name, related, pivotTable, foreignPivotKey, relatedPivotKey, parentKey?, relatedKey?)`, `hasManyThrough`, `morphMany`/`morphTo`. There are **no `attach`/`detach`/`sync` pivot helpers and no `firstOrCreate`/`updateOrCreate`** — manage pivot rows via a model on the pivot table (`PivotModel.create(...)` / `PivotModel.delete(...)`), and hand-roll find-or-create with `Model.first(where)` + `Model.create(...)`. Full guide: `docs/en/guides/database.md` (Relationships section).
|
|
127
|
-
|
|
128
|
-
### Routes
|
|
129
|
-
Source: `packages/server/src/mvc/Router.ts`
|
|
130
|
-
|
|
131
|
-
```typescript
|
|
132
|
-
import { Router, requireAuthenticated } from '@guren/core'
|
|
133
|
-
import { PostPayloadSchema } from '../app/Http/Validators/PostValidator.js'
|
|
134
|
-
|
|
135
|
-
export function registerWebRoutes(router: Router): void {
|
|
136
|
-
router.aliasMiddleware('auth', requireAuthenticated({ redirectTo: '/login' }))
|
|
137
|
-
|
|
138
|
-
router.get('/posts', [PostController, 'index']).name('posts.index')
|
|
139
|
-
// Attach body schema to mutation routes for codegen type extraction
|
|
140
|
-
router.post('/posts', { name: 'posts.store', body: PostPayloadSchema }, [PostController, 'store'])
|
|
141
|
-
router.put('/posts/:id', { name: 'posts.update', body: PostPayloadSchema }, [PostController, 'update'])
|
|
142
|
-
|
|
143
|
-
router.middleware('auth').group((auth) => {
|
|
144
|
-
auth.get('/dashboard', [DashboardController, 'index'])
|
|
145
|
-
})
|
|
146
|
-
}
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
**Route contract options** — attach `body`, `params`, `query` schemas to routes:
|
|
150
|
-
- Schemas are metadata for codegen (not double-validated for Controller actions)
|
|
151
|
-
- `bunx guren codegen` extracts schemas → generates typed `ApiRoutes` interface
|
|
152
|
-
- Frontend derives form types via `ApiRoutes['route.name']['body']`
|
|
153
|
-
|
|
154
|
-
### End-to-End Type Safety
|
|
155
|
-
Source: `packages/cli/src/api-client-types.ts`, `packages/inertia-client/src/typed-forms.ts`
|
|
156
|
-
|
|
157
|
-
Guren provides bidirectional type safety between frontend forms and backend validation:
|
|
158
|
-
|
|
159
|
-
```
|
|
160
|
-
Zod schema (Validator) → Route body option → codegen → ApiRoutes → Frontend form type
|
|
161
|
-
→ Controller.validateBody() → Runtime validation (422 on failure)
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
**1. Define schema once** (Validator file):
|
|
165
|
-
```typescript
|
|
166
|
-
export const PostPayloadSchema = z.object({ title: z.string().min(1), body: z.string().min(1) })
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
**2. Attach to route** (routes/web.ts):
|
|
170
|
-
```typescript
|
|
171
|
-
router.post('/posts', { name: 'posts.store', body: PostPayloadSchema }, [PostController, 'store'])
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
**3. Frontend derives types** (after `bunx guren codegen`):
|
|
175
|
-
```typescript
|
|
176
|
-
import type { ApiRoutes } from '../../../../.guren/api-client.gen'
|
|
177
|
-
import type { RouteErrors } from '@guren/inertia-client/typed-forms'
|
|
178
|
-
import { route } from '../../../../.guren/routes.gen'
|
|
179
|
-
|
|
180
|
-
type PostFormData = ApiRoutes['posts.store']['body'] // { title: string; body: string }
|
|
181
|
-
type PostErrors = RouteErrors<PostFormData> // Partial<Record<'title' | 'body', string | string[]>>
|
|
182
|
-
|
|
183
|
-
// Typed form submission
|
|
184
|
-
form.post(route('posts.store'))
|
|
185
|
-
|
|
186
|
-
// Typed navigation
|
|
187
|
-
<Link href={route('posts.show', { id: post.id })}>
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
**4. Controller validates at runtime** (same schema):
|
|
191
|
-
```typescript
|
|
192
|
-
const data = await this.validateBody(PostPayloadSchema) // throws 422, returns typed data
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
### Middleware
|
|
196
|
-
Source: `packages/server/src/http/middleware/`
|
|
197
|
-
|
|
198
|
-
```typescript
|
|
199
|
-
import { defineMiddleware } from '@guren/core'
|
|
200
|
-
|
|
201
|
-
export const logRequest = defineMiddleware(async (ctx, next) => {
|
|
202
|
-
console.log(ctx.req.method, ctx.req.url)
|
|
203
|
-
await next()
|
|
204
|
-
})
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
### Authentication
|
|
208
|
-
Source: `packages/server/src/auth/`
|
|
209
|
-
|
|
210
|
-
```typescript
|
|
211
|
-
import { Router, requireAuthenticated } from '@guren/core'
|
|
212
|
-
|
|
213
|
-
const router = new Router()
|
|
214
|
-
.aliasMiddleware('auth', requireAuthenticated({ redirectTo: '/login' }))
|
|
215
|
-
|
|
216
|
-
router.middleware('auth').group((auth) => {
|
|
217
|
-
// Protected routes
|
|
218
|
-
})
|
|
219
|
-
|
|
220
|
-
// In controller
|
|
221
|
-
const user = await this.auth.user() // returns user | null
|
|
222
|
-
const user = await this.auth.userOrFail() // throws AuthenticationException (401)
|
|
223
|
-
const isLoggedIn = await this.auth.check() // returns boolean
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
Additional auth features:
|
|
227
|
-
- API Tokens: `packages/server/src/auth/api-token.ts`
|
|
228
|
-
- Email Verification: `packages/server/src/auth/email-verification.ts`
|
|
229
|
-
- Password Reset: `packages/server/src/auth/password-reset.ts`
|
|
230
|
-
|
|
231
|
-
## Extended Subsystems
|
|
232
|
-
|
|
233
|
-
### Authorization (Gate & Policy)
|
|
234
|
-
Source: `packages/server/src/authorization/`
|
|
235
|
-
|
|
236
|
-
- `Gate.ts` — Define abilities and policies
|
|
237
|
-
- `Policy.ts` — Resource-based authorization
|
|
238
|
-
- `middleware.ts` — Route-level authorization middleware
|
|
239
|
-
|
|
240
|
-
### Events & Listeners
|
|
241
|
-
Source: `packages/server/src/events/`
|
|
242
|
-
|
|
243
|
-
- `Event.ts` — Base event class
|
|
244
|
-
- `EventManager.ts` — Event dispatcher
|
|
245
|
-
- `Listener.ts` — Base listener class
|
|
246
|
-
- `builtin.ts` — Built-in framework events
|
|
247
|
-
|
|
248
|
-
Register events in `app/Providers/EventServiceProvider.ts`.
|
|
249
|
-
|
|
250
|
-
### Jobs & Queue
|
|
251
|
-
Source: `packages/server/src/queue/`
|
|
252
|
-
|
|
253
|
-
- `Job.ts` — Base job class with `handle()` method
|
|
254
|
-
- `QueueManager.ts` — Queue manager (memory, Redis drivers)
|
|
255
|
-
- `Worker.ts` — Queue worker process
|
|
256
|
-
|
|
257
|
-
Drivers: `packages/server/src/queue/drivers/`
|
|
258
|
-
|
|
259
|
-
### Mail
|
|
260
|
-
Source: `packages/server/src/mail/`
|
|
261
|
-
|
|
262
|
-
- `Mail.ts` — Base mailable class
|
|
263
|
-
- `MailManager.ts` — Mail manager
|
|
264
|
-
|
|
265
|
-
Transports:
|
|
266
|
-
- `MemoryTransport.ts` — For testing
|
|
267
|
-
- `ResendTransport.ts` — Resend API
|
|
268
|
-
- `SmtpTransport.ts` — SMTP
|
|
269
|
-
|
|
270
|
-
### Cache
|
|
271
|
-
Source: `packages/server/src/cache/`
|
|
272
|
-
|
|
273
|
-
- `CacheManager.ts` — Cache manager
|
|
274
|
-
- `TaggedCache.ts` — Tag-based cache invalidation
|
|
275
|
-
|
|
276
|
-
Stores:
|
|
277
|
-
- `MemoryStore.ts` — In-memory
|
|
278
|
-
- `FileStore.ts` — File-based
|
|
279
|
-
- `RedisStore.ts` — Redis
|
|
280
|
-
|
|
281
|
-
### Validation
|
|
282
|
-
Source: `packages/server/src/http/validation/`
|
|
283
|
-
|
|
284
|
-
- `Validator.ts` — Validation engine
|
|
285
|
-
- `rules.ts` — Built-in validation rules
|
|
286
|
-
- `FormRequest.ts` — Form request validation (`packages/server/src/http/FormRequest.ts`)
|
|
287
|
-
|
|
288
|
-
### Broadcasting
|
|
289
|
-
Source: `packages/server/src/broadcasting/`
|
|
290
|
-
|
|
291
|
-
- `BroadcastManager.ts` — Broadcast manager
|
|
292
|
-
|
|
293
|
-
Channels: `Channel.ts`, `PrivateChannel.ts`, `PresenceChannel.ts`
|
|
294
|
-
Drivers: `MemoryDriver.ts`, `RedisDriver.ts`
|
|
295
|
-
|
|
296
|
-
### Notifications
|
|
297
|
-
Source: `packages/server/src/notifications/`
|
|
298
|
-
|
|
299
|
-
- `Notification.ts` — Base notification class
|
|
300
|
-
- `NotificationManager.ts` — Notification dispatcher
|
|
301
|
-
|
|
302
|
-
Channels: `MailChannel.ts`, `SlackChannel.ts`, `DatabaseChannel.ts`, `MemoryChannel.ts`
|
|
303
|
-
|
|
304
|
-
### Storage
|
|
305
|
-
Source: `packages/server/src/storage/`
|
|
306
|
-
|
|
307
|
-
- `StorageManager.ts` — Storage manager
|
|
308
|
-
|
|
309
|
-
Drivers: `LocalDriver.ts`, `MemoryDriver.ts`, `S3Driver.ts`
|
|
310
|
-
|
|
311
|
-
### Scheduling
|
|
312
|
-
Source: `packages/server/src/scheduling/`
|
|
313
|
-
|
|
314
|
-
- `Schedule.ts` — Schedule definition
|
|
315
|
-
- `Scheduler.ts` — Scheduler runner
|
|
316
|
-
- `ScheduledTask.ts` — Individual scheduled task
|
|
317
|
-
- `CronParser.ts` — Cron expression parser
|
|
318
|
-
|
|
319
|
-
### I18n (Internationalization)
|
|
320
|
-
Source: `packages/server/src/i18n/`
|
|
321
|
-
|
|
322
|
-
- `I18nManager.ts` — I18n manager
|
|
323
|
-
- `Translator.ts` — Translation engine
|
|
324
|
-
- `pluralization.ts` — Pluralization rules
|
|
325
|
-
|
|
326
|
-
Loaders: `JsonLoader.ts`, `MemoryLoader.ts`
|
|
327
|
-
|
|
328
|
-
### Encryption
|
|
329
|
-
Source: `packages/server/src/encryption/`
|
|
330
|
-
|
|
331
|
-
- `Encrypter.ts` — Encrypt/decrypt values
|
|
332
|
-
- `Hash.ts` — Hashing utilities
|
|
333
|
-
- `Random.ts` — Secure random generation
|
|
334
|
-
|
|
335
|
-
### Health Checks
|
|
336
|
-
Source: `packages/server/src/health/`
|
|
337
|
-
|
|
338
|
-
- `HealthManager.ts` — Health check manager
|
|
339
|
-
- `HealthCheck.ts` — Base health check
|
|
340
|
-
|
|
341
|
-
Checks: `DatabaseCheck.ts`, `RedisCheck.ts`, `CacheCheck.ts`, `MemoryCheck.ts`, `StorageCheck.ts`, `CustomCheck.ts`
|
|
342
|
-
|
|
343
|
-
### Error Handling
|
|
344
|
-
Source: `packages/server/src/errors/`
|
|
345
|
-
|
|
346
|
-
- `ExceptionHandler.ts` — Global exception handler (supports duck-typed `statusCode` property)
|
|
347
|
-
- `HttpException.ts` — Base HTTP exception
|
|
348
|
-
- `debug-page.ts` — Debug error page
|
|
349
|
-
|
|
350
|
-
Exceptions: `NotFoundHttpException.ts`, `ValidationException.ts`, `AuthenticationException.ts`, `AuthorizationException.ts`, `MethodNotAllowedException.ts`
|
|
351
|
-
|
|
352
|
-
The ExceptionHandler automatically handles:
|
|
353
|
-
- `HttpException` subclasses → uses their status code
|
|
354
|
-
- Any error with a `statusCode` property (duck-typed) → uses that status code (e.g., `ModelNotFoundException` → 404)
|
|
355
|
-
- Other errors → 500 (message hidden unless debug mode)
|
|
356
|
-
|
|
357
|
-
### Container & Service Providers
|
|
358
|
-
Source: `packages/server/src/container/`
|
|
359
|
-
|
|
360
|
-
- `Container.ts` — IoC container
|
|
361
|
-
- `ServiceProvider.ts` — Base service provider
|
|
362
|
-
|
|
363
|
-
Built-in providers: `packages/server/src/providers/`
|
|
364
|
-
|
|
365
|
-
### Console Commands
|
|
366
|
-
Source: `packages/server/src/console/`
|
|
367
|
-
|
|
368
|
-
- `Command.ts` — Base command class
|
|
369
|
-
- `ConsoleKernel.ts` — Console kernel
|
|
370
|
-
- `Input.ts` / `Output.ts` — IO handling
|
|
371
|
-
|
|
372
|
-
### API Resources
|
|
373
|
-
Source: `packages/server/src/http/resources/`
|
|
374
|
-
|
|
375
|
-
- `Resource.ts` — API resource transformer
|
|
376
|
-
- `ResourceCollection.ts` — Collection of resources
|
|
377
|
-
- `Paginator.ts` — Offset-based pagination
|
|
378
|
-
- `CursorPaginator.ts` — Cursor-based pagination
|
|
379
|
-
|
|
380
|
-
### Database (Factory & Seeder)
|
|
381
|
-
Source: `packages/server/src/database/`
|
|
382
|
-
|
|
383
|
-
- `Factory.ts` — Model factory for testing
|
|
384
|
-
- `Seeder.ts` — Database seeder
|
|
385
|
-
- `SeederRunner.ts` — Seeder execution
|
|
386
|
-
|
|
387
|
-
### Logging
|
|
388
|
-
Source: `packages/server/src/logging/`
|
|
389
|
-
|
|
390
|
-
- `LogManager.ts` — Log manager
|
|
391
|
-
- `Logger.ts` — Logger instance
|
|
392
|
-
|
|
393
|
-
Channels: `ConsoleChannel.ts`, `FileChannel.ts`, `DailyFileChannel.ts`
|
|
394
|
-
|
|
395
|
-
### Redis
|
|
396
|
-
Source: `packages/server/src/redis/`
|
|
397
|
-
|
|
398
|
-
- `client.ts` — Redis client
|
|
399
|
-
- Session, rate-limit, API token, email verification, password reset stores
|
|
400
|
-
|
|
401
|
-
## Reference Locations
|
|
402
|
-
|
|
403
|
-
| Subsystem | Source Path |
|
|
404
|
-
|-----------|------------|
|
|
405
|
-
| Controllers | `packages/server/src/mvc/Controller.ts` |
|
|
406
|
-
| Models | `packages/orm/src/Model.ts` |
|
|
407
|
-
| Routes | `packages/server/src/mvc/Route.ts` |
|
|
408
|
-
| Auth | `packages/server/src/auth/` |
|
|
409
|
-
| Authorization | `packages/server/src/authorization/` |
|
|
410
|
-
| Events | `packages/server/src/events/` |
|
|
411
|
-
| Queue/Jobs | `packages/server/src/queue/` |
|
|
412
|
-
| Mail | `packages/server/src/mail/` |
|
|
413
|
-
| Cache | `packages/server/src/cache/` |
|
|
414
|
-
| Validation | `packages/server/src/http/validation/` |
|
|
415
|
-
| Broadcasting | `packages/server/src/broadcasting/` |
|
|
416
|
-
| Notifications | `packages/server/src/notifications/` |
|
|
417
|
-
| Storage | `packages/server/src/storage/` |
|
|
418
|
-
| Scheduling | `packages/server/src/scheduling/` |
|
|
419
|
-
| I18n | `packages/server/src/i18n/` |
|
|
420
|
-
| Encryption | `packages/server/src/encryption/` |
|
|
421
|
-
| Health Checks | `packages/server/src/health/` |
|
|
422
|
-
| Error Handling | `packages/server/src/errors/` |
|
|
423
|
-
| Container | `packages/server/src/container/` |
|
|
424
|
-
| Console | `packages/server/src/console/` |
|
|
425
|
-
| API Resources | `packages/server/src/http/resources/` |
|
|
426
|
-
| Database/Seeder | `packages/server/src/database/` |
|
|
427
|
-
| Logging | `packages/server/src/logging/` |
|
|
428
|
-
| Redis | `packages/server/src/redis/` |
|
|
429
|
-
| Example App | `examples/blog/` |
|
|
430
|
-
| API Example | `examples/api/` |
|
|
431
|
-
| Docs | `web/` |
|
|
@@ -1,83 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: scaffold
|
|
3
|
-
description: Generate individual Guren framework components using bunx guren make:* CLI commands. Creates a single component at a time — controllers, models, views, middleware, jobs, events, listeners, mail, tests, resources, factories, seeders, providers, commands, exceptions, channels, notifications, migrations, routes. Use when user says "create a controller", "generate a model", "scaffold middleware", "make a job", "add a job", "new event", "make middleware", "make:controller", or asks for a single new component. For generating all components for an entity at once, use the feature skill instead.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Scaffold Skill
|
|
7
|
-
|
|
8
|
-
You are a component scaffolding assistant for the Guren framework.
|
|
9
|
-
|
|
10
|
-
> When editing the generated files, the verified API signatures live in `.claude/rules/*.md` (auto-loaded per edited path).
|
|
11
|
-
|
|
12
|
-
## Your Role
|
|
13
|
-
|
|
14
|
-
Help users generate individual framework components using the Guren CLI. Understand context and suggest related components.
|
|
15
|
-
|
|
16
|
-
## Available CLI Commands
|
|
17
|
-
|
|
18
|
-
```bash
|
|
19
|
-
bunx guren make:controller <Name>
|
|
20
|
-
bunx guren make:model <Name>
|
|
21
|
-
bunx guren make:view <path>
|
|
22
|
-
bunx guren make:middleware <Name>
|
|
23
|
-
bunx guren make:job <Name>
|
|
24
|
-
bunx guren make:event <Name>
|
|
25
|
-
bunx guren make:listener <Name> --event=<EventName>
|
|
26
|
-
bunx guren make:mail <Name>
|
|
27
|
-
bunx guren make:test <Name> --runner=bun|vitest
|
|
28
|
-
bunx guren make:resource <Name> --model=<Model>
|
|
29
|
-
bunx guren make:factory <Name> --model=<Model>
|
|
30
|
-
bunx guren make:seeder <Name>
|
|
31
|
-
bunx guren make:provider <Name>
|
|
32
|
-
bunx guren make:command <Name> --command=<cmd>
|
|
33
|
-
bunx guren make:exception <Name> --status=<code>
|
|
34
|
-
bunx guren make:channel <Name> [--private|--presence]
|
|
35
|
-
bunx guren make:notification <Name>
|
|
36
|
-
bunx guren make:migration <name>
|
|
37
|
-
bunx guren make:route <Name>
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## Workflow
|
|
41
|
-
|
|
42
|
-
1. Determine what component type the user needs
|
|
43
|
-
2. Get the name if not provided
|
|
44
|
-
3. Run the appropriate CLI command
|
|
45
|
-
4. After creation, suggest related components:
|
|
46
|
-
- Controller → Model, Views, Tests
|
|
47
|
-
- Model → Migration, Factory, Seeder
|
|
48
|
-
- Event → Listener
|
|
49
|
-
- Job → Event (if triggered by event)
|
|
50
|
-
- Mail → Notification (if part of notification flow)
|
|
51
|
-
|
|
52
|
-
## Output Locations
|
|
53
|
-
|
|
54
|
-
| Component | Location |
|
|
55
|
-
|-----------|----------|
|
|
56
|
-
| Controller | `app/Http/Controllers/{Name}Controller.ts` |
|
|
57
|
-
| Model | `app/Models/{Name}.ts` |
|
|
58
|
-
| View | `resources/js/pages/{path}.tsx` |
|
|
59
|
-
| Middleware | `app/Http/Middleware/{Name}Middleware.ts` |
|
|
60
|
-
| Job | `app/Jobs/{Name}Job.ts` |
|
|
61
|
-
| Event | `app/Events/{Name}.ts` |
|
|
62
|
-
| Listener | `app/Listeners/{Name}Listener.ts` |
|
|
63
|
-
| Mail | `app/Mail/{Name}Mail.ts` |
|
|
64
|
-
| Test | `tests/{path}/{Name}.test.ts` |
|
|
65
|
-
| Resource | `app/Http/Resources/{Name}Resource.ts` |
|
|
66
|
-
| Factory | `db/factories/{Name}Factory.ts` |
|
|
67
|
-
| Seeder | `db/seeders/{Name}Seeder.ts` |
|
|
68
|
-
| Provider | `app/Providers/{Name}Provider.ts` |
|
|
69
|
-
| Command | `app/Console/Commands/{Name}Command.ts` |
|
|
70
|
-
| Exception | `app/Exceptions/{Name}Exception.ts` |
|
|
71
|
-
| Channel | `app/Broadcasting/{Name}Channel.ts` |
|
|
72
|
-
| Notification | `app/Notifications/{Name}Notification.ts` |
|
|
73
|
-
|
|
74
|
-
## MCP Alternative
|
|
75
|
-
|
|
76
|
-
If the dev server is running, the `guren_make_component` MCP tool can generate individual components without shell access.
|
|
77
|
-
Supported types: controller, model, view, test, route. Other types fall back to CLI.
|
|
78
|
-
|
|
79
|
-
## Example
|
|
80
|
-
|
|
81
|
-
User: "Create a Post controller"
|
|
82
|
-
-> Run: `bunx guren make:controller Post`
|
|
83
|
-
-> Suggest: "Would you also like the Post model and views?"
|
|
@@ -1,173 +0,0 @@
|
|
|
1
|
-
# __APP_TITLE__
|
|
2
|
-
|
|
3
|
-
## Overview
|
|
4
|
-
|
|
5
|
-
A fullstack TypeScript application built with the Guren framework (Laravel-inspired, running on Bun).
|
|
6
|
-
|
|
7
|
-
## AI Agents: Start Here
|
|
8
|
-
|
|
9
|
-
Before exploring `node_modules`, use the built-in introspection commands:
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
bunx guren context # project map: models, routes, controllers, pages (add --json for JSON)
|
|
13
|
-
bunx guren check # validate route ↔ controller ↔ page consistency — run after changes
|
|
14
|
-
bunx guren codegen # regenerate .guren/*.gen.ts typed manifests (also runs via `bun run dev`)
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
Detailed, verified API rules live in `.claude/rules/*.md` and load automatically
|
|
18
|
-
based on the files you are editing (glob-scoped): `orm-models.md` (models, queries,
|
|
19
|
-
relations), `controllers-http.md` (validation, Inertia, auth), `routes-codegen.md`
|
|
20
|
-
(route options, schema binding, codegen), `testing.md` (TestApp assertions).
|
|
21
|
-
Read the matching rule file before reading `node_modules/@guren/*` — it covers the
|
|
22
|
-
exact signatures.
|
|
23
|
-
|
|
24
|
-
## Project Structure
|
|
25
|
-
|
|
26
|
-
```
|
|
27
|
-
app/
|
|
28
|
-
├── Http/
|
|
29
|
-
│ ├── Controllers/ # Request handlers
|
|
30
|
-
│ ├── Middleware/ # HTTP middleware
|
|
31
|
-
│ └── Resources/ # API resource transformers
|
|
32
|
-
├── Models/ # Drizzle ORM models
|
|
33
|
-
├── Events/ # Event classes
|
|
34
|
-
├── Listeners/ # Event listeners
|
|
35
|
-
├── Jobs/ # Queue job classes
|
|
36
|
-
├── Mail/ # Mailable classes
|
|
37
|
-
├── Notifications/ # Notification classes
|
|
38
|
-
├── Providers/ # Service providers
|
|
39
|
-
├── Exceptions/ # Custom exceptions
|
|
40
|
-
└── Console/Commands/ # CLI commands
|
|
41
|
-
bin/
|
|
42
|
-
└── serve.ts # Server entry point
|
|
43
|
-
config/ # Application configuration
|
|
44
|
-
db/
|
|
45
|
-
├── schema.ts # Drizzle table definitions
|
|
46
|
-
├── migrations/ # SQL migration files
|
|
47
|
-
├── factories/ # Model factories
|
|
48
|
-
└── seeders/ # Database seeders
|
|
49
|
-
resources/js/
|
|
50
|
-
├── pages/ # Inertia.js React pages
|
|
51
|
-
├── components/ # Shared React components
|
|
52
|
-
└── layouts/ # Page layouts
|
|
53
|
-
routes/
|
|
54
|
-
├── web.ts # Web routes
|
|
55
|
-
└── api.ts # API routes (if applicable)
|
|
56
|
-
tests/
|
|
57
|
-
├── controllers/ # Controller tests
|
|
58
|
-
└── models/ # Model tests
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
## Development Commands
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
# Start development server
|
|
65
|
-
bun run dev
|
|
66
|
-
|
|
67
|
-
# Generate components
|
|
68
|
-
bunx guren make:controller <Name>
|
|
69
|
-
bunx guren make:model <Name>
|
|
70
|
-
bunx guren make:migration <name>
|
|
71
|
-
bunx guren make:view <path>
|
|
72
|
-
bunx guren make:middleware <Name>
|
|
73
|
-
bunx guren make:job <Name>
|
|
74
|
-
bunx guren make:event <Name>
|
|
75
|
-
bunx guren make:listener <Name> --event=<EventName>
|
|
76
|
-
bunx guren make:mail <Name>
|
|
77
|
-
bunx guren make:test <Name>
|
|
78
|
-
|
|
79
|
-
# Database workflow: edit db/schema.ts first, then
|
|
80
|
-
bunx guren make:migration <name> # generate SQL migration via drizzle-kit into db/migrations/
|
|
81
|
-
bun run db:migrate # apply pending migrations
|
|
82
|
-
bunx guren db:status # show applied/pending state
|
|
83
|
-
bun run db:seed # run seeders
|
|
84
|
-
# Migrations are forward-only (no rollback). Dev reset: bunx guren db:reset --seed
|
|
85
|
-
|
|
86
|
-
# Build & test
|
|
87
|
-
bun run build
|
|
88
|
-
bun run test
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
## MCP Server (AI Agent Integration)
|
|
92
|
-
|
|
93
|
-
`bun run dev` を実行すると、開発サーバーに MCP エンドポイントが自動的に起動します:
|
|
94
|
-
|
|
95
|
-
```
|
|
96
|
-
http://localhost:3333/_guren/mcp
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
`.mcp.json` が設定済みなので、Claude Code / Cursor は自動的に接続します。
|
|
100
|
-
本番環境(`NODE_ENV=production`)では無効化されます。
|
|
101
|
-
|
|
102
|
-
### 利用可能なツール
|
|
103
|
-
|
|
104
|
-
| Tool | 説明 |
|
|
105
|
-
|------|------|
|
|
106
|
-
| `guren_get_context` | プロジェクト構造マップ(models, routes, pages, controllers等) |
|
|
107
|
-
| `guren_check` | route↔controller↔page の整合性検証 |
|
|
108
|
-
| `guren_list_models` | モデル一覧(リレーション、soft deletes、auth trait含む) |
|
|
109
|
-
| `guren_generate_guidelines` | プロジェクト固有コーディング規約の自動生成 |
|
|
110
|
-
| `guren_doctor` | プロジェクト健全性チェック + 次のアクション提案 |
|
|
111
|
-
| `guren_make_feature` | CRUD 一括スキャフォールド |
|
|
112
|
-
| `guren_make_component` | 個別コンポーネント生成 |
|
|
113
|
-
| `guren_codegen` | 型マニフェスト生成(routes.gen.ts, pages.gen.ts等) |
|
|
114
|
-
|
|
115
|
-
## Architecture Overview
|
|
116
|
-
|
|
117
|
-
The request lifecycle: `routes/web.ts` registers routes on a `Router`, each pointing
|
|
118
|
-
at a `[Controller, 'method']` tuple. Controllers validate input with Zod schemas,
|
|
119
|
-
query models, and render Inertia pages or JSON.
|
|
120
|
-
|
|
121
|
-
```typescript
|
|
122
|
-
// routes/web.ts
|
|
123
|
-
router.get('/posts', [PostController, 'index']).name('posts.index')
|
|
124
|
-
router.post('/posts', { name: 'posts.store', body: CreatePostSchema }, [PostController, 'store'])
|
|
125
|
-
|
|
126
|
-
// app/Http/Controllers/PostController.ts
|
|
127
|
-
export class PostController extends Controller {
|
|
128
|
-
async store() {
|
|
129
|
-
const data = await this.validateBody(CreatePostSchema) // 422 on failure
|
|
130
|
-
const user = await this.auth.userOrFail() // 401 if unauthenticated
|
|
131
|
-
const post = await Post.create({ ...data, authorId: user.id })
|
|
132
|
-
return this.redirect('/posts')
|
|
133
|
-
}
|
|
134
|
-
}
|
|
135
|
-
|
|
136
|
-
// app/Models/Post.ts
|
|
137
|
-
export class Post extends defineModel(posts) {
|
|
138
|
-
static fillable = ['title', 'body', 'authorId']
|
|
139
|
-
}
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
- Models: `await Post.findOrFail(id)` throws a 404; `Post.where(...)` starts a query
|
|
143
|
-
builder chain. Full API in `.claude/rules/orm-models.md`.
|
|
144
|
-
- Attaching a Zod schema to a route both validates the request automatically and
|
|
145
|
-
feeds `bunx guren codegen` typed manifests. Details in `.claude/rules/routes-codegen.md`.
|
|
146
|
-
- Middleware: `defineMiddleware(async (c, next) => { ... })` from `@guren/core`;
|
|
147
|
-
register aliases via `router.aliasMiddleware('auth', requireAuthenticated({ redirectTo: '/login' }))`.
|
|
148
|
-
|
|
149
|
-
## Testing
|
|
150
|
-
|
|
151
|
-
Uses `bun:test` + `@guren/testing`. Requests run in-process via `app.fetch()` — no server needed.
|
|
152
|
-
|
|
153
|
-
```typescript
|
|
154
|
-
import { TestApp } from '@guren/testing'
|
|
155
|
-
|
|
156
|
-
const app = await TestApp.create()
|
|
157
|
-
await app.get('/posts').assertOk()
|
|
158
|
-
await app.actingAs(user).json().post('/posts', { title: 'Hi' }).assertCreated()
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
Full client and assertion reference: `.claude/rules/testing.md`.
|
|
162
|
-
|
|
163
|
-
## Key Files
|
|
164
|
-
|
|
165
|
-
| Path | Purpose |
|
|
166
|
-
|------|---------|
|
|
167
|
-
| `bin/serve.ts` | Server entry point |
|
|
168
|
-
| `config/` | Application configuration |
|
|
169
|
-
| `db/schema.ts` | Database table definitions |
|
|
170
|
-
| `routes/web.ts` | Web route definitions |
|
|
171
|
-
| `app/Providers/` | Service providers |
|
|
172
|
-
| `resources/js/pages/` | React page components |
|
|
173
|
-
| `.claude/rules/` | Glob-scoped API rules (auto-loaded per edited path) |
|