initial commit for v5 harper upgrade

[BboyAkers]

Harper v4 -> v5 upgrade (Getting-Started-PubSub)

Completes the in-progress v5 upgrade on this branch. The Harper app lives in harper/ and is schema-only (tables Sensors and Topics exported over REST + MQTT/WS/SSE); there is no app JS, so there was no harperdb import/global footprint to migrate — the v4->v5 work is the dependency/CLI swap plus tooling.

Changes

• Dependency: harper 5.0.11 -> 5.0.28 (latest). CLI scripts already swapped harperdb -> harper (run/dev/deploy) in the prior commits on this branch.
• Integration tests (harper/integrationTests/) using @harperfast/integration-testing, covering the pub/sub paths:
  • mqtt.test.ts — MQTT subscriber receives a message published to Sensors/{id}; MQTT publish is persisted and readable over REST.
  • rest.test.ts — REST table-export backbone: PUT/GET a Sensors record and a Topics message.
  • A minimal component fixture (integrationTests/fixture/) holds only config.yaml + schema.graphql + package.json so the harness pre-installs the component without copying node_modules.
  • harperBinPath is resolved from the harper package main entry — harper's exports map only exposes ".", so harper/dist/bin/harper.js is not directly resolvable (documented harness escape hatch).
• CI: .github/workflows/integration-tests.yml at repo root. Node matrix [22, 24, 26], actions pinned to commit hashes, working-directory: harper, cache-dependency-path: harper/package-lock.json.
• Lockfile: committed harper/package-lock.json (the root .gitignore was ignoring it; added a negation) so npm ci is reproducible. Regenerated cleanly — includes ws native optional deps (bufferutil/utf-8-validate/node-gyp-build) so npm ci passes on Node 24/26, not just 22. All resolved URLs point at the public registry (no file:/.tgz).
• TypeScript: pinned typescript to 5.9.3 (latest 6.x violates the >=4.8.4 <6.0.0 peer range required by the @harperdb/code-guidelines eslint toolchain). Added a base tsconfig.json and a small eslint override so typed linting resolves the project's tsconfig (the shared config hardcodes project: './tsconfig.json' relative to its own package dir).
• Branding: HarperDB -> Harper in harper/README.md prose; fixed the stale v4 install command (npm install -g harperdb -> harper). Left @harperdb/code-guidelines and live docs.harperdb.io / github.com/HarperDB URLs intact.

Migration items

• Import/global swap, Table.get() shape, frozen records, transaction/context, blob.save(), child-process spawning, install scripts, module-loader config: N/A — this is a schema-only component with no application JS/DB code.

Tests

• npm run test:integration — 4/4 pass locally when run with --isolation=none (binds 127.0.0.1).
• The default pooled run fails on this macOS dev box at the loopback bind (EADDRNOTAVAIL for 127.0.0.2+) because the machine has no loopback aliases configured — this is environmental, not a code issue. CI runs on ubuntu-latest, which supports the full 127.0.0.0/8 range, so the pooled run works there. Relying on the CI run for the pooled-mode test gate.

Flagged for a human

• npm scope: package name is harper-mqtt-getting-started (unscoped). If it should move to the current Harper npm scope, that's a manual decision — not done here.

🤖 Generated with Claude Code

[BboyAkers]

Review follow-up (autonomous agent): Fixed blocking findings: corrected stale Sensors/101 references in the MQTT test — updated the test name (line 44) and the file-level doc-comment (line 5) to match the Sensors/102 topic actually used in the test body.