jpm-pkg 1.0.3 → 1.0.5

package/src/commands/x.js

@@ -1,136 +1,174 @@
 'use strict';
 
+const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
+const BaseCommand = require('./base-command');
 const Resolver = require('../core/resolver');
 const Installer = require('../core/installer');
 const { tempDir, rimraf } = require('../utils/fs');
 const { Spinner } = require('../utils/progress');
-const config = require('../utils/config');
-const logger = require('../utils/logger');
 
 /**
- * jpm x <package>[@version] [args...]
- * 
- * Equivalent to npx. Resolves, installs to a temp dir, and executes.
+ * ExecCommand handles the 'jpm x' and 'jpm exec' commands (equivalent to npx).
+ * It resolves a package, installs it to a temporary directory, and executes its binary.
  */
-module.exports = async function xCommand(args, flags) {
-    if (!args.length) {
-        logger.error('No package specified to execute.');
-        logger.info('Usage: jpm x <package>[@version] [args...]');
-        process.exit(1);
+class ExecCommand extends BaseCommand {
+    constructor() {
+        super('x');
     }
 
-    const pkgArg = args[0];
-    const execArgs = args.slice(1);
-
-    const lastAt = pkgArg.lastIndexOf('@');
-    // Handle scoped packages correctly: @scope/pkg@version
-    const hasVersion = lastAt > 0 && !pkgArg.startsWith('@') || (pkgArg.startsWith('@') && pkgArg.split('@').length > 2);
-
-    let name, range;
-    if (pkgArg.startsWith('@')) {
-        const parts = pkgArg.split('@');
-        name = '@' + parts[1];
-        range = parts[2] || 'latest';
-    } else {
-        name = hasVersion ? pkgArg.slice(0, lastAt) : pkgArg;
-        range = hasVersion ? pkgArg.slice(lastAt + 1) : 'latest';
-    }
+    /**
+     * Executes the specified package binary.
+     * 
+     * @param {string[]} args - Package name and arguments for the binary
+     * @param {Object} flags - CLI flags
+     * @returns {Promise<void>}
+     */
+    async run(args, flags) {
+        if (!args.length) {
+            this.logger.error('No package specified to execute.');
+            this.logger.info('Usage: jpm x <package>[@version] [args...]');
+            throw new Error('No package specified.');
+        }
 
-    const resolveSpinner = new Spinner(`Resolving ${name}@${range}...`).start();
+        const pkgArg = args[0];
+        const execArgs = args.slice(1);
 
-    try {
-        // 1. Resolve
-        const resolver = new Resolver();
-        const resolvedMap = await resolver.resolve({ [name]: range }, {}, {}, (count) => {
-            resolveSpinner.text = `Resolving... (${count} resolved)`;
-        });
-        resolveSpinner.succeed(`Resolved ${resolvedMap.size} packages`);
+        // Parse name and range from argument (handling scoped packages)
+        let name, range;
+        const lastAt = pkgArg.lastIndexOf('@');
+        const isScoped = pkgArg.startsWith('@');
+        const hasVersion = lastAt > 0 && !(isScoped && pkgArg.indexOf('@', 1) === -1);
 
-        // 2. Install to temp
-        const tmp = tempDir('jpm-x-');
-        const installer = new Installer(tmp);
+        if (isScoped) {
+            const parts = pkgArg.split('@');
+            name = '@' + parts[1];
+            range = parts[2] || 'latest';
+        } else {
+            name = hasVersion ? pkgArg.slice(0, lastAt) : pkgArg;
+            range = hasVersion ? pkgArg.slice(lastAt + 1) : 'latest';
+        }
 
-        logger.info(`Installing to temporary directory...`);
-        await installer.installAll(resolvedMap, { flags });
+        const resolveSpinner = new Spinner(`Resolving ${name}@${range}...`).start();
 
-        // 3. Find the binary
-        const resolvedPkg = [...resolvedMap.values()].find(m => m.name === name);
-        if (!resolvedPkg) throw new Error(`Failed to find resolved metadata for ${name}`);
+        let tmpDir;
+        try {
+            // 1. Resolve dependencies
+            const resolver = new Resolver();
+            const resolvedMap = await resolver.resolve({ [name]: range }, {}, {}, (count) => {
+                resolveSpinner.text = `Resolving... (${count} resolved)`;
+            });
+            resolveSpinner.succeed(`Resolved ${resolvedMap.size} packages`);
 
-        const bins = resolvedPkg.bin;
-        let binName;
+            // 2. Install to temporary directory
+            tmpDir = tempDir('jpm-x-');
+            const installer = new Installer(tmpDir);
 
-        if (typeof bins === 'string') {
-            binName = name.split('/').pop();
-        } else if (typeof bins === 'object' && bins !== null) {
-            const entries = Object.keys(bins);
-            if (entries.length === 0) throw new Error(`Package ${name} has no binaries.`);
-            binName = entries.find(k => k === name || k === name.split('/').pop()) || entries[0];
-        } else {
-            throw new Error(`Package ${name} does not define any binaries in package.json`);
-        }
+            this.logger.info(`Installing to temporary directory...`);
+            await installer.installAll(resolvedMap, { flags });
 
-        const binPath = path.join(tmp, 'node_modules', '.bin', binName + (process.platform === 'win32' ? '.cmd' : ''));
+            // 3. Locate and execute binary
+            const resolvedPkg = [...resolvedMap.values()].find(m => m.name === name);
+            if (!resolvedPkg) {
+                throw new Error(`Failed to find resolved metadata for ${name}`);
+            }
 
-        // If the .cmd doesn't exist, try the raw JS file with node
-        let finalBin = binPath;
-        let finalArgs = execArgs;
-        let useNode = false;
+            const binaryInfo = this._resolveBinary(name, resolvedPkg.bin);
+            const binaryPath = path.join(tmpDir, 'node_modules', '.bin', binaryInfo.name + (process.platform === 'win32' ? '.cmd' : ''));
 
-        const fs = require('node:fs');
-        if (!fs.existsSync(binPath)) {
-            // Fallback to finding the JS file
-            const relPath = typeof bins === 'string' ? bins : bins[binName];
-            finalBin = path.join(tmp, 'node_modules', name, relPath);
-            useNode = true;
-        }
+            let finalExecutable = binaryPath;
+            let finalArgs = execArgs;
+            let useNode = false;
+
+            if (!fs.existsSync(binaryPath)) {
+                // Fallback: search for the JS file defined in package.json bin field
+                const relPath = typeof resolvedPkg.bin === 'string' ? resolvedPkg.bin : resolvedPkg.bin[binaryInfo.name];
+                finalExecutable = path.join(tmpDir, 'node_modules', name, relPath);
+                useNode = true;
+            }
+
+            this.logger.info(`Executing ${binaryInfo.name}...\n`);
+
+            const env = {
+                ...process.env,
+                PATH: `${path.join(tmpDir, 'node_modules', '.bin')}${process.platform === 'win32' ? ';' : ':'}${process.env.PATH}`,
+            };
 
-        logger.info(`Executing ${binName}...\n`);
+            const result = this._spawnProcess(finalExecutable, finalArgs, useNode, env);
 
-        const spawnCmd = useNode ? process.execPath : finalBin;
-        const spawnArgs = useNode ? [finalBin, ...execArgs] : execArgs;
+            if (result.error) throw result.error;
 
-        const env = {
-            ...process.env,
-            PATH: `${path.join(tmp, 'node_modules', '.bin')}${process.platform === 'win32' ? ';' : ':'}${process.env.PATH}`,
-        };
+            // Cleanup temp directory on success unless debugging
+            if (result.status === 0 && this.config.loglevel !== 'debug') {
+                rimraf(tmpDir);
+            }
 
-        // On Windows, when shell: true is used, we need to be very careful with quoting
-        // if the path to node or the binary contains spaces (like C:\Program Files\...)
+            process.exit(result.status ?? 0);
+
+        } catch (err) {
+            if (tmpDir && fs.existsSync(tmpDir) && this.config.loglevel !== 'debug') {
+                rimraf(tmpDir);
+            }
+            resolveSpinner.fail(`Error: ${err.message}`);
+            throw err;
+        }
+    }
+
+    /**
+     * Identifies the primary binary name from package metadata.
+     * 
+     * @param {string} pkgName - Package name
+     * @param {string|Object} binField - The 'bin' field from package.json
+     * @returns {Object} Binary name and relative path
+     * @private
+     */
+    _resolveBinary(pkgName, binField) {
+        let name;
+        if (typeof binField === 'string') {
+            name = pkgName.split('/').pop();
+            return { name, path: binField };
+        } else if (typeof binField === 'object' && binField !== null) {
+            const entries = Object.keys(binField);
+            if (entries.length === 0) throw new Error(`Package ${pkgName} has no binaries.`);
+            name = entries.find(k => k === pkgName || k === pkgName.split('/').pop()) || entries[0];
+            return { name, path: binField[name] };
+        }
+        throw new Error(`Package ${pkgName} defines no binaries.`);
+    }
+
+    /**
+     * Spawns the execution process with cross-platform considerations.
+     * 
+     * @param {string} bin - Binary/Executable path
+     * @param {string[]} args - Arguments
+     * @param {boolean} useNode - Whether to execute via the node binary
+     * @param {Object} env - Environment variables
+     * @returns {import('node:child_process').SpawnSyncReturns<Buffer>}
+     * @private
+     */
+    _spawnProcess(bin, args, useNode, env) {
         const isWin = process.platform === 'win32';
 
-        let result;
         if (isWin && useNode) {
-            // Special handling for Windows + Node to avoid quoting hell with shell: true
-            result = spawnSync(`"${process.execPath}"`, [`"${finalBin}"`, ...execArgs.map(a => `"${a}"`)], {
+            // Windows specific: wrap in quotes and use verbatim arguments for reliability
+            return spawnSync(`"${process.execPath}"`, [`"${bin}"`, ...args.map(a => `"${a}"`)], {
                 cwd: process.cwd(),
                 stdio: 'inherit',
                 env,
                 shell: true,
                 windowsVerbatimArguments: true
             });
-        } else {
-            result = spawnSync(useNode ? process.execPath : finalBin, useNode ? [finalBin, ...execArgs] : execArgs, {
-                cwd: process.cwd(),
-                stdio: 'inherit',
-                env,
-                shell: true
-            });
         }
 
-        if (result.error) throw result.error;
-
-        // Cleanup on success if not in debug
-        if (result.status === 0 && config.loglevel !== 'debug') {
-            rimraf(tmp);
-        }
+        return spawnSync(useNode ? process.execPath : bin, useNode ? [bin, ...args] : args, {
+            cwd: process.cwd(),
+            stdio: 'inherit',
+            env,
+            shell: true
+        });
+    }
+}
 
-        process.exit(result.status ?? 0);
+module.exports = ExecCommand;
 
-    } catch (err) {
-        resolveSpinner.fail(`Error: ${err.message}`);
-        process.exit(1);
-    }
-};

package/src/core/cache.js

@@ -2,116 +2,217 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const crypto = require('node:crypto');
 const config = require('../utils/config');
 const { mkdirp, rimraf } = require('../utils/fs');
 const logger = require('../utils/logger');
 
 /**
- * Disk cache at ~/.jpm/cache/<name>/<version>.tgz
- * Also stores metadata JSON alongside: <name>/<version>.json
+ * Cache class handles persistent disk caching of package tarballs and metadata.
+ * Packages are stored at `<cacheDir>/<name>/<version>.tgz`.
+ * Scoped packages handle '@' by replacing '/' with '__SCOPE__'.
  */
+class Cache {
+    /**
+     * Creates an instance of the Cache.
+     * @param {Object} [options={}] - Configuration options for the cache
+     */
+    constructor(options = {}) {
+        this._config = options.config || config;
+    }
 
-function cacheRoot() {
-    return config.cacheDir;
-}
-
-function tgzPath(name, version) {
-    const safeName = name.replace('/', '__SCOPE__');
-    return path.join(cacheRoot(), safeName, `${version}.tgz`);
-}
+    /**
+     * Returns the root directory for the cache.
+     * @returns {string} Absolute path to the cache directory
+     */
+    get cacheRoot() {
+        return this._config.cacheDir;
+    }
 
-function metaPath(name, version) {
-    const safeName = name.replace('/', '__SCOPE__');
-    return path.join(cacheRoot(), safeName, `${version}.json`);
-}
+    /**
+     * Resolves the absolute path for a package tarball in the cache.
+     * 
+     * @param {string} name - The package name
+     * @param {string} version - The package version
+     * @returns {string} Absolute path to the .tgz file
+     * @private
+     */
+    _tgzPath(name, version) {
+        const safeName = name.replace('/', '__SCOPE__');
+        return path.join(this.cacheRoot, safeName, `${version}.tgz`);
+    }
 
-async function get(name, version) {
-    const p = tgzPath(name, version);
-    if (fs.existsSync(p)) {
-        logger.verbose(`cache hit ${name}@${version}`);
-        return p;
+    /**
+     * Resolves the absolute path for a package metadata JSON in the cache.
+     * 
+     * @param {string} name - The package name
+     * @param {string} version - The package version
+     * @returns {string} Absolute path to the .json file
+     * @private
+     */
+    _metaPath(name, version) {
+        const safeName = name.replace('/', '__SCOPE__');
+        return path.join(this.cacheRoot, safeName, `${version}.json`);
     }
-    return null;
-}
 
-async function set(name, version, srcTgz) {
-    const dest = tgzPath(name, version);
-    mkdirp(path.dirname(dest));
-    fs.copyFileSync(srcTgz, dest);
-    logger.verbose(`cache store ${name}@${version}`);
-}
+    /**
+     * Retrieves a package tarball from the cache if it exists.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @returns {Promise<string|null>} Path to the cached tarball, or null if not found
+     */
+    async get(name, version) {
+        const p = this._tgzPath(name, version);
+        if (fs.existsSync(p)) {
+            logger.verbose(`cache hit ${name}@${version}`);
+            return p;
+        }
+        return null;
+    }
 
-async function setMeta(name, version, meta) {
-    const p = metaPath(name, version);
-    mkdirp(path.dirname(p));
-    fs.writeFileSync(p, JSON.stringify(meta, null, 2), 'utf8');
-}
+    /**
+     * Stores a package tarball in the cache.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @param {string} srcTgz - Path to the source tarball to be copied
+     * @returns {Promise<void>}
+     */
+    async set(name, version, srcTgz) {
+        const dest = this._tgzPath(name, version);
+        mkdirp(path.dirname(dest));
+        fs.copyFileSync(srcTgz, dest);
+        logger.verbose(`cache store ${name}@${version}`);
+    }
 
-async function getMeta(name, version) {
-    const p = metaPath(name, version);
-    try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
-    catch { return null; }
-}
+    /**
+     * Stores package metadata in the cache.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @param {Object} meta - Metadata object to be serialized
+     * @returns {Promise<void>}
+     */
+    async setMeta(name, version, meta) {
+        const p = this._metaPath(name, version);
+        mkdirp(path.dirname(p));
+        fs.writeFileSync(p, JSON.stringify(meta, null, 2), 'utf8');
+    }
 
-function has(name, version) {
-    return fs.existsSync(tgzPath(name, version));
-}
+    /**
+     * Retrieves package metadata from the cache.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @returns {Promise<Object|null>} Decoded metadata object, or null if not found/invalid
+     */
+    async getMeta(name, version) {
+        const p = this._metaPath(name, version);
+        try {
+            return JSON.parse(fs.readFileSync(p, 'utf8'));
+        } catch {
+            return null;
+        }
+    }
 
-function clear(name, version) {
-    if (name && version) {
-        rimraf(tgzPath(name, version));
-        rimraf(metaPath(name, version));
-    } else if (name) {
-        const safeName = name.replace('/', '__SCOPE__');
-        rimraf(path.join(cacheRoot(), safeName));
-    } else {
-        // Clear entire cache
-        rimraf(cacheRoot());
-        logger.success('Cache cleared');
+    /**
+     * Checks if a package version exists in the cache.
+     * 
+     * @param {string} name - Package name
+     * @param {string} version - Package version
+     * @returns {boolean} True if the tarball exists in cache
+     */
+    has(name, version) {
+        return fs.existsSync(this._tgzPath(name, version));
     }
-}
 
-function stats() {
-    const root = cacheRoot();
-    if (!fs.existsSync(root)) return { packages: 0, size: 0 };
-
-    let packages = 0;
-    let size = 0;
-
-    function walk(dir) {
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                walk(full);
-            } else {
-                const s = fs.statSync(full);
-                size += s.size;
-                if (entry.name.endsWith('.tgz')) packages++;
-            }
+    /**
+     * Clears specific items or the entire cache.
+     * 
+     * @param {string} [name] - Optional package name to clear
+     * @param {string} [version] - Optional version to clear (requires name)
+     */
+    clear(name, version) {
+        if (name && version) {
+            rimraf(this._tgzPath(name, version));
+            rimraf(this._metaPath(name, version));
+        } else if (name) {
+            const safeName = name.replace('/', '__SCOPE__');
+            rimraf(path.join(this.cacheRoot, safeName));
+        } else {
+            // Clear entire cache
+            rimraf(this.cacheRoot);
+            logger.success('Cache cleared');
         }
     }
 
-    try { walk(root); } catch { }
-    return { packages, size, root };
-}
+    /**
+     * Calculates cache statistics (total packages and disk usage).
+     * 
+     * @returns {Object} { packages: number, size: number, root: string }
+     */
+    stats() {
+        const root = this.cacheRoot;
+        if (!fs.existsSync(root)) return { packages: 0, size: 0, root };
+
+        let packages = 0;
+        let size = 0;
+
+        const walk = (dir) => {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(full);
+                } else {
+                    const s = fs.statSync(full);
+                    size += s.size;
+                    if (entry.name.endsWith('.tgz')) packages++;
+                }
+            }
+        };
 
-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 });
+        try {
+            walk(root);
+        } catch { }
+        return { packages, size, root };
+    }
+
+    /**
+     * Lists all packages and versions currently in the cache.
+     * 
+     * @returns {{ name: string, version: string }[]} Array of package descriptors
+     */
+    list() {
+        const root = this.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;
     }
-    return result;
 }
 
-module.exports = { get, set, getMeta, setMeta, has, clear, stats, list };
+// Singleton instance for backward compatibility
+const defaultCache = new Cache();
+
+module.exports = {
+    Cache,
+    get: defaultCache.get.bind(defaultCache),
+    set: defaultCache.set.bind(defaultCache),
+    getMeta: defaultCache.getMeta.bind(defaultCache),
+    setMeta: defaultCache.setMeta.bind(defaultCache),
+    has: defaultCache.has.bind(defaultCache),
+    clear: defaultCache.clear.bind(defaultCache),
+    stats: defaultCache.stats.bind(defaultCache),
+    list: defaultCache.list.bind(defaultCache),
+};
+