@gjsify/cli 0.26.0 → 0.27.0

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

@@ -1,10 +1,17 @@
 // Utility to find npm packages with gjsify native prebuilds.
 // Packages declare: "gjsify": { "prebuilds": "<dir>" } in their package.json,
-// and (since the OS-axis audit) the `<os>-<arch>` targets they promise in
-// "gjsify": { "platforms": [...] }.
+// and (since the OS-axis audit) the `<os>-<arch>[-musl]` targets they promise in
+// "gjsify": { "platforms": [...] }. The libc half of that token is the newest
+// axis; which libc a package's artifacts actually NEED is a separate, measured
+// claim (npm's `libc` field + `gjsify.glibcRequires`, held to the binaries by the
+// `prebuild-libc` conformance rule) — this file only resolves DIRECTORIES.
 //
-// One algorithm — `detectNativePackages(startDir)` — walks up from `startDir`
-// and exhaustively scans every `node_modules` it finds. Used by:
+// TWO passes, and the second one exists because the first cannot see an isolated
+// (pnpm-style) layout: `detectNativePackages(startDir)` walks up from `startDir`
+// and exhaustively scans every `node_modules` it finds, then resolves any package
+// that DECLARED a prebuild without shipping one through its per-platform
+// companion package (`<name>-<token>`), searching from THAT package's own
+// directory. See `resolvePlatformSibling`. Used by:
 //   * `gjsify run`, `gjsify info`, `gjsify install` — startDir = process.cwd()
 //   * `runGjsBundle()` — startDir = dirname(bundlePath), so DLX-cache layouts
 //     (`~/.cache/gjsify/dlx/<sha>/.../node_modules/<pkg>/dist/bundle.js`) get
@@ -13,11 +20,12 @@
 //     for packages whose Vala typelibs live in *indirect* deps.
 //
 // PLATFORM RESOLUTION IS A PURE FUNCTION. Everything that depends on the host
