@omega.js/desktop 0.50.0 → 0.51.0

package/dist/gulp/tasks/bundle.js

@@ -1,5 +1,6 @@
 // bundle — three bundles (main / preload / renderer), built in parallel.
-// Each one gets `OMEGA_BUILD_JSON` baked in as a define.
+// The NODE pair (main / preload) gets `OMEGA_BUILD_JSON` baked in as a define;
+// the renderer reads the ONE `dist/build.js` the page template loads (#743).
 //
 // The bundler is esbuild since [#737](https://github.com/Omega-JS-Stack/omega/issues/737),
 // and the file, the gulp task, the log tag and `npm run gulp -- bundle` were
@@ -19,11 +20,12 @@ const logger = Manager.logger('bundle');
 const path = require('path');
 const glob = require('glob').globSync;
 const jetpack = require('fs-jetpack');
-const { readSiblingPorts, readSiblingOrigin, envPorts } = require('../../vendor/config/index.js');
-const { bakeKeys } = require('../../vendor/config/env-delivery.js');
+const { CLASSIC_PORTS, CLASSIC_DEV_ORIGIN, readSiblingPorts, readSiblingOrigin, envPorts, targetNameFromDir } = require('../../vendor/config/index.js');
+const { bakeKeys, bakeSourceKeys } = require('../../vendor/config/env-delivery.js');
 const { checkEnvRules } = require('../../vendor/config/env-rules.js');
 const { resolveLicenseStamp } = require('../../vendor/devkit/license.js');
 const { bundle, formatBytes } = require('../../vendor/devkit/bundle.js');
+const buildJsonKit = require('../../vendor/devkit/build-json.js');
 const { emptyModulesPlugin } = require('../../vendor/devkit/empty-modules-plugin.js');
 const electronTargets = require('../../utils/electron-targets.js');
 
@@ -49,33 +51,72 @@ const RENDERER_EMPTY_MODULES = [
   'querystring', 'string_decoder', 'electron',
 ];
 
