diff --git a/Cargo.toml b/Cargo.toml
index 4daa5b5..8013baf 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -16,6 +16,7 @@ members = [
   "rsquickjs",
 
   # xmas-js
+  "package-manager",
   "modules",
   "repl",
 ]
@@ -23,11 +24,12 @@ members = [
 [workspace.dependencies]
 # TODO: modify quickjs and rsquickjs-sys later
 rquickjs-sys = { version = "0.10.0", git = "https://github.com/DelSkayn/rquickjs", rev = "111951b1a31075bdff46684e0ff29f37ff2a04b2" }
-
 rsquickjs-core = { version = "0.10.0", path = "rsquickjs/core" }
 rsquickjs-macro = { version = "0.10.0", path = "rsquickjs/macro" }
 rsquickjs = { version = "0.10.0", path = "rsquickjs" }
+
 xmas-js-modules = { path = "modules" }
+xmas-package-manager = { path = "package-manager" }
 
 [dependencies]
 xmas-js-modules = { workspace = true }
diff --git a/README.md b/README.md
index eb50fe9..ef88945 100644
--- a/README.md
+++ b/README.md
@@ -207,6 +207,7 @@ Xmas.JS stands on the shoulders of giants:
 - **[rquickjs](https://github.com/DelSkayn/rquickjs)** - Rust bindings (we maintain a fork)
 - **[LLRT](https://github.com/awslabs/llrt)** - Inspiration and code for AWS Lambda optimization
 - **[Tokio](https://tokio.rs/)** - Async runtime that powers our I/O
+- **[Cotton](https://github.com/danielhuang/cotton)** - Package manager forked for our needs
 
 **Inspired by:**
 - [Deno](https://deno.land/) - Modern JavaScript runtime design
diff --git a/TODO.md b/TODO.md
index ee934ce..e2031fc 100644
--- a/TODO.md
+++ b/TODO.md
@@ -4,9 +4,6 @@ i decided to use WAMR,
 because it is more lightweight and mature than other runtimes like wasmtime or wasmer.
 in addition, WAMR has GC support and both JIT and AOT compilation modes.
 
-# shell for executing package.json scripts
-
-`deno_task_shell` is a great example
 
 # Networking API
 
@@ -32,13 +29,6 @@ and the host application can grant or deny those permissions.
 
 for both main thread and worker threads.
 
-# Package Manager
-
-i want to implement a fast and lightweight package manager,
-maybe i need to research at [cotton](https://github.com/danielhuang/cotton) which
-does not currently support Git repositories or local paths as dependencies;
-and i also want to support jsr and http package sources.
-
 # bundler / minifier / optimizer / typescript / lint / etc...
 
 OXC is great!
@@ -49,12 +39,11 @@ xmas: start repl
 - [ ] run <file>.<js/ts/mjs/cjs/jsx/tsx>
 - [ ] run also could behave like npx if not running a file
 
-- [ ] add : in project add to project.json dependencies, else add to global cache
-- [ ] remove : in project remove from project.json dependencies, else remove from global cache
-- [ ] install i : install all dependencies in project.json
-- [ ] update u : update all dependencies in project.json
-- [ ] list ls : list all dependencies in project.json, or global cache if not in project
-- [ ] execute exec <script> [args...] : execute script from project.json scripts
+- [x] add : in project add to project.json dependencies, else add to global cache
+- [x] install i : install all dependencies in project.json
+- [x] update u : update all dependencies in project.json
+- [x] list ls : list all dependencies in project.json, or global cache if not in project
+- [x] execute exec <script> [args...] : execute script from project.json scripts
 
 - [ ] compile <input> <output> (compile to quickjs bytecode)
 - [ ] init (project): create a new xmas project
@@ -107,12 +96,7 @@ i want to implement those API's as well.
 - [ ] WritableStream
 - [ ] WritableStreamDefaultController
 
-- [ ] WASM
-    - [ ] WebAssembly.Global
-    - [ ] WebAssembly.Instance
-    - [ ] WebAssembly.Memory
-    - [ ] WebAssembly.Module
-    - [ ] WebAssembly.Table
+
 
 Global methods / properties:
 - [x] globalThis
@@ -134,9 +118,30 @@ Global methods / properties:
 - [x] globalThis.setInterval() / globalThis.clearInterval()
 - [x] globalThis.structuredClone()
 
+---
+
 - [ ] WASM
+    - [ ] WebAssembly.Global
+    - [ ] WebAssembly.Instance
+    - [ ] WebAssembly.Memory
+    - [ ] WebAssembly.Module
+    - [ ] WebAssembly.Table
     - [ ] globalThis.WebAssembly.compile()
     - [ ] globalThis.WebAssembly.compileStreaming()
     - [ ] globalThis.WebAssembly.instantiate()
     - [ ] globalThis.WebAssembly.instantiateStreaming()
-    - [ ] globalThis.WebAssembly.validate()
\ No newline at end of file
+    - [ ] globalThis.WebAssembly.validate()
+
+---
+
+- [ ] globalThis
+  - [ ] $ for shell commands
+  - [ ] cli
+    - [ ] prompt
+    - [ ] ansi
+    - [ ] command
+
+- [x] Repl
+  - [ ] complete method/property name
+  - [ ] complete globalThis property name
+  - [x] package manager commands
\ No newline at end of file
diff --git a/package-manager/Cargo.toml b/package-manager/Cargo.toml
new file mode 100644
index 0000000..cb7bc19
--- /dev/null
+++ b/package-manager/Cargo.toml
@@ -0,0 +1,57 @@
+[package]
+name = "xmas-package-manager"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+tracing = "0.1.40"
+
+tokio = { version = "1.37.0", features = ["full"] }
+tokio-tar = { version = "*" }
+tokio-util = { version = "0.7.10", features = ["compat"] }
+
+itertools = "0.14.0"
+
+
+async-compression = { version = "0.4.9", features = ["tokio", "gzip"] }
+async-recursion = "1.1.1"
+cached = { version = "0.56.0", features = ["async"] }
+
+clap = { version = "4.5.4", features = ["derive"] }
+color-eyre = "0.6.3"
+compact_str = { version = "0.9.0", features = ["serde"] }
+dashmap = { version = "6.0.0", features = ["serde"] }
+async-channel = "2.5.0"
+futures = "0.3.31"
+indexmap = { version = "2.2.6", features = ["serde"] }
+indicatif = "0.18.0"
+multimap = "0.10.0"
+node-semver = { git = "https://github.com/danielhuang/node-semver-rs", rev = "bf4b103dc88b310c9dc049433aff1a14716e1e68" }
+notify = "=8.2.0"
+reqwest = { version = "0.12.4", features = [
+    "json",
+    "stream",
+    "rustls-tls",
+    "trust-dns",
+    "brotli",
+    "gzip",
+    "deflate",
+    "http2",
+], default-features = false }
+
+rustc-hash = "2.0.0"
+
+serde = { version = "1.0.200", features = ["derive", "rc"] }
+serde_json = { version = "1.0.116", features = ["preserve_order"] }
+serde_path_to_error = "0.1.16"
+
+
+toml = "0.9.0"
+tap = "1.0.1"
+url = { version = "2.5.0", features = ["serde"] }
+rand = "0.8.5"
+which = "8.0.0"
+deno_task_shell = "0.26.1"
+owo-colors = "4.2.3"
+junction = "1.3.0"
+exec = "0.3.1"
diff --git a/package-manager/src/cache.rs b/package-manager/src/cache.rs
new file mode 100644
index 0000000..7755936
--- /dev/null
+++ b/package-manager/src/cache.rs
@@ -0,0 +1,53 @@
+use std::{fmt::Debug, hash::Hash, sync::Arc};
+
+use dashmap::DashMap;
+use futures::{
+    future::{BoxFuture, Shared},
+    Future, FutureExt,
+};
+
+use crate::progress::PROGRESS_BAR;
+
+type SharedBoxFuture<T> = Shared<BoxFuture<'static, T>>;
+
+pub struct Cache<K: Eq + Hash + Clone + Send + Debug + 'static, V: Clone + Send + 'static> {
+    loader: Box<dyn Fn(K) -> BoxFuture<'static, V> + Send + Sync + 'static>,
+    map: DashMap<K, SharedBoxFuture<V>>,
+}
+
+impl<K: Eq + Hash + Clone + Send + Debug + 'static, V: Clone + Send + 'static> Cache<K, V> {
+    pub fn new<T, F>(loader: T) -> Self
+    where
+        F: Future<Output = V> + Sized + Send + 'static,
+        T: Fn(K) -> F + Send + Sync + Clone + 'static,
+    {
+        let loader = Arc::new(loader);
+
+        Self {
+            loader: Box::new({
+                move |key| {
+                    let loader = loader.clone();
+                    Box::pin({
+                        async move {
+                            PROGRESS_BAR.inc_length(1);
+                            let v = loader(key).await;
+                            PROGRESS_BAR.inc(1);
+                            v
+                        }
+                    })
+                }
+            }),
+            map: DashMap::new(),
+        }
+    }
+
+    pub async fn get(&self, key: K) -> V {
+        let f = self
+            .map
+            .entry(key.clone())
+            .or_insert_with(|| (self.loader)(key).boxed().shared())
+            .clone();
+
+        f.await
+    }
+}
diff --git a/package-manager/src/cli.rs b/package-manager/src/cli.rs
new file mode 100644
index 0000000..87cc133
--- /dev/null
+++ b/package-manager/src/cli.rs
@@ -0,0 +1,78 @@
+//! Command-line interface definitions for Cotton.
+
+use clap::Parser;
+use compact_str::CompactString;
+use node_semver::Version;
+use std::ffi::OsString;
+use std::path::PathBuf;
+
+#[derive(Parser, Debug)]
+#[clap(author, version, about, long_about = None)]
+pub struct Args {
+    /// Print verbose logs (including progress indicators)
+    #[clap(short, long, global = true)]
+    pub verbose: bool,
+    /// Prevent any modifications to the lockfile
+    #[clap(long, global = true)]
+    pub immutable: bool,
+    /// Run in a custom working directory
+    #[clap(long, global = true, alias = "cwd")]
+    pub working_dir: Option<PathBuf>,
+
+    /// Subcommand to execute
+    #[clap(subcommand)]
+    pub cmd: Subcommand,
+}
+
+#[derive(Parser, Debug, Clone)]
+pub enum Subcommand {
+    /// Install packages defined in package.json
+    #[clap(alias = "i")]
+    Install,
+    /// Prepare and save a newly planned lockfile
+    Update,
+    /// Add package to package.json
+    #[clap(alias = "a")]
+    Add {
+        names: Vec<CompactString>,
+        /// Add to `devDependencies` instead of `dependencies`
+        #[clap(short = 'D', long)]
+        dev: bool,
+        /// Pin dependencies to a specific version
+        #[clap(long, alias = "exact")]
+        pin: bool,
+    },
+    /// Run a script defined in package.json
+    Run {
+        name: CompactString,
+        #[clap(long)]
+        watch: Vec<PathBuf>,
+    },
+    /// Clean packages installed in `node_modules` and remove cache
+    Clean,
+    /// Update packages specified in package.json to the latest available version
+    Upgrade {
+        /// Pin dependencies to a specific version
+        #[clap(long)]
+        pin: bool,
+    },
+    /// Execute a command that is not specified as a script
+    Exec { exe: OsString, args: Vec<OsString> },
+    /// Remove package from package.json
+    Remove {
+        names: Vec<CompactString>,
+        /// Remove from `devDependencies` instead of `dependencies`
+        #[clap(short = 'D', long)]
+        dev: bool,
+    },
+    /// Find all uses of a given package
+    Why {
+        name: CompactString,
+        version: Option<Version>,
+    },
+    /// Create new projects from a `create-` starter kit
+    Create { name: CompactString },
+    /// Download (if needed) and execute a command
+    #[clap(name = "x")]
+    DownloadAndExec { name: OsString, args: Vec<OsString> },
+}
diff --git a/package-manager/src/commands/add.rs b/package-manager/src/commands/add.rs
new file mode 100644
index 0000000..012f19f
--- /dev/null
+++ b/package-manager/src/commands/add.rs
@@ -0,0 +1,68 @@
+//! Add command implementation.
+
+use color_eyre::eyre::{ContextCompat, Result};
+use color_eyre::owo_colors::OwoColorize;
+use compact_str::CompactString;
+use futures::future::try_join_all;
+use serde_json::Value;
+
+use crate::npm::fetch_package;
+use crate::progress::{log_progress, PROGRESS_BAR};
+use crate::util::{read_package_or_default, save_package};
+
+/// Execute the add command.
+pub async fn cmd_add(names: &[CompactString], dev: bool, pin: bool) -> Result<()> {
+    if names.is_empty() {
+        PROGRESS_BAR.suspend(|| println!("Note: no packages specified"));
+    }
+
+    add_packages(names, dev, pin).await
+}
+
+/// Add packages to package.json.
+pub async fn add_packages(names: &[CompactString], dev: bool, pin: bool) -> Result<()> {
+    let mut package: Value = read_package_or_default().await?;
+    let dependencies = package
+        .as_object_mut()
+        .wrap_err("`package.json` is invalid")?
+        .entry(if dev {
+            "devDependencies"
+        } else {
+            "dependencies"
+        })
+        .or_insert(Value::Object(Default::default()))
+        .as_object_mut()
+        .wrap_err("`package.json` contains non-object dependencies field")?;
+
+    PROGRESS_BAR.set_message("Resolving packages".to_string());
+    PROGRESS_BAR.set_length(names.len() as u64);
+
+    for (name, res) in try_join_all(names.iter().map(|name| async move {
+        let x = fetch_package(name).await.map(|res| (name, res));
+        PROGRESS_BAR.inc(1);
+        PROGRESS_BAR.set_message(format!("Resolved {name}"));
+        x
+    }))
+    .await?
+    {
+        let latest = res
+            .dist_tags
+            .get("latest")
+            .wrap_err("Package `latest` tag not specified")?;
+
+        let version = if pin {
+            latest.to_string()
+        } else {
+            format!("^{latest}")
+        };
+
+        dependencies.insert(name.to_string(), Value::String(version.to_string()));
+
+        PROGRESS_BAR.suspend(|| println!("Added {} {}", name.yellow(), version.yellow()));
+    }
+
+    PROGRESS_BAR.finish_and_clear();
+    save_package(&package).await?;
+
+    Ok(())
+}
diff --git a/package-manager/src/commands/clean.rs b/package-manager/src/commands/clean.rs
new file mode 100644
index 0000000..52995d3
--- /dev/null
+++ b/package-manager/src/commands/clean.rs
@@ -0,0 +1,17 @@
+//! Clean command implementation.
+
+use color_eyre::eyre::Result;
+use std::fs::remove_dir_all;
+use std::io::ErrorKind;
+
+/// Execute the clean command.
+pub fn cmd_clean() -> Result<()> {
+    for dir in ["node_modules", ".xmas"] {
+        match remove_dir_all(dir) {
+            Ok(()) => {}
+            Err(e) if e.kind() == ErrorKind::NotFound => {}
+            r => r?,
+        }
+    }
+    Ok(())
+}
diff --git a/package-manager/src/commands/create.rs b/package-manager/src/commands/create.rs
new file mode 100644
index 0000000..a36d82a
--- /dev/null
+++ b/package-manager/src/commands/create.rs
@@ -0,0 +1,14 @@
+//! Create command implementation.
+
+use color_eyre::eyre::Result;
+use compact_str::CompactString;
+use std::ffi::OsStr;
+
+use crate::commands::exec::{exec_with_args, install_bin_temp};
+
+/// Execute the create command.
+pub async fn cmd_create(args: &crate::Args, name: &CompactString) -> Result<()> {
+    let name = format!("create-{name}");
+    install_bin_temp(args, &name).await?;
+    exec_with_args(OsStr::new(&name), &[])
+}
diff --git a/package-manager/src/commands/exec.rs b/package-manager/src/commands/exec.rs
new file mode 100644
index 0000000..4366319
--- /dev/null
+++ b/package-manager/src/commands/exec.rs
@@ -0,0 +1,131 @@
+//! Exec command implementation.
+
+use color_eyre::eyre::{eyre, ContextCompat, Result};
+use compact_str::ToCompactString;
+use deno_task_shell::KillSignal;
+use rand::distributions::Alphanumeric;
+use rand::Rng;
+use serde_json::{Map, Value};
+use std::collections::HashMap;
+use std::env::{current_dir, current_exe, set_current_dir, set_var, temp_dir};
+use std::ffi::{OsStr, OsString};
+use std::path::PathBuf;
+use tokio::fs::create_dir;
+use which::which;
+
+use crate::commands::add::add_packages;
+use crate::commands::{install, join_paths};
+use crate::progress::log_verbose;
+use crate::util::save_package;
+
+/// Execute the exec command.
+pub async fn cmd_exec(args: &crate::Args, exe: &OsString, cmd_args: &[OsString]) -> Result<()> {
+    install(args).await?;
+    join_paths()?;
+
+    exec_with_args(exe.as_ref(), cmd_args)
+}
+
+/// Execute the download-and-exec (x) command.
+pub async fn cmd_download_and_exec(
+    args: &crate::Args,
+    name: &OsString,
+    cmd_args: &[OsString],
+) -> Result<()> {
+    if let Err(e) = which(name) {
+        log_verbose(&e.to_string());
+        install_bin_temp(args, name.to_str().wrap_err("package name invalid")?).await?;
+    }
+    exec_with_args(name.as_ref(), cmd_args)
+}
+
+/// Execute a command with arguments
+#[tracing::instrument]
+pub fn exec_with_args(exe: &OsStr, args: &[OsString]) -> Result<()> {
+    let mut args = args.to_vec();
+    args.insert(0, exe.to_os_string());
+    let error = exec::execvp(&exe, &args);
+    match error {
+        exec::Error::BadArgument(nul_error) => Err(eyre!("Invalid argument: {}", nul_error)),
+        exec::Error::Errno(errno) => {
+            if errno.0 != 0 {
+                Err(eyre!("Failed to execute command: errno {}", errno.0))
+            } else {
+                Ok(())
+            }
+        }
+    }
+}
+
+/// Install a binary package to a temporary directory.
+pub async fn install_bin_temp(args: &crate::Args, package_name: &str) -> Result<()> {
+    let orig_dir = current_dir()?;
+
+    let dir_name: String = rand::thread_rng()
+        .sample_iter(&Alphanumeric)
+        .take(10)
+        .map(char::from)
+        .collect();
+
+    let mut temp_dir = temp_dir();
+    temp_dir.push(dir_name);
+    create_dir(&temp_dir).await?;
+    set_current_dir(&temp_dir)?;
+    log_verbose(&format!("Now in {temp_dir:?}"));
+
+    save_package(&Value::Object(Map::new())).await?;
+    add_packages(&[package_name.to_compact_string()], false, false).await?;
+    install(args).await?;
+    set_var("npm_config_user_agent", "yarn/1.22.19 npm/none xmas/0.0.0");
+    let current_exe = current_exe().map(|p| p.to_string_lossy().to_string())?;
+
+    std::fs::create_dir_all("node_modules/.bin")?;
+    #[cfg(windows)]
+    {
+        // 使用 cmd shim 代替符号链接
+        let shim_content = format!("@ECHO off\r\n\"{current_exe}\" %*\r\n");
+        std::fs::write("node_modules/.bin/yarn.cmd", &shim_content)?;
+        let ps1_content =
+            format!("#!/usr/bin/env pwsh\r\n& \"{current_exe}\" $args\r\nexit $LASTEXITCODE\r\n");
+        std::fs::write("node_modules/.bin/yarn.ps1", &ps1_content)?;
+    }
+    #[cfg(unix)]
+    {
+        crate::plan::symlink(&current_exe, "node_modules/.bin/yarn", None)?;
+    }
+
+    join_paths()?;
+
+    set_current_dir(&orig_dir)?;
+    log_verbose(&format!("Now in {orig_dir:?}"));
+
+    Ok(())
+}
+
+pub async fn shell(
+    text: &str,
+    cwd: PathBuf,
+    new_env: HashMap<OsString, OsString>,
+    kill_signal: KillSignal,
+) -> Result<i32> {
+    // parse
+    let list =
+        deno_task_shell::parser::parse(&text).map_err(|e| eyre!("Shell parse error: {}", e))?;
+
+    // execute
+    let mut env_vars = std::env::vars_os().collect::<HashMap<_, _>>();
+    for (k, v) in new_env {
+        let _ = env_vars.insert(k, v);
+    }
+
+    let exit_code = deno_task_shell::execute(
+        list,
+        env_vars,
+        cwd,
+        Default::default(), // custom commands
+        kill_signal,
+    )
+    .await;
+
+    Ok(exit_code)
+}
diff --git a/package-manager/src/commands/install.rs b/package-manager/src/commands/install.rs
new file mode 100644
index 0000000..3dcce0e
--- /dev/null
+++ b/package-manager/src/commands/install.rs
@@ -0,0 +1,210 @@
+//! Install command implementation.
+
+use async_recursion::async_recursion;
+use color_eyre::eyre::{eyre, Result};
+use color_eyre::owo_colors::OwoColorize;
+use compact_str::{CompactString, ToCompactString};
+use deno_task_shell::KillSignal;
+use itertools::Itertools;
+use serde_json::Value;
+use std::collections::HashMap;
+use std::env;
+use std::ffi::OsString;
+use std::io::ErrorKind;
+use std::path::PathBuf;
+use std::time::Instant;
+use tokio::fs::{create_dir_all, read_to_string};
+use tokio::process::Command;
+
+use crate::commands::exec::shell;
+use crate::config::read_config;
+use crate::npm::DependencyTree;
+use crate::package::PackageMetadata;
+use crate::plan::{execute_plan, setup_bins, tree_size, Plan};
+use crate::progress::{finish_progress, log_progress, log_verbose, set_total, PROGRESS_BAR};
+use crate::resolve::Lockfile;
+use crate::scoped_path::scoped_join;
+use crate::util::{load_graph_from_lockfile, read_package, write_json};
+use crate::Args;
+
+/// Execute the install command.
+pub async fn cmd_install(args: &Args) -> Result<()> {
+    install(args).await
+}
+
+/// Prepare a plan for installing packages.
+pub async fn prepare_plan(args: &Args, package: &PackageMetadata) -> Result<Plan> {
+    log_progress("Preparing");
+
+    let mut graph = load_graph_from_lockfile().await;
+
+    if !args.immutable {
+        graph.append(package.iter_all(), true).await?;
+        write_json("xmas.lock", Lockfile::new(graph.clone())).await?;
+    }
+
+    log_progress("Retrieved dependency graph");
+
+    let trees = graph.build_trees(&package.iter_all().collect_vec())?;
+    log_progress(&format!("Fetched {} root deps", trees.len().yellow()));
+
+    let plan = Plan::new(
+        trees
+            .iter()
+            .map(|x| (x.root.name.to_compact_string(), x.clone()))
+            .collect(),
+    );
+
+    log_progress(&format!(
+        "Planned {} dependencies",
+        plan.trees.len().yellow()
+    ));
+
+    Ok(plan)
+}
+
+async fn read_plan(path: &str) -> Result<Plan> {
+    let plan = read_to_string(path).await?;
+    Ok(serde_json::from_str(&plan)?)
+}
+
+/// Verify that the current installation matches the plan.
+pub async fn verify_installation(package: &PackageMetadata, plan: &Plan) -> Result<bool> {
+    let installed = read_plan("node_modules/.xmas/plan.json").await?;
+
+    if &installed != plan {
+        return Ok(false);
+    }
+
+    Ok(installed.satisfies(package))
+}
+
+async fn exec_install_scripts_in(stack: &[CompactString]) -> Result<()> {
+    let path = stack.join("/node_modules/");
+
+    let dir = scoped_join("node_modules", path)?;
+
+    let package_json = match read_to_string(dir.join("package.json")).await {
+        Ok(x) => x,
+        Err(e) if e.kind() == ErrorKind::NotFound => {
+            return Ok(());
+        }
+        Err(e) => return Err(e.into()),
+    };
+
+    let package_json: PackageMetadata = serde_json::from_str(&package_json)?;
+
+    for script_name in ["preinstall", "install", "postinstall"] {
+        if let Some(Value::String(script)) = package_json.scripts.get(script_name) {
+            PROGRESS_BAR.suspend(|| {
+                println!("Executing {script_name} script for {}", stack.join(" > "));
+            });
+
+            let mut new_env = HashMap::new();
+            new_env.insert(OsString::from("PATH"), new_path()?);
+            let child = shell(script, dir.clone(), new_env, KillSignal::default()).await?;
+
+            if child > 0 {
+                return Err(eyre!(
+                    "{} script failed with exit code {}",
+                    script_name,
+                    child
+                ));
+            }
+        }
+    }
+
+    Ok(())
+}
+
+async fn exec_install_scripts(
+    tree: &DependencyTree,
+    initial_stack: &[CompactString],
+) -> Result<()> {
+    let mut work_stack: Vec<(&DependencyTree, Vec<CompactString>)> =
+        vec![(tree, initial_stack.to_vec())];
+
+    while let Some((current_tree, mut stack)) = work_stack.pop() {
+        exec_install_scripts_in(&stack).await?;
+
+        stack.push(current_tree.root.name.clone());
+        for child_tree in current_tree.children.values() {
+            work_stack.push((child_tree, stack.clone()));
+        }
+    }
+
+    Ok(())
+}
+
+/// Install packages based on package.json.
+pub async fn install(args: &Args) -> Result<()> {
+    let package = read_package().await?;
+
+    init_storage().await?;
+    let config = read_config().await?;
+
+    let start = Instant::now();
+
+    let plan = prepare_plan(args, &package).await?;
+    let size = tree_size(&plan.trees);
+    set_total(size as u64 * 2); // download + install
+
+    if matches!(verify_installation(&package, &plan).await, Ok(true)) {
+        log_verbose("Packages already installed")
+    } else {
+        execute_plan(plan.clone()).await?;
+
+        finish_progress();
+        PROGRESS_BAR.suspend(|| {
+            if size > 0 {
+                println!(
+                    "Installed {} packages in {}ms",
+                    size.yellow(),
+                    start.elapsed().as_millis().yellow()
+                )
+            }
+        });
+
+        if !config.disallow_install_scripts {
+            for (name, tree) in plan.trees.iter() {
+                exec_install_scripts(tree, &mut vec![name.clone()]).await?;
+            }
+        }
+
+        setup_bins(&plan).await?;
+
+        write_json("node_modules/.xmas/plan.json", &plan).await?;
+    }
+
+    PROGRESS_BAR.finish_and_clear();
+
+    Ok(())
+}
+
+/// Create a new PATH with node_modules/.bin prepended.
+pub fn new_path() -> Result<OsString> {
+    let path = env::var_os("PATH").unwrap_or_default();
+    let mut paths = env::split_paths(&path).collect::<Vec<_>>();
+    let new = PathBuf::from("node_modules/.bin");
+    paths.insert(0, new);
+    let new_path = env::join_paths(paths)?;
+    Ok(new_path)
+}
+
+/// Join node_modules/.bin to the PATH environment variable.
+pub fn join_paths() -> Result<()> {
+    let path = new_path()?;
+    log_verbose(&format!("Setting PATH to {path:?}"));
+    env::set_var("PATH", path);
+
+    Ok(())
+}
+
+/// Initialize storage directories.
+pub async fn init_storage() -> Result<()> {
+    create_dir_all(".xmas/store").await?;
+    create_dir_all("node_modules/.xmas").await?;
+    create_dir_all("node_modules/.bin").await?;
+
+    Ok(())
+}
diff --git a/package-manager/src/commands/mod.rs b/package-manager/src/commands/mod.rs
new file mode 100644
index 0000000..6eb6e9d
--- /dev/null
+++ b/package-manager/src/commands/mod.rs
@@ -0,0 +1,51 @@
+//! Command implementations for Cotton CLI.
+
+mod add;
+mod clean;
+mod create;
+pub mod exec;
+mod install;
+mod remove;
+mod run;
+mod update;
+mod upgrade;
+mod why;
+
+pub use add::cmd_add;
+pub use clean::cmd_clean;
+pub use create::cmd_create;
+pub use exec::cmd_exec;
+pub use install::{cmd_install, init_storage, install, join_paths, new_path};
+pub use remove::cmd_remove;
+pub use run::cmd_run;
+pub use update::cmd_update;
+pub use upgrade::cmd_upgrade;
+pub use why::cmd_why;
+
+use crate::{cli::Subcommand, Args};
+use color_eyre::eyre::Result;
+
+/// Execute the appropriate command based on CLI arguments.
+pub async fn execute_command(args: &Args) -> Result<()> {
+    match &args.cmd {
+        Subcommand::Install => cmd_install(&args).await,
+        Subcommand::Update => cmd_update(&args).await,
+        Subcommand::Add { names, dev, pin } => cmd_add(&names, *dev, *pin).await,
+        Subcommand::Run { name, watch } => cmd_run(&args, &name, &watch).await,
+        Subcommand::Clean => cmd_clean(),
+        Subcommand::Upgrade { pin } => cmd_upgrade(*pin).await,
+
+        // TODO: fix with deno task shell
+        Subcommand::Exec {
+            exe,
+            args: cmd_args,
+        } => cmd_exec(&args, exe, cmd_args).await,
+        Subcommand::Remove { names, dev } => cmd_remove(&names, *dev).await,
+        Subcommand::Why { name, version } => cmd_why(&name, version.as_ref()).await,
+        Subcommand::Create { name } => cmd_create(&args, &name).await,
+        Subcommand::DownloadAndExec {
+            name,
+            args: cmd_args,
+        } => exec::cmd_download_and_exec(&args, name, cmd_args).await,
+    }
+}
diff --git a/package-manager/src/commands/remove.rs b/package-manager/src/commands/remove.rs
new file mode 100644
index 0000000..29a6623
--- /dev/null
+++ b/package-manager/src/commands/remove.rs
@@ -0,0 +1,40 @@
+//! Remove command implementation.
+
+use color_eyre::eyre::{eyre, ContextCompat, Result};
+use compact_str::CompactString;
+use serde_json::Value;
+
+use crate::progress::{log_progress, PROGRESS_BAR};
+use crate::util::{read_package_or_default, save_package};
+
+/// Execute the remove command.
+pub async fn cmd_remove(names: &[CompactString], dev: bool) -> Result<()> {
+    if names.is_empty() {
+        PROGRESS_BAR.suspend(|| println!("Note: no packages specified"));
+    }
+
+    let mut package: Value = read_package_or_default().await?;
+    let dependencies = package
+        .as_object_mut()
+        .wrap_err("`package.json` is invalid")?
+        .entry(if dev {
+            "devDependencies"
+        } else {
+            "dependencies"
+        })
+        .or_insert(Value::Object(Default::default()))
+        .as_object_mut()
+        .wrap_err("`package.json` contains non-object dependencies field")?;
+
+    for name in names {
+        dependencies
+            .remove(&name.to_string())
+            .wrap_err(eyre!("Package `{name}` is not specified in `package.json`"))?;
+    }
+
+    log_progress(&format!("Removed {} dependencies", names.len()));
+
+    save_package(&package).await?;
+
+    Ok(())
+}
diff --git a/package-manager/src/commands/run.rs b/package-manager/src/commands/run.rs
new file mode 100644
index 0000000..01f9414
--- /dev/null
+++ b/package-manager/src/commands/run.rs
@@ -0,0 +1,69 @@
+//! Run command implementation.
+
+use color_eyre::eyre::{ContextCompat, Result};
+use color_eyre::owo_colors::OwoColorize;
+use compact_str::CompactString;
+use deno_task_shell::KillSignal;
+use std::collections::HashMap;
+use std::ffi::OsString;
+use std::path::PathBuf;
+use std::process::exit;
+
+use crate::commands::exec::shell;
+use crate::commands::{install, join_paths, new_path};
+use crate::progress::PROGRESS_BAR;
+use crate::util::read_package;
+use crate::watch::async_watch;
+
+/// Execute the run command.
+pub async fn cmd_run(arg: &crate::Args, name: &CompactString, watch: &[PathBuf]) -> Result<()> {
+    join_paths()?;
+
+    loop {
+        let finish = async {
+            let event = async_watch(watch.iter().map(|x| x.as_ref())).await?;
+            PROGRESS_BAR.suspend(|| {
+                println!(
+                    "{} File modified: {}",
+                    " WATCH ".on_purple(),
+                    event.paths[0].to_string_lossy()
+                )
+            });
+            PROGRESS_BAR.finish_and_clear();
+
+            Ok(()) as Result<_>
+        };
+
+        let install = async {
+            let package = read_package().await?;
+
+            let script = package
+                .scripts
+                .get(name)
+                .wrap_err(format!("Script `{name}` is not defined"))?
+                .as_str()
+                .wrap_err(format!("Script `{name}` is not a string"))?;
+
+            install(arg).await?;
+            let cwd = std::env::current_dir()?;
+            let mut new_env = HashMap::new();
+            new_env.insert(OsString::from("PATH"), new_path()?);
+            let exit_code = shell(script, cwd, new_env, KillSignal::default()).await?;
+
+            if exit_code != 0 {
+                exit(exit_code);
+            }
+
+            Ok(()) as Result<_>
+        };
+
+        tokio::select! {
+            res = finish => {
+                res?;
+            }
+            res = install => {
+                res?;
+            }
+        }
+    }
+}
diff --git a/package-manager/src/commands/update.rs b/package-manager/src/commands/update.rs
new file mode 100644
index 0000000..c60ceae
--- /dev/null
+++ b/package-manager/src/commands/update.rs
@@ -0,0 +1,40 @@
+//! Update command implementation.
+
+use color_eyre::eyre::eyre;
+use color_eyre::eyre::Result;
+use color_eyre::owo_colors::OwoColorize;
+use color_eyre::Help;
+use std::time::Instant;
+
+use crate::commands::init_storage;
+use crate::progress::PROGRESS_BAR;
+use crate::resolve::{Graph, Lockfile};
+use crate::util::{read_package, write_json};
+use crate::Args;
+
+/// Execute the update command.
+pub async fn cmd_update(args: &Args) -> Result<()> {
+    if args.immutable {
+        return Err(eyre!("Cannot update lockfile").suggestion("Remove the --immutable flag"));
+    }
+
+    let package = read_package().await?;
+
+    init_storage().await?;
+
+    let start = Instant::now();
+
+    let mut graph = Graph::default();
+    graph.append(package.iter_all(), false).await?;
+    write_json("xmas.lock", Lockfile::new(graph.clone())).await?;
+
+    PROGRESS_BAR.suspend(|| {
+        println!(
+            "Prepared {} packages in {}ms",
+            graph.relations.len().yellow(),
+            start.elapsed().as_millis().yellow()
+        )
+    });
+
+    Ok(())
+}
diff --git a/package-manager/src/commands/upgrade.rs b/package-manager/src/commands/upgrade.rs
new file mode 100644
index 0000000..f1cef6c
--- /dev/null
+++ b/package-manager/src/commands/upgrade.rs
@@ -0,0 +1,25 @@
+//! Upgrade command implementation.
+
+use color_eyre::eyre::Result;
+use itertools::Itertools;
+
+use crate::commands::add::add_packages;
+use crate::util::read_package;
+
+/// Execute the upgrade command.
+pub async fn cmd_upgrade(pin: bool) -> Result<()> {
+    let package = read_package().await?;
+    add_packages(
+        &package.dependencies.keys().cloned().collect_vec(),
+        false,
+        pin,
+    )
+    .await?;
+    add_packages(
+        &package.dev_dependencies.keys().cloned().collect_vec(),
+        true,
+        pin,
+    )
+    .await?;
+    Ok(())
+}
diff --git a/package-manager/src/commands/why.rs b/package-manager/src/commands/why.rs
new file mode 100644
index 0000000..da16bd4
--- /dev/null
+++ b/package-manager/src/commands/why.rs
@@ -0,0 +1,93 @@
+//! Why command implementation.
+
+use color_eyre::eyre::{eyre, Result};
+use color_eyre::owo_colors::OwoColorize;
+use compact_str::CompactString;
+use itertools::Itertools;
+use multimap::MultiMap;
+use node_semver::Version;
+use rustc_hash::FxHashSet;
+use std::collections::VecDeque;
+
+use crate::package::PackageSpecifier;
+use crate::resolve::Graph;
+use crate::util::{load_graph_from_lockfile, read_package};
+
+/// Execute the why command.
+pub async fn cmd_why(name: &CompactString, version: Option<&Version>) -> Result<()> {
+    let package = read_package().await?;
+
+    let graph = load_graph_from_lockfile().await;
+
+    let map = build_map(&graph)?;
+
+    let mut seen = FxHashSet::default();
+    let mut queue = VecDeque::new();
+
+    if let Some(version) = version {
+        queue.push_back((name.clone(), version.clone()));
+    } else {
+        for (req, resolved) in graph.relations.iter() {
+            if name == &req.name {
+                queue.push_back((name.clone(), resolved.version.clone()));
+            }
+        }
+    }
+
+    if queue.is_empty() {
+        return Err(eyre!("Package {} is not used", name));
+    }
+
+    while let Some((name, version)) = queue.pop_front() {
+        if seen.insert((name.clone(), version.clone())) {
+            if let Some(required_by) = map.get_vec(&(name.clone(), version.clone())) {
+                let required_by: FxHashSet<_> = required_by
+                    .iter()
+                    .map(|x| graph.resolve_req(x))
+                    .try_collect()?;
+                if !required_by.is_empty() {
+                    println!(
+                        "{}",
+                        format!("{}@{} is used by:", name.yellow(), version).bold()
+                    );
+                    for dep in required_by {
+                        queue.push_back((dep.package.name.clone(), dep.version.clone()));
+                        println!(" - {}@{}", dep.package.name, dep.version);
+                    }
+                    println!();
+                }
+            } else if package
+                .iter_all()
+                .any(|x| x.name == name && x.version.satisfies(&version))
+            {
+                println!(
+                    "{}",
+                    format!("{}@{} is used by package.json", name.yellow(), version).bold()
+                );
+                println!();
+            } else {
+                return Err(eyre!("Package {}@{} is not used", name, version));
+            }
+        }
+    }
+
+    println!("Analyzed {} packages", seen.len().yellow());
+
+    Ok(())
+}
+
+fn build_map(graph: &Graph) -> Result<MultiMap<(CompactString, Version), PackageSpecifier>> {
+    let mut map = MultiMap::new();
+
+    for (from, to) in graph.relations.iter() {
+        for child_req in to.package.iter() {
+            let child_dep = graph.resolve_req(&child_req)?;
+            map.insert(
+                (child_dep.package.name.clone(), child_dep.version),
+                from.clone(),
+            );
+        }
+    }
+
+    Ok(map)
+}
diff --git a/package-manager/src/config.rs b/package-manager/src/config.rs
new file mode 100644
index 0000000..b545761
--- /dev/null
+++ b/package-manager/src/config.rs
@@ -0,0 +1,80 @@
+use color_eyre::eyre::Result;
+use reqwest::RequestBuilder;
+use serde::{Deserialize, Serialize};
+use std::env;
+use tokio::fs::read_to_string;
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Hash, Debug, Default)]
+#[serde(deny_unknown_fields)]
+pub struct Config {
+    #[serde(default)]
+    pub registry: Vec<Registry>,
+    #[serde(default)]
+    pub disallow_install_scripts: bool,
+}
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Hash, Debug)]
+#[serde(deny_unknown_fields)]
+pub struct Registry {
+    pub url: String,
+    pub scope: Option<String>,
+    pub auth: Option<RegistryAuth>,
+}
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Hash, Debug)]
+#[serde(rename_all = "snake_case")]
+#[serde(untagged)]
+#[serde(deny_unknown_fields)]
+pub enum RegistryAuth {
+    Token {
+        token: AuthSource,
+    },
+    Basic {
+        username: AuthSource,
+        #[serde(default)]
+        password: Option<AuthSource>,
+    },
+}
+
+pub fn client_auth(req: RequestBuilder, auth: Option<&RegistryAuth>) -> Result<RequestBuilder> {
+    Ok(match auth {
+        Some(RegistryAuth::Token { token }) => {
+            let token = token.read_token()?;
+            req.bearer_auth(token)
+        }
+        Some(RegistryAuth::Basic { username, password }) => {
+            let username = username.read_token()?;
+            let password = password.as_ref().map(|x| x.read_token()).transpose()?;
+            req.basic_auth(username, password)
+        }
+        None => req,
+    })
+}
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Hash, Debug)]
+#[serde(rename_all = "snake_case")]
+#[serde(untagged)]
+#[serde(deny_unknown_fields)]
+pub enum AuthSource {
+    Inline(String),
+    FromEnv { from_env: String },
+}
+
+impl AuthSource {
+    #[tracing::instrument]
+    pub fn read_token(&self) -> Result<String> {
+        match self {
+            AuthSource::Inline(x) => Ok(x.clone()),
+            AuthSource::FromEnv { from_env } => Ok(env::var(from_env)?),
+        }
+    }
+}
+
+pub async fn read_config() -> Result<Config> {
+    let config = read_to_string("xmas.toml").await;
+    if let Ok(config) = config {
+        Ok(toml::from_str(&config)?)
+    } else {
+        Ok(Config::default())
+    }
+}
diff --git a/package-manager/src/lib.rs b/package-manager/src/lib.rs
new file mode 100644
index 0000000..bf17387
--- /dev/null
+++ b/package-manager/src/lib.rs
@@ -0,0 +1,36 @@
+//! Cotton - A fast JavaScript/Node.js package manager.
+//!
+//! This library provides the core functionality for managing npm packages,
+//! resolving dependencies, and executing package scripts.
+
+pub mod cache;
+pub mod cli;
+pub mod commands;
+pub mod config;
+pub mod npm;
+pub mod package;
+pub mod plan;
+pub mod progress;
+pub mod resolve;
+pub mod scoped_path;
+pub mod util;
+pub mod watch;
+
+pub use cli::{Args, Subcommand};
+pub use commands::execute_command;
+pub use progress::PROGRESS_BAR;
+
+// ---
+
+use color_eyre::eyre::Result;
+use std::env::set_current_dir;
+
+pub async fn package_manager(args: &Args) -> Result<()> {
+    color_eyre::install()?;
+    if let Some(cwd) = &args.working_dir {
+        set_current_dir(cwd)?;
+    }
+    execute_command(&args).await?;
+    PROGRESS_BAR.finish_and_clear();
+    Ok(())
+}
diff --git a/package-manager/src/npm.rs b/package-manager/src/npm.rs
new file mode 100644
index 0000000..a9bcb3c
--- /dev/null
+++ b/package-manager/src/npm.rs
@@ -0,0 +1,269 @@
+use async_compression::tokio::bufread::GzipDecoder;
+use async_recursion::async_recursion;
+use cached::proc_macro::cached;
+use color_eyre::{
+    eyre::{eyre, ContextCompat, Result},
+    Report,
+};
+use compact_str::{CompactString, ToCompactString};
+use futures::TryStreamExt;
+use indexmap::IndexMap;
+use itertools::Itertools;
+use node_semver::Version;
+use owo_colors::OwoColorize;
+use rustc_hash::{FxHashMap, FxHashSet};
+use serde::{Deserialize, Serialize};
+use std::{
+    collections::{BTreeMap, BTreeSet},
+    path::MAIN_SEPARATOR,
+    sync::{Arc, LazyLock},
+};
+use std::{fmt::Debug, io};
+use tap::Pipe;
+use tokio::{io::AsyncReadExt, sync::Semaphore};
+use tokio_tar::Archive;
+use tokio_util::io::StreamReader;
+
+use crate::{
+    cache::Cache,
+    config::{client_auth, read_config, Registry},
+    package::{Dist, PackageInfo, PackageMetadata, PackageSpecifier},
+    progress::{log_progress, log_verbose},
+    util::{decode_json, retry, ArcResult, VersionSpecifier, CLIENT, CLIENT_LIMIT, CLIENT_Z},
+};
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Debug)]
+pub struct RegistryResponse {
+    #[serde(rename = "dist-tags")]
+    pub dist_tags: FxHashMap<CompactString, CompactString>,
+    pub versions: IndexMap<Version, PackageMetadata>,
+}
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Hash, Debug, Default)]
+pub struct PlatformMap(BTreeSet<CompactString>);
+
+impl PlatformMap {
+    pub fn allowed(&self) -> impl Iterator<Item = &str> {
+        self.0
+            .iter()
+            .filter(|x| !x.starts_with('!'))
+            .map(|x| x.as_str())
+    }
+
+    pub fn blocked(&self) -> impl Iterator<Item = &str> {
+        self.0.iter().filter_map(|x| x.strip_prefix('!'))
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.0.is_empty()
+    }
+
+    pub fn is_supported(&self, platform: &str) -> bool {
+        if self.is_empty() {
+            true
+        } else {
+            self.allowed().any(|o| o == platform) && !self.blocked().any(|o| o == platform)
+        }
+    }
+}
+
+async fn select_registry(name: &str) -> Result<Registry> {
+    for registry in read_config().await?.registry {
+        if let Some(scope) = &registry.scope {
+            if name.starts_with(scope) {
+                return Ok(registry);
+            }
+        } else {
+            return Ok(registry);
+        }
+    }
+
+    Ok(Registry {
+        url: "https://registry.npmjs.org".into(),
+        scope: None,
+        auth: None,
+    })
+}
+
+#[tracing::instrument]
+pub async fn fetch_package(name: &str) -> Result<Arc<RegistryResponse>> {
+    #[tracing::instrument]
+    async fn fetch_package(name: &str) -> Result<RegistryResponse> {
+        static S: LazyLock<Semaphore> = LazyLock::new(|| Semaphore::new(CLIENT_LIMIT));
+        let _permit = S.acquire().await.unwrap();
+
+        let selected_registry = select_registry(name).await?;
+
+        retry(|| async {
+            decode_json(
+                &CLIENT_Z
+                    .get(format!("{}/{name}", selected_registry.url))
+                    .pipe(|x| client_auth(x, selected_registry.auth.as_ref()))?
+                    .send()
+                    .await?
+                    .error_for_status()?
+                    .bytes()
+                    .await?,
+            )
+            .map_err(|e| eyre!("[{name}] {e}"))
+        })
+        .await
+    }
+
+    static CACHE: LazyLock<Cache<CompactString, ArcResult<Arc<RegistryResponse>>>> = LazyLock::new(|| {
+        Cache::new(|key: CompactString| async move {
+            fetch_package(&key).await.map(Arc::new).map_err(Arc::new)
+        })
+    });
+
+    CACHE
+        .get(name.to_compact_string())
+        .await
+        .map_err(Report::msg)
+}
+
+#[tracing::instrument]
+#[cached(result)]
+#[async_recursion]
+pub async fn fetch_versioned_package(d: PackageSpecifier) -> Result<(Version, Arc<PackageInfo>)> {
+    log_progress(&format!("Fetched {}", d.name.bright_blue()));
+
+    match &d.version {
+        VersionSpecifier::Other(tag) => {
+            let res = fetch_package(&d.name).await?;
+            let tag = res
+                .dist_tags
+                .get(tag)
+                .wrap_err_with(|| eyre!("Version cannot be satisfied: {} {}", d.name, d.version))?;
+            let version = Version::parse(tag)?;
+            let package = res.versions.get(&version).wrap_err_with(|| {
+                eyre!(
+                    "Tag refers to a version that does not exist: {} - {} refers to {}",
+                    d.name,
+                    d.version,
+                    version
+                )
+            })?;
+
+            Ok((version, Arc::new(package.clone().info())))
+        }
+        VersionSpecifier::Range(_) => {
+            let res = fetch_package(&d.name).await?;
+            let (version, package) = res
+                .versions
+                .iter()
+                .sorted_by_key(|(v, _)| !v.is_prerelease())
+                .rfind(|(v, _)| d.version.satisfies(v))
+                .wrap_err_with(|| {
+                    eyre!(
+                        "Version cannot be satisfied: expected {} {}",
+                        d.name,
+                        d.version
+                    )
+                })?;
+
+            Ok((version.clone(), Arc::new(package.clone().info())))
+        }
+        VersionSpecifier::DirectUrl(url) => {
+            log_verbose(&format!(
+                "Downloading metadata for {}@{}",
+                d.name, d.version
+            ));
+
+            let res = CLIENT
+                .get(url.clone())
+                .send()
+                .await?
+                .error_for_status()?
+                .bytes_stream()
+                .map_err(|e| io::Error::new(io::ErrorKind::Other, e));
+
+            let reader = StreamReader::new(res);
+            let reader = GzipDecoder::new(reader);
+
+            let mut archive = Archive::new(reader);
+            let mut entries = archive.entries()?;
+
+            while let Some(mut entry) = entries.try_next().await? {
+                if entry.path()?.to_str() == Some("package/package.json") {
+                    let mut buf = String::new();
+                    entry.read_to_string(&mut buf).await?;
+
+                    let mut package: PackageMetadata = serde_json::from_str(&buf)?;
+                    let version = package.version.clone().wrap_err_with(|| {
+                        format!("Package from {url} does not specify a version")
+                    })?;
+
+                    package.dist.tarball = url.to_compact_string();
+
+                    return Ok((version, Arc::new(package.info())));
+                }
+            }
+
+            Err(eyre!("Package from {url} does not contain package.json"))
+        }
+        VersionSpecifier::Prefixed(prefixed) => match prefixed.prefix.as_str() {
+            "npm" => {
+                let (actual_name, actual_req) = prefixed
+                    .rest
+                    .rsplit_once('@')
+                    .ok_or_else(|| eyre!("Invalid prefixed version: {prefixed}"))?;
+
+                let actual_req = VersionSpecifier::Range(actual_req.parse()?);
+
+                let inner_req = PackageSpecifier {
+                    name: actual_name.to_compact_string(),
+                    version: actual_req,
+                    optional: d.optional,
+                };
+
+                let (inner_version, mut inner_pkg) = fetch_versioned_package(inner_req).await?;
+                Arc::make_mut(&mut inner_pkg).name = d.name;
+
+                Ok((inner_version, inner_pkg))
+            }
+            _ => Err(eyre!("Unsupported version prefix")),
+        },
+    }
+}
+
+#[derive(Serialize, Deserialize, PartialEq, Eq, Clone, Debug)]
+pub struct DependencyTree {
+    #[serde(flatten)]
+    pub root: Dependency,
+    pub children: FxHashMap<CompactString, DependencyTree>,
+}
+
+impl DependencyTree {
+    pub fn filter(&self, exclude: &FxHashSet<Dependency>) -> Self {
+        Self {
+            root: self.root.clone(),
+            children: self
+                .children
+                .iter()
+                .filter_map(|(name, tree)| {
+                    if !exclude.contains(&tree.root) {
+                        Some((name.clone(), tree.filter(exclude)))
+                    } else {
+                        None
+                    }
+                })
+                .collect(),
+        }
+    }
+}
+
+#[derive(PartialEq, Eq, Hash, Debug, Clone, Serialize, Deserialize)]
+pub struct Dependency {
+    pub name: CompactString,
+    pub version: Version,
+    pub dist: Dist,
+    pub bins: BTreeMap<CompactString, CompactString>,
+    pub scripts: BTreeMap<CompactString, CompactString>,
+}
+
+impl Dependency {
+    pub fn id(&self) -> String {
+        format!("{}@{}", self.name, self.version).replace(MAIN_SEPARATOR, "!")
+    }
+}
diff --git a/package-manager/src/package.rs b/package-manager/src/package.rs
new file mode 100644
index 0000000..e619b1e
--- /dev/null
+++ b/package-manager/src/package.rs
@@ -0,0 +1,191 @@
+use std::{
+    collections::BTreeMap,
+    fmt::{Debug, Display},
+    sync::Arc,
+};
+
+use crate::{
+    npm::PlatformMap,
+    util::{get_node_cpu, get_node_os, VersionSpecifier},
+};
+use color_eyre::eyre::Result;
+use compact_str::{CompactString, ToCompactString};
+use node_semver::Version;
+use rustc_hash::FxHashMap;
+use serde::{
+    de::{self},
+    Deserialize, Serialize,
+};
+use serde_json::Value;
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Debug, Default)]
+#[serde(rename_all = "camelCase")]
+#[serde(default)]
+pub struct PackageMetadata {
+    pub name: CompactString,
+    pub version: Option<Version>,
+    pub bin: Option<Bin>,
+    pub dist: Dist,
+    pub dependencies: BTreeMap<CompactString, VersionSpecifier>,
+    pub optional_dependencies: BTreeMap<CompactString, VersionSpecifier>,
+    pub dev_dependencies: FxHashMap<CompactString, VersionSpecifier>,
+    pub os: PlatformMap,
+    pub cpu: PlatformMap,
+    pub scripts: FxHashMap<CompactString, Value>,
+}
+
+impl PackageMetadata {
+    pub fn info(self) -> PackageInfo {
+        PackageInfo {
+            name: self.name,
+            dist: self.dist,
+            dependencies: self.dependencies,
+            optional_dependencies: self.optional_dependencies,
+            os: self.os,
+            cpu: self.cpu,
+            bin: self.bin,
+            scripts: self
+                .scripts
+                .iter()
+                .filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_compact_string())))
+                .collect(),
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Debug, Default, Hash)]
+#[serde(rename_all = "camelCase")]
+#[serde(default)]
+pub struct PackageInfo {
+    pub name: CompactString,
+    pub dist: Dist,
+    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
+    pub dependencies: BTreeMap<CompactString, VersionSpecifier>,
+    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
+    pub optional_dependencies: BTreeMap<CompactString, VersionSpecifier>,
+    #[serde(skip_serializing_if = "PlatformMap::is_empty")]
+    pub os: PlatformMap,
+    #[serde(skip_serializing_if = "PlatformMap::is_empty")]
+    pub cpu: PlatformMap,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub bin: Option<Bin>,
+    #[serde(skip_serializing_if = "BTreeMap::is_empty")]
+    pub scripts: BTreeMap<CompactString, CompactString>,
+}
+
+#[derive(Debug, Hash, PartialEq, Eq, Clone, Deserialize)]
+pub struct VersionedPackageInfo {
+    pub package: Arc<PackageInfo>,
+    pub version: Version,
+}
+
+impl PackageInfo {
+    pub fn bins(&self) -> BTreeMap<CompactString, CompactString> {
+        match &self.bin {
+            Some(Bin::Multi(x)) => x.clone().into_iter().collect(),
+            Some(Bin::Single(x)) => [(self.name.to_compact_string(), x.to_compact_string())]
+                .into_iter()
+                .collect(),
+            None => [].into_iter().collect(),
+        }
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = PackageSpecifier> + '_ {
+        self.dependencies
+            .iter()
+            .chain(self.optional_dependencies.iter())
+            .map(|(n, v)| PackageSpecifier {
+                name: n.to_compact_string(),
+                version: v.to_owned(),
+                optional: self.optional_dependencies.contains_key(n),
+            })
+    }
+
+    pub fn supported(&self) -> bool {
+        self.os.is_supported(get_node_os()) && self.cpu.is_supported(get_node_cpu())
+    }
+}
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Debug, Hash)]
+#[serde(untagged)]
+pub enum Bin {
+    Single(CompactString),
+    Multi(BTreeMap<CompactString, CompactString>),
+}
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Hash, Debug, Default, PartialOrd, Ord)]
+pub struct Dist {
+    pub tarball: CompactString,
+}
+
+#[derive(PartialEq, Eq, Hash, Clone, PartialOrd, Ord)]
+pub struct PackageSpecifier {
+    pub name: CompactString,
+    pub version: VersionSpecifier,
+    pub optional: bool,
+}
+
+impl Display for PackageSpecifier {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "{}!{}{}",
+            self.name,
+            self.version,
+            if self.optional { "?" } else { "" }
+        )
+    }
+}
+
+impl Serialize for PackageSpecifier {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_str(&self.to_string())
+    }
+}
+
+impl<'de> Deserialize<'de> for PackageSpecifier {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let s = String::deserialize(deserializer)?;
+        let (name, rest) = s
+            .split_once('!')
+            .ok_or_else(|| de::Error::custom("Failed to parse version"))?;
+        let optional = rest.ends_with('?');
+        let version = rest.trim_end_matches('?');
+        Ok(Self {
+            name: name.to_compact_string(),
+            version: serde_json::from_value(Value::String(version.to_string()))
+                .map_err(de::Error::custom)?,
+            optional,
+        })
+    }
+}
+
+impl Debug for PackageSpecifier {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{} {}", self.name, self.version)?;
+        if self.optional {
+            write!(f, " (optional)")?;
+        }
+        Ok(())
+    }
+}
+
+impl PackageMetadata {
+    pub fn iter_all(&self) -> impl Iterator<Item = PackageSpecifier> + '_ {
+        self.dependencies
+            .iter()
+            .chain(self.dev_dependencies.iter())
+            .chain(self.optional_dependencies.iter())
+            .map(|(n, v)| PackageSpecifier {
+                name: n.to_compact_string(),
+                version: v.to_owned(),
+                optional: self.optional_dependencies.contains_key(n),
+            })
+    }
+}
diff --git a/package-manager/src/plan.rs b/package-manager/src/plan.rs
new file mode 100644
index 0000000..72bb4a2
--- /dev/null
+++ b/package-manager/src/plan.rs
@@ -0,0 +1,336 @@
+use async_compression::tokio::bufread::GzipDecoder;
+use color_eyre::{
+    eyre::{eyre, Context, Result},
+    Report, Section,
+};
+use compact_str::{CompactString, ToCompactString};
+use futures::{StreamExt, TryStreamExt};
+use owo_colors::OwoColorize;
+use rustc_hash::FxHashMap;
+use serde::{Deserialize, Serialize};
+use std::fs::{create_dir_all, exists, metadata, read_dir, remove_dir_all, set_permissions, File};
+use std::{
+    fs::Permissions,
+    io::{self, ErrorKind},
+    path::{Path, PathBuf},
+    sync::{Arc, LazyLock},
+};
+use tap::Pipe;
+use tokio::{sync::Semaphore, task::JoinHandle};
+use tokio_tar::Archive;
+use tokio_util::io::StreamReader;
+
+use crate::{
+    cache::Cache,
+    config::{client_auth, read_config},
+    npm::{Dependency, DependencyTree},
+    package::PackageMetadata,
+    progress::{log_progress, log_verbose, log_warning},
+    scoped_path::scoped_join,
+    util::{retry, VersionSpecifier, CLIENT, CLIENT_LIMIT},
+};
+
+#[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)]
+pub struct Plan {
+    #[serde(flatten)]
+    pub trees: FxHashMap<CompactString, DependencyTree>,
+}
+
+impl Plan {
+    pub fn new(trees: FxHashMap<CompactString, DependencyTree>) -> Self {
+        Self { trees }
+    }
+
+    pub fn satisfies(&self, package: &PackageMetadata) -> bool {
+        let map: FxHashMap<_, _> = self
+            .trees
+            .values()
+            .map(|x| (x.root.name.to_compact_string(), x.root.version.clone()))
+            .collect();
+        package.iter_all().all(|req| {
+            if let Some(version) = map.get(&req.name) {
+                if let VersionSpecifier::Range(range) = req.version {
+                    return range.satisfies(version);
+                }
+            }
+            false
+        })
+    }
+}
+
+pub fn tree_size(trees: &FxHashMap<CompactString, DependencyTree>) -> usize {
+    trees.len()
+        + trees
+            .values()
+            .map(|x| tree_size(&x.children))
+            .sum::<usize>()
+}
+
+#[tracing::instrument]
+async fn download_package(dep: &Dependency) -> Result<()> {
+    let target_path = scoped_join(".xmas/store", dep.id())?;
+
+    create_dir_all(&target_path)?;
+
+    if metadata(target_path.join("_complete")).is_ok() {
+        log_verbose(&format!("Skipped downloading {}", dep.id()));
+        return Ok(());
+    }
+
+    static S: LazyLock<Semaphore> = LazyLock::new(|| Semaphore::new(CLIENT_LIMIT));
+    let permit = S.acquire().await.unwrap();
+
+    log_verbose(&format!("Downloading {}@{}", dep.name, dep.version));
+
+    let registry_auth = read_config()
+        .await?
+        .registry
+        .into_iter()
+        .find(|x| dep.dist.tarball.starts_with(&x.url))
+        .and_then(|x| x.auth);
+
+    let mut res = CLIENT
+        .get(&*dep.dist.tarball)
+        .pipe(|x| client_auth(x, registry_auth.as_ref()))?
+        .send()
+        .await?
+        .error_for_status()?
+        .bytes_stream()
+        .map_err(|e| io::Error::new(io::ErrorKind::Other, e));
+
+    let res = {
+        let (tx, rx) = async_channel::unbounded();
+        tokio::spawn(async move {
+            while let Some(buf) = res.next().await {
+                if tx.send(buf).await.is_err() {
+                    break;
+                }
+            }
+            drop(permit);
+        });
+        rx.into_stream()
+    };
+
+    let reader = StreamReader::new(res);
+    let reader = GzipDecoder::new(reader);
+    let reader = Box::pin(reader);
+
+    let mut archive = Archive::new(reader);
+
+    archive
+        .unpack(&target_path)
+        .await
+        .map_err(|e| eyre!("{e:?}"))?;
+
+    File::create(target_path.join("_complete"))?;
+
+    log_progress(&format!("Downloaded {}", dep.id().bright_blue()));
+
+    Ok(())
+}
+
+pub async fn download_package_shared(dep: Dependency) -> Result<()> {
+    static CACHE: LazyLock<Cache<Dependency, Result<(), Arc<Report>>>> = LazyLock::new(|| {
+        Cache::new(|key: Dependency| async move {
+            retry(|| download_package(&key)).await.map_err(Arc::new)
+        })
+    });
+
+    CACHE.get(dep).await.map_err(Report::msg)
+}
+
+fn hardlink_dir(src: PathBuf, dst: PathBuf) -> Result<()> {
+    std::fs::create_dir_all(&dst)?;
+    let dir = std::fs::read_dir(src)?;
+    for entry in dir {
+        let entry = entry?;
+        let ty = entry.file_type()?;
+        if ty.is_dir() {
+            hardlink_dir(entry.path(), dst.join(entry.file_name()))?;
+        } else {
+            std::fs::hard_link(entry.path(), dst.join(entry.file_name()))?;
+        }
+    }
+    Ok(())
+}
+
+fn get_package_src(src: &Path) -> Result<PathBuf> {
+    let mut dir = read_dir(src)?;
+    while let Some(entry) = dir.next().transpose()? {
+        let ty = entry.file_type()?;
+        if ty.is_dir() {
+            return Ok(entry.path());
+        }
+    }
+    Err(Report::msg("No package src found"))
+}
+
+#[tracing::instrument]
+pub async fn install_package(prefix: &[CompactString], dep: &Dependency) -> Result<()> {
+    download_package_shared(dep.clone()).await?;
+
+    let mut target_path = PathBuf::new();
+
+    for segment in prefix {
+        target_path.push(segment.as_str());
+        target_path.push("node_modules");
+    }
+
+    target_path.push(&*dep.name);
+
+    log_verbose(&format!("Installing {}", target_path.to_string_lossy()));
+
+    target_path = scoped_join("node_modules", target_path)?;
+
+    let install_marker = target_path.join(format!(".installed!{}", dep.id()));
+    if exists(&install_marker)? {
+        log_verbose(&format!(
+            "Skipping installation for {}",
+            dep.id().bright_blue()
+        ));
+        return Ok(());
+    }
+
+    let _ = remove_dir_all(&target_path);
+
+    let src_path = scoped_join(".xmas/store", dep.id())?;
+
+    hardlink_dir(get_package_src(&src_path)?, target_path)?;
+
+    File::create(&install_marker)?;
+
+    log_progress(&format!("Installed {}", dep.id().bright_blue()));
+
+    Ok(())
+}
+
+fn warmup_dep_tree(dep: &DependencyTree) {
+    tokio::spawn(download_package_shared(dep.root.clone()));
+    for child in dep.children.values() {
+        warmup_dep_tree(child);
+    }
+}
+
+pub async fn execute_plan(plan: Plan) -> Result<()> {
+    let (send, recv) = async_channel::unbounded();
+
+    fn queue_install(
+        send: async_channel::Sender<JoinHandle<Result<()>>>,
+        tree: DependencyTree,
+        prefix: Vec<CompactString>,
+    ) -> Result<()> {
+        send.clone().send(tokio::spawn(async move {
+            install_package(&prefix, &tree.root).await?;
+
+            for (_, dep) in tree.children {
+                let mut prefix = prefix.clone();
+                prefix.push(tree.root.name.clone());
+                queue_install(send.clone(), dep, prefix)?;
+            }
+
+            Result::Ok(())
+        }));
+
+        Ok(())
+    }
+
+    for (_, tree) in plan.trees.into_iter() {
+        warmup_dep_tree(&tree);
+        queue_install(send.clone(), tree, vec![])?;
+    }
+
+    drop(send);
+
+    while let Ok(x) = recv.recv().await {
+        x.await??;
+    }
+
+    Ok(())
+}
+
+pub(crate) fn symlink(target: &str, path: &str, type_value: Option<String>) -> io::Result<()> {
+    #[cfg(unix)]
+    {
+        _ = type_value;
+        std::os::unix::fs::symlink(target, path)
+    }
+    #[cfg(windows)]
+    {
+        let type_str = match type_value.as_deref() {
+            Some(t @ ("file" | "dir" | "junction")) => t,
+            _ => {
+                if std::fs::metadata(target)
+                    .map(|m| m.is_dir())
+                    .unwrap_or(false)
+                {
+                    "dir"
+                } else {
+                    "file"
+                }
+            }
+        };
+        match type_str {
+            "junction" | "dir" => junction::create(target, path),
+            _ => std::os::windows::fs::symlink_file(target, path),
+        }
+    }
+}
+
+pub async fn setup_bins(plan: &Plan) -> Result<()> {
+    create_dir_all("node_modules/.bin")?;
+
+    for tree in plan.trees.values() {
+        let dep = &tree.root;
+        for (cmd, path) in &dep.bins {
+            let path = path.to_compact_string();
+            let mut script_path = PathBuf::from("../").join(&*dep.name).join(&*path);
+            if !exists(PathBuf::from("node_modules/.bin").join(&script_path))? {
+                script_path.set_extension("js");
+            }
+            if !cmd.contains('/') {
+                #[cfg(windows)]
+                {
+                    // 使用 cmd shim 代替符号链接，避免权限问题
+                    let cmd_path = PathBuf::from("node_modules/.bin").join(format!("{}.cmd", cmd));
+                    let shim_content = format!(
+                        "@ECHO off\r\nGOTO start\r\n:find_dp0\r\nSET dp0=%~dp0\r\nEXIT /b\r\n:start\r\nSETLOCAL\r\nCALL :find_dp0\r\n\r\n\"%dp0%\\{}\" %*\r\n",
+                        script_path.to_str().unwrap().replace('/', "\\")
+                    );
+                    if let Err(e) = std::fs::write(&cmd_path, &shim_content) {
+                        if e.kind() != ErrorKind::AlreadyExists {
+                            return Err(e.into());
+                        }
+                    }
+                    // 同时创建 PowerShell shim
+                    let ps1_path = PathBuf::from("node_modules/.bin").join(format!("{}.ps1", cmd));
+                    let ps1_content = format!(
+                        "#!/usr/bin/env pwsh\r\n$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent\r\n\r\n$exe=\"\"\r\nif ($PSVersionTable.PSVersion -lt \"6.0\" -or $IsWindows) {{\r\n  $exe=\".exe\"\r\n}}\r\n& \"$basedir/{}\" $args\r\nexit $LASTEXITCODE\r\n",
+                        script_path.to_str().unwrap()
+                    );
+                    let _ = std::fs::write(&ps1_path, &ps1_content);
+                }
+                #[cfg(unix)]
+                {
+                    let bin_path = PathBuf::from("node_modules/.bin").join(&**cmd);
+                    if let Err(e) = symlink(
+                        script_path.to_str().unwrap(),
+                        bin_path.to_str().unwrap(),
+                        None,
+                    ) {
+                        if e.kind() != ErrorKind::AlreadyExists {
+                            return Err(e.into());
+                        }
+                    }
+                }
+
+                if read_config().await?.disallow_install_scripts {
+                    log_warning(
+                        &format!("Package {} may require install scripts; consider disabling `disallow_install_scripts`", dep.id())
+                    );
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
diff --git a/package-manager/src/progress.rs b/package-manager/src/progress.rs
new file mode 100644
index 0000000..3948b9f
--- /dev/null
+++ b/package-manager/src/progress.rs
@@ -0,0 +1,43 @@
+use std::{sync::LazyLock, time::Duration};
+
+use indicatif::{ProgressBar, ProgressStyle};
+use owo_colors::OwoColorize;
+
+pub static PROGRESS_BAR: LazyLock<ProgressBar> = LazyLock::new(|| {
+    let pb = ProgressBar::new(0).with_style(
+        ProgressStyle::with_template(
+            "{spinner:.cyan} {wide_msg}\n{bar:40.green/dim} {pos}/{len} packages {elapsed_precise:.dim}"
+        )
+        .unwrap()
+        .progress_chars("━━╾─")
+        .tick_chars("◐◓◑◒"),
+    );
+    pb.enable_steady_tick(Duration::from_millis(80));
+    pb
+});
+
+pub fn set_total(total: u64) {
+    PROGRESS_BAR.set_length(total);
+}
+
+pub fn inc_progress() {
+    PROGRESS_BAR.inc(1);
+}
+
+pub fn log_verbose(text: &str) {
+    // PROGRESS_BAR.suspend(|| println!("{} {}", " VERBOSE ".on_white(), text));
+}
+
+pub fn log_warning(text: &str) {
+    PROGRESS_BAR.suspend(|| println!("{} {}", " WARNING ".on_yellow(), text));
+}
+
+pub fn log_progress(text: &str) {
+    PROGRESS_BAR.set_message(text.to_string());
+    inc_progress();
+    log_verbose(text);
+}
+
+pub fn finish_progress() {
+    PROGRESS_BAR.finish_with_message("✨ Done!".green().to_string());
+}
diff --git a/package-manager/src/resolve.rs b/package-manager/src/resolve.rs
new file mode 100644
index 0000000..1c666e4
--- /dev/null
+++ b/package-manager/src/resolve.rs
@@ -0,0 +1,299 @@
+use crate::npm::{Dependency, DependencyTree};
+use crate::package::{PackageInfo, PackageSpecifier, VersionedPackageInfo};
+use crate::plan::download_package_shared;
+use crate::progress::log_verbose;
+use crate::{npm};
+use color_eyre::eyre::ContextCompat;
+use color_eyre::{Report, Section};
+use compact_str::{CompactString, ToCompactString};
+use dashmap::{DashMap, DashSet};
+use itertools::Itertools;
+use node_semver::Version;
+use owo_colors::OwoColorize;
+use rustc_hash::{FxHashMap, FxHashSet};
+use serde::{Deserialize, Serialize};
+use std::collections::{BTreeMap, VecDeque};
+use std::mem::take;
+use std::sync::Arc;
+use tokio::task::JoinHandle;
+
+#[derive(Deserialize, Debug, Default, Clone)]
+pub struct Graph {
+    #[serde(flatten)]
+    pub relations: FxHashMap<PackageSpecifier, VersionedPackageInfo>,
+}
+
+impl Graph {
+    pub async fn append(
+        &mut self,
+        remaining: impl Iterator<Item = PackageSpecifier>,
+        download: bool,
+    ) -> color_eyre::Result<()> {
+        fn queue_resolve(
+            send: async_channel::Sender<JoinHandle<color_eyre::Result<()>>>,
+            req: PackageSpecifier,
+            relations: Arc<DashMap<PackageSpecifier, VersionedPackageInfo>>,
+            seen: Arc<DashSet<PackageSpecifier>>,
+            download: bool,
+        ) -> color_eyre::Result<()> {
+            if !seen.insert(req.clone()) {
+                return Ok(());
+            }
+
+            if let Some(subpackage) = relations.get(&req) {
+                for child_req in subpackage.package.iter() {
+                    queue_resolve(
+                        send.clone(),
+                        child_req,
+                        relations.clone(),
+                        seen.clone(),
+                        download,
+                    )?;
+                }
+
+                return Ok(());
+            }
+
+            send.clone().send(tokio::spawn(async move {
+                let (version, subpackage) = npm::fetch_versioned_package(req.clone()).await?;
+
+                if download && subpackage.supported() {
+                    tokio::spawn(download_package_shared(Dependency {
+                        name: req.name.to_compact_string(),
+                        version: version.clone(),
+                        dist: subpackage.dist.clone(),
+                        bins: subpackage.bins().into_iter().collect(),
+                        scripts: subpackage.scripts.clone(),
+                    }));
+                }
+
+                relations.insert(
+                    req.clone(),
+                    VersionedPackageInfo {
+                        package: subpackage.clone(),
+                        version,
+                    },
+                );
+
+                for child_req in subpackage.iter() {
+                    queue_resolve(
+                        send.clone(),
+                        child_req,
+                        relations.clone(),
+                        seen.clone(),
+                        download,
+                    )?;
+                }
+
+                Ok(()) as color_eyre::Result<_>
+            }));
+
+            Ok(())
+        }
+
+        let relations: Arc<DashMap<_, _>> =
+            Arc::new(take(&mut self.relations).into_iter().collect());
+
+        let (send, recv) = async_channel::unbounded();
+
+        let seen = Arc::new(DashSet::new());
+
+        for req in remaining {
+            queue_resolve(send.clone(), req, relations.clone(), seen.clone(), download)?;
+        }
+
+        drop(send);
+
+        while let Ok(f) = recv.recv().await {
+            f.await??;
+        }
+
+        self.relations = relations
+            .iter()
+            .filter(|x| seen.contains(x.key()))
+            .map(|x| (x.key().clone(), x.value().clone()))
+            .collect();
+
+        Ok(())
+    }
+
+    pub fn resolve_req(
+        &self,
+        req: &PackageSpecifier,
+    ) -> color_eyre::Result<VersionedPackageInfo, Report> {
+        Ok(self
+            .relations
+            .get(req)
+            .wrap_err("A dependency could not be found")
+            .with_note(|| format!("Attempted to find {req:?}"))
+            .with_suggestion(|| "Make sure that the lockfile is up-to-date. Passing --immutable prevents any changes to the lockfile.")?
+            .clone())
+    }
+
+    fn build_tree(
+        &self,
+        package: &VersionedPackageInfo,
+        stack: &mut Vec<VersionedPackageInfo>,
+        exclude: &FxHashSet<(CompactString, Version)>,
+        optional: bool,
+    ) -> color_eyre::Result<Option<DependencyTree>> {
+        if stack.iter().any(|x| package == x) {
+            log_verbose(&format!(
+                "Detected cyclic dependencies: {} > {} {}",
+                stack
+                    .iter()
+                    .map(
+                        |package| format!("{}@{}", package.package.name, package.version)
+                            .bright_blue()
+                            .to_string()
+                    )
+                    .join(" > "),
+                package.package.name,
+                package.version
+            ));
+
+            return Ok(None);
+        }
+
+        let root = Dependency {
+            name: package.package.name.to_compact_string(),
+            version: package.version.clone(),
+            dist: package.package.dist.clone(),
+            bins: package.package.bins().into_iter().collect(),
+            scripts: package.package.scripts.clone(),
+        };
+
+        if !package.package.supported() {
+            if optional {
+                return Ok(None);
+            } else {
+                return Err(
+                    Report::msg("Required dependency is not supported").note(format!(
+                        "Package {}@{} is not supported on this platform.",
+                        package.package.name, package.version
+                    )),
+                );
+            }
+        }
+
+        let mut deps = vec![];
+        for dep in package.package.iter() {
+            let package2 = self.resolve_req(&dep)?;
+            stack.push(package.clone());
+            if !exclude.contains(&(package2.package.name.clone(), package2.version.clone())) {
+                if let Some(tree) = self.build_tree(&package2, stack, exclude, dep.optional)? {
+                    deps.push(tree);
+                }
+            }
+            stack.pop().unwrap();
+        }
+
+        let tree = DependencyTree {
+            children: deps
+                .into_iter()
+                .map(|x| (x.root.name.to_compact_string(), x))
+                .collect(),
+            root,
+        };
+
+        Ok(Some(tree))
+    }
+
+    pub fn build_trees(
+        &self,
+        root_reqs: &[PackageSpecifier],
+    ) -> color_eyre::Result<Vec<DependencyTree>> {
+        let mut is_optional = FxHashMap::default();
+
+        let mut reqs = FxHashMap::default();
+
+        for req in root_reqs {
+            let pkg = self.resolve_req(req)?;
+            reqs.insert(req.name.clone(), pkg.clone());
+            is_optional.insert(pkg, req.optional);
+        }
+
+        let mut flat_deps = FxHashSet::default();
+        let mut edge = VecDeque::new();
+        edge.extend(reqs.values().cloned());
+
+        while let Some(next) = edge.pop_front() {
+            if !flat_deps.contains(&next) {
+                for req in next.package.iter() {
+                    let pkg = self.resolve_req(&req)?;
+                    is_optional.insert(pkg.clone(), req.optional);
+                    edge.push_back(pkg);
+                }
+                flat_deps.insert(next);
+            }
+        }
+
+        let mut hoisted: FxHashMap<_, VersionedPackageInfo> = FxHashMap::default();
+        for dep in flat_deps {
+            if let Some(prev) = hoisted.get(&dep.package.name) {
+                if dep.version > prev.version {
+                    hoisted.insert(dep.package.name.clone(), dep.clone());
+                }
+            } else {
+                hoisted.insert(dep.package.name.clone(), dep.clone());
+            }
+        }
+
+        for (name, pkg) in &reqs {
+            hoisted.insert(name.clone(), pkg.clone());
+        }
+
+        for (name, pkg) in hoisted.iter() {
+            reqs.insert(name.clone(), pkg.clone());
+        }
+
+        let exclude = hoisted
+            .into_iter()
+            .map(|(name, pkg)| (name, pkg.version))
+            .collect();
+
+        let mut v = vec![];
+        for pkg in reqs.values() {
+            v.push(self.build_tree(pkg, &mut vec![], &exclude, is_optional[pkg])?);
+        }
+
+        let v = v.into_iter().flatten().collect();
+        Ok(v)
+    }
+}
+
+#[derive(Serialize, Deserialize, Default)]
+pub struct Lockfile {
+    #[serde(flatten)]
+    pub relations: BTreeMap<PackageSpecifier, (Version, PackageInfo)>,
+}
+
+impl Lockfile {
+    pub fn new(graph: Graph) -> Self {
+        Self {
+            relations: graph
+                .relations
+                .into_iter()
+                .map(|(req, pkg)| (req, (pkg.version, (*pkg.package).clone())))
+                .collect(),
+        }
+    }
+
+    pub fn into_graph(self) -> Graph {
+        Graph {
+            relations: self
+                .relations
+                .into_iter()
+                .map(|(req, pkg)| {
+                    (
+                        req,
+                        VersionedPackageInfo {
+                            package: Arc::new(pkg.1),
+                            version: pkg.0,
+                        },
+                    )
+                })
+                .collect(),
+        }
+    }
+}
diff --git a/package-manager/src/scoped_path.rs b/package-manager/src/scoped_path.rs
new file mode 100644
index 0000000..8b50553
--- /dev/null
+++ b/package-manager/src/scoped_path.rs
@@ -0,0 +1,101 @@
+// Source retrieved from [safe-path](https://crates.io/crates/safe-path).
+// This single file has been extracted to ensure compatibility with multiple platforms.
+
+use std::io::{Error, ErrorKind, Result};
+use std::path::{Component, Path, PathBuf};
+
+// Follow the same configuration as
+// [secure_join](https://github.com/cyphar/filepath-securejoin/blob/master/join.go#L51)
+const MAX_SYMLINK_DEPTH: u32 = 255;
+
+fn do_scoped_resolve<R: AsRef<Path>, U: AsRef<Path>>(
+    root: R,
+    unsafe_path: U,
+) -> Result<(PathBuf, PathBuf)> {
+    let root = root.as_ref().canonicalize()?;
+
+    let mut nlinks = 0u32;
+    let mut curr_path = unsafe_path.as_ref().to_path_buf();
+    'restart: loop {
+        let mut subpath = PathBuf::new();
+        let mut iter = curr_path.components();
+
+        'next_comp: while let Some(comp) = iter.next() {
+            match comp {
+                // Linux paths don't have prefixes.
+                Component::Prefix(_) => {
+                    return Err(Error::new(
+                        ErrorKind::Other,
+                        format!("Invalid path prefix in: {}", unsafe_path.as_ref().display()),
+                    ));
+                }
+                // `RootDir` should always be the first component, and Path::components() ensures
+                // that.
+                Component::RootDir | Component::CurDir => {
+                    continue 'next_comp;
+                }
+                Component::ParentDir => {
+                    subpath.pop();
+                }
+                Component::Normal(n) => {
+                    let path = root.join(&subpath).join(n);
+                    if let Ok(v) = path.read_link() {
+                        nlinks += 1;
+                        if nlinks > MAX_SYMLINK_DEPTH {
+                            return Err(Error::new(
+                                ErrorKind::Other,
+                                format!(
+                                    "Too many levels of symlinks: {}",
+                                    unsafe_path.as_ref().display()
+                                ),
+                            ));
+                        }
+                        curr_path = if v.is_absolute() {
+                            v.join(iter.as_path())
+                        } else {
+                            subpath.join(v).join(iter.as_path())
+                        };
+                        continue 'restart;
+                    } else {
+                        subpath.push(n);
+                    }
+                }
+            }
+        }
+
+        return Ok((root, subpath));
+    }
+}
+
+/// Safely join `unsafe_path` to `root`, and ensure `unsafe_path` is scoped under `root`.
+///
+/// The `scoped_join()` function assumes `root` exists and is an absolute path. It safely joins the
+/// two given paths and ensures:
+/// - The returned path is guaranteed to be scoped inside `root`.
+/// - Any symbolic links in the path are evaluated with the given `root` treated as the root of the
+///   filesystem, similar to a chroot.
+///
+/// It's modelled after [secure_join](https://github.com/cyphar/filepath-securejoin), but only
+/// for Linux systems.
+///
+/// # Arguments
+/// - `root`: the absolute path to scope the symlink evaluation.
+/// - `unsafe_path`: the path to evaluated and joint with `root`. It is unsafe since it may try to
+///   escape from the `root` by using "../" or symlinks.
+///
+/// # Security
+/// On success return, the `scoped_join()` function guarantees that:
+/// - The resulting PathBuf must be a child path of `root` and will not contain any symlink path
+///   components (they will all get expanded).
+/// - When expanding symlinks, all symlink path components must be resolved relative to the provided
+///   `root`. In particular, this can be considered a userspace implementation of how chroot(2)
+///    operates on file paths.
+/// - Non-existent path components are unaffected.
+///
+/// Note that the guarantees provided by this function only apply if the path components in the
+/// returned string are not modified (in other words are not replaced with symlinks on the
+/// filesystem) after this function has returned. You may use [crate::PinnedPathBuf] to protect
+/// from such TOCTTOU attacks.
+pub fn scoped_join<R: AsRef<Path>, U: AsRef<Path>>(root: R, unsafe_path: U) -> Result<PathBuf> {
+    do_scoped_resolve(root, unsafe_path).map(|(root, path)| root.join(path))
+}
diff --git a/package-manager/src/util.rs b/package-manager/src/util.rs
new file mode 100644
index 0000000..2209764
--- /dev/null
+++ b/package-manager/src/util.rs
@@ -0,0 +1,188 @@
+use color_eyre::eyre::{Context, Result};
+use color_eyre::Report;
+use compact_str::{CompactString, ToCompactString};
+use node_semver::{Range, Version};
+use reqwest::{Client, ClientBuilder, Url};
+use serde::de::DeserializeOwned;
+use serde::{de::Error, Deserialize, Serialize};
+use serde_json::Value;
+use std::future::Future;
+use std::io::ErrorKind;
+use std::path::Path;
+use std::sync::{Arc, LazyLock};
+use std::{
+    env::consts::{ARCH, OS},
+    fmt::Display,
+};
+use tokio::fs::{read_to_string, File};
+use tokio::io::AsyncWriteExt;
+use tracing::instrument;
+
+use crate::package::PackageMetadata;
+use crate::progress::log_warning;
+use crate::resolve::{Graph, Lockfile};
+
+pub const CLIENT_LIMIT: usize = 100;
+
+pub static CLIENT: LazyLock<Client> = LazyLock::new(Client::new);
+pub static CLIENT_Z: LazyLock<Client> = LazyLock::new(|| {
+    ClientBuilder::new()
+        .brotli(true)
+        .gzip(true)
+        .deflate(true)
+        .build()
+        .unwrap()
+});
+
+pub fn decode_json<T: DeserializeOwned>(
+    x: &[u8],
+) -> Result<T, serde_path_to_error::Error<serde_json::Error>> {
+    let jd = &mut serde_json::Deserializer::from_slice(x);
+
+    serde_path_to_error::deserialize(jd)
+}
+
+#[derive(Clone, PartialEq, Eq, Hash, Debug, PartialOrd, Ord)]
+pub struct VersionSpecifierPrefixed {
+    pub prefix: CompactString,
+    pub rest: CompactString,
+}
+
+impl Display for VersionSpecifierPrefixed {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}:{}", self.prefix, self.rest)
+    }
+}
+
+impl Serialize for VersionSpecifierPrefixed {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        self.to_string().serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for VersionSpecifierPrefixed {
+    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let s = String::deserialize(deserializer)?;
+        let (prefix, rest) = s
+            .split_once(':')
+            .ok_or_else(|| D::Error::custom("missing :"))?;
+        if prefix.starts_with("http") {
+            return Err(D::Error::custom("http not allowed"));
+        }
+        Ok(Self {
+            prefix: prefix.to_compact_string(),
+            rest: rest.to_compact_string(),
+        })
+    }
+}
+
+#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, Hash, Debug, PartialOrd, Ord)]
+#[serde(untagged)]
+pub enum VersionSpecifier {
+    Range(Range),
+    Prefixed(VersionSpecifierPrefixed),
+    DirectUrl(Url),
+    Other(CompactString),
+}
+
+impl VersionSpecifier {
+    pub fn satisfies(&self, v: &Version) -> bool {
+        match self {
+            VersionSpecifier::Range(r) => r.satisfies(v),
+            VersionSpecifier::Prefixed(_) => true,
+            VersionSpecifier::DirectUrl(_) => true,
+            VersionSpecifier::Other(_) => false,
+        }
+    }
+}
+
+impl Display for VersionSpecifier {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            VersionSpecifier::Range(a) => a.fmt(f),
+            VersionSpecifier::Prefixed(a) => a.fmt(f),
+            VersionSpecifier::DirectUrl(a) => a.fmt(f),
+            VersionSpecifier::Other(a) => a.fmt(f),
+        }
+    }
+}
+
+pub fn get_node_os() -> &'static str {
+    match OS {
+        "linux" => "linux",
+        "macos" => "darwin",
+        "freebsd" => "freebsd",
+        "openbsd" => "openbsd",
+        "windows" => "win32",
+        _ => unreachable!(),
+    }
+}
+
+pub fn get_node_cpu() -> &'static str {
+    match ARCH {
+        "x86_64" => "x64",
+        x => x,
+    }
+}
+
+const RETRY_LIMIT: usize = 3;
+
+pub async fn retry<T, Fut: Future<Output = Result<T>>>(mut f: impl FnMut() -> Fut) -> Result<T> {
+    let mut last = None;
+    for _ in 0..RETRY_LIMIT {
+        match f().await {
+            Ok(x) => return Ok(x),
+            Err(e) => {
+                log_warning(&format!("Retrying {e}"));
+                last = Some(e);
+            }
+        }
+    }
+    Err(last.unwrap()).wrap_err("Failed all retries")
+}
+
+pub async fn read_package() -> Result<PackageMetadata> {
+    read_json("package.json").await
+}
+
+pub async fn read_package_or_default<T: DeserializeOwned>() -> Result<T> {
+    let s = match read_to_string("package.json").await {
+        Ok(s) => s,
+        Err(e) if e.kind() == ErrorKind::NotFound => "{}".into(),
+        r => r?,
+    };
+    Ok(serde_json::from_str(&s)?)
+}
+
+pub async fn save_package(package: &Value) -> Result<()> {
+    write_json("package.json", package).await
+}
+
+#[instrument]
+pub async fn read_json<T: DeserializeOwned>(path: impl AsRef<Path> + std::fmt::Debug) -> Result<T> {
+    Ok(serde_json::from_str(&read_to_string(path).await?)?)
+}
+
+pub async fn write_json<T: Serialize>(path: impl AsRef<Path>, data: T) -> Result<()> {
+    let mut file = File::create(path).await?;
+
+    file.write_all(serde_json::to_string_pretty(&data)?.as_bytes())
+        .await?;
+
+    file.flush().await?;
+
+    Ok(())
+}
+
+pub async fn load_graph_from_lockfile() -> Graph {
+    let lockfile: Lockfile = read_json("xmas.lock").await.unwrap_or_default();
+    lockfile.into_graph()
+}
+
+pub type ArcResult<T, E = Report> = Result<T, Arc<E>>;
diff --git a/package-manager/src/watch.rs b/package-manager/src/watch.rs
new file mode 100644
index 0000000..ec5a7b6
--- /dev/null
+++ b/package-manager/src/watch.rs
@@ -0,0 +1,35 @@
+use futures::{
+    channel::mpsc::{channel, Receiver},
+    SinkExt, StreamExt,
+};
+use notify::{Config, Event, RecommendedWatcher, RecursiveMode, Watcher};
+use std::path::Path;
+
+fn async_watcher() -> notify::Result<(RecommendedWatcher, Receiver<Event>)> {
+    let (mut tx, rx) = channel(1);
+
+    let watcher = RecommendedWatcher::new(
+        move |res: notify::Result<Event>| {
+            futures::executor::block_on(async {
+                if let Ok(res) = res {
+                    if res.kind.is_access() {
+                        let _ = tx.send(res).await;
+                    }
+                }
+            })
+        },
+        Config::default(),
+    )?;
+
+    Ok((watcher, rx))
+}
+
+pub async fn async_watch(paths: impl IntoIterator<Item = &Path>) -> notify::Result<Event> {
+    let (mut watcher, mut rx) = async_watcher()?;
+
+    for path in paths {
+        watcher.watch(path, RecursiveMode::Recursive)?;
+    }
+
+    Ok(rx.next().await.unwrap())
+}
diff --git a/repl/Cargo.toml b/repl/Cargo.toml
index 2e1692c..c67c403 100644
--- a/repl/Cargo.toml
+++ b/repl/Cargo.toml
@@ -11,6 +11,9 @@ keywords = ["quickjs", "ecmascript", "javascript", "es6", "es2020"]
 [dependencies]
 rsquickjs = { workspace = true, features = ["macro"] }
 xmas-js-modules = { workspace = true }
