Migrate to spago v1 (#316)

* feat: migrate client to latest spago

Resolves #315

* feat: migrate staging to latest spago, package set

and bring compiler up to date with latest Hackage release (0.15.15)

* doc: __DEVELOPMENT__ flag

* chore: update CHANGELOG

* fix: npm command in CI

* docs: remove irrelevant stuff from RELEASE.md

* fix: avoid exceeding max-heap

* fix: spago fetch in start script

* fix: trim package set by "cannot run in playground", record exclusions

Addresses PR feedback that the trim in 0fd79d9 left no record of what was
removed or why, so the next `spago install $(spago ls packages ...)` per
RELEASE.md would have silently reinstalled the full set.

- Add staging/excluded-packages.txt: 148 packages, one line each with the
  reason. The only criterion is that a package cannot execute in the
  playground: its foreign modules (or a dependency's) import bare JS
  specifiers that the import map in client/public/frame.html does not shim.
  Packages previously cut for size despite being runnable (spec, spec-mocha,
  test-unit, pmock, react-basic-dom-beta, css-frameworks) are back in.
- Filter the RELEASE.md install step through the exclusion list, and document
  the criterion and the un-exclude path (add a shim, delete the line).
- Upgrade the package set 77.6.0 -> 77.10.2; spago.{yaml,lock} regenerated by
  running the documented steps for real: 492 of 640 packages installed. The
  77.10.2 cannot-run closure is identical to 77.6.0's; both packages new to
  the set (harmonia, yoga-format) are clean.
- Verified at production RTS settings (-M3G): cold boot compiles all 3,798
  modules (peak residency 1,165 MB); warm restart peaks at 1,907 MB, ~160 MB
  below the previous trim, leaving ~1.1 GB headroom.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: remove irrelevant note about metadata

* docs: instruction for measuring heap usage

* chore: use same purs version everywhere

* fix: node version in ci

because spago needs node:sqlite (added in v22)

---------

Co-authored-by: Peter Murphy <26548438+ptrfrncsmrph@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: pete-murphy

.github/workflows/ci.yml

@@ -62,7 +62,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
 
       - name: Build client code
         run: |
@@ -71,7 +71,7 @@ jobs:
           npm run build
           npm run test
           npm run build:production
-          npm run bundle
+          npm run bundle:production
 
       - name: Check SharedConfig.purs versions
         run: |
@@ -80,7 +80,7 @@ jobs:
           node updateSharedConfigVersions.mjs sharedConfig.out
           diff src/Try/SharedConfig.purs sharedConfig.out || {
             echo 'PureScript and/or package set versions in "client/src/Try/SharedConfig.purs"'
-            echo 'do not match the versions extracted from "stack.yaml" and "staging/packages.dhall".'
+            echo 'do not match the versions extracted from "stack.yaml" and "staging/spago.yaml".'
             echo 'Please run "cd client && npm run updateConfigVersions". CI will fail until then.'
             exit 1
           }

CHANGELOG.md

@@ -11,6 +11,10 @@ New features:
 Bugfixes:
 
 Other improvements:
+- Bump PureScript to `0.15.15` (#316 by @pete-murphy)
+- Bump Spago to `1.0.4` (#316 by @pete-murphy)
+- Update to latest package set (#316 by @pete-murphy)
+- Exclude packages that cannot run in the playground (unshimmed JS imports) from the package set, with per-package reasons recorded in `staging/excluded-packages.txt` (#316 by @pete-murphy)
 
 ## [v2026-07-03.1](https://github.com/purescript/trypurescript/releases/tag/v2026-07-03.1)
 

README.md

@@ -47,7 +47,7 @@ Most of these features can be controlled not only from the toolbar, but also usi
 
 ### Which Libraries Are Available?
 
-Try PureScript aims to provide a complete, recent package set from <https://github.com/purescript/package-sets>. The available libraries are those listed in [`staging/spago.dhall`](./staging/spago.dhall), at the versions in the package set mentioned in [`staging/packages.dhall`](./staging/packages.dhall).
+Try PureScript aims to provide a complete, recent package set from <https://github.com/purescript/registry/tree/main/package-sets>. The available libraries are those listed under `package.dependencies` in [`staging/spago.yaml`](./staging/spago.yaml), at the versions in the package set named by `workspace.packageSet.registry` in that same file.
 
 ## Development
 
@@ -109,13 +109,12 @@ npm run serve:(dev|production)
 
 ### 4. Choosing a Tag
 
-The built-in examples for Try PureScript are loaded from this GitHub repository. To change the tag that the examples are loaded from, you'll need to touch three files:
+The built-in examples for Try PureScript are loaded from this GitHub repository. To change the tag that the examples are loaded from, you'll need to touch two files:
 
-* `client/config/dev/Try.Config.purs`
-* `client/config/prod/Try.Config.purs`
+* `client/src/Try/Config.js`
 * `client/examples/Main.purs`, in the `fromExample` function.
 
-If you are preparing a release or if you need to adjust examples in development, you should change the tag in these three places (and ensure you're using the same tag in each place!).
+If you are preparing a release or if you need to adjust examples in development, you should change the tag in these two places (and ensure you're using the same tag in each place!).
 
 ## Server API
 

RELEASE.md

@@ -14,29 +14,42 @@ After making a new compiler release, do the following to redeploy Try PureScript
 2. Once the PR is merged, create a new GitHub tagged release using `vYYYY-MM-DD.X` (where `X` is usually `1` or the release attempt) as the version schema. The release will trigger a GitHub Actions build.
 3. Wait for the GitHub Actions build to finish (it builds the assets)
 4. Run `./deploy/run.sh vX-X-X.1`, replacing `vX-X-X.1` with the version you created.
-    - Note: if you're updating the compiler, be sure to push the corresponding tag to [`purescript-metadata`](https://github.com/purescript/purescript-metadata). Otherwise, `spago install` will fail on the server and prevent the server from starting.
 
 ## Updating the Package Set
 
 The try.purescript.org server only has a limited amount of memory. If the package set we use in deployment is too large, the server will run out of memory.
 
 Before deploying an updated package set, someone (your reviewer) should check that the memory required to hold the package set's externs files does not exceed that of the try.purescript.org server.
 
+To check, run the server locally from `staging/` with the production RTS flags (see `deploy/start`) plus `-s`, which prints a heap summary when the server exits:
+
+```console
+$ cd staging
+$ rm -rf .psci_modules   # start cold: the server's compilation cache
+$ (set -o noglob && stack exec trypurescript -- +RTS -N2 -A128m -M3G -s -RTS 8081 $(spago sources))
+```
+
+Cold boot compiles the whole set, which takes a few minutes. Once the server responds on port 8081, stop the server with Ctrl-C and you should see a summary printed on exit. The number to watch is `bytes maximum residency`. You'll have to run this a _second time_, keeping the `.psci_modules` that the first run produced, to measure the peak memory usage (warm boot has higher max live heap than cold boot without cache).
+
 Update the package set by doing the following. Each step is explained below:
 
 ### Summary
 
 ```sh
 pushd staging
-spago upgrade-set
-cat > spago.dhall << EOF
-{ name = "try-purescript-server"
-, dependencies = [] : List Text
-, packages = ./packages.dhall
-, sources = [ "src/**/*.purs" ]
-}
+cat > spago.yaml << EOF
+package:
+  name: try-purescript-server
+  dependencies: []
+workspace:
+  packageSet:
+    registry: 0.0.1
+  extraPackages: {}
 EOF
-spago ls packages | cut -f 1 -d ' ' | xargs spago install
+spago upgrade
+spago install $(spago ls packages --json --quiet \
+  | jq -r 'to_entries[] | select(.value.type == "registry") | .key' \
+  | grep -vxF -f <(awk -F'\t' '!/^#/ && NF {print $1}' excluded-packages.txt))
 popd
 pushd client
 npm run updateConfigVersions
@@ -47,33 +60,41 @@ popd
 
 ### Step-by-Step Explanation
 
-1. Update the `upstream` package set in `staging/packages.dhall`:
+1. Overwrite `staging/spago.yaml` with a placeholder config: an empty
+   `dependencies` list and any valid registry package set as a seed (the exact
+   version doesn't matter — the next step overwrites it). Starting from a clean
+   file ensures packages dropped from the new set don't linger.
 
-        ```
-        $ pushd staging && spago upgrade-set && popd
-        ```
+2. Upgrade to the latest package set:
 
-2. Set the `dependencies` key in the `spago.dhall` file to be an empty list. This will require a type annotation of `List Text`:
+    ```console
+    $ spago upgrade
+    ```
 
-        ```dhall
-        { name = "try-purescript-server"
-        , dependencies = [] : List Text
-        , packages = ./packages.dhall
-        , sources = [ "src/**/*.purs" ]
-        }
-        ```
+    This rewrites `workspace.packageSet.registry` to the newest available set,
+    replacing the seed version. Each set's JSON at
+    <https://github.com/purescript/registry/tree/main/package-sets> records the
+    `compiler` version it targets, which should line up with the `purescript`
+    version in `stack.yaml` — pin the set explicitly in step 1 instead if the
+    latest set targets a compiler you don't want.
 
-3. For `staging/spago.dhall`, install all packages in the package set by running this command:
+3. Install every package in the new set — except those listed in
+   `staging/excluded-packages.txt` (see [Excluded Packages](#excluded-packages))
+   — so they're all available in the playground. This overwrites the empty
+   `dependencies` list in `staging/spago.yaml`, then downloads, compiles, and
+   locks them.
 
-        ```
-        $ spago ls packages | cut -f 1 -d ' ' | xargs spago install
-        ```
+    ```console
+    $ spago install $(spago ls packages --json --quiet \
+        | jq -r 'to_entries[] | select(.value.type == "registry") | .key' \
+        | grep -vxF -f <(awk -F'\t' '!/^#/ && NF {print $1}' excluded-packages.txt))
+    ```
 
 4. Update the `client/src/Try/SharedConfig.purs` file by running this command in `client`:
 
-        ```console
-        $ npm run updateConfigVersions
-        ```
+    ```console
+    $ npm run updateConfigVersions
+    ```
 
 5. If any packages need NPM dependencies, you can try adding their shims to the import map in `client/public/frame.html`
     - Open up the `generator.jspm.io` URL in the comment
@@ -86,9 +107,30 @@ popd
 
 6. If `es-module-shims` releases a new version, you can calculate its SHA-384 via
 
-        ```console
-        $ ESM_VERSION=1.5.5
-        $ curl -L -o es-module-shims.js "https://ga.jspm.io/npm:es-module-shims@$ESM_VERSION/dist/es-module-shims.js"
-        $ echo "sha384-$(openssl dgst -sha384 -binary es-module-shims.js | openssl base64 -A)"
-        $ rm es-module-shims.js
-        ```
+    ```console
+    $ ESM_VERSION=1.5.5
+    $ curl -L -o es-module-shims.js "https://ga.jspm.io/npm:es-module-shims@$ESM_VERSION/dist/es-module-shims.js"
+    $ echo "sha384-$(openssl dgst -sha384 -binary es-module-shims.js | openssl base64 -A)"
+    $ rm es-module-shims.js
+    ```
+
+### Excluded Packages
+
+`staging/excluded-packages.txt` lists the packages deliberately left out of the
+set, one per line with a tab-separated reason. The install command above
+filters through this file, so re-running the update steps keeps them excluded.
+
+The only exclusion criterion is that a package cannot *run* in the playground:
+its foreign modules (or a dependency's) import bare JS specifiers — npm packages
+or Node builtins — that the import map in `client/public/frame.html` does not
+shim, so the compiled code throws as soon as it executes. Excluding these
+packages also keeps the server inside its memory budget (see the note at the top
+of this section).
+
+To bring an excluded package back: add shims for its imports to the import map
+(step 5 above), then remove its line — along with the lines of any packages
+that were excluded only for depending on it — and re-run the install step.
+
+When upgrading to a new package set, check any packages that are new to the
+set for unshimmed bare imports in their foreign modules, and append them here
+with a reason.

client/config/dev/Try.Config.purs

@@ -3,23 +3,24 @@
   "private": true,
   "scripts": {
     "clean": "rimraf output",
-    "test": "spago test --path config/dev/Try.Config.purs",
-    "build": "spago build --path config/dev/Try.Config.purs",
-    "build:dev": "spago bundle-app --path config/dev/Try.Config.purs --to client.js",
-    "build:production": "spago bundle-app --path config/prod/Try.Config.purs --purs-args '--censor-lib --strict' --to client.js",
-    "bundle": "esbuild --outfile=public/js/index.js --bundle --minify --platform=browser --format=iife --tree-shaking=true client.js",
+    "test": "spago test",
+    "build": "spago build",
+    "build:dev": "spago bundle --outfile client.js --force",
+    "build:production": "spago bundle --outfile client.js --force --strict",
+    "bundle:dev": "esbuild --define:__DEVELOPMENT__=true --outfile=public/js/index.js --bundle --minify --platform=browser --format=iife --tree-shaking=true client.js",
+    "bundle:production": "esbuild --define:__DEVELOPMENT__=false --outfile=public/js/index.js --bundle --minify --platform=browser --format=iife --tree-shaking=true client.js",
     "serve": "http-server public/ -o / --cors=\"Access-Control-Allow-Origin: *\" -c-1",
-    "serve:dev": "npm run build:dev && npm run bundle && npm run serve",
-    "serve:production": "npm run build:production && npm run bundle && npm run serve",
+    "serve:dev": "npm run build:dev && npm run bundle:dev && npm run serve",
+    "serve:production": "npm run build:production && npm run bundle:production && npm run serve",
     "updateConfigVersions": "node updateSharedConfigVersions.mjs src/Try/SharedConfig.purs"
   },
   "devDependencies": {
     "esbuild": "^0.14.43",
     "http-server": "^14.1.0",
-    "purescript": "^0.15.2",
+    "purescript": "^0.15.15",
     "purescript-psa": "^0.8.2",
     "rimraf": "^2.5.4",
-    "spago": "^0.20.9"
+    "spago": "^1.0.4"
   },
   "dependencies": {
     "ace-builds": "^1.5.0",