@omega.js/desktop 0.1.0

package/dist/test/harness/renderer-preload.js

@@ -0,0 +1,310 @@
+// Renderer test-harness preload. Bridges between the harness BrowserWindow and the parent
+// main-process harness via two channels:
+//
+//   __emTest:ready   — renderer signals it's ready to receive suites
+//   __emTest:result  — renderer emits per-test results / suite-start / fatal
+//   __emTest:suites  — main sends serialized renderer suites for execution
+//
+// Also exposes the production-style `window.desktop` surface (mirrors src/preload.js so renderer
+// test suites can assert on it).
+
+const { contextBridge, ipcRenderer } = require('electron');
+
+// Mirror the production preload's forwarding logger so renderer-layer tests can
+// verify that logger.log/warn/error actually emits 'desktop:log:forward' to main.
+// Kept minimal — same channel name as production (src/preload.js).
+function makeForwardingLogger() {
+  const FORWARD_CHANNEL = 'desktop:log:forward';
+  const methods = ['log', 'info', 'warn', 'error', 'debug'];
+  const out = {};
+  for (const m of methods) {
+    const fileLevel = m === 'log' ? 'info' : m;
+    out[m] = function () {
+      const args = ['[em]', ...Array.from(arguments)];
+      const fn = console[m] || console.log;
+      try { fn.apply(console, args); } catch (_) { /* ignore */ }
+      try {
+        ipcRenderer.send(FORWARD_CHANNEL, {
+          name:  'renderer',
+          level: fileLevel,
+          args:  Array.from(arguments).map((a) => {
+            if (a instanceof Error) return { __error: true, message: a.message, stack: a.stack };
+            try { JSON.stringify(a); return a; } catch (_) { return String(a); }
+          }),
+        });
+      } catch (_) { /* ignore */ }
+    };
+  }
+  return out;
+}
+
+contextBridge.exposeInMainWorld('__emTest', {
+  // Signal main that the harness page is loaded and ready to accept suites.
+  ready: () => ipcRenderer.send('__emTest:ready'),
+  // Forward a result event up to main, which prints it.
+  emit:  (evt) => ipcRenderer.send('__emTest:result', evt),
+  // Subscribe to incoming suite payloads.
+  onSuites: (handler) => {
+    ipcRenderer.on('__emTest:suites', (_e, suites) => handler(suites));
+  },
+});
+
+// Expose a thin bridge to the actual renderer Manager so renderer-layer tests can
+// assert on its cross-context helpers (isDevelopment / isProduction / isTesting /
+// getVersion / getEnvironment / getApiUrl / getFunctionsUrl / getWebsiteUrl). We
+// instantiate the renderer Manager here in the preload (before contextIsolation
+// closes off `require`) and forward each helper as a sync contextBridge function.
+// We deliberately do NOT call `manager.initialize()` — that touches @omega.js/client /
+// firebase / IPC, which is heavy + flaky for a helper-shape assertion. Instead we
+// stub `manager.config` from a built-time-injected blob so config-dependent
+// helpers (getEnvironment fallback, getWebsiteUrl prod path) have something to read.
+let testManager;
+try {
+  // The renderer test harness loads the renderer Manager by absolute dist path
+  // injected by the boot harness. In its absence, fall back to require-by-name
+  // (works when the harness is run from a consumer with @omega.js/desktop in node_modules).
+  const RendererManager = process.env.OMEGA_TEST_RENDERER_MANAGER_PATH
+    ? require(process.env.OMEGA_TEST_RENDERER_MANAGER_PATH)
+    : require('@omega.js/desktop/renderer');
+  testManager = new RendererManager();
+  // Seed config so getApiUrl / getFunctionsUrl / getWebsiteUrl have something to
+  // read in their prod branches. Tests can mutate this via __emTestManager.config.set().
+  testManager.config = {
+    em:    { environment: 'production' },
+    brand: { url: 'https://example.com' },
+    cloud: { provider: 'firebase', config: { projectId: 'demo-app', authDomain: 'demo-app.firebaseapp.com' } },
+  };
+} catch (e) {
+  console.warn('[renderer-preload] Could not instantiate renderer Manager for tests:', e.message);
+}
+
+// Wire the renderer Manager's DOM enhancements (FontAwesome auto-render +
+// Bootstrap tooltip auto-init) against THIS document. In production these run
+// in the page world (the consumer's esbuild bundle); here the preload world
+// stands in — the DOM is shared, so injected SVGs / tooltip tips are visible
+// to page-world test suites. The Manager reads `window.desktop.ipc` which only
+// exists in the page world, so hand it the preload's ipcRenderer directly.
+try {
+  if (testManager) {
+    testManager.ipc = {
+      invoke: (channel, payload) => ipcRenderer.invoke(channel, payload),
+    };
+    testManager._wireFontAwesome();
+    testManager._wireTooltips();
+  }
+} catch (e) {
+  console.warn('[renderer-preload] Could not wire DOM enhancements:', e.message);
+}
+
+
+// Mirror the production preload surface so renderer test suites can assert against it.
+const desktopSurface = {
+  ipc: {
+    invoke: (channel, payload) => ipcRenderer.invoke(channel, payload),
+    // Mirror production preload (wave-5 F4): returns an unsubscribe fn.
+    on: (channel, handler) => {
+      const wrapped = (_, payload) => handler(payload);
+      ipcRenderer.on(channel, wrapped);
+      return () => ipcRenderer.removeListener(channel, wrapped);
+    },
+    send: (channel, payload) => ipcRenderer.send(channel, payload),
+  },
+  storage: {
+    get:    (key, def) => ipcRenderer.invoke('desktop:storage:get',    { key, def }),
+    set:    (key, val) => ipcRenderer.invoke('desktop:storage:set',    { key, val }),
+    delete: (key)      => ipcRenderer.invoke('desktop:storage:delete', { key }),
+    has:    (key)      => ipcRenderer.invoke('desktop:storage:has',    { key }),
+    clear:  ()         => ipcRenderer.invoke('desktop:storage:clear'),
+    // Mirror production preload's onChange so renderer-layer tests can verify
+    // change-broadcasts round-trip across IPC.
+    onChange: (key, handler) => {
+      const wrapped = (_, payload) => {
+        if (key === '*' || payload?.key === key) handler(payload);
+      };
+      ipcRenderer.on('desktop:storage:change', wrapped);
+      return () => ipcRenderer.removeListener('desktop:storage:change', wrapped);
+    },
+  },
+  // Mirror production preload's theme surface (get/set via IPC; onChange via
+  // matchMedia — the real mechanism, since themeSource flips prefers-color-scheme).
+  theme: {
+    get: ()       => ipcRenderer.invoke('desktop:theme:get'),
+    set: (source) => ipcRenderer.invoke('desktop:theme:set', { source }),
+    onChange: (handler) => {
+      const media = window.matchMedia('(prefers-color-scheme: dark)');
+      const wrapped = (e) => handler({ resolved: e.matches ? 'dark' : 'light' });
+      media.addEventListener('change', wrapped);
+      return () => media.removeEventListener('change', wrapped);
+    },
+  },
+  // Mirror production preload's fontawesome surface (bundled-icon lookup).
+  fontawesome: {
+    get: (name, style) => ipcRenderer.invoke('desktop:fontawesome:get', { name, style }).then((r) => r?.svg ?? null),
+  },
+  logger: makeForwardingLogger(),
+  autoUpdater: {
+    getStatus:  ()  => ipcRenderer.invoke('desktop:auto-updater:status'),
+    checkNow:   ()  => ipcRenderer.invoke('desktop:auto-updater:check-now'),
+    installNow: ()  => ipcRenderer.invoke('desktop:auto-updater:install-now'),
+    onStatus: (handler) => {
+      const wrapped = (_, payload) => handler(payload);
+      ipcRenderer.on('desktop:auto-updater:status', wrapped);
+      return () => ipcRenderer.removeListener('desktop:auto-updater:status', wrapped);
+    },
+  },
+  // Mirror production preload's analytics/context/usage/remoteConfig so renderer-layer
+  // tests can verify their IPC behavior end-to-end.
+  analytics: {
+    event:             (name, params) => ipcRenderer.send('desktop:analytics:event', { name, params }),
+    pageview:          (path)         => ipcRenderer.send('desktop:analytics:event', { name: 'page_view',   params: path ? { page_path: path } : {} }),
+    screenview:        (screenName)   => ipcRenderer.send('desktop:analytics:event', { name: 'screen_view', params: screenName ? { screen_name: screenName } : {} }),
+    setUserProperties: (props)        => ipcRenderer.send('desktop:analytics:set-user-properties', props),
+    getStatus:         ()             => ipcRenderer.invoke('desktop:analytics:status'),
+  },
+  context: {
+    get: () => ipcRenderer.invoke('desktop:context:get'),
+  },
+  usage: {
+    get: () => ipcRenderer.invoke('desktop:usage:get'),
+  },
+  remoteConfig: {
+    get:        (path) => ipcRenderer.invoke('desktop:remote-config:get', path),
+    refreshNow: ()     => ipcRenderer.invoke('desktop:remote-config:refresh-now'),
+    onUpdate: (handler) => {
+      const wrapped = (_, payload) => handler(payload);
+      ipcRenderer.on('desktop:remote-config:update', wrapped);
+      return () => ipcRenderer.removeListener('desktop:remote-config:update', wrapped);
+    },
+  },
+};
+
+contextBridge.exposeInMainWorld('desktop', desktopSurface);
+
+// Defined ABOVE the client wiring below, which injects `desktopSurface.analytics`
+// as that client's analytics bridge ([#411](https://github.com/Omega-JS-Stack/omega/issues/411)):
+// the surface has to exist before the wiring reads it. Observed, not assumed —
+// with this block further down, the wiring resolved nothing.
+
+// Wire the verts auto-bind against THIS document. Production hands the client
+// singleton to _wireAds via manager.initialize(); here the preload requires
+// the REAL @omega.js/client (same resolution _wireFontAwesome uses) and seeds
+// its config directly — full initialize() is deliberately skipped (firebase,
+// heavy). AdSense is INTENTIONALLY configured and no inhouse source is: the
+// house-lane pin is exactly what must keep the provider lane (remote script)
+// from ever being attempted, and a source-less house render collapses
+// deterministically with zero network.
+(async () => {
+  try {
+    if (!testManager) return;
+    // The client is pure ESM — Electron's preload require() can't load it
+    // (unlike the CJS-compatible icon-renderer), so go through the Node ESM
+    // loader. Resolves well before suites arrive from main.
+    const wmMod = await import('@omega.js/client');
+    testManager.omega = wmMod.default || wmMod;
+    testManager.omega.config = Object.assign({}, testManager.omega.config, {
+      advertising: {
+        providers: { adsense: { client: 'ca-pub-test' } },
+      },
+      // The analytics bridge, INJECTED exactly the way src/renderer.js injects
+      // it in production ([#411](https://github.com/Omega-JS-Stack/omega/issues/411)):
+      // the preload's own analytics surface, handed over as config. The client
+      // reads this key and nothing else — no global is involved either side.
+      analyticsBridge: desktopSurface.analytics,
+    });
+    testManager._wireAds();
+
+    // Analytics, BRIDGED: the real client resolves the injected bridge and
+    // forwards every event over IPC to main's ONE sender. Same
+    // `analytics().init()` call `manager.initialize()` makes — the rest of
+    // initialize (firebase, auth) stays out, as everywhere else here.
+    //
+    // Credentials are handed in ON PURPOSE, the mistake desktop's build must
+    // never make: a bridged renderer has to DROP them (`analytics-bridge`
+    // renderer suite pins that it holds neither).
+    testManager.omega.analytics().init({
+      id:        'G-RENDERER1',
+      secret:    'harness-renderer-secret',
+      projectId: 'demo-app',
+      bridge:    testManager.omega._resolveAnalyticsBridge(),
+    });
+  } catch (e) {
+    console.warn('[renderer-preload] Could not wire verts auto-bind:', e.message);
+  }
+})();
+
+// Page-world probe for the bridged client analytics: `event()` is the call a
+// renderer's own code makes (`omega.analytics().event(...)`), `state()` reads
+// back what the module holds so a suite can pin that no second sender exists.
+contextBridge.exposeInMainWorld('__emTestClientAnalytics', {
+  event: (name, params) => testManager?.omega?.analytics().event(name, params),
+  state: () => {
+    const a = testManager?.omega?.analytics();
+    return {
+      initialized: Boolean(a?.initialized),
+      bridged:     Boolean(a?.bridge),
+      secret:      a?.secret ?? null,
+      clientId:    a?.clientId ?? null,
+    };
+  },
+});
+
+// Tooltip instances live in the preload world (page world can't reach the
+// bootstrap namespace across the contextIsolation boundary) — expose a probe so
+// page-world suites can assert instance lifecycle by element id. `error()`
+// surfaces WHY the Bootstrap bundle failed to load (renderer.js swallows the
+// require error into a logger.warn that the harness can't see).
+contextBridge.exposeInMainWorld('__emTestTooltip', {
+  available: () => Boolean(testManager?.bootstrap?.Tooltip),
+  // Lazy — by call time the DOM exists, so a require failure here is the real
+  // reason the bundle can't load (not just "no documentElement yet").
+  error: () => {
+    try {
+      if (process.env.OMEGA_TEST_RENDERER_MANAGER_PATH) {
+        const path = require('path');
+        require(path.join(path.dirname(process.env.OMEGA_TEST_RENDERER_MANAGER_PATH), 'assets', 'js', 'bootstrap.bundle.js'));
+      }
+      return null;
+    } catch (e) {
+      return e.message;
+    }
+  },
+  hasInstance: (id) => {
+    const el = document.getElementById(id);
+    return Boolean(el && testManager?.bootstrap?.Tooltip?.getInstance(el));
+  },
+  // Show the tooltip from the PRELOAD world. Synthetic mouse events dispatched
+  // by page-world test code don't cross the contextIsolation boundary to the
+  // preload world's Bootstrap listeners, so hover can't be simulated from a
+  // suite — real single-world hover behavior is covered by consumer boot
+  // suites. Returns true or the error message.
+  showDirect: (id) => {
+    try {
+      testManager.bootstrap.Tooltip.getOrCreateInstance(document.getElementById(id)).show();
+      return true;
+    } catch (e) {
+      return e.message;
+    }
+  },
+});
+
+contextBridge.exposeInMainWorld('__emTestManager', {
+  isDevelopment:  () => testManager?.isDevelopment(),
+  isProduction:   () => testManager?.isProduction(),
+  isTesting:      () => testManager?.isTesting(),
+  getVersion:     () => testManager?.getVersion(),
+  getEnvironment: () => testManager?.getEnvironment(),
+  getApiUrl:      (env) => testManager?.getApiUrl(env),
+  getFunctionsUrl:(env) => testManager?.getFunctionsUrl(env),
+  getWebsiteUrl:  (env) => testManager?.getWebsiteUrl(env),
+  // Mutator used by tests to flip config flags between assertions.
+  setConfig:      (path, value) => {
+    if (!testManager) return;
+    const parts = path.split('.');
+    let obj = testManager.config;
+    for (let i = 0; i < parts.length - 1; i++) {
+      obj[parts[i]] = obj[parts[i]] || {};
+      obj = obj[parts[i]];
+    }
+    obj[parts[parts.length - 1]] = value;
+  },
+});

