@gjsify/cli 0.3.4 → 0.3.6

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

@@ -11,6 +11,8 @@ import {
     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'
 
@@ -18,8 +20,10 @@ 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/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);
 }

package/src/utils/dlx-cache.ts

@@ -0,0 +1,135 @@
+// Cache for `gjsify dlx` — content-addressable, atomic, parallel-safe.
+//
+// Pattern adapted from refs/pnpm/exec/commands/src/dlx.ts:
+//   - cache key = sha256 over sorted [packages, registries]
+//   - cache layout: <root>/<sha>/{pkg,timestamp-pid}/
+//   - prepare into a fresh temp dir, then atomically swap a `pkg` symlink
+//   - TTL via lstat mtime + maxAgeMinutes (default 7 days)
+
+import { createHash } from 'node:crypto';
+import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync, symlinkSync, type Stats } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const ONE_MINUTE_MS = 60_000;
+const DEFAULT_TTL_MIN = 60 * 24 * 7; // 7 days
+
+function lexCompare(a: string, b: string): number {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+
+interface CacheKeyOpts {
+    packages: string[];
+    registries?: Record<string, string>;
+}
+
+/** Stable, sorted JSON hash of inputs. */
+export function createCacheKey(opts: CacheKeyOpts): string {
+    const sortedPkgs = [...opts.packages].sort(lexCompare);
+    const sortedRegs = Object.entries(opts.registries ?? {}).sort(([a], [b]) => lexCompare(a, b));
+    const payload = JSON.stringify([sortedPkgs, sortedRegs]);
+    return createHash('sha256').update(payload).digest('hex');
+}
+
+/** $XDG_CACHE_HOME/gjsify/dlx — created if missing. */
+export function dlxCacheRoot(): string {
+    const xdg = process.env.XDG_CACHE_HOME;
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.cache');
+    const root = join(base, 'gjsify', 'dlx');
+    mkdirSync(root, { recursive: true });
+    return root;
+}
+
+/** Per-key cache directory: <root>/<sha>. */
+export function cacheDirFor(cacheKey: string): string {
+    const dir = join(dlxCacheRoot(), cacheKey);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+
+/** A fresh prepare directory under the per-key cache, named timestamp-pid. */
+export function makePrepareDir(cacheDir: string): string {
+    const name = `${Date.now().toString(16)}-${process.pid.toString(16)}`;
+    const dir = join(cacheDir, name);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+
+/**
+ * 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 function getValidCachedPkg(
+    cacheDir: string,
+    maxAgeMinutes: number = DEFAULT_TTL_MIN,
+): string | undefined {
+    const linkPath = join(cacheDir, 'pkg');
+    let stats: Stats;
+    try {
+        stats = lstatSync(linkPath);
+    } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+        throw err;
+    }
+    if (!stats.isSymbolicLink()) return undefined;
+
+    let target: string;
+    try {
+        target = realpathSync(linkPath);
+    } catch {
+        return undefined;
+    }
+
+    const ageMs = Date.now() - stats.mtime.getTime();
+    return ageMs <= maxAgeMinutes * ONE_MINUTE_MS ? target : 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 function symlinkSwap(cacheDir: string, prepareDir: string): string {
+    const linkPath = join(cacheDir, 'pkg');
+    const tmpName = `pkg.tmp-${Date.now().toString(16)}-${process.pid.toString(16)}`;
+    const tmpLink = join(cacheDir, tmpName);
+
+    try {
+        symlinkSync(prepareDir, tmpLink, 'dir');
+    } catch (err) {
+        // If we cannot even create the tmp link, give up.
+        throw err;
+    }
+
+    try {
+        renameSync(tmpLink, linkPath);
+    } catch (err) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code === 'EBUSY' || code === 'EPERM' || code === 'EEXIST') {
+            // Race lost — clean up our tmp and use whoever won.
+            try { rmSync(tmpLink); } catch {}
+            return realpathSync(linkPath);
+        }
+        throw err;
+    }
+
+    return realpathSync(linkPath);
+}
+
+/** Clean up `<cacheDir>/<oldPrepareDir>` siblings older than `maxAgeMinutes`. */
+export function cleanupStalePrepareDirs(cacheDir: string, _maxAgeMinutes: number = DEFAULT_TTL_MIN): void {
+    // Out of scope for Phase 1 — pnpm has the same TODO. Leaving a stub so
+    // call sites already exist when we do implement it.
+    void cacheDir;
+}
+
+/** Resolve absolute path to the installed package's directory inside cache. */
+export function resolveInstalledPkgDir(cachedRoot: string, pkgName: string): string {
+    return resolve(cachedRoot, 'node_modules', pkgName);
+}

package/src/utils/install-backend.ts

@@ -0,0 +1,79 @@
+// Install backend abstraction — Phase-4 seam.
+//
+// Today: spawns `npm install --no-package-lock --no-audit --no-fund --prefix <dir> <specs...>`.
+// Future (Phase 4): a GJS-native resolver replaces this without changing
+// the public signature, switched via `GJSIFY_INSTALL_BACKEND=native|npm`.
+//
+// Why npm and not pnpm/yarn? npm ships with Node so users already have it.
+// Adding a yarn/pnpm dep would defeat the purpose of `gjsify dlx` (which
+// itself is meant to ship binary-free GJS apps).
+//
+// `--no-package-lock` keeps the cache prepare dir hermetic; the cache key
+// already covers reproducibility. `--no-audit --no-fund` cuts ~5s off cold runs.
+
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface InstallOptions {
+    /** Directory to install into (npm `--prefix`). Created by caller. */
+    prefix: string;
+    /** npm-resolvable specs: `name`, `name@version`, `git+https://...`, tarball URL, ... */
+    specs: string[];
+    /** Verbose logging passes through `--loglevel verbose`. */
+    verbose?: boolean;
+    /** Optional registry override (writes a temp `.npmrc` in prefix). */
+    registry?: string;
+}
+
+const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'npm';
+
+export async function installPackages(opts: InstallOptions): Promise<void> {
+    if (DEFAULT_BACKEND === 'native') {
+        throw new Error(
+            'GJSIFY_INSTALL_BACKEND=native is reserved for the Phase 4 GJS-native resolver — not yet implemented.',
+        );
+    }
+    return installViaNpm(opts);
+}
+
+async function installViaNpm({ prefix, specs, verbose, registry }: InstallOptions): Promise<void> {
+    if (specs.length === 0) {
+        throw new Error('installPackages: empty specs list');
+    }
+
+    // Seed an empty package.json so npm doesn't walk up from prefix and pick
+    // up the user's project metadata. Cosmetic name/version only.
+    writeFileSync(
+        join(prefix, 'package.json'),
+        JSON.stringify({ name: 'gjsify-dlx-cache', version: '0.0.0', private: true }, null, 2),
+    );
+
+    if (registry) {
+        writeFileSync(join(prefix, '.npmrc'), `registry=${registry}\n`);
+    }
+
+    const args = [
+        'install',
+        '--no-package-lock',
+        '--no-audit',
+        '--no-fund',
+        '--prefix', prefix,
+        ...(verbose ? ['--loglevel', 'verbose'] : ['--loglevel', 'warn']),
+        ...specs,
+    ];
+
+    await new Promise<void>((resolve, reject) => {
+        const child = spawn('npm', args, { 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 msg = (err as NodeJS.ErrnoException).code === 'ENOENT'
+                ? 'npm not found on PATH — install Node.js or set GJSIFY_INSTALL_BACKEND=native (not yet supported)'
+                : `npm install failed: ${err.message}`;
+            reject(new Error(msg));
+        });
+    });
+}