npm - @mwguerra/hull - Versions diffs - 0.1.0 - Mend

@mwguerra/hull 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/LICENSE +21 -0
package/README.md +631 -0
package/assets/hull-logo.png +0 -0
package/assets/hull-logo.svg +5 -0
package/bin/hull.js +4 -0
package/devtools/dist/index.html +29 -0
package/host/CMakeLists.txt +101 -0
package/host/README.md +94 -0
package/host/linux.Dockerfile +26 -0
package/host/src/bindings/credentials.hpp +35 -0
package/host/src/bindings/database.hpp +51 -0
package/host/src/bindings/files.hpp +58 -0
package/host/src/bindings/http.hpp +84 -0
package/host/src/bindings/printer.hpp +281 -0
package/host/src/bindings/storage.hpp +71 -0
package/host/src/db_core.hpp +198 -0
package/host/src/dispatcher.hpp +81 -0
package/host/src/file_store.hpp +91 -0
package/host/src/keychain.hpp +157 -0
package/host/src/main.cpp +386 -0
package/host/src/paths.hpp +62 -0
package/host/src/secure.hpp +124 -0
package/host/src/serve.hpp +113 -0
package/host/test/db_test.cpp +80 -0
package/host/test/secure_files_test.cpp +68 -0
package/host/third_party/sqlite/sqlite3.c +269376 -0
package/host/third_party/sqlite/sqlite3.h +14347 -0
package/package.json +58 -0
package/src/bridge/bridge-core.js +92 -0
package/src/bridge/index.js +139 -0
package/src/bridge/native-store.js +34 -0
package/src/cli/build.js +122 -0
package/src/cli/config.js +102 -0
package/src/cli/dev.js +158 -0
package/src/cli/eject.js +39 -0
package/src/cli/host.js +61 -0
package/src/cli/index.js +54 -0
package/src/cli/installer.js +265 -0
package/src/cli/release.js +178 -0
package/src/cli/start.js +45 -0
package/src/cli/timing.js +22 -0
package/src/cli/vite.js +16 -0
package/src/react/index.js +30 -0
package/src/vue/index.js +31 -0

