@gjsify/cli 0.36.0 → 0.37.0

package/lib/utils/resolve-npm-package.js

@@ -1,88 +1,59 @@
 // Multi-anchor npm-package resolver for the GJS-bundled CLI.
 //
-// GJS's native ESM loader has no node_modules walker — a bare
-// `await import('rolldown')` from inside the bundle throws
-// `ImportError: Module not found: rolldown` even when the package is
-// physically present in a node_modules above the caller's cwd.
+// GJS's native ESM loader has no node_modules walker — a bare `await import('rolldown')`
+// from inside the bundle throws `ImportError: Module not found: rolldown` even when the
+// package is physically present in a node_modules above the caller's cwd.
 //
-// `createRequire(import.meta.url)` works when invoked under Node, and
-// when invoked under GJS *with* `@gjsify/module`'s polyfill it walks the
-// node_modules chain from the URL it was anchored at. But it walks
-// only ONE chain — the one rooted at the anchor's parent. When the
-// bundle lives at `<install>/dist/cli.gjs.mjs` and the user runs
-// `gjs -m <install>/dist/cli.gjs.mjs build …` from a completely
-// unrelated cwd (`/tmp/sandbox/`) whose `node_modules` is the only
-// place rolldown is present, anchoring on the bundle URL misses it.
+// `createRequire(import.meta.url)` works under Node, and under GJS with `@gjsify/module`'s
+// polyfill it walks the node_modules chain from the URL it was anchored at — but only ONE
+// chain, the one rooted at the anchor's parent. When the bundle lives at
+// `<install>/dist/cli.gjs.mjs` and the user runs it from an unrelated cwd whose
+// `node_modules` is the only place rolldown is present, anchoring on the bundle URL misses
+// it. So a bare specifier is tried against several anchors, first hit wins:
 //
-// This helper resolves a bare specifier against multiple anchors in
-// order — the first one that resolves wins:
-//
-//   1. `GJSIFY_NODE_PATH` env override (colon-separated dir list,
-//      matches Node's NODE_PATH semantics — each entry is treated as a
-//      synthetic `node_modules` parent).
+//   1. `GJSIFY_NODE_PATH` env override (NODE_PATH semantics — each entry is a synthetic
+//      `node_modules` parent).
 //   2. Caller-supplied anchor dir (typically process.cwd()).
-//   3. Workspace root from `findWorkspaceRoot(anchorDir)` — finds the
-//      monorepo top when invoked from a sub-package directory.
+//   3. Workspace root from `findWorkspaceRoot(anchorDir)` — the monorepo top when invoked
+//      from a sub-package directory.
 //   4. Bundle path's parent chain (`import.meta.url` of THIS module).
-//   5. Parent dirs of the anchor (fallback for nested-without-workspace
-//      setups — matches `oxc-resolve.ts`'s walker).
-//
-// Returns the absolute path on success (the caller usually wraps it in
-// `pathToFileURL().href` before passing to dynamic `import(...)`).
-// Returns null when every anchor failed.
+//   5. Parent dirs of the anchor (nested-without-workspace layouts).
 //
