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, 31 insertions, 14 deletions

diff --git a/lua/mason-core/receipt.lua b/lua/mason-core/receipt.lua
index 63403503..847b8011 100644
--- a/lua/mason-core/receipt.lua
+++ b/lua/mason-core/receipt.lua
@@ -1,15 +1,11 @@
-local Result = require "mason-core.result"
-local fs = require "mason-core.fs"
-local path = require "mason-core.path"
-
 local M = {}
 
 ---@alias InstallReceiptSchemaVersion
 ---| '"1.0"'
 ---| '"1.1"'
----| '"1.2"'
+---| '"2.0"'
 
----@alias InstallReceiptSource {type: RegistryPackageSpecSchema, id: string}
+---@alias InstallReceiptSource {type: RegistryPackageSpecSchema, id: string, raw: RegistryPackageSource}
 
 ---@class InstallReceiptLinks
 ---@field bin? table<string, string>
@@ -22,6 +18,7 @@ local M = {}
 ---@field public metrics {start_time:integer, completion_time:integer}
 ---@field public source InstallReceiptSource
 ---@field public links InstallReceiptLinks
+---@field public install_options PackageInstallOpts
 local InstallReceipt = {}
 InstallReceipt.__index = InstallReceipt
 
@@ -33,6 +30,10 @@ function InstallReceipt.from_json(json)
     return InstallReceipt:new(json)
 end
 
+function InstallReceipt:__tostring()
+    return ("InstallReceipt(name=%s, purl=%s)"):format(self.name, self:get_source().id or "N/A")
+end
+
 function InstallReceipt:get_name()
     return self.name
 end
@@ -49,22 +50,30 @@ end
 
 ---@return InstallReceiptSource
 function InstallReceipt:get_source()
-    if self:is_schema_min "1.2" then
+    if self:is_schema_min "2.0" then
         return self.source
     end
     return self.primary_source --[[@as InstallReceiptSource]]
 end
 
+function InstallReceipt:get_raw_source()
+    if self:is_schema_min "2.0" then
+        return self.source.raw
+    else
+        return nil
+    end
+end
+
+function InstallReceipt:get_install_options()
+    return self.install_options
+end
+
 function InstallReceipt:get_links()
     return self.links
 end
 
----@async
----@param dir string
-function InstallReceipt:write(dir)
-    return Result.pcall(function()
-        fs.async.write_file(path.concat { dir, "mason-receipt.json" }, vim.json.encode(self))
-    end)
+function InstallReceipt:to_json()
+    return vim.json.encode(self)
 end
 
 ---@class InstallReceiptBuilder
@@ -96,6 +105,12 @@ function InstallReceiptBuilder:with_source(source)
     return self
 end
 
+---@param install_options PackageInstallOpts
+function InstallReceiptBuilder:with_install_options(install_options)
+    self.install_options = install_options
+    return self
+end
+
 ---@param typ '"bin"' | '"share"' | '"opt"'
 ---@param name string
 ---@param rel_path string
@@ -132,13 +147,15 @@ function InstallReceiptBuilder:build()
     assert(self.start_time, "start_time is required")
     assert(self.completion_time, "completion_time is required")
     assert(self.source, "source is required")
+    assert(self.install_options, "install_options is required")
     return InstallReceipt:new {
         name = self.name,
-        schema_version = "1.2",
+        schema_version = "2.0",
         metrics = {
             start_time = self.start_time,
             completion_time = self.completion_time,
         },
+        install_options = self.install_options,
         source = self.source,
         links = self.links,
     }