@gjsify/cli 0.1.8 → 0.1.10

package/src/commands/check.ts

@@ -7,7 +7,7 @@ interface CheckOptions {
 
 export const checkCommand: Command<any, CheckOptions> = {
     command: 'check',
-    description: 'Check that all required system dependencies (GJS, GTK4, Blueprint Compiler, etc.) are installed.',
+    description: 'Check that required system dependencies (GJS, GTK4, libsoup3, …) are installed. Optional dependencies are detected only when their @gjsify/* package is in your project.',
     builder: (yargs) => {
         return yargs
             .option('json', {
@@ -19,36 +19,69 @@ export const checkCommand: Command<any, CheckOptions> = {
     handler: async (args) => {
         const results = runAllChecks(process.cwd());
         const pm = detectPackageManager();
-        const missing = results.filter(r => !r.found);
+        const missingRequired = results.filter(r => !r.found && r.severity === 'required');
+        const missingOptional = results.filter(r => !r.found && r.severity === 'optional');
+        const allMissing = [...missingRequired, ...missingOptional];
 
         if (args.json) {
             console.log(JSON.stringify({ packageManager: pm, deps: results }, null, 2));
-            process.exit(missing.length > 0 ? 1 : 0);
+            // Only required deps influence the exit code.
+            process.exit(missingRequired.length > 0 ? 1 : 0);
             return;
         }
 
         console.log('System dependency check\n');
-        for (const dep of results) {
-            const icon = dep.found ? '✓' : '✗';
-            const ver = dep.version ? `  (${dep.version})` : '';
-            console.log(`  ${icon}  ${dep.name}${ver}`);
+
+        const required = results.filter(r => r.severity === 'required');
+        const optional = results.filter(r => r.severity === 'optional');
+
+        if (required.length > 0) {
+            console.log('Required:');
+            for (const dep of required) {
+                const icon = dep.found ? '✓' : '✗';
+                const ver = dep.version ? `  (${dep.version})` : '';
+                console.log(`  ${icon}  ${dep.name}${ver}`);
+            }
+        }
+
+        if (optional.length > 0) {
+            console.log('\nOptional:');
+            for (const dep of optional) {
+                // ⚠ for missing-but-needed-by-installed-packages, ○ for missing-but-not-needed (shouldn't appear in conditional mode)
+                const icon = dep.found ? '✓' : '⚠';
+                const ver = dep.version ? `  (${dep.version})` : '';
+                const requiredBy = dep.requiredBy && dep.requiredBy.length > 0
+                    ? `  — needed by ${dep.requiredBy.join(', ')}`
+                    : '';
+                console.log(`  ${icon}  ${dep.name}${ver}${requiredBy}`);
+            }
         }
 
         console.log(`\nPackage manager: ${pm}`);
 
-        if (missing.length === 0) {
+        if (allMissing.length === 0) {
             console.log('\nAll dependencies found.');
             return;
         }
 
-        console.log(`\nMissing: ${missing.map(d => d.name).join(', ')}`);
-        const cmd = buildInstallCommand(pm, missing);
+        if (missingRequired.length > 0) {
+            console.log(`\nMissing required: ${missingRequired.map(d => d.name).join(', ')}`);
+        }
+        if (missingOptional.length > 0) {
+            console.log(`Missing optional: ${missingOptional.map(d => d.name).join(', ')}`);
+        }
+
+        const cmd = buildInstallCommand(pm, allMissing);
         if (cmd) {
-            console.log(`\nTo install missing dependencies:\n  ${cmd}`);
+            console.log(`\nTo install:\n  ${cmd}`);
         } else {
             console.log('\nNo install command available for your package manager. Install manually.');
         }
 
-        process.exit(1);
+        // Exit non-zero ONLY if a required dependency is missing.
+        // Optional deps that are missing but needed by an installed @gjsify/*
+        // package generate a warning but keep exit code 0 — the user can still
+        // build/run code paths that don't touch the optional library.
+        process.exit(missingRequired.length > 0 ? 1 : 0);
     },
 };

package/src/commands/showcase.ts

@@ -83,14 +83,16 @@ export const showcaseCommand: Command<any, ShowcaseOptions> = {
         if (needsWebgl) {
             results.push(checkGwebgl(process.cwd()));
         }
-        const missing = results.filter(r => !r.found);
-        if (missing.length > 0) {
+        // Hard-fail only on missing REQUIRED deps (gjs, gwebgl is required if needsWebgl).
+        // For showcase, gwebgl is treated as required because the bundle won't run without it.
+        const missingHard = results.filter(r => !r.found && (r.severity === 'required' || r.id === 'gwebgl'));
+        if (missingHard.length > 0) {
             console.error('Missing system dependencies:\n');
-            for (const dep of missing) {
+            for (const dep of missingHard) {
                 console.error(`  ✗  ${dep.name}`);
             }
             const pm = detectPackageManager();
-            const cmd = buildInstallCommand(pm, missing);
+            const cmd = buildInstallCommand(pm, missingHard);
             if (cmd) {
                 console.error(`\nInstall with:\n  ${cmd}`);
             }

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

@@ -1,11 +1,23 @@
 // 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.
+//
+// Severity model:
+//   - 'required'  → must be present, exit code 1 if missing
+//   - 'optional'  → nice to have, only warned about, exit code stays 0
+//
+// Conditional checking: when a project's package.json is reachable from cwd,
+// optional system deps are only checked if the corresponding @gjsify/* package
+// is in the project's dependency tree. A user with only @gjsify/fs in their
+// project never sees a warning about libmanette.
 
 import { execFileSync } from 'node:child_process';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+
+export type DepSeverity = 'required' | 'optional';
 
 export interface DepCheck {
     /** Stable key used for install command lookup, e.g. "gjs" */
@@ -15,6 +27,10 @@ export interface DepCheck {
     found: boolean;
     /** Version string when found, e.g. "1.86.0" */
     version?: string;
+    /** required = exit 1 if missing, optional = warn only */
+    severity: DepSeverity;
+    /** For optional deps: which @gjsify/* packages need this lib */
+    requiredBy?: string[];
 }
 
 export type PackageManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk' | 'unknown';
@@ -29,18 +45,32 @@ function tryExecFile(binary: string, args: string[]): string | 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 {
+function checkBinary(
+    id: string,
+    name: string,
+    binary: string,
+    versionArgs: string[],
+    severity: DepSeverity,
+    parseVersion?: (out: string) => string,
+    requiredBy?: string[],
+): DepCheck {
     const out = tryExecFile(binary, versionArgs);
-    if (out === null) return { id, name, found: false };
+    if (out === null) return { id, name, found: false, severity, requiredBy };
     const version = parseVersion ? parseVersion(out) : out.split('\n')[0] ?? out;
-    return { id, name, found: true, version };
+    return { id, name, found: true, version, severity, requiredBy };
 }
 
 /** Check a pkg-config library. pkg-config --modversion returns version on stdout. */
-function checkPkgConfig(id: string, name: string, libName: string): DepCheck {
+function checkPkgConfig(
+    id: string,
+    name: string,
+    libName: string,
+    severity: DepSeverity,
+    requiredBy?: 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] };
+    if (version === null) return { id, name, found: false, severity, requiredBy };
+    return { id, name, found: true, version: version.split('\n')[0], severity, requiredBy };
 }
 
 /**
@@ -48,21 +78,28 @@ function checkPkgConfig(id: string, name: string, libName: string): DepCheck {
  * back to the CLI's own node_modules. This way a locally installed version
  * takes precedence, but npx usage still works via the CLI's own dependencies.
  */
-function checkNpmPackage(id: string, name: string, packageName: string, cwd: string): DepCheck {
+function checkNpmPackage(
+    id: string,
+    name: string,
+    packageName: string,
+    cwd: string,
+    severity: DepSeverity,
+    requiredBy?: string[],
+): DepCheck {
     // 1. Try user's project
     try {
         const requireFromCwd = createRequire(pathToFileURL(join(cwd, '_check_.js')).href);
         requireFromCwd.resolve(packageName);
-        return { id, name, found: true };
+        return { id, name, found: true, severity, requiredBy };
     } catch { /* not in project, try CLI fallback */ }
 
     // 2. Fallback: CLI's own node_modules
     try {
         const requireFromCli = createRequire(import.meta.url);
         requireFromCli.resolve(packageName);
-        return { id, name, found: true };
+        return { id, name, found: true, severity, requiredBy };
     } catch {
-        return { id, name, found: false };
+        return { id, name, found: false, severity, requiredBy };
     }
 }
 
@@ -75,72 +112,219 @@ export function detectPackageManager(): PackageManager {
     return 'unknown';
 }
 
+// ---------------------------------------------------------------------------
+// @gjsify/* package → system dependency mapping
+// ---------------------------------------------------------------------------
+//
+// Lists which OPTIONAL system dependencies each gjsify package needs at
+// runtime. Required deps (gjs, gtk4, libsoup3, libadwaita, etc.) are checked
+// unconditionally because they're needed by the core toolchain.
+//
+// Used by `runAllChecks(cwd)` to skip optional deps for packages the user
+// isn't using. If a project doesn't depend on @gjsify/gamepad, libmanette
+// is not checked (and won't appear as a warning).
+
+interface OptionalDep {
+    /** DepCheck id */
+    id: string;
+    /** Display name */
+    name: string;
+    /** pkg-config library name */
+    pkgName: string;
+}
+
+/** Optional system deps keyed by their DepCheck id. */
+const OPTIONAL_DEPS: Record<string, OptionalDep> = {
+    manette:    { id: 'manette',    name: 'libmanette',     pkgName: 'manette-0.2' },
+    gstreamer:  { id: 'gstreamer',  name: 'GStreamer',      pkgName: 'gstreamer-1.0' },
+    'gst-app':  { id: 'gst-app',    name: 'GStreamer App',  pkgName: 'gstreamer-app-1.0' },
+    'gdk-pixbuf':{ id: 'gdk-pixbuf', name: 'GdkPixbuf',     pkgName: 'gdk-pixbuf-2.0' },
+    pango:      { id: 'pango',      name: 'Pango',          pkgName: 'pango' },
+    pangocairo: { id: 'pangocairo', name: 'PangoCairo',     pkgName: 'pangocairo' },
+    webkitgtk:  { id: 'webkitgtk',  name: 'WebKitGTK',      pkgName: 'webkitgtk-6.0' },
+    cairo:      { id: 'cairo',      name: 'Cairo',          pkgName: 'cairo' },
+};
+
+/**
+ * Map of @gjsify/* package name → ids of OPTIONAL_DEPS this package needs.
+ * Generated by walking each package's `gi://` imports (excluding the always-
+ * available trio GLib/GObject/Gio).
+ *
+ * Used to compute the set of optional deps to check for a given project.
+ */
+const PACKAGE_DEPS: Record<string, string[]> = {
+    '@gjsify/gamepad':       ['manette'],
+    '@gjsify/webaudio':      ['gstreamer', 'gst-app'],
+    '@gjsify/iframe':        ['webkitgtk'],
+    '@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.
+};
+
+/** Walk up from cwd looking for the nearest package.json. */
+function findProjectRoot(cwd: string): string | null {
+    let dir = resolve(cwd);
+    while (true) {
+        if (existsSync(join(dir, 'package.json'))) return dir;
+        const parent = resolve(dir, '..');
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}
+
+/**
+ * Discover which @gjsify/* packages a project depends on (transitively),
+ * by walking the node_modules tree from the project root. Returns a Set of
+ * package names like '@gjsify/webgl', '@gjsify/canvas2d'.
+ *
+ * If the project root cannot be determined or has no node_modules, returns
+ * `null` to signal "check all optional deps" — this matches the historical
+ * behaviour where `gjsify check` outside any project shows the full list.
+ */
+function discoverGjsifyPackages(cwd: string): Set<string> | null {
+    const root = findProjectRoot(cwd);
+    if (!root) return null;
+
+    const nodeModulesDir = join(root, 'node_modules', '@gjsify');
+    if (!existsSync(nodeModulesDir)) {
+        // Project exists but no @gjsify/* installed → only need core checks.
+        return new Set();
+    }
+
+    // Read top-level package.json to determine if @gjsify/cli is the only
+    // dep (in which case we still want to warn about everything the CLI
+    // transitively brings in). Otherwise scan node_modules for installed packages.
+    const pkgJsonPath = join(root, 'package.json');
+    let topPkg: Record<string, unknown> = {};
+    try {
+        topPkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+    } catch { /* ignore */ }
+
+    const directDeps = {
+        ...(topPkg.dependencies as Record<string, string> | undefined),
+        ...(topPkg.devDependencies as Record<string, string> | undefined),
+    };
+
+    const found = new Set<string>();
+    try {
+        for (const entry of readdirSync(nodeModulesDir, { withFileTypes: true })) {
+            if (entry.isDirectory() || entry.isSymbolicLink()) {
+                found.add(`@gjsify/${entry.name}`);
+            }
+        }
+    } catch { /* ignore */ }
+
+    // Also include direct deps even if node_modules walk failed
+    for (const dep of Object.keys(directDeps)) {
+        if (dep.startsWith('@gjsify/')) found.add(dep);
+    }
+
+    return found;
+}
+
+/**
+ * Compute the set of optional dep ids that should be checked for the
+ * current project. Returns null to indicate "check all" (no project context).
+ */
+function computeNeededOptionalDeps(cwd: string): Set<string> | null {
+    const installedPackages = discoverGjsifyPackages(cwd);
+    if (installedPackages === null) return null; // no project → check everything
+
+    const needed = new Set<string>();
+    for (const pkg of installedPackages) {
+        const deps = PACKAGE_DEPS[pkg];
+        if (deps) for (const id of deps) needed.add(id);
+    }
+    return needed;
+}
+
 /**
  * Run all dependency checks. Used by `gjsify check` to show full system status.
+ *
+ * Required deps (gjs, gtk4, libsoup3, libadwaita, gobject-introspection,
+ * blueprint-compiler, pkg-config, meson) are always checked.
+ *
+ * Optional deps are checked conditionally based on which @gjsify/* packages
+ * the project (resolved from cwd) actually consumes. If no project context
+ * is available, all optional deps are checked.
  */
 export function runAllChecks(cwd: string): DepCheck[] {
-    return [...runMinimalChecks(), ...runExtraChecks(cwd)];
+    const needed = computeNeededOptionalDeps(cwd);
+    return [...runMinimalChecks(), ...runRequiredChecks(cwd), ...runOptionalChecks(needed, cwd)];
 }
 
 /**
- * Minimal checks needed to run any GJS example (GJS binary only).
+ * Minimal checks needed to run any GJS example (Node + GJS binaries only).
  * Used by `gjsify showcase` for examples that have no native deps.
  */
 export function runMinimalChecks(): DepCheck[] {
     const results: DepCheck[] = [];
 
     // Node.js — always present
-    results.push({ id: 'nodejs', name: 'Node.js', found: true, version: process.version });
+    results.push({ id: 'nodejs', name: 'Node.js', found: true, version: process.version, severity: 'required' });
 
     // GJS
-    results.push(checkBinary('gjs', 'GJS', 'gjs', ['--version'],
+    results.push(checkBinary('gjs', 'GJS', 'gjs', ['--version'], 'required',
         (out) => out.replace(/^GJS\s+/i, '').split('\n')[0] ?? out));
 
     return results;
 }
 
-/** Check gwebgl npm package (project first, CLI fallback). */
+/** Check gwebgl npm package (project first, CLI fallback). Optional — only needed by @gjsify/webgl users. */
 export function checkGwebgl(cwd: string): DepCheck {
-    return checkNpmPackage('gwebgl', 'gwebgl (@gjsify/webgl)', '@gjsify/webgl', cwd);
+    return checkNpmPackage('gwebgl', 'gwebgl (@gjsify/webgl)', '@gjsify/webgl', cwd, 'optional', ['@gjsify/webgl']);
 }
 
 /**
- * Extra checks for development and full system audit.
+ * Required system dependencies — always checked, missing → exit 1.
+ * Includes the core build toolchain (pkg-config, meson, blueprint-compiler)
+ * and the foundational libraries (gtk4, libadwaita, libsoup3,
+ * gobject-introspection) that nearly every gjsify app needs.
  */
-function runExtraChecks(cwd: string): DepCheck[] {
+function runRequiredChecks(_cwd: string): DepCheck[] {
     const results: DepCheck[] = [];
 
-    // Blueprint Compiler
+    // Build toolchain
     results.push(checkBinary('blueprint-compiler', 'Blueprint Compiler',
-        'blueprint-compiler', ['--version']));
+        'blueprint-compiler', ['--version'], 'required'));
+    results.push(checkBinary('pkg-config', 'pkg-config', 'pkg-config', ['--version'], 'required'));
+    results.push(checkBinary('meson', 'Meson', 'meson', ['--version'], 'required'));
 
-    // pkg-config (needed for library checks)
-    results.push(checkBinary('pkg-config', 'pkg-config', 'pkg-config', ['--version']));
+    // Foundational libraries
+    results.push(checkPkgConfig('gtk4', 'GTK4', 'gtk4', 'required'));
+    results.push(checkPkgConfig('libadwaita', 'libadwaita', 'libadwaita-1', 'required'));
+    results.push(checkPkgConfig('libsoup3', 'libsoup3', 'libsoup-3.0', 'required'));
+    results.push(checkPkgConfig('gobject-introspection', 'GObject Introspection',
+        'gobject-introspection-1.0', 'required'));
 
-    // Meson (for building native extensions)
-    results.push(checkBinary('meson', 'Meson', 'meson', ['--version']));
+    return results;
+}
 
-    // GTK4
-    results.push(checkPkgConfig('gtk4', 'GTK4', 'gtk4'));
+/**
+ * Optional system dependencies — only checked if the corresponding @gjsify/*
+ * package is in use. Missing optional deps generate warnings, not errors.
+ *
+ * @param needed Set of optional dep ids to check, or null to check all.
+ * @param cwd Used to resolve the gwebgl npm package check.
+ */
+function runOptionalChecks(needed: Set<string> | null, cwd: string): DepCheck[] {
+    const results: DepCheck[] = [];
 
-    // libadwaita
-    results.push(checkPkgConfig('libadwaita', 'libadwaita', 'libadwaita-1'));
+    for (const [id, dep] of Object.entries(OPTIONAL_DEPS)) {
+        if (needed !== null && !needed.has(id)) continue;
 
-    // libsoup3
-    results.push(checkPkgConfig('libsoup3', 'libsoup3', 'libsoup-3.0'));
+        const requiredBy = Object.entries(PACKAGE_DEPS)
+            .filter(([, ids]) => ids.includes(id))
+            .map(([pkg]) => pkg);
 
-    // 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'));
+        results.push(checkPkgConfig(dep.id, dep.name, dep.pkgName, 'optional', requiredBy));
     }
 
-    // GObject Introspection
-    results.push(checkPkgConfig('gobject-introspection', 'GObject Introspection', 'gobject-introspection-1.0'));
-
-    // gwebgl — project first, CLI fallback.
+    // 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));
 
     return results;
@@ -157,8 +341,15 @@ const PM_PACKAGES: Record<PackageManager, Partial<Record<string, string>>> = {
         gtk4: 'libgtk-4-dev',
         libadwaita: 'libadwaita-1-dev',
         libsoup3: 'libsoup-3.0-dev',
-        webkitgtk: 'libwebkit2gtk-4.1-dev',
+        webkitgtk: 'libwebkit2gtk-6.0-dev',
         'gobject-introspection': 'gobject-introspection libgirepository1.0-dev',
+        manette: 'libmanette-0.2-0 gir1.2-manette-0.2',
+        gstreamer: 'libgstreamer1.0-dev',
+        'gst-app': 'libgstreamer-plugins-base1.0-dev gir1.2-gst-plugins-base-1.0',
+        'gdk-pixbuf': 'libgdk-pixbuf-2.0-dev',
+        pango: 'libpango1.0-dev',
+        pangocairo: 'libpango1.0-dev',
+        cairo: 'libcairo2-dev',
     },
     dnf: {
         gjs: 'gjs',
@@ -170,6 +361,13 @@ const PM_PACKAGES: Record<PackageManager, Partial<Record<string, string>>> = {
         libsoup3: 'libsoup3-devel',
         webkitgtk: 'webkitgtk6.0-devel',
         'gobject-introspection': 'gobject-introspection-devel',
+        manette: 'libmanette-devel',
+        gstreamer: 'gstreamer1-devel',
+        'gst-app': 'gstreamer1-plugins-base-devel',
+        'gdk-pixbuf': 'gdk-pixbuf2-devel',
+        pango: 'pango-devel',
+        pangocairo: 'pango-devel',
+        cairo: 'cairo-devel',
     },
     pacman: {
         gjs: 'gjs',
@@ -179,8 +377,15 @@ const PM_PACKAGES: Record<PackageManager, Partial<Record<string, string>>> = {
         gtk4: 'gtk4',
         libadwaita: 'libadwaita',
         libsoup3: 'libsoup3',
-        webkitgtk: 'webkit2gtk-4.1',
+        webkitgtk: 'webkitgtk-6.0',
         'gobject-introspection': 'gobject-introspection',
+        manette: 'libmanette',
+        gstreamer: 'gstreamer',
+        'gst-app': 'gst-plugins-base',
+        'gdk-pixbuf': 'gdk-pixbuf2',
+        pango: 'pango',
+        pangocairo: 'pango',
+        cairo: 'cairo',
     },
     zypper: {
         gjs: 'gjs',
@@ -190,8 +395,15 @@ const PM_PACKAGES: Record<PackageManager, Partial<Record<string, string>>> = {
         gtk4: 'gtk4-devel',
         libadwaita: 'libadwaita-devel',
         libsoup3: 'libsoup-3_0-devel',
-        webkitgtk: 'webkit2gtk3-devel',
+        webkitgtk: 'webkitgtk6_0-devel',
         'gobject-introspection': 'gobject-introspection-devel',
+        manette: 'libmanette-0_2-0-devel',
+        gstreamer: 'gstreamer-devel',
+        'gst-app': 'gstreamer-plugins-base-devel',
+        'gdk-pixbuf': 'gdk-pixbuf-devel',
+        pango: 'pango-devel',
+        pangocairo: 'pango-devel',
+        cairo: 'cairo-devel',
     },
     apk: {
         gjs: 'gjs',
@@ -201,8 +413,15 @@ const PM_PACKAGES: Record<PackageManager, Partial<Record<string, string>>> = {
         gtk4: 'gtk4.0-dev',
         libadwaita: 'libadwaita-dev',
         libsoup3: 'libsoup3-dev',
-        webkitgtk: 'webkit2gtk-4.1-dev',
+        webkitgtk: 'webkit2gtk-6.0-dev',
         'gobject-introspection': 'gobject-introspection-dev',
+        manette: 'libmanette-dev',
+        gstreamer: 'gstreamer-dev',
+        'gst-app': 'gst-plugins-base-dev',
+        'gdk-pixbuf': 'gdk-pixbuf-dev',
+        pango: 'pango-dev',
+        pangocairo: 'pango-dev',
+        cairo: 'cairo-dev',
     },
     unknown: {},
 };

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

@@ -135,6 +135,10 @@ function findNearestPackageJson(startDir: string): string | null {
  * Reads the nearest package.json to discover dependencies, then checks each
  * for gjsify native prebuilds metadata.
  *
+ * Also checks the **nearest package.json itself** — a workspace package may
+ * have its own prebuilds (e.g. `@gjsify/webgl` running its own test) and
+ * never list itself in dependencies.
+ *
  * This complements detectNativePackages() (filesystem walk from CWD) by using
  * require.resolve() — which handles hoisting, workspaces, and nested node_modules.
  */
@@ -152,6 +156,14 @@ export function resolveNativePackages(fromFilePath: string): NativePackage[] {
         const pkg = readPackageJson(nearestPkgJson);
         if (!pkg) return results;
 
+        // Check the nearest package itself (e.g. @gjsify/webgl running its own
+        // test bundle — webgl never lists itself in dependencies)
+        const ownName = typeof pkg['name'] === 'string' ? pkg['name'] as string : '';
+        if (ownName) {
+            const ownNative = checkPackage(dirname(nearestPkgJson), ownName, arch);
+            if (ownNative) results.push(ownNative);
+        }
+
         const deps = pkg['dependencies'] as Record<string, string> | undefined;
         if (!deps) return results;