@omega.js/desktop 0.1.0

package/dist/defaults/hooks/build/post.js

@@ -0,0 +1,9 @@
+// Optional consumer extension hook — called AFTER the build pipeline finishes, BEFORE
+// electron-builder packages anything. No-op by default.
+//
+// Use this for: post-build asset processing, additional file copies into dist/, generating
+// auxiliary files (changelog, license bundling, etc.).
+
+module.exports = async (ctx) => {
+  // ctx = { manager, mode, projectRoot, distDir }
+};

package/dist/defaults/hooks/build/pre.js

@@ -0,0 +1,9 @@
+// Optional consumer extension hook — called BEFORE the build pipeline runs (defaults →
+// distribute → bundle → sass → html → audit → build-config). No-op by default.
+//
+// Use this for: pre-flight checks, generating build-time artifacts, mutating config before
+// the bundle / build-config tasks see it.
+
+module.exports = async (ctx) => {
+  // ctx = { manager, mode, projectRoot }
+};

package/dist/defaults/hooks/notarize/post.js

@@ -0,0 +1,16 @@
+// Optional consumer extension hook — called AFTER @omega.js/desktop's built-in macOS
+// notarization has already run. No-op by default.
+//
+// Use this for: custom stapling, archiving the notarized .app, notifications, uploading the
+// notarized artifact to a secondary location.
+//
+// Receives the full electron-builder afterSign context.
+//
+// IMPORTANT: This file is NOT the notarization entrypoint. @omega.js/desktop's electron-builder integration
+// uses its own internal notarize hook as the afterSign entrypoint, then calls into this file
+// as a final step. You can never accidentally break notarization by editing this — at worst,
+// a thrown error here fails the build loudly.
+
+module.exports = async (context) => {
+  // No-op by default. Add your post-notarize logic here.
+};

package/dist/defaults/hooks/release/post.js

@@ -0,0 +1,9 @@
+// Optional consumer extension hook — called AFTER the release publishes successfully (after
+// electron-builder finishes). No-op by default.
+//
+// Use this for: posting to Slack/Discord, kicking off downstream workflows, updating a
+// changelog page on your marketing site, sending notification emails.
+
+module.exports = async (ctx) => {
+  // ctx = { manager, projectRoot, artifacts }   // artifacts: array of release/ paths
+};

package/dist/defaults/hooks/release/pre.js

@@ -0,0 +1,9 @@
+// Optional consumer extension hook — called BEFORE electron-builder runs the sign + notarize
+// + publish flow. No-op by default.
+//
+// Use this for: bumping version files in extra places, last-mile validations, archiving the
+// previous release before overwriting.
+
+module.exports = async (ctx) => {
+  // ctx = { manager, projectRoot }
+};

package/dist/defaults/src/assets/js/components/about/index.js

@@ -0,0 +1,10 @@
+// About window renderer entry.
+const Manager = require('@omega.js/desktop/renderer');
+
+const manager = new Manager();
+
+manager.initialize()
+  .then(() => {
+    const { logger } = manager;
+    logger.log('About window initialized!');
+  });

package/dist/defaults/src/assets/js/components/main/index.js

@@ -0,0 +1,14 @@
+// Main window renderer entry.
+const Manager = require('@omega.js/desktop/renderer');
+
+const manager = new Manager();
+
+manager.initialize()
+  .then(() => {
+    const { logger, ipc, storage, omega } = manager;
+
+    // Add your main-window UI logic here.
+    // ...
+
+    logger.log('Main window initialized!');
+  });

package/dist/defaults/src/assets/js/components/settings/index.js

@@ -0,0 +1,10 @@
+// Settings window renderer entry.
+const Manager = require('@omega.js/desktop/renderer');
+
+const manager = new Manager();
+
+manager.initialize()
+  .then(() => {
+    const { logger } = manager;
+    logger.log('Settings window initialized!');
+  });

package/dist/defaults/src/assets/scss/main.scss

