@gjsify/cli 0.3.5 → 0.3.6

package/lib/actions/build.js

@@ -60,10 +60,16 @@ async function getPnpPlugin() {
         }
         let pnpApi = null;
         try {
-            // pnpapi has no npm package — it is a virtual module injected by Yarn PnP
+            // pnpapi has no npm package — it is a virtual CJS module injected by
+            // Yarn PnP. `await import()` of a CJS module yields the ESM namespace
+            // `{ default, "module.exports" }`, NOT the exports object — so
+            // `mod.resolveRequest` is `undefined`. Unwrap `.default` (the CJS
+            // exports) before use, falling back to the namespace itself for ESM
+            // builds of pnpapi (none today, but defensive).
             // eslint-disable-next-line @typescript-eslint/ban-ts-comment
             // @ts-expect-error
-            pnpApi = (await import("pnpapi"));
+            const mod = await import("pnpapi");
+            pnpApi = (mod.default ?? mod);
         }
         catch {
             // Not in a PnP runtime (shouldn't happen since findPnpRoot passed)

package/lib/commands/index.d.ts

@@ -7,3 +7,4 @@ export * from './create.js';
 export * from './gresource.js';
 export * from './gettext.js';
 export * from './dlx.js';
+export * from './install.js';

package/lib/commands/index.js

@@ -7,3 +7,4 @@ export * from './create.js';
 export * from './gresource.js';
 export * from './gettext.js';
 export * from './dlx.js';
+export * from './install.js';

package/lib/commands/install.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from '../types/index.js';
+interface InstallOptions {
+    packages?: string[];
+    'save-dev'?: boolean;
+    'save-peer'?: boolean;
+    'save-optional'?: boolean;
+    verbose: boolean;
+}
+export declare const installCommand: Command<any, InstallOptions>;
+export {};

package/lib/commands/install.js

@@ -0,0 +1,99 @@
+// `gjsify install [pkg...]` — thin npm wrapper with gjsify-aware post-checks.
+//
+// The actual install is delegated to `npm install` in the user's project root
+// (no `--prefix` rewrite, unlike `gjsify dlx`). After install completes we run
+// `runMinimalChecks()` so missing system deps (gjs, gtk4, libsoup, ...) surface
+// immediately, and report any installed `@gjsify/*` packages that ship native
+// prebuilds so users know they can use `gjsify run` to wire `LD_LIBRARY_PATH` /
+// `GI_TYPELIB_PATH` automatically.
+//
+// Modes:
+//   gjsify install                    → project install (npm install)
+//   gjsify install <pkg> [<pkg>...]   → add package(s) (npm install <pkg>...)
+import { spawn } from 'node:child_process';
+import { buildInstallCommand, detectPackageManager, runMinimalChecks, } from '../utils/check-system-deps.js';
+import { detectNativePackages } from '../utils/detect-native-packages.js';
+export const installCommand = {
+    command: 'install [packages..]',
+    description: 'Install npm dependencies in the current project, then run gjsify-aware post-checks.',
+    builder: (yargs) => yargs
+        .positional('packages', {
+        description: 'Optional package specs. With none, runs a full project install.',
+        type: 'string',
+        array: true,
+    })
+        .option('save-dev', { type: 'boolean', alias: 'D' })
+        .option('save-peer', { type: 'boolean' })
+        .option('save-optional', { type: 'boolean', alias: 'O' })
+        .option('verbose', {
+        description: 'Verbose npm logging.',
+        type: 'boolean',
+        default: false,
+    }),
+    handler: async (args) => {
+        const npmArgs = ['install'];
+        if (args['save-dev'])
+            npmArgs.push('--save-dev');
+        if (args['save-peer'])
+            npmArgs.push('--save-peer');
+        if (args['save-optional'])
+            npmArgs.push('--save-optional');
+        if (args.verbose)
+            npmArgs.push('--loglevel', 'verbose');
+        if (args.packages && args.packages.length > 0) {
+            npmArgs.push(...args.packages);
+        }
+        await spawnNpm(npmArgs);
+        await runPostInstallChecks();
+    },
+};
+async function spawnNpm(npmArgs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('npm', npmArgs, { stdio: 'inherit' });
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`npm install exited with code ${code}`));
+        });
+        child.on('error', (err) => {
+            const code = err.code;
+            const msg = code === 'ENOENT'
+                ? 'npm not found on PATH — install Node.js first.'
+                : `npm install failed: ${err.message}`;
+            reject(new Error(msg));
+        });
+    }).catch((err) => {
+        console.error(err.message);
+        process.exit(1);
+    });
+}
+async function runPostInstallChecks() {
+    console.log('\n--- gjsify post-install checks ---');
+    // 1. System deps that GJS apps typically need.
+    const results = runMinimalChecks();
+    const missing = results.filter((r) => !r.found && r.severity === 'required');
+    if (missing.length > 0) {
+        console.warn('Missing required system dependencies:\n');
+        for (const dep of missing) {
+            console.warn(`  ✗  ${dep.name}`);
+        }
+        const pm = detectPackageManager();
+        const cmd = buildInstallCommand(pm, missing);
+        if (cmd)
+            console.warn(`\nInstall with:\n  ${cmd}`);
+    }
+    else {
+        console.log('System dependencies OK.');
+    }
+    // 2. Surface @gjsify/* packages with native prebuilds — `gjsify run`
+    //    will set LD_LIBRARY_PATH / GI_TYPELIB_PATH for these automatically.
+    const native = detectNativePackages(process.cwd());
+    if (native.length > 0) {
+        console.log(`\nDetected ${native.length} @gjsify/* package(s) with native prebuilds:`);
+        for (const pkg of native) {
+            console.log(`  • ${pkg.name}`);
+        }
+        console.log('\nUse `gjsify run <bundle>` to launch with LD_LIBRARY_PATH/GI_TYPELIB_PATH set.');
+    }
+}

