create-guren-app 1.2.0 → 1.4.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 +15 -5
- package/package.json +1 -1
- package/templates/api-only/.env.example +4 -0
- package/templates/api-only/README.md +2 -0
- package/templates/api-only/bin/console.ts +13 -0
- package/templates/api-only/config/app.ts +12 -1
- package/templates/api-only/docs/adr/0001-record-architecture-decisions.md +47 -0
- package/templates/api-only/drizzle.config.ts +5 -0
- package/templates/api-only/package.json +3 -4
- package/templates/api-only/src/console.ts +9 -0
- package/templates/default/.env.example +4 -0
- package/templates/default/README.md +12 -0
- package/templates/default/bin/console.ts +13 -0
- package/templates/default/config/app.ts +10 -2
- package/templates/default/docs/adr/0001-record-architecture-decisions.md +47 -0
- package/templates/default/drizzle.config.ts +5 -0
- package/templates/default/package.json +3 -4
- package/templates/default/public/favicon.svg +11 -0
- package/templates/default/public/index.html +1 -0
- package/templates/default/src/app.ts +7 -0
- package/templates/default/src/console.ts +9 -0
package/dist/cli.js
CHANGED
|
@@ -1996,6 +1996,9 @@ export default defineConfig({
|
|
|
1996
1996
|
})
|
|
1997
1997
|
`;
|
|
1998
1998
|
}
|
|
1999
|
+
function usesDatabaseContainer(driver) {
|
|
2000
|
+
return generateDockerCompose(driver) !== null;
|
|
2001
|
+
}
|
|
1999
2002
|
function generateDockerCompose(driver) {
|
|
2000
2003
|
if (driver === "postgres") {
|
|
2001
2004
|
return `services:
|
|
@@ -2052,12 +2055,19 @@ async function applyDatabaseConfig(destination, driver) {
|
|
|
2052
2055
|
}
|
|
2053
2056
|
})
|
|
2054
2057
|
]);
|
|
2055
|
-
if (dep) {
|
|
2058
|
+
if (dep || dockerCompose) {
|
|
2056
2059
|
const packageJsonPath = join(destination, "package.json");
|
|
2057
2060
|
const raw = await readFile(packageJsonPath, "utf8");
|
|
2058
2061
|
const pkg = JSON.parse(raw);
|
|
2059
|
-
|
|
2060
|
-
|
|
2062
|
+
if (dep) {
|
|
2063
|
+
pkg.dependencies ??= {};
|
|
2064
|
+
Object.assign(pkg.dependencies, dep);
|
|
2065
|
+
}
|
|
2066
|
+
if (dockerCompose) {
|
|
2067
|
+
pkg.scripts ??= {};
|
|
2068
|
+
pkg.scripts["db:up"] = "docker compose up -d";
|
|
2069
|
+
pkg.scripts["db:down"] = "docker compose down";
|
|
2070
|
+
}
|
|
2061
2071
|
await writeFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}
|
|
2062
2072
|
`, "utf8");
|
|
2063
2073
|
}
|
|
@@ -2309,8 +2319,8 @@ var command = defineCommand({
|
|
|
2309
2319
|
if (!installed) {
|
|
2310
2320
|
consola.log(" bun install");
|
|
2311
2321
|
}
|
|
2312
|
-
if (database
|
|
2313
|
-
consola.log("
|
|
2322
|
+
if (usesDatabaseContainer(database)) {
|
|
2323
|
+
consola.log(" bun run db:up");
|
|
2314
2324
|
}
|
|
2315
2325
|
consola.log("");
|
|
2316
2326
|
consola.info("Add features:");
|
package/package.json
CHANGED
|
@@ -33,3 +33,7 @@ MAIL_FROM_NAME="${APP_NAME}"
|
|
|
33
33
|
# OAUTH_GOOGLE_CLIENT_ID=
|
|
34
34
|
# OAUTH_GOOGLE_CLIENT_SECRET=
|
|
35
35
|
# OAUTH_GOOGLE_REDIRECT_URI=http://localhost:3333/auth/google/callback
|
|
36
|
+
|
|
37
|
+
# OAUTH_DISCORD_CLIENT_ID=
|
|
38
|
+
# OAUTH_DISCORD_CLIENT_SECRET=
|
|
39
|
+
# OAUTH_DISCORD_REDIRECT_URI=http://localhost:3333/auth/discord/callback
|
|
@@ -10,6 +10,8 @@ bun run db:migrate
|
|
|
10
10
|
bun run dev
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
+
If you scaffolded with PostgreSQL or MySQL, this project also has a `docker-compose.yml` and `bun run db:up` / `bun run db:down` to start and stop the database container. Start it before `bun run db:migrate`.
|
|
14
|
+
|
|
13
15
|
## API Endpoints
|
|
14
16
|
|
|
15
17
|
- `GET /health` — Health check
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { ready } from '../src/main.js'
|
|
2
|
+
import { kernel } from '../src/console.js'
|
|
3
|
+
|
|
4
|
+
try {
|
|
5
|
+
await ready
|
|
6
|
+
} catch (error) {
|
|
7
|
+
console.error('Failed to bootstrap application:', error)
|
|
8
|
+
process.exit(1)
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
// process.exit() is required, not just tidy: an idle database pool keeps the
|
|
12
|
+
// event loop alive, so returning normally would hang after the command runs.
|
|
13
|
+
process.exit(await kernel.handle(process.argv.slice(2)))
|
|
@@ -17,6 +17,15 @@ function hasMigrations(): boolean {
|
|
|
17
17
|
)
|
|
18
18
|
}
|
|
19
19
|
|
|
20
|
+
/**
|
|
21
|
+
* Seeding is one-shot provisioning, not part of booting: production boots
|
|
22
|
+
* repeatedly on serverless cold starts, and a bundle has no resolver for the
|
|
23
|
+
* raw db/seeders/*.ts files. Run `bunx guren db:seed` explicitly instead.
|
|
24
|
+
*/
|
|
25
|
+
function shouldSeedOnBoot(): boolean {
|
|
26
|
+
return process.env.NODE_ENV !== 'production'
|
|
27
|
+
}
|
|
28
|
+
|
|
20
29
|
export async function bootModels(): Promise<void> {
|
|
21
30
|
if (bootstrapped) return
|
|
22
31
|
|
|
@@ -26,6 +35,8 @@ export async function bootModels(): Promise<void> {
|
|
|
26
35
|
}
|
|
27
36
|
|
|
28
37
|
await configureOrm()
|
|
29
|
-
|
|
38
|
+
if (shouldSeedOnBoot()) {
|
|
39
|
+
await seedDatabase()
|
|
40
|
+
}
|
|
30
41
|
bootstrapped = true
|
|
31
42
|
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
kind: adr
|
|
3
|
+
status: accepted
|
|
4
|
+
entities: []
|
|
5
|
+
related: []
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Record architecture decisions
|
|
9
|
+
|
|
10
|
+
## Context
|
|
11
|
+
|
|
12
|
+
Code shows *what* the system does; it cannot show *why*. Decisions —
|
|
13
|
+
business rules, trade-offs, rejected alternatives — live in people's
|
|
14
|
+
heads and get lost. AI coding agents working on this codebase have the
|
|
15
|
+
same problem: without recorded decisions they can only infer intent.
|
|
16
|
+
|
|
17
|
+
## Decision
|
|
18
|
+
|
|
19
|
+
We record significant decisions as numbered ADRs in this directory,
|
|
20
|
+
created with:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
bunx guren make:adr "Title of the decision"
|
|
24
|
+
bunx guren make:adr "Title" --entity Invoice # prefills the links below
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Each ADR declares what it governs in its frontmatter:
|
|
28
|
+
|
|
29
|
+
- `entities: [Invoice]` — model class names the decision affects.
|
|
30
|
+
`bunx guren context Invoice` then surfaces this ADR to anyone (human
|
|
31
|
+
or agent) working on that model.
|
|
32
|
+
- `related: [app/Http/Controllers/InvoiceController.ts]` — files or
|
|
33
|
+
globs the decision touches.
|
|
34
|
+
- `status:` — `draft` → `accepted`; mark `superseded` when replaced
|
|
35
|
+
(and write the replacement).
|
|
36
|
+
|
|
37
|
+
Once declared, the links are verified: `bunx guren check` reports a
|
|
38
|
+
renamed file a doc points at, or a removed model a doc names, as a
|
|
39
|
+
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.
|
|
41
|
+
|
|
42
|
+
## Consequences
|
|
43
|
+
|
|
44
|
+
Decisions stay discoverable from the code they govern, at the cost of
|
|
45
|
+
writing them down and keeping links fresh — declared links are checked,
|
|
46
|
+
so they can be trusted. (An ADR with no links, like this one, is valid;
|
|
47
|
+
it simply isn't surfaced by `guren context`.)
|
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
import { defineConfig } from 'drizzle-kit'
|
|
2
2
|
|
|
3
3
|
export default defineConfig({
|
|
4
|
+
// `guren make:module` wires each modules/<name>/db/schema.ts into this
|
|
5
|
+
// file automatically via a re-export, so this single path is enough by
|
|
6
|
+
// default. If you'd rather point drizzle-kit at every module schema
|
|
7
|
+
// directly instead, `schema` also accepts an array of paths/globs, e.g.
|
|
8
|
+
// schema: ['./db/schema.ts', './modules/*/db/schema.ts'].
|
|
4
9
|
schema: './db/schema.ts',
|
|
5
10
|
out: './db/migrations',
|
|
6
11
|
dialect: 'sqlite',
|
|
@@ -4,8 +4,9 @@
|
|
|
4
4
|
"private": true,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
7
|
-
"dev": "bun run codegen && bun run dev:server",
|
|
8
|
-
"dev:server": "bun bin/serve.ts",
|
|
7
|
+
"dev": "bun run codegen && GUREN_MCP=1 bun run dev:server",
|
|
8
|
+
"dev:server": "bun --hot bin/serve.ts",
|
|
9
|
+
"console": "bun bin/console.ts",
|
|
9
10
|
"codegen": "bunx guren codegen --routes routes/api.ts --force",
|
|
10
11
|
"typecheck": "tsc --noEmit",
|
|
11
12
|
"db:make": "bunx guren make:migration",
|
|
@@ -26,8 +27,6 @@
|
|
|
26
27
|
"@guren/testing": "^1.0.0",
|
|
27
28
|
"bun-types": "^1.3.1",
|
|
28
29
|
"drizzle-kit": "1.0.0-rc.4",
|
|
29
|
-
"mysql2": "^3.11.3",
|
|
30
|
-
"postgres": "^3.4.3",
|
|
31
30
|
"typescript": "^5.4.0"
|
|
32
31
|
}
|
|
33
32
|
}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { ConsoleKernel } from '@guren/core'
|
|
2
|
+
import app from './app.js'
|
|
3
|
+
|
|
4
|
+
export const kernel = new ConsoleKernel({ container: app.container })
|
|
5
|
+
|
|
6
|
+
// `bunx guren make:command` adds the import and the array entry for you; the
|
|
7
|
+
// empty array literal is what it edits, so keep it even while unused.
|
|
8
|
+
// `bunx guren check` warns about any command class this file never registers.
|
|
9
|
+
kernel.registerMany([])
|
|
@@ -37,5 +37,9 @@ MAIL_FROM_NAME="${APP_NAME}"
|
|
|
37
37
|
# OAUTH_GOOGLE_CLIENT_SECRET=
|
|
38
38
|
# OAUTH_GOOGLE_REDIRECT_URI=http://localhost:3333/auth/google/callback
|
|
39
39
|
|
|
40
|
+
# OAUTH_DISCORD_CLIENT_ID=
|
|
41
|
+
# OAUTH_DISCORD_CLIENT_SECRET=
|
|
42
|
+
# OAUTH_DISCORD_REDIRECT_URI=http://localhost:3333/auth/discord/callback
|
|
43
|
+
|
|
40
44
|
# Optional: point to an already-running external Vite dev server.
|
|
41
45
|
# VITE_DEV_SERVER_URL=http://localhost:5173
|
|
@@ -37,6 +37,16 @@ bunx guren add schedule # task scheduling
|
|
|
37
37
|
- `config/database.ts` — database configuration
|
|
38
38
|
- `db/schema.ts` — Drizzle table definitions
|
|
39
39
|
|
|
40
|
+
## Favicon
|
|
41
|
+
|
|
42
|
+
`public/favicon.svg` ships as a placeholder and is linked from `src/app.ts` via
|
|
43
|
+
`setInertiaDocument({ head })`, which is the only path that reaches the
|
|
44
|
+
production document — `public/index.html` is not read by the server. Replace the
|
|
45
|
+
file to change the icon, or edit the `head` markup to add more tags.
|
|
46
|
+
|
|
47
|
+
Files at the root of `public/` are served by the Bun runtime. On Node-based
|
|
48
|
+
deployments (AWS Lambda, for example) serve them from a CDN instead.
|
|
49
|
+
|
|
40
50
|
## Scripts
|
|
41
51
|
|
|
42
52
|
| Command | Description |
|
|
@@ -48,6 +58,8 @@ bunx guren add schedule # task scheduling
|
|
|
48
58
|
| `bun run db:seed` | Seed the database |
|
|
49
59
|
| `bun run codegen` | Regenerate route/page types |
|
|
50
60
|
|
|
61
|
+
If you scaffolded with PostgreSQL or MySQL, this project also has a `docker-compose.yml` and `bun run db:up` / `bun run db:down` to start and stop the database container. Start it before `bun run db:migrate`.
|
|
62
|
+
|
|
51
63
|
Run `bun run build` before `bun run preview` so the production server can read the generated manifests from `public/assets`.
|
|
52
64
|
|
|
53
65
|
## Switching to PostgreSQL
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { ready } from '../src/main.js'
|
|
2
|
+
import { kernel } from '../src/console.js'
|
|
3
|
+
|
|
4
|
+
try {
|
|
5
|
+
await ready
|
|
6
|
+
} catch (error) {
|
|
7
|
+
console.error('Failed to bootstrap application:', error)
|
|
8
|
+
process.exit(1)
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
// process.exit() is required, not just tidy: an idle database pool keeps the
|
|
12
|
+
// event loop alive, so returning normally would hang after the command runs.
|
|
13
|
+
process.exit(await kernel.handle(process.argv.slice(2)))
|
|
@@ -17,13 +17,21 @@ function hasMigrations(): boolean {
|
|
|
17
17
|
)
|
|
18
18
|
}
|
|
19
19
|
|
|
20
|
+
/**
|
|
21
|
+
* Seeding is one-shot provisioning, not part of booting: production boots
|
|
22
|
+
* repeatedly on serverless cold starts, and a bundle has no resolver for the
|
|
23
|
+
* raw db/seeders/*.ts files. Run `bunx guren db:seed` explicitly instead.
|
|
24
|
+
*/
|
|
25
|
+
function shouldSeedOnBoot(): boolean {
|
|
26
|
+
return process.env.NODE_ENV !== 'production'
|
|
27
|
+
}
|
|
28
|
+
|
|
20
29
|
export async function bootModels(): Promise<void> {
|
|
21
30
|
if (bootstrapped) return
|
|
22
31
|
|
|
23
32
|
// Always initialize ORM (even without migrations, models need a connection).
|
|
24
|
-
// Only run seeders when migrations exist.
|
|
25
33
|
await configureOrm()
|
|
26
|
-
if (hasMigrations()) {
|
|
34
|
+
if (shouldSeedOnBoot() && hasMigrations()) {
|
|
27
35
|
await seedDatabase()
|
|
28
36
|
}
|
|
29
37
|
bootstrapped = true
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
kind: adr
|
|
3
|
+
status: accepted
|
|
4
|
+
entities: []
|
|
5
|
+
related: []
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Record architecture decisions
|
|
9
|
+
|
|
10
|
+
## Context
|
|
11
|
+
|
|
12
|
+
Code shows *what* the system does; it cannot show *why*. Decisions —
|
|
13
|
+
business rules, trade-offs, rejected alternatives — live in people's
|
|
14
|
+
heads and get lost. AI coding agents working on this codebase have the
|
|
15
|
+
same problem: without recorded decisions they can only infer intent.
|
|
16
|
+
|
|
17
|
+
## Decision
|
|
18
|
+
|
|
19
|
+
We record significant decisions as numbered ADRs in this directory,
|
|
20
|
+
created with:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
bunx guren make:adr "Title of the decision"
|
|
24
|
+
bunx guren make:adr "Title" --entity Invoice # prefills the links below
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Each ADR declares what it governs in its frontmatter:
|
|
28
|
+
|
|
29
|
+
- `entities: [Invoice]` — model class names the decision affects.
|
|
30
|
+
`bunx guren context Invoice` then surfaces this ADR to anyone (human
|
|
31
|
+
or agent) working on that model.
|
|
32
|
+
- `related: [app/Http/Controllers/InvoiceController.ts]` — files or
|
|
33
|
+
globs the decision touches.
|
|
34
|
+
- `status:` — `draft` → `accepted`; mark `superseded` when replaced
|
|
35
|
+
(and write the replacement).
|
|
36
|
+
|
|
37
|
+
Once declared, the links are verified: `bunx guren check` reports a
|
|
38
|
+
renamed file a doc points at, or a removed model a doc names, as a
|
|
39
|
+
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.
|
|
41
|
+
|
|
42
|
+
## Consequences
|
|
43
|
+
|
|
44
|
+
Decisions stay discoverable from the code they govern, at the cost of
|
|
45
|
+
writing them down and keeping links fresh — declared links are checked,
|
|
46
|
+
so they can be trusted. (An ADR with no links, like this one, is valid;
|
|
47
|
+
it simply isn't surfaced by `guren context`.)
|
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
import { defineConfig } from 'drizzle-kit'
|
|
2
2
|
|
|
3
3
|
export default defineConfig({
|
|
4
|
+
// `guren make:module` wires each modules/<name>/db/schema.ts into this
|
|
5
|
+
// file automatically via a re-export, so this single path is enough by
|
|
6
|
+
// default. If you'd rather point drizzle-kit at every module schema
|
|
7
|
+
// directly instead, `schema` also accepts an array of paths/globs, e.g.
|
|
8
|
+
// schema: ['./db/schema.ts', './modules/*/db/schema.ts'].
|
|
4
9
|
schema: './db/schema.ts',
|
|
5
10
|
out: './db/migrations',
|
|
6
11
|
dialect: 'sqlite',
|
|
@@ -5,8 +5,9 @@
|
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
7
7
|
"codegen": "bunx guren codegen --force",
|
|
8
|
-
"dev": "bun run codegen && bun run dev:server",
|
|
9
|
-
"dev:server": "bun bin/serve.ts",
|
|
8
|
+
"dev": "bun run codegen && GUREN_MCP=1 bun run dev:server",
|
|
9
|
+
"dev:server": "bun --hot bin/serve.ts",
|
|
10
|
+
"console": "bun bin/console.ts",
|
|
10
11
|
"typecheck": "tsc --noEmit",
|
|
11
12
|
"build": "bun run codegen && bunx vite build",
|
|
12
13
|
"preview": "NODE_ENV=production bun bin/serve.ts",
|
|
@@ -33,8 +34,6 @@
|
|
|
33
34
|
"@types/react-dom": "^19.0.0",
|
|
34
35
|
"bun-types": "^1.3.1",
|
|
35
36
|
"drizzle-kit": "1.0.0-rc.4",
|
|
36
|
-
"mysql2": "^3.11.3",
|
|
37
|
-
"postgres": "^3.4.3",
|
|
38
37
|
"typescript": "^5.4.0",
|
|
39
38
|
"@vitejs/plugin-react": "^6.0.0",
|
|
40
39
|
"vite": "^8.0.0",
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<svg width="512" height="512" viewBox="0 0 512 512" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<g transform="translate(123 26) scale(0.8915)">
|
|
3
|
+
<path fill-rule="evenodd" clip-rule="evenodd" d="M120.853 0C169.647 25.1364 195.255 83.7877 184.353 136.5C175.756 178.065 136.039 208.749 137.372 253.138C138.729 298.251 168.879 330.194 161.353 377.5C181.444 352.982 200.458 332.078 208.353 300.5C214.367 261.839 179.943 229.848 190.898 190.72C194.731 177.22 208.153 147.3 231.353 136.5C218.919 181.573 237.455 211.003 266.353 245C300.243 280.246 308.266 343.188 284.853 386C253.141 442.376 189.378 465.573 149.853 515.5C121.558 476.749 77.5264 459.842 48.8528 424C-12.4118 347.419 -19.5127 245.133 47.3528 169C80.8397 130.872 165.348 59.327 120.853 0Z" fill="url(#guren-favicon-gradient)"/>
|
|
4
|
+
</g>
|
|
5
|
+
<defs>
|
|
6
|
+
<linearGradient id="guren-favicon-gradient" x1="256" y1="26" x2="256" y2="486" gradientUnits="userSpaceOnUse">
|
|
7
|
+
<stop stop-color="#FF3C28"/>
|
|
8
|
+
<stop offset="1" stop-color="#8B0000"/>
|
|
9
|
+
</linearGradient>
|
|
10
|
+
</defs>
|
|
11
|
+
</svg>
|
|
@@ -1,7 +1,14 @@
|
|
|
1
1
|
import { createApp } from '@guren/core'
|
|
2
|
+
import { setInertiaDocument } from '@guren/core'
|
|
2
3
|
import DatabaseProvider from '../app/Providers/DatabaseProvider.js'
|
|
3
4
|
import { registerWebRoutes } from '../routes/web.js'
|
|
4
5
|
|
|
6
|
+
// Rendered into every server-rendered document. Replace public/favicon.svg
|
|
7
|
+
// with your own artwork, or add more tags here (Open Graph, apple-touch-icon).
|
|
8
|
+
setInertiaDocument({
|
|
9
|
+
head: '<link rel="icon" type="image/svg+xml" href="/favicon.svg" />',
|
|
10
|
+
})
|
|
11
|
+
|
|
5
12
|
const app = createApp({
|
|
6
13
|
routes: registerWebRoutes,
|
|
7
14
|
providers: [DatabaseProvider],
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { ConsoleKernel } from '@guren/core'
|
|
2
|
+
import app from './app.js'
|
|
3
|
+
|
|
4
|
+
export const kernel = new ConsoleKernel({ container: app.container })
|
|
5
|
+
|
|
6
|
+
// `bunx guren make:command` adds the import and the array entry for you; the
|
|
7
|
+
// empty array literal is what it edits, so keep it even while unused.
|
|
8
|
+
// `bunx guren check` warns about any command class this file never registers.
|
|
9
|
+
kernel.registerMany([])
|