-// Reference: `packages/infra/cli/src/commands/tsc.ts` (workspace-root +
-// cwd anchoring precedent) and `packages/infra/cli/src/utils/oxc-resolve.ts`
-// (parent-dir walker precedent).
+// Precedents: `commands/tsc.ts` (workspace-root + cwd anchoring), `utils/oxc-resolve.ts`
+// (parent-dir walker).
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { delimiter, join, resolve } from 'node:path';
 import { findWorkspaceRoot } from './workspace-root.js';
 /**
- * Resolve a bare npm specifier through multiple createRequire anchors.
- * Returns the absolute filesystem path of the resolved module, or null
- * if no anchor succeeded.
- *
- * Each anchor is tried in priority order — `GJSIFY_NODE_PATH` (highest)
- * → caller cwd → workspace root → bundle URL → parent-dir walk from
- * cwd. The first anchor whose `require.resolve()` succeeds wins.
+ * Resolve a bare npm specifier through the anchors listed above, returning the resolved
+ * module's absolute path or null when every anchor failed. Callers usually wrap the result in
+ * `pathToFileURL().href` before a dynamic `import(...)`.
  */
 export function resolveNpmPackage(specifier, opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
-    // 1. GJSIFY_NODE_PATH env override (NODE_PATH-like) — each entry is
-    //    treated as a directory whose own `node_modules` participates
-    //    in the lookup. Mirrors Node's NODE_PATH semantics.
     const envPath = process.env['GJSIFY_NODE_PATH'];
     if (envPath) {
-        // `path.delimiter`, not `':'` — Node's own NODE_PATH uses `;` on
-        // Windows, and this override claims to mirror NODE_PATH semantics. Split
-        // on a colon there and even a SINGLE entry is destroyed: `C:\tools`
-        // becomes `['C', '\tools']`, neither of which resolves, so the documented
-        // override silently did nothing on Windows and fell through to anchor 2.
-        // `commands/run.ts` and `utils/run-lifecycle-script.ts` already get this
-        // right; this was the site that was missed.
+        // `path.delimiter`, not `':'` — NODE_PATH uses `;` on Windows, where splitting on a
+        // colon destroys even a SINGLE entry (`C:\tools` → `['C', '\tools']`), so the
+        // documented override silently did nothing there and fell through to anchor 2.
         for (const dir of envPath.split(delimiter).filter(Boolean)) {
             const hit = tryResolveFromDir(specifier, resolve(dir));
             if (hit)
                 return hit;
         }
     }
-    // 2. Caller cwd → walk up for nearest node_modules/<pkg>.
     const fromCwd = tryResolveFromDir(specifier, cwd);
     if (fromCwd)
         return fromCwd;
-    // 3. Workspace root (monorepo top, if any).
     const wsRoot = findWorkspaceRoot(cwd);
     if (wsRoot && wsRoot !== cwd) {
         const fromWsRoot = tryResolveFromDir(specifier, wsRoot);
         if (fromWsRoot)
             return fromWsRoot;
     }
-    // 4. Bundle path's own parent chain — anchored at the bundle URL
-    //    so the install-time node_modules layout (e.g.
-    //    `<install>/node_modules/rolldown` next to the CLI bundle)
-    //    is reachable even when the user runs the bundle directly from
-    //    an unrelated cwd.
+    // Anchored at the bundle URL so the install-time layout (`<install>/node_modules/rolldown`
+    // next to the CLI bundle) stays reachable when the bundle is run from an unrelated cwd.
     if (opts.bundleUrl) {
         try {
             const req = createRequire(opts.bundleUrl);
@@ -92,11 +63,8 @@ export function resolveNpmPackage(specifier, opts = {}) {
             // Fall through.
         }
     }
-    // 5. Parent-dir walk from cwd as a last resort (nested
-    //    package layouts without a workspace marker). Capped at 8
-    //    levels to avoid runaway filesystem walks on pathological
-    //    layouts. Matches the depth `oxc-resolve.ts` uses for its
-    //    equivalent walker.
+    // Last resort for nested layouts without a workspace marker. Depth-capped so a
+    // pathological layout cannot turn a failed resolve into a filesystem walk to `/`.
     let dir = resolve(cwd, '..');
     for (let i = 0; i < 8; i++) {
         const hit = tryResolveFromDir(specifier, dir);
@@ -110,11 +78,9 @@ export function resolveNpmPackage(specifier, opts = {}) {
     return null;
 }
 /**
- * Attempt to resolve `specifier` as if a fictional source file at
- * `<dir>/__gjsify_resolve__.js` were doing the lookup. createRequire's
- * algorithm walks up from the anchor's parent for `node_modules/<pkg>`
- * so seeding it inside `<dir>` makes `<dir>/node_modules/<pkg>` the
- * first hit.
+ * Resolve `specifier` as if a fictional source file at `<dir>/__gjsify_resolve__.js` were
+ * doing the lookup: createRequire walks up from the anchor's PARENT for `node_modules/<pkg>`,
+ * so seeding it inside `<dir>` makes `<dir>/node_modules/<pkg>` the first hit.
  */
 function tryResolveFromDir(specifier, dir) {
     try {

package/lib/utils/resolve-plugin-by-name.d.ts

@@ -10,32 +10,24 @@ export interface PluginByName {
 /**
  * Strategy for turning a resolved plugin file path into its module namespace.
  *
- * On Node this is a plain dynamic `import()`. Under GJS it cannot be — GJS's
- * native ESM loader does not follow npm `package.json#exports` subpath maps
- * for bare specifiers, so importing a plugin whose source does
- * `import … from '@scope/pkg/internal-subpath'` throws
- * `Module not found: @scope/pkg/internal-subpath` even when the file is on
- * disk. The CLI injects a GJS strategy that first bundles the plugin to a
- * single self-contained ESM file (Rolldown resolves the exports map at
- * bundle time), then imports that. See `BuildAction.loadPluginViaGjsBundle`.
+ * A plain dynamic `import()` on Node, but under GJS it cannot be: GJS's native ESM loader does not
+ * follow npm `package.json#exports` subpath maps for bare specifiers, so a plugin whose source
+ * does `import … from '@scope/pkg/internal-subpath'` throws `Module not found` even with the file
+ * on disk. The CLI injects a GJS strategy that first bundles the plugin to one self-contained ESM
+ * file (Rolldown resolves the exports map at bundle time), then imports that — see
+ * `BuildAction.loadPluginViaGjsBundle`.
  */
 export type LoadPluginModule = (resolvedPath: string, pluginName: string) => Promise<Record<string, unknown>>;
 export interface ResolveUserPluginsOptions {
-    /**
-     * Override how a resolved plugin path is turned into its module
-     * namespace. Defaults to a direct dynamic `import()` (correct on Node).
-     */
+    /** Defaults to a direct dynamic `import()`, which is correct on Node. */
     loadModule?: LoadPluginModule;
 }
 /** Type-guard: a `PluginByName` shape rather than a Rolldown plugin object. */
 export declare function isPluginByName(value: unknown): value is PluginByName;
 /**
- * Resolve a list of mixed user plugins. Entries that are already plugin
- * objects pass through unchanged; entries shaped like `PluginByName` get
- * dynamically imported, instantiated with their `options`, and returned in
- * the same position. Resolution is anchored at `projectDir`.
- *
- * Throws when a name fails to resolve, when the chosen export is not a
- * function, or when the factory returns nothing.
+ * Resolve a list of mixed user plugins, anchored at `projectDir`. Plugin objects pass through
+ * unchanged; `PluginByName` entries are imported, instantiated with their `options`, and returned
+ * in the same position. Throws when a name fails to resolve, the chosen export is not a function,
+ * or the factory returns nothing.
  */
 export declare function resolveUserPlugins(plugins: ReadonlyArray<RolldownPluginOption | PluginByName>, projectDir: string, options?: ResolveUserPluginsOptions): Promise<RolldownPluginOption[]>;

package/lib/utils/resolve-plugin-by-name.js

@@ -8,10 +8,9 @@
 //     ]
 //   }
 //
-// Lets `package.json#gjsify` describe the full plugin chain without dropping
-// to a JS-form config file (`gjsify.config.mjs`). Resolution is anchored at
-// the project root (where the config lives) so the project's own
-// `node_modules` wins over the CLI's own dependencies.
+// Lets `package.json#gjsify` describe the full plugin chain without dropping to a JS-form config
+// file (`gjsify.config.mjs`). Resolution is anchored at the project root, so the project's own
+// `node_modules` wins over the CLI's dependencies.
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -22,9 +21,8 @@ export function isPluginByName(value) {
     return (typeof value === 'object' &&
         value !== null &&
         typeof value.name === 'string' &&
-        // RolldownPluginOption can be `false | null | undefined | Plugin | Promise<Plugin>`.
-        // A real plugin always has a function-shape behavior; `name` alone is shared
-        // with our shape, so we additionally require absence of plugin-shape fields.
+        // `name` alone does not discriminate — a real Rolldown plugin has it too — so the
+        // absence of every plugin-shape hook is what separates the two.
         !('apply' in value) &&
         !('resolveId' in value) &&
         !('load' in value) &&
@@ -33,13 +31,10 @@ export function isPluginByName(value) {
         !('generateBundle' in value));
 }
 /**
- * Resolve a list of mixed user plugins. Entries that are already plugin
- * objects pass through unchanged; entries shaped like `PluginByName` get
- * dynamically imported, instantiated with their `options`, and returned in
- * the same position. Resolution is anchored at `projectDir`.
- *
- * Throws when a name fails to resolve, when the chosen export is not a
- * function, or when the factory returns nothing.
+ * Resolve a list of mixed user plugins, anchored at `projectDir`. Plugin objects pass through
+ * unchanged; `PluginByName` entries are imported, instantiated with their `options`, and returned
+ * in the same position. Throws when a name fails to resolve, the chosen export is not a function,
+ * or the factory returns nothing.
  */
 export async function resolveUserPlugins(plugins, projectDir, options = {}) {
     const loadModule = options.loadModule ?? defaultLoadModule;

package/lib/utils/run-gjs.d.ts

@@ -1,38 +1,33 @@
 import { type NativeEnv } from './detect-native-packages.js';
 /**
- * Pure env computation for a given bundle. Returns the typelib +
- * shared-library search paths that {@link runGjsBundle} would inject into the
- * spawned `gjs` process, plus the formatted env-prefix string used for the
- * `$ …` echo. Which library variable is set is host-dependent
- * (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see `buildNativeEnv`.
+ * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
+ * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
+ * variable is set is host-dependent (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see
+ * `buildNativeEnv`.
  */
 export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: string, inherited?: Record<string, string | undefined>): {
     env: NativeEnv;
     envPrefix: string;
 };
 /**
- * Run a GJS bundle, automatically setting LD_LIBRARY_PATH and GI_TYPELIB_PATH
- * for any installed native gjsify packages discoverable from either the CWD
- * or the bundle's own node_modules tree.
+ * Options for {@link runGjsBundle}, which runs a GJS bundle with `GI_TYPELIB_PATH` and the
+ * host's library variable set for any native gjsify packages discoverable from the CWD or the
+ * bundle's own node_modules tree.
  */
 export interface RunGjsBundleOptions {
     /**
-     * Exit this process with code 0 once the child succeeds. Under GJS,
-     * `ensureMainLoop()` (armed by spawn) keeps the parent's GLib loop alive
-     * after the child exits — a TERMINAL caller (`gjsify run <file>`, `dlx`)
-     * must opt in here or it parks forever (this exact gap hung CI's
-     * "Test WebGL conformance" for 83 min: the suite finished in 1.35 s, the
-     * parent `gjsify run conformance.gjs.js` never exited). Callers that
-     * continue after the bundle (e.g. `gjsify test`'s multi-runtime
-     * aggregation loop) MUST leave this false — an unconditional exit here
-     * truncated `gjsify test` after the first gjs bundle.
+     * Exit this process with code 0 once the child succeeds. Under GJS, `ensureMainLoop()`
+     * (armed by spawn) keeps the parent's GLib loop alive after the child exits, so a TERMINAL
+     * caller (`gjsify run <file>`, `dlx`) must opt in or it parks forever — this gap hung CI's
+     * WebGL conformance job for 83 min on a suite that finished in 1.35 s. Callers that
+     * continue after the bundle (`gjsify test`'s multi-runtime loop) MUST leave this false; an
+     * unconditional exit truncated `gjsify test` after the first gjs bundle.
      */
     exitOnSuccess?: boolean;
     /**
-     * Suppress the `$ <env> gjs -m …` echo. The echo exists so a user can
-     * copy-paste the exact command, which is worth ~2 kB of env prefix for a
-     * one-shot `gjsify run <bundle>` — and is pure noise for a build script the
-     * chain invokes a dozen times (`utils/node-script.ts`).
+     * Suppress the `$ <env> gjs -m …` echo. Worth its ~2 kB of env prefix for a one-shot
+     * `gjsify run <bundle>`; pure noise for a build script invoked a dozen times per chain
+     * (`utils/node-script.ts`).
      */
     quiet?: boolean;
 }

package/lib/utils/run-gjs.js

@@ -1,30 +1,22 @@
 // Shared utility for running a GJS bundle with native package env vars.
 // Used by `gjsify run`, `gjsify dlx`, and the showcase command (via dlx).
 //
-// Detection runs the same exhaustive node_modules walker (`detectNativePackages`)
-// from two starting points and merges by package name (CWD shadows bundle):
+// Detection runs `detectNativePackages` from two starting points and merges by package name
+// (CWD shadows bundle): `process.cwd()` for native deps in the user's project, and
+// `dirname(bundlePath)` for those in whatever node_modules the bundle lives in — critical for
+// `gjsify dlx`, where the bundle sits under `~/.cache/gjsify/dlx/<sha>/…` and the user's CWD
+// is unrelated. The bundle-side walk also catches transitive deps' typelibs.
 //
-//   1. process.cwd()          — picks up native deps in the user's project
-//                               (yarn / pnpm / npm node_modules walking up).
-//   2. dirname(bundlePath)    — picks up native deps in whatever node_modules
-//                               the bundle lives in. Critical for `gjsify dlx`
-//                               where the bundle resides in
-//                               `~/.cache/gjsify/dlx/<sha>/.../node_modules/<pkg>/dist/`
-//                               and the user's CWD is unrelated. The bundle-side
-//                               walk also catches transitive deps' typelibs.
-//
-// Env composition is split out as `computeNativeEnvForBundle()` — a pure
-// function that takes a bundle path + cwd and returns the env it would inject.
-// This lets the e2e tests assert the env without spawning gjs.
+// Env composition is split out as the pure `computeNativeEnvForBundle()` so the e2e tests can
+// assert the env without spawning gjs.
 import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { detectNativePackages, buildNativeEnv } from './detect-native-packages.js';
 /**
- * Pure env computation for a given bundle. Returns the typelib +
- * shared-library search paths that {@link runGjsBundle} would inject into the
- * spawned `gjs` process, plus the formatted env-prefix string used for the
- * `$ …` echo. Which library variable is set is host-dependent
- * (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see `buildNativeEnv`.
+ * Pure env computation: the typelib + shared-library search paths {@link runGjsBundle} would
+ * inject into the spawned `gjs`, plus the formatted prefix for the `$ …` echo. Which library
+ * variable is set is host-dependent (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see
+ * `buildNativeEnv`.
  */
 export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inherited = process.env) {
     const resolvedBundle = resolve(bundlePath);
@@ -32,23 +24,16 @@ export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inher
     const bundlePackages = detectNativePackages(dirname(resolvedBundle));
     const seen = new Set(cwdPackages.map((p) => p.name));
     const nativePackages = [...cwdPackages, ...bundlePackages.filter((p) => !seen.has(p.name))];
-    // `inherited` feeds BOTH halves — the composition and the comparison. Split
-    // them and the win32 branch disagrees with itself: `buildNativeEnv` writes
-    // the library variable back under the host's own spelling (`Path` in a
-    // stock env block), so a comparison keyed on the canonical `PATH` would
-    // look up a key that is not there and call every run a change.
+    // `inherited` feeds BOTH halves — composition and comparison. Split them and the win32
+    // branch disagrees with itself: `buildNativeEnv` writes the library variable back under
+    // the host's own spelling (`Path` in a stock env block), so a comparison keyed on the
+    // canonical `PATH` would look up a key that is not there and call every run a change.
     const env = buildNativeEnv(nativePackages, { env: inherited });
-    // Show only what this CLI actually CHANGED. `buildNativeEnv` prepends the
-    // detected directories to the inherited value and returns the result
-    // unconditionally, so with no native packages it hands back the host's own
-    // variable verbatim — and the echo then claimed the CLI had set it.
-    //
-    // Harmless on Linux, where `LD_LIBRARY_PATH` is usually unset and the empty
-    // filter caught it. On Windows the library variable IS `PATH`, which is
-    // never empty, so every run printed a ~2 kB dump of the host PATH in front
-    // of a command the user is invited to copy — burying the command, and
-    // claiming a change that never happened. Comparing against the inherited
-    // value is what makes the echo honest on both.
+    // Show only what this CLI actually CHANGED: `buildNativeEnv` prepends to the inherited
+    // value unconditionally, so with no native packages it hands back the host's own variable
+    // verbatim. Harmless on Linux, where `LD_LIBRARY_PATH` is usually unset; on Windows the
+    // library variable IS `PATH`, never empty, so every run printed a ~2 kB dump of the host
+    // PATH in front of a command the user is invited to copy.
     const envPrefix = Object.entries(env)
         .filter(([key, value]) => value !== undefined && value !== '' && value !== inherited[key])
         .map(([key, value]) => `${key}=${value}`)
@@ -62,24 +47,16 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
         ...nativeEnv,
     };
     const gjsArgs = ['-m', bundlePath, ...extraArgs];
-    // Print the exact command being executed so users can copy-paste it to
-    // run gjs directly without the wrapper. Env vars are only shown if we
-    // actually set any (i.e. native gjsify packages were detected).
-    // Use stderr so that children speaking a protocol on stdout (e.g. an
-    // MCP stdio server) receive an uncontaminated stdout stream.
+    // Echo the exact command so users can copy-paste it and run gjs without the wrapper.
+    // stderr, so children speaking a protocol on stdout (an MCP stdio server) keep a clean one.
     const gjsCommand = ['gjs', ...gjsArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
     if (!options.quiet)
         console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
     const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
     let failed = false;
-    // The CHILD's own exit code, so it can be re-raised verbatim. A spawn error
-    // (no `gjs` on PATH) has no code of its own and falls back to 1.
-    //
-    // Collapsing every failure to 1 lost information a caller acts on: a script
-    // run through `gjsify run --node-script` reports ITS status (the bootstrap
-    // scripts all end `process.exit(r.status ?? 1)`, forwarding a child's code),
-    // and a chain that reads `$?` to distinguish "tool failed" from "tool says
-    // no" saw the same 1 for both.
+    // The CHILD's own exit code, re-raised verbatim; a spawn error (no `gjs` on PATH) has none
+    // of its own and falls back to 1. Collapsing every failure to 1 lost information callers
+    // act on — a chain reading `$?` to tell "tool failed" from "tool says no" saw 1 for both.
     let childCode = 1;
     await new Promise((resolvePromise, reject) => {
         child.on('close', (code) => {
@@ -97,14 +74,12 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
         failed = true;
     });
     if (failed) {
-        // Set `process.exitCode` synchronously BEFORE exiting: under GJS
-        // `process.exit()` is deferred (the GLib main loop is armed), so when
-        // this runs via run.ts's in-process script dispatch, execution returns
-        // to the caller, which propagates by reading `process.exitCode`. Without
-        // this, `gjsify run <script>` whose body is `gjsify run <bundle>`
-        // swallowed a non-zero gjs exit and returned 0 — masking a failing
-        // `test:gjs` in the `test` script chain (and, via `gjsify foreach test`,
-        // in CI). The `return` guards against a fall-through second `exit`.
+        // Set `process.exitCode` synchronously BEFORE exiting: under GJS `process.exit()` is
+        // deferred (the GLib main loop is armed), so under run.ts's in-process script dispatch
+        // execution returns to the caller, which propagates by reading `process.exitCode`.
+        // Without it, `gjsify run <script>` wrapping `gjsify run <bundle>` swallowed a non-zero
+        // gjs exit and returned 0 — masking a failing `test:gjs` in the `test` chain, and via
+        // `gjsify foreach test` in CI. The `return` guards a fall-through second `exit`.
         process.exitCode = childCode;
         return process.exit(childCode);
     }

package/lib/utils/run-lifecycle-script.d.ts

@@ -2,20 +2,16 @@ export interface RunLifecycleScriptOptions {
     /** When true, do not throw on missing scripts — return `false` instead. */
     optional?: boolean;
     /**
-     * Stdio inheritance for the spawned script. Default `'inherit'` so output
-     * appears in the parent's terminal. Pass `'inherit-stderr'` to mirror
-     * inheritance but redirect the child's stdout → parent's stderr — used by
-     * `gjsify pack --json` and `gjsify publish` so the parent's stdout stays
-     * a clean JSON stream (script log lines would otherwise corrupt the
-     * machine-readable output that callers `JSON.parse`).
+     * Stdio for the spawned script; default `'inherit'`. `'inherit-stderr'` redirects the
+     * child's stdout → parent's stderr, used by `gjsify pack --json` and `gjsify publish` so
+     * script log lines cannot corrupt the JSON stream callers `JSON.parse`.
      */
     stdio?: 'inherit' | 'inherit-stderr' | 'pipe' | 'ignore';
     /** Extra environment variables layered on top of the defaults. */
     env?: Record<string, string>;
 }
 /**
- * Run a lifecycle script defined in `pkg.scripts[name]` from `wsDir`.
- * Returns `true` if the script existed and exited 0. Returns `false` if
- * `optional: true` and the script is missing. Throws on non-zero exit.
+ * Run the lifecycle script `pkg.scripts[name]` from `wsDir`. `true` when it existed and exited
+ * 0, `false` when it is missing and `optional` is set; throws on a non-zero exit.
  */
 export declare function runLifecycleScript(wsDir: string, pkg: Record<string, unknown>, name: string, opts?: RunLifecycleScriptOptions): Promise<boolean>;

package/lib/utils/run-lifecycle-script.js

@@ -2,47 +2,31 @@
 // `postpack`, `postpublish`, …) from inside a `gjsify pack` / `gjsify
 // publish` flow.
 //
-// Why this exists separately from `gjsify run`: `gjsify run <script>` ends
-// with `process.exit(<code>)` so it can be used as a CLI entrypoint that
-// behaves like `yarn run` / `npm run`. That's wrong for the embedded use
-// case where pack/publish needs the lifecycle script to finish, then keep
-// running its own logic. This helper resolves to a Promise that settles
-// when the child exits.
+// Separate from `gjsify run` because that ends with `process.exit(<code>)` so it can act as a
+// CLI entrypoint like `yarn run`. Pack/publish instead needs the lifecycle script to finish and
+// then keep running its own logic, so this settles a Promise when the child exits.
 //
-// ## Not calling `process.exit()` is what ARMED the hang, not what avoided it
-//
-// This header used to end "no process.exit, no GLib-mainloop intermingling
-// from `ensureMainLoop`". The second half was exactly backwards, and it is why
-// nobody looked here for #1010.
-//
-// `@gjsify/child_process`'s async `spawn()` calls `ensureMainLoop()`
-// unconditionally — the caller has no say. That arms a GJS main-loop hook whose
-// blocking `g_main_loop_run()` only `process.exit()` tears down. So a helper
-// that spawns asynchronously and deliberately does NOT exit leaves the loop
-// armed forever: `gjsify pack` on a package with a `prepack` wrote its tarball,
-// printed its complete JSON, and then parked at 0% CPU until killed at 5m30s.
-// A package with no lifecycle script exited in under a second, and the same
-// pack under Node exited in 0.68s.
-//
-// `utils/spawn.ts` already owns that contract and makes every call site DECLARE
-// which side of it they are on. This helper was the one spawn in the CLI that
-// bypassed it — the seventh of the "six near-identical wrappers" that file was
-// written to consolidate. It now goes through it with `completion: 'return'`,
-// which is what "settle, then keep running our own logic" means.
+// NOT calling `process.exit()` is what ARMS a hang, not what avoids it (#1010):
+// `@gjsify/child_process`'s async `spawn()` calls `ensureMainLoop()` unconditionally — the
+// caller has no say — and that main-loop hook's blocking `g_main_loop_run()` is torn down only
+// by `process.exit()`. A helper that spawns asynchronously and deliberately does not exit
+// therefore leaves the loop armed forever: `gjsify pack` on a package with a `prepack` wrote
+// its tarball, printed its complete JSON, then parked at 0% CPU until killed at 5m30s (no
+// lifecycle script: under a second; the same pack under Node: 0.68s). `utils/spawn.ts` owns
+// that contract and makes every call site DECLARE which side of it it is on; this goes through
+// it with `completion: 'return'`.
 //
 // Matches yarn / npm script semantics:
 //   - `shell: true` so `&&` / `|` / env-var refs work
 //   - PATH prepended with `<wsDir>/node_modules/.bin` + monorepo-root bin
-//   - `npm_lifecycle_event` / `npm_package_name` / `npm_package_version`
-//     env vars set
+//   - `npm_lifecycle_event` / `npm_package_name` / `npm_package_version` set
 //   - FORCE_COLOR=1 default unless caller overrides
 import { delimiter, join } from 'node:path';
 import { describeExit, spawnToCompletion } from './spawn.js';
 import { findWorkspaceRoot } from './workspace-root.js';
 /**
- * Run a lifecycle script defined in `pkg.scripts[name]` from `wsDir`.
- * Returns `true` if the script existed and exited 0. Returns `false` if
- * `optional: true` and the script is missing. Throws on non-zero exit.
+ * Run the lifecycle script `pkg.scripts[name]` from `wsDir`. `true` when it existed and exited
+ * 0, `false` when it is missing and `optional` is set; throws on a non-zero exit.
  */
 export async function runLifecycleScript(wsDir, pkg, name, opts = {}) {
     const scripts = pkg.scripts ?? {};
@@ -57,11 +41,9 @@ export async function runLifecycleScript(wsDir, pkg, name, opts = {}) {
     if (monorepoRoot && monorepoRoot !== wsDir) {
         binDirs.push(join(monorepoRoot, 'node_modules', '.bin'));
     }
-    // Match yarn / npm color-forcing default — see runScript() in run.ts
-    // for the full reasoning. Without this, lifecycle scripts that call
-    // tools like biome / esbuild / tsc lose ANSI color in piped contexts
-    // (CI logs, redirected output) because `process.stdout.isTTY` is
-    // false for the spawned child.
+    // Match yarn / npm color-forcing — see `runScript()` in run.ts. Without it, scripts calling
+    // biome / esbuild / tsc lose ANSI color in piped contexts (CI logs, redirected output)
+    // because `process.stdout.isTTY` is false for the spawned child.
     const colorEnv = process.env.FORCE_COLOR !== undefined || process.env.NO_COLOR !== undefined ? {} : { FORCE_COLOR: '1' };
     const env = {
         ...process.env,
@@ -72,16 +54,15 @@ export async function runLifecycleScript(wsDir, pkg, name, opts = {}) {
         npm_package_version: pkg.version ?? '',
         ...opts.env,
     };
-    // `'ignore'` has no `spawnToCompletion` equivalent and no call site in the
-    // tree; folding it onto `'inherit'` would silently start printing where a
-    // caller asked for silence, so it is rejected rather than approximated.
+    // `'ignore'` has no `spawnToCompletion` equivalent and no call site; folding it onto
+    // `'inherit'` would start printing where a caller asked for silence, so it is rejected
+    // rather than approximated.
     if (opts.stdio === 'ignore') {
         throw new Error('gjsify lifecycle-script: stdio "ignore" is not supported — see utils/spawn.ts');
     }
     const result = await spawnToCompletion(literal, [], {
-        // The whole point of this helper: pack/publish waits for the script and
-        // then keeps running. Under GJS that is the blocking path, which is what
-        // keeps the armed main loop from outliving us — see the header.
+        // pack/publish waits for the script, then keeps running. Under GJS that is the blocking
+        // path, which is what keeps the armed main loop from outliving us — see the header.
         completion: 'return',
         cwd: wsDir,
         env: env,