@@ -0,0 +1,34 @@
+// ============================================
+// Theme Configuration
+// ============================================
+// Customize Classy theme variables here. See:
+// node_modules/@omega.js/desktop/dist/assets/themes/classy/_config.scss for all available variables.
+
+@use 'omega-desktop' as * with (
+  // ============================================
+  // Brand Colors
+  // ============================================
+  $primary: #2563EB,
+  // $secondary: #6C757D,
+
+  // ============================================
+  // Backgrounds
+  // ============================================
+  // $classy-bg-light: #FFFFFF,
+  // $classy-bg-dark: #212529,
+
+  // ============================================
+  // Typography (uncomment to customize)
+  // ============================================
+  // $font-family-sans-serif: -apple-system, sans-serif,
+
+  // ============================================
+  // Borders (uncomment to customize)
+  // ============================================
+  // $border-radius: 0.5rem,
+);
+
+// ============================================
+// Custom Global Styles
+// ============================================
+// Add your project-specific styles below — applied on every page.

package/dist/defaults/src/assets/scss/pages/about.scss

@@ -0,0 +1,3 @@
+// About window — page-specific styles. Compiled to dist/assets/css/components/about.bundle.css.
+
+// Add your page-only styles below.

package/dist/defaults/src/assets/scss/pages/main.scss

@@ -0,0 +1,4 @@
+// Main window — page-specific styles. Compiled to dist/assets/css/components/main.bundle.css
+// and loaded only on the main window's HTML page.
+
+// Add your page-only styles below.

package/dist/defaults/src/assets/scss/pages/settings.scss

@@ -0,0 +1,3 @@
+// Settings window — page-specific styles. Compiled to dist/assets/css/components/settings.bundle.css.
+
+// Add your page-only styles below.

package/dist/defaults/src/integrations/context-menu/index.js

@@ -0,0 +1,60 @@
+// Context-menu definition. Called by @omega.js/desktop EVERY time the user right-clicks.
+//
+// `manager`     — the running @omega.js/desktop Manager.
+// `menu`        — per-event builder API + id-path API.
+// `params`      — Electron's context-menu params (selectionText, isEditable, linkURL,
+//                 srcURL, mediaType, editFlags, x, y, etc.).
+// `webContents` — the webContents that fired the event.
+//
+// This file is OPTIONAL — delete it and @omega.js/desktop still ships a working context menu.
+//
+// @omega.js/desktop ships a default template (built per-event from params) with these ids (flat):
+//   undo, redo                                   — when params.editFlags allow
+//   cut, copy, paste, paste-and-match-style,
+//   select-all                                   — when params.isEditable
+//   copy                                          — when params.selectionText (read-only)
+//   open-link, copy-link                          — when params.linkURL
+//   reload                                        — always
+//   inspect, toggle-devtools                      — dev mode only
+
+module.exports = ({ manager, menu, params, webContents }) => {
+  // Start from @omega.js/desktop's default template. Don't add anything by default — leave it
+  // identical to what the framework would do without this file.
+  menu.useDefaults();
+
+  // ───────── Examples (uncomment to use) ─────────
+  //
+  // // Add "Search Google" when text is selected:
+  // if (params.selectionText) {
+  //   menu.insertAfter('copy', {
+  //     id: 'search-google',
+  //     label: `Search "${params.selectionText.slice(0, 20)}"`,
+  //     click: () => {
+  //       const { shell } = require('electron');
+  //       shell.openExternal(`https://google.com/search?q=${encodeURIComponent(params.selectionText)}`);
+  //     },
+  //   });
+  // }
+  //
+  // // Remove the dev-tools entry (even in development):
+  // menu.remove('toggle-devtools');
+  //
+  // // Hide instead of remove (visible:false):
+  // menu.hide('inspect');
+  //
+  // // Disable Paste without removing it:
+  // menu.enable('paste', false);
+  //
+  // // Add an "Open in External Editor" item only on links:
+  // if (params.linkURL) {
+  //   menu.insertAfter('open-link', {
+  //     id: 'open-in-editor',
+  //     label: 'Open in External Editor',
+  //     click: () => { /* ... */ },
+  //   });
+  // }
+  //
+  // // Build entirely from scratch instead of useDefaults():
+  // menu.clear();
+  // menu.item({ id: 'custom', label: 'Custom Action', click: () => {} });
+};

