pi/core/

package_manager.rs

//! Extension package management: source parsing, install paths, trust gating,
//! npm/git/local install/remove/update, and atomic `packages[]` settings edits.
//!
//! Ports the install/remove/update/list side of
//! `.references/pi/packages/coding-agent/src/core/package-manager.ts`. The
//! resolve-side resource collection lives in
//! [`crate::core::resources::discovery`]; [`PackageManager::resolve`]
//! delegates to [`PackagePathResolver`] so the two surfaces never disagree on
//! managed install paths. Source parsing reuses [`parse_package_source`] for
//! the same reason.
//!
//! # Design
//!
//! - [`Runner`] is a narrow, synchronous command-execution seam. [`SystemRunner`]
//!   spawns real subprocesses with a detached process group, a per-call timeout,
//!   and process-tree kill + reap on timeout. Tests inject a [`Runner`]
//!   implementation to assert exact argv and to simulate offline/timeout
//!   failures without touching the network.
//! - All network package operations apply [`NETWORK_TIMEOUT_MS`] (10 s) and are
//!   skipped entirely when `PI_OFFLINE` is enabled.
//! - Settings edits read the per-scope `packages[]`, compute the next array
//!   (idempotent normalize / dedupe, project-wins), and persist through
//!   [`SettingsManager`], whose locked overlay preserves every unknown field.

use std::fs;
use std::io::Read;
use std::path::{Component, Path, PathBuf};
use std::process::{Command, Stdio};
use std::sync::Mutex;
use std::time::Duration;

use semver::{Version, VersionReq};
use serde_json::Value;
use thiserror::Error;

use crate::core::config::{CONFIG_DIR_NAME, PathInputOptions, resolve_path, resolve_path_with};
use crate::core::resources::discovery::{
    PackagePathResolver, PackageResolveError, ParsedSource, ResolvedPaths, parse_package_source,
    temporary_dir_hash,
};
use crate::core::settings::{
    PackageSource, PackageSourceFilter, SettingsManager, SettingsManagerError,
};

/// Network package operation timeout in milliseconds (`NETWORK_TIMEOUT_MS`).
pub const NETWORK_TIMEOUT_MS: u64 = 10_000;

/// Canonical content written to a managed install root `.gitignore`.
const GITIGNORE_CONTENT: &str = "*\n!.gitignore\n";
/// Managed npm project `package.json` body.
const NPM_PROJECT_PACKAGE_JSON: &str = "{\n  \"name\": \"pi-extensions\",\n  \"private\": true\n}";

/// TypeScript `parseSource`: delegate to the shared resolver parser so install
/// paths and identities match [`PackagePathResolver`] exactly.
///
/// This is a free function (not an associated function on [`PackageManager`])
/// so callers do not have to fix the `Runner` type parameter.
#[must_use]
pub fn parse_source(source: &str) -> ParsedSource {
    parse_package_source(source)
}

/// Errors raised by [`PackageManager`].
#[derive(Debug, Error)]
pub enum PackageManagerError {
    /// Project-scoped storage was requested while the project is untrusted.
    #[error("Project is not trusted; refusing to access project package storage")]
    ProjectNotTrusted,
    /// A local install source path does not exist on disk.
    #[error("Path does not exist: {0}")]
    PathNotFound(String),
    /// A computed managed path escaped its install root.
    #[error("Refusing to use path outside package install root: {0}")]
    PathEscape(String),
    /// Git install root was missing for a non-temporary scope.
    #[error("Missing git install root")]
    MissingGitInstallRoot,
    /// Configured `npmCommand` had an empty first entry.
    #[error("Invalid npmCommand: first array entry must be a non-empty command")]
    InvalidNpmCommand,
    /// Install source kind is not supported.
    #[error("Unsupported install source: {0}")]
    UnsupportedInstallSource(String),
    /// Remove source kind is not supported.
    #[error("Unsupported remove source: {0}")]
    UnsupportedRemoveSource(String),
    /// No configured package matched an `update` filter.
    #[error("No matching package found for {0}")]
    NoMatchingPackage(String),
    /// No configured package matched an `update` filter, with a suggestion.
    #[error("No matching package found for {0}. Did you mean {1}?")]
    NoMatchingPackageWithSuggestion(String, String),
    /// A subprocess failed, timed out, or could not be spawned.
    #[error("{0}")]
    Runner(String),
    /// The underlying settings manager rejected a project write.
    #[error(transparent)]
    Settings(SettingsManagerError),
    /// A resolve-side path error propagated from [`PackagePathResolver`].
    #[error(transparent)]
    Resolve(#[from] PackageResolveError),
}

impl From<SettingsManagerError> for PackageManagerError {
    fn from(error: SettingsManagerError) -> Self {
        match error {
            SettingsManagerError::ProjectNotTrusted => Self::ProjectNotTrusted,
            error @ SettingsManagerError::InvalidSetting { .. } => Self::Settings(error),
        }
    }
}

/// Callback invoked for each package operation progress event.
pub type ProgressCallback = Box<dyn Fn(&ProgressEvent) + Send + Sync>;

/// Installed package scope: global agent directory or project `.pi`.
///
/// The temporary/CLI scope is internal to resolve-side discovery and never
/// appears in the install/remove/update API.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
pub enum Scope {
    /// Global agent directory (`~/.pi/agent` or `PI_CODING_AGENT_DIR`).
    User,
    /// Project-local (`{cwd}/.pi`), trust-gated.
    Project,
}

impl Scope {
    /// Wire discriminant.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::User => "user",
            Self::Project => "project",
        }
    }
}

/// Caller decision when a configured package is missing on disk.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum MissingSourceAction {
    /// Install the missing package.
    Install,
    /// Leave it missing and skip.
    Skip,
    /// Fail resolution with an error.
    Error,
}

/// One progress notification emitted during a package operation.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ProgressEvent {
    /// Event phase.
    pub kind: ProgressKind,
    /// Operation category.
    pub action: ProgressAction,
    /// Source string the operation targets.
    pub source: String,
    /// Human-readable detail (start message or error text).
    pub message: Option<String>,
}

/// Progress event phase (`type` in TypeScript).
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ProgressKind {
    /// Operation started.
    Start,
    /// Operation completed.
    Complete,
    /// Operation failed.
    Error,
}

/// Operation category (`action` in TypeScript).
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ProgressAction {
    /// `install`.
    Install,
    /// `remove`.
    Remove,
    /// `update`.
    Update,
    /// `pull` (temporary git refresh).
    Pull,
}

/// One configured package row returned by [`PackageManager::list_configured_packages`].
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ConfiguredPackage {
    /// Package source string (`npm:…`, git URL, or local path).
    pub source: String,
    /// Scope the package is configured in.
    pub scope: Scope,
    /// Whether the entry used the object/filter form.
    pub filtered: bool,
    /// Absolute install path when present on disk, else `None`.
    pub installed_path: Option<PathBuf>,
}

/// Command execution request handed to a [`Runner`].
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct RunRequest {
    /// Executable name or path.
    pub command: String,
    /// Argument vector (already includes any configured `npmCommand` prefix).
    pub args: Vec<String>,
    /// Working directory; `None` inherits the process cwd.
    pub cwd: Option<PathBuf>,
    /// Per-call timeout in milliseconds; `None` waits forever.
    pub timeout_ms: Option<u64>,
    /// Extra environment overrides merged on top of the process environment.
    pub env: Vec<(String, String)>,
}

impl RunRequest {
    /// Build a request with no timeout and no extra env.
    #[must_use]
    pub fn new(command: impl Into<String>, args: Vec<String>) -> Self {
        Self {
            command: command.into(),
            args,
            cwd: None,
            timeout_ms: None,
            env: Vec::new(),
        }
    }

    /// Set the working directory.
    #[must_use]
    pub fn cwd(mut self, cwd: impl Into<PathBuf>) -> Self {
        self.cwd = Some(cwd.into());
        self
    }

    /// Set the per-call timeout.
    #[must_use]
    pub fn timeout_ms(mut self, timeout_ms: u64) -> Self {
        self.timeout_ms = Some(timeout_ms);
        self
    }

