Upgrade Harper to v5

[BboyAkers]

Summary

• Dependency bump: adds harper@^5.0.28 and @harperfast/integration-testing@^0.4.0 as devDependencies; removed stale js-yaml-only lockfile. The app code uses Harper as a runtime-provided global (no harperdb import in source) so no import swap was needed.
• v5 migration: resources.js is already v5-compatible — the source get(path) does not use this.request, there is no blob.save() call, no wasLoadedFromSource(), and no delete() on the cache table. Code reviewed against all v5 migration checklist items; none required.
• Integration tests: integrationTests/page-cache.test.ts added covering: Harper startup, origin HTML fetch, text/html content-type assertion, cache-hit idempotency (same body on second read), and ETag/304 conditional-request test with async-commit polling (per v5 caching contract — validators appear on HITs, not the priming MISS).
• harperBinPath fix: applied in test setup to work around ERR_PACKAGE_PATH_NOT_EXPORTED from harper's restricted exports map.
• CI: .github/workflows/integration-tests.yml added with Node 22/24/26 matrix and actions pinned to commit hashes.
• Lockfile: regenerated with --os=linux --cpu=x64 --include=optional; confirmed bufferutil, utf-8-validate, and node-gyp-build are recorded.
• Branding: HarperDB → Harper throughout README; install command updated to npm i -g harper; dev command updated to harper dev .; GitHub repo link updated to HarperFast/application-template.
• Scripts: added start, dev, and test:integration to package.json.
• tsconfig.json: added for integration test type-checking (ESM + NodeNext, strict, noEmit).

Migration items — N/A

Item	Reason N/A
from 'harperdb' import swap	No imports — Harper is a runtime-provided global
Table.get() return shape / wasLoadedFromSource()	Not used in this repo
blob.save() removal	Already uses createBlob() without .save()
Record immutability (frozen records)	No record mutation
Transaction/context changes	Not used
Process spawning restrictions	Not used
VM module loading	N/A (no problematic named ESM imports found)
delete() → invalidate() on cache table	delete() is not called anywhere

Test results

LOCAL: blocked by loopback EADDRNOTAVAIL (macOS — environmental, not a code bug). CI is the gate.

Known issues / flags

• npm scope: The package is currently scoped as full-page-caching (no npm scope). If this should be published under the Harper npm scope, that change requires manual decision — flagged for the team per master plan §11.1.
• The origin fetch in tests hits https://www.harperdb.io/ — requires outbound network access from CI (standard on ubuntu-latest).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates the repository to use the new Harper branding, adds integration tests for the page caching component, and configures TypeScript and package scripts. Feedback on the changes suggests refactoring the fetchUntilCached test helper to avoid returning a disturbed response object, polling before asserting cache hits to account for asynchronous cache commits, and upgrading the TypeScript dependency in package.json to at least ^5.5.0 to support the erasableSyntaxOnly compiler option.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[BboyAkers]

Review finding: resources.js caches origin error responses as HTTP 200 (pre-existing bug, exposed by new tests)

resources.js line 18-28 — the get(path) source function fetches from the origin and stores the result unconditionally:

const response = await fetch(new URL(path, origin));
const blob = await createBlob((await response.body));
return { path, pageContents: blob };

If the origin returns a 404, 500, or any other error status, the error-page HTML is stored as pageContents and Harper serves subsequent requests with a 200 response — silently poisoning the cache entry for the full 3600-second TTL.

This bug is not changed by this PR (it pre-exists on main), but the integration tests added here do not catch it — a test that sends a request to a path that currently returns 404 on harperdb.io would still pass all the assertions. Consider adding a guard in resources.js:

if (!response.ok) {
  throw new Error(`Origin returned ${response.status} for path: ${path}`);
}

And consider adding a test case that verifies a non-200 origin response is NOT cached (i.e., a follow-up request still fetches fresh from origin rather than serving a cached error page).

[BboyAkers]

Review follow-up (autonomous agent): Fixed all 4 blocking findings: origin error responses no longer cached as 200s (resources.js), fetchUntilCached timeout now skips cleanly instead of triggering a misleading assertion, body equality check is no longer racy (uses fetchUntilCached to wait for cache commit), and 504 added to status allowlist at all three guard sites in the integration tests.