@gjsify/cli 0.1.7 → 0.1.8

package/lib/actions/build.d.ts

@@ -7,6 +7,12 @@ export declare class BuildAction {
     getEsBuildDefaults(): BuildOptions;
     /** Library mode */
     buildLibrary(): Promise<BuildResult<BuildOptions>[]>;
+    /**
+     * 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.
+     */
+    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 } from '@gjsify/esbuild-plugin-gjsify/globals';
 import { dirname, extname } from 'path';
 export class BuildAction {
     configData;
@@ -63,6 +64,23 @@ export class BuildAction {
         }
         return results;
     }
+    /**
+     * 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.
+     */
+    async resolveGlobalsInject(app, globals, verbose) {
+        if (app !== 'gjs' || !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;
@@ -71,17 +89,26 @@ export class BuildAction {
         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 autoGlobalsInject = await this.resolveGlobalsInject(app, globals, verbose);
         const result = await build({
             ...this.getEsBuildDefaults(),
             ...esbuild,
             format,
             plugins: [
-                gjsifyPlugin({ debug: verbose, app, format, exclude, reflection: typescript?.reflection, consoleShim }),
+                gjsifyPlugin({
+                    debug: verbose,
+                    app,
+                    format,
+                    exclude,
+                    reflection: typescript?.reflection,
+                    consoleShim,
+                    autoGlobalsInject,
+                }),
             ]
         });
         // See https://esbuild.github.io/api/#metafile
-        // TODO add cli options for this 
+        // 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));

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 your code needs (e.g. 'fetch,Buffer,process,URL,crypto'). Each identifier is mapped to the corresponding `@gjsify/<pkg>/register` module and injected into the bundle. See the CLI Reference docs for the full list of known identifiers. Only applies to GJS app builds.",
+            type: 'string',
+            normalize: true,
+            default: ''
         });
     },
     handler: async (args) => {

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,47 +24,47 @@ 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()));
         }
@@ -81,8 +81,8 @@ export const showcaseCommand = {
             }
             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/discover-showcases.d.ts

@@ -0,0 +1,19 @@
+export interface ShowcaseInfo {
+    /** Short name, e.g. "three-postprocessing-pixel" */
+    name: string;
+    /** Full npm package name, e.g. "@gjsify/example-dom-three-postprocessing-pixel" */
+    packageName: string;
+    /** Category: "dom" or "node" */
+    category: string;
+    /** Description from showcase's package.json */
+    description: string;
+    /** Absolute path to the GJS bundle (resolved from "main" field) */
+    bundlePath: string;
+}
+/**
+ * Discover all installed showcase packages by scanning the CLI's own dependencies.
+ * Returns showcases sorted by category then name.
+ */
+export declare function discoverShowcases(): ShowcaseInfo[];
+/** Find a single showcase by short name. */
+export declare function findShowcase(name: string): ShowcaseInfo | undefined;

package/lib/utils/{discover-examples.js → discover-showcases.js}

@@ -1,4 +1,4 @@
-// Dynamic discovery of installed @gjsify/example-* packages.
+// Dynamic discovery of installed showcase packages (@gjsify/example-*).
 // Scans the CLI's own package.json dependencies at runtime.
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -6,9 +6,8 @@ import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 const EXAMPLE_PREFIX = '@gjsify/example-';
 /** Extract short name and category from package name. */
