@gjsify/cli 0.3.4 → 0.3.6

package/lib/actions/build.js

@@ -43,13 +43,16 @@ async function getPnpPlugin() {
         // as direct deps, so we can resolve them as relay issuers from here.
         const gjsifyIssuer = fileURLToPath(import.meta.url);
         // Two-hop relay: node-polyfills and web-polyfills have all individual
-        // @gjsify/* packages as direct deps. Resolving from their paths allows
-        // PnP to reach e.g. @gjsify/node-globals (dep of node-polyfills).
+        // @gjsify/* packages as direct deps. Resolving from their package.json
+        // paths allows PnP to use them as issuers — sub-path imports
+        // (`@gjsify/foo/register/bar`) then resolve through the polyfill's
+        // dep graph. Resolve to package.json (always present, exports-agnostic)
+        // rather than main/module (the polyfills meta packages have no main).
         const requireFromGjsify = createRequire(gjsifyIssuer);
         const relayIssuers = [];
         for (const pkg of ["@gjsify/node-polyfills", "@gjsify/web-polyfills"]) {
             try {
-                relayIssuers.push(requireFromGjsify.resolve(pkg));
+                relayIssuers.push(requireFromGjsify.resolve(`${pkg}/package.json`));
             }
             catch {
                 // polyfills package not in dep tree — relay won't cover it
@@ -57,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/build.js

@@ -93,10 +93,9 @@ export const buildCommand = {
             default: 'auto'
         })
             .option('shebang', {
-            description: "Prepend a `#!/usr/bin/env -S gjs -m` shebang to the output and mark it executable (chmod 755). Only applies to GJS app builds with a single --outfile.",
+            description: "Prepend a `#!/usr/bin/env -S gjs -m` shebang to the output and mark it executable (chmod 755). Only applies to GJS app builds with a single --outfile. Default: false (use --shebang to enable, or set `shebang: true` in `.gjsifyrc.js`).",
             type: 'boolean',
-            normalize: true,
-            default: false
+            normalize: true
         })
             .option('external', {
             description: "Module names that should NOT be bundled. Repeat the flag or pass a comma-separated list (e.g. --external typedoc,prettier). Globs are forwarded to esbuild as-is. See https://esbuild.github.io/api/#external",

package/lib/commands/dlx.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from '../types/index.js';
+interface DlxOptions {
+    spec: string;
+    binOrArg?: string;
+    extraArgs?: string[];
+    'cache-max-age': number;
+    verbose: boolean;
+    registry?: string;
+}
+export declare const dlxCommand: Command<any, DlxOptions>;
+export {};

package/lib/commands/dlx.js

@@ -0,0 +1,117 @@
+// `gjsify dlx <package> [bin] [-- args...]` — runs the GJS bundle of an
+// npm-published package without persisting it in the user's project.
+//
+// Cardinal rule: dlx is a **GJS-bundle runner**, not a generic bin runner.
+// It always invokes `gjs -m <bundle>` via the existing `runGjsBundle()` util.
+// Packages without a GJS entry (no `gjsify.main`/`gjsify.bin`, no fallback
+// `main`) fail loudly.
+//
+// Cache: $XDG_CACHE_HOME/gjsify/dlx/<sha256>/ with TTL (default 7d, override
+// via --cache-max-age=<minutes>). Cache hit on second run skips `npm install`
+// entirely. Layout + atomic-swap pattern adapted from pnpm's dlx implementation
+// (refs/pnpm/exec/commands/src/dlx.ts).
+import { runGjsBundle } from '../utils/run-gjs.js';
+import { parseSpec } from '../utils/parse-spec.js';
+import { resolveGjsEntry } from '../utils/resolve-gjs-entry.js';
+import { cacheDirFor, createCacheKey, getValidCachedPkg, makePrepareDir, resolveInstalledPkgDir, symlinkSwap, } from '../utils/dlx-cache.js';
+import { installPackages } from '../utils/install-backend.js';
+export const dlxCommand = {
+    command: 'dlx <spec> [binOrArg] [extraArgs..]',
+    description: 'Run the GJS bundle of an npm-published package without installing it locally.',
+    builder: (yargs) => yargs
+        .positional('spec', {
+        description: 'Package spec (`name`, `name@version`, `@scope/name@spec`, or local path).',
+        type: 'string',
+        demandOption: true,
+    })
+        .positional('binOrArg', {
+        description: 'Optional bin name when the package defines `gjsify.bin` with multiple entries; otherwise treated as the first argument forwarded to the bundle.',
+        type: 'string',
+    })
+        .positional('extraArgs', {
+        description: 'Extra args forwarded to `gjs -m <bundle>`.',
+        type: 'string',
+        array: true,
+    })
+        .option('cache-max-age', {
+        description: 'Cache TTL in minutes. Defaults to 7 days. Use 0 to bypass cache.',
+        type: 'number',
+        default: 60 * 24 * 7,
+    })
+        .option('verbose', {
+        description: 'Verbose logging (passes --loglevel verbose to npm).',
+        type: 'boolean',
+        default: false,
+    })
+        .option('registry', {
+        description: 'Registry URL override.',
+        type: 'string',
+    }),
+    handler: async (args) => {
+        const parsed = parseSpec(args.spec);
+        const { pkgDir, cachedPkgName } = await ensurePkgDir(parsed, {
+            verbose: args.verbose,
+            registry: args.registry,
+            cacheMaxAge: args['cache-max-age'],
+        });
+        // Bin / args disambiguation:
+        //   gjsify dlx <pkg>                         → no bin, no args
+        //   gjsify dlx <pkg> mybin                   → bin if package has gjsify.bin[mybin], else arg
+        //   gjsify dlx <pkg> mybin -- arg1 arg2      → bin + extra args
+        //   gjsify dlx <pkg> -- arg1 arg2            → no bin, extra args
+        const { binName, extraArgs } = splitBinAndArgs(pkgDir, args.binOrArg, args.extraArgs ?? []);
+        const entry = resolveGjsEntry(pkgDir, binName);
+        if (entry.fromFallback) {
+            console.warn(`[gjsify dlx] package "${cachedPkgName ?? parsed.kind}" has no \`gjsify\` field — falling back to package.json#main. Add \`gjsify.main\` to silence.`);
+        }
+        await runGjsBundle(entry.bundlePath, extraArgs);
+    },
+};
+async function ensurePkgDir(parsed, opts) {
+    if (parsed.kind === 'local') {
+        return { pkgDir: parsed.path, cachedPkgName: null };
+    }
+    const cacheKey = createCacheKey({ packages: [parsed.spec] });
+    const cacheDir = cacheDirFor(cacheKey);
+    const cached = opts.cacheMaxAge > 0 ? getValidCachedPkg(cacheDir, opts.cacheMaxAge) : undefined;
+    if (cached) {
+        return {
+            pkgDir: resolveInstalledPkgDir(cached, parsed.name),
+            cachedPkgName: parsed.name,
+        };
+    }
+    const prepareDir = makePrepareDir(cacheDir);
+    await installPackages({
+        prefix: prepareDir,
+        specs: [parsed.spec],
+        verbose: opts.verbose,
+        registry: opts.registry,
+    });
+    const liveTarget = symlinkSwap(cacheDir, prepareDir);
+    return {
+        pkgDir: resolveInstalledPkgDir(liveTarget, parsed.name),
+        cachedPkgName: parsed.name,
+    };
+}
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+function splitBinAndArgs(pkgDir, binOrArg, extraArgs) {
+    if (!binOrArg) {
+        return { binName: null, extraArgs };
+    }
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    if (existsSync(pkgJsonPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            const bins = pkg.gjsify?.bin;
+            if (bins && Object.prototype.hasOwnProperty.call(bins, binOrArg)) {
+                return { binName: binOrArg, extraArgs };
+            }
+        }
+        catch {
+            // Fall through to treating as an arg.
+        }
+    }
+    // Not a known bin — treat the positional as the first argv to the bundle.
+    return { binName: null, extraArgs: [binOrArg, ...extraArgs] };
+}

package/lib/commands/index.d.ts

@@ -6,3 +6,5 @@ export * from './showcase.js';
 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

@@ -6,3 +6,5 @@ export * from './showcase.js';
 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,14 +1,16 @@
 #!/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, } 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)
     .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)

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/lib/utils/dlx-cache.d.ts

@@ -0,0 +1,34 @@
+interface CacheKeyOpts {
+    packages: string[];
+    registries?: Record<string, string>;
+}
+/** Stable, sorted JSON hash of inputs. */
+export declare function createCacheKey(opts: CacheKeyOpts): string;
+/** $XDG_CACHE_HOME/gjsify/dlx — created if missing. */
+export declare function dlxCacheRoot(): string;
+/** Per-key cache directory: <root>/<sha>. */
+export declare function cacheDirFor(cacheKey: string): string;
+/** A fresh prepare directory under the per-key cache, named timestamp-pid. */
+export declare function makePrepareDir(cacheDir: string): string;
+/**
+ * If <cacheDir>/pkg points to a target whose mtime + maxAge < now, return its
+ * realpath. Returns undefined when the link doesn't exist, isn't a symlink,
+ * has been removed, or has expired.
+ */
+export declare function getValidCachedPkg(cacheDir: string, maxAgeMinutes?: number): string | undefined;
+/**
+ * Atomically swap `<cacheDir>/pkg` to point at `prepareDir`.
+ *
+ * Strategy:
+ *   1. Create new symlink `<cacheDir>/pkg-<rand>` → prepareDir.
+ *   2. `rename(pkg-<rand>, pkg)` — POSIX guarantees rename-over-existing is atomic.
+ *
+ * Returns the realpath of the new live target. EBUSY/EEXIST indicates a race
+ * — a parallel process won, return its realpath.
+ */
+export declare function symlinkSwap(cacheDir: string, prepareDir: string): string;
+/** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
+export declare function cleanupStalePrepareDirs(cacheDir: string, _maxAgeMinutes?: number): void;
+/** Resolve absolute path to the installed package's directory inside cache. */
+export declare function resolveInstalledPkgDir(cachedRoot: string, pkgName: string): string;
+export {};