@gjsify/cli 0.36.0 → 0.37.0

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;

package/lib/utils/dir-link.js

@@ -1,19 +1,12 @@
 // 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.
+// Windows cannot create a directory *symlink* without elevation or Developer Mode
+// (`EPERM`), but any user can create an NTFS **junction**, which is why npm, yarn
+// and pnpm all use junctions for directory links. Encoded as a local constant and
+// shared nowhere, the next site got it wrong: `dlx-cache.ts` linked with `'dir'` and
+// every non-elevated Windows user hit `EPERM: operation not permitted, symlink` on a
+// plain `npx @gjsify/cli@latest showcase …`. Hence one callable definition rather
+// than a convention.
 //
 // THE TWO GOTCHAS, both load-bearing:
 //
@@ -25,19 +18,16 @@
 //     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.
+// Autodetection is no substitute on Windows: with the type argument omitted Node
+// picks `'file'` or `'dir'`, never `'junction'`.
 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
+ * 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 const DIR_LINK_TYPE = DIR_LINK_KIND === 'junction' ? 'junction' : undefined;
@@ -50,23 +40,17 @@ export const dirLinksAreJunctions = () => DIR_LINK_KIND === 'junction';
  * 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)
  */
@@ -75,11 +59,9 @@ export function dirLinkTarget(linkPath, absTarget, linkKind = DIR_LINK_KIND) {
 }
 /**
  * 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 function linkDirSync(linkPath, absTarget) {
     assertAbsolute(absTarget);
@@ -93,22 +75,17 @@ export async function linkDir(linkPath, absTarget) {
 /**
  * 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 function replicateLinkSync(srcLink, dstLink) {
     const rawTarget = readlinkSync(srcLink);

package/lib/utils/discover-showcases.d.ts

@@ -1,17 +1,16 @@
 export interface ShowcaseInfo {
-    /** Short name, e.g. "three-postprocessing-pixel" */
+    /** Short name, the `gjsify showcase <name>` argument. */
     name: string;
-    /** Full npm package name, e.g. "@gjsify/example-dom-three-postprocessing-pixel" */
+    /** Full npm package name, e.g. "@gjsify/example-dom-three-postprocessing-pixel". */
     packageName: string;
-    /** Category: "dom" or "node" */
+    /** `"dom"` or `"node"`. */
     category: string;
-    /** Description for the list view */
     description: string;
 }
 /**
- * Read the curated showcase list from `showcases.json`. Returns showcases
- * sorted by category then name. An empty list (or missing manifest) yields
- * an empty array — `gjsify showcase` then prints the empty-state message.
+ * Read the curated showcase list from `showcases.json`, sorted by category then
+ * name. A missing or unparseable manifest yields `[]`, letting `gjsify showcase`
+ * print its empty-state message instead of failing.
  */
 export declare function discoverShowcases(): ShowcaseInfo[];
 /** Find a single showcase by short name. */

package/lib/utils/discover-showcases.js

@@ -1,29 +1,25 @@
 // Static discovery of showcase packages from `showcases.json`.
 //
