@gjsify/cli 0.22.0 → 0.24.1

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';
@@ -208,7 +208,7 @@ export const foreachCommand = {
         default: false,
     })
         .option('include', {
-        description: 'Glob pattern to include workspaces by name (repeatable).',
+        description: 'Glob pattern to include workspaces by name (repeatable). A pattern that matches NO discovered workspace is a hard error — a filter selecting nothing is a typo or a caller-side quoting bug, never an intent.',
         type: 'string',
         array: true,
     })
@@ -295,6 +295,7 @@ export const foreachCommand = {
                 process.exit(1);
             }
         }
+        assertEveryIncludeMatches(allWorkspaces, args.include);
         let selected = filterWorkspaces(allWorkspaces, {
             include: args.include,
             exclude: args.exclude,
@@ -344,6 +345,12 @@ export const foreachCommand = {
             }
         }
         if (selected.length === 0) {
+            // Reaching here means every --include pattern DID match something
+            // (assertEveryIncludeMatches above is fatal otherwise) and the set
+            // was then narrowed to nothing by --exclude, --no-private, the
+            // script-presence filter, or --shard. All four are legitimate, so
+            // this stays a clean exit-0 no-op — see the assert's doc comment
+            // for why the two cases are not the same condition.
             console.log(`gjsify foreach: no workspaces match (${exec ? 'exec' : 'script'}="${cmd}", include=${JSON.stringify(args.include ?? [])}, exclude=${JSON.stringify(args.exclude ?? [])})`);
             return;
         }
@@ -410,6 +417,69 @@ export const foreachCommand = {
         process.exit(0);
     },
 };