-function parseExampleName(packageName) {
-    // @gjsify/example-dom-three-geometry-shapes → category=dom, name=three-geometry-shapes
-    // @gjsify/example-node-cli-node-path → category=node, name=cli-node-path
+function parseShowcaseName(packageName) {
+    // @gjsify/example-dom-three-postprocessing-pixel → category=dom, name=three-postprocessing-pixel
     const suffix = packageName.slice(EXAMPLE_PREFIX.length);
     const dashIdx = suffix.indexOf('-');
     if (dashIdx === -1)
@@ -19,10 +18,10 @@ function parseExampleName(packageName) {
     };
 }
 /**
- * Discover all installed example packages by scanning the CLI's own dependencies.
- * Returns examples sorted by category then name.
+ * Discover all installed showcase packages by scanning the CLI's own dependencies.
+ * Returns showcases sorted by category then name.
  */
-export function discoverExamples() {
+export function discoverShowcases() {
     const require = createRequire(import.meta.url);
     const cliPkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
     let cliPkg;
@@ -35,11 +34,11 @@ export function discoverExamples() {
     const deps = cliPkg['dependencies'];
     if (!deps)
         return [];
-    const examples = [];
+    const showcases = [];
     for (const packageName of Object.keys(deps)) {
         if (!packageName.startsWith(EXAMPLE_PREFIX))
             continue;
-        const parsed = parseExampleName(packageName);
+        const parsed = parseShowcaseName(packageName);
         if (!parsed)
             continue;
         try {
@@ -48,7 +47,7 @@ export function discoverExamples() {
             const main = pkg['main'];
             if (!main)
                 continue;
-            examples.push({
+            showcases.push({
                 name: parsed.name,
                 packageName,
                 category: parsed.category,
@@ -60,10 +59,10 @@ export function discoverExamples() {
             // Package listed as dep but not resolvable — skip silently
         }
     }
-    examples.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
-    return examples;
+    showcases.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+    return showcases;
 }
-/** Find a single example by short name. */
-export function findExample(name) {
-    return discoverExamples().find(e => e.name === name);
+/** Find a single showcase by short name. */
+export function findShowcase(name) {
+    return discoverShowcases().find(e => e.name === name);
 }

package/lib/utils/run-gjs.js

@@ -29,6 +29,15 @@ export async function runGjsBundle(bundlePath, extraArgs = []) {
         ...nativeEnv,
     };
     const gjsArgs = ['-m', bundlePath, ...extraArgs];
+    // Print the exact command being executed so users can copy-paste it to
+    // run gjs directly without the wrapper. Env vars are only shown if we
+    // actually set any (i.e. native gjsify packages were detected).
+    const envPrefix = Object.entries(nativeEnv)
+        .filter(([, value]) => value !== undefined && value !== '')
+        .map(([key, value]) => `${key}=${value}`)
+        .join(' ');
+    const gjsCommand = ['gjs', ...gjsArgs.map(a => a.includes(' ') ? `"${a}"` : a)].join(' ');
+    console.log(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
     const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
     await new Promise((resolvePromise, reject) => {
         child.on('close', (code) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "CLI for Gjsify",
   "type": "module",
   "main": "lib/index.js",
@@ -23,55 +23,14 @@
     "cli"
   ],
   "dependencies": {
-    "@gjsify/esbuild-plugin-gjsify": "^0.1.7",
-    "@gjsify/example-dom-canvas2d-confetti": "^0.1.7",
-    "@gjsify/example-dom-canvas2d-fireworks": "^0.1.7",
-    "@gjsify/example-dom-canvas2d-text": "^0.1.7",
-    "@gjsify/example-dom-iframe-basic": "^0.1.7",
-    "@gjsify/example-dom-three-extrude-shapes": "^0.1.7",
-    "@gjsify/example-dom-three-geometry-cube": "^0.1.7",
-    "@gjsify/example-dom-three-geometry-shapes": "^0.1.7",
-    "@gjsify/example-dom-three-geometry-teapot": "^0.1.7",
-    "@gjsify/example-dom-three-loader-ldraw": "^0.1.7",
-    "@gjsify/example-dom-three-morphtargets": "^0.1.7",
-    "@gjsify/example-dom-three-multiple-rendertargets": "^0.1.7",
-    "@gjsify/example-dom-three-postprocessing-pixel": "^0.1.7",
-    "@gjsify/example-dom-webgl-demo-fade": "^0.1.7",
-    "@gjsify/example-dom-webgl-tutorial-01": "^0.1.7",
-    "@gjsify/example-dom-webgl-tutorial-02": "^0.1.7",
-    "@gjsify/example-dom-webgl-tutorial-03": "^0.1.7",
-    "@gjsify/example-dom-webgl-tutorial-04": "^0.1.7",
-    "@gjsify/example-dom-webgl-tutorial-05": "^0.1.7",
-    "@gjsify/example-dom-webgl-tutorial-06": "^0.1.7",
-    "@gjsify/example-dom-webgl-tutorial-07": "^0.1.7",
-    "@gjsify/example-node-cli-deepkit-di": "^0.1.7",
-    "@gjsify/example-node-cli-deepkit-events": "^0.1.7",
-    "@gjsify/example-node-cli-deepkit-types": "^0.1.7",
-    "@gjsify/example-node-cli-deepkit-validation": "^0.1.7",
-    "@gjsify/example-node-cli-deepkit-workflow": "^0.1.7",
-    "@gjsify/example-node-cli-dns-lookup": "^0.1.7",
-    "@gjsify/example-node-cli-esbuild-plugin-deepkit": "^0.1.7",
-    "@gjsify/example-node-cli-esbuild-plugin-transform-ext": "^0.1.7",
-    "@gjsify/example-node-cli-file-search": "^0.1.7",
-    "@gjsify/example-node-cli-gio-cat": "^0.1.7",
-    "@gjsify/example-node-cli-json-store": "^0.1.7",
-    "@gjsify/example-node-cli-node-buffer": "^0.1.7",
-    "@gjsify/example-node-cli-node-events": "^0.1.7",
-    "@gjsify/example-node-cli-node-fs": "^0.1.7",
-    "@gjsify/example-node-cli-node-os": "^0.1.7",
-    "@gjsify/example-node-cli-node-path": "^0.1.7",
-    "@gjsify/example-node-cli-node-url": "^0.1.7",
-    "@gjsify/example-node-cli-worker-pool": "^0.1.7",
-    "@gjsify/example-node-cli-yargs-demo": "^0.1.7",
-    "@gjsify/example-node-gtk-http-dashboard": "^0.1.7",
-    "@gjsify/example-node-net-express-hello": "^0.1.7",
-    "@gjsify/example-node-net-hono-rest": "^0.1.7",
-    "@gjsify/example-node-net-koa-blog": "^0.1.7",
-    "@gjsify/example-node-net-sse-chat": "^0.1.7",
-    "@gjsify/example-node-net-static-file-server": "^0.1.7",
-    "@gjsify/example-node-net-ws-chat": "^0.1.7",
-    "@gjsify/node-polyfills": "^0.1.7",
-    "@gjsify/web-polyfills": "^0.1.7",
+    "@gjsify/create-app": "^0.1.8",
+    "@gjsify/esbuild-plugin-gjsify": "^0.1.8",
+    "@gjsify/example-dom-canvas2d-fireworks": "^0.1.8",
+    "@gjsify/example-dom-three-geometry-teapot": "^0.1.8",
+    "@gjsify/example-dom-three-postprocessing-pixel": "^0.1.8",
+    "@gjsify/example-node-express-webserver": "^0.1.8",
+    "@gjsify/node-polyfills": "^0.1.8",
+    "@gjsify/web-polyfills": "^0.1.8",
     "cosmiconfig": "^9.0.1",
     "esbuild": "^0.28.0",
     "get-tsconfig": "^4.13.7",

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 } from '@gjsify/esbuild-plugin-gjsify/globals';
 import { dirname, extname } from 'path';
 
 export class BuildAction {
@@ -74,6 +75,30 @@ export class BuildAction {
         return results;
     }
 
+    /**
+     * 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.
+     */
+    private async resolveGlobalsInject(
+        app: App,
+        globals: string | undefined,
+        verbose: boolean | undefined,
+    ): Promise<string | undefined> {
+        if (app !== 'gjs' || !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') {
 
@@ -86,22 +111,31 @@ export class BuildAction {
             esbuild.outfile = esbuild?.format === 'cjs' ? pgk.main || pgk.module : pgk.module || pgk.main;
         }
 
-        const { consoleShim } = this.configData;
+        const { consoleShim, globals } = this.configData;
+        const autoGlobalsInject = await this.resolveGlobalsInject(app, globals, verbose);
+
         const result = await build({
             ...this.getEsBuildDefaults(),
             ...esbuild,
             format,
             plugins: [
-                gjsifyPlugin({debug: verbose, app, format, exclude, reflection: typescript?.reflection, consoleShim}),
+                gjsifyPlugin({
+                    debug: verbose,
+                    app,
+                    format,
+                    exclude,
+                    reflection: typescript?.reflection,
+                    consoleShim,
+                    autoGlobalsInject,
+                }),
             ]
         });
 
         // See https://esbuild.github.io/api/#metafile
-        // TODO add cli options for this 
+        // 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)
         // }

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 your code needs (e.g. 'fetch,Buffer,process,URL,crypto'). Each identifier is mapped to the corresponding `@gjsify/<pkg>/register` module and injected into the bundle. See the CLI Reference docs for the full list of known identifiers. Only applies to GJS app builds.",
+                type: 'string',
+                normalize: true,
+                default: ''
+            })
     },
     handler: async (args) => {
         const config = new Config();

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,54 +32,54 @@ 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()));
         }
@@ -97,8 +97,8 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             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;
+}

package/src/utils/{discover-examples.ts → discover-showcases.ts}

@@ -1,4 +1,4 @@
-// Dynamic discovery of installed @gjsify/example-* packages.
+// Dynamic discovery of installed showcase packages (@gjsify/example-*).
 // Scans the CLI's own package.json dependencies at runtime.
 
 import { readFileSync } from 'node:fs';
@@ -6,14 +6,14 @@ import { dirname, join } from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
-export interface ExampleInfo {
-    /** Short name, e.g. "three-geometry-shapes" */
+export interface ShowcaseInfo {
+    /** Short name, e.g. "three-postprocessing-pixel" */
     name: string;
-    /** Full npm package name, e.g. "@gjsify/example-dom-three-geometry-shapes" */
+    /** Full npm package name, e.g. "@gjsify/example-dom-three-postprocessing-pixel" */
     packageName: string;
     /** Category: "dom" or "node" */
     category: string;
-    /** Description from example's package.json */
+    /** Description from showcase's package.json */
     description: string;
     /** Absolute path to the GJS bundle (resolved from "main" field) */
     bundlePath: string;
@@ -22,9 +22,8 @@ export interface ExampleInfo {
 const EXAMPLE_PREFIX = '@gjsify/example-';
 
 /** Extract short name and category from package name. */
-function parseExampleName(packageName: string): { name: string; category: string } | null {
-    // @gjsify/example-dom-three-geometry-shapes → category=dom, name=three-geometry-shapes
-    // @gjsify/example-node-cli-node-path → category=node, name=cli-node-path
+function parseShowcaseName(packageName: string): { name: string; category: string } | null {
+    // @gjsify/example-dom-three-postprocessing-pixel → category=dom, name=three-postprocessing-pixel
     const suffix = packageName.slice(EXAMPLE_PREFIX.length);
     const dashIdx = suffix.indexOf('-');
     if (dashIdx === -1) return null;
@@ -35,10 +34,10 @@ function parseExampleName(packageName: string): { name: string; category: string
 }
 
 /**
- * Discover all installed example packages by scanning the CLI's own dependencies.
- * Returns examples sorted by category then name.
+ * Discover all installed showcase packages by scanning the CLI's own dependencies.
+ * Returns showcases sorted by category then name.
  */
-export function discoverExamples(): ExampleInfo[] {
+export function discoverShowcases(): ShowcaseInfo[] {
     const require = createRequire(import.meta.url);
     const cliPkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
     let cliPkg: Record<string, unknown>;
@@ -51,12 +50,12 @@ export function discoverExamples(): ExampleInfo[] {
     const deps = cliPkg['dependencies'] as Record<string, string> | undefined;
     if (!deps) return [];
 
-    const examples: ExampleInfo[] = [];
+    const showcases: ShowcaseInfo[] = [];
 
     for (const packageName of Object.keys(deps)) {
         if (!packageName.startsWith(EXAMPLE_PREFIX)) continue;
 
-        const parsed = parseExampleName(packageName);
+        const parsed = parseShowcaseName(packageName);
         if (!parsed) continue;
 
         try {
@@ -65,7 +64,7 @@ export function discoverExamples(): ExampleInfo[] {
             const main = pkg['main'] as string | undefined;
             if (!main) continue;
 
-            examples.push({
+            showcases.push({
                 name: parsed.name,
                 packageName,
                 category: parsed.category,
@@ -77,11 +76,11 @@ export function discoverExamples(): ExampleInfo[] {
         }
     }
 
-    examples.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
-    return examples;
+    showcases.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+    return showcases;
 }
 
-/** Find a single example by short name. */
-export function findExample(name: string): ExampleInfo | undefined {
-    return discoverExamples().find(e => e.name === name);
+/** Find a single showcase by short name. */
+export function findShowcase(name: string): ShowcaseInfo | undefined {
+    return discoverShowcases().find(e => e.name === name);
 }

package/src/utils/run-gjs.ts

@@ -36,6 +36,17 @@ export async function runGjsBundle(bundlePath: string, extraArgs: string[] = [])
     };
 
     const gjsArgs = ['-m', bundlePath, ...extraArgs];
+
+    // Print the exact command being executed so users can copy-paste it to
+    // run gjs directly without the wrapper. Env vars are only shown if we
+    // actually set any (i.e. native gjsify packages were detected).
+    const envPrefix = Object.entries(nativeEnv)
+        .filter(([, value]) => value !== undefined && value !== '')
+        .map(([key, value]) => `${key}=${value}`)
+        .join(' ');
+    const gjsCommand = ['gjs', ...gjsArgs.map(a => a.includes(' ') ? `"${a}"` : a)].join(' ');
+    console.log(`$ ${envPrefix ? `${envPrefix} ` : ''}${gjsCommand}`);
+
     const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
 
     await new Promise<void>((resolvePromise, reject) => {

package/lib/utils/discover-examples.d.ts

@@ -1,19 +0,0 @@
-export interface ExampleInfo {
-    /** Short name, e.g. "three-geometry-shapes" */
-    name: string;
-    /** Full npm package name, e.g. "@gjsify/example-dom-three-geometry-shapes" */
-    packageName: string;
-    /** Category: "dom" or "node" */
-    category: string;
-    /** Description from example's package.json */
-    description: string;
-    /** Absolute path to the GJS bundle (resolved from "main" field) */
-    bundlePath: string;
-}
-/**
- * Discover all installed example packages by scanning the CLI's own dependencies.
- * Returns examples sorted by category then name.
- */
-export declare function discoverExamples(): ExampleInfo[];
-/** Find a single example by short name. */
-export declare function findExample(name: string): ExampleInfo | undefined;