package/lib/commands/showcase.js

@@ -1,26 +1,25 @@
 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';
+import { runMinimalChecks, checkGwebgl, detectPackageManager, buildInstallCommand, } from '../utils/check-system-deps.js';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 export const showcaseCommand = {
     command: 'showcase [name]',
-    description: 'List or run built-in gjsify showcase applications.',
-    builder: (yargs) => {
-        return yargs
-            .positional('name', {
-            description: 'Showcase name to run (omit to list all)',
-            type: 'string',
-        })
-            .option('json', {
-            description: 'Output as JSON',
-            type: 'boolean',
-            default: false,
-        })
-            .option('list', {
-            description: 'List available showcases',
-            type: 'boolean',
-            default: false,
-        });
-    },
+    description: 'List or run curated gjsify showcase applications.',
+    builder: (yargs) => yargs
+        .positional('name', {
+        description: 'Showcase name to run (omit to list all)',
+        type: 'string',
+    })
+        .option('json', {
+        description: 'Output as JSON',
+        type: 'boolean',
+        default: false,
+    })
+        .option('list', {
+        description: 'List available showcases',
+        type: 'boolean',
+        default: false,
+    }),
     handler: async (args) => {
         // List mode: no name given, or --list flag
         if (!args.name || args.list) {
@@ -30,10 +29,9 @@ export const showcaseCommand = {
                 return;
             }
             if (showcases.length === 0) {
-                console.log('No showcases found. Showcase packages may not be installed.');
+                console.log('No showcases found. The CLI ships a curated list in `showcases.json`; if it is missing the CLI install is incomplete.');
                 return;
             }
-            // Group by category
             const grouped = new Map();
             for (const sc of showcases) {
                 const list = grouped.get(sc.category) ?? [];
@@ -43,7 +41,7 @@ export const showcaseCommand = {
             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));
+                const maxNameLen = Math.max(...list.map((e) => e.name.length));
                 for (const sc of list) {
                     const pad = ' '.repeat(maxNameLen - sc.name.length + 2);
                     const desc = sc.description ? `${pad}${sc.description}` : '';
@@ -54,23 +52,18 @@ export const showcaseCommand = {
             console.log('Run a showcase:  gjsify showcase <name>');
             return;
         }
-        // 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 showcase needs.
-        // All showcases need GJS; WebGL showcases additionally need gwebgl prebuilds.
+        // System dependency check before delegating — only what this showcase needs.
         const results = runMinimalChecks();
-        const needsWebgl = showcase.packageName.includes('webgl') || showcase.packageName.includes('three');
-        if (needsWebgl) {
+        if (showcase.needsWebgl) {
             results.push(checkGwebgl(process.cwd()));
         }
-        // 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'));
+        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 missingHard) {
@@ -83,8 +76,27 @@ export const showcaseCommand = {
             }
             process.exit(1);
         }
-        // Run the showcase via shared GJS runner
-        console.log(`Running showcase: ${showcase.name}\n`);
-        await runGjsBundle(showcase.bundlePath);
+        // Delegate to `gjsify dlx <package>` — same npm-cache, same atomic
+        // symlink-swap, same `gjsify.main` resolution. Re-spawning the CLI
+        // keeps the dlx logic in one place.
+        console.log(`Running showcase: ${showcase.name} (via gjsify dlx)\n`);
+        const cliBin = fileURLToPath(new URL('../index.js', import.meta.url));
+        const child = spawn(process.execPath, [cliBin, 'dlx', showcase.packageName], {
+            stdio: 'inherit',
+        });
+        await new Promise((resolvePromise, reject) => {
+            child.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`gjsify dlx exited with code ${code}`));
+                }
+                else {
+                    resolvePromise();
+                }
+            });
+            child.on('error', reject);
+        }).catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
     },
 };

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, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, dlxCommand as dlx, } from './commands/index.js';
+import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, dlxCommand as dlx, installCommand as install, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 void yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
     .strict()
     .command(create.command, create.description, create.builder, create.handler)
