lg-dev-manager-bridge 1.0.0 → 1.0.2

package/README.md

@@ -1,39 +1,197 @@
-# lg-dev-manager-bridge
+# 📺 LG Dev Manager
 
-The local bridge for **[LG Dev Manager](https://lg.scoty.uk)** — manage LG webOS TVs (rooted or in Developer
-Mode) from your browser: install and update apps, the webOS Homebrew repository, files, a shell, logs and more.
+Manage LG webOS TVs from your browser — rooted (Homebrew Channel) or in Developer Mode. Install apps from the
+webOS Homebrew repository or from an IPK file, update them, install any build of [Litefin](#litefin-in-one-click)
+in one click, browse the TV's files, open a shell, take screenshots, renew the Dev Mode session and dig into logs and
+the luna bus.
 
-Browsers can't speak SSH, so this small program does it for the web app, on your own computer.
+🌐 **Open it:** https://lg.scoty.uk — then run the bridge on your computer (one command, below).
+
+A web rebuild of [webosbrew/dev-manager-desktop](https://github.com/webosbrew/dev-manager-desktop), styled after
+[Adminator](https://github.com/puikinsh/adminator-admin-dashboard).
+
+> ⚠️ **Note:** LG Dev Manager is an independent, community project. It is not affiliated with, endorsed by or supported
+> by LG Electronics. LG and webOS are trademarks of LG Electronics. Rooting a TV or using Developer Mode is at your own
+> risk.
+
+### 🎬 Add a TV, install an app and update it
+
+![Adding the Living Room TV with the wizard, installing Moonfin 2.8.2 from an IPK file and updating it to 2.9.0 from the Homebrew repository](https://raw.githubusercontent.com/Scoty/lg-dev-manager/main/docs/demo-basic.webp)
+
+### 🐞 Debug tools on a rooted TV
+
+![Switching to the Bedroom TV and going through the system log, log levels, kernel log, crash reports and the luna monitor](https://raw.githubusercontent.com/Scoty/lg-dev-manager/main/docs/demo-advanced.webp)
+
+## 🚀 Get started
+
+The app needs a small helper on your computer, **the bridge** (why: [How it works](#how-it-works)). There are three
+ways to run it. It's the same bridge every time, so pick whichever suits you:
+
+| | Needs | How |
+|---|---|---|
+| 🖥️ **The app** | nothing | Download it from the [latest release](https://github.com/Scoty/lg-dev-manager/releases/latest) and open it |
+| 📦 **npx** | Node.js 22.12+ | `npx lg-dev-manager-bridge@latest` in a terminal |
+| 🛠️ **From the source code** | Node.js 22.12+ | [Clone, build and run](#run-from-source) |
+
+### 🖥️ Option 1: the app — no Node.js needed
+
+One file with everything inside. Download the one for your computer from the
+[latest release](https://github.com/Scoty/lg-dev-manager/releases/latest):
+
+| Computer | File |
+|---|---|
+| 🪟 Windows | `lg-dev-manager-bridge-<version>-windows-x64.exe` — just run it (also works on Windows on ARM) |
+| 🍎 Mac with Apple Silicon (M1 and newer) | `…-macos-arm64.dmg` — open it, then double-click `lg-dev-manager-bridge` |
+| 🍎 Mac with Intel | `…-macos-x64.dmg` |
+| 🐧 Linux (x64 / ARM64) | `…-linux-x64.tar.gz` / `…-linux-arm64.tar.gz` — `tar -xzf …`, then `./lg-dev-manager-bridge` |
+
+A window opens with the **pairing token**, and https://lg.scoty.uk opens in your browser. Keep the window open while you
+use the app; closing it stops the bridge.
+
+> 🔐 **The first time:** the app isn't signed by Apple or Microsoft (that costs a yearly fee), so your computer asks
+> before running it. **Windows**: "Windows protected your PC" → **More info** → **Run anyway**. **macOS**: "Apple
+> could not verify…" → **Done**, then **System Settings → Privacy & Security** → **Open Anyway**. You only do this
+> once. It's the same code as the npm package, built and tested by GitHub Actions in public. Each release lists
+> SHA-256 checksums.
+
+### 📦 Option 2: npx
+
+**You need [Node.js](https://nodejs.org) 22.12 or newer** (any current LTS — 22 or 24). `node --version` shows
+yours. In a terminal:
 
 ```bash
 npx lg-dev-manager-bridge@latest
 ```
 
-Then open **https://lg.scoty.uk** (or the local copy at **http://localhost:5199**), go to **Bridge** and paste the
-pairing token it printed. Needs Node.js 22 or newer.
+It prints a **pairing token**. Keep the terminal open while you use the app (Ctrl+C stops it).
+
+### 🔗 Then, whichever way you chose
 
-## Safety
+1. Open **https://lg.scoty.uk**, or the local page the bridge serves at **http://localhost:5199** — they are the
+   same app. On the **Bridge** page, paste the token.
+2. On **Devices → Add a TV**, pick your TV from the scan. Rooted TVs log in as root (Homebrew Channel's SSH server);
+   other TVs use the Developer Mode app and its passphrase.
 
-- Listens on `127.0.0.1` only; other devices on your network can't reach it.
-- Accepts connections only from the app's own pages, and only with the pairing token (kept in
-  `~/.lg-dev-manager/bridge.json`, readable only by you).
-- Stores nothing else: your TVs' addresses, keys and passwords stay in your browser and are sent with each request.
-- Offers fixed operations (list apps, install, read a log…), never a general network tunnel.
+🍎 On macOS, the first time the bridge looks for your TV, the system asks whether your terminal may find devices on the
+local network — choose **Allow**. 📱 Phones and tablets aren't supported: the bridge has to run on the same computer
+as the browser.
 
-## Options
+Which page to use is up to you. 🌐 **lg.scoty.uk** always has the latest version and needs nothing installed besides the
+bridge. 🏠 **http://localhost:5199** is served from your computer by the bridge itself, so it works even when the
+website can't be reached. Each keeps its own list of TVs (browsers store them per site); use **Export backup** / **Import backup** on
+the Devices page to move them.
+
+<a id="how-it-works"></a>
+
+## 🔧 How it works
+
+Browsers can't open SSH connections, so the app comes in two parts:
+
+```
+ Browser (lg.scoty.uk or localhost:5199)        Your computer                      Your TV
+ ┌──────────────────────────────────┐   WebSocket   ┌────────────────────┐   SSH / SFTP   ┌──────────────┐
+ │ Web app — your TVs, keys and     │ ────────────▶ │ Bridge             │ ─────────────▶ │ webOS        │
+ │ passwords are stored only here   │  127.0.0.1    │ (app or npx)       │                │ (port 22 or  │
+ └──────────────────────────────────┘  + token      └────────────────────┘                │  9922)       │
+                                                                                          └──────────────┘
+```
+
+- 🖥️ **The web app** is a static site. Saved TVs — names, addresses, keys and passwords — live only in your browser's
+  storage. They are never sent to the website; each request sends them to your own bridge, and only to it.
+- 🌉 **The bridge** is a small Node.js program that does the SSH, SFTP and HTTP work the browser can't. It listens on
+  `127.0.0.1` only (nothing else on your network can reach it), accepts only the app's own pages, needs the pairing
+  token, and keeps nothing on disk except that token. It offers fixed operations — list apps, install, read a log —
+  never a general "connect anywhere" tunnel.
+- 📦 **Homebrew repository and Litefin releases** are fetched by the bridge, so the site itself talks to no one but your
+  bridge. Downloads are checked against their published SHA-256 whenever one is published.
+
+🔄 The bridge tells the site its version; when a newer one is out, the app says so and how to update: download the
+new app from the [releases](https://github.com/Scoty/lg-dev-manager/releases/latest), or run
+`npx lg-dev-manager-bridge@latest` again. Your pairing and TVs stay as they are.
+
+## ✨ What it does
+
+- 📡 **Devices** — network scan, add rooted or Developer Mode TVs (key fetched from the TV's key server, or a new key
+  made for it), edit, test, export / import.
+- 📦 **Apps** — installed apps with update badges; install IPK files (drag and drop); the webOS **Homebrew repository**
+  with search, details, install and update; the **Litefin repo** with every webOS build of the latest releases
+  (see [below](#litefin-in-one-click)).
+- 📁 **Files** — browse, upload, download, preview, rename, delete over SFTP.
+- 💻 **Terminal** — full shell in tabs, plus a simple mode for TVs without a terminal.
+- ℹ️ **Device info** — model, webOS and firmware, Homebrew Channel status and update, screenshots, Dev Mode session
+  countdown and renewal.
+- 🐞 **Debug** — live system log and kernel log, PmLog levels, crash reports, luna bus monitor (rooted TVs).
+- 🧾 **Console** — every command the bridge runs on the TV, live, with the option to type your own.
+
+🌗 Light and dark themes, a command palette (⌘K / Ctrl K), and no analytics or tracking.
+
+<a id="litefin-in-one-click"></a>
+
+## 🍿 Litefin in one click
+
+This app started with one itch. [Litefin](https://github.com/MoazSalem/litefin), a lightweight Jellyfin client for
+LG TVs, publishes a separate IPK for each generation of webOS (Modern, Normal, Legacy, Ultra Legacy) on every
+release, and the Homebrew repository carries only one of them. Updating used to mean opening the GitHub releases,
+downloading the right IPK by hand and installing it through the desktop webOS Dev Manager.
+
+👉 **Apps → Litefin repo** does all of that in one click:
+
+- It lists the last five Litefin releases with every webOS build side by side, read straight from GitHub by the
+  bridge (pre-releases are skipped).
+- It suggests the right build for the active TV from its webOS version, and shows which version is installed and
+  whether a newer one is out.
+- **Install** downloads that build, checks it against GitHub's SHA-256 when one is published, and installs it on the TV
+  — through Homebrew Channel on a rooted TV, or the Developer Mode installer otherwise. All builds are the same app,
+  so switching builds or versions simply replaces it.
+
+<a id="run-from-source"></a>
+
+## 🛠️ Run the bridge from the source code
+
+The third way: run it from a clone. It's the same bridge, and it serves the local page too:
+
+```bash
+git clone https://github.com/Scoty/lg-dev-manager.git
+cd lg-dev-manager
+corepack enable      # once, to get pnpm
+pnpm install
+pnpm build
+pnpm bridge          # same as: node apps/bridge/dist/cli.js
+```
+
+This needs Node.js 22.12 or newer, the same as npx (the project itself is developed on Node 24, see `.nvmrc`).
+To update: `git pull`, `pnpm install`, `pnpm build`, then `pnpm bridge`.
+
+Bridge options (`--help`; with the app, run it from a terminal: `lg-dev-manager-bridge --help`):
 
 | Option | |
 |---|---|
 | `--port <n>` | Port to listen on (default 5199) |
 | `--no-ui` | Don't serve the local page |
-| `--web-root <dir>` | Serve the web app from another folder |
 | `--allow-origin <url>` | Also accept another origin, e.g. a self-hosted copy of the web app |
 | `--reset-token` | Make a new pairing token (un-pairs every browser) |
-| `--version`, `--help` | |
+| `--no-open` | The app only: don't open lg.scoty.uk in the browser when it starts |
+| `--license` | Show the licenses of the bridge and everything it includes |
+
+## 🧪 Development
+
+```bash
+pnpm install
+pnpm dev            # web app (Vite, http://localhost:5173) + bridge with --dev
+pnpm test           # unit and integration tests (against a mock TV)
+pnpm e2e            # Playwright: built app + real bridge + mock TVs + fake Homebrew repo
+pnpm dev:rig        # the same rig to try by hand: http://127.0.0.1:5299, token e2e-token
+pnpm lint && pnpm typecheck
+pnpm app            # the standalone app for this computer → apps/bridge/release (after pnpm build)
+```
+
+`tools/mock-tv` fakes webOS TVs (SSH, luna-send, key server, logs) so everything can be tested without a TV.
+Contributors, human or AI: read [AGENTS.md](https://github.com/Scoty/lg-dev-manager/blob/main/AGENTS.md) and [PLAN.md](https://github.com/Scoty/lg-dev-manager/blob/main/PLAN.md) first.
 
-Source, documentation and the from-source instructions: https://github.com/Scoty/lg-dev-manager
+## 📄 License
 
-Apache-2.0 — see LICENSE and NOTICE (credits the original
-[dev-manager-desktop](https://github.com/webosbrew/dev-manager-desktop) and Adminator).
+[Apache-2.0](https://github.com/Scoty/lg-dev-manager/blob/main/LICENSE). You may use, change and share the app and its code freely, including commercially, as long
+as you keep the license and the [NOTICE](https://github.com/Scoty/lg-dev-manager/blob/main/NOTICE) file that credits its authors — this project, the original
+[dev-manager-desktop](https://github.com/webosbrew/dev-manager-desktop) by the webOS Homebrew team, and Adminator.
 
 Not affiliated with or endorsed by LG Electronics. LG and webOS are trademarks of LG Electronics.

package/dist/cli.js

@@ -2,8 +2,8 @@
 
 // src/config.ts
 import { randomBytes } from "crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
-import { fileURLToPath } from "url";
+import { chmodSync, existsSync as existsSync2, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { homedir } from "os";
 import { join } from "path";
 
@@ -346,7 +346,9 @@ var Methods = {
     result: z9.object({
       protocolVersion: z9.number().int(),
       bridgeVersion: z9.string(),
-      platform: z9.string()
+      platform: z9.string(),
+      /** How the bridge was installed, so the site can say how to update it (bridges before 1.0.2 don't say). */
+      distribution: z9.enum(["app", "npm", "source"]).optional()
     })
   },
   "system.ping": {
@@ -737,6 +739,54 @@ var UNAUTHENTICATED_METHODS = ["system.hello"];
 var PUBLIC_WEB_ORIGIN = "https://lg.scoty.uk";
 var DEFAULT_ALLOWED_ORIGINS = [PUBLIC_WEB_ORIGIN];
 var DEV_ALLOWED_ORIGINS = ["http://localhost:5173", "http://127.0.0.1:5173"];
+var REPO_URL = "https://github.com/Scoty/lg-dev-manager";
+var RELEASES_URL = `${REPO_URL}/releases/latest`;
+
+// src/standalone.ts
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import * as sea from "sea";
+function isStandalone() {
+  try {
+    return sea.isSea();
+  } catch {
+    return false;
+  }
+}
+function distribution() {
+  if (isStandalone()) return "app";
+  try {
+    return existsSync(fileURLToPath(new URL("../src/", import.meta.url))) ? "source" : "npm";
+  } catch {
+    return "npm";
+  }
+}
+var WEB_MANIFEST_ASSET = "web-manifest.json";
+function standaloneUi() {
+  if (!isStandalone()) return void 0;
+  try {
+    const names = JSON.parse(sea.getAsset(WEB_MANIFEST_ASSET, "utf8"));
+    if (!Array.isArray(names)) return void 0;
+    const files = /* @__PURE__ */ new Map();
+    for (const name of names) {
+      if (typeof name === "string") files.set(name, new Uint8Array(sea.getAsset(`web/${name}`)));
+    }
+    return files.has("index.html") ? files : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function licenseText() {
+  if (!isStandalone()) {
+    return `Apache-2.0. See the LICENSE and NOTICE files next to this program, or https://github.com/Scoty/lg-dev-manager/blob/main/LICENSE
+`;
+  }
+  const rule = `
+${"=".repeat(78)}
+
+`;
+  return ["LICENSE", "NOTICE", "THIRD-PARTY-LICENSES.txt"].map((f) => sea.getAsset(f, "utf8").trim()).join(rule) + "\n";
+}
 
 // src/config.ts
 var stateDir = () => process.env.LGDM_STATE_DIR ?? join(homedir(), ".lg-dev-manager");
@@ -769,9 +819,14 @@ function loadOrCreateToken(reset = false) {
   return token;
 }
 function bundledUi() {
+  const packed = standaloneUi();
+  if (packed) return packed;
   for (const rel of ["../web/", "../../web/dist/"]) {
-    const dir = fileURLToPath(new URL(rel, import.meta.url));
-    if (existsSync(join(dir, "index.html"))) return dir;
+    try {
+      const dir = fileURLToPath2(new URL(rel, import.meta.url));
+      if (existsSync2(join(dir, "index.html"))) return dir;
+    } catch {
+    }
   }
   return void 0;
 }
@@ -837,7 +892,7 @@ import { platform } from "os";
 import { randomUUID as randomUUID2 } from "crypto";
 
 // src/version.ts
-var BRIDGE_VERSION = "1.0.0";
+var BRIDGE_VERSION = "1.0.2";
 
 // src/ssh/logged.ts
 import { randomUUID } from "crypto";
@@ -2603,7 +2658,7 @@ var handlers = {
       );
     }
     session.authed = true;
-    return { protocolVersion: PROTOCOL_VERSION, bridgeVersion: BRIDGE_VERSION, platform: platform() };
+    return { protocolVersion: PROTOCOL_VERSION, bridgeVersion: BRIDGE_VERSION, platform: platform(), distribution: distribution() };
   },
   "system.ping": () => ({ now: Date.now() }),
   "device.checkConnection": ({ host }) => checkConnection(host),
@@ -2870,7 +2925,7 @@ async function dispatch(raw, session, ctx) {
 
 // src/http/static.ts
 import { createReadStream, statSync } from "fs";
-import { extname, join as join2, normalize, resolve, sep } from "path";
+import { extname, join as join2, normalize, posix as posix4, resolve, sep } from "path";
 var MIME = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -2898,13 +2953,29 @@ var statOf = (file) => {
     return null;
   }
 };
+var headersFor = (name, size) => ({
+  "content-type": MIME[extname(name)] ?? "application/octet-stream",
+  "content-length": size,
+  "cache-control": name.endsWith("index.html") ? "no-cache" : "public, max-age=31536000, immutable",
+  ...SECURITY_HEADERS
+});
+function serveFiles(files, urlPath, req, res) {
+  let name = posix4.normalize(urlPath).replace(/^\/+/, "");
+  if (!files.has(name)) name = "index.html";
+  const body = files.get(name);
+  if (!body) {
+    res.writeHead(404, { "content-type": "text/plain", ...SECURITY_HEADERS }).end("Web UI missing from this build.");
+    return;
+  }
+  res.writeHead(200, headersFor(name, body.byteLength));
+  res.end(req.method === "HEAD" ? void 0 : body);
+}
 function serveStatic(root, req, res) {
   try {
     if (req.method !== "GET" && req.method !== "HEAD") {
       res.writeHead(405, { allow: "GET, HEAD", ...SECURITY_HEADERS }).end();
       return;
     }
-    const base = resolve(root);
     let urlPath;
     try {
       urlPath = decodeURIComponent((req.url ?? "/").split("?")[0] ?? "/");
@@ -2916,6 +2987,11 @@ function serveStatic(root, req, res) {
       res.writeHead(400, SECURITY_HEADERS).end();
       return;
     }
+    if (typeof root !== "string") {
+      serveFiles(root, urlPath, req, res);
+      return;
+    }
+    const base = resolve(root);
     let file = normalize(join2(base, urlPath));
     if (!file.startsWith(base + sep) && file !== base) {
       res.writeHead(403, SECURITY_HEADERS).end();
@@ -2930,12 +3006,7 @@ function serveStatic(root, req, res) {
       res.writeHead(404, { "content-type": "text/plain", ...SECURITY_HEADERS }).end("Web UI not built. Run `pnpm build`.");
       return;
     }
-    res.writeHead(200, {
-      "content-type": MIME[extname(file)] ?? "application/octet-stream",
-      "content-length": st.size,
-      "cache-control": file.endsWith("index.html") ? "no-cache" : "public, max-age=31536000, immutable",
-      ...SECURITY_HEADERS
-    });
+    res.writeHead(200, headersFor(file, st.size));
     if (req.method === "HEAD") {
       res.end();
       return;
@@ -4224,6 +4295,20 @@ function startServer(config, pool = new SshPool(), repo = new RepoClient(config.
   });
 }
 
+// src/open.ts
+import { spawn } from "child_process";
+function openInBrowser(url2) {
+  if (!/^https:\/\/[a-z0-9.-]+\/?$/i.test(url2)) return;
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url2]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url2]] : ["xdg-open", [url2]];
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+
 // src/cli.ts
 var HELP = `lg-dev-manager-bridge ${BRIDGE_VERSION}
 
@@ -4234,7 +4319,9 @@ Usage: lg-dev-manager-bridge [options]
   --web-root <dir>      Serve the web UI from this folder instead of the bundled one (env LGDM_WEB_ROOT)
   --no-ui               Don't serve the local page; use https://lg.scoty.uk only
   --reset-token         Generate a new pairing token (un-pairs existing browsers)
+  --no-open             The app only: don't open ${PUBLIC_WEB_ORIGIN} in the browser on start
   --version             Print the version
+  --license             Print the licenses of this program and what it includes
   --help                Show this help
 `;
 process.on("uncaughtException", (e) => console.error(`[bridge] unexpected error: ${e instanceof Error ? e.message : String(e)}`));
@@ -4250,6 +4337,10 @@ async function main() {
 `);
     return;
   }
+  if (argv.includes("--license")) {
+    process.stdout.write(licenseText());
+    return;
+  }
   const config = parseArgs(argv);
   await startServer(config);
   const shown = config.host;
@@ -4260,8 +4351,19 @@ async function main() {
   console.log(`  Pairing token  ${config.token}`);
   console.log(`  Allowed origins ${config.allowedOrigins.join(", ")}
 `);
+  if (isStandalone()) {
+    console.log("  Keep this window open while you use the app. Close it (or press Ctrl+C) to stop the bridge.\n");
+    if (!argv.includes("--no-open")) openInBrowser(PUBLIC_WEB_ORIGIN);
+  }
 }
 main().catch((e) => {
-  console.error(`[bridge] failed to start: ${e.message}`);
+  console.error(
+    e.code === "EADDRINUSE" ? `[bridge] failed to start: port ${/:(\d+)$/.exec(e.message)?.[1] ?? ""} is already in use. Is the bridge already running in another window? Close that one, or start this one with --port <another port>.` : `[bridge] failed to start: ${e.message}`
+  );
+  if (isStandalone() && process.stdin.isTTY) {
+    console.error("\nPress Enter to close this window.");
+    process.stdin.once("data", () => process.exit(1));
+    return;
+  }
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lg-dev-manager-bridge",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Local bridge for LG Dev Manager: lets the web app at lg.scoty.uk (or its local copy) manage LG webOS TVs over SSH",
   "license": "Apache-2.0",
   "author": "Scoty (https://github.com/Scoty)",
@@ -34,7 +34,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12"
   },
   "dependencies": {
     "ssh2": "^1.17.0",
@@ -45,12 +45,14 @@
     "@types/node": "^22.10.0",
     "@types/ssh2": "^1.15.6",
     "@types/ws": "^8.5.0",
+    "esbuild": "^0.27.7",
+    "postject": "1.0.0-alpha.6",
     "tsup": "^8.5.0",
     "tsx": "^4.20.0",
     "typescript": "^5.9.0",
     "vitest": "^4.1.11",
-    "@lgdm/mock-tv": "1.0.0",
-    "@lgdm/protocol": "1.0.0"
+    "@lgdm/mock-tv": "1.0.2",
+    "@lgdm/protocol": "1.0.2"
   },
   "scripts": {
     "dev": "tsx watch src/cli.ts --dev",