pg-here 0.1.5 → 0.1.8

package/README.md

@@ -33,18 +33,18 @@ bunx pg-here
 
 This is the single command you want from any directory.
 
-If it still resolves an older release, the package `latest` dist-tag is behind:
+If it still resolves an older release, the package `latest` dist-tag may be behind:
 
 To force that version and bypass a stale cache:
 
 ```bash
-bunx pg-here@0.1.5
+bunx pg-here@0.1.8
 ```
 
 If maintainers want plain `bunx pg-here` to work for everyone, run once:
 
 ```bash
-npm dist-tag add pg-here@0.1.5 latest
+npm dist-tag add pg-here@0.1.8 latest
 ```
 
 After that, this should work anywhere:
@@ -90,6 +90,37 @@ sudo apk add libxml2
 
 If that machine is intentionally minimal (or containerized), use an image with PostgreSQL runtime dependencies.
 
+If apt says `Package 'libxml2' has no installation candidate`, your apt sources are likely missing standard repos.
+
+```bash
+cat /etc/os-release
+apt-cache search '^libxml2$'
+```
+
+and if that returns nothing, fix apt sources for your distro/arch first, or use a base image that includes PostgreSQL runtime packages.
+
+Important ABI note:
+
+- If your host exposes `libxml2.so.16` but not `libxml2.so.2`, older releases may fail to start before applying fallback.
+- If a failure mentions `/pg_local/bin/bin/postgres`, clear and redownload:
+
+```bash
+rm -rf pg_local
+bunx pg-here@0.1.8
+```
+
+For this release, `0.1.8` also attempts a one-time compatibility workaround when it detects
+`libxml2.so.16`-only hosts:
+- it creates a local runtime symlink in `./pg_local/runtime-libs/libxml2.so.2` pointing to the discovered `libxml2.so.16`
+- sets `LD_LIBRARY_PATH` for the retry so `postgres`/`initdb` can launch
+
+If your system is locked down and this still fails, create a global compatibility symlink (where permitted):
+
+```bash
+sudo ln -sfn /usr/lib/x86_64-linux-gnu/libxml2.so.16 /usr/local/lib/libxml2.so.2
+sudo ldconfig
+```
+
 ### Programmatic usage
 
 Use `pg-here` directly from your server startup code and auto-create the app database if missing.

package/bin/pg-here.mjs

@@ -3,7 +3,10 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { startPgHere } from "../dist/index.js";
-import { maybePrintLinuxRuntimeHelp } from "../scripts/cli-error-help.mjs";
+import {
+  maybePrintLinuxRuntimeHelp,
+  startPgHereWithLibxml2Compat,
+} from "../scripts/cli-error-help.mjs";
 
 const argv = await yargs(hideBin(process.argv))
   .version(false)
@@ -33,8 +36,8 @@ const argv = await yargs(hideBin(process.argv))
   .parse();
 
 let pg;