+    .command(install.command, install.description, install.builder, install.handler)
     .command(build.command, build.description, build.builder, build.handler)
     .command(run.command, run.description, run.builder, run.handler)
     .command(dlx.command, dlx.description, dlx.builder, dlx.handler)

package/lib/utils/check-system-deps.js

@@ -96,8 +96,13 @@ const PACKAGE_DEPS = {
     '@gjsify/canvas2d': ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
     '@gjsify/canvas2d-core': ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
     '@gjsify/dom-elements': ['gdk-pixbuf'],
-    // @gjsify/webgl, @gjsify/event-bridge only need gtk4/gdk which are
-    // already in the required set, so they don't need optional entries.
+    // @gjsify/webgl needs the gwebgl npm package (Vala prebuild) — handled
+    // as a special-case checkNpmPackage rather than checkPkgConfig in
+    // runOptionalChecks. Mapping it here so its presence in the project's
+    // dep tree triggers the check.
+    '@gjsify/webgl': ['gwebgl'],
+    // @gjsify/event-bridge only needs gtk4/gdk which are already in the
+    // required set, so it doesn't need an optional entry.
 };
 /** Walk up from cwd looking for the nearest package.json. */
 function findProjectRoot(cwd) {
@@ -241,10 +246,16 @@ function runOptionalChecks(needed, cwd) {
             .map(([pkg]) => pkg);
         results.push(checkPkgConfig(dep.id, dep.name, dep.pkgName, 'optional', requiredBy));
     }
-    // gwebgl npm package — special case (not a pkg-config lib).
-    // Always reported (the npm package is bundled with the CLI), but marked
-    // optional because only @gjsify/webgl users need it.
-    results.push(checkGwebgl(cwd));
+    // gwebgl npm package — special case (not a pkg-config lib). Only checked
+    // when the project directly or transitively depends on @gjsify/webgl —
+    // since the CLI tarball no longer ships any showcase example packages,
+    // gwebgl is not part of the CLI's own dep tree, so reporting it for every
+    // project would always be `found: false`. `needed === null` means "check
+    // everything" (no project context).
+    const hasWebglDep = needed === null || needed.has('gwebgl');
+    if (hasWebglDep) {
+        results.push(checkGwebgl(cwd));
+    }
     return results;
 }
 // Per-package-manager install package names, keyed by dep id.

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

@@ -5,14 +5,15 @@ export interface ShowcaseInfo {
     packageName: string;
     /** Category: "dom" or "node" */
     category: string;
-    /** Description from showcase's package.json */
+    /** Description for the list view */
     description: string;
-    /** Absolute path to the GJS bundle (resolved from "main" field) */
-    bundlePath: string;
+    /** Whether the showcase needs the gwebgl native prebuild. */
+    needsWebgl: boolean;
 }
 /**
- * Discover all installed showcase packages by scanning the CLI's own dependencies.
- * Returns showcases sorted by category then name.
+ * Read the curated showcase list from `showcases.json`. Returns showcases
+ * sorted by category then name. An empty list (or missing manifest) yields
+ * an empty array — `gjsify showcase` then prints the empty-state message.
  */
 export declare function discoverShowcases(): ShowcaseInfo[];
 /** Find a single showcase by short name. */

