@omega.js/desktop 0.1.0

package/dist/lib/context.js

@@ -0,0 +1,162 @@
+// Runtime context — what we know about the user's machine + their network +
+// the current session. Modeled after @omega.js/backend's `assistant.request.{geolocation,client}`
+// shape so @omega.js/desktop apps + sister projects (@omega.js/backend, UJM, @omega.js/client) all reference the
+// same property paths when reading user info.
+//
+// Populated asynchronously during manager.initialize():
+//
+//   manager.context.geolocation = { ip, country, region, city }      // ipify-fetched
+//   manager.context.client      = { userAgent, locale, platform, arch, mobile }
+//   manager.context.session     = { id, startTime, deviceId }        // desktop-specific
+//   manager.context.app         = { version, environment, isPackaged }
+//
+// Geolocation is fetched from https://api.ipify.org (IP only) and persisted to
+// storage so a subsequent boot offline still reports the last-known IP. The
+// `country/region/city` fields stay null until we add a richer geolocation
+// fetcher (left as a future enhancement so we don't add a brittle dep here).
+//
+// Session is one-shot per launch; deviceId is persistent across launches via
+// `os.networkInterfaces()` (first non-internal MAC) with a generated-UUID
+// fallback persisted to storage on first launch.
+
+const os         = require('os');
+const crypto     = require('crypto');
+const LoggerLite = require('./logger-lite.js');
+const fetch      = require('wonderful-fetch');
+// The device-id walk itself is the shared one — @omega.js/analytics owns it, and
+// @omega.js/client makes the same call with a browser's storage
+// ([#396](https://github.com/Omega-JS-Stack/omega/issues/396)). This module
+// supplies what is genuinely desktop's: electron-store and the MAC seed.
+const core = require('../vendor/analytics/core.js');
+
+const logger = new LoggerLite('context');
+
+const STORAGE_KEY = 'context';
+const IPIFY_URL   = 'https://api.ipify.org?format=json';
+const IP_FETCH_TIMEOUT_MS = 5000;
+
+const context = {
+  _initialized: false,
+  _manager:     null,
+
+  // Public shape — populated during initialize(). Exported as plain JSON so renderer
+  // tests + IPC consumers can read it via structured-clone.
+  geolocation: { ip: null, country: null, region: null, city: null },
+  client:      { userAgent: null, locale: null, platform: null, arch: null, mobile: false },
+  session:     { id: null, startTime: null, deviceId: null },
+  app:         { version: null, environment: null, isPackaged: null },
+
+  async initialize(manager) {
+    if (context._initialized) return;
+    context._initialized = true;
+    context._manager = manager;
+
+    // ─── session ──────────────────────────────────────────────────────────────
+    context.session.id        = crypto.randomUUID();
+    context.session.startTime = new Date().toISOString();
+    context.session.deviceId  = await context._resolveDeviceId();
+
+    // ─── client ───────────────────────────────────────────────────────────────
+    context.client.platform = os.platform();
+    context.client.arch     = os.arch();
+    context.client.mobile   = false;   // desktop framework — never true
+
+    const { app } = require('electron');
+    context.client.userAgent = app.userAgentFallback || null;
+    context.client.locale    = app.getLocale();
+    context.app.isPackaged   = app.isPackaged;
+
+    // ─── app ──────────────────────────────────────────────────────────────────
+    context.app.version     = manager.getVersion();
+    context.app.environment = manager.getEnvironment();
+
+    // ─── geolocation ──────────────────────────────────────────────────────────
+    // Restore last-known from storage immediately so we always have SOMETHING to
+    // work with (offline boot, ipify down, slow network, etc.). Then fire the
+    // network fetch in the background — when it lands it overwrites + persists.
+    const cached = manager.storage.get(STORAGE_KEY) || null;
+    if (cached?.geolocation) {
+      Object.assign(context.geolocation, cached.geolocation);
+    }
+    // Fire-and-forget; failures fall back to cached.
+    context._fetchGeolocation().catch((e) => logger.warn(`geolocation fetch failed: ${e.message}`));
+
+    // IPC: renderer can read the full context block.
+    manager.ipc.unhandle('desktop:context:get');
+    manager.ipc.handle('desktop:context:get', () => context.toJSON());
+
+    logger.log(`context initialized — session=${context.session.id} deviceId=${context.session.deviceId} platform=${context.client.platform}`);
+  },
+
+  // Resolve a stable per-machine UUID — the shared walk, with this target's
+  // storage and seed handed in. Order:
+  //   1. Storage (already persisted from a prior boot — wins so we're stable across
+  //      NIC swaps / VPN changes that would shuffle MAC-derived IDs).
+  //   2. First non-internal MAC from os.networkInterfaces() (stable on a stable
+  //      rig) — the SEED injected below, so a reinstalled app resolves the same
+  //      id it had before its storage was wiped.
+  //   3. A generated UUID (the shared derivation's floor), persisted for next boot.
+  async _resolveDeviceId() {
+    const m = context._manager;
+
+    return core.deriveDeviceId({
+      get:  () => m.storage.get(`${STORAGE_KEY}.deviceId`),
+      set:  (id) => m.storage.set(`${STORAGE_KEY}.deviceId`, id),
+      seed: () => context._readFirstMac(),
+    });
+  },
+
+  // Walk os.networkInterfaces() and return the first MAC that's not all-zeros and
+  // not the internal loopback. Returns null if none found.
+  _readFirstMac() {
+    try {
+      const ifaces = os.networkInterfaces();
+      for (const name of Object.keys(ifaces)) {
+        for (const iface of ifaces[name] || []) {
+          if (iface.internal) continue;
+          if (!iface.mac || iface.mac === '00:00:00:00:00:00') continue;
+          return iface.mac;
+        }
+      }
+    } catch (_) { /* fall through */ }
+    return null;
+  },
+
+  // Async geolocation fetch. ipify gives us the IP; richer country/region/city
+  // lookups can be added later via a separate provider (kept simple here so the
+  // happy path is one fast HTTPS round-trip, no third-party data leak surface
+  // beyond ipify itself).
+  async _fetchGeolocation() {
+    const data = await fetch(IPIFY_URL, {
+      method:   'get',
+      response: 'json',
+      timeout:  IP_FETCH_TIMEOUT_MS,
+      tries:    1,
+    });
+    const ip = data?.ip || null;
+    if (!ip) return;
+
+    context.geolocation.ip = ip;
+    // Persist for next launch so an offline boot still has a usable IP.
+    context._manager.storage.set(`${STORAGE_KEY}.geolocation`, { ...context.geolocation });
+  },
+
+  // Test/teardown helper. Re-initialize is idempotent guarded; call this first
+  // if a test wants to re-run with mutated state.
+  shutdown() {
+    context._initialized = false;
+    context._manager     = null;
+  },
+
+  // Plain-JSON snapshot — what gets sent over IPC to the renderer.
+  toJSON() {
+    return {
+      geolocation: { ...context.geolocation },
+      client:      { ...context.client },
+      session:     { ...context.session },
+      app:         { ...context.app },
+    };
+  },
+};
+
+module.exports = context;