    /// Add one environment override.
    #[must_use]
    pub fn env(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
        self.env.push((key.into(), value.into()));
        self
    }

    /// The TypeScript command label used in error messages
    /// (`{command} {args joined by space}`).
    #[must_use]
    pub fn label(&self) -> String {
        let mut label = self.command.clone();
        for arg in &self.args {
            label.push(' ');
            label.push_str(arg);
        }
        label
    }
}

/// Errors raised by a [`Runner`].
#[derive(Debug, Error)]
pub enum RunError {
    /// Process exited nonzero, failed to spawn, or was signaled.
    #[error("{0}")]
    Failed(String),
    /// Process did not exit before the requested timeout.
    #[error("{0}")]
    TimedOut(String),
}

/// Narrow, synchronous command-execution seam.
///
/// [`SystemRunner`] is the production implementation. Tests inject a fake to
/// assert exact argv and to simulate offline / timeout behavior without real
/// subprocesses. Both methods receive the in-flight [`RunRequest`] and apply
/// the same timeout / kill / reap semantics.
pub trait Runner: Send + Sync {
    /// Run with inherited stdout/stderr; error on nonzero exit.
    ///
    /// # Errors
    ///
    /// Returns [`RunError::Failed`] on a nonzero exit or spawn failure, and
    /// [`RunError::TimedOut`] when `req.timeout_ms` elapses first.
    fn run(&self, req: &RunRequest) -> Result<(), RunError>;

    /// Run capturing trimmed stdout; error on nonzero exit.
    ///
    /// # Errors
    ///
    /// Returns [`RunError::Failed`] (message includes `stderr || stdout`) on a
    /// nonzero exit or spawn failure, and [`RunError::TimedOut`] on timeout.
    fn capture(&self, req: &RunRequest) -> Result<String, RunError>;
}

/// Production [`Runner`] over real subprocesses.
///
/// Spawns each command in its own process group (Unix) or with
/// `CREATE_NO_WINDOW` (Windows), applies the requested timeout, and on timeout
/// kills the whole process tree then reaps it. stdout/stderr are inherited for
/// [`Runner::run`] and piped for [`Runner::capture`].
#[derive(Clone, Copy, Debug, Default)]
pub struct SystemRunner;

impl Runner for SystemRunner {
    fn run(&self, req: &RunRequest) -> Result<(), RunError> {
        let mut cmd = build_command(req);
        cmd.stdin(Stdio::null());
        cmd.stdout(Stdio::inherit());
        cmd.stderr(Stdio::inherit());
        configure_platform(&mut cmd);
        let mut child = cmd
            .spawn()
            .map_err(|e| RunError::Failed(format!("{}: {e}", req.label())))?;
        wait_with_timeout(&mut child, req)
    }

    fn capture(&self, req: &RunRequest) -> Result<String, RunError> {
        let mut cmd = build_command(req);
        cmd.stdin(Stdio::null());
        cmd.stdout(Stdio::piped());
        cmd.stderr(Stdio::piped());
        configure_platform(&mut cmd);
        let mut child = cmd
            .spawn()
            .map_err(|e| RunError::Failed(format!("{}: {e}", req.label())))?;
        let stdout = child.stdout.take();
        let stderr = child.stderr.take();
        let stdout_thread = std::thread::spawn(move || read_pipe(stdout));
        let stderr_thread = std::thread::spawn(move || read_pipe(stderr));

        match wait_with_timeout(&mut child, req) {
            Ok(()) => {
                let stdout_out = stdout_thread.join().unwrap_or_default();
                Ok(stdout_out.trim().to_owned())
            }
            Err(RunError::Failed(_)) => {
                let stdout_out = stdout_thread.join().unwrap_or_default();
                let stderr_out = stderr_thread.join().unwrap_or_default();
                let detail = if stderr_out.is_empty() {
                    stdout_out
                } else {
                    stderr_out
                };
                Err(RunError::Failed(format!(
                    "{} failed with: {detail}",
                    req.label()
                )))
            }
            Err(other) => Err(other),
        }
    }
}

/// Build a [`Command`] from a request, inheriting the process environment and
/// applying the requested overrides.
fn build_command(req: &RunRequest) -> Command {
    let mut cmd = Command::new(&req.command);
    cmd.args(&req.args);
    if let Some(cwd) = &req.cwd {
        cmd.current_dir(cwd);
    }
    for (key, value) in &req.env {
        cmd.env(key, value);
    }
    cmd
}

/// Apply platform-specific spawn flags (process group on Unix,
/// `CREATE_NO_WINDOW` on Windows).
fn configure_platform(cmd: &mut Command) {
    #[cfg(unix)]
    {
        use std::os::unix::process::CommandExt as _;
        cmd.process_group(0);
    }
    #[cfg(windows)]
    {
        use std::os::windows::process::CommandExt as _;
        const CREATE_NO_WINDOW: u32 = 0x0800_0000;
        cmd.creation_flags(CREATE_NO_WINDOW);
    }
}

/// Wait for `child` with the request timeout, killing the tree on timeout.
fn wait_with_timeout(child: &mut std::process::Child, req: &RunRequest) -> Result<(), RunError> {
    use wait_timeout::ChildExt as _;
    let Some(timeout_ms) = req.timeout_ms else {
        let status = child
            .wait()
            .map_err(|e| RunError::Failed(format!("{}: {e}", req.label())))?;
        return exit_status_result(&req.label(), status);
    };
    let duration = Duration::from_millis(timeout_ms);
    match child.wait_timeout(duration) {
        Ok(Some(status)) => exit_status_result(&req.label(), status),
        Ok(None) => {
            kill_process_tree(child.id());
            let _ = child.wait();
            Err(RunError::TimedOut(format!(
                "{} timed out after {timeout_ms}ms",
                req.label()
            )))
        }
        Err(error) => Err(RunError::Failed(format!("{}: {error}", req.label()))),
    }
}

/// Map a finished exit status into a [`RunError`] when nonzero.
fn exit_status_result(label: &str, status: std::process::ExitStatus) -> Result<(), RunError> {
    if status.success() {
        Ok(())
    } else {
        let exit_status = match status.code() {
            Some(code) => format!("code {code}"),
            None => "signal".to_owned(),
        };
        Err(RunError::Failed(format!(
            "{label} failed with {exit_status}"
        )))
    }
}

/// Read an optional pipe to a string (best-effort).
fn read_pipe<R: Read>(mut pipe: Option<R>) -> String {
    let Some(inner) = pipe.as_mut() else {
        return String::new();
    };
    let mut buf = String::new();
    let _ = inner.read_to_string(&mut buf);
    buf
}

/// Kill a process and its descendants (process group on Unix, `taskkill /T` on Windows).
fn kill_process_tree(pid: u32) {
    #[cfg(unix)]
    {
        use nix::sys::signal::{Signal, kill, killpg};
        use nix::unistd::Pid;
        if let Ok(raw) = i32::try_from(pid) {
            let group = Pid::from_raw(raw);
            if killpg(group, Signal::SIGKILL).is_err() {
                let _ = kill(group, Signal::SIGKILL);
            }
        }
    }
    #[cfg(not(unix))]
    {
        let _ = Command::new("taskkill")
            .args(["/F", "/T", "/PID", &pid.to_string()])
            .stdin(Stdio::null())
            .stdout(Stdio::null())
            .stderr(Stdio::null())
            .spawn();
    }
}

/// Options for constructing a [`PackageManager`].
#[derive(Clone, Debug)]
pub struct PackageManagerOptions {
    /// Project working directory.
    pub cwd: PathBuf,
    /// Agent config directory (`~/.pi/agent` or `PI_CODING_AGENT_DIR`).
    pub agent_dir: PathBuf,
    /// Optional home directory seam (defaults to the process home).
    pub home_dir: Option<PathBuf>,
}

impl PackageManagerOptions {
    /// Create options from cwd and agent dir.
    #[must_use]
    pub fn new(cwd: impl Into<PathBuf>, agent_dir: impl Into<PathBuf>) -> Self {
        Self {
            cwd: cwd.into(),
            agent_dir: agent_dir.into(),
            home_dir: None,
        }
    }

