@omega.js/desktop 0.1.0

package/dist/test/suites/build/resolve-signing-cert.test.js

@@ -0,0 +1,342 @@
+// resolve-signing-cert tests ([#28](https://github.com/Omega-JS-Stack/omega/issues/28)) —
+// the signing lookup ORDER: an explicit CSC_LINK wins, then the brand's
+// gitignored .omega/certificates/apple/ tree, then the company's tree (reached
+// through the brand's .omega/company.json stamp — a brand is NEVER physically
+// inside its company folder), then the Keychain.
+//
+// The Keychain branch is today's default and MUST stay it: with no cert in the
+// tree the resolver hands electron-builder nothing, exactly as before.
+//
+// The tree branch is only taken when the password actually OPENS the .p12 —
+// the adoption flow can pair an adopted legacy .p12 with a freshly generated
+// CSC_KEY_PASSWORD, and handing electron-builder an unopenable file is the
+// failure this lookup exists to avoid. Real openssl material is generated in a
+// temp dir for that check; nothing here is stubbed.
+
+const { execFileSync } = require('node:child_process');
+const { mkdtempSync } = require('node:fs');
+const { homedir, tmpdir } = require('node:os');
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const resolveSigningCert = require('../../../utils/resolve-signing-cert.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+const CERT_REL = join('.omega', 'certificates', 'apple', 'certificates', 'DEVELOPER_ID_APPLICATION_G2.p12');
+const REAL_PASSWORD = 'fixture-p12-password';
+
+// One real self-signed key/cert exported to a .p12, the same way the manager's
+// certificate-manager.js exports one (`pkcs12 -export -legacy`).
+let realP12 = null;
+function realP12Bytes() {
+  if (realP12) {
+    return realP12;
+  }
+
+  const dir = mkdtempSync(join(tmpdir(), 'omega-signing-material-'));
+  execFileSync('openssl', [
+    'req', '-x509', '-nodes', '-newkey', 'rsa:2048',
+    '-keyout', join(dir, 'private.key'), '-out', join(dir, 'cert.cer'),
+    '-days', '2', '-subj', '/CN=Signing Fixture/C=US', '-outform', 'DER',
+  ], { stdio: 'pipe' });
+  execFileSync('openssl', [
+    'pkcs12', '-export', '-legacy',
+    '-inkey', join(dir, 'private.key'), '-in', join(dir, 'cert.cer'),
+    '-out', join(dir, 'fixture.p12'), '-passout', 'env:OMEGA_P12_PASSWORD',
+  ], { stdio: 'pipe', env: { ...process.env, OMEGA_P12_PASSWORD: REAL_PASSWORD } });
+
+  realP12 = jetpack.read(join(dir, 'fixture.p12'), 'buffer');
+  return realP12;
+}
+
+// A brand root with a desktop app under it, mirroring a real brand monorepo.
+// `cert: 'real'` writes an openable .p12; `cert: 'dummy'` writes bytes that are
+// not a certificate at all. A brand root ALWAYS carries a `.omega/` — that is
+// what identifies it to the walk.
+function stageBrand({ cert = null, root = null } = {}) {
+  const brandRoot = root || mkdtempSync(join(tmpdir(), 'omega-signing-'));
+  const targetRoot = join(brandRoot, 'targets', 'desktop');
+
+  jetpack.dir(targetRoot);
+  jetpack.dir(join(brandRoot, '.omega'));
+  if (cert === 'real') {
+    jetpack.write(join(brandRoot, CERT_REL), realP12Bytes());
+  } else if (cert === 'dummy') {
+    jetpack.write(join(brandRoot, CERT_REL), 'p12-bytes');
+  }
+
+  return { brandRoot, targetRoot };
+}
+
+// Stamp a brand as company-managed — the ONE membership rule
+// (@omega.js/config's readCompanyRoot / .omega/company.json).
+function stampCompany(brandRoot, companyRoot) {
+  jetpack.write(join(brandRoot, '.omega', 'company.json'), JSON.stringify({ root: companyRoot }));
+}
+
+module.exports = defineCases({
+  type: 'group',
+  layer: 'build',
+  description: 'resolve-signing-cert',
+  tests: [
+    {
+      name: 'no cert anywhere → keychain (today\'s default, unchanged)',
+      run: (ctx) => {
+        const { targetRoot } = stageBrand();
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: {} });
+
+        ctx.expect(resolved.source).toBe('keychain');
+        ctx.expect(resolved.cscLink).toBe(null);
+      },
+    },
+    {
+      name: 'an explicit CSC_LINK always wins',
+      run: (ctx) => {
+        const { targetRoot } = stageBrand({ cert: 'real' });
+
+        const resolved = resolveSigningCert({
+          projectRoot: targetRoot,
+          env: { CSC_LINK: 'config/certs/developer-id-application.p12', CSC_KEY_PASSWORD: REAL_PASSWORD },
+        });
+
+        ctx.expect(resolved.source).toBe('env');
+        ctx.expect(resolved.cscLink).toBe('config/certs/developer-id-application.p12');
+      },
+    },
+    {
+      name: 'the brand certificates tree is preferred over the keychain',
+      run: (ctx) => {
+        const { brandRoot, targetRoot } = stageBrand({ cert: 'real' });
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+        ctx.expect(resolved.source).toBe('certificates');
+        ctx.expect(resolved.cscLink).toBe(join(brandRoot, CERT_REL));
+      },
+    },
+    {
+      name: 'a stamped brand reaches its company tree — a SIBLING directory, never an ancestor',
+      run: (ctx) => {
+        // No nesting: the company workspace lives beside the brand, and the
+        // brand's .omega/company.json is the only thing pointing at it.
+        const { brandRoot, targetRoot } = stageBrand();
+        const companyRoot = mkdtempSync(join(tmpdir(), 'omega-company-'));
+        jetpack.write(join(companyRoot, CERT_REL), realP12Bytes());
+        stampCompany(brandRoot, companyRoot);
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+        ctx.expect(resolved.source).toBe('certificates');
+        ctx.expect(resolved.cscLink).toBe(join(companyRoot, CERT_REL));
+      },
+    },
+    {
+      name: 'the brand tree wins over the company tree',
+      run: (ctx) => {
+        const { brandRoot, targetRoot } = stageBrand({ cert: 'real' });
+        const companyRoot = mkdtempSync(join(tmpdir(), 'omega-company-'));
+        jetpack.write(join(companyRoot, CERT_REL), realP12Bytes());
+        stampCompany(brandRoot, companyRoot);
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+        ctx.expect(resolved.cscLink).toBe(join(brandRoot, CERT_REL));
+      },
+    },
+    {
+      name: 'an unstamped brand with no tree stays on the keychain — no company is guessed',
+      run: (ctx) => {
+        const { targetRoot } = stageBrand();
+        // A company workspace exists on disk but nothing points at it.
+        const companyRoot = mkdtempSync(join(tmpdir(), 'omega-company-'));
+        jetpack.write(join(companyRoot, CERT_REL), realP12Bytes());
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+        ctx.expect(resolved.source).toBe('keychain');
+        ctx.expect(resolved.cscLink).toBe(null);
+      },
+    },
+    {
+      name: 'a stamp pointing at a company with no tree stays on the keychain',
+      run: (ctx) => {
+        const { brandRoot, targetRoot } = stageBrand();
+        stampCompany(brandRoot, mkdtempSync(join(tmpdir(), 'omega-company-')));
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+        ctx.expect(resolved.source).toBe('keychain');
+      },
+    },
+    {
+      name: 'a cert with no CSC_KEY_PASSWORD stays on the keychain — an unopenable .p12 would fail the build',
+      run: (ctx) => {
+        const { targetRoot } = stageBrand({ cert: 'real' });
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: {} });
+
+        ctx.expect(resolved.source).toBe('keychain');
+        ctx.expect(resolved.cscLink).toBe(null);
+        ctx.expect(resolved.reason.includes('CSC_KEY_PASSWORD')).toBe(true);
+      },
+    },
+    {
+      name: 'a password that does NOT open the .p12 stays on the keychain',
+      run: (ctx) => {
+        const { targetRoot } = stageBrand({ cert: 'real' });
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { CSC_KEY_PASSWORD: 'not-the-password' } });
+
+        ctx.expect(resolved.source).toBe('keychain');
+        ctx.expect(resolved.cscLink).toBe(null);
+        ctx.expect(resolved.reason.includes('does not open')).toBe(true);
+      },
+    },
+    {
+      name: 'a file that is not a .p12 at all stays on the keychain',
+      run: (ctx) => {
+        const { targetRoot } = stageBrand({ cert: 'dummy' });
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+        ctx.expect(resolved.source).toBe('keychain');
+        ctx.expect(resolved.reason.includes('does not open')).toBe(true);
+      },
+    },
+    {
+      name: 'an empty CSC_LINK is not an answer — the tree still wins',
+      run: (ctx) => {
+        const { brandRoot, targetRoot } = stageBrand({ cert: 'real' });
+
+        const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { CSC_LINK: '', CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+        ctx.expect(resolved.source).toBe('certificates');
+        ctx.expect(resolved.cscLink).toBe(join(brandRoot, CERT_REL));
+      },
+    },
+    {
+      name: 'a tree AT the home directory never signs a build (the ~/.omega overlay)',
+      run: (ctx) => {
+        // ~/.omega is a real personal overlay on developer machines. A stand-in
+        // home carries the tree here; without the bound the walk would take it.
+        const fakeHome = mkdtempSync(join(tmpdir(), 'omega-fake-home-'));
+        const targetRoot = join(fakeHome, 'brand', 'targets', 'desktop');
+        jetpack.dir(targetRoot);
+        jetpack.write(join(fakeHome, CERT_REL), realP12Bytes());
+
+        const resolved = resolveSigningCert({
+          projectRoot: targetRoot,
+          env: { CSC_KEY_PASSWORD: REAL_PASSWORD },
+          homeDir: fakeHome,
+        });
+
+        ctx.expect(resolved.source).toBe('keychain');
+        ctx.expect(resolved.cscLink).toBe(null);
+      },
+    },
+    {
+      name: 'a tree ABOVE the home directory is out of bounds too',
+      run: (ctx) => {
+        const above = mkdtempSync(join(tmpdir(), 'omega-above-home-'));
+        const fakeHome = join(above, 'home');
+        const targetRoot = join(fakeHome, 'brand', 'targets', 'desktop');
+        jetpack.dir(targetRoot);
+        jetpack.write(join(above, CERT_REL), realP12Bytes());
+
+        const resolved = resolveSigningCert({
+          projectRoot: targetRoot,
+          env: { CSC_KEY_PASSWORD: REAL_PASSWORD },
+          homeDir: fakeHome,
+        });
+
+        ctx.expect(resolved.source).toBe('keychain');
+      },
+    },
+    {
+      name: 'a tree BELOW home still resolves — the bound is the home dir, not "anywhere under it"',
+      run: (ctx) => {
+        const fakeHome = mkdtempSync(join(tmpdir(), 'omega-under-home-'));
+        const brandRoot = join(fakeHome, 'Developer', 'brand');
+        const targetRoot = join(brandRoot, 'targets', 'desktop');
+        jetpack.dir(targetRoot);
+        jetpack.write(join(brandRoot, CERT_REL), realP12Bytes());
+
+        const resolved = resolveSigningCert({
+          projectRoot: targetRoot,
+          env: { CSC_KEY_PASSWORD: REAL_PASSWORD },
+          homeDir: fakeHome,
+        });
+
+        ctx.expect(resolved.source).toBe('certificates');
+        ctx.expect(resolved.cscLink).toBe(join(brandRoot, CERT_REL));
+      },
+    },
+    {
+      name: 'a LibreSSL openssl (no -legacy flag) still verifies the cert — the check retries without the flag',
+      run: (ctx) => {
+        // Stock macOS /usr/bin/openssl is LibreSSL: it rejects the -legacy FLAG
+        // but reads legacy containers natively. A stub front presents exactly
+        // that behavior, delegating the flagless retry to the system binary.
+        const { brandRoot, targetRoot } = stageBrand({ cert: 'real' });
+        const stubDir = mkdtempSync(join(tmpdir(), 'omega-libressl-stub-'));
+        const stub = join(stubDir, 'openssl');
+        jetpack.write(stub, [
+          '#!/bin/sh',
+          'for a in "$@"; do',
+          '  if [ "$a" = "-legacy" ]; then echo "pkcs12: unknown option \'-legacy\'" >&2; exit 1; fi',
+          'done',
+          'if [ -x /usr/bin/openssl ]; then exec /usr/bin/openssl "$@"; fi',
+          'exit 0',
+          '',
+        ].join('\n'));
+        execFileSync('chmod', ['+x', stub]);
+
+        const realPath = process.env.PATH;
+        process.env.PATH = `${stubDir}:${realPath}`;
+        try {
+          const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { ...process.env, CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+          ctx.expect(resolved.source).toBe('certificates');
+          ctx.expect(resolved.cscLink).toBe(join(brandRoot, CERT_REL));
+        } finally {
+          process.env.PATH = realPath;
+        }
+      },
+    },
+    {
+      name: 'no openssl at all names the tooling, not the password, and stays on the keychain',
+      run: (ctx) => {
+        const { targetRoot } = stageBrand({ cert: 'real' });
+        const emptyDir = mkdtempSync(join(tmpdir(), 'omega-no-openssl-'));
+
+        const realPath = process.env.PATH;
+        process.env.PATH = emptyDir;
+        try {
+          const resolved = resolveSigningCert({ projectRoot: targetRoot, env: { ...process.env, CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+          ctx.expect(resolved.source).toBe('keychain');
+          ctx.expect(resolved.reason.includes('openssl is not available')).toBe(true);
+          ctx.expect(resolved.reason.includes('does not open')).toBe(false);
+        } finally {
+          process.env.PATH = realPath;
+        }
+      },
+    },
+    {
+      name: 'the default boundary is the REAL home — a project under it picks up no stray tree',
+      run: (ctx) => {
+        const projectRoot = mkdtempSync(join(homedir(), '.omega-signing-probe-'));
+
+        // No homeDir passed: the default must apply, and nothing in the real
+        // home (including its ~/.omega overlay) may be reached.
+        const resolved = resolveSigningCert({ projectRoot, env: { CSC_KEY_PASSWORD: REAL_PASSWORD } });
+
+        ctx.expect(resolved.source).toBe('keychain');
+        ctx.expect(resolved.cscLink).toBe(null);
+
+        jetpack.remove(projectRoot);
+      },
+    },
+  ],
+});

package/dist/test/suites/build/restart-manager-install.test.js

@@ -0,0 +1,178 @@
+// Build-layer tests for lib/restart-manager/install.js — feed parsing, artifact
+// picking, URL building, and the advisory install lock. Pure functions + real
+// temp-dir filesystem; no network.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const install = require('../../../lib/restart-manager/install.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+// Realistic electron-builder feed fixtures (shapes match what @omega.js/desktop's release
+// pipeline publishes to update-server).
+const MAC_YML = [
+  'version: 1.2.3',
+  'files:',
+  '  - url: Restart-Manager-1.2.3-universal-mac.zip',
+  '    sha512: abc123==',
+  '    size: 123456789',
+  '  - url: Restart-Manager-1.2.3.dmg',
+  '    sha512: def456==',
+  '    size: 234567890',
+  'path: Restart-Manager-1.2.3-universal-mac.zip',
+  "releaseDate: '2026-07-01T00:00:00.000Z'",
+].join('\n');
+
+const WIN_YML = [
+  'version: 1.2.3',
+  'files:',
+  '  - url: Restart-Manager-Setup-1.2.3.exe',
+  '    sha512: aaa==',
+  '  - url: Restart-Manager-1.2.3-win.zip',
+  '    sha512: bbb==',
+  'path: Restart-Manager-Setup-1.2.3.exe',
+].join('\n');
+
+const LINUX_YML = [
+  'version: 1.2.3',
+  'files:',
+  '  - url: Restart-Manager-1.2.3-x64.AppImage',
+  '    sha512: ccc==',
+  '  - url: restart-manager_1.2.3_amd64.deb',
+  '    sha512: ddd==',
+].join('\n');
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'restart-manager install machinery (build)',
+  tests: [
+    {
+      name: 'parseFeed extracts version + files from all three platform feeds',
+      run: (ctx) => {
+        const mac = install.parseFeed(MAC_YML);
+        ctx.expect(mac.version).toBe('1.2.3');
+        ctx.expect(mac.files.length).toBe(2);
+        ctx.expect(mac.files[0].url).toBe('Restart-Manager-1.2.3-universal-mac.zip');
+
+        ctx.expect(install.parseFeed(WIN_YML).files.length).toBe(2);
+        ctx.expect(install.parseFeed(LINUX_YML).version).toBe('1.2.3');
+      },
+    },
+    {
+      name: 'parseFeed rejects garbage and version-less feeds',
+      run: (ctx) => {
+        ctx.expect(() => install.parseFeed('[]')).toThrow();
+        ctx.expect(() => install.parseFeed('files:\n  - url: x.zip')).toThrow();
+      },
+    },
+    {
+      name: 'pickArtifact darwin: arch-specific → universal → plain -mac.zip order',
+      run: (ctx) => {
+        const universalOnly = install.parseFeed(MAC_YML);
+        // No arm64 zip in feed → falls through to universal.
+        ctx.expect(install.pickArtifact(universalOnly, 'darwin', 'arm64')).toBe('Restart-Manager-1.2.3-universal-mac.zip');
+
+        const archSplit = {
+          version: '2.0.0',
+          files: [
+            { url: 'RM-2.0.0-arm64-mac.zip' },
+            { url: 'RM-2.0.0-x64-mac.zip' },
+          ],
+        };
+        ctx.expect(install.pickArtifact(archSplit, 'darwin', 'arm64')).toBe('RM-2.0.0-arm64-mac.zip');
+        ctx.expect(install.pickArtifact(archSplit, 'darwin', 'x64')).toBe('RM-2.0.0-x64-mac.zip');
+
+        const plain = { version: '3.0.0', files: [{ url: 'RM-3.0.0-mac.zip' }] };
+        ctx.expect(install.pickArtifact(plain, 'darwin', 'arm64')).toBe('RM-3.0.0-mac.zip');
+
+        // The versionless name @omega.js/desktop packages under since #620 —
+        // an RM built by the current framework publishes THIS zip.
+        const versionless = { version: '4.0.0', files: [{ url: 'Restart-Manager-mac-universal.zip' }] };
+        ctx.expect(install.pickArtifact(versionless, 'darwin', 'arm64')).toBe('Restart-Manager-mac-universal.zip');
+      },
+    },
+    {
+      name: 'pickArtifact win: the NSIS setup exe (run with /S; enables electron-updater self-updates)',
+      run: (ctx) => {
+        const feed = install.parseFeed(WIN_YML);
+        ctx.expect(install.pickArtifact(feed, 'win32', 'x64')).toBe('Restart-Manager-Setup-1.2.3.exe');
+      },
+    },
+    {
+      name: 'pickArtifact linux: the AppImage, never the deb',
+      run: (ctx) => {
+        const feed = install.parseFeed(LINUX_YML);
+        ctx.expect(install.pickArtifact(feed, 'linux', 'x64')).toBe('Restart-Manager-1.2.3-x64.AppImage');
+      },
+    },
+    {
+      name: 'pickArtifact: no match throws listing the candidates',
+      run: (ctx) => {
+        const feed = { version: '1.0.0', files: [{ url: 'Something-1.0.0.dmg' }] };
+        let threw = null;
+        try { install.pickArtifact(feed, 'darwin', 'arm64'); }
+        catch (e) { threw = e; }
+        ctx.expect(threw).not.toBe(null);
+        ctx.expect(threw.message).toContain('Something-1.0.0.dmg');
+      },
+    },
+    {
+      name: 'buildFeedUrl: default github form, url override, trailing-slash tolerance',
+      run: (ctx) => {
+        const github = install.buildFeedUrl({ owner: 'restart-manager', repo: 'update-server' }, 'darwin');
+        ctx.expect(github).toBe('https://github.com/restart-manager/update-server/releases/latest/download/latest-mac.yml');
+
+        ctx.expect(install.buildFeedUrl({ owner: 'o', repo: 'r' }, 'win32').endsWith('/latest.yml')).toBe(true);
+        ctx.expect(install.buildFeedUrl({ owner: 'o', repo: 'r' }, 'linux').endsWith('/latest-linux.yml')).toBe(true);
+
+        const mirrored = install.buildFeedUrl({ url: 'https://mirror.example.com/rm/' }, 'darwin');
+        ctx.expect(mirrored).toBe('https://mirror.example.com/rm/latest-mac.yml');
+
+        ctx.expect(() => install.buildFeedUrl({ owner: 'o', repo: 'r' }, 'freebsd')).toThrow();
+      },
+    },
+    {
+      name: 'buildArtifactUrl URL-encodes artifact names (space survives as %20)',
+      run: (ctx) => {
+        const url = install.buildArtifactUrl({ owner: 'o', repo: 'r' }, 'Weird Name-1.0.0-mac.zip');
+        ctx.expect(url).toBe('https://github.com/o/r/releases/latest/download/Weird%20Name-1.0.0-mac.zip');
+      },
+    },
+    {
+      name: 'install lock: wx-create, live holder blocks, dead holder is taken over',
+      run: (ctx) => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'desktop-rm-lock-'));
+        ctx.state.lockRoot = root;
+
+        // Fresh acquire succeeds; a second acquire while OUR live pid holds it fails.
+        ctx.expect(install.acquireInstallLock(root, { pid: process.pid, hostAppId: 'a' })).toBe(true);
+        ctx.expect(install.acquireInstallLock(root, { pid: process.pid, hostAppId: 'b' })).toBe(false);
+
+        // Dead holder → takeover (999999 is far above any real pid on the runner).
+        fs.writeFileSync(path.join(root, 'install.lock'), JSON.stringify({ pid: 999999, hostAppId: 'ghost', acquiredAt: Date.now() }));
+        ctx.expect(install.acquireInstallLock(root, { pid: process.pid, hostAppId: 'c' })).toBe(true);
+
+        // Stale timestamp (even with a live pid) → takeover.
+        fs.writeFileSync(path.join(root, 'install.lock'), JSON.stringify({ pid: process.pid, hostAppId: 'old', acquiredAt: Date.now() - 11 * 60 * 1000 }));
+        ctx.expect(install.acquireInstallLock(root, { pid: process.pid, hostAppId: 'd' })).toBe(true);
+
+        // Release then re-acquire.
+        install.releaseInstallLock(root);
+        ctx.expect(install.acquireInstallLock(root, { pid: process.pid, hostAppId: 'e' })).toBe(true);
+      },
+      cleanup: (ctx) => {
+        if (ctx.state.lockRoot) fs.rmSync(ctx.state.lockRoot, { recursive: true, force: true });
+      },
+    },
+    {
+      name: 'pidAlive: own pid true, absurd pid false, junk false',
+      run: (ctx) => {
+        ctx.expect(install.pidAlive(process.pid)).toBe(true);
+        ctx.expect(install.pidAlive(999999)).toBe(false);
+        ctx.expect(install.pidAlive(0)).toBe(false);
+        ctx.expect(install.pidAlive('12')).toBe(false);
+      },
+    },
+  ],
+});