package/src/cli/dev.js ADDED Viewed

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { loadConfig, hostArgs, hostEnv } from "./config.js";
+import { resolveHost } from "./host.js";
+import { loadVite } from "./vite.js";
+import { createTimer } from "./timing.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+const INSPECTOR_HTML = path.resolve(here, "../../devtools/dist/index.html"); // built single file
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function freePort() {
+  return new Promise((res, rej) => {
+    const s = net.createServer();
+    s.on("error", rej);
+    s.listen(0, "127.0.0.1", () => { const p = s.address().port; s.close(() => res(p)); });
+  });
+}
+function openUrl(url) {
+  const [cmd, args] =
+    process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+    : process.platform === "darwin" ? ["open", [url]]
+    : ["xdg-open", [url]];
+  try { spawn(cmd, args, { stdio: "ignore", detached: true }).unref(); } catch { /* ignore */ }
+}
+async function waitForHealth(url) {
+  for (let i = 0; i < 60; i++) {
+    try { const r = await fetch(`${url}/health`); if (r.ok) return true; } catch { /* not up yet */ }
+    await sleep(100);
+  }
+  return false;
+}
+// Make sure the dev server is actually serving the app before we open the native
+// window. server.listen() resolves when the port is bound, but on a cold start (or
+// after Vite re-optimizes deps) the first load can come back incomplete, and WebKitGTK
+// shows a blank page without retrying -> intermittent white screen in `hull dev`. So we
+// fetch the index, then warm the entry module (runs Vite's transform + dep optimize) so
+// the page the web view loads is already fully ready.
+async function waitForApp(server, url) {
+  let html = null;
+  for (let i = 0; i < 120 && html === null; i++) {            // ~6s
+    try { const r = await fetch(url); if (r.ok) html = await r.text(); } catch { /* not up */ }
+    if (html === null) await sleep(50);
+  }
+  if (!html) return;
+  const m = html.match(/<script[^>]*type=["']module["'][^>]*src=["']([^"']+)["']/i);
+  if (!m) return;
+  try { await server.warmupRequest?.(m[1]); } catch { /* best effort */ }
+  try { await fetch(new URL(m[1], url).href); } catch { /* best effort */ }
+}
+// Vite plugin (browser mode only): inject the bridge URL into every served page and
+// serve the inspector at /__hull/devtools. Never part of `hull build`.
+function devBrowserPlugin(bridgeUrl) {
+  const inject = (html) =>
+    html.replace(/<head>/i, `<head><script>window.__HULL_BRIDGE__=${JSON.stringify(bridgeUrl)};</script>`);
+  return {
+    name: "hull:dev-browser",
+    transformIndexHtml(html) { return inject(html); },
+    configureServer(server) {
+      server.middlewares.use("/__hull/devtools", (_req, res) => {
+        let html = "<!doctype html><p>Inspector not built. Run <code>npm run build:devtools</code>.</p>";
+        try { html = inject(fs.readFileSync(INSPECTOR_HTML, "utf8")); } catch { /* fall through */ }
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        res.end(html);
+      });
+    },
+  };
+}
+export async function dev(cwd, args, { verbose } = {}) {
+  const timer = createTimer(verbose);
+  const browser = args.includes("--browser");
+  const cfg = await loadConfig(cwd);
+  timer.step("config loaded");
+  const vite = await loadVite(cwd);
+  timer.step("vite loaded");
+  // ---- Browser mode: UI in your browser (full HMR), bridge over HTTP/SSE ----
+  if (browser) {
+    const port = await freePort();
+    const bridgeUrl = `http://127.0.0.1:${port}`;
+    const server = await vite.createServer({
+      root: cwd,
+      server: { open: false },
+      plugins: [devBrowserPlugin(bridgeUrl)],
+    });
+    await server.listen();
+    const appUrl = server.resolvedUrls?.local?.[0] ?? `http://localhost:5173/`;
+    timer.step("vite dev server");
+    const { binary } = await resolveHost({ secure: cfg.secure });
+    const host = spawn(binary, ["--serve", String(port), "--inspect", "--app-id", cfg.appId],
+                       { stdio: "inherit" });
+    await waitForHealth(bridgeUrl);
+    timer.step("host bridge server");
+    openUrl(appUrl);
+    openUrl(`${appUrl}__hull/devtools`);
+    console.log(`hull dev --browser${cfg.secure ? " (secure host)" : ""}:`);
+    console.log(`  app:       ${appUrl}`);
+    console.log(`  inspector: ${appUrl}__hull/devtools`);
+    console.log(`  bridge:    ${bridgeUrl}  (edit UI freely — just reload, no recompile)`);
+    timer.total("hull dev --browser ready");
+    const shutdown = async () => { try { host.kill(); } catch {} try { await server.close(); } catch {} process.exit(0); };
+    host.on("exit", shutdown);
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    return;
+  }
+  // ---- Native window mode: Vite dev server rendered in the host web view ----
+  // The app runs in the native window; the companion inspector opens as a browser tab
+  // fed by the host's trace server (same inspector UI as browser mode).
+  const inspectPort = await freePort();
+  const traceUrl = `http://127.0.0.1:${inspectPort}`;
+  const server = await vite.createServer({
+    root: cwd,
+    server: { open: false },
+    plugins: [devBrowserPlugin(traceUrl)], // serves the inspector at /__hull/devtools
+  });
+  await server.listen();
+  const url =
+    server.resolvedUrls?.local?.[0] ??
+    `http://localhost:${server.config.server.port ?? 5173}/`;
+  timer.step("vite dev server");
+  console.log(`hull dev: serving ${url}${cfg.secure ? " (secure host)" : ""}`);
+  // Don't open the window until the app is actually served (avoids a cold-start blank).
+  await waitForApp(server, url);
+  timer.step("dev server ready");
+  const { binary } = await resolveHost({ secure: cfg.secure });
+  // --inspect enables the trace; --inspect-port runs the trace server for the inspector.
+  const env = { ...process.env, ...hostEnv(cfg, { noSandbox: args.includes("--no-sandbox") }) };
+  const child = spawn(
+    binary,
+    ["--url", url, "--inspect", "--inspect-port", String(inspectPort), ...hostArgs(cfg)],
+    { stdio: "inherit", env });
+  timer.step("native window launched");
+  if (await waitForHealth(traceUrl)) {
+    openUrl(`${url}__hull/devtools`);
+    console.log(`  inspector: ${url}__hull/devtools`);
+  }
+  timer.total("hull dev ready");
+  const shutdown = async () => { try { await server.close(); } catch {} process.exit(0); };
+  child.on("exit", shutdown);
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}

package/src/cli/eject.js ADDED Viewed

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createTimer } from "./timing.js";
+// Copy the C++ host project into ./desktop so you can add custom native bindings
+// and compile your own host. The standard bindings (HTTP/storage/keychain/print)
+// are already there to extend. Requires a C++ toolchain (see desktop/README.md).
+export async function eject(cwd, _args, { verbose } = {}) {
+  const timer = createTimer(verbose);
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const hostSrc = path.resolve(here, "../../host"); // packages/hull/host
+  const dest = path.join(cwd, "desktop");
+  if (!fs.existsSync(hostSrc)) {
+    throw new Error(`bundled host sources not found at ${hostSrc}`);
+  }
+  if (fs.existsSync(dest)) {
+    throw new Error(`${path.relative(cwd, dest)} already exists — remove it first`);
+  }
+  timer.step("located host sources");
+  copyDir(hostSrc, dest);
+  timer.step("copied host project");
+  console.log(`hull eject: C++ host copied to ./desktop`);
+  console.log(`  add bindings under desktop/src/bindings, then build with CMake (see desktop/README.md).`);
+  timer.total("hull eject");
+}
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name === "build" || entry.name === "node_modules") continue; // skip artifacts
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}