    /// Override the home directory seam.
    #[must_use]
    pub fn home_dir(mut self, home_dir: impl Into<PathBuf>) -> Self {
        self.home_dir = Some(home_dir.into());
        self
    }
}

/// Extension package manager: install, remove, update, list, resolve.
///
/// Generic over a [`Runner`] so tests can inject command execution. Production
/// code uses [`PackageManager`] (which defaults to [`SystemRunner`]).
pub struct PackageManager<R: Runner = SystemRunner> {
    cwd: PathBuf,
    agent_dir: PathBuf,
    home_dir: Option<PathBuf>,
    runner: R,
    progress: Option<ProgressCallback>,
    /// `Some(force)` overrides `PI_OFFLINE`; `None` reads the env each call.
    offline: Option<bool>,
    /// Cached global npm root (`npm root -g` / `bun pm bin -g`), keyed by npmCommand argv.
    global_npm_root: Mutex<Option<(String, String)>>,
}

impl PackageManager<SystemRunner> {
    /// Create a manager backed by the real subprocess runner.
    #[must_use]
    pub fn new(options: PackageManagerOptions) -> Self {
        Self::with_runner(options, SystemRunner)
    }
}

impl<R: Runner> PackageManager<R> {
    /// Create a manager with an injected runner.
    #[must_use]
    pub fn with_runner(options: PackageManagerOptions, runner: R) -> Self {
        let cwd = resolve_path_with(
            &options.cwd.to_string_lossy(),
            Path::new("."),
            path_options(options.home_dir.as_deref()).trim(true),
        );
        let agent_dir = resolve_path_with(
            &options.agent_dir.to_string_lossy(),
            Path::new("."),
            path_options(options.home_dir.as_deref()).trim(true),
        );
        Self {
            cwd,
            agent_dir,
            home_dir: options.home_dir,
            runner,
            progress: None,
            offline: None,
            global_npm_root: Mutex::new(None),
        }
    }

    /// Force offline mode (`Some(true)`) or online (`Some(false)`), overriding
    /// `PI_OFFLINE`. `None` (the default) reads the env on each call.
    #[must_use]
    pub fn with_offline(mut self, offline: bool) -> Self {
        self.offline = Some(offline);
        self
    }

    /// Install a progress callback (replaces any previous one).
    pub fn set_progress_callback(&mut self, callback: Option<ProgressCallback>) {
        self.progress = callback;
    }

    /// Whether package network operations are skipped.
    fn is_offline(&self) -> bool {
        self.offline.unwrap_or_else(pi_offline_enabled)
    }

    /// Absolute install path for `source` in `scope`, or `None` when absent.
    ///
    /// # Errors
    ///
    /// Returns [`PackageManagerError::ProjectNotTrusted`] for project scope
    /// while untrusted, or [`PackageManagerError::Resolve`] on path escape.
    pub fn get_installed_path(
        &self,
        settings: &SettingsManager,
        source: &str,
        scope: Scope,
    ) -> Result<Option<PathBuf>, PackageManagerError> {
        let parsed = parse_source(source);
        match parsed {
            ParsedSource::Npm { name, .. } => {
                let path = self.npm_install_path(&name, scope, settings)?;
                Ok(path.exists().then_some(path))
            }
            ParsedSource::Git { host, path, .. } => {
                let path = self.git_install_path(&host, &path, scope)?;
                Ok(path.exists().then_some(path))
            }
            ParsedSource::Local { path } => {
                let base = self.base_dir_for_scope(scope);
                let resolved = self.resolve_path_from_base(&path, &base);
                Ok(resolved.exists().then_some(resolved))
            }
        }
    }

    /// Install `source` into `scope` without recording it in settings.
    ///
    /// Local sources only verify the path exists; npm and git run the package
    /// manager / git clone under [`NETWORK_TIMEOUT_MS`].
    ///
    /// # Errors
    ///
    /// Returns [`PackageManagerError::ProjectNotTrusted`] for untrusted project
    /// scope, [`PackageManagerError::PathNotFound`] for a missing local path,
    /// or [`PackageManagerError::Runner`] on subprocess failure.
    pub fn install(
        &self,
        settings: &SettingsManager,
        source: &str,
        scope: Scope,
    ) -> Result<(), PackageManagerError> {
        let parsed = parse_source(source);
        Self::assert_project_trusted(scope, settings)?;
        let settings_ref = settings;
        self.with_progress(
            ProgressAction::Install,
            source,
            format!("Installing {source}..."),
            || match &parsed {
                ParsedSource::Npm { spec, .. } => {
                    self.install_npm(settings_ref, spec, scope, false)
                }
                ParsedSource::Git { .. } => self.install_git(settings_ref, &parsed, scope),
                ParsedSource::Local { path } => {
                    let resolved = self.resolve_path(path);
                    if resolved.exists() {
                        Ok(())
                    } else {
                        Err(PackageManagerError::PathNotFound(path_string(&resolved)))
                    }
                }
            },
        )
    }

    /// Install then persist the source into the scope's `packages[]`.
    ///
    /// # Errors
    ///
    /// See [`Self::install`] and [`Self::add_source_to_settings`].
    pub fn install_and_persist(
        &self,
        settings: &mut SettingsManager,
        source: &str,
        scope: Scope,
    ) -> Result<(), PackageManagerError> {
        self.install(settings, source, scope)?;
        self.add_source_to_settings(settings, source, scope)?;
        Ok(())
    }

    /// Remove `source` from `scope` (disk only; settings untouched).
    ///
    /// Local sources are a no-op; npm uninstalls and git removes the clone.
    ///
    /// # Errors
    ///
    /// Returns [`PackageManagerError::ProjectNotTrusted`] for untrusted project
    /// scope or [`PackageManagerError::Runner`] on subprocess failure.
    pub fn remove(
        &self,
        settings: &SettingsManager,
        source: &str,
        scope: Scope,
    ) -> Result<(), PackageManagerError> {
        let parsed = parse_source(source);
        Self::assert_project_trusted(scope, settings)?;
        let settings_ref = settings;
        self.with_progress(
            ProgressAction::Remove,
            source,
            format!("Removing {source}..."),
            || match &parsed {
                ParsedSource::Npm { .. } => self.uninstall_npm(settings_ref, &parsed, scope),
                ParsedSource::Git { .. } => self.remove_git(&parsed, scope),
                ParsedSource::Local { .. } => Ok(()),
            },
        )
    }

    /// Remove from disk then drop the source from `packages[]`.
    ///
    /// Returns whether the settings array actually changed.
    ///
    /// # Errors
    ///
    /// See [`Self::remove`] and [`Self::remove_source_from_settings`].
    pub fn remove_and_persist(
        &self,
        settings: &mut SettingsManager,
        source: &str,
        scope: Scope,
    ) -> Result<bool, PackageManagerError> {
        self.remove(settings, source, scope)?;
        self.remove_source_from_settings(settings, source, scope)
    }

    /// Update one package (`Some`) or every configured package (`None`).
    ///
    /// Pinned npm versions are skipped (they are fixed). Pinned git refs are
    /// reconciled against the configured ref. Offline mode or an empty match
    /// set is a no-op. A filter that matches nothing is an error.
    ///
    /// # Errors
    ///
    /// Returns [`PackageManagerError::NoMatchingPackage`] (with a suggestion
    /// when one exists) for an unmatched filter, or [`PackageManagerError`]
    /// variants from the underlying install/clone operations.
    pub fn update_extensions(
        &self,
        settings: &SettingsManager,
        source: Option<&str>,
    ) -> Result<(), PackageManagerError> {
        if self.is_offline() {
            return Ok(());
        }
        let global = settings.get_global_settings();
        let project = settings.get_project_settings();
        let identity = source.map(|s| self.package_identity(s, None));
        let mut matched = false;
        let mut targets: Vec<(String, Scope)> = Vec::new();
        for pkg in global.packages.clone().unwrap_or_default() {
            let src = package_source_string(&pkg);
            if identity
                .as_ref()
                .is_some_and(|id| self.package_identity(&src, Some(Scope::User)) != *id)
            {
                continue;
            }
            matched = true;
            targets.push((src, Scope::User));
        }
        for pkg in project.packages.clone().unwrap_or_default() {
            let src = package_source_string(&pkg);
            if identity
                .as_ref()
                .is_some_and(|id| self.package_identity(&src, Some(Scope::Project)) != *id)
            {
                continue;
            }
            matched = true;
            targets.push((src, Scope::Project));
        }
        if source.is_some() && !matched {
            let configured: Vec<PackageSource> = global
                .packages
                .clone()
                .unwrap_or_default()
                .into_iter()
                .chain(project.packages.clone().unwrap_or_default())
                .collect();
            return Err(no_matching_package_error(source.unwrap_or(""), &configured));
        }
        self.update_configured_targets(settings, &targets)?;
        Ok(())
    }

