@omega.js/desktop 0.1.0

package/dist/test/suites/renderer/window-em-surface.test.js

@@ -0,0 +1,107 @@
+// Renderer-layer suite — asserts the `window.desktop` surface exposed by preload is shaped
+// correctly and that the storage proxy round-trips through IPC into the main store.
+//
+// Runs inside a hidden BrowserWindow spawned by the test harness. The renderer harness
+// reconstructs each `run` function via `new Function('ctx', body)` so the function bodies
+// here can only reference `ctx` and `window` — no closures over module scope.
+
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'renderer',
+  description: 'window.desktop surface + storage proxy roundtrip',
+  tests: [
+    {
+      name: 'window.desktop is exposed and is an object',
+      run: (ctx) => {
+        ctx.expect(typeof window.desktop).toBe('object');
+        ctx.expect(window.desktop).toBeTruthy();
+      },
+    },
+    {
+      name: 'window.desktop.ipc has invoke / on / send',
+      run: (ctx) => {
+        ctx.expect(typeof window.desktop.ipc.invoke).toBe('function');
+        ctx.expect(typeof window.desktop.ipc.on).toBe('function');
+        ctx.expect(typeof window.desktop.ipc.send).toBe('function');
+      },
+    },
+    {
+      // wave-5 F4: ipc.on used to return ipcRenderer (stripped to a useless
+      // object across the contextBridge) — docs/ipc.md promises an unsubscribe fn.
+      name: 'ipc.on returns an unsubscribe function (docs contract)',
+      run: (ctx) => {
+        const off = window.desktop.ipc.on('em-test:noop-channel', () => {});
+        ctx.expect(typeof off).toBe('function');
+        off(); // must not throw
+      },
+    },
+    {
+      name: 'window.desktop.storage has get / set / delete / has / clear',
+      run: (ctx) => {
+        ctx.expect(typeof window.desktop.storage.get).toBe('function');
+        ctx.expect(typeof window.desktop.storage.set).toBe('function');
+        ctx.expect(typeof window.desktop.storage.delete).toBe('function');
+        ctx.expect(typeof window.desktop.storage.has).toBe('function');
+        ctx.expect(typeof window.desktop.storage.clear).toBe('function');
+      },
+    },
+    {
+      name: 'window.desktop.logger has log / warn / error',
+      run: (ctx) => {
+        ctx.expect(typeof window.desktop.logger.log).toBe('function');
+        ctx.expect(typeof window.desktop.logger.warn).toBe('function');
+        ctx.expect(typeof window.desktop.logger.error).toBe('function');
+      },
+    },
+    {
+      name: 'window.desktop.autoUpdater has getStatus / checkNow / installNow',
+      run: (ctx) => {
+        ctx.expect(typeof window.desktop.autoUpdater.getStatus).toBe('function');
+        ctx.expect(typeof window.desktop.autoUpdater.checkNow).toBe('function');
+        ctx.expect(typeof window.desktop.autoUpdater.installNow).toBe('function');
+      },
+    },
+    {
+      name: 'storage.set + storage.get round-trips through IPC',
+      run: async (ctx) => {
+        const key = '__em_renderer_test_value';
+        await window.desktop.storage.set(key, { hello: 'world', n: 42 });
+        const value = await window.desktop.storage.get(key);
+        ctx.expect(value).toEqual({ hello: 'world', n: 42 });
+        await window.desktop.storage.delete(key);
+      },
+    },
+    {
+      name: 'storage.has reports correctly',
+      run: async (ctx) => {
+        const key = '__em_renderer_has_test';
+        await window.desktop.storage.set(key, 'x');
+        const yes = await window.desktop.storage.has(key);
+        ctx.expect(yes).toBe(true);
+        await window.desktop.storage.delete(key);
+        const no = await window.desktop.storage.has(key);
+        ctx.expect(no).toBe(false);
+      },
+    },
+    {
+      name: 'storage.delete removes the key',
+      run: async (ctx) => {
+        const key = '__em_renderer_delete_test';
+        await window.desktop.storage.set(key, 'gone');
+        await window.desktop.storage.delete(key);
+        const value = await window.desktop.storage.get(key, 'fallback');
+        ctx.expect(value).toBe('fallback');
+      },
+    },
+    {
+      name: 'autoUpdater.getStatus returns a status object',
+      run: async (ctx) => {
+        const status = await window.desktop.autoUpdater.getStatus();
+        ctx.expect(status).toBeDefined();
+        ctx.expect(typeof status.code).toBe('string');
+      },
+    },
+  ],
+});

