create-guren-app 1.4.0 → 1.6.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 (60) hide show
  1. package/README.md +17 -1
  2. package/dist/cli.js +176 -234
  3. package/package.json +1 -1
  4. package/templates/api-only/.github/workflows/ci.yml +35 -0
  5. package/templates/api-only/_gitignore +6 -0
  6. package/templates/api-only/docs/adr/0001-record-architecture-decisions.md +10 -5
  7. package/templates/api-only/package.json +5 -5
  8. package/templates/api-only/src/app.ts +27 -4
  9. package/templates/api-only/tests/app.test.ts +24 -0
  10. package/templates/blog/.guren/api-client.gen.ts +184 -0
  11. package/templates/blog/.guren/data.gen.ts +23 -0
  12. package/templates/blog/.guren/pages.gen.ts +99 -0
  13. package/templates/blog/.guren/routes.gen.ts +138 -0
  14. package/templates/blog/README.md +85 -0
  15. package/templates/blog/app/Http/Controllers/Auth/LoginController.ts +30 -0
  16. package/templates/blog/app/Http/Controllers/Auth/RegisterController.ts +28 -0
  17. package/templates/blog/app/Http/Controllers/DashboardController.ts +17 -0
  18. package/templates/blog/app/Http/Controllers/HomeController.ts +22 -0
  19. package/templates/blog/app/Http/Controllers/PostController.ts +83 -0
  20. package/templates/blog/app/Http/Controllers/ProfileController.ts +54 -0
  21. package/templates/blog/app/Http/Resources/PostResource.ts +40 -0
  22. package/templates/blog/app/Http/Validators/LoginValidator.ts +27 -0
  23. package/templates/blog/app/Http/Validators/PostValidator.ts +17 -0
  24. package/templates/blog/app/Http/Validators/ProfileValidator.ts +23 -0
  25. package/templates/blog/app/Http/Validators/RegisterValidator.ts +31 -0
  26. package/templates/blog/app/Models/Post.ts +18 -0
  27. package/templates/blog/app/Models/User.ts +27 -0
  28. package/templates/blog/app/Policies/PostPolicy.ts +32 -0
  29. package/templates/blog/app/Providers/AuthProvider.ts +28 -0
  30. package/templates/blog/app/Providers/AuthorizationProvider.ts +19 -0
  31. package/templates/blog/db/schema.mysql.ts +26 -0
  32. package/templates/blog/db/schema.postgres.ts +22 -0
  33. package/templates/blog/db/schema.sqlite.ts +22 -0
  34. package/templates/blog/db/seeders/001_users.ts +23 -0
  35. package/templates/blog/db/seeders/002_posts.ts +32 -0
  36. package/templates/blog/resources/js/components/Layout.tsx +56 -0
  37. package/templates/blog/resources/js/pages/Home.tsx +55 -0
  38. package/templates/blog/resources/js/pages/auth/Login.tsx +108 -0
  39. package/templates/blog/resources/js/pages/auth/Register.tsx +132 -0
  40. package/templates/blog/resources/js/pages/dashboard/Index.tsx +29 -0
  41. package/templates/blog/resources/js/pages/posts/Edit.tsx +79 -0
  42. package/templates/blog/resources/js/pages/posts/Index.tsx +49 -0
  43. package/templates/blog/resources/js/pages/posts/New.tsx +71 -0
  44. package/templates/blog/resources/js/pages/posts/Show.tsx +55 -0
  45. package/templates/blog/resources/js/pages/profile/Edit.tsx +90 -0
  46. package/templates/blog/routes/auth.ts +22 -0
  47. package/templates/blog/routes/web.ts +34 -0
  48. package/templates/blog/src/app.ts +46 -0
  49. package/templates/blog/tests/HomeController.test.ts +19 -0
  50. package/templates/default/.github/workflows/ci.yml +35 -0
  51. package/templates/default/.guren/api-client.gen.ts +76 -4
  52. package/templates/default/_gitignore +7 -0
  53. package/templates/default/docs/adr/0001-record-architecture-decisions.md +10 -5
  54. package/templates/default/package.json +12 -10
  55. package/templates/default/src/app.ts +27 -4
  56. package/templates/default/tests/HomeController.test.ts +24 -0
  57. package/templates/default/tsconfig.json +1 -0
  58. package/templates/default/types/generated/_gitignore +2 -0
  59. package/templates/api-only/config/database.ts +0 -21
  60. package/templates/default/config/database.ts +0 -21
