@gjsify/cli 0.36.0 → 0.37.0

package/lib/bundler-pick.js

@@ -1,65 +1,51 @@
-// Runtime bundler pick (Phase D-2.B.5b → D-3.1 runtime-aware default).
+// Runtime bundler pick. `shouldUseNative()` chooses per host runtime: Node gets
+// npm `rolldown(opts).write(opts.output)`; GJS gets `@gjsify/rolldown-native` (the
+// Vala/Rust prebuild) via `bundleWithPlugins()`, with `runNativeBundle` replicating
+// npm rolldown's `.write()` including nested chunk/asset subdirectories. The native
+// engine is the GJS DEFAULT with no env var, because npm `rolldown` is a Rust N-API
+// addon that cannot load under GJS at all.
 //
-// The engine is chosen by `shouldUseNative()` per host runtime:
-//   - Node: npm `rolldown(opts).write(opts.output)`.
-//   - GJS:  `@gjsify/rolldown-native` (the Vala/Rust prebuild) via
-//           `bundleWithPlugins()`. npm `rolldown` is a Rust N-API addon
-//           that CANNOT load under GJS, so the native engine is the GJS
-//           DEFAULT — no env var needed (this is the Node-free build
-//           chain's bundler). This writes the BundleOutput to disk
-//           (`runNativeBundle`), replicating npm rolldown's `.write()`
-//           incl. nested chunk/asset subdirectories.
+// `GJSIFY_BUNDLER=native|npm` overrides that: `native` throws when the prebuild is
+// not loadable for the running architecture instead of silently switching engines;
+// `npm` forces the npm crate (Node only).
 //
-// `GJSIFY_BUNDLER=native|npm` is an explicit override: `native` forces
-// the native engine and throws if its prebuild isn't loadable for the
-// running architecture (instead of silently switching engines); `npm`
-// forces the npm crate (Node only).
+// Plugin hooks arrive either as bare functions (`load(id)`) or as
+// `{filter, handler}` objects; both are translated to `NativePlugin` form, with
+// `filter.id` regex/string sources becoming `idFilter.<hook>` regex strings on the
+// Rust side, and `this.resolve()` / `this.warn()` / `this.error()` routing through
+// the nested protocol.
 //
-// Plugin shape conversion: rolldown plugins may declare hooks either
-// as bare functions (`load(id)`) or as `{filter, handler}` objects.
-// Both shapes are translated to `NativePlugin` form. `filter.id`
-// regex/string sources become `idFilter.<hook>` regex strings on the
-// Rust side. `this.resolve()` / `this.warn()` / `this.error()` calls
-// inside hook handlers route through the B.3 nested protocol.
-//
-// Plugins that depend on rolldown context methods we don't implement
-// (`this.parse`, `this.emitFile`, `this.getModuleInfo`, …) will fail
-// at hook-call time. The current gjsify plugin set doesn't use any
-// of those, so we don't gate on it; future incompatibilities surface
-// as build errors rather than silent wrong behavior.
+// Plugins using rolldown context methods this bridge does not implement
+// (`this.parse`, `this.emitFile`, `this.getModuleInfo`, …) fail at hook-call time.
+// Deliberately not gated: the current gjsify plugin set uses none of them, and a
+// future incompatibility surfaces as a build error rather than silent wrong output.
 import { promises as fs, existsSync } from 'node:fs';
 import * as path from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { resolveNpmPackage } from './utils/resolve-npm-package.js';
-// Static, not dynamic: `diagnoseNativeEngine()` is synchronous and is called
-// inside a `throw` expression. Safe — check-system-deps imports only `node:`
-// builtins, so there is no cycle, and every one of them is already in the GJS
-// bundle via `commands/install.ts`.
+// Static, not dynamic: `diagnoseNativeEngine()` is synchronous and called inside a
+// `throw` expression. Safe because check-system-deps imports only `node:` builtins,
+// all of which the GJS bundle already carries via `commands/install.ts`.
 import { buildInstallCommand, detectPackageManager, missingSystemDepsFor } from './utils/check-system-deps.js';
 import { activateNativePrebuilds } from './utils/gi-search-path.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