package/dist/test/utils/dist-snapshot.js

@@ -0,0 +1,36 @@
+// Fingerprint a build-output tree: one line per file — relative path, size, mtime.
+//
+// Used by the boot layer to prove a boot-test run leaves the project's REAL dist/
+// untouched (#110): the runner records the snapshot before the test build, ships it in
+// the boot spec, and the boot suite re-reads the same tree from inside the booted app
+// and compares. A missing tree snapshots as the empty string, so "absent before, absent
+// after" passes and "absent before, written during the run" fails.
+
+const fs = require('fs');
+const path = require('path');
+
+module.exports = function distSnapshot(dir) {
+  const lines = [];
+  walk(dir, dir, lines);
+  return lines.sort().join('\n');
+};
+
+function walk(root, current, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(current, { withFileTypes: true });
+  } catch (e) {
+    return;   // absent (or unreadable) tree — nothing to fingerprint
+  }
+
+  for (const entry of entries) {
+    const abs = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      walk(root, abs, out);
+      continue;
+    }
+    // lstat, not stat — a symlink is recorded as itself, never followed.
+    const stats = fs.lstatSync(abs);
+    out.push(`${path.relative(root, abs)}\t${stats.size}\t${stats.mtimeMs}`);
+  }
+}

package/dist/test/utils/extended-mode-warning.js

@@ -0,0 +1,13 @@
+// TEST_EXTENDED_MODE warning — SSOT for consistent messaging.
+//
+// The headline + shape live in @omega.js/devkit (mirrored across @omega.js/backend/BXM/UJM); these
+// detail lines describe @omega.js/desktop's blast radius. Used by the test command (printed to
+// console + teed to logs/test.log).
+const { makeExtendedModeWarning } = require('../../vendor/devkit/test/extended-mode-warning.js');
+
+const EXTENDED_MODE_WARNING = makeExtendedModeWarning([
+  'Tests that hit real external services (Firebase, analytics, update feeds) are ENABLED!',
+  'This will make real network calls against live backends.',
+]);
+
+module.exports = { EXTENDED_MODE_WARNING };

package/dist/utils/app-root.js

@@ -0,0 +1,28 @@
+// Resolve the consumer app's root directory at runtime.
+//
+// Why this exists:
+//   `process.cwd()` is the project directory in dev (when launched via `npm start` /
+//   gulp/serve), but in a PACKAGED .app it's `/` (or the user's home dir, depending on
+//   how the app was launched). That breaks every `path.join(process.cwd(), 'dist', ...)`
+//   call in lib/* — they end up trying to read `/dist/views/main/index.html` and fail
+//   with ERR_FILE_NOT_FOUND.
+//
+// What it returns:
+//   - In Electron context: `app.getAppPath()` — the consumer's app dir, which is the
+//     extracted asar mount point in production and the project root in dev.
+//   - Outside Electron (tests, scaffolding scripts): falls back to `process.cwd()`.
+//
+// Always prefer this over `process.cwd()` for runtime path resolution in lib/*.
+
+module.exports = function appRoot() {
+  // In main, `electron.app.getAppPath` is the right answer. In renderer/preload
+  // / plain Node, `app` is undefined — fall through to cwd.
+  // In renderer bundles (target: 'web'), require is not available — skip.
+  if (typeof require !== 'undefined') {
+    try {
+      const electron = require('electron');
+      if (electron?.app?.getAppPath) return electron.app.getAppPath();
+    } catch (_) {}
+  }
+  return typeof process !== 'undefined' ? process.cwd() : '/';
+};

package/dist/utils/attach-log-file.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/attach-log-file.js');

