@gjsify/cli 0.3.7 → 0.3.8

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.7",
+  "version": "0.3.8",
   "description": "CLI for Gjsify",
   "type": "module",
   "main": "lib/index.js",
@@ -23,11 +23,14 @@
     "cli"
   ],
   "dependencies": {
-    "@gjsify/create-app": "^0.3.7",
-    "@gjsify/esbuild-plugin-gjsify": "^0.3.7",
-    "@gjsify/node-polyfills": "^0.3.7",
-    "@gjsify/resolve-npm": "^0.3.7",
-    "@gjsify/web-polyfills": "^0.3.7",
+    "@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/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> {