@gjsify/cli 0.4.44 → 0.5.0

package/lib/utils/oxc-resolve.js

@@ -28,10 +28,31 @@
 // We still reuse Biome's platform/arch/musl detection — it's used to name the
 // expected NAPI binding package in the not-found install hint, so the user
 // knows exactly which optionalDependency npm failed to place.
+//
+// NATIVE ENGINE (GJS) — `@gjsify/oxfmt-native`
+// ────────────────────────────────────────────
+// Under GJS the Node launcher path is a dead end: there is no Node host to
+// spawn. For oxfmt the dual-engine pick mirrors `bundler-pick.ts`'s
+// native/npm pattern exactly: `shouldUseNativeOxfmt()` prefers the
+// `@gjsify/oxfmt-native` GI bridge (Vala/Rust prebuild wrapping the full
+// pure-Rust oxfmt CLI — config resolution, ignore handling, file walking,
+// --write/--check/--list-different) when running under GJS and the prebuild
+// is loadable, and falls back to spawning the Node launcher otherwise.
+// `GJSIFY_OXFMT=native|npm` is the explicit override (native throws when the
+// prebuild isn't loadable instead of silently switching engines).
+//
+// oxlint has NO native path yet: its JS-plugin host (the internal
+// `gjsify/register-class-order` rule wired via `.oxlintrc.json` jsPlugins)
+// lives in the Node launcher, so a native oxlint bridge could only run the
+// Rust rule subset. Lint stays Node-spawned until that trade-off is decided
+// (tracked in STATUS.md Open TODOs).
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 import { findWorkspaceRoot } from './workspace-root.js';
+import { resolveNpmPackage } from './resolve-npm-package.js';
 /**
  * Map Node.js `process.platform` + `arch` (+ musl on Linux) to the
  * napi-rs binding-package suffix oxc uses, e.g. `linux-x64-gnu`,
@@ -178,17 +199,99 @@ function findConfigFile(cwd, names) {
     }
     return null;
 }
+let _nativeOxfmtProbe = null;
+/**
+ * Try to load `@gjsify/oxfmt-native` (GJS only). Same multi-anchor
+ * resolution as `bundler-pick.ts`'s `tryLoadNative()` — GJS's native ESM
+ * loader has no node_modules walker, so bare specifiers must be resolved
+ * to a `file://` URL via createRequire/resolveNpmPackage first.
+ */
+async function tryLoadNativeOxfmt() {
+    if (_nativeOxfmtProbe)
+        return _nativeOxfmtProbe;
+    _nativeOxfmtProbe = (async () => {
+        const isGjs = typeof globalThis.imports?.gi !== 'undefined';
+        if (!isGjs)
+            return null;
+        try {
+            const specifier = '@gjsify/oxfmt-native';
+            const resolved = resolveNpmPackage(specifier, { bundleUrl: import.meta.url }) ??
+                createRequire(import.meta.url).resolve(specifier);
+            const target = pathToFileURL(resolved).href;
+            const mod = (await import(/* @vite-ignore */ target));
+            if (!mod.hasNativeOxfmt())
+                return null;
+            return mod;
+        }
+        catch {
+            return null;
+        }
+    })();
+    return _nativeOxfmtProbe;
+}
+/**
+ * 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 async function shouldUseNativeOxfmt() {
+    const env = globalThis.process?.env ?? {};
+    const choice = env.GJSIFY_OXFMT;
+    if (choice === 'npm')
+        return false;
+    if (choice === 'native') {
+        const native = await tryLoadNativeOxfmt();
+        if (!native) {
+            throw new Error('GJSIFY_OXFMT=native but @gjsify/oxfmt-native is not loadable (no prebuild for this architecture, or not running under GJS).');
+        }
+        return true;
+    }
+    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
+    if (!isGjs)
+        return false;
+    return (await tryLoadNativeOxfmt()) !== null;
+}
 /**
- * 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.
+ * 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).
  */
