pkgmgr 1.0.0

package/README.md

@@ -0,0 +1,135 @@
+# pkgmgr
+
+A minimal CLI that forwards commands to whichever package manager you're already using.
+
+## The Problem
+
+You're writing a script, a tool, or documentation that needs to run package manager commands. But different users use different package managers (npm, pnpm, yarn, bun), and you don't want to:
+
+- Hardcode a specific package manager
+- Ask users to modify your script
+- Set up complex workspace configurations
+
+## What pkgmgr Does
+
+pkgmgr detects which package manager invoked the current process and forwards your command to it verbatim. It's a best-effort user-intent propagation tool.
+
+```bash
+pkgmgr install          # runs: <detected-pm> install
+pkgmgr add react        # runs: <detected-pm> add react
+pkgmgr remove lodash    # runs: <detected-pm> remove lodash
+pkgmgr run build        # runs: <detected-pm> run build
+pkgmgr exec vitest      # runs: <detected-pm> exec vitest
+```
+
+## Available Binaries
+
+| Binary | Fallback |
+|--------|----------|
+| `pkgmgr` | npm |
+| `pkgmgr-bun` | bun |
+| `pkgmgr-pnpm` | pnpm |
+| `pkgmgr-yarn` | yarn |
+
+All binaries use the same detection logic. The only difference is which package manager is used when detection fails (no `PKGMGR` env var and no `npm_config_user_agent`).
+
+## Detection Logic
+
+pkgmgr determines which package manager to use in this order:
+
+1. **`PKGMGR` environment variable** — If set to a supported value, use it
+2. **`npm_config_user_agent`** — Parse the first token (e.g., `pnpm/8.0.0` → `pnpm`)
+3. **Fallback** — Use `npm`
+
+This is heuristic detection, not verification. pkgmgr trusts the environment.
+
+## Supported Package Managers
+
+- npm
+- pnpm
+- yarn
+- bun
+
+## Overriding Detection
+
+Set the `PKGMGR` environment variable to force a specific package manager:
+
+```bash
+PKGMGR=pnpm pkgmgr add zod
+```
+
+## Usage Examples
+
+```bash
+# Install dependencies (default command if no args)
+pkgmgr
+
+# Add a package
+pkgmgr add express
+
+# Remove a package
+pkgmgr remove lodash
+
+# Run a script
+pkgmgr run test
+
+# Run with arguments
+pkgmgr run build -- --watch
+
+# Execute a binary
+pkgmgr exec tsc --version
+
+# Override detection
+PKGMGR=yarn pkgmgr add react
+```
+
+## When to Use This
+
+**Good fit:**
+
+- Scripts that should work regardless of user's package manager choice
+- Documentation that doesn't want to prescribe a specific tool
+- Tools that need to install dependencies as part of setup
+
+**Not a good fit:**
+
+- CI pipelines where you control the environment (just use your package manager directly)
+- Situations requiring specific package manager features
+- Contexts where command translation between package managers is needed
+
+## Known Limitations
+
+- **No command translation** — `pkgmgr add` is passed verbatim; if you're using npm, you may need `pkgmgr install` instead. This tool does not normalize commands between package managers.
+- **Corepack** — pkgmgr does not interact with Corepack. If Corepack intercepts your package manager, that's between you and Corepack.
+- **CI environments** — Detection relies on `npm_config_user_agent`, which may not be set in all CI contexts. Use `PKGMGR` explicitly if needed.
+- **Wrapper scripts** — If your package manager is wrapped or aliased, detection may not work as expected.
+- **Nested installs** — If you're running pkgmgr from within another package manager's lifecycle script, detection reflects the outer package manager.
+- **No lockfile inspection** — pkgmgr does not look at lockfiles to determine package manager. It trusts the runtime environment only.
+
+## Why Not npx?
+
+Running `npx pkgmgr add react` defeats the purpose. npx is part of npm, so it sets `npm_config_user_agent` to npm. pkgmgr would detect npm and run `npm add react`—regardless of what package manager you actually use.
+
+The same applies to other package runners:
+- `npx pkgmgr ...` → detects npm
+- `pnpm dlx pkgmgr ...` → detects pnpm  
+- `yarn dlx pkgmgr ...` → detects yarn
+- `bunx pkgmgr ...` → detects bun
+
+pkgmgr is meant to be **installed as a dependency** in your project. When users run your scripts through their package manager (e.g., `pnpm run setup`), pkgmgr detects the invoking package manager from within that context.
+
+## Installation
+
+```bash
+npm install pkgmgr
+# or
+pnpm add pkgmgr
+# or
+yarn add pkgmgr
+# or
+bun add pkgmgr
+```
+
+## License
+
+MIT

