Upgrade Harper to v5

[BboyAkers]

Upgrade Harper v4 → v5 (resume of existing PR)

This PR completes the v4→v5 upgrade for the Svelte SSR + multi-tier caching example. Earlier commits on this branch already swapped the dependency and migrated most of resources.js; this update adds the testing/CI/branding work, fixes a cross-platform lockfile issue so CI can run, and fixes a remaining cached-resource response bug that integration tests surfaced.

Migration items applied

• Package/import swap — harper (was harperdb); import { tables } from 'harper' in resources.js. The harperdb runtime global / import is fully removed. (Done in earlier branch commits.)
• Resource methods → static — UncachedBlog, PageBuilder, and CachedBlog were converted from instance async get() (using this) to static async get(target) that fetch the record via tables.Post.get(target) / tables.BlogCache.get(target). Required because v5 Table.get() returns a plain record object, not a Resource instance. (Done in earlier branch commits.)
• Response shape (v4 { contentType, data } → v5) — the v4 response descriptor { contentType, data } was migrated to the v5 { status, headers, body } shape.
• Cached-resource response shape (fixed in this PR — found by tests) — the prior commits put the { status, headers, body } descriptor on CachedBlog.get (the cache resource). In v5 that descriptor is not honored on a cache resource: Harper serialized it verbatim, so GET /CachedBlog/0 returned the JSON {"status":200,"headers":{}} instead of HTML on the cache-fill request. The correct v5 contract (per Harper's caching layer) is for the source to return the response descriptor: PageBuilder.get now returns { status: 200, headers: { 'Content-Type': 'text/html' }, body: html }, which Harper parses, stores in BlogCache with its content type, and serves on cache hits. CachedBlog no longer overrides get() — Harper serves the cached HTML record and handles ETag/304 revalidation. (UncachedBlog, which extends a plain table rather than a cache, keeps the { status, headers, body } descriptor and is unaffected.)

Migration items N/A (and why)

• Frozen/immutable records — the app already builds new objects ({ ...currentPost, comments: [...] }) and never mutates records in place. No change needed.
• wasLoadedFromSource() / RequestTarget.loadedFromSource — not used; caching is wired via BlogCache.sourcedFrom(PageBuilder) + @table(expiration: 3600). N/A.
• Transaction/context commit semantics — no manual transaction polling/commits in the app. N/A.
• Child-process spawning (allowedSpawnCommands, named spawn) — the app spawns no child processes. N/A.
• Blob storage (blob.save → saveBeforeCommit) — no blob usage. N/A.
• Install scripts (allowInstallScripts) — no install scripts required. N/A.
• VM module loader config — default vm loader works; no override needed. N/A.

Tests added

integrationTests/app.test.ts (node:test + @harperfast/integration-testing), 5 tests covering:

• REST / core DB — seeded Post/0 is served with the right fields; GET /Post/ returns an array; PATCH /Post/0 persists a write.
• Cached SSR path — GET /CachedBlog/0 (against a pristine cache) returns text/html with the full SSR document: the rendered post, the window.__INITIAL_POST_DATA__ hydration bootstrap, and the #app mount node.
• Uncached SSR path — GET /UncachedBlog/0 returns the same full text/html SSR document.
• REST write + live re-render — after PATCH /Post/0, the write is persisted and UncachedBlog (which renders live from the Post) reflects the new comment.

These behaviors were verified locally against a real Harper instance (bound to 127.0.0.1 to work around the macOS loopback-pool limitation) — all 5 pass — in addition to the CI runs below.

Applied the documented harperBinPath harness fix (the harper package's exports only exposes ".", so the harness's auto-resolution of harper/dist/bin/harper.js throws ERR_PACKAGE_PATH_NOT_EXPORTED). Added tsconfig.json, @types/node, typescript, and a test:integration script. Because resources.js reads dist/client/index.html and imports dist/server/entry-server.js at module load, a Vite build must precede the tests — wired as pretest:integration locally and as an explicit build step in CI.

Test results

• CI (ubuntu-latest): all green on Node 22, 24, and 26. Run: https://github.com/HarperFast/svelte-ssr-example/actions/runs/27037304046
• Local (macOS): the default harper-integration-test-run harness binds Harper to loopback aliases 127.0.0.2+, which are not configured on this macOS host (EADDRNOTAVAIL / LoopbackAddressValidationError) — an environment limitation, not a code bug. To validate locally anyway, the suite was run against a real Harper instance pinned to 127.0.0.1 (bypassing the loopback pool); all 5 tests pass. CI on ubuntu, where the full 127.0.0.0/8 range is available, is the authoritative gate and is green.

Known v5 issue found (flagged for the team — not blocking)

The cached SSR endpoint has a real v5 behavioral gap that the upgrade surfaced: a fresh CachedBlog read correctly serves the SSR'd text/html page, and UncachedBlog correctly re-renders live, but after the source Post is mutated, the re-sourced BlogCache entry serves the raw Post record as JSON instead of re-rendering the HTML page through PageBuilder. This was confirmed locally across multiple resource designs:

• Source returns { content } + CachedBlog.get returns cached.content: cache headers/304 work, but the cache-fill response is JSON-wrapped, and after invalidation the resource returns undefined → 404.
• Source returns { status, headers, body } (the shipped design): fresh reads are correct text/html, but post-invalidation reads return the raw Post JSON record.
  Neither variant gives correct re-render-after-invalidation in this Harper build (5.0.28). The shipped design was chosen because it makes the demo's primary documented behavior — "the pages are server side rendered" — correct on fresh reads. The cache-invalidation re-render and the ETag/Last-Modified 304 conditional-request flow that the repo's caching-test.js exercises do not hold as-is on v5 and need a maintainer/upstream decision (e.g. a different cached-resource pattern, or a Harper fix). The integration tests deliberately assert only the deterministically-correct behaviors and do not assert the broken invalidation path.

CI

Added .github/workflows/integration-tests.yml at the repo root: Node matrix [22, 24, 26], actions pinned to commit hashes (actions/checkout v6.0.3, actions/setup-node v6.4.0, actions/upload-artifact v7.0.1), build step before tests, and Harper log artifact upload on failure.

Lockfile fix

The previously committed package-lock.json (written by an older npm) omitted harper's optionalDependencies bufferutil and utf-8-validate, so npm ci failed on the Linux runners ("Missing from lock file"). Regenerated the lockfile with npm 11 so these resolve cross-platform and npm ci is in sync. No application dependencies were changed.

Branding

HarperDB → Harper in README.md prose, the harperdb run . command (now harper run .), and the index.html <title>. Live URLs (e.g. docs.harperdb.io, the YouTube link) were left intact.

Known issues / flags for a human

• Harness escape hatch (upstream): harper should export its bin path, or @harperfast/integration-testing should resolve the CLI from the package root instead of the blocked deep subpath harper/dist/bin/harper.js.
• npm scope (manual): the repo still depends on @harperdb/code-guidelines@^0.0.1 (dev tooling, used by prettier.config.js). If this should move to the current Harper npm scope, that is a manual decision left for a human — not changed here.

🤖 Generated with Claude Code

[BboyAkers]

Fragile Content-Type assertion — strictEqual(res.headers.get('Content-Type'), 'text/html') will fail if Harper ever adds a charset parameter (e.g. text/html; charset=utf-8). The vue-ssr and react-ssr sibling repos use the same pattern, but at least one of them already switched to ok(...startsWith('text/html')) which is more robust. Consider:

Suggested change

	strictEqual(res.headers.get('Content-Type'), 'text/html');
	ok(res.headers.get('Content-Type')?.startsWith('text/html'), 'expected text/html content type');

[BboyAkers]

Same fragile Content-Type strict equality check as on line 63 — will break if Harper adds ; charset=utf-8. Prefer ok(...?.startsWith('text/html')).

Suggested change

	strictEqual(res.headers.get('Content-Type'), 'text/html');
	ok(res.headers.get('Content-Type')?.startsWith('text/html'), 'expected text/html content type');

[BboyAkers]

Missing null check — renders garbage on unknown ID — tables.Post.get(target) returns null when no record exists for the requested ID. renderPost(null) proceeds to call serverEntry.render({ initialPostData: null }) and inserts window.__INITIAL_POST_DATA__ = null into the page, returning HTTP 200 with a broken render instead of a 404. The old instance-method API handled missing records automatically; the static API requires an explicit check. PageBuilder.get on line 41 has the same gap.

[BboyAkers]

Same missing null guard as UncachedBlog.get — if a BlogCache source fill is triggered for a non-existent Post ID, tables.Post.get(target) returns null and renderPost(null) stores a broken HTML page in the cache. Subsequent cache hits would then serve the corrupted entry for that ID. Add an early if (!post) return { status: 404, body: 'Not Found' } guard here as well.

[BboyAkers]

Duplicated get() logic — UncachedBlog.static get(target) and PageBuilder.static get(target) now have identical bodies (fetch Post, return HTTP 200 text/html response). The only reason PageBuilder exists is as a cache source. Consider having PageBuilder extend UncachedBlog to remove the duplication, or extract the shared logic into a single function and call it from both.

[BboyAkers]

Fragile bin path resolution — resolve(dirname(require.resolve('harper')), 'bin/harper.js') derives the CLI path from the package main entry's directory. This is a necessary workaround (well-documented) given harper's exports map, but it will silently break if harper ever moves its main entry deeper in the package (e.g. from index.js to dist/index.js). Tracking issue: this same workaround is copy-pasted into vue-ssr-example and react-ssr-example; ideally it lives once in @harperfast/integration-testing so all consumers benefit from fixes.

[BboyAkers]

Known v5.0.x cache-invalidation bug has no skip/todo test — the NOTE here documents that after a Post mutation, the re-sourced BlogCache entry serves the raw Post record rather than a re-rendered page. The integration test suite covers only the first-fill path and has no test for the post-mutation re-render path (even a test.todo would make the gap visible in CI output and prevent accidentally shipping a fix that goes untested). Consider adding:

// TODO: Re-enable once Harper v5 re-render-after-invalidation is fixed (#XX)
test.todo('CachedBlog re-renders after Post mutation');

[BboyAkers]

Review follow-up (autonomous agent): Fixed blocking findings: added explicit if (!post) return { status: 404, body: 'Not Found' } guards in both UncachedBlog.get and PageBuilder.get (resources.js lines 32 and 43) so unknown Post IDs return 404 instead of rendering broken HTML or poisoning BlogCache.