@mwguerra/hull 0.1.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@mwguerra/hull",
+  "version": "0.1.0",
+  "description": "Tiny native desktop apps from your Vue/React UI — a prebuilt C++ web-view host you drive with npm scripts. No compiler, no Electron.",
+  "type": "module",
+  "bin": {
+    "hull": "bin/hull.js"
+  },
+  "exports": {
+    "./bridge": "./src/bridge/index.js",
+    "./vue": "./src/vue/index.js",
+    "./react": "./src/react/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "devtools/dist",
+    "README.md",
+    "host/CMakeLists.txt",
+    "host/README.md",
+    "host/linux.Dockerfile",
+    "host/src",
+    "host/test",
+    "host/third_party"
+  ],
+  "keywords": [
+    "desktop",
+    "webview",
+    "native",
+    "vue",
+    "react",
+    "cpp",
+    "gui",
+    "electron-alternative",
+    "tauri-alternative"
+  ],
+  "author": "mwguerra",
+  "license": "MIT",
+  "dependencies": {
+    "archiver": "^7.0.0",
+    "vite-plugin-singlefile": "^2.1.0"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@mwguerra/hull-win32-x64": "0.1.0",
+    "@mwguerra/hull-darwin-arm64": "0.1.0",
+    "@mwguerra/hull-linux-x64": "0.1.0"
+  }
+}

package/src/bridge/bridge-core.js

@@ -0,0 +1,92 @@
+// Framework-agnostic transport for the native C++ bridge. Auto-selects:
+//   - "native": running inside the host web view (window.<binding> functions exist)
+//   - "http":   running in a normal browser with a Hull dev server
+//               (window.__HULL_BRIDGE__ = "http://127.0.0.1:<port>", injected by
+//                `hull dev --browser`) — invoke over POST, events over SSE
+//   - "none":   plain browser, no host (calls reject gracefully)
+//
+//  invoke(name, ...args) -> Promise  (UI -> C++)
+//  on(event, handler)               (C++ -> UI; also "__trace" for the inspector)
+
+function bridgeUrl() {
+  return (typeof globalThis !== "undefined" && globalThis.__HULL_BRIDGE__) || null;
+}
+
+// The HTTP/SSE transport is for browser DEV mode only. Vite replaces import.meta.env.DEV
+// with `false` in `hull build`, so the entire HTTP branch is dead-code-eliminated from
+// the shipped app.html — production apps carry only the native transport.
+const DEV = import.meta.env.DEV;
+
+class NativeBridge {
+  constructor() {
+    this._handlers = new Map(); // event -> Set<handler>
+    this._url = bridgeUrl();
+    this.mode = this._detectMode();
+
+    if (this.mode === "native") {
+      // The C++ side pushes events via eval(window.__bridgeEmit(event, jsonString)).
+      window.__bridgeEmit = (event, jsonString) => {
+        let payload;
+        try { payload = JSON.parse(jsonString); } catch { payload = jsonString; }
+        this._dispatch(event, payload);
+      };
+    } else if (DEV && this.mode === "http") {
+      // Inlined (not a method) so the whole block is dead-code-eliminated when
+      // DEV is false — production app.html carries no SSE/EventSource code.
+      try {
+        const es = new EventSource(`${this._url}/bridge/events`);
+        es.onmessage = (e) => {
+          let msg;
+          try { msg = JSON.parse(e.data); } catch { return; }
+          if (msg && typeof msg.event === "string") this._dispatch(msg.event, msg.payload);
+        };
+        es.onerror = () => { /* EventSource auto-reconnects */ };
+        this._es = es;
+      } catch (e) {
+        console.error("hull bridge: SSE connect failed", e);
+      }
+    }
+  }
+
+  _detectMode() {
+    if (typeof window !== "undefined" && typeof window.ping === "function") return "native";
+    if (DEV && this._url) return "http";
+    return "none";
+  }
+
+  invoke(name, ...args) {
+    if (this.mode === "native") {
+      const fn = window[name];
+      if (typeof fn !== "function") {
+        return Promise.reject(new Error(`Native binding "${name}" unavailable`));
+      }
+      return fn(...args);
+    }
+    if (DEV && this.mode === "http") {
+      return fetch(`${this._url}/bridge/invoke`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name, args }),
+      }).then((r) => r.json());
+    }
+    return Promise.reject(new Error(`Native binding "${name}" unavailable (no host)`));
+  }
+
+  on(event, handler) {
+    if (!this._handlers.has(event)) this._handlers.set(event, new Set());
+    this._handlers.get(event).add(handler);
+    return () => this.off(event, handler);
+  }
+
+  off(event, handler) {
+    this._handlers.get(event)?.delete(handler);
+  }
+
+  _dispatch(event, payload) {
+    this._handlers.get(event)?.forEach((h) => {
+      try { h(payload); } catch (e) { console.error(`bridge handler "${event}"`, e); }
+    });
+  }
+}
+
+export const bridge = new NativeBridge(); // singleton