package/lib/utils/discover-showcases.js

@@ -1,68 +1,46 @@
-// Dynamic discovery of installed showcase packages (@gjsify/example-*).
-// Scans the CLI's own package.json dependencies at runtime.
-import { readFileSync } from 'node:fs';
+// Static discovery of showcase packages from `showcases.json`.
+//
+// Earlier versions read showcases from the CLI's own `package.json#dependencies`
+// — every showcase had to be a direct CLI dependency. That made the CLI tarball
+// blow up with each new showcase and required a CLI rebuild to publish a new
+// one. Static manifest decouples both: the CLI reads the manifest at runtime,
+// `gjsify showcase <name>` delegates to `gjsify dlx <package>`.
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
-const EXAMPLE_PREFIX = '@gjsify/example-';
-/** Extract short name and category from package name. */
-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)
-        return null;
-    return {
-        category: suffix.slice(0, dashIdx),
-        name: suffix.slice(dashIdx + 1),
-    };
+function manifestPath() {
+    // `showcases.json` lives at the package root: ../../showcases.json from lib/utils/.
+    return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'showcases.json');
 }
 /**
- * Discover all installed showcase packages by scanning the CLI's own dependencies.
- * Returns showcases sorted by category then name.
+ * Read the curated showcase list from `showcases.json`. Returns showcases
+ * sorted by category then name. An empty list (or missing manifest) yields
+ * an empty array — `gjsify showcase` then prints the empty-state message.
  */
 export function discoverShowcases() {
-    const require = createRequire(import.meta.url);
-    const cliPkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
-    let cliPkg;
+    const path = manifestPath();
+    if (!existsSync(path))
+        return [];
+    let manifest;
     try {
-        cliPkg = JSON.parse(readFileSync(cliPkgPath, 'utf-8'));
+        manifest = JSON.parse(readFileSync(path, 'utf-8'));
     }
     catch {
         return [];
     }
-    const deps = cliPkg['dependencies'];
-    if (!deps)
+    if (!Array.isArray(manifest.showcases))
         return [];
-    const showcases = [];
-    for (const packageName of Object.keys(deps)) {
-        if (!packageName.startsWith(EXAMPLE_PREFIX))
-            continue;
-        const parsed = parseShowcaseName(packageName);
-        if (!parsed)
-            continue;
-        try {
-            const pkgJsonPath = require.resolve(`${packageName}/package.json`);
-            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
-            const main = pkg['main'];
-            if (!main)
-                continue;
-            showcases.push({
-                name: parsed.name,
-                packageName,
-                category: parsed.category,
-                description: pkg['description'] ?? '',
-                bundlePath: join(dirname(pkgJsonPath), main),
-            });
-        }
-        catch {
-            // Package listed as dep but not resolvable — skip silently
-        }
-    }
+    const showcases = manifest.showcases.map((e) => ({
+        name: e.name,
+        packageName: e.package,
+        category: e.category,
+        description: e.description ?? '',
+        needsWebgl: Boolean(e.needsWebgl),
+    }));
     showcases.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
     return showcases;
 }
 /** Find a single showcase by short name. */
 export function findShowcase(name) {
-    return discoverShowcases().find(e => e.name === name);
+    return discoverShowcases().find((e) => e.name === name);
 }

package/package.json

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

package/showcases.json

@@ -0,0 +1,40 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "showcases": [
+        {
+            "name": "canvas2d-fireworks",
+            "category": "dom",
+            "package": "@gjsify/example-dom-canvas2d-fireworks",
+            "description": "Colorful fireworks Canvas 2D example with Adwaita controls",
+            "needsWebgl": false
+        },
+        {
+            "name": "excalibur-jelly-jumper",
+            "category": "dom",
+            "package": "@gjsify/example-dom-excalibur-jelly-jumper",
+            "description": "Excalibur.js jelly-jumper game",
+            "needsWebgl": false
+        },
+        {
+            "name": "three-geometry-teapot",
+            "category": "dom",
+            "package": "@gjsify/example-dom-three-geometry-teapot",
+            "description": "Three.js Utah teapot",
+            "needsWebgl": true
+        },
+        {
+            "name": "three-postprocessing-pixel",
+            "category": "dom",
+            "package": "@gjsify/example-dom-three-postprocessing-pixel",
+            "description": "Three.js postprocessing pixel demo",
+            "needsWebgl": true
+        },
+        {
+            "name": "express-webserver",
+            "category": "node",
+            "package": "@gjsify/example-node-express-webserver",
+            "description": "Express web server on GJS via @gjsify/http",
+            "needsWebgl": false
+        }
+    ]
+}

