From bbcc63f76e3442efbef7242d8cb041e4da71d084 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 08:24:12 +0000 Subject: [PATCH 1/8] fix: satisfy tsc's test-file type deps so the mirrored build passes @astrelitehq/localgrid's build script (tsc -b && vite build) type-checks its whole src tree, test files included, but the published npm package only ships its runtime dependencies, not the devDependencies (vitest, Testing Library, @types/spark-md5) those files need. Installing the same packages here, where npm's flat node_modules layout lets tsc resolve them from node_modules/@astrelitehq/localgrid, fixes the build without touching localgrid.dev. --legacy-peer-deps works around an unrelated npm arborist crash hit while resolving vitest's optional peer dependencies; that flag also disables npm's automatic peer-dependency install, so @testing-library/dom (a peer of @testing-library/react and user-event) is listed explicitly too. See the new README section for the full explanation and the real (upstream) fix this works around. --- .github/workflows/pages.yml | 9 ++++++- README.md | 48 ++++++++++++++++++++++++++++++++++++- package.json | 8 ++++++- 3 files changed, 62 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index f3f0320..dd2febf 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -43,7 +43,14 @@ jobs: - name: Install dependencies # npm ci needs a committed lockfile, which this repo doesn't have # yet (see .gitignore). Switch back to `npm ci` once one exists. - run: npm install + # + # --legacy-peer-deps works around an npm arborist crash + # ("Cannot read properties of null (reading 'edgesOut')") hit while + # resolving vitest's optional peer dependencies (@vitest/browser-*, + # msw, etc.) with npm's default (npm >= 7) peer-dependency + # resolver. See the "Why vitest and Testing Library are + # devDependencies here" section in README.md. + run: npm install --legacy-peer-deps env: NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # granted via the package's Actions access settings diff --git a/README.md b/README.md index 8e650a9..1d05828 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,52 @@ A single fine-grained PAT scoped to both repos (Packages: Read on localgrid.dev, Contents: Read + Actions: Write on localgrid.proxy) can back both secrets if you'd rather manage one token than two. +## Why `vitest`, Testing Library, and `@types/spark-md5` are devDependencies here + +This repo has no tests of its own, but `package.json` still lists `vitest`, +`@testing-library/dom`, `@testing-library/react`, +`@testing-library/user-event`, `@testing-library/jest-dom`, and +`@types/spark-md5` as devDependencies. That's a workaround, not an +accident. + +`@astrelitehq/localgrid`'s own `build` script is `tsc -b && vite build`, +and its `tsconfig.app.json` does `"include": ["src"]` with no exclusion for +`*.test.ts(x)` files, so `tsc -b` type-checks the whole `src` tree — +including its test files and `spark-md5`-typed source — on every build. +But the npm package only ships its own `dependencies`, not the +`devDependencies` those files need type declarations for (`vitest`, +`@testing-library/*` for the tests; `@types/spark-md5` for +`HashGeneratorWidget.tsx` itself, which imports the untyped `spark-md5` +package directly). Since this repo builds `@astrelitehq/localgrid` by +running its `build` script straight out of `node_modules` (see above), that +build fails here with `TS2307: Cannot find module 'vitest'` and similar +errors unless those packages are available too. (`@testing-library/dom` is +only a *peer* dependency of `@testing-library/react`/`user-event`, normally +auto-installed by npm — it's listed explicitly here because installing +with plain `npm install` currently hits an npm arborist crash resolving +`vitest`'s optional peer graph, worked around below with +`--legacy-peer-deps`, which skips that auto-install.) + +Because npm installs into one flat, hoisted `node_modules`, adding the same +packages as devDependencies *here* puts them where `tsc -b` running inside +`node_modules/@astrelitehq/localgrid` can still resolve them, without +touching localgrid.dev. Their versions should track the `devDependencies` +versions in [localgrid.dev's `package.json`](https://github.com/AstreliteHQ/localgrid.dev/blob/main/package.json) +for whichever files a given `@astrelitehq/localgrid` release ships; bump +them here if a new release needs something this list doesn't cover yet (a +build failing with another `TS2307`/`TS7016` for a `devDependency`-only +package is the signal). + +The real fix is upstream, in localgrid.dev: excluding test files from +`tsconfig.app.json`'s production project (or otherwise keeping them out of +`tsc -b`), and adding `@types/spark-md5` to `dependencies` instead of +`devDependencies` since `spark-md5` itself is a runtime dependency, so a +consumer installing the published package never needs the test toolchain +just to build it. Once that lands, this section and the devDependencies +above can go (except `@types/spark-md5`, or whatever replaces it, which +would then belong under `dependencies` in localgrid.dev and get pulled in +transitively instead). + ## Lockfile `package-lock.json` isn't committed yet (see `.gitignore`): generating one @@ -57,7 +103,7 @@ those locally (`export NODE_AUTH_TOKEN=...` with a PAT that has ```bash export NODE_AUTH_TOKEN= -npm install +npm install --legacy-peer-deps # see "Why vitest and Testing Library are devDependencies here" npm run dev # dev server, base path defaults to / npm run build # production build at /localgrid.proxy/, output in ./dist ``` diff --git a/package.json b/package.json index 8fac295..9113b35 100644 --- a/package.json +++ b/package.json @@ -13,13 +13,19 @@ }, "devDependencies": { "@tailwindcss/vite": "^4.3.3", + "@testing-library/dom": "^10.4.1", + "@testing-library/jest-dom": "^7.0.0", + "@testing-library/react": "^16.3.2", + "@testing-library/user-event": "^14.6.3", "@types/node": "^24.13.3", "@types/react": "^19.2.17", "@types/react-dom": "^19.2.3", + "@types/spark-md5": "^3.0.5", "@vitejs/plugin-react": "^6.0.4", "tailwindcss": "^4.3.3", "typescript": "~6.0.2", "vite": "^8.2.0", - "vite-plugin-pwa": "^1.3.0" + "vite-plugin-pwa": "^1.3.0", + "vitest": "^4.1.10" } } From 1b5719f51312c829c4217ed28b84461262f3e5bc Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 09:18:14 +0000 Subject: [PATCH 2/8] fix: upgrade npm in CI instead of using --legacy-peer-deps --legacy-peer-deps disables peer-dependency conflict checking for the entire install, not just the one package that needed a workaround. The actual problem is an npm arborist bug (npm < 12) that crashes resolving vitest's optional peer dependency graph; npm 12 resolves it correctly with default (non-legacy) peer resolution. Upgrading npm before `npm install` in CI fixes the crash without giving up peer-dependency checking, and lets npm auto-install @testing-library/dom (a real peer of @testing-library/react and user-event) instead of listing it explicitly. Also reframes the README section: this accommodation is meant to stay local to this repo rather than be treated as a stopgap for an upstream fix. --- .github/workflows/pages.yml | 18 ++++++++++-------- README.md | 38 ++++++++++++++++++------------------- package.json | 1 - 3 files changed, 28 insertions(+), 29 deletions(-) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index dd2febf..1df7c05 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -40,17 +40,19 @@ jobs: # (see .gitignore), so there's nothing for setup-node to key the # cache on. Switch this back on once a lockfile is committed. + - name: Upgrade npm + # Node 20's bundled npm (10.x) crashes ("Cannot read properties of + # null (reading 'edgesOut')") in its arborist resolver while + # resolving vitest's optional peer dependencies (@vitest/browser-*, + # msw, etc.) below. Fixed in npm 12. Pinned rather than `npm@latest` + # so a future npm release can't reintroduce a different resolver + # bug here silently. + run: npm install -g npm@12.0.2 + - name: Install dependencies # npm ci needs a committed lockfile, which this repo doesn't have # yet (see .gitignore). Switch back to `npm ci` once one exists. - # - # --legacy-peer-deps works around an npm arborist crash - # ("Cannot read properties of null (reading 'edgesOut')") hit while - # resolving vitest's optional peer dependencies (@vitest/browser-*, - # msw, etc.) with npm's default (npm >= 7) peer-dependency - # resolver. See the "Why vitest and Testing Library are - # devDependencies here" section in README.md. - run: npm install --legacy-peer-deps + run: npm install env: NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # granted via the package's Actions access settings diff --git a/README.md b/README.md index 1d05828..13e1353 100644 --- a/README.md +++ b/README.md @@ -45,10 +45,11 @@ both secrets if you'd rather manage one token than two. ## Why `vitest`, Testing Library, and `@types/spark-md5` are devDependencies here This repo has no tests of its own, but `package.json` still lists `vitest`, -`@testing-library/dom`, `@testing-library/react`, -`@testing-library/user-event`, `@testing-library/jest-dom`, and -`@types/spark-md5` as devDependencies. That's a workaround, not an -accident. +`@testing-library/react`, `@testing-library/user-event`, +`@testing-library/jest-dom`, and `@types/spark-md5` as devDependencies. +That's a deliberate, permanent accommodation this repo makes for how it +consumes `@astrelitehq/localgrid` — not something expected to be cleaned up +once some other repo changes. `@astrelitehq/localgrid`'s own `build` script is `tsc -b && vite build`, and its `tsconfig.app.json` does `"include": ["src"]` with no exclusion for @@ -61,12 +62,10 @@ But the npm package only ships its own `dependencies`, not the package directly). Since this repo builds `@astrelitehq/localgrid` by running its `build` script straight out of `node_modules` (see above), that build fails here with `TS2307: Cannot find module 'vitest'` and similar -errors unless those packages are available too. (`@testing-library/dom` is -only a *peer* dependency of `@testing-library/react`/`user-event`, normally -auto-installed by npm — it's listed explicitly here because installing -with plain `npm install` currently hits an npm arborist crash resolving -`vitest`'s optional peer graph, worked around below with -`--legacy-peer-deps`, which skips that auto-install.) +errors unless those packages are available too. `@testing-library/dom` (a +*peer* dependency of `@testing-library/react`/`user-event`) isn't listed +explicitly — npm auto-installs declared peers by default, so it's pulled in +on its own. Because npm installs into one flat, hoisted `node_modules`, adding the same packages as devDependencies *here* puts them where `tsc -b` running inside @@ -78,15 +77,13 @@ them here if a new release needs something this list doesn't cover yet (a build failing with another `TS2307`/`TS7016` for a `devDependency`-only package is the signal). -The real fix is upstream, in localgrid.dev: excluding test files from -`tsconfig.app.json`'s production project (or otherwise keeping them out of -`tsc -b`), and adding `@types/spark-md5` to `dependencies` instead of -`devDependencies` since `spark-md5` itself is a runtime dependency, so a -consumer installing the published package never needs the test toolchain -just to build it. Once that lands, this section and the devDependencies -above can go (except `@types/spark-md5`, or whatever replaces it, which -would then belong under `dependencies` in localgrid.dev and get pulled in -transitively instead). +This is intentionally contained to this repo rather than "fixed" in +localgrid.dev (e.g. by excluding test files from its production `tsc` +project). That app has no reason to carry build-config complexity to serve +a consumer that rebuilds its raw source with a different Vite base path — +this repo is the one adapter-shaped place that already exists to hold +differences like that (see the base-path override above), so this is where +the accommodation belongs. ## Lockfile @@ -103,7 +100,8 @@ those locally (`export NODE_AUTH_TOKEN=...` with a PAT that has ```bash export NODE_AUTH_TOKEN= -npm install --legacy-peer-deps # see "Why vitest and Testing Library are devDependencies here" +npm install # needs npm >= 12; older npm can crash resolving vitest's + # optional peer deps, see the "Upgrade npm" step in pages.yml npm run dev # dev server, base path defaults to / npm run build # production build at /localgrid.proxy/, output in ./dist ``` diff --git a/package.json b/package.json index 9113b35..c98d1c2 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,6 @@ }, "devDependencies": { "@tailwindcss/vite": "^4.3.3", - "@testing-library/dom": "^10.4.1", "@testing-library/jest-dom": "^7.0.0", "@testing-library/react": "^16.3.2", "@testing-library/user-event": "^14.6.3", From fb308f16c46b0a4e5749a92ec47a7b75699cddd0 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 09:22:18 +0000 Subject: [PATCH 3/8] chore: migrate CI to Node 24 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Matches @types/node's ^24.13.3 range, which was already declared here but untested against — CI ran Node 20 while types targeted Node 24 APIs. Also drops the "Upgrade npm" step: Node 24 bundles npm 11.19.0, which (like npm 12) doesn't hit the arborist crash resolving vitest's optional peer dependencies that Node 20/22's bundled npm 10.9.7 does. One less manual pin to maintain. --- .github/workflows/pages.yml | 11 +---------- README.md | 6 ++++-- 2 files changed, 5 insertions(+), 12 deletions(-) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 1df7c05..01cd019 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -35,20 +35,11 @@ jobs: - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: - node-version: '20' + node-version: '24' # matches @types/node's ^24.x range below # No npm cache here: there's no committed package-lock.json yet # (see .gitignore), so there's nothing for setup-node to key the # cache on. Switch this back on once a lockfile is committed. - - name: Upgrade npm - # Node 20's bundled npm (10.x) crashes ("Cannot read properties of - # null (reading 'edgesOut')") in its arborist resolver while - # resolving vitest's optional peer dependencies (@vitest/browser-*, - # msw, etc.) below. Fixed in npm 12. Pinned rather than `npm@latest` - # so a future npm release can't reintroduce a different resolver - # bug here silently. - run: npm install -g npm@12.0.2 - - name: Install dependencies # npm ci needs a committed lockfile, which this repo doesn't have # yet (see .gitignore). Switch back to `npm ci` once one exists. diff --git a/README.md b/README.md index 13e1353..33af7ab 100644 --- a/README.md +++ b/README.md @@ -100,8 +100,10 @@ those locally (`export NODE_AUTH_TOKEN=...` with a PAT that has ```bash export NODE_AUTH_TOKEN= -npm install # needs npm >= 12; older npm can crash resolving vitest's - # optional peer deps, see the "Upgrade npm" step in pages.yml +npm install # Node 24 recommended (matches @types/node below and CI); + # npm 10.9.7 (Node 22's bundled version at the time of + # writing) crashes resolving vitest's optional peer deps, + # npm 11+ (bundled with Node 24) doesn't npm run dev # dev server, base path defaults to / npm run build # production build at /localgrid.proxy/, output in ./dist ``` From 39c7ba0a047ead12356ef86d599139ad2b398d38 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 09:26:23 +0000 Subject: [PATCH 4/8] docs: trim comment and README verbosity Shorten pages.yml comments to one-liners and cut the README down to what's load-bearing, dropping restated rationale and narrative explanation. --- .github/workflows/pages.yml | 25 ++------ README.md | 123 ++++++++++-------------------------- 2 files changed, 38 insertions(+), 110 deletions(-) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 01cd019..c16357a 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -1,20 +1,14 @@ name: Deploy to GitHub Pages on: - # Fired by localgrid.dev's release-please.yml (notify-proxy job) once a - # new @astrelitehq/localgrid version is published, via repository_dispatch - # over the GitHub API (a plain push/release trigger can't reach across - # repos). client_payload.tag_name is informational only, it's not pinned - # into the install below: `npm install` always pulls whatever version - # satisfies package.json's range, which is what "the latest release" means - # here. + # Fired by localgrid.dev's release-please.yml after a new package version + # is published (repository_dispatch, since a cross-repo trigger can't + # work any other way). repository_dispatch: types: [localgrid-release] # Rebuild on this repo's own commits, not just localgrid releases. push: branches: [main] - # Manual re-run, e.g. after bumping the @astrelitehq/localgrid version - # range in package.json or editing this workflow. workflow_dispatch: {} permissions: @@ -36,22 +30,15 @@ jobs: - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: '24' # matches @types/node's ^24.x range below - # No npm cache here: there's no committed package-lock.json yet - # (see .gitignore), so there's nothing for setup-node to key the - # cache on. Switch this back on once a lockfile is committed. + # No npm cache: no committed package-lock.json yet (see .gitignore). - name: Install dependencies - # npm ci needs a committed lockfile, which this repo doesn't have - # yet (see .gitignore). Switch back to `npm ci` once one exists. - run: npm install + run: npm install # switch to `npm ci` once a lockfile is committed env: NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # granted via the package's Actions access settings - name: Build - # Builds @astrelitehq/localgrid's own source (installed into - # node_modules) with its base path set to this repo's github.io - # subpath, then copies the result to ./dist. See the "build" script - # in package.json. + # Builds @astrelitehq/localgrid's source with this repo's base path. run: npm run build - name: Upload build artifact diff --git a/README.md b/README.md index 33af7ab..415cfd7 100644 --- a/README.md +++ b/README.md @@ -1,109 +1,50 @@ # localgrid.proxy -A GitHub Pages (`github.io`) mirror of [localgrid.dev](https://github.com/AstreliteHQ/localgrid.dev). +Mirrors [localgrid.dev](https://github.com/AstreliteHQ/localgrid.dev) to +`astrelitehq.github.io/localgrid.proxy/`, alongside its custom-domain +deployment. No app source lives here: it installs the +[`@astrelitehq/localgrid`](https://github.com/AstreliteHQ/localgrid.dev/pkgs/npm/localgrid) +npm package and builds *that* package's source with a different Vite base +path baked in. -localgrid.dev deploys behind its own custom domain. This repo exists so the -app is also reachable at `astrelitehq.github.io/localgrid.proxy/`, without -touching that custom-domain deployment. It doesn't contain any app source of -its own: it installs the [`@astrelitehq/localgrid`](https://github.com/AstreliteHQ/localgrid.dev/pkgs/npm/localgrid) -npm package (published to GitHub Packages on every localgrid.dev release) and -builds *that* package's own source, with the Vite base path overridden to -`/localgrid.proxy/` instead of localgrid.dev's default `/`. The base path is -baked into the built assets at build time, so this is the only difference -between the two deployments. +## Staying up to date -## How it stays up to date +localgrid.dev's release workflow dispatches a rebuild here on every new +package version. Also rebuilds on push to `main`, or manually via +`workflow_dispatch`. -localgrid.dev's release workflow sends a `repository_dispatch` event to this -repo after it publishes a new `@astrelitehq/localgrid` version, which -triggers [`pages.yml`](.github/workflows/pages.yml) here to reinstall -(picking up the new version) and redeploy. It can also be run manually from -the Actions tab (`workflow_dispatch`). +## One-time setup -## One-time manual setup +- GitHub Pages source: this repo's Settings → Pages → "GitHub Actions". +- `PACKAGES_READ_TOKEN` secret (here): a PAT with `read:packages` on + AstreliteHQ, so `npm install` can pull the package. +- `PROXY_DISPATCH_TOKEN` secret (in localgrid.dev): a PAT with `repo` + scope (or Contents: Read + Actions: Write here), used by its + `notify-proxy` job to trigger this repo's deploy. -A few things can't be done from code and need to happen once in each repo's -settings: +One fine-grained PAT scoped to both repos can back both secrets. -- **GitHub Pages source**: in this repo's Settings → Pages, set the source - to "GitHub Actions". -- **`PACKAGES_READ_TOKEN` secret** (in this repo): a personal access token - with `read:packages` scope (classic) or Packages: Read (fine-grained) on - the AstreliteHQ org, so `npm install` can pull `@astrelitehq/localgrid` - from GitHub Packages. Add it under Settings → Secrets and variables → - Actions. -- **`PROXY_DISPATCH_TOKEN` secret** (in localgrid.dev, not here): a PAT with - `repo` scope (classic) or Contents: Read + Actions: Write (fine-grained) - on this repo, so localgrid.dev's release workflow can dispatch the deploy - above. See the `notify-proxy` job in localgrid.dev's - `.github/workflows/release-please.yml`. +## Extra devDependencies -A single fine-grained PAT scoped to both repos (Packages: Read on -localgrid.dev, Contents: Read + Actions: Write on localgrid.proxy) can back -both secrets if you'd rather manage one token than two. - -## Why `vitest`, Testing Library, and `@types/spark-md5` are devDependencies here - -This repo has no tests of its own, but `package.json` still lists `vitest`, -`@testing-library/react`, `@testing-library/user-event`, -`@testing-library/jest-dom`, and `@types/spark-md5` as devDependencies. -That's a deliberate, permanent accommodation this repo makes for how it -consumes `@astrelitehq/localgrid` — not something expected to be cleaned up -once some other repo changes. - -`@astrelitehq/localgrid`'s own `build` script is `tsc -b && vite build`, -and its `tsconfig.app.json` does `"include": ["src"]` with no exclusion for -`*.test.ts(x)` files, so `tsc -b` type-checks the whole `src` tree — -including its test files and `spark-md5`-typed source — on every build. -But the npm package only ships its own `dependencies`, not the -`devDependencies` those files need type declarations for (`vitest`, -`@testing-library/*` for the tests; `@types/spark-md5` for -`HashGeneratorWidget.tsx` itself, which imports the untyped `spark-md5` -package directly). Since this repo builds `@astrelitehq/localgrid` by -running its `build` script straight out of `node_modules` (see above), that -build fails here with `TS2307: Cannot find module 'vitest'` and similar -errors unless those packages are available too. `@testing-library/dom` (a -*peer* dependency of `@testing-library/react`/`user-event`) isn't listed -explicitly — npm auto-installs declared peers by default, so it's pulled in -on its own. - -Because npm installs into one flat, hoisted `node_modules`, adding the same -packages as devDependencies *here* puts them where `tsc -b` running inside -`node_modules/@astrelitehq/localgrid` can still resolve them, without -touching localgrid.dev. Their versions should track the `devDependencies` -versions in [localgrid.dev's `package.json`](https://github.com/AstreliteHQ/localgrid.dev/blob/main/package.json) -for whichever files a given `@astrelitehq/localgrid` release ships; bump -them here if a new release needs something this list doesn't cover yet (a -build failing with another `TS2307`/`TS7016` for a `devDependency`-only -package is the signal). - -This is intentionally contained to this repo rather than "fixed" in -localgrid.dev (e.g. by excluding test files from its production `tsc` -project). That app has no reason to carry build-config complexity to serve -a consumer that rebuilds its raw source with a different Vite base path — -this repo is the one adapter-shaped place that already exists to hold -differences like that (see the base-path override above), so this is where -the accommodation belongs. +`vitest`, Testing Library, and `@types/spark-md5` are devDependencies here +even though this repo has no tests. `@astrelitehq/localgrid`'s own build +(`tsc -b`) type-checks its whole source tree, tests included, but the +published package doesn't ship its devDependencies. Listing the same ones +here lets npm's hoisted `node_modules` satisfy that type-check. Keep their +versions in sync with localgrid.dev's own `package.json`. ## Lockfile -`package-lock.json` isn't committed yet (see `.gitignore`): generating one -requires resolving `@astrelitehq/localgrid` from GitHub Packages, which -needs the same `read:packages`-scoped credentials as above. Once you have -those locally (`export NODE_AUTH_TOKEN=...` with a PAT that has -`read:packages`), run `npm install`, commit the generated -`package-lock.json`, remove it from `.gitignore`, and switch -[`pages.yml`](.github/workflows/pages.yml) from `npm install` back to -`npm ci` for reproducible installs. +Not committed yet (see `.gitignore`) — generating one needs +`read:packages` credentials to resolve `@astrelitehq/localgrid`. Once you +have one, run `npm install`, commit `package-lock.json`, and switch +`pages.yml` to `npm ci`. ## Local development ```bash export NODE_AUTH_TOKEN= -npm install # Node 24 recommended (matches @types/node below and CI); - # npm 10.9.7 (Node 22's bundled version at the time of - # writing) crashes resolving vitest's optional peer deps, - # npm 11+ (bundled with Node 24) doesn't -npm run dev # dev server, base path defaults to / -npm run build # production build at /localgrid.proxy/, output in ./dist +npm install +npm run dev # base path defaults to / +npm run build # production build at /localgrid.proxy/ ``` From 6cce1905f1a695feecce2b518edeb483da4080b0 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 09:28:03 +0000 Subject: [PATCH 5/8] docs: add AGENTS.md Carries over the applicable clauses from localgrid.dev's AGENTS.md (style rules, commit/PR policy); skips the ones specific to its widget-app source structure, which this repo doesn't have. --- AGENTS.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..30ada0e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,19 @@ +# AGENTS.md + +localgrid.proxy mirrors [localgrid.dev](https://github.com/AstreliteHQ/localgrid.dev) to GitHub Pages at a different base path. No app source here: it installs the published `@astrelitehq/localgrid` npm package and builds that. + +## Important instructions + +- No em dash (—) or en dash (–) as punctuation. Use a comma, period, or parentheses instead. +- Avoid these words and phrases: delve, leverage, seamless, seamlessly, boilerplate, furthermore, moreover, "in today's world", "it's not just X, it's Y". +- No emoji unless the user explicitly asks for them. + +## Commands + +- `npm run dev` start the dev server +- `npm run build` build with this repo's base path, output in `dist/` + +## Commit and pull request + +- Use conventional commit message pattern +- Do not commit or open pull requests without explicit instruction From 9a62267355e00013bff1f6ca3863456b65614f1c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 09:30:06 +0000 Subject: [PATCH 6/8] ci: build on every push, all branches New ci.yml runs `npm run build` (no deploy) on push to any branch, so a broken build shows up before merging to main rather than at the next pages.yml deploy. --- .github/workflows/ci.yml | 32 ++++++++++++++++++++++++++++++++ README.md | 3 ++- 2 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..e02a930 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,32 @@ +name: Build + +# Validates the build on every push, any branch. Deploying to Pages (main +# only) is pages.yml's job, not this one. +on: + push: + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + packages: read # lets GITHUB_TOKEN read @astrelitehq/localgrid below + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 + with: + node-version: '24' + + - name: Install dependencies + run: npm install + env: + NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Build + run: npm run build diff --git a/README.md b/README.md index 415cfd7..91133c8 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,8 @@ path baked in. localgrid.dev's release workflow dispatches a rebuild here on every new package version. Also rebuilds on push to `main`, or manually via -`workflow_dispatch`. +`workflow_dispatch`. `ci.yml` builds (not deploys) on every push, any +branch, to catch a broken build before it reaches `main`. ## One-time setup From d5cab25cd3def47e8498be90286d8867b16c4ebc Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 09:31:58 +0000 Subject: [PATCH 7/8] docs: remove stale one-time setup section PACKAGES_READ_TOKEN isn't used; pages.yml and ci.yml both authenticate with the default GITHUB_TOKEN, granted access via the package's own Actions access settings. --- README.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/README.md b/README.md index 91133c8..71fbb16 100644 --- a/README.md +++ b/README.md @@ -14,17 +14,6 @@ package version. Also rebuilds on push to `main`, or manually via `workflow_dispatch`. `ci.yml` builds (not deploys) on every push, any branch, to catch a broken build before it reaches `main`. -## One-time setup - -- GitHub Pages source: this repo's Settings → Pages → "GitHub Actions". -- `PACKAGES_READ_TOKEN` secret (here): a PAT with `read:packages` on - AstreliteHQ, so `npm install` can pull the package. -- `PROXY_DISPATCH_TOKEN` secret (in localgrid.dev): a PAT with `repo` - scope (or Contents: Read + Actions: Write here), used by its - `notify-proxy` job to trigger this repo's deploy. - -One fine-grained PAT scoped to both repos can back both secrets. - ## Extra devDependencies `vitest`, Testing Library, and `@types/spark-md5` are devDependencies here From 8c9509288cf2bb38dfb38c7772061ec996d75471 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 12 Sep 2026 09:33:00 +0000 Subject: [PATCH 8/8] docs: drop em dash in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 71fbb16..85f9b40 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ versions in sync with localgrid.dev's own `package.json`. ## Lockfile -Not committed yet (see `.gitignore`) — generating one needs +Not committed yet (see `.gitignore`); generating one needs `read:packages` credentials to resolve `@astrelitehq/localgrid`. Once you have one, run `npm install`, commit `package-lock.json`, and switch `pages.yml` to `npm ci`.