+/**
+ * A `--include` pattern that matches ZERO of the discovered workspaces is a
+ * hard error. This is the load-bearing half of the fix for repo task #75: the
+ * CI classifier emitted its filter pre-quoted (`--include '@gjsify/fs'`), the
+ * workflow expanded it unquoted inside a `su … -c "… sh -c '…'"` nesting, the
+ * apostrophes became part of every glob, and this command matched nothing,
+ * printed one line, and exited 0. A build that did nothing was indistinguishable
+ * from a build that succeeded, so the bug lived through every selective PR run
+ * — the Build step took 0.65 s and every later step inspected whatever the
+ * cache had restored. The quoting was the defect; the SILENCE is why nobody saw
+ * it.
+ *
+ * Scope is deliberately "an include PATTERN matched no workspace", NOT "the
+ * final selection is empty". The final selection is legitimately empty in
+ * several supported situations and must stay exit-0:
+ *   * `--shard 3/4` over a 2-workspace closure — most shards run nothing;
+ *   * `--exclude '@gjsify/integration-*'` removing everything the include kept;
+ *   * script mode dropping workspaces that don't declare `<script>` (yarn does
+ *     this too, and it is why `foreach check` over a closure of script-less
+ *     packages is a no-op rather than a failure).
+ * All three describe a real, existing set being narrowed to nothing. A pattern
+ * that names something the workspace tree does not contain is different in
+ * kind: it is a typo, a stale package name, or a caller-side quoting bug, and
+ * it can never be what the caller meant. There is no opt-out flag — an escape
+ * hatch here would be re-arming exactly the silence this exists to remove.
+ */
+function assertEveryIncludeMatches(allWorkspaces, include) {
+    if (!include || include.length === 0)
+        return;
+    const unmatched = include.filter((pattern) => filterWorkspaces(allWorkspaces, { include: [pattern] }).length === 0);
+    if (unmatched.length === 0)
+        return;
+    const lines = [
+        `gjsify foreach: --include matched no workspace (${unmatched.length} of ${include.length} pattern(s)):`,
+    ];
+    for (const pattern of unmatched) {
+        lines.push(`  ${JSON.stringify(pattern)}`);
+        // The task-#75 signature: the pattern only fails because the caller's
+        // shell quotes ended up INSIDE the value. Name it outright — that
+        // failure reads as "package not found" and sends people hunting in the
+        // wrong place.
+        const unquoted = stripSurroundingQuotes(pattern);
+        if (unquoted !== pattern && filterWorkspaces(allWorkspaces, { include: [unquoted] }).length > 0) {
+            lines.push(`    → matches as ${JSON.stringify(unquoted)}: the QUOTES are part of the value. A shell expansion`, `      is not re-scanned for quoting, so a pre-quoted filter spliced through \`sh -c\` arrives with`, `      the quotes attached. Pass the bare name and let word splitting do the work.`);
+            continue;
+        }
+        const near = allWorkspaces
+            .map((w) => w.name)
+            .filter((name) => name.toLowerCase().includes(unquoted.replace(/\*/g, '').toLowerCase()))
+            .slice(0, 3);
+        if (near.length > 0)
+            lines.push(`    → did you mean: ${near.join(', ')}?`);
+    }
+    lines.push(`  ${allWorkspaces.length} workspace(s) discovered. Refusing to run: a filter that selects nothing would`, `  otherwise exit 0 and look exactly like a successful run over the whole set.`);
+    console.error(lines.join('\n'));
+    process.exit(1);
+}
+/** Drop ONE matching pair of surrounding `'` or `"` — the quoting-bug probe. */
+function stripSurroundingQuotes(s) {
+    if (s.length >= 2 && (s[0] === "'" || s[0] === '"') && s[s.length - 1] === s[0])
+        return s.slice(1, -1);
+    return s;
+}
 async function runSequential(workspaces, script, args, verbose, exec, cache) {
     for (const ws of workspaces) {
         await runOne(ws, script, args, /* prefixOutput */ false, verbose, exec, cache);
@@ -602,47 +672,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
@@ -183,10 +205,26 @@ export const installCommand = {
         const hardExitTimerId = overallTimeoutMs > 0
             ? setTimeout(() => {
                 const secs = Math.round(overallTimeoutMs / 100) / 10;
-                console.error(`gjsify install: still stuck ${Math.round(HARD_EXIT_GRACE_MS / 1000)}s after the ${secs}s ` +
-                    `budget elapsed and the in-flight aborts — forcing exit. A dependency's extract or ` +
-                    `link step wedged (typically a dropped Gio stream event under GJS). Re-run; if it ` +
-                    `persists, raise --timeout or file an issue.`);
+                // Do NOT assert a cause here — this timer cannot tell the
+                // two shapes apart, and claiming the rarer one sends the
+                // next reader after a bug that isn't there. Measured on a
+                // cold tree of this workspace: 1597 packages / ~4.8 GB
+                // extracted, of which ~3.4 GB are foreign-platform
+                // optional deps (`os`/`cpu` excludes the host) that npm
+                // would never place. That install was still making steady
+                // progress when the 30-min budget elapsed, and a re-run
+                // finished the remainder in ~2 min. Extraction also has
+                // multi-second SYNCHRONOUS stretches (tar parse + file
+                // writes) and 16 run concurrently, so the clean abort path
+                // can easily miss the grace window with nothing wedged.
+                console.error(`gjsify install: the ${secs}s budget elapsed and the abort did not unwind within ` +
+                    `${Math.round(HARD_EXIT_GRACE_MS / 1000)}s — forcing exit. That means one of two ` +
+                    `things, and this timer cannot distinguish them: the install was still WORKING ` +
+                    `(a cold tree here extracts several GB, and extraction blocks the loop in ` +
+                    `multi-second synchronous stretches), or a step genuinely wedged. Re-running tells ` +
+                    `you which, and is safe: extraction is idempotent, every package already on disk ` +
+                    `is skipped, so a second run finishes the remainder in a fraction of the time. A ` +
+                    `re-run that makes NO further progress is a real wedge — file an issue.`);
                 forceExit(1);
             }, overallTimeoutMs + HARD_EXIT_GRACE_MS)
             : null;
@@ -621,7 +659,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 +676,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 +742,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 +949,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 +1045,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 +1093,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 +1177,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);
     });
 }

package/lib/commands/onboard.js

@@ -27,6 +27,7 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { DEFAULT_REGISTRY, whoami } from '@gjsify/npm-registry';
 import { discoverWorkspaces, filterWorkspaces } from '@gjsify/workspace';
+import { mergePublishables } from '../utils/publishable-packages.js';
 import { hasAnyCredential, loadNpmrc } from '../utils/load-npmrc.js';
 import { OtpProvider } from '../utils/npm-otp.js';
 import { publishWorkspace } from './publish.js';
