dep 1.1.0 → 1.2.0

package/.claude/settings.local.json

@@ -59,7 +59,8 @@
       "Bash(timeout 60 npm exec --offline -- node-gyp --version)",
       "Bash(node -e 'const p=require\\(\"./package.json\"\\);console.log\\(\"dependencies:\",JSON.stringify\\(p.dependencies\\),\"| bundleDependencies:\",p.bundleDependencies||\"\\(removed\\)\"\\)')",
       "Bash(grep -nE '`[^`]*`' lib/utils/cmd-shim.js)",
-      "Bash(grep -v '\\\\${')"
+      "Bash(grep -v '\\\\${')",
+      "Bash(DEP_CONCURRENCY=4 node --input-type=module -e ' *)"
     ]
   }
 }

package/bin/dep.js

@@ -42,11 +42,12 @@ const help = () => {
     ...rows,
     '',
     'Options:',
-    '  --save             Save to dependencies (--save=dev for devDependencies)',
-    '  --save-dev         Save to devDependencies',
-    '  --only=prod|dev    Install only prod or dev dependencies',
-    '  -h, --help         Show help',
-    '  -v, --version      Show version information',
+    '  --save                  Save to dependencies (--save=dev for devDependencies)',
+    '  --save-dev              Save to devDependencies',
+    '  --only=prod|dev         Install only prod or dev dependencies',
+    '  -w, --workspace <name>  Add the package(s) to the named workspace(s)',
+    '  -h, --help              Show help',
+    '  -v, --version           Show version information',
     ''
   ].join('\n')
 }
@@ -62,7 +63,8 @@ const { values, positionals } = parseArgs({
     version: { type: 'boolean', short: 'v' },
     only: { type: 'string' },
     save: { type: 'string' },
-    'save-dev': { type: 'boolean' }
+    'save-dev': { type: 'boolean' },
+    workspace: { type: 'string', short: 'w', multiple: true }
   }
 })
 
@@ -79,7 +81,7 @@ if (values.version) {
 } else if (values.help) {
   process.stdout.write(help() + '\n')
 } else if (command) {
-  command.handler({ _: positionals, only: values.only, save })
+  command.handler({ _: positionals, only: values.only, save, workspace: values.workspace })
 } else {
   process.stderr.write(help() + '\n')
 }

package/lib/install/installer.js

@@ -1,6 +1,7 @@
 import fs from 'fs'
 import path from 'path'
 import nm from '../utils/nm.js'
+import pool from '../utils/pool.js'
 import bin from './installer/bin.js'
 import git from './installer/git.js'
 import local from './installer/local.js'
@@ -8,6 +9,11 @@ import remote from './installer/remote.js'
 import registry from './installer/registry.js'
 import runner from '../run/runner.js'
 
