@gjsify/cli 0.1.2 → 0.1.4

package/package.json

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

package/src/commands/check.ts

@@ -0,0 +1,55 @@
+import type { Command } from '../types/index.js';
+import { runAllChecks, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
+
+interface CheckOptions {
+    json: boolean;
+}
+
+export const checkCommand: Command<any, CheckOptions> = {
+    command: 'check',
+    description: 'Check that all required system dependencies (GJS, GTK4, Blueprint Compiler, etc.) are installed.',
+    builder: (yargs) => {
+        return yargs
+            .option('json', {
+                description: 'Output results as JSON',
+                type: 'boolean',
+                default: false,
+            });
+    },
+    handler: async (args) => {
+        const cwd = process.cwd();
+        const results = runAllChecks(cwd);
+        const pm = detectPackageManager();
+        const missing = results.filter(r => !r.found);
+
+        if (args.json) {
+            console.log(JSON.stringify({ packageManager: pm, deps: results }, null, 2));
+            process.exit(missing.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}`);
+        }
+
+        console.log(`\nPackage manager: ${pm}`);
+
+        if (missing.length === 0) {
+            console.log('\nAll dependencies found.');
+            return;
+        }
+
+        console.log(`\nMissing: ${missing.map(d => d.name).join(', ')}`);
+        const cmd = buildInstallCommand(pm, missing);
+        if (cmd) {
+            console.log(`\nTo install missing dependencies:\n  ${cmd}`);
+        } else {
+            console.log('\nNo install command available for your package manager. Install manually.');
+        }
+
+        process.exit(1);
+    },
+};

package/src/commands/index.ts

@@ -1,3 +1,5 @@
 export * from './build.js';
 export * from './run.js';
-export * from './info.js';
+export * from './info.js';
+export * from './check.js';
+export * from './showcase.js';

package/src/commands/run.ts

@@ -1,7 +1,6 @@
-import { spawn } from 'node:child_process';
 import { resolve } from 'node:path';
 import type { Command } from '../types/index.js';
-import { detectNativePackages, buildNativeEnv } from '../utils/detect-native-packages.js';
+import { runGjsBundle } from '../utils/run-gjs.js';
 
 interface RunOptions {
     file: string;
@@ -29,31 +28,6 @@ export const runCommand: Command<any, RunOptions> = {
     handler: async (args) => {
         const file = resolve(args.file as string);
         const extraArgs = (args.args as string[]) ?? [];
-        const cwd = process.cwd();
-
-        const nativePackages = detectNativePackages(cwd);
-        const nativeEnv = buildNativeEnv(nativePackages);
-
-        const env = {
-            ...process.env,
-            ...nativeEnv,
-        };
-
-        const gjsArgs = ['-m', file, ...extraArgs];
-        const child = spawn('gjs', gjsArgs, { env, stdio: 'inherit' });
-
-        await new Promise<void>((resolvePromise, reject) => {
-            child.on('close', (code) => {
-                if (code !== 0) {
-                    reject(new Error(`gjs exited with code ${code}`));
-                } else {
-                    resolvePromise();
-                }
-            });
-            child.on('error', reject);
-        }).catch((err) => {
-            console.error(err.message);
-            process.exit(1);
-        });
+        await runGjsBundle(file, extraArgs);
     },
 };

package/src/commands/showcase.ts

@@ -0,0 +1,99 @@
+import type { Command } from '../types/index.js';
+import { discoverExamples, findExample } from '../utils/discover-examples.js';
+import { runAllChecks, detectPackageManager, buildInstallCommand } from '../utils/check-system-deps.js';
+import { runGjsBundle } from '../utils/run-gjs.js';
+
+interface ShowcaseOptions {
+    name?: string;
+    json: boolean;
+    list: boolean;
+}
+
+export const showcaseCommand: Command<any, ShowcaseOptions> = {
+    command: 'showcase [name]',
+    description: 'List or run built-in gjsify example applications.',
+    builder: (yargs) => {
+        return yargs
+            .positional('name', {
+                description: 'Example name to run (omit to list all)',
+                type: 'string',
+            })
+            .option('json', {
+                description: 'Output as JSON',
+                type: 'boolean',
+                default: false,
+            })
+            .option('list', {
+                description: 'List available examples',
+                type: 'boolean',
+                default: false,
+            });
+    },
+    handler: async (args) => {
+        // List mode: no name given, or --list flag
+        if (!args.name || args.list) {
+            const examples = discoverExamples();
+
+            if (args.json) {
+                console.log(JSON.stringify(examples, null, 2));
+                return;
+            }
+
+            if (examples.length === 0) {
+                console.log('No examples found. Example 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);
+            }
+
+            console.log('Available gjsify examples:\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}`);
+                }
+                console.log('');
+            }
+
+            console.log('Run an example:  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.');
+            process.exit(1);
+        }
+
+        // System dependency check before running
+        const results = runAllChecks(process.cwd());
+        const missing = results.filter(r => !r.found);
+        if (missing.length > 0) {
+            console.error('Missing system dependencies:\n');
+            for (const dep of missing) {
+                console.error(`  ✗  ${dep.name}`);
+            }
+            const pm = detectPackageManager();
+            const cmd = buildInstallCommand(pm, missing);
+            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);
+    },
+};

