@gjsify/cli 0.36.0 → 0.38.0

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

@@ -1,44 +1,37 @@
-// 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>[-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.
+// Find npm packages carrying gjsify native prebuilds. Packages declare
+// `"gjsify": { "prebuilds": "<dir>" }` plus the `<os>-<arch>[-musl]` targets they
+// promise in `"gjsify": { "platforms": [...] }`. This file only resolves
+// DIRECTORIES — 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).
 //
-// 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:
+// TWO passes. `detectNativePackages(startDir)` walks up from `startDir` scanning
+// every `node_modules`, then resolves any package that DECLARED a prebuild without
+// shipping one through its per-platform companion (`<name>-<token>`), searching
+// from THAT package's own directory (`resolvePlatformSibling`). The second pass
+// exists because the first cannot see an isolated (pnpm-style) layout. Call sites:
 //   * `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
-//     their full transitive prebuild set picked up automatically. The
-//     transitive walk is what makes `gjsify showcase` / `gjsify dlx` work
-//     for packages whose Vala typelibs live in *indirect* deps.
+//   * `runGjsBundle()` — startDir = dirname(bundlePath), so DLX-cache layouts pick
+//     up their full transitive prebuild set. That transitive walk is what makes
+//     `gjsify showcase` / `gjsify dlx` work for packages whose Vala typelibs live
+//     in *indirect* deps.
 //