package/dist/defaults/src/integrations/menu/index.js

@@ -0,0 +1,58 @@
+// Application menu definition. Called by @omega.js/desktop during boot.
+//
+// `manager`  — the running @omega.js/desktop Manager.
+// `menu`     — builder API + id-path API (find/update/remove/insertAfter/etc.).
+// `defaults` — the platform-aware default template (an array you can mutate manually if needed).
+//
+// This file is OPTIONAL — delete it and @omega.js/desktop still ships a working application menu.
+//
+// @omega.js/desktop ships a default menu template with stable id paths. Highlights:
+//   main/about, main/check-for-updates, main/preferences (hidden), main/services,
+//     main/hide, main/relaunch, main/quit                                          (mac)
+//   file/close (mac), file/preferences, file/relaunch, file/quit                   (win/linux)
+//   edit/undo, edit/redo, edit/cut, edit/copy, edit/paste, edit/select-all
+//   view/reload, view/zoom-in, view/zoom-out, view/toggle-fullscreen
+//   view/developer/{toggle-devtools, inspect-elements, force-reload}               (dev only)
+//   window/minimize, window/zoom (mac), window/close (win/linux)
+//   help/check-for-updates (win/linux), help/website (when brand.url configured)
+//   development/{open-exe-folder, open-user-data, open-logs, open-app-config,
+//                test-error}                                                       (dev only)
+
+module.exports = ({ manager, menu, defaults }) => {
+  // Start from the platform-appropriate default template. Don't add anything
+  // by default — leave it identical to what the framework would do without
+  // this file. Add your own customizations below.
+  menu.useDefaults();
+
+  // ───────── Examples (uncomment to use) ─────────
+  //
+  // // Show the Preferences item (hidden by default — flip its visibility once you
+  // // wire up your settings window):
+  // menu.show(process.platform === 'darwin' ? 'main/preferences' : 'file/preferences');
+  //
+  // // Insert your own item right after Check for Updates:
+  // menu.insertAfter('main/check-for-updates', {
+  //   id: 'main/account',
+  //   label: 'Account...',
+  //   click: () => manager.windows.show('account'),
+  // });
+  //
+  // // Rename an existing item:
+  // menu.update('main/check-for-updates', { label: 'Get Latest Version' });
+  //
+  // // Remove an item entirely:
+  // menu.remove('view/reload');
+  //
+  // // Hide without removing (sets visible:false):
+  // menu.hide('main/services');
+  //
+  // // Add an entire new top-level menu:
+  // menu.menu('Tools', [
+  //   { id: 'tools/sync', label: 'Sync Now', click: () => {} },
+  //   { type: 'separator' },
+  //   { id: 'tools/export', label: 'Export...', click: () => {} },
+  // ]);
+  //
+  // // Append into an existing submenu:
+  // menu.appendTo('view', { id: 'view/custom-zoom', label: 'Custom Zoom...', click: () => {} });
+};

package/dist/defaults/src/integrations/tray/index.js

