@tn3270/gui 0.0.0-stage → 0.1.0

package/bin/launch.d.mts

@@ -0,0 +1,10 @@
+/** Types for `launch.mjs`, so its test is typechecked. */
+export const FORWARDED: readonly NodeJS.Signals[];
+export function exitPlan(
+  code: number | null,
+  signal: NodeJS.Signals | null,
+  platform?: NodeJS.Platform,
+): { exit: number } | { raise: NodeJS.Signals };
+export function electronMissing(err: unknown): string;
+export function bundleMissing(path: string): string;
+export function sandboxHint(chromeSandbox: string): string;

package/bin/launch.mjs

@@ -0,0 +1,56 @@
+/**
+ * The launcher's decisions, as pure functions, so they can be tested without Electron.
+ * `tn3270-gui.mjs` is the only caller; it does the I/O.
+ */
+import { constants } from 'node:os';
+
+/** Signals the launcher forwards to Electron. SIGHUP is the terminal closing. */
+export const FORWARDED = Object.freeze(['SIGINT', 'SIGTERM', 'SIGHUP']);
+
+/**
+ * Signals worth RE-RAISING on the launcher when Electron died of one, so a parent shell or
+ * harness sees "killed by SIGTERM" rather than an exit code. Anything else -- SIGTRAP from
+ * Chromium's sandbox abort, SIGSEGV -- would make Node dump core if re-raised, so it becomes the
+ * shell convention `128 + n` instead.
+ */
+const RERAISE = new Set(['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGKILL']);
+
+/**
+ * What the launcher does once Electron has exited: `{ exit: n }` or `{ raise: signal }`.
+ * `platform` is a parameter only for the tests.
+ */
+export function exitPlan(code, signal, platform = process.platform) {
+  if (signal === null || signal === undefined) return { exit: code ?? 1 };
+  // Windows has no signal delivery to itself worth the name: `process.kill(pid, sig)` there
+  // terminates outright, so an exit code says more.
+  if (platform !== 'win32' && RERAISE.has(signal)) return { raise: signal };
+  return { exit: 128 + (constants.signals[signal] ?? 0) };
+}
+
+/** The message for `require('electron')` throwing: the binary was never downloaded, or failed. */
+export function electronMissing(err) {
+  return 'tn3270-gui: the Electron binary is not installed.\n'
+    + `  (${err instanceof Error ? err.message : String(err)})\n`
+    + '  Electron 44 downloads its ~100 MB binary on first use, so this means that download failed\n'
+    + '  (no network, a proxy, or ELECTRON_MIRROR pointing somewhere wrong). Fix the network and\n'
+    + '  run tn3270-gui again, or reinstall: npm install -g @tn3270/gui\n';
+}
+
+/** The message for a package whose `app/` bundle is incomplete. */
+export function bundleMissing(path) {
+  return `tn3270-gui: reinstall @tn3270/gui (npm install -g @tn3270/gui): ${path} is missing, `
+    + 'so this install has no complete app bundle to run.\n';
+}
+
+/**
+ * Printed after Electron dies of SIGTRAP on Linux, which is how Chromium's "SUID sandbox helper
+ * binary was found, but is not configured correctly" abort arrives. Chromium's own FATAL line,
+ * just above on stderr, names only the chown/chmod fix; this names the other two.
+ */
+export function sandboxHint(chromeSandbox) {
+  return '\ntn3270-gui: Electron aborted. If the line above mentions the SUID sandbox helper, this\n'
+    + "  system blocks unprivileged user namespaces, which Chromium's sandbox needs when\n"
+    + '  chrome-sandbox is not setuid root (npm cannot install it setuid). Either, as root:\n'
+    + `    chown root:root ${chromeSandbox} && chmod 4755 ${chromeSandbox}\n`
+    + '  or run without the sandbox, at your own risk: tn3270-gui --no-sandbox ...\n';
+}

