jpm-pkg 1.0.6 → 1.0.7

package/bin/jpm.js

@@ -175,9 +175,13 @@ const COMMANDS = {
     audit: () => require('../src/commands/audit'),
     run: () => require('../src/commands/run'),
     init: () => require('../src/commands/init'),
-    create: () => require('../src/commands/init'),
-    show: () => require('../src/commands/info'),
+    create: () => require('../src/commands/create'),
+    info: () => require('../src/commands/info'),
     view: () => require('../src/commands/info'),
+    doctor: () => require('../src/commands/doctor'),
+    why: () => require('../src/commands/why'),
+    rebuild: () => require('../src/commands/rebuild'),
+    link: () => require('../src/commands/link'),
     list: () => require('../src/commands/list'),
     ls: () => require('../src/commands/list'),
     exec: () => require('../src/commands/x'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jpm-pkg",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Joint Package Manager — Joint, universal, advanced, and blazing fast package manager for Node.js and Bun.",
   "main": "src/index.js",
   "type": "commonjs",
@@ -34,9 +34,7 @@
     "url": "https://github.com/SulmaneDev/jpm/issues"
   },
   "homepage": "https://github.com/SulmaneDev/jpm#readme",
-  "dependencies": {
-    "tar": "^6.2.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "jest": "^29.7.0"
   },

package/src/commands/audit.js

@@ -19,7 +19,7 @@ class AuditCommand extends BaseCommand {
      * Executes the security audit.
      * 
      * @param {string[]} args - Optional arguments
-     * @param {Object} flags - CLI flags (e.g., --level)
+     * @param {Object} flags - CLI flags (e.g., --level, --fix)
      * @returns {Promise<void>}
      */
     async run(args, flags) {
@@ -34,10 +34,12 @@ class AuditCommand extends BaseCommand {
                 // Handle scoped packages (@org/pkg)
                 if (entry.name.startsWith('@') && entry.isDirectory()) {
                     const scopeDir = path.join(nodeModules, entry.name);
-                    for (const scoped of fs.readdirSync(scopeDir, { withFileTypes: true })) {
-                        const pkgJsonPath = path.join(scopeDir, scoped.name, 'package.json');
-                        this._tryAddPackage(pkgJsonPath, installed);
-                    }
+                    try {
+                        for (const scoped of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+                            const pkgJsonPath = path.join(scopeDir, scoped.name, 'package.json');
+                            this._tryAddPackage(pkgJsonPath, installed);
+                        }
+                    } catch (e) { /* skip */ }
                 } else if (entry.isDirectory() && !entry.name.startsWith('.')) {
                     const pkgJsonPath = path.join(nodeModules, entry.name, 'package.json');
                     this._tryAddPackage(pkgJsonPath, installed);
@@ -55,7 +57,37 @@ class AuditCommand extends BaseCommand {
 
         auditSec.formatAuditResults({ vulnerabilities, stats, total, error });
 
-        if (total > 0) {
+        // Handle --fix
+        if (vulnerabilities.length > 0 && flags.fix) {
+            const fixable = vulnerabilities.filter(v => v.fixedIn && v.package !== 'undefined');
+            if (fixable.length > 0) {
+                this.logger.log('');
+                this.logger.info(`Attempting to fix ${fixable.length} vulnerabilities...`);
+
+                const Engine = require('../core/engine');
+                const engine = new Engine(cwd);
+
+                // Deduplicate and prepare package specs
+                const seen = new Set();
+                const toInstall = [];
+                for (const v of fixable) {
+                    if (seen.has(v.package)) continue;
+                    seen.add(v.package);
+                    toInstall.push({ name: v.package, version: v.fixedIn });
+                }
+
+                try {
+                    await engine.install(toInstall, { flags });
+                    this.logger.success(`Applied security patches for ${toInstall.length} packages.`);
+                } catch (err) {
+                    this.logger.error(`Failed to apply fixes: ${err.message}`);
+                }
+            } else {
+                this.logger.info('No automated fixes available for these vulnerabilities.');
+            }
+        }
+
+        if (total > 0 && !flags.fix) {
             process.exitCode = 1;
         }
     }

package/src/commands/create.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const BaseCommand = require('./base-command');
+const ExecCommand = require('./x');
+
+/**
+ * CreateCommand handles project scaffolding.
+ * It's a specialized wrapper around 'jpm x' (exec) that defaults to 'create-' prefixed packages.
+ * For example: 'jpm create vite' will execute 'create-vite'.
+ */
+class CreateCommand extends BaseCommand {
+    constructor() {
+        super('create');
+    }
+
+    /**
+     * Executes the scaffolding process.
+     * 
+     * @param {string[]} args - Template name and optional generator arguments
+     * @param {Object} flags - CLI flags
+     * @returns {Promise<void>}
+     */
+    async run(args, flags) {
+        if (!args.length) {
+            this.logger.error('Usage: jpm create <template> [options]');
+            this.logger.log('Example: jpm create vite');
+            return;
+        }
+
+        const template = args[0];
+        // Convention: 'create-xxx' packages are used for scaffolding
+        const pkgName = template.includes('/') || template.startsWith('create-')
+            ? template
+            : `create-${template}`;
+
+        const remainingArgs = args.slice(1);
+
+        this.logger.info(`Scaffolding project using ${this.logger.c.cyan(pkgName)}...`);
+
+        /** @type {ExecCommand} */
+        const exec = new ExecCommand();
+
+        // Inherit config and logger from this command
+        exec.config = this.config;
+        exec.logger = this.logger;
+
+        try {
+            // jpm create vite app-name -- --template react
+            // We pass the package name and all following arguments to ExecCommand
+            await exec.run([pkgName, ...remainingArgs], flags);
+        } catch (err) {
+            this.logger.error(`Scaffolding failed: ${err.message}`);
+        }
+    }
+}
+
+module.exports = CreateCommand;

package/src/commands/doctor.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const BaseCommand = require('./base-command');
+const http = require('../utils/http');
+const registry = require('../core/registry');
+
+/**
+ * DoctorCommand handles the 'jpm doctor' command.
+ * It performs various health checks on the environment and project.
+ */
+class DoctorCommand extends BaseCommand {
+    constructor() {
+        super('doctor');
+    }
+
+    /**
+     * Executes the health checks.
+     * 
+     * @param {string[]} args - CLI arguments (unused)
+     * @param {Object} flags - CLI flags
+     * @returns {Promise<void>}
+     */
+    async run(args, flags) {
+        this.logger.section('JPM Doctor — Environment Health Check');
+
+        const c = this.logger.c;
+        let issues = 0;
+
+        // 1. Check Node.js Environment
+        const nodeVersion = process.version;
+        const platform = process.platform;
+        this.logger.log(`${c.cyan('Node.js')}    ${nodeVersion} (${platform})`);
+
+        const major = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+        if (major < 18) {
+            this.logger.warn(`  ! JPM recommends Node.js v18 or higher (found ${nodeVersion})`);
+            issues++;
+        }
+
+        // 2. Check Registry Connectivity
+        const registryUrl = this.config.get('registry');
+        this.logger.log(`${c.cyan('Registry')}   ${registryUrl}`);
+        try {
+            const start = Date.now();
+            await http.getJSON(`${registryUrl.replace(/\/$/, '')}/ping`);
+            const latency = Date.now() - start;
+            this.logger.log(`  ${c.green('✓')} Connected (${latency}ms)`);
+        } catch (err) {
+            this.logger.error(`  ${c.red('✖')} Could not connect to registry: ${err.message}`);
+            issues++;
+        }
+
+        // 3. Check Cache Directory
+        const cacheDir = this.config.cacheDir;
+        this.logger.log(`${c.cyan('Cache Dir')}  ${cacheDir}`);
+        try {
+            if (!fs.existsSync(cacheDir)) {
+                this.logger.log('  - Directory does not exist (will be created on first use)');
+            } else {
+                fs.accessSync(cacheDir, fs.constants.R_OK | fs.constants.W_OK);
+                const stats = fs.statSync(cacheDir);
+                this.logger.log(`  ${c.green('✓')} Writable (${stats.mode.toString(8)})`);
+            }
+        } catch (err) {
+            this.logger.error(`  ${c.red('✖')} Cache directory is not accessible: ${err.message}`);
+            issues++;
+        }
+
+        // 4. Check Local Project
+        const projectRoot = this.config.get('prefix') || process.cwd();
+        const pkgFile = path.join(projectRoot, 'package.json');
+        this.logger.log(`${c.cyan('Project')}    ${projectRoot}`);
+        if (fs.existsSync(pkgFile)) {
+            this.logger.log(`  ${c.green('✓')} package.json found`);
+        } else {
+            this.logger.warn('  ! No package.json found in current directory');
+            // Not necessarily an issue for a global check, but worth noting
+        }
+
+        this.logger.log('');
+        if (issues === 0) {
+            this.logger.success('Your environment is healthy! No issues found.');
+        } else {
+            this.logger.warn(`Found ${issues} potential issue(s). Check the logs above.`);
+        }
+    }
+}
+
+module.exports = DoctorCommand;

package/src/commands/install.js

@@ -1,10 +1,6 @@
 'use strict';
 
 const BaseCommand = require('./base-command');
-const Resolver = require('../core/resolver');
-const Installer = require('../core/installer');
-const Lockfile = require('../core/lockfile');
-const PackageJSON = require('../core/package-json');
 const { Spinner } = require('../utils/progress');
 
 /**
@@ -25,8 +21,9 @@ class InstallCommand extends BaseCommand {
      */
     async run(args, flags) {
         const cwd = process.cwd();
-        const pkgJson = PackageJSON.fromDir(cwd);
-        const lockfile = new Lockfile(cwd);
+        const Engine = require('../core/engine');
+        const engine = new Engine(cwd);
+
         const isDev = flags.D || flags['save-dev'];
         const isExact = flags.E || flags['save-exact'] || this.config.saveExact;
         const noSave = flags['no-save'];
@@ -45,95 +42,34 @@ class InstallCommand extends BaseCommand {
                 toInstall.push({ name, version });
             }
         } else {
-            // General install from package.json
-            const spinner = new Spinner('Reading package.json...').start();
+            // General install from package.json/lockfile
+            if (engine.lockfile.exists()) {
+                await engine.installFromLock(flags);
+                return;
+            }
+
             const allDeps = {
-                ...pkgJson.dependencies,
-                ...(flags.production ? {} : pkgJson.devDependencies),
+                ...engine.pkgJson.dependencies,
+                ...(flags.production ? {} : engine.pkgJson.devDependencies),
             };
-            spinner.succeed(`Found ${Object.keys(allDeps).length} dependencies`);
 
-            // Deterministic install from lockfile if it exists and no arguments provided
-            if (lockfile.exists()) {
-                this.logger.info('Using lock file for deterministic install');
-                const lockData = lockfile.allPackages();
-                const installer = new Installer(cwd);
-                const bar = new Spinner('Installing from lock file...');
-                bar.start();
-                const fakeMap = new Map(lockData.map(p => [`${p.name}@${p.version}`, p]));
-                await installer.installAll(fakeMap, { dryRun, flags });
-                bar.succeed(`Installed ${lockData.length} packages`);
+            if (!Object.keys(allDeps).length) {
+                this.logger.info('Nothing to install.');
                 return;
             }
 
             toInstall = Object.entries(allDeps).map(([name, version]) => ({ name, version }));
         }
 
-        if (!toInstall.length) {
-            this.logger.info('Nothing to install.');
-            return;
-        }
-
-        // ── Resolve ────────────────────────────────────────────────────────────────
-        const resolveSpinner = new Spinner(`Resolving ${toInstall.length} package(s)...`).start();
-        const resolver = new Resolver();
-
-        const deps = {};
-        const devDeps = {};
-        for (const { name, version } of toInstall) {
-            if (isDev) devDeps[name] = version;
-            else deps[name] = version;
-        }
-
-        let resolvedMap;
-        try {
-            resolvedMap = await resolver.resolve(deps, devDeps, {}, (count, total) => {
-                resolveSpinner.text = `Resolving packages... (${count} resolved)`;
-            });
-            resolveSpinner.succeed(`Resolved ${resolvedMap.size} packages (including transitive deps)`);
-        } catch (err) {
-            resolveSpinner.fail(`Resolution failed: ${err.message}`);
-            throw err; // Let caller handle exit
-        }
-
-        // Warn about circular deps
-        const circular = resolver.findCircular();
-        if (circular.length) {
-            this.logger.warn(`Circular dependencies detected:\n  ${circular.join('\n  ')}`);
-        }
-
-        // ── Install ────────────────────────────────────────────────────────────────
-        this.logger.info(`Installing ${resolvedMap.size} packages...`);
-        const installer = new Installer(cwd);
-        try {
-            await installer.installAll(resolvedMap, { dryRun, flags });
-        } catch (err) {
-            this.logger.error(`Install failed: ${err.message}`);
-            throw err;
-        }
-
-        // ── Update package.json & lock file ─────────────────────────────────────────
-        if (!noSave && !dryRun && args.length) {
-            for (const { name } of toInstall) {
-                const resolved = [...resolvedMap.values()].find(m => m.name === name);
-                if (!resolved) continue;
-                pkgJson.addDependency(name, resolved.version, { dev: !!isDev, exact: isExact });
-            }
-            pkgJson.save();
-            this.logger.verbose('Updated package.json');
-        }
-
-        if (!dryRun) {
-            lockfile.update(resolvedMap).save();
-            this.logger.verbose('Updated jpm-lock.json');
-        }
+        // ── Core Installation Flow ────────────────────────────────────────────────
+        const resolvedMap = await engine.install(toInstall, {
+            dev: !!isDev,
+            exact: !!isExact,
+            noSave: !!noSave,
+            flags
+        });
 
         // ── Summary ────────────────────────────────────────────────────────────────
-        const dupes = resolver.deduplicate();
-        if (dupes.length) {
-            this.logger.verbose(`Deduplication: ${dupes.length} packages have multiple versions`);
-        }
-
         const directly = toInstall.map(({ name }) => {
             const r = [...resolvedMap.values()].find(m => m.name === name);
             return r ? `${r.name}@${r.version}` : name;

package/src/commands/link.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const BaseCommand = require('./base-command');
+const { mkdirp, symlink } = require('../utils/fs');
+const PackageJSON = require('../core/package-json');
+
+/**
+ * LinkCommand handles 'jpm link' and 'jpm link <package>'.
+ * Facilitates local package development by creating symbolic links between projects.
+ * Similar to 'npm link'.
+ */
+class LinkCommand extends BaseCommand {
+    constructor() {
+        super('link');
+        /** @type {string} */
+        this.globalLinkDir = path.join(os.homedir(), '.jpm', 'links');
+    }
+
+    /**
+     * Executes the linking process.
+     * 
+     * @param {string[]} args - Optional package name to link into current project
+     * @param {Object} flags - CLI flags
+     * @returns {Promise<void>}
+     */
+    async run(args, flags) {
+        const cwd = process.cwd();
+
+        if (args.length === 0) {
+            // Step 1: Run 'jpm link' in the package directory to register it globally
+            await this._linkGlobal(cwd);
+        } else {
+            // Step 2: Run 'jpm link <pkg>' in the consumer project to use the linked package
+            for (const pkgName of args) {
+                await this._linkToProject(pkgName, cwd);
+            }
+        }
+    }
+
+    /**
+     * Registers a local package directory in the global JPM links folder.
+     * 
+     * @param {string} pkgDir - Absolute path to the package directory
+     * @returns {Promise<void>}
+     * @private
+     */
+    async _linkGlobal(pkgDir) {
+        let pkg;
+        try {
+            pkg = PackageJSON.fromDir(pkgDir);
+        } catch (err) {
+            this.logger.error(`Could not read package.json in ${pkgDir}`);
+            return;
+        }
+
+        mkdirp(this.globalLinkDir);
+        const dest = path.join(this.globalLinkDir, pkg.name);
+
+        this.logger.info(`Registering ${this.logger.c.cyan(pkg.name)} globally...`);
+
+        try {
+            symlink(pkgDir, dest);
+            this.logger.success(`${this.logger.c.bold(pkg.name)} linked globally to ${pkgDir}`);
+            this.logger.log(`Run ${this.logger.c.gray(`jpm link ${pkg.name}`)} in another project to use it.`);
+        } catch (err) {
+            this.logger.error(`Failed to create global link: ${err.message}`);
+        }
+    }
+
+    /**
+     * Links a globally registered package into a project's node_modules.
+     * 
+     * @param {string} pkgName - Name of the package to link
+     * @param {string} projectDir - Absolute path to the consumer project
+     * @returns {Promise<void>}
+     * @private
+     */
+    async _linkToProject(pkgName, projectDir) {
+        const globalSrc = path.join(this.globalLinkDir, pkgName);
+        if (!fs.existsSync(globalSrc)) {
+            this.logger.error(`Package "${pkgName}" is not linked globally.`);
+            this.logger.log(`Run ${this.logger.c.gray('jpm link')} inside the ${pkgName} directory first.`);
+            return;
+        }
+
+        const projectNM = path.join(projectDir, 'node_modules', pkgName);
+        this.logger.info(`Linking ${this.logger.c.cyan(pkgName)} into project...`);
+
+        try {
+            symlink(globalSrc, projectNM);
+            this.logger.success(`${this.logger.c.bold(pkgName)} linked to ${this.logger.c.gray(projectNM)}`);
+        } catch (err) {
+            this.logger.error(`Failed to link ${pkgName}: ${err.message}`);
+        }
+    }
+}
+
+module.exports = LinkCommand;

package/src/commands/rebuild.js

@@ -0,0 +1,115 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const BaseCommand = require('./base-command');
+const { Spinner } = require('../utils/progress');
+
+/**
+ * RebuildCommand handles the 'jpm rebuild' command.
+ * It re-runs lifecycle scripts (preinstall, install, postinstall) for installed packages.
+ */
+class RebuildCommand extends BaseCommand {
+    constructor() {
+        super('rebuild');
+    }
+
+    /**
+     * Executes the rebuild process across node_modules.
+     * 
+     * @param {string[]} args - Optional package names to limit the rebuild to
+     * @param {Object} flags - CLI flags
+     * @returns {Promise<void>}
+     */
+    async run(args, flags) {
+        const cwd = process.cwd();
+        const nmDir = path.join(cwd, 'node_modules');
+
+        if (!fs.existsSync(nmDir)) {
+            this.logger.error('node_modules directory not found. Run jpm install first.');
+            return;
+        }
+
+        const targets = args.length ? new Set(args) : null;
+        const scanSpinner = new Spinner('Scanning node_modules for scripts...').start();
+
+        const pkgsWithScripts = [];
+        const entries = fs.readdirSync(nmDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            // Skip non-package entries (like .bin)
+            if (entry.name.startsWith('.')) continue;
+
+            if (entry.name.startsWith('@')) {
+                // Handle scoped packages
+                const scopeDir = path.join(nmDir, entry.name);
+                try {
+                    const scopedEntries = fs.readdirSync(scopeDir, { withFileTypes: true });
+                    for (const scopedEntry of scopedEntries) {
+                        this._checkPkg(path.join(scopeDir, scopedEntry.name), pkgsWithScripts, targets);
+                    }
+                } catch (e) { /* ignore read errors */ }
+            } else {
+                this._checkPkg(path.join(nmDir, entry.name), pkgsWithScripts, targets);
+            }
+        }
+
+        scanSpinner.succeed(`Found ${pkgsWithScripts.length} package(s) with lifecycle scripts.`);
+
+        if (pkgsWithScripts.length === 0) {
+            this.logger.info('No lifecycle scripts found to run.');
+            return;
+        }
+
+        for (const { name, dir, scripts } of pkgsWithScripts) {
+            // Lifecycle scripts run in specific order: preinstall -> install -> postinstall
+            for (const hook of ['preinstall', 'install', 'postinstall']) {
+                if (scripts[hook]) {
+                    this.logger.section(`▶ ${this.logger.c.cyan(name)} — ${hook}`);
+                    const result = spawnSync(scripts[hook], {
+                        cwd: dir,
+                        shell: true,
+                        stdio: 'inherit',
+                        env: { ...process.env, PATH: `${path.join(nmDir, '.bin')}${path.delimiter}${process.env.PATH}` }
+                    });
+
+                    if (result.status !== 0) {
+                        this.logger.warn(`Script "${hook}" in ${name} failed with exit code ${result.status}`);
+                    }
+                }
+            }
+        }
+
+        this.logger.success('Rebuild complete!');
+    }
+
+    /**
+     * Checks a directory for a package.json containing lifecycle scripts.
+     * 
+     * @param {string} dir - Directory to check
+     * @param {Array} list - Array to push matching package info into
+     * @param {Set|null} targets - Optional set of package names to filter by
+     * @private
+     */
+    _checkPkg(dir, list, targets) {
+        const pkgFile = path.join(dir, 'package.json');
+        if (!fs.existsSync(pkgFile)) return;
+
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgFile, 'utf8'));
+            if (targets && !targets.has(pkg.name)) return;
+
+            const scripts = pkg.scripts || {};
+            const hasScripts = scripts.install || scripts.preinstall || scripts.postinstall;
+
+            if (hasScripts) {
+                list.push({ name: pkg.name, dir, scripts });
+            }
+        } catch (err) {
+            // skip invalid or unreadable package.json
+        }
+    }
+}
+
+module.exports = RebuildCommand;

package/src/commands/update.js

@@ -1,7 +1,6 @@
 'use strict';
 
 const BaseCommand = require('./base-command');
-const PackageJSON = require('../core/package-json');
 const registry = require('../core/registry');
 const semver = require('../utils/semver');
 const { Spinner } = require('../utils/progress');
@@ -24,8 +23,10 @@ class UpdateCommand extends BaseCommand {
      */
     async run(args, flags) {
         const cwd = process.cwd();
-        const pkgJson = PackageJSON.fromDir(cwd);
-        const allDeps = pkgJson.allDeps();
+        const Engine = require('../core/engine');
+        const engine = new Engine(cwd);
+
+        const allDeps = engine.pkgJson.allDeps();
 
         const targets = args.length
             ? args.reduce((acc, n) => { if (allDeps[n]) acc[n] = allDeps[n]; return acc; }, {})
@@ -91,12 +92,12 @@ class UpdateCommand extends BaseCommand {
 
         this.logger.info(`Updating ${outdatedPkgs.length} package(s)...`);
 
-        // Use dynamic import/require to avoid circular dependency with InstallCommand
-        const InstallCommand = require('./install');
-        const installInstance = new InstallCommand();
+        const pkgArgs = outdatedPkgs.map(p => ({
+            name: p.Package,
+            version: p.Latest
+        }));
 
-        const pkgArgs = outdatedPkgs.map(p => `${p.Package}@${p.Latest}`);
-        await installInstance.run(pkgArgs, flags);
+        await engine.install(pkgArgs, { flags });
     }
 }
 

package/src/commands/why.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const BaseCommand = require('./base-command');
+const Lockfile = require('../core/lockfile');
+const PackageJSON = require('../core/package-json');
+
+/**
+ * WhyCommand handles the 'jpm why <pkg>' command.
+ * It traces dependency paths to explain why a package is installed.
+ */
+class WhyCommand extends BaseCommand {
+    constructor() {
+        super('why');
+    }
+
+    /**
+     * Executes the dependency tracing.
+     * 
+     * @param {string[]} args - Package name to trace
+     * @param {Object} flags - CLI flags
+     * @returns {Promise<void>}
+     */
+    async run(args, flags) {
+        if (!args.length) {
+            this.logger.error('Usage: jpm why <package>');
+            return;
+        }
+
+        const target = args[0];
+        const cwd = process.cwd();
+        const lockfile = new Lockfile(cwd);
+        const pkgJson = PackageJSON.fromDir(cwd);
+
+        if (!lockfile.exists()) {
+            this.logger.error('No lockfile found. Run jpm install first.');
+            return;
+        }
+
+        const lockData = lockfile.allPackages();
+        // Index by name for easier lookup
+        const pkgMap = new Map();
+        for (const p of lockData) {
+            pkgMap.set(p.name, p);
+        }
+
+        const topLevel = pkgJson.allDeps();
+        const paths = [];
+        const seen = new Set();
+
+        /**
+         * Recursively searches for the target package in the dependency tree.
+         * 
+         * @param {string} currentName - Current package being inspected
+         * @param {string[]} currentPath - Breadcrumb path to the current package
+         */
+        const findPaths = (currentName, currentPath = []) => {
+            const pathKey = [...currentPath, currentName].join('>');
+            if (seen.has(pathKey)) return;
+            seen.add(pathKey);
+
+            if (currentName === target) {
+                paths.push([...currentPath, target]);
+                return;
+            }
+
+            const pkg = pkgMap.get(currentName);
+            if (!pkg || !pkg.dependencies) return;
+
+            for (const dep of Object.keys(pkg.dependencies)) {
+                // Generic cycle protection: don't revisit same package in current path
+                if (currentPath.includes(dep)) continue;
+                findPaths(dep, [...currentPath, currentName]);
+            }
+        };
+
+        for (const root of Object.keys(topLevel)) {
+            findPaths(root, ['(project)']);
+        }
+
+        if (paths.length === 0) {
+            this.logger.info(`Package "${this.logger.c.bold(target)}" is not required by any installed package.`);
+            return;
+        }
+
+        const c = this.logger.c;
+        this.logger.section(`Found ${paths.length} path(s) to ${c.bold(target)}:`);
+
+        for (const path of paths) {
+            const formatted = path.map((p, i) => {
+                if (p === '(project)') return c.gray(p);
+                if (p === target) return c.yellow(c.bold(p));
+                return c.cyan(p);
+            }).join(c.gray(' → '));
+
+            this.logger.log(`  ${formatted}`);
+        }
+    }
+}
+
+module.exports = WhyCommand;

package/src/commands/x.js

@@ -101,20 +101,37 @@ class ExecCommand extends BaseCommand {
 
             // Cleanup temp directory on success unless debugging
             if (result.status === 0 && this.config.loglevel !== 'debug') {
-                rimraf(tmpDir);
+                this._cleanupTemp(tmpDir);
             }
 
             process.exit(result.status ?? 0);
 
         } catch (err) {
             if (tmpDir && fs.existsSync(tmpDir) && this.config.loglevel !== 'debug') {
-                rimraf(tmpDir);
+                this._cleanupTemp(tmpDir);
             }
             resolveSpinner.fail(`Error: ${err.message}`);
             throw err;
         }
     }
 
+    /**
+     * Safely cleans up a temporary directory, handling Windows junctions and symlinks.
+     * 
+     * @param {string} tmpDir - Path to the temporary directory
+     * @private
+     */
+    _cleanupTemp(tmpDir) {
+        try {
+            // On Windows, junctions inside node_modules can sometimes block rimraf
+            // if not handled carefully. Our internal rimraf handles recursive delete,
+            // but we add an extra safety check here.
+            rimraf(tmpDir);
+        } catch (err) {
+            this.logger.debug(`Minor: Failed to cleanup temp directory ${tmpDir}: ${err.message}`);
+        }
+    }
+
     /**
      * Identifies the primary binary name from package metadata.
      * 

package/src/core/cache.js

@@ -54,6 +54,28 @@ class Cache {
         return path.join(this.cacheRoot, safeName, `${version}.json`);
     }
 
+    /**
+     * Initializes a SQLite database for metadata caching if running in Bun.
+     * 
+     * @returns {Object|null} The SQLite database instance or null
+     * @private
+     */
+    _getSQLite() {
+        if (typeof Bun === 'undefined') return null;
+        if (this._db) return this._db;
+
+        try {
+            const { Database } = require('bun:sqlite');
+            const dbPath = path.join(this.cacheRoot, 'cache.sqlite');
+            mkdirp(this.cacheRoot);
+            this._db = new Database(dbPath);
+            this._db.run('CREATE TABLE IF NOT EXISTS metadata (id TEXT PRIMARY KEY, data TEXT)');
+            return this._db;
+        } catch (e) {
+            return null;
+        }
+    }
+
     /**
      * Retrieves a package tarball from the cache if it exists.
      * 
@@ -94,6 +116,13 @@ class Cache {
      * @returns {Promise<void>}
      */
     async setMeta(name, version, meta) {
+        const db = this._getSQLite();
+        if (db) {
+            try {
+                db.run('INSERT OR REPLACE INTO metadata (id, data) VALUES (?, ?)', [`${name}@${version}`, JSON.stringify(meta)]);
+            } catch (e) { /* fallback */ }
+        }
+
         const p = this._metaPath(name, version);
         mkdirp(path.dirname(p));
         fs.writeFileSync(p, JSON.stringify(meta, null, 2), 'utf8');
@@ -107,6 +136,14 @@ class Cache {
      * @returns {Promise<Object|null>} Decoded metadata object, or null if not found/invalid
      */
     async getMeta(name, version) {
+        const db = this._getSQLite();
+        if (db) {
+            try {
+                const row = db.query('SELECT data FROM metadata WHERE id = ?').get(`${name}@${version}`);
+                if (row) return JSON.parse(row.data);
+            } catch (e) { /* fallback */ }
+        }
+
         const p = this._metaPath(name, version);
         try {
             return JSON.parse(fs.readFileSync(p, 'utf8'));

package/src/core/engine.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const path = require('node:path');
+const Resolver = require('./resolver');
+const Installer = require('./installer');
+const Lockfile = require('./lockfile');
+const PackageJSON = require('./package-json');
+const logger = require('../utils/logger');
+const { Spinner } = require('../utils/progress');
+
+/**
+ * Engine class coordinates the higher-level package management operations.
+ * It ties together resolution, installation, and persistence logic.
+ */
+class Engine {
+    /**
+     * @param {string} projectRoot - The absolute path to the project root directory
+     */
+    constructor(projectRoot) {
+        /** @type {string} */
+        this.projectRoot = projectRoot;
+        /** @type {PackageJSON} */
+        this.pkgJson = PackageJSON.fromDir(projectRoot);
+        /** @type {Lockfile} */
+        this.lockfile = new Lockfile(projectRoot);
+        /** @type {Installer} */
+        this.installer = new Installer(projectRoot);
+    }
+
+    /**
+     * Executes a full installation flow for a set of packages.
+     * 
+     * @param {Array<{name: string, version: string}>} packages - Packages to install
+     * @param {Object} options - Installation options
+     * @param {boolean} [options.dev=false] - Whether to install as devDependencies
+     * @param {boolean} [options.exact=false] - Whether to save as exact versions
+     * @param {boolean} [options.noSave=false] - Whether to skip updating package.json
+     * @param {Object} [options.flags={}] - CLI flags
+     * @returns {Promise<Map<string, Object>>} The resolved package map
+     */
+    async install(packages, options = {}) {
+        const { dev = false, exact = false, noSave = false, flags = {} } = options;
+
+        // 1. Resolve
+        const resolveSpinner = new Spinner(`Resolving ${packages.length} package(s)...`).start();
+        const resolver = new Resolver();
+
+        const deps = {};
+        const devDeps = {};
+        for (const { name, version } of packages) {
+            if (dev) devDeps[name] = version;
+            else deps[name] = version;
+        }
+
+        let resolvedMap;
+        try {
+            resolvedMap = await resolver.resolve(deps, devDeps, {}, (count) => {
+                resolveSpinner.text = `Resolving packages... (${count} resolved)`;
+            });
+            resolveSpinner.succeed(`Resolved ${resolvedMap.size} packages`);
+        } catch (err) {
+            resolveSpinner.fail(`Resolution failed: ${err.message}`);
+            throw err;
+        }
+
+        // 2. Audit for cycles
+        const circular = resolver.findCircular();
+        if (circular.length) {
+            logger.warn(`Circular dependencies detected:\n  ${circular.join('\n  ')}`);
+        }
+
+        // 3. Install
+        logger.info(`Installing ${resolvedMap.size} packages...`);
+        try {
+            await this.installer.installAll(resolvedMap, { dryRun: flags['dry-run'], flags });
+        } catch (err) {
+            logger.error(`Install failed: ${err.message}`);
+            throw err;
+        }
+
+        // 4. Persist Changes
+        if (!noSave && !flags['dry-run'] && packages.length) {
+            for (const { name } of packages) {
+                const resolved = [...resolvedMap.values()].find(m => m.name === name);
+                if (!resolved) continue;
+                this.pkgJson.addDependency(name, resolved.version, { dev, exact });
+            }
+            this.pkgJson.save();
+            logger.verbose('Updated package.json');
+        }
+
+        if (!flags['dry-run']) {
+            this.lockfile.update(resolvedMap).save();
+            logger.verbose('Updated jpm-lock.json');
+        }
+
+        return resolvedMap;
+    }
+
+    /**
+     * Performs a deterministic install from the lockfile.
+     * 
+     * @param {Object} [flags={}] - CLI flags
+     * @returns {Promise<void>}
+     */
+    async installFromLock(flags = {}) {
+        if (!this.lockfile.exists()) {
+            throw new Error('No lockfile found. Run jpm install first.');
+        }
+
+        logger.info('Using lock file for deterministic install');
+        const lockData = this.lockfile.allPackages();
+        const spinner = new Spinner('Installing from lock file...').start();
+
+        const fakeMap = new Map(lockData.map(p => [`${p.name}@${p.version}`, p]));
+        await this.installer.installAll(fakeMap, { dryRun: flags['dry-run'], flags });
+
+        spinner.succeed(`Installed ${lockData.length} packages`);
+    }
+}
+
+module.exports = Engine;

package/src/core/installer.js

@@ -3,7 +3,6 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const tar = require('tar');
 const registry = require('./registry');
 const cache = require('./cache');
 const { mkdirp, rimraf, tempDir, symlink } = require('../utils/fs');
@@ -170,28 +169,56 @@ class Installer {
     }
 
     /**
-     * Extracts a tarball to the destination directory.
+     * Extracts a tarball's contents into a target directory.
+     * Prioritizes system 'tar' for speed and to minimize dependency overhead.
      * 
-     * @param {string} tgzPath - Path to the tarball file
+     * @param {string} tgzPath - Absolute path to the source .tgz file
      * @param {string} destDir - Target directory for extraction
-     * @param {string} name - Package name for logging
-     * @param {string} version - Package version for logging
+     * @param {string} name - Package name for error context
+     * @param {string} version - Package version for error context
+     * @returns {Promise<void>}
      * @protected
      */
     async _extract(tgzPath, destDir, name, version) {
         rimraf(destDir);
         mkdirp(destDir);
 
-        const absoluteDest = path.resolve(destDir);
+        try {
+            // Attempt to use system 'tar' (available on Linux, macOS, and Win 10+)
+            const { spawnSync } = require('node:child_process');
+            const result = spawnSync('tar', [
+                '-xzf', tgzPath,
+                '-C', destDir,
+                '--strip-components=1'
+            ], { shell: true, stdio: 'pipe' });
+
+            if (result.status === 0) {
+                logger.verbose(`extracted ${name}@${version} via system tar`);
+                return;
+            }
+            logger.debug(`System tar failed (code ${result.status}): ${result.stderr.toString()}`);
+        } catch (err) {
+            logger.debug(`System tar not found or failed: ${err.message}`);
+        }
 
+        // Fallback to JS-based 'tar' package
+        logger.verbose(`falling back to 'tar' package for ${name}@${version}`);
+        let tar;
+        try {
+            tar = require('tar');
+        } catch (err) {
+            throw new Error(`Extraction failed: system 'tar' not available and 'tar' package not installed. ${err.message}`);
+        }
+
+        const absoluteDest = path.resolve(destDir);
         await tar.extract({
             file: tgzPath,
             cwd: destDir,
             strip: 1,
-            filter: (p, stat) => {
+            filter: (p) => {
                 const fullPath = path.resolve(destDir, p);
                 if (!fullPath.startsWith(absoluteDest)) {
-                    logger.error(`Zip Slip security violation blocked: ${p} in ${name}@${version}`);
+                    logger.error(`Zip Slip security violation blocked in ${name}@${version}: ${p}`);
                     return false;
                 }
                 return true;
@@ -260,6 +287,7 @@ class Installer {
      * Creates symbolic links for binary executables defined in package metadata.
      * 
      * @param {Object[]} packages - Array of resolved package metadata
+     * @returns {Promise<void>}
      * @protected
      */
     async _linkBins(packages) {
@@ -285,7 +313,9 @@ class Installer {
                 try {
                     symlink(src, dest);
                     fs.chmodSync(src, 0o755);
-                } catch { }
+                } catch (err) {
+                    logger.warn(`Failed to link binary "${binName}" for ${installName}: ${err.message}`);
+                }
             }
         }
     }

package/src/core/registry.js

@@ -149,6 +149,7 @@ class Registry {
      * 
      * @param {Object.<string, string[]>} requires - Map of package names to lists of required versions
      * @returns {Promise<Object>} Audit report containing vulnerabilities, advisories, and metadata
+     * @throws {Error} If the registry request fails or returns an invalid response
      */
     async fetchAdvisories(requires) {
         const url = `https://registry.npmjs.org/-/npm/v1/security/audits/quick`;
@@ -167,22 +168,29 @@ class Registry {
             dependencies: packages,
         });
 
-        const res = await request(url, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Content-Length': Buffer.byteLength(body),
-            },
-            body,
-            timeout: 30_000,
-            retries: 2,
-            strict: true, // Security: Always use HTTPS for audits
-        });
-
         try {
+            const res = await request(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Content-Length': Buffer.byteLength(body),
+                },
+                body,
+                timeout: 30_000,
+                retries: 2,
+                strict: true, // Security: Always use HTTPS for audits
+            });
+
+            if (res.status < 200 || res.status >= 300) {
+                throw new Error(`Registry audit failed with status ${res.status}: ${res.body.slice(0, 200)}`);
+            }
+
             return JSON.parse(res.body);
-        } catch {
-            return { advisories: {}, metadata: {} };
+        } catch (err) {
+            logger.error(`Security audit request failed: ${err.message}`);
+            // Return empty structure to allow the process to continue if non-critical,
+            // but log the error clearly.
+            return { advisories: {}, metadata: {}, error: err.message };
         }
     }
 }

package/src/utils/http.js

@@ -38,10 +38,39 @@ function checkBreaker() {
 }
 
 /**
- * options: { method, headers, timeout, retries, retryDelay, stream }
- * Returns: { status, headers, body } or a raw IncomingMessage if stream:true
+ * options: { method, headers, timeout, retries, retryDelay, stream, body, strict }
+ * Returns: { status, headers, body } or a raw IncomingMessage if stream:true.
+ * Uses Bun.fetch if running in a Bun environment for optimized performance.
+ * 
+ * @param {string} url - Target URL
+ * @param {Object} [options={}] - Request options
+ * @returns {Promise<Object|import('node:http').IncomingMessage>}
  */
-function request(url, options = {}) {
+async function request(url, options = {}) {
+    // ── Native Bun Optimization ──────────────────────────────────────────────
+    if (typeof Bun !== 'undefined' && !options.stream) {
+        try {
+            const res = await Bun.fetch(url, {
+                method: options.method || 'GET',
+                headers: {
+                    'User-Agent': USER_AGENT,
+                    'Accept-Encoding': 'gzip, deflate',
+                    'Accept': 'application/json',
+                    ...(options.headers || {}),
+                },
+                body: options.body,
+                redirect: 'follow',
+            });
+            return {
+                status: res.status,
+                headers: Object.fromEntries(res.headers.entries()),
+                body: await res.text(),
+            };
+        } catch (err) {
+            logger.debug(`Bun.fetch failed, falling back to node:http: ${err.message}`);
+        }
+    }
+
     const {
         method = 'GET',
         headers = {},
@@ -78,6 +107,12 @@ function request(url, options = {}) {
         },
     };
 
+    /**
+     * Executes a single request attempt with retries and circuit breaker logic.
+     * 
+     * @param {number} attemptsLeft - Remaining retry attempts
+     * @returns {Promise<Object|import('node:http').IncomingMessage>}
+     */
     function attempt(attemptsLeft) {
         return new Promise((resolve, reject) => {
             const req = lib.request(reqOptions, (res) => {
@@ -158,7 +193,9 @@ function request(url, options = {}) {
  * @returns {Promise<Object>} Parsed JSON object
  */
 async function getJSON(url, opts = {}) {
-    const { status, body } = await request(url, { ...opts, headers: { Accept: 'application/json', ...(opts.headers || {}) } });
+    const res = await request(url, { ...opts, headers: { Accept: 'application/json', ...(opts.headers || {}) } });
+    const { status, body } = res;
+
     if (status < 200 || status >= 300) {
         const err = new Error(`HTTP ${status}: ${url}`);
         err.status = status;
@@ -166,7 +203,7 @@ async function getJSON(url, opts = {}) {
         throw err;
     }
     try {
-        return JSON.parse(body);
+        return typeof body === 'object' ? body : JSON.parse(body);
     } catch (e) {
         throw new Error(`Invalid JSON from ${url}: ${e.message}\nBody snippet: ${body.slice(0, 200)}`);
     }
@@ -206,27 +243,4 @@ async function download(url, destStream, opts = {}) {
     });
 }
 
-/**
- * Retrieves a list of all packages currently stored in the local cache.
- * 
- * @returns {{ name: string, version: string }[]}
- */
-function list() {
-    const root = cacheRoot();
-    if (!fs.existsSync(root)) return [];
-    const result = [];
-    for (const scopeOrName of fs.readdirSync(root)) {
-        const dir = path.join(root, scopeOrName);
-        if (!fs.statSync(dir).isDirectory()) continue;
-        for (const file of fs.readdirSync(dir)) {
-            if (file.endsWith('.tgz')) {
-                const version = file.replace('.tgz', '');
-                const name = scopeOrName.replace('__SCOPE__', '/');
-                result.push({ name, version });
-            }
-        }
-    }
-    return result;
-}
-
-module.exports = { request, getJSON, download, list };
+module.exports = { request, getJSON, download };