@@ -0,0 +1,60 @@
+// Tray definition. Called by @omega.js/desktop during boot.
+//
+// `manager` — the running @omega.js/desktop Manager.
+// `tray`    — builder API + id-path API (find/update/remove/insertAfter/etc.).
+//
+// @omega.js/desktop auto-resolves the tray icon by convention (most specific wins):
+//   1. config/icons/<platform>/tray.png   (platform-specific override)
+//   2. config/icons/global/tray.png       (universal fallback for all platforms)
+//   3. config/icons/<platform>/icon.png   (slot fallback: tray → app icon)
+//   4. @omega.js/desktop bundled default
+// And auto-sets the tooltip to config.app.productName.
+//
+// Default items shipped by @omega.js/desktop (flat ids — no `tray/` prefix needed):
+//   title              — disabled label showing the app name
+//   open               — "Open <app>"
+//   check-for-updates  — wired to autoUpdater (label/enabled auto-updated)
+//   website            — opens brand.url in external browser (only if configured)
+//   quit               — quits the app
+//
+// This file is OPTIONAL — delete it and @omega.js/desktop still ships a working tray.
+
+module.exports = ({ manager, tray }) => {
+  // Use @omega.js/desktop's default template + auto-resolved icon + auto-resolved tooltip.
+  tray.useDefaults();
+
+  // ───────── Examples (uncomment to use) ─────────
+  //
+  // // Override the icon path (otherwise auto-resolved from config/icons/macos/tray.png).
+  // // On macOS, the filename MUST end in `Template.png` for OS dark-mode auto-inversion.
+  // tray.icon('src/assets/icons/my-trayTemplate.png');
+  //
+  // // Override the tooltip (otherwise = productName):
+  // tray.tooltip('My Custom Tooltip');
+  //
+  // // Add your own item right after "Open":
+  // tray.insertAfter('open', {
+  //   id: 'dashboard',
+  //   label: 'Open Dashboard',
+  //   click: () => manager.windows.show('dashboard'),
+  // });
+  //
+  // // Rename an existing item:
+  // tray.update('open', { label: 'Show Window' });
+  //
+  // // Remove an item entirely:
+  // tray.remove('website');
+  //
+  // // Hide without removing (sets visible:false):
+  // tray.hide('check-for-updates');
+  //
+  // // Disable without removing (sets enabled:false):
+  // tray.enable('quit', false);
+  //
+  // // Add a submenu — items inside addressable as 'account/sign-out' etc.
+  // tray.insertBefore('quit', {
+  //   id: 'account', label: 'Account', submenu: [
+  //     { id: 'sign-out', label: 'Sign out', click: () => {} },
+  //   ],
+  // });
+};

package/dist/defaults/src/main.js

@@ -0,0 +1,78 @@
+// Main-process entry. Config is auto-loaded from config/omega.json5 (resolved for the desktop target).
+const Manager = require('@omega.js/desktop/main');
+
+const manager = new Manager();
+
+manager.initialize()
+  .then(() => {
+    const { logger, ipc, storage, windows, tray, menu, contextMenu, deepLink, autoUpdater, omega, appState, sentry, startup } = manager;
+
+    // ─────────────────────────────────────────────────────────────────────────────
+    // 1. Create the main window
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Always create `main` — @omega.js/desktop uses its presence in the registry to surface UI when
+    // the user double-clicks the dock icon (macOS) or relaunches the app (win/linux).
+    // In hidden launches (agent / menubar apps with `startup.mode = 'hidden'`, or auto-
+    // launch at login), pass `show: false` so the window is registered but invisible:
+    // tray icon shows immediately, dock icon + window appear when something explicitly
+    // calls `windows.show('main')` (or the user double-clicks the running app).
+    windows.create('main', { show: !startup.isLaunchHidden() });
+
+    // Hidden launches surface UI on demand. Example: a tray click that shows the window:
+    //
+    //   tray.update('open', { click: () => windows.show('main') });
+
+    // ─── Window create() options (all optional; defaults shown) ───────────────────
+    // windows.create('main', {
+    //   view:            'main',     // src/views/<view>/index.html (defaults to name)
+    //   width:           1024,       // initial width
+    //   height:          720,        // initial height
+    //   minWidth:        400,
+    //   minHeight:       300,
+    //   x:               undefined,  // initial x position (undefined = OS centers)
+    //   y:               undefined,  // initial y position
+    //   show:            true,       // auto-show on ready-to-show
+    //   title:           'My App',   // defaults to app.productName
+    //   backgroundColor: '#ffffff',  // pre-load bg color
+    //   hideOnClose:     true,       // X-button hides instead of closes (default for 'main')
+    //   persistBounds:   true,       // remember position+size across launches
+    //   skipTaskbar:     false,      // suppress taskbar/dock entry for THIS window
+    //   titleBar:        'inset',    // 'inset' (mac/win native overlay) or 'native'
+    //   titleBarOverlay: {           // Windows-only: native overlay color/size
+    //     color:       '#ffffff',
+    //     symbolColor: '#000000',
+    //     height:      36,
+    //   },
+    // });
+
+    // Secondary windows — built-in defaults (800x600, hideOnClose:false) are good
+    // enough for most cases. Examples:
+    //
+    //   windows.create('settings');                                  // baked defaults
+    //   windows.create('about', { width: 480, height: 360 });        // override at call site
+
+    // ─────────────────────────────────────────────────────────────────────────────
+    // 2. Wire up your custom logic
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    // Deep links: handle custom routes from <brand-id>://your-route URLs.
+    //   deepLink.on('settings/open', () => windows.create('settings'));
+    //   deepLink.on('checkout/success', ({ params }) => { /* params.session_id, etc. */ });
+
+    // IPC handlers: respond to renderer requests.
+    //   ipc.handle('my-app:get-data', async () => ({ ok: true, data: [] }));
+
+    // Disable framework features you don't want (idempotent, safe pre/post-init):
+    //   tray.disable();         // no tray icon
+    //   menu.disable();         // no application menu
+    //   contextMenu.disable();  // no right-click menus
+
+    // Subscribe to auto-update status (renderer can also listen via window.desktop.autoUpdater):
+    //   autoUpdater.onStatus((status) => logger.log('updater:', status.code));
+
+    // First-launch detection / launch counter / crash recovery:
+    //   if (appState.isFirstLaunch()) { /* welcome flow */ }
+    //   logger.log(`launch #${appState.getLaunchCount()}`);
+
+    logger.log('Main initialized!');
+  });