@@ -1,6 +1,6 @@
1
1
  ---
2
- kind: adr
3
- status: accepted
2
+ type: adr
3
+ status: stable
4
4
  entities: []
5
5
  related: []
6
6
  ---
@@ -24,20 +24,25 @@ bunx guren make:adr "Title of the decision"
24
24
  bunx guren make:adr "Title" --entity Invoice # prefills the links below
25
25
  ```
26
26
 
27
- Each ADR declares what it governs in its frontmatter:
27
+ ADRs are OKF (Open Knowledge Format) concept documents: markdown with
28
+ YAML frontmatter, where `type` is the one required field. Each ADR
29
+ declares what it governs in its frontmatter:
28
30
 
29
31
  - `entities: [Invoice]` — model class names the decision affects.
30
32
  `bunx guren context Invoice` then surfaces this ADR to anyone (human
31
33
  or agent) working on that model.
32
34
  - `related: [app/Http/Controllers/InvoiceController.ts]` — files or
33
35
  globs the decision touches.
34
- - `status:` — `draft` → `accepted`; mark `superseded` when replaced
36
+ - `status:` — `draft` → `stable`; mark `deprecated` when replaced
35
37
  (and write the replacement).
38
+ - `generated: { by, at }` — who wrote it (`human:<id>` or an agent's
39
+ `<producer>/<version>`); `verified: { by, at }` — who confirmed it.
36
40
 
37
41
  Once declared, the links are verified: `bunx guren check` reports a
38
42
  renamed file a doc points at, or a removed model a doc names, as a
39
43
  failure, and `bunx guren check --docs` gates CI on it (non-zero exit).
40
- Keep frontmatter current in the same change that moves the code.
44
+ Ordinary markdown links between docs are checked too. Keep frontmatter
45
+ current in the same change that moves the code.
41
46
 
42
47
  ## Consequences
43
48
 
@@ -4,7 +4,7 @@
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "scripts": {
7
- "dev": "bun run codegen && GUREN_MCP=1 bun run dev:server",
7
+ "dev": "bun run codegen && GUREN_MCP=1 GUREN_DOCS=1 bun run dev:server",
8
8
  "dev:server": "bun --hot bin/serve.ts",
9
9
  "console": "bun bin/console.ts",
10
10
  "codegen": "bunx guren codegen --routes routes/api.ts --force",
@@ -18,13 +18,13 @@
18
18
  "test": "bun test"
19
19
  },
20
20
  "dependencies": {
21
- "@guren/cli": "^1.0.0",
22
- "@guren/core": "^1.0.0",
23
- "@guren/orm": "^1.0.0",
21
+ "@guren/cli": "^2.1.0",
22
+ "@guren/core": "^1.5.0",
23
+ "@guren/orm": "^2.1.0",
24
24
  "drizzle-orm": "1.0.0-rc.4"
25
25
  },
26
26
  "devDependencies": {
27
- "@guren/testing": "^1.0.0",
27
+ "@guren/testing": "^1.3.0",
28
28
  "bun-types": "^1.3.1",
29
29
  "drizzle-kit": "1.0.0-rc.4",
30
30
  "typescript": "^5.4.0"
@@ -2,13 +2,36 @@ import { createApp } from '@guren/core'
2
2
  import DatabaseProvider from '../app/Providers/DatabaseProvider.js'
3
3
  import { registerApiRoutes } from '../routes/api.js'
4
4
 
5
+ // The Host header is client-controlled, so production should answer only to the
6
+ // host this app is deployed as, which APP_URL carries.
7
+ //
8
+ // Read at module scope, where not every platform has populated process.env yet
9
+ // (the Cloudflare worker imports this module before wrangler `vars` land). A
10
+ // missing value therefore warns and leaves the check off, rather than throwing
11
+ // and stopping the app from booting at all. Emailed links do not depend on this
12
+ // — app/Auth/AppUrl.ts resolves those per request and fails closed there.
13
+ function hostAuthorization() {
14
+ const exclude = ['/health']
15
+
16
+ if (process.env.NODE_ENV !== 'production') {
17
+ return { allowedHosts: ['localhost:*', '127.0.0.1:*'], exclude }
18
+ }
19
+
20
+ const appUrl = process.env.APP_URL?.trim()
21
+ if (!appUrl) {
22
+ console.warn('[app] APP_URL is not set — host authorization is disabled. Set it to the public base URL of this app.')
23
+ return false
24
+ }
25
+
26
+ // `hostname:*` rather than the bare host: the hostname is the security
27
+ // boundary, and a proxy may or may not include the default port in `Host`.
28
+ return { allowedHosts: [`${new URL(appUrl).hostname}:*`], exclude }
29
+ }
30
+
5
31
  const app = createApp({
6
32
  routes: registerApiRoutes,
7
33
  providers: [DatabaseProvider],
8
- hostAuthorization: process.env.NODE_ENV === 'production' ? false : {
9
- allowedHosts: ['localhost:*', '127.0.0.1:*'],
10
- exclude: ['/health'],
11
- },
34
+ hostAuthorization: hostAuthorization(),
12
35
  })
13
36
 
14
37
  export default app
@@ -0,0 +1,24 @@
1
+ import { describe, it } from 'bun:test'
2
+ import { TestApp } from '@guren/testing'
3
+ import DatabaseProvider from '../app/Providers/DatabaseProvider.js'
4
+ import { registerApiRoutes } from '../routes/api.js'
5
+
6
+ describe('api', () => {
7
+ it('answers the health check', async () => {
8
+ const app = await TestApp.create({
9
+ routes: registerApiRoutes,
10
+ providers: [DatabaseProvider],
11
+ })
12
+
13
+ await app.get('/health').assertOk()
14
+ })
15
+
16
+ it('serves the API root', async () => {
17
+ const app = await TestApp.create({
18
+ routes: registerApiRoutes,
19
+ providers: [DatabaseProvider],
20
+ })
21
+
22
+ await app.get('/api/v1').assertOk()
23
+ })
24
+ })
@@ -0,0 +1,184 @@
1
+ // Generated — DO NOT EDIT
2
+ // Run `guren codegen` to regenerate.
3
+
4
+ /**
5
+ * Typed API route registry.
6
+ * Use with `createApiClient<ApiRoutes>()` for end-to-end type safety.
7
+ *
8
+ * `body` is the *request* shape — what you send. Coercing schemas are rendered
9
+ * as they travel: `z.coerce.date()` is a `string` here, not the `Date` the
10
+ * controller ends up with. `response` is the parsed shape you get back.
11
+ */
12
+ export interface ApiRoutes {
13
+ 'dashboard': {
14
+ method: 'GET'
15
+ path: '/dashboard'
16
+ params: Record<string, never>
17
+ }
18
+ 'home': {
19
+ method: 'GET'
20
+ path: '/'
21
+ params: Record<string, never>
22
+ }
23
+ 'login': {
24
+ method: 'GET'
25
+ path: '/login'
26
+ params: Record<string, never>
27
+ }
28
+ 'login.store': {
29
+ method: 'POST'
30
+ path: '/login'
31
+ params: Record<string, never>
32
+ }
33
+ 'logout': {
34
+ method: 'POST'
35
+ path: '/logout'
36
+ params: Record<string, never>
37
+ }
38
+ 'posts.create': {
39
+ method: 'GET'
40
+ path: '/posts/create'
41
+ params: Record<string, never>
42
+ }
43
+ 'posts.destroy': {
44
+ method: 'DELETE'
45
+ path: '/posts/:id'
46
+ params: { id: string | number }
47
+ }
48
+ 'posts.edit': {
49
+ method: 'GET'
50
+ path: '/posts/:id/edit'
51
+ params: { id: string | number }
52
+ }
53
+ 'posts.index': {
54
+ method: 'GET'
55
+ path: '/posts'
56
+ params: Record<string, never>
57
+ }
58
+ 'posts.show': {
59
+ method: 'GET'
60
+ path: '/posts/:id'
61
+ params: { id: string | number }
62
+ }
63
+ 'posts.store': {
64
+ method: 'POST'
65
+ path: '/posts'
66
+ params: Record<string, never>
67
+ body: { title: string; excerpt: string; body: string }
68
+ }
69
+ 'posts.update': {
70
+ method: 'PUT'
71
+ path: '/posts/:id'
72
+ params: { id: string | number }
73
+ body: { title: string; excerpt: string; body: string }
74
+ }
75
+ 'profile.edit': {
76
+ method: 'GET'
77
+ path: '/profile'
78
+ params: Record<string, never>
79
+ }
80
+ 'profile.update': {
81
+ method: 'PUT'
82
+ path: '/profile'
83
+ params: Record<string, never>
84
+ }
85
+ 'register': {
86
+ method: 'GET'
87
+ path: '/register'
88
+ params: Record<string, never>
89
+ }
90
+ 'register.store': {
91
+ method: 'POST'
92
+ path: '/register'
93
+ params: Record<string, never>
94
+ }
95
+ }
96
+
97
+ export type ApiRouteName = keyof ApiRoutes
98
+
99
+ export type ApiRouteMethod<T extends ApiRouteName> = ApiRoutes[T]['method']
100
+ export type ApiRoutePath<T extends ApiRouteName> = ApiRoutes[T]['path']
101
+ export type ApiRouteParams<T extends ApiRouteName> = ApiRoutes[T]['params']
102
+
103
+ type HasParams<T extends ApiRouteName> =
104
+ [keyof ApiRoutes[T]['params']] extends [never] ? false : true
105
+
106
+ export type ApiRequestOptions<T extends ApiRouteName> =
107
+ HasParams<T> extends true
108
+ ? { params: ApiRouteParams<T>; body?: unknown; query?: Record<string, unknown> }
109
+ : { params?: never; body?: unknown; query?: Record<string, unknown> }
110
+
111
+ /**
112
+ * Create a typed API client for consuming Guren routes.
113
+ *
114
+ * @example
115
+ * ```typescript
116
+ * import type { ApiRoutes } from '@/.guren/api-client.gen'
117
+ *
118
+ * const client = createApiClient<ApiRoutes>({ baseUrl: 'http://localhost:3000' })
119
+ * const posts = await client.request('posts.index')
120
+ * const post = await client.request('posts.show', { params: { id: 1 } })
121
+ * ```
122
+ */
123
+ export function createApiClient<TRoutes extends Record<string, { method: string; path: string; params: unknown }>>(
124
+ config: { baseUrl: string; headers?: Record<string, string> },
125
+ ) {
126
+ return {
127
+ async request<TName extends keyof TRoutes & string>(
128
+ name: TName,
129
+ ...args: [keyof TRoutes[TName]['params']] extends [never]
130
+ ? [options?: { body?: unknown; query?: Record<string, unknown> }]
131
+ : [options: { params: TRoutes[TName]['params']; body?: unknown; query?: Record<string, unknown> }]
132
+ ): Promise<Response> {
133
+ const route = (routes as Record<string, { method: string; path: string }>)[name]
134
+ if (!route) throw new Error(`Route [${name}] not defined.`)
135
+
136
+ const opts = (args as unknown[])[0] as { params?: Record<string, unknown>; body?: unknown; query?: Record<string, unknown> } | undefined
137
+ let path = route.path
138
+ if (opts?.params) {
139
+ for (const [key, value] of Object.entries(opts.params)) {
140
+ path = path.replace(`:${key}`, encodeURIComponent(String(value)))
141
+ }
142
+ }
143
+
144
+ let url = `${config.baseUrl}${path}`
145
+ if (opts?.query) {
146
+ const search = new URLSearchParams()
147
+ for (const [k, v] of Object.entries(opts.query)) {
148
+ if (v != null) search.set(k, String(v))
149
+ }
150
+ const qs = search.toString()
151
+ if (qs) url += `?${qs}`
152
+ }
153
+
154
+ const init: RequestInit = {
155
+ method: route.method,
156
+ headers: { 'Content-Type': 'application/json', ...config.headers },
157
+ }
158
+ if (opts?.body && route.method !== 'GET') {
159
+ init.body = JSON.stringify(opts.body)
160
+ }
161
+
162
+ return fetch(url, init)
163
+ },
164
+ }
165
+ }
166
+
167
+ const routes: Record<string, { method: string; path: string }> = {
168
+ 'dashboard': { method: 'GET', path: '/dashboard' },
169
+ 'home': { method: 'GET', path: '/' },
170
+ 'login': { method: 'GET', path: '/login' },
171
+ 'login.store': { method: 'POST', path: '/login' },
172
+ 'logout': { method: 'POST', path: '/logout' },
173
+ 'posts.create': { method: 'GET', path: '/posts/create' },
174
+ 'posts.destroy': { method: 'DELETE', path: '/posts/:id' },
175
+ 'posts.edit': { method: 'GET', path: '/posts/:id/edit' },
176
+ 'posts.index': { method: 'GET', path: '/posts' },
177
+ 'posts.show': { method: 'GET', path: '/posts/:id' },
178
+ 'posts.store': { method: 'POST', path: '/posts' },
179
+ 'posts.update': { method: 'PUT', path: '/posts/:id' },
180
+ 'profile.edit': { method: 'GET', path: '/profile' },
181
+ 'profile.update': { method: 'PUT', path: '/profile' },
182
+ 'register': { method: 'GET', path: '/register' },
183
+ 'register.store': { method: 'POST', path: '/register' },
184
+ }
@@ -0,0 +1,23 @@
1
+ // Generated from app/Http/Resources — DO NOT EDIT
2
+ // Run `guren codegen` to regenerate.
3
+
4
+ import type { PostRecord, PostAuthorSummary } from '../app/Models/Post.js'
5
+ import type { WithRelations } from '@guren/core'
6
+
7
+ /**
8
+ * Auto-extracted data types from Resource classes.
9
+ * Import these in your frontend to get typed API responses.
10
+ */
11
+ export namespace Data {
12
+ export type Post = {
13
+ id: number
14
+ title: string
15
+ excerpt: string
16
+ body: string
17
+ authorId: number
18
+ // Serialized here because `created_at` is a string on SQLite and a Date on
19
+ // PostgreSQL and MySQL — pages should not have to know which.
20
+ createdAt: string
21
+ author?: PostAuthorSummary
22
+ }
23
+ }
@@ -0,0 +1,99 @@
1
+ // Generated from resources/js/pages — DO NOT EDIT
2
+ // Run `guren codegen` to regenerate.
3
+
4
+ import type { PageContract, PagePropsRecord } from '@guren/inertia-client'
5
+ import type { ApiRoutes } from '@/.guren/api-client.gen'
6
+ import type { PostResourceData } from '@/app/Http/Resources/PostResource'
7
+ import type { PaginatedPageProps, ValidationErrors } from '@guren/core'
8
+
9
+
10
+ export const pageManifest = {
11
+ 'auth/Login': './pages/auth/Login.tsx',
12
+ 'auth/Register': './pages/auth/Register.tsx',
13
+ 'dashboard/Index': './pages/dashboard/Index.tsx',
14
+ 'Home': './pages/Home.tsx',
15
+ 'posts/Edit': './pages/posts/Edit.tsx',
16
+ 'posts/Index': './pages/posts/Index.tsx',
17
+ 'posts/New': './pages/posts/New.tsx',
18
+ 'posts/Show': './pages/posts/Show.tsx',
19
+ 'profile/Edit': './pages/profile/Edit.tsx',
20
+ } as const
21
+
22
+ export type PageManifest = typeof pageManifest
23
+ export type PageId = keyof PageManifest
24
+ export type PagePath<TPage extends PageId = PageId> = PageManifest[TPage]
25
+
26
+ export const pageIds = Object.keys(pageManifest) as PageId[]
27
+
28
+ export function isPageId(value: string): value is PageId {
29
+ return Object.prototype.hasOwnProperty.call(pageManifest, value)
30
+ }
31
+
32
+ type PostFormData = ApiRoutes['posts.store']['body']
33
+ /**
34
+ * Auto-extracted Props types from page components.
35
+ */
36
+ export interface PagePropsMap {
37
+ 'auth/Login': {
38
+ email?: string
39
+ errors?: ValidationErrors<'email' | 'password'>
40
+ }
41
+ 'auth/Register': {
42
+ errors?: ValidationErrors<'name' | 'email' | 'password' | 'passwordConfirmation'>
43
+ }
44
+ 'dashboard/Index': {
45
+ user?: { id: number; name: string; email: string } | null
46
+ }
47
+ 'Home': {
48
+ latest: PostResourceData[]
49
+ }
50
+ 'posts/Edit': {
51
+ post: PostFormData & { id: number }
52
+ }
53
+ 'posts/Index': PaginatedPageProps<PostResourceData> & {}
54
+ 'posts/Show': {
55
+ post: PostResourceData
56
+ }
57
+ 'profile/Edit': {
58
+ profile: { name: string; email: string }
59
+ errors?: ValidationErrors<'name' | 'email' | 'password'>
60
+ status?: string
61
+ }
62
+ }
63
+
64
+ export type InferPageProps<TId extends PageId> =
65
+ TId extends keyof PagePropsMap ? PagePropsMap[TId] : Record<string, never>
66
+
67
+ function defineGeneratedPage<TId extends string, TProps extends PagePropsRecord = Record<string, never>>(
68
+ id: TId,
69
+ path: string,
70
+ ): PageContract<TId, TProps> {
71
+ return {
72
+ id,
73
+ component: id,
74
+ path,
75
+ props<TNextProps extends PagePropsRecord>() {
76
+ return defineGeneratedPage(id, path) as PageContract<TId, TNextProps>
77
+ },
78
+ } as PageContract<TId, TProps>
79
+ }
80
+
81
+ export const pages = {
82
+ auth: {
83
+ Login: defineGeneratedPage<'auth/Login', PagePropsMap['auth/Login']>('auth/Login', pageManifest['auth/Login']),
84
+ Register: defineGeneratedPage<'auth/Register', PagePropsMap['auth/Register']>('auth/Register', pageManifest['auth/Register'])
85
+ },
86
+ dashboard: {
87
+ Index: defineGeneratedPage<'dashboard/Index', PagePropsMap['dashboard/Index']>('dashboard/Index', pageManifest['dashboard/Index'])
88
+ },
89
+ Home: defineGeneratedPage<'Home', PagePropsMap['Home']>('Home', pageManifest['Home']),
90
+ posts: {
91
+ Edit: defineGeneratedPage<'posts/Edit', PagePropsMap['posts/Edit']>('posts/Edit', pageManifest['posts/Edit']),
92
+ Index: defineGeneratedPage<'posts/Index', PagePropsMap['posts/Index']>('posts/Index', pageManifest['posts/Index']),
93
+ New: defineGeneratedPage('posts/New', pageManifest['posts/New']),
94
+ Show: defineGeneratedPage<'posts/Show', PagePropsMap['posts/Show']>('posts/Show', pageManifest['posts/Show'])
95
+ },
96
+ profile: {
97
+ Edit: defineGeneratedPage<'profile/Edit', PagePropsMap['profile/Edit']>('profile/Edit', pageManifest['profile/Edit'])
98
+ }
99
+ } as const
@@ -0,0 +1,138 @@
1
+ // Generated from routes/web.ts — DO NOT EDIT
2
+ // Run `guren codegen` to regenerate.
3
+
4
+ export const routeManifest = {
5
+ 'dashboard': { method: 'GET', path: '/dashboard' },
6
+ 'home': { method: 'GET', path: '/' },
7
+ 'login': { method: 'GET', path: '/login' },
8
+ 'login.store': { method: 'POST', path: '/login' },
9
+ 'logout': { method: 'POST', path: '/logout' },
10
+ 'posts.create': { method: 'GET', path: '/posts/create' },
11
+ 'posts.destroy': { method: 'DELETE', path: '/posts/:id' },
12
+ 'posts.edit': { method: 'GET', path: '/posts/:id/edit' },
13
+ 'posts.index': { method: 'GET', path: '/posts' },
14
+ 'posts.show': { method: 'GET', path: '/posts/:id' },
15
+ 'posts.store': { method: 'POST', path: '/posts' },
16
+ 'posts.update': { method: 'PUT', path: '/posts/:id' },
17
+ 'profile.edit': { method: 'GET', path: '/profile' },
18
+ 'profile.update': { method: 'PUT', path: '/profile' },
19
+ 'register': { method: 'GET', path: '/register' },
20
+ 'register.store': { method: 'POST', path: '/register' },
21
+ } as const
22
+
23
+ export type RouteManifest = typeof routeManifest
24
+ export type RouteName = keyof RouteManifest
25
+ export type RouteMethod = [RouteName] extends [never] ? string : RouteManifest[RouteName]['method']
26
+ export type RoutePath = [RouteName] extends [never] ? string : RouteManifest[RouteName]['path']
27
+
28
+ type PrimitiveQueryValue = string | number | boolean | null | undefined
29
+ type QueryValue = PrimitiveQueryValue | readonly PrimitiveQueryValue[]
30
+ export type RouteQuery = Record<string, QueryValue>
31
+
32
+ type NormalizeParamKey<TValue extends string> = TValue extends `${infer Key}?` ? Key : TValue
33
+ type PathParamKeys<TPath extends string> =
34
+ TPath extends `${string}:${infer Param}/${infer Rest}`
35
+ ? NormalizeParamKey<Param> | PathParamKeys<`/${Rest}`>
36
+ : TPath extends `${string}:${infer Param}`
37
+ ? NormalizeParamKey<Param>
38
+ : never
39
+
40
+ export type RouteParams<TName extends RouteName> =
41
+ [PathParamKeys<RouteManifest[TName]['path']>] extends [never]
42
+ ? Record<string, never>
43
+ : { [TKey in PathParamKeys<RouteManifest[TName]['path']>]: string | number }
44
+
45
+ type RouteArgs<TName extends RouteName> =
46
+ [PathParamKeys<RouteManifest[TName]['path']>] extends [never]
47
+ ? [query?: RouteQuery]
48
+ : [params: RouteParams<TName>, query?: RouteQuery]
49
+
50
+ export function route<TName extends RouteName>(name: TName, ...args: RouteArgs<TName>): string {
51
+ const definition = routeManifest[name]
52
+ if (!definition) {
53
+ throw new Error(`Route [${String(name)}] not defined.`)
54
+ }
55
+
56
+ const [firstArg, secondArg] = args as [RouteQuery | RouteParams<TName> | undefined, RouteQuery | undefined]
57
+ const params = (args.length > 1 ? firstArg : hasPathParams(definition.path) ? firstArg : undefined) as RouteParams<TName> | undefined
58
+ const query = (args.length > 1 ? secondArg : hasPathParams(definition.path) ? undefined : firstArg) as RouteQuery | undefined
59
+ const path = substituteParams(definition.path, params as Record<string, string | number> | undefined)
60
+ return appendQueryString(path, query)
61
+ }
62
+
63
+ export const routes = {
64
+ dashboard: (query?: RouteQuery) => route('dashboard', query),
65
+ home: (query?: RouteQuery) => route('home', query),
66
+ login: Object.assign(
67
+ (query?: RouteQuery) => route('login', query),
68
+ {
69
+ store: (query?: RouteQuery) => route('login.store', query)
70
+ }
71
+ ),
72
+ logout: (query?: RouteQuery) => route('logout', query),
73
+ posts: {
74
+ create: (query?: RouteQuery) => route('posts.create', query),
75
+ destroy: (params: RouteParams<'posts.destroy'>, query?: RouteQuery) => route('posts.destroy', params, query),
76
+ edit: (params: RouteParams<'posts.edit'>, query?: RouteQuery) => route('posts.edit', params, query),
77
+ index: (query?: RouteQuery) => route('posts.index', query),
78
+ show: (params: RouteParams<'posts.show'>, query?: RouteQuery) => route('posts.show', params, query),
79
+ store: (query?: RouteQuery) => route('posts.store', query),
80
+ update: (params: RouteParams<'posts.update'>, query?: RouteQuery) => route('posts.update', params, query)
81
+ },
82
+ profile: {
83
+ edit: (query?: RouteQuery) => route('profile.edit', query),
84
+ update: (query?: RouteQuery) => route('profile.update', query)
85
+ },
86
+ register: Object.assign(
87
+ (query?: RouteQuery) => route('register', query),
88
+ {
89
+ store: (query?: RouteQuery) => route('register.store', query)
90
+ }
91
+ )
92
+ } as const
93
+
94
+ function hasPathParams(path: string): boolean {
95
+ return /:[A-Za-z0-9_-]+/u.test(path)
96
+ }
97
+
98
+ function substituteParams(path: string, params?: Record<string, string | number>): string {
99
+ if (!params) {
100
+ return path
101
+ }
102
+
103
+ return path.replace(/:([A-Za-z0-9_-]+)/gu, (match, key) => {
104
+ if (!Object.prototype.hasOwnProperty.call(params, key)) {
105
+ return match
106
+ }
107
+
108
+ return encodeURIComponent(String(params[key]))
109
+ })
110
+ }
111
+
112
+ function appendQueryString(path: string, query?: RouteQuery): string {
113
+ if (!query) {
114
+ return path
115
+ }
116
+
117
+ const search = new URLSearchParams()
118
+
119
+ for (const [key, value] of Object.entries(query)) {
120
+ if (value == null) {
121
+ continue
122
+ }
123
+
124
+ if (Array.isArray(value)) {
125
+ for (const item of value) {
126
+ if (item != null) {
127
+ search.append(key, String(item))
128
+ }
129
+ }
130
+ continue
131
+ }
132
+
133
+ search.set(key, String(value))
134
+ }
135
+
136
+ const serialized = search.toString()
137
+ return serialized ? `${path}?${serialized}` : path
138
+ }
@@ -0,0 +1,85 @@
1
+ # __APP_TITLE__
2
+
3
+ A blog built with [Guren](https://guren.dev) — posts CRUD, session authentication,
4
+ and a seeded demo account, ready to run.
5
+
6
+ ## Quick Start
7
+
8
+ ```bash
9
+ bun install
10
+ bun run db:make # generate the first migration from db/schema.ts
11
+ bun run db:migrate
12
+ bun run db:seed # demo@example.com / secret, plus two sample posts
13
+ bun run dev
14
+ ```
15
+
16
+ Visit `http://localhost:3333`, then sign in as `demo@example.com` with the
17
+ password `secret` and publish a post from `/posts/create`.
18
+
19
+ If you scaffolded with PostgreSQL or MySQL, run `bun run db:up` first to start
20
+ the database container.
21
+
22
+ ## What's Included
23
+
24
+ - `/` — landing page with the latest posts
25
+ - `/posts` — paginated post list, `/posts/:id` — a single post
26
+ - `/posts/create`, `/posts/:id/edit` — write and edit, signed in only
27
+ - `/login`, `/register`, `/dashboard`, `/profile` — session authentication
28
+
29
+ Posts belong to their author. `app/Providers/AuthorizationProvider.ts` binds
30
+ `app/Policies/PostPolicy.ts` to the `Post` model, and `PostController` calls
31
+ `this.authorize()` in every mutating action, so nobody can edit someone else's
32
+ post. `app/Providers/AuthProvider.ts` shares the signed-in user with every page,
33
+ which is what `resources/js/components/Layout.tsx` reads to show the
34
+ Write/Dashboard/Log out controls.
35
+
36
+ ## Project Structure
37
+
38
+ - `routes/web.ts`, `routes/auth.ts` — route definitions
39
+ - `app/Http/Controllers/` — request handlers
40
+ - `app/Http/Validators/` — Zod schemas, bound to routes and reused by the pages
41
+ - `app/Http/Resources/` — the shapes controllers hand to pages
42
+ - `app/Models/` — ORM models (`Post` belongs to `User`)
43
+ - `app/Policies/` — authorization rules
44
+ - `app/Providers/` — the auth model binding, shared page props, and the policy binding
45
+ - `resources/js/pages/` — React pages (rendered via Inertia.js)
46
+ - `db/schema.ts` — Drizzle table definitions
47
+ - `db/seeders/` — the demo user and sample posts
48
+
49
+ ## Adding Features
50
+
51
+ ```bash
52
+ bunx guren add queue # background job processing
53
+ bunx guren add mail # email sending
54
+ bunx guren add events # event system
55
+ bunx guren add cache # caching layer
56
+ bunx guren add notifications # notification channels
57
+ bunx guren add storage # local/public disks
58
+ bunx guren add broadcasting # realtime channels
59
+ bunx guren add schedule # task scheduling
60
+ ```
61
+
62
+ ## Favicon
63
+
64
+ `public/favicon.svg` ships as a placeholder and is linked from `src/app.ts` via
65
+ `setInertiaDocument({ head })`, which is the only path that reaches the
66
+ production document — `public/index.html` is not read by the server. Replace the
67
+ file to change the icon, or edit the `head` markup to add more tags.
68
+
69
+ Files at the root of `public/` are served by the Bun runtime. On Node-based
70
+ deployments (AWS Lambda, for example) serve them from a CDN instead.
71
+
72
+ ## Scripts
73
+
74
+ | Command | Description |
75
+ |---------|-------------|
76
+ | `bun run dev` | Start dev server (Bun + Vite) |
77
+ | `bun run build` | Build for production |
78
+ | `bun run preview` | Start the built app with the Bun production server |
79
+ | `bun run db:make` | Generate a migration from `db/schema.ts` |
80
+ | `bun run db:migrate` | Run database migrations |
81
+ | `bun run db:seed` | Seed the database |
82
+ | `bun run codegen` | Regenerate route/page types |
83
+
84
+ Run `bun run build` before `bun run preview` so the production server can read
85
+ the generated manifests from `public/assets`.