package/dist/utils/build-pipeline.js

@@ -0,0 +1,58 @@
+// The build-mode pipeline shared by the `build`, `package`, and `publish` verbs.
+//
+// The CLI verbs are canonical and the synced projectScripts are thin
+// `omega <verb>` aliases, so a verb must run the pipeline ITSELF and never
+// shell back to `npm run build` / `npm run publish` — that would recurse. Each
+// verb declares its plan as data (env flags + ordered steps) and this runner
+// executes it; `npm run gulp -- <task>` is the one safe shell-out (the consumer's
+// `gulp` script is bare `gulp`, so there's no alias to recurse through).
+
+// Libraries
+const { execute } = require('node-powertools');
+
+function gulpCommand(task) {
+  return `npm run gulp -- ${task}`;
+}
+
+// Default step implementations — required lazily so requiring a plan never
+// loads the whole command surface.
+//
+// There is no `setup` step any more (#675): the local half runs inside the gulp
+// `defaults` task, which is the first step of every gulp build. What the plans
+// still need before signing is the Apple artifacts (#678) — `certs`.
+const RUNNERS = {
+  clean: (options) => require('../commands/clean.js')(options),
+  certs: () => {
+    const Manager = new (require('../build.js'));
+    require('./deliver-certs.js').deliverTargetCerts({
+      projectDir: Manager.getRootPath('project'),
+      logger: Manager.logger('certs'),
+    });
+  },
+  'validate-certs': (options) => require('../commands/validate-certs.js')(options),
+  gulp: (options, step) => execute(gulpCommand(step.task), { log: true }),
+};
+
+async function runPipeline(plan, options, runners) {
+  options = options || {};
+  runners = runners || RUNNERS;
+
+  // Set in-process so every child (gulp → esbuild → electron-builder) inherits them.
+  Object.entries(plan.env || {}).forEach(([key, value]) => {
+    process.env[key] = value;
+  });
+
+  for (const step of plan.steps) {
+    const runner = runners[step.type];
+
+    // Plans are authored in this package alongside the runner table — an
+    // unknown type is a programmer error, never consumer input.
+    if (!runner) {
+      throw new Error(`Unknown pipeline step type: ${step.type}`);
+    }
+
+    await runner(options, step);
+  }
+}
+
+module.exports = { runPipeline, gulpCommand, RUNNERS };

package/dist/utils/deliver-certs.js

@@ -0,0 +1,69 @@
+/**
+ * Signing-artifact delivery on the desktop verbs
+ * ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)).
+ *
+ * The copy itself is devkit's (`@omega.js/devkit/certs`) — the ONE delivery
+ * step, the same rules the manager's disperse writer rides. What lives here is
+ * the desktop FRAMING: which root holds the signing tree, the brand block the
+ * `{brand.id}` rules resolve from, and this framework's own voice.
+ *
+ * The source root is the COMPANY root when the brand is company-managed (the
+ * `.omega/company.json` stamp @omega.js/config reads), the brand root
+ * otherwise — the same rule disperse used, read through the same one reader.
+ * A target outside a brand has no tree and no delivery.
+ */
+const jetpack = require('fs-jetpack');
+const { findBrandRoot, readCompanyRoot, loadConfig } = require('../vendor/config/index.js');
+const { deliverCerts, certsSourceDir } = require('../vendor/devkit/certs.js');
+
+/**
+ * The root holding `.omega/certificates/apple/` for a target: the company
+ * workspace when one is stamped, else the brand root.
+ *
+ * @param {string} projectDir - The target root.
+ * @returns {string|null} The source root, or null when the target is not in a brand.
+ */
+function resolveSourceRoot(projectDir) {
+  const brandRoot = findBrandRoot(projectDir);
+  if (!brandRoot) return null;
+
+  return readCompanyRoot(brandRoot) || brandRoot;
+}
+
+/**
+ * Deliver this target's Apple artifacts into its own certs dir, so signing
+ * finds them on every verb rather than only after a manage run.
+ *
+ * Reports and returns; it never throws. A brandless target, a tree that was
+ * never produced, or a missing artifact are all normal states — the signing
+ * lookup and validate-certs are what judge them.
+ *
+ * @param {object} input
+ * @param {string} input.projectDir - The target root.
+ * @param {object} input.logger - `{ log, warn, error }`.
+ * @returns {{ copied: string[], current: string[], missing: string[] }|null} null when there is no tree.
+ */
+function deliverTargetCerts({ projectDir, logger }) {
+  const sourceRoot = resolveSourceRoot(projectDir);
+  if (!sourceRoot || !jetpack.exists(certsSourceDir(sourceRoot))) {
+    return null;
+  }
+
+  let brand = null;
+  try {
+    brand = loadConfig(projectDir, 'desktop').config.brand || null;
+  } catch (e) {
+    // Unloadable config — the `{brand.id}` rules simply resolve empty; the
+    // required rules below still deliver.
+  }
+
+  const result = deliverCerts({ sourceRoot, targetDir: projectDir, target: 'desktop', brand });
+
+  if (result.copied.length > 0) {
+    logger.log(`Delivered signing artifacts: ${result.copied.join(', ')}`);
+  }
+
+  return result;
+}
+
+module.exports = { deliverTargetCerts, resolveSourceRoot };