package/dist/test/harness/renderer.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>@omega.js/desktop renderer test harness</title>
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self' 'unsafe-eval' 'unsafe-inline'">
+  </head>
+  <body>
+    <pre id="log"></pre>
+    <script src="./renderer-entry.js"></script>
+  </body>
+</html>

package/dist/test/index.js

@@ -0,0 +1,65 @@
+// Public test API — what consumers see.
+//
+// Test files export a test definition. Three forms:
+//
+// Standalone:
+//   module.exports = {
+//     layer: 'build',                  // 'build' | 'main' | 'renderer' | 'boot'
+//     description: 'config has brand.id',
+//     timeout: 5000,
+//     run: async (ctx) => {
+//       const cfg = Manager.getConfig();
+//       ctx.expect(cfg.brand.id).toBeTruthy();
+//     },
+//     cleanup: async (ctx) => { ... },
+//   };
+//
+// Boot layer — spawns the consumer's actual built main bundle (dist/main.bundle.js)
+// and runs `inspect` against the live manager. Replaces shell-level `npm start && sleep && kill`
+// smoke tests with deterministic, signal-driven pass/fail. Use this to verify the WHOLE
+// integration: consumer scaffolds, brand config, custom integrations, real boot order.
+//
+//   module.exports = {
+//     layer: 'boot',
+//     description: 'tray boots with default items',
+//     timeout: 15000,
+//     inspect: async ({ manager, expect, projectRoot }) => {
+//       expect(manager.tray.has('open')).toBe(true);
+//       expect(manager.tray.has('check-for-updates')).toBe(true);
+//       expect(manager.menu.isRendered()).toBe(true);
+//     },
+//   };
+//
+// Suite (sequential, shared state, stop on first failure):
+//   module.exports = {
+//     type: 'suite',
+//     layer: 'main',
+//     description: 'storage round-trip',
+//     tests: [
+//       { name: 'set value', run: async (ctx) => { ctx.state.key = 'foo'; ctx.manager.storage.set('foo', 'bar'); } },
+//       { name: 'get value', run: async (ctx) => { ctx.expect(ctx.manager.storage.get('foo')).toBe('bar'); } },
+//       { name: 'delete',    run: async (ctx) => { ctx.manager.storage.delete('foo'); } },
+//     ],
+//   };
+//
+// Group (sequential, shared state, runs ALL tests even if some fail):
+//   module.exports = {
+//     type: 'group',
+//     layer: 'build',
+//     tests: [ ... ],
+//   };
+//
+// Array form (treated as group):
+//   module.exports = [ { name, run }, ... ];
+//
+// The ctx (context) provided to every run/cleanup includes:
+//   - ctx.expect       — Jest-compatible assertion library
+//   - ctx.state        — shared object across tests in a suite/group
+//   - ctx.skip(reason) — throw to skip the current test at runtime
+//   - ctx.layer        — current layer name
+//   - ctx.manager      — @omega.js/desktop Manager instance (main layer only — added in 2.3b)
+//   - ctx.page         — BrowserWindow page (renderer layer only — added in 2.3c)
+
+module.exports = {
+  expect: require('./assert.js'),
+};

