Upgrade Harper to v5

[BboyAkers]

Upgrade Harper to v5

Completes the v4 → v5 upgrade for this Solid SSR + Harper caching example. Resumes the existing branch (no clobber/duplicate); the prior commits had swapped the dependency and (incorrectly) converted resources to static methods, and this work finalizes the migration, fixes a caching-source correctness bug, adds integration tests + CI, and merges main.

⚠️ Caching-source correctness fix

A prior migration commit mechanically converted the resource handlers to static async get(target). In Harper v5, a sourcedFrom source is resolved per-id by instantiating the source resource and calling its INSTANCE get(query) — a static get() is never invoked (this matches harper's own SimpleCacheSource reference and the react-ssr-example pattern). As a result the PageBuilder source never ran: BlogCache stored the raw Post record instead of rendered HTML, CachedBlog's cached.content was undefined, and GET /CachedBlog/:id served an empty 200 body. The earlier test only checked the BlogCache table directly, so it stayed green.

Fix: convert PageBuilder, UncachedBlog, and CachedBlog to instance async get(query) calling await super.get(query) (preserving solid's async renderPost + generateHydrationScript and the { contentType, data } shape on CachedBlog). The integration test was strengthened to fail on the pre-fix bug: GET /CachedBlog/0 must now return 200 with a non-empty text/html body containing the rendered markers (__INITIAL_POST_DATA__ + the post title), plus a 304 conditional-hit and a source-update→invalidate→re-cache flow driven through /CachedBlog (asserting the re-render reflects the mutated Post). Verified the strengthened test fails on the pre-fix static-get code and passes after the fix; CI green on Node 22/24/26.

Dependency

• harper ^5.0.11 → ^5.0.28
• Added dev deps: @harperfast/integration-testing@^0.4.0, typescript@^6.0.3
• Merged main (picked up version field + postinstall: npm run build for npm-pack / deploy_component compatibility) and resolved the package.json conflict.

Migration items applied

• Package/import rename harperdb → harper (resources.js: import { tables } from 'harper'). ✅
• Caching-source resolution — cache source (PageBuilder) and the SSR resources (UncachedBlog, CachedBlog) use instance async get(query) with await super.get(query), as v5 requires for sourcedFrom sources. ✅ (corrected from the prior static-method commit — see fix above)
• Records returned as plain objects — no in-place record mutation; all updates send new objects. ✅

Migration items N/A

• Frozen/immutable records — app never mutates a fetched record in place. N/A.
• Transaction/context (getContext().transaction.commit) — no cross-call transaction polling. N/A.
• Child-process spawning (allowedSpawnCommands) — app spawns nothing. N/A.
• Blob storage (blob.save → saveBeforeCommit) — no blobs. N/A.
• wasLoadedFromSource → loadedFromSource — not used. N/A.
• Install-script blocking / VM module loader — no install scripts; default loader works (CI green). N/A.

Tests (integrationTests/solid-ssr.test.ts, node:test + ESM/TS)

Runs against a real ephemeral Harper instance. The suite builds the Vite SSR output and assembles a clean component fixture (config + resources + schema + dist/ + a minimal solid-js runtime dependency set, since resources.js imports solid-js/web at runtime), pre-installed via setupHarperWithFixture. Coverage:

• SSR render path — Post seed + REST GET; UncachedBlog server-side-renders the Solid app to HTML (title, body, hydration data); CachedBlog renders SSR HTML into the cache and serves byte-identical cached bytes for an unchanged Post — asserting a non-empty text/html body with __INITIAL_POST_DATA__ + title (regression guard for the static-get bug).
• Harper caching — BlogCache cache table (sourcedFrom PageBuilder, expiration: 3600) serves a conditional-request 304 cache hit; the same 304 hit is also asserted through /CachedBlog; updating the source Post (REST PATCH) invalidates the cached /CachedBlog render (200 with fresh HTML reflecting the new comment) and then re-caches (304 once settled).
• REST — Post GET/PATCH.

Applied the mandatory harperBinPath harness fix (harper's exports only exposes ., so harper/dist/bin/harper.js is not resolvable) — resolve the CLI from the package main and pass { harperBinPath }.

Local: blocked by the macOS loopback bind (EADDRNOTAVAIL on 127.0.0.2+; environmental, not a code/v5 bug — even --isolation=none validates a pool address).
CI (ubuntu): ✅ all green on Node 22 / 24 / 26 — https://github.com/HarperFast/solid-ssr-example/actions/runs/27149436373

CI

Added .github/workflows/integration-tests.yml (repo root) — Node matrix [22, 24, 26], actions pinned to commit hashes; pretest:integration builds before tests; uploads Harper logs on failure.

Notes / observed v5 behavior

• With the instance-get() fix, CachedBlog reads through BlogCache and does participate in Harper's conditional-request handling: /CachedBlog/0 returns a 304 cache hit on a matching If-None-Match/If-Modified-Since, and invalidates → re-caches when the source Post changes. (The earlier note claiming /CachedBlog always returned 200 reflected the broken static-get state and no longer applies.)
• Lockfile: package-lock.json already includes harper's optional native deps (bufferutil, utf-8-validate, node-gyp-build), so npm ci succeeds across the full Node 22/24/26 matrix; no regeneration needed for this fix.

Manual / human items

• npm scope: @harperdb/code-guidelines (devDep) is on the legacy @harperdb scope. Per policy, npm-scope moves are manual — flagged, not changed here.

🤖 Generated with Claude Code