@omega.js/desktop 0.52.0 → 0.54.0

package/dist/lib/_lifecycle-mixin.js

@@ -0,0 +1,45 @@
+// The main process's quit/relaunch pair: methods mixed into the `Omega` class
+// (src/main.js) with `Object.assign(Omega.prototype, ...)`, so they stay
+// `omega.quit()` and `omega.relaunch()` on the instance.
+
+module.exports = {
+  // Force a real quit, bypassing per-window `hideOnClose`. Use this anywhere the
+  // app legitimately wants to exit (tray Quit, Cmd+Q from menu role:'quit',
+  // auto-updater install). Without `{ force: true }`, the close events still get
+  // trapped by hide-on-close handlers and the app stays running.
+  quit(options) {
+    options = options || {};
+
+    if (options.force) {
+      this._allowQuit = true;
+    }
+
+    try {
+      require('electron').app.quit();
+    } catch (e) { /* electron not available: no-op in test/headless */ }
+  },
+
+  // Force a relaunch: same gating as quit, but tells electron to start back up
+  // after exit. If an update has been downloaded, prefers `quitAndInstall()` so
+  // the user lands on the new version instead of the old one.
+  relaunch(options) {
+    options = options || {};
+
+    if (options.force) {
+      this._allowQuit = true;
+    }
+
+    const electron = require('electron');
+
+    // If updater downloaded a fresh build, install + relaunch via electron-updater
+    // (which calls `app.quit()` internally with the right post-quit script). Falls
+    // back to plain relaunch if updater hasn't downloaded anything.
+    const updaterStatus = this.autoUpdater.getStatus();
+    if (updaterStatus.code === 'downloaded') {
+      return this.autoUpdater.installNow();
+    }
+
+    electron.app.relaunch();
+    electron.app.quit();
+  },
+};

package/dist/lib/analytics.js

@@ -1,6 +1,6 @@
 // Analytics — GA4 via Measurement Protocol. Mirrors @omega.js/backend's
-// `Manager.config.analytics.providers.google.id` shape so the same person can be
-// tracked across desktop (@omega.js/desktop) + web (UJM/@omega.js/client) + backend (@omega.js/backend) by
+// `omega.config.analytics.providers.google.id` shape so the same person can be
+// tracked across desktop (@omega.js/desktop) + web (@omega.js/client) + backend (@omega.js/backend) by
 // referencing a single namespaced UUIDv5 identity.
 //
 // Cross-platform identity (the key feature):
@@ -18,16 +18,16 @@
 // namespace via uuidv5.URL of the projectId string. Same projectId in @omega.js/backend/@omega.js/client/@omega.js/desktop
 // → the same uid hashes to the same user_id everywhere → unified analytics.
 //
-// Anonymous (client-bridge hasn't reported auth yet) → user_id stays null.
+// Anonymous (auth holds no signed-in account yet) → user_id stays null.
 // Authed (auth event fires) → user_id is set + a `login` event is dispatched. On
 // logout → user_id clears + `logout` event fires.
 //
 // API surface:
-//   manager.analytics.event(name, params?)         // generic event
-//   manager.analytics.pageview(path?)              // convenience wrapper
-//   manager.analytics.screenview(name?)            // convenience wrapper
-//   manager.analytics.setUserId(uid)               // manual override; auto-wired to omega
-//   manager.analytics.setUserProperties(props)     // merge into user_properties block
+//   omega.analytics.event(name, params?)         // generic event
+//   omega.analytics.pageview(path?)              // convenience wrapper
+//   omega.analytics.screenview(name?)            // convenience wrapper
+//   omega.analytics.setUserId(uid)               // manual override; auto-wired to auth
+//   omega.analytics.setUserProperties(props)     // merge into user_properties block
 //
 // Events fired during normal operation are queued until init completes (we need
 // context.session + measurement_id + secret). Once initialized, the queue
