The PureScript Registry stores PureScript packages (and metadata about them) and provides an API for registering, updating, transferring, and unpublishing packages. Most PureScript users will only interact with the registry via package managers.
This repository provides three things:
- Metadata for every package version in the registry, stored in the
metadata
directory - Package sets, which are updated daily and stored in the
package-sets
directory - An API for registering, updating, transferring, and unpublishing packages, as well as for making manual package set updates
The PureScript Registry as a whole consists of this repository plus a few more resources:
- The Registry Index stores the manifest files for every package version in the registry. Package managers use the registry index to rapidly determine relationships among packages at specific versions.
- The Registry Storage stores tarballs of packages that have been uploaded to the registry. Package managers download dependencies from the registry storage.
- The Registry Dev repository is used to develop the registry. The registry-dev repository is also a library, which package managers can use to easily integrate with the registry by reusing its types and functions.
Most PureScript users will only use the Registry API via their package manager. However, it is also possible to interact with it directly via GitHub issues in this repository. The guide below separates Operations (API calls anyone can make) from Authenticated Operations (API calls that can only be made by package owners or registry trustees).
When you submit an issue with the correct payload, this repository's CI will execute the API. Any errors will be reported as a comment on the issue you opened; you can call the API again by commenting on the same issue you opened with another valid payload. If the operation completes successfully then that will be reported to you in a comment and the registry will close the issue.
The Registry API allows anyone to add a package, update a package, or upgrade the package set. To add or update a package, your package must contain a bower.json
file, spago.dhall
file, or purs.json
manifest file. Eventually, the registry will no longer accept packages that do not have a registry manifest file, but for now legacy manifests are still accepted. For an example of the new manifests, see the manifests for the prelude
package.
To register a new package, open an issue with the JSON representation of the Addition type. For example, you can copy the below payload into a new issue on this repository, change the fields to match your library, and submit it.
{
"newPackageLocation": {
"githubOwner": "purescript",
"githubRepo": "purescript-prelude"
},
"newRef": "v1.0.0",
"packageName": "prelude",
"buildPlan": { "compiler": "0.15.4" }
}
The registry will fetch the repository at the provided ref and attempt to register the package, compile it with the compiler version in the buildPlan
field, upload the documentation to Pursuit, and add the package to the day's package set batch.
For the
buildPlan
you must provide a compiler version. You can also optionally provideresolutions
, which is an object in which keys are dependency names and values are specific versions. If you do not provide resolutions then the registry will solve your dependencies for you. If you do, then the registry will compile your package using your provided resolutions.
To publish a new package version, open an issue with the JSON representation of the Update type. The registry will reuse the location stored for the given package in metadata to fetch the package at the provided ref, compile it with the compiler version in the buildPlan
field, upload the documentation to Pursuit, and add the package to the day's package set batch. As with additions, you can optionally provide resolutions
as part of your build plan.
Example payload:
{
"packageName": "prelude",
"updateRef": "v2.0.0",
"buildPlan": { "compiler": "0.15.4" }
}
Package sets are released once per day automatically. However, they sometimes need manual intervention (for example, to update a set of packages all together). The registry provides a batch package set update API for this purpose. You can add new packages or update package versions using the JSON representation of the PackageSetUpdate type. The registry will update the package set to the indicated versions and recompile it. If successful, it will release a new package set with your changes.
Only Registry Trustees are able to remove packages (by setting their value to null
in the payload) or upgrade the compiler version (by setting the compiler
field). If you are not a Trustee, then you should just set the packages
field to the new desired versions for the packages you wish to update.
Example payload:
{
"packages": {
"aff": "7.1.0",
"argonaut": "9.1.0"
}
}
The Registry API allows package owners or Registry Trustees to transfer or unpublish packages. A "package owner" is an Owner listed in the package manifest; if you wish to take an authenticated action for a package then you must first publish a version in which your SSH public key is listed in the owners
field. For example:
// Your public key will list these three fields in the format <keytype> <public> <email>
{
"email": "owner@email.org", // this does not need to be a valid email address, but it must match the key
"keytype": "ssh-ed25519",
"public": "AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSAQEIg9p"
}
If your key is listed in the package owners, then you can transfer or unpublish your package. To do so, create the JSON payload for one of the operations below, and then sign the payload with your SSH key and submit the result in the Authenticated type. Let's walk through a short example of transferring a package.
First, we produce the payload for the operation we wish to take. For a transfer, that might be:
{
"packageName": "my-package",
"newPackageLocation": {
"githubOwner": "new-owner",
"githubRepo": "purescript-my-package"
}
}
Next, place the JSON for your authenticated operation in a file. Then, you can sign the file with your SSH key using this command:
ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n file payload_file
The signature is written to a new file called payload_file.sig, which looks like this:
-----BEGIN SSH SIGNATURE-----
U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAg2rirQQddpzEzOZwbtM0LUMmlLG
krl2EkDq4CVn/Hw7sAAAAEZmlsZQAAAAAAAAAGc2hhNTEyAAAAUwAAAAtzc2gtZWQyNTUx
OQAAAEDyjWPjmOdG8HJ8gh1CbM8WDDWoGfm+TTd8Qa8eua9Bt5Cc+43S24i/JqVWmk98qV
YXoQmOYL4bY8t/q7cSNeMH
-----END SSH SIGNATURE-----
Alternately, if you use -
as the filename, then the payload will be read from stdin and the signature will be written to stdout. Now, we can produce our authenticated operation:
{
"payload":
{
"packageName": "my-package",
"newPackageLocation": {
"githubOwner": "new-owner",
"githubRepo": "purescript-my-package"
}
},
"signature": [
"-----BEGIN SSH SIGNATURE-----",
"U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAg2rirQQddpzEzOZwbtM0LUMmlLG"
"krl2EkDq4CVn/Hw7sAAAAEZmlsZQAAAAAAAAAGc2hhNTEyAAAAUwAAAAtzc2gtZWQyNTUx",
"OQAAAEDyjWPjmOdG8HJ8gh1CbM8WDDWoGfm+TTd8Qa8eua9Bt5Cc+43S24i/JqVWmk98qV",
"YXoQmOYL4bY8t/q7cSNeMH",
"-----END SSH SIGNATURE-----"
],
"email": "owner@email.com"
}
You can now submit this payload to the registry to process the authenticated operation.
To transfer a package, create an authenticated payload for the Transfer type. Provide the package name to transfer and the new location the registry should fetch from.
Example payload:
{
"packageName": "math",
"newPackageLocation": {
"githubOwner": "purescript-deprecated",
"githubRepo": "purescript-math"
}
}
Packages versions can be unpublished for a short time after being published. To unpublish a recently-published package version, create an authenticated payload for the Unpublish type.
Example payload:
{
"packageName": "halogen-hooks",
"unpublishVersion": "2.0.0",
"unpublishReason": "Accidentally committed key."
}