@gjsify/cli 0.4.44 → 0.5.1

package/lib/commands/run.js

@@ -33,10 +33,25 @@ export const runCommand = {
         type: 'string',
         array: true,
         default: [],
+    })
+        .parserConfiguration({
+        // Preserve `--` as args['--'] so callers can write
+        //   gjsify run ./server.mjs -- --port 8080
+        // without yargs intercepting --port as its own option.
+        // Without this, anything after `--` lands in args._ and is
+        // silently dropped by the handler.
+        'populate--': true,
     }),
     handler: async (args) => {
         const target = args.target;
-        const extraArgs = args.args ?? [];
+        // Collect positional args AND anything after the `--` separator.
+        // With `parserConfiguration({ 'populate--': true })` in the builder,
+        // `gjsify run target -- a b c` puts a, b, c into args['--'] rather
+        // than silently discarding them (without it they land in args._ and
+        // are never forwarded to the child).
+        const positionalArgs = args.args ?? [];
+        const doubleDashArgs = (args['--'] ?? []).filter((v) => typeof v === 'string');
+        const extraArgs = [...positionalArgs, ...doubleDashArgs];
         // Script lookup wins over file detection. Without this, a bare
         // `gjsify run build` would resolve to a file when a `./build`
         // directory exists in cwd (e.g. meson's build dir from a Vala
@@ -47,7 +62,9 @@ export const runCommand = {
         const hasScript = pkg?.scripts && typeof pkg.scripts[target] === 'string';
         if (!hasScript && looksLikeFile(target)) {
             const file = resolve(target);
-            await runGjsBundle(file, extraArgs);
+            // Terminal call — exit on success, or the GJS main loop parks
+            // this process forever (see RunGjsBundleOptions.exitOnSuccess).
+            await runGjsBundle(file, extraArgs, { exitOnSuccess: true });
             return;
         }
         await runScript(target, extraArgs);
@@ -117,6 +134,43 @@ async function runScript(script, extraArgs) {
         npm_package_name: pkg.name ?? '',
         npm_package_version: pkg.version ?? '',
     };
+    // In-process fast path: under GJS, the build orchestration chains a
+    // heavyweight gjs per level (`foreach → npm → gjsify run X → gjsify <cmd>`),
+    // which oversubscribes CI's few cores and thrashes. When the script is a
+    // single `gjsify <subcommand>` (no shell operators / substitutions /
+    // unquoted globs), dispatch it through the same yargs surface IN THIS
+    // process instead of spawning another gjs — collapsing two gjs into one.
+    // Anything fancier (compound `&&`, pipes, a non-gjsify command) falls
+    // through to the shell spawn below. Node keeps spawning (cheap there); this
+    // only triggers under GJS, where the nesting actually hurts. See cli-app.ts.
+    const inProcArgv = runningUnderGjs() ? gjsifyInProcessArgv(literal, extraArgs) : null;
+    if (inProcArgv) {
+        // The subcommand runs in our process, so surface the script env on
+        // `process.env` (PATH with the workspace .bin dirs, npm_* lifecycle
+        // vars) exactly as the spawn path would. We process.exit afterwards, so
+        // mutating the global env is fine.
+        process.env.PATH = env.PATH;
+        process.env.npm_lifecycle_event = env.npm_lifecycle_event;
+        process.env.npm_package_name = env.npm_package_name;
+        process.env.npm_package_version = env.npm_package_version;
+        if (env.FORCE_COLOR !== undefined)
+            process.env.FORCE_COLOR = env.FORCE_COLOR;
+        try {
+            // Dynamic import to avoid a static cli-app ↔ run.ts import cycle;
+            // cli-app is already loaded (the CLI is running through it), so this
+            // resolves from cache instantly.
+            const { runCli } = await import('../cli-app.js');
+            await runCli(inProcArgv);
+        }
+        catch (err) {
+            console.error(err.message);
+            process.exit(1);
+        }
+        // Honor a non-zero `process.exitCode` set by the dispatched handler
+        // (e.g. a failing check that sets the code instead of exiting) —
+        // a bare exit(0) here masked such failures as success.
+        process.exit(process.exitCode != null ? Number(process.exitCode) : 0);
+    }
     const fullCmd = extraArgs.length > 0 ? `${literal} ${extraArgs.map(shellEscape).join(' ')}` : literal;
     // ensureMainLoop() (called inside spawn) keeps GJS alive after the
     // child exits — without an explicit process.exit() the success path
@@ -141,3 +195,79 @@ function shellEscape(arg) {
         return arg;
     return `'${arg.replace(/'/g, "'\\''")}'`;
 }
+// Detected at CALL time (a module-load const reads `undefined` in the bundled
+// `--app gjs` form). `bundler-pick.ts` uses the same expression.
+function runningUnderGjs() {
+    return typeof globalThis.imports?.gi !== 'undefined';
+}
+/**
+ * If `literal` is a SINGLE `gjsify <subcommand> …` command with no shell
+ * operators / substitutions / unquoted globs, return the argv to feed `runCli`
+ * (the subcommand + its args, with `extraArgs` appended). Otherwise null — the
+ * caller falls back to the shell spawn path. Quotes are honoured so a quoted
+ * glob (`'src/**'`) survives as a single literal token, exactly as the shell
+ * would hand it to `gjsify` (which does its own glob expansion).
+ */
+function gjsifyInProcessArgv(literal, extraArgs) {
+    const tokens = tokenizeSimpleCommand(literal);
+    if (!tokens || tokens.length < 2 || tokens[0] !== 'gjsify')
+        return null;
+    return [...tokens.slice(1), ...extraArgs];
+}
+/**
+ * Quote-aware tokenizer for a SIMPLE command line (no shell features beyond
+ * single/double quoting). Returns the tokens, or null if the string contains
+ * anything the shell would treat specially — operators (`&& | ; < > &`),
+ * substitutions (`$(...)` / backticks / `$VAR`), unquoted globs/expansions
+ * (`* ? { } [ ] ~`), comments (`#`), or an unterminated quote — in which case
+ * the caller MUST use the real shell instead.
+ */
+function tokenizeSimpleCommand(cmd) {
+    const tokens = [];
+    let cur = '';
+    let has = false;
+    let quote = null;
+    for (let i = 0; i < cmd.length; i++) {
+        const c = cmd[i];
+        if (quote === "'") {
+            if (c === "'")
+                quote = null;
+            else
+                cur += c;
+            continue;
+        }
+        if (quote === '"') {
+            if (c === '"')
+                quote = null;
+            else if (c === '\\' && (cmd[i + 1] === '"' || cmd[i + 1] === '\\'))
+                cur += cmd[++i];
+            else if (c === '$' || c === '`')
+                return null; // substitution inside "…"
+            else
+                cur += c;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            quote = c;
+            has = true;
+            continue;
+        }
+        if (c === ' ' || c === '\t') {
+            if (has) {
+                tokens.push(cur);
+                cur = '';
+                has = false;
+            }
+            continue;
+        }
+        if ('|&;<>`$()\\\n\r*?{}[]~#!'.includes(c))
+            return null;
+        cur += c;
+        has = true;
+    }
+    if (quote)
+        return null; // unterminated quote
+    if (has)
+        tokens.push(cur);
+    return tokens;
+}

package/lib/commands/test.js

@@ -126,6 +126,11 @@ export const testCommand = {
         if (anyFailed) {
             process.exit(1);
         }
+        // Explicit success exit: under GJS the spawn-armed main loop would
+        // otherwise park this process after the summary. (runGjsBundle
+        // deliberately does NOT exit mid-flow — an unconditional exit there
+        // truncated this multi-runtime loop after the first gjs bundle.)
+        process.exit(0);
     },
 };
 /** Build a single test bundle in-process via `BuildAction`. */

package/lib/commands/tsc.js

@@ -19,6 +19,7 @@
 // Reference: packages/infra/cli/src/commands/run.ts (env-setup precedent).
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { detectNativePackages, buildNativeEnv } from '../utils/detect-native-packages.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
@@ -63,16 +64,46 @@ export const tscCommand = {
         // (e.g. `packages/web/fetch`) still finds the hoisted `@gjsify/tsc`
         // at the root's `node_modules`. Falls back to cwd for standalone
         // (non-monorepo) projects that have the package locally.
+        // Resolve `@gjsify/tsc/bundle` from two anchors, in order:
+        //   1. the consumer's workspace root / cwd (the normal install — a
+        //      project that has `@gjsify/tsc` as a dev dependency), then
+        //   2. the running CLI bundle's own location (`import.meta.url`).
+        // Anchor 2 is what makes a *bundled* gjsify (the Flatpak SDK
+        // extension's `node_modules/@gjsify/tsc`, or any install where the CLI
+        // ships its own toolchain) resolve `@gjsify/tsc` even when the consumer
+        // project has none — mirroring how `bundler-pick.ts` dual-anchors the
+        // native bridges at cwd AND the bundle.
         const anchorDir = findWorkspaceRoot(cwd) ?? cwd;
-        const anchor = pathToFileURL(`${anchorDir}/__gjsify_tsc__.js`).href;
-        const require = createRequire(anchor);
+        const anchors = [pathToFileURL(`${anchorDir}/__gjsify_tsc__.js`).href, import.meta.url];
         let bundlePath;
-        try {
-            bundlePath = require.resolve('@gjsify/tsc/bundle');
+        for (const anchor of anchors) {
+            try {
+                bundlePath = createRequire(anchor).resolve('@gjsify/tsc/bundle');
+                break;
+            }
+            catch {
+                // try the next anchor
+            }
         }
-        catch {
-            console.error('gjsify tsc: @gjsify/tsc is not installed.');
-            console.error('  Install with: gjsify install --save-dev @gjsify/tsc');
+        // Node fallback: upstream npm `typescript`'s CLI (`lib/tsc.js`),
+        // resolved from the same anchors. gjsify tsc is GJS-first — the
+        // @gjsify/tsc bundle is the Node-free path — but it stays runnable
+        // under Node: on a machine with no `gjs`, it transparently spawns
+        // upstream `typescript`. Mirrors how `bundler-pick.ts` falls back to
+        // npm `rolldown` off GJS, so "both with both" holds for the type-gate.
+        let nodeTscPath;
+        for (const anchor of anchors) {
+            try {
+                nodeTscPath = join(dirname(createRequire(anchor).resolve('typescript/package.json')), 'lib', 'tsc.js');
+                break;
+            }
+            catch {
+                // try the next anchor
+            }
+        }
+        if (!bundlePath && !nodeTscPath) {
+            console.error('gjsify tsc: neither @gjsify/tsc (GJS bundle) nor npm `typescript` (Node) is installed.');
+            console.error('  Install with: gjsify install --save-dev @gjsify/tsc   (or add `typescript`).');
             process.exit(1);
         }
         // Mirror `gjsify run`'s native-env composition so any future
@@ -85,25 +116,48 @@ export const tscCommand = {
             ...process.env,
             ...nativeEnv,
         };
-        const gjsArgs = ['-m', bundlePath, ...tscArgs];
-        const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
-        await new Promise((resolvePromise) => {
-            child.on('close', (code) => {
-                process.exit(code ?? 1);
-            });
+        // Run upstream `typescript` under this Node — the Node-only fallback.
+        const runNodeTsc = () => {
+            const child = spawn(process.execPath, [nodeTscPath, ...tscArgs], { env, stdio: 'inherit' });
+            child.on('close', (code) => process.exit(code ?? 1));
             child.on('error', (err) => {
-                if (err.code === 'ENOENT') {
-                    console.error('gjsify tsc: `gjs` not found on PATH. Install GJS (e.g. `dnf install gjs`).');
-                }
-                else {
-                    console.error(`gjsify tsc: ${err.message}`);
-                }
+                console.error(`gjsify tsc (node typescript): ${err.message}`);
                 process.exit(1);
             });
-            // Never resolves naturally — process.exit() above terminates
-            // the program once the child closes. The promise just keeps
-            // the handler alive while gjs runs.
-            void resolvePromise;
-        });
+        };
+        // Prefer GJS — the Node-free @gjsify/tsc bundle — when it resolves. If
+        // `gjs` is not on PATH (ENOENT), transparently fall back to upstream
+        // `typescript` under Node when available.
+        if (bundlePath) {
+            const child = spawn('gjs', ['-m', bundlePath, ...tscArgs], { env, stdio: 'inherit' });
+            await new Promise((resolvePromise) => {
+                child.on('close', (code) => {
+                    process.exit(code ?? 1);
+                });
+                child.on('error', (err) => {
+                    if (err.code === 'ENOENT' && nodeTscPath) {
+                        // No gjs on PATH — run upstream typescript under Node.
+                        runNodeTsc();
+                    }
+                    else if (err.code === 'ENOENT') {
+                        console.error('gjsify tsc: `gjs` not found on PATH and no npm `typescript` fallback.');
+                        console.error('  Install GJS (e.g. `dnf install gjs`), or add `typescript` to the project.');
+                        process.exit(1);
+                    }
+                    else {
+                        console.error(`gjsify tsc: ${err.message}`);
+                        process.exit(1);
+                    }
+                });
+                // Never resolves naturally — process.exit() above terminates the
+                // program once the child closes. The promise just keeps the
+                // handler alive while the child runs.
+                void resolvePromise;
+            });
+        }
+        else {
+            // No GJS bundle resolvable — go straight to the Node fallback.
+            runNodeTsc();
+        }
     },
 };

package/lib/index.js

@@ -1,98 +1,9 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import yargs from 'yargs';
+// gjsify CLI entry point. The whole command surface lives in `cli-app.ts`
+// (`runCli`), factored out so that `gjsify run` can dispatch a `gjsify
+// <subcommand>` script IN-PROCESS instead of spawning a fresh gjs — the
+// nested-gjs explosion that makes the GJS-first build orchestration thrash CI.
+// This file is just the executable wrapper around `runCli`.
 import { hideBin } from 'yargs/helpers';
-import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, } from './commands/index.js';
-import { APP_NAME } from './constants.js';
-// Detect which runtime is executing the CLI (GJS or Node.js).
-// GJS MUST be checked first because @gjsify/process sets
-// `process.versions.node = '20.0.0'` for compatibility — a plain
-// `process.versions.node` check would be a false Node positive under GJS.
-function runtimeLabel() {
-    try {
-        const sys = globalThis.imports?.system;
-        if (sys?.version !== undefined) {
-            const v = Number(sys.version);
-            return `GJS ${Math.floor(v / 10000)}.${Math.floor((v % 10000) / 100)}.${v % 100} (SpiderMonkey)`;
-        }
-    }
-    catch {
-        /* not GJS */
-    }
-    if (typeof process !== 'undefined' && typeof process.versions?.node === 'string') {
-        return `Node.js ${process.version}`;
-    }
-    return 'unknown runtime';
-}
-// Read the version from package.json adjacent to the bundle. yargs's
-// auto-version-discovery (its `pkg-up`-driven default) doesn't reach
-// through the bundled `dist/cli.gjs.mjs` path on GJS — falls back to
-// "unknown". Both layouts are covered:
-//   - dev (tsx, `yarn workspace`):  src/index.ts → ../package.json
-//   - bundled (install -g):         dist/cli.gjs.mjs → ../package.json
-function readBundleVersion() {
-    try {
-        const here = dirname(fileURLToPath(import.meta.url));
-        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
-        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
-    }
-    catch {
-        return 'unknown';
-    }
-}
-// `parseAsync()` instead of `.argv` so the top-level await keeps the
-// process alive until command handlers complete. Under Node this is
-// cosmetic — the event loop holds the process up — but under GJS the
-// script ends as soon as the top-level synchronous flow finishes, and
-// fire-and-forget handlers silently exit before any async work runs.
-const cli = yargs(hideBin(process.argv));
-await cli
-    .scriptName(APP_NAME)
-    .version(readBundleVersion())
-    .strict()
-    // Use the full terminal width for help. yargs's default caps at 80
-    // (`Math.min(80, process.stdout.columns)`); we explicitly opt into
-    // the real terminal width so long option/description lines wrap at
-    // the actual terminal edge instead of an arbitrary 80-col limit.
-    // `terminalWidth()` reads `process.stdout.columns`, which under GJS
-    // is backed by @gjsify/terminal-native (ioctl TIOCGWINSZ) when the
-    // typelib is on GI_TYPELIB_PATH — see the global launcher in
-    // packages/infra/cli/src/utils/install-global.ts.
-    .wrap(cli.terminalWidth())
-    .command(create.command, create.description, create.builder, create.handler)
-    .command(install.command, install.description, install.builder, install.handler)
-    .command(build.command, build.description, build.builder, build.handler)
-    .command(test.command, test.description, test.builder, test.handler)
-    .command(run.command, run.description, run.builder, run.handler)
-    .command(dlx.command, dlx.description, dlx.builder, dlx.handler)
-    .command(info.command, info.description, info.builder, info.handler)
-    .command(systemCheck.command, systemCheck.description, systemCheck.builder, systemCheck.handler)
-    .command(check.command, check.description, check.builder, check.handler)
-    .command(showcase.command, showcase.description, showcase.builder, showcase.handler)
-    .command(gresource.command, gresource.description, gresource.builder, gresource.handler)
-    .command(gettext.command, gettext.description, gettext.builder, gettext.handler)
-    .command(gsettings.command, gsettings.description, gsettings.builder, gsettings.handler)
-    .command(flatpak.command, flatpak.description, flatpak.builder, flatpak.handler)
-    .command(foreach.command, foreach.description, foreach.builder, foreach.handler)
-    .command(workspace.command, workspace.description, workspace.builder, workspace.handler)
-    .command(pack.command, pack.description, pack.builder, pack.handler)
-    .command(publish.command, publish.description, publish.builder, publish.handler)
-    .command(whoami.command, whoami.description, whoami.builder, whoami.handler)
-    .command(login.command, login.description, login.builder, login.handler)
-    .command(logout.command, logout.description, logout.builder, logout.handler)
-    .command(selfUpdate.command, selfUpdate.description, selfUpdate.builder, selfUpdate.handler)
-    .command(generateInstaller.command, generateInstaller.description, generateInstaller.builder, generateInstaller.handler)
-    .command(uninstall.command, uninstall.description, uninstall.builder, uninstall.handler)
-    .command(upgrade.command, upgrade.description, upgrade.builder, upgrade.handler)
-    .command(format.command, format.description, format.builder, format.handler)
-    .command(lint.command, lint.description, lint.builder, lint.handler)
-    .command(fix.command, fix.description, fix.builder, fix.handler)
-    .command(barrels.command, barrels.description, barrels.builder, barrels.handler)
-    .command(tsc.command, tsc.description, tsc.builder, tsc.handler)
-    .command(affected.command, affected.description, affected.builder, affected.handler)
-    .demandCommand(1)
-    .epilogue(`Running on ${runtimeLabel()}`)
-    .help()
-    .parseAsync();
+import { runCli } from './cli-app.js';
+await runCli(hideBin(process.argv));

package/lib/utils/npm-oidc.d.ts

@@ -20,8 +20,30 @@ export declare class OidcExchangeError extends Error {
     readonly status: number;
     readonly body: string;
     readonly packageName: string;
-    constructor(message: string, status: number, body: string, packageName: string);
+    /**
+     * The non-secret claims decoded from the GitHub OIDC JWT that npm
+     * rejected — `repository`, `workflow_ref`, `environment`, … These are
+     * exactly what npm matches a Trusted Publisher config against, so on a
+     * 401/403 they tell you precisely which fields the config must carry.
+     */
+    readonly claims?: Record<string, unknown> | undefined;
+    constructor(message: string, status: number, body: string, packageName: string, 
+    /**
+     * The non-secret claims decoded from the GitHub OIDC JWT that npm
+     * rejected — `repository`, `workflow_ref`, `environment`, … These are
+     * exactly what npm matches a Trusted Publisher config against, so on a
+     * 401/403 they tell you precisely which fields the config must carry.
+     */
+    claims?: Record<string, unknown> | undefined);
 }
+/**
+ * Decode the (non-secret) payload of a JWT — the middle base64url segment.
+ * A GitHub OIDC id-token's payload is public metadata about the workflow run
+ * (`repository`, `repository_owner`, `workflow_ref`, `job_workflow_ref`,
+ * `ref`, `environment`, `sub`, …); the SIGNATURE is what makes it trustworthy.
+ * Returns null if the token isn't a well-formed three-part JWT.
+ */
+export declare function decodeJwtPayload(jwt: string): Record<string, unknown> | null;
 /**
  * Probe whether OIDC publishing is available in the current process —
  * cheap env-var check, no network access. Used by `gjsify publish` to

package/lib/utils/npm-oidc.js

@@ -31,14 +31,43 @@ export class OidcExchangeError extends Error {
     status;
     body;
     packageName;
-    constructor(message, status, body, packageName) {
+    claims;
+    constructor(message, status, body, packageName, 
+    /**
+     * The non-secret claims decoded from the GitHub OIDC JWT that npm
+     * rejected — `repository`, `workflow_ref`, `environment`, … These are
+     * exactly what npm matches a Trusted Publisher config against, so on a
+     * 401/403 they tell you precisely which fields the config must carry.
+     */
+    claims) {
         super(message);
         this.status = status;
         this.body = body;
         this.packageName = packageName;
+        this.claims = claims;
         this.name = 'OidcExchangeError';
     }
 }
