@omega.js/desktop 0.1.0

package/dist/utils/mode-helpers.js

@@ -0,0 +1,147 @@
+// Runtime mode helpers (@omega.js/backend-pattern), shared across all three context Managers
+// (main / renderer / preload) and the build-time Manager.
+//
+// Three MUTUALLY EXCLUSIVE environments — exactly one is true:
+//   isDevelopment() — app run from source / being developed (unpackaged, e.g. `electron .`,
+//                     gulp dev), and NOT testing. Authoritative signal: `app.isPackaged ===
+//                     false`. Falls back to NODE_ENV when `app` isn't available (preload,
+//                     build-time scripts, renderer).
+//   isTesting()     — app being tested (@omega.js/desktop's test framework running this process). Single
+//                     canonical env var: `OMEGA_TEST_MODE=true`. TAKES PRECEDENCE over dev:
+//                     a test run is unpackaged, but it's a TEST, not development.
+//   isProduction()  — app packaged & distributed to users (`app.isPackaged === true`),
+//                     and NOT testing. A real positive check — NOT `!isDevelopment()`.
+//
+// To gate "anything non-production" (skip OS side effects, isolate data) use
+// `!isProduction()` or `isDevelopment() || isTesting()` intentionally — never assume two
+// values.
+//
+// Use these whenever behavior should differ by *what kind of process* you're in —
+// shorter timeouts in tests, DevTools menu items only in dev, prompts suppressed in
+// tests. Don't use them for "should we hit dev or prod backends" — that's a config
+// concern; use `getEnvironment()` for that (in build.js).
+//
+// Renderer caveat: Electron's `app` API isn't available in renderer processes
+// (the renderer's `electron` import surface has `ipcRenderer`, `contextBridge`,
+// etc. — no `app`). Same in preload. So those contexts fall back to NODE_ENV /
+// config.em.environment. To get a renderer-truthful signal, the consumer can have
+// main inject the value into `OMEGA_BUILD_JSON.runtime` at build time (future
+// enhancement); for now, NODE_ENV being inherited from the parent process is the
+// pragmatic answer.
+//
+// In plain Node (gulp tasks, CLI commands), `require('electron')` returns the
+// binary path as a string — no `app` object — so the same `app && typeof
+// app.isPackaged === 'boolean'` check naturally falls through to NODE_ENV.
+
+// The three environment checks are MUTUALLY EXCLUSIVE — exactly one is true:
+//   isDevelopment() — app run from source / being developed (unpackaged, NOT testing).
+//   isTesting()     — app being tested (OMEGA_TEST_MODE=true). Takes precedence over dev.
+//   isProduction()  — app packaged & distributed to users (real positive check, NOT testing).
+// Testing wins first: a test run is unpackaged, but it's a TEST, not development.
+
+// getEnvironment() — the SINGLE SOURCE OF TRUTH. Reads every raw signal and resolves to
+// exactly ONE of 'development' | 'testing' | 'production' (mutually exclusive; testing wins).
+// Precedence: testing → explicit config override → Electron app.isPackaged → build-time signal.
+function getEnvironment() {
+  // 1. Testing wins — set by @omega.js/desktop's test runners (OMEGA_TEST_MODE=true), regardless of packaged state.
+  if (process.env.OMEGA_TEST_MODE === 'true') return 'testing';
+
+  // 2. An explicit config.em.environment override — the consumer's deliberate decision. It beats
+  //    the auto-detected app.isPackaged (e.g. a packaged app the consumer wants to treat as dev).
+  const cfgEnv = this?.config?.em?.environment;
+  if (cfgEnv === 'development' || cfgEnv === 'testing' || cfgEnv === 'production') return cfgEnv;
+
+  // 3. In Electron main, `app.isPackaged` is the authoritative runtime signal (more accurate
+  //    than env vars). In renderer/preload, `electron` has no `app`; from plain Node (gulp/CLI),
+  //    `require('electron')` returns the binary path string — `.app` is undefined in both, so we
+  //    fall through to the build signals below.
+  //    In renderer bundles (target: 'web'), require is not available — skip entirely.
+  if (typeof require !== 'undefined') {
+    try {
+      const { app } = require('electron');
+      if (app && typeof app.isPackaged === 'boolean') return app.isPackaged ? 'production' : 'development';
+    } catch (_) {}
+  }
+
+  // 4. Build-time / Node signals. OMEGA_BUILD_MODE=true is set during a production build
+  //    (npm run build / npm run release); NODE_ENV=development is the dev fallback.
+  if (process.env.OMEGA_BUILD_MODE === 'true') return 'production';
+  if (process.env.NODE_ENV === 'development') return 'development';
+
+  // 5. Default: production. @omega.js/desktop's deployed RUNTIME can reach here without a dev signal — a
+  //    packaged app whose `app.isPackaged` somehow didn't resolve is still a shipped binary,
+  //    so production is the safe assumption for a distributed artifact. (Contrast UJM/BXM,
+  //    whose deployed artifacts always carry their signal, so they default to development —
+  //    a bare context there is just build tooling.)
+  return 'production';
+}
+
+// The three checks DERIVE from getEnvironment() — they never read raw signals, so they can
+// never disagree with it. isDevelopment() is NOT true in testing; isProduction() is a real
+// positive check (never `!isDevelopment()`).
+function isDevelopment() {
+  return getEnvironment.call(this) === 'development';
+}
+
+function isProduction() {
+  return getEnvironment.call(this) === 'production';
+}
+
+function isTesting() {
+  return getEnvironment.call(this) === 'testing';
+}
+
+// `getVersion()` — returns the app's version string. Sources, in priority order:
+//   1. `electron.app.getVersion()` when running inside Electron (main process —
+//      authoritative; reads from the packaged app's package.json baked into asar).
+//   2. `<cwd>/package.json#version` for build-time scripts / non-Electron contexts.
+//   3. null when neither resolves.
+//
+// Renderer caveat: same as isDevelopment — `electron.app` isn't available in renderer,
+// so the fallback to `process.cwd()/package.json` won't find anything useful in a
+// packaged app. Renderers that need the version should ask main via IPC, or read
+// `OMEGA_BUILD_JSON.package.version` (baked in by the bundle task's `define`).
+function getVersion() {
+  if (typeof require !== 'undefined') {
+    try {
+      const { app } = require('electron');
+      if (app && typeof app.getVersion === 'function') return app.getVersion();
+    } catch (_) {}
+  }
+  // Build-time scripts / non-Electron contexts: read project package.json.
+  try {
+    const path = require('path');
+    const pkg = require(path.join(process.cwd(), 'package.json'));
+    return pkg.version || null;
+  } catch (_) {
+    // Only legitimate failure: no package.json at cwd. Tolerate so build-time
+    // tooling running outside a project root still loads cleanly.
+    return null;
+  }
+}
+
+// Mix the helpers into a Manager constructor's prototype + the constructor itself
+// (so `Manager.isTesting()` works statically too, matching @omega.js/backend's pattern). getEnvironment()
+// is attached here too so all four entry points share one resolver — the URL helpers in
+// url-helpers.js depend on this.getEnvironment() existing.
+function attachTo(Manager) {
+  Manager.prototype.isDevelopment  = isDevelopment;
+  Manager.prototype.isProduction   = isProduction;
+  Manager.prototype.isTesting      = isTesting;
+  Manager.prototype.getEnvironment = getEnvironment;
+  Manager.prototype.getVersion     = getVersion;
+  Manager.isDevelopment  = isDevelopment;
+  Manager.isProduction   = isProduction;
+  Manager.isTesting      = isTesting;
+  Manager.getEnvironment = getEnvironment;
+  Manager.getVersion     = getVersion;
+}
+
+module.exports = {
+  attachTo,
+  isDevelopment,
+  isProduction,
+  isTesting,
+  getEnvironment,
+  getVersion,
+};