    /// List every configured package across both scopes with its install path.
    ///
    /// # Errors
    ///
    /// Returns [`PackageManagerError`] only when an install-path lookup hits a
    /// trust or path-escape failure.
    pub fn list_configured_packages(
        &self,
        settings: &SettingsManager,
    ) -> Result<Vec<ConfiguredPackage>, PackageManagerError> {
        let global = settings.get_global_settings();
        let project = settings.get_project_settings();
        let mut out = Vec::new();
        for pkg in global.packages.clone().unwrap_or_default() {
            let source = package_source_string(&pkg);
            let filtered = matches!(pkg, PackageSource::Filtered(_));
            let installed_path = self.get_installed_path(settings, &source, Scope::User)?;
            out.push(ConfiguredPackage {
                source,
                scope: Scope::User,
                filtered,
                installed_path,
            });
        }
        for pkg in project.packages.clone().unwrap_or_default() {
            let source = package_source_string(&pkg);
            let filtered = matches!(pkg, PackageSource::Filtered(_));
            let installed_path = self.get_installed_path(settings, &source, Scope::Project)?;
            out.push(ConfiguredPackage {
                source,
                scope: Scope::Project,
                filtered,
                installed_path,
            });
        }
        Ok(out)
    }

    /// Resolve all configured packages and local resources to concrete paths.
    ///
    /// Delegates to [`PackagePathResolver::resolve`] so this surface and the
    /// resolve-side discovery never disagree on managed install locations.
    /// Missing installs are skipped (no network install here).
    ///
    /// # Errors
    ///
    /// Propagates [`PackageResolveError`] as [`PackageManagerError::Resolve`].
    pub fn resolve(
        &self,
        settings: &SettingsManager,
    ) -> Result<ResolvedPaths, PackageManagerError> {
        let resolver = PackagePathResolver::new(&self.cwd, &self.agent_dir, settings);
        Ok(resolver.resolve()?)
    }

    /// Add (or normalize) `source` in `scope`'s `packages[]`.
    ///
    /// Returns whether the settings array changed. Adding the same source is
    /// idempotent (returns `false`); a re-normalized local path returns `true`.
    ///
    /// # Errors
    ///
    /// Returns [`PackageManagerError::ProjectNotTrusted`] (via the settings
    /// setter) for untrusted project scope.
    pub fn add_source_to_settings(
        &self,
        settings: &mut SettingsManager,
        source: &str,
        scope: Scope,
    ) -> Result<bool, PackageManagerError> {
        let current = Self::scope_packages(settings, scope);
        let normalized = self.normalize_source_for_settings(source, scope);
        if let Some(index) = self.find_match(&current, source, scope) {
            let existing = &current[index];
            if package_source_string(existing) == normalized {
                return Ok(false);
            }
            let mut next = current.clone();
            next[index] = replace_source(existing, normalized);
            Self::set_scope_packages(settings, scope, &next)?;
            return Ok(true);
        }
        let mut next = current;
        next.push(PackageSource::Source(normalized));
        Self::set_scope_packages(settings, scope, &next)?;
        Ok(true)
    }

    /// Remove `source` from `scope`'s `packages[]`.
    ///
    /// Returns whether the array changed.
    ///
    /// # Errors
    ///
    /// Returns [`PackageManagerError::ProjectNotTrusted`] for untrusted project
    /// scope.
    pub fn remove_source_from_settings(
        &self,
        settings: &mut SettingsManager,
        source: &str,
        scope: Scope,
    ) -> Result<bool, PackageManagerError> {
        let current = Self::scope_packages(settings, scope);
        let mut next = Vec::new();
        for pkg in &current {
            if !self.sources_match(pkg, source, scope) {
                next.push(pkg.clone());
            }
        }
        if next.len() == current.len() {
            return Ok(false);
        }
        Self::set_scope_packages(settings, scope, &next)?;
        Ok(true)
    }

    // -- internal: progress ---------------------------------------------------

    fn with_progress<F>(
        &self,
        action: ProgressAction,
        source: &str,
        message: String,
        op: F,
    ) -> Result<(), PackageManagerError>
    where
        F: FnOnce() -> Result<(), PackageManagerError>,
    {
        self.emit(&ProgressEvent {
            kind: ProgressKind::Start,
            action,
            source: source.to_owned(),
            message: Some(message),
        });
        match op() {
            Ok(()) => {
                self.emit(&ProgressEvent {
                    kind: ProgressKind::Complete,
                    action,
                    source: source.to_owned(),
                    message: None,
                });
                Ok(())
            }
            Err(error) => {
                self.emit(&ProgressEvent {
                    kind: ProgressKind::Error,
                    action,
                    source: source.to_owned(),
                    message: Some(error.to_string()),
                });
                Err(error)
            }
        }
    }

    fn emit(&self, event: &ProgressEvent) {
        if let Some(callback) = &self.progress {
            callback(event);
        }
    }

    // -- internal: trust / settings ----------------------------------------

    fn assert_project_trusted(
        scope: Scope,
        settings: &SettingsManager,
    ) -> Result<(), PackageManagerError> {
        if scope == Scope::Project && !settings.is_project_trusted() {
            return Err(PackageManagerError::ProjectNotTrusted);
        }
        Ok(())
    }

    fn scope_packages(settings: &SettingsManager, scope: Scope) -> Vec<PackageSource> {
        match scope {
            Scope::Project => settings
                .get_project_settings()
                .packages
                .clone()
                .unwrap_or_default(),
            Scope::User => settings
                .get_global_settings()
                .packages
                .clone()
                .unwrap_or_default(),
        }
    }

    fn set_scope_packages(
        settings: &mut SettingsManager,
        scope: Scope,
        packages: &[PackageSource],
    ) -> Result<(), PackageManagerError> {
        match scope {
            Scope::Project => settings.set_project_packages(packages)?,
            Scope::User => settings.set_packages(packages),
        }
        Ok(())
    }

    fn find_match(&self, packages: &[PackageSource], input: &str, scope: Scope) -> Option<usize> {
        let right = self.source_match_key_for_input(input);
        for (index, pkg) in packages.iter().enumerate() {
            let left = self.source_match_key_for_settings(&package_source_string(pkg), scope);
            if left == right {
                return Some(index);
            }
        }
        None
    }

    fn sources_match(&self, existing: &PackageSource, input: &str, scope: Scope) -> bool {
        self.find_match(std::slice::from_ref(existing), input, scope)
            .is_some()
    }

    /// `getPackageIdentity`: identity ignores version/ref. Local identity is
    /// scope-base-relative when a scope is given.
    fn package_identity(&self, source: &str, scope: Option<Scope>) -> String {
        match parse_source(source) {
            ParsedSource::Npm { name, .. } => format!("npm:{name}"),
            ParsedSource::Git { host, path, .. } => format!("git:{host}/{path}"),
            ParsedSource::Local { path } => match scope {
                Some(scope) => {
                    let base = self.base_dir_for_scope(scope);
                    format!(
                        "local:{}",
                        path_string(&self.resolve_path_from_base(&path, &base))
                    )
                }
                None => format!("local:{}", path_string(&self.resolve_path(&path))),
            },
        }
    }

    fn source_match_key_for_input(&self, source: &str) -> String {
        match parse_source(source) {
            ParsedSource::Npm { name, .. } => format!("npm:{name}"),
            ParsedSource::Git { host, path, .. } => format!("git:{host}/{path}"),
            ParsedSource::Local { path } => {
                format!("local:{}", path_string(&self.resolve_path(&path)))
            }
        }
    }

