@gjsify/cli 0.26.1 → 0.27.0

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

@@ -4,12 +4,28 @@ export interface NativePackage {
     /** Absolute path to the arch-specific prebuilds dir, e.g. "/…/@gjsify/webgl/prebuilds/linux-x64" */
     prebuildsDir: string;
 }
+/**
+ * Which C library an artifact is built against. npm's own `libc` manifest field
+ * uses exactly these two tokens, and it is LINUX-ONLY there — every other OS has
+ * one C library, so the axis does not exist off Linux and is `null` there rather
+ * than defaulted to something.
+ */
+export type HostLibc = 'glibc' | 'musl';
 /** The host target a resolution is performed for. Defaults to the running process. */
 export interface HostTarget {
     /** `process.platform` value — `linux` | `darwin` | `win32` | … */
     platform?: string;
     /** `process.arch` value — `x64` | `arm64` | `ppc64` | `s390x` | `riscv64` | … */
     arch?: string;
+    /**
+     * Host C library, or `undefined`/`null` when the axis does not apply (any
+     * non-Linux OS) or could not be determined. Both non-values mean the same
+     * thing to the resolver: behave exactly as before the libc axis existed —
+     * never offer a `-musl` directory. That is deliberately the conservative
+     * direction: an unsuffixed directory is the DEFAULT build, so a host we
+     * cannot classify still resolves what it always did.
+     */
+    libc?: HostLibc | null;
 }
 /**
  * Environment a GJS process needs so `gi://Gjsify…` imports resolve against
@@ -31,12 +47,78 @@ export interface NativeEnv {
     [key: string]: string | undefined;
 }
 /**
- * Canonical `<os>-<arch>` form — the node spelling — so `linux-x86_64` and
- * `linux-x64` compare equal. Only the *arch* half is normalised; the OS half
- * is always a `process.platform` token (`linux`/`darwin`/`win32`), which has
- * no competing spelling.
+ * Split a prebuild target into its three axes.
+ *
+ * TOKEN GRAMMAR: `<os>-<arch>[-musl]`.
+ *
+ * An UNSUFFIXED token means "the default build". Note what it does NOT mean: it
+ * is not a synonym for glibc. For an artifact that links `libc.so.6` the default
+ * build IS glibc; for one that links only GLib/GObject/GIO (plus GnuTLS resp.
+ * GStreamer) it is libc-AGNOSTIC and loads against whatever libc the host's GLib
+ * was built for. The directory name cannot express that difference and does not
+ * need to: the package's own `libc` field answers it at install time, and the
+ * `prebuild-libc` conformance rule verifies that field against the binaries
+ * (`readElfNeeded` — the DT_NEEDED list is where the answer actually lives).
+ *
+ * DELIBERATELY NOT CHOSEN: renaming every existing `linux-<arch>` directory to
+ * `linux-<arch>-gnu`, which is what a symmetric grammar would demand. It would
+ * rename ~60 COMMITTED directories, and — per `status/open-todos.md`'s
+ * "Nine fixtures re-implement the prebuild-target name instead of importing it"
+ * — nine e2e fixtures COMPOSE the token themselves instead of importing it, so
+ * the rename would have to be swept by hand in two shapes (the literal path and
+ * the computed one), which is exactly how the last vocabulary change missed
+ * `tests/e2e/self-host/run.mjs`. The asymmetric grammar buys the same
+ * expressiveness for zero renames, and the cost — that "unsuffixed" is not
+ * self-describing — is paid by a field that is machine-checked anyway.
+ *
+ * A `-musl` suffix is only meaningful when the OS half is `linux`: musl targets
+ * no other kernel, and npm's own `libc` field is documented as Linux-only. A
+ * `darwin-arm64-musl` token is therefore not a target with an odd name, it is a
+ * malformed one, and this returns `libc: null` for it so callers report the
+ * token rather than half-honouring it.
+ */
+export declare function parsePlatformToken(token: string): {
+    os: string;
+    arch: string;
+    libc: HostLibc | null;
+};
+/**
+ * Canonical `<os>-<arch>[-musl]` form — the node spelling — so `linux-x86_64`
+ * and `linux-x64` compare equal. Only the *arch* half is normalised: the OS half
+ * is always a `process.platform` token (`linux`/`darwin`/`win32`), which has no
+ * competing spelling, and the libc half has exactly one spelling by
+ * construction.
+ *
+ * A `-musl` suffix on a non-Linux token is preserved verbatim rather than
+ * dropped. Silently canonicalising `darwin-arm64-musl` to `darwin-arm64` would
+ * make a malformed declaration compare EQUAL to a valid one, so the audit that
+ * rejects it would never see it — the same class of bug as folding the legacy
+ * uname spelling on a WRITE path.
  */
 export declare function canonicalPlatformToken(token: string): string;