package/dist/utils/resolve-signing-cert.js

@@ -0,0 +1,175 @@
+// Where the macOS signing certificate comes from — the ONE lookup order.
+//
+//   1. CSC_LINK in the environment — an explicit answer always wins.
+//   2. The BRAND's gitignored signing tree:
+//      <brandRoot>/.omega/certificates/apple/certificates/DEVELOPER_ID_APPLICATION_G2.p12
+//      The brand root is the nearest directory at or above the target carrying a
+//      `.omega/`. The manager's disperse service also copies this material into
+//      each app's config/certs/; this lookup is the portable/CI path that needs
+//      no dispersal first.
+//   3. The COMPANY's tree, when the brand is company-managed. A brand is NEVER
+//      physically inside its company folder — membership is the
+//      `.omega/company.json` stamp at the brand root, read through
+//      @omega.js/config's readCompanyRoot (the ecosystem's ONE company rule; no
+//      second reader lives here). The stamp's target is used as given: it is
+//      explicit config, not discovery, so the home bound below does not apply to it.
+//   4. The macOS Keychain — electron-builder's own identity auto-discovery,
+//      which is what happens when nothing sets CSC_LINK.
+//
+// Keychain stays the DEFAULT for local signed builds: a tree with no cert (every
+// setup that predates the certificates service) resolves to it untouched. Two
+// further conditions keep it there rather than handing electron-builder a file
+// it cannot use:
+//   - no CSC_KEY_PASSWORD (it comes from the .env cascade, never from config), or
+//   - a password that does not OPEN the .p12. An unopenable .p12 fails the build
+//     outright — worse than today's behavior. The check is the read-side twin of
+//     how the manager EXPORTS one (openssl `pkcs12 -legacy`; the legacy provider
+//     reads modern containers too).
+//
+// The brand-root walk stops BELOW the home directory: `~/.omega` is a real
+// personal overlay on developer machines, and a stray tree there must never sign
+// every build.
+
+const { execFileSync } = require('node:child_process');
+const { homedir } = require('node:os');
+const { dirname, join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const { readCompanyRoot } = require('../vendor/config/index.js');
+
+const OMEGA_DIR = '.omega';
+const CERT_REL = join(OMEGA_DIR, 'certificates', 'apple', 'certificates', 'DEVELOPER_ID_APPLICATION_G2.p12');
+
+/**
+ * The brand root a target belongs to: the nearest directory at or above it
+ * carrying a `.omega/`. Stops below the home directory.
+ *
+ * @param {string} from - Directory to start walking up from
+ * @param {string} homeDir - Boundary: this directory and everything above never count
+ * @returns {string|null}
+ */
+function findBrandRoot(from, homeDir) {
+  let dir = from;
+
+  while (true) {
+    // The home directory itself — and everything above it — is out of bounds.
+    if (dir === homeDir) {
+      return null;
+    }
+
+    if (jetpack.exists(join(dir, OMEGA_DIR)) === 'dir') {
+      return dir;
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * The signing certificate a root holds, if any.
+ *
+ * @param {string|null} root
+ * @returns {string|null} - Absolute path to the .p12, or null
+ */
+function certificateIn(root) {
+  if (!root) {
+    return null;
+  }
+
+  const candidate = join(root, CERT_REL);
+  return jetpack.exists(candidate) === 'file' ? candidate : null;
+}
+
+/**
+ * Does this password actually open the container?
+ *
+ * Two openssl families answer differently: OpenSSL 3 needs `-legacy` to read
+ * the legacy-format containers the manager exports (macOS `security import`
+ * needs that format), while stock macOS /usr/bin/openssl is LibreSSL, which
+ * rejects the `-legacy` FLAG but reads legacy containers natively. A flag
+ * rejection is retried without it; only a real password/container failure
+ * counts as "does not open".
+ *
+ * @param {string} p12Path - Path to the .p12
+ * @param {string} password - Candidate password
+ * @returns {{ opens: boolean, tooling?: string }} - tooling set when openssl
+ *   itself was unavailable/unusable, so the caller can say so instead of
+ *   blaming the password
+ */
+function opensWith(p12Path, password) {
+  // Password rides an env var — never argv, never a shell string.
+  const run = (args) => execFileSync(
+    'openssl',
+    ['pkcs12', ...args, '-in', p12Path, '-nokeys', '-noout', '-passin', 'env:OMEGA_P12_PASSWORD'],
+    { stdio: 'pipe', env: { ...process.env, OMEGA_P12_PASSWORD: password } },
+  );
+
+  try {
+    run(['-legacy']);
+    return { opens: true };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return { opens: false, tooling: 'openssl is not available' };
+    }
+
+    if (String(error.stderr || '').includes('unknown option')) {
+      try {
+        run([]);
+        return { opens: true };
+      } catch (retryError) {
+        if (retryError.code === 'ENOENT') {
+          return { opens: false, tooling: 'openssl is not available' };
+        }
+        return { opens: false };
+      }
+    }
+
+    return { opens: false };
+  }
+}
+
+/**
+ * Resolve which certificate source a signed build should use.
+ *
+ * @param {object} options
+ * @param {string} options.projectRoot - The desktop app's root
+ * @param {object} [options.env] - Environment to read (default process.env)
+ * @param {string} [options.homeDir] - Walk boundary (default os.homedir())
+ * @returns {{ source: 'env'|'certificates'|'keychain', cscLink: string|null, reason: string }}
+ */
+function resolveSigningCert({ projectRoot, env = process.env, homeDir = homedir() }) {
+  const cscLink = typeof env.CSC_LINK === 'string' ? env.CSC_LINK.trim() : '';
+
+  if (cscLink) {
+    return { source: 'env', cscLink, reason: 'CSC_LINK is set' };
+  }
+
+  // The brand's own tree first, then the company's — reached ONLY through the
+  // brand's .omega/company.json stamp, never by walking up into a parent folder.
+  const brandRoot = findBrandRoot(projectRoot, homeDir);
+  const found = certificateIn(brandRoot) || certificateIn(brandRoot && readCompanyRoot(brandRoot));
+
+  if (!found) {
+    return { source: 'keychain', cscLink: null, reason: 'no .omega/certificates signing tree — using Keychain identity discovery' };
+  }
+
+  if (!env.CSC_KEY_PASSWORD) {
+    return { source: 'keychain', cscLink: null, reason: `found ${found} but CSC_KEY_PASSWORD is unset — using Keychain identity discovery` };
+  }
+
+  const check = opensWith(found, env.CSC_KEY_PASSWORD);
+  if (check.tooling) {
+    return { source: 'keychain', cscLink: null, reason: `${check.tooling} — cannot verify ${found}; using Keychain identity discovery` };
+  }
+  if (!check.opens) {
+    return { source: 'keychain', cscLink: null, reason: `CSC_KEY_PASSWORD does not open ${found} — using Keychain identity discovery` };
+  }
+
+  return { source: 'certificates', cscLink: found, reason: 'signing certificate from the brand .omega/certificates tree' };
+}
+
+module.exports = resolveSigningCert;
+module.exports.CERT_REL = CERT_REL;

package/dist/utils/run-consumer-hook.js

@@ -0,0 +1,38 @@
+// runConsumerHook(name, ...args) — load and invoke the consumer's optional hook file.
+//
+// Hook lookup: <projectRoot>/hooks/<name>.js.
+// Hook contract:
+//   - File missing entirely → log that the hook is not present and return undefined.
+//   - File exists but fails to load (syntax error, throws on require) → throws.
+//   - File exists but doesn't export a function → throws (malformed).
+//   - File loads + exports a fn that throws at runtime → throws.
+// In short: missing is fine (logged but doesn't fail); malformed or broken hooks fail the build
+// loudly so consumers don't ship a broken hook silently.
+
+const path = require('path');
+const fs = require('fs');
+const loadConsumerFile = require('./load-consumer-file.js');
+const LoggerLite = require('../lib/logger-lite.js');
+
+const logger = new LoggerLite('hooks');
+
+async function runConsumerHook(name, ...args) {
+  const projectRoot = process.cwd();
+  const absPath = path.join(projectRoot, 'hooks', `${name}.js`);
+
+  if (!fs.existsSync(absPath)) {
+    logger.log(`hook "${name}" not present at ${absPath} — skipping.`);
+    return undefined;
+  }
+
+  const exported = loadConsumerFile(absPath);
+
+  if (typeof exported !== 'function') {
+    throw new Error(`[desktop:hooks] hook "${name}" at ${absPath} did not export a function (got ${typeof exported}).`);
+  }
+
+  logger.log(`running hook "${name}"`);
+  return await exported(...args);
+}
+
+module.exports = runConsumerHook;