package/bin/tn3270-gui.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * `tn3270-gui`: runs the bundled app (`../app/main.js`) under the Electron that npm installed
+ * beside it, with the user's arguments. The decisions are in `launch.mjs`, tested without Electron.
+ *
+ * ## WHY NOT ELECTRON'S OWN BIN
+ *
+ * `electron/cli.js` forwards only SIGINT, SIGTERM and SIGUSR2 and never kills its child when it
+ * dies itself, so a harness's SIGKILL in this repo orphaned the real binary to PID 1 (see
+ * `scripts/xvfb.mjs`). This one forwards SIGINT/SIGTERM/SIGHUP, kills Electron if the launcher
+ * exits first, and exits with Electron's code -- or re-raises its signal. A SIGKILL to the
+ * launcher still cannot be forwarded (nothing can catch it); kill Electron's PID for that.
+ *
+ * ## THE SANDBOX IS LEFT ON -- MEASURED 2026-11-06, Electron 44.10.2, Rocky 9 kernel 5.14
+ *
+ * npm cannot install `chrome-sandbox` setuid root (here it is `athor 0755`). That does NOT stop
+ * Electron: Chromium prefers the user-namespace sandbox and only falls back to the SUID helper
+ * when namespaces are blocked. On this box the app ran and drew the golden pixels WITHOUT
+ * `--no-sandbox`; forcing the SUID path (`--disable-namespace-sandbox`) reproduced the abort
+ * ("SUID sandbox helper binary was found, but is not configured correctly"), exit by SIGTRAP.
+ * So adding `--no-sandbox` automatically would switch the sandbox off on every system that can
+ * run it, to help only those that block unprivileged namespaces (Ubuntu 23.10+ AppArmor, some
+ * hardened kernels). Electron's own npm launcher (`electron/cli.js`, read 2026-11-06) makes the
+ * same choice: it never adds `--no-sandbox`. The user passes it, or fixes the helper's ownership
+ * (what distro packages of Electron apps do in a postinst). We print both remedies when Electron
+ * dies of
+ * SIGTRAP on Linux, and `--no-sandbox` on the command line passes straight through to Chromium
+ * (main.ts strips it from what our own parser sees).
+ *
+ * ## WINDOWS -- NOT RUN THERE YET
+ *
+ * Node emulates SIGINT/SIGHUP delivery only from the console, and `child.kill()` there is
+ * TerminateProcess whatever the signal, so forwarding degrades to "kill Electron when asked to
+ * stop". Re-raising is replaced by an exit code (`exitPlan`), and `process.kill` is guarded.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FORWARDED, bundleMissing, electronMissing, exitPlan, sandboxHint } from './launch.mjs';
+
+const app = join(dirname(fileURLToPath(import.meta.url)), '..', 'app');
+const main = join(app, 'main.js');
+
+// BOTH, because bundle.mjs writes BUNDLED last: main.js without it is a bundle that failed its
+// own self-check. Without this, Electron given a missing path opens its default window.
+for (const f of [main, join(app, 'BUNDLED')]) {
+  if (!existsSync(f)) {
+    process.stderr.write(bundleMissing(f));
+    process.exit(1);
+  }
+}
+
+let electron;
+try {
+  // In Node, `require('electron')` is the binary's PATH -- and, in Electron 44, downloads the
+  // binary first if npm's install never did. It throws if that download fails.
+  electron = createRequire(import.meta.url)('electron');
+} catch (err) {
+  process.stderr.write(electronMissing(err));
+  process.exit(1);
+}
+
+const child = spawn(electron, [main, ...process.argv.slice(2)], { stdio: 'inherit', windowsHide: false });
+
+for (const sig of FORWARDED) {
+  process.on(sig, () => {
+    if (child.exitCode === null && child.signalCode === null) child.kill(sig);
+  });
+}
+// Any way the launcher leaves before Electron does (an uncaught throw, process.exit elsewhere)
+// takes Electron with it, so no path here orphans it.
+process.on('exit', () => {
+  if (child.exitCode === null && child.signalCode === null) child.kill('SIGTERM');
+});
+
+child.on('error', (err) => {
+  process.stderr.write(`tn3270-gui: cannot start Electron (${electron}): ${err.message}\n`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal === 'SIGTRAP' && process.platform === 'linux') {
+    process.stderr.write(sandboxHint(join(dirname(electron), 'chrome-sandbox')));
+  }
+  const plan = exitPlan(code, signal);
+  if ('exit' in plan) process.exit(plan.exit);
+  // Our own handler for that signal would swallow it; drop it, then die of the same signal so the
+  // parent sees what Electron died of.
+  process.removeAllListeners(plan.raise);
+  try {
+    process.kill(process.pid, plan.raise);
+  } catch {
+    process.exit(1);
+  }
+});

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@tn3270/gui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "An Electron TN3270 emulator with a canvas renderer that blits glyphs from an atlas baked out of x3270's own 3270 bitmap font.",
+  "license": "MIT",
+  "author": "Adam Thornton <athornton@gmail.com>",
+  "type": "module",
+  "main": "./dist/main.js",
+  "bin": {
+    "tn3270-gui": "./bin/tn3270-gui.mjs"
+  },
+  "files": ["app", "bin", "README.md"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/athornton/tn3270.git",
+    "directory": "packages/gui"
+  },
+  "homepage": "https://github.com/athornton/tn3270#readme",
+  "engines": { "node": ">=22" },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "@tn3270/canvas": "0.1.0",
+    "@tn3270/core": "0.1.0",
+    "@tn3270/frontend": "0.1.0",
+    "@tn3270/node-files": "0.1.0",
+    "electron": "44.10.2"
+  },
+  "scripts": {
+    "build": "tsc --build"
+  }
+}