@omega.js/desktop 0.1.0

package/docs/releasing.md

@@ -0,0 +1,229 @@
+# Releasing — From `.env` to GitHub Release
+
+End-to-end walkthrough for cutting a signed + notarized + published release of an OMEGA Desktop app.
+
+## Repo layout (private app, ONE public releases repo)
+
+@omega.js/desktop separates the app from its binaries:
+
+| Repo | Visibility | Purpose |
+|---|---|---|
+| `<owner>/<app>` | usually **private** | the app source code |
+| `<owner>/<brand.id>-releases` | **public** | release artifacts + auto-update feed (`latest-mac.yml` etc.) — AND the marketing site's direct-download links |
+
+Why: auto-update feeds and marketing downloads MUST be publicly accessible (no auth headers in `electron-updater` or in an `<a href>`). Your app source can stay private; the public repo contains only binaries.
+
+ONE public repo answers both ([#620](https://github.com/Omega-JS-Stack/omega/issues/620)), because the assets carry no version — see [Versionless assets](#versionless-assets-and-direct-download-links) below.
+
+**Its address has ONE home** ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)): `@omega.js/config`'s `releasesRepo`, which defaults the name to `<brand.id>-releases` and the owner to the brand repo's own owner. Every reader takes it from there: the electron-builder publish block the build bakes into `app-update.yml`, the deploy precheck's repo provisioning, `finalize-release`'s uploads, and the website's download buttons. Nothing reads a git remote, so a target inside a brand monorepo (and a brand nested in another repo) addresses its own repo rather than the enclosing one.
+
+`npx omega deploy`'s precheck auto-creates the public repo if it doesn't exist (uses `GH_TOKEN`). Override the defaults in `config/omega.json5` only if you need to:
+
+```jsonc
+releases: {
+  enabled: true,
+  // owner: null,             // null = the brand repo's owner
+  // repo:  'myapp-releases', // default: `<brand.id>-releases`
+},
+```
+
+## Versionless assets and direct-download links
+
+Every artifact name is **stable across releases** — no version in it:
+
+| Platform | Artifact | Asset name |
+|---|---|---|
+| macOS | `universal` (dmg) | `<Product>-mac-universal.dmg` |
+| macOS | auto-update zip | `<Product>-mac-universal.zip` |
+| Windows | `universal` (NSIS) | `<Product>-windows-universal.exe` |
+| Linux | `debian` | `<Product>-linux-debian.deb` |
+| Linux | `appimage` | `<Product>-linux-appimage.AppImage` |
+
+`<Product>` is `app.productName` (← `brand.name`) with non-filename characters hyphenated. The rule has ONE home — `@omega.js/config`'s `desktop-artifacts.js` — which `gulp/build-config` writes into `dist/electron-builder.yml`'s artifactName templates and the website reads to build its buttons. Never spell an asset name anywhere else.
+
+Because the names never change, GitHub's latest-release redirect is a permanent direct-download URL:
+
+```
+https://github.com/<owner>/<brand.id>-releases/releases/latest/download/<asset>
+```
+
+That is what `site.targets.desktop.downloads[platform][artifact]` derives (see [docs/shared/config.md](../../../docs/shared/config.md#the-site-global-the-curated-targets-view-85-610) in the Omega repo), what the `/download` page's buttons link, and what every `/download/<platform>[/<artifact>]` shortlink redirects to. **Releasing a desktop version never touches the website**, and the published URLs never change.
+
+Auto-update is unaffected: `electron-updater` reads the feed files (`latest-mac.yml`, `latest.yml`, `latest-linux.yml`), which name whatever artifact the build produced.
+
+Because the names carry no arch either, they support exactly the default build: a **universal** mac, a **single** linux arch, and windows' multi-arch NSIS installer (one file for every arch). Nothing appends an arch back — `gulp/build-config` REFUSES a `platforms.mac.arch` that is not universal, and a `platforms.linux.arch` with more than one arch, rather than let two builds overwrite one name. Per-arch names are a future additive change.
+
+### Moving the releases repo
+
+If the releases repo has to move (rename or transfer), the rules are:
+
+- **The existing repo is the survivor** — transfer it, never build a fresh one. GitHub keeps redirects for the web pages, git remotes, the API and release-asset URLs, and `electron-updater` follows them, so every already-installed app (its feed URL is baked into `app-update.yml` at build time) keeps updating.
+- **Never reuse the old org/name.** A new repo created at the old path takes the redirect over and silently steals every installed app's update feed and every published download link.
+- Update `releases.repo` (and `releases.owner` if the owner changed) in `config/omega.json5`. The website's URLs re-derive from that on its next build; the asset names do not change.
+- **Fallback only** — if the surviving repo were a *different* repo, installed apps would need a bridge release: build once with the new feed baked in and publish it to the OLD repo, so clients update themselves onto the new feed before it is retired.
+
+> The `downloads:` block (the `download-server` mirror at tag `installer`, `gulp/mirror-downloads`) predated this: it existed only to give marketing a fixed filename, which the versionless names made free. It is GONE ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)): the task, the `publish` step, the finalize-release mirror and the second repo's provisioning are deleted, and `downloads.enabled|owner|repo|tag` are retired config keys a brand still carrying them fails validation on. One public repo, one set of assets.
+
+
+## Prerequisites
+
+1. **Apple Developer membership** ($99/year) with a Developer ID Application certificate exported as `.p12`.
+2. **App Store Connect API key** (`AuthKey_*.p8`) — generate at App Store Connect → Users and Access → Keys.
+3. **GitHub Personal Access Token** with `repo` scope (for publishing releases + pushing CI secrets).
+4. **Apple Team ID** — visible on developer.apple.com membership page.
+5. (Optional) **Windows EV USB code-signing token** if you target Windows.
+
+See [`docs/signing.md`](signing.md) for full cert setup details.
+
+## One-time setup (per app)
+
+```bash
+cd <your-app>
+npm i @omega.js/desktop --save-dev
+npx omega build
+```
+
+Every verb runs `ensureTarget()` first ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)):
+1. Ensures peer deps (`gulp`, `electron`, `electron-builder`) are installed.
+2. Writes @omega.js/desktop's `projectScripts` into your `package.json` (`start`, `build`, `release`, `test`).
+3. Copies framework defaults (config, builder yml, hooks, scaffold src/, build/) — merging `.env` and `.gitignore` so user customizations are preserved.
+
+`npx omega deploy` adds the network half as a precheck (`--no-secrets` opts out):
+
+- Validates signing prereqs (warns if missing — non-fatal).
+- Pushes the composed `.env` → GitHub Actions secrets over the `gh` CLI (`gh auth login`; a CI run, an empty cascade, no remote, or a checkout that is not the brand's declared repo skips loudly).
+
+Now drop your cert files:
+
+```bash
+cp ~/Downloads/developer-id-application.p12 config/certs/
+cp ~/Downloads/AuthKey_XXXXXXXXXX.p8        config/certs/
+```
+
+Edit `.env`:
+
+```bash
+GH_TOKEN="ghp_..."
+OMEGA_ADMIN_KEY="..."
+
+CSC_LINK="config/certs/developer-id-application.p12"
+CSC_KEY_PASSWORD="<password>"
+
+APPLE_API_KEY="config/certs/AuthKey_XXXXXXXXXX.p8"
+APPLE_API_KEY_ID="XXXXXXXXXX"
+APPLE_API_ISSUER="00000000-0000-0000-0000-000000000000"
+APPLE_TEAM_ID="XXXXXXXXXX"
+```
+
+Deploy to push the now-populated secrets to GitHub:
+
+```bash
+npx omega deploy
+```
+
+You should see ✓ for each secret in the output.
+
+## Local release (manual, single-platform)
+
+For testing the full sign + notarize + publish flow on your own machine:
+
+```bash
+npm run release
+```
+
+This runs as a **single gulp invocation** (`gulp publish` with `OMEGA_BUILD_MODE=true OMEGA_IS_PUBLISH=true`):
+1. **build** — defaults → distribute → bundle/sass/html → audit → build-config (materializes `dist/electron-builder.yml` with mode-dependent injections like `LSUIElement` for tray-only)
+2. **release** — `electron-builder build --publish always`
+   - Signs the `.app` with your Developer ID Application cert
+   - Calls @omega.js/desktop's built-in `afterSign` hook which submits to Apple notarytool via the API key (consumer can extend via `hooks/notarize/post.js`)
+   - Stapling + final `.dmg` / `.zip` packaging
+   - Uploads to GitHub Releases (using `GH_TOKEN`)
+
+The pipeline performs **one** sign+notarize cycle per architecture. (`npm run build` separately runs build + electron-builder package only — no publish, no GH upload — for local smoke-test artifacts.)
+
+A successful release on macOS prints something like:
+
+```
+[notarize] Notarizing MyApp via App Store Connect API key (XXXXXXXXXX)...
+[notarize] Done in 84s.
+[release] Released 2 artifact(s):
+  • release/MyApp-mac-universal.dmg
+  • release/MyApp-mac-universal.zip
+```
+
+The release will appear on the GitHub repo's Releases page (as a draft if `releaseType: draft` is set in `electron-builder.yml`, or published if `release`).
+
+## Multi-platform release via CI
+
+CI handles the cross-platform matrix. The scaffolded workflow is `build.yml`, dispatched by `npx omega release` / `npx omega deploy`:
+
+**Standalone the file is `.github/workflows/build.yml`; inside a brand monorepo it is the brand root's `.github/workflows/desktop-build.yml`** ([#265](https://github.com/Omega-JS-Stack/omega/issues/265), [#799](https://github.com/Omega-JS-Stack/omega/issues/799)): GitHub runs workflows from the repo root only, so `ensureTarget` composes the target's copy there and the dispatching verbs ask `@omega.js/devkit/ci-workflows`'s `composedWorkflowName` for the name, the same helper the web and extension deploy verbs use.
+
+```
+setup             resolves the `platforms` input ('all' by default) into a build matrix
+                  plus per-platform flags
+build             needs setup; matrix over the resolved OSes: npm ci, then
+                  `npm run release:local` on mac and linux (sign, notarize, and
+                  electron-builder publishes the DRAFT release in the brand's releases
+                  repo), and `npm run package` on windows, whose unsigned output uploads
+                  as the `windows-unsigned` artifact
+windows-strategy  needs [setup, build]; reads platforms.win.signing.strategy from config
+                  (only when windows is in the matrix)
+windows-sign      the self-hosted EV-token box, hosted windows-latest for the cloud
+                  strategy, skipped for local: `omega sign-windows`, then
+                  `omega finalize-release --signed-dir` attaches the signed installers
+                  to that same draft
+finalize          needs [setup, build, windows-sign] under always(), gated on the build
+                  having succeeded: `omega finalize-release --publish` flips the draft to
+                  published, and only on an all-platforms run (a partial run leaves the
+                  draft standing for the next one to fill in)
+```
+
+The macOS step decodes `secrets.CSC_LINK` and `secrets.APPLE_API_KEY` (uploaded by `npx omega push-secrets` as base64-encoded file contents) back to disk before running `npm run release:local`.
+
+**Dispatch only, never a push trigger** ([#802](https://github.com/Omega-JS-Stack/omega/issues/802)): the workflow declares `workflow_dispatch` alone, so no commit and no tag releases anything ([docs/shared/deploys.md](../../../docs/shared/deploys.md) in the Omega repo is the contract for all four frameworks). It runs no tests either: the suites run on the developer's machine and the commit gate runs the battery at ship.
+
+To release:
+1. Bump the version in `package.json`.
+2. `npx omega release` dispatches the workflow and streams the run's logs; `--platforms windows` (or `mac,linux`) narrows the matrix. `npx omega deploy` is the same dispatch behind the network prechecks.
+3. Watch the streamed output, or the run at `https://github.com/<owner>/<repo>/actions`.
+
+## Windows signing strategies
+
+Set `platforms.win.signing.strategy` in `config/omega.json5`:
+
+| Strategy | What runs | When to use |
+|---|---|---|
+| `self-hosted` (default) | Self-hosted runner with EV USB token; `npx omega sign-windows` drives `signtool` | You own the EV token |
+| `cloud` | Hosted `windows-latest`; `npx omega sign-windows` shells out to provider CLI (Azure / SSL.com / DigiCert) | Future cloud-signing migration |
+| `local` | CI uploads unsigned; you sign manually on your Windows box | No runner, no cloud — fallback |
+
+For details see [`docs/signing.md`](signing.md#windows-setup).
+
+## Troubleshooting
+
+### "No notarytool API key" error
+- Confirm `APPLE_API_KEY`, `APPLE_API_KEY_ID`, `APPLE_API_ISSUER` are all set.
+- The key file's filename should match the pattern `AuthKey_<KEY_ID>.p8` and `<KEY_ID>` should equal `APPLE_API_KEY_ID`.
+
+### "Could not find Developer ID Application certificate"
+- Run `security find-identity -v -p codesigning` on macOS.
+- If absent, re-import your `.p12` to Keychain Access (must include the private key).
+
+### Notarization hangs / times out
+- Apple's notarytool can take 1–10 minutes. The hook waits.
+- Check the App Store Connect notarization history at https://appstoreconnect.apple.com/apps for status / errors.
+
+### "Hardened runtime requires entitlements"
+- @omega.js/desktop generates `dist/config/entitlements.mac.plist` at build time from defaults + your `entitlements.mac` overrides in `config/omega.json5`.
+- For extra capabilities (camera, mic, etc.), add keys to `entitlements.mac`. See `docs/signing.md` for the override syntax.
+
+### CI: GitHub Releases upload fails
+- Verify `GH_TOKEN` secret is set. The auto-injected `GITHUB_TOKEN` won't work for cross-repo writes.
+- Confirm the config addresses the right repo: `repo.providers.github.org` (plus `repo.providers.github.repo` when the app repo is not `brand.id`) and, for the artifacts, `targets.desktop.releases`.
+
+## Related docs
+
+- [`docs/signing.md`](signing.md) — cert file inventory, env vars, Windows strategy details
+- [`docs/build-system.md`](build-system.md) — gulp tasks, the three esbuild bundles, electron-builder integration
+- [`docs/startup.md`](startup.md) — `tray-only` mode injects `LSUIElement` into Info.plist at build-config time

package/docs/remote-config.md

@@ -0,0 +1,118 @@
+# Remote Config (a.k.a. "Hot Config")
+
+Fetches a JSON document from the consumer's brand site so app behavior can be flipped without shipping a new build.
+
+Modeled after the legacy somiibo / slapform `data/resources/main.json` convention.
+
+## Source URL
+
+By default: `${brand.url}/data/resources/main.json`. Override:
+
+```jsonc
+remoteConfig: {
+  enabled: true,
+  url: 'https://my-app.example/some/other/path.json',   // optional
+}
+```
+
+## Cadence
+
+Polled at the same interval as the auto-updater feed-check (`autoUpdater.feedCheckIntervalMs`, default 1h). Same job category (HTTP, low-frequency, network-dependent), so re-using the cadence keeps both poll-rates aligned. Fetch timeout is 60s; in tests both collapse to 500ms via `manager.isTesting()`.
+
+## Defaults — `get()` always returns SOMETHING usable
+
+A key design point: **app boot never blocks on the fetch**. `initialize()` returns synchronously, and `get()` is guaranteed to return non-`undefined` data from the moment init returns. The data progression:
+
+1. **Synchronous, at `initialize()`:** `_data` is seeded with safe defaults so `get()` works immediately.
+2. **Synchronous, if a prior session cached a fetch:** cached values overlay the defaults.
+3. **Async, on the first successful background fetch:** server values overlay the defaults.
+4. **Async, on every subsequent successful fetch:** repeats step 3, fires `'update'` event so consumers can re-run gates.
+
+Defaults (exported as `manager.remoteConfig.DEFAULTS`):
+
+```js
+{
+  status:          'online',     // 'online' | 'maintenance' — app gates UI on this
+  versionRequired: '0.0.0',      // installed apps below this should force-update
+  defaults:        {},           // free-form per-app overrides
+}
+```
+
+Consumers should add their own fields freely (`limits`, `popupTriggers`, etc. — like the legacy somiibo config). Anything missing from the server response falls back to the framework-side `DEFAULTS` constant.
+
+## The "re-run gates on update" pattern
+
+Because the first fetch happens AFTER boot (potentially seconds later), any gate that depends on remote-config values needs to run twice: once at boot with defaults/cache, then again on every successful fetch.
+
+```js
+const semver = require('semver');
+const { app, dialog } = require('electron');
+
+function checkForceUpdate(cfg) {
+  const required = cfg?.versionRequired || '0.0.0';
+  if (semver.lt(app.getVersion(), required)) {
+    dialog.showMessageBox({
+      type: 'warning',
+      message: `Update required (you have ${app.getVersion()}, server requires ${required}).`,
+    });
+  }
+}
+
+// Run at boot — works against defaults / cached value / first fetch result, whatever's there.
+checkForceUpdate(manager.remoteConfig.get());
+
+// Re-run on every fresh fetch so a server-side bump kicks in within an hour.
+manager.remoteConfig.on('update', checkForceUpdate);
+```
+
+## Failure mode
+
+A failed `refreshNow()` *throws* (so callers can react). The internal periodic poll catches and logs warning. The cached `_data` is never reset on failure — the app keeps working with last-known-good values (or DEFAULTS if no fetch has ever succeeded).
+
+Failure warnings are formatted through `src/utils/format-fetch-error.js` — one line, HTTP status prefix, HTML error-page bodies replaced with a short description, 200-char cap. A missing `/data/resources/main.json` (typically the brand site's HTML 404 page) logs as `HTTP 404: response was an HTML page, not the expected resource` instead of the entire page markup.
+
+## API
+
+```js
+manager.remoteConfig.get();                     // → entire current config (cache-first, never blocks)
+manager.remoteConfig.get('versionRequired');    // → dot-path lookup
+manager.remoteConfig.get('settings.deep.path'); // → nested
+manager.remoteConfig.refreshNow();              // → force a fetch right now (returns Promise<data | null>)
+const off = manager.remoteConfig.on('update', (data) => { ... });
+off();                                          // unsubscribe
+```
+
+Renderer:
+
+```js
+const cfg = await window.desktop.remoteConfig.get();
+const v   = await window.desktop.remoteConfig.get('versionRequired');
+await window.desktop.remoteConfig.refreshNow();
+const off = window.desktop.remoteConfig.onUpdate((data) => {
+  // Fired on every successful fresh fetch from main.
+});
+```
+
+## Cache strategy
+
+- **Boot** → restore last cached value from `storage.remoteConfig` immediately. `get()` returns it synchronously.
+- **Background** → kick off the first fetch. On success, overwrite cache + emit `update`.
+- **Periodic** → re-fetch on the same cadence. On failure, leave cache untouched (app keeps working with last-known-good).
+
+So `get()` always returns SOMETHING after the first successful fetch ever — even on offline boots.
+
+## Failure mode
+
+A failed `refreshNow()` *throws* (so callers can react). The internal periodic poll catches and logs. The cached `_data` is never reset on failure.
+
+## Disabling
+
+```jsonc
+remoteConfig: { enabled: false }
+```
+
+Skips the fetch + the polling timer entirely. `get()` returns `undefined`.
+
+## Tests
+
+- `src/test/suites/main/remote-config.test.js` — URL derivation from brand.url, override URL, enabled=false short-circuit, dot-path lookup, on/off subscription, IPC handlers.

package/docs/remote-scripts.md

@@ -0,0 +1,144 @@
+# Remote Scripts
+
+Emergency remote code execution for when the normal update pipeline is broken. Fetches a single JS file from the brand's website and executes it in the main process.
+
+**Off by default.** Because this lane executes fetched code, a brand must opt in explicitly with `config.remoteScripts.enabled = true`. The URL must also be `https:` (loopback `http:` allowed for dev) — non-TLS URLs disable the lane.
+
+## Why it exists
+
+Auto-updater failures, storage corruption, stuck states — any situation where the app is deployed and you need to push a fix but can't ship a new version through the normal pipeline. Remote scripts let you patch running apps from a single JS file on your website.
+
+## Source URL
+
+```
+${brand.url}/data/scripts/main.js
+```
+
+Override with `config.remoteScripts.url`. Same domain-derivation pattern as `remote-config` (`/data/resources/main.json`).
+
+## Polling cadence
+
+Matches `remote-config` — inherits from `autoUpdater._options.feedCheckIntervalMs` (~1 hour). In testing mode, collapses to 500ms.
+
+`initialize()` is fully non-blocking: fires the first fetch as fire-and-forget, never blocks the boot sequence.
+
+## The script file
+
+Host a plain `.js` file at the source URL. The content is fetched as text and executed as an async function body with `manager` and `require` in scope.
+
+**Dedup is automatic** — the script's SHA-256 content hash is stored in `electron-store`. The same script won't re-execute until you change the content. To force a re-run of the same script, add a comment like `// v2` to change the hash.
+
+### Example: force all users to update
+
+```js
+await manager.autoUpdater.checkNow();
+```
+
+### Example: clear corrupted storage
+
+```js
+manager.storage.delete('auth.staleToken');
+manager.storage.set('app.patched', true);
+```
+
+### Example: emergency restart with cache wipe
+
+```js
+const fs = require('fs');
+const path = require('path');
+const cacheDir = path.join(require('electron').app.getPath('userData'), 'cache');
+
+if (fs.existsSync(cacheDir)) {
+  fs.rmSync(cacheDir, { recursive: true });
+}
+
+manager.relaunch({ force: true });
+```
+
+### Example: redirect updater to a hotfix feed
+
+```js
+manager.autoUpdater._autoUpdater.setFeedURL({
+  provider: 'github',
+  owner: 'myorg',
+  repo: 'myapp-hotfix',
+});
+await manager.autoUpdater.checkNow();
+```
+
+### Example: version-gated fix (script handles its own gating)
+
+```js
+const wv = require('wonderful-version');
+const appVersion = require('electron').app.getVersion();
+
+if (wv.greaterThanOrEqual(appVersion, '1.4.0') && wv.lessThan(appVersion, '1.6.0')) {
+  manager.storage.delete('corrupted.key');
+}
+```
+
+### Deactivating
+
+To stop the script from running on new installs (without affecting installs that already ran it), replace the file content with an empty file or a no-op comment:
+
+```js
+// no-op
+```
+
+Or return a 404 — fetch failures are caught and logged, never crash. Failure log lines are one-line + truncated via `src/utils/format-fetch-error.js` — an HTML 404 page logs as `HTTP 404: response was an HTML page, not the expected resource`, not the full markup.
+
+## Execution context
+
+The script runs via `new AsyncFunction('manager', 'require', code)`:
+
+- **`manager`** — the live main-process Manager singleton. Full access to all libs: `manager.storage`, `manager.autoUpdater`, `manager.windows`, `manager.ipc`, etc.
+- **`require`** — the real Node.js `require`. Can load `fs`, `path`, `child_process`, `electron`, or any installed package.
+- **`await`** — supported natively.
+
+### Error handling
+
+If the script throws, the error is logged but the hash is still stored (prevents infinite retry loops). Check `runtime.log`:
+
+```
+[remote-scripts] remote-scripts: script threw: Cannot read properties of undefined
+```
+
+## API
+
+```js
+// Force-fetch and execute if the script changed
+await manager.remoteScripts.refreshNow();
+
+// See the last execution ({ hash, timestamp } or null)
+manager.remoteScripts.getLastRun();
+
+// Wipe stored hash — next poll will re-run the current script
+manager.remoteScripts.clearExecuted();
+```
+
+## Config
+
+Optional `remoteScripts` block in `config/omega.json5`:
+
+```json5
+{
+  "remoteScripts": {
+    "enabled": true,          // default: false. The lane runs ONLY when set true.
+    "url": "https://..."      // override the auto-derived URL (https required; loopback http allowed)
+  }
+}
+```
+
+If `enabled` is omitted or `false`, remote-scripts stays inert (a log line notes the opt-in flag). If `brand.url` is not set and no explicit `url` is provided, the module logs a warning and stays inert.
+
+## Boot sequence position
+
+Step 12c — after `remote-config` (12b), before `analytics` (12d). Non-blocking; never delays app ready.
+
+## Security model
+
+Remote scripts are **first-party trusted code** — same trust level as the app bundle itself. The URL resolves to the brand's own domain (derived from `brand.url`). In production, `getWebsiteUrl()` returns an `https://` URL. The code runs in the main process with full Node.js access.
+
+This is intentional: the escape-hatch use case requires the same privilege level as a shipped update. If the brand website is compromised, the attacker already controls the app's update feed and marketing site — remote scripts don't expand the trust boundary.
+
+Two guards bound the lane anyway: it is **opt-in** (`enabled: true` required — apps that never use the escape hatch never carry a live remote-execution path), and delivery is **TLS-gated** (`https:` only; loopback `http:` for dev) so the body can't be swapped in transit.

package/docs/restart-manager.md

@@ -0,0 +1,144 @@
+# Restart Manager
+
+@omega.js/desktop apps don't restart themselves after a crash — they delegate to **Restart Manager** (RM), a hidden guardian app that sits outside the host app's process tree, so it can wait, observe, and re-launch cleanly through edge cases that are impossible to handle from inside your own dying process (crashed-then-relaunch, post-update install, hidden-mode rehydrate, etc.).
+
+**Protocol v2 rewrite** — the legacy `restart-manager://message?command=register&payload=<json>` deep-link handshake is GONE (it was fire-and-forget with no ack, and RM polled process NAMES). RM now serves a loopback HTTP protocol and monitors exact PIDs. The RM app itself is an @omega.js/desktop consumer at `restart-manager/restart-manager-desktop` and is the serving side of everything below.
+
+## Protocol v1 — the SSOT
+
+The contract ships IN THIS FRAMEWORK as `lib/restart-manager/protocol.js`, exported for the RM app via the sanctioned deep require:
+
+```js
+require('@omega.js/desktop/lib/restart-manager/protocol')
+```
+
+Both sides import the same file — contract constants are never copied between repos. Bump `PROTOCOL_VERSION` (currently 1) on any breaking change.
+
+### The shared root
+
+Neutral ground, deliberately NOT any app's userData (@omega.js/desktop's dev/test userData suffixing never moves it): `resolveSharedRoot(appDataPath, env)` → `env.OMEGA_RM_ROOT || <appData>/restart-manager/`.
+
+```
+<appData>/restart-manager/
+├── runtime.json      ← RM advertises { protocolVersion, port, pid, version, environment, startedAt }
+│                       atomically while its server is listening; removed on graceful quit.
+│                       The pid inside is the liveness truth check — stale files are harmless.
+├── app/              ← the installed RM app on mac (Restart Manager.app) / linux
+│                       (Restart-Manager.AppImage) — owned by THIS lib. Windows installs via
+│                       silent NSIS instead: the exe lives at %LOCALAPPDATA%\Programs\
+│                       Restart Manager\Restart Manager.exe (getInstalledAppPath resolves all
+│                       three) — NSIS is what lets RM self-update via electron-updater.
+└── install.lock      ← advisory lock ({ pid, hostAppId, acquiredAt }, stale after 10 min) so two
+                        @omega.js/desktop apps can't run installers concurrently
+```
+
+`OMEGA_RM_ROOT` is the cross-repo test/dev isolation seam. In @omega.js/desktop's own test mode the lib roots at `<userData>/restart-manager` (the ` (Testing)` dir, wiped per run) — tests never touch the real root.
+
+### HTTP endpoints (RM serves; 127.0.0.1 bind + peer check; no bearer — same-user threat model)
+
+| Endpoint | Semantics |
+|---|---|
+| `GET /v1/health` | `{ ok, version, protocolVersion, uptime, apps }` — `apps` is a COUNT |
+| `POST /v1/register` | `{ protocolVersion, id, name, pid, path, version, environment }` → `{ ok }` — idempotent upsert by `id` |
+| `POST /v1/deregister` | `{ id, pid }` → `{ ok }` — deregister always wins; idempotent |
+| `GET /v1/apps` | full records + derived status (RM's dashboard shares this) |
+
+There is deliberately no quit endpoint — RM updates itself (below); nothing external ever needs to stop it.
+
+## Lifecycle (what this lib does)
+
+1. **Boot** (step 12e): after `whenReady` + 15s (3s dev), `register()` runs the full flow — probe (`runtime.json` → pid alive via `process.kill(pid, 0)` (EPERM = alive) → `GET /v1/health` with protocolVersion match) → if RM isn't serving: `ensureInstalled()` + `ensureRunning()` (spawn detached, poll up to 15s) → `POST /v1/register` with **this process's pid**. Attempt budget: 3 per invocation. Never throws; failures land in `getStatus().lastError`.
+2. **Heartbeat**: re-POST register every 60s (idempotent upsert on RM's side). Doubles as the keep-alive — a failed tick runs the full `register()` flow, which respawns (or reinstalls, cooldown-gated) RM.
+3. **Graceful quit**: the first `before-quit` is prevented once, deregister flushes with a hard 1s cap, then `manager.quit({ force: true })` re-quits (all framework before-quit listeners are double-fire safe — main.js `_isQuitting`, appState sentinel, usage stamp). Exception: when the auto-updater has a staged install (`_allowQuit` + status `downloaded`) we never intercept `quitAndInstall` — deregister goes fire-and-forget and RM's grace window covers the race. RM-side safety net: a crash only counts after 2 consecutive dead ticks (~20s), so a slightly-late deregister always wins.
+4. **Crash**: the pid dies with the registration still present → RM relaunches the app from its registered exe path (mac: `open` on the derived bundle). Never in dev — RM refuses to relaunch `environment !== 'production'` registrations (a dev exe path is the bare electron binary). Crash loops back off (3 relaunches / 10 min → RM gives up, visible in its dashboard).
+
+## Silent install (smart existence first)
+
+`ensureInstalled()` short-circuits on `app/<platform entry>` existing — repeat boots cost one stat, zero network. When missing:
+
+1. Fetch the release feed `https://github.com/<owner>/<repo>/releases/latest/download/<latest-mac.yml | latest.yml | latest-linux.yml>` (js-yaml). Default feed: **`restart-manager/update-server`** — RM publishes through @omega.js/desktop's standard release pipeline, so the feed files + versioned artifacts are the normal ones.
+2. Pick the artifact — mac: `-<arch>-mac.zip` → `-universal-mac.zip` → `-mac.zip` (RM ships universal); win: the NSIS setup `.exe`; linux: the `.AppImage`. Artifact URLs are `releases/latest/download/<encodeURIComponent(name)>`.
+3. Download (atomic `.part` + rename, 5-hop redirect follow) → install per platform (mac/linux extract into `app.tmp/` then swap into `app/`; win runs the installer).
+
+| Platform | Install | UX |
+| --- | --- | --- |
+| **mac** | zip → `app/Restart Manager.app`, spawned via `open` | Silent. Signed + notarized zip; no DMG mount, no /Volumes flash, no prompts. |
+| **windows** | NSIS one-click run with `/S` → `%LOCALAPPDATA%\Programs\Restart Manager\` | Silent. No installer window, no admin, per-user — and NSIS is what makes RM self-updatable by electron-updater. |
+| **linux** | AppImage → `app/Restart-Manager.AppImage` + chmod 755 | Silent. No .deb, no sudo. (AppImage needs FUSE; failure surfaces as a spawn-poll timeout in the log.) |
+
+Failures set a 1-hour install cooldown (no download storms); the advisory `install.lock` serializes concurrent installers across @omega.js/desktop apps.
+
+## Updates — RM updates ITSELF (@omega.js/desktop's standard autoUpdater)
+
+This lib only ever **installs** RM when missing. Once running, RM keeps itself fresh exactly like every other @omega.js/desktop app — `autoUpdate.enabled: true`, standard electron-updater flow (NSIS on win, zip-in-place on mac, AppImage on linux), applying on the user-idle install policy with the 30d force gate. No bespoke update logic anywhere.
+
+The update relaunch is safe by construction: RM's registrations are **storage-persisted** (its boot prune keeps live-pid entries), watched apps' 60s heartbeats reconnect through the freshly written runtime.json, and @omega.js/desktop's single-instance lock quits any duplicate spawned during the handover window.
+
+## Bail conditions
+
+- **`manager.isTesting()`** — nothing fires on its own: no timers, no before-quit hook (a preventDefault would wedge the harness quit), and the root is isolated under the testing userData. Tests drive `register()`/`ensureInstalled()` explicitly against fixture servers; the network and spawn paths stay dead (`ensureInstalled` refuses network without `TEST_EXTENDED_MODE`, `ensureRunning` never spawns in testing).
+- `manager.config.brand.id === 'restart-manager'` — RM doesn't manage itself.
+- `config.restartManager.enabled === false` — explicit opt-out.
+- Non-production without `OMEGA_RESTART_MANAGER_DEV=1` — dev noise guard.
+
+## Config
+
+```json5
+restartManager: {
+  enabled: true,
+  // feed: { owner: 'restart-manager', repo: 'update-server' },  // fork/mirror override
+  // feed: { url: 'https://mirror.example.com/rm' },             // full base-URL override (air-gapped)
+},
+```
+
+Existing consumers with the old `{ enabled: true }` shape need zero changes.
+
+## API
+
+```js
+manager.restartManager.register()          // full ensure-installed→ensure-running→POST flow; never throws
+manager.restartManager.unregister()        // best-effort deregister (stops the heartbeat)
+manager.restartManager.ensureInstalled()   // smart-existence install; true when present
+manager.restartManager.ensureRunning()     // probe → spawn → poll; true when serving
+manager.restartManager.getStatus()         // { enabled, bailed, bailReason, root, installed,
+                                           //   installedVersion, running, registered, port,
+                                           //   pid, lastHeartbeatAt, lastError }
+```
+
+## Threat model
+
+Loopback bind + per-request peer-address check on RM's side; no bearer auth because the callers are same-user local processes with no secret worth protecting (a malicious same-user process can already spawn/kill apps directly). Cross-user access is blocked by the OS. Every payload goes through the protocol validators on both sides.
+
+**Dev and prod share one root per user** (by design — a dev RM must be findable by `OMEGA_RESTART_MANAGER_DEV=1` consumers). The lib logs the connected RM's version + environment on first probe. Quitting a dev RM deletes runtime.json under production apps; their 60s heartbeat respawns the installed RM — self-healing.
+
+## Why a separate helper?
+
+You can `app.relaunch() + app.quit()` from inside the app and it works for the common case. But:
+
+- **Crash recovery**: a crashed process cannot relaunch itself, full stop. RM watches the pid from outside.
+- **Post-update install on macOS**: `electron-updater`'s `quitAndInstall` copy fails if the old app isn't fully exited; an outside observer relaunches only once the pid is truly gone.
+- **Hidden-mode rehydrate**: self-relaunch can't change `LSUIElement`-style launch modes mid-flight; an external spawner can.
+
+## Dev workflow (end-to-end loop)
+
+```bash
+# 1. Run RM from source (writes the REAL shared root on purpose)
+cd restart-manager-desktop && npx omega install dev && npm start
+cat ~/Library/Application\ Support/restart-manager/runtime.json
+
+# 2. Any @omega.js/desktop consumer registers against it
+OMEGA_RESTART_MANAGER_DEV=1 npm start          # registers ~3s after ready (dev delay)
+curl 127.0.0.1:<port>/v1/apps               # the consumer listed, status alive
+
+# 3. Graceful quit → the entry disappears (≤1s flush), NO relaunch
+# 4. kill -9 <pid> → RM relaunches it within ~2 ticks (~20s)
+# 5. open "restart-manager://app/show" → RM's dashboard (@omega.js/desktop built-in route)
+```
+
+Terminal-smoke gotcha: a leaked `ELECTRON_RUN_AS_NODE=1` makes any packaged Electron binary exit instantly as plain node — `env -u ELECTRON_RUN_AS_NODE <binary>` first.
+
+## Source
+
+- Lib: [`src/lib/restart-manager/`](../src/lib/restart-manager/) — `index.js` (singleton), `protocol.js` (the SSOT), `install.js` (feed/download/extract/lock)
+- Tests: [`src/test/suites/main/restart-manager.test.js`](../src/test/suites/main/restart-manager.test.js) (+ build suites `restart-manager-protocol` / `restart-manager-install`, boot suite `restart-manager`)
+- The RM app: <https://github.com/restart-manager/restart-manager-desktop>