package/src/cli/host.js ADDED Viewed

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+// Known target keys (os-arch), matching the platform package names.
+export const KNOWN_TARGETS = [
+  "win32-x64",
+  "darwin-arm64",
+  "linux-x64",
+];
+export const currentTarget = () => `${process.platform}-${process.arch}`;
+const here = path.dirname(fileURLToPath(import.meta.url));
+// Load a platform package's entry. We try a normal import first (works when the
+// package is installed for end users via the published optionalDependencies), then
+// fall back to the sibling path. The sibling path is identical in both layouts:
+//   monorepo:   packages/hull/src/cli  ->  ../../../hull-<key>
+//   installed:  @mwguerra/hull/src/cli ->  ../../../hull-<key>  (same @mwguerra scope)
+async function loadPlatform(key) {
+  try {
+    return await import(`@mwguerra/hull-${key}`);
+  } catch {
+    const rel = path.resolve(here, `../../../hull-${key}/index.js`);
+    if (fs.existsSync(rel)) return import(pathToFileURL(rel).href);
+    return null;
+  }
+}
+// The on-disk binary name for a platform + flavor.
+export function binaryName(key, secure) {
+  const base = secure ? "hull-host-secure" : "hull-host";
+  return key.startsWith("win32-") ? `${base}.exe` : base;
+}
+// Resolve a specific platform's prebuilt host. Returns null if neither the default
+// nor secure binary has been built yet (so callers can skip the platform).
+export async function resolveHostFor(key) {
+  const mod = await loadPlatform(key);
+  if (!mod || !mod.hostDir) return null;
+  const hostBinary = mod.hostBinary && fs.existsSync(mod.hostBinary) ? mod.hostBinary : null;
+  const secureBinary = mod.secureBinary && fs.existsSync(mod.secureBinary) ? mod.secureBinary : null;
+  if (!hostBinary && !secureBinary) return null;
+  return { key, pkg: `@mwguerra/hull-${key}`, hostDir: mod.hostDir, hostBinary, secureBinary };
+}
+// Resolve the runnable binary for the CURRENT platform and the requested flavor,
+// throwing a helpful error if it isn't built.
+export async function resolveHost({ secure = false } = {}) {
+  const key = currentTarget();
+  const found = await resolveHostFor(key);
+  const binary = found && (secure ? found.secureBinary : found.hostBinary);
+  if (binary) return { ...found, binary, secure };
+  const flavor = secure ? "secure host (-DHULL_CRYPTO=ON)" : "host";
+  throw new Error(
+    `no prebuilt Hull ${flavor} for "${key}".\n` +
+    `  Build it with "npm run build:host${secure ? ":secure" : ""}", install the published\n` +
+    `  @mwguerra/hull-${key}, or run "hull eject" to build from source.`
+  );
+}

package/src/cli/index.js ADDED Viewed