package/src/actions/build.ts

@@ -72,10 +72,16 @@ async function getPnpPlugin(): Promise<Plugin | null> {
 		};
 		let pnpApi: PnpApi | null = null;
 		try {
-			// pnpapi has no npm package — it is a virtual module injected by Yarn PnP
+			// pnpapi has no npm package — it is a virtual CJS module injected by
+			// Yarn PnP. `await import()` of a CJS module yields the ESM namespace
+			// `{ default, "module.exports" }`, NOT the exports object — so
+			// `mod.resolveRequest` is `undefined`. Unwrap `.default` (the CJS
+			// exports) before use, falling back to the namespace itself for ESM
+			// builds of pnpapi (none today, but defensive).
 			// eslint-disable-next-line @typescript-eslint/ban-ts-comment
 			// @ts-expect-error
-			pnpApi = (await import("pnpapi")) as PnpApi;
+			const mod = await import("pnpapi");
+			pnpApi = ((mod as { default?: PnpApi }).default ?? mod) as PnpApi;
 		} catch {
 			// Not in a PnP runtime (shouldn't happen since findPnpRoot passed)
 		}

package/src/commands/index.ts

@@ -6,4 +6,5 @@ export * from './showcase.js';
 export * from './create.js';
 export * from './gresource.js';
 export * from './gettext.js';
-export * from './dlx.js';
+export * from './dlx.js';
+export * from './install.js';

package/src/commands/install.ts

@@ -0,0 +1,116 @@
+// `gjsify install [pkg...]` — thin npm wrapper with gjsify-aware post-checks.
+//
+// The actual install is delegated to `npm install` in the user's project root
+// (no `--prefix` rewrite, unlike `gjsify dlx`). After install completes we run
+// `runMinimalChecks()` so missing system deps (gjs, gtk4, libsoup, ...) surface
+// immediately, and report any installed `@gjsify/*` packages that ship native
+// prebuilds so users know they can use `gjsify run` to wire `LD_LIBRARY_PATH` /
+// `GI_TYPELIB_PATH` automatically.
+//
+// Modes:
+//   gjsify install                    → project install (npm install)
+//   gjsify install <pkg> [<pkg>...]   → add package(s) (npm install <pkg>...)
+
+import { spawn } from 'node:child_process';
+import type { Command } from '../types/index.js';
+import {
+    buildInstallCommand,
+    detectPackageManager,
+    runMinimalChecks,
+} from '../utils/check-system-deps.js';
+import { detectNativePackages } from '../utils/detect-native-packages.js';
+
+interface InstallOptions {
+    packages?: string[];
+    'save-dev'?: boolean;
+    'save-peer'?: boolean;
+    'save-optional'?: boolean;
+    verbose: boolean;
+}
+
+export const installCommand: Command<any, InstallOptions> = {
+    command: 'install [packages..]',
+    description:
+        'Install npm dependencies in the current project, then run gjsify-aware post-checks.',
+    builder: (yargs) =>
+        yargs
+            .positional('packages', {
+                description: 'Optional package specs. With none, runs a full project install.',
+                type: 'string',
+                array: true,
+            })
+            .option('save-dev', { type: 'boolean', alias: 'D' })
+            .option('save-peer', { type: 'boolean' })
+            .option('save-optional', { type: 'boolean', alias: 'O' })
+            .option('verbose', {
+                description: 'Verbose npm logging.',
+                type: 'boolean',
+                default: false,
+            }),
+    handler: async (args) => {
+        const npmArgs = ['install'];
+        if (args['save-dev']) npmArgs.push('--save-dev');
+        if (args['save-peer']) npmArgs.push('--save-peer');
+        if (args['save-optional']) npmArgs.push('--save-optional');
+        if (args.verbose) npmArgs.push('--loglevel', 'verbose');
+        if (args.packages && args.packages.length > 0) {
+            npmArgs.push(...args.packages);
+        }
+
+        await spawnNpm(npmArgs);
+
+        await runPostInstallChecks();
+    },
+};
+
+async function spawnNpm(npmArgs: string[]): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+        const child = spawn('npm', npmArgs, { stdio: 'inherit' });
+        child.on('close', (code) => {
+            if (code === 0) resolve();
+            else reject(new Error(`npm install exited with code ${code}`));
+        });
+        child.on('error', (err) => {
+            const code = (err as NodeJS.ErrnoException).code;
+            const msg = code === 'ENOENT'
+                ? 'npm not found on PATH — install Node.js first.'
+                : `npm install failed: ${err.message}`;
+            reject(new Error(msg));
+        });
+    }).catch((err: Error) => {
+        console.error(err.message);
+        process.exit(1);
+    });
+}
+
+async function runPostInstallChecks(): Promise<void> {
+    console.log('\n--- gjsify post-install checks ---');
+
+    // 1. System deps that GJS apps typically need.
+    const results = runMinimalChecks();
+    const missing = results.filter((r) => !r.found && r.severity === 'required');
+    if (missing.length > 0) {
+        console.warn('Missing required system dependencies:\n');
+        for (const dep of missing) {
+            console.warn(`  ✗  ${dep.name}`);
+        }
+        const pm = detectPackageManager();
+        const cmd = buildInstallCommand(pm, missing);
+        if (cmd) console.warn(`\nInstall with:\n  ${cmd}`);
+    } else {
+        console.log('System dependencies OK.');
+    }
+
+    // 2. Surface @gjsify/* packages with native prebuilds — `gjsify run`
+    //    will set LD_LIBRARY_PATH / GI_TYPELIB_PATH for these automatically.
+    const native = detectNativePackages(process.cwd());
+    if (native.length > 0) {
+        console.log(
+            `\nDetected ${native.length} @gjsify/* package(s) with native prebuilds:`,
+        );
+        for (const pkg of native) {
+            console.log(`  • ${pkg.name}`);
+        }
+        console.log('\nUse `gjsify run <bundle>` to launch with LD_LIBRARY_PATH/GI_TYPELIB_PATH set.');
+    }
+}

