@omega.js/desktop 0.1.0

package/dist/lib/fontawesome.js

@@ -0,0 +1,203 @@
+// FontAwesome — the Font Awesome icon server: resolves icons from the
+// brand's best available icon set and serves them to renderers on demand,
+// so consumers get icons with ZERO setup. Roots, best-first (cp111):
+//
+//   1. OMEGA_FONTAWESOME_ROOT — a fontawesome.com download dir
+//      (contains svgs/ + metadata/); no npm token needed.
+//   2. @fortawesome/fontawesome-pro — installed by the BRAND target with its
+//      own FA npm token (a prod dependency there, so it ships in the asar).
+//      Never a dependency of @omega.js/desktop itself — license.
+//   3. @fortawesome/fontawesome-free — the declared-dependency floor
+//      (nothing vendored). Stays in the chain under a brand set, so a
+//      partial Pro supply never loses icons the free set has.
+//
+// Main-side API:
+//   manager.fontawesome.get(name, style)  → svg string | null   ('play', 'solid')
+//   manager.fontawesome.has(name, style)  → boolean
+//
+// Renderer-side (preload contextBridge):
+//   window.desktop.fontawesome.get(name, style) → Promise<svg string | null>
+//
+// Renderers normally never call this directly — @omega.js/desktop's renderer
+// bootstrap auto-renders any `<i class="fa-solid fa-play">` element by
+// injecting the SVG inline (see src/renderer.js _wireFontAwesome). Served
+// SVGs size to the surrounding font and inherit its color — no icon font,
+// no CSS framework, works offline (fs reads through asar transparently in
+// packaged apps).
+//
+// Icon SEMANTICS (valid names/styles, candidate order incl. the brands
+// fallback, the injected root attributes, alias mapping) live in
+// @omega.js/client's icon-core (C4 cp108) — the SAME module web's
+// build-time inlining pass uses, so lookup rules and rendered markup can
+// never drift between the surfaces. Aliases ('search' →
+// 'magnifying-glass') resolve through fontawesome-free's own metadata.
+//
+// Lookups are sanitized (lowercase slug names, path-safe style slugs) so
+// the IPC channel can never be used to read outside the icon directories,
+// and cached — each icon file is read from disk once per app run.
+
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const {
+  PACKAGES,
+  isValidIconName,
+  isValidStyle,
+  injectSvgAttributes,
+  candidateRelPaths,
+  buildAliasMap,
+} = require('@omega.js/client/modules/icon-core.js');
+
+const LoggerLite = require('./logger-lite.js');
+const ipc = require('./ipc.js');
+
+const logger = new LoggerLite('fontawesome');
+
+const fontawesome = {
+  _initialized: false,
+  _manager: null,
+  _roots: [],
+  _aliasMap: null,
+  _cache: new Map(),
+
+  initialize(manager) {
+    if (fontawesome._initialized) {
+      return;
+    }
+
+    fontawesome._manager = manager;
+    fontawesome._roots = fontawesome._resolveRoots();
+
+    fontawesome._registerIpc();
+
+    fontawesome._initialized = true;
+  },
+
+  // The icon package roots ({svgs,metadata} live under each), best-first:
+  // OMEGA_FONTAWESOME_ROOT dir → Pro npm install → the free floor (a
+  // declared runtime dependency, so it resolves in dev and inside a
+  // packaged app.asar alike). Preference order is icon-core's PACKAGES —
+  // the same chain web builds use.
+  _resolveRoots() {
+    const roots = [];
+
+    const envRoot = process.env.OMEGA_FONTAWESOME_ROOT;
+    if (envRoot) {
+      if (jetpack.exists(path.join(envRoot, 'svgs')) === 'dir') {
+        logger.log(`brand icon set active — OMEGA_FONTAWESOME_ROOT=${envRoot}`);
+        roots.push(envRoot);
+      } else {
+        logger.warn(`OMEGA_FONTAWESOME_ROOT has no svgs/ dir — ignored (${envRoot}).`);
+      }
+    }
+
+    for (const pkg of PACKAGES) {
+      try {
+        const root = path.dirname(require.resolve(`${pkg}/package.json`));
+        if (roots.length === 0 && pkg === PACKAGES[0]) {
+          logger.log('Font Awesome Pro npm set active.');
+        }
+        roots.push(root);
+      } catch (e) {
+        // Pro is brand-supplied and usually absent; a missing FREE set is
+        // a real problem.
+        if (pkg === PACKAGES[PACKAGES.length - 1]) {
+          logger.warn(`${pkg} not resolvable — icon lookups may return null.`);
+        }
+      }
+    }
+
+    if (roots.length === 0) {
+      logger.warn('no Font Awesome set resolvable — icon lookups will return null.');
+    }
+    return roots;
+  },
+
+  _registerIpc() {
+    if (!ipc._initialized) {
+      return;
+    }
+
+    ipc.handle('desktop:fontawesome:get', ({ name, style } = {}) => ({
+      svg: fontawesome.get(name, style),
+    }));
+  },
+
+  // Resolve an icon to its inline-SVG string ('play' → '<svg …>…</svg>').
+  // Unknown names, invalid slugs, and unknown styles all return null — a
+  // missing icon is a content problem, not a crash.
+  get(name, style = 'solid') {
+    if (!isValidIconName(name) || !isValidStyle(style)) {
+      return null;
+    }
+
+    const key = `${style}/${name}`;
+    if (fontawesome._cache.has(key)) {
+      return fontawesome._cache.get(key);
+    }
+
+    const svg = fontawesome._read(name, style)
+      || fontawesome._read(fontawesome._alias(name), style);
+    if (!svg) {
+      logger.warn(`unknown icon '${key}'.`);
+    }
+
+    fontawesome._cache.set(key, svg);
+    return svg;
+  },
+
+  has(name, style = 'solid') {
+    return fontawesome.get(name, style) !== null;
+  },
+
+  // Read one icon through icon-core's candidate order (style dir, then the
+  // brands fallback), across the root chain best-first. Null name (no
+  // alias) or no resolved roots → null.
+  _read(name, style) {
+    if (!name) {
+      return null;
+    }
+    for (const root of fontawesome._roots) {
+      for (const rel of candidateRelPaths(name, style)) {
+        const raw = jetpack.read(path.join(root, 'svgs', rel), 'utf8');
+        if (raw) {
+          return injectSvgAttributes(raw);
+        }
+      }
+    }
+    return null;
+  },
+
+  // Alias slug → canonical slug from the richest metadata in the root
+  // chain, built once per app run ('search' → 'magnifying-glass').
+  _alias(name) {
+    if (!fontawesome._aliasMap) {
+      let map = new Map();
+      for (const root of fontawesome._roots) {
+        const raw = jetpack.read(path.join(root, 'metadata', 'icon-families.json'), 'utf8');
+        if (!raw) {
+          continue;
+        }
+        try {
+          map = buildAliasMap(JSON.parse(raw));
+        } catch (e) {
+          logger.warn('could not parse icon-families.json — aliases disabled.');
+        }
+        break;
+      }
+      fontawesome._aliasMap = map;
+    }
+    return fontawesome._aliasMap.get(name) || null;
+  },
+
+  // Tear down IPC + caches (idempotent).
+  disable() {
+    if (ipc._initialized) {
+      ipc.unhandle('desktop:fontawesome:get');
+    }
+    fontawesome._cache.clear();
+    fontawesome._aliasMap = null;
+    fontawesome._initialized = false;
+  },
+};
+
+module.exports = fontawesome;