package/bin/lib.js

@@ -0,0 +1,47 @@
+const SUPPORTED = new Set(['npm', 'pnpm', 'yarn', 'bun'])
+
+export function detectPackageManager(fallback = 'npm') {
+  // 1. Explicit override via environment variable
+  const envOverride = process.env.PKGMGR
+  if (envOverride && SUPPORTED.has(envOverride)) {
+    return envOverride
+  }
+
+  // 2. Infer from npm_config_user_agent (set by package managers when running scripts)
+  // Format: "npm/10.2.0 node/v20.10.0 darwin arm64"
+  const userAgent = process.env.npm_config_user_agent
+  if (userAgent) {
+    const firstToken = userAgent.split(' ')[0] // e.g. "npm/10.2.0"
+    const name = firstToken?.split('/')[0]
+    if (name && SUPPORTED.has(name)) {
+      return name
+    }
+  }
+
+  // 3. Fall back to specified default
+  return fallback
+}
+
+export async function run(fallback = 'npm') {
+  const pm = detectPackageManager(fallback)
+  const args = process.argv.slice(2)
+
+  // Default to 'install' if no arguments provided
+  const command = args.length > 0 ? args : ['install']
+
+  const { spawn } = await import('node:child_process')
+
+  const child = spawn(pm, command, {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  })
+
+  child.on('error', (err) => {
+    console.error(`pkgmgr: failed to execute ${pm}: ${err.message}`)
+    process.exit(1)
+  })
+
+  child.on('close', (code) => {
+    process.exit(code ?? 0)
+  })
+}

package/bin/lib.test.js

