@gjsify/cli 0.28.0 → 0.30.0

package/lib/utils/check-system-deps.js

@@ -11,7 +11,7 @@
 // is in the project's dependency tree. A user with only @gjsify/fs in their
 // project never sees a warning about libmanette.
 import { execFileSync } from 'node:child_process';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
@@ -87,8 +87,8 @@ export function detectPackageManager() {
     }
     return 'unknown';
 }
-/** Optional system deps keyed by their DepCheck id. */
-const OPTIONAL_DEPS = {
+/** Optional system deps keyed by their DepCheck id. Exported for the spec's declaration invariant. */
+export const OPTIONAL_DEPS = {
     manette: { id: 'manette', name: 'libmanette', pkgName: 'manette-0.2' },
     gstreamer: { id: 'gstreamer', name: 'GStreamer', pkgName: 'gstreamer-1.0' },
     'gst-app': { id: 'gst-app', name: 'GStreamer App', pkgName: 'gstreamer-app-1.0' },
@@ -105,6 +105,21 @@ const OPTIONAL_DEPS = {
     // `Run-time dependency X found: NO` error mid-build.
     gnutls: { id: 'gnutls', name: 'GnuTLS', pkgName: 'gnutls' },
     nghttp2: { id: 'nghttp2', name: 'libnghttp2', pkgName: 'libnghttp2' },
+    // RUNTIME deps of the shipped prebuilds, not build-time ones — the distinction
+    // the two entries above make does not hold for these. Measured on fedora:43
+    // provisioned like a CONSUMER (gjs + libsoup3 only), `ldd` over every committed
+    // linux-x64 prebuild: three sonames do not resolve, and each makes its typelib
+    // UNLOADABLE, which surfaces as `Unsupported type void, deriving from
+    // fundamental void` at first construction — a message that names nothing.
+    //   @gjsify/rolldown-native  libjson-glib-1.0.so.0
+    //   @gjsify/webgl            libepoxy.so.0            (gdk-pixbuf already listed)
+    //   @gjsify/webrtc-native    libgstwebrtc-1.0.so.0    (gstreamer already listed)
+    // json-glib is the severe one: rolldown-native IS the GJS bundler engine, so a
+    // host without it cannot `gjsify build` at all, while `gjsify install` printed
+    // "System dependencies OK." — a check passing for the wrong reason.
+    'json-glib': { id: 'json-glib', name: 'JSON-GLib', pkgName: 'json-glib-1.0' },
+    epoxy: { id: 'epoxy', name: 'libepoxy', pkgName: 'epoxy' },
+    'gst-webrtc': { id: 'gst-webrtc', name: 'GStreamer WebRTC', pkgName: 'gstreamer-webrtc-1.0' },
 };
 /**
  * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
@@ -112,8 +127,11 @@ const OPTIONAL_DEPS = {
  * available trio GLib/GObject/Gio).
  *
  * Used to compute the set of optional deps to check for a given project.
+ *
+ * Exported for the spec's declaration invariant: every id named here must exist in
+ * OPTIONAL_DEPS, or the dep is silently never checked.
  */
-const PACKAGE_DEPS = {
+export const PACKAGE_DEPS = {
     '@gjsify/gamepad': ['manette'],
     '@gjsify/webaudio': ['gstreamer', 'gst-app'],
     '@gjsify/iframe': ['webkitgtk'],
@@ -124,13 +142,17 @@ const PACKAGE_DEPS = {
     // as a special-case checkNpmPackage rather than checkPkgConfig in
     // runOptionalChecks. Mapping it here so its presence in the project's
     // dep tree triggers the check.
-    '@gjsify/webgl': ['gwebgl'],
+    '@gjsify/webgl': ['gwebgl', 'gdk-pixbuf', 'epoxy'],
     // Native Vala bridges with `dependency('gnutls')` / `dependency('libnghttp2')`
     // in their meson.build. Optional because the shipped prebuild covers the
     // common-arch user path; only contributors rebuilding from source hit the
     // build-time dep.
     '@gjsify/tls-native': ['gnutls'],
     '@gjsify/http2-native': ['nghttp2'],
+    // Unlike the two above, these are LOAD-time: the prebuild is dynamically linked
+    // and GIRepository cannot open its backing library without them.
+    '@gjsify/rolldown-native': ['json-glib'],
+    '@gjsify/webrtc-native': ['gstreamer', 'gst-webrtc'],
     // @gjsify/event-bridge only needs gtk4/gdk which are already in the
     // required set, so it doesn't need an optional entry.
 };
@@ -367,6 +389,8 @@ const PM_PACKAGES = {
         cairo: 'libcairo2-dev',
         gnutls: 'libgnutls28-dev',
         nghttp2: 'libnghttp2-dev',
+        'json-glib': 'libjson-glib-dev',
+        epoxy: 'libepoxy-dev',
     },
     dnf: {
         gjs: 'gjs',
@@ -390,6 +414,8 @@ const PM_PACKAGES = {
         cairo: 'cairo-devel',
         gnutls: 'gnutls-devel',
         nghttp2: 'libnghttp2-devel',
+        'json-glib': 'json-glib-devel',
+        epoxy: 'libepoxy-devel',
     },
     pacman: {
         gjs: 'gjs',
@@ -413,6 +439,8 @@ const PM_PACKAGES = {
         cairo: 'cairo',
         gnutls: 'gnutls',
         nghttp2: 'libnghttp2',
+        'json-glib': 'json-glib',
+        epoxy: 'libepoxy',
     },
     zypper: {
         gjs: 'gjs',
@@ -436,6 +464,8 @@ const PM_PACKAGES = {
         cairo: 'cairo-devel',
         gnutls: 'libgnutls-devel',
         nghttp2: 'libnghttp2-devel',
+        'json-glib': 'json-glib-devel',
+        epoxy: 'libepoxy-devel',
     },
     apk: {
         gjs: 'gjs',
@@ -459,6 +489,8 @@ const PM_PACKAGES = {
         cairo: 'cairo-dev',
         gnutls: 'gnutls-dev',
         nghttp2: 'nghttp2-dev',
+        'json-glib': 'json-glib-dev',
+        epoxy: 'libepoxy-dev',
     },
     // macOS. Names verified against homebrew/core rather than inferred from the
     // Linux rows — the mapping is NOT mechanical: Homebrew ships no `-dev`/`-devel`
@@ -502,6 +534,8 @@ const PM_PACKAGES = {
         cairo: 'cairo',
         gnutls: 'gnutls',
         nghttp2: 'nghttp2',
+        'json-glib': 'json-glib',
+        epoxy: 'libepoxy',
     },
     unknown: {},
 };
@@ -546,3 +580,123 @@ export function buildInstallCommand(pm, missing) {
     }
     return lines.length > 0 ? lines.join('\n  ') : null;
 }
+/**
+ * Only libraries whose GIR carries a real `<package version>`, verified against
+ * the published packages rather than assumed. A binding whose value turns out
+ * degenerate is skipped at runtime by `isDegenerate`, so a wrong entry here
+ * cannot produce a false alarm — it can only produce silence.
+ */
+const TYPE_PACKAGE_BINDINGS = [
+    { pkgConfig: 'gtk4', typePackage: '@girs/gtk-4.0', namespaceVersion: '4.0' },
+    { pkgConfig: 'libadwaita-1', typePackage: '@girs/adw-1', namespaceVersion: '1' },
+    { pkgConfig: 'libsoup-3.0', typePackage: '@girs/soup-3.0', namespaceVersion: '3.0' },
+    { pkgConfig: 'glib-2.0', typePackage: '@girs/glib-2.0', namespaceVersion: '2.0' },
+    { pkgConfig: 'gobject-2.0', typePackage: '@girs/gobject-2.0', namespaceVersion: '2.0' },
+    { pkgConfig: 'gio-2.0', typePackage: '@girs/gio-2.0', namespaceVersion: '2.0' },
+    { pkgConfig: 'gstreamer-1.0', typePackage: '@girs/gst-1.0', namespaceVersion: '1.0' },
+    { pkgConfig: 'webkitgtk-6.0', typePackage: '@girs/webkit-6.0', namespaceVersion: '6.0' },
+    { pkgConfig: 'manette-0.2', typePackage: '@girs/manette-0.2', namespaceVersion: '0.2' },
+    { pkgConfig: 'pango', typePackage: '@girs/pango-1.0', namespaceVersion: '1.0' },
+    { pkgConfig: 'harfbuzz', typePackage: '@girs/harfbuzz-0.0', namespaceVersion: '0.0' },
+];
+/**
+ * Read `libraryVersion` from an installed `@girs/*` package.
+ *
+ * Resolves the package's MAIN entry and walks up to its root `package.json`
+ * rather than resolving the `package.json` subpath: `@girs/*` exports maps do not
+ * expose `./package.json` (verified on all 32 installed packages), so
+ * `require.resolve('@girs/gtk-4.0/package.json')` throws
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED`. The same trap silently disabled the
+ * `@nativescript/vite` major-version gate until it was found by measurement.
+ */
+function readGirsLibraryVersion(cwd, typePackage) {
+    for (const from of [pathToFileURL(join(cwd, '_girs_.js')).href, import.meta.url]) {
+        let dir;
+        try {
+            dir = dirname(createRequire(from).resolve(typePackage));
+        }
+        catch {
+            continue;
+        }
+        // Walk up to the package root — the entry may sit in a subdirectory.
+        for (let i = 0; i < 5; i++) {
+            const manifest = join(dir, 'package.json');
+            if (existsSync(manifest)) {
+                try {
+                    const parsed = JSON.parse(readFileSync(manifest, 'utf-8'));
+                    if (parsed.name === typePackage)
+                        return parsed.libraryVersion ?? null;
+                }
+                catch {
+                    return null; // present but unreadable — nothing to compare against
+                }
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+/** `[major, minor]`, or null when the string is not a comparable version. */
+function majorMinor(version) {
+    const match = /^(\d+)\.(\d+)/.exec(version.trim());
+    if (!match)
+        return null;
+    return [Number(match[1]), Number(match[2])];
+}
+/**
+ * True when `libraryVersion` is ts-for-gir's namespace-version fallback rather
+ * than a real upstream release — `@girs/gdk-4.0`'s `4.0.0` against namespace `4.0`.
+ *
+ * Compares against every `.0`-padded spelling of the namespace version, not just
+ * the three-component one: `4.0` and `4.0.0` are the same claim, and matching only
+ * the padded form let the bare spelling through as a bogus 18-minor "behind"
+ * finding. Deliberately NOT a major.minor comparison — `@girs/adw-1` has namespace
+ * `1` and a real `libraryVersion` of `1.10.0`, which any major-only rule discards.
+ */
+function isDegenerate(declared, namespaceVersion) {
+    const trimmed = declared.trim();
+    const parts = namespaceVersion.split('.');
+    for (let n = parts.length; n <= 3; n++) {
+        if (trimmed === [...parts, ...Array(n - parts.length).fill('0')].join('.'))
+            return true;
+    }
+    return false;
+}
+/**
+ * Compare each installed `@girs/*` package's declared upstream version against the
+ * library the host actually has. Only reports a `major.minor` difference: a micro
+ * difference does not change the API set, and reporting it would train people to
+ * ignore the output.
+ */
+export function checkTypeSkew(cwd, readers = {}) {
+    const readDeclared = readers.readDeclared ?? readGirsLibraryVersion;
+    const readInstalled = readers.readInstalled ?? ((pkgConfig) => tryExecFile('pkg-config', ['--modversion', pkgConfig]));
+    const findings = [];
+    for (const binding of TYPE_PACKAGE_BINDINGS) {
+        const declared = readDeclared(cwd, binding.typePackage);
+        if (declared === null)
+            continue; // types not installed, or no declaration
+        if (isDegenerate(declared, binding.namespaceVersion))
+            continue;
+        const installed = readInstalled(binding.pkgConfig);
+        if (installed === null)
+            continue; // library absent — the presence check owns that
+        const want = majorMinor(declared);
+        const have = majorMinor(installed.split('\n')[0] ?? installed);
+        if (!want || !have)
+            continue;
+        if (want[0] === have[0] && want[1] === have[1])
+            continue;
+        findings.push({
+            typePackage: binding.typePackage,
+            pkgConfig: binding.pkgConfig,
+            declared,
+            installed: installed.split('\n')[0] ?? installed,
+            relation: want[0] > have[0] || (want[0] === have[0] && want[1] > have[1]) ? 'ahead' : 'behind',
+        });
+    }
+    return findings;
+}

package/lib/utils/detect-native-packages.d.ts

@@ -1,3 +1,4 @@
+import { type SystemGiOptions } from './system-gi.js';
 export interface NativePackage {
     /** npm package name, e.g. "@gjsify/webgl" */
     name: string;
@@ -42,8 +43,15 @@ export interface NativeEnv {
     GI_TYPELIB_PATH: string;
     /** ELF loader (Linux and other ELF platforms). */
     LD_LIBRARY_PATH?: string;
-    /** Mach-O loader (macOS). `dyld` ignores `LD_LIBRARY_PATH` entirely. */
+    /** Mach-O loader (macOS), OVERRIDING resolution by leaf. `dyld` ignores `LD_LIBRARY_PATH` entirely. */
     DYLD_LIBRARY_PATH?: string;
+    /**
+     * Mach-O loader (macOS), consulted only AFTER the normal search fails. This
+     * is where the HOST's GI libdirs go — never `DYLD_LIBRARY_PATH`, which would
+     * shadow correctly-resolved libraries process-wide. See
+     * {@link buildNativeEnv}.
+     */
+    DYLD_FALLBACK_LIBRARY_PATH?: string;
     [key: string]: string | undefined;
 }
 /**
@@ -287,8 +295,44 @@ export declare function libraryPathVar(platform: string): {
  * (a stock Windows env block uses `Path`) — Windows env names are
  * case-insensitive, but a plain JS object is not, and `{...process.env,
  * PATH: …}` would hand a child process two competing entries.
+ *
+ * ── DARWIN ALSO GETS THE *HOST'S* GI LIBDIRS ─────────────────────────────────
+ *
+ * Everything above is about the prebuilds gjsify itself ships. On macOS there is
+ * a second, independent gap that has nothing to do with gjsify: a typelib names
+ * its library by BARE LEAF (`libgtk-4.1.dylib`), and dyld carries neither
+ * `/usr/local/lib` nor `/opt/homebrew/lib` in its default fallback path.
+ * Homebrew's `gjs` has an rpath into GLIB's keg only, so it resolves no other
+ * keg's leaves — measured: bare `gjs -c "imports.gi.Gtk; Gtk.init()"`, no gjsify
+ * in the process, dies on that dlopen (full trace in `utils/system-gi.ts`). This
+ * is the ONE place `gjsify run`, `showcase`, `storybook`, `tsc` and `info` all
+ * pass through, so it is where the child's launch env is repaired.
+ *
+ * Two properties are load-bearing:
+ *
+ *   1. **`DYLD_FALLBACK_LIBRARY_PATH`, never `DYLD_LIBRARY_PATH`.** The override
+ *      variable wins by LEAF for every dylib in the process, including ones the
+ *      host already resolved correctly — pointing it at a whole system libdir is
+ *      how you replace a linked-against library with a same-named different one.
+ *      The fallback is consulted only after the normal search fails, which is
+ *      exactly the "nothing else found it" case. Consequence, and it is the
+ *      intended precedence: gjsify's own prebuilds keep priority through the
+ *      override variable, the system stack fills in behind it.
+ *   2. **Our dirs go FIRST, an inherited fallback is kept BEHIND them, and
+ *      `/usr/lib` is appended when there is none.** Setting the variable
+ *      REPLACES dyld's own default fallback list, so writing only our dirs would
+ *      silently remove `/usr/lib` from the search — a host that exported the
+ *      variable itself already carries whatever tail it wants. Same composition
+ *      as node-gi's re-exec.
+ *
+ * Emitted even when `packages` is empty: the gap is in the host's loader, not in
+ * a gjsify prebuild, so a plain `gjsify run script.gjs.js` that touches GTK needs
+ * it just as much. Empty off darwin — `ld.so`'s configured cache already resolves
+ * these leaves on Linux, and Windows re-reads `PATH` per `LoadLibrary`.
  */
 export declare function buildNativeEnv(packages: NativePackage[], opts?: {
     platform?: string;
     env?: Record<string, string | undefined>;
+    /** Injectable for tests — the darwin branch is asserted from Linux. */
+    systemGiDirs?: (opts: SystemGiOptions) => string[];
 }): NativeEnv;

package/lib/utils/detect-native-packages.js

@@ -29,6 +29,7 @@
 import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readPackageJson } from './pkg-json.js';
+import { splitSearchPath, systemGiLibraryDirs } from './system-gi.js';
 /**
  * Map a Node `process.arch` value to the uname-style spelling the Vala/meson
  * bridges used to stage into (`prebuilds/linux-x86_64/`, the output of
@@ -558,6 +559,18 @@ export function libraryPathVar(platform) {
         return { name: 'PATH', separator: ';' };
     return { name: 'LD_LIBRARY_PATH', separator: ':' };
 }
+/**
+ * dyld's *fallback* search path — consulted only AFTER the normal search
+ * (rpath / absolute name / dyld cache) has failed.
+ *
+ * Deliberately NOT part of {@link libraryPathVar}, which answers a different
+ * question: that one names the variable that OVERRIDES resolution for every
+ * dylib in the process (the right home for a prebuild we ship and want used),
+ * this one names the variable that fills in what nothing else could find (the
+ * right home for the host's own libdirs). Mixing the two roles is the mistake
+ * `buildNativeEnv` documents at length.
+ */
+const DYLD_FALLBACK_VAR = 'DYLD_FALLBACK_LIBRARY_PATH';
 /**
  * Build the typelib + shared-library search-path environment for the detected
  * native packages. Prepends the new paths to any existing values.
@@ -569,6 +582,40 @@ export function libraryPathVar(platform) {
  * (a stock Windows env block uses `Path`) — Windows env names are
  * case-insensitive, but a plain JS object is not, and `{...process.env,
  * PATH: …}` would hand a child process two competing entries.
+ *
+ * ── DARWIN ALSO GETS THE *HOST'S* GI LIBDIRS ─────────────────────────────────
+ *
+ * Everything above is about the prebuilds gjsify itself ships. On macOS there is
+ * a second, independent gap that has nothing to do with gjsify: a typelib names
+ * its library by BARE LEAF (`libgtk-4.1.dylib`), and dyld carries neither
+ * `/usr/local/lib` nor `/opt/homebrew/lib` in its default fallback path.
+ * Homebrew's `gjs` has an rpath into GLIB's keg only, so it resolves no other
+ * keg's leaves — measured: bare `gjs -c "imports.gi.Gtk; Gtk.init()"`, no gjsify
+ * in the process, dies on that dlopen (full trace in `utils/system-gi.ts`). This
+ * is the ONE place `gjsify run`, `showcase`, `storybook`, `tsc` and `info` all
+ * pass through, so it is where the child's launch env is repaired.
+ *
+ * Two properties are load-bearing:
+ *
+ *   1. **`DYLD_FALLBACK_LIBRARY_PATH`, never `DYLD_LIBRARY_PATH`.** The override
+ *      variable wins by LEAF for every dylib in the process, including ones the
+ *      host already resolved correctly — pointing it at a whole system libdir is
+ *      how you replace a linked-against library with a same-named different one.
+ *      The fallback is consulted only after the normal search fails, which is
+ *      exactly the "nothing else found it" case. Consequence, and it is the
+ *      intended precedence: gjsify's own prebuilds keep priority through the
+ *      override variable, the system stack fills in behind it.
+ *   2. **Our dirs go FIRST, an inherited fallback is kept BEHIND them, and
+ *      `/usr/lib` is appended when there is none.** Setting the variable
+ *      REPLACES dyld's own default fallback list, so writing only our dirs would
+ *      silently remove `/usr/lib` from the search — a host that exported the
+ *      variable itself already carries whatever tail it wants. Same composition
+ *      as node-gi's re-exec.
+ *
+ * Emitted even when `packages` is empty: the gap is in the host's loader, not in
+ * a gjsify prebuild, so a plain `gjsify run script.gjs.js` that touches GTK needs
+ * it just as much. Empty off darwin — `ld.so`'s configured cache already resolves
+ * these leaves on Linux, and Windows re-reads `PATH` per `LoadLibrary`.
  */
 export function buildNativeEnv(packages, opts = {}) {
     const platform = opts.platform ?? process.platform;
@@ -588,5 +635,14 @@ export function buildNativeEnv(packages, opts = {}) {
         GI_TYPELIB_PATH: prepend(env['GI_TYPELIB_PATH'], giSeparator),
     };
     out[libVarKey] = prepend(env[libVarKey], libSeparator);
+    // The host's own GI libdirs — see the block comment above. `systemGiLibraryDirs`
+    // is itself `[]` off darwin, so this is a no-op elsewhere without a second
+    // platform test; the variable is only WRITTEN when there is something to put in
+    // it, so a Mac with no GI stack installed is left byte-unchanged.
+    const systemDirs = (opts.systemGiDirs ?? systemGiLibraryDirs)({ platform, env });
+    if (systemDirs.length > 0) {
+        const inherited = splitSearchPath(env[DYLD_FALLBACK_VAR]);
+        out[DYLD_FALLBACK_VAR] = [...systemDirs, ...(inherited.length > 0 ? inherited : ['/usr/lib'])].join(':');
+    }
     return out;
 }

package/lib/utils/dlx-cache.js

@@ -158,7 +158,7 @@ export function symlinkSwap(cacheDir, prepareDir, opts = {}) {
 }
 /** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
 export function cleanupStalePrepareDirs(cacheDir, _maxAgeMinutes = DEFAULT_TTL_MIN) {
-    // Out of scope for Phase 1 — pnpm has the same TODO. Leaving a stub so
+    // TODO(open-todos: 10 small API gaps): out of scope for Phase 1 — pnpm has the same stub. Kept so
     // call sites already exist when we do implement it.
     void cacheDir;
 }

package/lib/utils/install-backend-native.d.ts

@@ -5,7 +5,13 @@ interface ParsedSpec {
     name: string;
     range: string;
 }
-interface ResolvedNode {
+/**
+ * One placed package in the resolved tree. Exported as a TYPE only: it is the
+ * graph shape {@link computeOptionalFlags} and {@link applyPlatformFilter} take,
+ * so a spec can inject a tree by hand instead of driving a whole install to reach
+ * them. Nothing outside this module constructs one for real.
+ */
+export interface ResolvedNode {
     /** Package name (e.g. `@gjsify/cli`, `lodash`). */
     name: string;
     version: string;
@@ -133,6 +139,78 @@ export declare function applyPlatformFilter(nodes: ResolvedNode[], target: Platf
  * detection — no script is run, so node-free-ness is preserved.
  */
 export declare function warnMissingNativeBuilds(nodes: ResolvedNode[], prefix: string, log: Logger): void;
+/**
+ * A node's REQUIRED dependency edges: its `dependencies`, minus every name its
+ * `optionalDependencies` also lists. The one place that decides what kind an edge
+ * is — both the resolve walk and the optionality fixpoint read it, so the two
+ * cannot drift.
+ *
+ * THE SUBTRACTION IS npm's RULE, not a policy of ours: "entries in
+ * optionalDependencies will override entries of the same name in dependencies, so
+ * it's usually best to only put in one place" (npm's package.json docs). Measured
+ * on `@parcel/rust@2.16.4`, which lists all eight per-platform napi packages in
+ * both blocks: `npm install` exits 0, installs `@parcel/rust-linux-x64-gnu` only,
+ * and writes `"optional": true` for all eight in its `package-lock.json`.
+ *
+ * WHY IT IS NOT MERELY A DEDUP: the kind decides what an incompatible
+ * `os`/`cpu`/`libc` MEANS (`applyPlatformFilter` — fatal vs. inert) and whether a
+ * failed resolve is tolerated. Reading `dependencies` alone therefore does not
+ * just visit a name twice, it promotes a foreign-platform binary to a required
+ * dependency and fails installs npm completes.
+ *
+ * The inverse direction is deliberately NOT symmetric: a name in
+ * `optionalDependencies` alone is optional (no `dependencies` entry to override),
+ * which is what {@link resolveDeps}'s second queue loop covers.
+ */
+export declare function requiredDepEntries(node: Pick<ResolvedNode, 'dependencies' | 'optionalDependencies'>): [string, string][];
+/**
+ * Recompute every node's `optional` flag as a FIXPOINT over the placed graph.
+ * The only writer of the final flag; whatever the nodes arrive carrying is an
+ * input nothing checked (a BFS forward guess on the resolve path, a value read
+ * back out of a file on the lockfile path) and is overwritten unconditionally.
+ *
+ * DEFINITION: a node is REQUIRED iff it is reachable from `requiredNames`
+ * through REQUIRED edges alone ({@link requiredDepEntries} — `dependencies` minus
+ * the names `optionalDependencies` overrides); every other node is optional.
+ * Optionality is therefore INHERITED — a plain dependency OF an optional package
+ * is still optional — which is what npm's `optionalSet` computes.
+ *
+ * WHY A FIXPOINT AND NOT A ONE-SHOT PROMOTION AT THE REUSE SITE (the reviewed
+ * defect): the walk queues a node's own dep edges at the moment it is placed,
+ * carrying the optionality it had THEN. Promoting the node later leaves its
+ * children behind, so the answer depends on which edge BFS happened to traverse
+ * first — a genuinely required transitive dep reached first through an optional
+ * edge stayed flagged optional, was persisted that way, and was then silently
+ * skipped by the platform filter on every machine instead of raising
+ * EBADPLATFORM. A monotone worklist over the FINISHED graph cannot have that
+ * property: "required" only ever spreads, so the result is independent of visit
+ * order. npm reaches for the same shape and says so —
+ * refs/npm-cli/workspaces/arborist/lib/calc-dep-flags.js: "If a node is changed,
+ * we add to the queue and continue until no more changes."
+ *
+ * PATH-INDEPENDENCE IS THE OTHER REQUIREMENT, and it is why the lockfile carries
+ * an `optionalDependencies` map per entry (v4). The walk USED to read
+ * `dependencies` only, for exactly that reason — a lockfile entry recorded nothing
+ * else, so consulting `node.optionalDependencies` would have made the two paths
+ * compute different flags for the same tree. The premise was fixable and the
+ * consequence was not: a publisher listing the same name in BOTH blocks means
+ * "optional" to npm, came out REQUIRED here, and the shape is not rare — it is
+ * `@parcel/rust@2.16.4` (all eight per-platform napi packages in both blocks), so
+ * every Linux install of any tree containing parcel failed with EBADPLATFORM on
+ * `@parcel/rust-darwin-x64` while `npm install` thinned the same tree and exited
+ * 0. "Erring toward REQUIRED errs toward the loud failure" is true and was the
+ * wrong trade: the loud failure was not a real one, and no `--force` lifts it
+ * (nor should it). So the declaration is persisted and both paths subtract it.
+ * Reading a pre-v4 lockfile leaves the map empty, which reproduces the old
+ * behaviour for that file alone — see READABLE_LOCKFILE_VERSIONS.
+ *
+ * Runs before `writeLockfile` so the persisted flag is the final one, and before
+ * `applyPlatformFilter` so the fatal-vs-inert decision reads it rather than the
+ * guess. Exported so the unit spec can drive it with INJECTED graphs: the whole
+ * fatal-vs-inert question is decided by these two functions in composition, and
+ * that is worth pinning without a registry.
+ */
+export declare function computeOptionalFlags(nodes: ResolvedNode[], requiredNames: Set<string>, log: Logger): void;
 export declare function parseSpec(raw: string): ParsedSpec;
 export declare function pickVersion(packument: Packument, range: string, preferred?: string): string | null;
 /**
@@ -172,6 +250,14 @@ export declare function writeBinEntry(opts: {
         envPreamble: string;
         prebuildDirs: readonly string[];
     };
+    /**
+     * The package's npm `bin` target, when it declares one ALONGSIDE
+     * `gjsify.bin`. The launcher then picks a runtime per invocation instead of
+     * hard-coding `gjs` — see {@link pickBinMap}. Absent for a package that
+     * declares only one of the two, which is every package but `@gjsify/cli`
+     * today.
+     */
+    nodeFallbackAbs?: string;
 }): void;
 type Logger = (fmt: string, ...args: unknown[]) => void;
 export {};