@gjsify/cli 0.26.1 → 0.27.1

package/lib/utils/install-backend.js

@@ -12,9 +12,9 @@
 //
 // `--no-package-lock` keeps the cache prepare dir hermetic; the cache key
 // already covers reproducibility. `--no-audit --no-fund` cuts ~5s off cold runs.
-import { spawn } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { spawnToCompletion } from './spawn.js';
 export { makeProgressReporter } from './install-progress.js';
 const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
 export async function installPackages(opts) {
@@ -46,19 +46,21 @@ async function installViaNpm({ prefix, specs, verbose, registry }) {
         ...(verbose ? ['--loglevel', 'verbose'] : ['--loglevel', 'warn']),
         ...specs,
     ];
-    await new Promise((resolve, reject) => {
-        const child = spawn('npm', args, { stdio: 'inherit' });
-        child.on('close', (code) => {
-            if (code === 0)
-                resolve();
-            else
-                reject(new Error(`npm install exited with code ${code}`));
-        });
-        child.on('error', (err) => {
-            const msg = err.code === 'ENOENT'
-                ? 'npm not found on PATH — install Node.js or set GJSIFY_INSTALL_BACKEND=native (not yet supported)'
-                : `npm install failed: ${err.message}`;
-            reject(new Error(msg));
-        });
+    // Through `spawnToCompletion` so `npm` is resolved the way every other
+    // spawn in the CLI resolves it. A bare `spawn('npm', …)` is ENOENT on
+    // Windows — `CreateProcess` appends only `.exe` and npm ships a `.cmd`
+    // shim (see utils/win32-command.ts). That made this backend unusable
+    // there, and the ENOENT hint below actively misdiagnosed it: npm IS on
+    // PATH on such a host, and it told the user to select the backend that
+    // was already the default while calling it unsupported.
+    //
+    // `completion: 'return'` — `installPackages` resolves a promise to its
+    // caller instead of exiting, so under GJS this must not leave a main loop
+    // armed. (Moot in practice: this backend needs npm, hence Node.)
+    const { code } = await spawnToCompletion('npm', args, {
+        completion: 'return',
+        notFound: (err) => new Error(`npm not found on PATH — install Node.js, or unset GJSIFY_INSTALL_BACKEND to use the default native backend (${err.message})`),
     });
+    if (code !== 0)
+        throw new Error(`npm install exited with code ${code}`);
 }

package/lib/utils/install-global.js

@@ -24,7 +24,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { detectNativePackages } from './detect-native-packages.js';
-import { buildLauncherShims, buildNativeEnvPreamble, parseShebang } from './bin-shim.js';
+import { buildLauncherShims, buildNativeEnvPreamble, buildShLauncher, isGjsBundlePath, parseShebang, pickBinMap, } from './bin-shim.js';
 /**
  * Compute the canonical global install layout for the current user. Honours
  * `XDG_DATA_HOME` (per the XDG Base Directory Spec) plus
@@ -168,10 +168,10 @@ export function linkGlobalBins(packageNames, layout) {
         if (!fs.existsSync(pkgJsonPath))
             continue;
         const pkgJson = readJson(pkgJsonPath);
-        const binMap = pickBinMap(pkgName, pkgJson);
-        if (!binMap || binMap.size === 0)
+        const picked = pickBinMap(pkgName, pkgJson);
+        if (picked === null || picked.map.size === 0)
             continue;
-        for (const [binName, binTarget] of binMap) {
+        for (const [binName, binTarget] of picked.map) {
             const targetAbs = path.join(pkgDir, binTarget);
             if (!fs.existsSync(targetAbs))
                 continue;
@@ -197,14 +197,11 @@ export function linkGlobalBins(packageNames, layout) {
             // exec'ing a shebang-less .mjs file falls back to /bin/sh which
             // then tries to parse JavaScript as shell. Plain Node scripts
             // with shebangs (lib/index.js) keep the direct-exec path.
-            const isGjsBundle = targetAbs.endsWith('.gjs.mjs') || targetAbs.endsWith('.mjs');
+            const isGjsBundle = isGjsBundlePath(targetAbs);
             // Only GJS bundles need the GI typelib search path. Plain Node
             // scripts ignore GI_TYPELIB_PATH, so skipping the preamble there
             // keeps the launcher minimal.
-            const launcher = isGjsBundle
-                ? `#!/bin/sh\n${envPreamble}exec gjs -m ${shQuote(targetAbs)} "$@"\n`
-                : `#!/bin/sh\nexec ${shQuote(targetAbs)} "$@"\n`;
-            fs.writeFileSync(linkPath, launcher);
+            fs.writeFileSync(linkPath, buildShLauncher(targetAbs, { envPreamble, isGjsBundle }));
             fs.chmodSync(linkPath, 0o755);
             // Windows runs neither an extension-less file nor a `#!` line, so
             // the `sh` launcher above is only reachable from git-bash/MSYS/WSL.
@@ -241,9 +238,6 @@ export function linkGlobalBins(packageNames, layout) {
     }
     return created;
 }
-function shQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
 /** Parse a bin file's `#!` line; `null` when unreadable or not a shebang. */
 function readShebangOf(file) {
     try {
@@ -254,28 +248,6 @@ function readShebangOf(file) {
         return null;
     }
 }
-function pickBinMap(pkgName, pkgJson) {
-    const gjsifyEntry = pkgJson.gjsify;
-    if (gjsifyEntry?.bin !== undefined) {
-        return normalizeBin(pkgName, gjsifyEntry.bin);
-    }
-    const npmBin = pkgJson.bin;
-    if (npmBin !== undefined) {
-        return normalizeBin(pkgName, npmBin);
-    }
-    return null;
-}
-function normalizeBin(pkgName, bin) {
-    const out = new Map();
-    if (typeof bin === 'string') {
-        const baseName = pkgName.startsWith('@') ? pkgName.slice(pkgName.indexOf('/') + 1) : pkgName;
-        out.set(baseName, bin);
-        return out;
-    }
-    for (const [k, v] of Object.entries(bin))
-        out.set(k, v);
-    return out;
-}
 function readJson(file) {
     return JSON.parse(fs.readFileSync(file, 'utf-8'));
 }

package/lib/utils/install-lock.js

@@ -43,7 +43,7 @@
 // Escape hatch: GJSIFY_INSTALL_LOCK=0 disables locking entirely (e.g. for a
 // network filesystem with broken rename/mkdir atomicity, or an outer tool
 // that already serializes installs).
-import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 const LOCK_DIR_NAME = '.gjsify-install-lock';
 const OWNER_FILE = 'owner.json';

package/lib/utils/install-packument-cache.d.ts

@@ -1,11 +1,18 @@
 import type { Packument } from '@gjsify/npm-registry';
+/**
+ * Which document shape an entry holds. `'corgi'` = the abbreviated
+ * `application/vnd.npm.install-v1+json` install document (the default for every
+ * resolve); `'full'` = `application/json`. Same names pacote uses, so the two
+ * caches are describable in one sentence.
+ */
+export type PackumentShape = 'corgi' | 'full';
 export interface CachedPackument {
     etag: string;
     packument: Packument;
 }
 /**
- * The cache key for a (registry, name) pair — exported so the filename rule
- * below is a PROPERTY a test can assert, not a claim in a comment.
+ * The cache key for a (shape, registry, name) triple — exported so the filename
+ * rule below is a PROPERTY a test can assert, not a claim in a comment.
  *
  * THE SEPARATOR IS NOT COSMETIC. It used to be `|`, producing names like
  * `corgi|https%3A%2F%2Fregistry.npmjs.org%2F|%40gjsify%2Fnode-gi.json` — and `|`
@@ -17,25 +24,37 @@ export interface CachedPackument {
  * entire reason this file exists never engaged once.
  *
  * `,` is legal on Win32 AND escaped by `encodeURIComponent`, which is what keeps
- * a flat two-part name injective: an encoded part cannot contain the separator,
- * so exactly one `(registry, name)` pair maps to any given filename.
+ * a flat three-part name injective: an encoded part cannot contain the
+ * separator, so exactly one triple maps to any given filename. The shape needs
+ * no encoding — it is one of two literals, neither containing the separator —
+ * and it LEADS so that listing a shard groups by shape.
  *
  * The shard key and the filename are derived from the SAME encoded parts. They
- * used to disagree — the key hashed the raw pair while the name used the encoded
- * one — which is how a reserved character in the name survived review of a
- * function whose other half looked correct.
+ * used to disagree — the key hashed the raw values while the name used the
+ * encoded ones — which is how a reserved character in the name survived review
+ * of a function whose other half looked correct.
  */
-export declare function packumentCacheKey(registry: string, name: string): string;
+export declare function packumentCacheKey(registry: string, name: string, shape: PackumentShape): string;
 /**
- * Read a cached packument + its ETag for `(registry, name)`. Returns `null` on
- * a miss, when the cache is disabled, or when the entry is unreadable/corrupt
- * (treated as a miss — the caller just re-fetches).
+ * Read a cached packument + its ETag for `(registry, name)` in the given
+ * document `shape`. Returns `null` on a miss, when the cache is disabled, or
+ * when the entry is unreadable/corrupt (treated as a miss — the caller just
+ * re-fetches).
+ *
+ * `shape` defaults to `'corgi'` because that is what a resolve fetches and what
+ * every caller predating the full-document escalation meant. A caller that
+ * escalated MUST pass `'full'` — reading the corgi entry would return a body
+ * with no `libc`, i.e. the exact wrong answer the shape key exists to prevent.
  */
-export declare function getCachedPackument(registry: string, name: string): CachedPackument | null;
+export declare function getCachedPackument(registry: string, name: string, shape?: PackumentShape): CachedPackument | null;
 /**
- * Persist a packument + ETag for `(registry, name)`. Writes to a `<path>.tmp.<pid>`
- * sibling then atomically renames so a concurrent reader never sees a partial
- * write. No-op when the cache is disabled, the ETag is empty, or the write
- * fails (read-only / out-of-disk cache volume must not break the install).
+ * Persist a packument + ETag for `(registry, name)` under its document `shape`.
+ * Writes to a `<path>.tmp.<pid>` sibling then atomically renames so a concurrent
+ * reader never sees a partial write. No-op when the cache is disabled, the ETag
+ * is empty, or the write fails (read-only / out-of-disk cache volume must not
+ * break the install).
+ *
+ * `shape` is last and defaults to `'corgi'` to keep the pre-escalation call
+ * shape valid; it must match the `accept` header the body was fetched with.
  */
-export declare function putCachedPackument(registry: string, name: string, etag: string, packument: Packument): void;
+export declare function putCachedPackument(registry: string, name: string, etag: string, packument: Packument, shape?: PackumentShape): void;

package/lib/utils/install-packument-cache.js

@@ -13,22 +13,37 @@
 //
 // Layout:
 //
-//   $XDG_CACHE_HOME/gjsify/metadata/v2/<shard>/<encoded-registry>,<encoded-name>.json
+//   $XDG_CACHE_HOME/gjsify/metadata/v3/<shard>/<shape>,<encoded-registry>,<encoded-name>.json
 //
-// The cache is keyed by (registry, name) — NOT name alone — so switching the
-// registry for a scope can never serve a packument from the wrong source on a
-// coincidental ETag match. `<shard>` is a 2-hex FNV-1a digest of the key, a
+// The cache is keyed by (SHAPE, registry, name) — NOT name alone — so switching
+// the registry for a scope can never serve a packument from the wrong source on
+// a coincidental ETag match. `<shard>` is a 2-hex FNV-1a digest of the key, a
 // directory-fan-out step so the leaf dir never grows unbounded (same rationale
 // as the tarball cache's hex sharding). `v2` is a layout version.
 //
+// WHY THE SHAPE IS PART OF THE KEY (the v1 → v2 bump): the same packument URL
+// serves TWO different documents — the abbreviated "corgi" install document and
+// the full one — and only the full one carries a version's `libc` field (see
+// `@gjsify/npm-registry` `FetchOptions.fullMetadata`). With one key per (registry,
+// name), an escalated read would be answered by whichever shape happened to be
+// cached first: a musl-only package would come back `libc`-less, be judged
+// compatible on a glibc host, and get installed — a WRONG ANSWER that looks
+// exactly like a cache hit, with no failure until something dlopens the binary.
+// pacote prefixes its own cache key with `full:`/`corgi:` for precisely this
+// reason. The layout bump (rather than just a longer filename) makes the v1
+// entries — written before the distinction existed and therefore of unknown
+// shape — unreachable instead of ambiguous.
+//
 // Disabled with `GJSIFY_PACKUMENT_CACHE=0` (or `false`). Honours
 // `XDG_CACHE_HOME` like the tarball + dlx caches.
 import { join } from 'node:path';
 import { atomicWrite, gjsifyCacheRoot, readCacheFile } from './install-cache-fs.js';
-// v2: the separator changed from the Win32-reserved `|` to `,` (see `pathFor`),
-// so every v1 entry is unreachable rather than merely stale — a new root retires
-// them instead of leaving orphans under the old one.
-const CACHE_LAYOUT_VERSION = 'v2';
+// v3, and BOTH halves of the bump matter. v2 moved the separator off the
+// Win32-reserved `|` (see `packumentCacheKey`); v3 additionally makes the
+// document SHAPE part of the key. Either change alone makes older entries
+// unreachable rather than merely stale, so a new root retires them instead of
+// leaving ambiguous orphans under the old one.
+const CACHE_LAYOUT_VERSION = 'v3';
 /** `true` unless `GJSIFY_PACKUMENT_CACHE` is `0` / `false` / empty. */
 function isEnabled() {
     const flag = process.env.GJSIFY_PACKUMENT_CACHE;
@@ -37,7 +52,7 @@ function isEnabled() {
     const trimmed = flag.trim();
     return !(trimmed === '0' || trimmed === 'false' || trimmed === '');
 }
-/** Root of the packument cache: `$XDG_CACHE_HOME/gjsify/metadata/v2`. */
+/** Root of the packument cache: `$XDG_CACHE_HOME/gjsify/metadata/v3`. */
 function cacheRoot() {
     return gjsifyCacheRoot('metadata', CACHE_LAYOUT_VERSION);
 }
@@ -62,8 +77,8 @@ function encodePart(part) {
     return encodeURIComponent(part).replace(/\*/g, '%2A');
 }
 /**
- * The cache key for a (registry, name) pair — exported so the filename rule
- * below is a PROPERTY a test can assert, not a claim in a comment.
+ * The cache key for a (shape, registry, name) triple — exported so the filename
+ * rule below is a PROPERTY a test can assert, not a claim in a comment.
  *
  * THE SEPARATOR IS NOT COSMETIC. It used to be `|`, producing names like
  * `corgi|https%3A%2F%2Fregistry.npmjs.org%2F|%40gjsify%2Fnode-gi.json` — and `|`
@@ -75,30 +90,39 @@ function encodePart(part) {
  * entire reason this file exists never engaged once.
  *
  * `,` is legal on Win32 AND escaped by `encodeURIComponent`, which is what keeps
- * a flat two-part name injective: an encoded part cannot contain the separator,
- * so exactly one `(registry, name)` pair maps to any given filename.
+ * a flat three-part name injective: an encoded part cannot contain the
+ * separator, so exactly one triple maps to any given filename. The shape needs
+ * no encoding — it is one of two literals, neither containing the separator —
+ * and it LEADS so that listing a shard groups by shape.
  *
  * The shard key and the filename are derived from the SAME encoded parts. They
- * used to disagree — the key hashed the raw pair while the name used the encoded
- * one — which is how a reserved character in the name survived review of a
- * function whose other half looked correct.
+ * used to disagree — the key hashed the raw values while the name used the
+ * encoded ones — which is how a reserved character in the name survived review
+ * of a function whose other half looked correct.
  */
-export function packumentCacheKey(registry, name) {
-    return `${encodePart(registry)},${encodePart(name)}`;
+export function packumentCacheKey(registry, name, shape) {
+    return `${shape},${encodePart(registry)},${encodePart(name)}`;
 }
-function pathFor(registry, name) {
+/** Filesystem path for a (shape, registry, name) triple, or `null` when disabled. */
+function pathFor(registry, name, shape) {
     if (!isEnabled())
         return null;
-    const key = packumentCacheKey(registry, name);
+    const key = packumentCacheKey(registry, name, shape);
     return join(cacheRoot(), shardFor(key), `${key}.json`);
 }
 /**
- * Read a cached packument + its ETag for `(registry, name)`. Returns `null` on
- * a miss, when the cache is disabled, or when the entry is unreadable/corrupt
- * (treated as a miss — the caller just re-fetches).
+ * Read a cached packument + its ETag for `(registry, name)` in the given
+ * document `shape`. Returns `null` on a miss, when the cache is disabled, or
+ * when the entry is unreadable/corrupt (treated as a miss — the caller just
+ * re-fetches).
+ *
+ * `shape` defaults to `'corgi'` because that is what a resolve fetches and what
+ * every caller predating the full-document escalation meant. A caller that
+ * escalated MUST pass `'full'` — reading the corgi entry would return a body
+ * with no `libc`, i.e. the exact wrong answer the shape key exists to prevent.
  */
-export function getCachedPackument(registry, name) {
-    const path = pathFor(registry, name);
+export function getCachedPackument(registry, name, shape = 'corgi') {
+    const path = pathFor(registry, name, shape);
     if (!path)
         return null;
     const buf = readCacheFile(path);
@@ -117,15 +141,19 @@ export function getCachedPackument(registry, name) {
     }
 }
 /**
- * Persist a packument + ETag for `(registry, name)`. Writes to a `<path>.tmp.<pid>`
- * sibling then atomically renames so a concurrent reader never sees a partial
- * write. No-op when the cache is disabled, the ETag is empty, or the write
- * fails (read-only / out-of-disk cache volume must not break the install).
+ * Persist a packument + ETag for `(registry, name)` under its document `shape`.
+ * Writes to a `<path>.tmp.<pid>` sibling then atomically renames so a concurrent
+ * reader never sees a partial write. No-op when the cache is disabled, the ETag
+ * is empty, or the write fails (read-only / out-of-disk cache volume must not
+ * break the install).
+ *
+ * `shape` is last and defaults to `'corgi'` to keep the pre-escalation call
+ * shape valid; it must match the `accept` header the body was fetched with.
  */
-export function putCachedPackument(registry, name, etag, packument) {
+export function putCachedPackument(registry, name, etag, packument, shape = 'corgi') {
     if (!etag)
         return;
-    const path = pathFor(registry, name);
+    const path = pathFor(registry, name, shape);
     if (!path)
         return;
     const entry = { etag, packument };

package/lib/utils/oxc-resolve.d.ts

@@ -9,7 +9,33 @@ export declare function findOxcLauncher(tool: OxcTool, cwd?: string): string;
 export declare class OxcNotFoundError extends Error {
     tool: OxcTool;
     cwd: string;
-    constructor(tool: OxcTool, cwd: string);
+    /**
+     * The interpreter that could not be executed, when the LAUNCHER resolved
+     * and the spawn still failed with `ENOENT`.
+     *
+     * Then the missing file is the interpreter, not the tool, and saying
+     * "install <tool>" sends the user in a circle: on a Node-less GJS host
+     * (postmarketOS/aarch64, gjs present, no node) `gjsify install -D oxlint`
+     * succeeds, the launcher lands on disk, and the next run repeats the very
+     * same advice. `spawnToCompletion`'s `notFound` fires for the COMMAND, and
+     * the command here is `node` — never the launcher, which
+     * {@link findOxcLauncher} already proved exists by not throwing.
+     */
+    missingInterpreter?: string | undefined;
+    constructor(tool: OxcTool, cwd: string, 
+    /**
+     * The interpreter that could not be executed, when the LAUNCHER resolved
+     * and the spawn still failed with `ENOENT`.
+     *
+     * Then the missing file is the interpreter, not the tool, and saying
+     * "install <tool>" sends the user in a circle: on a Node-less GJS host
+     * (postmarketOS/aarch64, gjs present, no node) `gjsify install -D oxlint`
+     * succeeds, the launcher lands on disk, and the next run repeats the very
+     * same advice. `spawnToCompletion`'s `notFound` fires for the COMMAND, and
+     * the command here is `node` — never the launcher, which
+     * {@link findOxcLauncher} already proved exists by not throwing.
+     */
+    missingInterpreter?: string | undefined);
 }
 /**
  * Walk up from a starting directory to find the nearest oxlint config

package/lib/utils/oxc-resolve.js

@@ -46,10 +46,11 @@
 // lives in the Node launcher, so a native oxlint bridge could only run the
 // Rust rule subset. Lint stays Node-spawned until that trade-off is decided
 // (tracked in status/open-todos.md).
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
+import { hostLibc } from './platform-check.js';
 import { findWorkspaceRoot } from './workspace-root.js';
 import { resolveNpmPackage } from './resolve-npm-package.js';
 import { nodeBinary } from './run-node.js';
@@ -85,24 +86,23 @@ function oxcBindingSuffix() {
         throw new Error(`[gjsify oxc] Unsupported arch on ${plat}: ${arch}`);
     if (plat === 'linux') {
         // musl detection on Linux — oxc ships separate musl/gnu bindings.
-        // Same approach as biome's launcher: probe for the musl loader.
-        // glibc systems have `/lib/ld-linux-*`, musl has `/lib/ld-musl-*`.
-        let libc = 'gnu';
-        try {
-            // `readdirSync` is imported STATICALLY at the top of this file. It
-            // used to be a lazy `require('node:fs')` inside this try — a bare
-            // `require` in an ESM module, so it threw ReferenceError, the catch
-            // below swallowed it, and `libc` silently stayed 'gnu': a musl host
-            // would be told to install the WRONG binding package. Same defect
-            // class as commands/affected.ts, and even quieter.
-            const libEntries = readdirSync('/lib');
-            if (libEntries.some((e) => e.startsWith('ld-musl-'))) {
-                libc = 'musl';
-            }
-        }
-        catch {
-            // /lib unreadable — fall through, glibc is the safer default
-        }
+        //
+        // ONE DEFINITION, in `platform-check.ts`. This used to be a local
+        // `readdirSync('/lib')` scan for `ld-musl-*`, which is the same question
+        // the install backend asks about a package's `libc` field — and the local
+        // copy is the one that broke: its `readdirSync` was a lazy
+        // `require('node:fs')`, a bare `require` in an ESM module, so it threw
+        // ReferenceError, the surrounding catch swallowed it, and every host was
+        // silently told to install the `-gnu` binding. `hostLibc()` is the shared
+        // probe (ldd text → process.report → loader scan), memoized and unit-
+        // tested with injected hosts, so a musl box gets the right answer here
+        // and in the resolver from the same code.
+        //
+        // Vocabulary hop: npm spells the families `glibc`/`musl`, napi-rs target
+        // triples spell them `gnu`/`musl`. An UNKNOWN libc maps to `gnu` — this
+        // string only names a package in an install HINT, and gnu is the right
+        // guess for the overwhelming majority of hosts we cannot probe.
+        const libc = hostLibc('linux') === 'musl' ? 'musl' : 'gnu';
         return `${plat}-${a}-${libc}`;
     }
     if (plat === 'win32')
@@ -158,7 +158,21 @@ export function findOxcLauncher(tool, cwd = process.cwd()) {
 export class OxcNotFoundError extends Error {
     tool;
     cwd;
-    constructor(tool, cwd) {
+    missingInterpreter;
+    constructor(tool, cwd, 
+    /**
+     * The interpreter that could not be executed, when the LAUNCHER resolved
+     * and the spawn still failed with `ENOENT`.
+     *
+     * Then the missing file is the interpreter, not the tool, and saying
+     * "install <tool>" sends the user in a circle: on a Node-less GJS host
+     * (postmarketOS/aarch64, gjs present, no node) `gjsify install -D oxlint`
+     * succeeds, the launcher lands on disk, and the next run repeats the very
+     * same advice. `spawnToCompletion`'s `notFound` fires for the COMMAND, and
+     * the command here is `node` — never the launcher, which
+     * {@link findOxcLauncher} already proved exists by not throwing.
+     */
+    missingInterpreter) {
         const binding = (() => {
             try {
                 return bindingPackageName(tool);
@@ -167,13 +181,24 @@ export class OxcNotFoundError extends Error {
                 return `@${tool === 'oxlint' ? 'oxlint' : 'oxfmt'}/binding-<platform>`;
             }
         })();
-        super(`[gjsify oxc] ${tool} not found.\n` +
-            `  Expected: ${tool}/bin/${tool} in node_modules of ${cwd} or any workspace root above it.\n` +
-            `  Install it via: gjsify install -D ${tool}\n` +
-            `  (this adds ${tool} to devDependencies; the matching ${binding} ` +
-            `napi binding lands automatically as an optionalDependency.)`);
+        super(missingInterpreter === undefined
+            ? `[gjsify oxc] ${tool} not found.\n` +
+                `  Expected: ${tool}/bin/${tool} in node_modules of ${cwd} or any workspace root above it.\n` +
+                `  Install it via: gjsify install -D ${tool}\n` +
+                `  (this adds ${tool} to devDependencies; the matching ${binding} ` +
+                `napi binding lands automatically as an optionalDependency.)`
+            : `[gjsify oxc] cannot run ${tool}: no \`${missingInterpreter}\` binary on PATH.\n` +
+                `  ${tool} IS installed — its launcher was found. What is missing is the\n` +
+                `  interpreter that runs it: ${tool}'s launcher is a Node ESM script.\n` +
+                (tool === 'oxfmt'
+                    ? `  For a Node-free formatter install the GI bridge:\n` +
+                        `    gjsify install -D @gjsify/oxfmt-native\n` +
+                        `  (\`gjsify format\`/\`fix\` then run oxfmt in-process under GJS.)`
+                    : `  oxlint has no native GJS bridge yet — its JS-plugin host lives in the\n` +
+                        `  Node launcher — so \`gjsify lint\` needs Node on the host for now.`));
         this.tool = tool;
         this.cwd = cwd;
+        this.missingInterpreter = missingInterpreter;
         this.name = 'OxcNotFoundError';
     }
 }
@@ -322,7 +347,9 @@ function spawnOxcLauncher(tool, args, opts = {}) {
     return spawnToCompletion(node, [launcher, ...args], {
         completion: 'return',
         cwd,
-        notFound: () => new OxcNotFoundError(tool, cwd),
+        // ENOENT here is the COMMAND — `node` — not the launcher: `findOxcLauncher`
+        // above already proved that exists by not throwing.
+        notFound: () => new OxcNotFoundError(tool, cwd, node),
     }).then(({ code, signal }) => {
         if (signal !== null) {
             console.error(`[gjsify oxc] ${tool} terminated by signal ${signal}`);

package/lib/utils/pkg-json.d.ts

@@ -1,6 +1,30 @@
 import type { PackageJson } from './pkg-json-edit.js';
+/**
+ * Drop a leading UTF-8 BOM (`U+FEFF`, the decoded form of `EF BB BF`).
+ *
+ * `JSON.parse` rejects a BOM — it is not whitespace — so a manifest carrying
+ * one is "invalid JSON" to every reader here. That is not a hypothetical file
+ * shape on Windows: Windows PowerShell 5.1 writes a BOM for `-Encoding utf8`,
+ * which is its DEFAULT for `Out-File`/`Set-Content`, so any script that edits a
+ * manifest produces one. Notepad offers "UTF-8 with BOM" too.
+ *
+ * npm reads such a file without complaint (`npm pkg get name` on a BOM'd
+ * manifest returns the name), so the file is valid as far as the ecosystem is
+ * concerned and gjsify was the strict one. Stripping matches npm, VS Code and
+ * `parse-json`'s own guidance; nothing downstream wants the character.
+ *
+ * Only a LEADING BOM: `U+FEFF` elsewhere is a zero-width no-break space inside
+ * a string value, and removing it would corrupt the data.
+ */
+export declare function stripBom(text: string): string;
 /**
  * Read + parse a `package.json` at `pkgPath`. Permissive: any error (missing
  * file, unreadable, invalid JSON) yields `null`.
+ *
+ * The BOM strip matters MORE here than in a throwing reader: this one reports
+ * an unparseable manifest as `null`, which every caller reads as "no
+ * package.json". On Windows a BOM therefore did not produce an error — it made
+ * a package look like it had no manifest at all, so `gjsify check` found no
+ * `check` script, discovery skipped the package, and nothing said why.
  */
 export declare function readPackageJson(pkgPath: string): PackageJson | null;

package/lib/utils/pkg-json.js

@@ -10,13 +10,39 @@
 // during `gjsify install <pkg>`. That contract is intentional and load-bearing
 // — do not fold it into this one.
 import { readFileSync } from 'node:fs';
+/**
+ * Drop a leading UTF-8 BOM (`U+FEFF`, the decoded form of `EF BB BF`).
+ *
+ * `JSON.parse` rejects a BOM — it is not whitespace — so a manifest carrying
+ * one is "invalid JSON" to every reader here. That is not a hypothetical file
+ * shape on Windows: Windows PowerShell 5.1 writes a BOM for `-Encoding utf8`,
+ * which is its DEFAULT for `Out-File`/`Set-Content`, so any script that edits a
+ * manifest produces one. Notepad offers "UTF-8 with BOM" too.
+ *
+ * npm reads such a file without complaint (`npm pkg get name` on a BOM'd
+ * manifest returns the name), so the file is valid as far as the ecosystem is
+ * concerned and gjsify was the strict one. Stripping matches npm, VS Code and
+ * `parse-json`'s own guidance; nothing downstream wants the character.
+ *
+ * Only a LEADING BOM: `U+FEFF` elsewhere is a zero-width no-break space inside
+ * a string value, and removing it would corrupt the data.
+ */
+export function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
 /**
  * Read + parse a `package.json` at `pkgPath`. Permissive: any error (missing
  * file, unreadable, invalid JSON) yields `null`.
+ *
+ * The BOM strip matters MORE here than in a throwing reader: this one reports
+ * an unparseable manifest as `null`, which every caller reads as "no
+ * package.json". On Windows a BOM therefore did not produce an error — it made
+ * a package look like it had no manifest at all, so `gjsify check` found no
+ * `check` script, discovery skipped the package, and nothing said why.
  */
 export function readPackageJson(pkgPath) {
     try {
-        return JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return JSON.parse(stripBom(readFileSync(pkgPath, 'utf-8')));
     }
     catch {
         return null;