@niyamulahsan/create-deskapp 1.2.4 → 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.
- package/package.json +16 -16
- package/template/.env.example +20 -13
- package/template/AGENTS.md +699 -0
- package/template/package.json +3 -0
- package/template/src/config/app.ts +26 -24
- package/template/src/config/winsetup.ts +93 -91
- package/template/src/core/api/binding-error.ts +57 -0
- package/template/src/core/api/bindings.generated.ts +2 -0
- package/template/src/core/api/generate.manifest.ts +84 -80
- package/template/src/core/api/registry.ts +58 -48
- package/template/src/core/config.ts +101 -99
- package/template/src/core/database/aggregate.ts +89 -85
- package/template/src/core/database/config.ts +50 -48
- package/template/src/core/database/connection.ts +116 -114
- package/template/src/core/database/migrate-hooks.ts +86 -84
- package/template/src/core/database/paginate.ts +226 -224
- package/template/src/core/database/reset.ts +21 -19
- package/template/src/core/database/seed.ts +169 -167
- package/template/src/core/database/status.ts +37 -35
- package/template/src/core/env.ts +108 -106
- package/template/src/core/facade.ts +63 -61
- package/template/src/core/maker/db/fresh.ts +10 -8
- package/template/src/core/maker/db/generate.ts +13 -11
- package/template/src/core/maker/db/helpers.ts +92 -96
- package/template/src/core/maker/db/migrate.ts +37 -35
- package/template/src/core/maker/db/mod.ts +93 -91
- package/template/src/core/maker/db/module-migrate.ts +56 -54
- package/template/src/core/maker/db/push.ts +23 -21
- package/template/src/core/maker/db/reset.ts +8 -6
- package/template/src/core/maker/db/seed.ts +9 -7
- package/template/src/core/maker/db/status.ts +8 -6
- package/template/src/core/maker/help.ts +59 -57
- package/template/src/core/maker/make/controller.ts +25 -22
- package/template/src/core/maker/make/helpers.ts +97 -91
- package/template/src/core/maker/make/mod.ts +69 -67
- package/template/src/core/maker/make/model.ts +16 -14
- package/template/src/core/maker/make/module.ts +53 -39
- package/template/src/core/maker/make/seeder.ts +23 -21
- package/template/src/core/maker/make/test.ts +33 -30
- package/template/src/core/maker/mod.ts +85 -83
- package/template/src/core/maker/run/mod.ts +134 -132
- package/template/src/core/maker/stub.ts +26 -24
- package/template/src/core/maker/stubs/controller/controller.controller.stub +57 -55
- package/template/src/core/maker/stubs/controller/controller.schema.stub +18 -13
- package/template/src/core/maker/stubs/facade/facade.stub +21 -0
- package/template/src/core/maker/stubs/model/model.stub +10 -8
- package/template/src/core/maker/stubs/seeder/seeder.stub +18 -16
- package/template/src/core/maker/stubs/test/test.stub +9 -7
- package/template/src/core/maker/sync-config.ts +93 -94
- package/template/src/core/utils/password.ts +29 -27
- package/template/src/core/utils/playwright.ts +123 -121
- package/template/src/core/utils/queue.ts +68 -66
- package/template/src/core/utils/scheduler.ts +62 -60
- package/template/src/core/utils/storage.ts +3 -1
- package/template/src/core/utils/validation.ts +37 -35
- package/template/src/database/schema.ts +2 -0
- package/template/src/main.ts +120 -118
- package/template/src/modules/app/__tests__/demo.controller.test.ts +75 -0
- package/template/src/modules/app/__tests__/net.controller.test.ts +65 -0
- package/template/src/modules/app/__tests__/playwright.controller.test.ts +50 -0
- package/template/src/modules/app/__tests__/storage.controller.test.ts +114 -0
- package/template/src/modules/app/__tests__/window.controller.test.ts +98 -0
- package/template/src/modules/app/controllers/demo.controller.ts +120 -118
- package/template/src/modules/app/controllers/net.controller.ts +50 -48
- package/template/src/modules/app/controllers/playwright.controller.ts +142 -140
- package/template/src/modules/app/controllers/storage.controller.ts +231 -229
- package/template/src/modules/app/controllers/window.controller.ts +2 -0
- package/template/src/modules/app/facade.ts +21 -0
- package/template/src/preload.ts +25 -2
- package/template/src/ui/src/App.vue +4 -2
- package/template/src/ui/src/app.ts +38 -23
- package/template/src/ui/src/bindings.d.ts +18 -16
- package/template/src/ui/src/components/Button.vue +34 -32
- package/template/src/ui/src/components/Checkbox.vue +26 -29
- package/template/src/ui/src/components/Input.vue +221 -227
- package/template/src/ui/src/components/InputGroup.vue +141 -0
- package/template/src/ui/src/components/InputPasswordToggle.vue +204 -0
- package/template/src/ui/src/components/Modal.vue +65 -55
- package/template/src/ui/src/components/Spinner.vue +44 -42
- package/template/src/ui/src/components/Switch.vue +62 -65
- package/template/src/ui/src/components/TextArea.vue +108 -121
- package/template/src/ui/src/components/Toast.vue +55 -56
- package/template/src/ui/src/components/datatable/DataTableSkeleton.vue +100 -98
- package/template/src/ui/src/components/datatable/Pagination.vue +153 -125
- package/template/src/ui/src/components/datatable/SelectOpption.vue +36 -35
- package/template/src/ui/src/components/datatable/index.vue +336 -258
- package/template/src/ui/src/env.d.ts +16 -13
- package/template/src/ui/src/global.d.ts +21 -2
- package/template/src/ui/src/helpers/nformatter.ts +12 -10
- package/template/src/ui/src/pages/dashboard/index.vue +690 -687
- package/template/src/ui/src/plugins/browserDetect.ts +57 -0
- package/template/src/ui/src/plugins/gum.ts +576 -549
- package/template/src/ui/src/plugins/pulse.ts +181 -147
- package/template/src/ui/src/plugins/routeProgress.ts +89 -0
- package/template/src/ui/src/router/index.ts +44 -25
- package/template/src/ui/src/stores/example.ts +2 -0
- package/template/src/ui/vite.config.ts +40 -38
- package/template/src/window/app-menu.ts +89 -87
- package/template/src/window/config.ts +14 -12
- package/template/src/window/context-menu.ts +23 -21
- package/template/src/window/dialogs.ts +92 -90
- package/template/src/window/manager.ts +2 -0
- package/template/src/window/native.ts +47 -45
- 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.
|