+// Bound the number of tarball downloads / extractions / git clones running at
+// once so deep trees don't open thousands of sockets and file handles.
+const CONCURRENCY = Math.max(1, Number(process.env.DEP_CONCURRENCY) || 16)
+const limit = pool(CONCURRENCY)
+
 const installer = (dep, deps, base, resolve, reject) => {
   fs.mkdirSync(nm, { recursive: true })
   fs.mkdirSync(path.join(nm, '.bin'), { recursive: true })
@@ -20,18 +26,19 @@ const installer = (dep, deps, base, resolve, reject) => {
   const pkg = deps[dep]
   let fetch
 
+  // Defer the actual work into the pool (thunks) so only CONCURRENCY run at once.
   switch (pkg.type) {
     case 'git':
-      fetch = git(pkg, target)
+      fetch = limit(() => git(pkg, target))
       break
     case 'remote':
-      fetch = remote(pkg, target)
+      fetch = limit(() => remote(pkg, target))
       break
     case 'local':
-      fetch = local(pkg, target)
+      fetch = limit(() => local(pkg, target))
       break
     case 'registry':
-      fetch = registry(pkg, target)
+      fetch = limit(() => registry(pkg, target))
       break
   }
 

package/lib/install/saver.js

@@ -3,8 +3,8 @@ import path from 'path'
 import npmrc from '../utils/npmrc.js'
 import npa from '../utils/npa.js'
 
-export default (pkgs, save) => {
-  const pkgJSON = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json')))
+export default (pkgs, save, cwd = process.cwd()) => {
+  const pkgJSON = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json')))
   const saveDeps = {}
   pkgs.forEach((pkg) => {
     // npa keeps scoped names (@scope/name) intact; the spec is whatever
@@ -29,7 +29,7 @@ export default (pkgs, save) => {
   const newDeps = Object.assign({}, oldDeps, saveDeps)
   pkgJSON[field] = newDeps
   fs.writeFileSync(
-    path.join(process.cwd(), 'package.json'),
+    path.join(cwd, 'package.json'),
     JSON.stringify(pkgJSON, null, 2)
   )
 }

package/lib/install.js

@@ -6,8 +6,23 @@ import saver from './install/saver.js'
 import nodeGyp from './utils/node-gyp.js'
 import nm from './utils/nm.js'
 import npa from './utils/npa.js'
+import bin from './install/installer/bin.js'
+import { findWorkspaces, resolveWorkspace } from './utils/workspaces.js'
 import dropPrivilege from './utils/drop-privilege.js'
 
+const isWin = process.platform === 'win32'
+
+// Symlink each workspace package into the root node_modules so cross-workspace
+// imports resolve, and link its bins into node_modules/.bin.
+const linkWorkspaces = (workspaces) => Promise.all(workspaces.map(async (ws) => {
+  const dest = path.join(nm, ws.name)
+  fs.mkdirSync(path.dirname(dest), { recursive: true })
+  fs.rmSync(dest, { recursive: true, force: true })
+  const target = isWin ? ws.dir : path.relative(path.dirname(dest), ws.dir)
+  fs.symlinkSync(target, dest, isWin ? 'junction' : 'dir')
+  await bin(ws.name, ws.dir)
+}))
+
 global.dependenciesCount = 0
 global.dependenciesTree = {}
 global.nativeBuildQueue = []
@@ -19,7 +34,6 @@ const install = (argv) => {
   const only = argv.only === 'dev' || argv.only === 'prod' ? argv.only : 'all'
   const save = argv.save === 'dev' || argv.save === 'prod' ? argv.save : null
   const pkgJSON = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json')))
-  const optionalDependencies = pkgJSON.optionalDependencies || {}
   const allDependencies = {
     all: [
       'dependencies',
@@ -32,11 +46,42 @@ const install = (argv) => {
       'devDependencies'
     ]
   }
-  const deps = Object.assign({}, optionalDependencies)
-  allDependencies[only].forEach((key) => {
-    if (!pkgJSON[key]) return
-    Object.assign(deps, pkgJSON[key])
+  // Collect a package.json's deps honouring the --only filter (optional deps
+  // are always included, like npm).
+  const collect = (json) => {
+    const out = Object.assign({}, json.optionalDependencies || {})
+    allDependencies[only].forEach((key) => {
+      if (json[key]) Object.assign(out, json[key])
+    })
+    return out
+  }
+
+  const deps = collect(pkgJSON)
+
+  // Workspaces: merge every workspace's deps into the root install and link the
+  // workspace packages themselves rather than fetching them from the registry.
+  const workspaces = pkgJSON.workspaces
+    ? findWorkspaces(process.cwd(), pkgJSON.workspaces)
+    : []
+  workspaces.forEach((ws) => {
+    const wsDeps = collect(ws.pkg)
+    Object.keys(wsDeps).forEach((name) => {
+      if (!(name in deps)) deps[name] = wsDeps[name]
+    })
+  })
+  workspaces.forEach((ws) => { delete deps[ws.name] })
+
+  // `-w <workspace>`: the named package(s) belong to those workspaces. Resolve
+  // each target up front so a typo fails before we touch anything.
+  const wsTargets = (argv.workspace || []).map((target) => {
+    const ws = resolveWorkspace(workspaces, process.cwd(), target)
+    if (!ws) {
+      process.stderr.write(`No workspace found for "${target}"\n`)
+      process.exit(1)
+    }
+    return ws
   })
+
   pkgs.forEach((pkg) => {
     // Use npa to split the name from the spec so scoped packages
     // (@scope/name@range) aren't broken by the leading '@'.
@@ -50,8 +95,14 @@ const install = (argv) => {
     dropPrivilege() // if root
     const tasks = installer(global.dependenciesTree)
     process.stdout.write('Installing dependencies\n')
-    Promise.all(tasks).then(() => {
-      if (save) saver(pkgs, save)
+    Promise.all(tasks).then(async () => {
+      // `-w` implies saving into the target workspace(s); otherwise honour
+      // --save against the root package.json.
+      if (wsTargets.length && pkgs.length) {
+        wsTargets.forEach((ws) => saver(pkgs, save, ws.dir))
+      } else if (save) {
+        saver(pkgs, save)
+      }
       global.nativeBuildQueue.forEach((cwd) => {
         try {
           process.stdout.write('Building dependencies\n')
@@ -61,6 +112,10 @@ const install = (argv) => {
           fs.rmSync(cwd, { recursive: true, force: true })
         }
       })
+      if (workspaces.length) {
+        process.stdout.write('Linking workspaces\n')
+        await linkWorkspaces(workspaces)
+      }
       const duration = process.hrtime(global.time)
       const time = duration[0] + duration[1] / 1e9
       const s = Math.round(time * 1000) / 1000

package/lib/lock/locker.js

@@ -53,7 +53,9 @@ const resolveFrom = (packages, fromPath, name) => {
   }
 }
 
-// Mark every location reachable from a set of root dependency names.
+// Mark every location reachable from a set of root dependency names. A
+// workspace link is followed to its source entry, so the workspace's own
+// dependencies are traversed too.
 const reachable = (packages, roots) => {
   const seen = {}
   const stack = roots
@@ -63,21 +65,28 @@ const reachable = (packages, roots) => {
     const location = stack.pop()
     if (seen[location]) continue
     seen[location] = true
-    const entry = packages[location]
+    let entry = packages[location]
+    let base = location
+    if (entry && entry.link) {
+      base = entry.resolved
+      entry = packages[entry.resolved]
+    }
+    if (!entry) continue
     const edges = Object.assign({}, entry.dependencies, entry.optionalDependencies)
     Object.keys(edges).forEach((name) => {
-      const child = resolveFrom(packages, location, name)
+      const child = resolveFrom(packages, base, name)
       if (child) stack.push(child)
     })
   }
   return seen
 }
 
-const locker = (pkgJSON, tree) => {
+const locker = (pkgJSON, tree, workspaces = []) => {
   const packages = {}
 
   const root = { name: pkgJSON.name, version: pkgJSON.version }
   if (pkgJSON.license) root.license = pkgJSON.license
+  if (pkgJSON.workspaces) root.workspaces = pkgJSON.workspaces
   if (notEmpty(pkgJSON.dependencies)) root.dependencies = pkgJSON.dependencies
   if (notEmpty(pkgJSON.devDependencies)) root.devDependencies = pkgJSON.devDependencies
   if (notEmpty(pkgJSON.optionalDependencies)) root.optionalDependencies = pkgJSON.optionalDependencies
@@ -85,11 +94,33 @@ const locker = (pkgJSON, tree) => {
 
   flatten(tree, '', packages)
 
+  // Each workspace appears twice, npm-style: a source entry at its real
+  // location, and a `link: true` entry in node_modules pointing at it.
+  workspaces.forEach((ws) => {
+    const location = path.relative(process.cwd(), ws.dir).split(path.sep).join('/')
+    const src = { name: ws.pkg.name, version: ws.pkg.version }
+    if (ws.pkg.license) src.license = ws.pkg.license
+    if (notEmpty(ws.pkg.dependencies)) src.dependencies = ws.pkg.dependencies
+    if (notEmpty(ws.pkg.devDependencies)) src.devDependencies = ws.pkg.devDependencies
+    if (notEmpty(ws.pkg.optionalDependencies)) src.optionalDependencies = ws.pkg.optionalDependencies
+    if (notEmpty(ws.pkg.peerDependencies)) src.peerDependencies = ws.pkg.peerDependencies
+    if (ws.pkg.bin) src.bin = ws.pkg.bin
+    if (ws.pkg.engines) src.engines = ws.pkg.engines
+    packages[location] = src
+    packages['node_modules/' + ws.name] = { resolved: location, link: true }
+  })
+
   // Classify each package as production, dev and/or optional so the lockfile
-  // mirrors npm's `dev`/`optional`/`devOptional` annotations.
-  const inProd = reachable(packages, Object.keys(pkgJSON.dependencies || {}))
-  const inDev = reachable(packages, Object.keys(pkgJSON.devDependencies || {}))
-  const inOptional = reachable(packages, Object.keys(pkgJSON.optionalDependencies || {}))
+  // mirrors npm's `dev`/`optional`/`devOptional` annotations. Workspaces (and
+  // the deps reached through their links) count as production.
+  const wsDevNames = workspaces.flatMap((ws) => Object.keys(ws.pkg.devDependencies || {}))
+  const wsOptNames = workspaces.flatMap((ws) => Object.keys(ws.pkg.optionalDependencies || {}))
+  const inProd = reachable(packages, [
+    ...Object.keys(pkgJSON.dependencies || {}),
+    ...workspaces.map((ws) => ws.name)
+  ])
+  const inDev = reachable(packages, [...Object.keys(pkgJSON.devDependencies || {}), ...wsDevNames])
+  const inOptional = reachable(packages, [...Object.keys(pkgJSON.optionalDependencies || {}), ...wsOptNames])
   Object.keys(packages).forEach((location) => {
     if (location === '') return
     if (inProd[location]) return

package/lib/lock.js

@@ -2,23 +2,62 @@ import path from 'path'
 import fs from 'fs'
 import resolver from './lock/resolver.js'
 import locker from './lock/locker.js'
+import { findWorkspaces, resolveWorkspace } from './utils/workspaces.js'
 
 global.dependenciesTree = {}
 
+const allDeps = (json) => Object.assign(
+  {},
+  json.optionalDependencies || {},
+  json.devDependencies || {},
+  json.dependencies || {}
+)
+
 const lock = (argv) => {
   argv._handled = true
   const pkgJSON = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json')))
-  const deps = Object.assign(
-    {},
-    pkgJSON.optionalDependencies || {},
-    pkgJSON.devDependencies || {},
-    pkgJSON.dependencies || {}
-  )
+
+  const allWorkspaces = pkgJSON.workspaces
+    ? findWorkspaces(process.cwd(), pkgJSON.workspaces)
+    : []
+
+  // `-w <workspace>`: narrow the lockfile to the named workspace(s). Without
+  // it, lock the root plus every workspace.
+  const targets = argv.workspace || []
+  const scoped = targets.length > 0
+  const workspaces = scoped
+    ? targets.map((target) => {
+      const ws = resolveWorkspace(allWorkspaces, process.cwd(), target)
+      if (!ws) {
+        process.stderr.write(`No workspace found for "${target}"\n`)
+        process.exit(1)
+      }
+      return ws
+    })
+    : allWorkspaces
+
+  // The root's own deps are only locked when not scoping to specific workspaces.
+  const deps = scoped ? {} : allDeps(pkgJSON)
+
+  // Lock each in-scope workspace's deps too, and link the workspace packages
+  // themselves rather than fetching them from the registry.
+  workspaces.forEach((ws) => {
+    const wsDeps = allDeps(ws.pkg)
+    Object.keys(wsDeps).forEach((name) => {
+      if (!(name in deps)) deps[name] = wsDeps[name]
+    })
+  })
+  workspaces.forEach((ws) => { delete deps[ws.name] })
+
+  // When scoped, the root entry shouldn't declare deps we didn't resolve.
+  const rootJSON = scoped
+    ? { name: pkgJSON.name, version: pkgJSON.version, license: pkgJSON.license, workspaces: pkgJSON.workspaces }
+    : pkgJSON
 
   const list = resolver(deps)
   process.stdout.write('Resolving dependencies\n')
   Promise.all(list).then(() => {
-    locker(pkgJSON, global.dependenciesTree)
+    locker(rootJSON, global.dependenciesTree, workspaces)
     process.stdout.write(
       'created package-lock.json\n'
     )

package/lib/utils/pool.js

@@ -0,0 +1,29 @@
+// Bounded-concurrency runner. Returns a `run(thunk)` that schedules an async
+// task (a function returning a promise) and resolves with its result, keeping
+// at most `size` tasks in flight at once. Queued tasks start as slots free up.
+//
+// This caps simultaneous network connections, open file handles and tarball
+// extractions so large dependency trees don't exhaust sockets/FDs or trip
+// registry rate limits.
+export default (size) => {
+  let active = 0
+  const queue = []
+
+  const next = () => {
+    if (active >= size || queue.length === 0) return
+    active++
+    const { thunk, resolve, reject } = queue.shift()
+    Promise.resolve()
+      .then(thunk)
+      .then(resolve, reject)
+      .finally(() => {
+        active--
+        next()
+      })
+  }
+
+  return (thunk) => new Promise((resolve, reject) => {
+    queue.push({ thunk, resolve, reject })
+    next()
+  })
+}

package/lib/utils/resolve-tree.js

@@ -1,4 +1,7 @@
 import semver from './semver.js'
+import pool from './pool.js'
+
+const CONCURRENCY = Math.max(1, Number(process.env.DEP_CONCURRENCY) || 16)
 
 // Resolve a dependency graph into the hoisted tree shape consumed by the
 // installer and locker (a top-level name->node map, with conflicting versions
@@ -9,22 +12,11 @@ import semver from './semver.js'
 //      `name@spec` (and, for the registry, by packument). This is where the
 //      time goes, so it runs fully concurrently and never fetches the same
 //      thing twice.
-//   2. Build the tree with a deterministic depth-first walk over the cached
-//      metadata, so the output is identical on every run regardless of network
-//      timing.
-
-const getter = (list, keys) => {
-  let ref = list
-  while (keys.length) {
-    const key = keys.shift()
-    if (key in ref) {
-      ref = ref[key]
-    } else {
-      return
-    }
-  }
-  return ref
-}
+//   2. Build the tree with a deterministic breadth-first walk over the cached
+//      metadata. Processing shallower dependencies first lets direct deps claim
+//      the top-level (hoisted) slots, with conflicting deeper versions nested
+//      under their parent — and the output is identical on every run regardless
+//      of network timing.
 
 const setter = (list, key, value, walk) => {
   let i = 0
@@ -62,13 +54,14 @@ export default (deps, fetcher, keepRequires) => {
   const cache = new Map() // name@spec -> in-flight promise
   const metas = new Map() // name@spec -> resolved metadata
   const pending = []
+  const limit = pool(CONCURRENCY)
   let firstError = null
 
-  // --- phase 1: fetch all metadata, concurrently and de-duplicated ---
+  // --- phase 1: fetch all metadata, concurrently (bounded) and de-duplicated ---
   const schedule = (name, spec) => {
     const key = metaKey(name, spec)
     if (cache.has(key)) return
-    const p = fetcher(name, spec)
+    const p = limit(() => fetcher(name, spec))
       .then((meta) => {
         metas.set(key, meta)
         if (meta.dependencies) {
@@ -89,45 +82,46 @@ export default (deps, fetcher, keepRequires) => {
     if (firstError) throw firstError
   }
 
-  // --- phase 2: build the hoisted tree deterministically ---
-  const place = (dep, list, base, path) => {
-    const range = list[dep]
-    if (tree[dep] && tree[dep].version && semver.satisfies(tree[dep].version, range)) {
-      return
-    }
-    for (let i = 0; i < base.length; i += 2) {
-      const target = getter(tree, base.slice(0, i))
-      if (target && target[dep] && target[dep].version &&
-          semver.satisfies(target[dep].version, range)) {
-        return
+  // --- phase 2: build the hoisted tree breadth-first (deterministic) ---
+  const build = () => {
+    const queue = Object.keys(deps).map((name) => ({ dep: name, list: deps, base: [] }))
+    const visited = new Set()
+
+    while (queue.length) {
+      const { dep, list, base } = queue.shift()
+      const range = list[dep]
+
+      // Already satisfied by the hoisted top-level copy.
+      if (tree[dep] && tree[dep].version && semver.satisfies(tree[dep].version, range)) {
+        continue
       }
-    }
 
-    const meta = metas.get(metaKey(dep, range))
-    if (!meta || !meta.version) return
-    const id = `${dep}@${meta.version}`
-    if (path.has(id)) return // guard against dependency cycles
-
-    const item = Object.assign({}, meta)
-    if (keepRequires) item.requires = meta.dependencies
-    delete item.dependencies
-    if (!tree[dep]) tree[dep] = item
-    else setter(tree, dep, item, base)
-
-    if (!meta.dependencies) return
-    const newBase = base.length === 0
-      ? [id]
-      : [...base, 'dependencies', id]
-    path.add(id)
-    for (const child of Object.keys(meta.dependencies)) {
-      place(child, meta.dependencies, newBase, path)
+      const meta = metas.get(metaKey(dep, range))
+      if (!meta || !meta.version) continue
+
+      // Skip identical (path, dep, version) work — guards against cycles and
+      // redundant nesting.
+      const mark = `${base.join('|')}|${dep}@${meta.version}`
+      if (visited.has(mark)) continue
+      visited.add(mark)
+
+      const item = Object.assign({}, meta)
+      if (keepRequires) item.requires = meta.dependencies
+      delete item.dependencies
+      // First (shallowest) occurrence hoists to the top; conflicts nest.
+      if (!tree[dep]) tree[dep] = item
+      else setter(tree, dep, item, base)
+
+      if (!meta.dependencies) continue
+      const id = `${dep}@${meta.version}`
+      const childBase = base.length === 0 ? [id] : [...base, 'dependencies', id]
+      for (const child of Object.keys(meta.dependencies)) {
+        queue.push({ dep: child, list: meta.dependencies, base: childBase })
+      }
     }
-    path.delete(id)
   }
 
   for (const name of Object.keys(deps)) schedule(name, deps[name])
 
-  return drain().then(() => {
-    for (const name of Object.keys(deps)) place(name, deps, [], new Set())
-  })
+  return drain().then(build)
 }

package/lib/utils/workspaces.js

@@ -0,0 +1,89 @@
+import fs from 'fs'
+import path from 'path'
+
+// Discover workspace packages declared in a root package.json `workspaces`
+// field (npm/yarn style): an array of globs, or { packages: [...] }. Supports
+// `*`, `**`, exact paths and `!`-prefixed negations.
+
+const isDir = (p) => {
+  try { return fs.statSync(p).isDirectory() } catch (e) { return false }
+}
+
+const readPkg = (dir) => {
+  try { return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'))) } catch (e) { return null }
+}
+
+const subdirs = (dir) => {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((e) => (e.isDirectory() || e.isSymbolicLink()) && e.name !== 'node_modules' && e.name[0] !== '.')
+      .map((e) => e.name)
+  } catch (e) {
+    return []
+  }
+}
+
+const allDirs = (dir, acc) => {
+  acc.push(dir)
+  for (const name of subdirs(dir)) allDirs(path.join(dir, name), acc)
+  return acc
+}
+
+const segToRe = (seg) =>
+  new RegExp('^' + seg.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*') + '$')
+
+// Expand a single glob pattern to matching directories under `root`.
+const expand = (root, pattern) => {
+  let dirs = [root]
+  for (const seg of pattern.split('/').filter(Boolean)) {
+    const next = []
+    for (const d of dirs) {
+      if (seg === '**') {
+        allDirs(d, next)
+      } else if (seg.includes('*')) {
+        const re = segToRe(seg)
+        for (const name of subdirs(d)) if (re.test(name)) next.push(path.join(d, name))
+      } else {
+        const p = path.join(d, seg)
+        if (isDir(p)) next.push(p)
+      }
+    }
+    dirs = next
+  }
+  return dirs
+}
+
+export const getPatterns = (workspaces) =>
+  Array.isArray(workspaces) ? workspaces : (workspaces && workspaces.packages) || []
+
+// Returns [{ dir, name, pkg }] for every workspace package with a name.
+export const findWorkspaces = (root, workspaces) => {
+  const patterns = getPatterns(workspaces)
+  const includes = patterns.filter((p) => !p.startsWith('!'))
+  const excludes = patterns.filter((p) => p.startsWith('!')).map((p) => p.slice(1))
+  const excluded = new Set()
+  for (const pattern of excludes) {
+    for (const dir of expand(root, pattern)) excluded.add(dir)
+  }
+
+  const seen = new Set()
+  const result = []
+  for (const pattern of includes) {
+    for (const dir of expand(root, pattern)) {
+      if (seen.has(dir) || excluded.has(dir) || dir === root) continue
+      seen.add(dir)
+      const pkg = readPkg(dir)
+      if (pkg && pkg.name) result.push({ dir, name: pkg.name, pkg })
+    }
+  }
+  return result
+}
+
+// Resolve a `-w` target (a workspace name, or a path relative to root) to one of
+// the discovered workspaces. Returns the matching entry, or undefined.
+export const resolveWorkspace = (workspaces, root, target) => {
+  const byName = workspaces.find((ws) => ws.name === target)
+  if (byName) return byName
+  const wanted = path.resolve(root, target)
+  return workspaces.find((ws) => ws.dir === wanted)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dep",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A little Node.js dependency installer",
   "type": "module",
   "main": "lib/install.js",

package/test/45-pool.js

@@ -0,0 +1,45 @@
+import tap from 'tap'
+import pool from '../lib/utils/pool.js'
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+tap.test('runs at most `size` tasks concurrently', async (t) => {
+  const limit = pool(3)
+  let active = 0
+  let peak = 0
+
+  const results = await Promise.all(
+    Array.from({ length: 12 }, (_, i) =>
+      limit(async () => {
+        active++
+        peak = Math.max(peak, active)
+        await delay(10)
+        active--
+        return i * 2
+      })
+    )
+  )
+
+  t.ok(peak <= 3, `peak concurrency (${peak}) never exceeded the limit`)
+  t.ok(peak > 1, 'tasks actually ran in parallel up to the limit')
+  t.same(results, Array.from({ length: 12 }, (_, i) => i * 2), 'every task resolved with its own result')
+  t.end()
+})
+
+tap.test('a failing task rejects only its own promise and frees its slot', async (t) => {
+  const limit = pool(2)
+
+  await t.rejects(limit(() => Promise.reject(new Error('boom'))), /boom/, 'rejection propagates')
+
+  // The pool keeps working after a failure.
+  const value = await limit(() => Promise.resolve('ok'))
+  t.equal(value, 'ok', 'subsequent tasks still run')
+  t.end()
+})
+
+tap.test('a task that throws synchronously is caught', async (t) => {
+  const limit = pool(1)
+  await t.rejects(limit(() => { throw new Error('sync') }), /sync/, 'sync throw becomes a rejection')
+  t.equal(await limit(() => Promise.resolve(1)), 1, 'pool is not wedged')
+  t.end()
+})

package/test/50-workspace.js

@@ -0,0 +1,167 @@
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { exec } from 'child_process'
+import tap from 'tap'
+import { findWorkspaces, resolveWorkspace } from '../lib/utils/workspaces.js'
+
+const bin = path.join(import.meta.dirname, '..', 'bin', 'dep.js')
+
+const mkMonorepo = () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'dep-ws-'))
+  const write = (rel, obj) => {
+    const file = path.join(root, rel)
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(obj, null, 2))
+  }
+  write('package.json', { name: 'root', version: '1.0.0', private: true, workspaces: ['packages/*'] })
+  write('packages/a/package.json', { name: '@scope/a', version: '1.0.0', dependencies: { 'is-odd': '^3.0.0' } })
+  write('packages/b/package.json', { name: 'pkg-b', version: '1.0.0', dependencies: { '@scope/a': '^1.0.0', 'is-number': '^7.0.0' } })
+  return root
+}
+
+tap.test('findWorkspaces discovers packages by glob, honouring excludes', (t) => {
+  const root = mkMonorepo()
+  fs.mkdirSync(path.join(root, 'packages', 'ignored'), { recursive: true })
+  fs.writeFileSync(
+    path.join(root, 'packages', 'ignored', 'package.json'),
+    JSON.stringify({ name: 'ignored', version: '1.0.0' })
+  )
+  t.teardown(() => fs.rmSync(root, { recursive: true, force: true }))
+
+  const all = findWorkspaces(root, ['packages/*'])
+  t.same(all.map((w) => w.name).sort(), ['@scope/a', 'ignored', 'pkg-b'], 'globs every package dir')
+
+  const filtered = findWorkspaces(root, ['packages/*', '!packages/ignored'])
+  t.same(filtered.map((w) => w.name).sort(), ['@scope/a', 'pkg-b'], 'negation excludes a package')
+  t.end()
+})
+
+tap.test('install links workspaces, hoists shared deps and nests conflicts', (t) => {
+  const root = mkMonorepo()
+  t.teardown(() => fs.rmSync(root, { recursive: true, force: true }))
+
+  exec(`node ${bin} install`, { cwd: root }, (err) => {
+    t.error(err, 'workspace install ran without error')
+
+    const nm = path.join(root, 'node_modules')
+    t.ok(fs.lstatSync(path.join(nm, 'pkg-b')).isSymbolicLink(), 'pkg-b is symlinked into node_modules')
+    t.ok(fs.lstatSync(path.join(nm, '@scope', 'a')).isSymbolicLink(), 'scoped workspace is symlinked')
+
+    // cross-workspace dependency resolves through the link
+    t.ok(fs.existsSync(path.join(nm, '@scope', 'a', 'package.json')), 'pkg-b can reach @scope/a')
+
+    // shared registry dep hoisted; conflicting transitive version nested
+    const top = JSON.parse(fs.readFileSync(path.join(nm, 'is-number', 'package.json')))
+    t.match(top.version, /^7\./, 'is-number@7 (direct) hoisted to the top')
+    const nested = JSON.parse(fs.readFileSync(path.join(nm, 'is-odd', 'node_modules', 'is-number', 'package.json')))
+    t.match(nested.version, /^6\./, "is-odd's is-number@6 nested underneath")
+
+    // workspace packages are linked, never fetched into a real folder
+    t.notOk(fs.existsSync(path.join(nm, 'pkg-b', 'node_modules')), 'workspace was not re-installed from the registry')
+    t.end()
+  })
+})
+
+tap.test('lock records workspaces as npm-style link + source entries', (t) => {
+  const root = mkMonorepo()
+  t.teardown(() => fs.rmSync(root, { recursive: true, force: true }))
+
+  exec(`node ${bin} lock`, { cwd: root }, (err) => {
+    t.error(err, 'workspace lock ran without error')
+    const lock = JSON.parse(fs.readFileSync(path.join(root, 'package-lock.json'), 'utf8'))
+    const pkgs = lock.packages
+
+    t.same(pkgs[''].workspaces, ['packages/*'], 'root keeps the workspaces field')
+
+    // each workspace: a source entry + a link entry in node_modules
+    t.equal(pkgs['packages/a'].name, '@scope/a', 'workspace source entry at its real path')
+    t.same(pkgs['node_modules/@scope/a'], { resolved: 'packages/a', link: true }, 'scoped workspace linked to its source')
+    t.same(pkgs['node_modules/pkg-b'], { resolved: 'packages/b', link: true }, 'workspace linked to its source')
+
+    // shared dep hoisted, conflict nested — reached through the workspace links
+    t.match(pkgs['node_modules/is-number'].version, /^7\./, 'is-number@7 hoisted')
+    t.match(pkgs['node_modules/is-odd/node_modules/is-number'].version, /^6\./, 'is-number@6 nested')
+
+    // deps reached only via a workspace are production, not dev/optional
+    t.notOk(pkgs['node_modules/is-odd'].dev, 'transitive dep of a workspace is not marked dev')
+    t.end()
+  })
+})
+
+tap.test('lock -w <workspace> narrows the lockfile to that workspace', (t) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'dep-ws-'))
+  const write = (rel, obj) => {
+    const file = path.join(root, rel)
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(obj, null, 2))
+  }
+  write('package.json', { name: 'root', version: '1.0.0', private: true, workspaces: ['packages/*'], dependencies: { 'left-pad': '^1.3.0' } })
+  write('packages/a/package.json', { name: '@scope/a', version: '1.0.0', dependencies: { 'is-odd': '^3.0.0' } })
+  write('packages/b/package.json', { name: 'pkg-b', version: '1.0.0', dependencies: { 'is-number': '^7.0.0' } })
+  t.teardown(() => fs.rmSync(root, { recursive: true, force: true }))
+
+  exec(`node ${bin} lock -w @scope/a`, { cwd: root }, (err) => {
+    t.error(err, 'scoped lock ran without error')
+    const pkgs = JSON.parse(fs.readFileSync(path.join(root, 'package-lock.json'), 'utf8')).packages
+
+    t.ok(pkgs['node_modules/@scope/a'], 'targeted workspace is linked')
+    t.ok(pkgs['node_modules/is-odd'], "targeted workspace's dep is locked")
+    t.notOk(pkgs['node_modules/pkg-b'], 'other workspace is excluded')
+    t.notOk(pkgs['node_modules/left-pad'], 'root-only dep is excluded')
+    t.notOk(pkgs[''].dependencies, 'root entry declares no unresolved deps when scoped')
+
+    exec(`node ${bin} lock -w nope`, { cwd: root }, (err2) => {
+      t.ok(err2, 'unknown workspace exits non-zero')
+      t.end()
+    })
+  })
+})
+
+tap.test('resolveWorkspace matches by name and by path', (t) => {
+  const root = mkMonorepo()
+  t.teardown(() => fs.rmSync(root, { recursive: true, force: true }))
+  const workspaces = findWorkspaces(root, ['packages/*'])
+
+  t.equal(resolveWorkspace(workspaces, root, '@scope/a').dir, path.join(root, 'packages', 'a'), 'resolves by package name')
+  t.equal(resolveWorkspace(workspaces, root, 'packages/b').name, 'pkg-b', 'resolves by relative path')
+  t.equal(resolveWorkspace(workspaces, root, 'nope'), undefined, 'unknown target is undefined')
+  t.end()
+})
+
+tap.test('install <pkg> -w <workspace> adds dep to that workspace and hoists it', (t) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'dep-ws-'))
+  const write = (rel, obj) => {
+    const file = path.join(root, rel)
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(obj, null, 2))
+  }
+  write('package.json', { name: 'root', version: '1.0.0', private: true, workspaces: ['packages/*'] })
+  write('packages/a/package.json', { name: '@scope/a', version: '1.0.0' })
+  write('packages/b/package.json', { name: 'pkg-b', version: '1.0.0' })
+  t.teardown(() => fs.rmSync(root, { recursive: true, force: true }))
+
+  // by name, default save target is dependencies
+  exec(`node ${bin} install is-odd@^3.0.0 -w @scope/a`, { cwd: root }, (err) => {
+    t.error(err, 'install -w (by name) ran without error')
+    const a = JSON.parse(fs.readFileSync(path.join(root, 'packages', 'a', 'package.json')))
+    t.equal(a.dependencies && a.dependencies['is-odd'], '^3.0.0', 'dep written to the target workspace')
+    t.ok(fs.existsSync(path.join(root, 'node_modules', 'is-odd', 'package.json')), 'dep hoisted into root node_modules')
+    t.notOk(fs.existsSync(path.join(root, 'packages', 'b', 'package.json')) &&
+      JSON.parse(fs.readFileSync(path.join(root, 'packages', 'b', 'package.json'))).dependencies,
+    'other workspace untouched')
+
+    // by path + --save-dev
+    exec(`node ${bin} install is-number@^7.0.0 -w packages/b --save-dev`, { cwd: root }, (err2) => {
+      t.error(err2, 'install -w (by path) ran without error')
+      const b = JSON.parse(fs.readFileSync(path.join(root, 'packages', 'b', 'package.json')))
+      t.equal(b.devDependencies && b.devDependencies['is-number'], '^7.0.0', '--save-dev writes to the workspace devDependencies')
+
+      // unknown workspace fails
+      exec(`node ${bin} install left-pad -w nope`, { cwd: root }, (err3) => {
+        t.ok(err3, 'unknown workspace exits non-zero')
+        t.end()
+      })
+    })
+  })
+})