package/dist/lib/deep-link.js

@@ -0,0 +1,370 @@
+// Deep Link — unified cross-platform deep-link handler.
+//
+// Cross-platform plumbing handled internally:
+//   - macOS: the OS routes `<scheme>://...` URLs via `app.on('open-url')`. Cold-start opens may queue
+//            them before whenReady; we drain them after.
+//   - Windows/Linux: deep links arrive as the LAST entry in `process.argv` on cold-start, and as the
+//            `argv` arg of `app.on('second-instance')` on warm-start.
+//
+// Public API on manager.deepLink:
+//
+//   manager.deepLink.on(routeOrPattern, fn)    // register a handler. Returns unsubscribe fn.
+//   manager.deepLink.off(routeOrPattern, fn)
+//   manager.deepLink.dispatch(url)             // manually fire (for testing or custom triggers)
+//   manager.deepLink.getColdStartUrl()         // the deep-link URL the app was launched with, or null
+//
+// Handler signature:
+//
+//   manager.deepLink.on('user/profile/:id', (ctx) => {
+//     ctx.url      // 'myapp://user/profile/42?ref=abc'
+//     ctx.scheme   // 'myapp'
+//     ctx.route    // 'user/profile/42'
+//     ctx.pattern  // 'user/profile/:id' — the matching pattern
+//     ctx.params   // { id: '42' }
+//     ctx.query    // { ref: 'abc' }
+//     ctx.source   // 'cold-start' | 'warm-start' | 'manual'
+//     ctx.argv     // process.argv (cold) or second-instance argv
+//     ctx.cwd      // process.cwd() or second-instance cwd
+//     ctx.handled  // mutate: set true to suppress fall-through to '*' catch-all
+//   });
+//
+// Patterns:
+//   - Exact: 'auth/token'
+//   - Param: 'user/profile/:id', 'org/:slug/repo/:repo'
+//   - Wildcard: '*' (catch-all, runs only if no concrete handler claimed the event)
+//
+// Multiple handlers per pattern run in registration order. Setting ctx.handled = true stops
+// the fall-through to wildcard handlers (concrete-pattern handlers always run).
+//
+// Built-in routes (registered by @omega.js/desktop, can be overridden by registering your own handler):
+//   auth/token   → manager.omega.handleAuthToken(query.token)  [Pass 2.12 wires this up]
+//   app/show     → manager.windows.show(query.window || 'main')
+//   app/quit     → app.quit()
+//
+// Built-in handlers run AFTER consumer handlers, so a consumer can shadow any built-in
+// by registering their own handler for the same route and setting ctx.handled = true.
+
+const LoggerLite = require('./logger-lite.js');
+
+const logger = new LoggerLite('deep-link');
+
+const deepLink = {
+  _initialized:    false,
+  _manager:        null,
+  _electron:       null,
+  _handlers:       [],          // [{ pattern, fn, builtin: bool }]
+  _coldStartUrl:   null,        // the URL the app was launched with (if any)
+  _wired:          false,       // open-url + second-instance + queueing wired?
+  _pendingUrls:    [],          // urls received before whenReady — drained on init
+  _managerReady:   false,       // manager.initialize() finished — safe to dispatch
+  _bootQueue:      [],          // dispatches held until _managerReady (client-bridge et al. are up)
+
+  initialize(manager) {
+    if (deepLink._initialized) {
+      return;
+    }
+
+    deepLink._manager = manager;
+    deepLink._electron = require('electron');
+
+    deepLink._wireElectronEvents();
+    deepLink._registerBuiltins();
+
+    // Cold-start argv parse. On Windows/Linux the deep link arrives in argv;
+    // on macOS it arrives via open-url (already wired above).
+    const coldUrl = deepLink._extractUrlFromArgv(process.argv);
+    if (coldUrl) {
+      deepLink._coldStartUrl = coldUrl;
+      manager.appState.setLaunchedFromDeepLink(true);
+      // _handle queues until markManagerReady() — a cold-start auth/token must
+      // not dispatch before client-bridge has booted Firebase.
+      deepLink._handle(coldUrl, 'cold-start', { argv: process.argv, cwd: process.cwd() });
+    }
+
+    // Drain anything that came in via open-url before initialize ran.
+    if (deepLink._pendingUrls.length > 0) {
+      const urls = deepLink._pendingUrls.slice();
+      deepLink._pendingUrls = [];
+      if (!deepLink._coldStartUrl) {
+        deepLink._coldStartUrl = urls[0];
+        manager.appState.setLaunchedFromDeepLink(true);
+      }
+      urls.forEach((u) => deepLink._handle(u, 'cold-start', { argv: process.argv, cwd: process.cwd() }));
+    }
+
+    logger.log(`initialize — coldStartUrl=${deepLink._coldStartUrl || '(none)'} handlers=${deepLink._handlers.length}`);
+    deepLink._initialized = true;
+  },
+
+  _wireElectronEvents() {
+    if (deepLink._wired) return;
+    deepLink._wired = true;
+
+    const { app } = deepLink._electron;
+
+    // macOS: open-url. Fires for both cold-start and warm-start opens.
+    app.on('open-url', (event, url) => {
+      event.preventDefault();
+      // Before whenReady: queue.
+      if (!app.isReady()) {
+        deepLink._pendingUrls.push(url);
+        return;
+      }
+      // Post-whenReady: dispatch as warm-start (the app is already running).
+      deepLink._handle(url, 'warm-start', { argv: process.argv, cwd: process.cwd() });
+    });
+
+    // Windows/Linux warm-start: another instance launched (e.g. user double-clicked the
+    // app icon while it's already running, or a deep link arrived). The OS gave us the
+    // lock, killed the duplicate, and forwarded its argv here.
+    app.on('second-instance', (_event, argv, cwd) => {
+      logger.log(`second-instance — argv=${JSON.stringify(argv)} cwd=${cwd}`);
+
+      // Surface the main window. With hidden-mode apps, the consumer typically created
+      // `main` with `show: false` at boot, so it's in the registry but invisible — we
+      // just need to show it now that the user explicitly asked.
+      const main = deepLink._manager.windows.get('main');
+      if (main) {
+        logger.log(`second-instance — surfacing main (visible=${main.isVisible()}, minimized=${main.isMinimized()})`);
+        if (main.isMinimized()) main.restore();
+        deepLink._manager.windows._ensureDockVisible();
+        main.show();
+        main.focus();
+      } else {
+        logger.log('second-instance — no main window in registry; ignoring');
+      }
+
+      const url = deepLink._extractUrlFromArgv(argv);
+      if (url) {
+        deepLink._handle(url, 'warm-start', { argv, cwd });
+      }
+    });
+  },
+
+  _registerBuiltins() {
+    // auth/token — hand off to client-bridge. The receiving end of
+    // manager.getAuthUrl()'s sign-in round-trip: the website's token page redirects
+    // here with ?authToken=<custom-token>. MODERN shape only — legacy-app formats
+    // (?payload=, ?token=) are UJM's concern, not @omega.js/desktop's.
+    deepLink._handlers.push({
+      pattern: 'auth/token',
+      builtin: true,
+      fn: (ctx) => {
+        const token = ctx.query?.authToken;
+        if (!token) {
+          logger.warn('auth/token: no authToken in query string.');
+          return;
+        }
+        deepLink._manager.omega.handleAuthToken(token);
+      },
+    });
+
+    // app/show — surface a named window.
+    deepLink._handlers.push({
+      pattern: 'app/show',
+      builtin: true,
+      fn: (ctx) => {
+        const name = ctx.query?.window || 'main';
+        deepLink._manager.windows.show(name);
+      },
+    });
+
+    // app/quit — graceful quit.
+    deepLink._handlers.push({
+      pattern: 'app/quit',
+      builtin: true,
+      fn: () => {
+        deepLink._electron.app.quit();
+      },
+    });
+  },
+
+  // Pull a `<scheme>://...` URL out of an argv array. Returns null if none of our schemes match.
+  _extractUrlFromArgv(argv) {
+    if (!Array.isArray(argv)) return null;
+    const schemes = deepLink._manager.protocol.getSchemes();
+    if (schemes.length === 0) return null;
+
+    // Walk argv backward — the URL is typically the last meaningful arg.
+    for (let i = argv.length - 1; i >= 0; i -= 1) {
+      const a = argv[i];
+      if (typeof a !== 'string') continue;
+      if (schemes.some((s) => a.startsWith(`${s}://`))) {
+        return a;
+      }
+    }
+    return null;
+  },
+
+  // Parse a `<scheme>://route?query` URL into a route object.
+  _parseUrl(url) {
+    try {
+      const u = new URL(url);
+      const scheme = u.protocol.replace(/:$/, '');
+      // host + pathname together form the "route." Strip leading/trailing slashes.
+      // myapp://auth/token        → host='auth', pathname='/token' → route='auth/token'
+      // myapp://user/profile/42   → host='user', pathname='/profile/42' → route='user/profile/42'
+      const host = u.host || u.hostname || '';
+      const path = (u.pathname || '').replace(/^\/+|\/+$/g, '');
+      const route = [host, path].filter(Boolean).join('/');
+
+      const query = {};
+      u.searchParams.forEach((v, k) => { query[k] = v; });
+
+      return { scheme, route, query };
+    } catch (e) {
+      logger.warn(`failed to parse URL "${url}":`, e.message);
+      return null;
+    }
+  },
+
+  // Match a parsed route against a registered pattern. Returns the params object on match,
+  // or null on miss. Wildcard '*' matches anything and yields {}.
+  _matchPattern(route, pattern) {
+    if (pattern === '*') return {};
+    const pParts = pattern.split('/');
+    const rParts = route.split('/');
+    if (pParts.length !== rParts.length) return null;
+
+    const params = {};
+    for (let i = 0; i < pParts.length; i += 1) {
+      const p = pParts[i];
+      const r = rParts[i];
+      if (p.startsWith(':')) {
+        params[p.slice(1)] = decodeURIComponent(r);
+      } else if (p !== r) {
+        return null;
+      }
+    }
+    return params;
+  },
+
+  // Called by main.js once manager.initialize() completes — every LIB a handler
+  // touches (client-bridge Firebase, the windows registry, tray) is up from here
+  // on. (Consumer-created windows may still be pending — consumers create them
+  // in initialize().then(); app/show on a not-yet-created window warns + drops,
+  // same as always.) Any dispatch that arrived earlier drains now.
+  markManagerReady() {
+    deepLink._managerReady = true;
+    const queued = deepLink._bootQueue.slice();
+    deepLink._bootQueue = [];
+    queued.forEach(({ url, source, env }) => deepLink._handle(url, source, env));
+  },
+
+  // Run the dispatch pipeline for a single URL.
+  _handle(url, source, env) {
+    // Hold every dispatch until the manager is fully initialized — handlers
+    // deref manager surfaces that don't exist yet during boot.
+    if (!deepLink._managerReady) {
+      logger.log(`queueing ${source} dispatch until manager ready — ${url}`);
+      deepLink._bootQueue.push({ url, source, env });
+      return;
+    }
+
+    const parsed = deepLink._parseUrl(url);
+    if (!parsed) return;
+
+    logger.log(`dispatch — source=${source} scheme=${parsed.scheme} route=${parsed.route}`);
+
+    // Concrete (non-wildcard) handlers first, in registration order. Consumer concrete handlers
+    // are appended in registration order; built-in handlers were registered first by @omega.js/desktop, so
+    // they run last among concrete handlers — meaning a consumer concrete handler runs BEFORE
+    // @omega.js/desktop's built-in for the same route. To shadow a built-in entirely, the consumer sets
+    // ctx.handled = true.
+    //
+    // We split into concrete + wildcard so wildcards never run if any concrete handler matched.
+    const concrete = deepLink._handlers.filter((h) => h.pattern !== '*');
+    const wild     = deepLink._handlers.filter((h) => h.pattern === '*');
+
+    // Re-order: consumer concrete handlers BEFORE built-ins of the same pattern, regardless of
+    // registration order. We do this by partitioning by builtin flag.
+    const consumerConcrete = concrete.filter((h) => !h.builtin);
+    const builtinConcrete  = concrete.filter((h) =>  h.builtin);
+    const ordered = [...consumerConcrete, ...builtinConcrete];
+
+    let matched = false;
+    let claimed = false;
+
+    for (const h of ordered) {
+      const params = deepLink._matchPattern(parsed.route, h.pattern);
+      if (params == null) continue;
+      matched = true;
+
+      const ctx = {
+        url,
+        scheme:  parsed.scheme,
+        route:   parsed.route,
+        pattern: h.pattern,
+        params,
+        query:   parsed.query,
+        source,
+        argv:    env?.argv || process.argv,
+        cwd:     env?.cwd  || process.cwd(),
+        handled: false,
+      };
+
+      try {
+        h.fn(ctx);
+      } catch (e) {
+        logger.error(`handler for "${h.pattern}" threw:`, e);
+      }
+
+      if (ctx.handled) {
+        claimed = true;
+        break;
+      }
+    }
+
+    // Wildcards run only if NO concrete handler matched (not even a built-in).
+    if (!matched && !claimed) {
+      for (const h of wild) {
+        const ctx = {
+          url,
+          scheme:  parsed.scheme,
+          route:   parsed.route,
+          pattern: '*',
+          params:  {},
+          query:   parsed.query,
+          source,
+          argv:    env?.argv || process.argv,
+          cwd:     env?.cwd  || process.cwd(),
+          handled: false,
+        };
+        try { h.fn(ctx); }
+        catch (e) { logger.error('wildcard handler threw:', e); }
+      }
+    }
+  },
+
+  // Public API ──────────────────────────────────────────────────────────────────
+
+  on(pattern, fn) {
+    if (typeof pattern !== 'string' || !pattern) {
+      throw new Error('deepLink.on: pattern must be a non-empty string');
+    }
+    if (typeof fn !== 'function') {
+      throw new Error('deepLink.on: fn must be a function');
+    }
+    deepLink._handlers.push({ pattern, fn, builtin: false });
+    return () => deepLink.off(pattern, fn);
+  },
+
+  off(pattern, fn) {
+    deepLink._handlers = deepLink._handlers.filter((h) => !(h.pattern === pattern && h.fn === fn));
+  },
+
+  dispatch(url) {
+    deepLink._handle(url, 'manual', { argv: process.argv, cwd: process.cwd() });
+  },
+
+  getColdStartUrl() {
+    return deepLink._coldStartUrl;
+  },
+
+  // Inspection (used by tests).
+  getHandlers() {
+    return deepLink._handlers.slice();
+  },
+};
+
+module.exports = deepLink;