package/src/index.ts

@@ -2,7 +2,7 @@
 import yargs from 'yargs'
 import { hideBin } from 'yargs/helpers'
 
-import { buildCommand as build, runCommand as run, infoCommand as info } from './commands/index.js'
+import { buildCommand as build, runCommand as run, infoCommand as info, checkCommand as check, showcaseCommand as showcase } from './commands/index.js'
 import { APP_NAME } from './constants.js'
 
 void yargs(hideBin(process.argv))
@@ -12,5 +12,7 @@ void yargs(hideBin(process.argv))
     .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)
+    .command(check.command, check.description, check.builder, check.handler)
+    .command(showcase.command, showcase.description, showcase.builder, showcase.handler)
     .demandCommand(1)
     .help().argv

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

@@ -0,0 +1,216 @@
+// System dependency checker for gjsify CLI.
+// Uses execFileSync with explicit argument arrays — no shell injection possible.
+// All binary names are hardcoded constants, never derived from user input.
+
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+export interface DepCheck {
+    /** Stable key used for install command lookup, e.g. "gjs" */
+    id: string;
+    /** Human-readable display name, e.g. "GJS" */
+    name: string;
+    found: boolean;
+    /** Version string when found, e.g. "1.86.0" */
+    version?: string;
+}
+
+export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'unknown';
+
+/** Run a binary and return its stdout trimmed, or null if it fails. */
+function tryExecFile(binary: string, args: string[]): string | null {
+    try {
+        return execFileSync(binary, args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch {
+        return null;
+    }
+}
+
+/** Check if a binary exists and optionally capture its version output. */
+function checkBinary(id: string, name: string, binary: string, versionArgs: string[], parseVersion?: (out: string) => string): DepCheck {
+    const out = tryExecFile(binary, versionArgs);
+    if (out === null) return { id, name, found: false };
+    const version = parseVersion ? parseVersion(out) : out.split('\n')[0] ?? out;
+    return { id, name, found: true, version };
+}
+
+/** Check a pkg-config library. pkg-config --modversion returns version on stdout. */
+function checkPkgConfig(id: string, name: string, libName: string): DepCheck {
+    const version = tryExecFile('pkg-config', ['--modversion', libName]);
+    if (version === null) return { id, name, found: false };
+    return { id, name, found: true, version: version.split('\n')[0] };
+}
+
+/**
+ * Check for an npm package by resolving it via Node.js module resolution from cwd.
+ * Mirrors the resolution logic used by esbuild / the build command.
+ */
+function checkNpmPackage(id: string, name: string, packageName: string, cwd: string): DepCheck {
+    try {
+        const requireFromCwd = createRequire(pathToFileURL(join(cwd, '_check_.js')).href);
+        requireFromCwd.resolve(packageName);
+        return { id, name, found: true };
+    } catch {
+        return { id, name, found: false };
+    }
+}
+
+export function detectPackageManager(): PackageManager {
+    const managers: PackageManager[] = ['apt', 'dnf', 'pacman', 'zypper', 'apk'];
+    for (const pm of managers) {
+        const result = tryExecFile('which', [pm]);
+        if (result !== null) return pm;
+    }
+    return 'unknown';
+}
+
+export function runAllChecks(cwd: string): DepCheck[] {
+    const results: DepCheck[] = [];
+
+    // Node.js — always present
+    results.push({ id: 'nodejs', name: 'Node.js', found: true, version: process.version });
+
+    // GJS
+    results.push(checkBinary('gjs', 'GJS', 'gjs', ['--version'],
+        (out) => out.replace(/^GJS\s+/i, '').split('\n')[0] ?? out));
+
+    // Blueprint Compiler
+    results.push(checkBinary('blueprint-compiler', 'Blueprint Compiler',
+        'blueprint-compiler', ['--version']));
+
+    // pkg-config (needed for library checks)
+    results.push(checkBinary('pkg-config', 'pkg-config', 'pkg-config', ['--version']));
+
+    // Meson (for building native extensions)
+    results.push(checkBinary('meson', 'Meson', 'meson', ['--version']));
+
+    // GTK4
+    results.push(checkPkgConfig('gtk4', 'GTK4', 'gtk4'));
+
+    // libadwaita
+    results.push(checkPkgConfig('libadwaita', 'libadwaita', 'libadwaita-1'));
+
+    // libsoup3
+    results.push(checkPkgConfig('libsoup3', 'libsoup3', 'libsoup-3.0'));
+
+    // WebKitGTK — try 4.1 first, fall back to 4.0
+    const webkitCheck = checkPkgConfig('webkitgtk', 'WebKitGTK', 'webkit2gtk-4.1');
+    if (webkitCheck.found) {
+        results.push(webkitCheck);
+    } else {
+        results.push(checkPkgConfig('webkitgtk', 'WebKitGTK', 'webkitgtk-6.0'));
+    }
+
+    // GObject Introspection
+    results.push(checkPkgConfig('gobject-introspection', 'GObject Introspection', 'gobject-introspection-1.0'));
+
+    // gwebgl — resolve via Node.js module resolution from cwd, same as esbuild would.
+    results.push(checkNpmPackage('gwebgl', 'gwebgl (@gjsify/webgl)', '@gjsify/webgl', cwd));
+
+    return results;
+}
+
+// Per-package-manager install package names, keyed by dep id.
+// Entries with multiple space-separated packages are intentional (one dep needs multiple system pkgs).
+const PM_PACKAGES: Record<PackageManager, Partial<Record<string, string>>> = {
+    apt: {
+        gjs: 'gjs',
+        'blueprint-compiler': 'blueprint-compiler',
+        'pkg-config': 'pkg-config',
+        meson: 'meson',
+        gtk4: 'libgtk-4-dev',
+        libadwaita: 'libadwaita-1-dev',
+        libsoup3: 'libsoup-3.0-dev',
+        webkitgtk: 'libwebkit2gtk-4.1-dev',
+        'gobject-introspection': 'gobject-introspection libgirepository1.0-dev',
+    },
+    dnf: {
+        gjs: 'gjs',
+        'blueprint-compiler': 'blueprint-compiler',
+        'pkg-config': 'pkgconf-pkg-config',
+        meson: 'meson',
+        gtk4: 'gtk4-devel',
+        libadwaita: 'libadwaita-devel',
+        libsoup3: 'libsoup3-devel',
+        webkitgtk: 'webkitgtk6.0-devel',
+        'gobject-introspection': 'gobject-introspection-devel',
+    },
+    pacman: {
+        gjs: 'gjs',
+        'blueprint-compiler': 'blueprint-compiler',
+        'pkg-config': 'pkgconf',
+        meson: 'meson',
+        gtk4: 'gtk4',
+        libadwaita: 'libadwaita',
+        libsoup3: 'libsoup3',
+        webkitgtk: 'webkit2gtk-4.1',
+        'gobject-introspection': 'gobject-introspection',
+    },
+    zypper: {
+        gjs: 'gjs',
+        'blueprint-compiler': 'blueprint-compiler',
+        'pkg-config': 'pkg-config',
+        meson: 'meson',
+        gtk4: 'gtk4-devel',
+        libadwaita: 'libadwaita-devel',
+        libsoup3: 'libsoup-3_0-devel',
+        webkitgtk: 'webkit2gtk3-devel',
+        'gobject-introspection': 'gobject-introspection-devel',
+    },
+    apk: {
+        gjs: 'gjs',
+        'blueprint-compiler': 'blueprint-compiler',
+        'pkg-config': 'pkgconf',
+        meson: 'meson',
+        gtk4: 'gtk4.0-dev',
+        libadwaita: 'libadwaita-dev',
+        libsoup3: 'libsoup3-dev',
+        webkitgtk: 'webkit2gtk-4.1-dev',
+        'gobject-introspection': 'gobject-introspection-dev',
+    },
+    unknown: {},
+};
+
+const PM_INSTALL_PREFIX: Record<PackageManager, string> = {
+    apt: 'sudo apt install',
+    dnf: 'sudo dnf install',
+    pacman: 'sudo pacman -S',
+    zypper: 'sudo zypper install',
+    apk: 'sudo apk add',
+    unknown: '',
+};
+
+/**
+ * Build a suggested install command for missing dependencies.
+ * gwebgl is an npm package, not a system package — handled separately.
+ * Returns null when package manager is unknown or no installable deps are missing.
+ */
+export function buildInstallCommand(pm: PackageManager, missing: DepCheck[]): string | null {
+    if (pm === 'unknown') return null;
+
+    const pkgMap = PM_PACKAGES[pm];
+    const pkgs: string[] = [];
+    const npmDeps: string[] = [];
+
+    for (const dep of missing) {
+        if (dep.id === 'gwebgl') {
+            npmDeps.push('@gjsify/webgl');
+            continue;
+        }
+        if (dep.id === 'nodejs') continue; // can't be missing if we're running
+        const pkg = pkgMap[dep.id];
+        if (pkg) pkgs.push(pkg);
+    }
+
+    const lines: string[] = [];
+    if (pkgs.length > 0) {
+        lines.push(`${PM_INSTALL_PREFIX[pm]} ${pkgs.join(' ')}`);
+    }
+    if (npmDeps.length > 0) {
+        lines.push(`npm install ${npmDeps.join(' ')}`);
+    }
+
+    return lines.length > 0 ? lines.join('\n  ') : null;
+}

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

@@ -3,7 +3,9 @@
 // The CLI uses this to auto-set LD_LIBRARY_PATH / GI_TYPELIB_PATH before running gjs.
 
 import { readdirSync, existsSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 export interface NativePackage {
     /** npm package name, e.g. "@gjsify/webgl" */
@@ -116,6 +118,64 @@ export function detectNativePackages(startDir: string): NativePackage[] {
     return [];
 }
 
+/** Walk up from dir to find the nearest package.json. */
+function findNearestPackageJson(startDir: string): string | null {
+    let dir = resolve(startDir);
+    while (true) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) return candidate;
+        const parent = resolve(dir, '..');
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+
+/**
+ * Resolve native packages using Node.js module resolution from a given file path.
+ * Reads the nearest package.json to discover dependencies, then checks each
+ * for gjsify native prebuilds metadata.
+ *
+ * This complements detectNativePackages() (filesystem walk from CWD) by using
+ * require.resolve() — which handles hoisting, workspaces, and nested node_modules.
+ */
+export function resolveNativePackages(fromFilePath: string): NativePackage[] {
+    const arch = nodeArchToLinuxArch(process.arch);
+    const results: NativePackage[] = [];
+
+    try {
+        const req = createRequire(pathToFileURL(fromFilePath).href);
+
+        // Find the nearest package.json to get the dependency list
+        const nearestPkgJson = findNearestPackageJson(dirname(resolve(fromFilePath)));
+        if (!nearestPkgJson) return results;
+
+        const pkg = readPackageJson(nearestPkgJson);
+        if (!pkg) return results;
+
+        const deps = pkg['dependencies'] as Record<string, string> | undefined;
+        if (!deps) return results;
+
+        for (const depName of Object.keys(deps)) {
+            try {
+                // Resolve the package's main entry, then walk up to find its package.json.
+                // We cannot use require.resolve(name + '/package.json') because packages
+                // with an "exports" field may not expose ./package.json as a subpath.
+                const entryPath = req.resolve(depName);
+                const depPkgJson = findNearestPackageJson(dirname(entryPath));
+                if (!depPkgJson) continue;
+                const native = checkPackage(dirname(depPkgJson), depName, arch);
+                if (native) results.push(native);
+            } catch {
+                // Dependency not resolvable — skip
+            }
+        }
+    } catch {
+        // Resolution failed — return empty
+    }
+
+    return results;
+}
+
 /**
  * Build the LD_LIBRARY_PATH and GI_TYPELIB_PATH env var values for the detected native packages.
  * Prepends the new paths to any existing values from the environment.

package/src/utils/discover-examples.ts

@@ -0,0 +1,87 @@
+// Dynamic discovery of installed @gjsify/example-* packages.
+// Scans the CLI's own package.json dependencies at runtime.
+
+import { readFileSync } from 'node:fs';
+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" */
+    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;
+}
+
+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
+    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),
+    };
+}
+
+/**
+ * Discover all installed example packages by scanning the CLI's own dependencies.
+ * Returns examples sorted by category then name.
+ */
+export function discoverExamples(): ExampleInfo[] {
+    const require = createRequire(import.meta.url);
+    const cliPkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    let cliPkg: Record<string, unknown>;
+    try {
+        cliPkg = JSON.parse(readFileSync(cliPkgPath, 'utf-8')) as Record<string, unknown>;
+    } catch {
+        return [];
+    }
+
+    const deps = cliPkg['dependencies'] as Record<string, string> | undefined;
+    if (!deps) return [];
+
+    const examples: ExampleInfo[] = [];
+
+    for (const packageName of Object.keys(deps)) {
+        if (!packageName.startsWith(EXAMPLE_PREFIX)) continue;
+
+        const parsed = parseExampleName(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;
+
+            examples.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
+        }
+    }
+
+    examples.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+    return examples;
+}
+
+/** Find a single example by short name. */
+export function findExample(name: string): ExampleInfo | undefined {
+    return discoverExamples().find(e => e.name === name);
+}