+/**
+ * The target tokens that describe THIS host, most-specific first — the WRITE-side
+ * vocabulary.
+ *
+ * This is the single definition of the musl preference order, and three callers
+ * share it so it cannot drift: the directory probe ({@link prebuildDirCandidates}),
+ * the per-platform sibling package probe ({@link platformPackageName}), and
+ * `scripts/stage-prebuild.mjs`, which must stage a musl build into
+ * `linux-x64-musl/` and never into `linux-x64/`.
+ *
+ * On a musl host the suffixed token comes FIRST and the unsuffixed one stays as a
+ * fallback: an unsuffixed directory is the default build, which for the
+ * libc-agnostic bridges (they record no `libc.so.6` at all) genuinely does load
+ * on musl. On glibc the `-musl` token is not offered at all — a musl artifact
+ * cannot load against glibc, so probing for it could only ever produce a
+ * false positive.
+ *
+ * @param platform `process.platform` value.
+ * @param arch `process.arch` value.
+ * @param libc host C library; `undefined`/`null` behaves as glibc (see
+ *   {@link HostTarget.libc} for why that is the safe default).
+ */
+export declare function hostPlatformTokens(platform: string, arch: string, libc?: HostLibc | null): string[];
 /**
  * The prebuild directory names to probe for a host, most-specific first.
  *
@@ -65,11 +147,21 @@ export declare function canonicalPlatformToken(token: string): string;
  * listing — no extra I/O — so tolerance on the READ side costs nothing, while
  * the single spelling is enforced everywhere a name is WRITTEN.
  *
+ * The LIBC AXIS rides in front of all of that: on a musl host the
+ * `<os>-<arch>-musl` token is preferred over `<os>-<arch>`, and on glibc the
+ * suffixed token is NEVER offered (a musl artifact cannot load against glibc, so
+ * a probe for it can only produce a false positive). The `libc` value is a
+ * PARAMETER rather than a `process` read for the same reason `platform` and
+ * `arch` are: it is the only way the musl branch gets exercised at all, since CI
+ * and every developer machine here run glibc.
+ *
  * @param platform `process.platform` value.
  * @param arch `process.arch` value.
  * @param declaredPlatforms `package.json#gjsify.platforms`, when present.
+ * @param libc host C library; `undefined`/`null` = behave as before the axis
+ *   existed.
  */
-export declare function prebuildDirCandidates(platform: string, arch: string, declaredPlatforms?: readonly string[] | undefined): string[];
+export declare function prebuildDirCandidates(platform: string, arch: string, declaredPlatforms?: readonly string[] | undefined, libc?: HostLibc | null): string[];
 /**
  * Pick the prebuild directory a host should load, given the directories that
  * actually exist under `<pkg>/<prebuilds>/`.
@@ -85,7 +177,28 @@ export declare function resolvePrebuildDirName(input: {
     arch: string;
     declaredPlatforms?: readonly string[] | undefined;
     existingDirs: readonly string[];
+    libc?: HostLibc | null;
 }): string | null;
+/**
+ * The npm name of the per-platform companion package for a target.
+ *
+ * `@gjsify/rolldown-native` + `linux-x64` → `@gjsify/rolldown-native-linux-x64`,
+ * the pattern `@gjsify/gtk-runtime-darwin-arm64` already ships (and the one
+ * napi-rs uses for its `<pkg>-<triple>` siblings, which
+ * `napi-node-addon.ts`'s `isNapiRsSibling` already knows).
+ *
+ * Exported so there is exactly ONE definition of it. The heavy bridges are being
+ * split into per-platform packages, and that rollout, the sibling resolution
+ * below and the workspace audit all need this string — three independent
+ * `` `${name}-${token}` `` template literals would be three places for the
+ * separator, the scope handling or the token spelling to drift, and a drifted
+ * copy fails as "prebuild not found" in a consumer while every test here stays
+ * green.
+ *
+ * @param baseName the depending package's npm name, scope included.
+ * @param token an `<os>-<arch>[-musl]` target.
+ */
+export declare function platformPackageName(baseName: string, token: string): string;
 /**
  * Walk up the directory tree from `startDir` and merge native packages found
  * in every `node_modules` encountered.
@@ -103,6 +216,48 @@ export declare function resolvePrebuildDirName(input: {
  * production call sites take the defaults.
  */
 export declare function detectNativePackages(startDir: string, target?: HostTarget): NativePackage[];
+/**
+ * Decide a host's C library from independently-gathered facts. PURE.
+ *
+ * Two probes, because neither is available everywhere this CLI runs:
+ *
+ *   1. `process.report.getReport().header.glibcVersionRuntime` — present iff the
+ *      running process is linked against glibc. This is the probe `detect-libc`
+ *      and node-gyp use, and it is authoritative when it answers. It is a
+ *      NODE-only API: under the committed GJS bundle `@gjsify/process` has no
+ *      `report`, so on the runtime this project targets FIRST it never answers.
+ *   2. Whether musl's dynamic loader is installed. musl always installs it as
+ *      `/lib/ld-musl-<arch>.so.1`, which is a fact about the SYSTEM rather than
+ *      about the running process, so it answers under GJS too.
+ *
+ * The order matters only for speed; the two cannot disagree on a sane host.
+ * When NEITHER answers we return `'glibc'`, and that is a claim about the
+ * evidence rather than a guess: probe 2 not finding a musl loader means the host
+ * has no musl at all, so `-musl` directories are not what it wants. The failure
+ * mode of the opposite default — treating an unclassified host as musl — is
+ * probing for suffixed directories on every glibc machine, which is noise with no
+ * upside.
+ *
+ * @param platform `process.platform` value; the axis is Linux-only (as npm's own
+ *   `libc` field is), so every other OS returns null.
+ */
+export declare function resolveHostLibc(input: {
+    platform: string;
+    glibcVersionRuntime?: string | undefined;
+    muslLoaderPresent?: boolean;
+}): HostLibc | null;
+/**
+ * Gather the two host facts {@link resolveHostLibc} decides from.
+ *
+ * BOTH are gathered unconditionally, even though the first one alone usually
+ * answers. They are independent observations — one about the running process, one
+ * about the system — and a host can genuinely exhibit both (a glibc-linked Node
+ * on a distro that also installs musl, e.g. under gcompat). Collecting them
+ * separately keeps the decision itself in one pure function a test can pin,
+ * instead of encoding the precedence in an if/else chain here where nothing can
+ * reach it.
+ */
+export declare function detectHostLibc(platform: string): HostLibc | null;
 /**
  * The environment-variable name the host's dynamic loader consults for an
  * additional shared-library search path, plus the separator its search paths