package/src/commands/showcase.ts

@@ -1,7 +1,13 @@
 import type { Command } from '../types/index.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';
+import {
+    runMinimalChecks,
+    checkGwebgl,
+    detectPackageManager,
+    buildInstallCommand,
+} from '../utils/check-system-deps.js';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 interface ShowcaseOptions {
     name?: string;
@@ -11,9 +17,9 @@ interface ShowcaseOptions {
 
 export const showcaseCommand: Command<any, ShowcaseOptions> = {
     command: 'showcase [name]',
-    description: 'List or run built-in gjsify showcase applications.',
-    builder: (yargs) => {
-        return yargs
+    description: 'List or run curated gjsify showcase applications.',
+    builder: (yargs) =>
+        yargs
             .positional('name', {
                 description: 'Showcase name to run (omit to list all)',
                 type: 'string',
@@ -27,8 +33,7 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
                 description: 'List available showcases',
                 type: 'boolean',
                 default: false,
-            });
-    },
+            }),
     handler: async (args) => {
         // List mode: no name given, or --list flag
         if (!args.name || args.list) {
@@ -40,11 +45,10 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             }
 
             if (showcases.length === 0) {
-                console.log('No showcases found. Showcase packages may not be installed.');
+                console.log('No showcases found. The CLI ships a curated list in `showcases.json`; if it is missing the CLI install is incomplete.');
                 return;
             }
 
-            // Group by category
             const grouped = new Map<string, typeof showcases>();
             for (const sc of showcases) {
                 const list = grouped.get(sc.category) ?? [];
@@ -55,7 +59,7 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             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));
+                const maxNameLen = Math.max(...list.map((e) => e.name.length));
                 for (const sc of list) {
                     const pad = ' '.repeat(maxNameLen - sc.name.length + 2);
                     const desc = sc.description ? `${pad}${sc.description}` : '';
@@ -68,7 +72,6 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             return;
         }
 
-        // Run mode: find the showcase
         const showcase = findShowcase(args.name);
         if (!showcase) {
             console.error(`Unknown showcase: "${args.name}"`);
@@ -76,16 +79,14 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             process.exit(1);
         }
 
-        // System dependency check before running — only check what this showcase needs.
-        // All showcases need GJS; WebGL showcases additionally need gwebgl prebuilds.
+        // System dependency check before delegating — only what this showcase needs.
         const results = runMinimalChecks();
-        const needsWebgl = showcase.packageName.includes('webgl') || showcase.packageName.includes('three');
-        if (needsWebgl) {
+        if (showcase.needsWebgl) {
             results.push(checkGwebgl(process.cwd()));
         }
-        // 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'));
+        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 missingHard) {
@@ -99,8 +100,26 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
             process.exit(1);
         }
 
-        // Run the showcase via shared GJS runner
-        console.log(`Running showcase: ${showcase.name}\n`);
-        await runGjsBundle(showcase.bundlePath);
+        // Delegate to `gjsify dlx <package>` — same npm-cache, same atomic
+        // symlink-swap, same `gjsify.main` resolution. Re-spawning the CLI
+        // keeps the dlx logic in one place.
+        console.log(`Running showcase: ${showcase.name} (via gjsify dlx)\n`);
+        const cliBin = fileURLToPath(new URL('../index.js', import.meta.url));
+        const child = spawn(process.execPath, [cliBin, 'dlx', showcase.packageName], {
+            stdio: 'inherit',
+        });
+        await new Promise<void>((resolvePromise, reject) => {
+            child.on('close', (code) => {
+                if (code !== 0) {
+                    reject(new Error(`gjsify dlx exited with code ${code}`));
+                } else {
+                    resolvePromise();
+                }
+            });
+            child.on('error', reject);
+        }).catch((err) => {
+            console.error(err.message);
+            process.exit(1);
+        });
     },
 };

