build: support npm/yarn/pnpm + Changesets publishing

.changeset/README.md

@@ -0,0 +1,9 @@
+# Changesets
+
+This folder is managed by [Changesets](https://github.com/changesets/changesets) — it drives the version bumps, changelogs and npm publishing for this monorepo.
+
+- **Add a changeset** for your change: `npm run changeset` (or `yarn`/`pnpm`/`gjsify run changeset`). Pick the affected packages and the bump type, write a one-line summary. Commit the generated `.changeset/*.md` with your PR.
+- All `@learn6502/*` packages are **version-locked** (`fixed` group) — they bump together, keeping the internal `^x.y.z` ranges consistent. Changesets rewrites those internal ranges automatically on `version`, so you never hand-sync them.
+- Only **`@learn6502/6502`** is published to npm; the other packages are `private` (they still get versioned + changelogged, just not published).
+
+Release flow (maintainer): `npm run changeset:version` (applies pending changesets → bumps versions + internal ranges + writes CHANGELOGs), commit, then `npm run changeset:publish` (builds + `changeset publish`).

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [["@learn6502/*"]],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/package-managers.yml

@@ -0,0 +1,75 @@
+# Verifies the repo installs + resolves its workspaces with every supported
+# package manager — npm, yarn, pnpm and gjsify. Deliberately NOT run per-PR
+# (the normal CI on every PR uses gjsify): this is manual (`workflow_dispatch`)
+# plus a weekly safety-net cron, so a regression in the multi-PM contract
+# (e.g. someone reintroduces the `workspace:` protocol, which npm/yarn-v1 can't
+# resolve) is still caught without taxing every PR.
+name: Package Managers
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Weekly, Monday 05:00 UTC — light insurance, not per-PR.
+    - cron: "0 5 * * 1"
+
+jobs:
+  install-and-resolve:
+    name: ${{ matrix.pm }}
+    runs-on: ubuntu-latest
+    # Fedora ships gjs (SpiderMonkey) — needed by `gjsify tsc`, which the
+    # build/check scripts spawn. Mirrors the CI `type-check` job's container.
+    container:
+      image: fedora:43
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # npm/yarn-v1/pnpm only work because internal deps use plain `^x.y.z`
+          # ranges (NOT the `workspace:` protocol). pnpm additionally needs the
+          # committed pnpm-workspace.yaml (+ nodeLinker: hoisted) in the repo.
+          - pm: npm
+            setup: ""
+            install: "npm install"
+          - pm: yarn
+            setup: "npm install -g yarn"
+            install: "yarn install"
+          - pm: pnpm
+            setup: "npm install -g pnpm"
+            install: "pnpm install"
+          - pm: gjsify
+            setup: "npm install -g @gjsify/cli@^0.10.0"
+            install: "gjsify install"
+
+    steps:
+      - name: Install system prerequisites (incl. gjs)
+        run: dnf install -y git tar xz findutils gjs
+
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+
+      - name: Setup + install with ${{ matrix.pm }}
+        # Matrix values are trusted workflow constants; passed via env (not
+        # inlined into the script) per the GitHub-Actions injection guidance.
+        env:
+          SETUP: ${{ matrix.setup }}
+          INSTALL: ${{ matrix.install }}
+        run: |
+          set -eux
+          if [ -n "$SETUP" ]; then sh -c "$SETUP"; fi
+          sh -c "$INSTALL"
+
+      - name: Verify workspace resolution (build 6502 → type-check common-ui)
+        # common-ui imports @learn6502/6502; this only type-checks if the PM
+        # symlinked the workspace + resolved the internal `^x.y.z` range to the
+        # local package. The lightest decisive cross-workspace check (gjs only,
+        # no GTK build deps). The full app-gnome build is covered by flatpak.yml.
+        run: |
+          set -eux
+          export PATH="$PWD/node_modules/.bin:$PATH"
+          gjsify workspace @learn6502/6502 build
+          gjsify workspace @learn6502/common-ui check

.npmrc

@@ -0,0 +1,13 @@
+# pnpm-specific settings. npm/yarn/gjsify ignore these keys (npm may print a
+# cosmetic "unknown config" for node-linker — install still works).
+#
+# link-workspace-packages: the internal deps use plain `^x.y.z` ranges (not the
+# `workspace:` protocol). pnpm 10 defaults this to false, so without it pnpm
+# fetches @learn6502/* from the registry (404) instead of linking the local
+# workspace. true makes pnpm resolve a workspace-named dep to the local package.
+link-workspace-packages=true
+# node-linker: flat node_modules (like npm/yarn/gjsify). pnpm's default strict
+# symlinked layout hides the gjsify bundler's node-builtin polyfills
+# (@gjsify/node-globals etc.) → `--globals auto` fails the build with
+# "Unsupported URI scheme for importing: node".
+node-linker=hoisted

README.md

@@ -41,19 +41,29 @@ This project is a fork of the [original web-based easy6502 tutorial](https://git
 
 ### Local Development
 
-To get started with local development:
+The repository works with **gjsify** (recommended), **npm**, **yarn** or **pnpm** — use whichever you're comfortable with.
 
 ```bash
-# Install dependencies
+# Recommended — gjsify (the canonical toolchain)
 gjsify install
-
-# Build all packages
 gjsify run build
-
-# Start the GNOME application
 gjsify run start:gnome
 ```
 
+Prefer npm / yarn / pnpm? They all work too — each installs the workspaces and resolves the internal dependencies; the build itself still runs through gjsify (it's a dev dependency, so its bin is available after any install):
+
+```bash
+npm install        # or:  yarn install   |   pnpm install
+npm run build && npm run start:gnome      # or the yarn / pnpm equivalent
+```
+
+Notes:
+
+- **gjsify is the canonical path** — the committed `gjsify-lock.json` and the offline Flatpak build use it. npm/yarn/pnpm generate their own lockfiles (gitignored); they're fine for local dev, please don't commit them.
+- **pnpm** relies on the committed `pnpm-workspace.yaml` (pnpm doesn't read the `workspaces` field) plus `.npmrc` — `link-workspace-packages=true` (so plain `^` ranges link the local workspaces) and `node-linker=hoisted` (flat layout the gjsify bundler needs).
+- The internal packages use plain `^x.y.z` ranges (not the `workspace:` protocol), which is why every manager — including npm and classic yarn — can resolve them.
+- A manual **Package Managers** CI workflow verifies all four managers install + resolve the workspaces; trigger it from the Actions tab if you touch the dependency wiring.
+
 ### Flatpak Build
 
 ### Building
@@ -64,6 +74,10 @@ To build the packages, run `gjsify run build` in the root of the repository.
 
 To run the packages, run `gjsify run start:gnome` for the GNOME app or `gjsify run start:web` for the web app.
 
+### Releasing
+
+Versioning, changelogs and npm publishing are managed with [Changesets](https://github.com/changesets/changesets) (see [`.changeset/README.md`](.changeset/README.md)). Add a changeset with your change (`gjsify run changeset`, or `npm`/`yarn`/`pnpm run changeset`). All `@learn6502/*` packages are version-locked and bump together; only `@learn6502/6502` is published to npm (the rest are private). Maintainer release: `… run changeset:version` then `… run changeset:publish`.
+
 ## Contributing
 
 Contributions are welcome :)