@niyamulahsan/create-deskapp 1.2.5 → 1.2.6

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 (104) hide show
  1. package/package.json +1 -1
  2. package/template/.env.example +20 -13
  3. package/template/AGENTS.md +699 -0
  4. package/template/package.json +3 -0
  5. package/template/src/config/app.ts +26 -24
  6. package/template/src/config/winsetup.ts +93 -91
  7. package/template/src/core/api/binding-error.ts +57 -0
  8. package/template/src/core/api/bindings.generated.ts +2 -0
  9. package/template/src/core/api/generate.manifest.ts +84 -80
  10. package/template/src/core/api/registry.ts +58 -48
  11. package/template/src/core/config.ts +101 -99
  12. package/template/src/core/database/aggregate.ts +89 -85
  13. package/template/src/core/database/config.ts +50 -48
  14. package/template/src/core/database/connection.ts +116 -114
  15. package/template/src/core/database/migrate-hooks.ts +86 -84
  16. package/template/src/core/database/paginate.ts +226 -224
  17. package/template/src/core/database/reset.ts +21 -19
  18. package/template/src/core/database/seed.ts +169 -167
  19. package/template/src/core/database/status.ts +37 -35
  20. package/template/src/core/env.ts +108 -106
  21. package/template/src/core/facade.ts +63 -61
  22. package/template/src/core/maker/db/fresh.ts +10 -8
  23. package/template/src/core/maker/db/generate.ts +13 -11
  24. package/template/src/core/maker/db/helpers.ts +92 -96
  25. package/template/src/core/maker/db/migrate.ts +37 -35
  26. package/template/src/core/maker/db/mod.ts +93 -91
  27. package/template/src/core/maker/db/module-migrate.ts +56 -54
  28. package/template/src/core/maker/db/push.ts +23 -21
  29. package/template/src/core/maker/db/reset.ts +8 -6
  30. package/template/src/core/maker/db/seed.ts +9 -7
  31. package/template/src/core/maker/db/status.ts +8 -6
  32. package/template/src/core/maker/help.ts +59 -57
  33. package/template/src/core/maker/make/controller.ts +25 -22
  34. package/template/src/core/maker/make/helpers.ts +97 -91
  35. package/template/src/core/maker/make/mod.ts +69 -67
  36. package/template/src/core/maker/make/model.ts +16 -14
  37. package/template/src/core/maker/make/module.ts +53 -39
  38. package/template/src/core/maker/make/seeder.ts +23 -21
  39. package/template/src/core/maker/make/test.ts +33 -30
  40. package/template/src/core/maker/mod.ts +85 -83
  41. package/template/src/core/maker/run/mod.ts +134 -132
  42. package/template/src/core/maker/stub.ts +26 -24
  43. package/template/src/core/maker/stubs/controller/controller.controller.stub +57 -55
  44. package/template/src/core/maker/stubs/controller/controller.schema.stub +18 -13
  45. package/template/src/core/maker/stubs/facade/facade.stub +21 -0
  46. package/template/src/core/maker/stubs/model/model.stub +10 -8
  47. package/template/src/core/maker/stubs/seeder/seeder.stub +18 -16
  48. package/template/src/core/maker/stubs/test/test.stub +9 -7
  49. package/template/src/core/maker/sync-config.ts +93 -94
  50. package/template/src/core/utils/password.ts +29 -27
  51. package/template/src/core/utils/playwright.ts +123 -121
  52. package/template/src/core/utils/queue.ts +68 -66
  53. package/template/src/core/utils/scheduler.ts +62 -60
  54. package/template/src/core/utils/storage.ts +3 -1
  55. package/template/src/core/utils/validation.ts +37 -35
  56. package/template/src/database/schema.ts +2 -0
  57. package/template/src/main.ts +120 -118
  58. package/template/src/modules/app/__tests__/demo.controller.test.ts +75 -0
  59. package/template/src/modules/app/__tests__/net.controller.test.ts +65 -0
  60. package/template/src/modules/app/__tests__/playwright.controller.test.ts +50 -0
  61. package/template/src/modules/app/__tests__/storage.controller.test.ts +114 -0
  62. package/template/src/modules/app/__tests__/window.controller.test.ts +98 -0
  63. package/template/src/modules/app/controllers/demo.controller.ts +120 -118
  64. package/template/src/modules/app/controllers/net.controller.ts +50 -48
  65. package/template/src/modules/app/controllers/playwright.controller.ts +142 -140
  66. package/template/src/modules/app/controllers/storage.controller.ts +231 -229
  67. package/template/src/modules/app/controllers/window.controller.ts +2 -0
  68. package/template/src/modules/app/facade.ts +21 -0
  69. package/template/src/preload.ts +25 -2
  70. package/template/src/ui/src/App.vue +4 -2
  71. package/template/src/ui/src/app.ts +38 -23
  72. package/template/src/ui/src/bindings.d.ts +18 -16
  73. package/template/src/ui/src/components/Button.vue +34 -32
  74. package/template/src/ui/src/components/Checkbox.vue +26 -29
  75. package/template/src/ui/src/components/Input.vue +221 -227
  76. package/template/src/ui/src/components/InputGroup.vue +141 -0
  77. package/template/src/ui/src/components/InputPasswordToggle.vue +204 -0
  78. package/template/src/ui/src/components/Modal.vue +65 -55
  79. package/template/src/ui/src/components/Spinner.vue +44 -42
  80. package/template/src/ui/src/components/Switch.vue +62 -65
  81. package/template/src/ui/src/components/TextArea.vue +108 -121
  82. package/template/src/ui/src/components/Toast.vue +55 -56
  83. package/template/src/ui/src/components/datatable/DataTableSkeleton.vue +100 -98
  84. package/template/src/ui/src/components/datatable/Pagination.vue +153 -125
  85. package/template/src/ui/src/components/datatable/SelectOpption.vue +36 -35
  86. package/template/src/ui/src/components/datatable/index.vue +336 -258
  87. package/template/src/ui/src/env.d.ts +16 -13
  88. package/template/src/ui/src/global.d.ts +21 -2
  89. package/template/src/ui/src/helpers/nformatter.ts +12 -10
  90. package/template/src/ui/src/pages/dashboard/index.vue +690 -687
  91. package/template/src/ui/src/plugins/browserDetect.ts +57 -0
  92. package/template/src/ui/src/plugins/gum.ts +576 -549
  93. package/template/src/ui/src/plugins/pulse.ts +2 -0
  94. package/template/src/ui/src/plugins/routeProgress.ts +89 -0
  95. package/template/src/ui/src/router/index.ts +44 -25
  96. package/template/src/ui/src/stores/example.ts +2 -0
  97. package/template/src/ui/vite.config.ts +40 -38
  98. package/template/src/window/app-menu.ts +89 -87
  99. package/template/src/window/config.ts +14 -12
  100. package/template/src/window/context-menu.ts +23 -21
  101. package/template/src/window/dialogs.ts +92 -90
  102. package/template/src/window/manager.ts +2 -0
  103. package/template/src/window/native.ts +47 -45
  104. package/template/src/window/tray.ts +132 -130