@@ -0,0 +1,54 @@
+import { dev } from "./dev.js";
+import { build } from "./build.js";
+import { start } from "./start.js";
+import { eject } from "./eject.js";
+import { installer } from "./installer.js";
+const HELP = `
+hull — tiny native desktop apps from your web UI
+Usage: hull <command> [options]
+  dev        Start the Vite dev server and open it in a native window (HMR)
+  build      Build the single-file UI and package it with the native host
+  start      Run the packaged app from ./release
+  installer  Wrap the build into a native installer (.dmg / .deb / .exe)
+  eject      Copy the C++ host project into ./desktop for custom native code
+  help       Show this help
+Options:
+  -v, --verbose   Print per-step timings (every command also prints its total time)
+Config is optional. Defaults come from package.json; override in .hullrc:
+  { "appId": "com.you.app", "secure": false, "window": { "title": "App" } }
+`;
+export async function run(argv) {
+  const verbose = argv.includes("-v") || argv.includes("--verbose");
+  const rest = argv.filter((a) => a !== "-v" && a !== "--verbose");
+  const [cmd, ...args] = rest;
+  const cwd = process.cwd();
+  const opts = { verbose };
+  try {
+    switch (cmd) {
+      case "dev":   await dev(cwd, args, opts);   break;
+      case "build": await build(cwd, args, opts); break;
+      case "start": await start(cwd, args, opts); break;
+      case "installer": await installer(cwd, args, opts); break;
+      case "eject": await eject(cwd, args, opts); break;
+      case undefined:
+      case "help":
+      case "-h":
+      case "--help":
+        console.log(HELP);
+        break;
+      default:
+        console.error(`hull: unknown command "${cmd}"`);
+        console.log(HELP);
+        process.exit(1);
+    }
+  } catch (e) {
+    console.error(`hull ${cmd ?? ""}: ${e.message}`);
+    process.exit(1);
+  }
+}

package/src/cli/installer.js ADDED Viewed

