@gjsify/cli 0.35.0 → 0.37.0

package/lib/utils/system-gi.js

@@ -3,110 +3,65 @@
 // dynamic loader can find the ones a typelib names by BARE LEAF
 // (`libgtk-4.1.dylib`, `libgdk_pixbuf-2.0.0.dylib`, …).
 //
-// ── A DELIBERATE MIRROR ──────────────────────────────────────────────────────
+// A PINNED MIRROR of `packages/node-gi/node-gi/system-gi.js` — the two must agree
+// and `system-gi.spec.ts` asserts it over a table of injected host shapes. Why a
+// mirror and not an import, and what is owed to retire it:
+// `status/open-todos.md` § "systemGiLibraryDirs() lives in two places".
 //
-// This is a PINNED PORT of `packages/node-gi/node-gi/system-gi.js`. The two must
-// agree, and `system-gi.spec.ts` is the check: it imports node-gi's copy by
-// relative path and asserts both return identical arrays for a table of injected
-// inputs. That is the same shape `impliedExampleNodeEntry()` in
-// `@gjsify/manifest-conformance` uses for `resolveNodeEntry()` in this package —
-// "this is the check, that is the consumer".
+// WHY THIS EXISTS. A failed `dlopen('libgtk-4.1.dylib')` surfaces one layer up as
+// something that reads like a type-system bug — `TypeError: Gtk.DrawingArea is not
+// a subclassable GObject type` under Node, `Error: Unsupported type void, deriving
+// from fundamental void` under a bare `gjs -c "imports.gi.Gtk; Gtk.init()"`:
+// `gi_repository_require` resolves the typelib, `g_module_open` then fails, and no
+// `gtk_*_get_type` is ever registered.
 //
-// Why a mirror and not an import: ADR 0005 Decision 2 forbids any Tier-1/Tier-2
-// package taking a `dependencies`/`optionalDependencies` edge on
-// `@gjsify/node-gi`, and `@gjsify/cli` is Tier 1. The alternative — lifting the
-// module into a new shared npm name — is the documented expensive path (manual
-// first publish + Trusted Publisher bootstrap; the `@gjsify/tls-native` incident
-// stalled 60+ packages), so it is tracked in `status/open-todos.md` instead of
-// taken here. A spec may reach across the repo because it is never bundled into
-// the published `lib/`, which is what lets the agreement be machine-checked
-// without creating the forbidden edge.
+// The gap is the LOADER, not the installation (measured on macOS 15.7.8 / Homebrew
+// /usr/local / GTK 4.22.4). `node` has no rpath; Homebrew's `gjs` has one into
+// GLIB's keg alone (`…/opt/glib/lib`), so it resolves the glib-family leaves it
+// links against and no other keg's. `/usr/local/lib`, where `libgtk-4.1.dylib`
+// actually is, is in neither, nor in dyld's default fallback path.
 //