@@ -67,7 +67,7 @@ const MAX_QUEUE = 200;
 
 const analytics = {
   _initialized:  false,
-  _manager:      null,
+  _omega:        null,
   _enabled:      false,
   _measurementId: null,
   _apiSecret:    null,
@@ -78,12 +78,12 @@ const analytics = {
   _queue:        [],
   _authUnsub:    null,
 
-  initialize(manager) {
+  initialize(omega) {
     if (analytics._initialized) return;
     analytics._initialized = true;
-    analytics._manager = manager;
+    analytics._omega = omega;
 
-    const cfg = manager.config.analytics || {};
+    const cfg = omega.config.analytics || {};
 
     // Presence-driven: providers.google.id presence enables analytics. No separate
     // `enabled` flag (matches @omega.js/backend convention — credentials are the enable signal).
@@ -109,8 +109,8 @@ const analytics = {
     // projectId in @omega.js/backend/@omega.js/client/@omega.js/desktop → same namespace → same per-uid UUIDv5
     // everywhere. UUIDv5 needs a UUID-shaped namespace — we derive one from the
     // string projectId by hashing it into uuidv5.URL space (RFC 4122).
-    const projectId = manager.config.cloud?.config?.projectId
-      || manager.config.brand.id;
+    const projectId = omega.config.cloud?.config?.projectId
+      || omega.config.brand.id;
     analytics._namespace = core.deriveNamespace(projectId);
 
     // Apply a uid stored by a pre-init setUserId() call — the auth
@@ -125,7 +125,7 @@ const analytics = {
     // so an empty one is a broken boot order, never a runtime condition — and a
     // fresh id minted here would persist nowhere, making every launch a new GA
     // client (#396). It raises instead.
-    const deviceId = manager.context.session.deviceId;
+    const deviceId = omega.context.session.deviceId;
 
     if (!deviceId) {
       throw new Error('analytics.initialize() ran before context.initialize() resolved session.deviceId — the boot sequence must init context first');
@@ -142,16 +142,14 @@ const analytics = {
     analytics_.configure({
       transport: { send: (descriptor) => analytics._send(descriptor) },
       context: { runtime: 'electron' },
-      environment: manager.isDevelopment?.() ? 'development' : 'production',
+      environment: omega.isDevelopment?.() ? 'development' : 'production',
     });
 
-    // Wire auth subscription so user_id flips automatically on login/logout.
-    analytics._authUnsub = manager.omega.onAuthChange((snap) => {
-      analytics._handleAuthChange(snap);
+    // Listen to auth so user_id flips automatically on login/logout. The listen
+    // catch-up delivers the state auth already holds, so nothing is pulled here.
+    analytics._authUnsub = omega.auth.listen(({ user }) => {
+      analytics._handleAuthChange(user);
     });
-    // Pull current state immediately in case auth already resolved.
-    const current = manager.omega.getCurrentUser();
-    if (current?.uid) analytics._handleAuthChange(current);
 
     // Compute initial user_properties from context + usage.
     analytics._userProperties = analytics._buildUserProperties();
@@ -176,11 +174,11 @@ const analytics = {
 
     // IPC: renderer → main analytics calls. Forward fires-and-forgets via send;
     // status query via invoke.
-    manager.ipc.unhandle('desktop:analytics:status');
-    manager.ipc.handle('desktop:analytics:status', () => analytics.toJSON());
+    omega.ipc.unhandle('desktop:analytics:status');
+    omega.ipc.handle('desktop:analytics:status', () => analytics.toJSON());
     // Use Set-deduped listener; named handler so re-init collapses duplicates.
-    manager.ipc.on('desktop:analytics:event',               analytics._onIpcEvent);
-    manager.ipc.on('desktop:analytics:set-user-properties', analytics._onIpcSetProps);
+    omega.ipc.on('desktop:analytics:event',               analytics._onIpcEvent);
+    omega.ipc.on('desktop:analytics:set-user-properties', analytics._onIpcSetProps);
   },
 
   _onIpcEvent({ name, params } = {}) {
@@ -248,7 +246,7 @@ const analytics = {
     analytics.event('screen_view', name ? { screen_name: name } : {});
   },
 
-  // Manual user-id override. Normally client-bridge wires this automatically.
+  // Manual user-id override. Normally auth.listen wires this automatically.
   setUserId(uid) {
     if (!analytics._namespace) {
       // Init hasn't run yet — store and apply at init.
@@ -273,24 +271,24 @@ const analytics = {
   // GA4 param contract: each event needs engagement_time_msec (else session bounces),
   // and we add session_id + page_location so reports group properly.
   _enrichParams(params) {
-    const m = analytics._manager;
-    const ctx = m.context;
+    const omega = analytics._omega;
+    const ctx = omega.context;
     const sessionStart = ctx.session.startTime ? new Date(ctx.session.startTime).getTime() : Date.now();
     const engagement   = Math.max(1, Date.now() - sessionStart);
     return {
       session_id:           ctx.session.id || 'unknown',
       engagement_time_msec: engagement,
-      page_location:        params.page_location || `app://${m.config.brand.id}`,
-      page_title:           params.page_title || m.config.app?.productName || m.config.brand.name,
+      page_location:        params.page_location || `app://${omega.config.brand.id}`,
+      page_title:           params.page_title || omega.config.app?.productName || omega.config.brand.name,
       ...params,
     };
   },
 
   // Compute user-properties from current context + usage. Re-run on auth change.
   _buildUserProperties() {
-    const m = analytics._manager;
-    const ctx = m.context;
-    const usage = m.usage;
+    const omega = analytics._omega;
+    const ctx = omega.context;
+    const usage = omega.usage;
     const wrap = (v) => ({ value: v });
     const out = {
       app_version:      wrap(ctx.app.version || 'unknown'),
@@ -343,7 +341,7 @@ const analytics = {
       analytics._authUnsub();
     }
     analytics._initialized   = false;
-    analytics._manager       = null;
+    analytics._omega         = null;
     analytics._enabled       = false;
     analytics._measurementId = null;
     analytics._apiSecret     = null;

package/dist/lib/app-state.js

@@ -11,7 +11,7 @@
 //     sentinel:       true,             // set on launch, cleared on graceful quit; survival = crash
 //   }
 //
-// Public API on `manager.appState`:
+// Public API on `omega.appState`:
 //   isFirstLaunch()        — true only for the very first boot of the app on this machine
 //   getLaunchCount()       — total successful launches (including this one)
 //   getInstalledAt()       — Date of first launch
@@ -40,7 +40,7 @@ const STORAGE_KEY = 'appState';
 const appState = {
   _initialized:        false,
   _quitWired:          false,
-  _manager:            null,
+  _omega:              null,
   _electron:           null,
 
   // Cached snapshot of the state AS LOADED at the start of this launch.
@@ -54,15 +54,15 @@ const appState = {
   // Set by lib/deep-link.initialize when argv contains a deep-link payload.
   _launchedFromDeepLink: false,
 
-  async initialize(manager) {
+  async initialize(omega) {
     if (appState._initialized) {
       return;
     }
 
-    appState._manager = manager;
+    appState._omega = omega;
     appState._electron = require('electron');
 
-    const storage = manager.storage;
+    const storage = omega.storage;
 
     const now = Date.now();
     const previous = storage.get(STORAGE_KEY) || {};
@@ -74,11 +74,11 @@ const appState = {
     const previousQuitAt   = previous.lastQuitAt || null;
     appState._recoveredFromCrash = !isFirstLaunch && previousSentinel && !previousQuitAt;
 
-    // Version detection. Prefer the cross-context manager.getVersion() helper —
+    // Version detection. Prefer the cross-context omega.getVersion() helper —
     // it tries `app.getVersion()` first (authoritative in main, reads asar
     // package.json in packaged builds) and falls back to project package.json.
-    const currentVersion  = manager.config.app?.version
-                         || manager.getVersion()
+    const currentVersion  = omega.config.app?.version
+                         || omega.getVersion()
                          || tryGetVersionFromPackage()
                          || null;
     const previousVersion = previous.version || null;
@@ -122,7 +122,7 @@ const appState = {
     const onQuit = () => {
       if (cleared) return;
       cleared = true;
-      const storage = appState._manager.storage;
+      const storage = appState._omega.storage;
       const cur = storage.get(STORAGE_KEY) || {};
       cur.sentinel  = false;
       cur.lastQuitAt = Date.now();
@@ -157,7 +157,7 @@ const appState = {
     // The CURRENT snapshot's lastQuitAt is null (we cleared it on init).
     // What the consumer wants is "when did we previously quit gracefully" — read storage live,
     // because at the moment of the call this launch hasn't quit yet.
-    const cur = appState._manager.storage.get(STORAGE_KEY) || {};
+    const cur = appState._omega.storage.get(STORAGE_KEY) || {};
     const ms  = cur.lastQuitAt;
     return ms ? new Date(ms) : null;
   },
@@ -201,7 +201,7 @@ const appState = {
   // Test helper — wipe persisted state and reset the in-memory snapshot.
   // (Public, intentionally — used by integration tests + by consumers who want a "reset to factory" command.)
   reset() {
-    appState._manager.storage.delete(STORAGE_KEY);
+    appState._omega.storage.delete(STORAGE_KEY);
     appState._snapshot = null;
     appState._recoveredFromCrash = false;
     appState._launchedFromDeepLink = false;
@@ -209,11 +209,11 @@ const appState = {
 };
 
 function tryGetVersionFromPackage() {
-  // Last-resort fallback used only when manager.getVersion() is unavailable.
+  // Last-resort fallback used only when omega.getVersion() is unavailable.
   // Reads via build.js's getPackage helper which already handles "no package.json
   // at projectRoot" by returning null — no try/catch needed.
-  const Manager = require('../build.js');
-  const pkg = Manager.getPackage('project');
+  const build = require('../build.js');
+  const pkg = build.getPackage('project');
   return pkg?.version || null;
 }
 

package/dist/lib/auth-flow.js

@@ -1,6 +1,6 @@
-// Auth Flow — the framework-owned sign-in round trip: `manager.openAuthFlow()`.
+// Auth Flow — the framework-owned sign-in round trip: `omega.openAuthFlow()`.
 //
-// Opens the user's REAL default browser on manager.getAuthUrl()'s /signin → /token
+// Opens the user's REAL default browser on omega.getAuthUrl()'s /signin → /token
 // chain — never an embedded window, so sign-in rides the user's own browser session
 // (SSO with whatever they're already logged into). What differs per environment is
 // only the RETURN CHANNEL for the minted token:
@@ -25,12 +25,12 @@
 // return), and self-expiring (default 5 min). The browser tab gets a tiny
 // "return to the app" page on success.
 //
-// Public API (via manager):
-//   manager.openAuthFlow(options?)  → Promise<{ url, port? }> — resolves once the flow
+// Public API (via omega):
+//   omega.openAuthFlow(options?)  → Promise<{ url, port? }> — resolves once the flow
 //                                     is LAUNCHED; completion arrives later through
-//                                     auth/token → omega.handleAuthToken →
+//                                     auth/token → auth.handleToken →
 //                                     the desktop:auth:sign-in-with-token broadcast.
-//   manager.authFlow.cancel()       → tear down a pending dev listener (idempotent).
+//   omega.authFlow.cancel()       → tear down a pending dev listener (idempotent).
 
 const crypto = require('crypto');
 const http = require('http');
@@ -43,26 +43,26 @@ const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
 
 const authFlow = {
   _initialized: false,
-  _manager:     null,
+  _omega:       null,
   _pending:     null,   // { server, nonce, timer, port } — the one in-flight dev listener
 
-  initialize(manager) {
+  initialize(omega) {
     if (authFlow._initialized) {
       return;
     }
-    authFlow._manager = manager;
+    authFlow._omega = omega;
     authFlow._initialized = true;
   },
 
   // Open the sign-in flow in the user's default browser. Resolves once the flow is
   // launched — NOT when the user finishes signing in.
   async open(options) {
-    const manager = authFlow._manager;
+    const omega = authFlow._omega;
     options = options || {};
 
     // Production: the OS routes the custom scheme back to us — plain external open.
-    if (manager.isProduction()) {
-      const url = manager.getAuthUrl();
+    if (omega.isProduction()) {
+      const url = omega.getAuthUrl();
       require('electron').shell.openExternal(url);
       logger.log(`production — opened ${url}`);
       return { url };
@@ -89,7 +89,7 @@ const authFlow = {
     authFlow._pending = { server, nonce, timer, port };
 
     const returnUrl = `http://127.0.0.1:${port}/auth/token?state=${nonce}`;
-    const url = manager.getAuthUrl(null, returnUrl);
+    const url = omega.getAuthUrl(null, returnUrl);
     require('electron').shell.openExternal(url);
     logger.log(`dev — loopback listener on 127.0.0.1:${port}, opened ${url}`);
     return { url, port };
@@ -113,7 +113,7 @@ const authFlow = {
   },
 
   _handleRequest(req, res) {
-    const manager = authFlow._manager;
+    const omega = authFlow._omega;
     const pending = authFlow._pending;
     const url = new URL(req.url, 'http://127.0.0.1');
 
@@ -136,18 +136,18 @@ const authFlow = {
     }
 
     // Valid return: reply, tear down, then feed the SAME pipeline production uses.
-    const appName = manager.config?.brand?.name || 'the app';
+    const appName = omega.config?.brand?.name || 'the app';
     res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', Connection: 'close' });
     res.end(authFlow._page('Signed in', `You can close this tab and return to ${appName}.`));
     authFlow.cancel();
 
-    const brandId = manager.config.brand.id;
-    manager.deepLink.dispatch(`${brandId}://auth/token?authToken=${encodeURIComponent(token)}`);
+    const brandId = omega.config.brand.id;
+    omega.deepLink.dispatch(`${brandId}://auth/token?authToken=${encodeURIComponent(token)}`);
 
     // The browser held focus during sign-in — bring the app back to the front,
     // mirroring what a real OS deep-link arrival does. windows.show is the
     // stealth-aware surface (raw win.show() would flash windows during tests).
-    manager.windows.show('main');
+    omega.windows.show('main');
   },
 
   _page(title, message) {

package/dist/lib/auth-persistence.js

@@ -1,6 +1,6 @@
 // Auth Persistence — pluggable MAIN-process storage for the Firebase auth session.
 //
-// Every browser context (renderers here, popup/options/background in BXM) gets Firebase
+// Every browser context (renderers here, popup/options/background in an extension) gets Firebase
 // session persistence for free via IndexedDB. Main is the one Node context — Firebase
 // defaults to in-memory there, so sign-in died with the process and the bridge's
 // authority rule signed every renderer out on the next boot.
@@ -30,7 +30,7 @@
 // signal isTestRun() reads below ([#907](https://github.com/Omega-JS-Stack/omega/issues/907)).
 //
 // Select via config `omega.authPersistence` ('safeStorage' | 'none' | a custom
-// registered name). Register custom strategies BEFORE manager.initialize():
+// registered name). Register custom strategies BEFORE omega.initialize():
 //   require('@omega.js/desktop/lib/auth-persistence').register('keytar', {...})
 //
 // The firebase adapter mirrors firebase's own getReactNativePersistence(): a class
@@ -114,18 +114,18 @@ const noneStrategy = {
   async removeItem() {},
 };
 
-// Is this process a TEST RUN, in either lane that reaches this lib? The manager
+// Is this process a TEST RUN, in either lane that reaches this lib? The omega instance
 // answers it, in both: each lane spawns its child with `OMEGA_ENVIRONMENT=testing`
 // and the baked word never writes over it
 // ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)), so a booted
 // production artifact reports the lane it is running in too.
-function isTestRun(manager) {
-  return !!manager?.isTesting?.();
+function isTestRun(omega) {
+  return !!omega?.isTesting?.();
 }
 
 const authPersistence = {
   _initialized: false,
-  _manager:     null,
+  _omega:       null,
   _strategies: {
     safeStorage: safeStorageStrategy,
     none:        noneStrategy,
@@ -134,15 +134,15 @@ const authPersistence = {
 
   // Lib-shape conformance — the real work happens in resolve(), called by the
   // @omega.js/client bridge at auth boot (it needs the async availability check).
-  initialize(manager) {
+  initialize(omega) {
     if (authPersistence._initialized) {
       return;
     }
-    authPersistence._manager = manager;
+    authPersistence._omega = omega;
     authPersistence._initialized = true;
   },
 
-  // Consumers add custom strategies before manager.initialize().
+  // Consumers add custom strategies before omega.initialize().
   register(name, strategy) {
     if (!name || typeof strategy?.getItem !== 'function') {
       throw new Error('auth-persistence.register: strategy must implement getItem/setItem/removeItem/available');
@@ -152,20 +152,20 @@ const authPersistence = {
 
   // Pick + availability-check the configured strategy. Returns the active strategy
   // or null (→ caller falls back to firebase's in-memory default).
-  async resolve(manager) {
+  async resolve(omega) {
     // A TEST RUN is `none`, before any config is read: the test lanes never sign a
     // real user in, so the OS keychain is never asked. This overrides an explicit
     // consumer value too, because the boot layer boots the brand's REAL config through
     // the staged test app, and an unsigned Electron binary asking macOS for a keychain
     // item parks the whole run behind a SecurityAgent prompt
     // ([#907](https://github.com/Omega-JS-Stack/omega/issues/907)).
-    if (isTestRun(manager)) {
+    if (isTestRun(omega)) {
       logger.log('auth persistence: none (test mode)');
       authPersistence._active = null;
       return null;
     }
 
-    const wanted = manager.config?.omega?.authPersistence || 'safeStorage';
+    const wanted = omega.config?.omega?.authPersistence || 'safeStorage';
     const strategy = authPersistence._strategies[wanted];
 
     if (!strategy) {