-// PLATFORM RESOLUTION IS A PURE FUNCTION. Everything that depends on the host
-// 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.
+// PLATFORM RESOLUTION IS A PURE FUNCTION: `resolvePrebuildDirName()`,
+// `buildNativeEnv()` and `resolveHostLibc()` take `platform`/`arch`/`libc` as
+// parameters instead of reading `process.*` inline, which is what makes the darwin,
+// win32 AND musl branches unit-testable from a glibc Linux host. The host values
+// are read only 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';
-import { splitSearchPath, systemGiLibraryDirs } from './system-gi.js';
+import { composeDyldFallback, 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
- * `uname -m` on the build host).
- *
- * LEGACY. Every `@gjsify/*` package now declares and stages the node spelling
- * (`linux-x64`); this table exists only so the CLI can still load a prebuild
- * out of a tarball published before the rename. See
- * {@link prebuildDirCandidates}.
+ * Node `process.arch` → the uname-style spelling the Vala/meson bridges used to stage
+ * into (`prebuilds/linux-x86_64/`).
+ *
+ * LEGACY: every `@gjsify/*` package now stages the node spelling (`linux-x64`), and
+ * this table exists only so the CLI can still load a prebuild out of a tarball
+ * published before the rename. See {@link prebuildDirCandidates}.
  */
 const NODE_ARCH_TO_LEGACY_UNAME = {
     x64: 'x86_64',
@@ -47,16 +40,14 @@ const NODE_ARCH_TO_LEGACY_UNAME = {
     ia32: 'i686',
 };
 /**
- * Arch spellings that name the same target, folded onto the NODE spelling.
- * 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
- * host identity never has to be translated in the hot path.
+ * Arch spellings that name the same target, folded onto the NODE spelling. MUST agree
+ * with `ARCH_ALIASES` in `packages/infra/manifest-conformance/lib/platforms.mjs` (what
+ * `scripts/audit-runtimes.mjs` canonicalises `gjsify.platforms` through), or a package
+ * passes 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 host identity is
+ * never translated in the hot path.
  */
 const ARCH_ALIASES = {
     x86_64: 'x64',
@@ -70,35 +61,27 @@ const ARCH_ALIASES = {
  */
 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.
+ * Split a prebuild target into its three axes. TOKEN GRAMMAR: `<os>-<arch>[-musl]`.
+ *
+ * An UNSUFFIXED token means "the default build", NOT a synonym for glibc. For an
+ * artifact linking `libc.so.6` the default build IS glibc; for one linking only
+ * GLib/GObject/GIO it is libc-AGNOSTIC and loads against whatever libc the host's GLib
+ * was built for. The directory name cannot express that and does not need to — the
+ * package's own `libc` field answers it at install time, verified against the binaries'
+ * DT_NEEDED list by the `prebuild-libc` conformance rule.
+ *
+ * DELIBERATELY NOT CHOSEN: the symmetric grammar, renaming every `linux-<arch>` to
+ * `linux-<arch>-gnu`. That is ~60 committed directories plus nine e2e fixtures that
+ * COMPOSE the token instead of importing it (open-todos: "Nine fixtures re-implement
+ * the prebuild-target name instead of importing it"), so the sweep would have to be
+ * done 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 is equally expressive for zero renames.
+ *
+ * A `-musl` suffix is only meaningful when the OS half is `linux`: musl targets no
+ * other kernel and npm's `libc` field is documented Linux-only. `darwin-arm64-musl` is
+ * therefore malformed rather than oddly named, and this returns `libc: null` for it so
+ * callers report the token instead of half-honouring it.
  */
 export function parsePlatformToken(token) {
     const isMusl = token.endsWith(MUSL_SUFFIX);
@@ -109,17 +92,15 @@ export function parsePlatformToken(token) {
     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.
+ * Canonical `<os>-<arch>[-musl]` (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 with no competing spelling, and the libc half has exactly
+ * one spelling by construction.
+ *
+ * A `-musl` suffix on a non-Linux token is preserved 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.
  */
 export function canonicalPlatformToken(token) {
     const { os, arch, libc } = parsePlatformToken(token);
@@ -128,37 +109,30 @@ export function canonicalPlatformToken(token) {
     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.
+    // Not a Linux musl token, so any `-musl` here 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).
+ * The target tokens describing THIS host, most-specific first — the WRITE-side
+ * vocabulary, and the SINGLE definition of the musl preference order. Three callers
+ * share it so it cannot drift: the directory probe ({@link prebuildDirCandidates}), the
+ * companion-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 with the unsuffixed one as fallback,
+ * because an unsuffixed directory is the default build and the libc-agnostic bridges
+ * (no `libc.so.6` recorded at all) genuinely do 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 produce a false positive.
+ *
+ * @param libc `undefined`/`null` behaves as glibc — see {@link HostTarget.libc}.
  */
 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.
+    // 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];
@@ -166,44 +140,34 @@ export function hostPlatformTokens(platform, arch, libc) {
 /**
  * The prebuild directory names to probe for a host, most-specific first.
  *
- * The canonical name is `${process.platform}-${process.arch}` — `linux-x64`,
- * `linux-arm64`, `darwin-arm64`, `win32-x64`. Every package in the release
- * train declares it (`gjsify.platforms`), `scripts/stage-prebuild.mjs` is the
- * only thing that creates it, and `scripts/audit-runtimes.mjs --check` rejects
- * any other spelling, so the three can no longer drift.
- *
- * Two probes remain BEHIND that canonical name, and both are backward
- * compatibility with tarballs already on npm — not a second convention:
- *
- *   1. **The package's own declared spelling.** A tarball published before the
- *      rename declares (and ships) `linux-x86_64`; probing its declaration
- *      first loads it without the CLI having to guess. This is also what makes
- *      the rename work in the OTHER direction — an older CLI resolving a newer
- *      package — because `canonicalPlatformToken` folds both spellings onto
- *      one form at both ends.
- *   2. **The legacy uname spelling.** Only reachable for a package that ships
- *      a prebuild dir and declares NO `gjsify.platforms` at all — i.e. a
- *      tarball predating the OS-axis audit, or a third-party package using
- *      `gjsify.prebuilds` without the declaration. Inside this repo the audit
- *      makes that state impossible.
- *
- * Both are pure array entries matched against an already-read directory
- * 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.
+ * The canonical name is `${process.platform}-${process.arch}`. Every package in the
+ * release train declares it (`gjsify.platforms`), `scripts/stage-prebuild.mjs` is the
+ * only thing that creates it, and `scripts/audit-runtimes.mjs --check` rejects any
+ * other spelling, so the three cannot drift.
+ *
+ * Two probes sit BEHIND it, both backward compatibility with tarballs already on npm
+ * rather than a second convention:
+ *
+ *   1. **The package's own declared spelling.** A pre-rename tarball declares and
+ *      ships `linux-x86_64`, so probing its declaration first loads it without
+ *      guessing. This is also what makes the rename work in the OTHER direction (an
+ *      older CLI, a newer package), since `canonicalPlatformToken` folds both
+ *      spellings onto one form at both ends.
+ *   2. **The legacy uname spelling.** Only reachable for a package that ships a
+ *      prebuild dir and declares NO `gjsify.platforms` — a tarball predating the
+ *      OS-axis audit, or a third-party package. The audit makes that state impossible
+ *      inside this repo.
+ *
+ * Both are array entries matched against an already-read directory listing, so
+ * tolerance on the READ side costs no I/O while the single spelling stays enforced
+ * everywhere a name is WRITTEN.
+ *
+ * The LIBC AXIS rides in front of all of it (see {@link hostPlatformTokens}). `libc` is
+ * a PARAMETER rather than a `process` read for the same reason `platform` and `arch`
+ * are: it is the only way the musl branch is exercised at all, since CI and every
+ * developer machine here run glibc.
+ *
  * @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, libc) {
     const hostTokens = hostPlatformTokens(platform, arch, libc);
@@ -213,10 +177,8 @@ export function prebuildDirCandidates(platform, arch, declaredPlatforms, libc) {
         if (!out.includes(name))
             out.push(name);
     };
-    // 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
+    // 1. The package's own declared spelling per host token, most-specific first. Keyed
+    //    off the SAME host-token list as step 2, so the declaration probe cannot
     //    reorder the libc preference.
     for (const token of hostTokens) {
         for (const declared of declaredPlatforms ?? []) {
@@ -605,12 +567,12 @@ const DYLD_FALLBACK_VAR = 'DYLD_FALLBACK_LIBRARY_PATH';
  *      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.
+ *   2. **Our dirs go FIRST, an inherited fallback behind them, and dyld's own
+ *      default list behind that** — `composeDyldFallback()`, the same
+ *      composition node-gi's re-exec uses. Setting the variable REPLACES that
+ *      default list rather than extending it, so any composition that does not
+ *      carry it hands the child a SMALLER search path than it would have had
+ *      with the variable unset.
  *
  * 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
@@ -641,19 +603,7 @@ export function buildNativeEnv(packages, opts = {}) {
     // 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]);
-        // Deduplicated, and not for tidiness: `systemGiLibraryDirs()` accepts a
-        // libdir stated outright through `GI_TYPELIB_PATH` on directory
-        // existence alone, so a host that names `/usr/lib/girepository-1.0`
-        // there puts `/usr/lib` in `systemDirs` — and the `/usr/lib` tail below
-        // then repeated it. A search path that lists the same directory twice
-        // asks the loader to stat it twice for every miss, and it makes the
-        // value the `$ …` echo prints read as though the CLI had composed
-        // something it did not. First occurrence wins in every loader, so
-        // dropping later repeats is behaviour-preserving.
-        out[DYLD_FALLBACK_VAR] = [
-            ...new Set([...systemDirs, ...(inherited.length > 0 ? inherited : ['/usr/lib'])]),
-        ].join(':');
+        out[DYLD_FALLBACK_VAR] = composeDyldFallback(systemDirs, env);
     }
     return out;
 }

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

@@ -1,24 +1,18 @@
 /**
  * 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.
+ * The POSIX case is spelled with a NAME rather than `undefined` so both branches
+ * stay explicitly requestable: `dirLinkTarget` takes this as a DEFAULTED
+ * parameter, and a defaulted parameter cannot receive `undefined` — passing it IS
+ * how you ask for the host's kind. Spelled `undefined`, each branch was
+ * unexercisable off its own platform while the suite read as if it covered both.
  */
 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
+ * The link type a directory link must pass to `fs.symlink` — `undefined` on POSIX,
+ * where Node's default is correct. Derived from {@link DIR_LINK_KIND} so the
  * platform decision has exactly one source.
  */
 export declare const DIR_LINK_TYPE: 'junction' | undefined;
@@ -31,34 +25,26 @@ export declare const dirLinksAreJunctions: () => boolean;
  * 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.
+ * `detect-native-packages.ts` takes `platform`/`arch`: the Windows branch is then
+ * unit-testable from a Linux host, the only place anyone runs the tests.
  *
- * 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.
+ * BOTH paths must be in the SAME canonical space. 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 yields a link pointing nowhere. macOS is where this
+ * bites: `os.tmpdir()` is `/var/folders/…` and `/var` is a symlink to
+ * `/private/var`, so a `linkPath` from `tmpdir()` and an `absTarget` that went
+ * through `realpathSync` disagree and the relative path between them walks out of
+ * the real tree. `realpathSync` whichever side is not already canonical.
  *
- * @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.
+ * spelling for the host. A relative `absTarget` is gotcha 1 and would only misbehave
+ * on Windows, so it is rejected 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}. */
@@ -66,21 +52,16 @@ export declare function linkDir(linkPath: string, absTarget: string): Promise<vo
 /**
  * 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.
+ * Cannot reuse {@link linkDirSync}: the source link's target is whatever it
+ * already is — frequently relative, deliberately so — while a junction demands an
+ * absolute one, so copying verbatim is right on POSIX and wrong on Windows the
+ * moment the target is a directory. The target's KIND therefore decides: a link to
+ * a directory becomes a junction with the target resolved against the source
+ * link's own directory (gotcha 1); anything else stays a plain file symlink, which
+ * Windows allows unprivileged. A dangling source link keeps the verbatim target —
+ * 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.
+ * Primitive fs ops only: this runs under the GJS facade as well as Node, hence no
+ * `fs.cp`/`opendir`.
  */
 export declare function replicateLinkSync(srcLink: string, dstLink: string): void;