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,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,8 +0,0 @@
1
- {
2
- "mcpServers": {
3
- "guren": {
4
- "type": "http",
5
- "url": "http://localhost:3333/_guren/mcp"
6
- }
7
- }
8
- }
@@ -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) |