package/dist/test/suites/build/restart-manager-protocol.test.js

@@ -0,0 +1,158 @@
+// Build-layer tests for lib/restart-manager/protocol.js — the protocol v1 SSOT
+// both @omega.js/desktop and the Restart Manager app import. Pure functions, plain Node.
+
+const path = require('path');
+const protocol = require('../../../lib/restart-manager/protocol.js');
+const defineCases = require('../../../vendor/devkit/test/define-cases.js');
+
+module.exports = defineCases({
+  type: 'suite',
+  layer: 'build',
+  description: 'restart-manager protocol SSOT (build)',
+  tests: [
+    {
+      name: 'constants: PROTOCOL_VERSION=1, endpoints complete and /v1/-prefixed',
+      run: (ctx) => {
+        ctx.expect(protocol.PROTOCOL_VERSION).toBe(1);
+        const endpoints = ['health', 'register', 'deregister', 'apps'];
+        for (const key of endpoints) {
+          ctx.expect(typeof protocol.ENDPOINTS[key]).toBe('string');
+          ctx.expect(protocol.ENDPOINTS[key].startsWith('/v1/')).toBe(true);
+        }
+        // No /v1/quit — RM self-updates via @omega.js/desktop's autoUpdater; nothing external quits it.
+        ctx.expect(Object.keys(protocol.ENDPOINTS).length).toBe(endpoints.length);
+      },
+    },
+    {
+      name: 'resolveSharedRoot: default under appData, OMEGA_RM_ROOT override wins',
+      run: (ctx) => {
+        const def = protocol.resolveSharedRoot('/x/appData', {});
+        ctx.expect(def).toBe(path.join('/x/appData', 'restart-manager'));
+
+        const overridden = protocol.resolveSharedRoot('/x/appData', { OMEGA_RM_ROOT: '/tmp/rm-isolated' });
+        ctx.expect(overridden).toBe('/tmp/rm-isolated');
+      },
+    },
+    {
+      name: 'path derivations hang off the shared root',
+      run: (ctx) => {
+        const root = '/x/appData/restart-manager';
+        ctx.expect(protocol.getRuntimePath(root)).toBe(path.join(root, 'runtime.json'));
+        ctx.expect(protocol.getAppDir(root)).toBe(path.join(root, 'app'));
+        ctx.expect(protocol.getLockPath(root)).toBe(path.join(root, 'install.lock'));
+      },
+    },
+    {
+      name: 'getInstalledAppPath: mac/linux in app/, win in LOCALAPPDATA Programs; unknown throws',
+      run: (ctx) => {
+        const root = '/r';
+        ctx.expect(protocol.getInstalledAppPath(root, 'darwin')).toBe(path.join(root, 'app', 'Restart Manager.app'));
+        ctx.expect(protocol.getInstalledAppPath(root, 'linux')).toBe(path.join(root, 'app', 'Restart-Manager.AppImage'));
+
+        // Windows: the NSIS per-user install location (self-updatable by
+        // electron-updater) — NOT the shared root.
+        const win = protocol.getInstalledAppPath(root, 'win32', { LOCALAPPDATA: 'C:\\Users\\x\\AppData\\Local' });
+        ctx.expect(win).toBe(path.join('C:\\Users\\x\\AppData\\Local', 'Programs', 'Restart Manager', 'Restart Manager.exe'));
+        ctx.expect(() => protocol.getInstalledAppPath(root, 'win32', {})).toThrow();
+        ctx.expect(() => protocol.getInstalledAppPath(root, 'freebsd')).toThrow();
+      },
+    },
+    {
+      name: 'validateRuntime: accepts the contract example',
+      run: (ctx) => {
+        const result = protocol.validateRuntime({
+          protocolVersion: 1,
+          port: 41234,
+          pid: 4242,
+          version: '1.0.0',
+          environment: 'production',
+          startedAt: new Date().toISOString(),
+        });
+        ctx.expect(result.valid).toBe(true);
+        ctx.expect(result.errors.length).toBe(0);
+      },
+    },
+    {
+      name: 'validateRuntime: rejects wrong version / bad port / bad pid / non-object',
+      run: (ctx) => {
+        const base = { protocolVersion: 1, port: 4000, pid: 1, version: '1.0.0', environment: 'production', startedAt: 'x' };
+
+        ctx.expect(protocol.validateRuntime({ ...base, protocolVersion: 2 }).valid).toBe(false);
+        ctx.expect(protocol.validateRuntime({ ...base, port: 0 }).valid).toBe(false);
+        ctx.expect(protocol.validateRuntime({ ...base, port: 70000 }).valid).toBe(false);
+        ctx.expect(protocol.validateRuntime({ ...base, port: '80' }).valid).toBe(false);
+        ctx.expect(protocol.validateRuntime({ ...base, pid: undefined }).valid).toBe(false);
+        ctx.expect(protocol.validateRuntime(null).valid).toBe(false);
+        ctx.expect(protocol.validateRuntime([]).valid).toBe(false);
+
+        // Errors carry field names so callers can log precisely.
+        const bad = protocol.validateRuntime({ ...base, port: 0, pid: -1 });
+        const fields = bad.errors.map((e) => e.field);
+        ctx.expect(fields).toContain('port');
+        ctx.expect(fields).toContain('pid');
+      },
+    },
+    {
+      name: 'validateRegisterPayload: accepts a wire-ready payload',
+      run: (ctx) => {
+        const result = protocol.validateRegisterPayload({
+          protocolVersion: 1,
+          id: 'somiibo',
+          name: 'Somiibo',
+          pid: 1234,
+          path: '/Applications/Somiibo.app/Contents/MacOS/Somiibo',
+          version: '2.0.0',
+          environment: 'production',
+        });
+        ctx.expect(result.valid).toBe(true);
+      },
+    },
+    {
+      name: 'validateRegisterPayload: rejects each bad field with a named error',
+      run: (ctx) => {
+        const good = {
+          protocolVersion: 1, id: 'app', name: 'App', pid: 1,
+          path: '/abs/path', version: '1.0.0', environment: 'production',
+        };
+        const cases = [
+          [{ ...good, protocolVersion: 99 }, 'protocolVersion'],
+          [{ ...good, id: '' },              'id'],
+          [{ ...good, name: 7 },             'name'],
+          [{ ...good, pid: 1.5 },            'pid'],
+          [{ ...good, path: 'relative/x' },  'path'],
+          [{ ...good, version: '' },         'version'],
+          [{ ...good, environment: 'prod' }, 'environment'],
+        ];
+        for (const [payload, field] of cases) {
+          const result = protocol.validateRegisterPayload(payload);
+          ctx.expect(result.valid).toBe(false);
+          ctx.expect(result.errors.map((e) => e.field)).toContain(field);
+        }
+      },
+    },
+    {
+      name: 'validateDeregisterPayload: id + pid required',
+      run: (ctx) => {
+        ctx.expect(protocol.validateDeregisterPayload({ id: 'app', pid: 12 }).valid).toBe(true);
+        ctx.expect(protocol.validateDeregisterPayload({ id: '', pid: 12 }).valid).toBe(false);
+        ctx.expect(protocol.validateDeregisterPayload({ id: 'app' }).valid).toBe(false);
+        ctx.expect(protocol.validateDeregisterPayload(null).valid).toBe(false);
+      },
+    },
+    {
+      name: 'buildRegisterPayload stamps protocolVersion and round-trips validation',
+      run: (ctx) => {
+        const payload = protocol.buildRegisterPayload({
+          id: 'somiibo',
+          name: 'Somiibo',
+          pid: 999,
+          path: '/Applications/Somiibo.app/Contents/MacOS/Somiibo',
+          version: '2.0.0',
+          environment: 'development',
+        });
+        ctx.expect(payload.protocolVersion).toBe(protocol.PROTOCOL_VERSION);
+        ctx.expect(protocol.validateRegisterPayload(payload).valid).toBe(true);
+      },
+    },
+  ],
+});