@phystack/cli 5.2.1 → 6.1.0

package/bin/index.js

@@ -3,9 +3,50 @@ const { spawnSync } = require('child_process');
 const path = require('path');
 
 const BINARY = 'phy';
-const key = `${process.platform}-${process.arch}`;
+
+// On Linux, distinguish glibc vs musl so we resolve the right per-platform
+// package. `process.report.getReport().header.glibcVersionRuntime` is set on
+// glibc systems and undefined on musl (Alpine). All other platforms ignore
+// the libc suffix.
+//
+// No optional chaining on `process.report` itself: we WANT a missing
+// `process.report` to throw and land in the catch (returning null = "unknown"
+// = same behavior as the pre-musl shim, which is safer on glibc Linux than
+// guessing musl).
+function detectLibc() {
+  if (process.platform !== 'linux') return null;
+  try {
+    const runtime = process.report.getReport().header.glibcVersionRuntime;
+    return runtime ? 'glibc' : 'musl';
+  } catch (err) {
+    console.error(
+      `phy: libc detection via process.report failed (${err?.message || err}); ` +
+        `falling back to the platform-default package.`,
+    );
+    return null;
+  }
+}
+
+// `JSON.stringify` can throw on circular refs or BigInts.
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch (err) {
+    return `[unserializable: ${err?.message || err}]`;
+  }
+}
+
+const libc = detectLibc();
+const isMusl = libc === 'musl';
+const libcSuffix = isMusl ? '-musl' : '';
+const key = `${process.platform}-${process.arch}${libcSuffix}`;
 const pkg = `@phystack/${BINARY}-${key}`;
 const ext = process.platform === 'win32' ? '.exe' : '';
+const runtimeTag = `${process.platform}-${process.arch}${libc ? ` (libc=${libc})` : ''}`;
+
+// Reused across diagnostic branches so the message format stays consistent.
+const runtimeLine = `Runtime: ${runtimeTag}\n`;
+const muslHint = `You're on musl (Alpine). Ensure ${pkg} is installed (the musl variant).`;
 
 let binPath;
 try {
@@ -17,12 +58,115 @@ try {
 } catch {
   console.error(
     `Unsupported or missing platform package: ${pkg}\n` +
-      `Platform: ${key}\n\n` +
-      `Install manually:  npm install ${pkg}\n` +
-      `Or download:       bunx ${pkg}`,
+      `${runtimeLine}\n` +
+      `Fix: npm install ${pkg}\n` +
+      `Or:  bunx ${pkg}`,
   );
   process.exit(1);
 }
 
 const result = spawnSync(binPath, process.argv.slice(2), { stdio: 'inherit' });
+
+// `spawnSync` collapses many failure modes into status === null (with `error`
+// or `signal` set instead) — see explainSpawnFailureIfAny for the full taxonomy.
+// Must run BEFORE process.exit, which never returns.
+explainSpawnFailureIfAny(result);
 process.exit(result.status ?? 1);
+
+function explainSpawnFailureIfAny(result) {
+  const willDiagnose =
+    result.error || result.signal || result.status === 127 || result.status === 126;
+  if (!willDiagnose) return;
+
+  // Raw dump first — gives a future debugger the full spawnSync result even
+  // if our specific branches misclassify the failure mode.
+  console.error(
+    `\nphy: spawnSync result: ${safeStringify({
+      error: result.error
+        ? { code: result.error.code, message: result.error.message }
+        : null,
+      signal: result.signal,
+      status: result.status,
+    })}`,
+  );
+
+  // 1. Spawn itself failed — kernel never started the binary, or rejected the format.
+  if (result.error) {
+    const code = result.error.code;
+    if (code === 'ENOENT') {
+      console.error(
+        `\nphy: binary not found at ${binPath}\n` +
+          runtimeLine +
+          `Cause: the platform package ${pkg} wasn't installed. Most common reasons:\n` +
+          `  - npm/yarn ran with --omit=optional or --no-optional\n` +
+          `  - your platform (${key}) isn't published\n` +
+          `Fix: npm install ${pkg}`,
+      );
+      return;
+    }
+    if (code === 'EACCES') {
+      console.error(
+        `\nphy: binary at ${binPath} is not executable\n` +
+          runtimeLine +
+          `Fix: chmod +x ${binPath} (or reinstall: npm install --force ${pkg})`,
+      );
+      return;
+    }
+    if (code === 'ENOEXEC') {
+      console.error(
+        `\nphy: binary at ${binPath} is not a valid executable for this platform\n` +
+          runtimeLine +
+          `Cause: architecture or libc mismatch.\n` +
+          `Fix: file ${binPath} (inspect the actual format)`,
+      );
+      return;
+    }
+    console.error(`\nphy: spawn failed — ${result.error.message} (${code})`);
+    return;
+  }
+
+  // 2. Killed by signal — exec succeeded but the process died before normal exit.
+  if (result.signal) {
+    const sig = result.signal;
+    if (sig === 'SIGSEGV' || sig === 'SIGABRT') {
+      console.error(
+        `\nphy: binary crashed (${sig})\n` +
+          runtimeLine +
+          `Cause: glibc/musl mismatch or glibc too old.\n` +
+          (isMusl ? `Fix: ${muslHint}` : `Fix: ldd --version (check glibc version)`),
+      );
+      return;
+    }
+    if (sig === 'SIGILL') {
+      console.error(
+        `\nphy: SIGILL — your CPU is missing a required instruction set. ` +
+          `(We ship the linux-x64-baseline build; this should be rare.)`,
+      );
+      return;
+    }
+    if (sig === 'SIGKILL') {
+      console.error(
+        `\nphy: SIGKILL — likely OOM killer or external kill. Check memory limits.`,
+      );
+      return;
+    }
+    console.error(`\nphy: killed by signal ${sig}`);
+    return;
+  }
+
+  // 3. Loader-stage exit codes — process exec'd but the dynamic linker failed.
+  if (result.status === 127) {
+    console.error(
+      `\nphy: exited 127 — dynamic linker could not load the binary\n` +
+        runtimeLine +
+        (isMusl
+          ? `Fix: ${muslHint}`
+          : `Fix: LD_DEBUG=libs ${binPath} ... (see which library failed to load)`),
+    );
+    return;
+  }
+  if (result.status === 126) {
+    console.error(`\nphy: exited 126 — binary found but not executable.`);
+    return;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phystack/cli",
-  "version": "5.2.1",
+  "version": "6.1.0",
   "description": "Phygrid CLI.",
   "main": "index.js",
   "homepage": "./",
@@ -37,11 +37,13 @@
   },
   "gitHead": "4b0803f6728ceb0665bd999b88ecbb31f8ea025c",
   "optionalDependencies": {
-    "@phystack/phy-darwin-arm64": "5.2.1",
-    "@phystack/phy-darwin-x64": "5.2.1",
-    "@phystack/phy-linux-arm64": "5.2.1",
-    "@phystack/phy-linux-x64": "5.2.1",
-    "@phystack/phy-win32-x64": "5.2.1",
-    "@phystack/phy-win32-arm64": "5.2.1"
+    "@phystack/phy-darwin-arm64": "6.1.0",
+    "@phystack/phy-darwin-x64": "6.1.0",
+    "@phystack/phy-linux-arm64": "6.1.0",
+    "@phystack/phy-linux-x64": "6.1.0",
+    "@phystack/phy-win32-x64": "6.1.0",
+    "@phystack/phy-win32-arm64": "6.1.0",
+    "@phystack/phy-linux-x64-musl": "6.1.0",
+    "@phystack/phy-linux-arm64-musl": "6.1.0"
   }
 }