@gjsify/cli 0.1.8 → 0.1.9

package/lib/actions/build.d.ts

@@ -7,10 +7,23 @@ export declare class BuildAction {
     getEsBuildDefaults(): BuildOptions;
     /** Library mode */
     buildLibrary(): Promise<BuildResult<BuildOptions>[]>;
+    /**
+     * 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;
     /**
      * 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 resolveGlobalsInject;
     /** Application mode */

package/lib/actions/build.js

@@ -1,6 +1,6 @@
 import { build } 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 {
     configData;
@@ -64,13 +64,37 @@ 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)
+     */
+    parseGlobalsValue(value) {
+        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.
      */
     async resolveGlobalsInject(app, globals, verbose) {
-        if (app !== 'gjs' || !globals)
+        if (app !== 'gjs')
+            return undefined;
+        if (!globals)
             return undefined;
         const registerPaths = resolveGlobalsList(globals);
         if (registerPaths.size === 0)
@@ -85,36 +109,54 @@ export class BuildAction {
     async buildApp(app = 'gjs') {
         const { verbose, esbuild, typescript, exclude, library: pgk } = this.configData;
         const format = esbuild?.format ?? (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(),
             ...esbuild,
             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];
     }
     async start(buildType = { app: 'gjs' }) {

package/lib/commands/build.js

@@ -87,10 +87,10 @@ export const buildCommand = {
             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) => {

package/lib/commands/check.js

@@ -1,7 +1,7 @@
 import { runAllChecks, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
 export const checkCommand = {
     command: 'check',
-    description: 'Check that all required system dependencies (GJS, GTK4, Blueprint Compiler, etc.) are installed.',
+    description: 'Check that required system dependencies (GJS, GTK4, libsoup3, …) are installed. Optional dependencies are detected only when their @gjsify/* package is in your project.',
     builder: (yargs) => {
         return yargs
             .option('json', {
@@ -13,31 +13,60 @@ export const checkCommand = {
     handler: async (args) => {
         const results = runAllChecks(process.cwd());
         const pm = detectPackageManager();
-        const missing = results.filter(r => !r.found);
+        const missingRequired = results.filter(r => !r.found && r.severity === 'required');
+        const missingOptional = results.filter(r => !r.found && r.severity === 'optional');
+        const allMissing = [...missingRequired, ...missingOptional];
         if (args.json) {
             console.log(JSON.stringify({ packageManager: pm, deps: results }, null, 2));
-            process.exit(missing.length > 0 ? 1 : 0);
+            // Only required deps influence the exit code.
+            process.exit(missingRequired.length > 0 ? 1 : 0);
             return;
         }
         console.log('System dependency check\n');
-        for (const dep of results) {
-            const icon = dep.found ? '✓' : '✗';
-            const ver = dep.version ? `  (${dep.version})` : '';
-            console.log(`  ${icon}  ${dep.name}${ver}`);
+        const required = results.filter(r => r.severity === 'required');
+        const optional = results.filter(r => r.severity === 'optional');
+        if (required.length > 0) {
+            console.log('Required:');
+            for (const dep of required) {
+                const icon = dep.found ? '✓' : '✗';
+                const ver = dep.version ? `  (${dep.version})` : '';
+                console.log(`  ${icon}  ${dep.name}${ver}`);
+            }
+        }
+        if (optional.length > 0) {
+            console.log('\nOptional:');
+            for (const dep of optional) {
+                // ⚠ for missing-but-needed-by-installed-packages, ○ for missing-but-not-needed (shouldn't appear in conditional mode)
+                const icon = dep.found ? '✓' : '⚠';
+                const ver = dep.version ? `  (${dep.version})` : '';
+                const requiredBy = dep.requiredBy && dep.requiredBy.length > 0
+                    ? `  — needed by ${dep.requiredBy.join(', ')}`
+                    : '';
+                console.log(`  ${icon}  ${dep.name}${ver}${requiredBy}`);
+            }
         }
         console.log(`\nPackage manager: ${pm}`);
-        if (missing.length === 0) {
+        if (allMissing.length === 0) {
             console.log('\nAll dependencies found.');
             return;
         }
-        console.log(`\nMissing: ${missing.map(d => d.name).join(', ')}`);
-        const cmd = buildInstallCommand(pm, missing);
+        if (missingRequired.length > 0) {
+            console.log(`\nMissing required: ${missingRequired.map(d => d.name).join(', ')}`);
+        }
+        if (missingOptional.length > 0) {
+            console.log(`Missing optional: ${missingOptional.map(d => d.name).join(', ')}`);
+        }
+        const cmd = buildInstallCommand(pm, allMissing);
         if (cmd) {
-            console.log(`\nTo install missing dependencies:\n  ${cmd}`);
+            console.log(`\nTo install:\n  ${cmd}`);
         }
         else {
             console.log('\nNo install command available for your package manager. Install manually.');
         }
-        process.exit(1);
+        // Exit non-zero ONLY if a required dependency is missing.
+        // Optional deps that are missing but needed by an installed @gjsify/*
+        // package generate a warning but keep exit code 0 — the user can still
+        // build/run code paths that don't touch the optional library.
+        process.exit(missingRequired.length > 0 ? 1 : 0);
     },
 };

package/lib/commands/showcase.js

@@ -68,14 +68,16 @@ export const showcaseCommand = {
         if (needsWebgl) {
             results.push(checkGwebgl(process.cwd()));
         }
-        const missing = results.filter(r => !r.found);
-        if (missing.length > 0) {
+        // Hard-fail only on missing REQUIRED deps (gjs, gwebgl is required if needsWebgl).
+        // For showcase, gwebgl is treated as required because the bundle won't run without it.
+        const missingHard = results.filter(r => !r.found && (r.severity === 'required' || r.id === 'gwebgl'));
+        if (missingHard.length > 0) {
             console.error('Missing system dependencies:\n');
-            for (const dep of missing) {
+            for (const dep of missingHard) {
                 console.error(`  ✗  ${dep.name}`);
             }
             const pm = detectPackageManager();
-            const cmd = buildInstallCommand(pm, missing);
+            const cmd = buildInstallCommand(pm, missingHard);
             if (cmd) {
                 console.error(`\nInstall with:\n  ${cmd}`);
             }

package/lib/utils/check-system-deps.d.ts

@@ -1,3 +1,4 @@
+export type DepSeverity = 'required' | 'optional';
 export interface DepCheck {
     /** Stable key used for install command lookup, e.g. "gjs" */
     id: string;
@@ -6,19 +7,30 @@ export interface DepCheck {
     found: boolean;
     /** Version string when found, e.g. "1.86.0" */
     version?: string;
+    /** required = exit 1 if missing, optional = warn only */
+    severity: DepSeverity;
+    /** For optional deps: which @gjsify/* packages need this lib */
+    requiredBy?: string[];
 }
 export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'unknown';
 export declare function detectPackageManager(): PackageManager;
 /**
  * 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 declare function runAllChecks(cwd: string): DepCheck[];
 /**
- * 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 declare function runMinimalChecks(): DepCheck[];
-/** Check gwebgl npm package (project first, CLI fallback). */
+/** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
 export declare function checkGwebgl(cwd: string): DepCheck;
 /**
  * Build a suggested install command for missing dependencies.