-try {
-  pg = await startPgHere({
+const startInstance = () =>
+  startPgHere({
     projectDir: process.cwd(),
     port: argv.port,
     username: argv.username,
@@ -42,6 +45,9 @@ try {
     database: argv.database,
     postgresVersion: argv["pg-version"],
   });
+
+try {
+  pg = await startPgHereWithLibxml2Compat(startInstance, process.cwd());
 } catch (error) {
   if (process.platform === "linux") {
     maybePrintLinuxRuntimeHelp(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pg-here",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "Per-project embedded PostgreSQL with programmatic startup and auto DB creation.",
   "type": "module",
   "main": "./dist/index.js",

package/scripts/cli-error-help.mjs

@@ -1,11 +1,26 @@
 import { spawnSync } from "node:child_process";
+import { accessSync, existsSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync, F_OK } from "node:fs";
+import { join } from "node:path";
 
-const LIBXML_LIBRARY = /libxml2\.so\.2/;
+const LIBXML2_SONAME = "libxml2.so.2";
+const LIBXML2_ALTERNATE_SONAME = "libxml2.so.16";
+const LIBXML2_COMPAT_DIR = "pg_local/runtime-libs";
+
+const LIB_PATHS = [
+  "/usr/lib/x86_64-linux-gnu",
+  "/usr/lib/i386-linux-gnu",
+  "/usr/lib",
+  "/lib/x86_64-linux-gnu",
+  "/lib/i386-linux-gnu",
+  "/lib",
+  "/usr/local/lib",
+];
 
 export function maybePrintLinuxRuntimeHelp(error) {
   const message = String(error?.message ?? error);
   const missingLibsFromError = extractMissingLibrariesFromMessage(message);
   const missingLibsFromBinary = extractMissingLibrariesFromBinaryPath(message);
+  const binPath = extractBinaryPathFromError(message);
 
   const missingLibs = [...new Set([...missingLibsFromError, ...missingLibsFromBinary])];
 
@@ -18,20 +33,144 @@ export function maybePrintLinuxRuntimeHelp(error) {
   console.error(`Missing libraries: ${missingLibs.join(", ")}`);
   console.error();
   console.error("Install system packages for your distro and retry:");
-  console.error("  Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y libxml2");
-  console.error("  Fedora/RHEL:   sudo dnf install -y libxml2");
-  console.error("  Alpine:        sudo apk add libxml2");
   console.error(
-    `If your distro requires different package names, install packages that provide: ${missingLibs.join(
-      ", "
-    )}`
+    "  Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y libxml2 libxml2-dev libxml2-utils"
+  );
+  console.error(
+    "  Fedora/RHEL:   sudo dnf install -y libxml2"
+  );
+  console.error(
+    "  Alpine:        sudo apk add libxml2"
+  );
+  console.error();
+  console.error("  Quick checks:");
+  console.error(
+    "    find /usr/lib /usr/local/lib /lib -name 'libxml2.so.2*' 2>/dev/null | head"
   );
+  if (binPath) {
+    console.error(`    ldd ${binPath} | grep libxml2`);
+  }
+  console.error("    sudo ldconfig && sudo ldconfig -p | grep libxml2.so.2");
+  if (binPath.includes("/bin/bin/postgres")) {
+    console.error("  Your local pg_local cache looks partially provisioned (bin/bin/postgres path).");
+    console.error("  Try removing it and retrying:");
+    console.error("    rm -rf pg_local && bunx pg-here@0.1.8");
+  }
+  console.error(
+    `If your distro requires different package names, install packages that provide: ${missingLibs.join(", ")}`
+  );
+  printPotentialSymlinkHint();
 
-  if (LIBXML_LIBRARY.test(message)) {
-    console.error("Hint: this project does not ship all optional shared objects in every Linux image.");
+  if (hasLibxml2CompatibilityNeed(error)) {
+    const fallback = findLibraryPath(LIBXML2_ALTERNATE_SONAME);
+    console.error();
+    console.error("Compatibility note:");
+    if (fallback) {
+      console.error(
+        `This host only provides ${LIBXML2_ALTERNATE_SONAME} at ${fallback}, not ${LIBXML2_SONAME}.`
+      );
+      console.error(
+        "This release now retries startup with a project-local symlink fallback automatically."
+      );
+      console.error(
+        `If that does not work, you can retry with a global symlink (requires sudo):\n    sudo ln -sfn ${fallback} /usr/local/lib/${LIBXML2_SONAME} && sudo ldconfig`
+      );
+    } else {
+      console.error(
+        `Expected ${LIBXML2_SONAME} was not found and no ${LIBXML2_ALTERNATE_SONAME} fallback was discovered.`
+      );
+      console.error(
+        `Your host may be too minimal or custom; install a PostgreSQL-ready runtime stack for your distro.`
+      );
+    }
   }
 }
 
+export function hasLibxml2CompatibilityNeed(error) {
+  const message = String(error?.message ?? error);
+  const missingFromMessage = extractMissingLibrariesFromMessage(message);
+  const missingFromBinary = extractMissingLibrariesFromBinaryPath(message);
+  const missing = [...missingFromMessage, ...missingFromBinary];
+  return missing.includes(LIBXML2_SONAME) || message.includes("libxml2.so.2");
+}
+
+export async function startPgHereWithLibxml2Compat(start, workingDir) {
+  try {
+    return await start();
+  } catch (error) {
+    if (!hasLibxml2CompatibilityNeed(error)) {
+      throw error;
+    }
+
+    const patched = ensureLibxml2Compatibility(workingDir);
+    if (!patched) {
+      throw error;
+    }
+
+    return await start();
+  }
+}
+
+export function ensureLibxml2Compatibility(workingDir) {
+  if (process.platform !== "linux") {
+    return false;
+  }
+
+  const projectDir = typeof workingDir === "string" && workingDir ? workingDir : process.cwd();
+  const compatDir = join(projectDir, LIBXML2_COMPAT_DIR);
+  const compatLib = join(compatDir, LIBXML2_SONAME);
+
+  if (findLibraryPath(LIBXML2_SONAME)) {
+    return false;
+  }
+
+  const fallback = findLibraryPath(LIBXML2_ALTERNATE_SONAME);
+  if (!fallback) {
+    return false;
+  }
+
+  try {
+    mkdirSync(compatDir, { recursive: true });
+    if (existsSync(compatLib)) {
+      const existing = readCompatLink(compatLib);
+      if (existing === fallback) {
+        ensureLdLibraryPath(compatDir);
+        return true;
+      }
+
+      rmSync(compatLib, { force: true });
+    }
+
+    symlinkSync(fallback, compatLib);
+    ensureLdLibraryPath(compatDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readCompatLink(path) {
+  try {
+    const info = lstatSync(path);
+    if (!info.isSymbolicLink()) {
+      return "";
+    }
+    return readlinkSync(path);
+  } catch {
+    return "";
+  }
+}
+
+function ensureLdLibraryPath(path) {
+  const currentPath = process.env.LD_LIBRARY_PATH ?? "";
+  const paths = currentPath.split(":").filter(Boolean);
+  if (paths.includes(path)) {
+    return;
+  }
+
+  process.env.LD_LIBRARY_PATH = path + (currentPath ? `:${currentPath}` : "");
+}
+
 function extractMissingLibrariesFromMessage(message) {
   const regex = /([A-Za-z0-9._-]+\.so(?:\.\d+)*)\b/g;
   const matches = [...message.matchAll(regex)].map((match) => match[1]);
@@ -55,3 +194,68 @@ function extractMissingLibrariesFromBinaryPath(message) {
     (match) => match[1]
   );
 }
+
+function extractBinaryPathFromError(message) {
+  const pathMatch = message.match(/(\/[^\s"]*\/bin\/postgres)/);
+  return pathMatch ? pathMatch[1] : "";
+}
+
+function hasLibxmlVersion16Only() {
+  const candidates = ["/usr/lib/x86_64-linux-gnu", "/usr/lib", "/lib/x86_64-linux-gnu", "/lib"];
+  for (const dir of candidates) {
+    try {
+      accessSync(`${dir}/libxml2.so.2`, F_OK);
+      return false;
+    } catch {
+      // continue
+    }
+
+    try {
+      accessSync(`${dir}/libxml2.so.16`, F_OK);
+      if (hasLibxmlVersion16AtPath(`${dir}/libxml2.so.16`)) {
+        return true;
+      }
+    } catch {}
+  }
+
+  return false;
+}
+
+function hasLibxmlVersion16AtPath(path) {
+  return typeof path === "string" && path.endsWith("/libxml2.so.16");
+}
+
+function printPotentialSymlinkHint() {
+  const result = spawnSync("sh", [
+    "-c",
+    "find /usr/lib /usr/local/lib /lib -name 'libxml2.so.2*' 2>/dev/null",
+  ], { encoding: "utf8" });
+
+  if (result.status !== 0) {
+    return;
+  }
+
+  const matches = (result.stdout ?? "").split("\n").filter(Boolean);
+  const exact = matches.find((item) => item.endsWith("/libxml2.so.2"));
+  if (!exact) {
+    console.error();
+    console.error("Hint:");
+    if (hasLibxmlVersion16Only()) {
+      console.error("This host appears to provide only libxml2.so.16. Compatibility is not guaranteed.");
+    } else {
+      console.error("No libxml2.so.2 file was found in the standard library paths.");
+    }
+  }
+}
+
+function findLibraryPath(name) {
+  const args = [...LIB_PATHS, "-name", `${name}*`, "-print"];
+  const result = spawnSync("find", args, { encoding: "utf8" });
+  const matches = (result.stdout ?? "").split("\n").filter(Boolean);
+  if (matches.length === 0) {
+    return "";
+  }
+
+  const exact = matches.find((item) => item.endsWith(`/${name}`));
+  return exact ?? matches[0];
+}

package/scripts/pg-dev.mjs

@@ -1,7 +1,10 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { startPgHere } from "../index.ts";
-import { maybePrintLinuxRuntimeHelp } from "./cli-error-help.mjs";
+import {
+  maybePrintLinuxRuntimeHelp,
+  startPgHereWithLibxml2Compat,
+} from "./cli-error-help.mjs";
 
 const argv = await yargs(hideBin(process.argv))
   .version(false)
@@ -31,8 +34,8 @@ const argv = await yargs(hideBin(process.argv))
   .parse();
 
 let pg;
-try {
-  pg = await startPgHere({
+const startInstance = () =>
+  startPgHere({
     projectDir: process.cwd(),
     port: argv.port,
     username: argv.username,
@@ -40,6 +43,9 @@ try {
     database: argv.database,
     postgresVersion: argv["pg-version"],
   });
+
+try {
+  pg = await startPgHereWithLibxml2Compat(startInstance, process.cwd());
 } catch (error) {
   if (process.platform === "linux") {
     maybePrintLinuxRuntimeHelp(error);