03 Custom Resource v5 Upgrades

[BboyAkers]

Summary

Completes the Harper v4 -> v5 upgrade for the 03-custom-resource tutorial step of the "Create Your First Application" Learn guide.

This guide repo has one progressive app captured across step branches (01-create-table -> 02-rest-api -> 03-custom-resource -> 04-logger). This PR upgrades the 03-custom-resource step (base branch: 03-custom-resource). The sibling PR #2 upgrades the next step (04-logger); see "Two-PR structure" below.

Changes

• Dependency: harper ^5.0.11 -> ^5.0.28; @harperfast/integration-testing ^0.3.1 -> ^0.4.0.
• Migration (item Difference with https://github.com/harperfast/application-template/ #1, import/package rename): resources.js imports { tables } from harper and drops the v4-only static loadAsInstance = false. (Applied in the original commit; confirmed correct.)
• Tests: integrationTests/dog.test.ts covers Dog REST CRUD (PUT/GET/PUT-update/DELETE/404) and the DogWithHumanAge custom resource (humanAge for ages 1/2/3). Added the mandatory harperBinPath escape hatch so the harness resolves the CLI past harper's restricted exports map.
• Test script: standardized to test:integration (harper-integration-test-run "integrationTests/**/*.test.ts"), matching the CI workflow.
• CI: added .github/workflows/integration-tests.yml (Node 22/24/26; actions pinned to commit hashes).
• TypeScript: added typescript devDependency for tsconfig.json / editor support.
• Branding: package.json author "HarperDB Inc." -> "Harper Inc.". Live docs.harperdb.io URLs left intact.

Migration items N/A

This is a minimal tutorial app (a single custom resource that reads via super.get(target) and returns a fresh spread object). The following v5 changes do not apply: Table.get() return shape (#2), frozen/immutable records (#3 — already returns a new object), implicit transaction context (#4), child-process spawn allowlist (#5), blob storage (#6), install scripts (#7), VM module loader config (#8).

Tests

• Local: blocked at the macOS loopback bind (EADDRNOTAVAIL on 127.0.0.2+) — environmental, not a code issue. The harperBinPath fix is confirmed working: the run progresses past CLI resolution to the loopback-pool stage before failing.
• CI: runs on ubuntu-latest, which supports the full 127.0.0.0/8 range and needs no loopback aliasing. This is the authoritative test gate for this PR.

Known issue (upstream, flagged)

The harper package's exports map only exposes ".", so the harness's default require.resolve('harper/dist/bin/harper.js') throws ERR_PACKAGE_PATH_NOT_EXPORTED (harper 5.0.11–5.0.28, integration-testing 0.3.1–0.4.0). Worked around via the documented harperBinPath option. Upstream fix: harper should export its bin path, or the harness should resolve via the package root.

Two-PR structure

• PR 03 Custom Resource v5 Upgrades #3 (this one) -> base 03-custom-resource: fully completed (deps, migration, tests, CI, branding).
• PR 04 Logger v5 Upgrades #2 -> base 04-logger: upgrades the next tutorial step (adds logger + console.log). It applies the same import/rename migration but has no integration tests, no tsconfig, no CI, and still pins harper@^5.0.11. Recommend mirroring this PR onto 04 Logger v5 Upgrades #2 (bump versions, add a test asserting the logger path still returns correct data, add the same CI workflow, harperBinPath fix). Not changed here to avoid clobbering that PR.

Manual follow-up

• npm scope: if this package should move to the current Harper npm scope, that is a manual decision for a maintainer (out of scope for this automated upgrade).

🤖 Generated with Claude Code

[BboyAkers]

Review follow-up (autonomous agent): Fixed all 4 blocking findings: added 03-custom-resource to push branches filter, asserted setup PUT succeeds in DELETE test, added status check before getRes.json() in update test, and added round-trip GET after PUT in creates test to verify persistence.