@gjsify/cli 0.1.13 → 0.2.0

package/lib/actions/build.js

@@ -131,7 +131,7 @@ export class BuildAction {
     }
     /** Application mode */
     async buildApp(app = 'gjs') {
-        const { verbose, esbuild, typescript, exclude, library: pgk } = this.configData;
+        const { verbose, esbuild, typescript, exclude, library: pgk, aliases } = 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)) {
@@ -145,6 +145,7 @@ export class BuildAction {
             exclude,
             reflection: typescript?.reflection,
             consoleShim,
+            ...(aliases ? { aliases } : {}),
         };
         const { autoMode, extras } = this.parseGlobalsValue(globals);
         // --- Auto mode (with optional extras): iterative multi-pass build ---

package/lib/commands/build.js

@@ -97,6 +97,26 @@ export const buildCommand = {
             type: 'boolean',
             normalize: true,
             default: false
+        })
+            .option('external', {
+            description: "Module names that should NOT be bundled. Repeat the flag or pass a comma-separated list (e.g. --external typedoc,prettier). Globs are forwarded to esbuild as-is. See https://esbuild.github.io/api/#external",
+            array: true,
+            type: 'string',
+            default: [],
+            coerce: (arg) => arg.flatMap((v) => v.split(',').map((s) => s.trim()).filter(Boolean)),
+        })
+            .option('define', {
+            description: "Substitute compile-time constants. Each entry is KEY=VALUE where VALUE is a JS expression (string literals must be quoted: --define VERSION='\"1.2.3\"'). Repeat the flag or pass comma-separated. See https://esbuild.github.io/api/#define",
+            array: true,
+            type: 'string',
+            default: [],
+        })
+            .option('alias', {
+            description: "Map module specifiers at bundle time. Each entry is FROM=TO (e.g. --alias typedoc=@gjsify/empty). Layered on top of the built-in alias map. Useful for stubbing heavy deps the test scenario never executes.",
+            array: true,
+            type: 'string',
+            default: [],
+            coerce: (arg) => arg.flatMap((v) => v.split(',').map((s) => s.trim()).filter(Boolean)),
         });
     },
     handler: async (args) => {

package/lib/config.js

@@ -75,13 +75,40 @@ export class Config {
             configData.shebang = cliArgs.shebang;
         merge(configData.library ??= {}, pkg, configData.library);
         merge(configData.typescript ??= {}, tsConfig, configData.typescript);
+        // Parse `KEY=VALUE` style flags into Record<string, string>.
+        // - `--define`: VALUE is a JS expression (string literals must be
+        //   pre-quoted by the caller, e.g. `'"1.2.3"'`).
+        // - `--alias`: VALUE is the substitute module specifier.
+        const parseKvPairs = (entries, flag) => {
+            const out = {};
+            for (const entry of entries) {
+                const idx = entry.indexOf('=');
+                if (idx === -1) {
+                    throw new Error(`Invalid --${flag} value '${entry}'. Expected KEY=VALUE.`);
+                }
+                const key = entry.slice(0, idx).trim();
+                const value = entry.slice(idx + 1);
+                if (!key) {
+                    throw new Error(`Invalid --${flag} value '${entry}'. Empty key.`);
+                }
+                out[key] = value;
+            }
+            return out;
+        };
+        const defineMap = parseKvPairs(cliArgs.define ?? [], 'define');
+        const aliasMap = parseKvPairs(cliArgs.alias ?? [], 'alias');
+        if (Object.keys(aliasMap).length) {
+            configData.aliases = { ...(configData.aliases ?? {}), ...aliasMap };
+        }
         merge(configData.esbuild ??= {}, {
             format: cliArgs.format,
             minify: cliArgs.minify,
             entryPoints: cliArgs.entryPoints,
             outfile: cliArgs.outfile,
             outdir: cliArgs.outdir,
-            logLevel: cliArgs.logLevel || 'warning'
+            logLevel: cliArgs.logLevel || 'warning',
+            ...(cliArgs.external?.length ? { external: cliArgs.external } : {}),
+            ...(Object.keys(defineMap).length ? { define: defineMap } : {}),
         });
         if (configData.verbose)
             console.debug("configData", configData);

package/lib/types/cli-build-options.d.ts

@@ -60,4 +60,33 @@ export interface CliBuildOptions {
      * `--outfile`. Default: false.
      */
     shebang?: boolean;
+    /**
+     * Module names that should NOT be bundled. Each name remains as a literal
+     * `import`/`require` in the output and is resolved by the runtime against
+     * its own `node_modules` (or equivalent) at execution time.
+     *
+     * Repeat the flag or pass a comma-separated value:
+     * `--external typedoc,prettier --external typescript`. Glob-style wildcards
+     * (`@inquirer/*`, `lodash-*`) are forwarded as-is to esbuild.
+     *
+     * @see https://esbuild.github.io/api/#external
+     */
+    external?: string[];
+    /**
+     * Substitute compile-time constants in the bundle. Each entry is a
+     * `KEY=VALUE` pair where `VALUE` is an arbitrary JS expression — string
+     * literals must be quoted (`--define VERSION='"1.2.3"'`). Useful for
+     * upstream packages that read a build-time constant via
+     * `typeof __FOO__ !== 'undefined'`.
+     *
+     * @see https://esbuild.github.io/api/#define
+     */
+    define?: string[];
+    /**
+     * Map module specifiers to alternative targets at bundle time. Each entry
+     * is `FROM=TO` where `FROM` is the imported package name and `TO` is the
+     * substitute (typically `@gjsify/empty` to drop a heavy dep that the test
+     * scenario never executes). Layered on top of the built-in alias map.
+     */
+    alias?: string[];
 }

package/lib/types/config-data.d.ts

@@ -22,4 +22,9 @@ export interface ConfigData {
      * Prepend GJS shebang to output and mark executable. See CliBuildOptions.
      */
     shebang?: boolean;
+    /**
+     * Extra module aliases layered on top of the built-in alias map.
+     * Comes from `gjsify build --alias FROM=TO`.
+     */
+    aliases?: Record<string, string>;
 }

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

@@ -5,11 +5,17 @@ export interface NativePackage {
     prebuildsDir: string;
 }
 /**
- * Walk up the directory tree from `startDir` looking for a node_modules directory.
- * Returns all native packages found in the first node_modules encountered.
+ * Walk up the directory tree from `startDir` and merge native packages found
+ * in every `node_modules` encountered.
  *
- * Note: This intentionally stops at the first node_modules to match how Node.js
- * resolves packages from the perspective of the calling project.
+ * We keep walking past the first node_modules because yarn v4 / pnpm hoisting
+ * puts a project's direct deps in a local node_modules (often just `.cache/`
+ * or a subset) while hoisted transitive deps live in a root `node_modules`
+ * higher up. Node's own resolver also walks the chain — returning only the
+ * first hit would miss root-hoisted native packages.
+ *
+ * Deduplication: the first match for a given package name wins (closer
+ * node_modules shadows outer ones), matching Node.js resolution semantics.
  */
 export declare function detectNativePackages(startDir: string): NativePackage[];
 /**

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

@@ -85,27 +85,39 @@ function checkPackage(pkgDir, name, arch) {
     return { name, prebuildsDir };
 }
 /**
- * Walk up the directory tree from `startDir` looking for a node_modules directory.
- * Returns all native packages found in the first node_modules encountered.
+ * Walk up the directory tree from `startDir` and merge native packages found
+ * in every `node_modules` encountered.
  *
- * Note: This intentionally stops at the first node_modules to match how Node.js
- * resolves packages from the perspective of the calling project.
+ * We keep walking past the first node_modules because yarn v4 / pnpm hoisting
+ * puts a project's direct deps in a local node_modules (often just `.cache/`
+ * or a subset) while hoisted transitive deps live in a root `node_modules`
+ * higher up. Node's own resolver also walks the chain — returning only the
+ * first hit would miss root-hoisted native packages.
+ *
+ * Deduplication: the first match for a given package name wins (closer
+ * node_modules shadows outer ones), matching Node.js resolution semantics.
  */
 export function detectNativePackages(startDir) {
     const arch = nodeArchToLinuxArch(process.arch);
+    const merged = [];
+    const seen = new Set();
     let dir = resolve(startDir);
-    // Walk up to filesystem root
     while (true) {
         const nodeModulesDir = join(dir, 'node_modules');
         if (existsSync(nodeModulesDir)) {
-            return scanNodeModules(nodeModulesDir, arch);
+            for (const pkg of scanNodeModules(nodeModulesDir, arch)) {
+                if (seen.has(pkg.name))
+                    continue;
+                seen.add(pkg.name);
+                merged.push(pkg);
+            }
         }
         const parent = resolve(dir, '..');
         if (parent === dir)
             break; // reached filesystem root
         dir = parent;
     }
-    return [];
+    return merged;
 }
 /** Walk up from dir to find the nearest package.json. */
 function findNearestPackageJson(startDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/cli",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "description": "CLI for Gjsify",
   "type": "module",
   "main": "lib/index.js",
@@ -23,24 +23,23 @@
     "cli"
   ],
   "dependencies": {
-    "@gjsify/create-app": "^0.1.13",
-    "@gjsify/esbuild-plugin-gjsify": "^0.1.13",
-    "@gjsify/example-dom-adwaita-package-builder": "^0.1.13",
-    "@gjsify/example-dom-canvas2d-fireworks": "^0.1.13",
-    "@gjsify/example-dom-excalibur-jelly-jumper": "^0.1.13",
-    "@gjsify/example-dom-three-geometry-teapot": "^0.1.13",
-    "@gjsify/example-dom-three-postprocessing-pixel": "^0.1.13",
-    "@gjsify/example-node-express-webserver": "^0.1.13",
-    "@gjsify/node-polyfills": "^0.1.13",
-    "@gjsify/web-polyfills": "^0.1.13",
+    "@gjsify/create-app": "^0.2.0",
+    "@gjsify/esbuild-plugin-gjsify": "^0.2.0",
+    "@gjsify/example-dom-canvas2d-fireworks": "^0.2.0",
+    "@gjsify/example-dom-excalibur-jelly-jumper": "^0.2.0",
+    "@gjsify/example-dom-three-geometry-teapot": "^0.2.0",
+    "@gjsify/example-dom-three-postprocessing-pixel": "^0.2.0",
+    "@gjsify/example-node-express-webserver": "^0.2.0",
+    "@gjsify/node-polyfills": "^0.2.0",
+    "@gjsify/web-polyfills": "^0.2.0",
     "cosmiconfig": "^9.0.1",
     "esbuild": "^0.28.0",
     "get-tsconfig": "^4.14.0",
-    "pkg-types": "^2.3.0",
+    "pkg-types": "^2.3.1",
     "yargs": "^18.0.0"
   },
   "devDependencies": {
     "@types/yargs": "^17.0.35",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }

package/src/actions/build.ts

@@ -149,7 +149,7 @@ export class BuildAction {
     /** Application mode */
     async buildApp(app: App = 'gjs') {
 
-        const { verbose, esbuild, typescript, exclude, library: pgk } = this.configData;
+        const { verbose, esbuild, typescript, exclude, library: pgk, aliases } = this.configData;
 
         const format: 'esm' | 'cjs' = (esbuild?.format as 'esm' | 'cjs') ?? (esbuild?.outfile?.endsWith('.cjs') ? 'cjs' : 'esm');
 
@@ -167,6 +167,7 @@ export class BuildAction {
             exclude,
             reflection: typescript?.reflection,
             consoleShim,
+            ...(aliases ? { aliases } : {}),
         };
 
         const { autoMode, extras } = this.parseGlobalsValue(globals);

package/src/commands/build.ts

@@ -100,6 +100,26 @@ export const buildCommand: Command<any, CliBuildOptions> = {
                 normalize: true,
                 default: false
             })
+            .option('external', {
+                description: "Module names that should NOT be bundled. Repeat the flag or pass a comma-separated list (e.g. --external typedoc,prettier). Globs are forwarded to esbuild as-is. See https://esbuild.github.io/api/#external",
+                array: true,
+                type: 'string',
+                default: [] as string[],
+                coerce: (arg: string[]) => arg.flatMap((v) => v.split(',').map((s) => s.trim()).filter(Boolean)),
+            })
+            .option('define', {
+                description: "Substitute compile-time constants. Each entry is KEY=VALUE where VALUE is a JS expression (string literals must be quoted: --define VERSION='\"1.2.3\"'). Repeat the flag or pass comma-separated. See https://esbuild.github.io/api/#define",
+                array: true,
+                type: 'string',
+                default: [] as string[],
+            })
+            .option('alias', {
+                description: "Map module specifiers at bundle time. Each entry is FROM=TO (e.g. --alias typedoc=@gjsify/empty). Layered on top of the built-in alias map. Useful for stubbing heavy deps the test scenario never executes.",
+                array: true,
+                type: 'string',
+                default: [] as string[],
+                coerce: (arg: string[]) => arg.flatMap((v) => v.split(',').map((s) => s.trim()).filter(Boolean)),
+            })
     },
     handler: async (args) => {
         const config = new Config();

package/src/config.ts

@@ -87,13 +87,42 @@ export class Config {
 
         merge(configData.library ??= {}, pkg, configData.library);
         merge(configData.typescript ??= {}, tsConfig, configData.typescript);
+
+        // Parse `KEY=VALUE` style flags into Record<string, string>.
+        // - `--define`: VALUE is a JS expression (string literals must be
+        //   pre-quoted by the caller, e.g. `'"1.2.3"'`).
+        // - `--alias`: VALUE is the substitute module specifier.
+        const parseKvPairs = (entries: readonly string[], flag: string): Record<string, string> => {
+            const out: Record<string, string> = {};
+            for (const entry of entries) {
+                const idx = entry.indexOf('=');
+                if (idx === -1) {
+                    throw new Error(`Invalid --${flag} value '${entry}'. Expected KEY=VALUE.`);
+                }
+                const key = entry.slice(0, idx).trim();
+                const value = entry.slice(idx + 1);
+                if (!key) {
+                    throw new Error(`Invalid --${flag} value '${entry}'. Empty key.`);
+                }
+                out[key] = value;
+            }
+            return out;
+        };
+        const defineMap = parseKvPairs(cliArgs.define ?? [], 'define');
+        const aliasMap = parseKvPairs(cliArgs.alias ?? [], 'alias');
+        if (Object.keys(aliasMap).length) {
+            configData.aliases = { ...(configData.aliases ?? {}), ...aliasMap };
+        }
+
         merge(configData.esbuild ??= {}, {
             format: cliArgs.format,
             minify: cliArgs.minify,
             entryPoints: cliArgs.entryPoints,
             outfile: cliArgs.outfile,
             outdir: cliArgs.outdir,
-            logLevel: cliArgs.logLevel || 'warning'
+            logLevel: cliArgs.logLevel || 'warning',
+            ...(cliArgs.external?.length ? { external: cliArgs.external } : {}),
+            ...(Object.keys(defineMap).length ? { define: defineMap } : {}),
         });
 
         if(configData.verbose) console.debug("configData", configData);

package/src/types/cli-build-options.ts

@@ -61,4 +61,33 @@ export interface CliBuildOptions {
    * `--outfile`. Default: false.
    */
   shebang?: boolean;
+  /**
+   * Module names that should NOT be bundled. Each name remains as a literal
+   * `import`/`require` in the output and is resolved by the runtime against
+   * its own `node_modules` (or equivalent) at execution time.
+   *
+   * Repeat the flag or pass a comma-separated value:
+   * `--external typedoc,prettier --external typescript`. Glob-style wildcards
+   * (`@inquirer/*`, `lodash-*`) are forwarded as-is to esbuild.
+   *
+   * @see https://esbuild.github.io/api/#external
+   */
+  external?: string[];
+  /**
+   * Substitute compile-time constants in the bundle. Each entry is a
+   * `KEY=VALUE` pair where `VALUE` is an arbitrary JS expression — string
+   * literals must be quoted (`--define VERSION='"1.2.3"'`). Useful for
+   * upstream packages that read a build-time constant via
+   * `typeof __FOO__ !== 'undefined'`.
+   *
+   * @see https://esbuild.github.io/api/#define
+   */
+  define?: string[];
+  /**
+   * Map module specifiers to alternative targets at bundle time. Each entry
+   * is `FROM=TO` where `FROM` is the imported package name and `TO` is the
+   * substitute (typically `@gjsify/empty` to drop a heavy dep that the test
+   * scenario never executes). Layered on top of the built-in alias map.
+   */
+  alias?: string[];
 }

package/src/types/config-data.ts

@@ -23,4 +23,9 @@ export interface ConfigData {
      * Prepend GJS shebang to output and mark executable. See CliBuildOptions.
      */
     shebang?: boolean;
+    /**
+     * Extra module aliases layered on top of the built-in alias map.
+     * Comes from `gjsify build --alias FROM=TO`.
+     */
+    aliases?: Record<string, string>;
 }

package/src/utils/detect-native-packages.ts

@@ -94,28 +94,39 @@ function checkPackage(pkgDir: string, name: string, arch: string): NativePackage
 }
 
 /**
- * Walk up the directory tree from `startDir` looking for a node_modules directory.
- * Returns all native packages found in the first node_modules encountered.
+ * Walk up the directory tree from `startDir` and merge native packages found
+ * in every `node_modules` encountered.
  *
- * Note: This intentionally stops at the first node_modules to match how Node.js
- * resolves packages from the perspective of the calling project.
+ * We keep walking past the first node_modules because yarn v4 / pnpm hoisting
+ * puts a project's direct deps in a local node_modules (often just `.cache/`
+ * or a subset) while hoisted transitive deps live in a root `node_modules`
+ * higher up. Node's own resolver also walks the chain — returning only the
+ * first hit would miss root-hoisted native packages.
+ *
+ * Deduplication: the first match for a given package name wins (closer
+ * node_modules shadows outer ones), matching Node.js resolution semantics.
  */
 export function detectNativePackages(startDir: string): NativePackage[] {
     const arch = nodeArchToLinuxArch(process.arch);
+    const merged: NativePackage[] = [];
+    const seen = new Set<string>();
     let dir = resolve(startDir);
 
-    // Walk up to filesystem root
     while (true) {
         const nodeModulesDir = join(dir, 'node_modules');
         if (existsSync(nodeModulesDir)) {
-            return scanNodeModules(nodeModulesDir, arch);
+            for (const pkg of scanNodeModules(nodeModulesDir, arch)) {
+                if (seen.has(pkg.name)) continue;
+                seen.add(pkg.name);
+                merged.push(pkg);
+            }
         }
         const parent = resolve(dir, '..');
         if (parent === dir) break; // reached filesystem root
         dir = parent;
     }
 
-    return [];
+    return merged;
 }
 
 /** Walk up from dir to find the nearest package.json. */