package/dist/test/runner.js

@@ -0,0 +1,99 @@
+// Test runner — discovers + runs suites, reports framework-style.
+//
+// The runner CORE (discovery, suite/group/standalone execution, filtering, skip
+// semantics, init hooks, reporting) is the shared @omega.js/devkit runner-core,
+// vendored into dist/vendor/devkit at prepare time. This file is @omega.js/desktop's config:
+// title, target alias, and the framework-specific layer glue.
+//
+// Layers:
+//   - 'build'    runs in plain Node (runner core).
+//   - 'main'     spawns Electron via runners/electron.js, runs in the main process.
+//   - 'renderer' runs in a hidden BrowserWindow in the same spawned Electron process.
+//   - 'boot'     spawns the consumer's actual built bundle and inspects the live manager.
+//
+// Electron / boot runners are lazy-loaded so a missing electron doesn't prevent build-layer
+// tests from running. The layer callbacks below require() them only when those layers exist.
+
+const path = require('path');
+const chalk = require('chalk').default;
+
+const { createRunner, SkipError, DISCOVERY_IGNORE } = require('../vendor/devkit/test/runner-core.js');
+const { FRAMEWORK_IDS } = require('../vendor/devkit/test/scope.js');
+
+const runner = createRunner({
+  title: 'OMEGA Desktop Tests',
+  packageName: '@omega.js/desktop',
+  targetAlias: 'desktop',
+  frameworkAliases: FRAMEWORK_IDS['@omega.js/desktop'],
+  suitesDir: path.join(__dirname, 'suites'),
+  frameworkTestDir: path.resolve(__dirname, '../../test'),
+  bootDefaultTimeout: 15000,
+
+  // A renderer suite that names a project view rides the BOOT lane instead of the harness
+  // page: only the boot runner stages and builds the real app, and the view needs that
+  // build (its own preload, its own IPC handlers, its own config). The runner core hands
+  // such a file to boot.run whole, as `suites`, never flattened into the inspect list.
+  bootBound: (mod) => mod.layer === 'renderer' && typeof mod.view === 'string',
+
+  middleLayers: [
+    {
+      // Main + renderer share one spawned Electron process — main suites first, then a
+      // hidden BrowserWindow takes over for renderer suites. This keeps a single
+      // electron boot per `npx omega test` invocation.
+      layers: ['main', 'renderer'],
+      run: async ({ byLayer, wants, options, results, projectRoot }) => {
+        let runElectronTests;
+        try {
+          ({ runElectronTests } = require('./runners/electron.js'));
+        } catch (e) {
+          console.log(chalk.yellow(`    ○ main + renderer tests skipped (electron runner not available: ${e.message})`));
+          const skipCount = (wants.main ? byLayer.main.length : 0)
+            + (wants.renderer ? byLayer.renderer.length : 0);
+          results.skipped += skipCount;
+        }
+        if (runElectronTests) {
+          const counts = await runElectronTests({
+            harnessEntry: path.join(__dirname, 'harness', 'main-entry.js'),
+            suiteFiles:         wants.main     ? byLayer.main     : [],
+            rendererSuiteFiles: wants.renderer ? byLayer.renderer : [],
+            filter: options.filter,
+            projectRoot,
+          });
+          results.passed  += counts.passed;
+          results.failed  += counts.failed;
+          results.skipped += counts.skipped;
+        }
+      },
+    },
+  ],
+
+  boot: {
+    // Spawn the consumer's actual built bundle and inspect the live manager (the core
+    // aggregates boot tests into the flat `tests` list). `suites` are the boot-bound
+    // renderer suites (`view: '<name>'`), which run in a real window of that same app.
+    run: async ({ tests, suites, results, projectRoot }) => {
+      let runBootTests;
+      try {
+        ({ runBootTests } = require('./runners/boot.js'));
+      } catch (e) {
+        console.log(chalk.yellow(`    ○ boot tests skipped (boot runner not available: ${e.message})`));
+        results.skipped += tests.length + suites.reduce((n, s) => n + (s.mod.tests || []).length, 0);
+        return;
+      }
+
+      console.log(chalk.cyan('    ⤷ boot tests (consumer bundle)'));
+
+      const counts = await runBootTests({
+        tests,
+        suites,
+        projectRoot,
+        frameworkDistRoot: path.resolve(__dirname, '..'),
+      });
+      results.passed  += counts.passed;
+      results.failed  += counts.failed;
+      results.skipped += counts.skipped;
+    },
+  },
+});
+
+module.exports = { run: runner.run, SkipError, DISCOVERY_IGNORE };