@gjsify/cli 0.26.0 → 0.26.1

package/lib/commands/affected.js

@@ -7,15 +7,30 @@
 // up running the touched workspace + its downstream consumers instead of
 // the whole monorepo.
 //
+// EVERY VERDICT THIS FILE EMITS IS SCOPED TO ONE WORKFLOW: `main.yml`. That
+// scoping is the single most misread thing here, so it is stated before the
+// tables rather than after. The classifier is booted only by `main.yml`'s
+// `changes` job, and `main.yml` is the only workflow whose jobs consume its
+// outputs. So "ignored" NEVER means "irrelevant to the repository" — it means
+// "cannot change what `main.yml` builds or tests". Sibling workflows
+// (`prebuilds.yml`, `audit-runtimes.yml`, `node-gi.yml`, `napi.yml`,
+// `deploy-docs.yml`, …) gate themselves with their OWN `paths:` filters and are
+// unaffected by anything decided here. `IGNORE` has always worked this way —
+// `packages/node-gi/**` and `packages/napi/**` are load-bearing build inputs to
+// their own workflows and ignored here — but the table read as a global claim,
+// which is how a directory that is genuinely irrelevant to `main.yml` still
+// looks like something that must not be ignored.
+//
 // Classifier table (first-match wins) handles the cases that aren't a
 // straightforward "file lives in workspace X":
 //
-//   1. IGNORE  — pure-docs / *.md / website / refs/ submodule / unrelated
-//      workflow files / LICENSE / .gitignore. Discarded FIRST, before every
-//      other rule: an ignored file is never build-relevant, not even inside
-//      a GLOBAL_TRIGGERS directory (e.g. `packages/infra/cli/README.md` must
-//      not force a full run just because `packages/infra/cli/` is a global
-//      trigger). Ignore wins over global.
+//   1. IGNORE  — cannot change what `main.yml` builds or tests: pure-docs /
+//      *.md / website / refs/ submodule / other workflows' files and their
+//      inputs / LICENSE / .gitignore. Discarded FIRST, before every other
+//      rule: an ignored file is never build-relevant to this workflow, not
+//      even inside a GLOBAL_TRIGGERS directory (e.g.
+//      `packages/infra/cli/README.md` must not force a full run just because
+//      `packages/infra/cli/` is a global trigger). Ignore wins over global.
 //
 //   2. GLOBAL_TRIGGERS  — a non-ignored change touching infra the classifier
 //      itself depends on (`@gjsify/workspace`, `@gjsify/cli`, the bundler
@@ -24,12 +39,17 @@
 //      can't trust the closure when the algorithm that computes it just
 //      changed.
 //
-//   3. TEST_ONLY  — every changed file under ONE workspace is a spec
+//   3. SCRIPT_COUPLINGS  — a build input that reaches its consumer through a
+//      BUILD SCRIPT instead of a dependency, so the closure walk has no edge
+//      to follow. Contributes EXTRA seeds (and may force a test tier). See
+//      the table for why this cannot be inferred and must be declared.
+//
+//   4. TEST_ONLY  — every changed file under ONE workspace is a spec
 //      file, e2e fixture, or integration test. Seed = that workspace
 //      but SKIP the closure expansion (downstream consumers don't care
 //      about test code changes).
 //
-//   4. CODE (default)  — `workspacesForChangedFiles` maps file → ws,
+//   5. CODE (default)  — `workspacesForChangedFiles` maps file → ws,
 //      then `affectedClosure` walks reverse-dep edges.
 //
 // Integration tests are gated separately: they run when any workspace
@@ -162,13 +182,55 @@ const GLOBAL_TRIGGERS = [
     /^\.github\/workflows\/main\.yml$/,
     /^scripts\/audit-runtimes\.mjs$/,
 ];