-// npm `rolldown` is a Rust crate with platform-specific prebuilds; loading
-// it eagerly at module init pulls musl-detection code that does
-// `require('node:fs')` synchronously — fine on Node, but fatal under GJS
-// where the createRequire polyfill rejects synchronous builtin loads.
-// Dynamic import keeps it off the GJS code path entirely; the native
-// branch (`@gjsify/rolldown-native`) handles bundling there.
+// Loaded lazily: eager module-init loading of the npm crate pulls musl-detection
+// code that calls `require('node:fs')` synchronously — fine on Node, fatal under
+// GJS, where the createRequire polyfill rejects synchronous builtin loads.
 async function loadNpmRolldown() {
-    // Under GJS the npm crate can NEVER run (its JS wrapper requires a
-    // napi binary). Reaching this loader under GJS means the native
-    // engine probe failed — historically that surfaced as an opaque
-    // `ImportError: Unsupported URI scheme for importing: node` from deep
-    // inside the crate's wrapper (e.g. on a truly-cold workspace where
-    // `@gjsify/rolldown-native`'s lib/ is not built yet, issue #497).
-    // Fail with the actionable diagnosis instead.
+    // Under GJS the npm crate can NEVER run (its JS wrapper needs a napi binary), so
+    // reaching this loader there means the native probe failed. That used to surface
+    // as an opaque `ImportError: Unsupported URI scheme for importing: node` from deep
+    // inside the crate's wrapper (#497, on a cold workspace where the native engine's
+    // lib/ was not built yet). Fail with the actionable diagnosis instead.
     if (isGjs()) {
         throw new Error('gjsify build: no usable bundler engine under GJS — `@gjsify/rolldown-native` is not loadable, ' +
             'and the npm `rolldown` engine is a Rust napi crate that cannot run under GJS.\n' +
             diagnoseNativeEngine());
     }
-    // Indirect specifier so Rolldown's static-analysis doesn't try to
-    // bundle the npm crate into a GJS target build.
+    // Indirect specifier so Rolldown's static analysis does not try to bundle the npm
+    // crate into a GJS target build.
     const specifier = 'rolldown';
     const target = resolveImportTargetForGjs(specifier);
     const mod = (await import(/* @vite-ignore */ target));
@@ -69,24 +55,19 @@ async function loadNpmRolldown() {
  * Say WHY the native engine could not be loaded, read off disk rather than
  * guessed.
  *
- * The causes need different fixes, and this message used to assert the rarest
- * of them ("the CLI bundle was invoked DIRECTLY … bypasses the `gjsify`
- * launcher") as the "most likely cause". On the by-far most common one — a
- * freshly cloned + freshly installed tree, where the engine's JS facade has
- * simply never been built — that reading is not merely unhelpful, it points at
- * a launcher that was in fact used correctly, so the reader goes looking for an
- * env-var problem that does not exist. `scripts/verify-committed-bundles.mjs`
- * hit exactly that and it blocked releases. ADR 0021 then removed the bypassed
- * launcher as a CAUSE outright, so it is no longer among the candidates at all.
+ * The causes need different fixes, so never name the rarest as "most likely": this
+ * message used to lead with a bypassed `gjsify` launcher, which on the by-far most
+ * common case — a fresh clone where the engine's JS facade has never been built —
+ * sent readers after an env-var problem that did not exist, and blocked releases via
+ * `scripts/verify-committed-bundles.mjs`. ADR 0021 has since removed the bypassed
+ * launcher as a cause outright.
  *
  * NOTHING here may throw or recurse into the failure being explained. Branches 1
- * and 2 are `existsSync`-only (no import, no resolution). Branch 3 additionally
- * asks `missingSystemDepsFor()` and reads the memoized `activateNativePrebuilds()`
- * result — both safe by construction rather than by a catch: the former routes
- * every probe through `tryExecFile`, which returns null on any failure, and the
- * latter is an array the failing load attempt already computed. Keep that
- * property when editing: a probe that dies here replaces the diagnosis with its
- * own stack.
+ * and 2 are `existsSync`-only. Branch 3 also asks `missingSystemDepsFor()` and reads
+ * the memoized `activateNativePrebuilds()` result — safe by construction rather than
+ * by a catch: the former routes every probe through `tryExecFile`, which returns
+ * null on any failure, and the latter is an array the failed load already computed.
+ * Keep that property: a probe that dies here replaces the diagnosis with its stack.
  */
 function diagnoseNativeEngine() {
     let pkgDir = null;
@@ -122,29 +103,23 @@ function diagnoseNativeEngine() {
             'of failing. That is fixed in `@gjsify/module`, so a `gjsify` OLDER than the fix still stops here — ' +
             'update it (`gjs -m install.mjs`), or seed `lib/` from the published package, which ships it.');
     }
-    // Branch 3: installed AND built, so the typelib/prebuild LOOKUP failed.
-    //
-    // This branch used to assert "Most likely the CLI bundle was invoked
-    // DIRECTLY … bypasses the launcher" — repeating, one branch later, the exact
-    // mistake this function's docblock records fixing in branch 2: naming the
-    // rarest cause as the most likely one. After #994 measured `ldd` over every
-    // committed linux-x64 prebuild on a consumer-baseline host, a missing
-    // `libjson-glib-1.0.so.0` is at least as common, and it is what ts-for-gir#437
-    // actually hit — with this message on screen.
-    //
-    // So both candidates are now MEASURED, cheaply and without any call that can
-    // throw while explaining a failure, and the measured one is printed first.
+    // Branch 3: installed AND built, so the typelib/prebuild LOOKUP failed. Both
+    // remaining candidates are MEASURED, cheaply and without any call that can throw
+    // while explaining a failure, and the measured one prints first: #994 ran `ldd`
+    // over every committed linux-x64 prebuild on a consumer-baseline host and found a
+    // missing `libjson-glib-1.0.so.0` at least as common as the alternative — it is
+    // what ts-for-gir#437 hit, with this message on screen.
     //
-    // ADR 0021 RETIRED THE THIRD CANDIDATE. "The launcher was bypassed, export
-    // these two variables yourself" is no longer a cause of failure at all:
-    // `tryLoadNative()` calls `activateNativePrebuilds()` before the engine is
-    // loaded, which puts every detected prebuild dir on girepository's typelib
-    // AND library search paths in-process. Do not reintroduce it — besides now
-    // being false, the path it printed (`<facade>/prebuilds/<target>`) had been
-    // wrong since ADR 0017 moved every artifact into a per-target SIBLING
-    // package, so it told readers to export a directory that does not exist.
+    // ADR 0021 RETIRED A THIRD CANDIDATE: "the launcher was bypassed, export these
+    // two variables yourself" is no longer a cause at all, because `tryLoadNative()`
+    // calls `activateNativePrebuilds()` before the engine loads, putting every
+    // detected prebuild dir on girepository's typelib AND library search paths
+    // in-process. Do not reintroduce it — besides being false, the path it printed
+    // (`<facade>/prebuilds/<target>`) has been wrong since ADR 0017 moved every
+    // artifact into a per-target SIBLING package, so it named a directory that does
+    // not exist.
     const parts = ['The JS facade is built, so this is the typelib/prebuild lookup failing.'];
-    // (1) A declared system library that is not on this host. `missingSystemDepsFor`
+    // (1) A declared system library missing from this host. `missingSystemDepsFor`
     // reads the same tables `gjsify system-check` does, so the answer cannot drift
     // from the declaration.
     const missing = missingSystemDepsFor('@gjsify/rolldown-native');
@@ -160,11 +135,10 @@ function diagnoseNativeEngine() {
         else
             parts.push(`Install ${names} with your system package manager (this host's manager was not recognised, so no command is suggested rather than a wrong one).`);
     }
-    // (2) The remaining cause, last because it is the least actionable: no
-    // prebuild for this architecture. Read off the set `activateNativePrebuilds()`
-    // ACTUALLY put on the search paths — memoized, so this is a cached-array read
-    // that cannot throw, and unlike the old hand-composed path it names the
-    // per-target sibling package that really holds the artifact.
+    // (2) No prebuild for this architecture — last because it is least actionable.
+    // Read off the set `activateNativePrebuilds()` ACTUALLY put on the search paths:
+    // a memoized cached-array read that cannot throw, and it names the per-target
+    // sibling package really holding the artifact.
     if (missing.length === 0) {
         const engine = activateNativePrebuilds().find((p) => p.name.startsWith('@gjsify/rolldown-native'));
         parts.push(engine

package/lib/cli-fail.d.ts

@@ -11,12 +11,9 @@ export type CliFailure =
 };
 /**
  * Classify a yargs `fail(msg, err)` callback into the two cases that need
- * different output.
- *
- * Pure on purpose — the whole point is that the rule is testable without
- * driving a process to its death. `cli-fail.spec.ts` additionally pins the
- * yargs-side half (which call site passes `null`) against a real instance, so a
- * yargs upgrade that changes the routing fails a test instead of silently
- * turning every runtime error back into a help dump.
+ * different output. Kept pure so the rule is testable without driving a process
+ * to its death; `cli-fail.spec.ts` pins the yargs-side half against a real
+ * instance, so a yargs upgrade that reroutes `fail` fails a test instead of
+ * silently turning every runtime error back into a help dump.
  */
 export declare function classifyCliFailure(msg: string | null | undefined, _err: unknown): CliFailure;

package/lib/cli-fail.js

@@ -1,66 +1,40 @@
-// How the CLI ends when something goes wrong — the one place that decides
-// whether a failure is a USAGE error (help is the right output) or a RUNTIME
-// error (help is noise that buries the answer).
+// The one place that decides whether a CLI failure is a USAGE error (help is the
+// right output) or a RUNTIME error (help buries the answer).
 //
-// The defect this exists for, measured from outside the repo: `gjsify build`
-// under GJS without `@gjsify/rolldown-native` prints a CORRECT and actionable
-// diagnosis — `diagnoseNativeEngine()` names the package and the exact install
-// command — and then yargs prints ~60 lines of `gjsify build` help on top of it
-// and exits 1. In a CI log the actionable line scrolls out of view and the
-// visible artifact is a help dump, which reads as "bad arguments". That is what
-// ts-for-gir's `test-e2e` leg looked like (#1005). A missing engine is not a
-// usage error and must not leave through the usage path.
+// A missing native engine must not leave through the usage path: `gjsify build`
+// under GJS without `@gjsify/rolldown-native` printed an actionable diagnosis
+// naming the package and the install command, and then ~60 lines of yargs help on
+// top of it, so the CI log read as "bad arguments" (#1005).
 //
-// Four things about yargs make this module's shape non-obvious. All four were
-// measured against the pinned `yargs@18.0.0` (note `@types/yargs` is still 17,
-// one major behind, so the types lie in one place — see below):
+// Four yargs behaviours shape this module, measured against the pinned yargs 18
+// (`@types/yargs` is still 17, so the types understate `fail`):
 //
-//  1. `.fail()` IS reached for an async handler rejection. `command.js:253-260`
-//     does `if (isPromise(innerArgv) && !hasParseCallback()) innerArgv.catch(e =>
-//     usage.fail(null, e))`, and `hasParseCallback()` is false because
-//     `cli-app.ts` calls `parseAsync()` with no function argument. So no
-//     try/catch around `parseAsync` is needed to see handler errors here.
+//  1. `.fail()` IS reached for an async handler rejection, because `cli-app.ts`
+//     calls `parseAsync()` with no callback. No try/catch around it is needed.
+//  2. `msg` is the discriminator, NOT `err`: every usage/validation/parse site
+//     passes a string, and only the handler rejection passes `null`. Branching on
+//     `err` would suppress help for genuine parser errors — exactly backwards.
+//  3. Registering a handler removes yargs' own `showHelp` + `exit(1)`, so the
+//     usage branch must terminate itself. `throw` rather than relying on
+//     `showHelp()` setting `hasOutput`, which only holds while the chain is
+//     synchronous and would break under a future async builder or middleware.
+//  4. Never re-throw the incoming `YError` — yargs routes that class back into
+//     `usage.fail()` and prints help twice. Throw a plain `Error` with `cause`.
 //
-//  2. THE DISCRIMINATOR IS `msg`, NOT `err`. Every usage/validation/parse
-//     failure passes a STRING: all ten `validation.js` sites call
-//     `usage.fail(msg)`, `command.js:370` calls `fail(parsed.error.message,
-//     parsed.error)`, and `yargs-factory.js:188/192/1473` call `fail(msg, err)`.
-//     Only `command.js:257` — the handler rejection — passes `null`. Branching on
-//     `err` instead would suppress help for genuine parser errors, which is
-//     exactly backwards.
-//
-//  3. REGISTERING A HANDLER REMOVES YARGS' OWN EXIT. With no `.fail()` yargs does
-//     `showHelp('error')` + `logger.error(msg || err)` + `exit(1)` itself
-//     (`usage.js:27-70`). With one, it does none of that — so the usage branch has
-//     to terminate on its own. `showHelp()` happens to set `hasOutput`
-//     (`yargs-factory.js:834`), which blocks the handler while the chain is still
-//     synchronous, but that is a side effect, not a guarantee: `throw` is what
-//     survives a future async builder or middleware.
-//
-//  4. NEVER RE-THROW THE INCOMING `YError`. `yargs-factory.js:1471-1475` routes
-//     that class back into `usage.fail()`, so re-throwing it prints the help a
-//     second time. The usage branch throws a plain `Error` with the original
-//     attached as `cause`.
-//
-// The runtime branch deliberately prints NOTHING and exits NOTHING: the rejection
-// propagates out of `parseAsync()` on its own, and `index.ts` is the single
-// printer (it also handles `GJSIFY_DEBUG` stacks and the GJS-side `gjsExit(1)`,
-// which a second printer here would duplicate). Suppressing yargs'
-// help-and-exit IS this branch's whole job — it only looks like a no-op.
+// The runtime branch prints and exits NOTHING on purpose: the rejection
+// propagates out of `parseAsync()` and `index.ts` is the single printer (it owns
+// `GJSIFY_DEBUG` stacks and the GJS-side `gjsExit(1)`). Suppressing yargs'
+// help-and-exit is this branch's whole job — it only looks like a no-op.
 /**
  * Classify a yargs `fail(msg, err)` callback into the two cases that need
- * different output.
- *
- * Pure on purpose — the whole point is that the rule is testable without
- * driving a process to its death. `cli-fail.spec.ts` additionally pins the
- * yargs-side half (which call site passes `null`) against a real instance, so a
- * yargs upgrade that changes the routing fails a test instead of silently
- * turning every runtime error back into a help dump.
+ * different output. Kept pure so the rule is testable without driving a process
+ * to its death; `cli-fail.spec.ts` pins the yargs-side half against a real
+ * instance, so a yargs upgrade that reroutes `fail` fails a test instead of
+ * silently turning every runtime error back into a help dump.
  */
 export function classifyCliFailure(msg, _err) {
-    // A non-empty string means yargs itself diagnosed the argv. An empty string
-    // is treated as "no message" rather than as an empty usage error: it carries
-    // nothing to print, and printing help with no reason is the worst of both.
+    // An empty string counts as "no message", not as an empty usage error: it has
+    // nothing to print, and help with no reason is the worst of both.
     if (typeof msg === 'string' && msg.length > 0)
         return { kind: 'usage', message: msg };
     return { kind: 'runtime' };