package/dist/defaults/src/preload.js

@@ -0,0 +1,15 @@
+// Preload entry. Exposes window.desktop to the renderer via contextBridge.
+const Manager = require('@omega.js/desktop/preload');
+
+const manager = new Manager();
+
+manager.initialize()
+  .then(() => {
+    const { logger } = manager;
+
+    // Add any extra contextBridge-exposed APIs here. Be careful — anything you expose runs
+    // in the renderer's context, so don't pass through privileged Node APIs without care.
+    // ...
+
+    logger.log('Preload initialized!');
+  });

package/dist/defaults/src/views/about/index.html

@@ -0,0 +1,3 @@
+<main>
+  <h1>About {{ app.productName }}</h1>
+</main>

package/dist/defaults/src/views/main/index.html

@@ -0,0 +1,8 @@
+<div class="container py-5 text-center">
+  <h1 class="display-4 fw-bold mb-3">{{ app.productName }}</h1>
+  <p class="lead text-muted mb-4">Powered by @omega.js/desktop.</p>
+  <div class="d-flex gap-2 justify-content-center">
+    <button type="button" class="btn btn-primary" id="get-started">Get started</button>
+    <button type="button" class="btn btn-outline-secondary" id="open-docs">Documentation</button>
+  </div>
+</div>

package/dist/defaults/src/views/settings/index.html

@@ -0,0 +1,3 @@
+<main>
+  <h1>Settings</h1>
+</main>

package/dist/defaults/test/README.md

@@ -0,0 +1,41 @@
+# Project tests
+
+Drop your project test suites here. The framework auto-runs them alongside its own when you run `npx omega test`.
+
+## Layers
+
+Match the framework's four layers — OMEGA Desktop's test runner discovers files by the directory they sit in:
+
+| Directory | Runtime | Use for |
+|---|---|---|
+| `test/build/` | Plain Node | Build-time logic, config validation, pure utilities |
+| `test/main/` | Spawned Electron main process | IPC, storage, windows, anything that needs `app.*` |
+| `test/renderer/` | Hidden BrowserWindow | Renderer-side logic, DOM, preload bridge (add `view: '<name>'` to load one of your `src/views/`) |
+| `test/boot/` | Consumer's actual built bundle | End-to-end smoke tests (does the app boot, does main show a window, do IPC handlers register) |
+
+A renderer suite that declares `view: '<name>'` runs against that view of YOUR app instead of the framework's harness page: the framework builds the app first, so the page carries your real preload, IPC handlers and config. It rides the boot lane, so `--layer=boot` (or the default `all`) runs it and `--layer=renderer` does not.
+
+## Coverage
+
+Every feature ships with tests at every layer it has a surface in — logic (`build`/`main`), UI (`renderer`), end-to-end (`boot`). Skip a layer only when the feature genuinely has no surface there; "the logic test covers it" does not excuse the UI test.
+
+## Quick example
+
+```js
+// test/build/my-feature.test.js
+const Manager = require('@omega.js/desktop/build');
+
+module.exports = {
+  layer: 'build',
+  description: 'the project config carries a brand id',
+  run: (ctx) => {
+    ctx.expect(Manager.getConfig().brand.id).toBeTruthy();
+  },
+};
+```
+
+That is the standalone form: one test per file. Every `run` receives `ctx`, whose `ctx.expect` is the Jest-compatible assertion library (there is nothing to require). The `suite`, `group` and array forms, and the `inspect` form the `boot` layer takes, are all in the reference below.
+
+## See also
+
+`node_modules/@omega.js/desktop/docs/test-framework.md` — full reference for the test framework (layers, assert API, fixtures, runner internals).

