kreftjs 0.0.16-beta → 0.0.19-beta

package/README.md

@@ -42,6 +42,25 @@ Open the address in the terminal (normally `http://localhost:8000`). A new proje
 | **Authentication** | Cookie sessions with CSRF protection, API tokens with permissions, device list, two-factor codes, email verification, account lockout. |
 | **Tooling** | `kreft dev` with hot reload, DevTools, an error monitor, `kreft build` (CSP-safe), prerendering, TypeScript, Vite and Electron support, a safer `kreft add`, an MCP server for AI agents. |
 
+## Desktop apps (Electron)
+
+```bash
+kreft new my-app --electron      # or: kreft electron:init in an existing app
+npm install
+kreft electron                   # opens the app in its own window (no browser, no URL)
+```
+
+Make installers (build each system on that system; `.deb` and `.rpm` need Linux):
+
+```bash
+npm run electron:build:mac     # .dmg and .zip
+npm run electron:build:win     # NSIS installer and portable .exe
+npm run electron:build:linux   # AppImage, .deb and .rpm
+npm run electron:build:all     # all three (same as: kreft electron:build --all)
+```
+
+The app icon is `build/icon.png`, and `ELECTRON_MENU=show|auto|hide` controls the window menu. Details: [Desktop apps with Electron](docs/README.md#desktop-apps-with-electron).
+
 ## Learn more
 
 | I want to… | Read |

package/bin/electron.js

@@ -54,11 +54,21 @@ function getDevToolsConfig() {
 //   ELECTRON_MENU=hide   no menu at all
 // Change it while running from the page:  window.kreftDesktop.setMenu('show' | 'auto' | 'hide')
 let menuMode = String(process.env.ELECTRON_MENU || 'show').toLowerCase();
-const defaultMenu = Menu.getApplicationMenu();
+let defaultMenu = null; // Electron's own menu, read once the app is ready
 function applyMenu(mode) {
   menuMode = ['show', 'auto', 'hide'].includes(mode) ? mode : 'show';
-  Menu.setApplicationMenu(menuMode === 'hide' ? null : (Menu.getApplicationMenu() || defaultMenu));
+  if (!defaultMenu) defaultMenu = Menu.getApplicationMenu();
+  if (menuMode === 'hide') {
+    // macOS keeps one app menu (with Quit) because the system needs it; Windows and Linux lose the bar
+    Menu.setApplicationMenu(process.platform === 'darwin'
+      ? Menu.buildFromTemplate([{ role: 'appMenu' }])
+      : null);
+  } else {
+    Menu.setApplicationMenu(defaultMenu);
+  }
   if (mainWindow && process.platform !== 'darwin') {
+    if (menuMode === 'hide') mainWindow.removeMenu();
+    else mainWindow.setMenu(defaultMenu);
     mainWindow.setAutoHideMenuBar(menuMode === 'auto');
     mainWindow.setMenuBarVisibility(menuMode === 'show');
   }
@@ -235,6 +245,7 @@ ipcMain.handle('kreft:dialog:save', async (_, options) => {
 });
 
 app.whenReady().then(() => {
+  applyMenu(menuMode);
   createWindow();
 
   app.on('activate', () => {
@@ -286,6 +297,26 @@ function dropWebFonts(root) {
   return path.relative(root, file);
 }
 
+// electron-builder needs a description, a homepage, an author with an e-mail and a Linux maintainer (.deb / .rpm).
+// Missing ones are filled from git config (name, e-mail); edit them in package.json.
+function ensureMeta(pkg) {
+  const git = (k) => { try { return require('child_process').execSync('git config ' + k, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim(); } catch (_) { return ''; } };
+  let changed = false;
+  if (!pkg.description) { pkg.description = (pkg.build && pkg.build.productName) || pkg.name || 'Kreft desktop app'; changed = true; }
+  if (!pkg.homepage) { pkg.homepage = 'https://kreftjs.com'; changed = true; }
+  const hasMail = pkg.author && (typeof pkg.author === 'object' ? pkg.author.email : /<[^>]+@[^>]+>/.test(pkg.author));
+  if (!hasMail) {
+    const name = (pkg.author && (typeof pkg.author === 'object' ? pkg.author.name : String(pkg.author).replace(/<.*>/, '').trim())) || git('user.name') || pkg.name || 'App';
+    pkg.author = { name, email: git('user.email') || 'you@example.com' };
+    changed = true;
+  }
+  if (pkg.build) {
+    pkg.build.linux = pkg.build.linux || {};
+    if (!pkg.build.linux.maintainer) { pkg.build.linux.maintainer = `${pkg.author.name} <${pkg.author.email}>`; changed = true; }
+  }
+  return changed;
+}
+
 function init(args = []) {
   const target = typeof args === 'string' ? args : (args[0] && !args[0].startsWith('-') ? args[0] : process.cwd());
   const root = getProjectRoot(target);
@@ -345,6 +376,7 @@ function init(args = []) {
     }
   }
 
+  ensureMeta(pkg);
   fs.writeFileSync(pkgFile, JSON.stringify(pkg, null, 2) + '\n');
 
   const droppedFonts = dropWebFonts(root);
@@ -410,7 +442,52 @@ function freePort(start) {
   });
 }
 
+function help() {
+  console.log(`
+  Kreft + Electron: your app as a desktop program (Windows, macOS, Linux)
+
+  Commands
+    kreft new <name> --electron   A new app with desktop support
+    kreft electron:init           Add desktop support to an existing app (alias: kreft make:electron)
+                                  Writes electron/main.js, electron/preload.js, build/icon.png and the build block
+                                  in package.json. Files that exist are never overwritten.
+    kreft electron                Open the app in its own window: no browser, no URL (alias: kreft electron:dev)
+        --devtools[=right|bottom|left|detach]   Open DevTools     --no-devtools   Do not
+        --port <number>           Private port for the hidden dev server (default: the next free one)
+    kreft electron:build          Build the app (kreft build --base ./) and make installers in dist-electron/
+        --mac --win --linux       Choose the systems (more electron-builder flags work: --arm64, --x64, --dir)
+    npm run electron:build:mac    .dmg and .zip
+    npm run electron:build:win    NSIS installer and portable .exe
+    npm run electron:build:linux  AppImage, .deb and .rpm
+    npm run electron:build:all    All three
+    kreft electron:help           This text
+
+  Window menu     ELECTRON_MENU=show (default) | auto (Alt shows it) | hide
+                  From a page: kreftDesktop.setMenu('hide'), kreftDesktop.getMenu()
+                  (macOS always keeps one app menu with Quit)
+  DevTools        ELECTRON_DEVTOOLS=right|bottom|left|detach|false, or F12 / Ctrl+Shift+I
+  App icon        build/icon.png, a square PNG of 512x512 or more (.icns and .ico are made from it)
+  App name        build.productName and build.appId in package.json
+  Installer info  description, homepage, author (with e-mail) and build.linux.maintainer in package.json
+                  (missing ones are filled in from git when you build; check them)
+  From a page     if (Kreftjs.isElectron) kreftDesktop.getInfo(), minimize(), maximize(), close(),
+                  showMessageBox(), showOpenDialog(), showSaveDialog(), openDevTools()
+
+  Good to know
+    - Build each system on that system. On a Mac, .deb and .rpm fail: build them on Linux.
+    - npm run build makes the website (paths start at /). electron:build makes the desktop build (--base ./).
+    - The packaged app has no backend: frontend-only apps work, full-stack ones (login, database) need a server.
+    - Unsigned apps show a warning on macOS and Windows: https://www.electron.build/code-signing
+    - Errors: "Electron is not installed locally" -> kreft add -D electron
+              "electron-builder is not installed" -> kreft add -D electron-builder
+              White window in the app -> run electron:build again (it needs --base ./)
+
+  Full guide: docs/README.md, "Desktop apps with Electron"
+`);
+}
+
 function dev(args = []) {
+  if (['help', '--help', '-h'].includes(args[0])) return help();
   const asked = args.findIndex((a) => a === '--port' || a === '-p');
   if (asked >= 0 && Number(args[asked + 1])) return startDev(args, Number(args[asked + 1]));
   return freePort(Number(process.env.PORT) || 8000).then((port) => startDev(args, port));
@@ -500,6 +577,8 @@ function startDev(args, port) {
 }
 
 function build(args = []) {
+  // --all is a Kreft shortcut for --mac --win --linux (electron-builder has no such flag)
+  if (args.includes('--all')) args = [...args.filter((a) => a !== '--all'), ...['--mac', '--win', '--linux'].filter((p) => !args.includes(p))];
   const root = getProjectRoot();
   const electronMain = path.join(root, 'electron', 'main.js');
   if (!fs.existsSync(electronMain)) {
@@ -507,6 +586,15 @@ function build(args = []) {
     init();
   }
 
+  try {
+    const f = path.join(root, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(f, 'utf8'));
+    if (ensureMeta(pkg)) {
+      fs.writeFileSync(f, JSON.stringify(pkg, null, 2) + '\n');
+      console.log('  Added description / author / Linux maintainer to package.json (needed for installers). Please check them.');
+    }
+  } catch (_) {}
+
   // 1. Build Kreft frontend for desktop with relative base
   console.log('\n  Step 1: Building Kreft static bundle with relative base (./)…');
   const kreftCli = path.join(__dirname, 'kreftjs.js');
@@ -544,6 +632,7 @@ function build(args = []) {
 
 module.exports = {
   init,
+  help,
   dev,
   run: dev,
   build,

package/bin/kreftjs.js

@@ -46,6 +46,7 @@ const commands = {
   'electron:dev': (a) => require('./electron.js').dev(a),
   'electron:build': (a) => require('./electron.js').build(a),
   'electron:init': (a) => require('./electron.js').init(a),
+  'electron:help': () => require('./electron.js').help(),
   'make:electron': (a) => require('./electron.js').init(a),
   vite: (a) => require('./vite.js').dev(a),
   'vite:dev': (a) => require('./vite.js').dev(a),
@@ -117,10 +118,10 @@ function help() {
     kreft vite:init         Add Vite configuration to an existing project (alias: kreft make:vite)
 
   Desktop (Electron.js):
-    kreft electron          Start dev server and launch desktop window (alias: kreft electron:dev)
-    kreft electron:dev      Start dev server and launch desktop window
-    kreft electron:build    Build static bundle and package desktop app with electron-builder
+    kreft electron          Open the app in a desktop window only: no browser, no URL (alias: kreft electron:dev)
+    kreft electron:build    Build and make installers (--mac, --win, --linux; or npm run electron:build:all)
     kreft electron:init     Add Electron support to an existing project (alias: kreft make:electron)
+    kreft electron:help     Everything about desktop apps: menu, icon, installers, errors
 
   The backend (kreft list shows every command, yours too):
     kreft key:generate      Set the application encryption key in .env (--show: print only)

package/docs/README.md

@@ -82,7 +82,7 @@ npx kreftjs dev
 ### Check that it works
 
 ```bash
-kreft --version     # for example 0.0.16-beta
+kreft --version     # for example 0.0.19-beta
 kreft about         # Kreft and Node.js versions, this project's settings and drivers
 kreft list          # every command your version has
 ```
@@ -1908,10 +1908,31 @@ npm install                     # installs electron and electron-builder
 |---|---|
 | `kreft electron:init` | Writes `electron/main.js`, `electron/preload.js` and the app icon `build/icon.png`, and adds the scripts (including `electron:build:mac`, `:win`, `:linux` and `:all`), the `electron` and `electron-builder` dev dependencies and a `build` block to `package.json`. Files that already exist are never overwritten. It also removes the Google Fonts links from `index.html`, so the app starts without a network. |
 | `kreft electron:dev` | Opens the app in a desktop window only: no browser opens and no URL is printed. The dev server runs hidden on a private port of your computer that only the window uses (hot reload works). Closing the window stops the server. Flags after the command go to the dev server. |
-| `kreft electron:build` | Runs `kreft build --base ./`, then `electron-builder`. |
+| `kreft electron:build` | Runs `kreft build --base ./`, then `electron-builder`. With no flag it builds for the system you are on. |
+| `kreft electron:build --mac` | `.dmg` and `.zip` for macOS. |
+| `kreft electron:build --win` | NSIS installer and portable `.exe` for Windows. |
+| `kreft electron:build --linux` | AppImage, `.deb` and `.rpm` for Linux. |
+| `kreft electron:build --mac --win --linux` | All three systems in one run. |
+| `kreft electron:build --all` | The same as `--mac --win --linux`. |
+| `npm run electron:build:mac`, `:win`, `:linux`, `:all` | Shortcuts for the four commands above. |
+
+Other flags go straight to electron-builder: `--x64`, `--arm64`, `--ia32`, `--armv7l`, `--universal` (macOS) and `--dir` (an unpacked app folder only, no installer: fast for testing).
 
 `kreft electron` is the same as `kreft electron:dev`. If the `electron/` folder is missing, both commands create it first.
 
+### Quick reference
+
+| I want to… | Do this |
+|---|---|
+| Add desktop support | `kreft new my-app --electron`, or `kreft electron:init` in an existing app, then `npm install` |
+| Open the app in its window | `kreft electron` (no browser, no URL) |
+| Open DevTools | `kreft electron --devtools=bottom`, `ELECTRON_DEVTOOLS=right`, or F12 |
+| Show, auto-hide or hide the menu | `ELECTRON_MENU=show`, `auto` or `hide`; `kreftDesktop.setMenu('hide')` |
+| Change the icon | Replace `build/icon.png` (square PNG, 512×512 or bigger) |
+| Change the app name | `build.productName` and `build.appId` in `package.json` |
+| Make an installer | `npm run electron:build:mac`, `:win`, `:linux` or `:all` |
+| Get help in the terminal | `kreft electron:help` |
+
 ### Project layout
 
 ```text
@@ -2011,21 +2032,24 @@ window.kreftDesktop.setMenu('hide')   // 'show' | 'auto' | 'hide'
 window.kreftDesktop.getMenu()         // the current mode
 ```
 
-On macOS the menu lives in the top bar of the screen, so `show` and `auto` look the same. For your own menu (File, Edit…), call `Menu.buildFromTemplate([...])` and `Menu.setApplicationMenu(...)` in `electron/main.js`.
+On macOS the menu lives in the top bar of the screen, so `show` and `auto` look the same, and `hide` keeps only the app-name menu (with Quit) because macOS needs one. Apps created before 0.0.18 have the old `electron/main.js` without this: delete it and run `kreft electron:init` (copy your own changes back first). For your own menu (File, Edit…), call `Menu.buildFromTemplate([...])` and `Menu.setApplicationMenu(...)` in `electron/main.js`.
 
 ### The app icon
 
-`kreft electron:init` copies the Kreft logo to `build/icon.png`. Replace it with your own square PNG, 512×512 or bigger. The window uses it, and electron-builder makes the `.icns` (macOS) and `.ico` (Windows) files from it. Set the app name with `build.productName` and `build.appId` in `package.json`, and add `description` and `author` there too (electron-builder warns without them).
+`kreft electron:init` copies the Kreft logo to `build/icon.png`. Replace it with your own square PNG, 512×512 or bigger. The window uses it, and electron-builder makes the `.icns` (macOS) and `.ico` (Windows) files from it. Set the app name with `build.productName` and `build.appId` in `package.json`, electron-builder also needs `description`, `homepage`, an `author` with an e-mail and `build.linux.maintainer` (for `.deb` and `.rpm`). `kreft electron:init` and `kreft electron:build` fill in the missing ones (from your git name and e-mail); check them before you release.
 
 ### Packaging and installers
 
 ```bash
-npm run electron:build:mac     # .dmg and .zip
-npm run electron:build:win     # NSIS installer and portable .exe
-npm run electron:build:linux   # AppImage, .deb and .rpm
-npm run electron:build:all     # all three
+kreft electron:build --mac                 # .dmg and .zip
+kreft electron:build --win                 # NSIS installer and portable .exe
+kreft electron:build --linux               # AppImage, .deb and .rpm
+kreft electron:build --mac --win --linux   # all three
+kreft electron:build --all                 # the same as the line above
 ```
 
+The `package.json` scripts do the same: `npm run electron:build:mac`, `:win`, `:linux` and `:all`.
+
 `electron:build` writes to `dist-electron/`. Flags go to electron-builder, for example `kreft electron:build --mac --arm64`. The defaults in the `build` block of `package.json` are:
 
 | System | Targets |
@@ -2034,10 +2058,21 @@ npm run electron:build:all     # all three
 | macOS | `dmg`, `zip` |
 | Linux | `AppImage`, `deb`, `rpm` |
 
-Edit `appId`, `productName` and the targets there. Build for each system on that system: a macOS installer needs a Mac (Windows installers from a Mac need Wine; `.rpm` needs `rpm` installed). Code signing and notarisation (macOS) or a signing certificate (Windows) are set up through electron-builder (electron.build/code-signing) and are needed before you give the app to other people; unsigned macOS apps show a Gatekeeper warning.
+Edit `appId`, `productName` and the targets there. Build for each system on that system: a macOS installer needs a Mac (on a Mac, the Linux `AppImage` and the Windows installers build, but `.deb` and `.rpm` fail: build those on Linux, or remove them from `build.linux.target`). Code signing and notarisation (macOS) or a signing certificate (Windows) are set up through electron-builder (electron.build/code-signing) and are needed before you give the app to other people; unsigned macOS apps show a Gatekeeper warning.
 
 The packaged app loads the built `dist/index.html` and does not start a backend. A frontend-only app works as is; a full-stack app (login, database) does not work once installed.
 
+### `npm run build` or `electron:build`?
+
+Adding Electron does not change `npm run build`. The two commands make different things:
+
+| Command | What it makes | Use it for |
+|---|---|---|
+| `npm run build` | The website in `dist/`, with paths that start at `/` (the `docs/` folder is included). | Putting the app on a web server. |
+| `npm run electron:build` | The same site built with `--base ./` so it opens from a file, then an installer in `dist-electron/`. | Giving the app to people as a desktop program. |
+
+A `dist/` made by `npm run build` shows a white window if you open it in Electron, because its paths start at `/`. Run `electron:build` (or `kreft build --base ./`) first. Doing both is fine: `electron:build` rewrites `dist/`, so run `npm run build` again before you deploy the website.
+
 ### Security
 
 The window follows Electron's security guidance:

package/kreftjs.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for Kreft 0.0.16-beta
+// Type definitions for Kreft 0.0.19-beta
 // Use from TypeScript or for editor hints in plain JavaScript (// @ts-check).
 
 export interface Signal<T> { value: T }

package/kreftjs.js

@@ -1,5 +1,5 @@
 /*!
- * Kreft v0.0.16-beta — reactive by nature
+ * Kreft v0.0.19-beta — reactive by nature
  * The .kreft component language (state · derive · action · when · watch · on),
  * { } views with k-if / k-each / k-model, components, slots, router, stores,
  * share / receive, event bus and a template engine.
@@ -5036,7 +5036,7 @@
     stores, storeLog, busLog,
   };
 
-  const VERSION = '0.0.16-beta';
+  const VERSION = '0.0.19-beta';
   const Kreftjs = {
     version: VERSION,
     // PUBLIC_ values from .env (kreft dev and kreft build put them here); never secrets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kreftjs",
-  "version": "0.0.16-beta",
+  "version": "0.0.19-beta",
   "description": "A tiny reactive framework with its own component language (.kreft files): router with nested routes, stores, saved data, animations, an API client, hot reload, DevTools and a template engine.",
   "license": "Elastic-2.0",
   "main": "kreftjs.js",
@@ -14,7 +14,7 @@
     "start": "node bin/kreftjs.js dev --api demo/db.json --db sqlite:demo/database/demo.db --migrations demo/database/migrations --server demo/server --backend demo --seed",
     "build": "node bin/kreftjs.js build demo --out dist/demo --include docs",
     "preview": "node bin/kreftjs.js dev dist --api demo/db.json --db sqlite:demo/database/demo.db --migrations demo/database/migrations --server demo/server --backend demo --seed",
-    "test": "node --test test/security.test.js test/prerender.test.js test/seo.test.js test/rebrand.test.js test/noauth.test.js test/winspawn.test.js test/htaccess.test.js test/cookie-secure.test.js test/password-rule.test.js test/headline.test.js test/menu.test.js",
+    "test": "node --test test/security.test.js test/prerender.test.js test/seo.test.js test/rebrand.test.js test/noauth.test.js test/winspawn.test.js test/htaccess.test.js test/cookie-secure.test.js test/password-rule.test.js test/headline.test.js test/menu.test.js test/electron-all.test.js",
     "electron": "kreftjs electron",
     "electron:dev": "kreftjs electron:dev",
     "electron:build": "kreftjs electron:build"

package/templates/app/frontend/errors/ErrorMonitor.kreft

@@ -92,7 +92,7 @@ state docs = (Kreftjs.env.PUBLIC_DOCS_URL || 'http://kreftjs.com').replace(/\/+$
         <div class="badges">
           <span class="badge danger-badge">HTTP {status}</span>
           <span class="badge solid">{currentTitle}</span>
-          <span class="badge">Kreft {Kreftjs.version || '0.0.16-beta'}</span>
+          <span class="badge">Kreft {Kreftjs.version || '0.0.19-beta'}</span>
         </div>
         <div class="actions">
           <button class="sm" @click={copyReport}>{copied ? 'Copied Markdown' : 'Copy Report'}</button>
@@ -189,7 +189,7 @@ state docs = (Kreftjs.env.PUBLIC_DOCS_URL || 'http://kreftjs.com').replace(/\/+$
         <h3>Kreft Runtime</h3>
         <table>
           <tbody>
-            <tr><th>Engine</th><td><code>Kreft v{Kreftjs.version || '0.0.16-beta'}</code></td></tr>
+            <tr><th>Engine</th><td><code>Kreft v{Kreftjs.version || '0.0.19-beta'}</code></td></tr>
             <tr><th>Sanitizer</th><td><code>Active (cleanHtml / SafeHtml)</code></td></tr>
             <tr><th>Environment</th><td><code>development (APP_DEBUG=true)</code></td></tr>
           </tbody>

package/templates/app/frontend/kreftjs.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for Kreft 0.0.16-beta
+// Type definitions for Kreft 0.0.19-beta
 // Use from TypeScript or for editor hints in plain JavaScript (// @ts-check).
 
 export interface Signal<T> { value: T }

package/templates/app/frontend/kreftjs.js

@@ -1,5 +1,5 @@
 /*!
- * Kreft v0.0.16-beta — reactive by nature
+ * Kreft v0.0.19-beta — reactive by nature
  * The .kreft component language (state · derive · action · when · watch · on),
  * { } views with k-if / k-each / k-model, components, slots, router, stores,
  * share / receive, event bus and a template engine.
@@ -5036,7 +5036,7 @@
     stores, storeLog, busLog,
   };
 
-  const VERSION = '0.0.16-beta';
+  const VERSION = '0.0.19-beta';
   const Kreftjs = {
     version: VERSION,
     // PUBLIC_ values from .env (kreft dev and kreft build put them here); never secrets

package/templates/app/frontend/pages/Dashboard.kreft

@@ -112,7 +112,7 @@ state docs = (Kreftjs.env.PUBLIC_DOCS_URL || 'http://kreftjs.com').replace(/\/+$
         <div class="info-list">
           <div class="info-item">
             <span class="info-label">Framework Engine</span>
-            <span class="info-value">Kreft {Kreftjs.version || '0.0.16-beta'}</span>
+            <span class="info-value">Kreft {Kreftjs.version || '0.0.19-beta'}</span>
           </div>
           <div class="info-item">
             <span class="info-label">Active Database</span>

package/templates/errors/ErrorMonitor.kreft

@@ -118,7 +118,7 @@ state docs = (Kreftjs.env.PUBLIC_DOCS_URL || 'http://kreftjs.com').replace(/\/+$
         <div class="hero-badges">
           <span class="badge-exception">{currentTitle}</span>
           <span class="badge-env">Node.js {typeof process !== 'undefined' ? process.version : 'v22.0.0'}</span>
-          <span class="badge-env">Kreft v0.0.16-beta</span>
+          <span class="badge-env">Kreft v0.0.19-beta</span>
         </div>
         <h1 class="hero-error-message">{currentMessage}</h1>
       </div>