+/**
+ * Inputs OWNED BY ANOTHER WORKFLOW — build-relevant, just not to `main.yml`.
+ *
+ * This is the sub-table where the workflow scoping stated at the top of the
+ * file is load-bearing, so each entry NAMES the workflow that does gate it.
+ * The test for membership is not "is this file unimportant" (none of these
+ * are) but "can `main.yml` build or test differently because of it" — and for
+ * every entry the answer is no, while the owning workflow has the path in its
+ * own `paths:` filter and would go red on a break.
+ *
+ * Adding a regex here is therefore a claim with two halves, and BOTH must
+ * hold: `main.yml` must not read the path, and some other workflow must.
+ */
+const OTHER_WORKFLOW_INPUTS = [
+    // Each sibling workflow's own definition. `main.yml` is deliberately
+    // absent — it is a GLOBAL_TRIGGER, since a job-shape change there is
+    // invisible until the workflow re-runs.
+    /^\.github\/workflows\/(deploy-docs|commitlint|release|release-cut|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image)\.yml$/,
+    // `prebuilds.yml`'s toolchain (#838): the QEMU-emulated build script and
+    // the `changed-packages` classifier that decides which native packages a
+    // prebuild run rebuilds. `prebuilds.yml` lists `.github/prebuild-toolchain/**`
+    // in BOTH its `push` and `pull_request` `paths:` filters, so a break here
+    // reds that workflow on the same PR. `main.yml` never executes any of it —
+    // it builds no prebuild and runs no emulated leg.
+    /^\.github\/prebuild-toolchain\//,
+    // The REPO-SCOPED manifest-conformance rules (#847) — `tier`, `refs-pin`,
+    // `platforms-ci` plus the `unchecked-fields` ledger. Their gate is
+    // `audit-runtimes.yml`, which runs `node scripts/audit-runtimes.mjs
+    // --check --strict` on EVERY pull_request with no `paths:` filter at all,
+    // so this content is verified on every PR regardless of what is ignored
+    // here; `prebuilds.yml` additionally declares it a shared input (#843) and
+    // rebuilds every native package when it changes.
+    //
+    // The distinction that makes this safe is a real one, not a technicality:
+    // `main.yml` DOES run manifest-conformance code, but it reaches it through
+    // `scripts/verify-package-outputs.mjs` importing
+    // `packages/infra/manifest-conformance/lib/**` — the PACKAGE, a normal
+    // workspace under the `packages/infra/*` glob that maps and seeds like any
+    // other. Only the `scripts/`-side repo-scoped half is ignored, and that
+    // half is precisely the half `main.yml` does not load.
+    /^scripts\/manifest-conformance\//,
+];
 /** Patterns that contribute no seed and don't force a full run. */
 const IGNORE = [
     /\.md$/i,
     /^refs\//,
     /^website\//,
     /^docs\//,
-    /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image)\.yml$/,
+    ...OTHER_WORKFLOW_INPUTS,
     /^\.githooks\//,
     // @gjsify/node-gi (the Node-native GObject-Introspection engine, Axis 5) is
     // NOT a gjsify workspace member — the GJS-first install/foreach tooling can't