-// Earlier versions read showcases from the CLI's own `package.json#dependencies`
-// — every showcase had to be a direct CLI dependency. That made the CLI tarball
-// blow up with each new showcase and required a CLI rebuild to publish a new
-// one. Static manifest decouples both: the CLI reads the manifest at runtime,
-// `gjsify showcase <name>` delegates to `gjsify dlx <package>`.
+// A manifest read at runtime, not CLI `dependencies`: a showcase must not have to
+// be a direct CLI dependency, or every new one grows the CLI tarball and needs a
+// CLI rebuild to publish. `gjsify showcase <name>` delegates to `gjsify dlx`.
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 function manifestPath() {
     const here = dirname(fileURLToPath(import.meta.url));
-    // `showcases.json` lives at the CLI package root. Its position relative to
-    // this module depends on how the CLI is loaded:
-    //   - `lib/utils/discover-showcases.js` (Node/Bun/Deno) → `../../showcases.json`.
-    //   - the committed `dist/cli.gjs.mjs` GJS bundle (`gjsify showcase` under
-    //     gjs) → `import.meta.url` is `dist/cli.gjs.mjs`, so the manifest is one
-    //     level up (`../showcases.json`), not two — without this the gjs CLI
-    //     finds no manifest and `showcase` wrongly reports "No showcases found".
+    // `showcases.json` sits at the CLI package root, but its depth below this
+    // module depends on how the CLI was loaded: two levels from
+    // `lib/utils/discover-showcases.js` (Node/Bun/Deno), one from the committed
+    // `dist/cli.gjs.mjs` bundle. Try both, or the gjs CLI finds no manifest and
+    // `showcase` wrongly reports that there are none.
     const candidates = [join(here, '..', '..', 'showcases.json'), join(here, '..', 'showcases.json')];
     return candidates.find((c) => existsSync(c)) ?? candidates[0];
 }
 /**
- * Read the curated showcase list from `showcases.json`. Returns showcases
- * sorted by category then name. An empty list (or missing manifest) yields
- * an empty array — `gjsify showcase` then prints the empty-state message.
+ * Read the curated showcase list from `showcases.json`, sorted by category then
+ * name. A missing or unparseable manifest yields `[]`, letting `gjsify showcase`
+ * print its empty-state message instead of failing.
  */
 export function discoverShowcases() {
     const path = manifestPath();

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

@@ -11,9 +11,8 @@ export declare function cacheDirFor(cacheKey: string): string;
 /** A fresh prepare directory under the per-key cache, named timestamp-pid. */
 export declare function makePrepareDir(cacheDir: string): string;
 /**
- * If <cacheDir>/pkg points to a target whose mtime + maxAge < now, return its
- * realpath. Returns undefined when the link doesn't exist, isn't a symlink,
- * has been removed, or has expired.
+ * The realpath of `<cacheDir>/pkg` when it is a symlink within its TTL; undefined
+ * when the link is missing, is not a symlink, has been removed, or has expired.
  */
 export declare function getValidCachedPkg(cacheDir: string, maxAgeMinutes?: number): string | undefined;
 /**
@@ -26,30 +25,25 @@ export declare function getValidCachedPkg(cacheDir: string, maxAgeMinutes?: numb
  * 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:
+ * WINDOWS breaks both halves:
  *
- *   • 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.
+ *   • A directory SYMLINK needs elevation or Developer Mode, so step 1 goes
+ *     through {@link linkDirSync} for an NTFS junction — the choice npm and yarn
+ *     make. A raw `symlinkSync(…, 'dir')` died with `EPERM: operation not
+ *     permitted, symlink` on a plain `npx @gjsify/cli@latest showcase …`.
+ *   • Step 2's rename-over-existing is a POSIX guarantee only: `MoveFileEx` will
+ *     not replace an existing DIRECTORY, and a junction is a directory reparse
+ *     point. On the second run the rename fails `EPERM`, the catch below reads it
+ *     as "race lost", and the OLD target comes back — not a crash, but worse: the
+ *     cache silently never refreshes. Windows therefore unlinks first and accepts
+ *     a non-atomic window, which the 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.
+ * @param opts.junctions force the Windows link strategy (TESTS ONLY), defaulting to
+ *   the host's. A parameter for the same reason `dirLinkTarget` takes `linkKind`:
+ *   nothing in CI runs on Windows, so an injected `true` is the ONLY way the
+ *   unlink-then-rename ordering is ever EXECUTED. It proves the ORDERING and that a
+ *   second swap really refreshes; it cannot prove `MoveFileEx`/junction syscall
+ *   behaviour.
  */
 export declare function symlinkSwap(cacheDir: string, prepareDir: string, opts?: {
     junctions?: boolean;
@@ -57,23 +51,20 @@ export declare function symlinkSwap(cacheDir: string, prepareDir: string, opts?:
 /**
  * Remove `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`.
  *
- * Every `gjsify dlx` miss creates a fresh prepare dir and swaps the `pkg` link
- * onto it; the previous one is then unreferenced and stayed on disk forever,
- * because this function accepted a TTL and did nothing with it. A full npm tree
- * per miss makes that the largest thing gjsify writes to a user's cache.
+ * Every `gjsify dlx` miss creates a fresh prepare dir and swaps the `pkg` link onto
+ * it, leaving the previous one unreferenced — a full npm tree per miss, the largest
+ * thing gjsify writes to a user's cache.
  *
  * Three rules keep it from deleting something it should not:
  *
  *   1. **Only names `makePrepareDir` could have produced** (`<hex>-<hex>`). The
- *      cache dir also holds `pkg` and, briefly, `pkg.tmp-<ts>-<pid>` links from
- *      a concurrent swap — and a name-shape guard is what makes "delete the
- *      rest" safe against anything a future version puts here.
- *   2. **Never the LIVE target**, whatever its age. A long-lived cache entry
- *      that is still current is exactly the one worth keeping, and it ages past
- *      any TTL while being used on every run.
- *   3. **Never throws.** This is housekeeping on a best-effort path: a losing
- *      race (a parallel dlx removing the same dir) or a read-only cache must not
- *      fail the command the user actually ran.
+ *      cache dir also holds `pkg` and, briefly, `pkg.tmp-<ts>-<pid>` links from a
+ *      concurrent swap; the name-shape guard is what makes "delete the rest" safe
+ *      against anything a future version puts here.
+ *   2. **Never the LIVE target**, whatever its age — a still-current entry ages
+ *      past any TTL precisely because it is used on every run.
+ *   3. **Never throws.** Best-effort housekeeping: a lost race against a parallel
+ *      dlx, or a read-only cache, must not fail the command the user ran.
  */
 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

@@ -50,9 +50,8 @@ export function makePrepareDir(cacheDir) {
     return dir;
 }
 /**
- * If <cacheDir>/pkg points to a target whose mtime + maxAge < now, return its
- * realpath. Returns undefined when the link doesn't exist, isn't a symlink,
- * has been removed, or has expired.
+ * The realpath of `<cacheDir>/pkg` when it is a symlink within its TTL; undefined
+ * when the link is missing, is not a symlink, has been removed, or has expired.
  */
 export function getValidCachedPkg(cacheDir, maxAgeMinutes = DEFAULT_TTL_MIN) {
     const linkPath = join(cacheDir, 'pkg');
@@ -87,52 +86,46 @@ export function getValidCachedPkg(cacheDir, maxAgeMinutes = DEFAULT_TTL_MIN) {
  * 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:
+ * WINDOWS breaks both halves:
  *
- *   • 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.
+ *   • A directory SYMLINK needs elevation or Developer Mode, so step 1 goes
+ *     through {@link linkDirSync} for an NTFS junction — the choice npm and yarn
+ *     make. A raw `symlinkSync(…, 'dir')` died with `EPERM: operation not
+ *     permitted, symlink` on a plain `npx @gjsify/cli@latest showcase …`.
+ *   • Step 2's rename-over-existing is a POSIX guarantee only: `MoveFileEx` will
+ *     not replace an existing DIRECTORY, and a junction is a directory reparse
+ *     point. On the second run the rename fails `EPERM`, the catch below reads it
+ *     as "race lost", and the OLD target comes back — not a crash, but worse: the
+ *     cache silently never refreshes. Windows therefore unlinks first and accepts
+ *     a non-atomic window, which the 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.
+ * @param opts.junctions force the Windows link strategy (TESTS ONLY), defaulting to
+ *   the host's. A parameter for the same reason `dirLinkTarget` takes `linkKind`:
+ *   nothing in CI runs on Windows, so an injected `true` is the ONLY way the
+ *   unlink-then-rename ordering is ever EXECUTED. It proves the ORDERING and that a
+ *   second swap really refreshes; it cannot prove `MoveFileEx`/junction syscall
+ *   behaviour.
  */
 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).
+    // If the tmp link cannot be created, give up (the error propagates).
     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.
+            // Windows: no rename-over-a-directory. Removing first opens a window in
+            // which `pkg` is absent; a concurrent reader treats that as a miss and
+            // prepares its own — 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.
+            // wraps deletes in `rmWithRetry`: on Windows a delete fails EBUSY/EPERM
+            // while ANY process holds a handle (an antivirus scan, a concurrent
+            // reader that just realpath'd this link) and then stays PENDING, so
+            // without the retry a transient handle takes the "race lost" branch and
+            // the cache silently does not refresh. Free on POSIX.
             rmSync(linkPath, { force: true, recursive: false, maxRetries: 10, retryDelay: 100 });
         }
         renameSync(tmpLink, linkPath);
@@ -140,21 +133,21 @@ export function symlinkSwap(cacheDir, prepareDir, opts = {}) {
     catch (err) {
         const code = err.code;
         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.
+            // Race lost — clean up our tmp and use whoever won. `force:true` is the
+            // non-throwing "remove if still there"; any other failure on our own
+            // pid-unique link is real and should surface.
             rmSync(tmpLink, { force: true });
             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.
+                // Windows 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 to a caller that reports it as `Could not resolve
+                // showcase "<name>"`. Our own prepareDir is a complete, correctly
+                // installed tree — a truthful answer for THIS run, and the next run
+                // reads whichever link won.
                 return realpathSync(prepareDir);
             }
         }
@@ -165,28 +158,25 @@ export function symlinkSwap(cacheDir, prepareDir, opts = {}) {
 /**
  * Remove `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`.
  *
- * Every `gjsify dlx` miss creates a fresh prepare dir and swaps the `pkg` link
- * onto it; the previous one is then unreferenced and stayed on disk forever,
- * because this function accepted a TTL and did nothing with it. A full npm tree
- * per miss makes that the largest thing gjsify writes to a user's cache.
+ * Every `gjsify dlx` miss creates a fresh prepare dir and swaps the `pkg` link onto
+ * it, leaving the previous one unreferenced — a full npm tree per miss, the largest
+ * thing gjsify writes to a user's cache.
  *
  * Three rules keep it from deleting something it should not:
  *
  *   1. **Only names `makePrepareDir` could have produced** (`<hex>-<hex>`). The
- *      cache dir also holds `pkg` and, briefly, `pkg.tmp-<ts>-<pid>` links from
- *      a concurrent swap — and a name-shape guard is what makes "delete the
- *      rest" safe against anything a future version puts here.
- *   2. **Never the LIVE target**, whatever its age. A long-lived cache entry
- *      that is still current is exactly the one worth keeping, and it ages past
- *      any TTL while being used on every run.
- *   3. **Never throws.** This is housekeeping on a best-effort path: a losing
- *      race (a parallel dlx removing the same dir) or a read-only cache must not
- *      fail the command the user actually ran.
+ *      cache dir also holds `pkg` and, briefly, `pkg.tmp-<ts>-<pid>` links from a
+ *      concurrent swap; the name-shape guard is what makes "delete the rest" safe
+ *      against anything a future version puts here.
+ *   2. **Never the LIVE target**, whatever its age — a still-current entry ages
+ *      past any TTL precisely because it is used on every run.
+ *   3. **Never throws.** Best-effort housekeeping: a lost race against a parallel
+ *      dlx, or a read-only cache, must not fail the command the user ran.
  */
 export function cleanupStalePrepareDirs(cacheDir, maxAgeMinutes = DEFAULT_TTL_MIN) {
     const cutoff = Date.now() - maxAgeMinutes * ONE_MINUTE_MS;
-    // The live target, resolved once. An unreadable or absent `pkg` link simply
-    // means nothing is live yet — every prepare dir is then a candidate.
+    // An unreadable or absent `pkg` link means nothing is live yet, so every prepare
+    // dir is a candidate.
     let live;
     try {
         live = realpathSync(join(cacheDir, 'pkg'));
@@ -213,8 +203,8 @@ export function cleanupStalePrepareDirs(cacheDir, maxAgeMinutes = DEFAULT_TTL_MI
             rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
         }
         catch {
-            // Lost a race with another dlx, or the entry vanished between the
-            // readdir and the stat. Both mean "someone else handled it".
+            // Lost a race with another dlx, or the entry vanished between readdir and
+            // stat. Both mean someone else handled it.
         }
     }
 }

package/lib/utils/force-exit.d.ts

@@ -3,8 +3,5 @@
  *
  * Safe to call from any context, including an async callback where a bare
  * `process.exit()` would be dropped under GJS. Does not return.
- *
- * `process.exitCode` is set FIRST so that a host which somehow reaches natural
- * shutdown anyway still reports the right code.
  */
 export declare function forceExit(code: number): never;