package/src/index.ts

@@ -12,6 +12,7 @@ import {
     gresourceCommand as gresource,
     gettextCommand as gettext,
     dlxCommand as dlx,
+    installCommand as install,
 } from './commands/index.js'
 import { APP_NAME } from './constants.js'
 
@@ -19,6 +20,7 @@ void yargs(hideBin(process.argv))
     .scriptName(APP_NAME)
     .strict()
     .command(create.command, create.description, create.builder, create.handler)
+    .command(install.command, install.description, install.builder, install.handler)
     .command(build.command, build.description, build.builder, build.handler)
     .command(run.command, run.description, run.builder, run.handler)
     .command(dlx.command, dlx.description, dlx.builder, dlx.handler)

package/src/utils/check-system-deps.ts

@@ -159,8 +159,13 @@ const PACKAGE_DEPS: Record<string, string[]> = {
     '@gjsify/canvas2d':      ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
     '@gjsify/canvas2d-core': ['gdk-pixbuf', 'pango', 'pangocairo', 'cairo'],
     '@gjsify/dom-elements':  ['gdk-pixbuf'],
-    // @gjsify/webgl, @gjsify/event-bridge only need gtk4/gdk which are
-    // already in the required set, so they don't need optional entries.
+    // @gjsify/webgl needs the gwebgl npm package (Vala prebuild) — handled
+    // as a special-case checkNpmPackage rather than checkPkgConfig in
+    // runOptionalChecks. Mapping it here so its presence in the project's
+    // dep tree triggers the check.
+    '@gjsify/webgl':         ['gwebgl'],
+    // @gjsify/event-bridge only needs gtk4/gdk which are already in the
+    // required set, so it doesn't need an optional entry.
 };
 
 /** Walk up from cwd looking for the nearest package.json. */
@@ -322,10 +327,16 @@ function runOptionalChecks(needed: Set<string> | null, cwd: string): DepCheck[]
         results.push(checkPkgConfig(dep.id, dep.name, dep.pkgName, 'optional', requiredBy));
     }
 
-    // gwebgl npm package — special case (not a pkg-config lib).
-    // Always reported (the npm package is bundled with the CLI), but marked
-    // optional because only @gjsify/webgl users need it.
-    results.push(checkGwebgl(cwd));
+    // gwebgl npm package — special case (not a pkg-config lib). Only checked
+    // when the project directly or transitively depends on @gjsify/webgl —
+    // since the CLI tarball no longer ships any showcase example packages,
+    // gwebgl is not part of the CLI's own dep tree, so reporting it for every
+    // project would always be `found: false`. `needed === null` means "check
+    // everything" (no project context).
+    const hasWebglDep = needed === null || needed.has('gwebgl');
+    if (hasWebglDep) {
+        results.push(checkGwebgl(cwd));
+    }
 
     return results;
 }