package/dist/utils/derive-signing-env.js

@@ -0,0 +1,56 @@
+// Where CSC_LINK and APPLE_API_KEY come from when nothing has answered yet
+// ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)).
+//
+// The manager's disperse service used to stamp both into the target's .env as
+// target-relative paths, and only when the file was there. No machine writes a
+// target .env any more, so the build derives them instead: the artifacts are
+// delivered into config/certs/ by every verb (deliver-certs.js), and a delivered
+// file that nothing has pointed at IS the answer.
+//
+// Rules, per key: an env value that is already set always wins (an explicit
+// answer is never overridden), and a file that is not there sets nothing (an
+// unset key lets electron-builder's own skip/auto-discovery logic apply — the
+// same reason sanitize-signing-env.js deletes empty placeholders).
+//
+// APPLE_API_KEY's filename carries the key id, so an unset APPLE_API_KEY_ID
+// means there is no path to derive.
+
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const CERTS_DIR = path.join('config', 'certs');
+const DEVELOPER_ID_APPLICATION = 'developer-id-application.p12';
+
+/**
+ * Set the signing paths the delivered artifacts imply. Mutates `env`.
+ *
+ * @param {object} input
+ * @param {object} input.env - The env map to derive into (the build's process env).
+ * @param {string} input.projectDir - The target root (paths are written relative to it).
+ * @returns {Array<{ key: string, value: string }>} What was derived — empty when nothing was.
+ */
+function deriveSigningEnv({ env, projectDir }) {
+  const derived = [];
+
+  const candidates = [
+    { key: 'CSC_LINK', file: DEVELOPER_ID_APPLICATION },
+    { key: 'APPLE_API_KEY', file: env.APPLE_API_KEY_ID ? `AuthKey_${env.APPLE_API_KEY_ID}.p8` : null },
+  ];
+
+  for (const { key, file } of candidates) {
+    if (!file) continue;
+    if (typeof env[key] === 'string' && env[key].trim() !== '') continue;
+
+    const relative = path.join(CERTS_DIR, file);
+    if (!jetpack.exists(path.join(projectDir, relative))) continue;
+
+    env[key] = relative;
+    derived.push({ key, value: relative });
+  }
+
+  return derived;
+}
+
+module.exports = deriveSigningEnv;
+module.exports.CERTS_DIR = CERTS_DIR;
+module.exports.DEVELOPER_ID_APPLICATION = DEVELOPER_ID_APPLICATION;

package/dist/utils/dist-root.js

