@gjsify/cli 0.8.0 → 0.10.0

package/lib/actions/build.d.ts

@@ -37,9 +37,40 @@ export declare class BuildAction {
      * there is no in-bundle plugin, so this hook is the sole injection point.
      */
     private applyShebang;
+    /**
+     * GJS plugin loader — bundle the resolved plugin module to a single
+     * self-contained ESM file, then import that. Works around GJS's native
+     * ESM loader not following `package.json#exports` subpath maps for bare
+     * specifiers: Rolldown resolves those subpaths at bundle time, so the
+     * emitted file has no unresolvable bare-specifier imports left. Injected
+     * as the `loadModule` strategy in `buildApp` only when running under GJS.
+     */
+    private loadPluginViaGjsBundle;
+    /**
+     * Bundle a single plugin entry for `--app gjs` to a cached temp file and
+     * return its path. Reuses the full `--app gjs` pipeline (exports-map-aware
+     * resolution, `node:`→`@gjsify` aliases, `--globals auto`, single-file
+     * output) via a nested `BuildAction`. The nested config carries no
+     * `bundler.plugins`, so it never recurses back into plugin resolution.
+     *
+     * Cached under `node_modules/.cache/gjsify/plugins/`, keyed by the resolved
+     * source path. Invalidated when the plugin entry OR the project lockfile is
+     * newer than the cached bundle — a dep bump rewrites the lockfile but not
+     * the plugin's own entry mtime. The one window neither mtime catches (a
+     * transitive dep edited in place) is covered by the `GJSIFY_NO_PLUGIN_CACHE=1`
+     * escape hatch. Failures are rethrown with context naming the plugin.
+     */
+    private bundlePluginForGjs;
+    /**
+     * Fresh when the cached bundle is newer than BOTH the plugin entry AND the
+     * project's lockfile (the dep-change signal). Missing bundle/source → not
+     * fresh (rebuild).
+     */
+    private isPluginBundleFresh;
     /** Application mode */
     buildApp(app?: App, opts?: {
         watch?: boolean;
+        preserveDefaultExport?: boolean;
     }): Promise<RolldownOutput[]>;
     /**
      * Drive `rolldown.watch(...)`: rebuild on source change, apply the

package/lib/actions/build.js

@@ -1,10 +1,12 @@
 import { runBundle, runWatch, bundleToChunks } from '../bundler-pick.js';
 import { gjsifyPlugin, textLoaderPlugin, resolveShebangLine, NODE_SHEBANG } from '@gjsify/rolldown-plugin-gjsify';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 import { resolveUserPlugins } from '../utils/resolve-plugin-by-name.js';
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals } from '@gjsify/rolldown-plugin-gjsify/globals';
 import { pnpPlugin } from '@gjsify/rolldown-plugin-pnp';
-import { dirname, extname } from 'node:path';
-import { chmod, readFile, writeFile } from 'node:fs/promises';
+import { dirname, extname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { normalizeBundlerOptions, mergeBundlerOptions } from '../utils/normalize-bundler-options.js';
 const DEFAULT_GJS_SHEBANG = '#!/usr/bin/env -S gjs -m';
 /**
@@ -34,6 +36,43 @@ function isUnsafeDefaultOutput(path) {
 async function buildPnpPlugin() {
     return pnpPlugin({ issuerUrl: import.meta.url });
 }
+/**
+ * Stable, filesystem-safe short hash of a string (djb2 → 8 hex chars).
+ * Used to key a plugin's cached GJS bundle by its resolved source path.
+ * Dependency-free on purpose — avoids pulling crypto into this hot path.
+ */
+function shortHash(value) {
+    let h = 5381;
+    for (let i = 0; i < value.length; i++) {
+        h = ((h << 5) + h + value.charCodeAt(i)) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+function isTruthyEnv(v) {
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/**
+ * Lockfiles whose change implies a plugin's *transitive* deps may have moved.
+ * A dep bump (`npm/yarn/pnpm/gjsify install`) rewrites one of these but leaves
+ * the plugin's own entry-file mtime untouched — so the plugin GJS-bundle cache
+ * must invalidate on these too, not only on the entry.
+ */
+const PLUGIN_CACHE_DEP_SIGNALS = ['gjsify-lock.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'];
+/** Newest mtime (ms) among known lockfiles in `cwd`, or 0 when none exist. */
+async function newestLockfileMtime(cwd) {
+    let newest = 0;
+    for (const name of PLUGIN_CACHE_DEP_SIGNALS) {
+        try {
+            const s = await stat(join(cwd, name));
+            if (s.mtimeMs > newest)
+                newest = s.mtimeMs;
+        }
+        catch {
+            // not present — ignore
+        }
+    }
+    return newest;
+}
 export class BuildAction {
     configData;
     constructor(configData = {}) {
@@ -179,6 +218,90 @@ export class BuildAction {
         if (verbose)
             console.debug(`[gjsify] --shebang: wrote ${line} + chmod 0o755 to ${outfile}`);
     }
+    /**
+     * GJS plugin loader — bundle the resolved plugin module to a single
+     * self-contained ESM file, then import that. Works around GJS's native
+     * ESM loader not following `package.json#exports` subpath maps for bare
+     * specifiers: Rolldown resolves those subpaths at bundle time, so the
+     * emitted file has no unresolvable bare-specifier imports left. Injected
+     * as the `loadModule` strategy in `buildApp` only when running under GJS.
+     */
+    async loadPluginViaGjsBundle(resolvedPath, pluginName, verbose) {
+        const outfile = await this.bundlePluginForGjs(resolvedPath, pluginName, verbose);
+        try {
+            return (await import(pathToFileURL(outfile).href));
+        }
+        catch (err) {
+            throw new Error(`gjsify config: failed to import the GJS bundle for plugin "${pluginName}" ` +
+                `(bundled to ${outfile}). (${err.message})`);
+        }
+    }
+    /**
+     * Bundle a single plugin entry for `--app gjs` to a cached temp file and
+     * return its path. Reuses the full `--app gjs` pipeline (exports-map-aware
+     * resolution, `node:`→`@gjsify` aliases, `--globals auto`, single-file
+     * output) via a nested `BuildAction`. The nested config carries no
+     * `bundler.plugins`, so it never recurses back into plugin resolution.
+     *
+     * Cached under `node_modules/.cache/gjsify/plugins/`, keyed by the resolved
+     * source path. Invalidated when the plugin entry OR the project lockfile is
+     * newer than the cached bundle — a dep bump rewrites the lockfile but not
+     * the plugin's own entry mtime. The one window neither mtime catches (a
+     * transitive dep edited in place) is covered by the `GJSIFY_NO_PLUGIN_CACHE=1`
+     * escape hatch. Failures are rethrown with context naming the plugin.
+     */
+    async bundlePluginForGjs(resolvedPath, pluginName, verbose) {
+        const cwd = process.cwd();
+        const cacheDir = join(cwd, 'node_modules', '.cache', 'gjsify', 'plugins');
+        const safeName = pluginName.replace(/[^a-zA-Z0-9._-]/g, '_');
+        const outfile = join(cacheDir, `${safeName}-${shortHash(resolvedPath)}.mjs`);
+        const cacheDisabled = isTruthyEnv(process.env.GJSIFY_NO_PLUGIN_CACHE);
+        if (!cacheDisabled && (await this.isPluginBundleFresh(outfile, resolvedPath, cwd))) {
+            if (verbose)
+                console.debug(`[gjsify] plugin "${pluginName}": reusing cached GJS bundle ${outfile}`);
+            return outfile;
+        }
+        if (verbose)
+            console.debug(`[gjsify] plugin "${pluginName}": bundling for GJS → ${outfile}`);
+        try {
+            await mkdir(cacheDir, { recursive: true });
+            // `--globals auto` stays on so the plugin's own runtime globals
+            // (the MDX/unified toolchain touches `document`, etc.) are injected
+            // — but that injection wraps the entry with `export * from <entry>`,
+            // which drops the `default` export the plugin factory lives on.
+            // `preserveDefaultExport` makes the wrapper re-export `default` too,
+            // so the bundled plugin imports correctly as a library.
+            // shebang is intentionally left unset — the artifact is imported,
+            // not executed, so it must NOT carry a `#!` line.
+            const pluginBuild = new BuildAction({
+                verbose,
+                bundler: { input: resolvedPath, output: { file: outfile } },
+            });
+            await pluginBuild.buildApp('gjs', { preserveDefaultExport: true });
+        }
+        catch (err) {
+            throw new Error(`gjsify config: failed to bundle plugin "${pluginName}" for GJS ` +
+                `(needed because GJS can't import packages that use exports-map subpaths directly; ` +
+                `cache dir ${cacheDir}). (${err.message})`);
+        }
+        return outfile;
+    }
+    /**
+     * Fresh when the cached bundle is newer than BOTH the plugin entry AND the
+     * project's lockfile (the dep-change signal). Missing bundle/source → not
+     * fresh (rebuild).
+     */
+    async isPluginBundleFresh(outfile, resolvedPath, cwd) {
+        try {
+            const outStat = await stat(outfile);
+            const srcStat = await stat(resolvedPath);
+            const depMtime = await newestLockfileMtime(cwd);
+            return outStat.mtimeMs >= Math.max(srcStat.mtimeMs, depMtime);
+        }
+        catch {
+            return false;
+        }
+    }
     /** Application mode */
     async buildApp(app = 'gjs', opts = {}) {
         const { verbose, typescript, exclude, library: pkg, aliases, excludeGlobals } = this.configData;
@@ -211,6 +334,7 @@ export class BuildAction {
             reflection: typescript?.reflection,
             consoleShim,
             ...(aliases ? { aliases } : {}),
+            ...(opts.preserveDefaultExport ? { preserveDefaultExport: true } : {}),
         };
         const { autoMode, extras } = this.parseGlobalsValue(globals);
         const pnp = await buildPnpPlugin();
@@ -230,7 +354,15 @@ export class BuildAction {
         // auto-globals pre-build to avoid claiming the same files via
         // Rolldown's default classifier.
         if (userBundler.plugins?.length) {
-            const resolved = await resolveUserPlugins(userBundler.plugins, process.cwd());
+            // Under GJS, plugin modules can't always be imported directly:
+            // GJS's native ESM loader doesn't follow `package.json#exports`
+            // subpath maps, so a plugin whose source imports an internal
+            // subpath (e.g. `@mdx-js/mdx/internal-…`) throws `Module not
+            // found` even when the file is on disk. The injected loader
+            // first bundles such a plugin to a single self-contained ESM
+            // (Rolldown resolves the exports map at bundle time) and imports
+            // that instead. On Node the default direct-import path is used.
+            const resolved = await resolveUserPlugins(userBundler.plugins, process.cwd(), isGjs() ? { loadModule: (p, name) => this.loadPluginViaGjsBundle(p, name, verbose) } : {});
             userPlugins.push(...resolved);
         }
         // --- Auto mode (with optional extras): iterative multi-pass build ---

package/lib/bundler-pick.js

@@ -32,6 +32,7 @@ import * as path from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { resolveNpmPackage } from './utils/resolve-npm-package.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
@@ -46,8 +47,7 @@ async function loadNpmRolldown() {
     // 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.
-    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-    if (isGjs) {
+    if (isGjs()) {
         throw new Error('gjsify build: no usable bundler engine under GJS — `@gjsify/rolldown-native` is not loadable ' +
             '(its JS facade lib/ is not built, or its prebuild typelib is missing from GI_TYPELIB_PATH), ' +
             'and the npm `rolldown` engine is a Rust napi crate that cannot run under GJS. ' +
@@ -83,8 +83,7 @@ async function loadNpmRolldown() {
  * rolldown` even though the package is present under the install dir.
  */
 function resolveImportTargetForGjs(specifier) {
-    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-    if (!isGjs)
+    if (!isGjs())
         return specifier;
     const resolved = resolveNpmPackage(specifier, { bundleUrl: import.meta.url });
     if (resolved)
@@ -193,8 +192,7 @@ export async function shouldUseNative() {
     //   GJS:     try @gjsify/rolldown-native — it's the only engine
     //            that can actually run here (npm rolldown is a Rust
     //            crate). Fall back to npm only on Node.
-    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-    if (!isGjs)
+    if (!isGjs())
         return false;
     const native = await tryLoadNative();
     return native !== null;
@@ -236,8 +234,7 @@ async function tryLoadNative() {
     if (_nativeProbe)
         return _nativeProbe;
     _nativeProbe = (async () => {
-        const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-        if (!isGjs)
+        if (!isGjs())
             return null;
         try {
             // Under GJS the ESM loader has no node_modules resolver — a bare
@@ -256,7 +253,7 @@ async function tryLoadNative() {
             // to npm rolldown (which then throws ImportError for `rolldown`).
             const specifier = '@gjsify/rolldown-native';
             let target = specifier;
-            if (isGjs) {
+            if (isGjs()) {
                 // Same multi-anchor resolution as `loadNpmRolldown` —
                 // when the bundle is invoked from a cwd outside the
                 // install dir, anchoring solely at `import.meta.url`

package/lib/cli-app.js

@@ -21,6 +21,8 @@ import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
 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, trustCommand as trust, 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, storybookCommand as storybook, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
+import { isNode } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { ensureGjsifyShimOnPath } from './utils/gjsify-shim.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
@@ -36,7 +38,7 @@ function runtimeLabel() {
     catch {
         /* not GJS */
     }
-    if (typeof process !== 'undefined' && typeof process.versions?.node === 'string') {
+    if (isNode()) {
         return `Node.js ${process.version}`;
     }
     return 'unknown runtime';
@@ -67,6 +69,11 @@ function readBundleVersion() {
  * exit before any async work runs.
  */
 export async function runCli(argv) {
+    // Under GJS, make a GJS-runnable `gjsify` available on PATH for child
+    // processes (workspace/foreach orchestration + compound `gjsify run`
+    // scripts) so node-free builds don't fall back to the Node bin. No-op on
+    // Node.
+    ensureGjsifyShimOnPath();
     const cli = yargs(argv);
     await cli
         .scriptName(APP_NAME)

package/lib/commands/foreach.js

@@ -14,6 +14,7 @@ import { cpus } from 'node:os';
 import { buildDependencyGraph, discoverWorkspaces, filterWorkspaces, topologicalSort, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { prefixLines } from '../utils/prefixed-output.js';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 // Every child spawned by spawnPrefixed registers here so fail-fast can
 // terminate the whole in-flight set instead of waiting on it. On CI a
 // single failed package used to leave foreach awaiting its still-running
@@ -520,6 +521,11 @@ async function runOne(ws, script, args, prefixOutput, verbose, exec) {
     await spawnPrefixed(runner, argv, ws.location, prefixOutput ? `[${ws.name}] ` : null);
 }
 function detectPackageManager() {
+    // Under GJS there is no Node — neither `npm` nor `yarn` can run scripts, so
+    // the runner is `gjsify` itself via the GJS shim on PATH
+    // (`ensureGjsifyShimOnPath`). Makes node-free `gjsify foreach` work.
+    if (isGjs())
+        return 'gjsify';
     // `npm_config_user_agent` is set by npm/yarn/pnpm — first token is
     // `<name>/<version>`. Reuse it so `gjsify foreach build` invoked
     // through `yarn run` keeps using yarn, etc.

package/lib/commands/run.js

@@ -19,6 +19,7 @@ import { spawn } from 'node:child_process';
 import { runGjsBundle } from '../utils/run-gjs.js';
 import { readPackageJson } from '../utils/pkg-json-edit.js';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 export const runCommand = {
     command: 'run <target> [args..]',
     description: 'Run a script from package.json (yarn-run-style) or a GJS bundle file. If <target> resolves to a file on disk (or has a path-like prefix), it is launched via gjs with LD_LIBRARY_PATH + GI_TYPELIB_PATH set for native packages. Otherwise it is looked up in the current package.json `scripts`.',
@@ -126,6 +127,15 @@ async function runScript(script, extraArgs) {
     if (monorepoRoot && monorepoRoot !== cwd) {
         binDirs.push(join(monorepoRoot, 'node_modules', '.bin'));
     }
+    // Under GJS, the GJS-runnable `gjsify` shim (see `ensureGjsifyShimOnPath`)
+    // MUST shadow the workspace `node_modules/.bin/gjsify`, which is the Node
+    // entry and unusable in a node-free sandbox. So put the shim dir ahead of
+    // the `.bin` dirs in the child's PATH — otherwise a compound script like
+    // `gjsify run a && gjsify run b` resolves `gjsify` to the Node bin and
+    // fails. `GJSIFY_SHIM_DIR` is only set under GJS, so this is a no-op on Node.
+    if (process.env.GJSIFY_SHIM_DIR) {
+        binDirs.unshift(process.env.GJSIFY_SHIM_DIR);
+    }
     // Default FORCE_COLOR=1 when not already set, matching yarn / npm
     // script-runner behaviour. Without this, tools that check
     // `process.stdout.isTTY` (chalk, picocolors, biome, …) disable colors
@@ -151,7 +161,7 @@ async function runScript(script, extraArgs) {
     // 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;
+    const inProcArgv = isGjs() ? 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
@@ -203,11 +213,6 @@ 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`

package/lib/commands/workspace.js

@@ -17,6 +17,7 @@
 import { spawn } from 'node:child_process';
 import { buildDependencyGraph, discoverWorkspaces, topologicalSort, } from '@gjsify/workspace';
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 export const workspaceCommand = {
     command: 'workspace <name> <script> [args..]',
     description: 'Run a workspace script (`yarn workspace <name> run <script>` equivalent).',
@@ -203,6 +204,12 @@ async function runOne(ws, script, extraArgs, runner, verbose) {
     });
 }
 function detectPackageManager() {
+    // Under GJS there is no Node, so neither `npm` nor `yarn` can run scripts —
+    // the only option is `gjsify` itself, resolved via the GJS shim on PATH
+    // (see `ensureGjsifyShimOnPath`). This is what makes node-free multi-package
+    // orchestration work in the Flatpak sandbox.
+    if (isGjs())
+        return 'gjsify';
     const ua = process.env.npm_config_user_agent ?? '';
     if (ua.startsWith('yarn/'))
         return 'yarn';

package/lib/utils/gjsify-shim.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Ensure a GJS-runnable `gjsify` is on `process.env.PATH` for child processes.
+ * Idempotent per process; children inherit the shim via `GJSIFY_SHIM_DIR` and
+ * reuse it instead of creating their own. No-op when not running under GJS.
+ */
+export declare function ensureGjsifyShimOnPath(): void;

package/lib/utils/gjsify-shim.js

@@ -0,0 +1,52 @@
+// Node-free orchestration: a GJS-runnable `gjsify` on PATH.
+//
+// The CLI's npm `bin` (`node_modules/.bin/gjsify`) is the NODE entry — useless
+// in a node-free environment (the Flatpak sandbox has no Node). But multi-
+// package orchestration and compound package scripts resolve `gjsify` from
+// PATH and would hit that Node bin:
+//   - `gjsify workspace`/`foreach` spawn `<pm> run <script>` per package; under
+//     GJS the package manager is `gjsify` itself, and `spawn('gjsify', …)`
+//     searches PATH.
+//   - a compound script like `gjsify run a && gjsify run b` is executed via
+//     `/bin/sh -c …`, and the shell resolves each `gjsify` from PATH.
+// Both fail without Node (`spawn npm ENOENT`, `gjsify: not found`).
+//
+// Fix: under GJS, write a tiny wrapper that re-invokes the running GJS bundle
+// under `gjs -m`, and prepend its directory to `process.env.PATH` so every
+// child process (and grandchild, via the inherited `GJSIFY_SHIM_DIR` marker)
+// resolves `gjsify` to a GJS-runnable executable. No-op on Node.
+import { mkdtempSync, writeFileSync, chmodSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, delimiter } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+let _ensured = false;
+/**
+ * Ensure a GJS-runnable `gjsify` is on `process.env.PATH` for child processes.
+ * Idempotent per process; children inherit the shim via `GJSIFY_SHIM_DIR` and
+ * reuse it instead of creating their own. No-op when not running under GJS.
+ */
+export function ensureGjsifyShimOnPath() {
+    if (_ensured || !isGjs())
+        return;
+    _ensured = true;
+    // A parent gjsify (also under GJS) already created the shim — reuse it so
+    // nested orchestration doesn't pile up temp dirs / PATH entries.
+    const inherited = process.env.GJSIFY_SHIM_DIR;
+    if (inherited && existsSync(join(inherited, 'gjsify'))) {
+        if (!(process.env.PATH ?? '').split(delimiter).includes(inherited)) {
+            process.env.PATH = inherited + delimiter + (process.env.PATH ?? '');
+        }
+        return;
+    }
+    // `import.meta.url` resolves to the running GJS bundle (cli.gjs.mjs) — the
+    // whole CLI collapses into that single file, so this module's URL is it.
+    const selfBundle = fileURLToPath(import.meta.url);
+    const gjs = process.env.GJS_CONSOLE || 'gjs';
+    const dir = mkdtempSync(join(tmpdir(), 'gjsify-shim-'));
+    const shim = join(dir, 'gjsify');
+    writeFileSync(shim, `#!/bin/sh\nexec "${gjs}" -m "${selfBundle}" "$@"\n`, { mode: 0o755 });
+    chmodSync(shim, 0o755);
+    process.env.GJSIFY_SHIM_DIR = dir;
+    process.env.PATH = dir + delimiter + (process.env.PATH ?? '');
+}

package/lib/utils/oxc-resolve.js

@@ -53,6 +53,7 @@ import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 import { findWorkspaceRoot } from './workspace-root.js';
 import { resolveNpmPackage } from './resolve-npm-package.js';
+import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
 /**
  * Map Node.js `process.platform` + `arch` (+ musl on Linux) to the
  * napi-rs binding-package suffix oxc uses, e.g. `linux-x64-gnu`,
@@ -210,8 +211,7 @@ async function tryLoadNativeOxfmt() {
     if (_nativeOxfmtProbe)
         return _nativeOxfmtProbe;
     _nativeOxfmtProbe = (async () => {
-        const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-        if (!isGjs)
+        if (!isGjs())
             return null;
         try {
             const specifier = '@gjsify/oxfmt-native';
@@ -249,8 +249,7 @@ export async function shouldUseNativeOxfmt() {
         }
         return true;
     }
-    const isGjs = typeof globalThis.imports?.gi !== 'undefined';
-    if (!isGjs)
+    if (!isGjs())
         return false;
     return (await tryLoadNativeOxfmt()) !== null;
 }

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

@@ -7,6 +7,26 @@ export interface PluginByName {
     /** Options forwarded to the plugin factory. */
     options?: unknown;
 }
+/**
+ * Strategy for turning a resolved plugin file path into its module namespace.
+ *
+ * On Node this is a plain dynamic `import()`. Under GJS it cannot be — GJS's
+ * native ESM loader does not follow npm `package.json#exports` subpath maps
+ * for bare specifiers, so importing a plugin whose source does
+ * `import … from '@scope/pkg/internal-subpath'` throws
+ * `Module not found: @scope/pkg/internal-subpath` even when the file is on
+ * disk. The CLI injects a GJS strategy that first bundles the plugin to a
+ * single self-contained ESM file (Rolldown resolves the exports map at
+ * bundle time), then imports that. See `BuildAction.loadPluginViaGjsBundle`.
+ */
+export type LoadPluginModule = (resolvedPath: string, pluginName: string) => Promise<Record<string, unknown>>;
+export interface ResolveUserPluginsOptions {
+    /**
+     * Override how a resolved plugin path is turned into its module
+     * namespace. Defaults to a direct dynamic `import()` (correct on Node).
+     */
+    loadModule?: LoadPluginModule;
+}
 /** Type-guard: a `PluginByName` shape rather than a Rolldown plugin object. */
 export declare function isPluginByName(value: unknown): value is PluginByName;
 /**
@@ -18,4 +38,4 @@ export declare function isPluginByName(value: unknown): value is PluginByName;
  * Throws when a name fails to resolve, when the chosen export is not a
  * function, or when the factory returns nothing.
  */
-export declare function resolveUserPlugins(plugins: ReadonlyArray<RolldownPluginOption | PluginByName>, projectDir: string): Promise<RolldownPluginOption[]>;
+export declare function resolveUserPlugins(plugins: ReadonlyArray<RolldownPluginOption | PluginByName>, projectDir: string, options?: ResolveUserPluginsOptions): Promise<RolldownPluginOption[]>;

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

@@ -15,6 +15,8 @@
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+/** Default loader: a plain dynamic import of the resolved file URL (Node path). */
+const defaultLoadModule = async (resolvedPath) => (await import(pathToFileURL(resolvedPath).href));
 /** Type-guard: a `PluginByName` shape rather than a Rolldown plugin object. */
 export function isPluginByName(value) {
     return (typeof value === 'object' &&
@@ -39,7 +41,8 @@ export function isPluginByName(value) {
  * Throws when a name fails to resolve, when the chosen export is not a
  * function, or when the factory returns nothing.
  */
-export async function resolveUserPlugins(plugins, projectDir) {
+export async function resolveUserPlugins(plugins, projectDir, options = {}) {
+    const loadModule = options.loadModule ?? defaultLoadModule;
     const requireFromProject = createRequire(join(projectDir, 'package.json'));
     const out = [];
     for (const entry of plugins) {
@@ -56,7 +59,7 @@ export async function resolveUserPlugins(plugins, projectDir) {
                 `Add it to your project's dependencies, or pass a Plugin object directly. ` +
                 `(${err.message})`);
         }
-        const mod = await import(pathToFileURL(resolvedPath).href);
+        const mod = await loadModule(resolvedPath, entry.name);
         const exportName = entry.export ?? 'default';
         const factory = mod[exportName];
         if (typeof factory !== 'function') {

package/package.json

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