-// ── WHY THIS EXISTS ──────────────────────────────────────────────────────────
-//
-// Measured twice, on the same class of host, in two runtimes:
-//
-// 1. Node (macOS 15.7.8 / Homebrew /usr/local / Node 24.18.1 / GTK 4.22.4, the
-//    first release that shipped a darwin-x64 addon) — this is node-gi's report:
-//
-//        GLib-GIRepository-WARNING: Failed to load shared library 'libgtk-4.1.dylib'
-//          referenced by the typelib: dlopen(libgtk-4.1.dylib, 0x0009): tried:
-//          'libgtk-4.1.dylib' (no such file), …, '/usr/lib/libgtk-4.1.dylib' (no such file)
-//        TypeError: Gtk.DrawingArea is not a subclassable GObject type
-//
-// 2. GJS (same VM, gjs 1.88.1, `gjs -c "imports.gi.Gtk; Gtk.init()"`, nothing
-//    gjsify in the process at all) — the reason this CLI needs the module too:
-//
-//        dlopen(libgtk-4.1.dylib, 0x0009): tried: 'libgtk-4.1.dylib' (no such file),
-//          '/System/Volumes/Preboot/Cryptexes/OSlibgtk-4.1.dylib' (no such file),
-//          '/usr/local/Cellar/gjs/1.88.1/bin/../../../../opt/glib/lib/libgtk-4.1.dylib'
-//            (no such file), '/usr/lib/libgtk-4.1.dylib' (no such file, not in dyld cache)
-//        JS ERROR: Error: Unsupported type void, deriving from fundamental void
-//
-// Read the third path dyld tried: Homebrew's `gjs` binary has an rpath, and it
-// points into GLIB's keg (`…/opt/glib/lib`) — nowhere else. So Homebrew's gjs
-// resolves the glib-family leaves it links against and NO other keg's. The
-// difference between the two reports is cosmetic, not structural: `node` has no
-// rpath at all, `gjs` has one into the wrong keg, and `/usr/local/lib` — where
-// `libgtk-4.1.dylib` actually is — is in neither, nor in dyld's default fallback
-// path. The gap is the LOADER, not the installation: `gi_repository_require`
-// resolves the typelib, `g_module_open('libgtk-4.1.dylib')` then fails, no
-// `gtk_*_get_type` is ever registered, and the failure surfaces one layer up as
-// something that reads like a type-system bug.
-//
-// The value CANNOT come from `pkg-config --variable=libdir gtk4`. Measured on the
-// same host: that answers `/usr/local/Cellar/gtk4/4.22.4/lib` — a PER-FORMULA
-// directory that fixes GTK and leaves `libgdk_pixbuf-2.0.0.dylib` (a different
-// formula, so a different Cellar libdir) still unresolvable. What works is the
-// directory every keg is symlinked into, `<prefix>/lib`, because it is the UNION.
-// So the question this module answers is "which directories hold the GI stack",
-// never "where is one library".
+// The value CANNOT come from `pkg-config --variable=libdir gtk4`: that answers
+// `/usr/local/Cellar/gtk4/4.22.4/lib`, a PER-FORMULA directory that fixes GTK and
+// leaves `libgdk_pixbuf-2.0.0.dylib` (different formula, different Cellar libdir)
+// unresolvable. What works is `<prefix>/lib`, the UNION every keg is symlinked into.
+// The question is "which directories hold the GI stack", never "where is one library".
 //
 // THE RULE — a typelib and the library it names are SIBLINGS by GI's own install
 // layout: `<libdir>/girepository-1.0/Gtk-4.0.typelib` beside
-// `<libdir>/libgtk-4.1.dylib`. A directory holding `girepository-1.0/` therefore
-// IS a GI library directory. That convention is what makes this
-// package-manager-agnostic: it lands on `/usr/local/lib` (Homebrew x64),
-// `/opt/homebrew/lib` (Homebrew arm64), `/opt/local/lib` (MacPorts) or a custom
-// prefix without needing to know that any of them exist.
+// `<libdir>/libgtk-4.1.dylib`. A directory holding `girepository-1.0/` therefore IS
+// a GI library directory, which is what makes this package-manager-agnostic — it
+// lands on Homebrew, MacPorts or a custom prefix without knowing any of them exist.
 //
 // PURE FUNCTION of injected host facts (platform / env / fs / pkg-config), like
-// `resolvePrebuildDirName()` and `buildNativeEnv()` beside it — so the darwin
-// branch is unit-testable from a Linux host and the host values are read only at
-// the outermost call site, as defaults.
-//
-// ── HOW THE CONSUMER DIFFERS FROM NODE-GI'S ──────────────────────────────────
+// `resolvePrebuildDirName()` and `buildNativeEnv()` beside it, so the darwin branch
+// is unit-testable from Linux.
 //
-// node-gi RE-EXECS its own process with the result on `DYLD_FALLBACK_LIBRARY_PATH`,
-// because dyld captures that variable at process LAUNCH and an in-process
-// `process.env` mutation therefore does nothing. This CLI never needs a re-exec:
-// it is the one LAUNCHING the gjs child (`buildNativeEnv()` →
-// `spawn('gjs', …, { env })`), so it sets the variable in the child's launch env,
-// which is the same repair one hop earlier. A launcher could not fix this from
-// inside the bundle either way — GI resolves typelibs and their backers before the
-// bundle's first line runs.
+// node-gi RE-EXECS itself with the result on `DYLD_FALLBACK_LIBRARY_PATH`, because
+// dyld captures that variable at process LAUNCH and an in-process `process.env`
+// mutation does nothing. This CLI needs no re-exec: it is the one LAUNCHING the gjs
+// child (`buildNativeEnv()` → `spawn('gjs', …, { env })`), the same repair one hop
+// earlier. A launcher inside the bundle could not fix it either way — GI resolves
+// typelibs and their backers before the bundle's first line runs.
 import { spawnSync } from 'node:child_process';
 import { statSync } from 'node:fs';