@@ -200,6 +262,31 @@ const IGNORE = [
 ];
 /** Patterns that suggest a test-only change. */
 const TEST_PATHS = [/\.spec\.[mc]?[tj]sx?$/, /^tests\/(e2e|integration)\//];
+const SCRIPT_COUPLINGS = [
+    {
+        // `templates/*` ARE workspaces (root `package.json#workspaces` carries
+        // a `templates/*` glob), so a template change already seeds its own
+        // `@gjsify/template-<name>`. That is not the consumer that matters.
+        //
+        // The consumer is `@gjsify/create-app`, and it is unreachable twice
+        // over: it lives at `packages/infra/create-gjsify/`, so no
+        // directory-name search finds it, and it takes the templates in
+        // through `node scripts/process-template.mjs` in its `build` script
+        // (which resolves each template's `workspace:^` specifiers and copies
+        // the result into `dist-templates/`), so there is no dependency edge
+        // either. `dist-templates/` is a build-output cache candidate, so once
+        // it is stale it stays stale.
+        match: /^templates\//,
+        seeds: ['@gjsify/create-app'],
+        // …and `tests/e2e/create-app` is the ONLY thing that would notice: it
+        // scaffolds a project out of `dist-templates/` and builds it. Without
+        // this a templates-only PR got neither the regenerated templates nor
+        // the suite that exercises them. PR #853 passed only by accident of
+        // also touching root `package.json` and tripping a global trigger.
+        runE2E: true,
+        why: '@gjsify/create-app build → node scripts/process-template.mjs reads templates/',
+    },
+];
 function classifyAndExpand(workspaces, changedFiles) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
     if (files.length === 0) {
@@ -250,23 +337,64 @@ function classifyAndExpand(workspaces, changedFiles) {
     }
     // Map files → workspaces. Files outside any workspace stay in `unmatched`.
     const { matched, unmatched } = workspacesForChangedFiles(workspaces, remaining);
+    // SCRIPT_COUPLINGS: add the seeds no graph edge can reach. Applied BEFORE
+    // the `unmatched` bail-out so the table works for a coupled directory that
+    // is NOT itself a workspace — such a file would otherwise force a full run
+    // and the declared seeds would never be consulted.
+    const knownNames = new Set(workspaces.map((w) => w.name));
+    const couplingSeeds = new Set();
+    const couplingAccounted = new Set();
+    let couplingRunE2E = false;
+    for (const c of SCRIPT_COUPLINGS) {
+        const hits = remaining.filter((f) => c.match.test(f));
+        if (hits.length === 0)
+            continue;
+        for (const h of hits)
+            couplingAccounted.add(h);
+        for (const s of c.seeds) {
+            // A declared seed that is not a workspace means the table has
+            // drifted from the tree (package renamed, moved, removed). Fail
+            // towards the full run and SAY SO — the whole point of this table
+            // is that a missing rebuild here is otherwise invisible, so it must
+            // never degrade quietly back into the bug it exists to prevent.
+            if (!knownNames.has(s)) {
+                return {
+                    global: true,
+                    reason: `script-coupling seed ${s} is not a workspace (${c.match.source} → ${c.why}); ` +
+                        `SCRIPT_COUPLINGS in commands/affected.ts is stale`,
+                    workspaces: workspaces.map((w) => w.name),
+                    runE2E: true,
+                    runIntegration: true,
+                    skipAll: false,
+                };
+            }
+            couplingSeeds.add(s);
+        }
+        if (c.runE2E)
+            couplingRunE2E = true;
+    }
     // Unmatched-but-not-ignored files are suspicious enough to fall back to
     // the conservative "full run" path. Examples: a new top-level dotfile,
     // a script in `scripts/` we haven't carved out, a refs/-adjacent file.
-    if (unmatched.length > 0) {
+    // A file a coupling claimed is accounted for and does not count here.
+    const stillUnmatched = unmatched.filter((f) => !couplingAccounted.has(f));
+    if (stillUnmatched.length > 0) {
         return {
             global: true,
-            reason: `unmatched files (${unmatched.length}): ${unmatched.slice(0, 3).join(', ')}${unmatched.length > 3 ? '…' : ''}`,
+            reason: `unmatched files (${stillUnmatched.length}): ${stillUnmatched.slice(0, 3).join(', ')}${stillUnmatched.length > 3 ? '…' : ''}`,
             workspaces: workspaces.map((w) => w.name),
             runE2E: true,
             runIntegration: true,
             skipAll: false,
         };
     }
+    for (const s of couplingSeeds)
+        matched.add(s);
     // TEST_ONLY shortcut: every remaining file is a spec / e2e / integration
     // path, all under ONE workspace. Skip the closure expansion — test code
-    // has no downstream consumers.
-    const testOnly = remaining.every((f) => TEST_PATHS.some((re) => re.test(f)));
+    // has no downstream consumers. A coupling deliberately disables it: the
+    // extra seeds exist precisely because a downstream consumer DOES care.
+    const testOnly = couplingSeeds.size === 0 && remaining.every((f) => TEST_PATHS.some((re) => re.test(f)));
     if (testOnly && matched.size === 1) {
         const only = [...matched][0];
         // E2E or integration test-only changes still need their own job.
@@ -317,10 +445,13 @@ function classifyAndExpand(workspaces, changedFiles) {
             }
         }
     }
-    const runE2E = remaining.some((f) => f.startsWith('tests/e2e/'));
+    // A `tests/e2e/**` touch turns the tier on, and so does any coupling that
+    // declares e2e as its only real coverage (see SCRIPT_COUPLINGS).
+    const runE2E = remaining.some((f) => f.startsWith('tests/e2e/')) || couplingRunE2E;
     return {
         global: false,
-        reason: `closure (${closure.size} ws from ${matched.size} seed(s))`,
+        reason: `closure (${closure.size} ws from ${matched.size} seed(s))` +
+            (couplingSeeds.size > 0 ? `, ${couplingSeeds.size} via script-coupling` : ''),
         workspaces: [...closure].sort(),
         runE2E,
         runIntegration,

package/lib/utils/build-cache.js

@@ -49,10 +49,11 @@
 // or a permission error degrade to "run the script uncached" — a cache
 // hiccup must never break a build.
 import { createHash } from 'node:crypto';
-import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, renameSync, rmSync, symlinkSync, copyFileSync, writeFileSync, } from 'node:fs';
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, renameSync, rmSync, copyFileSync, writeFileSync, } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildDependencyGraph } from '@gjsify/workspace';
+import { replicateLinkSync } from './dir-link.js';
 /**
  * Bump to invalidate every existing cache entry (schema/semantic changes).
  *
@@ -417,7 +418,11 @@ function copyDirRecursive(from, to) {
         const dst = join(to, entry);
         const st = lstatSync(src);
         if (st.isSymbolicLink()) {
-            symlinkSync(readlinkSync(src), dst);
+            // Not `symlinkSync(readlinkSync(src), dst)`: replicating a link to a
+            // DIRECTORY verbatim needs a junction on Windows, and the target has
+            // to be resolved for it. See `dir-link.ts` — the one definition of
+            // that rule, added after the same mistake shipped in `dlx-cache.ts`.
+            replicateLinkSync(src, dst);
         }
         else if (st.isDirectory()) {
             copyDirRecursive(src, dst);

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

@@ -0,0 +1,58 @@
+/**
+ * The link type a directory link must use on this platform.
+ *
+ * `undefined` on POSIX is deliberate: Node's default is correct there, and
+ * passing a type would be noise.
+ */
+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).
+ *
+ * `linkType` 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.
+ *
+ * @param linkPath  where the link itself will live
+ * @param absTarget the directory it should point at, as an ABSOLUTE path
+ * @param linkType  override the host's link type (tests only)
+ */
+export declare function dirLinkTarget(linkPath: string, absTarget: string, linkType?: 'junction' | undefined): 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;

