@gjsify/cli 0.1.7 → 0.1.9

package/src/actions/build.ts

@@ -2,6 +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, detectAutoGlobals } from '@gjsify/esbuild-plugin-gjsify/globals';
 import { dirname, extname } from 'path';
 
 export class BuildAction {
@@ -74,6 +75,54 @@ 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,
+        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;
+    }
+
     /** Application mode */
     async buildApp(app: App = 'gjs') {
 
@@ -81,31 +130,68 @@ 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 } = this.configData;
+        const { consoleShim, globals } = this.configData;
+
+        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}),
+                gjsifyPlugin({
+                    ...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

@@ -88,6 +88,12 @@ export const buildCommand: Command<any, CliBuildOptions> = {
                 normalize: true,
                 default: true
             })
+            .option('globals', {
+                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: 'auto'
+            })
     },
     handler: async (args) => {
         const config = new Config();

package/src/commands/check.ts

@@ -7,7 +7,7 @@ interface CheckOptions {
 
 export const checkCommand: Command<any, CheckOptions> = {
     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', {
@@ -19,36 +19,69 @@ export const checkCommand: Command<any, CheckOptions> = {
     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/src/commands/create.ts

@@ -0,0 +1,21 @@
+import { createProject } from '@gjsify/create-app';
+import type { Command } from '../types/index.js';
+
+interface CreateOptions {
+    'project-name': string;
+}
+
+export const createCommand: Command<any, CreateOptions> = {
+    command: 'create [project-name]',
+    description: 'Scaffold a new Gjsify project in a new directory.',
+    builder: (yargs) => {
+        return yargs.positional('project-name', {
+            describe: 'Name of the project directory to create',
+            type: 'string',
+            default: 'my-gjs-app',
+        });
+    },
+    handler: async (args) => {
+        await createProject(args['project-name']);
+    },
+};

package/src/commands/index.ts

@@ -2,4 +2,5 @@ export * from './build.js';
 export * from './run.js';
 export * from './info.js';
 export * from './check.js';
-export * from './showcase.js';
+export * from './showcase.js';
+export * from './create.js';

package/src/commands/showcase.ts

@@ -1,5 +1,5 @@
 import type { Command } from '../types/index.js';
-import { discoverExamples, findExample } from '../utils/discover-examples.js';
+import { discoverShowcases, findShowcase } from '../utils/discover-showcases.js';
 import { runMinimalChecks, checkGwebgl, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
 import { runGjsBundle } from '../utils/run-gjs.js';
 
@@ -11,11 +11,11 @@ interface ShowcaseOptions {
 
 export const showcaseCommand: Command<any, ShowcaseOptions> = {
     command: 'showcase [name]',
-    description: 'List or run built-in gjsify example applications.',
+    description: 'List or run built-in gjsify showcase applications.',
     builder: (yargs) => {
         return yargs
             .positional('name', {
-                description: 'Example name to run (omit to list all)',
+                description: 'Showcase name to run (omit to list all)',
                 type: 'string',
             })
             .option('json', {
@@ -24,7 +24,7 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
                 default: false,
             })
             .option('list', {
-                description: 'List available examples',
+                description: 'List available showcases',
                 type: 'boolean',
                 default: false,
             });
@@ -32,73 +32,75 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
     handler: async (args) => {
         // List mode: no name given, or --list flag
         if (!args.name || args.list) {
-            const examples = discoverExamples();
+            const showcases = discoverShowcases();
 
             if (args.json) {
-                console.log(JSON.stringify(examples, null, 2));
+                console.log(JSON.stringify(showcases, null, 2));
                 return;
             }
 
-            if (examples.length === 0) {
-                console.log('No examples found. Example packages may not be installed.');
+            if (showcases.length === 0) {
+                console.log('No showcases found. Showcase packages may not be installed.');
                 return;
             }
 
             // Group by category
-            const grouped = new Map<string, typeof examples>();
-            for (const ex of examples) {
-                const list = grouped.get(ex.category) ?? [];
-                list.push(ex);
-                grouped.set(ex.category, list);
+            const grouped = new Map<string, typeof showcases>();
+            for (const sc of showcases) {
+                const list = grouped.get(sc.category) ?? [];
+                list.push(sc);
+                grouped.set(sc.category, list);
             }
 
-            console.log('Available gjsify examples:\n');
+            console.log('Available gjsify showcases:\n');
             for (const [category, list] of grouped) {
                 console.log(`  ${category.toUpperCase()}:`);
                 const maxNameLen = Math.max(...list.map(e => e.name.length));
-                for (const ex of list) {
-                    const pad = ' '.repeat(maxNameLen - ex.name.length + 2);
-                    const desc = ex.description ? `${pad}${ex.description}` : '';
-                    console.log(`    ${ex.name}${desc}`);
+                for (const sc of list) {
+                    const pad = ' '.repeat(maxNameLen - sc.name.length + 2);
+                    const desc = sc.description ? `${pad}${sc.description}` : '';
+                    console.log(`    ${sc.name}${desc}`);
                 }
                 console.log('');
             }
 
-            console.log('Run an example:  gjsify showcase <name>');
+            console.log('Run a showcase:  gjsify showcase <name>');
             return;
         }
 
-        // Run mode: find the example
-        const example = findExample(args.name);
-        if (!example) {
-            console.error(`Unknown example: "${args.name}"`);
-            console.error('Run "gjsify showcase" to list available examples.');
+        // Run mode: find the showcase
+        const showcase = findShowcase(args.name);
+        if (!showcase) {
+            console.error(`Unknown showcase: "${args.name}"`);
+            console.error('Run "gjsify showcase" to list available showcases.');
             process.exit(1);
         }
 
-        // System dependency check before running — only check what this example needs.
-        // All examples need GJS; WebGL examples additionally need gwebgl prebuilds.
+        // System dependency check before running — only check what this showcase needs.
+        // All showcases need GJS; WebGL showcases additionally need gwebgl prebuilds.
         const results = runMinimalChecks();
-        const needsWebgl = example.packageName.includes('webgl') || example.packageName.includes('three');
+        const needsWebgl = showcase.packageName.includes('webgl') || showcase.packageName.includes('three');
         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}`);
             }
             process.exit(1);
         }
 
-        // Run the example via shared GJS runner
-        console.log(`Running example: ${example.name}\n`);
-        await runGjsBundle(example.bundlePath);
+        // Run the showcase via shared GJS runner
+        console.log(`Running showcase: ${showcase.name}\n`);
+        await runGjsBundle(showcase.bundlePath);
     },
 };

package/src/config.ts

@@ -82,6 +82,7 @@ export class Config {
         configData.verbose = cliArgs.verbose || false;
         configData.exclude = cliArgs.exclude || [];
         if (cliArgs.consoleShim !== undefined) configData.consoleShim = cliArgs.consoleShim;
+        if (cliArgs.globals !== undefined) configData.globals = cliArgs.globals;
 
         merge(configData.library ??= {}, pkg, configData.library);
         merge(configData.typescript ??= {}, tsConfig, configData.typescript);

package/src/index.ts

@@ -2,13 +2,14 @@
 import yargs from 'yargs'
 import { hideBin } from 'yargs/helpers'
 
-import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase } from './commands/index.js'
+import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create } from './commands/index.js'
 import { APP_NAME } from './constants.js'
 
 void yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
     .strict()
     // .usage(Config.usage)
+    .command(create.command, create.description, create.builder, create.handler)
     .command(build.command, build.description, build.builder, build.handler)
     .command(run.command, run.description, run.builder, run.handler)
     .command(info.command, info.description, info.builder, info.handler)

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

@@ -48,4 +48,11 @@ export interface CliBuildOptions {
    * Use --no-console-shim to disable. Only applies to GJS app builds. Default: true.
    */
   consoleShim?: boolean;
-}
+  /**
+   * 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. Only applies to GJS app builds.
+   */
+  globals?: string;
+}

package/src/types/config-data.ts

@@ -14,4 +14,9 @@ export interface ConfigData {
      * Only applies to GJS app builds. Default: true.
      */
     consoleShim?: boolean;
-}
+    /**
+     * Comma-separated list of global identifiers to register in the bundle.
+     * See CliBuildOptions for format.
+     */
+    globals?: string;
+}