@gjsify/cli 0.21.0 → 0.23.0

package/lib/bundler-pick.js

@@ -48,10 +48,18 @@ async function loadNpmRolldown() {
     // `@gjsify/rolldown-native`'s lib/ is not built yet, issue #497).
     // Fail with the actionable diagnosis instead.
     if (isGjs()) {
-        throw new Error('gjsify build: no usable bundler engine under GJS — `@gjsify/rolldown-native` is not loadable ' +
-            '(its JS facade lib/ is not built, or its prebuild typelib is missing from GI_TYPELIB_PATH), ' +
-            'and the npm `rolldown` engine is a Rust napi crate that cannot run under GJS. ' +
-            'Build the facade first (`gjsify workspace @gjsify/rolldown-native build` under Node) or run this build under Node.');
+        throw new Error('gjsify build: no usable bundler engine under GJS — `@gjsify/rolldown-native` is not loadable, ' +
+            'and the npm `rolldown` engine is a Rust napi crate that cannot run under GJS.\n' +
+            'Most likely cause: the CLI bundle was invoked DIRECTLY (`gjs -m …/cli.gjs.mjs` or by executing ' +
+            'dist/cli.gjs.mjs), which bypasses the `gjsify` launcher that exports GI_TYPELIB_PATH / ' +
+            'LD_LIBRARY_PATH for the prebuilds. The typelib lookup happens inside the GJS runtime, so those ' +
+            'must be set BEFORE the process starts — the CLI cannot repair it from the inside. ' +
+            'Run through the `gjsify` bin instead (`node_modules/.bin/gjsify …`, or the globally installed shim), ' +
+            'or export the env yourself:\n' +
+            '  P=<repo>/packages/infra/rolldown-native/prebuilds/linux-x86_64\n' +
+            '  GI_TYPELIB_PATH=$P LD_LIBRARY_PATH=$P gjs -m …/cli.gjs.mjs build …\n' +
+            'Other causes: the JS facade `lib/` is not built (`gjsify workspace @gjsify/rolldown-native build` ' +
+            'under Node), or no prebuild exists for this architecture. Running the build under Node also works.');
     }
     // Indirect specifier so Rolldown's static-analysis doesn't try to
     // bundle the npm crate into a GJS target build.

package/lib/commands/affected.js

@@ -47,9 +47,12 @@
 //
 // `--changed-from-stdin` skips `git diff` entirely and reads a newline-
 // separated list of paths from stdin. Useful for local debugging and
-// for the spec suite.
+// for the spec suite. Stdin is slurped via `utils/stdin.ts`, NOT
+// `readFileSync(0)` — `@gjsify/fs` has no numeric-fd path, so the Node
+// idiom opens the relative file `./0` and the committed GJS classifier
+// bundle died with `ENOENT … read '0'` on every `--changed-from-stdin` run.
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
+import { readStdinLines } from '../utils/stdin.js';
 import { discoverWorkspaces, buildDependencyGraph, buildReverseDependencyGraph, affectedClosure, workspacesForChangedFiles, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 export const affectedCommand = {
@@ -85,7 +88,7 @@ export const affectedCommand = {
         const changedFiles = args['changed-from-stdin']
             ? readStdinLines()
             : runGitDiff(rootDir, args.base ?? 'origin/main', args.head ?? 'HEAD');
-        const result = classifyAndExpand(workspaces, rootDir, changedFiles);
+        const result = classifyAndExpand(workspaces, changedFiles);
         emit(args.format, result);
     },
 };
@@ -103,6 +106,11 @@ const GLOBAL_TRIGGERS = [
     // can break assertions anywhere. Treat it as a global trigger so a
     // `@gjsify/unit` change re-runs the full suite.
     /^packages\/gjs\/unit\//,
+    // The composite action every CI job runs to set itself up. A change here
+    // alters the environment of the whole matrix, so it must force a full run
+    // EXPLICITLY — it already did, but only by falling through to the
+    // conservative "unmatched files" path, which is luck rather than intent.
+    /^\.github\/actions\//,
     // Cross-cutting dep + lockfile + root config.
     /^gjsify-lock\.json$/,
     /^package\.json$/,
@@ -119,7 +127,7 @@ const IGNORE = [
     /^refs\//,
     /^website\//,
     /^docs\//,
-    /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds|node-gi)\.yml$/,
+    /^\.github\/workflows\/(deploy-docs|commitlint|release|audit-runtimes|prebuilds|node-gi|napi|cli-cross-platform|build-ci-image)\.yml$/,
     /^\.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
@@ -128,6 +136,14 @@ const IGNORE = [
     // tested on Node). Without this carve-out its files map to no workspace and
     // land in `unmatched`, forcing a conservative full run on every node-gi PR.
     /^packages\/node-gi\//,
+    // @gjsify/napi (the N-API host over GJS's SpiderMonkey, the forward mirror of
+    // node-gi) is likewise NOT a gjsify workspace member — the GJS-first
+    // install/foreach tooling can't build its Vala+C++/meson shim or its node-gyp
+    // test addons, so the main workflow neither builds nor tests it. Its own
+    // `.github/workflows/napi.yml` is the source of truth. Without this carve-out
+    // its files map to no workspace and force a conservative full run on every
+    // napi PR.
+    /^packages\/napi\//,
     // Flatpak build/distribution tooling (SDK-extension manifest + metainfo).
     // Like `.githooks/`, it has no package-test consumers; its own
     // `tests/e2e/flatpak-sdk-extension` runs on `tests/e2e/**` / global triggers.
@@ -143,7 +159,7 @@ const IGNORE = [
 ];
 /** Patterns that suggest a test-only change. */
 const TEST_PATHS = [/\.spec\.[mc]?[tj]sx?$/, /^tests\/(e2e|integration)\//];
-function classifyAndExpand(workspaces, rootDir, changedFiles) {
+function classifyAndExpand(workspaces, changedFiles) {
     const files = changedFiles.map((f) => f.replace(/\\/g, '/')).filter((f) => f.length > 0);
     if (files.length === 0) {
         return {
@@ -192,7 +208,7 @@ function classifyAndExpand(workspaces, rootDir, changedFiles) {
         }
     }
     // Map files → workspaces. Files outside any workspace stay in `unmatched`.
-    const { matched, unmatched } = workspacesForChangedFiles(workspaces, rootDir, remaining);
+    const { matched, unmatched } = workspacesForChangedFiles(workspaces, remaining);
     // 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.
@@ -290,10 +306,6 @@ function runGitDiff(cwd, base, head) {
     }
     return r.stdout.split('\n').filter(Boolean);
 }
-function readStdinLines() {
-    const data = readFileSync(0, 'utf8');
-    return data.split('\n').map((s) => s.trim()).filter(Boolean);
-}
 // ─── Output ────────────────────────────────────────────────────────────────
 function emit(format, r) {
     if (format === 'json') {

package/lib/commands/check.js

@@ -14,8 +14,9 @@
 // — if both `system-check`-style flags (`--json`) and `check`-style scripts
 // are reachable here, the `--json` flag routes through this command first
 // (since the typescript-check binding is positional `[paths..]`).
-import { spawn, spawnSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import { prefixLines } from '../utils/prefixed-output.js';
+import { spawnToCompletion } from '../utils/spawn.js';
 import { readPackageJson } from '../utils/pkg-json.js';
 import { join } from 'node:path';
 import { cpus } from 'node:os';
@@ -26,36 +27,44 @@ import { findWorkspaceRoot } from '../utils/workspace-root.js';
  * indicates failure. Output is forwarded to the parent's stdout/stderr,
  * line-prefixed with the workspace name when `prefix` is set.
  */
-function runCheck(ws, prefix) {
-    return new Promise((resolve) => {
-        const child = spawn('npm', ['run', 'check', '--if-present'], {
+async function runCheck(ws, prefix) {
+    // `completion: 'exit'` — every path out of this command's handler ends in
+    // `process.exit(…)`, which quits the GLib main loop `spawn()` arms under
+    // GJS, so the STREAMING async path is safe here (and required: the
+    // blocking one would serialize the parallel workers). See utils/spawn.ts.
+    const flushers = [];
+    try {
+        const { code } = await spawnToCompletion('npm', ['run', 'check', '--if-present'], {
+            completion: 'exit',
             cwd: ws.location,
-            stdio: prefix === null ? 'inherit' : ['ignore', 'pipe', 'pipe'],
-        });
-        // Shared with `foreach`: live line-prefixing on a tty, buffered
-        // flush-on-close on a non-tty sink. The previous inline forwarder
-        // wrote every line live — under GJS `process.stdout.write` is a
-        // blocking `Gio.write_all`, so a parallel check into a
-        // backpressuring CI pipe could stall the GLib loop the same way
-        // the foreach examples build did. See utils/prefixed-output.ts.
-        const buffered = !process.stdout.isTTY;
-        const flushers = [];
-        if (prefix !== null && child.stdout && child.stderr) {
-            const tag = `[${prefix}] `;
-            flushers.push(prefixLines(child.stdout, process.stdout, tag, buffered));
-            flushers.push(prefixLines(child.stderr, process.stderr, tag, buffered));
-        }
-        child.on('close', (code) => {
-            for (const flush of flushers)
-                flush();
-            resolve(code ?? 1);
-        });
-        child.on('error', () => {
-            for (const flush of flushers)
-                flush();
-            resolve(1);
+            stdio: prefix === null ? 'inherit' : 'pipe',
+            onSpawn: (child) => {
+                // Shared with `foreach`: live line-prefixing on a tty, buffered
+                // flush-on-close on a non-tty sink. The previous inline
+                // forwarder wrote every line live — under GJS
+                // `process.stdout.write` is a blocking `Gio.write_all`, so a
+                // parallel check into a backpressuring CI pipe could stall the
+                // GLib loop the same way the foreach examples build did. See
+                // utils/prefixed-output.ts.
+                const buffered = !process.stdout.isTTY;
+                if (prefix !== null && child.stdout && child.stderr) {
+                    const tag = `[${prefix}] `;
+                    flushers.push(prefixLines(child.stdout, process.stdout, tag, buffered));
+                    flushers.push(prefixLines(child.stderr, process.stderr, tag, buffered));
+                }
+            },
         });
-    });
+        for (const flush of flushers)
+            flush();
+        return code ?? 1;
+    }
+    catch {
+        // Spawn failure (npm not on PATH, …) reports as a failed check —
+        // `gjsify check` aggregates codes rather than throwing per workspace.
+        for (const flush of flushers)
+            flush();
+        return 1;
+    }
 }
 export const checkCommand = {
     command: 'check',

package/lib/commands/flatpak/build.js

@@ -3,9 +3,9 @@
 // Replaces the project-local `build-flatpak.sh`-style scripts: same flag
 // shape (manifest, build-dir, install, repo, bundle), plus a `--tarball`
 // helper for Flathub submissions.
-import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+import { spawnToCompletion } from '../../utils/spawn.js';
 export const flatpakBuildCommand = {
     command: 'build [manifest]',
     description: 'Build the Flatpak via `flatpak-builder`. Wraps a typical install + export + bundle + tarball pipeline.',
@@ -115,6 +115,12 @@ export const flatpakBuildCommand = {
             await runTar(['-czf', tarballPath, '-C', buildDir, '.'], { verbose: args.verbose });
         }
         console.log(`[gjsify flatpak build] done (${buildDir})`);
+        // Terminal command: exit explicitly. Under GJS the async `spawn` used
+        // above arms a GLib main loop (`ensureMainLoop`) that only
+        // `process.exit()` quits — returning here would park the CLI at 0% CPU
+        // after flatpak-builder had already finished. Same reason `foreach` /
+        // `workspace` / `check` end this way; see utils/spawn.ts.
+        return process.exit(0);
     },
 };
 /** Pick the first JSON file in cwd that looks like a Flatpak manifest. */
@@ -167,25 +173,20 @@ async function runFlatpak(args, opts) {
 async function runTar(args, opts) {
     return runProc('tar', args, opts, { notFoundHint: 'tar not found.' });
 }
-function runProc(cmd, args, opts, extra) {
+async function runProc(cmd, args, opts, extra) {
     if (opts.verbose) {
         console.log(`[gjsify flatpak] ${cmd} ${args.join(' ')}`);
     }
-    return new Promise((res, rej) => {
-        const child = spawn(cmd, args, { stdio: 'inherit' });
-        child.on('error', (err) => {
-            if (err.code === 'ENOENT') {
-                rej(new Error(`gjsify flatpak: ${extra.notFoundHint}`));
-            }
-            else {
-                rej(err);
-            }
-        });
-        child.on('exit', (code) => {
-            if (code === 0)
-                res();
-            else
-                rej(new Error(`gjsify flatpak: ${cmd} exited with status ${code}`));
-        });
+    // `completion: 'exit'` — the handler ends in `process.exit(0)` (added for
+    // exactly this reason), so the GLib main loop `spawn()` arms under GJS is
+    // quit on the way out and the STREAMING path stays available. That matters
+    // here more than anywhere: `flatpak-builder` runs for minutes and its live
+    // progress is the whole point of `stdio: 'inherit'`. See utils/spawn.ts.
+    const { code } = await spawnToCompletion(cmd, args, {
+        completion: 'exit',
+        notFound: () => new Error(`gjsify flatpak: ${extra.notFoundHint}`),
     });
+    if (code !== 0) {
+        throw new Error(`gjsify flatpak: ${cmd} exited with status ${code}`);
+    }
 }

package/lib/commands/foreach.js

@@ -8,7 +8,7 @@
 // Output is line-prefixed `[<workspace-name>]` when --parallel is set,
 // matching yarn's interactive flow. Exit code is non-zero if any child
 // process failed; first failure's stderr is forwarded.
-import { spawn } from 'node:child_process';
+import { spawnToCompletion } from '../utils/spawn.js';
 import { readFileSync, readdirSync } from 'node:fs';
 import { cpus } from 'node:os';
 import { buildDependencyGraph, discoverWorkspaces, filterWorkspaces, topologicalSort, } from '@gjsify/workspace';
@@ -602,47 +602,54 @@ function detectPackageManager() {
         return 'gjsify';
     return 'npm';
 }
-function spawnPrefixed(cmd, args, cwd, prefix) {
-    // Default FORCE_COLOR=1 unless the user explicitly opted out, so tools
-    // that key on `process.stdout.isTTY` (chalk, picocolors, …) still emit
-    // ANSI colors when run under gjsify foreach. Mirrors yarn / npm.
-    const colorEnv = process.env.FORCE_COLOR !== undefined || process.env.NO_COLOR !== undefined ? {} : { FORCE_COLOR: '1' };
-    return new Promise((resolve, reject) => {
-        const child = spawn(cmd, args, {
+async function spawnPrefixed(cmd, args, cwd, prefix) {
+    // `completion: 'exit'` — every path out of this command's handler ends in
+    // `process.exit(…)` (see the handler's tail), which is what quits the GLib
+    // main loop `spawn()` arms under GJS. That keeps foreach on the STREAMING
+    // async path: live prefixed output and real parallelism, both of which the
+    // blocking path would destroy. See utils/spawn.ts for the full contract.
+    let tracked = null;
+    const flushers = [];
+    try {
+        const result = await spawnToCompletion(cmd, args, {
+            completion: 'exit',
             cwd,
-            stdio: prefix ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-            env: { ...process.env, ...colorEnv },
+            stdio: prefix ? 'pipe' : 'inherit',
+            // Default FORCE_COLOR=1 unless the user explicitly opted out, so
+            // tools that key on `process.stdout.isTTY` (chalk, picocolors, …)
+            // still emit ANSI colors under gjsify foreach. Mirrors yarn / npm.
+            color: true,
+            onSpawn: (child) => {
+                tracked = child;
+                activeChildren.add(child);
+                // Under GJS, `process.stdout.write` is a BLOCKING
+                // `Gio.write_all`. Writing each prefixed line LIVE during a
+                // PARALLEL foreach to a backpressuring pipe (a CI log
+                // collector that drains slowly) stalls the single GLib main
+                // loop on a full pipe → every parallel child's pipe backs up →
+                // their reads stall → the whole run HANGS. (A tty or a file
+                // sink never backpressures, which is why it only bites in CI.)
+                // On a NON-tty sink we therefore BUFFER each child's prefixed
+                // output and flush it as ONE write when that child closes: the
+                // child is already done by then, so its own read can't stall,
+                // and concurrent flushes serialize into brief loop stalls
+                // instead of a deadlock. On a tty (interactive) we keep live
+                // line-prefixing for responsive output.
+                const buffered = !process.stdout.isTTY;
+                if (prefix && child.stdout && child.stderr) {
+                    flushers.push(prefixLines(child.stdout, process.stdout, prefix, buffered));
+                    flushers.push(prefixLines(child.stderr, process.stderr, prefix, buffered));
+                }
+            },
         });
-        activeChildren.add(child);
-        // Under GJS, `process.stdout.write` is a BLOCKING `Gio.write_all`.
-        // Writing each prefixed line LIVE during a PARALLEL foreach to a
-        // backpressuring pipe (a CI log collector that drains slowly) stalls
-        // the single GLib main loop on a full pipe → every parallel child's
-        // pipe backs up → their reads stall → the whole run HANGS. (A tty or a
-        // file sink never backpressures, which is why it only bites in CI.)
-        // On a NON-tty sink we therefore BUFFER each child's prefixed output
-        // and flush it as ONE write when that child closes: the child is
-        // already done by then, so its own read can't stall, and concurrent
-        // flushes serialize into brief loop stalls instead of a deadlock. On a
-        // tty (interactive) we keep live line-prefixing for responsive output.
-        const buffered = !process.stdout.isTTY;
-        const flushers = [];
-        if (prefix && child.stdout && child.stderr) {
-            flushers.push(prefixLines(child.stdout, process.stdout, prefix, buffered));
-            flushers.push(prefixLines(child.stderr, process.stderr, prefix, buffered));
+        for (const flush of flushers)
+            flush();
+        if (result.code !== 0) {
+            throw new Error(`${cmd} ${args.join(' ')} exited with code ${result.code}`);
         }
-        child.on('close', (code) => {
-            activeChildren.delete(child);
-            for (const flush of flushers)
-                flush();
-            if (code === 0)
-                resolve();
-            else
-                reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
-        });
-        child.on('error', (err) => {
-            activeChildren.delete(child);
-            reject(err);
-        });
-    });
+    }
+    finally {
+        if (tracked)
+            activeChildren.delete(tracked);
+    }
 }

package/lib/commands/info.js

@@ -20,11 +20,17 @@ export const infoCommand = {
         const cwd = process.cwd();
         const file = args.file ? resolve(args.file) : null;
         const nativePackages = detectNativePackages(cwd);
-        const { LD_LIBRARY_PATH, GI_TYPELIB_PATH } = buildNativeEnv(nativePackages);
+        // Which variables this yields is host-dependent: GI_TYPELIB_PATH
+        // everywhere, plus the loader path variable the host actually consults
+        // (LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS, PATH on
+        // Windows). Iterate rather than destructuring two fixed names, or the
+        // printed environment is wrong off Linux.
+        const nativeEnv = buildNativeEnv(nativePackages);
+        const envEntries = Object.entries(nativeEnv).filter(([, value]) => value !== undefined);
         if (args.export) {
             // Machine-readable output for eval
-            console.log(`export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}"`);
-            console.log(`export GI_TYPELIB_PATH="${GI_TYPELIB_PATH}"`);
+            for (const [key, value] of envEntries)
+                console.log(`export ${key}="${value}"`);
             return;
         }
         // Human-readable output
@@ -39,8 +45,8 @@ export const infoCommand = {
         }
         console.log('');
         console.log('To run your app directly with gjs, set:');
-        console.log(`  export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}"`);
-        console.log(`  export GI_TYPELIB_PATH="${GI_TYPELIB_PATH}"`);
+        for (const [key, value] of envEntries)
+            console.log(`  export ${key}="${value}"`);
         if (file) {
             console.log(`  gjs -m ${file}`);
         }

package/lib/commands/install.d.ts

@@ -14,4 +14,20 @@ interface InstallOptions {
     timeout: number;
 }
 export declare const installCommand: Command<unknown, InstallOptions>;
+export declare function buildBinShim(wsLocation: string, nodeTarget?: string, gjsTarget?: string, nativePrebuildDirs?: string[], platform?: string): string;
+/**
+ * `.cmd` / `.ps1` companions for {@link buildBinShim}.
+ *
+ * The `sh` shim's gjs-first / node-fallback probe has no Windows counterpart to
+ * express: there is no GJS host on Windows at all (no prebuilt `libgjs` — see
+ * `website/src/content/docs/platform-support.md`), so a workspace that ships
+ * both targets resolves to Node here, and a GJS-only workspace gets an honest
+ * `gjs`-invoking shim that fails exactly the way the `sh` one does.
+ *
+ * Exported + platform-free so it is unit-tested from Linux.
+ */
+export declare function buildWorkspaceBinShimsForWindows(wsLocation: string, nodeTarget?: string, gjsTarget?: string, nativePrebuildDirs?: string[]): {
+    cmd: string;
+    ps1: string;
+};
 export {};

package/lib/commands/install.js

@@ -30,18 +30,40 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawn, spawnSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { buildInstallCommand, detectPackageManager, runMinimalChecks } from '../utils/check-system-deps.js';
-import { detectNativePackages } from '../utils/detect-native-packages.js';
+import { detectNativePackages, libraryPathVar } from '../utils/detect-native-packages.js';
+import { buildLauncherShims } from '../utils/bin-shim.js';
 import { installPackages, makeProgressReporter } from '../utils/install-backend.js';
 import { atomicWriteStrict } from '../utils/install-cache-fs.js';
 import { acquireInstallLock } from '../utils/install-lock.js';
 import { nodeBinary } from '../utils/run-node.js';
+import { spawnToCompletion } from '../utils/spawn.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { binDirOnPath, defaultGlobalLayout, installGjsEnginePackages, linkGlobalBins, specToPackageName, } from '../utils/install-global.js';
 import { addDependencyEntry, defaultRangeFromVersion, parseSpec, projectSpecsFromPackageJson, readPackageJson, writePackageJson, } from '../utils/pkg-json-edit.js';
+/**
+ * Link type for the workspace↔workspace directory links.
+ *
+ * Windows cannot create a *directory symlink* without elevation or Developer
+ * Mode (`EPERM`), but any user can create an NTFS **junction** — which is why
+ * npm and yarn both use junctions for workspace links. These two call sites had
+ * no try/catch, so a non-elevated Windows workspace install hard-failed here.
+ */
+const WORKSPACE_LINK_TYPE = process.platform === 'win32' ? 'junction' : undefined;
+/**
+ * The `target` argument for a workspace link.
+ *
+ * Node normalises a `'junction'` target with `path.resolve()` — i.e. against
+ * the process CWD, NOT the link's own directory — so a junction MUST be given
+ * an absolute path. POSIX symlinks stay relative so the tree survives being
+ * moved.
+ */
+function workspaceLinkTarget(linkPath, absTarget) {
+    return WORKSPACE_LINK_TYPE === 'junction' ? resolve(absTarget) : relative(dirname(linkPath), absTarget);
+}
 // Default 30min wall-clock budget for the full install. Big workspaces
 // (212+ sub-packages × 600+ external deps in the gjsify monorepo itself)
 // can legitimately take 10-20 min on a fresh CI install when the npm CDN
@@ -621,7 +643,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
                     continue;
                 const linkPath = join(target.location, 'node_modules', link.depName);
                 parentDirs.add(dirname(linkPath));
-                const relTarget = relative(dirname(linkPath), link.targetLocation);
+                const relTarget = workspaceLinkTarget(linkPath, link.targetLocation);
                 plans.push({ linkPath, relTarget });
             }
             // Phase 1: one mkdir per unique parent (max ~213 instead of ~793).
@@ -638,13 +660,13 @@ async function workspaceInstallLocked(cwd, args, signal) {
                 // `{ recursive: true, force: true }` handles every shape (rm
                 // no-ops on missing paths under force; recursive covers dirs).
                 try {
-                    await fsp.rm(linkPath, { recursive: true, force: true });
+                    await fsp.rm(linkPath, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
                 }
                 catch {
                     /* unexpected; symlink call below will surface the real
                        cause if it persists. */
                 }
-                await fsp.symlink(relTarget, linkPath);
+                await fsp.symlink(relTarget, linkPath, WORKSPACE_LINK_TYPE);
             };
             for (let i = 0; i < Math.min(SYMLINK_CONCURRENCY, plans.length); i++) {
                 workers.push((async () => {
@@ -704,8 +726,7 @@ async function workspaceInstallLocked(cwd, args, signal) {
             if (existsHere)
                 continue;
             mkdirSync(dirname(linkPath), { recursive: true });
-            const relTarget = relative(dirname(linkPath), ws.location);
-            symlinkSync(relTarget, linkPath);
+            symlinkSync(workspaceLinkTarget(linkPath, ws.location), linkPath, WORKSPACE_LINK_TYPE);
             rootHoisted++;
         }
         if (rootHoisted > 0) {
@@ -912,16 +933,27 @@ function writeWorkspaceBinShims(cwd, workspaces) {
         mkdirSync(wsBinDir, { recursive: true });
         for (const [binName, { nodeTarget, gjsTarget }] of merged) {
             const linkPath = join(wsBinDir, binName);
-            try {
-                rmSync(linkPath, { force: true });
-            }
-            catch {
-                /* fine */
+            for (const file of [linkPath, `${linkPath}.cmd`, `${linkPath}.ps1`]) {
+                try {
+                    rmSync(file, { force: true, maxRetries: 10, retryDelay: 100 });
+                }
+                catch {
+                    /* fine */
+                }
             }
             writeFileSync(linkPath, buildBinShim(ws.location, nodeTarget, gjsTarget, nativePrebuildDirs), {
                 mode: 0o755,
             });
             chmodSync(linkPath, 0o755);
+            // Windows executes neither an extension-less file nor a `#!` line —
+            // the sh shim above is only reachable from git-bash/MSYS/WSL. Write
+            // the `.cmd`/`.ps1` companions cmd.exe and pwsh need, mirroring what
+            // npm's cmd-shim lays down next to every linked bin.
+            if (process.platform === 'win32') {
+                for (const [suffix, contents] of Object.entries(buildWorkspaceBinShimsForWindows(ws.location, nodeTarget, gjsTarget, nativePrebuildDirs))) {
+                    writeFileSync(`${linkPath}.${suffix}`, contents, { mode: 0o755 });
+                }
+            }
             wsBinsCreated++;
         }
     }
@@ -997,19 +1029,25 @@ function scopedOverrideFor(ws, depName, extracted) {
     }
     return undefined;
 }
-function buildBinShim(wsLocation, nodeTarget, gjsTarget, nativePrebuildDirs = []) {
+export function buildBinShim(wsLocation, nodeTarget, gjsTarget, nativePrebuildDirs = [], platform = process.platform) {
     const nodeAbs = nodeTarget ? join(wsLocation, nodeTarget) : null;
     const gjsAbs = gjsTarget ? join(wsLocation, gjsTarget) : null;
     // GJS-only env preamble — Node ignores GI_TYPELIB_PATH so we scope the
     // export to the gjs branch, keeping the shim minimal when no native pkgs
     // exist or only the Node bin is in play.
+    //
+    // The library-path variable is host-dependent: `dyld` on macOS never reads
+    // LD_LIBRARY_PATH, so exporting it there silently produced a launcher that
+    // could not load a single `darwin-arm64` prebuild. `libraryPathVar()` is the
+    // one place that mapping lives.
+    const { name: libVar } = libraryPathVar(platform);
     const gjsPreamble = nativePrebuildDirs.length === 0
         ? ''
         : (() => {
             const joined = `'${nativePrebuildDirs.join(':').replace(/'/g, `'\\''`)}'`;
             return (`GI_TYPELIB_PATH=${joined}\${GI_TYPELIB_PATH:+":$GI_TYPELIB_PATH"}\n` +
-                `LD_LIBRARY_PATH=${joined}\${LD_LIBRARY_PATH:+":$LD_LIBRARY_PATH"}\n` +
-                `export GI_TYPELIB_PATH LD_LIBRARY_PATH\n`);
+                `${libVar}=${joined}\${${libVar}:+":$${libVar}"}\n` +
+                `export GI_TYPELIB_PATH ${libVar}\n`);
         })();
     if (nodeAbs && gjsAbs) {
         // GJS-FIRST: prefer the committed Node-free GJS bundle when `gjs` is on
@@ -1039,6 +1077,37 @@ function buildBinShim(wsLocation, nodeTarget, gjsTarget, nativePrebuildDirs = []
         return `#!/bin/sh\n${gjsPreamble}exec gjs -m "${gjsAbs}" "$@"\n`;
     throw new Error('buildBinShim: either nodeTarget or gjsTarget must be provided');
 }
+/**
+ * `.cmd` / `.ps1` companions for {@link buildBinShim}.
+ *
+ * The `sh` shim's gjs-first / node-fallback probe has no Windows counterpart to
+ * express: there is no GJS host on Windows at all (no prebuilt `libgjs` — see
+ * `website/src/content/docs/platform-support.md`), so a workspace that ships
+ * both targets resolves to Node here, and a GJS-only workspace gets an honest
+ * `gjs`-invoking shim that fails exactly the way the `sh` one does.
+ *
+ * Exported + platform-free so it is unit-tested from Linux.
+ */
+export function buildWorkspaceBinShimsForWindows(wsLocation, nodeTarget, gjsTarget, nativePrebuildDirs = []) {
+    const nodeAbs = nodeTarget ? join(wsLocation, nodeTarget) : null;
+    const gjsAbs = gjsTarget ? join(wsLocation, gjsTarget) : null;
+    if (nodeAbs)
+        return buildLauncherShims({ interpreter: 'node', target: nodeAbs });
+    if (gjsAbs) {
+        // Windows has no dedicated library-path variable — LoadLibrary searches
+        // PATH — so the prebuild dirs go there, `;`-separated (which is also
+        // GLib's G_SEARCHPATH_SEPARATOR on Windows, hence the same join for
+        // GI_TYPELIB_PATH).
+        const joined = nativePrebuildDirs.join(';');
+        return buildLauncherShims({
+            interpreter: 'gjs',
+            interpreterArgs: ['-m'],
+            target: gjsAbs,
+            prependEnv: nativePrebuildDirs.length === 0 ? {} : { GI_TYPELIB_PATH: joined, PATH: joined },
+        });
+    }
+    throw new Error('buildWorkspaceBinShimsForWindows: either nodeTarget or gjsTarget must be provided');
+}
 /**
  * Walk a workspace's `bin` (Node) + `gjsify.bin` (GJS) declarations
  * into a unified `<binName> → {nodeTarget?, gjsTarget?}` map. The
@@ -1092,23 +1161,25 @@ async function projectInstallViaNpm(args) {
     await spawnNpm(npmArgs);
 }
 async function spawnNpm(npmArgs) {
-    return new Promise((resolve, reject) => {
-        const child = spawn('npm', npmArgs, { stdio: 'inherit' });
-        child.on('close', (code) => {
-            if (code === 0)
-                resolve();
-            else
-                reject(new Error(`npm install exited with code ${code}`));
-        });
-        child.on('error', (err) => {
-            const code = err.code;
-            const msg = code === 'ENOENT'
-                ? 'npm not found on PATH — install Node.js first.'
-                : `npm install failed: ${err.message}`;
-            reject(new Error(msg));
-        });
-    }).catch((err) => {
-        console.error(err.message);
+    // `completion: 'return'` — the `--backend npm` branch of the handler
+    // RETURNS after `runPostInstallChecks()` instead of exiting, so under GJS
+    // this must not leave the main loop `spawn()` arms parked (see
+    // utils/spawn.ts). The npm backend needs a Node host anyway, so the
+    // blocking path costs nothing in practice.
+    return spawnToCompletion('npm', npmArgs, {
+        completion: 'return',
+        notFound: () => new Error('npm not found on PATH — install Node.js first.'),
+    })
+        .then(({ code }) => {
+        if (code !== 0)
+            throw new Error(`npm install exited with code ${code}`);
+    })
+        .catch((err) => {
+        // A raw spawn failure still carries an errno `code`; the mapped
+        // not-found hint and the non-zero-exit error do not, and already
+        // read as finished sentences.
+        const errno = err.code;
+        console.error(errno === undefined ? err.message : `npm install failed: ${err.message}`);
         process.exit(1);
     });
 }