@@ -0,0 +1,21 @@
+// Resolve the build OUTPUT directory for a project root.
+//
+// Default `<root>/dist` — what every gulp task joined by hand until #110. The ONE seam:
+// `OMEGA_BUILD_OUTPUT` redirects the whole build output elsewhere, so a boot-test build
+// never interleaves writes with a concurrent `npm start` watcher's dist/. An absolute
+// value is used as-is; a relative one resolves against the project root.
+//
+// Build-time only — the runtime (window-manager, tray) still reads `<appRoot>/dist`,
+// because the boot runner stages an app root whose dist IS the redirected output.
+
+const path = require('path');
+
+module.exports = function distRoot(root) {
+  const override = process.env.OMEGA_BUILD_OUTPUT;
+
+  if (!override) {
+    return path.join(root, 'dist');
+  }
+
+  return path.isAbsolute(override) ? override : path.resolve(root, override);
+};

package/dist/utils/electron-node-version.js

@@ -0,0 +1,48 @@
+// Resolve the Node.js version that Electron's bundled runtime ships with, by querying the
+// official electron releases feed. Returns the major version (e.g. "24") so we can write
+// `.nvmrc` and `engines.node` from it.
+//
+// Same pattern as legacy @omega.js/desktop's `process_checkNodeVersion` — fetch releases.electronjs.org once
+// per setup, find the entry matching the consumer's installed electron version, return its
+// `node` field's major.
+
+const wonderfulFetch  = require('wonderful-fetch');
+const wonderfulVersion = require('wonderful-version');
+
+const RELEASES_URL = 'https://releases.electronjs.org/releases.json';
+
+let cachedReleases = null;
+
+async function fetchReleases() {
+  if (cachedReleases) return cachedReleases;
+  const data = await wonderfulFetch(RELEASES_URL, { response: 'json', tries: 3 });
+  cachedReleases = Array.isArray(data) ? data : [];
+  return cachedReleases;
+}
+
+// Resolve the Node major for a given electron version (e.g. '41.0.0' or '^41.0.0' → '24').
+// Returns null on miss / network failure — caller should fall back gracefully.
+async function resolveNodeMajorForElectron(electronVersion) {
+  if (!electronVersion) return null;
+  const electronMajor = wonderfulVersion.major(electronVersion);
+  if (!electronMajor) return null;
+
+  let releases;
+  try {
+    releases = await fetchReleases();
+  } catch (e) {
+    return null;
+  }
+
+  // Find the *.0.0 release for this electron major (matches legacy @omega.js/desktop's behavior — the .0.0 of
+  // each major is the canonical Node version for the line; later patch/minor electrons may bump
+  // Node within the line but the major-Node mapping is stable).
+  const match = releases.find((r) => r.version === `${electronMajor}.0.0`);
+  if (!match || !match.node) return null;
+  return wonderfulVersion.major(match.node);
+}
+
+module.exports = {
+  resolveNodeMajorForElectron,
+  fetchReleases,
+};

package/dist/utils/electron-targets.js