@@ -0,0 +1,128 @@
+import { test } from 'node:test'
+import assert from 'node:assert'
+import { detectPackageManager } from './lib.js'
+
+function setupEnv(overrides = {}) {
+  const original = { ...process.env }
+
+  delete process.env.PKGMGR
+  delete process.env.npm_config_user_agent
+
+  Object.assign(process.env, overrides)
+
+  return {
+    [Symbol.dispose]() {
+      process.env = original
+    },
+  }
+}
+
+// PKGMGR environment variable
+
+test('uses PKGMGR=npm when set', () => {
+  using _env = setupEnv({ PKGMGR: 'npm' })
+  assert.strictEqual(detectPackageManager(), 'npm')
+})
+
+test('uses PKGMGR=pnpm when set', () => {
+  using _env = setupEnv({ PKGMGR: 'pnpm' })
+  assert.strictEqual(detectPackageManager(), 'pnpm')
+})
+
+test('uses PKGMGR=yarn when set', () => {
+  using _env = setupEnv({ PKGMGR: 'yarn' })
+  assert.strictEqual(detectPackageManager(), 'yarn')
+})
+
+test('uses PKGMGR=bun when set', () => {
+  using _env = setupEnv({ PKGMGR: 'bun' })
+  assert.strictEqual(detectPackageManager(), 'bun')
+})
+
+test('ignores unsupported PKGMGR value and falls back to npm', () => {
+  using _env = setupEnv({ PKGMGR: 'unsupported' })
+  assert.strictEqual(detectPackageManager(), 'npm')
+})
+
+test('PKGMGR takes priority over npm_config_user_agent', () => {
+  using _env = setupEnv({
+    PKGMGR: 'yarn',
+    npm_config_user_agent: 'pnpm/8.0.0 node/v20.0.0',
+  })
+  assert.strictEqual(detectPackageManager(), 'yarn')
+})
+
+// npm_config_user_agent detection
+
+test('detects npm from user agent', () => {
+  using _env = setupEnv({
+    npm_config_user_agent: 'npm/10.2.0 node/v20.10.0 darwin arm64',
+  })
+  assert.strictEqual(detectPackageManager(), 'npm')
+})
+
+test('detects pnpm from user agent', () => {
+  using _env = setupEnv({
+    npm_config_user_agent: 'pnpm/8.15.0 npm/? node/v20.10.0',
+  })
+  assert.strictEqual(detectPackageManager(), 'pnpm')
+})
+
+test('detects yarn from user agent', () => {
+  using _env = setupEnv({
+    npm_config_user_agent: 'yarn/4.0.0 npm/? node/v20.10.0',
+  })
+  assert.strictEqual(detectPackageManager(), 'yarn')
+})
+
+test('detects bun from user agent', () => {
+  using _env = setupEnv({ npm_config_user_agent: 'bun/1.0.0 node/v20.10.0' })
+  assert.strictEqual(detectPackageManager(), 'bun')
+})
+
+test('falls back when user agent has unsupported package manager', () => {
+  using _env = setupEnv({ npm_config_user_agent: 'unknown/1.0.0 node/v20.0.0' })
+  assert.strictEqual(detectPackageManager(), 'npm')
+})
+
+test('falls back when user agent is malformed', () => {
+  using _env = setupEnv({ npm_config_user_agent: 'malformed-string' })
+  assert.strictEqual(detectPackageManager(), 'npm')
+})
+
+test('falls back when user agent is empty', () => {
+  using _env = setupEnv({ npm_config_user_agent: '' })
+  assert.strictEqual(detectPackageManager(), 'npm')
+})
+
+// Fallback behavior
+
+test('uses npm as default fallback when no env is set', () => {
+  using _env = setupEnv()
+  assert.strictEqual(detectPackageManager(), 'npm')
+})
+
+test('uses pnpm fallback when specified and no env is set', () => {
+  using _env = setupEnv()
+  assert.strictEqual(detectPackageManager('pnpm'), 'pnpm')
+})
+
+test('uses bun fallback when specified and no env is set', () => {
+  using _env = setupEnv()
+  assert.strictEqual(detectPackageManager('bun'), 'bun')
+})
+
+test('uses yarn fallback when specified and no env is set', () => {
+  using _env = setupEnv()
+  assert.strictEqual(detectPackageManager('yarn'), 'yarn')
+})
+
+test('custom fallback is ignored when PKGMGR is set', () => {
+  using _env = setupEnv({ PKGMGR: 'npm' })
+  assert.strictEqual(detectPackageManager('pnpm'), 'npm')
+})
+
+test('custom fallback is ignored when user agent is present', () => {
+  using _env = setupEnv({ npm_config_user_agent: 'yarn/4.0.0 node/v20.0.0' })
+  assert.strictEqual(detectPackageManager('pnpm'), 'yarn')
+})

package/bin/pkgmgr-bun.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from './lib.js'
+run('bun')

package/bin/pkgmgr-pnpm.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from './lib.js'
+run('pnpm')

package/bin/pkgmgr-yarn.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from './lib.js'
+run('yarn')

package/bin/pkgmgr.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from './lib.js'
+run('npm')

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "pkgmgr",
+  "version": "1.0.0",
+  "description": "Forward commands to the package manager you're already using",
+  "bin": {
+    "pkgmgr": "./bin/pkgmgr.js",
+    "pkgmgr-bun": "./bin/pkgmgr-bun.js",
+    "pkgmgr-pnpm": "./bin/pkgmgr-pnpm.js",
+    "pkgmgr-yarn": "./bin/pkgmgr-yarn.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test bin/lib.test.js"
+  },
+  "keywords": [
+    "npm",
+    "pnpm",
+    "yarn",
+    "bun",
+    "package-manager",
+    "cli"
+  ],
+  "author": "Kent C. Dodds <me@kentcdodds.com> (https://kentcdodds.com/)",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kentcdodds/pkgmgr.git"
+  }
+}