+/**
+ * Decode the (non-secret) payload of a JWT — the middle base64url segment.
+ * A GitHub OIDC id-token's payload is public metadata about the workflow run
+ * (`repository`, `repository_owner`, `workflow_ref`, `job_workflow_ref`,
+ * `ref`, `environment`, `sub`, …); the SIGNATURE is what makes it trustworthy.
+ * Returns null if the token isn't a well-formed three-part JWT.
+ */
+export function decodeJwtPayload(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+        const json = typeof atob === 'function' ? atob(b64) : Buffer.from(b64, 'base64').toString('binary');
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Probe whether OIDC publishing is available in the current process —
  * cheap env-var check, no network access. Used by `gjsify publish` to
@@ -59,10 +88,19 @@ export async function fetchGithubOidcToken(audience, log) {
         throw new OidcUnavailableError('GitHub Actions OIDC env vars (ACTIONS_ID_TOKEN_REQUEST_{URL,TOKEN}) not set. ' +
             'The calling workflow needs `permissions: id-token: write`.', 'no-env');
     }
-    const requestUrl = new URL(url);
-    requestUrl.searchParams.set('audience', audience);
-    log?.(`gjsify oidc: GET ${requestUrl.href.replace(bearer, '<bearer>')}`);
-    const res = await fetch(requestUrl.href, {
+    // Append the audience by STRING CONCATENATION, mirroring @actions/core's
+    // getIDToken (`${runtimeUrl}&audience=${encodeURIComponent(aud)}`) and the
+    // raw-curl probe that returns HTTP 201. Do NOT use `URL.searchParams.set` +
+    // `.href`: under GJS that serialization dropped the `audience` query param,
+    // so GitHub issued an id-token with the DEFAULT audience (the repo API URL)
+    // instead of `npm:registry.npmjs.org`. npm then rejected the otherwise-valid
+    // token with 401 "unauthorized" — the JWT's repository/workflow_ref/sub
+    // claims all matched the Trusted Publisher, only `aud` was wrong, which is
+    // exactly the failure we saw (curl from the same workflow → 201).
+    const sep = url.includes('?') ? '&' : '?';
+    const requestUrl = `${url}${sep}audience=${encodeURIComponent(audience)}`;
+    log?.(`gjsify oidc: GET ${requestUrl.replace(bearer, '<bearer>')}`);
+    const res = await fetch(requestUrl, {
         method: 'GET',
         headers: {
             Accept: 'application/json',
@@ -114,7 +152,7 @@ export async function exchangeOidcForNpmToken(args) {
     });
     const text = await res.text().catch(() => '');
     if (!res.ok) {
-        throw new OidcExchangeError(`npm OIDC token exchange failed for ${packageName}: ${res.status} ${res.statusText} — ${text.slice(0, 300)}`, res.status, text, packageName);
+        throw new OidcExchangeError(`npm OIDC token exchange failed for ${packageName}: ${res.status} ${res.statusText} — ${text.slice(0, 300)}`, res.status, text, packageName, decodeJwtPayload(idToken) ?? undefined);
     }
     let json;
     try {

package/lib/utils/oxc-resolve.d.ts

@@ -26,12 +26,27 @@ export interface RunOxcOptions {
     verbose?: boolean;
 }
 /**
- * Spawn an oxc tool (oxlint / oxfmt) via its Node ESM launcher. Inherits
- * stdio so the tool's own output (diagnostics, reformatted files, summary
- * lines) reaches the user.
+ * Engine pick for oxfmt — mirrors `bundler-pick.ts`'s `shouldUseNative()`:
+ *   - `GJSIFY_OXFMT=npm` forces the Node launcher.
+ *   - `GJSIFY_OXFMT=native` forces the GI bridge and throws when it is not
+ *     loadable (instead of silently switching engines).
+ *   - Default: native under GJS when loadable (the Node launcher cannot run
+ *     without a Node host), npm launcher on Node.
+ */
+export declare function shouldUseNativeOxfmt(): Promise<boolean>;
+/**
+ * Run an oxc tool (oxlint / oxfmt).
+ *
+ * oxfmt: dual-engine — under GJS the `@gjsify/oxfmt-native` GI bridge runs
+ * the full oxfmt CLI in-process (Node-free); otherwise the npm Node ESM
+ * launcher is spawned. `GJSIFY_OXFMT=native|npm` overrides the pick.
+ *
+ * oxlint: always spawned via its Node ESM launcher with the current Node
+ * executable (`process.execPath`) so the JS plugin host is available —
+ * required for the `jsPlugins`-wired `gjsify/register-class-order` rule.
  *
- * The launcher is run with the current Node executable (`process.execPath`)
- * so the JS plugin host is available — required for oxlint's `jsPlugins`.
+ * Inherits stdio so the tool's own output (diagnostics, reformatted files,
+ * summary lines) reaches the user.
  *
  * Returns the exit code; never throws on non-zero exit (callers check it).
  */
@@ -52,6 +67,22 @@ export declare function loadOxlintTemplate(): string;
 export declare function loadOxfmtTemplate(): string;
 /** Helper for callers to surface the install hint to the user cleanly. */
 export declare function printOxcNotFound(err: OxcNotFoundError): void;
+/**
+ * Propagate an oxc tool's exit code from a command handler.
+ *
+ * On Node, setting `process.exitCode` is the gentle idiom (streams flush,
+ * the process ends naturally). Under GJS there is no atexit hook, so
+ * `process.exitCode` alone is NOT honored at natural shutdown — the gjs
+ * process would exit 0 after a failed `--check`. Call `imports.system.exit`
+ * directly for non-zero codes there: SpiderMonkey raises its uncatchable
+ * exit exception from any context — including the yargs `parseAsync`
+ * microtask continuation this runs in — and stdout writes are synchronous
+ * under GJS, so the tool's report is already flushed. (`process.exit`'s
+ * idle-scheduled path is NOT used here: the scheduled idle never fires from
+ * this continuation — the module's top-level await is still pending and gjs
+ * exits 0 before the hook-registered loop runs.)
+ */
+export declare function setOxcExitCode(code: number): void;
 /**
  * Has the given oxc tool's npm package (or its companion) been declared in the
  * project's dependencies? Useful as a cheap pre-flight check — `gjsify flatpak