-// POSIX path semantics, not the HOST's. This function answers a question about
-// a darwin filesystem — `platform` is a PARAMETER, so the host running the code
-// may be any of the three. Node's default `join`/`dirname`/`basename` follow the
-// host, so on win32 `join('/usr/local/lib', 'girepository-1.0')` becomes
-// `\usr\local\lib\girepository-1.0` and never matches the darwin path the
-// caller (or the injected `existsDir`) is holding. Measured on the Windows leg:
-// three `systemGiLibraryDirs` specs returned `[]` where they assert a prefix.
-// `PROBED_GI_LIBDIRS` is darwin-only, so POSIX is always the right dialect here.
+// POSIX path semantics, not the HOST's: `platform` is a PARAMETER, so this answers
+// a question about a darwin filesystem from any host. Node's host-following
+// `join` turns `join('/usr/local/lib', 'girepository-1.0')` into
+// `\usr\local\lib\girepository-1.0` on win32, matching nothing the caller (or the
+// injected `existsDir`) holds — measured on the Windows leg, three
+// `systemGiLibraryDirs` specs returned `[]` where they assert a prefix.
 import { posix } from 'node:path';
 const { basename, dirname, join } = posix;
 /**
  * Prefixes a macOS GI stack is installed under in practice — probed, never
  * assumed: each is accepted only when it actually holds a `girepository-1.0/`.
  *
- * This is the no-pkg-config safety net, and it is load-bearing rather than
- * belt-and-braces: `brew install gtk4` installs RUNTIME dependencies only, so a
- * user running a published showcase routinely has the entire GTK stack and no
- * `pkg-config` at all (it is a BUILD dependency of those formulae). The
- * pkg-config source below is the GENERAL mechanism — it is what finds a jhbuild
- * or otherwise bespoke prefix — but it cannot be the only one.
+ * Load-bearing rather than belt-and-braces: `brew install gtk4` installs RUNTIME
+ * dependencies only, so a user running a published showcase routinely has the
+ * whole GTK stack and no `pkg-config` at all (a BUILD dependency of those
+ * formulae). The pkg-config source below is the general mechanism — it finds a
+ * jhbuild or otherwise bespoke prefix — but it cannot be the only one.
  */
 const PROBED_GI_LIBDIRS = {
     darwin: ['/opt/homebrew/lib', '/usr/local/lib', '/opt/local/lib'],
@@ -115,9 +70,7 @@ const PROBED_GI_LIBDIRS = {
 const TYPELIB_SUBDIR = 'girepository-1.0';
 /** Memoized `pkg-config` answer: the spawn happens at most once per process. */
 let pkgConfigDirsCache = null;
-/**
- * Split an OS search-path variable, dropping empty segments.
- */
+/** Split an OS search-path variable, dropping empty segments. */
 export function splitSearchPath(value, separator = ':') {
     return (value ?? '').split(separator).filter(Boolean);
 }
@@ -134,15 +87,12 @@ function isDirectory(dir) {
 /**
  * `pkg-config`'s OWN configured `.pc` search path plus `$PKG_CONFIG_PATH`. Every
  * entry is a `<libdir>/pkgconfig` (or `<datadir>/pkgconfig`) directory, so its
- * parent is a candidate libdir — which is how a prefix nobody hardcoded is
- * found. Measured on the reported host: `pc_path` =
- * `/usr/local/lib/pkgconfig:/usr/local/share/pkgconfig:/usr/lib/pkgconfig:…`,
- * whose first parent is exactly the `/usr/local/lib` that resolves every leaf.
+ * parent is a candidate libdir — which is how a prefix nobody hardcoded is found.
  *
- * `spawnSync` reports a missing executable as `result.error`, not by throwing —
- * an absent `pkg-config` is expected on a runtime-only GTK install, so it is a
- * checked return value here and not an exception path. (`@gjsify/child_process`
- * matches Node here deliberately; see its `spawnSync` note.)
+ * `spawnSync` reports a missing executable as `result.error`, not by throwing, so
+ * an absent `pkg-config` (expected on a runtime-only GTK install) is a checked
+ * return value and not an exception path. (`@gjsify/child_process` matches Node
+ * here deliberately; see its `spawnSync` note.)
  */
 export function pkgConfigSearchDirs(env) {
     if (pkgConfigDirsCache)
@@ -172,19 +122,16 @@ export function pkgConfigSearchDirs(env) {
  * Sources 2 and 3 are GUESSES at a prefix, so each must show the
  * `girepository-1.0/` marker before it is believed.
  *
- * Empty off darwin, and that is a statement about LOADERS, not about GI. Linux
- * resolves these leaves through `ld.so`'s system-wide configured cache
- * (`/etc/ld.so.conf.d`), which a package install populates — nothing per-process
- * is needed. dyld is the one loader that neither consults a system-wide config
- * NOR re-reads its search path after launch, which is why darwin needs the
- * variable set at launch and nobody else does.
+ * Empty off darwin, and that is a statement about LOADERS, not about GI: Linux
+ * resolves these leaves through `ld.so`'s system-wide cache (`/etc/ld.so.conf.d`),
+ * which a package install populates. dyld is the one loader that neither consults
+ * a system-wide config NOR re-reads its search path after launch.
  *
- * win32 is deliberately absent rather than proven unnecessary: `PATH` is the DLL
- * search path, a Windows GTK distribution puts its `bin` there itself, and
- * Windows re-reads that path at every `LoadLibrary` — so if a system GTK ever
- * turns out not to be on it, the repair is a `PATH` prepend (which
- * {@link buildNativeEnv} already does for the prebuilds), never a second
- * variable. Untested there.
+ * win32 is deliberately absent rather than proven unnecessary, and untested:
+ * `PATH` is the DLL search path, a Windows GTK distribution puts its `bin` there
+ * itself, and Windows re-reads that path at every `LoadLibrary` — so if a system
+ * GTK ever turns out not to be on it, the repair is a `PATH` prepend (which
+ * {@link buildNativeEnv} already does for the prebuilds), never a second variable.
  *
  * @returns absolute directories, or `[]` when this platform's loader needs none
  */
@@ -220,10 +167,9 @@ export function systemGiLibraryDirs({ platform = process.platform, env = process
  * Whether `current` (a split `DYLD_FALLBACK_LIBRARY_PATH`) already covers every
  * directory in `wanted` — the "nothing to do" test.
  *
- * Kept in the port even though this CLI's consumer does not branch on it: the
- * mirror's value is that the two files are the SAME file, and a surface that
- * drifts by one export is a mirror nobody can check. `system-gi.spec.ts` pins
- * both.
+ * Kept in the port even though this CLI's consumer does not branch on it: a mirror
+ * that drifts by one export is a mirror nobody can check. `system-gi.spec.ts`
+ * pins both.
  */
 export function pathCovers(wanted, current) {
     return wanted.every((dir) => current.includes(dir));

package/lib/utils/trust-registry.d.ts

@@ -29,9 +29,8 @@ export interface TrustEntry {
     };
 }
 /**
- * The POST body for `trust github`. npm always sends an ARRAY with a single
- * config object carrying `type`, `claims` AND `permissions` (the last is
- * required — `--allow-publish` → `['createPackage']`).
+ * The POST body for `trust github`: npm always sends an ARRAY with a single config object, and
+ * `permissions` is required alongside `type`/`claims`.
  */
 export declare function githubTrustBody(opts: {
     repository: string;
@@ -62,10 +61,7 @@ export declare function classifyTrustList(status: number, body: unknown, opts: {
     workflow: string;
 }): TrustState;
 /**
- * Derive `owner/repo` from a git remote URL. Handles the common GitHub forms:
- *   git@github.com:owner/repo.git
- *   ssh://git@github.com/owner/repo.git
- *   https://github.com/owner/repo(.git)
- * Returns null when it can't confidently extract two segments.
+ * Derive `owner/repo` from a git remote URL (scp-like `git@host:owner/repo.git` and the
+ * `ssh://`/`https://` forms). Null when two segments cannot be confidently extracted.
  */
 export declare function parseRepoFromGitRemote(url: string): string | null;

package/lib/utils/trust-registry.js

@@ -5,9 +5,8 @@
 //   github: POST   <registry>/-/package/<escaped>/trust            body: [{type,claims}]
 //   revoke: DELETE <registry>/-/package/<escaped>/trust/<id>
 //
-// Everything here is side-effect-free so it can be unit-tested without a
-// network; the command (commands/trust.ts) does the fetch + OTP orchestration.
-// Reference: refs/npm-cli/lib/trust-cmd.js + lib/commands/trust/*.js.
+// Side-effect-free so it unit-tests without a network; `commands/trust.ts` does the fetch + OTP
+// orchestration. Reference: refs/npm-cli/lib/trust-cmd.js + lib/commands/trust/*.js.
 import { escapePackageName } from './publish-headers.js';
 /** `<registry>/-/package/<@scope%2fname>/trust`. */
 export function trustUrl(registry, pkgName) {
@@ -25,9 +24,8 @@ export function trustRevokeUrl(registry, pkgName, id) {
 export const PERMISSION_PUBLISH = 'createPackage';
 export const PERMISSION_STAGE_PUBLISH = 'createStagedPackage';
 /**
- * The POST body for `trust github`. npm always sends an ARRAY with a single
- * config object carrying `type`, `claims` AND `permissions` (the last is
- * required — `--allow-publish` → `['createPackage']`).
+ * The POST body for `trust github`: npm always sends an ARRAY with a single config object, and
+ * `permissions` is required alongside `type`/`claims`.
  */
 export function githubTrustBody(opts) {
     const claims = {
@@ -77,24 +75,18 @@ export function classifyTrustList(status, body, opts) {
     return 'error';
 }
 /**
- * Derive `owner/repo` from a git remote URL. Handles the common GitHub forms:
- *   git@github.com:owner/repo.git
- *   ssh://git@github.com/owner/repo.git
- *   https://github.com/owner/repo(.git)
- * Returns null when it can't confidently extract two segments.
+ * Derive `owner/repo` from a git remote URL (scp-like `git@host:owner/repo.git` and the
+ * `ssh://`/`https://` forms). Null when two segments cannot be confidently extracted.
  */
 export function parseRepoFromGitRemote(url) {
     let s = url.trim();
     if (!s)
         return null;
-    // Strip a trailing .git
     s = s.replace(/\.git$/, '');
-    // scp-like: git@host:owner/repo
     const scp = s.match(/^[^/@]+@[^:]+:(.+)$/);
     if (scp) {
         return twoSegments(scp[1]);
     }
-    // URL forms: ssh://, https://, http://, git://
     const m = s.match(/^[a-z]+:\/\/[^/]+\/(.+)$/i);
     if (m) {
         return twoSegments(m[1]);
@@ -105,6 +97,6 @@ function twoSegments(path) {
     const parts = path.split('/').filter((p) => p.length > 0);
     if (parts.length < 2)
         return null;
-    // owner/repo are the LAST two segments (handles nested groups → take repo + its owner)
+    // The LAST two segments, so a nested group path still yields repo + its owner.
     return `${parts[parts.length - 2]}/${parts[parts.length - 1]}`;
 }

package/lib/utils/win32-command.d.ts

@@ -21,10 +21,9 @@ export interface Win32ResolveContext {
 /**
  * Read `name` from `env` case-insensitively.
  *
- * Windows environment variables are case-insensitive and `process.env` mirrors
- * that, but a plain object handed in as `env` (which is what every spawn call
- * site builds) does not — a child env carrying `Path` rather than `PATH` would
- * otherwise silently resolve nothing.
+ * Windows env vars are case-insensitive and `process.env` mirrors that, but a plain object —
+ * what every spawn call site builds — does not, so a child env carrying `Path` rather than
+ * `PATH` would silently resolve nothing.
  */
 export declare function lookupEnv(env: NodeJS.ProcessEnv, name: string): string | undefined;
 /** Escape a command path for cmd.exe. Port of cross-spawn's `escape.command`. */
@@ -35,20 +34,15 @@ export declare function escapeCmdCommand(arg: string): string;
  */
 export declare function escapeCmdArgument(arg: string, doubleEscapeMetaChars?: boolean): string;
 /**
- * Build the `cmd.exe /d /s /c "…"` invocation for a resolved, non-directly-
- * executable target. Pure — the unit tests drive this from any host.
- *
- * @param commandFile Resolved absolute path of the target (e.g. the `.cmd` shim).
- * @param args The caller's arguments, unescaped.
- * @param comspec The interpreter, normally `%COMSPEC%`.
+ * Build the `cmd.exe /d /s /c "…"` invocation for a resolved, non-directly-executable target.
+ * `args` are the caller's UNESCAPED arguments; `comspec` is normally `%COMSPEC%`.
  */
 export declare function buildCmdExeInvocation(commandFile: string, args: readonly string[], comspec?: string): Win32Invocation;
 /**
  * Rewrite a bare command name into something Windows can actually spawn.
  *
- * Returns `undefined` when nothing needs rewriting — not win32, not a bare
- * name, or not found on `PATH`. The last case is deliberate: letting `spawn`
- * fail with `ENOENT` preserves the contract callers key their install hints on
- * (see the module header).
+ * `undefined` when nothing needs rewriting — not win32, not a bare name, or not found on
+ * `PATH`. The last case is deliberate: letting `spawn` fail with `ENOENT` preserves the
+ * contract callers key their install hints on (see the module header).
  */
 export declare function resolveWin32Command(cmd: string, args: readonly string[], ctx: Win32ResolveContext): Win32Invocation | undefined;

package/lib/utils/win32-command.js

@@ -6,36 +6,28 @@
 // Linux host (the same shape `utils/bin-shim.ts` uses), and narrowed to the one
 // case the CLI needs — resolving a bare command name before `spawn`.
 //
-// WHY THIS EXISTS
-//
-// `spawn('npm', …)` cannot work on Windows, and the failure is not a PATH
-// problem. `CreateProcess` appends only `.exe` when it searches PATH for a bare
-// name, and every npm-installed bin on Windows is a `.cmd` shim. Measured on
-// win32 x64 / Node 24.18.1:
+// `spawn('npm', …)` cannot work on Windows, and the failure is not a PATH problem:
+// `CreateProcess` appends only `.exe` when it searches PATH for a bare name, and every
+// npm-installed bin on Windows is a `.cmd` shim. Measured on win32 x64 / Node 24.18.1:
 //
 //     spawn('npm',     ['--version'])  →  ENOENT   (.cmd is never tried)
 //     spawn('node',    ['--version'])  →  ok       (.exe is appended)
 //     spawn('npm.cmd', ['--version'])  →  EINVAL   (Node refuses a batch file)
 //
-// The EINVAL is Node's CVE-2024-27980 mitigation: a `.cmd`/`.bat` target has to
-// go through a command interpreter. So resolving the shim path is NOT enough —
-// it must be invoked as `cmd.exe /d /s /c "…"` with every argument escaped for
-// cmd's parser, which is what {@link buildCmdExeInvocation} does.
-//
-// That gap took out the whole orchestration layer, not one command: `gjsify
-// workspace`/`foreach`/`check` spawn `<pm> run <script>` per package and the
-// package manager is `npm` on every non-GJS host, so on Windows each one died
-// with `spawn npm ENOENT` before running a single script.
+// The EINVAL is Node's CVE-2024-27980 mitigation: a `.cmd`/`.bat` target must go through a
+// command interpreter, so resolving the shim path is NOT enough — it has to be invoked as
+// `cmd.exe /d /s /c "…"` with every argument escaped for cmd's parser ({@link
+// buildCmdExeInvocation}). The gap took out the whole orchestration layer, not one command:
+// `gjsify workspace`/`foreach`/`check` spawn `<pm> run <script>` per package and the package
+// manager is `npm` on every non-GJS host, so on Windows each died with `spawn npm ENOENT`
+// before running a single script.
 //
-// WHY RESOLUTION HAPPENS HERE AND NOT IN cmd.exe
-//
-// Handing the bare name to `cmd.exe /c` would also find the `.cmd` — and would
-// destroy the ENOENT contract every caller depends on. A missing command would
-// come back as a generic exit 1 with an unparsable message instead of an
-// `ENOENT` error, and `SpawnToCompletionOptions.notFound` (the install hints)
-// plus `commands/tsc.ts`'s transparent fall back to upstream tsc when `gjs` is
-// absent both key on exactly that code. Resolving first keeps "not found" a
-// spawn-time error and routes only what really is a batch file through cmd.exe.
+// Resolution happens HERE and not in cmd.exe because handing the bare name to `cmd.exe /c`
+// would also find the `.cmd` but destroy the ENOENT contract: a missing command would return a
+// generic exit 1 with an unparsable message, and both `SpawnToCompletionOptions.notFound` (the
+// install hints) and `commands/tsc.ts`'s fall back to upstream tsc when `gjs` is absent key on
+// that code. Resolving first keeps "not found" a spawn-time error and routes only a real batch
+// file through cmd.exe.
 /** Default when `PATHEXT` is unset — the extensions `CreateProcess` users expect. */
 const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
 /** Only `.com`/`.exe` can be executed without an interpreter. Verbatim from cross-spawn. */
@@ -47,17 +39,16 @@ const META_CHARS_RE = /([()\][%!^"`<>&|;, *?])/g;
 /**
  * Read `name` from `env` case-insensitively.
  *
- * Windows environment variables are case-insensitive and `process.env` mirrors
- * that, but a plain object handed in as `env` (which is what every spawn call
- * site builds) does not — a child env carrying `Path` rather than `PATH` would
- * otherwise silently resolve nothing.
+ * Windows env vars are case-insensitive and `process.env` mirrors that, but a plain object —
+ * what every spawn call site builds — does not, so a child env carrying `Path` rather than
+ * `PATH` would silently resolve nothing.
  */
 export function lookupEnv(env, name) {
     const wanted = name.toLowerCase();
     for (const key of Object.keys(env)) {
-        // A key present but explicitly `undefined` means NOT SET — `spawn`
-        // drops it from the child env. Returning it here would shadow a later
-        // spelling (`{ PATH: undefined, Path: 'C:\\bin' }`) and resolve nothing.
+        // A key present but explicitly `undefined` means NOT SET — `spawn` drops it from the
+        // child env. Returning it would shadow a later spelling (`{ PATH: undefined, Path:
+        // 'C:\\bin' }`) and resolve nothing.
         if (key.toLowerCase() === wanted && env[key] !== undefined)
             return env[key];
     }
@@ -84,12 +75,8 @@ export function escapeCmdArgument(arg, doubleEscapeMetaChars = false) {
     return out;
 }
 /**
- * Build the `cmd.exe /d /s /c "…"` invocation for a resolved, non-directly-
- * executable target. Pure — the unit tests drive this from any host.
- *
- * @param commandFile Resolved absolute path of the target (e.g. the `.cmd` shim).
- * @param args The caller's arguments, unescaped.
- * @param comspec The interpreter, normally `%COMSPEC%`.
+ * Build the `cmd.exe /d /s /c "…"` invocation for a resolved, non-directly-executable target.
+ * `args` are the caller's UNESCAPED arguments; `comspec` is normally `%COMSPEC%`.
  */
 export function buildCmdExeInvocation(commandFile, args, comspec = 'cmd.exe') {
     // A cmd-shim under `node_modules/.bin/` is itself a batch file that re-invokes
@@ -121,10 +108,9 @@ function lookupOnPath(cmd, ctx) {
 /**
  * Rewrite a bare command name into something Windows can actually spawn.
  *
- * Returns `undefined` when nothing needs rewriting — not win32, not a bare
- * name, or not found on `PATH`. The last case is deliberate: letting `spawn`
- * fail with `ENOENT` preserves the contract callers key their install hints on
- * (see the module header).
+ * `undefined` when nothing needs rewriting — not win32, not a bare name, or not found on
+ * `PATH`. The last case is deliberate: letting `spawn` fail with `ENOENT` preserves the
+ * contract callers key their install hints on (see the module header).
  */
 export function resolveWin32Command(cmd, args, ctx) {
     if (ctx.platform !== 'win32' || !isBareName(cmd))
@@ -132,8 +118,8 @@ export function resolveWin32Command(cmd, args, ctx) {
     const resolved = lookupOnPath(cmd, ctx);
     if (!resolved)
         return undefined;
-    // `.exe`/`.com` run without an interpreter; spawning the resolved absolute
-    // path skips a second PATH search and cannot be shadowed in between.
+    // `.exe`/`.com` run without an interpreter; spawning the resolved absolute path skips a
+    // second PATH search and cannot be shadowed in between.
     if (DIRECTLY_EXECUTABLE_RE.test(resolved))
         return { cmd: resolved, args: [...args] };
     return buildCmdExeInvocation(resolved, args, lookupEnv(ctx.env, 'COMSPEC') ?? 'cmd.exe');

package/lib/utils/workspace-root.js

@@ -1,16 +1,11 @@
-// Walk up from a starting directory to the first ancestor whose
-// `package.json` declares a `workspaces` field — the monorepo root.
+// Walk up from a starting directory to the first ancestor whose `package.json`
+// declares a `workspaces` field — the monorepo root that `gjsify
+// run`/`workspace`/`foreach` need to discover siblings, resolve `workspace:^`
+// deps and walk the dep graph. They can be invoked from anywhere, because a
+// chained script call puts the child CLI's cwd at the inner workspace.
 //
-// Used by `gjsify run`, `gjsify workspace`, and `gjsify foreach`: each
-// can be invoked from inside any workspace (chained script calls put the
-// child CLI invocation's cwd at the inner workspace's location), and
-// every one of them needs the monorepo root to discover sibling
-// workspaces, resolve `workspace:^` deps, and walk the dep graph.
-//
-// Sanity-checked via `discoverWorkspaces(candidate)`: the candidate
-// monorepo must actually contain `start` as one of its workspaces.
-// Without this guard, a grand-parent monorepo unrelated to `start`
-// could be picked up.
+// The candidate must also CONTAIN `start` (`discoverWorkspaces`), or an unrelated
+// grand-parent monorepo gets picked up.
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { discoverWorkspaces } from '@gjsify/workspace';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.35.0",
+    "version": "0.37.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -134,19 +134,20 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.35.0",
-        "@gjsify/create-app": "^0.35.0",
-        "@gjsify/node-globals": "^0.35.0",
-        "@gjsify/node-polyfills": "^0.35.0",
-        "@gjsify/npm-registry": "^0.35.0",
-        "@gjsify/resolve-npm": "^0.35.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.35.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.35.0",
-        "@gjsify/semver": "^0.35.0",
-        "@gjsify/tar": "^0.35.0",
-        "@gjsify/tsc": "^0.35.0",
-        "@gjsify/web-polyfills": "^0.35.0",
-        "@gjsify/workspace": "^0.35.0",
+        "@gjsify/buffer": "^0.37.0",
+        "@gjsify/create-app": "^0.37.0",
+        "@gjsify/node-globals": "^0.37.0",
+        "@gjsify/node-polyfills": "^0.37.0",
+        "@gjsify/npm-registry": "^0.37.0",
+        "@gjsify/resolve-npm": "^0.37.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.37.0",
+        "@gjsify/vite-plugin-blueprint": "^0.37.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.37.0",
+        "@gjsify/semver": "^0.37.0",
+        "@gjsify/tar": "^0.37.0",
+        "@gjsify/tsc": "^0.37.0",
+        "@gjsify/web-polyfills": "^0.37.0",
+        "@gjsify/workspace": "^0.37.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
@@ -154,13 +155,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.35.0",
+        "@gjsify/unit": "^0.37.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.35.0",
-        "@gjsify/rolldown-native": "^0.35.0"
+        "@gjsify/oxfmt-native": "^0.37.0",
+        "@gjsify/rolldown-native": "^0.37.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {

package/showcases.json

@@ -19,6 +19,12 @@
             "package": "@gjsify/example-dom-three-geometry-teapot",
             "description": "Three.js Utah teapot"
         },
+        {
+            "name": "three-loader-ldraw",
+            "category": "dom",
+            "package": "@gjsify/example-dom-three-loader-ldraw",
+            "description": "Three.js LDraw viewer — loads packed .mpd models over fetch and steps through their building instructions"
+        },
         {
             "name": "three-postprocessing-pixel",
             "category": "dom",