Title: Migrate toolchain to the new Spago (spago.yaml + registry), including the Lua package-set forks · Issue #55 · purescript-lua/purescript-lua · GitHub
Open Graph Title: Migrate toolchain to the new Spago (spago.yaml + registry), including the Lua package-set forks · Issue #55 · purescript-lua/purescript-lua
X Title: Migrate toolchain to the new Spago (spago.yaml + registry), including the Lua package-set forks · Issue #55 · purescript-lua/purescript-lua
Description: Motivation Legacy spago 0.21.x is the last release from the Haskell codebase, and it is the only release that still understands spago.dhall / packages.dhall. All ongoing Spago development happens in the PureScript rewrite (≥ 0.93), which...
Open Graph Description: Motivation Legacy spago 0.21.x is the last release from the Haskell codebase, and it is the only release that still understands spago.dhall / packages.dhall. All ongoing Spago development happens i...
X Description: Motivation Legacy spago 0.21.x is the last release from the Haskell codebase, and it is the only release that still understands spago.dhall / packages.dhall. All ongoing Spago development happens i...
Opengraph URL: https://github.com/purescript-lua/purescript-lua/issues/55
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Migrate toolchain to the new Spago (spago.yaml + registry), including the Lua package-set forks","articleBody":"## Motivation\n\nLegacy `spago` 0.21.x is the last release from the Haskell codebase, and it is the only release that still understands `spago.dhall` / `packages.dhall`. All ongoing Spago development happens in the PureScript rewrite (≥ 0.93), which dropped Dhall entirely in favour of `spago.yaml`, the PureScript Registry, and a `spago.lock` lock file. Staying on the legacy driver means we are pinned to a frozen tool while the ecosystem (package sets, registry, tooling) moves to the new format.\n\nPR #41 already attempted the test-project half of this migration. It is a useful starting point but incomplete in ways that would break our build, so this issue tracks the full migration so it lands correctly rather than merging that PR as-is. See the \"Relationship to PR #41\" section below.\n\n## Current state\n\n- **Dev shell** pins the legacy Haskell spago (`easy-ps.spago` = 0.21.0) and `purs-0_15_16-0`, both from easy-purescript-nix (`flake.nix`).\n- **Test project** (`test/ps`) is configured with `spago.dhall` + `packages.dhall`, where `packages.dhall` is `upstream-ps // upstream-lua`. The right operand (`Unisay/purescript-lua-package-sets`) overrides core packages with Lua FFI forks. That package set ships only `packages.dhall` (no JSON variant).\n- **Golden harness** (`test/Language/PureScript/Backend/Lua/Golden/Spec.hs`) shells out to `spago build -u '-g corefn'` and then reads `test/ps/output/**/corefn.json`.\n\n## Target state\n\n- Dev shell provides the new spago (≥ 0.93). The toolchain itself already comes from `purescript-overlay` (see the prerequisite issue), so this is a one-attribute swap of the spago pin; `purs` stays at 0.15.16.\n- `test/ps` uses `spago.yaml`: a `registry` package-set baseline plus `extraPackages` git overrides for the FFI-bearing Lua forks.\n- The build reliably emits CoreFn, goldens are regenerated against current package versions, and `spago.lock` is committed for reproducibility.\n\n## Migration plan\n\n### 1. Bump spago to the new release (`flake.nix`)\n\nPrerequisite: the separate \"source the toolchain from purescript-overlay\" issue (#54), which moves the dev shell to the overlay while keeping legacy spago 0.21. With the overlay already providing the toolchain, this step is just a pin swap.\n\n- [ ] Replace the legacy `spago-bin.spago-0_21_0` pin with the overlay's stable `spago` (new release, ≥ 0.93).\n- [ ] Keep `purs` at 0.15.16 (the overlay's stable `purs`), so only the package-set and build changes drive any golden churn.\n- [ ] Confirm `spago --version` ≥ 0.93 inside `nix develop`.\n\n### 2. Test-project config (`test/ps`)\n\n- [ ] Scaffold `spago.yaml` with `spago-legacy migrate` (the only release carrying the `migrate` command), then delete `spago.dhall` and `packages.dhall`.\n- [ ] Set `workspace.packageSet.registry: \u003cversion>` as the baseline.\n- [ ] Add `extraPackages` git overrides for the **FFI-bearing** forks only. Packages that ship `.lua` FFI and therefore require a Lua fork: `arrays`, `console`, `control`, `effect`, `enums`, `foldable-traversable`, `functions`, `integers`, `numbers`, `partial`, `prelude`, `refs`, `st`, `strings`, `unfoldable`, `unsafe-coerce`.\n- [ ] Leave pure (no-FFI) packages to come straight from the registry: `bifunctors`, `const`, `contravariant`, `distributive`, `either`, `exists`, `functors`, `gen`, `identity`, `invariant`, `maybe`, `newtype`, `nonempty`, `orders`, `profunctor`, `safe-coerce`, `tailrec`, `tuples`, `type-equality`. Verify each resolves against the chosen registry version; promote any that turn out to be incompatible.\n- [ ] Pin every git override to a tag, not a branch. The new spago strongly discourages branch refs, and the lock file records the resolved commit anyway.\n\n### 3. CoreFn generation (`Golden/Spec.hs`)\n\nThe new spago defaults to JS codegen; CoreFn is not produced unless asked for. PR #41's plain `spago build` would not generate `corefn.json` at all. The suite only appears to pass there because committed `Golden*/corefn.json` files are read as stale inputs, which silently defeats the point of recompiling from source.\n\n- [ ] Change the build command to pass CoreFn through purs, e.g. `spago build --purs-args \"--codegen corefn,js\"`. Use `corefn,js` rather than `corefn` alone: incremental-build caching can leave CoreFn stale when only one codegen target is requested (purescript/spago#643).\n- [ ] Confirm the build actually refreshes `corefn.json` (touch a source file, rebuild, diff) so the harness validates freshly compiled output rather than committed copies.\n\n### 4. `.gitignore` and the lock file\n\n- [ ] Commit `spago.lock` rather than ignoring it. For a golden-test project, pinning the exact resolved fork commits is what we want. (PR #41 ignored it; reverse that decision here.)\n- [ ] Ignore the dependency output directories and `.js` / `.js.map` artifacts while keeping `Golden*/corefn.json` tracked.\n\n### 5. Goldens and docs\n\n- [ ] Regenerate goldens with `./scripts/golden_reset` against current package versions.\n- [ ] Update the toolchain section of `CLAUDE.md` (spago version, the new build command, and how the override-based package set works).\n\n### 6. The Lua package-set forks (\"all packages\")\n\n`extraPackages` git entries need each package's dependency list. There are two ways to supply it:\n\n- **(a) Inline `dependencies:`** per git entry in `test/ps/spago.yaml` (fast; this is what PR #41 did; duplicates each fork's dep graph in our config and drifts over time).\n- **(b) Add a `spago.yaml` to each Lua fork repo** so consumers don't inline deps (reusable, single source of truth; ~16 FFI fork repos to touch, all under accounts we control).\n\n- [ ] Choose (a) or (b). Recommendation: (b) long-term since we own the forks, with (a) acceptable as an interim step to unblock the test project.\n\n## New spago features worth adopting\n\n- **Lock file (`spago.lock`)**: pins the exact fork commits behind every git override, giving reproducible golden inputs that complement the Nix pin. Commit it.\n- **Custom backend (`workspace.backend.cmd`)**: longer term, register `pslua` as a Spago backend so downstream users get first-class `spago build` / `spago bundle` / `spago run` targeting Lua instead of wiring the compiler by hand. Good for adoption, but worth a separate follow-up issue rather than folding it into this migration.\n- **Registry solver (`--use-solver`)**: deliberately not recommended here. Golden stability wants exact pins, not range solving, so the package set with pinned overrides is the better fit.\n\n## Open questions\n\n- Which registry package-set version aligns with `purs` 0.15.16 and the fork versions? (We plan to keep `purs` at 0.15.16; the registry baseline must be compatible with it.)\n- Strategy (a) vs (b) for fork dependency lists.\n- Do the FFI forks themselves need a one-time bump to be registry-resolvable (versions/bounds), or do the existing tags work as-is via git overrides?\n\n## Relationship to PR #41\n\nPR #41 (\"migrate test project from spago.dhall to spago.yaml\") is the prior art for steps 2, 4, and the inline-deps variant of step 6. What it is missing, and what this issue exists to get right:\n\n- It does not touch `flake.nix`, so the pinned legacy spago in the dev shell (and therefore CI) cannot read the new `spago.yaml`.\n- Its `spago build` does not request CoreFn codegen, so it would stop generating fresh `corefn.json` (masked by committed goldens).\n- Its regenerated goldens are now stale relative to `main` (the package set has since moved), and it drops a `luacheck --no-redefined` flag whose inline comment explains why it is needed.\n\n## References\n\n- [Spago README / migration guide](https://github.com/purescript/spago/blob/master/README.md)\n- [purescript/spago#643: CoreFn not refreshed by incremental build](https://github.com/purescript/spago/issues/643)\n- [purescript-overlay (new spago + purs via Nix)](https://github.com/thomashoneyman/purescript-overlay)\n- PR #41: prior art for the test-project migration\n","author":{"url":"https://github.com/Unisay","@type":"Person","name":"Unisay"},"datePublished":"2026-06-14T08:03:45Z","url":"https://github.com/purescript-lua/purescript-lua/issues/55"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:947e7c29-d816-7f0b-f286-1efaa98bde07 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | B9FA:4BB79:544DA7:6D72EE:6B00DB5C |
| html-safe-nonce | 64e7954c6f28e48e12d3525cdb54a7c16fcf7960823a6c68bdcb13b4e5a775a5 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCOUZBOjRCQjc5OjU0NERBNzo2RDcyRUU6NkIwMERCNUMiLCJ2aXNpdG9yX2lkIjoiNDkwMDc4Mjg1NDQ4NjY3ODM2NCIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | d602191f023f452a4c2aab86f5c0e56a6f2d07468e156d7d98cd7dc0f1e13937 |
| hovercard-subject-tag | issue:4658381851 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/purescript-lua/purescript-lua/55/issue_layout |
| twitter:image | https://opengraph.githubassets.com/91b10706739f830bc02817749e5e2fd619abeb9bdb148eb311e8a254610771a0/purescript-lua/purescript-lua/issues/55 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/91b10706739f830bc02817749e5e2fd619abeb9bdb148eb311e8a254610771a0/purescript-lua/purescript-lua/issues/55 |
| og:image:alt | Motivation Legacy spago 0.21.x is the last release from the Haskell codebase, and it is the only release that still understands spago.dhall / packages.dhall. All ongoing Spago development happens i... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | Unisay |
| hostname | github.com |
| expected-hostname | github.com |
| None | 043c3f30fbcbe2c6c8e729e10cbbbc90c406546f9fbbb67c648d38f6b7d16daf |
| turbo-cache-control | no-preview |
| go-import | github.com/purescript-lua/purescript-lua git https://github.com/purescript-lua/purescript-lua.git |
| octolytics-dimension-user_id | 131581790 |
| octolytics-dimension-user_login | purescript-lua |
| octolytics-dimension-repository_id | 587200487 |
| octolytics-dimension-repository_nwo | purescript-lua/purescript-lua |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 587200487 |
| octolytics-dimension-repository_network_root_nwo | purescript-lua/purescript-lua |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 5425dc24e8bd8d6fca9641a12afc984825a43875 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width