refactor!: change Package API

This changes the following public APIs:

**(_breaking_) Events on the `Package` class**
The `uninstall:success` event on the `Package` class now receives an `InstallReceipt` as argument, instead of an
`InstallHandle`. This receipt is an in-memory representation of what was uninstalled. There's also a new
`uninstall:failed` event for situations where uninstallation for some
reason fails. Note: this also applies to the registry events (i.e.
`package:uninstall:success` and `package:uninstall:failed`).

---

**(_breaking_) `Package:uninstall()` is now asynchronous and receives two new arguments, similarly to `Package:install()`**
While package uninstallations remain synchronous under the hood, the public API has been changed from synchronous ->
asynchronous. Users of this method are recommended to provide a callback in situations where code needs to execute after
uninstallation fully completes.

---

**(_breaking_) `Package:get_install_path()` has been removed.

---

**`Package:install()` now takes an optional callback**
This callback allows consumers to be informed whether installation was successful or not without having to go through a
different, low-level, API. See below for a comparison between the old and new APIs:
```lua
-- before
local handle = pkg:install()
handle:once("closed", function ()
    -- ...
end)

-- after
pkg:install({}, function (success, result)
    -- ...
end)
```

1 files changed, 98 insertions, 0 deletions

diff --git a/lua/mason-core/installer/InstallLocation.lua b/lua/mason-core/installer/InstallLocation.lua
new file mode 100644
index 00000000..00b517b9
--- /dev/null
+++ b/lua/mason-core/installer/InstallLocation.lua
@@ -0,0 +1,98 @@
+local Path = require "mason-core.path"
+local platform = require "mason-core.platform"
+local settings = require "mason.settings"
+
+---@class InstallLocation
+---@field private dir string
+local InstallLocation = {}
+InstallLocation.__index = InstallLocation
+
+---@param dir string
+function InstallLocation:new(dir)
+    ---@type InstallLocation
+    local instance = {}
+    setmetatable(instance, self)
+    instance.dir = dir
+    return instance
+end
+
+function InstallLocation.global()
+    return InstallLocation:new(settings.current.install_root_dir)
+end
+
+function InstallLocation:get_dir()
+    return self.dir
+end
+
+---@async
+function InstallLocation:initialize()
+    local Result = require "mason-core.result"
+    local fs = require "mason-core.fs"
+
+    return Result.try(function(try)
+        for _, p in ipairs {
+            self.dir,
+            self:bin(),
+            self:share(),
+            self:package(),
+            self:staging(),
+        } do
+            if not fs.async.dir_exists(p) then
+                try(Result.pcall(fs.async.mkdirp, p))
+            end
+        end
+    end)
+end
+
+---@param path string?
+function InstallLocation:bin(path)
+    return Path.concat { self.dir, "bin", path }
+end
+
+---@param path string?
+function InstallLocation:share(path)
+    return Path.concat { self.dir, "share", path }
+end
+
+---@param path string?
+function InstallLocation:opt(path)
+    return Path.concat { self.dir, "opt", path }
+end
+
+---@param pkg string?
+function InstallLocation:package(pkg)
+    return Path.concat { self.dir, "packages", pkg }
+end
+
+---@param path string?
+function InstallLocation:staging(path)
+    return Path.concat { self.dir, "staging", path }
+end
+
+---@param name string
+function InstallLocation:lockfile(name)
+    return self:staging(("%s.lock"):format(name))
+end
+
+---@param path string
+function InstallLocation:registry(path)
+    return Path.concat { self.dir, "registries", path }
+end
+
+---@param pkg string
+function InstallLocation:receipt(pkg)
+    return Path.concat { self:package(pkg), "mason-receipt.json" }
+end
+
+---@param opts { PATH: '"append"' | '"prepend"' | '"skip"' }
+function InstallLocation:set_env(opts)
+    vim.env.MASON = self.dir
+
+    if opts.PATH == "prepend" then
+        vim.env.PATH = self:bin() .. platform.path_sep .. vim.env.PATH
+    elseif opts.PATH == "append" then
+        vim.env.PATH = vim.env.PATH .. platform.path_sep .. self:bin()
+    end
+end
+
+return InstallLocation