    fn source_match_key_for_settings(&self, source: &str, scope: Scope) -> String {
        match parse_source(source) {
            ParsedSource::Npm { name, .. } => format!("npm:{name}"),
            ParsedSource::Git { host, path, .. } => format!("git:{host}/{path}"),
            ParsedSource::Local { path } => {
                let base = self.base_dir_for_scope(scope);
                format!(
                    "local:{}",
                    path_string(&self.resolve_path_from_base(&path, &base))
                )
            }
        }
    }

    fn normalize_source_for_settings(&self, source: &str, scope: Scope) -> String {
        match parse_source(source) {
            ParsedSource::Local { path } => {
                let base = self.base_dir_for_scope(scope);
                let resolved = self.resolve_path(&path);
                let rel = relative_path(&base, &resolved);
                rel.to_string_lossy().into_owned()
            }
            _ => source.to_owned(),
        }
    }

    // -- internal: npm ------------------------------------------------------

    fn npm_command(
        settings: &SettingsManager,
    ) -> Result<(String, Vec<String>), PackageManagerError> {
        let configured = settings.get_npm_command().unwrap_or_default();
        if configured.is_empty() {
            return Ok(("npm".to_owned(), Vec::new()));
        }
        let mut iter = configured.into_iter();
        let command = iter.next().ok_or(PackageManagerError::InvalidNpmCommand)?;
        if command.is_empty() {
            return Err(PackageManagerError::InvalidNpmCommand);
        }
        Ok((command, iter.collect()))
    }

    fn package_manager_name(command: &str, args: &[String]) -> String {
        let mut parts = vec![command.to_owned()];
        parts.extend(args.iter().cloned());
        let pm = match parts.iter().rposition(|p| p == "--") {
            Some(idx) => parts.get(idx + 1).cloned().unwrap_or_default(),
            None => command.to_owned(),
        };
        basename_no_exe(&pm)
    }

    /// `getNpmInstallArgs` dialect (no configured-arg prefix).
    fn npm_install_dialect(manager: &str, specs: &[String], install_root: &Path) -> Vec<String> {
        match manager {
            "bun" => {
                let mut out = vec!["install".to_owned()];
                out.extend(specs.iter().cloned());
                out.push("--cwd".to_owned());
                out.push(path_string(install_root));
                out.push("--omit=peer".to_owned());
                out
            }
            "pnpm" => {
                let mut out = vec!["install".to_owned()];
                out.extend(specs.iter().cloned());
                out.push("--prefix".to_owned());
                out.push(path_string(install_root));
                out.push("--config.auto-install-peers=false".to_owned());
                out.push("--config.strict-peer-dependencies=false".to_owned());
                out.push("--config.strict-dep-builds=false".to_owned());
                out
            }
            _ => {
                let mut out = vec!["install".to_owned()];
                out.extend(specs.iter().cloned());
                out.push("--prefix".to_owned());
                out.push(path_string(install_root));
                out.push("--legacy-peer-deps".to_owned());
                out
            }
        }
    }

    /// `uninstallNpm` dialect (no configured-arg prefix).
    fn npm_uninstall_dialect(manager: &str, name: &str, install_root: &Path) -> Vec<String> {
        match manager {
            "bun" => vec![
                "uninstall".to_owned(),
                name.to_owned(),
                "--cwd".to_owned(),
                path_string(install_root),
            ],
            "pnpm" => vec![
                "uninstall".to_owned(),
                name.to_owned(),
                "--prefix".to_owned(),
                path_string(install_root),
            ],
            _ => vec![
                "uninstall".to_owned(),
                name.to_owned(),
                "--prefix".to_owned(),
                path_string(install_root),
                "--legacy-peer-deps".to_owned(),
            ],
        }
    }

    /// `getGitDependencyInstallArgs` dialect.
    fn git_dependency_dialect(settings: &SettingsManager) -> Vec<String> {
        if settings.get_npm_command().is_some_and(|c| !c.is_empty()) {
            vec!["install".to_owned()]
        } else {
            vec!["install".to_owned(), "--omit=dev".to_owned()]
        }
    }

    /// Run `command prefix… dialect…` (TS `runNpmCommand`).
    fn run_npm(
        &self,
        settings: &SettingsManager,
        dialect: Vec<String>,
        cwd: Option<&Path>,
    ) -> Result<(), PackageManagerError> {
        let (command, prefix) = Self::npm_command(settings)?;
        let mut full = prefix;
        full.extend(dialect);
        let mut req = RunRequest::new(command, full).timeout_ms(NETWORK_TIMEOUT_MS);
        if let Some(cwd) = cwd {
            req = req.cwd(cwd);
        }
        self.runner.run(&req).map_err(|error| runner_error(&error))
    }

    fn install_npm(
        &self,
        settings: &SettingsManager,
        spec: &str,
        scope: Scope,
        temporary: bool,
    ) -> Result<(), PackageManagerError> {
        let install_root = self.npm_install_root(scope, temporary)?;
        Self::ensure_npm_project(&install_root)?;
        let (command, prefix) = Self::npm_command(settings)?;
        let manager = Self::package_manager_name(&command, &prefix);
        let spec_owned = spec.to_owned();
        let dialect =
            Self::npm_install_dialect(&manager, std::slice::from_ref(&spec_owned), &install_root);
        let mut full = prefix;
        full.extend(dialect);
        self.runner
            .run(&RunRequest::new(command, full).timeout_ms(NETWORK_TIMEOUT_MS))
            .map_err(|error| runner_error(&error))
    }

    fn uninstall_npm(
        &self,
        settings: &SettingsManager,
        parsed: &ParsedSource,
        scope: Scope,
    ) -> Result<(), PackageManagerError> {
        let ParsedSource::Npm { name, .. } = parsed else {
            return Ok(());
        };
        let install_root = self.npm_install_root(scope, false)?;
        if !install_root.exists() {
            return Ok(());
        }
        let (command, prefix) = Self::npm_command(settings)?;
        let manager = Self::package_manager_name(&command, &prefix);
        let dialect = Self::npm_uninstall_dialect(&manager, name, &install_root);
        let mut full = prefix;
        full.extend(dialect);
        self.runner
            .run(&RunRequest::new(command, full).timeout_ms(NETWORK_TIMEOUT_MS))
            .map_err(|error| runner_error(&error))
    }

    // -- internal: git ------------------------------------------------------

    fn install_git(
        &self,
        settings: &SettingsManager,
        parsed: &ParsedSource,
        scope: Scope,
    ) -> Result<(), PackageManagerError> {
        let ParsedSource::Git { repo, ref_name, .. } = parsed else {
            return Ok(());
        };
        let target = self.git_install_path_from_parsed(parsed, scope)?;
        if target.exists() {
            // Existing clone: reconcile to the configured ref/upstream. Deps are
            // reinstalled inside `ensure_git_ref` only when a reset happens.
            if let Some(reference) = ref_name {
                self.ensure_git_ref(
                    settings,
                    &target,
                    &["fetch".to_owned(), "origin".to_owned(), reference.clone()],
                    "FETCH_HEAD",
                )?;
            } else {
                let update_target = self.local_git_update_target(&target);
                self.ensure_git_ref(
                    settings,
                    &target,
                    &update_target.fetch_args,
                    &update_target.reference,
                )?;
            }
            return Ok(());
        }
        let root = self.git_install_root(scope);
        Self::ensure_git_ignore(&root)?;
        if let Some(parent) = target.parent() {
            fs::create_dir_all(parent).map_err(|error| io_escape(&error))?;
        }
        self.runner
            .run(
                &RunRequest::new(
                    "git",
                    vec!["clone".to_owned(), repo.clone(), path_string(&target)],
                )
                .timeout_ms(NETWORK_TIMEOUT_MS),
            )
            .map_err(|error| runner_error(&error))?;
        // Fresh clone checks out the configured ref directly (TS `git checkout`).
        if let Some(reference) = ref_name {
            self.runner
                .run(
                    &RunRequest::new("git", vec!["checkout".to_owned(), reference.clone()])
                        .cwd(&target)
                        .timeout_ms(NETWORK_TIMEOUT_MS),
                )
                .map_err(|error| runner_error(&error))?;
        }
        if target.join("package.json").exists() {
            self.run_npm(
                settings,
                Self::git_dependency_dialect(settings),
                Some(&target),
            )?;
        }
        Ok(())
    }