package/lib/utils/dir-link.js

@@ -0,0 +1,126 @@
+// 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 type a directory link must use on this platform.
+ *
+ * `undefined` on POSIX is deliberate: Node's default is correct there, and
+ * passing a type would be noise.
+ */
+export const DIR_LINK_TYPE = process.platform === 'win32' ? 'junction' : undefined;
+/** True when directory links on this platform are NTFS junctions. */
+export const dirLinksAreJunctions = () => DIR_LINK_TYPE === '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).
+ *
+ * `linkType` 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.
+ *
+ * @param linkPath  where the link itself will live
+ * @param absTarget the directory it should point at, as an ABSOLUTE path
+ * @param linkType  override the host's link type (tests only)
+ */
+export function dirLinkTarget(linkPath, absTarget, linkType = DIR_LINK_TYPE) {
+    return linkType === '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-packument-cache.d.ts

@@ -3,6 +3,29 @@ export interface CachedPackument {
     etag: string;
     packument: Packument;
 }
+/**
+ * The cache key for a (registry, name) pair — exported so the filename rule
+ * below is a PROPERTY a test can assert, not a claim in a comment.
+ *
+ * THE SEPARATOR IS NOT COSMETIC. It used to be `|`, producing names like
+ * `corgi|https%3A%2F%2Fregistry.npmjs.org%2F|%40gjsify%2Fnode-gi.json` — and `|`
+ * is a Win32 RESERVED filename character, so every write failed with `EINVAL`.
+ * Nothing reported it: `atomicWrite` is best-effort on purpose (a read-only
+ * cache volume must not break an install) and `readCacheFile` reads an
+ * unreadable path as a MISS. So on Windows this cache was never broken loudly —
+ * it was silently DEAD, and the `If-None-Match` → `304` revalidation that is the
+ * entire reason this file exists never engaged once.
+ *
+ * `,` is legal on Win32 AND escaped by `encodeURIComponent`, which is what keeps
+ * a flat two-part name injective: an encoded part cannot contain the separator,
+ * so exactly one `(registry, name)` pair maps to any given filename.
+ *
+ * The shard key and the filename are derived from the SAME encoded parts. They
+ * used to disagree — the key hashed the raw pair while the name used the encoded
+ * one — which is how a reserved character in the name survived review of a
+ * function whose other half looked correct.
+ */
+export declare function packumentCacheKey(registry: string, name: string): string;
 /**
  * Read a cached packument + its ETag for `(registry, name)`. Returns `null` on
  * a miss, when the cache is disabled, or when the entry is unreadable/corrupt