@@ -0,0 +1,699 @@
1
+ # AGENTS.md — deskapp
2
+
3
+ You are working in a **deskapp** application: a desktop app built on **Electron**
4
+ (the main process is your backend), a **Vue 3** renderer, and **Drizzle + SQLite**.
5
+ This file is the contract. Read it before writing any code and follow it exactly.
6
+ **A change that breaks a rule is wrong even if it compiles and every test passes.**
7
+
8
+ - Docs: https://niyamulahsan.github.io/deskapp/
9
+ - AI index (one file, every page): https://niyamulahsan.github.io/deskapp/llms.txt
10
+ - Full docs (single file): https://niyamulahsan.github.io/deskapp/llms-full.txt
11
+ - Conventions: https://niyamulahsan.github.io/deskapp/guide/conventions
12
+ - Modules: https://niyamulahsan.github.io/deskapp/guide/modules
13
+ - Controllers & bindings: https://niyamulahsan.github.io/deskapp/guide/controllers
14
+ - Database: https://niyamulahsan.github.io/deskapp/guide/database
15
+ - UI & gum: https://niyamulahsan.github.io/deskapp/guide/gum
16
+ - Testing: https://niyamulahsan.github.io/deskapp/guide/testing
17
+ - Facade / API reference: https://niyamulahsan.github.io/deskapp/api/
18
+
19
+ If a rule here conflicts with something you "know" from another framework, this
20
+ file wins. If a rule here conflicts with the linked docs, the docs win — report
21
+ the discrepancy, do not silently pick one.
22
+
23
+ ## 0. Non-negotiables
24
+
25
+ These override every other habit. A change that breaks one of them is wrong even
26
+ if it compiles and every test passes.
27
+
28
+ 1. **Never edit `src/core/**`.** It is the framework, not your application. Your
29
+ code lives in `src/modules/**`, `src/config/**`, `src/ui/**`, `src/main.ts`
30
+ and `src/preload.ts`. `src/window/**` is framework internals too — consume it
31
+ through the facade — **except** the desktop-chrome files
32
+ `src/window/app-menu.ts`, `src/window/context-menu.ts` and `src/window/tray.ts`,
33
+ which are the intended place to customize the app menu, right-click menu and
34
+ tray.
35
+ 2. **Never hand-edit generated files.** These are produced by the maker and are
36
+ overwritten without warning:
37
+ - `src/core/api/bindings.generated.ts` (`npm run maker -- bindings:gen`)
38
+ - `src/database/schema.ts` (`npm run maker -- db:schema`)
39
+ - `src/database/migrations/**` (`npm run maker -- db:generate`)
40
+ Regenerate them with the command instead.
41
+ 3. **Directory = meaning.** The framework discovers code by folder, never by a
42
+ manifest you maintain by hand. Controllers are only discovered as
43
+ `src/modules/<module>/controllers/<controller>.controller.ts` (files must end
44
+ in `.controller.ts`). Models live in `database/models/`, seeders in
45
+ `database/seeders/`, tests in `__tests__/`. A file anywhere else is invisible.
46
+ 4. **Every controller must export a `handlers` map.** A handler that is not in
47
+ `handlers` is never registered and can never be called from the UI. The
48
+ registry reads exactly this map.
49
+ 5. **Import framework utilities from `@/core/facade`.** Do not reach into
50
+ `@/core/**` internals from app modules. (The framework's own sample
51
+ controllers occasionally import a deep helper the facade does not expose,
52
+ e.g. `ensurePlaywrightBrowser` from `@/core/utils/playwright` — treat that as
53
+ an exception, never a pattern. If you need something, prefer the facade.)
54
+ 6. **The renderer never imports backend code.** `src/ui/**` must not import
55
+ `@/core/**`, `@/modules/**`, `electron`, `node:*`, or `drizzle-orm`. The UI
56
+ reaches the backend **only** through `bindings`/`md`. The backend must not
57
+ import from `src/ui/**` either.
58
+ 7. **Every source file opens with its location header on line 1, then one blank
59
+ line.** The header is `// ./<path-from-project-root>`, e.g.
60
+ `// ./src/modules/blog/controllers/post.controller.ts`; a Vue SFC uses the HTML
61
+ form, e.g. `<!-- ./src/ui/src/pages/dashboard/index.vue -->`. Keep it in place —
62
+ never remove it and never add a second one. `maker` writes it on every file it
63
+ scaffolds.
64
+ 8. **After adding or removing a controller, run `npm run maker -- bindings:gen`**
65
+ (or `npm run maker -- codegen` for schema + bindings). Packaged builds read
66
+ the generated manifest; an un-regenerated binding does not exist at runtime.
67
+
68
+ ## 1. Project layout
69
+
70
+ ```
71
+ src/
72
+ main.ts # Electron main entry — boots env, db, storage, bindings, windows
73
+ preload.ts # contextBridge: exposes bindings/md to the renderer
74
+ config/
75
+ app.ts # app identity (name, productName, appId, protocol) — edit this
76
+ winsetup.ts # window presets + dev-tools mode + chrome flags — edit this
77
+ modules/ # YOUR application code
78
+ <module>/
79
+ facade.ts # public API of the module (cross-module imports)
80
+ controllers/
81
+ <name>.controller.ts # named handlers + `handlers` map (required to be callable)
82
+ <name>.schema.ts # Zod schemas + inferred `<X>Type` for that controller
83
+ database/
84
+ models/<name>.model.ts # Drizzle sqlite table
85
+ seeders/<name>.seed.ts # default-export seeder (+ `table`)
86
+ __tests__/<name>.test.ts # Vitest
87
+ core/ # framework internals — DO NOT EDIT
88
+ facade.ts # the public API surface you import from
89
+ api/registry.ts # binds handlers to ipcMain
90
+ api/bindings.generated.ts # GENERATED — controller manifest
91
+ database/{connection,paginate,config,...}.ts
92
+ utils/{queue,scheduler,storage,validation,password,playwright}.ts
93
+ maker/** # the `npm run maker` CLI
94
+ window/ # window manager / native chrome / dialogs
95
+ app-menu.ts, context-menu.ts, tray.ts # menu & tray — edit these to customize desktop chrome
96
+ database/
97
+ schema.ts # GENERATED — aggregates every model
98
+ migrations/ # GENERATED
99
+ storage/ # runtime storage root (git-ignored; CLI/dev fallback)
100
+ ui/ # the Vue 3 renderer
101
+ vite.config.ts
102
+ tsconfig.json
103
+ src/
104
+ app.ts # createApp + plugins (head, Pinia, Pulse, Gum, router)
105
+ App.vue # <router-view/>
106
+ router/index.ts # routes
107
+ pages/<name>/index.vue # pages
108
+ components/ # shared components (DataTable lives here)
109
+ stores/<name>.ts # Pinia stores
110
+ plugins/{gum,pulse}.ts # request/form helper + realtime
111
+ bindings.d.ts, env.d.ts, global.d.ts
112
+ assets/
113
+ drizzle.config.ts # drizzle-kit config (mirrors the runtime DB path)
114
+ vitest.config.ts, biome.json, tsconfig.json, package.json
115
+ ```
116
+
117
+ ## 2. Module anatomy
118
+
119
+ A module is a self-contained feature under `src/modules/<name>/`. Create one with:
120
+
121
+ ```sh
122
+ npm run maker make:module blog # module + model + seeder + controller + schema + facade
123
+ npm run maker make:controller blog Post # add another controller (+ schema) to a module
124
+ npm run maker make:model blog Post # add a model
125
+ npm run maker make:seeder blog Post # add a seeder (model must already exist)
126
+ npm run maker make:test blog Post # add a Vitest file under __tests__/
127
+ ```
128
+
129
+ Names are lower-cased by the maker. A model named `Post` produces
130
+ `database/models/post.model.ts` exporting a table variable `posts` with the SQL
131
+ table name `posts`. The same lower-cased `<name>` is the controller key, so
132
+ `make:controller blog Post` binds handlers under `blog.post.<handler>`.
133
+
134
+ Rules:
135
+
136
+ - One concern per file. A controller file exports handlers **and** the `handlers`
137
+ map; schemas go in the sibling `<name>.schema.ts`.
138
+ - The module folder name is the binding namespace. `src/modules/blog/...` binds as
139
+ `blog.<controller>.<handler>`.
140
+ - **Cross-module access goes through the module's `facade.ts`.** Import from
141
+ `@/modules/<other>/facade`, never from its `controllers/` or `database/`
142
+ directly. The facade re-exports the pieces other modules may depend on — the
143
+ module's controller handlers and its model(s). The one exception is a Drizzle
144
+ `relations()` reference to another module's model, which may import the model
145
+ file directly.
146
+ - Facade rules: a module **never** imports its own facade, and a facade **never**
147
+ imports another facade. `make:module` scaffolds it as a namespace re-export of
148
+ the module's controller plus its model:
149
+ `export * as <module> from "./controllers/<module>.controller"` and
150
+ `export * from "./database/models/<module>.model"`. Add another namespace line
151
+ (`export * as post from "./controllers/post.controller"`) for each extra
152
+ controller other modules may use.
153
+
154
+ ## 3. Controllers & bindings
155
+
156
+ A controller is a file that exports named handlers plus a `handlers` map. The
157
+ registry (`src/core/api/registry.ts`) reads the generated manifest, takes each
158
+ controller's `handlers`, and registers every entry with Electron's `ipcMain` as
159
+ `deskapp:<module>.<controller>.<handler>`. The preload then exposes it to the
160
+ renderer as `bindings['<module>.<controller>.<handler>'](...)` and, nested, as
161
+ `md.<module>.<controller>.<handler>(...)`.
162
+
163
+ Canonical shape (this is exactly what `make:controller` generates):
164
+
165
+ ```ts
166
+ // ./src/modules/blog/controllers/post.controller.ts
167
+
168
+ import { validate } from "@/core/facade";
169
+ import { CreatePostSchema, PostIdParamsSchema, UpdatePostSchema } from "@/modules/blog/controllers/post.schema";
170
+
171
+ export const index = async () => {
172
+ return { message: "post list fetched successfully", data: [] };
173
+ };
174
+
175
+ export const show = async (params: unknown) => {
176
+ const { id } = await validate.run(PostIdParamsSchema, params);
177
+ return { message: "post fetched successfully", data: { id, name: "" } };
178
+ };
179
+
180
+ export const store = async (body: unknown) => {
181
+ await validate.run(CreatePostSchema, body);
182
+ return { message: "post created successfully" };
183
+ };
184
+
185
+ export const update = async (input: { params: unknown; body: unknown }) => {
186
+ await validate.run(PostIdParamsSchema, input.params);
187
+ await validate.run(UpdatePostSchema, input.body);
188
+ return { message: "post updated successfully" };
189
+ };
190
+
191
+ export const destroy = async (params: unknown) => {
192
+ await validate.run(PostIdParamsSchema, params);
193
+ return { message: "post deleted successfully" };
194
+ };
195
+
196
+ /** Handlers exposed to the frontend via the bindings registry. */
197
+ export const handlers = { index, show, store, update, destroy };
198
+ ```
199
+
200
+ Rules:
201
+
202
+ - Handlers receive **plain JSON args** (everything crosses IPC). Validate and
203
+ narrow `unknown` before using it.
204
+ - Return JSON-serializable values. Never return a Drizzle row with non-plain
205
+ fields, an Electron object, or a `File` — shape the payload first.
206
+ - Prefer the conventional handler names `index` / `show` / `store` / `update` /
207
+ `destroy`; `gum` and `DataTable` assume this payload contract (see §11).
208
+ - Calling from the renderer — both forms are equivalent:
209
+
210
+ ```ts
211
+ const rows = await bindings["blog.post.index"](); // flat (typed via bindings.d.ts)
212
+ const rows2 = await md.blog.post.index(); // nested (nicer, untyped)
213
+ ```
214
+
215
+ - `bindings` is the documented global; `md` is the nested alias. Types for
216
+ `bindings` live in `src/ui/src/bindings.d.ts` (it does not type `md`).
217
+ - The preload also exposes `bindings.__invoke(name, ...args)` as a fallback for
218
+ any name — treat it as an escape hatch, not the normal path.
219
+ - Adding/removing a controller is **not** live until you regenerate the manifest:
220
+ `npm run maker -- bindings:gen`, then restart Electron.
221
+
222
+ ## 4. Schemas & validation
223
+
224
+ Schemas are Zod and are the **single source of truth for input and its type**.
225
+ Put them in the controller's sibling `<name>.schema.ts`. Every schema is paired
226
+ with its inferred type on the next line — `z.input` for a request shape (a
227
+ `.default()` field stays optional), `z.infer` for a response shape:
228
+
229
+ ```ts
230
+ // ./src/modules/blog/controllers/post.schema.ts
231
+
232
+ import { z } from "zod";
233
+
234
+ export const CreatePostSchema = z.object({ name: z.string().min(1) });
235
+ export type CreatePostType = z.input<typeof CreatePostSchema>;
236
+
237
+ export const UpdatePostSchema = z.object({ name: z.string().min(1) });
238
+ export type UpdatePostType = z.input<typeof UpdatePostSchema>;
239
+
240
+ export const PostIdParamsSchema = z.object({ id: z.coerce.number().int().positive() });
241
+ export type PostIdParamsType = z.input<typeof PostIdParamsSchema>;
242
+ ```
243
+
244
+ - Name the pair `<X>Schema` / `<X>Type`. Import the `*Type` wherever a shape is
245
+ needed — a controller, a store, a helper — instead of re-declaring a body,
246
+ params or query by hand.
247
+
248
+ Run them with the facade's `validate`:
249
+
250
+ ```ts
251
+ import { validate } from "@/core/facade";
252
+
253
+ const data = await validate.run(CreatePostSchema, body); // returns parsed, typed data
254
+ ```
255
+
256
+ - `validate.z` is a re-export of Zod, so `validate.z.object({ ... })` also works
257
+ if you prefer not to import `z` directly. Pick one and stay consistent within a
258
+ file.
259
+ - `validate.run(schema, input)` is **async** and **throws** on failure:
260
+
261
+ ```ts
262
+ { status: 422, message: "Validation failed",
263
+ errors: { formErrors: [], fieldErrors: { email: ["Invalid email"] } } }
264
+ ```
265
+
266
+ `errors` is Zod's `result.error.flatten()`. `gum` normalizes exactly this shape
267
+ into per-field form errors (see §11), so **always validate with `validate.run`**
268
+ rather than calling `schema.parse` yourself.
269
+ - Never trust IPC input. Validate ids (`z.coerce.number()...`) and bodies at the
270
+ top of every handler that reads them.
271
+
272
+ ## 5. Database, models, seeders & pagination
273
+
274
+ `db` is the Drizzle client for SQLite (libsql). `src/main.ts` calls `db.init()`
275
+ at boot; `db.close()` runs on shutdown. Calls before `init()` throw.
276
+
277
+ Models use `drizzle-orm/sqlite-core`:
278
+
279
+ ```ts
280
+ // ./src/modules/blog/database/models/post.model.ts
281
+
282
+ import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
283
+
284
+ export const posts = sqliteTable("posts", {
285
+ id: integer("id").primaryKey({ autoIncrement: true }),
286
+ name: text("name").notNull(),
287
+ createdAt: text("created_at").notNull().default("current_timestamp"),
288
+ updatedAt: text("updated_at").notNull().default("current_timestamp"),
289
+ });
290
+ ```
291
+
292
+ Import a table directly from its module in app code:
293
+
294
+ ```ts
295
+ import { db, sql } from "@/core/facade";
296
+ import { posts } from "@/modules/blog/database/models/post.model";
297
+
298
+ await db.insert(posts).values({ name: "Hello" }).returning();
299
+ const rows = await db.select().from(posts).where(sql`name = ${name}`);
300
+ const one = await db.query.posts.findFirst({ where: (t, { eq }) => eq(t.id, id) });
301
+ ```
302
+
303
+ `src/database/schema.ts` is the **generated aggregate** of every model. Do not
304
+ edit it; regenerate with `npm run maker -- db:schema`. The `import * as schema`
305
+ form is the whole-schema view used by the framework — app code imports tables
306
+ directly.
307
+
308
+ Seeders are default-exported functions with a `table` export (used for FK
309
+ ordering):
310
+
311
+ ```ts
312
+ // ./src/modules/blog/database/seeders/post.seed.ts
313
+
314
+ import { db } from "@/core/database/connection";
315
+ import { posts } from "@/modules/blog/database/models/post.model";
316
+
317
+ export const table = posts;
318
+
319
+ export default async function PostSeeder() {
320
+ const rows: (typeof posts.$inferInsert)[] = [/* ... */];
321
+ for (const row of rows) await db.insert(posts).values(row);
322
+ }
323
+ ```
324
+
325
+ Pagination is nexgen-style via the facade's `paginate` (and `sql` for `where`).
326
+ All three methods return the **same envelope**:
327
+
328
+ ```ts
329
+ type PaginatedResult<T> = {
330
+ current_page: number; data: T[]; first_page_url: string | null; from: number | null;
331
+ last_page: number; last_page_url: string | null; next_page_url: string | null;
332
+ path: string; per_page: number; prev_page_url: string | null; to: number | null; total: number;
333
+ };
334
+ ```
335
+
336
+ | Use | Method |
337
+ | ------------------------------------------------ | ----------------------------------------------------------------------- |
338
+ | Whole table, optional `where`/`orderBy` | `paginate.table(posts, { page, perPage, where, orderBy, path })` |
339
+ | Eager-loaded relations (`db.query.<t>`) | `paginate.model({ table, query: db.query.posts, with, columns, path })` |
340
+ | Full control (`total()` + `data(limit, offset)`) | `paginate.query({ total, data, path })` |
341
+
342
+ `page`/`perPage` are normalized and clamped (`perPage` default 15, `maxPerPage`
343
+ default 100). A list handler that the UI can bind to looks like:
344
+
345
+ ```ts
346
+ export const table = async (opts?: { page?: number; size?: number }) => {
347
+ return paginate.model({
348
+ page: opts?.page,
349
+ perPage: opts?.size,
350
+ path: "blog.post.index",
351
+ table: posts,
352
+ query: db.query.posts,
353
+ });
354
+ };
355
+ ```
356
+
357
+ Database commands (all via the maker):
358
+
359
+ ```sh
360
+ npm run maker db:schema # regenerate src/database/schema.ts from models
361
+ npm run maker db:generate # schema + migration SQL (does not apply)
362
+ npm run maker db:migrate --seed # generate + run migrations + hooks (+ seeders)
363
+ npm run maker db:migrate:module blog # migrate one module's models
364
+ npm run maker db:fresh --seed # wipe + migrate + hooks + seed
365
+ npm run maker db:seed # run seeders (auto FK-ordered), --module <name> for one
366
+ npm run maker db:status # list generated migrations
367
+ npm run maker db:studio # Drizzle Studio GUI
368
+ ```
369
+
370
+ The SQLite file: runtime default is `<userData>/<app-kebab>.sqlite`;
371
+ `drizzle.config.ts` mirrors this with a `./src/storage/<app-kebab>.sqlite`
372
+ fallback for CLI/dev. `DATABASE_URL` overrides both.
373
+
374
+ ## 6. The facade
375
+
376
+ `src/core/facade.ts` is the **only** surface app modules import framework code
377
+ from. Everything is re-exported there:
378
+
379
+ | Export | What it is |
380
+ | ------------------------------ | ---------------------------------------------- |
381
+ | `db` | Drizzle client + `db.init()` / `db.close()` |
382
+ | `paginate`, `sql` | nexgen-style pagination + Drizzle `sql` helper |
383
+ | `validate` | Zod re-export (`validate.z`) + `validate.run` |
384
+ | `pass` | `hashPassword` / `verifyPassword` (bcrypt) |
385
+ | `queue` | Bounded in-process async queue |
386
+ | `cron` | Named cron schedules (croner) |
387
+ | `storage` | App-managed disks (`private` / `tmp`) |
388
+ | `files` | User-file layer (any picked absolute path) |
389
+ | `pickers` | Native open / save / folder dialogs |
390
+ | `alertDialog`, `confirmDialog` | Native message dialogs (async) |
391
+ | `win` | Window lifecycle |
392
+ | `chrome` | Menus, tray, native chrome |
393
+ | `chromium` | Playwright/Chromium locator |
394
+
395
+ ```ts
396
+ import { db, paginate, sql, validate, pass, queue, cron, storage, files, pickers, win, chrome } from "@/core/facade";
397
+ ```
398
+
399
+ Rule: **new app code imports from `@/core/facade`.** Do not import
400
+ `@/core/database/connection`, `@/core/utils/queue`, etc. directly in a module.
401
+ The facade only exports what is implemented, so if it is not there, ask whether
402
+ you need it at all before reaching past it.
403
+
404
+ `@/core/facade` is the **framework's** public API. Each app module has its own
405
+ `facade.ts` as well (see §2) — that is the **module's** public API, the one other
406
+ modules import from.
407
+
408
+ ## 7. Queue & scheduler
409
+
410
+ **Queue** — bounded concurrency. `add(task)` resolves with the task's own result;
411
+ a throwing task rejects only its own caller, never the queue.
412
+
413
+ ```ts
414
+ import { queue } from "@/core/facade";
415
+
416
+ const q = queue.create<string>({ concurrency: 3 }); // concurrency floored at 1
417
+ const results = await Promise.all(items.map((x) => q.add(async () => doWork(x))));
418
+ q.size; // pending
419
+ q.running; // executing now
420
+ ```
421
+
422
+ **Cron** — named schedules backed by `croner`. The same `name` replaces (stops and
423
+ recreates) the previous job, so re-applying settings never double-schedules.
424
+
425
+ ```ts
426
+ import { cron } from "@/core/facade";
427
+
428
+ const job = cron.schedule("cleanup", "0 4 * * *", async () => { /* ... */ }, { timezone: "UTC" });
429
+ job.stop(); // stop this job
430
+ cron.stop(); // stop ALL jobs (call on shutdown)
431
+ ```
432
+
433
+ - Failing tasks are caught and logged; a bad task never crashes the app.
434
+ - Register schedules once at boot (or replace them by name) — do not schedule the
435
+ same logical job under different names.
436
+
437
+ ## 8. Storage & files
438
+
439
+ Two layers, both from the facade.
440
+
441
+ **`files`** operates on the user's real filesystem — any absolute path a picker
442
+ returns. All writes are atomic (temp + rename).
443
+
444
+ ```ts
445
+ import { files, pickers } from "@/core/facade";
446
+
447
+ const src = await pickers.open({ title: "Import", filter: "CSV (*.csv)|*.csv" });
448
+ if (!src) return; // user cancelled — always check for null
449
+ const text = await files.readTextFile(src);
450
+ const meta = await files.fileMeta(src); // { path, size, modifiedAt, isFile, isDirectory } | null
451
+ await files.writeJson("/tmp/out.json", { ok: true });
452
+ ```
453
+
454
+ Read helpers (`readTextFileOr`, `readJson`, `fileMeta`) return fallbacks/`null`
455
+ instead of throwing; write helpers create parent folders.
456
+
457
+ **`storage`** is the app's **own** state, sandboxed to a disk root
458
+ (`<userData>/storage`, or `<project>/src/storage/app` in CLI/dev; override with
459
+ `APP_DATA_DIR`). `private` survives restarts; `tmp` is transient. Top-level
460
+ methods target `private`.
461
+
462
+ ```ts
463
+ import { storage } from "@/core/facade";
464
+
465
+ await storage.init(); // once at boot (done in main.ts)
466
+ await storage.put("settings.json", JSON.stringify(settings));
467
+ const bytes = await storage.get("settings.json");
468
+ await storage.disk("tmp").put("cache/1.json", "{}");
469
+ storage.path("settings.json"); // absolute path
470
+ ```
471
+
472
+ - Never build app-state paths by hand; use `storage` (it rejects paths that
473
+ escape the disk root) or `files` (for user paths).
474
+ - Expose storage to the UI through a controller + binding — the renderer has no
475
+ filesystem access.
476
+
477
+ ## 9. Windows, chrome, dialogs & pickers
478
+
479
+ All from the facade. `main.ts` already creates the windows declared in
480
+ `src/config/winsetup.ts`, so app code usually **drives** windows rather than
481
+ creating them.
482
+
483
+ ```ts
484
+ import { win, chrome } from "@/core/facade";
485
+
486
+ const main = win.getWindow(); // the main window (undefined before boot)
487
+ main?.setTitle(`${n} unsaved`);
488
+ await win.openWindow("settings"); // reopen-by-name; reuses an open window
489
+ await win.openWindow({ title: "Preview", width: 900, height: 640, route: "/preview" });
490
+ win.getWindowCount();
491
+ ```
492
+
493
+ - `DesktopWindow` **is** Electron's `BrowserWindow` — call Electron methods on it.
494
+ - `openWindow` is **async**; always `await` it. It reuses an open window keyed by
495
+ preset name (or inline `title`).
496
+ - `win.getWindow()` / `win.getWindowCount()` are read-only and safe anywhere;
497
+ creating a window needs the real Electron runtime — guard it in tests/CLI.
498
+ - App menu, context menu and tray apply to the **main window only**.
499
+ - To change the app menu, right-click menu or tray, edit
500
+ `src/window/app-menu.ts` (`defaultMenuItems` / `toElectronMenu` /
501
+ `installAppMenu`), `src/window/context-menu.ts` (`installContextMenu`) and
502
+ `src/window/tray.ts` (`createTray` / `createAppTray`) directly — these are
503
+ app-shipped, not framework. A menu item's `id` reaches the renderer via
504
+ `webContents.send("menu-click", id)`.
505
+
506
+ `chrome` (menus, tray, dialogs) is **backend-only** — the renderer can never
507
+ import it. Bridge it through a controller if the UI needs it.
508
+
509
+ ```ts
510
+ if (await chrome.confirmDialog(`Delete "${name}"?`)) await files.removePath(path);
511
+ await chrome.alertDialog("Done");
512
+ ```
513
+
514
+ `pickers` and the top-level `alertDialog` / `confirmDialog` are also on the facade;
515
+ `confirmDialog`/`alertDialog` are **async** — await them.
516
+
517
+ ## 10. Frontend: pages, components & the `@/ui` alias
518
+
519
+ The renderer lives in `src/ui/src`. Two aliases, and they are **not**
520
+ interchangeable:
521
+
522
+ - `@/ui/*` → `src/ui/src/*` (frontend code: pages, components, stores, plugins)
523
+ - `@/*` → `src/*` (the backend tree)
524
+
525
+ So a page imports `@/ui/plugins/gum.ts`, never `@/plugins/gum.ts`. Vite
526
+ (`src/ui/vite.config.ts`), the UI tsconfig, and `vitest.config.ts` all define
527
+ these aliases; use them everywhere.
528
+
529
+ - **Pages** go in `src/ui/src/pages/<name>/index.vue` and are registered in
530
+ `src/ui/src/router/index.ts` (lazy `component: () => import("@/ui/pages/...")`).
531
+ - **Shared components** go in `src/ui/src/components/`. The starter ships
532
+ `components/datatable/` (DataTable + `Pagination.vue`, `SelectOpption.vue`,
533
+ `DataTableSkeleton.vue` and the small `Button`/`Input`/`Checkbox` controls).
534
+ - **Stores** are Pinia: `src/ui/src/stores/<name>.ts`, `defineStore(...)`. Pinia is
535
+ installed in `src/ui/src/app.ts` (`createPinia()`), so `useStore()` works in any
536
+ component setup.
537
+ - `App.vue` is just `<router-view />`. Bootstrap CSS + Bootstrap Icons + the SCSS
538
+ are imported once in `src/ui/src/app.ts`, which also installs `@unhead/vue`
539
+ (`createHead()`) — call `useHead({ title })` from a page to set the window title.
540
+ - Global type shims live in `src/ui/src/{bindings.d.ts,env.d.ts,global.d.ts}` —
541
+ keep `global.d.ts` a global **script** (no top-level `import`/`export`), or its
542
+ `declare module` shims become augmentations and break.
543
+
544
+ Rule: the renderer **never** imports `@/core/**`, `@/modules/**`, `electron`, or
545
+ `node:*`. If you need backend data, add a controller + binding and call it.
546
+
547
+ ## 11. Frontend data: gum & DataTable
548
+
549
+ `gum` (`src/ui/src/plugins/gum.ts`) is the request/form helper. It has two
550
+ interchangeable transports — `"bindings"` (in-process, no HTTP; auto-detected
551
+ when the Electron bridge is present) and `"http"`. Over bindings the "URL" **is**
552
+ the binding name:
553
+
554
+ ```ts
555
+ import { useGum, useGumRemember } from "@/ui/plugins/gum.ts";
556
+
557
+ const gum = useGum();
558
+
559
+ // fetch, no navigation (what DataTable does)
560
+ const res = await gum.get("app.demo.table", { navigate: false, query: { page: 2, size: 15 } });
561
+ res.data.total;
562
+
563
+ // submit a form over bindings — pass defaults to useGum to also get `form`
564
+ const { form } = useGum({ name: "", email: "" });
565
+ await form.post("users.users.store");
566
+ form.errors; // { field: "first message" }
567
+ form.processing; // boolean
568
+ ```
569
+
570
+ - `useGum` exposes `get/post/put/patch/delete/reload/visit`; `processing` is a ref.
571
+ - Payload contract matches the generated handlers: `index()` → `undefined`,
572
+ `show(params)`/`destroy(params)` → query/data, `store(body)` → data,
573
+ `update({ params, body })` → both. `gum.patch("users.users.update", body, { query: { id } })`.
574
+ - `useGum(defaults).form` returns reactive `data`, `errors`, `processing`,
575
+ `wasSuccessful`, `recentlySuccessful`, `isDirty` plus `setError` / `clearErrors`
576
+ / `reset` and `post`/`put`/`patch`/`delete` (plus the `*With` fetcher variants).
577
+ `useGumForm` is **deprecated** — use `useGum(defaults).form`.
578
+ - `useGumRemember(key, defaults)` is a localStorage ref scoped to the current route.
579
+ - Errors are normalized: Zod `flatten` from `validate.run` becomes per-field
580
+ errors (form-level errors under `$root`). Thrown handler errors survive Electron
581
+ IPC — `bindAll` returns a tagged envelope and the preload bridge rethrows it with
582
+ `.response.data` — so `form.errors` populates over bindings too. This is why
583
+ backend handlers must validate with `validate.run`.
584
+ - `useGum()` reads the router (`useRouter`/`useRoute`), so call it in a component
585
+ setup, never at module scope. In a Pinia store call the binding directly
586
+ (`bindings["users.users.store"](payload)`) or pass a `fetcher` to `gum.postWith`
587
+ / `useGum(...).form.postWith`.
588
+
589
+ **DataTable** (`src/ui/src/components/datatable/index.vue`) is the gum-powered
590
+ table. It has three modes — pick one:
591
+
592
+ - **Path mode** (default) — point `path` at a binding (or REST endpoint) that
593
+ returns the `paginate` envelope; the table fetches it and owns its state.
594
+ - **Parent-owned mode** — pass the page's envelope with `:data` and wire the
595
+ built-in controls to a store action with `:fetcher`; the page owns the rows.
596
+ - **Static mode** — pass `:loop="rows"` and fetch nothing.
597
+
598
+ ```vue
599
+ <!-- path mode: the table fetches the binding itself -->
600
+ <DataTable ref="table" path="blog.post.index" :option="[10, 25, 50]" @remove="removeRows">
601
+ <template #thead><th>Name</th><th>Email</th></template>
602
+ <template #tbody="{ td }"><td>{{ td.name }}</td><td>{{ td.email }}</td></template>
603
+ </DataTable>
604
+
605
+ <!-- parent-owned mode: the page's store owns the envelope; the table drives the fetches -->
606
+ <DataTable :data="posts" :option="[10, 25, 50]" :fetcher="postStore.index" :filters="{ status: 'published' }" @remove="removeRows">
607
+ <template #thead><th>Name</th><th>Email</th></template>
608
+ <template #tbody="{ td }"><td>{{ td.name }}</td><td>{{ td.email }}</td></template>
609
+ </DataTable>
610
+ ```
611
+
612
+ ```ts
613
+ const table = ref<InstanceType<typeof DataTable> | null>(null);
614
+ async function removeRows(ids: Array<string | number>) {
615
+ await gum.delete("blog.post.destroy", { query: { ids } });
616
+ await table.value?.load(1); // exposed: load(page?), state, view, loading
617
+ }
618
+ ```
619
+
620
+ Props: `path`, `data`, `fetcher`, `filters`, `search`, `loop`, `option`,
621
+ `removable`, `countable`, `searchable`, `optionable`, `disabled`, `transport`,
622
+ `baseURL`. Exactly one data source is required: `path`, `data` or `loop`.
623
+ `fetcher` receives the built query (`{ page, size, search, ...filters }`) and
624
+ returns the envelope; it is called through `gum.getWith`. `filters` is merged
625
+ into every call so filters survive a search or a page change. Slots: `#thead`,
626
+ `#tbody="{ td }"`, `#customhead`, `#custombody`, `#extra`, `#extra-tools`. Each
627
+ row needs `td.id` for selection. The table sends `?page=&size=&search=` and
628
+ expects `{ data, current_page, last_page, per_page, total, from, to, path }`.
629
+
630
+ Realtime (`pulse`, Socket.IO) is in `src/ui/src/plugins/pulse.ts`; it only
631
+ activates when `VITE_SOCKET_URL` / `VITE_API_URL` is set. `pulse` is a plain
632
+ singleton (not a composable), so import it anywhere — including a Pinia store.
633
+ Nothing is offline-aware: `bindings` are in-process (work offline by nature), but
634
+ HTTP and pulse need the network — guard them with `navigator.onLine`.
635
+
636
+ ## 12. Config: app identity & windows
637
+
638
+ - `src/config/app.ts` — the app's identity: `name` (kebab), `productName`,
639
+ `description`, `appId`, `protocol`, `uninstallDataFolders`. After editing, run
640
+ `npm run config:sync` (also part of `prepare`/`dev`/`build`) to update
641
+ `package.json` and the NSIS installer fields. Runtime config reads from here.
642
+ - `src/config/winsetup.ts` — `windows` (each entry becomes a `BrowserWindow` at
643
+ boot; the first is the main window), `windowDev.devTools`, and `ChromeParts`
644
+ (`appMenu`/`contextMenu`/`tray`). Add presets here and open them with
645
+ `win.openWindow("<name>")`.
646
+
647
+ `DESKAPP_UI=false` runs the app headless (tray only); the flag is read via
648
+ `config.ui.enabled`. Do not hardcode app names or window sizes in components —
649
+ read them from config.
650
+
651
+ ## 13. Commands
652
+
653
+ ```sh
654
+ npm run dev # config:sync + db:schema + bindings:gen, then Vite + esbuild watch + Electron
655
+ npm run build # UI (vite) + main/preload (esbuild)
656
+ npm run package # build + electron-builder installer
657
+ npm start # run the built app (out/main/index.cjs)
658
+ npm run maker # list all maker commands
659
+ npm run maker -- <command> # run one (make:*, db:*, bindings:gen, codegen, config:sync, ...)
660
+ npm test # Vitest (node env; src/ui/** excluded)
661
+ npm run typecheck # tsc --noEmit (backend tsconfig + UI tsconfig)
662
+ npm run lint # Biome
663
+ ```
664
+
665
+ `codegen` = schema + bindings. `config:sync` = app identity → package.json/NSIS.
666
+
667
+ ## 14. Testing
668
+
669
+ - Tests are Vitest, `globals: true`, node environment, in
670
+ `src/modules/**/__tests__/*.test.ts` (also `src/**/*.test.ts`).
671
+ - `src/ui/**` is **excluded** from Vitest — do not write renderer tests here; test
672
+ the backend handler instead.
673
+ - Mock the facade when a handler touches framework services, e.g.:
674
+
675
+ ```ts
676
+ // ./src/modules/app/__tests__/demo.controller.test.ts
677
+
678
+ import { describe, expect, it, vi } from "vitest";
679
+ vi.mock("@/core/facade", () => ({ queue: { create: () => ({ add: (t: () => Promise<unknown>) => t() }) } }));
680
+ import { handlers, queue } from "@/modules/app/controllers/demo.controller";
681
+ ```
682
+
683
+ - `make:test <module> [name]` scaffolds a file; keep the test next to the module
684
+ it covers.
685
+
686
+ ## 15. Before you say "done"
687
+
688
+ 1. **Regenerate what you changed.**
689
+ - Added/removed/renamed a controller → `npm run maker -- bindings:gen`.
690
+ - Added/changed a model → `npm run maker -- db:generate` (or `db:migrate`).
691
+ - Changed app identity → `npm run config:sync`.
692
+ 2. **Verify, don't assume:** run `npm test`, `npm run typecheck` and `npm run lint`;
693
+ for anything that touches boot, windows, IPC or the DB, run `npm run dev` and
694
+ exercise it.
695
+ 3. **Check the rules:** no edits under `src/core/**`; no hand-edited generated
696
+ files; every new file opens with its location header; every new handler is in
697
+ its controller's `handlers` map; cross-module imports go through a module
698
+ `facade.ts`; the renderer imports no backend code; imports use `@/core/facade`
699
+ and the `@/ui/*` alias.