@nimbus-sh/core 0.1.0

package/dist/substrate/lifo/commands/system/npm.js

@@ -0,0 +1,934 @@
+import { resolve, join } from '../../utils/path.js';
+import { decompressGzip, parseTar } from '../../utils/archive.js';
+import { RegistryPackumentSchema, RegistrySearchResponseSchema, RegistryVersionInfoSchema, } from './registry-schemas.js';
+const GLOBAL_MODULES = '/usr/lib/node_modules';
+const GLOBAL_BIN = '/usr/bin';
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+export const NPM_VERSION = '10.0.0';
+// ─── Helpers ───
+function getRegistry(env) {
+    return env.NPM_REGISTRY || DEFAULT_REGISTRY;
+}
+function parsePackageSpec(spec) {
+    // Scoped: @scope/name@version
+    if (spec.startsWith('@')) {
+        const slashIdx = spec.indexOf('/');
+        if (slashIdx === -1)
+            return { name: spec, version: null };
+        const rest = spec.slice(slashIdx + 1);
+        const atIdx = rest.lastIndexOf('@');
+        if (atIdx > 0) {
+            return {
+                name: spec.slice(0, slashIdx + 1 + atIdx),
+                version: rest.slice(atIdx + 1),
+            };
+        }
+        return { name: spec, version: null };
+    }
+    // Regular: name@version
+    const atIdx = spec.lastIndexOf('@');
+    if (atIdx > 0) {
+        return { name: spec.slice(0, atIdx), version: spec.slice(atIdx + 1) };
+    }
+    return { name: spec, version: null };
+}
+// ─── Semver helpers ───
+function parseVersion(v) {
+    const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!m)
+        return null;
+    return [parseInt(m[1]), parseInt(m[2]), parseInt(m[3])];
+}
+function compareVersions(a, b) {
+    if (a[0] !== b[0])
+        return a[0] - b[0];
+    if (a[1] !== b[1])
+        return a[1] - b[1];
+    return a[2] - b[2];
+}
+function isVersionRange(version) {
+    return /[\^~>=<|*x]/.test(version);
+}
+function satisfiesRange(version, range) {
+    const v = parseVersion(version);
+    if (!v)
+        return false;
+    // Exact
+    if (/^\d+\.\d+\.\d+$/.test(range)) {
+        const r = parseVersion(range);
+        return r !== null && v[0] === r[0] && v[1] === r[1] && v[2] === r[2];
+    }
+    // Caret ^X.Y.Z
+    if (range.startsWith('^')) {
+        const r = parseVersion(range.slice(1));
+        if (!r)
+            return false;
+        if (r[0] > 0)
+            return v[0] === r[0] && compareVersions(v, r) >= 0;
+        if (r[1] > 0)
+            return v[0] === 0 && v[1] === r[1] && compareVersions(v, r) >= 0;
+        return v[0] === 0 && v[1] === 0 && v[2] === r[2];
+    }
+    // Tilde ~X.Y.Z
+    if (range.startsWith('~')) {
+        const r = parseVersion(range.slice(1));
+        if (!r)
+            return false;
+        return v[0] === r[0] && v[1] === r[1] && v[2] >= r[2];
+    }
+    // >=X.Y.Z
+    if (range.startsWith('>=')) {
+        const r = parseVersion(range.slice(2).trim());
+        if (!r)
+            return false;
+        return compareVersions(v, r) >= 0;
+    }
+    // * or latest
+    if (range === '*' || range === 'latest' || range === '')
+        return true;
+    return true; // unrecognised range - accept anything
+}
+// ─── Registry fetch ───
+function encodePackageName(name) {
+    return name.startsWith('@')
+        ? '@' + encodeURIComponent(name.slice(1))
+        : encodeURIComponent(name);
+}
+async function fetchPackageInfo(registry, name, version, signal) {
+    // If version is a semver range, resolve it against all versions
+    if (version && isVersionRange(version)) {
+        return fetchWithRange(registry, name, version, signal);
+    }
+    // Exact version or dist-tag (or null → latest)
+    const tag = version || 'latest';
+    const url = `${registry}/${encodePackageName(name)}/${tag}`;
+    const response = await fetch(url, { signal });
+    if (!response.ok) {
+        if (response.status === 404) {
+            throw new Error(`Package '${name}${version ? '@' + version : ''}' not found in registry`);
+        }
+        throw new Error(`Registry returned ${response.status} ${response.statusText}`);
+    }
+    return RegistryVersionInfoSchema.parse(await response.json());
+}
+async function fetchWithRange(registry, name, range, signal) {
+    const url = `${registry}/${encodePackageName(name)}`;
+    const response = await fetch(url, {
+        signal,
+        headers: { Accept: 'application/json' },
+    });
+    if (!response.ok) {
+        throw new Error(`Package '${name}' not found in registry`);
+    }
+    const data = RegistryPackumentSchema.parse(await response.json());
+    const versions = Object.keys(data.versions || {});
+    const matching = versions
+        .filter((v) => satisfiesRange(v, range))
+        .map((v) => ({ version: v, parsed: parseVersion(v) }))
+        .filter((v) => v.parsed !== null)
+        .sort((a, b) => compareVersions(b.parsed, a.parsed)); // highest first
+    if (matching.length === 0) {
+        throw new Error(`No version of '${name}' satisfies '${range}'`);
+    }
+    return data.versions[matching[0].version];
+}
+async function downloadAndExtract(tarballUrl, targetDir, vfs, signal) {
+    const response = await fetch(tarballUrl, { signal });
+    if (!response.ok) {
+        throw new Error(`Failed to download tarball: ${response.status}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    const compressed = new Uint8Array(arrayBuffer);
+    // Decompress gzip → parse tar
+    const decompressed = await decompressGzip(compressed);
+    const entries = parseTar(decompressed);
+    // Ensure target directory
+    try {
+        vfs.mkdir(targetDir, { recursive: true });
+    }
+    catch { /* exists */ }
+    // Extract, stripping the first path component (npm tarballs use "package/")
+    for (const entry of entries) {
+        const slashIdx = entry.path.indexOf('/');
+        if (slashIdx === -1)
+            continue;
+        const relativePath = entry.path.slice(slashIdx + 1);
+        if (!relativePath)
+            continue;
+        const fullPath = join(targetDir, relativePath);
+        if (entry.type === 'directory') {
+            try {
+                vfs.mkdir(fullPath, { recursive: true });
+            }
+            catch { /* exists */ }
+        }
+        else {
+            // Ensure parent exists
+            const parent = fullPath.slice(0, fullPath.lastIndexOf('/'));
+            if (parent) {
+                try {
+                    vfs.mkdir(parent, { recursive: true });
+                }
+                catch { /* exists */ }
+            }
+            vfs.writeFile(fullPath, entry.data);
+        }
+    }
+}
+function readProjectPackageJson(vfs, cwd) {
+    const pkgPath = join(cwd, 'package.json');
+    try {
+        return JSON.parse(vfs.readFileString(pkgPath));
+    }
+    catch {
+        return null;
+    }
+}
+function writeProjectPackageJson(vfs, cwd, pkg) {
+    const pkgPath = join(cwd, 'package.json');
+    vfs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+}
+export function getBinEntries(pkg) {
+    if (!pkg.bin)
+        return {};
+    if (typeof pkg.bin === 'string') {
+        return { [pkg.name || 'unknown']: pkg.bin };
+    }
+    return pkg.bin;
+}
+export function registerBinCommand(registry, binName, scriptPath, kernel) {
+    registry.registerLazy(binName, () => import('./node.js').then((mod) => ({
+        default: ((ctx) => {
+            // Use kernel's portRegistry if available, otherwise fall back to default
+            const nodeCommand = kernel ? mod.createNodeCommand(kernel) : mod.default;
+            return nodeCommand({
+                ...ctx,
+                args: [scriptPath, ...ctx.args],
+            });
+        }),
+    })));
+}
+// ─── Install logic ───
+async function installSinglePackage(name, version, targetBase, vfs, npmRegistry, signal, stdout, stderr, isGlobal, registry, seen, kernel) {
+    if (seen.has(name))
+        return 0;
+    seen.add(name);
+    const targetDir = join(targetBase, name);
+    // Skip if already installed
+    if (vfs.exists(join(targetDir, 'package.json'))) {
+        return 0;
+    }
+    stdout.write(`  ${name}${version ? '@' + version : ''}...\n`);
+    const info = await fetchPackageInfo(npmRegistry, name, version, signal);
+    await downloadAndExtract(info.dist.tarball, targetDir, vfs, signal);
+    let installed = 1;
+    // Global install: link binaries
+    if (isGlobal) {
+        const binEntries = getBinEntries(info);
+        for (const [binName, binPath] of Object.entries(binEntries)) {
+            const scriptPath = resolve(targetDir, binPath);
+            registerBinCommand(registry, binName, scriptPath, kernel);
+            try {
+                vfs.mkdir(GLOBAL_BIN, { recursive: true });
+            }
+            catch { /* exists */ }
+            vfs.writeFile(join(GLOBAL_BIN, binName), `#!/usr/bin/env node\nrequire('${scriptPath}');\n`);
+        }
+    }
+    // Recursively install dependencies (flat into the same targetBase)
+    if (info.dependencies) {
+        for (const [depName, depRange] of Object.entries(info.dependencies)) {
+            try {
+                installed += await installSinglePackage(depName, depRange, targetBase, vfs, npmRegistry, signal, stdout, stderr, isGlobal, registry, seen, kernel);
+            }
+            catch (e) {
+                stderr.write(`  warn: could not install ${depName}: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
+        }
+    }
+    return installed;
+}
+// ─── Subcommands ───
+function printHelp(ctx) {
+    ctx.stdout.write('Usage: npm <command> [args]\n\n');
+    ctx.stdout.write('Commands:\n');
+    ctx.stdout.write('  init [-y]                  create package.json\n');
+    ctx.stdout.write('  install [pkg...] [-g] [-D] install packages\n');
+    ctx.stdout.write('  uninstall <pkg> [-g]       remove a package\n');
+    ctx.stdout.write('  list [-g]                  list installed packages\n');
+    ctx.stdout.write('  run <script>               run a package.json script\n');
+    ctx.stdout.write('  start                      run the "start" script\n');
+    ctx.stdout.write('  test                       run the "test" script\n');
+    ctx.stdout.write('  info <pkg>                 show package info from registry\n');
+    ctx.stdout.write('  search <term>              search the npm registry\n');
+    ctx.stdout.write('  -v, --version              print npm version\n');
+}
+async function npmInit(ctx) {
+    const pkgPath = join(ctx.cwd, 'package.json');
+    if (ctx.vfs.exists(pkgPath)) {
+        ctx.stderr.write('package.json already exists\n');
+        return 1;
+    }
+    const dirName = ctx.cwd.split('/').pop() || 'project';
+    const pkg = {
+        name: dirName,
+        version: '1.0.0',
+        description: '',
+        main: 'index.js',
+        scripts: {
+            test: 'echo "Error: no test specified" && exit 1',
+        },
+        license: 'ISC',
+    };
+    writeProjectPackageJson(ctx.vfs, ctx.cwd, pkg);
+    ctx.stdout.write(`Wrote to ${pkgPath}:\n\n`);
+    ctx.stdout.write(JSON.stringify(pkg, null, 2) + '\n');
+    return 0;
+}
+async function npmInstall(ctx, registry, kernel) {
+    const args = ctx.args.slice(1);
+    let isGlobal = false;
+    let saveDev = false;
+    const packages = [];
+    for (const arg of args) {
+        if (arg === '-g' || arg === '--global') {
+            isGlobal = true;
+        }
+        else if (arg === '-D' || arg === '--save-dev') {
+            saveDev = true;
+        }
+        else if (arg === '--save' || arg === '-S') {
+            // default, ignore
+        }
+        else if (!arg.startsWith('-')) {
+            packages.push(arg);
+        }
+    }
+    const npmRegistry = getRegistry(ctx.env);
+    const startTime = Date.now();
+    let installed = 0;
+    const targetBase = isGlobal ? GLOBAL_MODULES : join(ctx.cwd, 'node_modules');
+    // Ensure global dirs exist
+    if (isGlobal) {
+        try {
+            ctx.vfs.mkdir(GLOBAL_MODULES, { recursive: true });
+        }
+        catch { /* exists */ }
+        try {
+            ctx.vfs.mkdir(GLOBAL_BIN, { recursive: true });
+        }
+        catch { /* exists */ }
+    }
+    if (packages.length === 0) {
+        // Install from package.json
+        if (isGlobal) {
+            ctx.stderr.write('npm: install with no args cannot be used with -g\n');
+            return 1;
+        }
+        const pkg = readProjectPackageJson(ctx.vfs, ctx.cwd);
+        if (!pkg) {
+            ctx.stderr.write('npm ERR! no package.json found in this directory\n');
+            return 1;
+        }
+        const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+        const depNames = Object.keys(allDeps);
+        if (depNames.length === 0) {
+            ctx.stdout.write('up to date, audited 0 packages\n');
+            return 0;
+        }
+        ctx.stdout.write('Installing dependencies...\n');
+        const seen = new Set();
+        for (const [name, range] of Object.entries(allDeps)) {
+            try {
+                installed += await installSinglePackage(name, range, targetBase, ctx.vfs, npmRegistry, ctx.signal, ctx.stdout, ctx.stderr, false, registry, seen, kernel);
+            }
+            catch (e) {
+                ctx.stderr.write(`npm ERR! ${name}: ${e instanceof Error ? e.message : String(e)}\n`);
+            }
+        }
+    }
+    else {
+        // Install specified packages
+        ctx.stdout.write('Installing packages...\n');
+        const seen = new Set();
+        for (const spec of packages) {
+            const { name, version } = parsePackageSpec(spec);
+            try {
+                installed += await installSinglePackage(name, version, targetBase, ctx.vfs, npmRegistry, ctx.signal, ctx.stdout, ctx.stderr, isGlobal, registry, seen);
+                // Update package.json for local installs
+                if (!isGlobal) {
+                    const pkg = readProjectPackageJson(ctx.vfs, ctx.cwd);
+                    if (pkg) {
+                        const installedPkgPath = join(targetBase, name, 'package.json');
+                        let versionStr = 'latest';
+                        try {
+                            const ipkg = JSON.parse(ctx.vfs.readFileString(installedPkgPath));
+                            versionStr = '^' + ipkg.version;
+                        }
+                        catch { /* ignore */ }
+                        if (saveDev) {
+                            pkg.devDependencies = pkg.devDependencies || {};
+                            pkg.devDependencies[name] = versionStr;
+                        }
+                        else {
+                            pkg.dependencies = pkg.dependencies || {};
+                            pkg.dependencies[name] = versionStr;
+                        }
+                        writeProjectPackageJson(ctx.vfs, ctx.cwd, pkg);
+                    }
+                }
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                if (msg.includes('Failed to fetch') || msg.includes('NetworkError') || msg.includes('CORS')) {
+                    ctx.stderr.write(`npm ERR! network error fetching ${name}\n`);
+                    ctx.stderr.write(`This may be a CORS restriction. Try: export NPM_REGISTRY=<proxy-url>\n`);
+                }
+                else {
+                    ctx.stderr.write(`npm ERR! ${msg}\n`);
+                }
+                return 1;
+            }
+        }
+    }
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+    ctx.stdout.write(`\nadded ${installed} package${installed !== 1 ? 's' : ''} in ${elapsed}s\n`);
+    return 0;
+}
+async function npmUninstall(ctx, _registry) {
+    const args = ctx.args.slice(1);
+    let isGlobal = false;
+    const packages = [];
+    for (const arg of args) {
+        if (arg === '-g' || arg === '--global') {
+            isGlobal = true;
+        }
+        else if (!arg.startsWith('-')) {
+            packages.push(arg);
+        }
+    }
+    if (packages.length === 0) {
+        ctx.stderr.write('npm uninstall requires at least one package name\n');
+        return 1;
+    }
+    const targetBase = isGlobal ? GLOBAL_MODULES : join(ctx.cwd, 'node_modules');
+    for (const name of packages) {
+        const targetDir = join(targetBase, name);
+        if (!ctx.vfs.exists(targetDir)) {
+            ctx.stderr.write(`npm warn: ${name} is not installed\n`);
+            continue;
+        }
+        // Unlink global binaries
+        if (isGlobal) {
+            try {
+                const pkg = JSON.parse(ctx.vfs.readFileString(join(targetDir, 'package.json')));
+                for (const binName of Object.keys(getBinEntries(pkg))) {
+                    try {
+                        ctx.vfs.unlink(join(GLOBAL_BIN, binName));
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            catch { /* ignore */ }
+        }
+        // Remove the package
+        try {
+            ctx.vfs.rmdirRecursive(targetDir);
+        }
+        catch (e) {
+            ctx.stderr.write(`npm ERR! could not remove ${name}: ${e instanceof Error ? e.message : String(e)}\n`);
+            return 1;
+        }
+        // Update package.json for local uninstalls
+        if (!isGlobal) {
+            const pkg = readProjectPackageJson(ctx.vfs, ctx.cwd);
+            if (pkg) {
+                if (pkg.dependencies)
+                    delete pkg.dependencies[name];
+                if (pkg.devDependencies)
+                    delete pkg.devDependencies[name];
+                writeProjectPackageJson(ctx.vfs, ctx.cwd, pkg);
+            }
+        }
+        ctx.stdout.write(`removed ${name}\n`);
+    }
+    return 0;
+}
+async function npmList(ctx) {
+    const args = ctx.args.slice(1);
+    const isGlobal = args.includes('-g') || args.includes('--global');
+    const modulesDir = isGlobal ? GLOBAL_MODULES : join(ctx.cwd, 'node_modules');
+    const header = isGlobal
+        ? '/usr/lib'
+        : (readProjectPackageJson(ctx.vfs, ctx.cwd)?.name || ctx.cwd);
+    ctx.stdout.write(`${header}\n`);
+    if (!ctx.vfs.exists(modulesDir)) {
+        ctx.stdout.write('└── (empty)\n');
+        return 0;
+    }
+    const entries = ctx.vfs.readdir(modulesDir);
+    const packages = [];
+    for (const entry of entries) {
+        if (entry.type !== 'directory')
+            continue;
+        if (entry.name.startsWith('@')) {
+            // Scoped packages
+            try {
+                const scopeEntries = ctx.vfs.readdir(join(modulesDir, entry.name));
+                for (const se of scopeEntries) {
+                    if (se.type !== 'directory')
+                        continue;
+                    const v = readPkgVersion(ctx.vfs, join(modulesDir, entry.name, se.name));
+                    packages.push({ name: `${entry.name}/${se.name}`, version: v });
+                }
+            }
+            catch { /* ignore */ }
+        }
+        else {
+            const v = readPkgVersion(ctx.vfs, join(modulesDir, entry.name));
+            packages.push({ name: entry.name, version: v });
+        }
+    }
+    if (packages.length === 0) {
+        ctx.stdout.write('└── (empty)\n');
+    }
+    else {
+        for (let i = 0; i < packages.length; i++) {
+            const p = packages[i];
+            const last = i === packages.length - 1;
+            ctx.stdout.write(`${last ? '└── ' : '├── '}${p.name}@${p.version}\n`);
+        }
+    }
+    return 0;
+}
+function readPkgVersion(vfs, pkgDir) {
+    try {
+        const pkg = JSON.parse(vfs.readFileString(join(pkgDir, 'package.json')));
+        return pkg.version || '?';
+    }
+    catch {
+        return '?';
+    }
+}
+async function npmRun(ctx, shellExecute, registry, kernel) {
+    const args = ctx.args.slice(1);
+    const scriptName = args[0];
+    const pkg = readProjectPackageJson(ctx.vfs, ctx.cwd);
+    if (!pkg) {
+        ctx.stderr.write('npm ERR! no package.json found\n');
+        return 1;
+    }
+    if (!scriptName) {
+        // List available scripts
+        if (!pkg.scripts || Object.keys(pkg.scripts).length === 0) {
+            ctx.stdout.write('No scripts defined in package.json\n');
+            return 0;
+        }
+        ctx.stdout.write('Available scripts:\n');
+        for (const [name, cmd] of Object.entries(pkg.scripts)) {
+            ctx.stdout.write(`  ${name}\n    ${cmd}\n`);
+        }
+        return 0;
+    }
+    if (!pkg.scripts || !pkg.scripts[scriptName]) {
+        ctx.stderr.write(`npm ERR! Missing script: "${scriptName}"\n`);
+        if (pkg.scripts) {
+            ctx.stderr.write('\nAvailable scripts:\n');
+            for (const name of Object.keys(pkg.scripts)) {
+                ctx.stderr.write(`  - ${name}\n`);
+            }
+        }
+        return 1;
+    }
+    const script = pkg.scripts[scriptName];
+    ctx.stdout.write(`\n> ${pkg.name || ''}@${pkg.version || '1.0.0'} ${scriptName}\n`);
+    ctx.stdout.write(`> ${script}\n\n`);
+    // Register local bin scripts from node_modules so they're available in scripts
+    if (registry) {
+        const nmDir = join(ctx.cwd, 'node_modules');
+        ctx.stderr.write(`[npm:debug] cwd="${ctx.cwd}", nmDir="${nmDir}", exists=${ctx.vfs.exists(nmDir)}\n`);
+        if (ctx.vfs.exists(nmDir)) {
+            try {
+                const entries = ctx.vfs.readdir(nmDir);
+                ctx.stderr.write(`[npm:debug] node_modules entries (${entries.length}): ${entries.slice(0, 20).join(', ')}\n`);
+                // Check vite specifically
+                const vitePkg = join(nmDir, 'vite', 'package.json');
+                if (ctx.vfs.exists(vitePkg)) {
+                    const vPkg = JSON.parse(ctx.vfs.readFileString(vitePkg));
+                    ctx.stderr.write(`[npm:debug] vite pkg.bin=${JSON.stringify(vPkg.bin)}\n`);
+                }
+                else {
+                    ctx.stderr.write(`[npm:debug] vite/package.json not found at ${vitePkg}\n`);
+                }
+            }
+            catch (e) {
+                ctx.stderr.write(`[npm:debug] readdir error: ${e}\n`);
+            }
+        }
+        const count = registerLocalBins(ctx.vfs, ctx.cwd, registry, kernel);
+        ctx.stderr.write(`[npm:debug] registered ${count} local bins, script="${script}"\n`);
+        const firstWord = script.trim().split(/\s+/)[0];
+        ctx.stderr.write(`[npm:debug] first command: "${firstWord}", has=${registry.has(firstWord)}\n`);
+    }
+    // For simple scripts (single command, no shell operators), invoke directly
+    // to avoid extra stack frames from shell.execute → interpreter chain
+    if (registry) {
+        const trimmed = script.trim();
+        const hasShellSyntax = /[;&|`$(){}]/.test(trimmed);
+        if (!hasShellSyntax) {
+            const parts = trimmed.split(/\s+/);
+            const cmdName = parts[0];
+            const cmdArgs = parts.slice(1);
+            const cmd = await registry.resolve(cmdName);
+            if (cmd) {
+                return cmd({ ...ctx, args: cmdArgs });
+            }
+        }
+    }
+    if (shellExecute) {
+        return shellExecute(script, ctx);
+    }
+    // No shell access - print the command for the user
+    ctx.stderr.write('(shell integration unavailable, run the command directly)\n');
+    return 1;
+}
+/** Scan node_modules for packages with bin entries and register them as commands */
+function registerLocalBins(vfs, cwd, registry, kernel) {
+    const nmDir = join(cwd, 'node_modules');
+    if (!vfs.exists(nmDir))
+        return 0;
+    let count = 0;
+    try {
+        const entries = vfs.readdir(nmDir);
+        for (const dirent of entries) {
+            const name = dirent.name;
+            if (name.startsWith('.'))
+                continue;
+            if (name.startsWith('@')) {
+                // Scoped packages: read @scope/pkg
+                const scopeDir = join(nmDir, name);
+                try {
+                    const scopeEntries = vfs.readdir(scopeDir);
+                    for (const scopeEntry of scopeEntries) {
+                        count += registerPkgBins(vfs, join(scopeDir, scopeEntry.name), registry, kernel);
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            else {
+                count += registerPkgBins(vfs, join(nmDir, name), registry, kernel);
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return count;
+}
+function isNativeExecutableBin(binPath) {
+    const clean = binPath.split(/[?#]/)[0];
+    const base = clean.slice(clean.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    const ext = dot > 0 ? base.slice(dot).toLowerCase() : '';
+    return ext === '.exe' || ext === '.node';
+}
+function registerPkgBins(vfs, pkgDir, registry, kernel) {
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    if (!vfs.exists(pkgJsonPath))
+        return 0;
+    let count = 0;
+    try {
+        const pkg = JSON.parse(vfs.readFileString(pkgJsonPath));
+        const bins = getBinEntries(pkg);
+        for (const [binName, binPath] of Object.entries(bins)) {
+            // Native-executable bins (.exe/.node) are not runnable here; skip
+            // them so a package whose only bin is a native launcher (e.g.
+            // opencode-ai's bin/opencode.exe) is handled by the npm-bin
+            // fallback resolver, which reads the authoritative bin manifest
+            // (including staged-artifact sentinels) instead of this raw scan.
+            if (isNativeExecutableBin(binPath))
+                continue;
+            // Only register if not already in registry
+            if (!registry.has(binName)) {
+                const scriptPath = resolve(pkgDir, binPath);
+                registerBinCommand(registry, binName, scriptPath, kernel);
+                count++;
+            }
+        }
+    }
+    catch { /* ignore */ }
+    return count;
+}
+async function npmInfo(ctx) {
+    const args = ctx.args.slice(1);
+    const spec = args[0];
+    if (!spec) {
+        ctx.stderr.write('Usage: npm info <package>\n');
+        return 1;
+    }
+    const { name, version } = parsePackageSpec(spec);
+    const npmRegistry = getRegistry(ctx.env);
+    try {
+        const info = await fetchPackageInfo(npmRegistry, name, version, ctx.signal);
+        ctx.stdout.write(`\n${info.name}@${info.version}\n`);
+        if (info.description)
+            ctx.stdout.write(`${info.description}\n`);
+        ctx.stdout.write('\n');
+        if (info.main)
+            ctx.stdout.write(`main: ${info.main}\n`);
+        const binEntries = getBinEntries(info);
+        if (Object.keys(binEntries).length > 0) {
+            ctx.stdout.write(`bin: ${Object.keys(binEntries).join(', ')}\n`);
+        }
+        if (info.dependencies) {
+            const deps = Object.keys(info.dependencies);
+            ctx.stdout.write(`\ndependencies (${deps.length}):\n`);
+            for (const dep of deps) {
+                ctx.stdout.write(`  ${dep}: ${info.dependencies[dep]}\n`);
+            }
+        }
+        ctx.stdout.write(`\ntarball: ${info.dist.tarball}\n`);
+        if (info.dist.shasum)
+            ctx.stdout.write(`shasum: ${info.dist.shasum}\n`);
+        if (info.dist.integrity)
+            ctx.stdout.write(`integrity: ${info.dist.integrity}\n`);
+    }
+    catch (e) {
+        ctx.stderr.write(`npm ERR! ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    return 0;
+}
+async function npmSearch(ctx) {
+    const args = ctx.args.slice(1);
+    const term = args.join(' ');
+    if (!term) {
+        ctx.stderr.write('Usage: npm search <term>\n');
+        return 1;
+    }
+    const npmRegistry = getRegistry(ctx.env);
+    const url = `${npmRegistry}/-/v1/search?text=${encodeURIComponent(term)}&size=10`;
+    try {
+        const response = await fetch(url, { signal: ctx.signal });
+        if (!response.ok) {
+            throw new Error(`Registry returned ${response.status}`);
+        }
+        const data = RegistrySearchResponseSchema.parse(await response.json());
+        const results = data.objects;
+        if (!results || results.length === 0) {
+            ctx.stdout.write('No results found\n');
+            return 0;
+        }
+        // Header
+        ctx.stdout.write('NAME'.padEnd(30) + 'VERSION'.padEnd(12) + 'DESCRIPTION\n');
+        ctx.stdout.write('-'.repeat(70) + '\n');
+        for (const r of results) {
+            const p = r.package;
+            const name = p.name.length > 28 ? p.name.slice(0, 28) + '..' : p.name;
+            const desc = (p.description || '').slice(0, 40);
+            ctx.stdout.write(`${name.padEnd(30)}${p.version.padEnd(12)}${desc}\n`);
+        }
+    }
+    catch (e) {
+        ctx.stderr.write(`npm ERR! ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    return 0;
+}
+// ─── Factory ───
+export function createNpmCommand(registry, shellExecute, kernel) {
+    return async (ctx) => {
+        const subcommand = ctx.args[0];
+        if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+            printHelp(ctx);
+            return subcommand ? 0 : 1;
+        }
+        switch (subcommand) {
+            case 'init':
+                return npmInit(ctx);
+            case 'install':
+            case 'i':
+            case 'add':
+                return npmInstall(ctx, registry, kernel);
+            case 'uninstall':
+            case 'remove':
+            case 'rm':
+            case 'un':
+                return npmUninstall(ctx, registry);
+            case 'list':
+            case 'ls':
+                return npmList(ctx);
+            case 'run':
+            case 'run-script':
+                return npmRun(ctx, shellExecute, registry, kernel);
+            case 'start':
+                return npmRun({ ...ctx, args: ['run', 'start', ...ctx.args.slice(1)] }, shellExecute, registry);
+            case 'test':
+                return npmRun({ ...ctx, args: ['run', 'test', ...ctx.args.slice(1)] }, shellExecute, registry);
+            case 'info':
+            case 'view':
+            case 'show':
+                return npmInfo(ctx);
+            case 'search':
+                return npmSearch(ctx);
+            case '-v':
+            case '--version':
+                ctx.stdout.write(NPM_VERSION + '\n');
+                return 0;
+            default:
+                ctx.stderr.write(`npm: unknown command '${subcommand}'\n`);
+                ctx.stderr.write('Run npm --help for usage\n');
+                return 1;
+        }
+    };
+}
+/**
+ * Install a single npm package globally into the VFS.
+ *
+ * Called directly by `lifo install` to avoid the shell.execute()
+ * round-trip which can silently swallow output and errors.
+ */
+// ─── npx ───
+const NPX_CACHE = '/tmp/.npx-cache/node_modules';
+function findBinScript(vfs, pkgDir, binName) {
+    const pkgJsonPath = join(pkgDir, 'package.json');
+    if (!vfs.exists(pkgJsonPath))
+        return null;
+    try {
+        const pkg = JSON.parse(vfs.readFileString(pkgJsonPath));
+        const bins = getBinEntries(pkg);
+        if (Object.keys(bins).length === 0)
+            return null;
+        // If a specific bin name is requested, look for it
+        if (binName && bins[binName])
+            return resolve(pkgDir, bins[binName]);
+        // Otherwise return the first entry
+        const first = Object.values(bins)[0];
+        return first ? resolve(pkgDir, first) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function createNpxCommand(registry, shellExecute) {
+    return async (ctx) => {
+        const rawArgs = ctx.args.slice();
+        let explicitPkg = null;
+        // Parse flags
+        const passthrough = [];
+        let i = 0;
+        while (i < rawArgs.length) {
+            const a = rawArgs[i];
+            if (a === '-y' || a === '--yes') {
+                i++;
+                continue;
+            }
+            if (a === '--package' && i + 1 < rawArgs.length) {
+                explicitPkg = rawArgs[i + 1];
+                i += 2;
+                continue;
+            }
+            if (a.startsWith('--package=')) {
+                explicitPkg = a.slice('--package='.length);
+                i++;
+                continue;
+            }
+            if (a === '--version' || a === '-v') {
+                ctx.stdout.write(NPM_VERSION + '\n');
+                return 0;
+            }
+            if (a === '--help' || a === '-h') {
+                ctx.stdout.write('Usage: npx [options] <package[@version]> [args...]\n\n');
+                ctx.stdout.write('Options:\n');
+                ctx.stdout.write('  -y, --yes              skip prompts\n');
+                ctx.stdout.write('  --package=<pkg>        explicit package name\n');
+                ctx.stdout.write('  -v, --version          print version\n');
+                ctx.stdout.write('  -h, --help             show this help\n');
+                return 0;
+            }
+            // First non-flag is the package spec (or bin name if --package was set)
+            break;
+        }
+        const spec = rawArgs[i];
+        if (!spec) {
+            ctx.stderr.write('npx: missing package or command\n');
+            ctx.stderr.write('Usage: npx <package[@version]> [args...]\n');
+            return 1;
+        }
+        // Everything after the spec is passthrough args
+        passthrough.push(...rawArgs.slice(i + 1));
+        const { name: parsedName, version } = parsePackageSpec(explicitPkg || spec);
+        // The bin name to look for: if --package was used, spec is the bin name; otherwise derive from package name
+        const binName = explicitPkg ? spec : parsedName.split('/').pop();
+        // 1. Check local node_modules
+        const localPkgDir = join(ctx.cwd, 'node_modules', parsedName);
+        let scriptPath = findBinScript(ctx.vfs, localPkgDir, binName);
+        // 2. Check global modules
+        if (!scriptPath) {
+            const globalPkgDir = join(GLOBAL_MODULES, parsedName);
+            scriptPath = findBinScript(ctx.vfs, globalPkgDir, binName);
+        }
+        // 3. Install to cache
+        if (!scriptPath) {
+            const cacheDir = join(NPX_CACHE, parsedName);
+            if (!ctx.vfs.exists(join(cacheDir, 'package.json'))) {
+                const npmRegistry = getRegistry(ctx.env);
+                const seen = new Set();
+                try {
+                    await installSinglePackage(parsedName, version, NPX_CACHE, ctx.vfs, npmRegistry, ctx.signal, ctx.stdout, ctx.stderr, false, registry, seen);
+                }
+                catch (e) {
+                    ctx.stderr.write(`npx: could not install ${parsedName}: ${e instanceof Error ? e.message : String(e)}\n`);
+                    return 1;
+                }
+            }
+            scriptPath = findBinScript(ctx.vfs, cacheDir, binName);
+        }
+        if (!scriptPath) {
+            ctx.stderr.write(`npx: could not find executable for '${binName}'\n`);
+            return 1;
+        }
+        // 4. Execute via node (prefer direct invocation to avoid shell reentrance)
+        const nodeCmd = await registry.resolve('node');
+        if (nodeCmd) {
+            return nodeCmd({ ...ctx, args: [scriptPath, ...passthrough] });
+        }
+        // Fallback: shellExecute
+        if (shellExecute) {
+            const cmd = ['node', scriptPath, ...passthrough]
+                .map((s) => (s.includes(' ') ? `"${s}"` : s))
+                .join(' ');
+            return shellExecute(cmd, ctx);
+        }
+        ctx.stderr.write('npx: node command not available\n');
+        return 1;
+    };
+}
+export async function npmInstallGlobal(packageName, ctx, registry, kernel) {
+    const npmRegistry = getRegistry(ctx.env);
+    const startTime = Date.now();
+    const seen = new Set();
+    try {
+        ctx.vfs.mkdir(GLOBAL_MODULES, { recursive: true });
+    }
+    catch { /* exists */ }
+    try {
+        ctx.vfs.mkdir(GLOBAL_BIN, { recursive: true });
+    }
+    catch { /* exists */ }
+    try {
+        const installed = await installSinglePackage(packageName, null, GLOBAL_MODULES, ctx.vfs, npmRegistry, ctx.signal, ctx.stdout, ctx.stderr, true, registry, seen, kernel);
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+        ctx.stdout.write(`\nadded ${installed} package${installed !== 1 ? 's' : ''} in ${elapsed}s\n`);
+        return 0;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes('Failed to fetch') || msg.includes('NetworkError') || msg.includes('CORS')) {
+            ctx.stderr.write(`npm ERR! network error fetching ${packageName}\n`);
+            ctx.stderr.write('This may be a CORS restriction. Try: export NPM_REGISTRY=<proxy-url>\n');
+        }
+        else {
+            ctx.stderr.write(`npm ERR! ${msg}\n`);
+        }
+        return 1;
+    }
+}