@gjsify/cli 0.3.2 → 0.3.3

package/lib/actions/build.d.ts

@@ -1,6 +1,6 @@
-import type { ConfigData } from '../types/index.js';
-import type { App } from '@gjsify/esbuild-plugin-gjsify';
-import { BuildOptions, BuildResult, Plugin } from 'esbuild';
+import type { ConfigData } from "../types/index.js";
+import type { App } from "@gjsify/esbuild-plugin-gjsify";
+import { BuildOptions, BuildResult, Plugin } from "esbuild";
 export declare class BuildAction {
     readonly configData: ConfigData;
     constructor(configData?: ConfigData);

package/lib/actions/build.js

@@ -1,9 +1,9 @@
-import { build } from 'esbuild';
-import { gjsifyPlugin } from '@gjsify/esbuild-plugin-gjsify';
-import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals } from '@gjsify/esbuild-plugin-gjsify/globals';
-import { dirname, extname, join } from 'node:path';
-import { chmod, readFile, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { build } from "esbuild";
+import { gjsifyPlugin } from "@gjsify/esbuild-plugin-gjsify";
+import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, } from "@gjsify/esbuild-plugin-gjsify/globals";
+import { dirname, extname, join } from "node:path";
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 const GJS_SHEBANG = "#!/usr/bin/env -S gjs -m\n";
 /** Walk up from dir until .pnp.cjs is found; return its directory or null. */
 function findPnpRoot(dir) {
@@ -21,13 +21,36 @@ function findPnpRoot(dir) {
  * If the current project uses Yarn PnP, return the official
  * @yarnpkg/esbuild-plugin-pnp plugin so esbuild can resolve
  * modules from zip archives without manual extraction.
+ *
+ * Custom onResolve: fall through on UNDECLARED_DEPENDENCY errors so the
+ * gjsify alias plugin can handle bare specifiers (e.g. `abort-controller`)
+ * that PnP can't resolve from the inject file's issuer context but that
+ * gjsify maps to `@gjsify/*` packages the project DOES have available.
  */
 async function getPnpPlugin() {
     if (!findPnpRoot(process.cwd()))
         return null;
     try {
         const { pnpPlugin } = await import("@yarnpkg/esbuild-plugin-pnp");
-        return pnpPlugin();
+        return pnpPlugin({
+            onResolve: async (_args, { resolvedPath, error, watchFiles }) => {
+                if (resolvedPath !== null) {
+                    return { namespace: "pnp", path: resolvedPath, watchFiles };
+                }
+                // UNDECLARED_DEPENDENCY: package exists transitively but isn't
+                // in the issuer's direct deps. Fall through so the gjsify alias
+                // plugin can resolve it (e.g. bare → @gjsify/* mappings).
+                if (error?.pnpCode ===
+                    "UNDECLARED_DEPENDENCY") {
+                    return null;
+                }
+                return {
+                    external: true,
+                    errors: error ? [{ text: error.message }] : [],
+                    watchFiles,
+                };
+            },
+        });
     }
     catch {
         return null;
@@ -40,7 +63,7 @@ export class BuildAction {
     }
     getEsBuildDefaults() {
         const defaults = {
-            allowOverwrite: true
+            allowOverwrite: true,
         };
         return defaults;
     }
@@ -59,7 +82,9 @@ export class BuildAction {
         const pnpPlugins = pnpPlugin ? [pnpPlugin] : [];
         const results = [];
         if (multipleBuilds) {
-            const moduleFormat = moduleOutdir.includes("/cjs") || moduleOutExt === ".cjs" ? "cjs" : "esm";
+            const moduleFormat = moduleOutdir.includes("/cjs") || moduleOutExt === ".cjs"
+                ? "cjs"
+                : "esm";
             results.push(await build({
                 ...this.getEsBuildDefaults(),
                 ...esbuild,
@@ -67,7 +92,13 @@ export class BuildAction {
                 outdir: moduleOutdir,
                 plugins: [
                     ...pnpPlugins,
-                    gjsifyPlugin({ debug: verbose, library: moduleFormat, exclude, reflection: typescript?.reflection, jsExtension: moduleOutExt }),
+                    gjsifyPlugin({
+                        debug: verbose,
+                        library: moduleFormat,
+                        exclude,
+                        reflection: typescript?.reflection,
+                        jsExtension: moduleOutExt,
+                    }),
                 ],
             }));
             const mainFormat = mainOutdir.includes("/cjs") || mainOutExt === ".cjs" ? "cjs" : "esm";
@@ -78,7 +109,13 @@ export class BuildAction {
                 outdir: mainOutdir,
                 plugins: [
                     ...pnpPlugins,
-                    gjsifyPlugin({ debug: verbose, library: mainFormat, exclude, reflection: typescript?.reflection, jsExtension: mainOutdir }),
+                    gjsifyPlugin({
+                        debug: verbose,
+                        library: mainFormat,
+                        exclude,
+                        reflection: typescript?.reflection,
+                        jsExtension: mainOutdir,
+                    }),
                 ],
             }));
         }
@@ -86,7 +123,8 @@ export class BuildAction {
             const outfilePath = esbuild?.outfile || library?.module || library?.main;
             const outExt = outfilePath ? extname(outfilePath) : ".js";
             const outdir = esbuild?.outdir || (outfilePath ? dirname(outfilePath) : undefined);
-            const format = esbuild?.format ?? (outdir?.includes("/cjs") || outExt === ".cjs" ? "cjs" : "esm");
+            const format = esbuild?.format ??
+                (outdir?.includes("/cjs") || outExt === ".cjs" ? "cjs" : "esm");
             results.push(await build({
                 ...this.getEsBuildDefaults(),
                 ...esbuild,
@@ -94,7 +132,13 @@ export class BuildAction {
                 outdir,
                 plugins: [
                     ...pnpPlugins,
-                    gjsifyPlugin({ debug: verbose, library: format, exclude, reflection: typescript?.reflection, jsExtension: outExt }),
+                    gjsifyPlugin({
+                        debug: verbose,
+                        library: format,
+                        exclude,
+                        reflection: typescript?.reflection,
+                        jsExtension: outExt,
+                    }),
                 ],
             }));
         }
@@ -111,12 +155,15 @@ export class BuildAction {
      */
     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: 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 };
     }
     /**
@@ -128,7 +175,7 @@ export class BuildAction {
      * The auto path is handled in `buildApp` via the two-pass build.
      */
     async resolveGlobalsInject(app, globals, verbose) {
-        if (app !== 'gjs')
+        if (app !== "gjs")
             return undefined;
         if (!globals)
             return undefined;
@@ -148,11 +195,11 @@ export class BuildAction {
     async applyShebang(outfile, verbose) {
         if (!outfile) {
             if (verbose)
-                console.warn('[gjsify] --shebang skipped: no single outfile (use --outfile for GJS executables)');
+                console.warn("[gjsify] --shebang skipped: no single outfile (use --outfile for GJS executables)");
             return;
         }
-        const content = await readFile(outfile, 'utf-8');
-        if (content.startsWith('#!')) {
+        const content = await readFile(outfile, "utf-8");
+        if (content.startsWith("#!")) {
             if (verbose)
                 console.debug(`[gjsify] --shebang skipped: ${outfile} already starts with a shebang`);
         }
@@ -165,11 +212,18 @@ export class BuildAction {
     }
     /** Application mode */
     async buildApp(app = "gjs") {
-        const { verbose, esbuild, typescript, exclude, library: pgk, aliases, excludeGlobals } = this.configData;
-        const format = esbuild?.format ?? (esbuild?.outfile?.endsWith(".cjs") ? "cjs" : "esm");
+        const { verbose, esbuild, typescript, exclude, library: pgk, aliases, excludeGlobals, } = this.configData;
+        const format = esbuild?.format ??
+            (esbuild?.outfile?.endsWith(".cjs") ? "cjs" : "esm");
         // 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;
+        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 pluginOpts = {
@@ -189,7 +243,12 @@ export class BuildAction {
         // 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, plugins: pnpPlugins }, pluginOpts, verbose, { extraGlobalsList: extras, excludeGlobals });
+            const { injectPath } = await detectAutoGlobals({
+                ...this.getEsBuildDefaults(),
+                ...esbuild,
+                format,
+                plugins: pnpPlugins,
+            }, pluginOpts, verbose, { extraGlobalsList: extras, excludeGlobals });
             const result = await build({
                 ...this.getEsBuildDefaults(),
                 ...esbuild,
@@ -208,7 +267,9 @@ export class BuildAction {
             return [result];
         }
         // --- Explicit list (no `auto` token) or none mode ---
-        const autoGlobalsInject = extras ? await this.resolveGlobalsInject(app, extras, verbose) : undefined;
+        const autoGlobalsInject = extras
+            ? await this.resolveGlobalsInject(app, extras, verbose)
+            : undefined;
         const result = await build({
             ...this.getEsBuildDefaults(),
             ...esbuild,
@@ -226,7 +287,7 @@ export class BuildAction {
         }
         return [result];
     }
-    async start(buildType = { app: 'gjs' }) {
+    async start(buildType = { app: "gjs" }) {
         const results = [];
         if (buildType.library) {
             results.push(...(await this.buildLibrary()));

package/package.json

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

package/src/actions/build.ts

@@ -1,280 +1,380 @@
-import type { ConfigData } from '../types/index.js';
-import type { App } from '@gjsify/esbuild-plugin-gjsify';
-import { build, BuildOptions, BuildResult, Plugin } from 'esbuild';
-import { gjsifyPlugin } from '@gjsify/esbuild-plugin-gjsify';
-import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals } from '@gjsify/esbuild-plugin-gjsify/globals';
-import { dirname, extname, join } from 'node:path';
-import { chmod, readFile, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import type { ConfigData } from "../types/index.js";
+import type { App } from "@gjsify/esbuild-plugin-gjsify";
+import { build, BuildOptions, BuildResult, Plugin } from "esbuild";
+import { gjsifyPlugin } from "@gjsify/esbuild-plugin-gjsify";
+import {
+	resolveGlobalsList,
+	writeRegisterInjectFile,
+	detectAutoGlobals,
+} from "@gjsify/esbuild-plugin-gjsify/globals";
+import { dirname, extname, join } from "node:path";
+import { chmod, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 
 const GJS_SHEBANG = "#!/usr/bin/env -S gjs -m\n";
 
 /** Walk up from dir until .pnp.cjs is found; return its directory or null. */
 function findPnpRoot(dir: string): string | null {
-    let current = dir;
-    while (true) {
-        if (existsSync(join(current, ".pnp.cjs"))) return current;
-        const parent = dirname(current);
-        if (parent === current) return null;
-        current = parent;
-    }
+	let current = dir;
+	while (true) {
+		if (existsSync(join(current, ".pnp.cjs"))) return current;
+		const parent = dirname(current);
+		if (parent === current) return null;
+		current = parent;
+	}
 }
 
 /**
  * If the current project uses Yarn PnP, return the official
  * @yarnpkg/esbuild-plugin-pnp plugin so esbuild can resolve
  * modules from zip archives without manual extraction.
+ *
+ * Custom onResolve: fall through on UNDECLARED_DEPENDENCY errors so the
+ * gjsify alias plugin can handle bare specifiers (e.g. `abort-controller`)
+ * that PnP can't resolve from the inject file's issuer context but that
+ * gjsify maps to `@gjsify/*` packages the project DOES have available.
  */
 async function getPnpPlugin(): Promise<Plugin | null> {
-    if (!findPnpRoot(process.cwd())) return null;
-    try {
-        const { pnpPlugin } = await import("@yarnpkg/esbuild-plugin-pnp");
-        return pnpPlugin();
-    } catch {
-        return null;
-    }
+	if (!findPnpRoot(process.cwd())) return null;
+	try {
+		const { pnpPlugin } = await import("@yarnpkg/esbuild-plugin-pnp");
+		return pnpPlugin({
+			onResolve: async (_args, { resolvedPath, error, watchFiles }) => {
+				if (resolvedPath !== null) {
+					return { namespace: "pnp", path: resolvedPath, watchFiles };
+				}
+				// UNDECLARED_DEPENDENCY: package exists transitively but isn't
+				// in the issuer's direct deps. Fall through so the gjsify alias
+				// plugin can resolve it (e.g. bare → @gjsify/* mappings).
+				if (
+					(error as { pnpCode?: string } | null)?.pnpCode ===
+					"UNDECLARED_DEPENDENCY"
+				) {
+					return null;
+				}
+				return {
+					external: true,
+					errors: error ? [{ text: error.message }] : [],
+					watchFiles,
+				};
+			},
+		});
+	} catch {
+		return null;
+	}
 }
 
 export class BuildAction {
-    constructor(readonly configData: ConfigData = {}) {
-
-    }
-
-    getEsBuildDefaults() {
-        const defaults: BuildOptions = {
-            allowOverwrite: true
-        }
-        return defaults;
-    }
-
-    /** Library mode */
-    async buildLibrary() {
-        let { verbose, library, esbuild, typescript, exclude } = this.configData;
-        library ||= {};
-        esbuild ||= {};
-        typescript ||= {};
-
-        const moduleOutdir = library?.module ? dirname(library.module) : undefined;
-        const mainOutdir = library?.main ? dirname(library.main) : undefined;
-
-        const moduleOutExt = library.module ? extname(library.module) : ".js";
-        const mainOutExt = library.main ? extname(library.main) : ".js";
-
-        const multipleBuilds = moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
-
-        const pnpPlugin = await getPnpPlugin();
-        const pnpPlugins: Plugin[] = pnpPlugin ? [pnpPlugin] : [];
-
-        const results: BuildResult[] = [];
-
-        if (multipleBuilds) {
-            const moduleFormat = moduleOutdir.includes("/cjs") || moduleOutExt === ".cjs" ? "cjs" : "esm";
-            results.push(
-                await build({
-                    ...this.getEsBuildDefaults(),
-                    ...esbuild,
-                    format: moduleFormat,
-                    outdir: moduleOutdir,
-                    plugins: [
-                        ...pnpPlugins,
-                        gjsifyPlugin({ debug: verbose, library: moduleFormat, exclude, reflection: typescript?.reflection, jsExtension: moduleOutExt }),
-                    ],
-                }),
-            );
-
-            const mainFormat = mainOutdir.includes("/cjs") || mainOutExt === ".cjs" ? "cjs" : "esm";
-            results.push(
-                await build({
-                    ...this.getEsBuildDefaults(),
-                    ...esbuild,
-                    format: moduleFormat,
-                    outdir: mainOutdir,
-                    plugins: [
-                        ...pnpPlugins,
-                        gjsifyPlugin({ debug: verbose, library: mainFormat, exclude, reflection: typescript?.reflection, jsExtension: mainOutdir }),
-                    ],
-                }),
-            );
-        } else {
-            const outfilePath = esbuild?.outfile || library?.module || library?.main;
-            const outExt = outfilePath ? extname(outfilePath) : ".js";
-            const outdir = esbuild?.outdir || (outfilePath ? dirname(outfilePath) : undefined);
-            const format: "esm" | "cjs" = (esbuild?.format as "esm" | "cjs") ?? (outdir?.includes("/cjs") || outExt === ".cjs" ? "cjs" : "esm");
-            results.push(
-                await build({
-                    ...this.getEsBuildDefaults(),
-                    ...esbuild,
-                    format,
-                    outdir,
-                    plugins: [
-                        ...pnpPlugins,
-                        gjsifyPlugin({ debug: verbose, library: format, exclude, reflection: typescript?.reflection, jsExtension: outExt }),
-                    ],
-                }),
-            );
-        }
-        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,
-        verbose: boolean | undefined,
-    ): Promise<string | undefined> {
-        if (app !== 'gjs') return undefined;
-        if (!globals) return undefined;
-
-        const registerPaths = resolveGlobalsList(globals);
-        if (registerPaths.size === 0) return undefined;
-
-        const injectPath = await writeRegisterInjectFile(registerPaths, process.cwd());
-        if (verbose && injectPath) {
-            console.debug(
-                `[gjsify] globals: injected ${registerPaths.size} register module(s) from --globals ${globals}`,
-            );
-        }
-        return injectPath ?? undefined;
-    }
-
-    /**
-     * Post-processing: prepend GJS shebang and mark the output file executable.
-     * Only runs for GJS app builds with a resolvable single outfile.
-     */
-    private async applyShebang(outfile: string | undefined, verbose: boolean | undefined): Promise<void> {
-        if (!outfile) {
-            if (verbose) console.warn('[gjsify] --shebang skipped: no single outfile (use --outfile for GJS executables)');
-            return;
-        }
-
-        const content = await readFile(outfile, 'utf-8');
-        if (content.startsWith('#!')) {
-            if (verbose) console.debug(`[gjsify] --shebang skipped: ${outfile} already starts with a shebang`);
-        } else {
-            await writeFile(outfile, GJS_SHEBANG + content);
-        }
-        await chmod(outfile, 0o755);
-        if (verbose) console.debug(`[gjsify] --shebang: wrote shebang + chmod 0o755 to ${outfile}`);
-    }
-
-    /** Application mode */
-    async buildApp(app: App = "gjs") {
-        const { verbose, esbuild, typescript, exclude, library: pgk, aliases, excludeGlobals } = this.configData;
-
-        const format: "esm" | "cjs" = (esbuild?.format as "esm" | "cjs") ?? (esbuild?.outfile?.endsWith(".cjs") ? "cjs" : "esm");
-
-        // 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 pluginOpts = {
-            debug: verbose,
-            app,
-            format,
-            exclude,
-            reflection: typescript?.reflection,
-            consoleShim,
-            ...(aliases ? { aliases } : {}),
-        };
-
-        const { autoMode, extras } = this.parseGlobalsValue(globals);
-
-        const pnpPlugin = await getPnpPlugin();
-        const pnpPlugins: Plugin[] = pnpPlugin ? [pnpPlugin] : [];
-
-        // --- 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, plugins: pnpPlugins },
-                pluginOpts,
-                verbose,
-                { extraGlobalsList: extras, excludeGlobals },
-            );
-
-            const result = await build({
-                ...this.getEsBuildDefaults(),
-                ...esbuild,
-                format,
-                plugins: [
-                    ...pnpPlugins,
-                    gjsifyPlugin({
-                        ...pluginOpts,
-                        autoGlobalsInject: injectPath,
-                    }),
-                ],
-            });
-
-            if (app === "gjs" && this.configData.shebang) {
-                await this.applyShebang(esbuild?.outfile, verbose);
-            }
-
-            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: [
-                ...pnpPlugins,
-                gjsifyPlugin({
-                    ...pluginOpts,
-                    autoGlobalsInject,
-                }),
-            ],
-        });
-
-        if (app === "gjs" && this.configData.shebang) {
-            await this.applyShebang(esbuild?.outfile, verbose);
-        }
-
-        return [result];
-    }
-
-    async start(buildType: {library?: boolean, app?: App} = {app: 'gjs'}) {
-        const results: BuildResult[] = [];
-        if(buildType.library) {
-            results.push(...(await this.buildLibrary()));
-        } else {
-            results.push(...(await this.buildApp(buildType.app)));
-        }
-
-        return results;
-    }
-}
+	constructor(readonly configData: ConfigData = {}) {}
+
+	getEsBuildDefaults() {
+		const defaults: BuildOptions = {
+			allowOverwrite: true,
+		};
+		return defaults;
+	}
+
+	/** Library mode */
+	async buildLibrary() {
+		let { verbose, library, esbuild, typescript, exclude } = this.configData;
+		library ||= {};
+		esbuild ||= {};
+		typescript ||= {};
+
+		const moduleOutdir = library?.module ? dirname(library.module) : undefined;
+		const mainOutdir = library?.main ? dirname(library.main) : undefined;
+
+		const moduleOutExt = library.module ? extname(library.module) : ".js";
+		const mainOutExt = library.main ? extname(library.main) : ".js";
+
+		const multipleBuilds =
+			moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
+
+		const pnpPlugin = await getPnpPlugin();
+		const pnpPlugins: Plugin[] = pnpPlugin ? [pnpPlugin] : [];
+
+		const results: BuildResult[] = [];
+
+		if (multipleBuilds) {
+			const moduleFormat =
+				moduleOutdir.includes("/cjs") || moduleOutExt === ".cjs"
+					? "cjs"
+					: "esm";
+			results.push(
+				await build({
+					...this.getEsBuildDefaults(),
+					...esbuild,
+					format: moduleFormat,
+					outdir: moduleOutdir,
+					plugins: [
+						...pnpPlugins,
+						gjsifyPlugin({
+							debug: verbose,
+							library: moduleFormat,
+							exclude,
+							reflection: typescript?.reflection,
+							jsExtension: moduleOutExt,
+						}),
+					],
+				}),
+			);
+
+			const mainFormat =
+				mainOutdir.includes("/cjs") || mainOutExt === ".cjs" ? "cjs" : "esm";
+			results.push(
+				await build({
+					...this.getEsBuildDefaults(),
+					...esbuild,
+					format: moduleFormat,
+					outdir: mainOutdir,
+					plugins: [
+						...pnpPlugins,
+						gjsifyPlugin({
+							debug: verbose,
+							library: mainFormat,
+							exclude,
+							reflection: typescript?.reflection,
+							jsExtension: mainOutdir,
+						}),
+					],
+				}),
+			);
+		} else {
+			const outfilePath = esbuild?.outfile || library?.module || library?.main;
+			const outExt = outfilePath ? extname(outfilePath) : ".js";
+			const outdir =
+				esbuild?.outdir || (outfilePath ? dirname(outfilePath) : undefined);
+			const format: "esm" | "cjs" =
+				(esbuild?.format as "esm" | "cjs") ??
+				(outdir?.includes("/cjs") || outExt === ".cjs" ? "cjs" : "esm");
+			results.push(
+				await build({
+					...this.getEsBuildDefaults(),
+					...esbuild,
+					format,
+					outdir,
+					plugins: [
+						...pnpPlugins,
+						gjsifyPlugin({
+							debug: verbose,
+							library: format,
+							exclude,
+							reflection: typescript?.reflection,
+							jsExtension: outExt,
+						}),
+					],
+				}),
+			);
+		}
+		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,
+		verbose: boolean | undefined,
+	): Promise<string | undefined> {
+		if (app !== "gjs") return undefined;
+		if (!globals) return undefined;
+
+		const registerPaths = resolveGlobalsList(globals);
+		if (registerPaths.size === 0) return undefined;
+
+		const injectPath = await writeRegisterInjectFile(
+			registerPaths,
+			process.cwd(),
+		);
+		if (verbose && injectPath) {
+			console.debug(
+				`[gjsify] globals: injected ${registerPaths.size} register module(s) from --globals ${globals}`,
+			);
+		}
+		return injectPath ?? undefined;
+	}
+
+	/**
+	 * Post-processing: prepend GJS shebang and mark the output file executable.
+	 * Only runs for GJS app builds with a resolvable single outfile.
+	 */
+	private async applyShebang(
+		outfile: string | undefined,
+		verbose: boolean | undefined,
+	): Promise<void> {
+		if (!outfile) {
+			if (verbose)
+				console.warn(
+					"[gjsify] --shebang skipped: no single outfile (use --outfile for GJS executables)",
+				);
+			return;
+		}
+
+		const content = await readFile(outfile, "utf-8");
+		if (content.startsWith("#!")) {
+			if (verbose)
+				console.debug(
+					`[gjsify] --shebang skipped: ${outfile} already starts with a shebang`,
+				);
+		} else {
+			await writeFile(outfile, GJS_SHEBANG + content);
+		}
+		await chmod(outfile, 0o755);
+		if (verbose)
+			console.debug(
+				`[gjsify] --shebang: wrote shebang + chmod 0o755 to ${outfile}`,
+			);
+	}
+
+	/** Application mode */
+	async buildApp(app: App = "gjs") {
+		const {
+			verbose,
+			esbuild,
+			typescript,
+			exclude,
+			library: pgk,
+			aliases,
+			excludeGlobals,
+		} = this.configData;
+
+		const format: "esm" | "cjs" =
+			(esbuild?.format as "esm" | "cjs") ??
+			(esbuild?.outfile?.endsWith(".cjs") ? "cjs" : "esm");
+
+		// 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 pluginOpts = {
+			debug: verbose,
+			app,
+			format,
+			exclude,
+			reflection: typescript?.reflection,
+			consoleShim,
+			...(aliases ? { aliases } : {}),
+		};
+
+		const { autoMode, extras } = this.parseGlobalsValue(globals);
+
+		const pnpPlugin = await getPnpPlugin();
+		const pnpPlugins: Plugin[] = pnpPlugin ? [pnpPlugin] : [];
+
+		// --- 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,
+					plugins: pnpPlugins,
+				},
+				pluginOpts,
+				verbose,
+				{ extraGlobalsList: extras, excludeGlobals },
+			);
+
+			const result = await build({
+				...this.getEsBuildDefaults(),
+				...esbuild,
+				format,
+				plugins: [
+					...pnpPlugins,
+					gjsifyPlugin({
+						...pluginOpts,
+						autoGlobalsInject: injectPath,
+					}),
+				],
+			});
+
+			if (app === "gjs" && this.configData.shebang) {
+				await this.applyShebang(esbuild?.outfile, verbose);
+			}
+
+			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: [
+				...pnpPlugins,
+				gjsifyPlugin({
+					...pluginOpts,
+					autoGlobalsInject,
+				}),
+			],
+		});
+
+		if (app === "gjs" && this.configData.shebang) {
+			await this.applyShebang(esbuild?.outfile, verbose);
+		}
+
+		return [result];
+	}
+
+	async start(buildType: { library?: boolean; app?: App } = { app: "gjs" }) {
+		const results: BuildResult[] = [];
+		if (buildType.library) {
+			results.push(...(await this.buildLibrary()));
+		} else {
+			results.push(...(await this.buildApp(buildType.app)));
+		}
+
+		return results;
+	}
+}