package/dist/defaults/test/_init.js

@@ -0,0 +1,10 @@
+/**
+ * Test lifecycle hook for this project. Runs once before any suite (not a test itself).
+ * See @omega.js/desktop/docs/test-framework.md → "test/_init.js".
+ */
+
+module.exports = ({ projectRoot }) => ({
+  // Seed any fixture a suite needs before it runs.
+  async setup() {
+  },
+});

package/dist/gulp/main.js

@@ -0,0 +1,144 @@
+// Strip ELECTRON_RUN_AS_NODE — see bin/omega-desktop for the full story. Belt-and-suspenders
+// at the gulp boundary too because gulp can be invoked outside of mgr (e.g. `npx gulp build`).
+delete process.env.ELECTRON_RUN_AS_NODE;
+
+// Libraries
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('main');
+const argv = Manager.getArguments();
+const { series, parallel } = require('gulp');
+const path = require('path');
+const glob = require('glob').globSync;
+
+// Load packages
+const package = Manager.getPackage('main');
+const project = Manager.getPackage('project');
+const projectRoot = Manager.getRootPath('project');
+
+// Resolve the .env cascade from the project root (shell > app > brand > company).
+// `target` delivers the schema's `deliverAs` renames into process.env (#678);
+// gulp can be invoked outside the CLI (`npx gulp build`), so it asks here too.
+require('../vendor/config/index.js').loadEnv(projectRoot, { target: 'desktop' });
+
+// Empty-string signing placeholders (CSC_LINK="" etc. from the .env template)
+// must read as UNSET — app-builder-lib only null-checks and would resolve ''
+// to the project root ("<projectRoot> not a file"). See utils/sanitize-signing-env.js.
+const sanitizedSigningKeys = require('../utils/sanitize-signing-env.js')(process.env);
+if (sanitizedSigningKeys.length) {
+  logger.log(`Ignoring empty signing env placeholders: ${sanitizedSigningKeys.join(', ')}`);
+}
+
+// Tee all stdout/stderr to <projectRoot>/logs/<dev|build>.log for easy `tail -f` / grep / Claude
+// inspection. build.log for production builds/packages (OMEGA_BUILD_MODE=true), dev.log for `npm start`.
+// Disable via OMEGA_LOG_FILE=false. Override path via OMEGA_LOG_FILE=<path>.
+const attachLogFile = require('../utils/attach-log-file.js');
+const logFileEnv = process.env.OMEGA_LOG_FILE;
+if (logFileEnv !== 'false' && logFileEnv !== '0') {
+  const defaultName = Manager.isBuildMode() ? 'build.log' : 'dev.log';
+  const logPath = (logFileEnv && logFileEnv !== 'true') ? logFileEnv : path.join(projectRoot, 'logs', defaultName);
+  attachLogFile(logPath);
+  logger.log(`Logs tee'd to ${logPath}`);
+}
+
+// Signing certificate lookup: explicit CSC_LINK → the brand's gitignored
+// .omega/certificates tree → the Keychain (the default, and what a tree-less
+// setup keeps getting). Runs AFTER the log tee so the chosen source and reason
+// land in build.log — the line a CI signing failure is diagnosed from.
+// See utils/resolve-signing-cert.js.
+const signingCert = require('../utils/resolve-signing-cert.js')({ projectRoot });
+if (signingCert.source === 'certificates') {
+  process.env.CSC_LINK = signingCert.cscLink;
+}
+logger.log(`Signing certificate: ${signingCert.source} (${signingCert.reason})`);
+
+// The signing paths the DELIVERED artifacts imply (#678): the manager's
+// disperse service used to stamp CSC_LINK / APPLE_API_KEY into the target's
+// .env; no machine writes a target .env any more, so an unset key whose file
+// sits in config/certs/ is derived here instead. Runs last: an explicit
+// answer, and the lookup above, always win. See utils/derive-signing-env.js.
+const derivedSigningKeys = require('../utils/derive-signing-env.js')({ env: process.env, projectDir: projectRoot });
+if (derivedSigningKeys.length) {
+  logger.log(`Derived signing env from the certs dir: ${derivedSigningKeys.map((entry) => `${entry.key}=${entry.value}`).join(', ')}`);
+}
+
+logger.log('Starting...', argv);
+
+// Auto-load tasks from src/gulp/tasks/*.js
+const tasks = glob('*.js', { cwd: `${__dirname}/tasks` });
+
+// Globals (parity with BXM)
+global.tasks = {};
+global.websocket = null;
+
+tasks.forEach((file) => {
+  const name = file.replace('.js', '');
+  logger.log('Loading task:', name);
+  exports[name] = require(path.join(__dirname, 'tasks', file));
+});
+
+global.tasks = exports;
+
+// Lifecycle hook tasks — each invokes the consumer's <projectRoot>/hooks/<name>.js file if it
+// exists, or no-ops. Inserted around the build/release stages so consumers can extend the
+// pipeline without forking gulp tasks.
+const runConsumerHook = require('../utils/run-consumer-hook.js');
+function makeHookTask(name) {
+  const fn = async () => {
+    const Manager = new (require('../build.js'));
+    await runConsumerHook(name, { manager: Manager, projectRoot: process.cwd(), mode: process.env.OMEGA_BUILD_MODE === 'true' ? 'production' : 'development' });
+  };
+  // Set displayName for nicer gulp logs.
+  Object.defineProperty(fn, 'name', { value: `hook:${name.replace('/', ':')}` });
+  return fn;
+}
+exports['hook:build:pre']   = makeHookTask('build/pre');
+exports['hook:build:post']  = makeHookTask('build/post');
+exports['hook:release:pre'] = makeHookTask('release/pre');
+exports['hook:release:post'] = makeHookTask('release/post');
+
+// Build pipeline: hook:build:pre → defaults → distribute → (sass | bundle | html in parallel)
+// → audit → build-config → hook:build:post.
+// build-config generates dist/electron-builder.yml entirely from @omega.js/desktop defaults +
+// config/omega.json5 (no consumer-shipped electron-builder.yml). Mode-dependent
+// injections (e.g. LSUIElement for tray-only) happen here. Must run BEFORE package/release.
+exports.build = series(
+  exports['hook:build:pre'],
+  exports.defaults,
+  exports.distribute,
+  parallel(exports.sass, exports.bundle, exports.html),
+  exports.audit,
+  exports['build-config'],
+  exports['hook:build:post'],
+);
+
+// Production package: build + electron-builder package (no publish)
+exports.packageBuild = series(
+  exports.build,
+  exports.package,
+);
+
+// Quick package: build + electron-builder --dir for host platform/arch only.
+// Skips DMG/zip/universal/notarize. Output: release/<platform>-<arch>/<ProductName>.app
+// (or .exe-folder on win, linux-unpacked on linux). ~20-30s. For local smoke-testing
+// production code paths (config loading, packaged-mode behavior) without the full pipeline.
+exports.packageQuick = series(
+  exports.build,
+  exports['package-quick'],
+);
+
+// Publish: build + hook:release:pre + electron-builder release + hook:release:post.
+// Single sign+notarize pass. The artifacts land in the brand's ONE public releases
+// repo under versionless names (#620/#799), which is what the site links: there is
+// no mirror step any more.
+exports.publish = series(
+  exports.build,
+  exports['hook:release:pre'],
+  exports.release,
+  exports['hook:release:post'],
+);
+
+// Default dev pipeline: build, then launch electron.
+exports.default = series(
+  exports.build,
+  exports.serve,
+);