package/src/utils/discover-showcases.ts

@@ -1,9 +1,13 @@
-// Dynamic discovery of installed showcase packages (@gjsify/example-*).
-// Scans the CLI's own package.json dependencies at runtime.
+// Static discovery of showcase packages from `showcases.json`.
+//
+// Earlier versions read showcases from the CLI's own `package.json#dependencies`
+// — every showcase had to be a direct CLI dependency. That made the CLI tarball
+// blow up with each new showcase and required a CLI rebuild to publish a new
+// one. Static manifest decouples both: the CLI reads the manifest at runtime,
+// `gjsify showcase <name>` delegates to `gjsify dlx <package>`.
 
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
 export interface ShowcaseInfo {
@@ -13,68 +17,53 @@ export interface ShowcaseInfo {
     packageName: string;
     /** Category: "dom" or "node" */
     category: string;
-    /** Description from showcase's package.json */
+    /** Description for the list view */
     description: string;
-    /** Absolute path to the GJS bundle (resolved from "main" field) */
-    bundlePath: string;
+    /** Whether the showcase needs the gwebgl native prebuild. */
+    needsWebgl: boolean;
 }
 
-const EXAMPLE_PREFIX = '@gjsify/example-';
+interface ManifestEntry {
+    name: string;
+    package: string;
+    category: string;
+    description?: string;
+    needsWebgl?: boolean;
+}
 
-/** Extract short name and category from package name. */
-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;
-    return {
-        category: suffix.slice(0, dashIdx),
-        name: suffix.slice(dashIdx + 1),
-    };
+interface Manifest {
+    showcases: ManifestEntry[];
+}
+
+function manifestPath(): string {
+    // `showcases.json` lives at the package root: ../../showcases.json from lib/utils/.
+    return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'showcases.json');
 }
 
 /**
- * Discover all installed showcase packages by scanning the CLI's own dependencies.
- * Returns showcases sorted by category then name.
+ * Read the curated showcase list from `showcases.json`. Returns showcases
+ * sorted by category then name. An empty list (or missing manifest) yields
+ * an empty array — `gjsify showcase` then prints the empty-state message.
  */
 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>;
+    const path = manifestPath();
+    if (!existsSync(path)) return [];
+
+    let manifest: Manifest;
     try {
-        cliPkg = JSON.parse(readFileSync(cliPkgPath, 'utf-8')) as Record<string, unknown>;
+        manifest = JSON.parse(readFileSync(path, 'utf-8')) as Manifest;
     } catch {
         return [];
     }
+    if (!Array.isArray(manifest.showcases)) return [];
 
-    const deps = cliPkg['dependencies'] as Record<string, string> | undefined;
-    if (!deps) return [];
-
-    const showcases: ShowcaseInfo[] = [];
-
-    for (const packageName of Object.keys(deps)) {
-        if (!packageName.startsWith(EXAMPLE_PREFIX)) continue;
-
-        const parsed = parseShowcaseName(packageName);
-        if (!parsed) continue;
-
-        try {
-            const pkgJsonPath = require.resolve(`${packageName}/package.json`);
-            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as Record<string, unknown>;
-            const main = pkg['main'] as string | undefined;
-            if (!main) continue;
-
-            showcases.push({
-                name: parsed.name,
-                packageName,
-                category: parsed.category,
-                description: (pkg['description'] as string) ?? '',
-                bundlePath: join(dirname(pkgJsonPath), main),
-            });
-        } catch {
-            // Package listed as dep but not resolvable — skip silently
-        }
-    }
+    const showcases: ShowcaseInfo[] = manifest.showcases.map((e) => ({
+        name: e.name,
+        packageName: e.package,
+        category: e.category,
+        description: e.description ?? '',
+        needsWebgl: Boolean(e.needsWebgl),
+    }));
 
     showcases.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
     return showcases;
@@ -82,5 +71,5 @@ export function discoverShowcases(): ShowcaseInfo[] {
 
 /** Find a single showcase by short name. */
 export function findShowcase(name: string): ShowcaseInfo | undefined {
-    return discoverShowcases().find(e => e.name === name);
+    return discoverShowcases().find((e) => e.name === name);
 }