-export function runOxc(tool, args, opts = {}) {
+export async function runOxc(tool, args, opts = {}) {
+    if (tool === 'oxfmt' && (await shouldUseNativeOxfmt())) {
+        const native = await tryLoadNativeOxfmt();
+        if (!native) {
+            // Unreachable: shouldUseNativeOxfmt() returned true above.
+            throw new Error('@gjsify/oxfmt-native not loadable');
+        }
+        if (opts.verbose) {
+            console.log(`[gjsify oxc] @gjsify/oxfmt-native (in-process) ${args.join(' ')}`);
+        }
+        // The native runner walks from the process working directory; the
+        // command handlers always pass cwd = process.cwd(), so no chdir is
+        // needed here.
+        return native.runOxfmt(args);
+    }
+    return spawnOxcLauncher(tool, args, opts);
+}
+/**
+ * Spawn an oxc tool via its Node ESM launcher (`node_modules/<tool>/bin/…`)
+ * with the current Node executable.
+ */
+function spawnOxcLauncher(tool, args, opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const launcher = findOxcLauncher(tool, cwd);
     const node = process.execPath || 'node';
@@ -242,6 +345,29 @@ export function loadOxfmtTemplate() {
 export function printOxcNotFound(err) {
     console.error(err.message);
 }
+/**
+ * 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 function setOxcExitCode(code) {
+    process.exitCode = code;
+    if (code === 0)
+        return;
+    const gjs = globalThis.imports;
+    if (gjs?.system?.exit)
+        gjs.system.exit(code);
+}
 /**
  * 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

package/lib/utils/prefixed-output.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Prefix every line of `src` with `prefix` and route it to `sink`. When
+ * `buffered` is false (tty), lines are written live. When true (non-tty /
+ * CI pipe), they are accumulated and emitted only by the returned `flush()`
+ * — call it once the child has closed.
+ */
+export declare function prefixLines(src: NodeJS.ReadableStream, sink: NodeJS.WritableStream, prefix: string, buffered: boolean): () => void;

package/lib/utils/prefixed-output.js

@@ -0,0 +1,52 @@
+// Shared line-prefixed child-output forwarding for the parallel runners
+// (`gjsify foreach`, `gjsify check`).
+//
+// Under GJS, `process.stdout.write` is a BLOCKING `Gio.write_all`. Writing
+// each prefixed line LIVE during a PARALLEL run into a backpressuring pipe
+// (a CI log collector that drains slowly) stalls the single GLib main loop
+// on a full pipe → every parallel child's pipe backs up → their reads stall
+// → the whole run HANGS. (A tty or file sink never backpressures, which is
+// why this only ever bites in CI.) On a NON-tty sink we therefore BUFFER
+// each child's prefixed output and flush it as ONE write when that child
+// closes: the child is already done by then, so its own read can't stall,
+// and concurrent flushes serialize into brief loop stalls instead of a
+// deadlock. On a tty (interactive) lines are written live for responsive
+// output.
+//
+// This helper is the single home for that logic — `foreach` shipped the fix
+// first; `check` had an unbuffered copy that kept the hang class alive.
+/**
+ * Prefix every line of `src` with `prefix` and route it to `sink`. When
+ * `buffered` is false (tty), lines are written live. When true (non-tty /
+ * CI pipe), they are accumulated and emitted only by the returned `flush()`
+ * — call it once the child has closed.
+ */
+export function prefixLines(src, sink, prefix, buffered) {
+    let buf = '';
+    let acc = '';
+    const emit = (line) => {
+        if (buffered)
+            acc += line;
+        else
+            sink.write(line);
+    };
+    src.setEncoding('utf-8');
+    src.on('data', (chunk) => {
+        buf += chunk;
+        let idx;
+        while ((idx = buf.indexOf('\n')) !== -1) {
+            emit(prefix + buf.slice(0, idx + 1));
+            buf = buf.slice(idx + 1);
+        }
+    });
+    src.on('end', () => {
+        if (buf.length > 0)
+            emit(prefix + buf + '\n');
+    });
+    return () => {
+        if (acc.length > 0) {
+            sink.write(acc);
+            acc = '';
+        }
+    };
+}

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

@@ -16,4 +16,18 @@ export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: stri
  * for any installed native gjsify packages discoverable from either the CWD
  * or the bundle's own node_modules tree.
  */
-export declare function runGjsBundle(bundlePath: string, extraArgs?: string[]): Promise<void>;
+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.
+     */
+    exitOnSuccess?: boolean;
+}
+export declare function runGjsBundle(bundlePath: string, extraArgs?: string[], options?: RunGjsBundleOptions): Promise<void>;

package/lib/utils/run-gjs.js

@@ -38,12 +38,7 @@ export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd()) {
         .join(' ');
     return { env, envPrefix };
 }
-/**
- * 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.
- */
-export async function runGjsBundle(bundlePath, extraArgs = []) {
+export async function runGjsBundle(bundlePath, extraArgs = [], options = {}) {
     const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath);
     const env = {
         ...process.env,
@@ -53,8 +48,10 @@ export async function runGjsBundle(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.
     const gjsCommand = ['gjs', ...gjsArgs.map((a) => (a.includes(' ') ? `"${a}"` : a))].join(' ');
-    console.log(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
+    console.error(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
     const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
     await new Promise((resolvePromise, reject) => {
         child.on('close', (code) => {
@@ -70,4 +67,8 @@ export async function runGjsBundle(bundlePath, extraArgs = []) {
         console.error(err.message);
         process.exit(1);
     });
+    // See RunGjsBundleOptions.exitOnSuccess — terminal callers opt in,
+    // mid-flow callers (test.ts's runtime loop) keep the process alive.
+    if (options.exitOnSuccess)
+        process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.4.44",
+    "version": "0.5.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -120,34 +120,38 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.4.44",
-        "@gjsify/create-app": "^0.4.44",
-        "@gjsify/node-globals": "^0.4.44",
-        "@gjsify/node-polyfills": "^0.4.44",
-        "@gjsify/npm-registry": "^0.4.44",
-        "@gjsify/resolve-npm": "^0.4.44",
-        "@gjsify/rolldown-plugin-gjsify": "^0.4.44",
-        "@gjsify/rolldown-plugin-pnp": "^0.4.44",
-        "@gjsify/semver": "^0.4.44",
-        "@gjsify/tar": "^0.4.44",
-        "@gjsify/tsc": "^0.4.44",
-        "@gjsify/web-polyfills": "^0.4.44",
-        "@gjsify/workspace": "^0.4.44",
-        "cosmiconfig": "^9.0.1",
+        "@gjsify/buffer": "^0.5.0",
+        "@gjsify/create-app": "^0.5.0",
+        "@gjsify/node-globals": "^0.5.0",
+        "@gjsify/node-polyfills": "^0.5.0",
+        "@gjsify/npm-registry": "^0.5.0",
+        "@gjsify/resolve-npm": "^0.5.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.5.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.5.0",
+        "@gjsify/semver": "^0.5.0",
+        "@gjsify/tar": "^0.5.0",
+        "@gjsify/tsc": "^0.5.0",
+        "@gjsify/web-polyfills": "^0.5.0",
+        "@gjsify/workspace": "^0.5.0",
+        "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
         "pkg-types": "^2.3.1",
-        "rolldown": "^1.0.3",
+        "rolldown": "^1.1.0",
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.4.44",
+        "@gjsify/unit": "^0.5.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/rolldown-native": "^0.4.44"
+        "@gjsify/oxfmt-native": "^0.5.0",
+        "@gjsify/rolldown-native": "^0.5.0"
     },
     "peerDependenciesMeta": {
+        "@gjsify/oxfmt-native": {
+            "optional": true
+        },
         "@gjsify/rolldown-native": {
             "optional": true
         }