@@ -0,0 +1,72 @@
+// The esbuild targets the three bundles compile to — read from the PINNED
+// Electron itself ([#737](https://github.com/Omega-JS-Stack/omega/issues/737)).
+//
+// webpack encoded this as `target: 'electron-main' | 'electron-preload' | 'web'`
+// and guessed a conservative syntax floor from its own tables. esbuild splits
+// the same fact into `platform` (which the build task states) and `target` (the
+// syntax floor), and the floor is a REAL number: the Node the main process runs
+// and the Chromium the renderer runs, both compiled into the binary a consumer
+// has pinned. Asking the binary is the only answer that stays right when the
+// consumer bumps Electron — a hand-kept Electron→Node/Chromium table drifts on
+// every release, and the releases feed
+// ([electron-node-version.js](electron-node-version.js)) needs a network a
+// build must never need.
+//
+// `ELECTRON_RUN_AS_NODE` runs the binary as plain Node: no window, no dock icon,
+// no focus stolen. The probe costs one spawn per build and is memoized per
+// binary path.
+//
+// A binary that cannot be run is an EXPECTED external condition, not a broken
+// invariant: a CI job with ELECTRON_SKIP_BINARY_DOWNLOAD set has a package and
+// no executable. That build gets `null` targets, which the caller reads as "no
+// syntax floor" (esbuild's default), and a warn line saying so — never a
+// silently-invented version.
+
+const { execFileSync } = require('child_process');
+
+const cache = new Map();
+
+/**
+ * The pinned Electron's own Node and Chromium versions, as esbuild targets.
+ * @param {string} binary - path to the Electron executable (`require('electron')`)
+ * @param {object} [options]
+ * @param {object} [options.logger] - logger with `warn` (a failed probe explains itself)
+ * @returns {{ node: string|null, chrome: string|null, electron: string|null }} esbuild target strings
+ */
+module.exports = function electronTargets(binary, options) {
+  if (cache.has(binary)) return cache.get(binary);
+
+  let targets = { node: null, chrome: null, electron: null };
+
+  try {
+    const output = execFileSync(binary, ['-p', 'JSON.stringify(process.versions)'], {
+      encoding: 'utf8',
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 60000,
+    });
+    // The LAST line, not the whole output: Electron writes its own diagnostics
+    // to stdout before running the script (a GPU or sandbox notice on Linux, a
+    // Squirrel line on Windows), and `-p` prints the value last. Parsing the
+    // whole buffer would fail on exactly the machines that talk the most.
+    const versions = JSON.parse(output.trim().split('\n').pop());
+    targets = {
+      // Node takes the full version (esbuild reads `node24.18.0`); Chromium
+      // ships four parts and esbuild reads at most three, so it takes the major
+      // — which is the only part a syntax floor turns on anyway.
+      node: versions.node ? `node${versions.node}` : null,
+      chrome: versions.chrome ? `chrome${versions.chrome.split('.')[0]}` : null,
+      electron: versions.electron || null,
+    };
+  } catch (e) {
+    // Called ON the logger, never as a detached reference: the devkit Logger
+    // reads its `[@omega.js/<package>:<module>]` tag off `this`, so a bare
+    // `const warn = logger.warn` prints `[undefined:undefined]`.
+    if (options && options.logger) {
+      options.logger.warn(`Could not read the Electron runtime versions from ${binary} (${e.message}) — bundles compile with no syntax floor.`);
+    }
+  }
+
+  cache.set(binary, targets);
+  return targets;
+};

package/dist/utils/format-fetch-error.js

@@ -0,0 +1,38 @@
+// format-fetch-error — flatten a fetch/network error into one short, log-safe line.
+//
+// wonderful-fetch's buildError() uses the ENTIRE response body as `error.message`.
+// When a brand-site endpoint is missing (remote-config, remote-scripts), that body
+// is a full HTML 404 page — dumping it into the console/runtime.log buries real
+// output, and re-spams on every periodic poll. This helper:
+//   1. Swaps HTML bodies for a short human description (markup is noise in a log).
+//   2. Prefixes the HTTP status when the error carries one (`error.status`).
+//   3. Collapses whitespace to a single line and caps the length.
+//
+// Usage:
+//   const formatFetchError = require('../utils/format-fetch-error.js');
+//   fetch(url, opts).catch((e) => logger.warn(`fetch failed: ${formatFetchError(e)}`));
+
+const MAX_LENGTH = 200;
+
+function formatFetchError(error, maxLength) {
+  const max = maxLength || MAX_LENGTH;
+  const status = (error && typeof error.status === 'number') ? `HTTP ${error.status}: ` : '';
+
+  // Flatten to one line — embedded newlines break grep and bury adjacent log lines.
+  let message = String((error && error.message) || error || 'Unknown error')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  // An HTML page in the message is pure noise — name it instead of printing it.
+  if (/^<!doctype\b|^<html\b/i.test(message)) {
+    message = 'response was an HTML page, not the expected resource';
+  }
+
+  if (message.length > max) {
+    message = `${message.slice(0, max)}… [truncated]`;
+  }
+
+  return `${status}${message}`;
+}
+
+module.exports = formatFetchError;

package/dist/utils/github.js

