@gjsify/cli 0.48.0 → 0.50.0

package/lib/commands/workspace.js

@@ -14,13 +14,16 @@
 // dependency, in topological build order, then in the target package.
 // Skips deps that don't declare the script (`--if-present` behaviour).
 // Stops on the first failure unless `--continue-on-error` is passed.
+// A local dependency counts whether it is declared with the `workspace:`
+// protocol or with a plain range the local member satisfies (@gjsify/workspace
+// § buildDependencyGraph) — and the expansion SAYS when it found nothing.
 //
 // This replaces the manual `gjsify workspace <A> build && gjsify workspace
 // <B> build && …` chains in root `build:infra` scripts: cascade build
 // failures on uninbuilt workspace deps are the single biggest local-dev
 // pain point in this monorepo.
 import { spawnToCompletion } from '../utils/spawn.js';
-import { buildDependencyGraph, discoverWorkspaces, topologicalSort } from '@gjsify/workspace';
+import { affectedClosure, buildDependencyGraph, discoverWorkspaces, topologicalSort, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
@@ -135,11 +138,29 @@ export const workspaceCommand = {
         // target itself.
         let runList;
         if (withDeps) {
-            const closure = collectTransitiveClosure(target, allWorkspaces, args['include-dev'] === true);
-            // Sort the closure topologically using the shared @gjsify/workspace
-            // algorithm — same code path that drives `gjsify foreach -t`.
-            const graph = buildDependencyGraph(closure, { includeDev: args['include-dev'] === true });
+            const includeDev = args['include-dev'] === true;
+            // The SHARED graph, walked by the shared closure — the same two calls
+            // `gjsify foreach --with-dependencies` makes. This used to be a private
+            // copy of the walk here, and the copy is where the defect lived: it
+            // followed `workspace:` edges only, so in a monorepo declaring its local
+            // deps by plain semver range it matched nothing, built nothing and exited
+            // 0 (#1587). One walk means the rule for "what is a local dependency" has
+            // one place to be wrong in.
+            const forward = buildDependencyGraph(allWorkspaces, { includeDev });
+            const names = affectedClosure(forward, [target.name]);
+            const closure = allWorkspaces.filter((ws) => names.has(ws.name));
+            reportUnlinked(forward.unlinked, names);
+            const graph = buildDependencyGraph(closure, { includeDev });
             runList = topologicalSort(graph);
+            if (runList.length === 1) {
+                // The expansion found nothing, and it SAYS so. A leaf package
+                // legitimately has no local dependencies, but "no local dependencies"
+                // and "the flag could not see them" produced the same silent exit 0,
+                // and that ambiguity is what cost a Flatpak build, a container run and
+                // a manual `ls` to resolve.
+                console.error(`gjsify workspace: --with-dependencies found no workspace dependencies of ` +
+                    `"${target.name}" — running "${script}" in it alone.`);
+            }
         }
         else {
             runList = [target];
@@ -197,48 +218,30 @@ export const workspaceCommand = {
     },
 };
 /**
- * Walk the workspace-dep graph from `target`, collecting every transitive
- * workspace dependency (production + optional, plus devDependencies when
- * `includeDev`). The returned list includes `target` itself so the caller
- * can pass it straight to `buildDependencyGraph` / `topologicalSort`.
+ * Name a dependency that points at a local workspace but does not link to it, because
+ * the member's version does not satisfy the declared range.
+ *
+ * Only entries declared BY a package in the closure are printed: an unlinked pair
+ * elsewhere in the monorepo is somebody else's business, and printing all of them would
+ * bury the one that explains why this closure is the size it is.
+ *
+ * This is a warning, not a failure, and it deliberately asserts NO outcome, because the
+ * outcome depends on which installer placed `node_modules`: npm and yarn fetch such a
+ * dependency from the registry — the rule the graph follows, under which leaving it out of
+ * the build order is simply right — while `gjsify install` symlinks the local member
+ * whatever the range says. Under that one the build order really is short a package, so
+ * the message asks for the range and the version to be brought into agreement instead of
+ * telling the reader where the files came from.
  */
-function collectTransitiveClosure(target, allWorkspaces, includeDev) {
-    const byName = new Map();
-    for (const ws of allWorkspaces)
-        byName.set(ws.name, ws);
-    const seen = new Set();
-    const out = [];
-    const stack = [target];
-    while (stack.length > 0) {
-        const ws = stack.pop();
-        if (seen.has(ws.name))
+function reportUnlinked(unlinked, closure) {
+    for (const entry of unlinked) {
+        if (!closure.has(entry.from))
             continue;
-        seen.add(ws.name);
-        out.push(ws);
-        const m = ws.manifest;
-        const blocks = [
-            m.dependencies,
-            includeDev ? m.devDependencies : undefined,
-            m.optionalDependencies,
-            // peerDependencies excluded by default (yarn does the same)
-        ];
-        for (const block of blocks) {
-            if (!block)
-                continue;
-            for (const [depName, spec] of Object.entries(block)) {
-                if (typeof spec !== 'string')
-                    continue;
-                if (!spec.startsWith('workspace:'))
-                    continue;
-                const dep = byName.get(depName);
-                if (!dep)
-                    continue;
-                if (!seen.has(dep.name))
-                    stack.push(dep);
-            }
-        }
+        console.error(`gjsify workspace: "${entry.from}" depends on "${entry.to}": ${entry.spec}, which the local ` +
+            `workspace (${entry.to}@${entry.version}) does not satisfy — NOT built as a dependency. ` +
+            `npm and yarn take that one from the registry; \`gjsify install\` links the local one ` +
+            `anyway, so if it is the local one you mean, make the range admit ${entry.version}.`);
     }
-    return out;
 }
 async function runOne(ws, script, extraArgs, runner, verbose, cache) {
     // Build-cache fast path: on a key hit restore the stored outputs and

package/lib/config.js

@@ -5,6 +5,7 @@ import { pathToFileURL } from 'node:url';
 import { isGjs, hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { buildAppForRuntime } from './utils/runtimes.js';
 import { DIALECT_APPS, isSourceDialect, SOURCE_DIALECTS } from '@gjsify/rolldown-plugin-gjsify';
+import { GI_RENDERER_APPS } from '@gjsify/resolve-npm';
 /**
  * Does the failed `import()` of a config look like a MODULE-RESOLUTION failure
  * (the config imports something GJS's ESM loader can't resolve for an external
@@ -269,6 +270,8 @@ export class Config {
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined)
             configData.consoleShim = cliArgs.consoleShim;
+        if (cliArgs.giRenderer !== undefined)
+            configData.giRenderer = cliArgs.giRenderer;
         // `--dialect` narrows here rather than at the call site. yargs `choices`
         // already rejects an unknown value typed on the command line, but a
         // `gjsify.dialect` in package.json or `.gjsifyrc.*` never passes through
@@ -303,6 +306,16 @@ export class Config {
                 `It composes on ${[...DIALECT_APPS].join(' and ')} only. ` +
                 'Drop the dialect, or build one of those targets.');
         }
+        // Same rule for the `gi://` arm, and the same reason: `--gi-renderer --app gjs`
+        // would parse, resolve and compose nothing, so the flag would be accepted and
+        // ignored. On `gjs` and `node` the specifier is already answered — natively and
+        // through `requireGi` — so there is nothing for a renderer to substitute for.
+        if (configData.giRenderer === true && !GI_RENDERER_APPS.includes(configData.app)) {
+            throw new Error(`gjsify build: --gi-renderer has no effect on --app ${configData.app}. ` +
+                `It composes on ${GI_RENDERER_APPS.join(' and ')} only — the targets with no GObject ` +
+                'introspection to answer `gi://` with. `--app gjs` resolves it natively and `--app node` ' +
+                'through @gjsify/node-gi, so neither needs a widget renderer standing in for it.');
+        }
         if (cliArgs.globals !== undefined)
             configData.globals = cliArgs.globals;
         // Fallback applied post-merge (not as a yargs `default:`) so a

package/lib/index.js

@@ -6,6 +6,7 @@
 // This file is just the executable wrapper around `runCli`.
 import { hideBin } from 'yargs/helpers';
 import { runCli } from './cli-app.js';
+import { exitOnReportedFailure } from './utils/cli-exit.js';
 import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
 try {
     await runCli(hideBin(process.argv));
@@ -43,3 +44,12 @@ catch (err) {
     process.exitCode = 1;
     gjsExit(1);
 }
+// The catch above is only HALF the entry's exit funnel, and the other half was
+// missing: a handler that reports a failure by assigning `process.exitCode` and
+// returning normally never reaches it. That is the Node idiom and the CLI uses
+// it wherever the failure is already printed in full (`gjsify gresource`,
+// `gjsify gsettings`, `gjsify barrels --check`, `setOxcExitCode`) — and under
+// GJS, which has no atexit hook, nothing read it back, so the process ended 0
+// with the error on stderr. `cli-exit.ts` carries the measurement and why `&&`
+// did not protect against it (JumpLink/Learn6502#180).
+exitOnReportedFailure();

package/lib/types/cli-build-options.d.ts

@@ -36,6 +36,12 @@ export interface CliBuildOptions {
      * whatever was typed, and the narrowing happens once, where the value is read.
      */
     dialect?: string;
+    /**
+     * Resolve `gi://Ns?version=X` to the target's widget renderer instead of an empty
+     * module — `--gi-renderer` (ADR 0034 stage 9). `browser` and `nativescript` targets.
+     * Default: unset; see `ConfigData.giRenderer` for why it is opt-in.
+     */
+    giRenderer?: boolean;
     /**
      * Comma-separated global identifiers the code needs, e.g.
      * `"fetch,Buffer,process,URL,crypto"`. Each maps to the corresponding

package/lib/types/config-data.d.ts

@@ -96,6 +96,20 @@ export interface ConfigData {
      * see the header of `SourceDialect`.
      */
     dialect?: SourceDialect;
+    /**
+     * Resolve `gi://Ns?version=X` to the target's widget renderer rather than to an
+     * empty module (ADR 0034 stage 9). `--app browser` answers out of
+     * `@gjsify/adwaita-web`, `--app nativescript` out of `@gjsify/adwaita-nativescript`;
+     * `GI_RENDERERS` in `@gjsify/resolve-npm` is the table, and a target with no row
+     * there has no arm. Default: unset.
+     *
+     * Opt-in, never inferred: a `gi://` import reaching one of those targets today is
+     * usually a GJS-only code path pulled in transitively, which the empty module
+     * silences on purpose. On by default it would pull a widget toolkit into bundles
+     * that never named one, and turn every unanswerable namespace from a silent stub
+     * into a hard build failure.
+     */
+    giRenderer?: boolean;
     /** Comma-separated global identifiers to register. Format: see CliBuildOptions. */
     globals?: string;
     /**

package/lib/utils/build-cache.d.ts

@@ -11,9 +11,19 @@ import { type Workspace } from '@gjsify/workspace';
  * still on v2's whole-dir ownership and could restore over a sibling unit; a v2
  * manifest for them records `lib`, so it must not be replayed against the
  * per-child units this version stores.
+ *
+ * v4: the input set is now `packageBuildInputs` instead of `src/**` + the
+ * manifests (#1651). Every v3 key was computed over a strictly narrower set,
+ * so replaying one would report a hit for a change it could not have seen.
+ */
+export declare const BUILD_CACHE_LAYOUT_VERSION = "v4";
+/**
+ * Conventional per-package build output directories, checked in this order.
+ *
+ * Deliberately the same constant the input definition subtracts: a directory
+ * this cache STORES as an output must never also be hashed as an input, or
+ * storing it would invalidate the key it was stored under.
  */
-export declare const BUILD_CACHE_LAYOUT_VERSION = "v3";
-/** Conventional per-package build output directories, checked in this order. */
 export declare const OUTPUT_DIR_CANDIDATES: readonly ["lib", "dist", "dist-templates"];
 /** Keep at most this many keys per package; evict the least recently stored/used. */
 export declare const MAX_KEYS_PER_PACKAGE = 2;
@@ -45,8 +55,9 @@ export declare function sanitizePackageDirName(name: string): string;
 /** Streamed sha256 of one file (bounded memory, real contents). */
 export declare function hashFileStream(path: string): string;
 /**
- * Content hash of a package's build INPUTS: every file under `src/**`, plus
- * `package.json`, plus root `tsconfig*.json`. Sorted, content-streamed —
+ * Content hash of a package's build INPUTS — the set is
+ * {@link packageBuildInputs}, shared with `gjsify test`'s freshness check so
+ * the two cannot drift about what an input is. Sorted, content-streamed:
  * mtimes do not participate, so a `git checkout` with identical contents
  * hashes identically across machines.
  */

package/lib/utils/build-cache.js

@@ -11,9 +11,9 @@
 //   - a toolchain salt (workspace-resolved versions of @gjsify/cli,
 //     @gjsify/tsc, rolldown, typescript — a bundler/compiler bump must
 //     invalidate everything),
-//   - the package's own input hash (every file under `src/**`, plus
-//     `package.json`, plus the package's root `tsconfig*.json` — real file
-//     contents, streamed sha256, sorted for determinism),
+//   - the package's own input hash — `packageBuildInputs`, the ONE definition
+//     of "what are this package's build inputs" (`utils/package-inputs.ts`),
+//     hashed by real file contents, streamed sha256, sorted for determinism,
 //   - the input hashes of EVERY workspace dependency in the package's
 //     transitive dep closure (prod + dev + optional + peer `workspace:`
 //     edges). Composing the closure's OWN hashes (instead of recursing into
@@ -54,6 +54,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { buildDependencyGraph } from '@gjsify/workspace';
 import { replicateLinkSync } from './dir-link.js';
+import { CONVENTIONAL_OUTPUT_DIRS, packageBuildInputs } from './package-inputs.js';
 /**
  * Bump to invalidate every existing cache entry (schema/semantic changes).
  *
@@ -66,10 +67,20 @@ import { replicateLinkSync } from './dir-link.js';
  * still on v2's whole-dir ownership and could restore over a sibling unit; a v2
  * manifest for them records `lib`, so it must not be replayed against the
  * per-child units this version stores.
+ *
+ * v4: the input set is now `packageBuildInputs` instead of `src/**` + the
+ * manifests (#1651). Every v3 key was computed over a strictly narrower set,
+ * so replaying one would report a hit for a change it could not have seen.
  */
-export const BUILD_CACHE_LAYOUT_VERSION = 'v3';
-/** Conventional per-package build output directories, checked in this order. */
-export const OUTPUT_DIR_CANDIDATES = ['lib', 'dist', 'dist-templates'];
+export const BUILD_CACHE_LAYOUT_VERSION = 'v4';
+/**
+ * Conventional per-package build output directories, checked in this order.
+ *
+ * Deliberately the same constant the input definition subtracts: a directory
+ * this cache STORES as an output must never also be hashed as an input, or
+ * storing it would invalidate the key it was stored under.
+ */
+export const OUTPUT_DIR_CANDIDATES = CONVENTIONAL_OUTPUT_DIRS;
 /** Keep at most this many keys per package; evict the least recently stored/used. */
 export const MAX_KEYS_PER_PACKAGE = 2;
 /** Toolchain packages whose resolved versions salt every cache key. */
@@ -113,11 +124,50 @@ export function hashFileStream(path) {
     }
     return hash.digest('hex');
 }
-// Recursive, sorted file walk. Yields workspace-relative paths (forward
-// slashes). Directory symlinks are NOT followed (loop safety) — the link
-// target string participates in the hash instead. `node_modules` and the
-// output dirs never appear because callers only walk `src/` + explicit root
-// files, but guard anyway for nested oddities.
+/**
+ * Content hash of a package's build INPUTS — the set is
+ * {@link packageBuildInputs}, shared with `gjsify test`'s freshness check so
+ * the two cannot drift about what an input is. Sorted, content-streamed:
+ * mtimes do not participate, so a `git checkout` with identical contents
+ * hashes identically across machines.
+ */
+export function hashPackageInputs(location) {
+    const files = packageBuildInputs(location);
+    const hash = createHash('sha256');
+    hash.update(`gjsify-build-cache-inputs/${BUILD_CACHE_LAYOUT_VERSION}\n`);
+    for (const f of files) {
+        if (f.link !== undefined) {
+            // Symlink: try content (file links), fall back to the target path.
+            let content;
+            try {
+                content = hashFileStream(f.abs);
+            }
+            catch {
+                content = `link:${f.link}`;
+            }
+            hash.update(`${f.rel} ${content}\n`);
+            continue;
+        }
+        try {
+            hash.update(`${f.rel} ${hashFileStream(f.abs)}\n`);
+        }
+        catch {
+            // Vanished mid-hash (concurrent edit) — record the absence so the
+            // key still changes vs. the file being present.
+            hash.update(`${f.rel} unreadable\n`);
+        }
+    }
+    return hash.digest('hex');
+}
+/**
+ * Recursive, sorted walk of an OUTPUT tree, yielding `/`-separated relative
+ * paths. Directory symlinks are not followed (loop safety) — the link target
+ * string participates in the hash instead.
+ *
+ * Deliberately NOT `packageBuildInputs`: this one is handed a directory that
+ * the input walk subtracts, and it must report everything inside it, dot-files
+ * included — an emitted `.gresource` is part of what was built.
+ */
 function walkFiles(dir, prefix, out) {
     let entries;
     try {
@@ -140,11 +190,8 @@ function walkFiles(dir, prefix, out) {
             continue;
         }
         if (st.isSymbolicLink()) {
-            // File symlinks: hash the resolved content below if readable;
-            // dir symlinks: record the target only.
             try {
-                const target = readlinkSync(abs);
-                out.push({ rel, abs, link: target });
+                out.push({ rel, abs, link: readlinkSync(abs) });
             }
             catch {
                 /* dropped mid-walk */
@@ -158,58 +205,6 @@ function walkFiles(dir, prefix, out) {
         }
     }
 }
-/**
- * Content hash of a package's build INPUTS: every file under `src/**`, plus
- * `package.json`, plus root `tsconfig*.json`. Sorted, content-streamed —
- * mtimes do not participate, so a `git checkout` with identical contents
- * hashes identically across machines.
- */
-export function hashPackageInputs(location) {
-    const files = [];
-    const pkgJson = join(location, 'package.json');
-    if (existsSync(pkgJson))
-        files.push({ rel: 'package.json', abs: pkgJson });
-    let rootEntries = [];
-    try {
-        rootEntries = readdirSync(location);
-    }
-    catch {
-        /* unreadable package dir — hash degenerates to the empty set */
-    }
-    for (const entry of rootEntries.sort()) {
-        if (/^tsconfig.*\.json$/.test(entry)) {
-            files.push({ rel: entry, abs: join(location, entry) });
-        }
-    }
-    const srcDir = join(location, 'src');
-    if (existsSync(srcDir))
-        walkFiles(srcDir, 'src', files);
-    const hash = createHash('sha256');
-    hash.update(`gjsify-build-cache-inputs/${BUILD_CACHE_LAYOUT_VERSION}\n`);
-    for (const f of files) {
-        if (f.link !== undefined) {
-            // Symlink: try content (file links), fall back to the target path.
-            let content;
-            try {
-                content = hashFileStream(f.abs);
-            }
-            catch {
-                content = `link:${f.link}`;
-            }
-            hash.update(`${f.rel} ${content}\n`);
-            continue;
-        }
-        try {
-            hash.update(`${f.rel} ${hashFileStream(f.abs)}\n`);
-        }
-        catch {
-            // Vanished mid-hash (concurrent edit) — record the absence so the
-            // key still changes vs. the file being present.
-            hash.update(`${f.rel} unreadable\n`);
-        }
-    }
-    return hash.digest('hex');
-}
 /**
  * Mtime-independent content hash of a set of output dirs — used to skip the
  * restore copy when the on-disk outputs already match the cached entry, and

package/lib/utils/cli-exit.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The status a settled CLI run still owes the shell, or `null` when it owes
+ * none.
+ *
+ * @param exitCode what `process.exitCode` holds now — `number | string | null |
+ *   undefined`, the full set Node accepts for that property.
+ * @param isDaemon whether the command declared itself a daemon. A watch loop
+ *   RESOLVES as soon as it is armed and keeps running, so its resolution is not
+ *   an ending to exit on — the same rule `gjsify run`'s fast path applies, and
+ *   the incident behind it (`gjsify run dev` killing the loop it had just
+ *   started) is in `daemon-command.ts`.
+ */
+export declare function pendingFailureCode(exitCode: number | string | null | undefined, isDaemon: boolean): number | null;
+/**
+ * End a settled CLI run on the status its handler reported, on both runtimes.
+ *
+ * No-op unless a handler actually reported a failure. On Node it is a no-op
+ * even then — `gjsExit` finds no `imports.system` and the runtime honours
+ * `process.exitCode` at natural shutdown by itself, which is why this does NOT
+ * reach for `process.exit()`: that would cut short the stdout flush Node's own
+ * idiom exists to allow.
+ */
+export declare function exitOnReportedFailure(): void;

package/lib/utils/cli-exit.js

@@ -0,0 +1,78 @@
+// The CLI has TWO ways to fail, and until now only one of them reached the shell
+// under GJS.
+//
+// A command handler either THROWS — `index.ts` catches it, prints, and calls
+// `gjsExit(1)` — or it REPORTS the failure by assigning `process.exitCode` and
+// returning normally. The second shape is the documented Node idiom (streams
+// flush, the process ends naturally) and the CLI uses it wherever a failure has
+// already been printed in full: `gjsify gresource`/`gjsify gsettings` propagate
+// the code `glib-compile-*` exited with, `gjsify barrels --check` reports drift,
+// `setOxcExitCode` propagates a formatter's verdict.
+//
+// **Under GJS that assignment is a REPORT and nothing more.** There is no atexit
+// hook, so nothing reads `process.exitCode` back at natural shutdown and the
+// process ends 0. Measured on the v0.49.0 bundle, same argv, same broken input:
+//
+//     $ node lib/index.js  gresource broken.gresource.xml   → exit 1
+//     $ gjs -m dist/cli.gjs.mjs gresource broken.gresource.xml → exit 0
+//       ("[gjsify gresource] glib-compile-resources failed (exit 1)" printed)
+//
+// and the same split for `gjsify gsettings` and `gjsify barrels --check`. The
+// consequence is not a cosmetic status: a package script chaining on it runs the
+// next step over an artifact that was never written —
+//
+//     "build:resources": "gjsify gresource … && echo SECOND"
+//       → SECOND printed, script exits 0   (JumpLink/Learn6502#180)
+//
+// — which is exactly the shape `&&` is supposed to protect. `gjsify run`'s
+// in-process fast path was already immune (it reads `process.exitCode` back
+// itself, #1568), so the hole survived precisely in the SPAWNED command, i.e.
+// in every chained script and every direct CI invocation.
+//
+// This module is the missing half of the entry's exit funnel, and a sibling of
+// `force-exit.ts`: that one is for a caller that knows the code it wants NOW,
+// this one for the status a settled run left behind. The rule is pure so it can
+// be stated as a test without driving a process to its death.
+//
+// Related, and deliberately distinct: `gjsify/deferred-process-exit` (oxlint)
+// covers the OTHER GJS exit trap, a bare `process.exit()` that does not halt.
+// No lint rule could have caught this one — every `process.exitCode = …` site
+// is correct; the entry was not reading them.
+import { gjsExit } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { isDaemonCommand } from './daemon-command.js';
+/**
+ * The status a settled CLI run still owes the shell, or `null` when it owes
+ * none.
+ *
+ * @param exitCode what `process.exitCode` holds now — `number | string | null |
+ *   undefined`, the full set Node accepts for that property.
+ * @param isDaemon whether the command declared itself a daemon. A watch loop
+ *   RESOLVES as soon as it is armed and keeps running, so its resolution is not
+ *   an ending to exit on — the same rule `gjsify run`'s fast path applies, and
+ *   the incident behind it (`gjsify run dev` killing the loop it had just
+ *   started) is in `daemon-command.ts`.
+ */
+export function pendingFailureCode(exitCode, isDaemon) {
+    if (isDaemon)
+        return null;
+    if (exitCode === null || exitCode === undefined)
+        return null;
+    const code = Number(exitCode);
+    // A non-finite value cannot be assigned to `process.exitCode` on Node at
+    // all, so there is no failure here to invent one from.
+    return Number.isFinite(code) && code !== 0 ? code : null;
+}
+/**
+ * End a settled CLI run on the status its handler reported, on both runtimes.
+ *
+ * No-op unless a handler actually reported a failure. On Node it is a no-op
+ * even then — `gjsExit` finds no `imports.system` and the runtime honours
+ * `process.exitCode` at natural shutdown by itself, which is why this does NOT
+ * reach for `process.exit()`: that would cut short the stdout flush Node's own
+ * idiom exists to allow.
+ */
+export function exitOnReportedFailure() {
+    const code = pendingFailureCode(process.exitCode, isDaemonCommand());
+    if (code !== null)
+        gjsExit(code);
+}

package/lib/utils/detect-native-packages.d.ts

@@ -233,6 +233,37 @@ export declare function resolveHostLibc(input: {
  * reach it.
  */
 export declare function detectHostLibc(platform: string): HostLibc | null;
+/**
+ * The packages a musl host had to take the DEFAULT prebuild of, because they ship
+ * no `-musl` directory — the fallback {@link hostPlatformTokens} deliberately
+ * allows, named so a caller can report it. Returns names and prints nothing: this
+ * module resolves, and `libc` is a parameter for the same reason it is on every
+ * other function here (there is no musl runner in this repo's CI, so an injected
+ * `libc: 'musl'` is the only way the branch executes).
+ *
+ * Why a fallback that mostly WORKS is worth naming. musl's loader resolves
+ * `libc.so.6`/`libm.so.6` to itself, so a glibc-linked prebuild loads — and a
+ * bridge that records no libc at all then runs correctly, which is why the
+ * fallback exists rather than resolving to null. The one that is NOT agnostic dies
+ * at `dlopen` on its first glibc-only symbol, far from its cause. Measured on a
+ * OnePlus 6 (postmarketOS v26.06, musl 1.2.6, aarch64, gjs 1.88.1) against the
+ * published 0.48.0 train: nine of ten prebuilds loaded, while
+ * `@gjsify/lightningcss-native-linux-arm64` answered `gnu_get_libc_version: symbol
+ * not found`. `gjsify install` had printed "System dependencies OK", and the first
+ * symptom was rolldown reporting `Could not load src/application.css` — the CSS
+ * bridge silently absent from the bundle. Nothing in that chain names libc, which
+ * is what makes the report worth more than the failure.
+ *
+ * Membership goes through {@link parsePlatformToken}, not the suffix constant, so
+ * this does not become a second reader of the libc half of the token grammar —
+ * `darwin-arm64-musl` is a malformed token rather than a musl build, and only the
+ * grammar knows that.
+ *
+ * TODO(open-todos: `-musl` prebuild package is published): naming the fallback is
+ * not fixing it. No `-musl` target is published for any bridge, so on a musl host
+ * this reports every prebuild in the tree and there is nothing to fall back FROM.
+ */
+export declare function muslPrebuildFallbacks(libc: HostLibc | null, packages: readonly NativePackage[]): string[];
 /**
  * The environment-variable name the host's dynamic loader consults for an
  * additional shared-library search path, plus the separator its search paths

package/lib/utils/detect-native-packages.js

@@ -22,7 +22,7 @@
 // win32 AND musl branches unit-testable from a glibc Linux host. The host values
 // are read only at the outermost call site, as a default.
 import { readdirSync, existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { readPackageJson } from './pkg-json.js';
 import { composeDyldFallback, systemGiLibraryDirs } from './system-gi.js';
 /**
@@ -500,6 +500,42 @@ export function detectHostLibc(platform) {
     const muslLoaderPresent = existsSync('/lib') && readdirSync('/lib').some((f) => f.startsWith('ld-musl-'));
     return resolveHostLibc({ platform, glibcVersionRuntime, muslLoaderPresent });
 }
+/**
+ * The packages a musl host had to take the DEFAULT prebuild of, because they ship
+ * no `-musl` directory — the fallback {@link hostPlatformTokens} deliberately
+ * allows, named so a caller can report it. Returns names and prints nothing: this
+ * module resolves, and `libc` is a parameter for the same reason it is on every
+ * other function here (there is no musl runner in this repo's CI, so an injected
+ * `libc: 'musl'` is the only way the branch executes).
+ *
+ * Why a fallback that mostly WORKS is worth naming. musl's loader resolves
+ * `libc.so.6`/`libm.so.6` to itself, so a glibc-linked prebuild loads — and a
+ * bridge that records no libc at all then runs correctly, which is why the
+ * fallback exists rather than resolving to null. The one that is NOT agnostic dies
+ * at `dlopen` on its first glibc-only symbol, far from its cause. Measured on a
+ * OnePlus 6 (postmarketOS v26.06, musl 1.2.6, aarch64, gjs 1.88.1) against the
+ * published 0.48.0 train: nine of ten prebuilds loaded, while
+ * `@gjsify/lightningcss-native-linux-arm64` answered `gnu_get_libc_version: symbol
+ * not found`. `gjsify install` had printed "System dependencies OK", and the first
+ * symptom was rolldown reporting `Could not load src/application.css` — the CSS
+ * bridge silently absent from the bundle. Nothing in that chain names libc, which
+ * is what makes the report worth more than the failure.
+ *
+ * Membership goes through {@link parsePlatformToken}, not the suffix constant, so
+ * this does not become a second reader of the libc half of the token grammar —
+ * `darwin-arm64-musl` is a malformed token rather than a musl build, and only the
+ * grammar knows that.
+ *
+ * TODO(open-todos: `-musl` prebuild package is published): naming the fallback is
+ * not fixing it. No `-musl` target is published for any bridge, so on a musl host
+ * this reports every prebuild in the tree and there is nothing to fall back FROM.
+ */
+export function muslPrebuildFallbacks(libc, packages) {
+    if (libc !== 'musl')
+        return [];
+    const fellBack = packages.filter((pkg) => parsePlatformToken(basename(pkg.prebuildsDir)).libc !== 'musl');
+    return fellBack.map((pkg) => pkg.name);
+}
 /**
  * The environment-variable name the host's dynamic loader consults for an
  * additional shared-library search path, plus the separator its search paths