express-file-cluster 0.3.15 → 0.7.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 (116) hide show
  1. package/README.md +71 -33
  2. package/dist/auth/index.cjs +12 -2
  3. package/dist/auth/index.cjs.map +1 -1
  4. package/dist/auth/index.d.cts +13 -2
  5. package/dist/auth/index.d.ts +13 -2
  6. package/dist/auth/index.js +12 -2
  7. package/dist/chunk-277BSYVH.js +127 -0
  8. package/dist/chunk-277BSYVH.js.map +1 -0
  9. package/dist/chunk-6OGOVV57.js +3847 -0
  10. package/dist/chunk-6OGOVV57.js.map +1 -0
  11. package/dist/chunk-7YEX4MQV.cjs +38 -0
  12. package/dist/chunk-7YEX4MQV.cjs.map +1 -0
  13. package/dist/chunk-AZYXQU3Z.cjs +3847 -0
  14. package/dist/chunk-AZYXQU3Z.cjs.map +1 -0
  15. package/dist/chunk-BUBXO7WU.js +170 -0
  16. package/dist/chunk-BUBXO7WU.js.map +1 -0
  17. package/dist/chunk-LJNSJFOL.js +38 -0
  18. package/dist/chunk-LJNSJFOL.js.map +1 -0
  19. package/dist/chunk-MGH4VDV3.cjs +170 -0
  20. package/dist/chunk-MGH4VDV3.cjs.map +1 -0
  21. package/dist/chunk-R34R7QPD.cjs +116 -0
  22. package/dist/chunk-R34R7QPD.cjs.map +1 -0
  23. package/dist/chunk-RS4MXCPW.js +116 -0
  24. package/dist/chunk-RS4MXCPW.js.map +1 -0
  25. package/dist/chunk-T4OHFU5T.cjs +154 -0
  26. package/dist/chunk-T4OHFU5T.cjs.map +1 -0
  27. package/dist/chunk-TI24L4XE.cjs.map +1 -1
  28. package/dist/chunk-TRC4DUZB.js +438 -0
  29. package/dist/chunk-TRC4DUZB.js.map +1 -0
  30. package/dist/chunk-TYR2GZZE.cjs +196 -0
  31. package/dist/chunk-TYR2GZZE.cjs.map +1 -0
  32. package/dist/chunk-UBQYQPBU.js +154 -0
  33. package/dist/chunk-UBQYQPBU.js.map +1 -0
  34. package/dist/chunk-UTM4PEVG.js +196 -0
  35. package/dist/chunk-UTM4PEVG.js.map +1 -0
  36. package/dist/chunk-YL37D6KM.cjs +127 -0
  37. package/dist/chunk-YL37D6KM.cjs.map +1 -0
  38. package/dist/chunk-ZDM5JHVK.cjs +438 -0
  39. package/dist/chunk-ZDM5JHVK.cjs.map +1 -0
  40. package/dist/cli/db-runner.cjs +497 -0
  41. package/dist/cli/db-runner.cjs.map +1 -0
  42. package/dist/cli/db-runner.d.cts +2 -0
  43. package/dist/cli/db-runner.d.ts +2 -0
  44. package/dist/cli/db-runner.js +497 -0
  45. package/dist/cli/db-runner.js.map +1 -0
  46. package/dist/cli/index.cjs +447 -69
  47. package/dist/cli/index.cjs.map +1 -1
  48. package/dist/cli/index.js +473 -95
  49. package/dist/cli/index.js.map +1 -1
  50. package/dist/docs/api-reference/auth.md +232 -0
  51. package/dist/docs/api-reference/compose.md +78 -0
  52. package/dist/docs/api-reference/db.md +351 -0
  53. package/dist/docs/api-reference/http-error.md +109 -0
  54. package/dist/docs/api-reference/ignite.md +326 -0
  55. package/dist/docs/api-reference/table.md +458 -0
  56. package/dist/docs/api-reference/tasks.md +140 -0
  57. package/dist/docs/cli/db.md +38 -0
  58. package/dist/docs/cli/diagnostics.md +145 -0
  59. package/dist/docs/cli/generate.md +120 -0
  60. package/dist/docs/cli/index.md +48 -0
  61. package/dist/docs/cli/start.md +112 -0
  62. package/dist/docs/contributing/index.md +139 -0
  63. package/dist/docs/core-concepts/background-tasks.md +228 -0
  64. package/dist/docs/core-concepts/clustering.md +114 -0
  65. package/dist/docs/core-concepts/file-based-routing.md +235 -0
  66. package/dist/docs/core-concepts/index.md +79 -0
  67. package/dist/docs/core-concepts/middleware.md +144 -0
  68. package/dist/docs/getting-started/index.md +91 -0
  69. package/dist/docs/getting-started/project-structure.md +154 -0
  70. package/dist/docs/guides/ai-agents.md +48 -0
  71. package/dist/docs/guides/authentication.md +196 -0
  72. package/dist/docs/guides/caching.md +124 -0
  73. package/dist/docs/guides/database.md +217 -0
  74. package/dist/docs/guides/deployment.md +171 -0
  75. package/dist/docs/guides/environment-variables.md +106 -0
  76. package/dist/docs/guides/error-handling.md +172 -0
  77. package/dist/docs/guides/generated-portals.md +115 -0
  78. package/dist/docs/guides/logging.md +108 -0
  79. package/dist/docs/guides/mailer.md +166 -0
  80. package/dist/docs/guides/migrations.md +106 -0
  81. package/dist/docs/guides/rbac.md +89 -0
  82. package/dist/docs/guides/validation.md +95 -0
  83. package/dist/docs/index.md +93 -0
  84. package/dist/docs/skills/SKILL.md +44 -0
  85. package/dist/docs/skills/api-surface.md +309 -0
  86. package/dist/docs/skills/auth-internals.md +141 -0
  87. package/dist/docs/skills/pre-flight.md +142 -0
  88. package/dist/docs/skills/routing-rules.md +114 -0
  89. package/dist/docs/skills/tasks-internals.md +172 -0
  90. package/dist/docs/skills/what-not-to-invent.md +251 -0
  91. package/dist/index.cjs +264 -391
  92. package/dist/index.cjs.map +1 -1
  93. package/dist/index.d.cts +699 -7
  94. package/dist/index.d.ts +699 -7
  95. package/dist/index.js +258 -385
  96. package/dist/index.js.map +1 -1
  97. package/dist/pgboss-backend-QKBXVJ6B.js +14 -0
  98. package/dist/pgboss-backend-QKBXVJ6B.js.map +1 -0
  99. package/dist/pgboss-backend-TCHI7CHM.cjs +14 -0
  100. package/dist/pgboss-backend-TCHI7CHM.cjs.map +1 -0
  101. package/dist/tasks/index.cjs.map +1 -1
  102. package/dist/tasks/index.d.cts +1 -1
  103. package/dist/tasks/index.d.ts +1 -1
  104. package/dist/types-B6lVw4bj.d.cts +588 -0
  105. package/dist/types-B6lVw4bj.d.ts +588 -0
  106. package/package.json +28 -5
  107. package/dist/chunk-6522HS2J.cjs +0 -99
  108. package/dist/chunk-6522HS2J.cjs.map +0 -1
  109. package/dist/chunk-DGVOJNR6.cjs +0 -55
  110. package/dist/chunk-DGVOJNR6.cjs.map +0 -1
  111. package/dist/chunk-KOHLLUN7.js +0 -55
  112. package/dist/chunk-KOHLLUN7.js.map +0 -1
  113. package/dist/chunk-VIP3PFWZ.js +0 -99
  114. package/dist/chunk-VIP3PFWZ.js.map +0 -1
  115. package/dist/types-BusbSenn.d.cts +0 -162
  116. package/dist/types-BusbSenn.d.ts +0 -162