-// The blob every bundle reads as OMEGA_BUILD_JSON.config — and the ONLY thing
-// the renderer hands @omega.js/client (renderer.js merges `buildJson.config`
-// with the runtime overrides). The app's VERSION rides INSIDE it for that
-// reason: the client tags every error report `<brand.id>@<version>` and falls
-// back to the build stamp without one (#380), and it never sees the sibling
-// `package` key. The dev map (#300) is a dev-build key only.
-function composeBuildConfig(config, dev, pkg) {
-  return { ...config, version: pkg.version, ...(dev ? { dev } : {}) };
+// The build FACTS this artifact carries, composed onto the resolved config by
+// both halves ([#894](https://github.com/Omega-JS-Stack/omega/issues/894)) and
+// spelled the way web and the extension spell them. The app's VERSION rides
+// INSIDE the config: the client tags every error report `<brand.id>@<version>`
+// and falls back to the build stamp without one (#380), and it never sees the
+// sibling `package` key. `runtime` is baked because the client's own sniff has
+// no Electron signal to find in a renderer and would answer `'web'`
+// ([#896](https://github.com/Omega-JS-Stack/omega/issues/896)). The dev map
+// (#300) is a dev-build key only.
+function buildFacts({ pkg, mode, dev }) {
+  return {
+    runtime: 'electron',
+    environment: mode.environment,
+    version: pkg.version,
+    buildTime: Date.now(),
+    // WHICH target this artifact IS, by name (#887)
+    target: targetNameFromDir(projectRoot) || 'desktop',
+    ...(dev ? { dev } : {}),
+  };
+}
+
+// The wrapper's `mode`, the same three keys on every OMEGA surface (#894).
+// Desktop's own `server` verdict stays inside the Manager, which is the only
+// thing that reads it: an artifact records what it WAS BUILT as.
+function artifactMode(mode) {
+  return { environment: mode.environment, build: mode.build, publish: mode.publish };
 }
 
-// OMEGA_BUILD_JSON itself — the build's own record of what it produced. The
-// `license` stamp ([#320](https://github.com/Omega-JS-Stack/omega/issues/320))
-// rides HERE and not inside `config`: it is a fact about the build, not part
-// of the client contract the renderer hands @omega.js/client. Nothing in the
-// app reads it today (a packaged app has no attribution surface, and payments
-// ride the backend's own gate) — it is what makes an artifact say which
-// verdict it was packaged under.
-function composeBuildJson({ config, dev, pkg, mode, license }) {
+// The config blob the NODE bundles read as OMEGA_BUILD_JSON.config (main and
+// preload): the WHOLE resolved config plus this build's facts.
+function composeBuildConfig(config, facts) {
+  return { ...config, ...facts };
+}
+
+// OMEGA_BUILD_JSON for the NODE half: the build's own record of what it
+// produced. The `license` stamp
+// ([#320](https://github.com/Omega-JS-Stack/omega/issues/320)) rides HERE and
+// not inside `config`: it is a fact about the build, not part of the client
+// contract the renderer hands @omega.js/client. Nothing in the app reads it
+// today (a packaged app has no attribution surface, and payments ride the
+// backend's own gate); it is what makes an artifact say which verdict it was
+// packaged under.
+//
+// Main and preload keep the whole resolved config because the main process
+// BOOTS from it (main.js reads OMEGA_BUILD_JSON.config in a packaged app, where
+// config/omega.json5 is inside the asar), and a preload is isolated from the
+// page. Both are Node, neither is a public surface.
+function composeBuildJson({ config, facts, pkg, mode, license }) {
   return {
-    config: composeBuildConfig(config, dev, pkg),
+    config: composeBuildConfig(config, facts),
     package: pkg,
-    mode,
+    mode: artifactMode(mode),
     license,
     builtAt: new Date().toISOString(),
   };
 }
 
+// The BROWSER half's snapshot ([#743](https://github.com/Omega-JS-Stack/omega/issues/743)):
+// @omega.js/devkit composes it (through @omega.js/config's browser subset) and
+// writes it to `dist/build.js`, which every view's page template loads with one
+// script tag ahead of its own bundle. One file, one shape and one consumption
+// on web, desktop and the extension alike.
+function composeClientBuildJson({ config, facts, pkg, mode, license }) {
+  return buildJsonKit.composeBuildJson({ config, pkg, mode, license, facts });
+}
+
 module.exports = function bundleTask(done) {
   const mode = Manager.getMode();
   const isProd = mode.environment === 'production';
@@ -88,13 +129,20 @@ module.exports = function bundleTask(done) {
   // channel, resolved on every build so a rebuild picks up a restarted
   // emulator ([#300](https://github.com/Omega-JS-Stack/omega/issues/300)).
   // The sibling website's published dev ORIGIN rides the same bake
-  // ([#262](https://github.com/Omega-JS-Stack/omega/issues/262)); a key
-  // present is a resolved fact, absent means the client assumes and warns.
-  // Never in production: a packaged app has no local stack.
+  // ([#262](https://github.com/Omega-JS-Stack/omega/issues/262)). Never in
+  // production: a packaged app has no local stack, so its `dev` is null and
+  // every dev read throws by name rather than reaching a localhost port.
   const devOrigin = isProd ? null : readSiblingOrigin(projectRoot);
   const dev = isProd ? null : {
-    ports: { ...readSiblingPorts(projectRoot), ...envPorts() },
-    ...(devOrigin ? { origin: devOrigin } : {}),
+    // The classic map is the FLOOR, from @omega.js/config, the one place the
+    // numbers are defined ([#834](https://github.com/Omega-JS-Stack/omega/issues/834)).
+    // A live stack's resolved (possibly bumped) numbers land on top of it, so a
+    // dev artifact always carries a COMPLETE map and no browser-side code needs
+    // a second copy of the defaults to fall back to. The same floor goes under
+    // the origin: the classic dev origin is `omega dev`'s own default, and a
+    // live website's published one wins over it.
+    ports: { ...CLASSIC_PORTS, ...readSiblingPorts(projectRoot), ...envPorts() },
+    origin: devOrigin || CLASSIC_DEV_ORIGIN,
   };
 
   // The license check (#320), once per build: a PRODUCTION build asks the
@@ -104,8 +152,14 @@ module.exports = function bundleTask(done) {
   const projectPackage = Manager.getPackage('project');
   resolveLicenseStamp({ config, production: isProd })
     .then((license) => {
-      // OMEGA_BUILD_JSON — frozen at build time, accessible at runtime as window/globalThis.OMEGA_BUILD_JSON.
-      const buildJson = composeBuildJson({ config, dev, pkg: projectPackage, mode, license });
+      // OMEGA_BUILD_JSON: frozen at build time. The NODE pair reads it as a
+      // define; the renderer reads the file written below.
+      const input = { config, facts: buildFacts({ pkg: projectPackage, mode, dev }), pkg: projectPackage, mode, license };
+      const buildJson = composeBuildJson(input);
+
+      // The ONE build.js, at dist/: the web root every view's shell resolves
+      // `../../build.js` against, inside a packaged asar exactly as on disk (#743).
+      buildJsonKit.writeBuildJs(outputRoot, composeClientBuildJson(input));
 
       logger.log(`bundling — environment=${mode.environment}, license=${license.status}`);
       runBundles(buildJson, isProd).then(() => done()).catch(done);
@@ -130,10 +184,16 @@ async function runBundles(buildJson, isProd) {
     dev: !isProd,
   };
 
+  // The renderer takes the same defines MINUS the snapshot: it reads the one
+  // build.js the page template loads ahead of it (#743), so nothing is copied
+  // into a bundle a user can read.
+  const { OMEGA_BUILD_JSON, ...rendererDefine } = shared.define;
+  const { banner, ...rendererShared } = { ...shared, define: rendererDefine };
+
   const builds = [
     mainBundle(shared),
     preloadBundle(shared),
-    rendererBundle(shared),
+    rendererBundle(rendererShared),
   ].filter(Boolean);
 
   if (builds.length === 0) {
@@ -172,7 +232,7 @@ function resolveTargets() {
   }
 }
 
-// Inject OMEGA_BUILD_JSON into every bundle two ways:
+// Inject OMEGA_BUILD_JSON into the NODE bundles (main and preload) two ways:
 // 1. `define` replaces the bare `OMEGA_BUILD_JSON` identifier with the literal at build time
 //    (so framework code can reference it without globals).
 // 2. `banner` prepends a tiny IIFE that assigns the same value to globalThis.OMEGA_BUILD_JSON
@@ -198,8 +258,9 @@ function buildJsonDefines(buildJson, isProd) {
 }
 
 /**
- * The globalThis/window assignment every bundle carries.
- * @param {object} buildJson - The blob every bundle bakes.
+ * The globalThis/window assignment the NODE bundles carry. The renderer takes
+ * no banner at all: its snapshot is the one `dist/build.js` its shell loads (#743).
+ * @param {object} buildJson - The blob the node bundles bake.
  * @returns {object} an esbuild banner
  */
 function buildJsonBanner(buildJson) {
@@ -214,6 +275,8 @@ function buildJsonBanner(buildJson) {
 // GOOGLE_ANALYTICS_SECRET read this replaced was one of three hand-kept lists
 // for one concern. A new baked key is one schema entry and nothing here.
 const BAKED_KEYS = bakeKeys('desktop');
+// The same set at the level a HUMAN sets it: what the bake guard judges (#891)
+const BAKED_SOURCE_KEYS = bakeSourceKeys('desktop');
 
 /**
  * The schema's presence rules at the BAKE seam
@@ -228,6 +291,12 @@ const BAKED_KEYS = bakeKeys('desktop');
  * warns and keeps going, because a half-configured brand is a normal step on
  * the way to a configured one.
  *
+ * Only keys this build BAKES are its business
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)): the schema's
+ * other desktop rules are CI-delivered signing credentials, which the deploy
+ * lane owns (the deploy precheck refuses to publish a half set) and which a local
+ * unsigned build has no need of at all.
+ *
  * @param {object} config - The target's resolved omega.json5 config.
  * @param {object} env - The build env.
  * @param {object} [options]
@@ -241,7 +310,7 @@ function assertBakeRules(config, env, options) {
   const warn = (options.logger || logger).warn.bind(options.logger || logger);
 
   const violations = checkEnvRules(config, env, { target: 'desktop' })
-    .filter((violation) => violation.rule === 'requiredWhen');
+    .filter((violation) => violation.rule === 'requiredWhen' && BAKED_SOURCE_KEYS.includes(violation.key));
   if (violations.length === 0) return;
 
   // The BRAND-LEVEL key name (GOOGLE_ANALYTICS_SECRET_DESKTOP, not the
@@ -249,7 +318,7 @@ function assertBakeRules(config, env, options) {
   // in the brand .env and in the repo's Actions secrets.
   const named = violations.map(({ key, path }) => `${key} (required by ${path})`).join(', ');
   const message = `${violations.length} env ${violations.length === 1 ? 'key this brand\'s config requires is' : 'keys this brand\'s config requires are'} missing from the build env: ${named}. `
-    + 'Set it in the brand .env (and as a repo Actions secret for a CI build — `omega push-secrets` sends them), then build again.';
+    + 'Set it in the brand .env (a CI build reads it as a repo Actions secret, which `omega deploy`\'s precheck pushes), then build again.';
 
   if (mode.build || mode.publish) {
     throw new Error(message);
@@ -365,7 +434,7 @@ function rendererEntryKey(rel) {
 /**
  * One browser bundle per `src/assets/js/components/<name>/index.js`, loaded by
  * the page template as a plain `<script src>` — so iife, not esm.
- * @param {object} shared - `{ define, banner, targets, dev }`, composed once per run
+ * @param {object} shared - `{ define, targets, dev }`, composed once per run (no banner: #743)
  * @returns {object|null} `{ name, options }`, or null when the consumer has no entries
  */
 function rendererBundle(shared) {
@@ -412,7 +481,8 @@ function rendererBundle(shared) {
         // a browser bundle leaves it undefined, so it is rewritten textually.
         global: 'globalThis',
       },
-      banner: shared.banner,
+      // No banner and no snapshot define: the renderer reads the ONE
+      // `dist/build.js` its page template loads ahead of it (#743).
       plugins: [emptyModulesPlugin(RENDERER_EMPTY_MODULES)],
     },
   };
@@ -443,8 +513,10 @@ function nativeExternals() {
 // The list behind the renderer's Node-builtin shim (#737) — pinned by
 // src/test/suites/build/renderer-node-shims.test.js.
 module.exports.RENDERER_EMPTY_MODULES = RENDERER_EMPTY_MODULES;
+module.exports.buildFacts = buildFacts;
 module.exports.composeBuildConfig = composeBuildConfig;
 module.exports.composeBuildJson = composeBuildJson;
+module.exports.composeClientBuildJson = composeClientBuildJson;
 module.exports.rendererEntryKey = rendererEntryKey;
 // The schema-derived bake set and its reader (#627).
 module.exports.BAKED_KEYS = BAKED_KEYS;

package/dist/gulp/tasks/release.js

@@ -18,6 +18,11 @@ const Manager = new (require('../../build.js'));
 
 const logger = Manager.logger('release');
 
+// The two warnings electron-publish prints when it uploads nothing: one per
+// release (`gitHubPublisher.getOrCreateRelease` returns null with its reason)
+// and one per file that never left the machine.
+const SKIP_WARNINGS = ['skipped publishing', 'GitHub release not created'];
+
 module.exports = function release(done) {
   const projectRoot = process.cwd();
   const config = path.join(require('../../utils/dist-root.js')(projectRoot), 'electron-builder.yml');
@@ -40,12 +45,25 @@ module.exports = function release(done) {
   const relConfig = path.relative(projectRoot, config);
   logger.log(`Releasing via electron-builder (config=${relConfig}, publish=always)...`);
 
-  builder.build({
+  // electron-publish reports a skipped upload through THIS logger and nowhere
+  // else, and a release that uploaded nothing must never print a success line,
+  // so the logger is a requirement of the task, not a nicety. It comes off
+  // electron-builder's OWN export, which re-exports the one `builder-util`
+  // instance electron-publish writes to: a bare require of `builder-util` names
+  // a package this manifest never declares (#872) and could resolve a SECOND
+  // copy whose log nothing ever writes to.
+  recordSkippedPublishes(builder.log, () => builder.build({
     config,
     publish: 'always',
-  })
-    .then((artifacts) => {
-      const list = (artifacts || []).map((a) => path.relative(projectRoot, a));
+  }))
+    .then(({ result, skips }) => {
+      const skipped = skippedUploadError(skips);
+      if (skipped) {
+        logger.error(skipped.message);
+        return done(skipped);
+      }
+
+      const list = (result || []).map((a) => path.relative(projectRoot, a));
       logger.log(`Released ${list.length} artifact(s):`);
       list.forEach((a) => logger.log(`  • ${a}`));
       done();
@@ -55,3 +73,67 @@ module.exports = function release(done) {
       done(e);
     });
 };
+
+/**
+ * Run the build with electron-builder's OWN logger watched, and hand back what
+ * it published NOTHING for. The promise `build()` returns resolves with the
+ * local artifact paths whether or not a byte was uploaded, so the resolve value
+ * says nothing about the release: the skip is announced only as a warning on
+ * electron-builder's log (the `builder-util` instance it re-exports), carrying
+ * the reason and the tag as fields. The wrapper
+ * is put back in a `finally`, so a build that throws leaves the logger the way
+ * it found it. Exported for tests.
+ *
+ * @param {{ warn: Function }} log - electron-builder's logger.
+ * @param {Function} fn - The build to run.
+ * @returns {Promise<{ result: *, skips: object[] }>} What the build resolved with, and every skip it logged.
+ */
+async function recordSkippedPublishes(log, fn) {
+  const skips = [];
+  const owned = Object.prototype.hasOwnProperty.call(log, 'warn');
+  const original = log.warn;
+
+  log.warn = function (messageOrFields, message) {
+    // `warn(message)` and `warn(fields, message)` are both legal on this logger.
+    const text = String(message === undefined ? messageOrFields : message);
+    const fields = message === undefined ? {} : (messageOrFields || {});
+    if (SKIP_WARNINGS.some((warning) => text.includes(warning))) {
+      skips.push({ message: text, ...fields });
+    }
+    return original.call(this, messageOrFields, message);
+  };
+
+  try {
+    const result = await fn();
+    return { result, skips };
+  } finally {
+    if (owned) {
+      log.warn = original;
+    } else {
+      delete log.warn;
+    }
+  }
+}
+
+/**
+ * The verdict on a build's recorded skips: a release that uploaded nothing is a
+ * failed release, named by electron-builder's own reason. Exported for tests.
+ *
+ * @param {object[]} skips - What recordSkippedPublishes collected.
+ * @returns {Error|null} The failure, or null when everything published.
+ */
+function skippedUploadError(skips) {
+  if (skips.length === 0) {
+    return null;
+  }
+
+  const reason = skips.find((skip) => skip.reason)?.reason || 'electron-builder gave no reason';
+  const tag = skips.find((skip) => skip.tag)?.tag || 'the configured tag';
+  const files = skips.map((skip) => skip.file).filter(Boolean);
+  const what = files.length > 0 ? `${files.length} artifact(s) (${files.join(', ')})` : 'every artifact';
+
+  return new Error(`Nothing was uploaded: electron-builder skipped publishing ${what} to ${tag} (${reason}). Bump the version in package.json: a release that already exists is never re-uploaded.`);
+}
+
+module.exports.recordSkippedPublishes = recordSkippedPublishes;
+module.exports.skippedUploadError = skippedUploadError;

package/dist/gulp/tasks/sass.js

@@ -7,6 +7,7 @@
 //   - <omega-package-root>/dist/assets/css      → resolves bare 'omega-desktop' to omega-desktop.scss
 //   - <omega-package-root>/dist/assets/themes/<active-theme>   → resolves bare 'theme' to <theme>/_theme.scss
 //   - <omega-package-root>/dist/assets/themes   → so themes can reference each other via '../<sibling>'
+//   - <output-root>/assets/scss              → resolves bare 'brand' to the generated _brand.scss (#912)
 //   - <consumer>/src/assets/scss             → consumer's own modules
 
 const Manager = new (require('../../build.js'));
@@ -15,6 +16,7 @@ const path = require('path');
 const jetpack = require('fs-jetpack');
 const sass = require('sass');
 const { formatBytes } = require('../../vendor/devkit/bundle.js');
+const { composeBrandTokens, renderBrandScss } = require('../../vendor/devkit/brand-tokens.js');
 
 const projectRoot = Manager.getRootPath('project');
 const packageRoot = Manager.getRootPath('main');
@@ -25,10 +27,19 @@ module.exports = function sassTask(done) {
   const config = Manager.getConfig() || {};
   const themeId = config.theme?.id || 'classy';
 
+  // The brand partial ([#912](https://github.com/Omega-JS-Stack/omega/issues/912)):
+  // `brand.color` is the ONE accent hex, and it reaches the css through a
+  // GENERATED partial rather than a literal a consumer keeps in sync by hand.
+  // Written before every compile (no color resolves to the framework default,
+  // whose one home is the renderer), so a config edit is the only edit.
+  const brandDir = path.join(outputRoot, 'assets', 'scss');
+  jetpack.write(path.join(brandDir, '_brand.scss'), renderBrandScss(composeBrandTokens(config.brand?.color)));
+
   const loadPaths = [
     path.join(packageRoot, 'dist', 'assets', 'css'),                    // for `@use 'omega-desktop'`
     path.join(packageRoot, 'dist', 'assets', 'themes', themeId),        // for `@use 'theme'`
     path.join(packageRoot, 'dist', 'assets', 'themes'),                 // for sibling-theme references
+    brandDir,                                                           // for `@use 'brand'` (generated above)
     path.join(projectRoot, 'src', 'assets', 'scss'),                    // consumer's own scss tree
   ];
 

package/dist/hooks/lib/notarize-tools.js

@@ -0,0 +1,137 @@
+// The notarization TOOLS: submit, staple, and PROVE, in one place
+// ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)).
+//
+// Proof run one shipped an unsigned, unnotarized mac app on a green build
+// because every rung assumed instead of checking. These three do the opposite:
+// each one reads the tool's own report and throws unless it says the words that
+// mean success. A hook that returns without throwing has PROVED its artifact is
+// notarized, stapled, and accepted by Gatekeeper.
+//
+// Both hooks (afterSign for the .app, artifactBuildCompleted for each .dmg) run
+// every command through the `run` seam a test replaces with a fake `xcrun` /
+// `spctl`; nothing here is global state.
+
+const { spawn } = require('child_process');
+
+// What Gatekeeper is asked about each artifact: an app is EXECUTED, a disk
+// image is OPENED, and a DMG's verdict must come from its own signature rather
+// than from a quarantine-less filesystem (`--context context:primary-signature`).
+const ASSESS_FLAGS = {
+  app: '--type execute',
+  dmg: '--type open --context context:primary-signature',
+};
+
+/**
+ * The default command runner: stdout + stderr of a shell command, in the order
+ * they arrived, WHATEVER the exit code. These tools write their verdict to the
+ * console and exit non-zero when they refuse, so the failure text is the
+ * answer, never an exception to lose (a runner that rejects on exit code
+ * threw the verdict away with it).
+ *
+ * @returns {function(string): Promise<string>}
+ */
+function toolRunner() {
+  return (command) => new Promise((resolve) => {
+    const child = spawn(command, { shell: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '';
+    child.stdout.on('data', (data) => { output += data; });
+    child.stderr.on('data', (data) => { output += data; });
+    child.on('close', () => resolve(output));
+  });
+}
+
+/**
+ * Run a command and hand back its REPORT. A runner that throws (a test's fake)
+ * reports its message.
+ *
+ * @param {function} run - The command runner.
+ * @param {string} command - The command.
+ * @returns {Promise<string>}
+ */
+async function report(run, command) {
+  try {
+    return String(await run(command) || '');
+  } catch (e) {
+    return String(e.message || '');
+  }
+}
+
+/**
+ * Run a command and require its report to SAY it worked.
+ *
+ * @param {object} input
+ * @param {function} input.run - The command runner.
+ * @param {string} input.command - The command.
+ * @param {RegExp} input.expect - What success reads like in the tool's report.
+ * @param {string} input.what - What failed, for the thrown message.
+ * @returns {Promise<string>} The report.
+ * @throws {Error} When the report does not say it worked.
+ */
+async function demand(input) {
+  const { run, command, expect, what } = input;
+  const output = await report(run, command);
+
+  if (!expect.test(output)) {
+    throw new Error(`[notarize] ${what}: ${output.trim() || 'no output'}`);
+  }
+
+  return output;
+}
+
+/**
+ * Submit an artifact to Apple and wait for the verdict. Used for the DMG (the
+ * .app rides @electron/notarize's own submit inside the afterSign hook).
+ *
+ * @param {object} input
+ * @param {string} input.filePath - The artifact.
+ * @param {object} input.credentials - `{ apiKeyPath, apiKeyId, apiIssuer }`.
+ * @param {function} [input.run] - Command runner (test seam).
+ * @returns {Promise<string>} notarytool's report.
+ */
+function submit({ filePath, credentials, run = toolRunner() }) {
+  const { apiKeyPath, apiKeyId, apiIssuer } = credentials;
+
+  return demand({
+    run,
+    command: `xcrun notarytool submit "${filePath}" --key "${apiKeyPath}" --key-id "${apiKeyId}" --issuer "${apiIssuer}" --wait`,
+    expect: /status:\s*Accepted/i,
+    what: `notarization of ${filePath} was not accepted`,
+  });
+}
+
+/**
+ * Staple the notarization ticket to an artifact and PROVE it took: the staple
+ * itself, the stapler's own re-read, and Gatekeeper's assessment. A user's Mac
+ * checks exactly this, offline, before it will open the thing.
+ *
+ * @param {object} input
+ * @param {string} input.filePath - The .app or .dmg.
+ * @param {'app'|'dmg'} input.kind - Which assessment Gatekeeper is asked for.
+ * @param {function} [input.run] - Command runner (test seam).
+ * @returns {Promise<void>}
+ * @throws {Error} When stapling, validation or the assessment fails.
+ */
+async function stapleAndProve({ filePath, kind, run = toolRunner() }) {
+  await demand({
+    run,
+    command: `xcrun stapler staple "${filePath}"`,
+    expect: /The staple and validate action worked!/i,
+    what: `could not staple the notarization ticket to ${filePath}`,
+  });
+
+  await demand({
+    run,
+    command: `xcrun stapler validate "${filePath}"`,
+    expect: /The validate action worked!/i,
+    what: `${filePath} carries no valid notarization ticket after stapling`,
+  });
+
+  await demand({
+    run,
+    command: `spctl --assess ${ASSESS_FLAGS[kind]} -vv "${filePath}"`,
+    expect: /: accepted/i,
+    what: `Gatekeeper refused ${filePath}`,
+  });
+}
+
+module.exports = { submit, stapleAndProve, toolRunner, report, ASSESS_FLAGS };

package/dist/hooks/notarize-artifacts.js

@@ -0,0 +1,57 @@
+// The DMG's own notarization, stapling and proof (electron-builder's
+// `artifactBuildCompleted`, [#891](https://github.com/Omega-JS-Stack/omega/issues/891)).
+//
+// The afterSign hook notarizes and staples the .app, and that ticket rides
+// INSIDE the disk image, not on it: a user who downloads the .dmg has Gatekeeper
+// assess the IMAGE first, and an unstapled image is refused on a Mac that is
+// offline. So every .dmg this build produces is submitted with the same App
+// Store Connect key, stapled, and PROVED (stapler validate + spctl --assess).
+//
+// Per artifact, not after all of them: electron-builder awaits this hook and
+// THEN emits the `artifactCreated` its publisher uploads on, whereas
+// `afterAllArtifactBuild` runs after every upload is already queued (run
+// 34738410986 published a signed, notarized image with no staple that way).
+//
+// Non-mac legs produce no .dmg, so this hook is a no-op there by construction:
+// it reads the artifact's extension, never the platform.
+
+const fs = require('fs');
+const path = require('path');
+const Logger = require('../lib/logger');
+const { submit, stapleAndProve, toolRunner } = require('./lib/notarize-tools.js');
+
+const logger = new Logger('notarize-artifacts');
+
+/**
+ * @param {object} event - electron-builder's artifactBuildCompleted event
+ *   (`{ file, target, arch, packager, ... }`).
+ * @param {object} [options]
+ * @param {function} [options.run] - Command runner (test seam for xcrun/spctl).
+ * @returns {Promise<void>}
+ */
+module.exports = async function notarizeArtifacts(event, { run = toolRunner() } = {}) {
+  const dmg = event.file;
+
+  if (path.extname(dmg).toLowerCase() !== '.dmg') {
+    return;
+  }
+
+  const apiKey    = process.env.APPLE_API_KEY;
+  const apiKeyId  = process.env.APPLE_API_KEY_ID;
+  const apiIssuer = process.env.APPLE_API_ISSUER;
+
+  if (!apiKey || !apiKeyId || !apiIssuer) {
+    throw new Error('[notarize] APPLE_API_KEY, APPLE_API_KEY_ID and APPLE_API_ISSUER are required to notarize the DMG. Run `omega deploy` (its precheck pushes them for CI) or set them in the target .env.');
+  }
+
+  const apiKeyPath = path.isAbsolute(apiKey) ? apiKey : path.resolve(process.cwd(), apiKey);
+  if (!fs.existsSync(apiKeyPath)) {
+    throw new Error(`[notarize] APPLE_API_KEY file not found at ${apiKeyPath}`);
+  }
+
+  logger.log(`Notarizing ${path.basename(dmg)} via App Store Connect API key (${apiKeyId})...`);
+  await submit({ filePath: dmg, credentials: { apiKeyPath, apiKeyId, apiIssuer }, run });
+
+  await stapleAndProve({ filePath: dmg, kind: 'dmg', run });
+  logger.log(`Stapled and verified: stapler validate + spctl --assess both accept ${path.basename(dmg)}.`);
+};