-// OS/CPU lives in `resolvePrebuildDirName()` / `buildNativeEnv()`, both of
-// which take `platform` / `arch` as parameters instead of reading
-// `process.platform` inline. That is what makes the darwin and win32 branches
-// unit-testable from a Linux host (see `detect-native-packages.spec.ts`) —
-// the host values are only read at the outermost call site, as a default.
+// OS/CPU/libc lives in `resolvePrebuildDirName()` / `buildNativeEnv()` /
+// `resolveHostLibc()`, all of which take `platform` / `arch` / `libc` as
+// parameters instead of reading `process.platform` inline. That is what makes
+// the darwin, win32 AND musl branches unit-testable from a glibc Linux host
+// (see `detect-native-packages.spec.ts`) — the host values are only read at the
+// outermost call site, as a default.
 import { readdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { readPackageJson } from './pkg-json.js';
@@ -39,10 +47,11 @@ const NODE_ARCH_TO_LEGACY_UNAME = {
 };
 /**
  * Arch spellings that name the same target, folded onto the NODE spelling.
- * Mirrors `ARCH_ALIASES` in `scripts/audit-runtimes.mjs` — that script
- * canonicalises `package.json#gjsify.platforms` the same way for the
- * platform-support matrix, and the two MUST agree or a package could pass the
- * audit while the CLI fails to find its artifact.
+ * Mirrors `ARCH_ALIASES` in `packages/infra/manifest-conformance/lib/platforms.mjs`
+ * — the table `scripts/audit-runtimes.mjs` canonicalises
+ * `package.json#gjsify.platforms` through for the platform-support matrix and the
+ * prebuild rules. The two MUST agree or a package could pass the audit while the
+ * CLI fails to find its artifact.
  *
  * The direction matters: `${process.platform}-${process.arch}` is what a
  * running process can compute about itself, so folding *onto* it means the
@@ -54,18 +63,104 @@ const ARCH_ALIASES = {
     aarch64: 'arm64',
 };
 /**
- * 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.
+ * The libc suffix a prebuild target may carry. Only ONE value is spelled out,
+ * and that asymmetry is the whole design of the grammar — see
+ * {@link canonicalPlatformToken}.
+ */
+const MUSL_SUFFIX = '-musl';
+/**
+ * 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 function parsePlatformToken(token) {
+    const isMusl = token.endsWith(MUSL_SUFFIX);
+    const base = isMusl ? token.slice(0, -MUSL_SUFFIX.length) : token;
+    const dash = base.indexOf('-');
+    const os = dash < 0 ? base : base.slice(0, dash);
+    const arch = dash < 0 ? '' : base.slice(dash + 1);
+    return { os, arch, libc: isMusl && os === 'linux' ? 'musl' : 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 function canonicalPlatformToken(token) {
-    const dash = token.indexOf('-');
-    if (dash < 0)
+    const { os, arch, libc } = parsePlatformToken(token);
+    if (!arch)
         return token;
-    const os = token.slice(0, dash);
-    const arch = token.slice(dash + 1);
-    return `${os}-${ARCH_ALIASES[arch] ?? arch}`;
+    const canonical = `${os}-${ARCH_ALIASES[arch] ?? arch}`;
+    if (libc === 'musl')
+        return `${canonical}${MUSL_SUFFIX}`;
+    // Not a Linux musl token, so `-musl` (if present at all) is not a libc
+    // suffix this grammar recognises — keep the token intact.
+    return token.endsWith(MUSL_SUFFIX) ? `${canonical}${MUSL_SUFFIX}` : canonical;
+}
+/**
+ * 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 function hostPlatformTokens(platform, arch, libc) {
+    const canonical = `${platform}-${arch}`;
+    // The suffix is Linux-only by construction, so a `libc: 'musl'` handed in
+    // for darwin/win32 is ignored rather than trusted — the caller's host facts
+    // do not get to invent a target the grammar does not have.
+    if (libc === 'musl' && platform === 'linux')
+        return [`${canonical}${MUSL_SUFFIX}`, canonical];
+    return [canonical];
 }
 /**
  * The prebuild directory names to probe for a host, most-specific first.
@@ -95,28 +190,46 @@ export function canonicalPlatformToken(token) {
  * 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 function prebuildDirCandidates(platform, arch, declaredPlatforms) {
-    const canonical = `${platform}-${arch}`;
+export function prebuildDirCandidates(platform, arch, declaredPlatforms, libc) {
+    const hostTokens = hostPlatformTokens(platform, arch, libc);
     const legacyArch = NODE_ARCH_TO_LEGACY_UNAME[arch] ?? arch;
     const out = [];
     const push = (name) => {
         if (!out.includes(name))
             out.push(name);
     };
-    // 1. The package's own declared spelling for THIS host, if it declares one.
-    for (const declared of declaredPlatforms ?? []) {
-        if (typeof declared !== 'string')
-            continue;
-        if (canonicalPlatformToken(declared) === canonical)
-            push(declared);
+    // 1. The package's own declared spelling for each host token, most-specific
+    //    token first. Keyed off the SAME host-token list as step 2, so a musl
+    //    host that finds `linux-x64-musl` in `gjsify.platforms` prefers it over
+    //    a declared `linux-x64` — the declaration probe must not be able to
+    //    reorder the libc preference.
+    for (const token of hostTokens) {
+        for (const declared of declaredPlatforms ?? []) {
+            if (typeof declared !== 'string')
+                continue;
+            if (canonicalPlatformToken(declared) === token)
+                push(declared);
+        }
+        // 2. The canonical node spelling — what everything in the train stages.
+        push(token);
     }
-    // 2. The canonical node spelling — what everything in the train stages.
-    push(canonical);
-    // 3. The legacy uname spelling, for undeclared pre-rename tarballs.
+    // 3. The legacy uname spelling, for undeclared pre-rename tarballs. No musl
+    //    variant: the rename predates the libc axis by years, so no tarball on
+    //    npm can carry a uname-spelled musl directory.
     push(`${platform}-${legacyArch}`);
     return out;
 }
@@ -131,28 +244,59 @@ export function prebuildDirCandidates(platform, arch, declaredPlatforms) {
  * ships nothing loadable on this host.
  */
 export function resolvePrebuildDirName(input) {
-    const { platform, arch, declaredPlatforms, existingDirs } = input;
-    for (const candidate of prebuildDirCandidates(platform, arch, declaredPlatforms)) {
+    const { platform, arch, declaredPlatforms, existingDirs, libc } = input;
+    for (const candidate of prebuildDirCandidates(platform, arch, declaredPlatforms, libc)) {
         if (existingDirs.includes(candidate))
             return candidate;
     }
     return 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 function platformPackageName(baseName, token) {
+    return `${baseName}-${token}`;
+}
 /**
  * Scan all packages in a node_modules directory for gjsify native prebuilds.
  * Handles scoped packages (@scope/name) as well as flat packages.
  */
 function scanNodeModules(nodeModulesDir, target) {
-    const results = [];
+    const resolved = [];
+    const declared = [];
     if (!existsSync(nodeModulesDir))
-        return results;
+        return { resolved, declared };
     let entries;
     try {
         entries = readdirSync(nodeModulesDir);
     }
     catch {
-        return results;
+        return { resolved, declared };
     }
+    const take = (probe) => {
+        if (!probe)
+            return;
+        if (probe.kind === 'resolved')
+            resolved.push(probe.pkg);
+        else
+            declared.push(probe.candidate);
+    };
     for (const entry of entries) {
         if (entry.startsWith('.'))
             continue;
@@ -168,19 +312,15 @@ function scanNodeModules(nodeModulesDir, target) {
             }
             for (const scopedPkg of scopeEntries) {
                 const pkgDir = join(scopeDir, scopedPkg);
-                const native = checkPackage(pkgDir, `${entry}/${scopedPkg}`, target);
-                if (native)
-                    results.push(native);
+                take(checkPackage(pkgDir, `${entry}/${scopedPkg}`, target));
             }
         }
         else {
             const pkgDir = join(nodeModulesDir, entry);
-            const native = checkPackage(pkgDir, entry, target);
-            if (native)
-                results.push(native);
+            take(checkPackage(pkgDir, entry, target));
         }
     }
-    return results;
+    return { resolved, declared };
 }
 /** Check a single package directory for gjsify prebuilds metadata. */
 function checkPackage(pkgDir, name, target) {
@@ -208,17 +348,66 @@ function checkPackage(pkgDir, name, target) {
             .map((e) => e.name);
     }
     catch {
-        return null;
+        // No `prebuilds/` tree at all. Still a DECLARED prebuild package — the
+        // per-platform-package layout puts the binaries in a sibling, so the
+        // absence of a local directory is now a normal state, not an absence of
+        // information.
+        return { kind: 'declared', candidate: { name, pkgDir } };
     }
     const dirName = resolvePrebuildDirName({
         platform: target.platform,
         arch: target.arch,
         declaredPlatforms,
         existingDirs,
+        libc: target.libc,
     });
     if (!dirName)
-        return null;
-    return { name, prebuildsDir: join(prebuildsRoot, dirName) };
+        return { kind: 'declared', candidate: { name, pkgDir } };
+    return { kind: 'resolved', pkg: { name, prebuildsDir: join(prebuildsRoot, dirName) } };
+}
+/**
+ * Find a declared package's prebuild in its PER-PLATFORM COMPANION PACKAGE.
+ *
+ * The heavy bridges are being split the way napi-rs and `@gjsify/gtk-runtime-*`
+ * already are: `@gjsify/rolldown-native` keeps the declaration and the JS facade,
+ * `@gjsify/rolldown-native-linux-x64` carries the binary. `detectNativePackages`
+ * finds such a companion in a HOISTED layout by accident — the up-walk from the
+ * start directory eventually lists it as just another `node_modules` entry — but
+ * NOT in an isolated one, where pnpm places it in the virtual store under the
+ * depending package and no ancestor of the CWD ever contains it.
+ *
+ * So the search starts at the DEPENDING PACKAGE's own directory instead of the
+ * caller's. That is not a second algorithm; it is the SAME up-walk with a
+ * different origin, and the first step of that walk — `<pkgDir>/node_modules/…` —
+ * is the isolated-layout case. It is also exactly what napi-rs achieves
+ * implicitly by calling `require()` from inside the package: Node's resolver
+ * walks up from the requiring FILE, not from the process CWD. We cannot use
+ * `require`/`import.meta.resolve` here because the companion package's `exports`
+ * map need not expose anything importable — the artifact is a directory, not a
+ * module — so the walk is done by hand.
+ *
+ * @returns the companion's own resolved prebuild directory, or null.
+ */
+function resolvePlatformSibling(candidate, target) {
+    const tokens = hostPlatformTokens(target.platform, target.arch, target.libc);
+    let dir = resolve(candidate.pkgDir);
+    while (true) {
+        for (const token of tokens) {
+            const siblingName = platformPackageName(candidate.name, token);
+            const siblingDir = join(dir, 'node_modules', ...siblingName.split('/'));
+            const probe = checkPackage(siblingDir, siblingName, target);
+            // A companion package resolves through the ORDINARY path: it
+            // declares its own `gjsify.prebuilds` + the one target it exists
+            // for. Reusing `checkPackage` is what keeps the split layout from
+            // becoming a second contract nothing audits.
+            if (probe?.kind === 'resolved')
+                return probe.pkg;
+        }
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null; // reached filesystem root
+        dir = parent;
+    }
 }
 /**
  * Walk up the directory tree from `startDir` and merge native packages found
@@ -237,30 +426,117 @@ function checkPackage(pkgDir, name, target) {
  * production call sites take the defaults.
  */
 export function detectNativePackages(startDir, target = {}) {
-    const resolved = {
+    const host = {
         platform: target.platform ?? process.platform,
         arch: target.arch ?? process.arch,
+        // The ONE place the host's libc is read, and only as a default — every
+        // function below takes it as a parameter so the musl branch is reachable
+        // from a glibc test host.
+        //
+        // `!== undefined` rather than `??`: an explicit `libc: null` means "no
+        // libc axis / do not classify", and `??` would treat it as absent and
+        // probe the host anyway — which is the one value a caller passes when it
+        // specifically does NOT want the host consulted.
+        libc: target.libc !== undefined ? target.libc : detectHostLibc(target.platform ?? process.platform),
     };
     const merged = [];
     const seen = new Set();
+    /** Declared-but-unresolved packages, first occurrence wins as above. */
+    const candidates = [];
     let dir = resolve(startDir);
     while (true) {
         const nodeModulesDir = join(dir, 'node_modules');
         if (existsSync(nodeModulesDir)) {
-            for (const pkg of scanNodeModules(nodeModulesDir, resolved)) {
+            const found = scanNodeModules(nodeModulesDir, host);
+            for (const pkg of found.resolved) {
                 if (seen.has(pkg.name))
                     continue;
                 seen.add(pkg.name);
                 merged.push(pkg);
             }
+            for (const candidate of found.declared) {
+                if (candidates.some((c) => c.name === candidate.name))
+                    continue;
+                candidates.push(candidate);
+            }
         }
         const parent = resolve(dir, '..');
         if (parent === dir)
             break; // reached filesystem root
         dir = parent;
     }
+    // Second pass: per-platform companion packages. Runs AFTER the whole walk so
+    // it can dedupe against everything the walk found — in a hoisted layout the
+    // companion is already in `merged` under its own name (the walk lists it like
+    // any other package), and adding it twice would put the same directory on
+    // `GI_TYPELIB_PATH` twice for no benefit. It also cannot ADD a name that a
+    // closer `node_modules` already resolved, which keeps Node's
+    // nearest-wins semantics intact.
+    for (const candidate of candidates) {
+        if (seen.has(candidate.name))
+            continue;
+        const sibling = resolvePlatformSibling(candidate, host);
+        if (!sibling || seen.has(sibling.name))
+            continue;
+        seen.add(sibling.name);
+        merged.push(sibling);
+    }
     return merged;
 }
+/**
+ * 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 function resolveHostLibc(input) {
+    if (input.platform !== 'linux')
+        return null;
+    if (typeof input.glibcVersionRuntime === 'string' && input.glibcVersionRuntime.length > 0)
+        return 'glibc';
+    return input.muslLoaderPresent ? 'musl' : 'glibc';
+}
+/**
+ * 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 function detectHostLibc(platform) {
+    if (platform !== 'linux')
+        return null;
+    const header = process.report?.getReport()?.header;
+    const glibcVersionRuntime = typeof header?.glibcVersionRuntime === 'string' ? header.glibcVersionRuntime : undefined;
+    // Read the directory rather than testing per-arch loader names: those names
+    // (`ld-musl-x86_64`, `ld-musl-aarch64`, …) are a THIRD arch vocabulary, and
+    // this file already documents why the repo keeps exactly one.
+    const muslLoaderPresent = existsSync('/lib') && readdirSync('/lib').some((f) => f.startsWith('ld-musl-'));
+    return resolveHostLibc({ platform, glibcVersionRuntime, muslLoaderPresent });
+}
 /**
  * The environment-variable name the host's dynamic loader consults for an
  * additional shared-library search path, plus the separator its search paths

package/lib/utils/dir-link.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Which kind of directory link this platform uses.
+ *
+ * Spelled with a NAME for the POSIX case rather than `undefined`, so both
+ * branches can be requested explicitly. `dirLinkTarget` takes this as a
+ * defaulted parameter, and a defaulted parameter cannot receive `undefined`:
+ * passing it IS how you ask for the default. So while POSIX was spelled
+ * `undefined`, `dirLinkTarget(link, target, undefined)` meant "use the host's
+ * kind" — the POSIX branch was unexercisable on Windows, and the win32 branch
+ * unexercisable anywhere else. The suite read as if it covered both and did
+ * not, which is precisely the shape the header above blames for the `'dir'`
+ * bug reaching a release.
+ */
+export type DirLinkKind = 'junction' | 'symlink';
+/** The link kind directory links use on this platform. */
+export declare const DIR_LINK_KIND: DirLinkKind;
+/**
+ * The link type a directory link must pass to `fs.symlink`.
+ *
+ * `undefined` on POSIX is deliberate: Node's default is correct there, and
+ * passing a type would be noise. Derived from {@link DIR_LINK_KIND} so the
+ * platform decision has exactly one source.
+ */
+export declare const DIR_LINK_TYPE: 'junction' | undefined;
+/** True when directory links on this platform are NTFS junctions. */
+export declare const dirLinksAreJunctions: () => boolean;
+/**
+ * Spell the `target` argument for a link at `linkPath` pointing at `absTarget`.
+ *
+ * Absolute on Windows because a junction demands it (gotcha 1 above); relative
+ * on POSIX so the tree stays movable (gotcha 2).
+ *
+ * `linkKind` is a PARAMETER, defaulting to the host's, for the same reason
+ * `detect-native-packages.ts` takes `platform`/`arch`: the Windows branch is
+ * then unit-testable from a Linux host, which is the only place anyone runs the
+ * tests. A branch nobody can exercise is how the `'dir'` bug survived to a
+ * release — and see {@link DirLinkKind} for why the POSIX side had to be named
+ * rather than spelled `undefined` before that promise actually held.
+ *
+ * BOTH paths must be in the SAME canonical space — either both canonical or
+ * both spelled through the same symlinks. The POSIX target is relative to the
+ * link's own directory, but the kernel resolves it from the link's REAL
+ * directory, so mixing the two spaces yields a link that points nowhere. macOS
+ * is where this actually happens: `os.tmpdir()` is `/var/folders/…` and `/var`
+ * is a symlink to `/private/var`, so a `linkPath` built from `tmpdir()` and an
+ * `absTarget` that has been through `realpathSync` disagree, and the relative
+ * path between them walks out of the real tree. `realpathSync` whichever side
+ * is not already canonical before calling this.
+ *
+ * @param linkPath  where the link itself will live
+ * @param absTarget the directory it should point at, as an ABSOLUTE path
+ * @param linkKind  override the host's link kind (tests only)
+ */
+export declare function dirLinkTarget(linkPath: string, absTarget: string, linkKind?: DirLinkKind): string;
+/**
+ * Link `linkPath` → `absTarget`, choosing symlink-vs-junction and the target
+ * spelling for the host.
+ *
+ * `absTarget` must be absolute; passing a relative path is the mistake gotcha 1
+ * describes, and it would only misbehave on Windows, so it is rejected here on
+ * every platform rather than left to surface on the one host nobody tests on.
+ */
+export declare function linkDirSync(linkPath: string, absTarget: string): void;
+/** Promise-returning twin of {@link linkDirSync}. */
+export declare function linkDir(linkPath: string, absTarget: string): Promise<void>;
+/**
+ * Recreate an EXISTING link at a new path, preserving what it points at.
+ *
+ * A different job from {@link linkDirSync}, and it cannot reuse it: the source
+ * link's target is whatever it already is — frequently relative, deliberately so
+ * — while a junction demands an absolute one. Copying the target verbatim is
+ * therefore right on POSIX and wrong on Windows the moment the target is a
+ * directory.
+ *
+ * So the target's KIND decides: a link to a directory becomes a junction with
+ * the target resolved against the source link's own directory (the resolution
+ * Node will not do for you — see gotcha 1 above); anything else stays a plain
+ * file symlink, which Windows allows unprivileged.
+ *
+ * A dangling source link keeps the verbatim target: it points nowhere either
+ * way, and guessing a kind for it would turn a faithful copy into a fabrication.
+ *
+ * Primitive fs ops only — this runs under the GJS facade as well as Node, which
+ * is why there is no `fs.cp`/`opendir` here.
+ */
+export declare function replicateLinkSync(srcLink: string, dstLink: string): void;