@omega.js/desktop 0.50.0 → 0.51.0

package/docs/signing.md

@@ -5,52 +5,67 @@ Cross-platform code signing reference. Covers macOS (sign + notarize), Windows (
 ## tl;dr
 
 - **macOS production**: Developer ID Application cert + notarization API key. Files in `config/certs/`. Env vars point at them.
-- **Windows production**: EV USB token (self-hosted runner now) or cloud signing (future, pluggable via `platforms.win.signing.strategy`).
+- **Windows production**: EV USB token (self-hosted runner now) or cloud signing (future, pluggable via `platforms.windows.signing.strategy`).
 - **Linux**: No signing for AppImage/deb. Snap/Flatpak have their own pipelines.
 
 ## Where files live
 
+Signing material lives in the SIGNING TREE and is read there, never copied into a target
+([#891](https://github.com/Omega-JS-Stack/omega/issues/891)):
+
 ```
+<company brand>/company/.omega/certificates/apple/   # read FIRST when the brand names a company
+<your brand>/.omega/certificates/apple/              # read second
+  certificates/DEVELOPER_ID_APPLICATION_G2.p12       # what CSC_LINK resolves to
+  certificates/DEVELOPER_ID_INSTALLER_G2.p12         # only for .pkg builds (rare)
+  AuthKey_XXXXXXXXXX.p8                              # what APPLE_API_KEY resolves to
+
 <your-app>/
   build/
-    entitlements.mac.plist             # universal — already in @omega.js/desktop defaults
+    entitlements.mac.plist             # universal, already in @omega.js/desktop defaults
     icon.icns / icon.ico / icon.png    # per-brand
-    certs/                             # gitignored
-      developer-id-application.p12     # universal across team
-      developer-id-installer.p12       # only for .pkg builds (rare)
-      AuthKey_XXXXXXXXXX.p8            # universal across team
-      <app-name>.provisionprofile      # per-app (only if entitlements require)
-  .env                                 # gitignored — env vars referencing config/certs/*
+  config/certs/                        # gitignored, and EMPTY on a developer machine:
+                                       # only a RUNNER writes here, decoding the pushed secrets
+    README.md                          # the ONE tracked file here (#913): it says the above
+  .env                                 # gitignored, and it carries no signing PATH: only
+                                       # CSC_KEY_PASSWORD and the APPLE_* three
 ```
 
+There is no provisioning profile: Developer ID is direct distribution, signed and notarized,
+and needs none.
+
 ## Where the macOS certificate comes from (the lookup order)
 
-A signed build resolves its Developer ID Application certificate in ONE order
-([src/utils/resolve-signing-cert.js](../src/utils/resolve-signing-cert.js), applied at the
-gulp boundary):
+Every desktop boot (the CLI and gulp alike) derives the signing paths ONCE, at the env load
+([src/utils/load-env.js](../src/utils/load-env.js), over `@omega.js/devkit/signing-env`), so
+the build, `omega validate-certs` and the deploy precheck's secret publish all read the same
+answer. `CSC_LINK` resolves in ONE order:
 
 1. **`CSC_LINK`** in the environment — an explicit answer always wins.
-2. **The brand's signing tree** —
-   `<brandRoot>/.omega/certificates/apple/certificates/DEVELOPER_ID_APPLICATION_G2.p12`,
-   where the brand root is the nearest directory at or above the target carrying a `.omega/`.
-   This is the portable/CI path: `@omega.js/manager`'s certificates service produces the
-   tree ([the manager guide](../../../docs/manager/index.md)).
-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). The stamp's target is used as given: it is explicit config, not discovery.
+2. **The COMPANY's tree**, when the brand names a company and that company is on this
+   machine: a brand with a company reuses the company tree first, always
+   ([#677](https://github.com/Omega-JS-Stack/omega/issues/677)). A brand is NEVER physically
+   inside its company folder: membership is its `company: { id }` key, resolved through
+   `@omega.js/config`'s `resolveCompany` (the ecosystem's one company rule), and the
+   certificate is one more relative path through that resolver's `file()`:
+   `<company>/company/.omega/certificates/apple/certificates/DEVELOPER_ID_APPLICATION_G2.p12`.
+3. **The brand's own signing tree**:
+   `<brandRoot>/.omega/certificates/apple/certificates/DEVELOPER_ID_APPLICATION_G2.p12`.
+   `@omega.js/manager`'s certificates service produces the tree
+   ([the manager guide](../../../docs/manager/index.md)).
 4. **The macOS Keychain** — electron-builder's own identity auto-discovery.
 
+`APPLE_API_KEY` follows the same order for `AuthKey_<APPLE_API_KEY_ID>.p8` (an unset id means
+there is no filename to look for). Both derived values are ABSOLUTE paths into the tree.
+
 **Keychain stays the default.** A project with no signing tree resolves to it exactly as
 before. Two further conditions keep a build on the Keychain rather than handing
 electron-builder a file it cannot use: no `CSC_KEY_PASSWORD` in the `.env` cascade, or a
 password that does not OPEN the `.p12` (verified with `openssl pkcs12 -legacy`, retried
 without the flag for LibreSSL — stock macOS openssl — which reads legacy containers but
 rejects the flag; a missing openssl is named as the reason rather than blamed on the
-password). The build log names the source it picked, and the reason, on every run.
-
-The brand-root walk stops **below the home directory**: `~/.omega` is a real personal
-overlay on developer machines, so a tree at or above `~` is never a signing tree.
+password). Either case prints one line naming the file and the reason, and leaves the key
+unset rather than failing the build silently.
 
 The password itself never lives in config: `CSC_KEY_PASSWORD` comes from the `.env`
 cascade (the manager's certificates service writes it to the signing root's `.env`),
@@ -110,11 +125,13 @@ npx omega validate-certs
 ```
 
 This checks:
-- macOS Keychain has a Developer ID Application identity
 - `CSC_LINK` exists and is readable
+- macOS Keychain has a Developer ID Application identity, and ONLY when `CSC_LINK` names no certificate: electron-builder imports a `CSC_LINK` `.p12` into its own temporary keychain, so the login keychain says nothing about that build
 - API key file exists and `APPLE_API_KEY_ID` + `APPLE_API_ISSUER` are set
 - Team ID matches the cert
 
+The electron-builder floor is 26.16.1 (the package's peer range, installed by ensure-target for any consumer below it): every earlier build hands the `.p12` password to `security set-key-partition-list`, which wants the temporary keychain's own password, and the macos-26 runner image rejects the mismatch (electron-userland/electron-builder#10066, [#891](https://github.com/Omega-JS-Stack/omega/issues/891)).
+
 ### 5. Build + notarize
 
 ```bash
@@ -141,8 +158,15 @@ Buy an EV code-signing cert from Sectigo, DigiCert, SSL.com, etc. Get a physical
 
 Setting the box up is [`docs/runner.md`](runner.md) — the runner home, the Startup-folder auto-start, the commands, and the Session 0 / Session 1 rule that makes the whole thing work.
 
+**A workflow that targets this runner fires only on dispatch**, and the box enforces it ([#875](https://github.com/Omega-JS-Stack/omega/issues/875)). Whoever can start a job on the signing box can sign binaries with your token, so two guards stand between a stray trigger and `signtool`:
+
+- The generated `windows-sign` job runs only on `workflow_dispatch`, the one trigger the file carries (#923). A `push` or `pull_request` trigger added to `build.yml` later SKIPS the sign job instead of signing what it built.
+- The runner itself refuses the job before its first step. `npx omega runner install` writes `job-started.js` beside the runner and points every registration's `ACTIONS_RUNNER_HOOK_JOB_STARTED` at it; the hook exits nonzero, failing the job with one line, unless the event is a dispatch, `GITHUB_REPOSITORY` is on `allowed-repos.txt` and `GITHUB_ACTOR` is on `allowed-actors.txt`. Both lists live on the box and are yours to edit ([`docs/runner.md`](runner.md) § One-time setup).
+
 `npx omega sign-windows` is the strategy-aware command that drives `signtool` (or the cloud provider CLI).
 
+Every signed artifact is verified before the job moves on, and the log says so in the mac lane's shape: `Signed and verified: signtool verify /pa accepts <file>.` mirrors macOS's `Stapled and verified: ...`, so a deploy log proves the Windows signature was checked rather than only claimed ([#918](https://github.com/Omega-JS-Stack/omega/issues/918)). A failing verify aborts the job.
+
 ### Cloud signing (future migration)
 
 Once the framework's cloud strategy is finalized, set the provider in `config/omega.json5`:
@@ -163,22 +187,25 @@ If no signing runner is available, CI uploads the unsigned `.exe` and a develope
 
 ## Pushing secrets to GitHub Actions
 
-@omega.js/desktop ships a command that pushes the target's **composed env** to the repo's GitHub Actions secrets over the same shared `gh` transport that the web and extension publish verbs use (`gh secret set`, which seals each value with the repo's public key locally): values travel on **stdin**, never in argv, and are never logged. For env vars whose value is a path to a local file (`.p12`, `.p8`, etc.), the secret value pushed is the **base64-encoded file contents** — the workflow decodes back to a temp file at job start.
+`omega deploy`'s precheck pushes the target's **composed env** to the repo's GitHub Actions secrets over the same shared `gh` transport the other three frameworks use (`gh secret set`, which seals each value with the repo's public key locally): values travel on **stdin**, never in argv, and are never logged. For env vars whose value is a path to a local file (`.p12`, `.p8`, etc.), the secret value pushed is the **base64-encoded file contents**: the workflow decodes back to a temp file at job start.
+
+There is no standalone `omega push-secrets` verb ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)): the push happens where it matters, and the manage walk's `repo` service runs the same function when you want a brand brought current without deploying.
 
 ```bash
-# Make sure the brand root's .env holds your signing creds, and that `gh auth login` has run
-npx omega push-secrets
+# Make sure the brand root's .env holds CSC_KEY_PASSWORD + the APPLE_* three, and `gh auth login` has run
+npx omega deploy
 
-# Push only specific keys
-npx omega push-secrets --only=CSC_LINK,CSC_KEY_PASSWORD
+# See exactly what it would publish, and publish nothing
+npx omega deploy --dry-run
 ```
 
 Behavior:
 - The source is `composeTargetEnv({ targetDir, target: 'desktop' })`: company `.env` ← brand `.env` ← target `.env`, the brand-side layers filtered by the env schema to the keys the desktop target reads. The brand root's `.env` is the one file you keep; a target `.env` is an optional per-key override.
 - Files only — the shell is never a source — and an empty value never claims a key, so unset keys simply don't publish.
 - Auto-detects "is this a path?" — relative or absolute paths ending in `.p12`/`.pem`/`.cer`/`.p8`/`.provisionprofile`/`.crt`/`.key`/`.json` that exist on disk (target root first, brand root second) get base64-encoded.
-- Publishes to the git remote's `owner/repo`, and REFUSES unless the brand's own config claims it (`repo.providers.github`) — a fork, a template clone or a vendored target never arms a stranger's Actions with your certificates.
+- Publishes to the brand's SOURCE repo (`repo.org` + `brand.id` → `<brand.id>-omega`), and REFUSES unless the checkout's own remote IS that repo: a fork, a template clone or a vendored target never arms a stranger's Actions with your certificates.
 - No PAT: the credential is `gh`'s auth session. A missing or signed-out `gh` fails loudly with install/auth instructions; a CI run, an empty cascade, a remote-less checkout or a repo mismatch skips loudly.
+- `CSC_LINK` and `APPLE_API_KEY` are DERIVED, never typed ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)): the env load resolved them from the signing tree, so the publish sends those files' bytes. A typed value still wins, and a key the config REQUIRES that neither the tree nor the `.env` answers STOPS the deploy (the step is `fatal`), naming both tier paths it looked in and `omega manage --service certificates`, publishing nothing.
 - Logs key NAMES only; never a value.
 
 The corresponding decode step in CI looks like:
@@ -211,7 +238,6 @@ GitHub Actions secrets you'll need (per repo):
 | Secret | Purpose |
 |---|---|
 | `GH_TOKEN` | Cross-repo publish, secret rotation |
-| `OMEGA_ADMIN_KEY` | Privileged backend API calls |
 | `CSC_LINK` | base64-encoded `.p12` (workflow decodes to file) |
 | `CSC_KEY_PASSWORD` | `.p12` password |
 | `APPLE_API_KEY` | base64-encoded `.p8` |
@@ -251,7 +277,7 @@ The workflow base64-decodes secrets into temp files inside `config/certs/` at jo
 
 ### Windows: "SignTool Error: No certificates were found"
 - Token unplugged or middleware not running.
-- For cloud: verify `platforms.win.signing.cloud.provider` in `config/omega.json5` matches the provider whose creds are in `.env`.
+- For cloud: verify `platforms.windows.signing.cloud.provider` in `config/omega.json5` matches the provider whose creds are in `.env`.
 
 ## What lives in `build/`
 

package/docs/test-framework.md

@@ -45,6 +45,7 @@ npx omega test --filter="storage"       # only suites/tests whose name contains
 npx omega test --extended               # opt into extended mode — real external APIs (also: TEST_EXTENDED_MODE=true)
 npx omega test --reporter=json          # pretty output + machine-readable {"event":"summary",...} line
 OMEGA_TEST_DEBUG=1 npx omega test          # see Electron stderr (otherwise drained silently)
+OMEGA_TEST_BOOT_TIMEOUT_MS=120000 npx omega test   # the boot lane's budget (default 60s)
 ```
 
 In @omega.js/desktop itself, `npm test` runs the framework's own suite — the self-test context flips the no-target default.
@@ -104,13 +105,13 @@ A target that names a path and matches NO file is a hard error: the run prints `
 
 ### Extended vs normal mode
 
-Suites that hit a live backend (Firebase Auth admin SDK, real GitHub API, etc.) are gated behind **extended mode** — `npx omega test --extended` or `TEST_EXTENDED_MODE=true`. `TEST_EXTENDED_MODE` is the **shared, unprefixed env var across @omega.js/backend, @omega.js/extension, UJM, and @omega.js/desktop** (cross-framework parity) — once set on `process.env` it propagates to every spawned test environment (the Electron main/renderer/boot children, the gulp boot build) automatically via `{ ...process.env }`. These external calls are **skipped in-source, NOT mocked** — the suite short-circuits / `ctx.skip()`s when `TEST_EXTENDED_MODE` is unset; with it set, it calls the real service. Default is to skip them so `npx omega test` is fast + green offline, and a warning prints when extended mode is on. The CI workflow runs normal mode by default; add a separate workflow that sets `TEST_EXTENDED_MODE: 'true'` for extended coverage.
+Suites that hit a live backend (a real GitHub API call, a store publish, etc.) are gated behind **extended mode**: `npx omega test --extended` or `TEST_EXTENDED_MODE=true`. `TEST_EXTENDED_MODE` is the **shared, unprefixed env var across @omega.js/backend, @omega.js/extension, UJM, and @omega.js/desktop** (cross-framework parity): once set on `process.env` it propagates to every spawned test environment (the Electron main/renderer/boot children, the gulp boot build) automatically via `{ ...process.env }`. These external calls are **skipped in-source, NOT mocked**: the suite short-circuits / `ctx.skip()`s when `TEST_EXTENDED_MODE` is unset; with it set, it calls the real service. Default is to skip them so `npx omega test` is fast + green offline, and a warning prints when extended mode is on. The CI workflow runs normal mode by default; add a separate workflow that sets `TEST_EXTENDED_MODE: 'true'` for extended coverage.
 
 Anything an extended suite creates externally must be torn down in its `cleanup(ctx)` — the harness only resets local Electron state between runs, never external systems.
 
-### `OMEGA_TEST_MODE=true` — the canonical "we're in tests" signal
+### `OMEGA_ENVIRONMENT=testing`, the one input a test run names
 
-Both @omega.js/desktop test runners (`runners/electron.js`, `runners/boot.js`) set `OMEGA_TEST_MODE=true` in the spawned child env. That powers `manager.isTesting()` (and `Manager.isTesting()` static) — the cross-context helper everything in @omega.js/desktop checks when it needs to behave differently in tests:
+Both @omega.js/desktop test runners (`runners/electron.js`, `runners/boot.js`) spawn their child with `OMEGA_ENVIRONMENT=testing`, the ONE environment input ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)), and nothing writes over an explicit one: the word a build baked into the artifact is the fallback for a packaged app, never an override ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)). That powers `manager.isTesting()` (and the `Manager.isTesting()` static), the cross-context helper everything in @omega.js/desktop checks when it needs to behave differently in tests:
 
 - `auto-updater` flips its idle threshold from 15min → 3s and its periodic tick from 60s → 500ms, AND short-circuits the native install-prompt dialog (so tests don't pop modal windows).
 - **Every BrowserWindow surfaces stealth** — named windows via `window-manager._surface()` AND raw `new BrowserWindow()` ones (e.g. a consumer's automation popup) via a global `browser-window-created` hook registered in `main.js` step 1a-ii. The shared recipe lives in `src/utils/stealth-window.js`: shown INACTIVE (keyboard focus never leaves your editor), opacity 0, click-through (`setIgnoreMouseEvents`), and raw windows get `show()` rerouted to `showInactive()` + `focus()` no-op'd — a test run never interrupts you, and a stray real click physically can't land in the app, while synthetic test input (`executeJavaScript`, `sendInputEvent`, CDP) is unaffected. **`webContents.focus()` is suppressed separately** (a global `web-contents-created` hook in the same main.js block): it bypasses the window-level patches — it's a different object whose `focus()` reaches the native window directly and makes the invisible window KEY, grabbing the keyboard mid-typing even under the accessory policy (which only prevents *launch* activation, not key-window steals). Consumers call it legitimately (e.g. address-bar focus on tab select), so it's no-op'd per-contents under the same predicate. Set **`OMEGA_TEST_SHOW=1`** to surface windows normally and watch a run live (the predicate is evaluated per window, so flipping it mid-run works). Deliberately NOT `hide()`/`minimize()`: occluded windows get throttled by Chromium (`requestAnimationFrame` pauses, `document.visibilityState` flips to `hidden`) — tests would exercise a DIFFERENT runtime, whereas an opacity-0 shown-inactive window renders and behaves identically to a visible one. See [windows.md](windows.md).
@@ -119,9 +120,9 @@ Both @omega.js/desktop test runners (`runners/electron.js`, `runners/boot.js`) s
 - **The main-layer harness exposes a CDP endpoint.** `test/harness/main-entry.js` appends `--remote-debugging-port=0` at require time (loopback-only, OS-assigned port) and publishes the resolved port as **`process.env.OMEGA_CDP_PORT`** before suites run (read from Chromium's `DevToolsActivePort` file; any value inherited from your shell is overwritten — that one points at your dev app, not the harness). Consumer suites can drive real browser automation against the harness Electron itself, e.g. `playwright-core`'s `connectOverCDP('http://127.0.0.1:' + process.env.OMEGA_CDP_PORT)`. Covered by `suites/main/harness-cdp.test.js`.
 - Other lib code can branch on `manager.isTesting()` to suppress dock bounce, login-item changes, OS protocol-handler registration, etc.
 
-Consumers writing their own tests should set `OMEGA_TEST_MODE=true` in their test runner so the same signal applies — for example, in `package.json`:
+Consumers writing their own tests name the same input in their own runner, for example in `package.json`:
 ```json
-"test": "OMEGA_TEST_MODE=true vitest"
+"test": "OMEGA_ENVIRONMENT=testing vitest"
 ```
 Then in your code, gate test-only behavior on `manager.isTesting()` instead of inventing yet another env var.
 
@@ -295,6 +296,10 @@ All test output is also teed (ANSI-stripped) to `<projectRoot>/logs/test.log`, t
 - `ELECTRON_RUN_AS_NODE` is stripped from the spawn env (would otherwise make Electron behave as Node and break the harness).
 - **Consumer-scheme containment.** The consumer's `main.js` — where the real `protocol.handle('<brand.id>', …)` lives — never runs in this harness, so `brand://` URLs loaded by main-layer suites would be UNHANDLED. Chromium treats a load on an unhandled scheme as an *external protocol* and hands it to the OS — and if an installed copy of the app owns the scheme (e.g. `/Applications/Brand.app` on macOS, registered via its `Info.plist`), Launch Services launches the installed production app mid-test-run. The harness contains this two ways after Manager boots: (1) it registers a stub handler for the consumer's brand scheme (read from `<cwd>/config/omega.json5`) on the default session, so `brand://` loads commit in-process as a blank page; (2) it denies the `openExternal` permission on the default session and every session created after it (partitions included), so no navigation can hand ANY scheme to the OS during a test run. Suites that need real page content for `brand://` URLs belong in the boot layer, where the real app (and its real protocol handler) runs. A main-layer suite that genuinely needs its OWN handler for the brand scheme must call `protocol.unhandle(brand.id)` first — the harness stub holds the scheme on the default session.
 
+## A test run never touches the OS keychain, and a blocked boot reports
+
+The harness resolves auth persistence to the **`none`** strategy on every layer, main and boot alike, before any config is read: a brand that declares `omega.authPersistence: 'safeStorage'` still runs its tests with Firebase auth in memory, because the lanes never sign a real user in. That is a hard rule, not a nicety. The boot lane spawns the raw, unsigned `Electron` binary, which carries no keychain ACL, so one `safeStorage` read parks the entire run behind a macOS SecurityAgent prompt ([#907](https://github.com/Omega-JS-Stack/omega/issues/907)). ONE signal answers "is this a test run" on both layers, `manager.isTesting()`: the boot lane boots the consumer's PRODUCTION artifact, and the word baked into it no longer writes over the `OMEGA_ENVIRONMENT=testing` the runner spawned it with ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)), so the booted app reports the lane it is running in. And since a boot can block long before `main.js` requires the harness (where the per-test timeout lives), the boot runner carries its own budget, measured as SILENCE: every harness line rearms it, so a suite that legitimately runs longer keeps going, and a boot that produces no harness output for 60s (`OMEGA_TEST_BOOT_TIMEOUT_MS` overrides) counts its tests failed, prints `✗ boot: no harness output after 60s; last runtime.log line: "<line>"` from the booted app's `logs/runtime.log`, and ends the child instead of hanging `npx omega test`.
+
 ## Writing consumer tests
 
 In a consumer project, drop files in `test/` (or `test/**`):

package/docs/themes.md

@@ -19,18 +19,32 @@ The active theme is selected via `config.theme.id` (default `'classy'`). The `gu
 Your `src/assets/scss/main.scss` becomes:
 
 ```scss
+// Generated from `brand.color` in config/omega.json5 by the sass task.
+@use 'brand';
+
 @use 'omega-desktop' as * with (
-  $primary: #2563EB,
+  $primary: brand.$primary,
   // $secondary: #6C757D,
   // $border-radius: 0.5rem,
 );
 
+// The runtime --omega-accent ramp, AFTER the framework import so it wins the
+// cascade over the token sheet's placeholders.
+@include brand.ramp;
+
 // Custom global styles below...
 main {
   padding: 2rem;
 }
 ```
 
+`$primary` is `brand.color`, not a literal: the sass task writes
+`dist/assets/scss/_brand.scss` from the resolved config before every compile, so
+recoloring the app is a config edit. Want an accent that DIVERGES from the
+brand? Put the literal back in its place: `$primary: #2563EB,`. No `brand.color`
+set at all, and the partial carries the framework default
+([shared/theming.md](shared/theming.md), [#912](https://github.com/Omega-JS-Stack/omega/issues/912)).
+
 That single import gives you:
 - Full Bootstrap 5 (utilities, components, grid, etc.)
 - Classy theme overlays (typography, animations, refined spacing)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omega.js/desktop",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "OMEGA desktop framework — build, test, and package Electron apps for macOS, Windows, and Linux",
   "private": false,
   "publishConfig": {
@@ -17,6 +17,7 @@
     "./build": "./dist/build.js",
     "./test": "./dist/test/index.js",
     "./hooks/notarize": "./dist/hooks/notarize.js",
+    "./hooks/notarize-artifacts": "./dist/hooks/notarize-artifacts.js",
     "./lib/app-state": "./dist/lib/app-state.js",
     "./lib/auto-updater": "./dist/lib/auto-updater.js",
     "./lib/context-menu": "./dist/lib/context-menu.js",
@@ -35,13 +36,13 @@
     "./lib/client-bridge": "./dist/lib/client-bridge.js",
     "./lib/window-manager": "./dist/lib/window-manager.js",
     "./cli": "./dist/cli-run.js",
+    "./ensure-target": "./dist/commands/lib/ensure-target.js",
     "./scripts/sync-nvmrc": "./scripts/sync-nvmrc.js"
   },
   "bin": {
     "omega": "./bin/omega",
     "omg": "./bin/omg",
-    "mgr": "./bin/omega",
-    "omega-desktop": "./bin/omega-desktop"
+    "mgr": "./bin/omega"
   },
   "files": [
     "bin/",
@@ -56,8 +57,8 @@
     "replace": {},
     "hooks": {
       "after": [
-        "node -e \"require('@omega.js/devkit/vendor')()\"",
-        "node -e \"require('@omega.js/devkit/prepare-guard').rewire()\""
+        "node -e \"require('@omega.js/devkit/prepare-guard').rewire()\"",
+        "node -e \"require('@omega.js/devkit/vendor')()\""
       ],
       "afterBlocking": true
     }
@@ -89,14 +90,19 @@
         "package": "@omega.js/web",
         "from": "themes",
         "to": "assets/themes"
+      },
+      {
+        "package": "@omega.js/devkit",
+        "from": "src/test/fixtures/esm-only-package",
+        "to": "vendor/devkit/test/fixtures/esm-only-package"
       }
     ]
   },
   "scripts": {
     "start": "npm run prepare:watch",
-    "prepare": "node -e \"require('@omega.js/devkit/prepare-guard')() && require('prepare-package')()\"",
+    "prepare": "node -e \"require('../devkit/tools/prepare-guard').run()\"",
     "prepare:watch": "node -e \"require('prepare-package/watch')()\"",
-    "test": "node ./bin/omega-desktop test"
+    "test": "node ./bin/omega test"
   },
   "projectScripts": {
     "start": "omega clean && npm run gulp --",
@@ -130,7 +136,7 @@
   "license": "Elastic-2.0",
   "peerDependencies": {
     "electron": ">=42",
-    "electron-builder": ">=26",
+    "electron-builder": ">=26.16.1",
     "gulp": "^5.0.1"
   },
   "devDependencies": {
@@ -141,7 +147,7 @@
     "@omega.js/monitoring": "*",
     "@omega.js/web": "*",
     "electron": "^42.0.1",
-    "electron-builder": "^26.8.1",
+    "electron-builder": "^26.16.1",
     "firebase-admin": "^13.9.0",
     "prepare-package": "^2.2.0"
   },
@@ -149,7 +155,7 @@
     "@fortawesome/fontawesome-free": "^7.3.0",
     "@inquirer/prompts": "^8.5.2",
     "@octokit/rest": "^22.0.1",
-    "@omega.js/client": "0.50.0",
+    "@omega.js/client": "0.51.0",
     "@popperjs/core": "^2.11.8",
     "@sentry/electron": "^7.13.0",
     "chalk": "^5.6.2",
@@ -172,11 +178,11 @@
     "node-powertools": "^3.0.0",
     "plist": "^4.0.0",
     "sass": "^1.99.0",
+    "sharp": "^0.35.3",
     "uuid": "^14.0.0",
     "wonderful-fetch": "^2.0.5",
     "wonderful-version": "^1.3.2",
-    "ws": "^8.20.0",
-    "yargs": "^18.0.0"
+    "ws": "^8.20.0"
   },
   "optionalDependencies": {
     "automately": "^1.0.5"

package/bin/omega-desktop

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-require('../dist/cli-run.js').run();

package/dist/commands/push-secrets.js

@@ -1,141 +0,0 @@
-/**
- * The `.env` → GitHub Actions secrets publisher for the desktop target.
- *
- * Since [#682](https://github.com/Omega-JS-Stack/omega/issues/682) this is a
- * BIND of `@omega.js/devkit/target-secrets`, exactly as web and the extension
- * are: the same derive (the schema's desktop delivery set, #627) → collect (the
- * COMPOSED target env, company ← brand ← target, files only, #678) → guard (the
- * brand's DECLARED repo, never an inferred remote) → publish, over the ONE `gh`
- * transport (values on stdin, never logged), with the same five loud skips. It
- * used to run @octokit/rest + libsodium-wrappers itself on a GH_TOKEN PAT the
- * consumer had to mint; `gh`'s own auth session is the credential now and the
- * sealed-box crypto is the CLI's.
- *
- * What is desktop's OWN is the value resolver, the seam the shared publisher
- * applies between collect and publish: a desktop secret can name a FILE
- * (`CSC_LINK=config/certs/dev-id.p12`, `APPLE_API_KEY=.omega/secrets/key.p8` —
- * target-root relative, falling back to the brand root), and CI needs the
- * BYTES, so an existing file publishes as its base64 contents. The workflow
- * decodes it back to a temp file at job start.
- *
- * Usage:
- *   npx omega push-secrets                       # push every composed desktop key
- *   npx omega push-secrets --only=GH_TOKEN,CSC_LINK
- */
-
-const path = require('path');
-const fs = require('fs');
-
-const Manager = new (require('../build.js'));
-const logger = Manager.logger('push-secrets');
-const { collectTargetSecrets, declaredBrandRepo: declaredRepoFor, publishTargetSecrets } = require('../vendor/devkit/target-secrets.js');
-const { findBrandRoot } = require('../vendor/config/index.js');
-
-const TARGET = 'desktop';
-
-module.exports = async function (options) {
-  options = options || {};
-
-  return publishEnvSecrets({
-    targetDir: process.cwd(),
-    logger,
-    only: options.only,
-  });
-};
-
-/**
- * Desktop's value seam: base64 for a value that names an existing file, the
- * value itself otherwise, and null for a key `--only` leaves out (the publisher
- * drops a falsy value, the same way it drops an empty composed one).
- *
- * @param {object} options
- * @param {string} options.targetDir - The target root.
- * @param {string} [options.only] - Comma-separated key names to narrow to.
- * @returns {function} `(value, key) => string|null`
- */
-function fileValueResolver(options) {
-  const { targetDir } = options;
-  const only = options.only ? String(options.only).split(',').map((s) => s.trim()).filter(Boolean) : null;
-  const brandRoot = findBrandRoot(targetDir);
-
-  return (value, key) => {
-    if (only && !only.includes(key)) return null;
-    return fileContentsBase64(value, { targetDir, brandRoot }) || value;
-  };
-}
-
-// The base64 contents of the file `value` names, or null when it names none.
-// Heuristic: a path-shaped value (a separator, or a typical cert/key extension)
-// that resolves to a real file under the target root or the brand root. A
-// path-shaped value that exists nowhere is pushed as-is — it is a string.
-function fileContentsBase64(value, { targetDir, brandRoot }) {
-  const looksLikePath = /[/\\]/.test(value) || /\.(p12|pem|cer|p8|provisionprofile|crt|key|json)$/i.test(value);
-  if (!looksLikePath) return null;
-
-  const roots = path.isAbsolute(value) ? [''] : [targetDir, brandRoot].filter(Boolean);
-  for (const root of roots) {
-    const absolute = path.isAbsolute(value) ? value : path.join(root, value);
-    if (fs.existsSync(absolute) && fs.statSync(absolute).isFile()) {
-      return fs.readFileSync(absolute).toString('base64');
-    }
-  }
-
-  return null;
-}
-
-/**
- * The publishable secrets: the schema's desktop delivery set, valued from the
- * composed env with file-path values resolved to their base64 contents. An
- * empty value never claims a key.
- *
- * @param {string} targetDir - The target root (its .env is the local layer).
- * @param {object} [options]
- * @param {string} [options.only] - Comma-separated key names to narrow to.
- * @returns {Object<string, string>} key → value, ready to publish.
- */
-function collectEnvSecrets(targetDir, options) {
-  return collectTargetSecrets({
-    targetDir,
-    target: TARGET,
-    resolveValue: fileValueResolver({ targetDir, only: (options || {}).only }),
-  });
-}
-
-/**
- * The brand's OWN repo as `owner/name`, from the composed config. Null when the
- * config declares nothing usable or doesn't load.
- *
- * @param {string} targetDir - The target root.
- * @returns {string|null}
- */
-function declaredBrandRepo(targetDir) {
-  return declaredRepoFor({ targetDir, target: TARGET });
-}
-
-/**
- * The `omega deploy` precheck step: publish the target's composed values as
- * repo Actions secrets.
- *
- * @param {object} options
- * @param {string} options.targetDir - The target root.
- * @param {object} options.logger - `{ log, warn, error }`.
- * @param {object} [options.env] - Env map (default: process.env).
- * @param {string} [options.only] - Comma-separated key names to narrow to (`--only`).
- * @param {function} [options.execFn] - Injectable `gh` exec (tests).
- * @param {function} [options.gitExecFn] - Injectable `git` exec for remote discovery (tests).
- * @returns {{ skipped: string }|{ published: string[], failed: Array<object> }}
- */
-function publishEnvSecrets(options) {
-  options = options || {};
-
-  return publishTargetSecrets({
-    ...options,
-    target: TARGET,
-    resolveValue: fileValueResolver({ targetDir: options.targetDir, only: options.only }),
-  });
-}
-
-module.exports.collectEnvSecrets = collectEnvSecrets;
-module.exports.declaredBrandRepo = declaredBrandRepo;
-module.exports.fileValueResolver = fileValueResolver;
-module.exports.publishEnvSecrets = publishEnvSecrets;

package/dist/test/suites/build/deliver-certs.test.js

@@ -1,95 +0,0 @@
-// deliver-certs — the Apple artifacts reach the target's certs dir on every
-// verb, not only on a manager `manage` run
-// ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)).
-//
-// The copy rules are devkit's; what is pinned here is desktop's framing: which
-// root holds the signing tree (company stamp wins over the brand root) and the
-// no-op when there is no tree at all.
-
-const path = require('path');
-const fs = require('fs');
-const os = require('os');
-const jetpack = require('fs-jetpack');
-
-const { deliverTargetCerts, resolveSourceRoot } = require('../../../utils/deliver-certs.js');
-const defineCases = require('../../../vendor/devkit/test/define-cases.js');
-
-const P12 = path.join('.omega', 'certificates', 'apple', 'certificates', 'DEVELOPER_ID_APPLICATION_G2.p12');
-const quiet = { log() {}, warn() {}, error() {} };
-
-// A brand root with a desktop target under it; `tree` seeds the signing tree.
-function stageBrand({ tree = true, companyTree = false } = {}) {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-certs-'));
-  const brandRoot = path.join(root, 'brand');
-  const targetDir = path.join(brandRoot, 'targets', 'desktop');
-
-  jetpack.write(path.join(brandRoot, 'config', 'omega.json5'), "{ brand: { id: 'acme', name: 'Acme', url: 'https://acme.test' }, targets: { desktop: {} } }\n");
-  jetpack.dir(targetDir);
-  if (tree) jetpack.write(path.join(brandRoot, P12), 'brand-cert');
-
-  if (companyTree) {
-    const companyRoot = path.join(root, 'company');
-    jetpack.write(path.join(companyRoot, P12), 'company-cert');
-    jetpack.write(path.join(brandRoot, '.omega', 'company.json'), JSON.stringify({ root: companyRoot }));
-    return { root, brandRoot, companyRoot, targetDir };
-  }
-
-  return { root, brandRoot, targetDir };
-}
-
-module.exports = defineCases({
-  type: 'group',
-  layer: 'build',
-  description: 'deliver-certs — signing artifacts on every verb (#678)',
-  tests: [
-    {
-      name: 'the brand tree delivers into the target certs dir, and the rerun is current',
-      run: (ctx) => {
-        const { root, targetDir } = stageBrand();
-
-        try {
-          const first = deliverTargetCerts({ projectDir: targetDir, logger: quiet });
-          ctx.expect(first.copied).toContain('config/certs/developer-id-application.p12');
-          ctx.expect(jetpack.read(path.join(targetDir, 'config', 'certs', 'developer-id-application.p12'))).toBe('brand-cert');
-          // Signing material can never be committed
-          ctx.expect(jetpack.read(path.join(targetDir, 'config', 'certs', '.gitignore'))).toContain('*');
-
-          const second = deliverTargetCerts({ projectDir: targetDir, logger: quiet });
-          ctx.expect(second.copied).toEqual([]);
-          ctx.expect(second.current).toContain('config/certs/developer-id-application.p12');
-        } finally {
-          fs.rmSync(root, { recursive: true, force: true });
-        }
-      },
-    },
-    {
-      name: 'the COMPANY stamp wins the source root — company-managed brands share the material',
-      run: (ctx) => {
-        const { root, brandRoot, companyRoot, targetDir } = stageBrand({ companyTree: true });
-
-        try {
-          ctx.expect(resolveSourceRoot(targetDir)).toBe(companyRoot);
-          ctx.expect(resolveSourceRoot(targetDir)).not.toBe(brandRoot);
-
-          deliverTargetCerts({ projectDir: targetDir, logger: quiet });
-          ctx.expect(jetpack.read(path.join(targetDir, 'config', 'certs', 'developer-id-application.p12'))).toBe('company-cert');
-        } finally {
-          fs.rmSync(root, { recursive: true, force: true });
-        }
-      },
-    },
-    {
-      name: 'no signing tree → a silent no-op, never a throw (the normal state of a tree-less brand)',
-      run: (ctx) => {
-        const { root, targetDir } = stageBrand({ tree: false });
-
-        try {
-          ctx.expect(deliverTargetCerts({ projectDir: targetDir, logger: quiet })).toBe(null);
-          ctx.expect(jetpack.exists(path.join(targetDir, 'config', 'certs'))).toBe(false);
-        } finally {
-          fs.rmSync(root, { recursive: true, force: true });
-        }
-      },
-    },
-  ],
-});