    fn update_git(
        &self,
        settings: &SettingsManager,
        parsed: &ParsedSource,
        scope: Scope,
    ) -> Result<(), PackageManagerError> {
        let target = self.git_install_path_from_parsed(parsed, scope)?;
        if !target.exists() {
            return self.install_git(settings, parsed, scope);
        }
        let ParsedSource::Git { ref_name, .. } = parsed else {
            return Ok(());
        };
        // Deps reinstall happens inside `ensure_git_ref` when a reset occurs.
        if let Some(reference) = ref_name {
            self.ensure_git_ref(
                settings,
                &target,
                &["fetch".to_owned(), "origin".to_owned(), reference.clone()],
                "FETCH_HEAD",
            )?;
        } else {
            let update_target = self.local_git_update_target(&target);
            self.ensure_git_ref(
                settings,
                &target,
                &update_target.fetch_args,
                &update_target.reference,
            )?;
        }
        Ok(())
    }

    /// `ensureGitRef`: fetch the target ref, and when HEAD differs reset
    /// `--hard`, run `git clean -fdx`, and reinstall npm deps so a reconciled
    /// extension is pristine (no stale untracked files or `node_modules`).
    fn ensure_git_ref(
        &self,
        settings: &SettingsManager,
        target: &Path,
        fetch_args: &[String],
        reference: &str,
    ) -> Result<(), PackageManagerError> {
        self.runner
            .run(
                &RunRequest::new("git", fetch_args.to_vec())
                    .cwd(target)
                    .timeout_ms(NETWORK_TIMEOUT_MS),
            )
            .map_err(|error| runner_error(&error))?;
        let local_head = self
            .runner
            .capture(
                &RunRequest::new("git", vec!["rev-parse".to_owned(), "HEAD".to_owned()])
                    .cwd(target)
                    .timeout_ms(NETWORK_TIMEOUT_MS),
            )
            .map_err(|error| runner_error(&error))?
            .trim()
            .to_owned();
        let commit_ref = format!("{reference}^{{commit}}");
        let target_head = self
            .runner
            .capture(
                &RunRequest::new("git", vec!["rev-parse".to_owned(), commit_ref.clone()])
                    .cwd(target)
                    .timeout_ms(NETWORK_TIMEOUT_MS),
            )
            .map_err(|error| runner_error(&error))?
            .trim()
            .to_owned();
        if local_head == target_head {
            return Ok(());
        }
        self.runner
            .run(
                &RunRequest::new(
                    "git",
                    vec!["reset".to_owned(), "--hard".to_owned(), commit_ref],
                )
                .cwd(target)
                .timeout_ms(NETWORK_TIMEOUT_MS),
            )
            .map_err(|error| runner_error(&error))?;
        // Clean untracked files (extensions should be pristine after a reset).
        self.runner
            .run(
                &RunRequest::new("git", vec!["clean".to_owned(), "-fdx".to_owned()])
                    .cwd(target)
                    .timeout_ms(NETWORK_TIMEOUT_MS),
            )
            .map_err(|error| runner_error(&error))?;
        if target.join("package.json").exists() {
            self.run_npm(
                settings,
                Self::git_dependency_dialect(settings),
                Some(target),
            )?;
        }
        Ok(())
    }

    fn remove_git(&self, parsed: &ParsedSource, scope: Scope) -> Result<(), PackageManagerError> {
        let target = self.git_install_path_from_parsed(parsed, scope)?;
        if !target.exists() {
            return Ok(());
        }
        remove_all(&target)?;
        let root = self.git_install_root(scope);
        Self::prune_empty_git_parents(&target, &root);
        Ok(())
    }

    /// Detect the local upstream tracking target (`getLocalGitUpdateTarget`).
    fn local_git_update_target(&self, target: &Path) -> GitUpdateTarget {
        let upstream = self.runner.capture(
            &RunRequest::new(
                "git",
                vec![
                    "rev-parse".to_owned(),
                    "--abbrev-ref".to_owned(),
                    "@{upstream}".to_owned(),
                ],
            )
            .cwd(target)
            .timeout_ms(NETWORK_TIMEOUT_MS),
        );
        if let Ok(upstream) = upstream {
            let trimmed = upstream.trim();
            if let Some(branch) = trimmed.strip_prefix("origin/")
                && !branch.is_empty()
            {
                return GitUpdateTarget {
                    reference: "@{upstream}".to_owned(),
                    fetch_args: git_fetch_args(branch),
                };
            }
        }
        let _ = self.runner.run(
            &RunRequest::new(
                "git",
                vec![
                    "remote".to_owned(),
                    "set-head".to_owned(),
                    "origin".to_owned(),
                    "-a".to_owned(),
                ],
            )
            .cwd(target)
            .timeout_ms(NETWORK_TIMEOUT_MS),
        );
        let head_ref = self
            .runner
            .capture(
                &RunRequest::new(
                    "git",
                    vec![
                        "symbolic-ref".to_owned(),
                        "refs/remotes/origin/HEAD".to_owned(),
                    ],
                )
                .cwd(target)
                .timeout_ms(NETWORK_TIMEOUT_MS),
            )
            .unwrap_or_default()
            .trim()
            .trim_start_matches("refs/remotes/origin/")
            .to_owned();
        if head_ref.is_empty() {
            // TS final fallback: fetch HEAD directly into refs/remotes/origin/HEAD.
            return GitUpdateTarget {
                reference: "origin/HEAD".to_owned(),
                fetch_args: git_head_fallback_fetch_args(),
            };
        }
        GitUpdateTarget {
            reference: "origin/HEAD".to_owned(),
            fetch_args: git_fetch_args(&head_ref),
        }
    }

    // -- internal: update batching -----------------------------------------

    fn update_configured_targets(
        &self,
        settings: &SettingsManager,
        targets: &[(String, Scope)],
    ) -> Result<(), PackageManagerError> {
        if targets.is_empty() {
            return Ok(());
        }
        // Sequential update checks (correctness over TS's bounded concurrency;
        // the observable result — every matching package updated — is identical).
        for (source, scope) in targets {
            let parsed = parse_source(source);
            match &parsed {
                ParsedSource::Npm {
                    spec,
                    name,
                    version,
                    ..
                } => {
                    if is_exact_npm_version(version.as_deref()) {
                        continue;
                    }
                    if !self.should_update_npm(settings, name, spec, version.as_deref(), *scope)? {
                        continue;
                    }
                    // TS `updateNpmBatch`: unpinned packages install `name@latest`.
                    let update_spec = spec_if_version(spec, name, version.as_deref());
                    let scope = *scope;
                    self.with_progress(
                        ProgressAction::Update,
                        source,
                        format!("Updating {source}..."),
                        || self.install_npm(settings, &update_spec, scope, false),
                    )?;
                }
                ParsedSource::Git { .. } => {
                    let scope = *scope;
                    let parsed = parsed.clone();
                    self.with_progress(
                        ProgressAction::Update,
                        source,
                        format!("Updating {source}..."),
                        || self.update_git(settings, &parsed, scope),
                    )?;
                }
                ParsedSource::Local { .. } => {}
            }
        }
        Ok(())
    }

    fn should_update_npm(
        &self,
        settings: &SettingsManager,
        name: &str,
        spec: &str,
        version: Option<&str>,
        scope: Scope,
    ) -> Result<bool, PackageManagerError> {
        let installed_path = self.managed_npm_install_path(name, scope)?;
        let Some(installed_version) = read_installed_version(&installed_path) else {
            return Ok(true);
        };
        // TS `getLatestNpmVersion`: `source.version ? source.spec : source.name`.
        let view_spec = if version.is_some() {
            spec.to_owned()
        } else {
            name.to_owned()
        };
        let target = self.latest_npm_version(settings, view_spec, version)?;
        Ok(target.as_deref() != Some(installed_version.as_str()))
    }

