@gjsify/cli 0.1.7 → 0.1.9

package/lib/actions/build.d.ts

@@ -7,6 +7,25 @@ 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 */
     buildApp(app?: App): Promise<BuildResult<{
         format: "esm" | "cjs";

package/lib/actions/build.js

@@ -1,5 +1,6 @@
 import { build } 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 {
     configData;
@@ -63,31 +64,99 @@ 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')
+            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 = '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 } = 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];
     }
     async start(buildType = { app: 'gjs' }) {

package/lib/commands/build.js

@@ -85,6 +85,12 @@ export const buildCommand = {
             type: 'boolean',
             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) => {

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/create.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from '../types/index.js';
+interface CreateOptions {
+    'project-name': string;
+}
+export declare const createCommand: Command<any, CreateOptions>;
+export {};

package/lib/commands/create.js

@@ -0,0 +1,15 @@
+import { createProject } from '@gjsify/create-app';
+export const createCommand = {
+    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/lib/commands/index.d.ts

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

package/lib/commands/index.js

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

package/lib/commands/showcase.js

@@ -1,13 +1,13 @@
-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';
 export const showcaseCommand = {
     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', {
@@ -16,7 +16,7 @@ export const showcaseCommand = {
             default: false,
         })
             .option('list', {
-            description: 'List available examples',
+            description: 'List available showcases',
             type: 'boolean',
             default: false,
         });
@@ -24,65 +24,67 @@ export const showcaseCommand = {
     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();
-            for (const ex of examples) {
-                const list = grouped.get(ex.category) ?? [];
-                list.push(ex);
-                grouped.set(ex.category, list);
+            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/lib/config.js

@@ -69,6 +69,8 @@ export class Config {
         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);
         merge(configData.esbuild ??= {}, {

package/lib/index.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 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/lib/types/cli-build-options.d.ts

@@ -47,4 +47,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/lib/types/config-data.d.ts

@@ -13,4 +13,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;
 }

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.