package/dist/lib/ipc.js

@@ -0,0 +1,169 @@
+// IPC — typed channel bus for main ↔ renderer communication.
+//
+// Main-side API:
+//   ipc.handle(channel, async (payload, evt) => result)   // request/response (renderer → main)
+//   ipc.unhandle(channel)
+//   ipc.on(channel, (payload, evt) => void)               // one-way subscribe (renderer → main)
+//   ipc.off(channel, fn)
+//   ipc.invoke(channel, payload)                          // main-side: call a registered handler locally
+//   ipc.broadcast(channel, payload)                       // main → all renderers
+//   ipc.send(webContents, channel, payload)               // main → one renderer
+//
+// Renderer-side (via preload contextBridge as `window.desktop.ipc`):
+//   window.desktop.ipc.invoke(channel, payload)                // → Promise<result>
+//   window.desktop.ipc.on(channel, fn)                         // returns unsubscribe fn
+//   window.desktop.ipc.send(channel, payload)                  // fire-and-forget renderer → main
+//
+// All framework-internal channels are prefixed `desktop:` (e.g. `desktop:storage:get`);
+// the test harness keeps its own `desktop:__test:*` channels (parked internals, like EM_* env vars).
+// Consumers can register their own channels under any namespace they want.
+
+const LoggerLite = require('./logger-lite.js');
+
+const logger = new LoggerLite('ipc');
+
+const ipc = {
+  _initialized: false,
+  _manager:     null,
+  _handlers:    {}, // channel -> handler fn
+  _listeners:   {}, // channel -> Set<fn>
+  _ipcMain:     null,
+  _electron:    null,
+
+  initialize(manager) {
+    if (ipc._initialized) {
+      return;
+    }
+
+    ipc._manager = manager;
+    ipc._electron = require('electron');
+    ipc._ipcMain = ipc._electron.ipcMain;
+    // No ipcMain in renderer/preload — those contexts use ipcRenderer instead.
+    // We're a main-side bus; bail in non-main contexts.
+    if (!ipc._ipcMain) {
+      logger.warn('ipc: ipcMain not available — running in test/no-op mode (renderer or non-Electron context)');
+      ipc._initialized = true;
+      return;
+    }
+
+    if (!ipc._ipcMain) {
+      logger.warn('ipcMain not available — ipc running in no-op mode.');
+      ipc._initialized = true;
+      return;
+    }
+
+    logger.log('initialize');
+    ipc._initialized = true;
+  },
+
+  // Register a request/response handler. Throws on duplicate registration.
+  handle(channel, handler) {
+    if (typeof channel !== 'string' || !channel) {
+      throw new Error('ipc.handle: channel must be a non-empty string');
+    }
+    if (typeof handler !== 'function') {
+      throw new Error('ipc.handle: handler must be a function');
+    }
+    if (ipc._handlers[channel]) {
+      throw new Error(`ipc.handle: channel "${channel}" already has a handler. Call ipc.unhandle() first.`);
+    }
+
+    ipc._handlers[channel] = handler;
+
+    if (ipc._ipcMain) {
+      ipc._ipcMain.handle(channel, async (evt, payload) => {
+        try {
+          return await handler(payload, evt);
+        } catch (e) {
+          logger.error(`handler for "${channel}" threw:`, e);
+          throw e; // propagate to renderer's invoke() promise
+        }
+      });
+    }
+  },
+
+  unhandle(channel) {
+    delete ipc._handlers[channel];
+    if (ipc._ipcMain) {
+      ipc._ipcMain.removeHandler(channel);
+    }
+  },
+
+  // Main-side direct invoke — calls the locally registered handler without going through electron's IPC.
+  // Used by other libs and by tests; the renderer goes through ipcRenderer.invoke.
+  async invoke(channel, payload) {
+    const handler = ipc._handlers[channel];
+    if (!handler) {
+      throw new Error(`ipc.invoke: no handler registered for "${channel}"`);
+    }
+    return handler(payload, null);
+  },
+
+  // Subscribe to one-way messages from renderers (renderer → main, no response).
+  on(channel, fn) {
+    if (!ipc._listeners[channel]) {
+      ipc._listeners[channel] = new Set();
+      if (ipc._ipcMain) {
+        ipc._ipcMain.on(channel, (evt, payload) => {
+          const set = ipc._listeners[channel];
+          if (!set) return;
+          set.forEach((sub) => {
+            try {
+              sub(payload, evt);
+            } catch (e) {
+              logger.error(`listener for "${channel}" threw:`, e);
+            }
+          });
+        });
+      }
+    }
+    ipc._listeners[channel].add(fn);
+
+    return () => ipc.off(channel, fn);
+  },
+
+  off(channel, fn) {
+    const set = ipc._listeners[channel];
+    if (!set) return;
+    set.delete(fn);
+    if (set.size === 0) {
+      delete ipc._listeners[channel];
+      if (ipc._ipcMain) {
+        ipc._ipcMain.removeAllListeners(channel);
+      }
+    }
+  },
+
+  // Broadcast to every BrowserWindow's webContents.
+  broadcast(channel, payload) {
+    if (!ipc._electron) return;
+    const { BrowserWindow } = ipc._electron;
+    if (!BrowserWindow) return;
+
+    BrowserWindow.getAllWindows().forEach((win) => {
+      if (win.isDestroyed()) return;
+      try {
+        win.webContents.send(channel, payload);
+      } catch (e) {
+        // window closing — ignore
+      }
+    });
+  },
+
+  // Send to a specific renderer's webContents.
+  send(webContents, channel, payload) {
+    if (!webContents || webContents.isDestroyed()) return;
+    webContents.send(channel, payload);
+  },
+
+  // Test/inspection helpers
+  hasHandler(channel) {
+    return Boolean(ipc._handlers[channel]);
+  },
+
+  listenerCount(channel) {
+    return ipc._listeners[channel]?.size || 0;
+  },
+};
+
+module.exports = ipc;