    fn latest_npm_version(
        &self,
        settings: &SettingsManager,
        package_spec: String,
        range: Option<&str>,
    ) -> Result<Option<String>, PackageManagerError> {
        let (command, prefix) = Self::npm_command(settings)?;
        let mut args = prefix;
        args.push("view".to_owned());
        args.push(package_spec);
        args.push("version".to_owned());
        args.push("--json".to_owned());
        let req = RunRequest::new(command, args)
            .cwd(&self.cwd)
            .timeout_ms(NETWORK_TIMEOUT_MS);
        let Ok(raw) = self.runner.capture(&req) else {
            return Ok(None);
        };
        let trimmed = raw.trim();
        if trimmed.is_empty() {
            return Ok(None);
        }
        Ok(parse_npm_view_version(trimmed, range))
    }

    // -- internal: paths ----------------------------------------------------

    fn base_dir_for_scope(&self, scope: Scope) -> PathBuf {
        match scope {
            Scope::Project => self.cwd.join(CONFIG_DIR_NAME),
            Scope::User => self.agent_dir.clone(),
        }
    }

    fn npm_install_root(
        &self,
        scope: Scope,
        temporary: bool,
    ) -> Result<PathBuf, PackageManagerError> {
        if temporary {
            return self.temporary_dir("npm", None);
        }
        match scope {
            Scope::Project => Ok(self.cwd.join(CONFIG_DIR_NAME).join("npm")),
            Scope::User => Ok(self.agent_dir.join("npm")),
        }
    }

    fn git_install_root(&self, scope: Scope) -> PathBuf {
        match scope {
            Scope::Project => self.cwd.join(CONFIG_DIR_NAME).join("git"),
            Scope::User => self.agent_dir.join("git"),
        }
    }

    fn managed_npm_install_path(
        &self,
        name: &str,
        scope: Scope,
    ) -> Result<PathBuf, PackageManagerError> {
        Ok(self
            .npm_install_root(scope, false)?
            .join("node_modules")
            .join(name))
    }

    fn git_install_path(
        &self,
        host: &str,
        path: &str,
        scope: Scope,
    ) -> Result<PathBuf, PackageManagerError> {
        let root = self.git_install_root(scope);
        resolve_managed_path(&root, &[host, path])
    }

    fn git_install_path_from_parsed(
        &self,
        parsed: &ParsedSource,
        scope: Scope,
    ) -> Result<PathBuf, PackageManagerError> {
        let ParsedSource::Git { host, path, .. } = parsed else {
            return Err(PackageManagerError::UnsupportedInstallSource(
                "non-git".to_owned(),
            ));
        };
        self.git_install_path(host, path, scope)
    }

    fn npm_install_path(
        &self,
        name: &str,
        scope: Scope,
        settings: &SettingsManager,
    ) -> Result<PathBuf, PackageManagerError> {
        let managed = self.managed_npm_install_path(name, scope)?;
        if scope != Scope::User || managed.exists() {
            return Ok(managed);
        }
        if let Some(legacy) = self.legacy_global_npm_install_path(name, settings)?
            && legacy.exists()
        {
            return Ok(legacy);
        }
        Ok(managed)
    }

    fn legacy_global_npm_install_path(
        &self,
        name: &str,
        settings: &SettingsManager,
    ) -> Result<Option<PathBuf>, PackageManagerError> {
        if let Some(path) = self.pnpm_global_package_path(name, settings)? {
            return Ok(Some(path));
        }
        let root = self.global_npm_root(settings)?;
        if root.is_empty() {
            return Ok(None);
        }
        Ok(Some(Path::new(&root).join(name)))
    }

    fn pnpm_global_package_path(
        &self,
        name: &str,
        settings: &SettingsManager,
    ) -> Result<Option<PathBuf>, PackageManagerError> {
        let (command, args) = Self::npm_command(settings)?;
        if Self::package_manager_name(&command, &args) != "pnpm" {
            return Ok(None);
        }
        let mut full = args;
        full.extend([
            "list".to_owned(),
            "-g".to_owned(),
            "--depth".to_owned(),
            "0".to_owned(),
            "--json".to_owned(),
        ]);
        let Ok(output) = self
            .runner
            .capture(&RunRequest::new(command, full).timeout_ms(NETWORK_TIMEOUT_MS))
        else {
            return Ok(None);
        };
        Ok(parse_pnpm_global_path(&output, name))
    }

    fn global_npm_root(&self, settings: &SettingsManager) -> Result<String, PackageManagerError> {
        let (command, args) = Self::npm_command(settings)?;
        let key = command_key(&command, &args);
        if let Some(entry) = self
            .global_npm_root
            .lock()
            .ok()
            .and_then(|guard| guard.clone())
            && entry.0 == key
        {
            return Ok(entry.1);
        }
        let manager = Self::package_manager_name(&command, &args);
        let root = if manager == "bun" {
            let mut a = args.clone();
            a.extend(["pm".to_owned(), "bin".to_owned(), "-g".to_owned()]);
            let bin_dir = self
                .runner
                .capture(&RunRequest::new(command.clone(), a).timeout_ms(NETWORK_TIMEOUT_MS))
                .unwrap_or_default();
            let parent = Path::new(bin_dir.trim())
                .parent()
                .map_or_else(|| bin_dir.trim().to_owned(), path_string);
            format!(
                "{}/install/global/node_modules",
                parent.trim_end_matches('/')
            )
        } else {
            let mut a = args.clone();
            a.extend(["root".to_owned(), "-g".to_owned()]);
            self.runner
                .capture(&RunRequest::new(command.clone(), a).timeout_ms(NETWORK_TIMEOUT_MS))
                .unwrap_or_default()
                .trim()
                .to_owned()
        };
        if let Ok(mut guard) = self.global_npm_root.lock() {
            *guard = Some((key, root.clone()));
        }
        Ok(root)
    }

    fn temporary_dir(
        &self,
        prefix: &str,
        suffix: Option<&str>,
    ) -> Result<PathBuf, PackageManagerError> {
        let root = resolve_managed_path(&extension_temp_folder(&self.agent_dir), &[prefix])?;
        let suffix_str = suffix.unwrap_or("");
        let hash = temporary_dir_hash(prefix, suffix_str);
        if suffix_str.is_empty() {
            resolve_managed_path(&root, &[&hash])
        } else {
            resolve_managed_path(&root, &[&hash, suffix_str])
        }
    }

    fn ensure_npm_project(install_root: &Path) -> Result<(), PackageManagerError> {
        if !install_root.exists() {
            fs::create_dir_all(install_root).map_err(|error| io_escape(&error))?;
        }
        Self::ensure_git_ignore(install_root)?;
        let package_json = install_root.join("package.json");
        if !package_json.exists() {
            fs::write(&package_json, NPM_PROJECT_PACKAGE_JSON)
                .map_err(|error| io_escape(&error))?;
        }
        Ok(())
    }

    fn ensure_git_ignore(dir: &Path) -> Result<(), PackageManagerError> {
        if !dir.exists() {
            fs::create_dir_all(dir).map_err(|error| io_escape(&error))?;
        }
        let ignore_path = dir.join(".gitignore");
        if !ignore_path.exists() {
            fs::write(&ignore_path, GITIGNORE_CONTENT).map_err(|error| io_escape(&error))?;
        }
        Ok(())
    }

    fn prune_empty_git_parents(target: &Path, install_root: &Path) {
        let resolved_root = resolve_path(path_string(install_root));
        let mut current = match target.parent() {
            Some(parent) => parent.to_path_buf(),
            None => return,
        };
        while current.starts_with(&resolved_root) && current != resolved_root {
            if !current.exists() {
                current = match current.parent() {
                    Some(parent) => parent.to_path_buf(),
                    None => return,
                };
                continue;
            }
            let is_empty = fs::read_dir(&current).is_ok_and(|mut it| it.next().is_none());
            if !is_empty {
                break;
            }
            let _ = fs::remove_dir_all(&current);
            current = match current.parent() {
                Some(parent) => parent.to_path_buf(),
                None => return,
            };
        }
    }

    // -- internal: path resolution seams -----------------------------------

    fn resolve_path(&self, input: &str) -> PathBuf {
        resolve_path_with(
            input,
            &self.cwd,
            path_options(self.home_dir.as_deref()).trim(true),
        )
    }