@@ -0,0 +1,145 @@
1
+ # Diagnostics — `efc routes` / `efc tasks` / `efc doctor`
2
+
3
+ The three diagnostic commands inspect your project without starting the server.
4
+
5
+ ---
6
+
7
+ ## `efc routes`
8
+
9
+ Prints the route table resolved from the `src/api/` directory.
10
+
11
+ ```bash
12
+ efc routes
13
+ ```
14
+
15
+ **Sample output:**
16
+
17
+ ```
18
+ Route Table
19
+ ────────────────────────────────────────────────────────────
20
+ /health src/api/health.ts
21
+ /users src/api/users/index.ts
22
+ /posts/:slug/comments src/api/posts/[slug]/comments.ts
23
+ /users/:id src/api/users/[id].ts
24
+ ────────────────────────────────────────────────────────────
25
+
26
+ 4 route(s) found
27
+ ```
28
+
29
+ Static routes appear before dynamic routes (routes with `:param` segments), matching the registration order used at runtime.
30
+
31
+ **When to use:** after adding, renaming, or moving route files to verify the URL mapping is what you expect.
32
+
33
+ **Lookup order for the routes directory:** `src/api/` → `api/` → `dist/api/` (first that exists). This is a fixed convention — there is no `apiDir` config option.
34
+
35
+ ---
36
+
37
+ ## `efc tasks`
38
+
39
+ Lists the background tasks found in `src/tasks/`.
40
+
41
+ ```bash
42
+ efc tasks
43
+ ```
44
+
45
+ **Sample output:**
46
+
47
+ ```
48
+ Background Tasks
49
+
50
+ SendEmail
51
+ ResizeImage
52
+ ProcessPayment
53
+ ```
54
+
55
+ Each name corresponds to a file basename without extension. That is the string to pass to `enqueue()`.
56
+
57
+ **Lookup order for the tasks directory:** `src/tasks/` → `tasks/` → `dist/tasks/` (first that exists). This is a fixed convention — there is no `tasksDir` config option.
58
+
59
+ ### Dead-letter queue: `efc tasks failed | retry | purge`
60
+
61
+ Jobs that exhausted their retries stay in the backend's failed set. These commands connect to it directly, so they work against a running app from any shell:
62
+
63
+ ```bash
64
+ efc tasks failed # failed jobs + queue counts
65
+ efc tasks failed --name SendEmail -n 50
66
+ efc tasks failed --json # machine-readable
67
+ efc tasks retry 1842 1843 # re-queue (one more attempt each)
68
+ efc tasks retry --all
69
+ efc tasks purge 1842 # delete
70
+ efc tasks purge --all
71
+ ```
72
+
73
+ ```
74
+ Queue waiting=0 active=1 delayed=2 completed=318 failed=1
75
+
76
+ ✗ SendEmail #1842 attempts=4 2026-10-10T12:00:01.000Z
77
+ SMTP connection refused
78
+ data: {"to":"ada@example.com","subject":"Welcome"}
79
+ ```
80
+
81
+ | Option | Meaning |
82
+ |---|---|
83
+ | `--backend <bullmq\|pg-boss>` | Default: BullMQ if `REDIS_URL` is set, else pg-boss for a `postgres` `DATABASE_URL` |
84
+ | `--queue <name>` | `tasks.queue` from `ignite()` (default `efc`) |
85
+ | `--redis-url <url>` | BullMQ connection (default `REDIS_URL`, from the environment or `.env`) |
86
+ | `--database-url <url>` | pg-boss connection (default `DATABASE_URL`) |
87
+
88
+ ---
89
+
90
+ ## `efc doctor`
91
+
92
+ Validates your project setup and reports any problems.
93
+
94
+ ```bash
95
+ efc doctor
96
+ ```
97
+
98
+ **Checks performed:**
99
+
100
+ | Check | What it validates |
101
+ |---|---|
102
+ | `package.json` exists | Project root has a `package.json` |
103
+ | `tsconfig.json` exists | TypeScript config is present; hint: `tsc --init` |
104
+ | `src/api` exists | Route directory is present |
105
+ | `DATABASE_URL` set | `process.env.DATABASE_URL` is non-empty |
106
+ | `JWT_SECRET` set | `process.env.JWT_SECRET` is non-empty |
107
+
108
+ **Sample passing output:**
109
+
110
+ ```
111
+ EFC Doctor
112
+
113
+ ✓ package.json exists
114
+ ✓ tsconfig.json exists
115
+ ✓ src/api directory exists
116
+ ✓ DATABASE_URL set
117
+ ✓ JWT_SECRET set
118
+
119
+ All checks passed!
120
+ ```
121
+
122
+ **Sample failing output:**
123
+
124
+ ```
125
+ EFC Doctor
126
+
127
+ ✓ package.json exists
128
+ ✓ tsconfig.json exists
129
+ ✓ src/api directory exists
130
+ ✗ DATABASE_URL set
131
+ → Add DATABASE_URL to .env
132
+ ✗ JWT_SECRET set
133
+ → Add JWT_SECRET to .env (generate: openssl rand -hex 64)
134
+
135
+ Some checks failed. Fix the issues above.
136
+ ```
137
+
138
+ Exits with code `1` if any check fails.
139
+
140
+ **Note:** `efc doctor` reads `DATABASE_URL` and `JWT_SECRET` from `process.env`. In development, source `.env` before running the command — or run it via `npm run dev` which loads `.env` automatically.
141
+
142
+ ```bash
143
+ # Quick way to run doctor with .env loaded:
144
+ source .env && efc doctor
145
+ ```
@@ -0,0 +1,120 @@
1
+ # `efc generate`
2
+
3
+ Scaffold boilerplate files without hand-writing them. All generators write TypeScript files and refuse to overwrite existing files.
4
+
5
+ The command also accepts the alias `efc g`.
6
+
7
+ ---
8
+
9
+ ## `efc generate route <routePath>`
10
+
11
+ Creates a route module at `src/api/<routePath>.ts`.
12
+
13
+ ```bash
14
+ efc generate route users
15
+ efc generate route users/[id]
16
+ efc generate route posts/[slug]/comments
17
+ ```
18
+
19
+ The generated file exports `GET` and `POST` stubs:
20
+
21
+ ```ts
22
+ // src/api/users/[id].ts (after: efc generate route users/[id])
23
+ import type { Request, Response } from 'express';
24
+
25
+ export const GET = async (req: Request, res: Response) => {
26
+ res.json({ message: 'OK' });
27
+ };
28
+
29
+ export const POST = async (req: Request, res: Response) => {
30
+ res.status(201).json({ message: 'Created' });
31
+ };
32
+ ```
33
+
34
+ The path argument is relative to `src/api/`. Parent directories are created automatically.
35
+
36
+ | Command | Output file | Route URL |
37
+ |---|---|---|
38
+ | `efc generate route health` | `src/api/health.ts` | `/health` |
39
+ | `efc generate route users/[id]` | `src/api/users/[id].ts` | `/users/:id` |
40
+ | `efc generate route posts/[slug]/comments` | `src/api/posts/[slug]/comments.ts` | `/posts/:slug/comments` |
41
+
42
+ ---
43
+
44
+ ## `efc generate task <name>`
45
+
46
+ Creates a task module at `src/tasks/<name>.ts`.
47
+
48
+ ```bash
49
+ efc generate task SendEmail
50
+ efc generate task ResizeImage
51
+ efc generate task ProcessPayment
52
+ ```
53
+
54
+ The generated file exports a typed `defineTask` skeleton:
55
+
56
+ ```ts
57
+ // src/tasks/SendEmail.ts (after: efc generate task SendEmail)
58
+ import { defineTask } from 'express-file-cluster/tasks';
59
+
60
+ interface SendEmailPayload {
61
+ // TODO: define payload fields
62
+ }
63
+
64
+ export default defineTask<SendEmailPayload>(async (payload) => {
65
+ // TODO: implement task logic
66
+ console.log('[Task:SendEmail]', payload);
67
+ });
68
+ ```
69
+
70
+ The task is registered automatically when the app starts — no extra wiring required.
71
+
72
+ ---
73
+
74
+ ## `efc generate middleware <name>`
75
+
76
+ Creates a middleware module at `src/middlewares/<name>.ts`.
77
+
78
+ ```bash
79
+ efc generate middleware authorize
80
+ efc generate middleware validateBody
81
+ efc generate middleware requestLogger
82
+ ```
83
+
84
+ The generated file exports a plain Express `RequestHandler`:
85
+
86
+ ```ts
87
+ // src/middlewares/authorize.ts (after: efc generate middleware authorize)
88
+ import type { Request, Response, NextFunction } from 'express';
89
+
90
+ export function authorize(req: Request, res: Response, next: NextFunction): void {
91
+ // TODO: implement middleware logic
92
+ next();
93
+ }
94
+ ```
95
+
96
+ ---
97
+
98
+ ## `efc generate migration <name>`
99
+
100
+ Creates `src/migrations/<UTC timestamp>_<snake_name>.ts` (`.js` without a `tsconfig.json`) with `up` / `down` stubs. Run it with `efc db migrate`. See [Migrations & Seeds](../guides/migrations.md).
101
+
102
+ ```bash
103
+ efc generate migration AddOrders # → src/migrations/20261010120000_add_orders.ts
104
+ ```
105
+
106
+ ---
107
+
108
+ ## `efc generate seed <name>`
109
+
110
+ Creates `src/seeds/<snake_name>.ts` exporting a default seed function. Run it with `efc db seed` or `efc db seed <snake_name>`.
111
+
112
+ ---
113
+
114
+ ## Error: file already exists
115
+
116
+ If the target file already exists, the generator prints an error and exits with code 1 — it never overwrites existing files:
117
+
118
+ ```
119
+ File already exists: src/api/users/[id].ts
120
+ ```
@@ -0,0 +1,48 @@
1
+ # CLI Reference
2
+
3
+ EFC ships a single `efc` binary installed as a dev dependency when you use `create-efc-app`. The scaffolder (`npx create-efc-app`) is a separate one-time tool.
4
+
5
+ ---
6
+
7
+ ## Installation
8
+
9
+ The `efc` binary is automatically available after scaffolding. For a manual install:
10
+
11
+ ```bash
12
+ npm install --save-dev express-file-cluster
13
+ ```
14
+
15
+ **Global vs project install.** `create-efc-app` also installs `efc` globally for convenience. Run inside a project, a global `efc` hands every command to the project's own `node_modules/express-file-cluster` — so commands always use the project's version, its database drivers and a single copy of the framework. Outside a project, the global install runs itself.
16
+
17
+ ---
18
+
19
+ ## Command overview
20
+
21
+ | Command | Description |
22
+ |---|---|
23
+ | `efc start dev` | Development server — hot-reload, single process |
24
+ | `efc start prod` | Production server — runs `dist/` with clustering |
25
+ | `efc build prod` | Type-check + transpile `src/` to `dist/src/` |
26
+ | `efc run tests` | Run tests via Vitest |
27
+ | `efc generate route <path>` | Scaffold a route file |
28
+ | `efc generate task <name>` | Scaffold a task file |
29
+ | `efc generate middleware <name>` | Scaffold a middleware file |
30
+ | `efc generate migration <name>` | Scaffold a timestamped migration |
31
+ | `efc generate seed <name>` | Scaffold a seed script |
32
+ | `efc db migrate \| rollback \| status` | Run, revert and inspect migrations |
33
+ | `efc db seed [name]` | Run seed scripts |
34
+ | `efc db studio` | Read-only database browser on 127.0.0.1 |
35
+ | `efc routes` | Print the resolved route table |
36
+ | `efc tasks` | List registered background tasks |
37
+ | `efc tasks failed \| retry \| purge` | Inspect and act on dead-lettered jobs |
38
+ | `efc doctor` | Validate config, env vars, and project setup |
39
+ | `efc --version` | Print the installed version |
40
+
41
+ ---
42
+
43
+ ## Detailed pages
44
+
45
+ - [start / build / run](./start.md) — Lifecycle commands
46
+ - [generate](./generate.md) — Code generation
47
+ - [db](./db.md) — migrations, seeds, studio
48
+ - [diagnostics](./diagnostics.md) — `routes`, `tasks` (incl. dead letters), `doctor`
@@ -0,0 +1,112 @@
1
+ # `efc start` / `efc build` / `efc run`
2
+
3
+ ## `efc start dev`
4
+
5
+ Starts the development server.
6
+
7
+ ```bash
8
+ efc start dev
9
+ ```
10
+
11
+ **Behaviour:**
12
+
13
+ - Reads `.env` from the project root and injects variables into `process.env`. Variables already present in the environment take precedence.
14
+ - Defaults `NODE_ENV` to `'development'`. A `NODE_ENV` value in `.env` or in the parent environment overrides this default.
15
+ - Locates the entry point by checking these paths in order:
16
+ 1. `src/index.ts`
17
+ 2. `index.ts`
18
+ 3. `src/index.js`
19
+ 4. `index.js`
20
+ - Launches the entry point via `tsx watch --include src <entry>` for hot-reload on every file change inside `src/`.
21
+ - **Clustering is off in development** — `ignite()` defaults `cluster` to `false` when `NODE_ENV !== 'production'`. This gives fast restarts and clean stack traces.
22
+
23
+ **Requires:** `tsx` installed (either as a project dependency in `node_modules/.bin/tsx`, or globally on `PATH`).
24
+
25
+ ---
26
+
27
+ ## `efc start prod`
28
+
29
+ Starts the production server from compiled output.
30
+
31
+ ```bash
32
+ efc start prod
33
+ ```
34
+
35
+ **Behaviour:**
36
+
37
+ - Looks for `dist/src/index.js` (the `efc build prod` layout), then `dist/index.js` (a custom `tsup.config`). If neither exists, prints an error instructing you to run `efc build prod` first.
38
+ - Sets `NODE_ENV=production`.
39
+ - Does **not** read `.env` — secrets must come from the platform's environment.
40
+ - Spawns `node dist/src/index.js`.
41
+ - Forwards `SIGTERM`/`SIGINT` to the server so `gracefulShutdown()` runs, and exits with the server's exit code.
42
+ - With `NODE_ENV=production`, `ignite()` defaults `cluster` to `true` and forks `os.cpus().length` workers. When the primary receives `SIGTERM` it relays it to every worker, waits for them to drain, then exits.
43
+
44
+ ---
45
+
46
+ ## `efc build prod`
47
+
48
+ Compiles the project to JavaScript in `dist/`.
49
+
50
+ ```bash
51
+ efc build prod
52
+ ```
53
+
54
+ **Behaviour:**
55
+
56
+ - Type-checks with `tsc --noEmit` when a `tsconfig.json` exists (skipped for JavaScript projects).
57
+ - Transpiles **every** file under `src/` plus `efc.config.ts` with `tsup`, one output file per source file, keeping the directory tree:
58
+
59
+ ```
60
+ src/index.ts → dist/src/index.js
61
+ src/api/users/[id].ts → dist/src/api/users/[id].js
62
+ src/tasks/SendEmail.ts → dist/src/tasks/SendEmail.js
63
+ efc.config.ts → dist/efc.config.js
64
+ ```
65
+
66
+ Files are not bundled: routes and tasks are discovered by scanning the filesystem at runtime, so each one must exist in `dist/` as its own file. Test files (`*.test.*`, `__tests__/`) are skipped.
67
+ - Output format follows `package.json` `"type"` — ESM for `"module"`, CommonJS otherwise.
68
+ - If the project has its own `tsup.config.*`, that config is used instead.
69
+
70
+ **Requires:** `tsup` installed as a dev dependency.
71
+
72
+ ---
73
+
74
+ ## `efc run tests`
75
+
76
+ Runs the test suite.
77
+
78
+ ```bash
79
+ efc run tests
80
+ ```
81
+
82
+ **Behaviour:**
83
+
84
+ - Invokes Vitest.
85
+ - Pass Vitest flags through directly:
86
+
87
+ ```bash
88
+ efc run tests --watch
89
+ efc run tests --coverage
90
+ efc run tests --reporter=verbose
91
+ ```
92
+
93
+ **Requires:** `vitest` installed as a dev dependency.
94
+
95
+ ---
96
+
97
+ ## `package.json` lifecycle scripts
98
+
99
+ The scaffolder wires these scripts automatically:
100
+
101
+ ```json
102
+ {
103
+ "scripts": {
104
+ "dev": "efc start dev",
105
+ "build": "efc build prod",
106
+ "start": "efc start prod",
107
+ "test": "efc run tests"
108
+ }
109
+ }
110
+ ```
111
+
112
+ Use `npm run dev`, `npm run build`, `npm start`, and `npm test` as shorthand.
@@ -0,0 +1,139 @@
1
+ # Contributing
2
+
3
+ ## Repository layout
4
+
5
+ ```
6
+ packages/
7
+ core/ → express-file-cluster (the framework)
8
+ create-efc-app/ → interactive scaffolder CLI
9
+ client/ → marketing site (static HTML/JS)
10
+ Skills/efc/ → reference cards for the /efc assistant skill
11
+ ```
12
+
13
+ ---
14
+
15
+ ## Getting started
16
+
17
+ ```bash
18
+ git clone https://github.com/your-org/efc.js.git
19
+ cd efc.js
20
+
21
+ # Install all workspace dependencies
22
+ npm install
23
+
24
+ # Build all packages
25
+ npm run build
26
+
27
+ # Run the test suite
28
+ npm test
29
+
30
+ # Type-check
31
+ npm run typecheck
32
+
33
+ # Lint
34
+ npm run lint
35
+ ```
36
+
37
+ ---
38
+
39
+ ## Integration and end-to-end tests
40
+
41
+ Integration tests skip themselves when a service isn't reachable, so `npm test` works with nothing running — but for full coverage start MongoDB (plus a single-node replica set for transactions), Redis and PostgreSQL, and point the tests at them:
42
+
43
+ | Variable | Default |
44
+ |---|---|
45
+ | `EFC_TEST_MONGO_URL` | `mongodb://127.0.0.1:27017/...` |
46
+ | `EFC_TEST_MONGO_RS_URL` | `mongodb://127.0.0.1:27018/...?replicaSet=rs0&directConnection=true` |
47
+ | `EFC_TEST_REDIS_URL` | `redis://127.0.0.1:6379/15` |
48
+ | `EFC_TEST_PG_URL` | `postgres://postgres@127.0.0.1:5433/efc_test` |
49
+
50
+ The cluster and CLI tests run the built `dist/`, so `npm run build` first.
51
+
52
+ The scaffolder end-to-end suite generates real projects (MongoDB + BullMQ, PostgreSQL + pg-boss, and a JavaScript project), installs them against a packed tarball of `packages/core`, then migrates, runs the dev server, builds, boots and exercises auth over HTTP:
53
+
54
+ ```bash
55
+ npm run build
56
+ EFC_E2E=1 npx vitest run --project create-efc-app e2e
57
+ EFC_E2E=1 EFC_E2E_KEEP=1 npx vitest run --project create-efc-app e2e # keep the generated apps to inspect
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Branch naming
63
+
64
+ | Type | Pattern | Example |
65
+ |---|---|---|
66
+ | Feature | `feat/<topic>` | `feat/postgresql-adapter` |
67
+ | Bug fix | `fix/<topic>` | `fix/route-sort-order` |
68
+ | Documentation | `docs/<topic>` | `docs/task-guide` |
69
+ | Chore | `chore/<topic>` | `chore/bump-bullmq` |
70
+
71
+ ---
72
+
73
+ ## Commit messages
74
+
75
+ Follow [Conventional Commits](https://www.conventionalcommits.org/):
76
+
77
+ ```
78
+ feat(router): support catch-all wildcard routes
79
+ fix(cluster): prevent infinite respawn loop on startup crash
80
+ docs(auth): add localStorage strategy example
81
+ chore(deps): upgrade jose to v5
82
+ ```
83
+
84
+ ---
85
+
86
+ ## Pull requests
87
+
88
+ Every PR must:
89
+
90
+ - Include tests for changed behaviour (unit or integration via Vitest).
91
+ - Pass `npm test`, `npm run lint`, and `npm run typecheck` in CI.
92
+ - Include a changelog entry under `Unreleased` in `CHANGELOG.md`.
93
+
94
+ ---
95
+
96
+ ## Package architecture
97
+
98
+ ### `packages/core`
99
+
100
+ The framework package published as `express-file-cluster`. Sub-path exports:
101
+
102
+ | Import | Source |
103
+ |---|---|
104
+ | `express-file-cluster` | `src/index.ts` — `ignite`, `gracefulShutdown`, `HttpError`, `compose`, `db`, `defineModel` |
105
+ | `express-file-cluster/auth` | `src/auth/index.ts` — `issueToken`, `revokeToken`, `revokeSession`, `revokeAllSessions`, `signToken`, `requireAuth`, `getCurrentUser` |
106
+ | `express-file-cluster/tasks` | `src/tasks/index.ts` — `defineTask`, `enqueue` |
107
+ | `express-file-cluster/cli` | `src/cli/index.ts` — the `efc` binary |
108
+
109
+ ### `packages/create-efc-app`
110
+
111
+ Interactive scaffolder published as `create-efc-app`. Invoked with `npx create-efc-app <name>`. Prompts the user and writes the project tree using the templates in `src/scaffold.ts`.
112
+
113
+ ---
114
+
115
+ ## Roadmap
116
+
117
+ | Phase | Target | Focus |
118
+ |---|---|---|
119
+ | **1** | Done | Core MVP — router, clustering, auth, DB, tasks, CLI |
120
+ | **2** | Done | Beta — PostgreSQL, pg-boss, request validation, structured logging, cron tasks, catch-all routes, migrations, `defineModel` upgrades |
121
+ | **3** | Q1 2027 | Stable v1.0 — plugins, WebSockets, OpenAPI, OpenTelemetry, testing utilities |
122
+ | **4** | 2027+ | Edge/serverless, gRPC, GraphQL |
123
+
124
+ ### Bug fix SLA
125
+
126
+ | Severity | SLA | Example |
127
+ |---|---|---|
128
+ | **P0 — Critical** | Patch within 48 h | Data loss, auth bypass, crash on startup |
129
+ | **P1 — High** | Patch within 1 week | Route not resolving, worker not respawning, task silently dropped |
130
+ | **P2 — Medium** | Next minor release | Wrong TypeScript types, misleading error message |
131
+ | **P3 — Low** | Best effort | Cosmetic CLI issues, doc typos |
132
+
133
+ ---
134
+
135
+ ## Influencing the roadmap
136
+
137
+ 1. **Open a GitHub Discussion** — propose a feature or share a use case.
138
+ 2. **Upvote issues** — 👍 reactions influence prioritisation.
139
+ 3. **Submit a PR** — the fastest path from idea to shipping.