package/dist/lib/logger-lite.js

@@ -0,0 +1,259 @@
+// Runtime-side logger. Prints the ONE identity tag, `[@omega.js/desktop:<name>]`,
+// with NO timestamp on the console — devtools stamps renderer lines and the file
+// transport carries its own timestamp
+// ([#12](https://github.com/Omega-JS-Stack/omega/issues/12)).
+//
+// Same per-name `new LoggerLite('foo')` API the rest of @omega.js/desktop has always used. Adds a
+// file transport when running inside Electron (main process) so consumers can read
+// runtime logs from disk without remoting into the running app.
+//
+// File location:
+//   - Dev (app.isPackaged === false)  : <projectRoot>/logs/runtime.log
+//   - Prod (app.isPackaged === true)  : app.getPath('logs')/runtime.log
+//                                        i.e. ~/Library/Logs/<AppName>/runtime.log on macOS,
+//                                             %APPDATA%\<AppName>\logs\runtime.log on Windows,
+//                                             ~/.config/<AppName>/logs/runtime.log on Linux.
+//
+// Renderer / preload don't have direct file access — they emit logs via IPC to main,
+// which writes them through the same single file transport. So all logs (main +
+// renderer + preload) converge in one file, ordered by arrival.
+//
+// Outside Electron entirely (e.g. when build/CLI code requires this module — should
+// be rare; build/CLI use `lib/logger.js` instead) it falls back to console-only.
+
+// The package segment of the identity tag — this file IS @omega.js/desktop.
+const PACKAGE = '@omega.js/desktop';
+
+// Channel used by renderer/preload to forward log calls to main. Public for the
+// preload contextBridge to attach to.
+const FORWARD_CHANNEL = 'desktop:log:forward';
+
+// Detect context. In renderer bundles (target: 'web'), Node modules like 'electron'
+// don't exist — all detection returns false, and the logger becomes console-only +
+// IPC forwarding to main. No top-level `require('electron')` — that would get bundled
+// by esbuild and crash in the browser-like renderer context.
+//
+// We lazy-load Node modules (path, fs, electron, electron-log) inside the functions
+// that actually need them (ensureMainFileTransport, tryForwardToMain) so esbuild's
+// renderer bundle never sees them.
+const _isBrowser = typeof window !== 'undefined' && typeof require === 'undefined';
+let _electron = null;
+let _isElectron = false;
+let _isMain = false;
+
+if (!_isBrowser) {
+  try {
+    _electron = require('electron');
+    _isElectron = !!(_electron && typeof _electron === 'object');
+    _isMain = !!(_isElectron && _electron.app && typeof _electron.app.getPath === 'function');
+  } catch (_) {
+    // Not in an Electron context (plain Node CLI, etc.)
+  }
+}
+
+// Public aliases for backward compat (exposed via _internals).
+const isElectron = _isElectron;
+const isMain = _isMain;
+
+// Cache the resolved electron-log module + its file transport's path so we can
+// expose `getLogFilePath()` synchronously without re-resolving.
+let _electronLog = null;
+let _logFilePath = null;
+let _initAttempted = false;
+
+// Attempt to wire up the file transport. Lazy + idempotent — first log() call from
+// main triggers init. Renderer skips this entirely.
+function ensureMainFileTransport() {
+  if (_initAttempted) return;
+  _initAttempted = true;
+
+  if (!_isMain) return;
+
+  let log;
+  try {
+    log = require('electron-log/main');
+  } catch (e) {
+    return;
+  }
+
+  // Lazy-load Node modules — only runs in main process, never bundled into renderer.
+  const path = require('path');
+  const fs   = require('fs');
+  const { app } = _electron;
+
+  // Resolve the target log file path based on packaged state. See module header.
+  const isPackaged = app.isPackaged === true;
+  let logsDir;
+  if (isPackaged) {
+    // Standard Electron user-data location. app.getPath('logs') resolves per-OS:
+    // mac:   ~/Library/Logs/<AppName>
+    // win:   %APPDATA%\<AppName>\logs
+    // linux: ~/.config/<AppName>/logs
+    logsDir = app.getPath('logs');
+  } else {
+    // In dev, write to the consumer project's logs/ dir alongside dev.log + build.log.
+    // process.cwd() is the consumer project root when launched via `npm start`.
+    logsDir = path.join(process.cwd(), 'logs');
+  }
+
+  try {
+    fs.mkdirSync(logsDir, { recursive: true });
+  } catch (e) {
+    // If we can't even create the dir, electron-log uses its default path internally.
+  }
+
+  _logFilePath = path.join(logsDir, 'runtime.log');
+
+  // Configure electron-log:
+  //   - file transport writes to runtime.log (resolved above)
+  //   - console transport keeps existing stderr/stdout output during dev
+  //   - log level: 'silly' captures everything; consumers can dial down via env
+  log.transports.file.resolvePathFn = () => _logFilePath;
+  log.transports.file.level = process.env.OMEGA_LOG_LEVEL_FILE || 'silly';
+  log.transports.console.level = process.env.OMEGA_LOG_LEVEL_CONSOLE || 'silly';
+  log.transports.file.maxSize = 10 * 1024 * 1024; // 10 MB → rotates to runtime.old.log
+
+  // Time format: 24-hour HH:MM:SS.ms — readable + grep-friendly. electron-log
+  // accepts moment-style tokens; this matches what we already print interactively.
+  log.transports.file.format    = '[{y}-{m}-{d} {h}:{i}:{s}.{ms}] [{level}] {scope} {text}';
+  log.transports.console.format = '[{h}:{i}:{s}.{ms}] [{level}] {scope} {text}';
+
+  // Listen for renderer/preload log forwards. The preload-side LoggerLite sends an
+  // `desktop:log:forward` message and we replay it through the same transport, so all
+  // logs (main + renderer + preload) end up in one file with one timestamp source.
+  if (_electron.ipcMain && typeof _electron.ipcMain.on === 'function') {
+    _electron.ipcMain.on(FORWARD_CHANNEL, (event, payload) => {
+      // payload = { name, level, args }
+      try {
+        if (!payload || typeof payload !== 'object') return;
+        const scoped = log.scope(String(payload.name || 'renderer'));
+        const method = scoped[payload.level] || scoped.info;
+        method.apply(scoped, Array.isArray(payload.args) ? payload.args : [String(payload.args)]);
+      } catch (e) {
+        // Don't let renderer log forwards crash main.
+      }
+    });
+  }
+
+  _electronLog = log;
+}
+
+// Renderer/preload-side: attempt to forward to main. Returns true if the IPC channel
+// was reachable, false otherwise (caller falls back to plain console).
+//
+// Two paths to reach main:
+//   1. Direct ipcRenderer access (preload, or renderer with contextIsolation off).
+//   2. Via window.desktop.ipc.send (renderer with contextIsolation on — preload exposes
+//      a contextBridge surface that proxies to ipcRenderer).
+// We try both; whichever works first wins.
+function tryForwardToMain(name, level, args) {
+  // Path 1: direct.
+  if (_electron) {
+    try {
+      if (_electron.ipcRenderer && typeof _electron.ipcRenderer.send === 'function') {
+        _electron.ipcRenderer.send(FORWARD_CHANNEL, { name, level, args: serializeArgs(args) });
+        return true;
+      }
+    } catch (e) {
+      // contextIsolation / sandbox can block ipcRenderer access in some configs.
+    }
+  }
+  // Path 2: contextBridge-exposed window.desktop.ipc.send (renderer in isolated context).
+  try {
+    if (typeof window !== 'undefined' && window.desktop && window.desktop.ipc && typeof window.desktop.ipc.send === 'function') {
+      window.desktop.ipc.send(FORWARD_CHANNEL, { name, level, args: serializeArgs(args) });
+      return true;
+    }
+  } catch (e) {
+    // ignore
+  }
+  return false;
+}
+
+// IPC message values must be structured-cloneable. Errors and circular refs aren't,
+// so flatten them aggressively before sending. This is a "best-effort" stringify —
+// the source-of-truth is still in the renderer's console for live debugging; the
+// file is for post-mortem.
+function serializeArgs(args) {
+  return Array.from(args).map((a) => {
+    if (a instanceof Error) return { __error: true, name: a.name, message: a.message, stack: a.stack };
+    if (a === undefined)    return { __undefined: true };
+    if (a === null)         return null;
+    if (typeof a === 'function') return `[Function: ${a.name || 'anonymous'}]`;
+    try {
+      // Round-trip through JSON to drop circulars / non-serializable bits.
+      return JSON.parse(JSON.stringify(a));
+    } catch (e) {
+      return String(a);
+    }
+  });
+}
+
+// Main constructor — same shape consumers have always used.
+function Logger(name) {
+  const self = this;
+  self.name = name;
+}
+
+['log', 'error', 'warn', 'info', 'debug'].forEach((method) => {
+  // electron-log's level naming: log/info/warn/error/debug/silly/verbose. Map our
+  // 'log' to 'info' on the file transport (electron-log treats them equivalently
+  // but 'info' is the canonical key).
+  const fileLevel = method === 'log' ? 'info' : method;
+
+  Logger.prototype[method] = function () {
+    const self = this;
+
+    // 1. Always write to console (dev visibility). The ONE identity tag, no
+    //    timestamp — devtools/electron-log stamp runtime lines themselves (#12).
+    const consoleArgs = [`[${PACKAGE}:${self.name}]`, ...Array.from(arguments)];
+    if (typeof console[method] === 'function') {
+      console[method].apply(console, consoleArgs);
+    } else {
+      console.log.apply(console, consoleArgs);
+    }
+
+    // 2. Branch based on process role:
+    if (isMain) {
+      // In main: lazily set up file transport, then write through it.
+      ensureMainFileTransport();
+      if (_electronLog) {
+        const scoped = _electronLog.scope(self.name);
+        const fn = scoped[fileLevel] || scoped.info;
+        try {
+          fn.apply(scoped, Array.from(arguments));
+        } catch (e) {
+          // Never let logging itself throw.
+        }
+      }
+    } else {
+      // In renderer/preload: forward to main. If forwarding fails, the console
+      // call above is the fallback (no file write).
+      tryForwardToMain(self.name, fileLevel, arguments);
+    }
+  };
+});
+
+// Public helper for tools that want to know where the file lives (e.g. `mgr logs`,
+// or app code that wants to surface "send us your log" to users). Returns null
+// before the file transport is set up (which only happens in main process).
+Logger.getLogFilePath = function () {
+  // Trigger init if we haven't yet — caller may invoke this before any log() call.
+  ensureMainFileTransport();
+  return _logFilePath;
+};
+
+// IPC channel name — exposed for tests + preload's contextBridge wiring.
+Logger.FORWARD_CHANNEL = FORWARD_CHANNEL;
+
+// Internal: exposed for tests so they can drive ensureMainFileTransport directly
+// without simulating Electron startup.
+Logger._internals = {
+  ensureMainFileTransport,
+  serializeArgs,
+  tryForwardToMain,
+  isMain,
+  isElectron,
+};
+
+module.exports = Logger;

package/dist/lib/logger.js

@@ -0,0 +1,4 @@
+// Shared devkit module — vendored into dist/vendor/devkit at prepare time by the
+// preparePackage `after` hook. This shim keeps the framework's internal require
+// paths stable while the implementation lives in @omega.js/devkit.
+module.exports = require('../vendor/devkit/logger.js');