    fn resolve_path_from_base(&self, input: &str, base: &Path) -> PathBuf {
        resolve_path_with(
            input,
            base,
            path_options(self.home_dir.as_deref()).trim(true),
        )
    }
}

// ===========================================================================
// Free helpers
// ===========================================================================

/// Extension temp folder (`{agentDir}/tmp/extensions`).
fn extension_temp_folder(agent_dir: &Path) -> PathBuf {
    agent_dir.join("tmp").join("extensions")
}

/// Resolve `root/parts…` refusing any component that escapes the root.
fn resolve_managed_path(root: &Path, parts: &[&str]) -> Result<PathBuf, PackageManagerError> {
    let resolved_root = resolve_path(path_string(root));
    let mut resolved = resolved_root.clone();
    for part in parts {
        for component in Path::new(part).components() {
            match component {
                Component::Normal(seg) => resolved.push(seg),
                Component::CurDir => {}
                Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
                    return Err(PackageManagerError::PathEscape(path_string(&resolved)));
                }
            }
        }
    }
    if resolved != resolved_root && !resolved.starts_with(&resolved_root) {
        return Err(PackageManagerError::PathEscape(path_string(&resolved)));
    }
    Ok(resolved)
}

/// `relative(base, resolved)`, defaulting to `.` when equal (TS `rel || "."`).
fn relative_path(base: &Path, resolved: &Path) -> PathBuf {
    match resolved.strip_prefix(base) {
        Ok(rel) if rel.as_os_str().is_empty() => PathBuf::from("."),
        Ok(rel) => rel.to_path_buf(),
        Err(_) => resolved.to_path_buf(),
    }
}

fn path_string(path: &Path) -> String {
    path.to_string_lossy().into_owned()
}

fn path_options(home_dir: Option<&Path>) -> PathInputOptions<'_> {
    PathInputOptions::new().home_dir(home_dir)
}

fn basename_no_exe(name: &str) -> String {
    let stem = Path::new(name)
        .file_stem()
        .map_or_else(|| name.to_owned(), |s| s.to_string_lossy().into_owned());
    stem.trim_end_matches(".cmd")
        .trim_end_matches(".exe")
        .to_owned()
}

fn command_key(command: &str, args: &[String]) -> String {
    let mut key = command.to_owned();
    for arg in args {
        key.push('\0');
        key.push_str(arg);
    }
    key
}

fn git_fetch_args(branch: &str) -> Vec<String> {
    vec![
        "fetch".to_owned(),
        "--prune".to_owned(),
        "--no-tags".to_owned(),
        "origin".to_owned(),
        format!("+refs/heads/{branch}:refs/remotes/origin/{branch}"),
    ]
}

/// `getLocalGitUpdateTarget` final fallback: fetch HEAD into the origin/HEAD ref.
fn git_head_fallback_fetch_args() -> Vec<String> {
    vec![
        "fetch".to_owned(),
        "--prune".to_owned(),
        "--no-tags".to_owned(),
        "origin".to_owned(),
        "+HEAD:refs/remotes/origin/HEAD".to_owned(),
    ]
}

/// `git@{upstream}` resolved fetch/reset target.
struct GitUpdateTarget {
    reference: String,
    fetch_args: Vec<String>,
}

fn is_exact_npm_version(version: Option<&str>) -> bool {
    version.is_some_and(|v| Version::parse(v).is_ok())
}

fn spec_if_version(spec: &str, name: &str, version: Option<&str>) -> String {
    if version.is_some() {
        spec.to_owned()
    } else {
        format!("{name}@latest")
    }
}

fn read_installed_version(install_path: &Path) -> Option<String> {
    let package_json = install_path.join("package.json");
    let content = fs::read_to_string(package_json).ok()?;
    let value: Value = serde_json::from_str(&content).ok()?;
    value
        .get("version")
        .and_then(Value::as_str)
        .map(str::to_owned)
}

fn parse_npm_view_version(raw: &str, range: Option<&str>) -> Option<String> {
    let value: Value = serde_json::from_str(raw).ok()?;
    if let Some(s) = value.as_str() {
        return Some(s.to_owned());
    }
    let arr = value.as_array()?;
    let mut versions: Vec<String> = arr
        .iter()
        .filter_map(|v| v.as_str().filter(|s| !s.is_empty()).map(str::to_owned))
        .collect();
    if let Some(range) = range
        && let Ok(req) = VersionReq::parse(range)
    {
        versions.retain(|v| Version::parse(v).is_ok_and(|parsed| req.matches(&parsed)));
    }
    semantic_max(versions)
}

/// Select the highest semver from a list, stringifying the result (TS `rcompare`).
fn semantic_max(versions: Vec<String>) -> Option<String> {
    versions
        .into_iter()
        .filter_map(|v| Version::parse(&v).ok().map(|parsed| (v, parsed)))
        .max_by(|a, b| a.1.cmp(&b.1))
        .map(|(v, _)| v)
}

fn parse_pnpm_global_path(raw: &str, name: &str) -> Option<PathBuf> {
    let value: Value = serde_json::from_str(raw).ok()?;
    let entries = value.as_array()?;
    for entry in entries {
        if let Some(deps) = entry.get("dependencies").and_then(Value::as_object)
            && let Some(path) = deps
                .get(name)
                .and_then(|d| d.get("path"))
                .and_then(Value::as_str)
        {
            return Some(PathBuf::from(path));
        }
    }
    None
}

fn package_source_string(pkg: &PackageSource) -> String {
    match pkg {
        PackageSource::Source(source) => source.clone(),
        PackageSource::Filtered(filter) => filter.source.clone(),
    }
}

fn replace_source(existing: &PackageSource, normalized: String) -> PackageSource {
    match existing {
        PackageSource::Source(_) => PackageSource::Source(normalized),
        PackageSource::Filtered(filter) => PackageSource::Filtered(PackageSourceFilter {
            source: normalized,
            autoload: filter.autoload,
            extensions: filter.extensions.clone(),
            skills: filter.skills.clone(),
            prompts: filter.prompts.clone(),
            themes: filter.themes.clone(),
            extra: filter.extra.clone(),
        }),
    }
}

fn no_matching_package_error(source: &str, configured: &[PackageSource]) -> PackageManagerError {
    match find_suggested_source(source, configured) {
        Some(suggestion) => {
            PackageManagerError::NoMatchingPackageWithSuggestion(source.to_owned(), suggestion)
        }
        None => PackageManagerError::NoMatchingPackage(source.to_owned()),
    }
}

fn find_suggested_source(source: &str, configured: &[PackageSource]) -> Option<String> {
    let trimmed = source.trim();
    for pkg in configured {
        let src = package_source_string(pkg);
        match parse_source(&src) {
            ParsedSource::Npm { name, spec, .. } => {
                if trimmed == name || trimmed == spec {
                    return Some(src);
                }
            }
            ParsedSource::Git {
                host,
                path,
                ref_name,
                ..
            } => {
                let shorthand = format!("{host}/{path}");
                let with_ref = ref_name.as_ref().map(|r| format!("{shorthand}@{r}"));
                if trimmed == shorthand || with_ref.is_some_and(|w| trimmed == w) {
                    return Some(src);
                }
            }
            ParsedSource::Local { .. } => {}
        }
    }
    None
}

fn runner_error(error: &RunError) -> PackageManagerError {
    PackageManagerError::Runner(error.to_string())
}

fn io_escape(error: &std::io::Error) -> PackageManagerError {
    PackageManagerError::Runner(error.to_string())
}

fn remove_all(path: &Path) -> Result<(), PackageManagerError> {
    if path.is_dir() {
        fs::remove_dir_all(path).map_err(|error| io_escape(&error))
    } else if path.exists() {
        fs::remove_file(path).map_err(|error| io_escape(&error))
    } else {
        Ok(())
    }
}

fn pi_offline_enabled() -> bool {
    match std::env::var("PI_OFFLINE") {
        Ok(value) => {
            value == "1" || value.eq_ignore_ascii_case("true") || value.eq_ignore_ascii_case("yes")
        }
        Err(_) => false,
    }
}

#[cfg(test)]
mod tests;