pigo-excel-python-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Mustier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# pigo-excel-python-bridge
+
+Local HTTPS Python / LibreOffice bridge helper for Pi for Excel.
+
+## Usage
+
+```bash
+npx pigo-excel-python-bridge
+```
+
+This command:
+
+1. Ensures `mkcert` exists (installs via Homebrew on macOS if missing)
+2. Creates certificates in `~/.pi-for-excel/certs/` when needed
+3. Starts the bridge at `https://localhost:3340`
+4. Runs in real local execution mode by default
+
+Real mode requires `python3` on `PATH`. LibreOffice (`soffice` / `libreoffice`) is optional for Python execution but required for `libreoffice_convert`.
+
+Optional assisted install (macOS/Homebrew):
+
+```bash
+npx pigo-excel-python-bridge --install-missing
+```
+
+This installs missing `python3` and/or LibreOffice before starting the bridge.
+
+To force safe simulated mode:
+
+```bash
+PYTHON_BRIDGE_MODE=stub npx pigo-excel-python-bridge
+```
+
+Then in Pi for Excel:
+
+1. The default Python bridge URL is already `https://localhost:3340`
+2. (Optional) set `/experimental python-bridge-url <url>` to use a non-default URL
+3. (Optional) run `/experimental python-bridge-token <token>` if you set `PYTHON_BRIDGE_TOKEN`
+
+## Publishing (maintainers)
+
+Package source lives in `pkg/python-bridge/`.
+
+Before packing/publishing, `prepack` copies runtime files from repo root:
+
+- `scripts/python-bridge-server.mjs`
+
+Publish from this directory:
+
+```bash
+cd pkg/python-bridge
+npm publish
+```

