@gjsify/cli 0.26.0 → 0.27.0

package/lib/utils/dir-link.js

@@ -0,0 +1,140 @@
+// Creating a link to a DIRECTORY, portably.
+//
+// WHY THIS FILE EXISTS. Windows cannot create a directory *symlink* without
+// elevation or Developer Mode — the call fails with `EPERM` — but any user can
+// create an NTFS **junction**, which is why npm, yarn and pnpm all use junctions
+// for directory links. `commands/install.ts` learned that and encoded it, twice,
+// as a local constant for its workspace links. Nothing shared it, so the next
+// site to link a directory got it wrong: `dlx-cache.ts` linked with `'dir'` and
+// every non-elevated Windows user hit
+//
+//     Could not resolve showcase "canvas2d-fireworks": EPERM: operation not
+//     permitted, symlink '…\<prepare-dir>' -> '…\pkg.tmp-…'
+//
+// on a plain `npx @gjsify/cli@latest showcase …`. The knowledge existed in the
+// repo and the bug shipped anyway, which is the argument for a single callable
+// definition rather than a convention.
+//
+// THE TWO GOTCHAS, both load-bearing:
+//
+//  1. **A junction target must be ABSOLUTE.** Node normalises a `'junction'`
+//     target with `path.resolve()` — against the process CWD, NOT against the
+//     link's own directory. A relative target that looks right produces a
+//     junction pointing somewhere else entirely, and only on Windows.
+//  2. **POSIX targets should stay RELATIVE** where the caller wants a movable
+//     tree: a relative symlink survives the whole tree being moved or mounted
+//     elsewhere. So the target spelling is per-platform, not one string.
+//
+// Autodetection is NOT a substitute. Node picks `'file'` or `'dir'` when the
+// type argument is omitted — never `'junction'` — so an omitted type is the
+// failing case, not the safe default.
+import { readlinkSync, statSync, symlinkSync } from 'node:fs';
+import { symlink } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+/** The link kind directory links use on this platform. */
+export const DIR_LINK_KIND = process.platform === 'win32' ? 'junction' : 'symlink';
+/**
+ * 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 const DIR_LINK_TYPE = DIR_LINK_KIND === 'junction' ? 'junction' : undefined;
+/** True when directory links on this platform are NTFS junctions. */
+export const dirLinksAreJunctions = () => DIR_LINK_KIND === 'junction';
+/**
+ * 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 function dirLinkTarget(linkPath, absTarget, linkKind = DIR_LINK_KIND) {
+    return linkKind === 'junction' ? resolve(absTarget) : relative(dirname(linkPath), absTarget);
+}
+/**
+ * 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 function linkDirSync(linkPath, absTarget) {
+    assertAbsolute(absTarget);
+    symlinkSync(dirLinkTarget(linkPath, absTarget), linkPath, DIR_LINK_TYPE);
+}
+/** Promise-returning twin of {@link linkDirSync}. */
+export async function linkDir(linkPath, absTarget) {
+    assertAbsolute(absTarget);
+    await symlink(dirLinkTarget(linkPath, absTarget), linkPath, DIR_LINK_TYPE);
+}
+/**
+ * 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 function replicateLinkSync(srcLink, dstLink) {
+    const rawTarget = readlinkSync(srcLink);
+    if (!dirLinksAreJunctions()) {
+        symlinkSync(rawTarget, dstLink);
+        return;
+    }
+    const resolvedTarget = resolve(dirname(srcLink), rawTarget);
+    let targetIsDir;
+    try {
+        targetIsDir = statSync(resolvedTarget).isDirectory();
+    }
+    catch {
+        // Dangling — copy it as-is rather than inventing a kind for it.
+        symlinkSync(rawTarget, dstLink);
+        return;
+    }
+    if (targetIsDir)
+        symlinkSync(resolvedTarget, dstLink, 'junction');
+    else
+        symlinkSync(rawTarget, dstLink, 'file');
+}
+function assertAbsolute(absTarget) {
+    if (resolve(absTarget) !== absTarget) {
+        throw new TypeError(`linkDir: target must be an absolute path, got ${JSON.stringify(absTarget)}. ` +
+            'Node resolves a Windows junction target against the process CWD rather than the ' +
+            "link's own directory, so a relative target silently points somewhere else there.");
+    }
+}

package/lib/utils/dlx-cache.d.ts

@@ -20,13 +20,40 @@ export declare function getValidCachedPkg(cacheDir: string, maxAgeMinutes?: numb
  * Atomically swap `<cacheDir>/pkg` to point at `prepareDir`.
  *
  * Strategy:
- *   1. Create new symlink `<cacheDir>/pkg-<rand>` → prepareDir.
- *   2. `rename(pkg-<rand>, pkg)` — POSIX guarantees rename-over-existing is atomic.
+ *   1. Create new link `<cacheDir>/pkg.tmp-<ts>-<pid>` → prepareDir.
+ *   2. `rename(pkg.tmp-…, pkg)` — POSIX guarantees rename-over-existing is atomic.
  *
  * Returns the realpath of the new live target. EBUSY/EEXIST indicates a race
  * — a parallel process won, return its realpath.
+ *
+ * WINDOWS, both halves of which shipped broken:
+ *
+ *   • Step 1 used `symlinkSync(…, 'dir')`, and a directory SYMLINK needs
+ *     elevation or Developer Mode there, so a plain
+ *     `npx @gjsify/cli@latest showcase …` died with `EPERM: operation not
+ *     permitted, symlink`. It now goes through {@link linkDirSync}, which picks
+ *     an NTFS junction — the same choice npm and yarn make, and the one
+ *     `commands/install.ts` already made for workspace links without sharing it.
+ *   • Step 2's rename-over-existing is a POSIX guarantee, not a Windows one:
+ *     `MoveFileEx` will not replace an existing DIRECTORY, and a junction is a
+ *     directory reparse point. So on the second run — when `pkg` already exists
+ *     — the rename failed with `EPERM`, the catch below read that as "race
+ *     lost", and the function returned the OLD target. That is not a crash but
+ *     it is worse than one: the cache silently never refreshed. Windows
+ *     therefore unlinks first and accepts the non-atomic window, which the
+ *     existing race handling already covers.
+ *
+ * @param opts.junctions force the Windows link strategy (TESTS ONLY). Defaults
+ *   to the host's. It is a parameter for the same reason `dirLinkTarget` takes
+ *   `linkType`: nothing in CI runs on Windows, so an injected `true` is the ONLY
+ *   way the unlink-then-rename ordering above is ever EXECUTED, and an
+ *   unexecutable Windows branch is exactly how the `'dir'` bug shipped. What the
+ *   injection proves off-host is the ORDERING and that the second swap really
+ *   refreshes; what it cannot prove is `MoveFileEx`/junction syscall behaviour.
  */
