@gjsify/cli 0.1.8 → 0.1.10

package/lib/utils/check-system-deps.js

@@ -1,10 +1,20 @@
 // System dependency checker for gjsify CLI.
 // Uses execFileSync with explicit argument arrays — no shell injection possible.
 // All binary names are hardcoded constants, never derived from user input.
+//
+// Severity model:
+//   - 'required'  → must be present, exit code 1 if missing
+//   - 'optional'  → nice to have, only warned about, exit code stays 0
+//
+// Conditional checking: when a project's package.json is reachable from cwd,
+// optional system deps are only checked if the corresponding @gjsify/* package
+// is in the project's dependency tree. A user with only @gjsify/fs in their
+// project never sees a warning about libmanette.
 import { execFileSync } from 'node:child_process';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 /** Run a binary and return its stdout trimmed, or null if it fails. */
 function tryExecFile(binary, args) {
     try {
@@ -15,41 +25,41 @@ function tryExecFile(binary, args) {
     }
 }
 /** Check if a binary exists and optionally capture its version output. */
-function checkBinary(id, name, binary, versionArgs, parseVersion) {
+function checkBinary(id, name, binary, versionArgs, severity, parseVersion, requiredBy) {
     const out = tryExecFile(binary, versionArgs);
     if (out === null)
-        return { id, name, found: false };
+        return { id, name, found: false, severity, requiredBy };
     const version = parseVersion ? parseVersion(out) : out.split('\n')[0] ?? out;
-    return { id, name, found: true, version };
+    return { id, name, found: true, version, severity, requiredBy };
 }
 /** Check a pkg-config library. pkg-config --modversion returns version on stdout. */
-function checkPkgConfig(id, name, libName) {
+function checkPkgConfig(id, name, libName, severity, requiredBy) {
     const version = tryExecFile('pkg-config', ['--modversion', libName]);
     if (version === null)
-        return { id, name, found: false };
-    return { id, name, found: true, version: version.split('\n')[0] };
+        return { id, name, found: false, severity, requiredBy };
+    return { id, name, found: true, version: version.split('\n')[0], severity, requiredBy };
 }
 /**
  * Check for an npm package. Tries the user's project first (cwd), then falls
  * back to the CLI's own node_modules. This way a locally installed version
  * takes precedence, but npx usage still works via the CLI's own dependencies.
  */
-function checkNpmPackage(id, name, packageName, cwd) {
+function checkNpmPackage(id, name, packageName, cwd, severity, requiredBy) {
     // 1. Try user's project
     try {
         const requireFromCwd = createRequire(pathToFileURL(join(cwd, '_check_.js')).href);
         requireFromCwd.resolve(packageName);
-        return { id, name, found: true };
+        return { id, name, found: true, severity, requiredBy };
     }
     catch { /* not in project, try CLI fallback */ }
     // 2. Fallback: CLI's own node_modules
     try {
         const requireFromCli = createRequire(import.meta.url);
         requireFromCli.resolve(packageName);
-        return { id, name, found: true };
+        return { id, name, found: true, severity, requiredBy };
     }
     catch {
-        return { id, name, found: false };
+        return { id, name, found: false, severity, requiredBy };
     }
 }
 export function detectPackageManager() {
@@ -61,56 +71,179 @@ export function detectPackageManager() {
     }
     return 'unknown';
 }
+/** Optional system deps keyed by their DepCheck id. */
+const OPTIONAL_DEPS = {
+    manette: { id: 'manette', name: 'libmanette', pkgName: 'manette-0.2' },
+    gstreamer: { id: 'gstreamer', name: 'GStreamer', pkgName: 'gstreamer-1.0' },
+    'gst-app': { id: 'gst-app', name: 'GStreamer App', pkgName: 'gstreamer-app-1.0' },
+    'gdk-pixbuf': { id: 'gdk-pixbuf', name: 'GdkPixbuf', pkgName: 'gdk-pixbuf-2.0' },
+    pango: { id: 'pango', name: 'Pango', pkgName: 'pango' },
+    pangocairo: { id: 'pangocairo', name: 'PangoCairo', pkgName: 'pangocairo' },
+    webkitgtk: { id: 'webkitgtk', name: 'WebKitGTK', pkgName: 'webkitgtk-6.0' },
+    cairo: { id: 'cairo', name: 'Cairo', pkgName: 'cairo' },
+};
+/**
+ * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
+ * Generated by walking each package's `gi://` imports (excluding the always-
+ * available trio GLib/GObject/Gio).
+ *
+ * Used to compute the set of optional deps to check for a given project.
+ */
+const PACKAGE_DEPS = {
+    '@gjsify/gamepad': ['manette'],
+    '@gjsify/webaudio': ['gstreamer', 'gst-app'],
+    '@gjsify/iframe': ['webkitgtk'],
+    '@gjsify/canvas2d': ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
+    '@gjsify/canvas2d-core': ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
+    '@gjsify/dom-elements': ['gdk-pixbuf'],
+    // @gjsify/webgl, @gjsify/event-bridge only need gtk4/gdk which are
+    // already in the required set, so they don't need optional entries.
+};
+/** Walk up from cwd looking for the nearest package.json. */
+function findProjectRoot(cwd) {
+    let dir = resolve(cwd);
+    while (true) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Discover which @gjsify/* packages a project depends on (transitively),
+ * by walking the node_modules tree from the project root. Returns a Set of
+ * package names like '@gjsify/webgl', '@gjsify/canvas2d'.
+ *
+ * If the project root cannot be determined or has no node_modules, returns
+ * `null` to signal "check all optional deps" — this matches the historical
+ * behaviour where `gjsify check` outside any project shows the full list.
+ */
+function discoverGjsifyPackages(cwd) {
+    const root = findProjectRoot(cwd);
+    if (!root)
+        return null;
+    const nodeModulesDir = join(root, 'node_modules', '@gjsify');
+    if (!existsSync(nodeModulesDir)) {
+        // Project exists but no @gjsify/* installed → only need core checks.
+        return new Set();
+    }
+    // Read top-level package.json to determine if @gjsify/cli is the only
+    // dep (in which case we still want to warn about everything the CLI
+    // transitively brings in). Otherwise scan node_modules for installed packages.
+    const pkgJsonPath = join(root, 'package.json');
+    let topPkg = {};
+    try {
+        topPkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+    }
+    catch { /* ignore */ }
+    const directDeps = {
+        ...topPkg.dependencies,
+        ...topPkg.devDependencies,
+    };
+    const found = new Set();
+    try {
+        for (const entry of readdirSync(nodeModulesDir, { withFileTypes: true })) {
+            if (entry.isDirectory() || entry.isSymbolicLink()) {
+                found.add(`@gjsify/${entry.name}`);
+            }
+        }
+    }
+    catch { /* ignore */ }
+    // Also include direct deps even if node_modules walk failed
+    for (const dep of Object.keys(directDeps)) {
+        if (dep.startsWith('@gjsify/'))
+            found.add(dep);
+    }
+    return found;
+}
+/**
+ * Compute the set of optional dep ids that should be checked for the
+ * current project. Returns null to indicate "check all" (no project context).
+ */
+function computeNeededOptionalDeps(cwd) {
+    const installedPackages = discoverGjsifyPackages(cwd);
+    if (installedPackages === null)
+        return null; // no project → check everything
+    const needed = new Set();
+    for (const pkg of installedPackages) {
+        const deps = PACKAGE_DEPS[pkg];
+        if (deps)
+            for (const id of deps)
+                needed.add(id);
+    }
+    return needed;
+}
 /**
  * Run all dependency checks. Used by `gjsify check` to show full system status.
+ *
+ * Required deps (gjs, gtk4, libsoup3, libadwaita, gobject-introspection,
+ * blueprint-compiler, pkg-config, meson) are always checked.
+ *
+ * Optional deps are checked conditionally based on which @gjsify/* packages
+ * the project (resolved from cwd) actually consumes. If no project context
+ * is available, all optional deps are checked.
  */
 export function runAllChecks(cwd) {
-    return [...runMinimalChecks(), ...runExtraChecks(cwd)];
+    const needed = computeNeededOptionalDeps(cwd);
+    return [...runMinimalChecks(), ...runRequiredChecks(cwd), ...runOptionalChecks(needed, cwd)];
 }
 /**
- * Minimal checks needed to run any GJS example (GJS binary only).
+ * Minimal checks needed to run any GJS example (Node + GJS binaries only).
  * Used by `gjsify showcase` for examples that have no native deps.
  */
 export function runMinimalChecks() {
     const results = [];
     // Node.js — always present
-    results.push({ id: 'nodejs', name: 'Node.js', found: true, version: process.version });
+    results.push({ id: 'nodejs', name: 'Node.js', found: true, version: process.version, severity: 'required' });
     // GJS
-    results.push(checkBinary('gjs', 'GJS', 'gjs', ['--version'], (out) => out.replace(/^GJS\s+/i, '').split('\n')[0] ?? out));
+    results.push(checkBinary('gjs', 'GJS', 'gjs', ['--version'], 'required', (out) => out.replace(/^GJS\s+/i, '').split('\n')[0] ?? out));
     return results;
 }
-/** Check gwebgl npm package (project first, CLI fallback). */
+/** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
 export function checkGwebgl(cwd) {
-    return checkNpmPackage('gwebgl', 'gwebgl (@gjsify/webgl)', '@gjsify/webgl', cwd);
+    return checkNpmPackage('gwebgl', 'gwebgl (@gjsify/webgl)', '@gjsify/webgl', cwd, 'optional', ['@gjsify/webgl']);
 }
 /**
- * Extra checks for development and full system audit.
+ * Required system dependencies — always checked, missing → exit 1.
+ * Includes the core build toolchain (pkg-config, meson, blueprint-compiler)
+ * and the foundational libraries (gtk4, libadwaita, libsoup3,
+ * gobject-introspection) that nearly every gjsify app needs.
  */
-function runExtraChecks(cwd) {
+function runRequiredChecks(_cwd) {
     const results = [];
-    // Blueprint Compiler
-    results.push(checkBinary('blueprint-compiler', 'Blueprint Compiler', 'blueprint-compiler', ['--version']));
-    // pkg-config (needed for library checks)
-    results.push(checkBinary('pkg-config', 'pkg-config', 'pkg-config', ['--version']));
-    // Meson (for building native extensions)
-    results.push(checkBinary('meson', 'Meson', 'meson', ['--version']));
-    // GTK4
-    results.push(checkPkgConfig('gtk4', 'GTK4', 'gtk4'));
-    // libadwaita
-    results.push(checkPkgConfig('libadwaita', 'libadwaita', 'libadwaita-1'));
-    // libsoup3
-    results.push(checkPkgConfig('libsoup3', 'libsoup3', 'libsoup-3.0'));
-    // WebKitGTK — try 4.1 first, fall back to 4.0
-    const webkitCheck = checkPkgConfig('webkitgtk', 'WebKitGTK', 'webkit2gtk-4.1');
-    if (webkitCheck.found) {
-        results.push(webkitCheck);
-    }
-    else {
-        results.push(checkPkgConfig('webkitgtk', 'WebKitGTK', 'webkitgtk-6.0'));
-    }
-    // GObject Introspection
-    results.push(checkPkgConfig('gobject-introspection', 'GObject Introspection', 'gobject-introspection-1.0'));
-    // gwebgl — project first, CLI fallback.
+    // Build toolchain
+    results.push(checkBinary('blueprint-compiler', 'Blueprint Compiler', 'blueprint-compiler', ['--version'], 'required'));
+    results.push(checkBinary('pkg-config', 'pkg-config', 'pkg-config', ['--version'], 'required'));
+    results.push(checkBinary('meson', 'Meson', 'meson', ['--version'], 'required'));
+    // Foundational libraries
+    results.push(checkPkgConfig('gtk4', 'GTK4', 'gtk4', 'required'));
+    results.push(checkPkgConfig('libadwaita', 'libadwaita', 'libadwaita-1', 'required'));
+    results.push(checkPkgConfig('libsoup3', 'libsoup3', 'libsoup-3.0', 'required'));
+    results.push(checkPkgConfig('gobject-introspection', 'GObject Introspection', 'gobject-introspection-1.0', 'required'));
+    return results;
+}
+/**
+ * Optional system dependencies — only checked if the corresponding @gjsify/*
+ * package is in use. Missing optional deps generate warnings, not errors.
+ *
+ * @param needed Set of optional dep ids to check, or null to check all.
+ * @param cwd Used to resolve the gwebgl npm package check.
+ */
+function runOptionalChecks(needed, cwd) {
+    const results = [];
+    for (const [id, dep] of Object.entries(OPTIONAL_DEPS)) {
+        if (needed !== null && !needed.has(id))
+            continue;
+        const requiredBy = Object.entries(PACKAGE_DEPS)
+            .filter(([, ids]) => ids.includes(id))
+            .map(([pkg]) => pkg);
+        results.push(checkPkgConfig(dep.id, dep.name, dep.pkgName, 'optional', requiredBy));
+    }
+    // gwebgl npm package — special case (not a pkg-config lib).
+    // Always reported (the npm package is bundled with the CLI), but marked
+    // optional because only @gjsify/webgl users need it.
     results.push(checkGwebgl(cwd));
     return results;
 }
@@ -125,8 +258,15 @@ const PM_PACKAGES = {
         gtk4: 'libgtk-4-dev',
         libadwaita: 'libadwaita-1-dev',
         libsoup3: 'libsoup-3.0-dev',
-        webkitgtk: 'libwebkit2gtk-4.1-dev',
+        webkitgtk: 'libwebkit2gtk-6.0-dev',
         'gobject-introspection': 'gobject-introspection libgirepository1.0-dev',
+        manette: 'libmanette-0.2-0 gir1.2-manette-0.2',
+        gstreamer: 'libgstreamer1.0-dev',
+        'gst-app': 'libgstreamer-plugins-base1.0-dev gir1.2-gst-plugins-base-1.0',
+        'gdk-pixbuf': 'libgdk-pixbuf-2.0-dev',
+        pango: 'libpango1.0-dev',
+        pangocairo: 'libpango1.0-dev',
+        cairo: 'libcairo2-dev',
     },
     dnf: {
         gjs: 'gjs',
@@ -138,6 +278,13 @@ const PM_PACKAGES = {
         libsoup3: 'libsoup3-devel',
         webkitgtk: 'webkitgtk6.0-devel',
         'gobject-introspection': 'gobject-introspection-devel',
+        manette: 'libmanette-devel',
+        gstreamer: 'gstreamer1-devel',
+        'gst-app': 'gstreamer1-plugins-base-devel',
+        'gdk-pixbuf': 'gdk-pixbuf2-devel',
+        pango: 'pango-devel',
+        pangocairo: 'pango-devel',
+        cairo: 'cairo-devel',
     },
     pacman: {
         gjs: 'gjs',
@@ -147,8 +294,15 @@ const PM_PACKAGES = {
         gtk4: 'gtk4',
         libadwaita: 'libadwaita',
         libsoup3: 'libsoup3',
-        webkitgtk: 'webkit2gtk-4.1',
+        webkitgtk: 'webkitgtk-6.0',
         'gobject-introspection': 'gobject-introspection',
+        manette: 'libmanette',
+        gstreamer: 'gstreamer',
+        'gst-app': 'gst-plugins-base',
+        'gdk-pixbuf': 'gdk-pixbuf2',
+        pango: 'pango',
+        pangocairo: 'pango',
+        cairo: 'cairo',
     },
     zypper: {
         gjs: 'gjs',
@@ -158,8 +312,15 @@ const PM_PACKAGES = {
         gtk4: 'gtk4-devel',
         libadwaita: 'libadwaita-devel',
         libsoup3: 'libsoup-3_0-devel',
-        webkitgtk: 'webkit2gtk3-devel',
+        webkitgtk: 'webkitgtk6_0-devel',
         'gobject-introspection': 'gobject-introspection-devel',
+        manette: 'libmanette-0_2-0-devel',
+        gstreamer: 'gstreamer-devel',
+        'gst-app': 'gstreamer-plugins-base-devel',
+        'gdk-pixbuf': 'gdk-pixbuf-devel',
+        pango: 'pango-devel',
+        pangocairo: 'pango-devel',
+        cairo: 'cairo-devel',
     },
     apk: {
         gjs: 'gjs',
@@ -169,8 +330,15 @@ const PM_PACKAGES = {
         gtk4: 'gtk4.0-dev',
         libadwaita: 'libadwaita-dev',
         libsoup3: 'libsoup3-dev',
-        webkitgtk: 'webkit2gtk-4.1-dev',
+        webkitgtk: 'webkit2gtk-6.0-dev',
         'gobject-introspection': 'gobject-introspection-dev',
+        manette: 'libmanette-dev',
+        gstreamer: 'gstreamer-dev',
+        'gst-app': 'gst-plugins-base-dev',
+        'gdk-pixbuf': 'gdk-pixbuf-dev',
+        pango: 'pango-dev',
+        pangocairo: 'pango-dev',
+        cairo: 'cairo-dev',
     },
     unknown: {},
 };

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

@@ -17,6 +17,10 @@ export declare function detectNativePackages(startDir: string): NativePackage[];
  * Reads the nearest package.json to discover dependencies, then checks each
  * for gjsify native prebuilds metadata.
  *
+ * Also checks the **nearest package.json itself** — a workspace package may
+ * have its own prebuilds (e.g. `@gjsify/webgl` running its own test) and
+ * never list itself in dependencies.
+ *
  * This complements detectNativePackages() (filesystem walk from CWD) by using
  * require.resolve() — which handles hoisting, workspaces, and nested node_modules.
  */

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

@@ -125,6 +125,10 @@ function findNearestPackageJson(startDir) {
  * Reads the nearest package.json to discover dependencies, then checks each
  * for gjsify native prebuilds metadata.
  *
+ * Also checks the **nearest package.json itself** — a workspace package may
+ * have its own prebuilds (e.g. `@gjsify/webgl` running its own test) and
+ * never list itself in dependencies.
+ *
  * This complements detectNativePackages() (filesystem walk from CWD) by using
  * require.resolve() — which handles hoisting, workspaces, and nested node_modules.
  */
@@ -140,6 +144,14 @@ export function resolveNativePackages(fromFilePath) {
         const pkg = readPackageJson(nearestPkgJson);
         if (!pkg)
             return results;
+        // Check the nearest package itself (e.g. @gjsify/webgl running its own
+        // test bundle — webgl never lists itself in dependencies)
+        const ownName = typeof pkg['name'] === 'string' ? pkg['name'] : '';
+        if (ownName) {
+            const ownNative = checkPackage(dirname(nearestPkgJson), ownName, arch);
+            if (ownNative)
+                results.push(ownNative);
+        }
         const deps = pkg['dependencies'];
         if (!deps)
             return results;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "CLI for Gjsify",
   "type": "module",
   "main": "lib/index.js",
@@ -23,14 +23,15 @@
     "cli"
   ],
   "dependencies": {
-    "@gjsify/create-app": "^0.1.8",
-    "@gjsify/esbuild-plugin-gjsify": "^0.1.8",
-    "@gjsify/example-dom-canvas2d-fireworks": "^0.1.8",
-    "@gjsify/example-dom-three-geometry-teapot": "^0.1.8",
-    "@gjsify/example-dom-three-postprocessing-pixel": "^0.1.8",
-    "@gjsify/example-node-express-webserver": "^0.1.8",
-    "@gjsify/node-polyfills": "^0.1.8",
-    "@gjsify/web-polyfills": "^0.1.8",
+    "@gjsify/create-app": "^0.1.10",
+    "@gjsify/esbuild-plugin-gjsify": "^0.1.10",
+    "@gjsify/example-dom-canvas2d-fireworks": "^0.1.10",
+    "@gjsify/example-dom-excalibur-jelly-jumper": "^0.1.10",
+    "@gjsify/example-dom-three-geometry-teapot": "^0.1.10",
+    "@gjsify/example-dom-three-postprocessing-pixel": "^0.1.10",
+    "@gjsify/example-node-express-webserver": "^0.1.10",
+    "@gjsify/node-polyfills": "^0.1.10",
+    "@gjsify/web-polyfills": "^0.1.10",
     "cosmiconfig": "^9.0.1",
     "esbuild": "^0.28.0",
     "get-tsconfig": "^4.13.7",

package/src/actions/build.ts

@@ -2,7 +2,7 @@ import type { ConfigData } from '../types/index.js';
 import type { App } from '@gjsify/esbuild-plugin-gjsify';
 import { build, BuildOptions, BuildResult } from 'esbuild';
 import { gjsifyPlugin } from '@gjsify/esbuild-plugin-gjsify';
-import { resolveGlobalsList, writeRegisterInjectFile } from '@gjsify/esbuild-plugin-gjsify/globals';
+import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals } from '@gjsify/esbuild-plugin-gjsify/globals';
 import { dirname, extname } from 'path';
 
 export class BuildAction {
@@ -75,17 +75,41 @@ export class BuildAction {
         return results;
     }
 
+    /**
+     * Parse the `--globals` value into { autoMode, extras }.
+     * - `auto`             → { autoMode: true, extras: '' }
+     * - `auto,dom`         → { autoMode: true, extras: 'dom' }
+     * - `auto,dom,fetch`   → { autoMode: true, extras: 'dom,fetch' }
+     * - `dom,fetch`        → { autoMode: false, extras: 'dom,fetch' }
+     * - `none` / ``        → { autoMode: false, extras: '' }
+     * - `undefined`        → { autoMode: true, extras: '' }  (default)
+     */
+    private parseGlobalsValue(value: string | undefined): { autoMode: boolean; extras: string } {
+        if (value === undefined) return { autoMode: true, extras: '' };
+        if (value === 'none' || value === '') return { autoMode: false, extras: '' };
+
+        const tokens = value.split(',').map(t => t.trim()).filter(Boolean);
+        const hasAuto = tokens.includes('auto');
+        const extras = tokens.filter(t => t !== 'auto').join(',');
+
+        return { autoMode: hasAuto, extras };
+    }
+
     /**
      * Resolve the `--globals` CLI list into a pre-computed inject stub path
      * that the esbuild plugin will append to its `inject` list. Only runs
      * for `--app gjs` — Node and browser builds rely on native globals.
+     *
+     * Used only for the explicit-only path (no `auto` token in the value).
+     * The auto path is handled in `buildApp` via the two-pass build.
      */
     private async resolveGlobalsInject(
         app: App,
-        globals: string | undefined,
+        globals: string,
         verbose: boolean | undefined,
     ): Promise<string | undefined> {
-        if (app !== 'gjs' || !globals) return undefined;
+        if (app !== 'gjs') return undefined;
+        if (!globals) return undefined;
 
         const registerPaths = resolveGlobalsList(globals);
         if (registerPaths.size === 0) return undefined;
@@ -106,13 +130,55 @@ export class BuildAction {
 
         const format: 'esm' | 'cjs' = (esbuild?.format as 'esm' | 'cjs') ?? (esbuild?.outfile?.endsWith('.cjs') ? 'cjs' : 'esm');
 
-        // Set default outfile if no outdir is set 
+        // Set default outfile if no outdir is set
         if(esbuild && !esbuild?.outfile && !esbuild?.outdir && (pgk?.main || pgk?.module)) {
             esbuild.outfile = esbuild?.format === 'cjs' ? pgk.main || pgk.module : pgk.module || pgk.main;
         }
 
         const { consoleShim, globals } = this.configData;
-        const autoGlobalsInject = await this.resolveGlobalsInject(app, globals, verbose);
+
+        const pluginOpts = {
+            debug: verbose,
+            app,
+            format,
+            exclude,
+            reflection: typescript?.reflection,
+            consoleShim,
+        };
+
+        const { autoMode, extras } = this.parseGlobalsValue(globals);
+
+        // --- Auto mode (with optional extras): iterative multi-pass build ---
+        // The extras token is used for cases where the detector cannot
+        // statically see a global (e.g. Excalibur indirects globalThis via
+        // BrowserComponent.nativeComponent). Common pattern: --globals auto,dom
+        if (app === 'gjs' && autoMode) {
+            const { injectPath } = await detectAutoGlobals(
+                { ...this.getEsBuildDefaults(), ...esbuild, format },
+                pluginOpts,
+                verbose,
+                { extraGlobalsList: extras },
+            );
+
+            const result = await build({
+                ...this.getEsBuildDefaults(),
+                ...esbuild,
+                format,
+                plugins: [
+                    gjsifyPlugin({
+                        ...pluginOpts,
+                        autoGlobalsInject: injectPath,
+                    }),
+                ],
+            });
+
+            return [result];
+        }
+
+        // --- Explicit list (no `auto` token) or none mode ---
+        const autoGlobalsInject = extras
+            ? await this.resolveGlobalsInject(app, extras, verbose)
+            : undefined;
 
         const result = await build({
             ...this.getEsBuildDefaults(),
@@ -120,26 +186,12 @@ export class BuildAction {
             format,
             plugins: [
                 gjsifyPlugin({
-                    debug: verbose,
-                    app,
-                    format,
-                    exclude,
-                    reflection: typescript?.reflection,
-                    consoleShim,
+                    ...pluginOpts,
                     autoGlobalsInject,
                 }),
             ]
         });
 
-        // See https://esbuild.github.io/api/#metafile
-        // TODO add cli options for this
-        // if(result.metafile) {
-        //     const outFile = esbuild?.outfile ? esbuild.outfile + '.meta.json' : 'meta.json';
-        //     await writeFile(outFile, JSON.stringify(result.metafile));
-        //     let text = await analyzeMetafile(result.metafile)
-        //     console.log(text)
-        // }
-
         return [result];
     }
 

package/src/commands/build.ts

@@ -89,10 +89,10 @@ export const buildCommand: Command<any, CliBuildOptions> = {
                 default: true
             })
             .option('globals', {
-                description: "Comma-separated list of global identifiers your code needs (e.g. 'fetch,Buffer,process,URL,crypto'). Each identifier is mapped to the corresponding `@gjsify/<pkg>/register` module and injected into the bundle. See the CLI Reference docs for the full list of known identifiers. Only applies to GJS app builds.",
+                description: "Comma-separated list of global identifiers, 'auto' (default) to detect automatically from the bundled output, or 'none' to disable. The 'auto' token may be combined with explicit identifiers/groups (e.g. 'auto,dom') for cases where the detector cannot statically see a global because it's accessed via indirection. Each identifier is mapped to the corresponding `@gjsify/<pkg>/register` module and injected into the bundle. See the CLI Reference docs for the full list of known identifiers. Only applies to GJS app builds.",
                 type: 'string',
                 normalize: true,
-                default: ''
+                default: 'auto'
             })
     },
     handler: async (args) => {