package/cli.mjs

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_TAG = "pigo-excel-python-bridge";
+const DEFAULT_PORT = "3340";
+const INSTALL_MISSING_FLAG = "--install-missing";
+
+const cliDir = path.dirname(fileURLToPath(import.meta.url));
+const bridgeScriptPath = path.join(cliDir, "scripts", "python-bridge-server.mjs");
+
+const homeDir = os.homedir();
+const appDir = path.join(homeDir, ".pi-for-excel");
+const certDir = path.join(appDir, "certs");
+const keyPath = path.join(certDir, "key.pem");
+const certPath = path.join(certDir, "cert.pem");
+
+function commandExists(command) {
+  const whichCommand = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(whichCommand, [command], { stdio: "ignore" });
+  return result.status === 0;
+}
+
+function canRunBinary(command, args = ["--version"]) {
+  const result = spawnSync(command, args, {
+    stdio: "ignore",
+  });
+
+  if (result.error || result.signal) {
+    return false;
+  }
+
+  return result.status === 0;
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    stdio: "inherit",
+    ...options,
+  });
+
+  if (result.error) {
+    console.error(`[${PACKAGE_TAG}] Failed to run: ${command}`);
+    console.error(result.error.message);
+    process.exit(1);
+  }
+
+  if (typeof result.status === "number" && result.status !== 0) {
+    process.exit(result.status);
+  }
+
+  if (result.signal) {
+    console.error(`[${PACKAGE_TAG}] ${command} terminated by signal ${result.signal}`);
+    process.exit(1);
+  }
+}
+
+function supportsMkcertCli(command) {
+  const result = spawnSync(command, ["-CAROOT"], {
+    stdio: "ignore",
+  });
+
+  if (result.error) {
+    return false;
+  }
+
+  return result.status === 0 && !result.signal;
+}
+
+function resolveMkcertCommand() {
+  const candidates = [];
+
+  if (process.platform === "darwin") {
+    const brewCandidates = ["/opt/homebrew/bin/mkcert", "/usr/local/bin/mkcert"];
+    for (const candidate of brewCandidates) {
+      if (fs.existsSync(candidate)) {
+        candidates.push(candidate);
+      }
+    }
+  }
+
+  if (commandExists("mkcert")) {
+    candidates.push("mkcert");
+  }
+
+  for (const candidate of candidates) {
+    if (supportsMkcertCli(candidate)) {
+      return candidate;
+    }
+  }
+
+  if (process.platform === "darwin") {
+    if (!commandExists("brew")) {
+      console.error(`[${PACKAGE_TAG}] Homebrew is not installed.`);
+      console.error(`[${PACKAGE_TAG}] Install Homebrew first: https://brew.sh`);
+      process.exit(1);
+    }
+
+    console.log(`[${PACKAGE_TAG}] Installing mkcert via Homebrew...`);
+    run("brew", ["install", "mkcert"]);
+
+    const brewCandidates = ["/opt/homebrew/bin/mkcert", "/usr/local/bin/mkcert", "mkcert"];
+    for (const candidate of brewCandidates) {
+      if (candidate !== "mkcert" && !fs.existsSync(candidate)) {
+        continue;
+      }
+
+      if (supportsMkcertCli(candidate)) {
+        return candidate;
+      }
+    }
+
+    console.error(`[${PACKAGE_TAG}] mkcert is installed but not compatible with required CLI flags.`);
+    console.error(`[${PACKAGE_TAG}] Ensure FiloSottile mkcert is used (not the npm mkcert package).`);
+    process.exit(1);
+  }
+
+  console.error(`[${PACKAGE_TAG}] Please install mkcert, then run this command again.`);
+  console.error(`[${PACKAGE_TAG}] Install instructions: https://github.com/FiloSottile/mkcert#installation`);
+  process.exit(1);
+}
+
+function installMkcertCa(mkcertCommand) {
+  const result = spawnSync(mkcertCommand, ["-install"], {
+    stdio: "inherit",
+  });
+
+  if (!result.error && result.status === 0 && !result.signal) {
+    return;
+  }
+
+  console.error(`[${PACKAGE_TAG}] Failed to install mkcert local CA.`);
+  console.error(`[${PACKAGE_TAG}] Run manually: mkcert -install`);
+  console.error(`[${PACKAGE_TAG}] If it fails, fix trust-store permissions and retry.`);
+
+  if (typeof result.status === "number" && result.status !== 0) {
+    process.exit(result.status);
+  }
+
+  process.exit(1);
+}
+
+function ensureCertificates() {
+  fs.mkdirSync(certDir, { recursive: true });
+
+  if (fs.existsSync(keyPath) && fs.existsSync(certPath)) {
+    return;
+  }
+
+  const mkcertCommand = resolveMkcertCommand();
+
+  console.log(`[${PACKAGE_TAG}] Generating local HTTPS certificates...`);
+  installMkcertCa(mkcertCommand);
+
+  run(mkcertCommand, ["-key-file", keyPath, "-cert-file", certPath, "localhost"], {
+    cwd: certDir,
+  });
+
+  if (!fs.existsSync(keyPath) || !fs.existsSync(certPath)) {
+    console.error(`[${PACKAGE_TAG}] Failed to generate TLS certificates.`);
+    process.exit(1);
+  }
+}
+
+function resolveConfiguredLibreOfficeBinary(env = process.env) {
+  const raw = typeof env.PYTHON_BRIDGE_LIBREOFFICE_BIN === "string"
+    ? env.PYTHON_BRIDGE_LIBREOFFICE_BIN
+    : "";
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function resolveBundledLibreOfficeBinary() {
+  const candidates = [
+    "/Applications/LibreOffice.app/Contents/MacOS/soffice",
+    path.join(homeDir, "Applications", "LibreOffice.app", "Contents", "MacOS", "soffice"),
+  ];
+
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+
+    if (canRunBinary(candidate, ["--version"])) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function resolveAvailableLibreOfficeBinary(env = process.env) {
+  const configured = resolveConfiguredLibreOfficeBinary(env);
+  if (configured && canRunBinary(configured, ["--version"])) {
+    return configured;
+  }
+
+  if (canRunBinary("soffice", ["--version"])) {
+    return "soffice";
+  }
+
+  if (canRunBinary("libreoffice", ["--version"])) {
+    return "libreoffice";
+  }
+
+  return resolveBundledLibreOfficeBinary();
+}
+
+function applyLibreOfficeBinaryOverride(env) {
+  if (resolveConfiguredLibreOfficeBinary(env)) {
+    return;
+  }
+
+  const availableBinary = resolveAvailableLibreOfficeBinary(env);
+  if (!availableBinary) {
+    return;
+  }
+
+  if (availableBinary === "soffice" || availableBinary === "libreoffice") {
+    return;
+  }
+
+  env.PYTHON_BRIDGE_LIBREOFFICE_BIN = availableBinary;
+  console.log(`[${PACKAGE_TAG}] Using LibreOffice binary: ${availableBinary}`);
+}
+
+function installMissingDependencies() {
+  const pythonMissing = !canRunBinary("python3", ["--version"]);
+  const libreOfficeMissing = !resolveAvailableLibreOfficeBinary();
+
+  if (!pythonMissing && !libreOfficeMissing) {
+    return;
+  }
+
+  if (process.platform !== "darwin") {
+    console.warn(`[${PACKAGE_TAG}] ${INSTALL_MISSING_FLAG} currently supports macOS/Homebrew only.`);
+    if (pythonMissing) {
+      console.warn(`[${PACKAGE_TAG}] Please install python3 manually and retry.`);
+    }
+    if (libreOfficeMissing) {
+      console.warn(`[${PACKAGE_TAG}] Please install LibreOffice manually and retry.`);
+    }
+    return;
+  }
+
+  if (!commandExists("brew")) {
+    console.error(`[${PACKAGE_TAG}] Homebrew is required for ${INSTALL_MISSING_FLAG}.`);
+    console.error(`[${PACKAGE_TAG}] Install Homebrew first: https://brew.sh`);
+    process.exit(1);
+  }
+
+  if (pythonMissing) {
+    console.log(`[${PACKAGE_TAG}] Installing missing dependency: python3`);
+    run("brew", ["install", "python"]);
+  }
+
+  if (libreOfficeMissing) {
+    console.log(`[${PACKAGE_TAG}] Installing missing dependency: LibreOffice`);
+    run("brew", ["install", "--cask", "libreoffice"]);
+  }
+
+  if (!canRunBinary("python3", ["--version"])) {
+    console.warn(`[${PACKAGE_TAG}] python3 is still unavailable after install attempt.`);
+  }
+
+  if (!resolveAvailableLibreOfficeBinary()) {
+    console.warn(`[${PACKAGE_TAG}] LibreOffice is still unavailable after install attempt.`);
+    console.warn(`[${PACKAGE_TAG}] You can set PYTHON_BRIDGE_LIBREOFFICE_BIN to an absolute soffice path.`);
+  }
+}
+
+function resolveBridgeConfig() {
+  const userArgs = process.argv.slice(2);
+  const installMissing = userArgs.includes(INSTALL_MISSING_FLAG);
+  const bridgeUserArgs = userArgs.filter((arg) => arg !== INSTALL_MISSING_FLAG);
+
+  const hasExplicitScheme = bridgeUserArgs.includes("--https") || bridgeUserArgs.includes("--http");
+  const bridgeArgs = hasExplicitScheme ? bridgeUserArgs : ["--https", ...bridgeUserArgs];
+
+  const usesHttpOnly = bridgeArgs.includes("--http") && !bridgeArgs.includes("--https");
+
+  return {
+    bridgeArgs,
+    usesHttps: !usesHttpOnly,
+    installMissing,
+  };
+}
+
+function applyDefaultPort(env) {
+  const configuredPort = typeof env.PORT === "string" ? env.PORT.trim() : "";
+  if (configuredPort.length === 0) {
+    env.PORT = DEFAULT_PORT;
+  }
+}
+
+function applyDefaultMode(env) {
+  const configuredMode = typeof env.PYTHON_BRIDGE_MODE === "string"
+    ? env.PYTHON_BRIDGE_MODE.trim()
+    : "";
+
+  if (configuredMode.length === 0) {
+    env.PYTHON_BRIDGE_MODE = "real";
+  }
+}
+
+function startBridge(bridgeArgs) {
+  fs.mkdirSync(certDir, { recursive: true });
+  console.log(`[${PACKAGE_TAG}] Using certificate directory: ${certDir}`);
+
+  const childEnv = { ...process.env };
+  applyDefaultPort(childEnv);
+  applyDefaultMode(childEnv);
+  applyLibreOfficeBinaryOverride(childEnv);
+
+  if (typeof childEnv.PI_FOR_EXCEL_CERT_DIR !== "string" || childEnv.PI_FOR_EXCEL_CERT_DIR.trim().length === 0) {
+    childEnv.PI_FOR_EXCEL_CERT_DIR = certDir;
+  }
+
+  const child = spawn(process.execPath, [bridgeScriptPath, ...bridgeArgs], {
+    env: childEnv,
+    stdio: "inherit",
+  });
+
+  let shuttingDown = false;
+
+  const forwardSignal = (signal) => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  };
+
+  process.on("SIGINT", () => forwardSignal("SIGINT"));
+  process.on("SIGTERM", () => forwardSignal("SIGTERM"));
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+
+  child.on("error", (error) => {
+    console.error(`[${PACKAGE_TAG}] Failed to start bridge process.`);
+    console.error(error.message);
+    process.exit(1);
+  });
+}
+
+if (!fs.existsSync(bridgeScriptPath)) {
+  console.error(`[${PACKAGE_TAG}] Missing bridge runtime files.`);
+  console.error(`[${PACKAGE_TAG}] Reinstall the package or run npm pack again.`);
+  process.exit(1);
+}
+
+const bridgeConfig = resolveBridgeConfig();
+if (bridgeConfig.installMissing) {
+  installMissingDependencies();
+}
+if (bridgeConfig.usesHttps) {
+  ensureCertificates();
+}
+startBridge(bridgeConfig.bridgeArgs);

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "pigo-excel-python-bridge",
+  "version": "0.1.0",
+  "description": "One-command local HTTPS Python / LibreOffice bridge helper for PiGo (Excel add-in).",
+  "type": "module",
+  "bin": {
+    "pigo-excel-python-bridge": "cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "scripts/*.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepack": "node ../../scripts/sync-python-bridge-package.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}