@@ -142,7 +143,11 @@ export const onboardCommand = {
         const environment = args.environment;
         // 2. Enumerate publishable workspaces (non-private, exclude @girs/*).
         const root = findWorkspaceRoot(cwd) ?? cwd;
-        const all = discoverWorkspaces(root, { includeRoot: true });
+        // Non-workspace publishables (packages/{node-gi,napi}/*) publish through
+        // release.yml but `discoverWorkspaces` cannot see them — without this
+        // merge the sweep reports "all done" while a package that was never
+        // published is simply absent from the list.
+        const all = mergePublishables(discoverWorkspaces(root, { includeRoot: true }), cwd);
         const selected = filterWorkspaces(all, { noPrivate: true, exclude: ['@girs/*'] }).filter((ws) => ws.name);
         if (selected.length === 0) {
             const msg = 'gjsify onboard: no publishable workspace packages found.';

package/lib/commands/pack.js

@@ -29,6 +29,7 @@ import { join, resolve } from 'node:path';
 import { createTarball, gzip } from '@gjsify/tar';
 import { discoverWorkspaces } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { readPackageJson } from '../utils/pkg-json.js';
 import { runLifecycleScript } from '../utils/run-lifecycle-script.js';
 export const packCommand = {
     command: 'pack [path]',
@@ -488,23 +489,87 @@ function globToRegex(glob) {
     pat = pat.replace(/\?/g, '[^/]');
     return new RegExp(`^${pat}($|/)`);
 }
+const DEP_BLOCKS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+/** Every `<block>.<name>` in `pkg` whose range uses the `workspace:` protocol. */
+function collectWorkspaceProtocolDeps(pkg) {
+    const found = [];
+    for (const block of DEP_BLOCKS) {
+        const deps = pkg[block];
+        if (!deps)
+            continue;
+        for (const [name, range] of Object.entries(deps)) {
+            if (typeof range === 'string' && range.startsWith('workspace:'))
+                found.push(`${block}.${name}`);
+        }
+    }
+    return found;
+}
+/**
+ * Monorepo root to resolve `workspace:` ranges against.
+ *
+ * `findWorkspaceRoot` is deliberately strict: it only accepts a candidate root
+ * whose OWN `workspaces` globs list `start` as a member (so an unrelated
+ * grand-parent monorepo can't be picked up). Packing needs a WIDER answer,
+ * because some packages live inside the monorepo on purpose WITHOUT being
+ * members — `packages/napi/**` and `packages/node-gi/**` are excluded from
+ * `package.json#workspaces` (own CI, own release cadence, see AGENTS.md). For
+ * those the strict lookup returns `null`, and the pre-fix code took that as
+ * "nothing to do" and shipped the literal `workspace:^` string.
+ *
+ * So: strict answer first, else the nearest ancestor that declares
+ * `workspaces` at all — the monorepo the package physically lives in, whose
+ * members are exactly the siblings a `workspace:` range can refer to.
+ */
+function findPackWorkspaceRoot(start) {
+    const strict = findWorkspaceRoot(start);
+    if (strict)
+        return strict;
+    let dir = start;
+    for (let i = 0; i < 12; i++) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath) && readPackageJson(pkgPath)?.workspaces !== undefined)
+            return dir;
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
 /**
  * Walk pkg.dependencies / devDependencies / peerDependencies /
  * optionalDependencies and replace `workspace:^` / `workspace:~` /
  * `workspace:*` ranges with the resolved npm range based on each sibling
  * workspace's version field.
+ *
+ * A `workspace:` range that survives into a published tarball is unresolvable
+ * by EVERY registry client (`npm install` fails with `Unsupported URL Type
+ * "workspace:"`), so there is no such thing as a harmless skip here: this
+ * either substitutes or throws. Same failure mode, same reasoning as
+ * `expandFilesPatterns` above — a packer that silently produces a broken
+ * tarball costs a whole release train (v0.4.20, v0.4.37).
  */
 function rewriteWorkspaceDeps(pkg, wsDir) {
-    const root = findWorkspaceRoot(wsDir);
-    if (!root)
+    const root = findPackWorkspaceRoot(wsDir);
+    if (!root) {
+        // No enclosing monorepo. Fine for a standalone package — but then a
+        // `workspace:` range cannot possibly be resolved, so refuse rather
+        // than ship it.
+        const unresolvable = collectWorkspaceProtocolDeps(pkg);
+        if (unresolvable.length > 0) {
+            throw new Error(`gjsify pack: ${String(pkg.name)} declares workspace: ranges (${unresolvable.join(', ')}) ` +
+                `but ${wsDir} is not inside a monorepo (no ancestor package.json declares "workspaces"). ` +
+                `A workspace: range cannot be published — replace it with a real npm range, or pack from within the monorepo.`);
+        }
         return pkg;
+    }
     const siblings = new Map();
     for (const ws of discoverWorkspaces(root)) {
         if (ws.name && ws.version)
             siblings.set(ws.name, ws.version);
     }
     const cloned = JSON.parse(JSON.stringify(pkg));
-    for (const block of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+    for (const block of DEP_BLOCKS) {
         const deps = cloned[block];
         if (!deps)
             continue;
@@ -513,7 +578,7 @@ function rewriteWorkspaceDeps(pkg, wsDir) {
                 continue;
             const wsVer = siblings.get(name);
             if (!wsVer) {
-                throw new Error(`gjsify pack: ${cloned.name} declares workspace:^ on ${name} but no sibling workspace with that name exists in the monorepo at ${root}`);
+                throw new Error(`gjsify pack: ${cloned.name} declares ${range} on ${name} (${block}) but no sibling workspace with that name exists in the monorepo at ${root}`);
             }
             const operator = range.slice('workspace:'.length);
             if (operator === '*' || operator === '') {