package/src/bridge/index.js

@@ -0,0 +1,139 @@
+// Public bridge API for app code:  import { ping, httpPost, ... } from "@mwguerra/hull/bridge";
+//
+// Every call goes UI -> C++ and returns a Promise. All real work (TLS HTTP,
+// encrypted storage, keychain, printing) happens in the native host.
+
+import { bridge } from "./bridge-core.js";
+
+export { bridge } from "./bridge-core.js";
+export { nativeSetting } from "./native-store.js";
+
+const call = (name, ...args) => bridge.invoke(name, ...args);
+
+// "native" (host web view) | "http" (browser + dev server) | "none" (plain browser).
+export const bridgeMode = () => bridge.mode;
+// true when the bridge can reach the backend (native OR browser dev mode).
+export const hasBridge = () => bridge.mode !== "none";
+// true only inside the native host web view.
+export const isNative = () => bridge.mode === "native";
+
+// --- Bridge / diagnostics ---
+export const ping = (text) => call("ping", text);
+
+// { ok, appId, secure }  — `secure` is true when running a crypto-enabled host build.
+export const appInfo = () => call("appInfo");
+
+// --- HTTP (TLS, on a C++ worker thread; auth token injected from the keychain) ---
+export const httpPost = (url, body) => call("httpPost", url, body);
+export const httpGet = (url) => call("httpGet", url);
+
+// --- Settings (persisted + AES-256-GCM encrypted at rest) ---
+export const saveSetting = (key, value) => call("saveSetting", key, value);
+export const loadSetting = (key) => call("loadSetting", key);
+export const loadAllSettings = () => call("loadAllSettings");
+
+// --- Credentials (WRITE-ONLY from the UI; secrets never returned to JS) ---
+export const saveCredential = (service, account, secret) =>
+  call("saveCredential", service, account, secret);
+export const credentialExists = (service, account) =>
+  call("credentialExists", service, account);
+export const eraseCredential = (service, account) =>
+  call("eraseCredential", service, account);
+
+// --- Printing (Winspool / CUPS) ---
+// printMessage: text document — works with ANY printer (Print to PDF, OneNote, laser).
+// printReceipt / printNetwork: raw ESC/POS for thermal receipt printers (spooler / TCP).
+export const listPrinters = () => call("listPrinters");
+export const printMessage = (printer, text) => call("printMessage", printer, text);
+export const printReceipt = (printer, text) => call("printReceipt", printer, text);
+export const printNetwork = (host, port, text) => call("printNetwork", host, port, text);
+
+// --- SQLite (parameterized; stored in the per-user app dir) ---
+// Ergonomic wrapper: unwraps the bridge envelope and throws on error, so you can
+// use plain try/catch. Always pass values via the `params` array (never string-
+// concatenate) — they're bound in C++, which is what makes it injection-safe.
+async function dbCall(method, ...args) {
+  const res = await call(method, ...args);
+  if (!res?.ok) throw new Error(res?.error ?? `${method} failed`);
+  return res;
+}
+
+export const db = {
+  // INSERT/UPDATE/DELETE/DDL (one statement). -> { changes, lastInsertRowid }
+  async exec(sql, params = []) {
+    const r = await dbCall("dbExec", sql, params);
+    return { changes: r.changes, lastInsertRowid: r.lastInsertRowid };
+  },
+  // SELECT -> array of row objects
+  async query(sql, params = []) {
+    return (await dbCall("dbQuery", sql, params)).rows;
+  },
+  // SELECT first row -> row object or null
+  async get(sql, params = []) {
+    return (await dbCall("dbGet", sql, params)).row;
+  },
+  // Run several { sql, params } atomically (one transaction). -> results[]
+  async batch(statements) {
+    return (await dbCall("dbBatch", statements)).results;
+  },
+  // Apply ordered, run-once migrations. `steps` is an array of SQL strings (or
+  // { sql }); step index i is schema version i+1, tracked via PRAGMA user_version.
+  async migrate(steps) {
+    const row = await this.get("PRAGMA user_version");
+    const current = row?.user_version ?? 0;
+    if (current >= steps.length) return current;
+    const stmts = [];
+    for (let i = current; i < steps.length; i++) {
+      stmts.push({ sql: typeof steps[i] === "string" ? steps[i] : steps[i].sql });
+    }
+    stmts.push({ sql: `PRAGMA user_version = ${steps.length}` });
+    await this.batch(stmts);
+    return steps.length;
+  },
+};
+
+// --- Files (uploads/blobs; stored per-user; passed through the secure layer) ---
+function bytesToBase64(bytes) {
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+function base64ToBytes(b64) {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export const files = {
+  // content: string (UTF-8) | Uint8Array | ArrayBuffer | Blob
+  async write(name, content) {
+    let bytes;
+    if (typeof content === "string") bytes = new TextEncoder().encode(content);
+    else if (content instanceof Uint8Array) bytes = content;
+    else if (content instanceof ArrayBuffer) bytes = new Uint8Array(content);
+    else if (typeof Blob !== "undefined" && content instanceof Blob)
+      bytes = new Uint8Array(await content.arrayBuffer());
+    else throw new Error("files.write: content must be a string, Uint8Array, ArrayBuffer, or Blob");
+    const res = await call("fileWrite", name, bytesToBase64(bytes));
+    if (!res?.ok) throw new Error(res?.error ?? "fileWrite failed");
+  },
+  async read(name) {
+    const res = await call("fileRead", name);
+    if (!res?.ok) throw new Error(res?.error ?? "fileRead failed");
+    return base64ToBytes(res.data); // Uint8Array
+  },
+  async readText(name) {
+    return new TextDecoder().decode(await this.read(name));
+  },
+  async list() {
+    const res = await call("fileList");
+    if (!res?.ok) throw new Error(res?.error ?? "fileList failed");
+    return res.files; // [{ name, size }]
+  },
+  async remove(name) {
+    const res = await call("fileDelete", name);
+    if (!res?.ok) throw new Error(res?.error ?? "fileDelete failed");
+    return res.removed;
+  },
+};

package/src/bridge/native-store.js

@@ -0,0 +1,34 @@
+import { bridge } from "./bridge-core.js";
+
+// A framework-agnostic, two-way store for one setting key.
+//  - load():       pull the current value from C++
+//  - get():        cached value
+//  - set(v):       write through to C++ (persisted + encrypted) and update locally
+//  - subscribe(cb): observe changes from EITHER direction; returns an unsubscribe fn
+// C++ emits "settings:changed" {key, value} after any successful write, keeping every
+// subscriber in sync (including other components/windows).
+export function nativeSetting(key) {
+  let value;
+  const subs = new Set();
+  const notify = () => subs.forEach((cb) => cb(value));
+
+  bridge.on("settings:changed", (p) => {
+    if (p && p.key === key) { value = p.value; notify(); } // C++ -> store
+  });
+
+  return {
+    get: () => value,
+    async load() {
+      const res = await bridge.invoke("loadSetting", key);
+      if (res?.ok) { value = res.value; notify(); }
+      return value;
+    },
+    async set(v) {
+      value = v; notify();                                   // optimistic local update
+      const res = await bridge.invoke("saveSetting", key, v);
+      if (!res?.ok) throw new Error(res?.error ?? "saveSetting failed");
+      return value;                                          // C++ echo re-syncs others
+    },
+    subscribe(cb) { subs.add(cb); return () => subs.delete(cb); },
+  };
+}

package/src/cli/build.js

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./config.js";
+import { loadVite } from "./vite.js";
+import { resolveHostFor, currentTarget, KNOWN_TARGETS, binaryName } from "./host.js";
+import {
+  parseVersion, sanitize, copyHostFiles, writeLauncher, makeArchive, defaultFormat,
+  writeMacApp, makeAppArchive,
+} from "./release.js";
+import { createTimer } from "./timing.js";
+
+// Usage:
+//   hull build [vX.Y.Z] [--platform <key|all>] [--format zip|tar.gz]
+// No version  -> release/development/...   ;  vX.Y.Z -> release/vX.Y.Z/...
+function parseArgs(args) {
+  let version = null, platform = null, format = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--platform") platform = args[++i];
+    else if (a === "--format") format = args[++i];
+    else if (!a.startsWith("-")) version = a;
+  }
+  return { ...parseVersion(version), platform, format };
+}
+
+export async function build(cwd, args, { verbose } = {}) {
+  const timer = createTimer(verbose);
+  const { label, platform, format } = parseArgs(args);
+  const cfg = await loadConfig(cwd);
+  timer.step("config loaded");
+
+  // Which platforms to package?
+  let targetKeys;
+  if (!platform) targetKeys = [currentTarget()];
+  else if (platform === "all") targetKeys = KNOWN_TARGETS;
+  else targetKeys = [platform];
+
+  // Keep only targets whose prebuilt host binary (for the chosen flavor) is present.
+  const flavor = cfg.secure ? "secure " : "";
+  const hosts = [];
+  for (const key of targetKeys) {
+    const h = await resolveHostFor(key);
+    const binPath = h && (cfg.secure ? h.secureBinary : h.hostBinary);
+    if (h && binPath) hosts.push(h);
+    else console.warn(`hull build: skipping ${key} (no ${flavor}host binary built)`);
+  }
+  if (hosts.length === 0) {
+    throw new Error(
+      `no ${flavor}host binary available for: ${targetKeys.join(", ")}.\n` +
+      `  Build it (npm run build:host${cfg.secure ? ":secure" : ""}), or run on the matching OS / CI.`
+    );
+  }
+  timer.step(`resolved ${hosts.length} host(s)`);
+
+  // Build the single-file UI ONCE, shared by every platform bundle.
+  const vite = await loadVite(cwd);
+  const { viteSingleFile } = await import("vite-plugin-singlefile");
+  timer.step("vite loaded");
+  console.log("hull build: bundling UI into a single file…");
+  await vite.build({
+    root: cwd,
+    plugins: [viteSingleFile()],
+    build: { outDir: cfg.outDir, cssCodeSplit: false, target: "esnext", emptyOutDir: true },
+    logLevel: "warn",
+  });
+  timer.step("vite single-file build");
+  const builtHtml = path.join(cwd, cfg.outDir, "index.html");
+  if (!fs.existsSync(builtHtml)) {
+    throw new Error(`expected ${path.relative(cwd, builtHtml)} after build — is this a Vite app?`);
+  }
+
+  // Assemble + archive one bundle per target.
+  const versionRoot = path.join(cwd, cfg.releaseDir, label);
+  fs.mkdirSync(versionRoot, { recursive: true });
+  const results = [];
+
+  for (const h of hosts) {
+    const binName = binaryName(h.key, cfg.secure);
+    const bundleDir = path.join(versionRoot, h.key + (cfg.secure ? "-secure" : ""));
+    fs.rmSync(bundleDir, { recursive: true, force: true });
+    const rootName = `${sanitize(cfg.title)}-${label}-${h.key}${cfg.secure ? "-secure" : ""}`;
+
+    // macOS: produce a real .app bundle (Dock/Finder icon, double-click) + tar.gz.
+    if (h.key.startsWith("darwin")) {
+      fs.mkdirSync(bundleDir, { recursive: true });
+      const { appName } = writeMacApp(bundleDir, cfg, h.hostDir, binName, builtHtml, cfg.icon);
+      const archivePath = path.join(versionRoot, `${rootName}.tar.gz`);
+      const bytes = await makeAppArchive(bundleDir, archivePath, rootName);
+      results.push({ key: h.key, archivePath, bytes, app: appName });
+      timer.step(`packaged ${h.key} (.app)`);
+      continue;
+    }
+
+    copyHostFiles(h.hostDir, bundleDir, binName);
+    fs.copyFileSync(builtHtml, path.join(bundleDir, "app.html"));
+    // Bundle the window icon so the distributed app shows it (no node_modules at runtime).
+    let iconName = null;
+    if (cfg.icon && fs.existsSync(cfg.icon)) {
+      iconName = "icon" + path.extname(cfg.icon);
+      fs.copyFileSync(cfg.icon, path.join(bundleDir, iconName));
+    }
+    const launcher = writeLauncher(bundleDir, h.key, cfg, binName, iconName);
+
+    const fmt = format ?? defaultFormat(h.key);
+    const ext = fmt === "zip" ? "zip" : "tar.gz";
+    const archivePath = path.join(versionRoot, `${rootName}.${ext}`);
+    const bytes = await makeArchive(bundleDir, archivePath, fmt, rootName, h.key, launcher.name, binName);
+    results.push({ key: h.key, archivePath, bytes });
+    timer.step(`packaged ${h.key}`);
+  }
+
+  // Summary.
+  const rel = (p) => path.relative(cwd, p).replace(/\\/g, "/");
+  console.log(`\nhull build: ${label} -> ${rel(versionRoot)}/`);
+  for (const r of results) {
+    console.log(`  ${r.key.padEnd(14)} ${rel(r.archivePath)}  (${(r.bytes / 1024).toFixed(0)} KB)`);
+  }
+  if (results.some((r) => r.key === currentTarget())) {
+    console.log(`  run it locally with "hull start${label === "development" ? "" : " " + label}"`);
+  }
+  timer.total("\nhull build");
+}

package/src/cli/config.js

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// The bundled default app icon (the Hull logo), used when .hullrc sets no icon.
+const DEFAULT_ICON = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)), "../../assets/hull-logo.png");
+
+// Package-level defaults. A project's .hullrc overrides these per key (the `window`
+// object is merged deeply); with no config file, all defaults apply.
+const DEFAULTS = {
+  window: { width: 1100, height: 760 },
+  secure: false,
+  debug: false,
+  outDir: "dist",
+  releaseDir: "release",
+};
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+// Project config: .hullrc (JSON) in the project root, preferred over the older
+// hull.config.json. Returns {} when none is present (=> all package defaults).
+function readProjectConfig(cwd) {
+  for (const f of [".hullrc", ".hullrc.json", "hull.config.json"]) {
+    const p = path.join(cwd, f);
+    if (fs.existsSync(p)) return readJson(p) ?? {};
+  }
+  return {};
+}
+
+export async function loadConfig(cwd) {
+  const pkg = readJson(path.join(cwd, "package.json")) ?? {};
+  const bareName = (pkg.name ?? "hull-app").replace(/^@[^/]+\//, "");
+  const file = readProjectConfig(cwd);
+  const win = { ...DEFAULTS.window, ...(file.window ?? {}) };
+
+  // Icon: .hullrc window.icon (or top-level icon), resolved against the project; else
+  // the bundled Hull logo. Falls back to the default if the configured file is missing.
+  const iconCfg = win.icon ?? file.icon;
+  let icon = DEFAULT_ICON;
+  if (iconCfg) {
+    const p = path.resolve(cwd, iconCfg);
+    icon = fs.existsSync(p) ? p : DEFAULT_ICON;
+  }
+
+  // Linux WebKitGTK sandbox: true = force on, false = force off, undefined = auto
+  // (the host probes for unprivileged user namespaces and disables it only if needed).
+  const linuxSandbox = file.linux?.sandbox;
+
+  // Installer/store metadata. license: SPDX id; publisher: human/developer name.
+  const license = file.license ?? pkg.license ?? null;
+  const rawAuthor = file.author ?? pkg.author ?? null;
+  const publisher = !rawAuthor ? null
+    : typeof rawAuthor === "string" ? rawAuthor.replace(/\s*[<(].*$/, "").trim()
+    : (rawAuthor.name ?? null);
+  const description = file.description ?? pkg.description ?? null;
+
+  return {
+    appId: file.appId ?? `com.hull.${bareName}`,
+    title: win.title ?? file.title ?? pkg.productName ?? bareName,
+    width: Number(win.width),
+    height: Number(win.height),
+    icon,
+    secure: Boolean(file.secure ?? DEFAULTS.secure),
+    debug: Boolean(file.debug ?? DEFAULTS.debug),
+    linuxSandbox: typeof linuxSandbox === "boolean" ? linuxSandbox : undefined,
+    license,
+    publisher,
+    description,
+    outDir: file.outDir ?? DEFAULTS.outDir,
+    releaseDir: file.releaseDir ?? DEFAULTS.releaseDir,
+  };
+}
+
+// Environment additions for the spawned host that control the Linux WebKitGTK sandbox.
+//   force off (cfg.linuxSandbox === false, or --no-sandbox) -> disable it up front
+//   force on  (cfg.linuxSandbox === true)                   -> tell the host to keep it
+//   otherwise                                               -> nothing (host auto-detects)
+export function hostEnv(cfg, { noSandbox = false } = {}) {
+  const env = {};
+  if (noSandbox || cfg.linuxSandbox === false) {
+    env.WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS = "1";
+  } else if (cfg.linuxSandbox === true) {
+    env.HULL_FORCE_SANDBOX = "1";
+  }
+  return env;
+}
+
+// Common host flags derived from config.
+export function hostArgs(cfg) {
+  const args = [
+    "--title", cfg.title,
+    "--app-id", cfg.appId,
+    "--width", String(cfg.width),
+    "--height", String(cfg.height),
+  ];
+  if (cfg.icon) args.push("--icon", cfg.icon);
+  if (cfg.debug) args.push("--debug");
+  return args;
+}