@@ -0,0 +1,265 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { loadConfig } from "./config.js";
+import { currentTarget, binaryName } from "./host.js";
+import { parseVersion, sanitize } from "./release.js";
+import { createTimer } from "./timing.js";
+// hull installer [vX.Y.Z]
+// Wrap the already-built bundle for the CURRENT platform into a native installer:
+//   macOS   -> .dmg   (hdiutil; the .app + an Applications drop-link)
+//   Linux   -> .deb   (dpkg-deb; installs to /opt + a .desktop + icon, declares deps)
+//   Windows -> .exe   (Inno Setup; per-user install, Start Menu/Desktop shortcuts)
+// Each runs on its own OS (the packaging tools are OS-native). Run `hull build` first.
+export async function installer(cwd, args, { verbose } = {}) {
+  const timer = createTimer(verbose);
+  const version = args.find((a) => !a.startsWith("-")) ?? null;
+  const { label } = parseVersion(version);
+  const cfg = await loadConfig(cwd);
+  const key = currentTarget();
+  const outDir = path.join(cwd, cfg.releaseDir, label);
+  const bundleDir = path.join(outDir, key + (cfg.secure ? "-secure" : ""));
+  if (!fs.existsSync(bundleDir)) {
+    const v = label === "development" ? "" : " " + label;
+    throw new Error(`no build at ${path.relative(cwd, bundleDir)}. Run "hull build${v}" first.`);
+  }
+  const base = `${sanitize(cfg.title)}-${label}-${key}${cfg.secure ? "-secure" : ""}`;
+  const ver = label === "development" ? "0.0.0" : label.replace(/^v/, ""); // installer version
+  const binName = binaryName(key, cfg.secure); // hull-host[-secure][.exe]
+  timer.step("located build");
+  let out;
+  if (process.platform === "darwin") out = macDmg(bundleDir, outDir, base, cfg);
+  else if (process.platform === "win32") out = winInno(bundleDir, outDir, base, cfg, ver, binName);
+  else out = linuxDeb(bundleDir, outDir, base, cfg, key, ver, binName);
+  const rel = path.relative(cwd, out).replace(/\\/g, "/");
+  console.log(`\nhull installer: ${rel}  (${(fs.statSync(out).size / 1048576).toFixed(1)} MB)`);
+  timer.total("hull installer");
+}
+// ---------------------------------- macOS (.dmg) ----------------------------------
+function macDmg(bundleDir, outDir, base, cfg) {
+  const appName = `${sanitize(cfg.title)}.app`;
+  const appPath = path.join(bundleDir, appName);
+  if (!fs.existsSync(appPath)) {
+    throw new Error(`no ${appName} in the build — run "hull build" on macOS first.`);
+  }
+  const stage = path.join(outDir, ".dmg-stage");
+  fs.rmSync(stage, { recursive: true, force: true });
+  fs.mkdirSync(stage, { recursive: true });
+  execFileSync("cp", ["-R", appPath, path.join(stage, appName)]);
+  try { fs.symlinkSync("/Applications", path.join(stage, "Applications")); } catch { /* exists */ }
+  const dmg = path.join(outDir, `${base}.dmg`);
+  fs.rmSync(dmg, { force: true });
+  execFileSync("hdiutil", ["create", "-volname", cfg.title, "-srcfolder", stage,
+                           "-ov", "-format", "UDZO", dmg], { stdio: "inherit" });
+  fs.rmSync(stage, { recursive: true, force: true });
+  return dmg;
+}
+// ---------------------------------- Linux (.deb) ----------------------------------
+function debArch(key) {
+  return key.endsWith("-arm64") ? "arm64" : "amd64";
+}
+function debName(cfg) {
+  // Debian package names: lowercase letters, digits, '+', '-', '.'; start alphanumeric.
+  const base = (cfg.appId?.split(".").pop() || sanitize(cfg.title)).toLowerCase();
+  return base.replace(/[^a-z0-9+.-]+/g, "-").replace(/^[^a-z0-9]+/, "") || "hull-app";
+}
+// Resolve shared-library Depends from the binary using dpkg-shlibdeps (part of
+// dpkg-dev, present on any host that built the C++ host). Version-proof: it emits the
+// exact runtime package names for the running distro. Falls back if unavailable.
+function computeDebDeps(stage, pkg, binName, cfg) {
+  try {
+    const debianDir = path.join(stage, "debian");
+    fs.mkdirSync(debianDir, { recursive: true });
+    fs.writeFileSync(path.join(debianDir, "control"),
+      `Source: ${pkg}\nMaintainer: ${cfg.appId}\n\nPackage: ${pkg}\nArchitecture: any\n`);
+    const out = execFileSync("dpkg-shlibdeps", ["-O", path.join("opt", pkg, binName)],
+      { cwd: stage, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    fs.rmSync(debianDir, { recursive: true, force: true });
+    const m = /shlibs:Depends=(.+)/.exec(out);
+    if (m && m[1].trim()) return m[1].trim();
+  } catch { /* dpkg-shlibdeps not available — use the fallback below */ }
+  const base = "libwebkitgtk-6.0-4, libgtk-4-1, libsecret-1-0, libcups2";
+  return cfg.secure ? `${base}, libsqlcipher0` : base;
+}
+const xmlEsc = (s) =>
+  String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+// Write /usr/share/metainfo/<appId>.metainfo.xml (AppStream) so App Center shows the
+// name, summary, license, developer, icon, and version/date instead of "Unknown".
+function writeMetainfo(stage, cfg, ver) {
+  const dir = path.join(stage, "usr", "share", "metainfo");
+  fs.mkdirSync(dir, { recursive: true });
+  const summary = (cfg.description || cfg.title).split("\n")[0].slice(0, 80);
+  const devId = cfg.appId.split(".").slice(0, 2).join(".") || cfg.appId; // e.g. com.you
+  const devName = cfg.publisher || devId;
+  const date = new Date().toISOString().slice(0, 10);
+  const xml =
+`<?xml version="1.0" encoding="UTF-8"?>
+<component type="desktop-application">
+  <id>${cfg.appId}</id>
+  <name>${xmlEsc(cfg.title)}</name>
+  <summary>${xmlEsc(summary)}</summary>
+  <metadata_license>CC0-1.0</metadata_license>
+${cfg.license ? `  <project_license>${xmlEsc(cfg.license)}</project_license>\n` : ""}  <description><p>${xmlEsc(cfg.description || cfg.title)}</p></description>
+  <launchable type="desktop-id">${cfg.appId}.desktop</launchable>
+  <icon type="stock">${cfg.appId}</icon>
+  <developer id="${xmlEsc(devId)}"><name>${xmlEsc(devName)}</name></developer>
+  <developer_name>${xmlEsc(devName)}</developer_name>
+  <content_rating type="oars-1.1"/>
+  <releases>
+    <release version="${ver}" date="${date}"/>
+  </releases>
+</component>
+`;
+  fs.writeFileSync(path.join(dir, `${cfg.appId}.metainfo.xml`), xml);
+}
+function linuxDeb(bundleDir, outDir, base, cfg, key, ver, binName) {
+  const pkg = debName(cfg);
+  const stage = path.join(outDir, ".deb-stage");
+  fs.rmSync(stage, { recursive: true, force: true });
+  // Payload -> /opt/<pkg>
+  const opt = path.join(stage, "opt", pkg);
+  fs.mkdirSync(opt, { recursive: true });
+  for (const e of fs.readdirSync(bundleDir)) {
+    fs.cpSync(path.join(bundleDir, e), path.join(opt, e), { recursive: true });
+  }
+  fs.chmodSync(path.join(opt, binName), 0o755);
+  // Launcher -> /usr/bin/<pkg>
+  const usrbin = path.join(stage, "usr", "bin");
+  fs.mkdirSync(usrbin, { recursive: true });
+  fs.writeFileSync(path.join(usrbin, pkg),
+    `#!/bin/sh\n` +
+    `exec /opt/${pkg}/${binName} --app /opt/${pkg}/app.html --title "${cfg.title}" ` +
+    `--app-id "${cfg.appId}" --width ${cfg.width} --height ${cfg.height} ` +
+    `--icon /opt/${pkg}/icon.png "$@"\n`, { mode: 0o755 });
+  // Desktop entry + icon -> the compositor matches the window (app-id) to this .desktop
+  const apps = path.join(stage, "usr", "share", "applications");
+  fs.mkdirSync(apps, { recursive: true });
+  const hasIcon = fs.existsSync(path.join(bundleDir, "icon.png"));
+  fs.writeFileSync(path.join(apps, `${cfg.appId}.desktop`),
+    `[Desktop Entry]\nType=Application\nName=${cfg.title}\nExec=/usr/bin/${pkg}\n` +
+    (hasIcon ? `Icon=${cfg.appId}\n` : "") +
+    `StartupWMClass=${cfg.appId}\nTerminal=false\nCategories=Utility;\n`);
+  if (hasIcon) {
+    const icons = path.join(stage, "usr", "share", "icons", "hicolor", "256x256", "apps");
+    fs.mkdirSync(icons, { recursive: true });
+    fs.copyFileSync(path.join(bundleDir, "icon.png"), path.join(icons, `${cfg.appId}.png`));
+  }
+  // AppStream MetaInfo -> rich metadata in GNOME Software / App Center (name, summary,
+  // license, developer, version/date, icon). Without it those fields show "Unknown".
+  writeMetainfo(stage, cfg, ver);
+  // Control metadata. Compute Depends from the actual binary via dpkg-shlibdeps so the
+  // package names are correct for THIS distro (Ubuntu 24.04 renamed many libs in the
+  // t64 transition); fall back to a best-effort list if dpkg-dev isn't installed.
+  const depends = computeDebDeps(stage, pkg, binName, cfg);
+  const desc = cfg.description || "A desktop app packaged with Hull.";
+  const deb = path.join(stage, "DEBIAN");
+  fs.mkdirSync(deb, { recursive: true });
+  fs.writeFileSync(path.join(deb, "control"),
+    `Package: ${pkg}\nVersion: ${ver}\nArchitecture: ${debArch(key)}\n` +
+    `Maintainer: ${cfg.publisher || cfg.appId}\nDepends: ${depends}\nSection: utils\n` +
+    `Priority: optional\nDescription: ${cfg.title}\n ${desc}\n`);
+  const outFile = path.join(outDir, `${base}.deb`);
+  fs.rmSync(outFile, { force: true });
+  execFileSync("dpkg-deb", ["--build", "--root-owner-group", stage, outFile], { stdio: "inherit" });
+  fs.rmSync(stage, { recursive: true, force: true });
+  return outFile;
+}
+// ---------------------------------- Windows (.exe) ----------------------------------
+function findISCC() {
+  const local = process.env.LOCALAPPDATA || path.join(process.env.USERPROFILE || "", "AppData", "Local");
+  for (const p of [
+    "C:/Program Files (x86)/Inno Setup 6/ISCC.exe",
+    "C:/Program Files/Inno Setup 6/ISCC.exe",
+    path.join(local, "Programs", "Inno Setup 6", "ISCC.exe"), // winget per-user install
+  ]) if (fs.existsSync(p)) return p;
+  return null;
+}
+// Wrap a PNG into a (Vista+) PNG-compressed .ico so Explorer/shortcuts show the logo.
+function pngToIco(png) {
+  const w = png.readUInt32BE(16), h = png.readUInt32BE(20); // PNG IHDR width/height
+  const head = Buffer.alloc(22);
+  head.writeUInt16LE(0, 0); head.writeUInt16LE(1, 2); head.writeUInt16LE(1, 4); // dir: type=icon, count=1
+  head.writeUInt8(w >= 256 ? 0 : w, 6); head.writeUInt8(h >= 256 ? 0 : h, 7);   // 0 means 256
+  head.writeUInt8(0, 8); head.writeUInt8(0, 9);
+  head.writeUInt16LE(1, 10); head.writeUInt16LE(32, 12);  // planes=1, bpp=32
+  head.writeUInt32LE(png.length, 14); head.writeUInt32LE(22, 18); // size, offset
+  return Buffer.concat([head, png]);
+}
+function winInno(bundleDir, outDir, base, cfg, ver, binName) {
+  const iscc = findISCC();
+  if (!iscc) {
+    throw new Error(
+      "Inno Setup not found. Install it once, then re-run:\n" +
+      "  winget install JRSoftware.InnoSetup");
+  }
+  // App icon for shortcuts (from the bundled icon.png).
+  const png = path.join(bundleDir, "icon.png");
+  let icoLine = "";
+  if (fs.existsSync(png)) {
+    fs.writeFileSync(path.join(bundleDir, "icon.ico"), pngToIco(fs.readFileSync(png)));
+    icoLine = `IconFilename: "{app}\\icon.ico"`;
+  }
+  const guid = crypto.createHash("md5").update(cfg.appId).digest("hex").toUpperCase();
+  // GUID without braces; the .iss writes `{{<guid>}` so Inno stores it as `{<guid>}`.
+  const g = `${guid.slice(0, 8)}-${guid.slice(8, 12)}-${guid.slice(12, 16)}-${guid.slice(16, 20)}-${guid.slice(20)}`;
+  // Inno treats `{` as a constant delimiter (escape as `{{`); inside quoted values `"`
+  // is doubled. Keeps a title/appId containing { or " from breaking the generated .iss.
+  const issStr = (s) => String(s).replace(/\{/g, "{{");
+  const t = issStr(cfg.title);                       // for unquoted directives
+  const tq = t.replace(/"/g, '""');                  // for quoted contexts
+  const appIdq = issStr(cfg.appId).replace(/"/g, '""');
+  const params =
+    `--app ""{app}\\app.html"" --title ""${tq}"" --app-id ""${appIdq}"" ` +
+    `--width ${cfg.width} --height ${cfg.height} --icon ""{app}\\icon.png""`;
+  const iss =
+`[Setup]
+AppId={{${g}}
+AppName=${t}
+AppVersion=${ver}
+DefaultDirName={autopf}\\${sanitize(cfg.title)}
+DefaultGroupName=${t}
+UninstallDisplayIcon={app}\\${binName}
+OutputDir=${outDir}
+OutputBaseFilename=${base}
+Compression=lzma2
+SolidCompression=yes
+PrivilegesRequired=lowest
+ArchitecturesInstallIn64BitMode=x64compatible
+[Files]
+Source: "${bundleDir}\\*"; DestDir: "{app}"; Flags: recursesubdirs ignoreversion
+[Icons]
+Name: "{group}\\${tq}"; Filename: "{app}\\${binName}"; Parameters: "${params}"; ${icoLine}
+Name: "{autodesktop}\\${tq}"; Filename: "{app}\\${binName}"; Parameters: "${params}"; ${icoLine}
+Name: "{group}\\Uninstall ${tq}"; Filename: "{uninstallexe}"
+[Run]
+Filename: "{app}\\${binName}"; Parameters: "${params}"; Description: "Launch ${tq}"; Flags: nowait postinstall skipifsilent
+`;
+  const issPath = path.join(outDir, `${base}.iss`);
+  fs.writeFileSync(issPath, iss);
+  execFileSync(iscc, [issPath], { stdio: "inherit" });
+  fs.rmSync(issPath, { force: true });
+  return path.join(outDir, `${base}.exe`);
+}