kreftjs 0.0.17-beta → 0.0.20-beta

package/README.md

@@ -42,10 +42,30 @@ 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 |
 |---|---|
+| Learn Kreft in Arabic, from basics to advanced tested examples | [كتاب Kreft بالعربية](book/ar/README.md) |
 | Build my first page | [Your first app](docs/README.md#your-first-app) and [Components](docs/README.md#components-and-the-kreft-file) |
 | Fetch data and handle forms | [Fetching data](docs/README.md#fetching-data), [Forms](docs/README.md#forms-and-validation) |
 | Add an API and a database | [Routing](docs/README.md#routing), [Models](docs/README.md#models-and-the-database), [Migrations](docs/README.md#migrations-seeders-and-factories) |

package/bin/build.js

@@ -34,12 +34,13 @@ const SERVER_DIRS = new Set();
 const SKIP = new Set(['node_modules', 'dist', 'dist-electron', '.git', '.vscode', '.idea', 'package.json', 'package-lock.json', '.DS_Store']);
 
 module.exports = function build(args) {
-  let folder = null, out = null, base = null, prerender = null, urlsFile = null, htaccess = true;
+  let folder = null, out = null, base = null, prerender = null, urlsFile = null, htaccess = true, minify = true;
   const include = [];
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--out' || args[i] === '-o') out = args[++i];
     else if (args[i] === '--base') base = args[++i];
     else if (args[i] === '--no-htaccess') htaccess = false;
+    else if (args[i] === '--no-minify') minify = false; // keep kreftjs.js readable (for debugging)
     else if (args[i] === '--include') include.push(args[++i]); // another folder to copy in, like the docs
     else if (args[i] === '--prerender') prerender = args[i + 1] && !args[i + 1].startsWith('-') && args[i + 1].includes('/') ? args[++i].split(',') : [];
     else if (args[i] === '--urls') urlsFile = args[++i]; // a file with more addresses to prerender (pages from your data)
@@ -154,7 +155,17 @@ ${indent(components.join('\n\n'))}
       }
     }
   }
-  fs.copyFileSync(path.join(__dirname, '..', 'kreftjs.js'), path.join(dist, 'kreftjs.js'));
+  // the framework file is minified when esbuild is installed (about 40% smaller); without it, it is copied as it is
+  const runtimeSrc = path.join(__dirname, '..', 'kreftjs.js'), runtimeOut = path.join(dist, 'kreftjs.js');
+  const esb = minify ? deps.loadEsbuild(root) : null;
+  let minified = false;
+  if (esb) {
+    try {
+      fs.writeFileSync(runtimeOut, esb.transformSync(fs.readFileSync(runtimeSrc, 'utf8'), { minify: true, target: 'es2020', legalComments: 'none' }).code);
+      minified = true;
+    } catch (_) { /* fall back to the plain copy */ }
+  }
+  if (!minified) fs.copyFileSync(runtimeSrc, runtimeOut);
   for (const dir of include) {
     const from = path.resolve(dir);
     if (!fs.existsSync(from)) fail(`--include: ${dir} does not exist.`);

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', () => {
@@ -431,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));
@@ -521,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)) {
@@ -574,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)
@@ -164,6 +165,7 @@ function help() {
         --prerender [paths] Also save every page as ready HTML (needs: npm i -D jsdom)
         --include <folder>  Also copy this folder into the output (for example docs)
         --no-htaccess       Do not write dist/.htaccess (page-address rules for Apache and Hostinger)
+        --no-minify         Copy kreftjs.js as it is (by default it is minified when esbuild is installed)
     kreft add <packages...>     Install npm packages with strict security gatekeeper (alias: kreft install, kreft i)
         -D, --dev           Install as devDependency
         -y, --yes           Auto-confirm unverified community packages in CI/CD

package/book/ar/01-getting-started.md

@@ -0,0 +1,169 @@
+# الفصل الأول: البداية
+
+## ما هو Kreft؟
+
+Kreft (يُكتب `kreftjs`) إطار عمل صغير، تفاعلي (reactive)، له لغة مكوّنات خاصة به: ملفات `.kreft`. تكتب في الملف الواحد حالتك وقيمك المشتقة وأفعالك بكلمات بسيطة، ثم تصف الصفحة في `<view>`. ويأتي مع واجهة خلفية كاملة على Node.js (مسارات، ومتحكمات، ونماذج، وترحيلات، وطوابير، وبريد)، فيغطي المشروع الواحد التطبيق بأكمله.
+
+> **ملاحظة:** الإصدار الحالي تجريبي (`0.0.x-beta`). كل ما في هذا الكتاب جُرِّب على الإصدار الذي صدر معه، لكن واجهات الإطار قد تتغير بين الإصدارات التجريبية. راجع `kreft --version` وملف `docs/README.md` (بالإنجليزية) عند الشك.
+
+لماذا قد تختاره؟
+
+- **لغة واحدة للمكوّن:** HTML ومنطق وتنسيق في ملف واحد، بلا ديكورات ولا وحدات (modules) تتعلمها.
+- **بدون إعداد:** `kreft new` ثم `kreft dev`. لا ملف إعداد لأداة تجميع.
+- **واجهة خلفية جاهزة:** تسجيل دخول، وتحقق من البريد، واستعادة كلمة المرور، ولوحة إدارة، ومصادقة ثنائية.
+- **تطبيقات سطح المكتب:** `kreft new --electron` ثم تبني مثبّتات لـ Windows وmacOS وLinux.
+- **دعم RTL من الأساس:** تبديل اللغة واتجاه الصفحة من دالة واحدة (مهم لنا نحن العرب، وله فصل كامل).
+
+## التثبيت
+
+المتطلبات: Node.js (يُفضَّل 22 أو أحدث) وnpm.
+
+```bash
+npm install -g kreftjs
+kreft --version        # مثال: 0.0.19-beta
+```
+
+للتحقق من أن كل شيء سليم:
+
+```bash
+kreft about
+```
+
+وللحصول على تلوين الملفات وملفات المقتطفات (snippets) في VS Code أو Cursor:
+
+```bash
+kreft vscode
+```
+
+## أول تطبيق
+
+```bash
+kreft new my-app            # يسألك: JavaScript أم TypeScript؟
+cd my-app
+npm run dev
+```
+
+افتح العنوان الذي يطبعه الطرفية (عادة `http://localhost:8000`؛ وإن كان المنفذ مشغولًا يُستخدم التالي).
+
+خيارات مفيدة عند الإنشاء:
+
+```bash
+kreft new shop --db mysql --ts          # TypeScript وقاعدة MySQL
+kreft new site --ui tailwind --no-auth  # Tailwind بدون صفحات تسجيل الدخول
+kreft new desk --electron               # مع دعم تطبيقات سطح المكتب
+kreft new app-name --ui bootstrap --no-auth
+```
+
+> **تنبيه:** اكتب قيم الخيارات كما هي بالضبط: `bootstrap` و`tailwind` و`bulma` و`pico`. أي قيمة أخرى توقف الأمر مع رسالة تعرض القيم المسموحة.
+
+يأتي المشروع الجديد (إن لم تستعمل `--no-auth`) بصفحات الدخول والتسجيل واستعادة كلمة المرور وتأكيد البريد والملف الشخصي ولوحة الإدارة. وعند تشغيل `npm run dev` تُنشأ الجداول ومستخدم تجريبي:
+
+- البريد: `test@example.com`
+- كلمة المرور: `password`
+
+> **تحذير:** هذا المستخدم للتطوير المحلي فقط. احذفه أو لا تشغّل `--seed` أبدًا على قاعدة بيانات حقيقية.
+
+رسائل البريد (تأكيد، استعادة) تُطبع في الطرفية إلى أن تضبط `MAIL_URL`.
+
+## أصغر تطبيق ممكن
+
+يمكنك استعمال Kreft بلا مشروع كامل. التطبيق صفحة HTML وملفات `.kreft`:
+
+```html
+<!-- index.html -->
+<div id="app"></div>
+<script src="kreftjs.js"></script>
+<script>
+  Kreftjs.app('App.kreft').mount('#app')
+</script>
+```
+
+```html
+<!-- App.kreft -->
+state name = 'العالم'
+
+<view>
+  <h1>مرحبًا يا {name}</h1>
+  <input k-model="name">
+</view>
+```
+
+> **تحذير:** ملفات `.kreft` تحتاج خادمًا. المتصفحات ترفض تحميل الملفات من `file://`، فافتح التطبيق دائمًا عبر `npm run dev` أو أي خادم.
+
+## بنية المشروع
+
+ينشئ `kreft new` مجلدين لا يختلطان أبدًا: `frontend/` هو ما يصل المتصفح، و`backend/` هو الخادم ولا يمكن الوصول إليه عبر HTTP.
+
+```text
+my-app/
+├── frontend/
+│   ├── index.html          نقطة الدخول
+│   ├── App.kreft           المكوّن الجذر وحاوية الموجِّه
+│   ├── routes/web.kreft    مسارات الصفحات
+│   ├── layouts/            app.kreft (بعد الدخول)، guest.kreft (صفحات الدخول)
+│   ├── pages/              ملف .kreft لكل شاشة
+│   ├── components/         مكوّنات قابلة لإعادة الاستخدام
+│   ├── ui.css              نظام التصميم
+│   └── tests/              اختبارات المكوّنات
+├── backend/
+│   ├── config/             app.js, auth.js, database.js, redis.js, session.js
+│   ├── app/
+│   │   ├── Http/           Controllers, Middleware, Requests, Resources
+│   │   ├── Models/         User, PersonalAccessToken
+│   │   └── Auth/           مساعدات الجلسات
+│   ├── database/           migrations, seeders, factories
+│   └── routes/             api.js, auth.js, console.js
+├── .env                    الأسرار والإعدادات (لا ترفعه إلى Git أبدًا)
+├── package.json
+└── kreftjs.config.json     خيارات سطر الأوامر
+```
+
+لماذا الفصل مهم؟
+
+- `kreft dev` و`kreft build` يقدّمان `frontend/` فقط. أما `backend/` وملفات قاعدة البيانات و`.env` فلا عنوان ويب لها.
+- على macOS وLinux يمنح `kreft new` المجلد `backend/` والملف `.env` صلاحيات يقرؤها المالك فقط.
+- ملفات مثل `.env` و`*.db` و`*.pem` و`package.json` مرفوضة حتى لو طُلبت بالاسم.
+
+## إضافة مكتبة CSS
+
+أي مكتبة تعمل. أضف `<link>` في `index.html`، أو ثبّتها واستورد ملفها من ملف `.kreft`:
+
+```html
+import 'bootstrap/dist/css/bootstrap.min.css'   // npm i bootstrap
+import './theme.css'                            // ملفك الخاص بجانب هذا الملف
+```
+
+## حزم npm في المتصفح
+
+```bash
+kreft add dayjs nanoid lodash
+kreft add -D esbuild      # مرة واحدة لكل مشروع: يجهّز الحزم للمتصفح
+```
+
+```html
+import dayjs from 'dayjs'
+import { nanoid } from 'nanoid'
+
+state id = nanoid()
+
+<view>
+  <p>{dayjs().format('YYYY-MM-DD')}</p>
+</view>
+```
+
+الأمر `kreft add` نسخة أكثر أمانًا من `npm install`: يمنع سكربتات التثبيت افتراضيًا، ويتحقق من أخطاء الكتابة المتعمدة في أسماء الحزم (typosquatting)، وينبّه إلى الحزم التي نُشرت قبل أقل من 14 يومًا، ثم يشغّل `npm audit`.
+
+## أوامر ستستخدمها كل يوم
+
+| الأمر | وظيفته |
+|---|---|
+| `kreft new my-app` | ينشئ مشروعًا |
+| `kreft dev` | خادم التطوير مع إعادة تحميل فورية |
+| `kreft build` | يصرّف التطبيق إلى ملفات عادية في `dist/` |
+| `kreft serve dist` | يشغّل التطبيق المبني للمستخدمين الحقيقيين |
+| `kreft list` | يعرض كل أوامر نسختك |
+| `kreft help` | خيارات الأوامر الرئيسية |
+| `kreft tinker` | طرفية تفاعلية مع نماذجك (`await User.count()`) |
+| `kreft update` | يحدّث الحزم وملف `kreftjs.js` |
+
+تدريب سريع: أنشئ مشروعًا، وغيّر كلمة في `frontend/pages/` وراقب الصفحة تتبدل في المتصفح دون إعادة تحميل وبدون ضياع الحالة. هذه هي إعادة التحميل الفورية (hot reload).