+xmas-package-manager = { workspace = true }
+clap = { version = "4.5.4", features = ["derive"] }
+deno_task_shell = "0.26.1"
 tracing-subscriber = "0.3.17"
 tracing = "0.1.44"
 rustyline = { version = "17.0.1", features = ["derive"] }
diff --git a/repl/src/lib.rs b/repl/src/lib.rs
index 0c357da..6c76fe0 100644
--- a/repl/src/lib.rs
+++ b/repl/src/lib.rs
@@ -1,3 +1,4 @@
+use clap::Parser;
 use colored::*;
 use core::alloc;
 use rsquickjs::prelude::Rest;
@@ -204,6 +205,8 @@ pub async fn repl() -> anyhow::Result<()> {
                                 println!("❄️\t{} - Show this help message", "/help".cyan().bold());
                                 println!("❄️\t{} - Show version information", "/version".cyan().bold());
                                 println!("❄️\t{} - Clear the console", "/clear".cyan().bold());
+                                println!("❄️\t{} - Package manager commands", "/pm".cyan().bold());
+                                println!("❄️\t{} - Cross platform shell commands", "/$".cyan().bold());
                             },
                             "version" => {
                                 print_version();
@@ -212,8 +215,39 @@ pub async fn repl() -> anyhow::Result<()> {
                                 // Clear the console
                                 println!("\x1B[2J\x1B[1;1H");
                             },
+                            // package manager commands
                             cmd => {
-                                eprintln!("{}: Unknown command '{}'", "Error".red().bold(), cmd);
+                                let args = cmd.split_ascii_whitespace().collect::<Vec<_>>();
+                                if args[0] == "pm" {
+                                    if let Ok(cmd) = xmas_package_manager::cli::Subcommand::try_parse_from(&args) {
+                                        let args = xmas_package_manager::Args {
+                                            verbose: true,
+                                            working_dir: std::env::current_dir().ok(),
+                                            immutable: false,
+                                            cmd
+                                        };
+                                        let _ = xmas_package_manager::execute_command(&args).await;
+                                    } else {
+                                        eprintln!("{}: Invalid package manager command", "Error".red().bold());
+                                    }
+                                }
+                                else if args[0] == "$" {
+                                    let shell_command = args[1..].join(" ");
+                                    let cwd = std::env::current_dir()?;
+                                    let mut new_env = std::collections::HashMap::new();
+                                    new_env.insert(std::ffi::OsString::from("PATH"), xmas_package_manager::commands::new_path().map_err(|e| {
+                                        anyhow::anyhow!("Failed to construct PATH: {}", e)
+                                    })?);
+                                    let exit_code = xmas_package_manager::commands::exec::shell(&shell_command, cwd, new_env, deno_task_shell::KillSignal::default()).await.map_err(|e| {
+                                        anyhow::anyhow!("Failed to execute shell command: {}", e)
+                                    })?;
+                                    if exit_code != 0 {
+                                        eprintln!("{}: Shell command exited with code {}", "Error".red().bold(), exit_code);
+                                    }
+                                }
+                                else {
+                                    eprintln!("{}: Unknown command '{}'", "Error".red().bold(), cmd);
+                                }
                             }
                         }
                         continue;