-export declare function symlinkSwap(cacheDir: string, prepareDir: string): string;
+export declare function symlinkSwap(cacheDir: string, prepareDir: string, opts?: {
+    junctions?: boolean;
+}): string;
 /** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
 export declare function cleanupStalePrepareDirs(cacheDir: string, _maxAgeMinutes?: number): void;
 /** Resolve absolute path to the installed package's directory inside cache. */

package/lib/utils/dlx-cache.js

@@ -6,9 +6,10 @@
 //   - prepare into a fresh temp dir, then atomically swap a `pkg` symlink
 //   - TTL via lstat mtime + maxAgeMinutes (default 7 days)
 import { createHash } from 'node:crypto';
-import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync, symlinkSync } from 'node:fs';
+import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
+import { dirLinksAreJunctions, linkDirSync } from './dir-link.js';
 const ONE_MINUTE_MS = 60_000;
 const DEFAULT_TTL_MIN = 60 * 24 * 7; // 7 days
 function lexCompare(a, b) {
@@ -74,29 +75,82 @@ export function getValidCachedPkg(cacheDir, maxAgeMinutes = DEFAULT_TTL_MIN) {
  * Atomically swap `<cacheDir>/pkg` to point at `prepareDir`.
  *
  * Strategy:
- *   1. Create new symlink `<cacheDir>/pkg-<rand>` → prepareDir.
- *   2. `rename(pkg-<rand>, pkg)` — POSIX guarantees rename-over-existing is atomic.
+ *   1. Create new link `<cacheDir>/pkg.tmp-<ts>-<pid>` → prepareDir.
+ *   2. `rename(pkg.tmp-…, pkg)` — POSIX guarantees rename-over-existing is atomic.
  *
  * Returns the realpath of the new live target. EBUSY/EEXIST indicates a race
  * — a parallel process won, return its realpath.
+ *
+ * WINDOWS, both halves of which shipped broken:
+ *
+ *   • Step 1 used `symlinkSync(…, 'dir')`, and a directory SYMLINK needs
+ *     elevation or Developer Mode there, so a plain
+ *     `npx @gjsify/cli@latest showcase …` died with `EPERM: operation not
+ *     permitted, symlink`. It now goes through {@link linkDirSync}, which picks
+ *     an NTFS junction — the same choice npm and yarn make, and the one
+ *     `commands/install.ts` already made for workspace links without sharing it.
+ *   • Step 2's rename-over-existing is a POSIX guarantee, not a Windows one:
+ *     `MoveFileEx` will not replace an existing DIRECTORY, and a junction is a
+ *     directory reparse point. So on the second run — when `pkg` already exists
+ *     — the rename failed with `EPERM`, the catch below read that as "race
+ *     lost", and the function returned the OLD target. That is not a crash but
+ *     it is worse than one: the cache silently never refreshed. Windows
+ *     therefore unlinks first and accepts the non-atomic window, which the
+ *     existing race handling already covers.
+ *
+ * @param opts.junctions force the Windows link strategy (TESTS ONLY). Defaults
+ *   to the host's. It is a parameter for the same reason `dirLinkTarget` takes
+ *   `linkType`: nothing in CI runs on Windows, so an injected `true` is the ONLY
+ *   way the unlink-then-rename ordering above is ever EXECUTED, and an
+ *   unexecutable Windows branch is exactly how the `'dir'` bug shipped. What the
+ *   injection proves off-host is the ORDERING and that the second swap really
+ *   refreshes; what it cannot prove is `MoveFileEx`/junction syscall behaviour.
  */
-export function symlinkSwap(cacheDir, prepareDir) {
+export function symlinkSwap(cacheDir, prepareDir, opts = {}) {
+    const junctions = opts.junctions ?? dirLinksAreJunctions();
     const linkPath = join(cacheDir, 'pkg');
     const tmpName = `pkg.tmp-${Date.now().toString(16)}-${process.pid.toString(16)}`;
     const tmpLink = join(cacheDir, tmpName);
     // If we cannot even create the tmp link, give up (the error propagates).
-    symlinkSync(prepareDir, tmpLink, 'dir');
+    linkDirSync(tmpLink, prepareDir);
     try {
+        if (junctions) {
+            // Windows: no rename-over-a-directory. Removing first opens a window
+            // in which `pkg` is absent; a concurrent reader treats that as a cache
+            // miss and prepares its own, which is correct, just wasteful. force:true
+            // keeps a first-ever swap (nothing to remove) from throwing.
+            //
+            // maxRetries/retryDelay for the same reason `install-backend-native.ts`
+            // wraps every delete in `rmWithRetry`: on Windows a delete fails with
+            // EBUSY/EPERM while ANY process holds a handle (an antivirus scan, a
+            // concurrent reader that just realpath'd this very link), and the
+            // deletion then stays PENDING — so without the retry a transient
+            // handle sends us down the "race lost" branch and the cache silently
+            // does not refresh. Free on POSIX, where the first attempt succeeds.
+            rmSync(linkPath, { force: true, recursive: false, maxRetries: 10, retryDelay: 100 });
+        }
         renameSync(tmpLink, linkPath);
     }
     catch (err) {
         const code = err.code;
-        if (code === 'EBUSY' || code === 'EPERM' || code === 'EEXIST') {
+        if (code === 'EBUSY' || code === 'EPERM' || code === 'EEXIST' || code === 'EACCES') {
             // Race lost — clean up our tmp and use whoever won. force:true is
             // the non-throwing spelling of "remove if still there"; any other
             // failure on our own pid-unique link is real and should surface.
             rmSync(tmpLink, { force: true });
-            return realpathSync(linkPath);
+            try {
+                return realpathSync(linkPath);
+            }
+            catch {
+                // Windows only, and only because the junction path unlinks before
+                // it renames: "race lost" can also mean the winner is INSIDE that
+                // non-atomic window, so `pkg` momentarily does not exist and this
+                // would throw ENOENT out of a function whose caller reports it to
+                // the user as `Could not resolve showcase "<name>"`. Our own
+                // prepareDir is a complete, correctly installed tree — a truthful
+                // answer for THIS run. The next run reads whichever link won.
+                return realpathSync(prepareDir);
+            }
         }
         throw err;
     }

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

@@ -1,5 +1,6 @@
 import { type Packument } from '@gjsify/npm-registry';
 import type { InstallOptions } from './install-backend.ts';
+import { type PlatformDeclaration, type PlatformTarget } from './platform-check.js';
 interface ParsedSpec {
     name: string;
     range: string;
@@ -19,12 +20,105 @@ interface ResolvedNode {
     /** `optionalDependencies` field from the packument. */
     optionalDependencies: Record<string, string>;
     bin?: string | Record<string, string>;
+    /**
+     * The version's `os`/`cpu`/`libc` declaration, as published. Recorded on the
+     * node (and in the lockfile) so the compatibility VERDICT can be recomputed
+     * for whichever host runs the install — see the header note on portability.
+     *
+     * Read from the FULL packument, which is the only document that carries
+     * `libc`. That is not an optimisation detail leaking into a comment: the
+     * abbreviated document can never PROVE the absence of a `libc` restriction,
+     * so a declaration built from it would be silently incomplete for exactly
+     * the packages the field exists for (this repo publishes nine of them —
+     * `@gjsify/{rolldown,lightningcss,oxfmt}-native`, `webgl`, `napi`,
+     * `sab-native`, `terminal-native`, `http2-native`, `http-soup-bridge` all
+     * declare `libc: ["glibc"]` and NO `os`/`cpu`).
+     */
+    platform?: PlatformDeclaration;
+    /**
+     * Is this node reachable ONLY through optionalDependency edges? Decides what
+     * an incompatible platform means: skip silently (optional) vs. fail the
+     * install (required). npm calls the same set `optionalSet`.
+     *
+     * DERIVED, not an input — {@link computeOptionalFlags} recomputes it as a
+     * fixpoint over the placed graph before anything reads it, on the fresh-
+     * resolve AND the lockfile path. The value the BFS assigns at placement time
+     * is a forward guess used only to decide whether a resolve FAILURE under this
+     * node is tolerated; it is edge-order-dependent and must never be the final
+     * answer (header note, invariant 2).
+     *
+     * OPTIONAL FIELD, and absent must read as `false` (= required): nodes are
+     * also built structurally by callers that only care about name/installPath,
+     * and the safe default for an unknown edge kind is the loud one — a required
+     * incompatible dependency fails the install instead of being silently
+     * dropped from the tree.
+     */
+    optional?: boolean;
+    /**
+     * Set by {@link applyPlatformFilter}: this node cannot run on the install
+     * target, so it is not downloaded or extracted. Never persisted — it is a
+     * per-host verdict, not a property of the resolution.
+     */
+    inert?: boolean;
 }
 export interface InstalledTopLevel {
     name: string;
     version: string;
 }
-export declare function installPackagesNative(opts: InstallOptions): Promise<InstalledTopLevel[]>;
+/**
+ * {@link InstallOptions} plus what only the NATIVE backend can use.
+ *
+ * `optionalSpecs` exists because a spec is a flat `"<name>@<range>"` string by
+ * the time it reaches here — `projectSpecsFromPackageJson` flattens
+ * `dependencies`, `devDependencies` and `optionalDependencies` into one list —
+ * yet the KIND decides what an incompatible `os`/`cpu`/`libc` means: an optional
+ * dependency is skipped, a required one fails the install. The shape that makes
+ * this concrete is `optionalDependencies: { fsevents }` in a project's own
+ * manifest: on Linux npm leaves fsevents out and installs fine, so treating
+ * every top-level spec as required would turn that into a hard EBADPLATFORM for
+ * a package nothing on the host would ever load.
+ *
+ * It rides the SAME options object `install-backend.ts` forwards wholesale to
+ * this function. If that forwarding is ever changed to destructure, this field
+ * must be forwarded with it — otherwise top-level optional deps quietly become
+ * required again (and the `install-platform-filter` e2e goes red, which is where
+ * that assumption is pinned).
+ */
+export interface NativeInstallOptions extends InstallOptions {
+    /**
+     * Names (not spec strings — the range differs per requester) of top-level
+     * specs declared as `optionalDependencies`. Absent ⇒ every top-level spec is
+     * required, the pre-platform-filter behaviour.
+     */
+    optionalSpecs?: Set<string>;
+}
+export declare function installPackagesNative(opts: NativeInstallOptions): Promise<InstalledTopLevel[]>;
+/**
+ * Split a resolved tree into what THIS target can install, marking the rest
+ * inert. Mirrors arborist's post-resolve platform pass
+ * (`refs/npm-cli/workspaces/arborist/lib/arborist/build-ideal-tree.js`, the
+ * `checkPlatform` loop around line 210) rather than filtering during the walk,
+ * for two reasons: the verdict must be identical whether the tree came from a
+ * fresh resolve or from `gjsify-lock.json`, and a node's optionality is only
+ * final once every edge that could reach it has been visited.
+ *
+ * The two outcomes are npm's, including the asymmetry around `force`:
+ *   - REQUIRED + incompatible → EBADPLATFORM. A required dependency the host
+ *     cannot run is a broken install, not a smaller one; failing loudly with
+ *     `pkgid`/`current`/`required` is the only honest answer. `--force`
+ *     suppresses it (the user is asserting something about their own machine).
+ *   - OPTIONAL + incompatible → inert: not downloaded, not extracted, still in
+ *     the lockfile. `--force` does NOT lift this — npm says so in as many words
+ *     ("We ignore the --force and --engine-strict flags") and it is right:
+ *     forcing an optional binary that cannot load buys a download and nothing
+ *     else.
+ *
+ * The skip line goes through the debug logger with npm's `current`/`required`
+ * payload, so `--verbose` recovers exactly WHY a package is absent. Silence
+ * here is what made the original defect invisible in the other direction: 3.67
+ * GB arrived with no line saying it should not have.
+ */
+export declare function applyPlatformFilter(nodes: ResolvedNode[], target: PlatformTarget, force: boolean, log: Logger): ResolvedNode[];
 /**
  * Warn about a native package that installed WITHOUT a usable binary.
  *
@@ -64,6 +158,20 @@ export declare function writeBinEntry(opts: {
     binName: string;
     targetAbs: string;
     platform?: string;
+    /**
+     * Set when this entry is the package's GJS-runnable artifact (declared via
+     * `gjsify.bin`). Then the entry is a GENERATED launcher rather than a link
+     * to a file with a shebang — see {@link buildShLauncher} for why, and
+     * {@link pickBinMap} for why `gjsify.bin` has to win here at all.
+     *
+     * The preamble is what exports `GI_TYPELIB_PATH` / the loader path before
+     * `gjs` starts. It cannot be done from inside the bundle: GI resolves the
+     * typelib while the runtime boots, before the first line runs.
+     */
+    gjs?: {
+        envPreamble: string;
+        prebuildDirs: readonly string[];
+    };
 }): void;
 type Logger = (fmt: string, ...args: unknown[]) => void;
 export {};