@gjsify/cli 0.3.6 → 0.3.8

package/lib/actions/build.js

@@ -1,122 +1,30 @@
 import { build } from "esbuild";
 import { gjsifyPlugin } from "@gjsify/esbuild-plugin-gjsify";
 import { resolveGlobalsList, writeRegisterInjectFile, detectAutoGlobals, } from "@gjsify/esbuild-plugin-gjsify/globals";
-import { dirname, extname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { getBundleDir, rewriteContents } from "@gjsify/esbuild-plugin-gjsify";
+import { getPnpPlugin } from "@gjsify/resolve-npm/pnp-relay";
+import { dirname, extname } from "node:path";
 import { chmod, readFile, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
 const GJS_SHEBANG = "#!/usr/bin/env -S gjs -m\n";
-/** Walk up from dir until .pnp.cjs is found; return its directory or null. */
-function findPnpRoot(dir) {
-    let current = dir;
-    while (true) {
-        if (existsSync(join(current, ".pnp.cjs")))
-            return current;
-        const parent = dirname(current);
-        if (parent === current)
-            return null;
-        current = parent;
-    }
-}
 /**
- * If the current project uses Yarn PnP, return the official
- * @yarnpkg/esbuild-plugin-pnp plugin so esbuild can resolve
- * modules from zip archives without manual extraction.
+ * Resolve the gjsify-flavoured PnP plugin. Anchors the relay on this file's
+ * URL so transitive `@gjsify/*` polyfills (reached via @gjsify/cli's deps on
+ * @gjsify/{node,web}-polyfills) are resolvable for external consumers without
+ * each one having to be a direct devDep.
  *
- * Custom onResolve: when the project's PnP context throws
- * UNDECLARED_DEPENDENCY, retry via a two-hop relay:
- *   1. @gjsify/cli context (direct dep of the project using gjsify build)
- *   2. @gjsify/node-polyfills context (direct dep of @gjsify/cli, has all
- *      node polyfills as direct deps including @gjsify/node-globals)
- *   3. @gjsify/web-polyfills context (direct dep of @gjsify/cli, has all
- *      web polyfills as direct deps including @gjsify/fetch, @gjsify/abort-controller)
- * For bare specifiers that the gjsify alias plugin maps (e.g. `abort-controller`),
- * fall through so that plugin can handle the transformation first.
+ * Wires the @gjsify/esbuild-plugin-gjsify rewriter (`__filename`/`__dirname`
+ * injection for CJS code in node_modules) into the pnp plugin's onLoad —
+ * esbuild stops at the first matching onLoad, so the rewriter MUST run from
+ * inside the pnp plugin's onLoad rather than as a separate registration.
  */
-async function getPnpPlugin() {
-    if (!findPnpRoot(process.cwd()))
-        return null;
-    try {
-        const { pnpPlugin } = await import("@yarnpkg/esbuild-plugin-pnp");
-        // gjsify's own file path — @gjsify/cli has node-polyfills + web-polyfills
-        // 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 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}/package.json`));
-            }
-            catch {
-                // polyfills package not in dep tree — relay won't cover it
-            }
-        }
-        let pnpApi = null;
-        try {
-            // 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
-            const mod = await import("pnpapi");
-            pnpApi = (mod.default ?? mod);
-        }
-        catch {
-            // Not in a PnP runtime (shouldn't happen since findPnpRoot passed)
-        }
-        return pnpPlugin({
-            onResolve: async (args, { resolvedPath, error, watchFiles }) => {
-                if (resolvedPath !== null) {
-                    return { namespace: "pnp", path: resolvedPath, watchFiles };
-                }
-                if (error?.pnpCode ===
-                    "UNDECLARED_DEPENDENCY") {
-                    if (pnpApi !== null) {
-                        // Try @gjsify/cli context first (covers @gjsify/* that are
-                        // direct deps of cli's own deps — unlikely but fast check).
-                        try {
-                            const rp = pnpApi.resolveRequest(args.path, gjsifyIssuer);
-                            if (rp !== null)
-                                return { namespace: "pnp", path: rp, watchFiles };
-                        }
-                        catch { }
-                        // Two-hop relay: resolve from node-polyfills / web-polyfills context
-                        // which have the individual @gjsify/* packages as direct deps.
-                        for (const relayIssuer of relayIssuers) {
-                            try {
-                                const rp = pnpApi.resolveRequest(args.path, relayIssuer);
-                                if (rp !== null)
-                                    return { namespace: "pnp", path: rp, watchFiles };
-                            }
-                            catch { }
-                        }
-                    }
-                    // Fall through — bare aliases (abort-controller, fetch/register/*)
-                    // are handled by the gjsify alias plugin after this returns null,
-                    // then the re-resolved @gjsify/* path goes through this hook again.
-                    return null;
-                }
-                return {
-                    external: true,
-                    errors: error ? [{ text: error.message }] : [],
-                    watchFiles,
-                };
-            },
-        });
-    }
-    catch {
-        return null;
-    }
+async function buildPnpPlugin() {
+    return getPnpPlugin({
+        issuerUrl: import.meta.url,
+        transformContentsFactory: (build) => {
+            const bundleDir = getBundleDir(build);
+            return (args, contents) => rewriteContents(args, contents, bundleDir);
+        },
+    });
 }
 export class BuildAction {
     configData;
@@ -140,7 +48,7 @@ export class BuildAction {
         const moduleOutExt = library.module ? extname(library.module) : ".js";
         const mainOutExt = library.main ? extname(library.main) : ".js";
         const multipleBuilds = moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
-        const pnpPlugin = await getPnpPlugin();
+        const pnpPlugin = await buildPnpPlugin();
         const pnpPlugins = pnpPlugin ? [pnpPlugin] : [];
         const results = [];
         if (multipleBuilds) {
@@ -298,7 +206,7 @@ export class BuildAction {
             ...(aliases ? { aliases } : {}),
         };
         const { autoMode, extras } = this.parseGlobalsValue(globals);
-        const pnpPlugin = await getPnpPlugin();
+        const pnpPlugin = await buildPnpPlugin();
         const pnpPlugins = pnpPlugin ? [pnpPlugin] : [];
         // --- Auto mode (with optional extras): iterative multi-pass build ---
         // The extras token is used for cases where the detector cannot

package/lib/commands/dlx.d.ts

@@ -4,6 +4,8 @@ interface DlxOptions {
     binOrArg?: string;
     extraArgs?: string[];
     'cache-max-age': number;
+    reinstall: boolean;
+    frozen: boolean;
     verbose: boolean;
     registry?: string;
 }

package/lib/commands/dlx.js

@@ -37,6 +37,16 @@ export const dlxCommand = {
         description: 'Cache TTL in minutes. Defaults to 7 days. Use 0 to bypass cache.',
         type: 'number',
         default: 60 * 24 * 7,
+    })
+        .option('reinstall', {
+        description: 'Bypass the cache for this run (alias for --cache-max-age=0).',
+        type: 'boolean',
+        default: false,
+    })
+        .option('frozen', {
+        description: 'Use the project-local gjsify-lock.json verbatim — fail if missing or stale (no resolver pass).',
+        type: 'boolean',
+        default: false,
     })
         .option('verbose', {
         description: 'Verbose logging (passes --loglevel verbose to npm).',
@@ -49,10 +59,12 @@ export const dlxCommand = {
     }),
     handler: async (args) => {
         const parsed = parseSpec(args.spec);
+        const cacheMaxAge = args.reinstall ? 0 : args['cache-max-age'];
         const { pkgDir, cachedPkgName } = await ensurePkgDir(parsed, {
             verbose: args.verbose,
             registry: args.registry,
-            cacheMaxAge: args['cache-max-age'],
+            cacheMaxAge,
+            frozen: args.frozen,
         });
         // Bin / args disambiguation:
         //   gjsify dlx <pkg>                         → no bin, no args
@@ -86,6 +98,11 @@ async function ensurePkgDir(parsed, opts) {
         specs: [parsed.spec],
         verbose: opts.verbose,
         registry: opts.registry,
+        // Cache-prepare dirs are scoped per cache key, so writing a lockfile
+        // there gives us reproducibility for repeated `gjsify dlx <pkg>` calls
+        // and lets `--frozen` short-circuit the resolver entirely.
+        lockfile: true,
+        frozen: opts.frozen,
     });
     const liveTarget = symlinkSwap(cacheDir, prepareDir);
     return {

package/lib/utils/install-backend-native.d.ts

@@ -0,0 +1,2 @@
+import type { InstallOptions } from "./install-backend.ts";
+export declare function installPackagesNative(opts: InstallOptions): Promise<void>;

package/lib/utils/install-backend-native.js

@@ -0,0 +1,299 @@
+// Native install backend — GJS-runnable replacement for `npm install`.
+//
+// Pipeline: parse specs → resolve deps via @gjsify/npm-registry packuments and
+// @gjsify/semver → download tarballs in parallel → extract into a flat
+// node_modules/ via @gjsify/tar. Output layout matches `npm install` so the
+// existing `runGjsBundle()` prebuild detection works without branching.
+//
+// Out of scope (deferred to Phase 4): lockfile, peerDependencies validation,
+// lifecycle scripts, git/file specs.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { Range, SemVer, maxSatisfying, } from "@gjsify/semver";
+import { DEFAULT_REGISTRY, fetchPackument, fetchTarball, parseNpmrc, } from "@gjsify/npm-registry";
+import { extractTarball } from "@gjsify/tar";
+const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? "8") || 8;
+const LOCKFILE_NAME = "gjsify-lock.json";
+const LOCKFILE_VERSION = 1;
+export async function installPackagesNative(opts) {
+    if (opts.specs.length === 0) {
+        throw new Error("installPackagesNative: empty specs list");
+    }
+    fs.mkdirSync(opts.prefix, { recursive: true });
+    const npmrc = await loadNpmrc(opts);
+    const log = makeLogger(opts.verbose ?? false);
+    const lockfilePath = path.join(opts.prefix, LOCKFILE_NAME);
+    const existingLock = readLockfile(lockfilePath);
+    let nodes;
+    if (existingLock && (opts.frozen || lockfileMatchesRequest(existingLock, opts.specs))) {
+        log("install: using lockfile (%d package(s))", Object.keys(existingLock.packages).length);
+        nodes = lockfileToNodes(existingLock);
+    }
+    else {
+        if (opts.frozen) {
+            throw new Error(`install: --frozen requested but ${lockfilePath} is missing or stale (specs differ)`);
+        }
+        log("install: resolving %d top-level spec(s) → %s", opts.specs.length, opts.prefix);
+        nodes = await resolveDeps(opts.specs, npmrc, log);
+        if (opts.lockfile) {
+            writeLockfile(lockfilePath, opts.specs, nodes);
+            log("install: wrote %s (%d entries)", LOCKFILE_NAME, nodes.length);
+        }
+    }
+    log("install: downloading %d tarball(s)", nodes.length);
+    await downloadAndExtractAll(nodes, opts.prefix, npmrc, log);
+    await linkBins(nodes, opts.prefix, log);
+    log("install: done");
+}
+async function resolveDeps(specs, npmrc, log) {
+    const packumentCache = new Map();
+    const fetchPkg = (name) => {
+        const cached = packumentCache.get(name);
+        if (cached)
+            return cached;
+        const fresh = fetchPackument(name, { npmrc });
+        packumentCache.set(name, fresh);
+        return fresh;
+    };
+    const resolved = new Map();
+    const queue = specs.map(parseSpec);
+    while (queue.length > 0) {
+        const spec = queue.shift();
+        if (resolved.has(spec.name)) {
+            // Single-version-per-name policy (npm v6 semantics). Phase 4 v2
+            // (when peer-dep validation lands) revisits this for duplication.
+            continue;
+        }
+        const packument = await fetchPkg(spec.name);
+        const version = pickVersion(packument, spec.range);
+        if (!version) {
+            throw new Error(`No version of ${spec.name} satisfies ${spec.range}`);
+        }
+        const v = packument.versions[version];
+        if (!v) {
+            throw new Error(`Packument for ${spec.name} promised ${version} but no entry exists`);
+        }
+        const node = {
+            name: spec.name,
+            version,
+            tarballUrl: v.dist.tarball,
+            integrity: v.dist.integrity,
+            dependencies: v.dependencies ?? {},
+            optionalDependencies: v.optionalDependencies ?? {},
+            bin: v.bin,
+        };
+        resolved.set(spec.name, node);
+        log("resolve: %s@%s ← %s", spec.name, version, spec.range);
+        for (const [depName, depRange] of Object.entries(node.dependencies)) {
+            if (!resolved.has(depName))
+                queue.push({ name: depName, range: depRange });
+        }
+        for (const [depName, depRange] of Object.entries(node.optionalDependencies)) {
+            if (!resolved.has(depName))
+                queue.push({ name: depName, range: depRange });
+        }
+    }
+    return Array.from(resolved.values());
+}
+function readLockfile(lockfilePath) {
+    if (!fs.existsSync(lockfilePath))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lockfilePath, "utf-8"));
+        if (parsed.lockfileVersion !== LOCKFILE_VERSION)
+            return null;
+        if (!parsed.packages || typeof parsed.packages !== "object")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeLockfile(lockfilePath, specs, nodes) {
+    const packages = {};
+    // Sort for deterministic output (diff-friendly).
+    const sorted = [...nodes].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const node of sorted) {
+        packages[node.name] = {
+            version: node.version,
+            resolved: node.tarballUrl,
+            integrity: node.integrity,
+            dependencies: Object.keys(node.dependencies).length > 0 ? node.dependencies : undefined,
+            bin: node.bin,
+        };
+    }
+    const lockfile = {
+        lockfileVersion: LOCKFILE_VERSION,
+        requested: [...specs],
+        packages,
+    };
+    fs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2) + "\n");
+}
+function lockfileToNodes(lockfile) {
+    return Object.entries(lockfile.packages).map(([name, entry]) => ({
+        name,
+        version: entry.version,
+        tarballUrl: entry.resolved,
+        integrity: entry.integrity,
+        dependencies: entry.dependencies ?? {},
+        optionalDependencies: {},
+        bin: entry.bin,
+    }));
+}
+function lockfileMatchesRequest(lockfile, specs) {
+    if (lockfile.requested.length !== specs.length)
+        return false;
+    const a = [...lockfile.requested].sort();
+    const b = [...specs].sort();
+    return a.every((v, i) => v === b[i]);
+}
+function parseSpec(raw) {
+    if (raw.startsWith("@")) {
+        const slash = raw.indexOf("/");
+        if (slash < 0)
+            throw new Error(`Invalid spec (scoped name without slash): ${raw}`);
+        const at = raw.indexOf("@", slash);
+        if (at < 0)
+            return { name: raw, range: "*" };
+        return { name: raw.slice(0, at), range: raw.slice(at + 1) || "*" };
+    }
+    const at = raw.indexOf("@");
+    if (at < 0)
+        return { name: raw, range: "*" };
+    return { name: raw.slice(0, at), range: raw.slice(at + 1) || "*" };
+}
+function pickVersion(packument, range) {
+    // dist-tag fast path: `latest`, `next`, ...
+    if (packument["dist-tags"][range])
+        return packument["dist-tags"][range];
+    // Validate range early so a typo fails loudly.
+    let parsedRange;
+    try {
+        parsedRange = new Range(range);
+    }
+    catch {
+        throw new Error(`Invalid version range for ${packument.name}: ${range}`);
+    }
+    const versions = Object.keys(packument.versions).filter((v) => {
+        try {
+            new SemVer(v);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    return maxSatisfying(versions, parsedRange);
+}
+async function downloadAndExtractAll(nodes, prefix, npmrc, log) {
+    const queue = [...nodes];
+    const workers = [];
+    const concurrency = Math.max(1, Math.min(DEFAULT_CONCURRENCY, queue.length));
+    for (let i = 0; i < concurrency; i++) {
+        workers.push(worker());
+    }
+    await Promise.all(workers);
+    async function worker() {
+        while (queue.length > 0) {
+            const node = queue.shift();
+            if (!node)
+                return;
+            const dest = path.join(prefix, "node_modules", node.name);
+            log("fetch: %s@%s ← %s", node.name, node.version, node.tarballUrl);
+            const bytes = await fetchTarball(node.tarballUrl, {
+                npmrc,
+                integrity: node.integrity,
+            });
+            fs.rmSync(dest, { recursive: true, force: true });
+            fs.mkdirSync(dest, { recursive: true });
+            await extractTarball(bytes, dest);
+        }
+    }
+}
+async function linkBins(nodes, prefix, log) {
+    const binDir = path.join(prefix, "node_modules", ".bin");
+    let created = 0;
+    for (const node of nodes) {
+        if (!node.bin)
+            continue;
+        const map = normalizeBin(node.name, node.bin);
+        if (map.size === 0)
+            continue;
+        fs.mkdirSync(binDir, { recursive: true });
+        for (const [binName, binTarget] of map) {
+            const targetAbs = path.join(prefix, "node_modules", node.name, binTarget);
+            if (!fs.existsSync(targetAbs))
+                continue;
+            try {
+                fs.chmodSync(targetAbs, 0o755);
+            }
+            catch {
+                /* best effort */
+            }
+            const linkPath = path.join(binDir, binName);
+            fs.rmSync(linkPath, { force: true });
+            const rel = path.relative(binDir, targetAbs);
+            try {
+                fs.symlinkSync(rel, linkPath);
+                created++;
+            }
+            catch {
+                fs.copyFileSync(targetAbs, linkPath);
+                fs.chmodSync(linkPath, 0o755);
+                created++;
+            }
+        }
+    }
+    if (created > 0)
+        log("bin: linked %d entry(ies) under .bin/", created);
+}
+function normalizeBin(pkgName, bin) {
+    const out = new Map();
+    if (typeof bin === "string") {
+        // String form is shorthand for `{ <last-segment-of-pkgName>: <bin> }`.
+        const baseName = pkgName.startsWith("@")
+            ? pkgName.slice(pkgName.indexOf("/") + 1)
+            : pkgName;
+        out.set(baseName, bin);
+        return out;
+    }
+    for (const [k, v] of Object.entries(bin))
+        out.set(k, v);
+    return out;
+}
+async function loadNpmrc(opts) {
+    const home = os.homedir();
+    const homeRc = path.join(home, ".npmrc");
+    let parsed = {
+        registry: opts.registry ?? DEFAULT_REGISTRY,
+        scopes: {},
+        authTokens: {},
+        basicAuth: {},
+    };
+    if (fs.existsSync(homeRc)) {
+        try {
+            parsed = parseNpmrc(fs.readFileSync(homeRc, "utf-8"));
+        }
+        catch (e) {
+            // Don't let a busted .npmrc prevent installs from anonymous registries.
+            console.warn(`gjsify install: ignoring malformed ${homeRc}: ${e.message}`);
+        }
+    }
+    if (opts.registry) {
+        parsed.registry = opts.registry;
+    }
+    return parsed;
+}
+function makeLogger(verbose) {
+    if (!verbose) {
+        return () => {
+            /* silent unless verbose */
+        };
+    }
+    return (fmt, ...args) => {
+        const msg = fmt.replace(/%s|%d/g, () => String(args.shift()));
+        process.stderr.write(`gjsify install: ${msg}\n`);
+    };
+}

package/lib/utils/install-backend.d.ts

@@ -7,5 +7,13 @@ export interface InstallOptions {
     verbose?: boolean;
     /** Optional registry override (writes a temp `.npmrc` in prefix). */
     registry?: string;
+    /**
+     * Native backend only: write `<prefix>/gjsify-lock.json` after a successful
+     * resolve. When the file exists on next call AND `frozen: true`, the
+     * resolver is skipped and downloads use the pinned tarball URL + integrity.
+     */
+    lockfile?: boolean;
+    /** Use `<prefix>/gjsify-lock.json` as the source of truth — fail if missing. */
+    frozen?: boolean;
 }
 export declare function installPackages(opts: InstallOptions): Promise<void>;

package/lib/utils/install-backend.js

@@ -1,24 +1,27 @@
-// Install backend abstraction — Phase-4 seam.
+// Install backend abstraction.
 //
-// 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`.
+// Default: native backend (resolves packuments via @gjsify/npm-registry,
+// extracts tarballs via @gjsify/tar — no Node, no npm required at runtime).
+// Fallback: `npm install --no-package-lock --no-audit --no-fund --prefix <dir> <specs...>`,
+// for parity with the legacy code path. 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).
+// `gjsify dlx` uses this seam — installing under a cache prefix, with no
+// package.json update to the user's project. The native backend matches that
+// workflow without ever shelling out to Node.
 //
 // `--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';
-const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'npm';
+const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
 export async function installPackages(opts) {
-    if (DEFAULT_BACKEND === 'native') {
-        throw new Error('GJSIFY_INSTALL_BACKEND=native is reserved for the Phase 4 GJS-native resolver — not yet implemented.');
+    if (DEFAULT_BACKEND === 'npm') {
+        return installViaNpm(opts);
     }
-    return installViaNpm(opts);
+    const { installPackagesNative } = await import('./install-backend-native.js');
+    return installPackagesNative(opts);
 }
 async function installViaNpm({ prefix, specs, verbose, registry }) {
     if (specs.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/cli",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "CLI for Gjsify",
   "type": "module",
   "main": "lib/index.js",
@@ -23,10 +23,14 @@
     "cli"
   ],
   "dependencies": {
-    "@gjsify/create-app": "^0.3.6",
-    "@gjsify/esbuild-plugin-gjsify": "^0.3.6",
-    "@gjsify/node-polyfills": "^0.3.6",
-    "@gjsify/web-polyfills": "^0.3.6",
+    "@gjsify/create-app": "^0.3.8",
+    "@gjsify/esbuild-plugin-gjsify": "^0.3.8",
+    "@gjsify/node-polyfills": "^0.3.8",
+    "@gjsify/npm-registry": "^0.3.8",
+    "@gjsify/resolve-npm": "^0.3.8",
+    "@gjsify/semver": "^0.3.8",
+    "@gjsify/tar": "^0.3.8",
+    "@gjsify/web-polyfills": "^0.3.8",
     "@yarnpkg/esbuild-plugin-pnp": "^3.0.0-rc.15",
     "cosmiconfig": "^9.0.1",
     "esbuild": "^0.28.0",

package/src/actions/build.ts

@@ -7,127 +7,32 @@ import {
 	writeRegisterInjectFile,
 	detectAutoGlobals,
 } from "@gjsify/esbuild-plugin-gjsify/globals";
-import { dirname, extname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { getBundleDir, rewriteContents } from "@gjsify/esbuild-plugin-gjsify";
+import { getPnpPlugin } from "@gjsify/resolve-npm/pnp-relay";
+import { dirname, extname } from "node:path";
 import { chmod, readFile, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
 
 const GJS_SHEBANG = "#!/usr/bin/env -S gjs -m\n";
 
-/** Walk up from dir until .pnp.cjs is found; return its directory or null. */
-function findPnpRoot(dir: string): string | null {
-	let current = dir;
-	while (true) {
-		if (existsSync(join(current, ".pnp.cjs"))) return current;
-		const parent = dirname(current);
-		if (parent === current) return null;
-		current = parent;
-	}
-}
-
 /**
- * If the current project uses Yarn PnP, return the official
- * @yarnpkg/esbuild-plugin-pnp plugin so esbuild can resolve
- * modules from zip archives without manual extraction.
+ * Resolve the gjsify-flavoured PnP plugin. Anchors the relay on this file's
+ * URL so transitive `@gjsify/*` polyfills (reached via @gjsify/cli's deps on
+ * @gjsify/{node,web}-polyfills) are resolvable for external consumers without
+ * each one having to be a direct devDep.
  *
- * Custom onResolve: when the project's PnP context throws
- * UNDECLARED_DEPENDENCY, retry via a two-hop relay:
- *   1. @gjsify/cli context (direct dep of the project using gjsify build)
- *   2. @gjsify/node-polyfills context (direct dep of @gjsify/cli, has all
- *      node polyfills as direct deps including @gjsify/node-globals)
- *   3. @gjsify/web-polyfills context (direct dep of @gjsify/cli, has all
- *      web polyfills as direct deps including @gjsify/fetch, @gjsify/abort-controller)
- * For bare specifiers that the gjsify alias plugin maps (e.g. `abort-controller`),
- * fall through so that plugin can handle the transformation first.
+ * Wires the @gjsify/esbuild-plugin-gjsify rewriter (`__filename`/`__dirname`
+ * injection for CJS code in node_modules) into the pnp plugin's onLoad —
+ * esbuild stops at the first matching onLoad, so the rewriter MUST run from
+ * inside the pnp plugin's onLoad rather than as a separate registration.
  */
-async function getPnpPlugin(): Promise<Plugin | null> {
-	if (!findPnpRoot(process.cwd())) return null;
-	try {
-		const { pnpPlugin } = await import("@yarnpkg/esbuild-plugin-pnp");
-
-		// gjsify's own file path — @gjsify/cli has node-polyfills + web-polyfills
-		// 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 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: string[] = [];
-		for (const pkg of ["@gjsify/node-polyfills", "@gjsify/web-polyfills"]) {
-			try {
-				relayIssuers.push(requireFromGjsify.resolve(`${pkg}/package.json`));
-			} catch {
-				// polyfills package not in dep tree — relay won't cover it
-			}
-		}
-
-		// pnpapi is a virtual module injected by Yarn PnP at runtime.
-		type PnpApi = {
-			resolveRequest: (req: string, issuer: string) => string | null;
-		};
-		let pnpApi: PnpApi | null = null;
-		try {
-			// 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
-			const mod = await import("pnpapi");
-			pnpApi = ((mod as { default?: PnpApi }).default ?? mod) as PnpApi;
-		} catch {
-			// Not in a PnP runtime (shouldn't happen since findPnpRoot passed)
-		}
-
-		return pnpPlugin({
-			onResolve: async (args, { resolvedPath, error, watchFiles }) => {
-				if (resolvedPath !== null) {
-					return { namespace: "pnp", path: resolvedPath, watchFiles };
-				}
-				if (
-					(error as { pnpCode?: string } | null)?.pnpCode ===
-					"UNDECLARED_DEPENDENCY"
-				) {
-					if (pnpApi !== null) {
-						// Try @gjsify/cli context first (covers @gjsify/* that are
-						// direct deps of cli's own deps — unlikely but fast check).
-						try {
-							const rp = pnpApi.resolveRequest(args.path, gjsifyIssuer);
-							if (rp !== null)
-								return { namespace: "pnp", path: rp, watchFiles };
-						} catch {}
-						// Two-hop relay: resolve from node-polyfills / web-polyfills context
-						// which have the individual @gjsify/* packages as direct deps.
-						for (const relayIssuer of relayIssuers) {
-							try {
-								const rp = pnpApi.resolveRequest(args.path, relayIssuer);
-								if (rp !== null)
-									return { namespace: "pnp", path: rp, watchFiles };
-							} catch {}
-						}
-					}
-					// Fall through — bare aliases (abort-controller, fetch/register/*)
-					// are handled by the gjsify alias plugin after this returns null,
-					// then the re-resolved @gjsify/* path goes through this hook again.
-					return null;
-				}
-				return {
-					external: true,
-					errors: error ? [{ text: error.message }] : [],
-					watchFiles,
-				};
-			},
-		});
-	} catch {
-		return null;
-	}
+async function buildPnpPlugin(): Promise<Plugin | null> {
+	return getPnpPlugin({
+		issuerUrl: import.meta.url,
+		transformContentsFactory: (build) => {
+			const bundleDir = getBundleDir(build);
+			return (args, contents) => rewriteContents(args, contents, bundleDir);
+		},
+	});
 }
 
 export class BuildAction {
@@ -156,7 +61,7 @@ export class BuildAction {
 		const multipleBuilds =
 			moduleOutdir && mainOutdir && moduleOutdir !== mainOutdir;
 
-		const pnpPlugin = await getPnpPlugin();
+		const pnpPlugin = await buildPnpPlugin();
 		const pnpPlugins: Plugin[] = pnpPlugin ? [pnpPlugin] : [];
 
 		const results: BuildResult[] = [];
@@ -368,7 +273,7 @@ export class BuildAction {
 
 		const { autoMode, extras } = this.parseGlobalsValue(globals);
 
-		const pnpPlugin = await getPnpPlugin();
+		const pnpPlugin = await buildPnpPlugin();
 		const pnpPlugins: Plugin[] = pnpPlugin ? [pnpPlugin] : [];
 
 		// --- Auto mode (with optional extras): iterative multi-pass build ---

package/src/commands/dlx.ts

@@ -30,6 +30,8 @@ interface DlxOptions {
     binOrArg?: string;
     extraArgs?: string[];
     'cache-max-age': number;
+    reinstall: boolean;
+    frozen: boolean;
     verbose: boolean;
     registry?: string;
 }
@@ -62,6 +64,18 @@ export const dlxCommand: Command<any, DlxOptions> = {
                 type: 'number',
                 default: 60 * 24 * 7,
             })
+            .option('reinstall', {
+                description:
+                    'Bypass the cache for this run (alias for --cache-max-age=0).',
+                type: 'boolean',
+                default: false,
+            })
+            .option('frozen', {
+                description:
+                    'Use the project-local gjsify-lock.json verbatim — fail if missing or stale (no resolver pass).',
+                type: 'boolean',
+                default: false,
+            })
             .option('verbose', {
                 description: 'Verbose logging (passes --loglevel verbose to npm).',
                 type: 'boolean',
@@ -74,10 +88,12 @@ export const dlxCommand: Command<any, DlxOptions> = {
     handler: async (args) => {
         const parsed = parseSpec(args.spec);
 
+        const cacheMaxAge = args.reinstall ? 0 : args['cache-max-age'];
         const { pkgDir, cachedPkgName } = await ensurePkgDir(parsed, {
             verbose: args.verbose,
             registry: args.registry,
-            cacheMaxAge: args['cache-max-age'],
+            cacheMaxAge,
+            frozen: args.frozen,
         });
 
         // Bin / args disambiguation:
@@ -106,6 +122,7 @@ interface EnsureOpts {
     verbose: boolean;
     registry?: string;
     cacheMaxAge: number;
+    frozen: boolean;
 }
 
 async function ensurePkgDir(
@@ -133,6 +150,11 @@ async function ensurePkgDir(
         specs: [parsed.spec],
         verbose: opts.verbose,
         registry: opts.registry,
+        // Cache-prepare dirs are scoped per cache key, so writing a lockfile
+        // there gives us reproducibility for repeated `gjsify dlx <pkg>` calls
+        // and lets `--frozen` short-circuit the resolver entirely.
+        lockfile: true,
+        frozen: opts.frozen,
     });
 
     const liveTarget = symlinkSwap(cacheDir, prepareDir);

package/src/utils/install-backend-native.ts

@@ -0,0 +1,363 @@
+// Native install backend — GJS-runnable replacement for `npm install`.
+//
+// Pipeline: parse specs → resolve deps via @gjsify/npm-registry packuments and
+// @gjsify/semver → download tarballs in parallel → extract into a flat
+// node_modules/ via @gjsify/tar. Output layout matches `npm install` so the
+// existing `runGjsBundle()` prebuild detection works without branching.
+//
+// Out of scope (deferred to Phase 4): lockfile, peerDependencies validation,
+// lifecycle scripts, git/file specs.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+import {
+    Range,
+    SemVer,
+    maxSatisfying,
+} from "@gjsify/semver";
+import {
+    DEFAULT_REGISTRY,
+    fetchPackument,
+    fetchTarball,
+    parseNpmrc,
+    type NpmrcConfig,
+    type Packument,
+    type PackumentVersion,
+} from "@gjsify/npm-registry";
+import { extractTarball } from "@gjsify/tar";
+
+import type { InstallOptions } from "./install-backend.ts";
+
+const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? "8") || 8;
+
+interface ParsedSpec {
+    name: string;
+    range: string;
+}
+
+interface ResolvedNode {
+    name: string;
+    version: string;
+    tarballUrl: string;
+    integrity?: string;
+    dependencies: Record<string, string>;
+    optionalDependencies: Record<string, string>;
+    bin?: string | Record<string, string>;
+}
+
+const LOCKFILE_NAME = "gjsify-lock.json";
+const LOCKFILE_VERSION = 1;
+
+interface LockfileEntry {
+    version: string;
+    resolved: string;
+    integrity?: string;
+    dependencies?: Record<string, string>;
+    bin?: string | Record<string, string>;
+}
+
+interface Lockfile {
+    lockfileVersion: number;
+    /** Top-level specs used to seed this lockfile (preserves user intent). */
+    requested: string[];
+    /** Pinned packages keyed by name. */
+    packages: Record<string, LockfileEntry>;
+}
+
+export async function installPackagesNative(opts: InstallOptions): Promise<void> {
+    if (opts.specs.length === 0) {
+        throw new Error("installPackagesNative: empty specs list");
+    }
+
+    fs.mkdirSync(opts.prefix, { recursive: true });
+    const npmrc = await loadNpmrc(opts);
+    const log = makeLogger(opts.verbose ?? false);
+
+    const lockfilePath = path.join(opts.prefix, LOCKFILE_NAME);
+    const existingLock = readLockfile(lockfilePath);
+
+    let nodes: ResolvedNode[];
+    if (existingLock && (opts.frozen || lockfileMatchesRequest(existingLock, opts.specs))) {
+        log("install: using lockfile (%d package(s))", Object.keys(existingLock.packages).length);
+        nodes = lockfileToNodes(existingLock);
+    } else {
+        if (opts.frozen) {
+            throw new Error(
+                `install: --frozen requested but ${lockfilePath} is missing or stale (specs differ)`,
+            );
+        }
+        log("install: resolving %d top-level spec(s) → %s", opts.specs.length, opts.prefix);
+        nodes = await resolveDeps(opts.specs, npmrc, log);
+        if (opts.lockfile) {
+            writeLockfile(lockfilePath, opts.specs, nodes);
+            log("install: wrote %s (%d entries)", LOCKFILE_NAME, nodes.length);
+        }
+    }
+
+    log("install: downloading %d tarball(s)", nodes.length);
+    await downloadAndExtractAll(nodes, opts.prefix, npmrc, log);
+    await linkBins(nodes, opts.prefix, log);
+    log("install: done");
+}
+
+async function resolveDeps(
+    specs: string[],
+    npmrc: NpmrcConfig,
+    log: Logger,
+): Promise<ResolvedNode[]> {
+    const packumentCache = new Map<string, Promise<Packument>>();
+    const fetchPkg = (name: string): Promise<Packument> => {
+        const cached = packumentCache.get(name);
+        if (cached) return cached;
+        const fresh = fetchPackument(name, { npmrc });
+        packumentCache.set(name, fresh);
+        return fresh;
+    };
+
+    const resolved = new Map<string, ResolvedNode>();
+    const queue: ParsedSpec[] = specs.map(parseSpec);
+
+    while (queue.length > 0) {
+        const spec = queue.shift() as ParsedSpec;
+        if (resolved.has(spec.name)) {
+            // Single-version-per-name policy (npm v6 semantics). Phase 4 v2
+            // (when peer-dep validation lands) revisits this for duplication.
+            continue;
+        }
+        const packument = await fetchPkg(spec.name);
+        const version = pickVersion(packument, spec.range);
+        if (!version) {
+            throw new Error(`No version of ${spec.name} satisfies ${spec.range}`);
+        }
+        const v = packument.versions[version];
+        if (!v) {
+            throw new Error(
+                `Packument for ${spec.name} promised ${version} but no entry exists`,
+            );
+        }
+        const node: ResolvedNode = {
+            name: spec.name,
+            version,
+            tarballUrl: v.dist.tarball,
+            integrity: v.dist.integrity,
+            dependencies: v.dependencies ?? {},
+            optionalDependencies: v.optionalDependencies ?? {},
+            bin: v.bin,
+        };
+        resolved.set(spec.name, node);
+        log("resolve: %s@%s ← %s", spec.name, version, spec.range);
+
+        for (const [depName, depRange] of Object.entries(node.dependencies)) {
+            if (!resolved.has(depName)) queue.push({ name: depName, range: depRange });
+        }
+        for (const [depName, depRange] of Object.entries(node.optionalDependencies)) {
+            if (!resolved.has(depName)) queue.push({ name: depName, range: depRange });
+        }
+    }
+    return Array.from(resolved.values());
+}
+
+function readLockfile(lockfilePath: string): Lockfile | null {
+    if (!fs.existsSync(lockfilePath)) return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lockfilePath, "utf-8")) as Lockfile;
+        if (parsed.lockfileVersion !== LOCKFILE_VERSION) return null;
+        if (!parsed.packages || typeof parsed.packages !== "object") return null;
+        return parsed;
+    } catch {
+        return null;
+    }
+}
+
+function writeLockfile(lockfilePath: string, specs: string[], nodes: ResolvedNode[]): void {
+    const packages: Record<string, LockfileEntry> = {};
+    // Sort for deterministic output (diff-friendly).
+    const sorted = [...nodes].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const node of sorted) {
+        packages[node.name] = {
+            version: node.version,
+            resolved: node.tarballUrl,
+            integrity: node.integrity,
+            dependencies:
+                Object.keys(node.dependencies).length > 0 ? node.dependencies : undefined,
+            bin: node.bin,
+        };
+    }
+    const lockfile: Lockfile = {
+        lockfileVersion: LOCKFILE_VERSION,
+        requested: [...specs],
+        packages,
+    };
+    fs.writeFileSync(lockfilePath, JSON.stringify(lockfile, null, 2) + "\n");
+}
+
+function lockfileToNodes(lockfile: Lockfile): ResolvedNode[] {
+    return Object.entries(lockfile.packages).map(([name, entry]) => ({
+        name,
+        version: entry.version,
+        tarballUrl: entry.resolved,
+        integrity: entry.integrity,
+        dependencies: entry.dependencies ?? {},
+        optionalDependencies: {},
+        bin: entry.bin,
+    }));
+}
+
+function lockfileMatchesRequest(lockfile: Lockfile, specs: string[]): boolean {
+    if (lockfile.requested.length !== specs.length) return false;
+    const a = [...lockfile.requested].sort();
+    const b = [...specs].sort();
+    return a.every((v, i) => v === b[i]);
+}
+
+function parseSpec(raw: string): ParsedSpec {
+    if (raw.startsWith("@")) {
+        const slash = raw.indexOf("/");
+        if (slash < 0) throw new Error(`Invalid spec (scoped name without slash): ${raw}`);
+        const at = raw.indexOf("@", slash);
+        if (at < 0) return { name: raw, range: "*" };
+        return { name: raw.slice(0, at), range: raw.slice(at + 1) || "*" };
+    }
+    const at = raw.indexOf("@");
+    if (at < 0) return { name: raw, range: "*" };
+    return { name: raw.slice(0, at), range: raw.slice(at + 1) || "*" };
+}
+
+function pickVersion(packument: Packument, range: string): string | null {
+    // dist-tag fast path: `latest`, `next`, ...
+    if (packument["dist-tags"][range]) return packument["dist-tags"][range];
+
+    // Validate range early so a typo fails loudly.
+    let parsedRange: Range;
+    try {
+        parsedRange = new Range(range);
+    } catch {
+        throw new Error(`Invalid version range for ${packument.name}: ${range}`);
+    }
+
+    const versions = Object.keys(packument.versions).filter((v) => {
+        try {
+            new SemVer(v);
+            return true;
+        } catch {
+            return false;
+        }
+    });
+    return maxSatisfying(versions, parsedRange);
+}
+
+async function downloadAndExtractAll(
+    nodes: ResolvedNode[],
+    prefix: string,
+    npmrc: NpmrcConfig,
+    log: Logger,
+): Promise<void> {
+    const queue = [...nodes];
+    const workers: Array<Promise<void>> = [];
+    const concurrency = Math.max(1, Math.min(DEFAULT_CONCURRENCY, queue.length));
+    for (let i = 0; i < concurrency; i++) {
+        workers.push(worker());
+    }
+    await Promise.all(workers);
+
+    async function worker(): Promise<void> {
+        while (queue.length > 0) {
+            const node = queue.shift();
+            if (!node) return;
+            const dest = path.join(prefix, "node_modules", node.name);
+            log("fetch: %s@%s ← %s", node.name, node.version, node.tarballUrl);
+            const bytes = await fetchTarball(node.tarballUrl, {
+                npmrc,
+                integrity: node.integrity,
+            });
+            fs.rmSync(dest, { recursive: true, force: true });
+            fs.mkdirSync(dest, { recursive: true });
+            await extractTarball(bytes, dest);
+        }
+    }
+}
+
+async function linkBins(nodes: ResolvedNode[], prefix: string, log: Logger): Promise<void> {
+    const binDir = path.join(prefix, "node_modules", ".bin");
+    let created = 0;
+    for (const node of nodes) {
+        if (!node.bin) continue;
+        const map = normalizeBin(node.name, node.bin);
+        if (map.size === 0) continue;
+        fs.mkdirSync(binDir, { recursive: true });
+        for (const [binName, binTarget] of map) {
+            const targetAbs = path.join(prefix, "node_modules", node.name, binTarget);
+            if (!fs.existsSync(targetAbs)) continue;
+            try {
+                fs.chmodSync(targetAbs, 0o755);
+            } catch {
+                /* best effort */
+            }
+            const linkPath = path.join(binDir, binName);
+            fs.rmSync(linkPath, { force: true });
+            const rel = path.relative(binDir, targetAbs);
+            try {
+                fs.symlinkSync(rel, linkPath);
+                created++;
+            } catch {
+                fs.copyFileSync(targetAbs, linkPath);
+                fs.chmodSync(linkPath, 0o755);
+                created++;
+            }
+        }
+    }
+    if (created > 0) log("bin: linked %d entry(ies) under .bin/", created);
+}
+
+function normalizeBin(pkgName: string, bin: string | Record<string, string>): Map<string, string> {
+    const out = new Map<string, string>();
+    if (typeof bin === "string") {
+        // String form is shorthand for `{ <last-segment-of-pkgName>: <bin> }`.
+        const baseName = pkgName.startsWith("@")
+            ? pkgName.slice(pkgName.indexOf("/") + 1)
+            : pkgName;
+        out.set(baseName, bin);
+        return out;
+    }
+    for (const [k, v] of Object.entries(bin)) out.set(k, v);
+    return out;
+}
+
+async function loadNpmrc(opts: InstallOptions): Promise<NpmrcConfig> {
+    const home = os.homedir();
+    const homeRc = path.join(home, ".npmrc");
+    let parsed: NpmrcConfig = {
+        registry: opts.registry ?? DEFAULT_REGISTRY,
+        scopes: {},
+        authTokens: {},
+        basicAuth: {},
+    };
+    if (fs.existsSync(homeRc)) {
+        try {
+            parsed = parseNpmrc(fs.readFileSync(homeRc, "utf-8"));
+        } catch (e) {
+            // Don't let a busted .npmrc prevent installs from anonymous registries.
+            console.warn(`gjsify install: ignoring malformed ${homeRc}: ${(e as Error).message}`);
+        }
+    }
+    if (opts.registry) {
+        parsed.registry = opts.registry;
+    }
+    return parsed;
+}
+
+type Logger = (fmt: string, ...args: unknown[]) => void;
+
+function makeLogger(verbose: boolean): Logger {
+    if (!verbose) {
+        return () => {
+            /* silent unless verbose */
+        };
+    }
+    return (fmt, ...args) => {
+        const msg = fmt.replace(/%s|%d/g, () => String(args.shift()));
+        process.stderr.write(`gjsify install: ${msg}\n`);
+    };
+}

package/src/utils/install-backend.ts

@@ -1,12 +1,14 @@
-// Install backend abstraction — Phase-4 seam.
+// Install backend abstraction.
 //
-// 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`.
+// Default: native backend (resolves packuments via @gjsify/npm-registry,
+// extracts tarballs via @gjsify/tar — no Node, no npm required at runtime).
+// Fallback: `npm install --no-package-lock --no-audit --no-fund --prefix <dir> <specs...>`,
+// for parity with the legacy code path. 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).
+// `gjsify dlx` uses this seam — installing under a cache prefix, with no
+// package.json update to the user's project. The native backend matches that
+// workflow without ever shelling out to Node.
 //
 // `--no-package-lock` keeps the cache prepare dir hermetic; the cache key
 // already covers reproducibility. `--no-audit --no-fund` cuts ~5s off cold runs.
@@ -24,17 +26,24 @@ export interface InstallOptions {
     verbose?: boolean;
     /** Optional registry override (writes a temp `.npmrc` in prefix). */
     registry?: string;
+    /**
+     * Native backend only: write `<prefix>/gjsify-lock.json` after a successful
+     * resolve. When the file exists on next call AND `frozen: true`, the
+     * resolver is skipped and downloads use the pinned tarball URL + integrity.
+     */
+    lockfile?: boolean;
+    /** Use `<prefix>/gjsify-lock.json` as the source of truth — fail if missing. */
+    frozen?: boolean;
 }
 
-const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'npm';
+const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
 
 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.',
-        );
+    if (DEFAULT_BACKEND === 'npm') {
+        return installViaNpm(opts);
     }
-    return installViaNpm(opts);
+    const { installPackagesNative } = await import('./install-backend-native.js');
+    return installPackagesNative(opts);
 }
 
 async function installViaNpm({ prefix, specs, verbose, registry }: InstallOptions): Promise<void> {