@@ -0,0 +1,73 @@
+// Shared GitHub helpers used by push-secrets and the release pipeline.
+//
+// WHICH repo a verb addresses is not decided here: the app repo is
+// @omega.js/config's `brandRepo` and the releases repo its `releasesRepo`, from
+// config/omega.json5 alone (#799). The old package.json/git-remote discovery is
+// gone: a brand nested in another repo (a target inside a brand monorepo, the
+// playground inside the framework monorepo) resolved to the ENCLOSING repo.
+//
+// Octokit factory: returns an authenticated client when GH_TOKEN is set. Returns null otherwise so
+// callers can choose to no-op or bail with a friendly message.
+//
+// Repo ensure: idempotently create a repo under <owner> if it doesn't exist. Used by the
+// deploy precheck to auto-provision the brand's public releases repo.
+
+// silent: true — pass a no-op logger so transient 404s during polling (e.g. fetching
+// in-progress job logs) don't spam the console. Errors still surface via thrown rejections.
+function getOctokit(opts = {}) {
+  const token = process.env.GH_TOKEN;
+  if (!token) return null;
+  const { Octokit } = require('@octokit/rest');
+  const config = { auth: token };
+  if (opts.silent) {
+    const noop = () => {};
+    config.log = { debug: noop, info: noop, warn: noop, error: noop };
+  }
+  return new Octokit(config);
+}
+
+// Idempotent: returns true if the repo exists (created or already there), false on failure.
+// Honors the `owner` distinction between user vs. org — the API endpoints differ.
+async function ensureRepo(octokit, owner, repo, opts = {}) {
+  const description = opts.description || '';
+  const isPrivate = opts.private === true;
+
+  try {
+    await octokit.rest.repos.get({ owner, repo });
+    return { created: false, exists: true };
+  } catch (err) {
+    if (err.status !== 404) throw err;
+  }
+
+  // Need to create. Check if owner is the authenticated user or an org.
+  let isOrg = false;
+  try {
+    const { data: me } = await octokit.rest.users.getAuthenticated();
+    isOrg = me.login.toLowerCase() !== owner.toLowerCase();
+  } catch (e) {
+    isOrg = true;
+  }
+
+  const params = {
+    name: repo,
+    description,
+    private: isPrivate,
+    has_issues: true,
+    has_projects: false,
+    has_wiki: false,
+    auto_init: true,
+  };
+
+  if (isOrg) {
+    await octokit.rest.repos.createInOrg({ org: owner, ...params });
+  } else {
+    await octokit.rest.repos.createForAuthenticatedUser(params);
+  }
+
+  return { created: true, exists: true };
+}
+
+module.exports = {
+  getOctokit,
+  ensureRepo,
+};

package/dist/utils/load-consumer-file.js

@@ -0,0 +1,26 @@
+// Loads a JS module from an arbitrary path on disk (e.g. consumer's src/tray/index.js).
+//
+// Used by tray/menu/context-menu to load consumer-defined definition files. A bundler would
+// normally try to resolve `require(<dynamicPath>)` at build time, which can never work for a
+// runtime path, so we use Node's `module.createRequire(...)` to get a real require function.
+// (In the webpack era this also drew a noisy "Critical dependency" warning at build time; the
+// runtime behavior was correct then too.)
+
+const path   = require('path');
+const Module = require('module');
+
+// Returns the module.exports of the file, or null if the file doesn't exist.
+// THROWS if the file exists but fails to load (syntax error, throws at module-eval, etc.).
+// Callers can decide whether to treat load errors as fatal — most should.
+// On success, also clears Node's require cache for the file so subsequent reloads pick up edits.
+function loadConsumerFile(absPath) {
+  const fs = require('fs');
+  if (!fs.existsSync(absPath)) return null;
+
+  const consumerRequire = Module.createRequire(path.join(process.cwd(), 'package.json'));
+  const resolved = consumerRequire.resolve(absPath);
+  delete consumerRequire.cache[resolved];
+  return consumerRequire(resolved);
+}
+
+module.exports = loadConsumerFile;

package/dist/utils/merge-line-files.js

@@ -0,0 +1,5 @@
+// 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 (@omega.js/desktop's copy was
+// the canonical seed — quote normalization + order-safe key substitution).
+module.exports = require('../vendor/devkit/merge-line-files.js');