HarperFast / HarperFast/harper

Standardize HarperDB Schema Deployment to Ensure Build Determinism and Prevent Monorepo Leaks

Open
#419 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

### Feature Summary
Shift the HarperDB schema (`packages/harper-dummy`) deployment from a "Ship and Install" model to a "Bundle and Ship" model. This involves introducing a bundling step (e.g., esbuild, tsup) or leveraging `turbo prune` to produce a fully self-contained artifact, eliminating runtime `npm install` on the HarperDB engine and preventing monorepo workspace package boundary leaks.

### Problem This Solves
The current `build-pack-deploy-dummy.mjs` script for the `packages/harper-dummy` schema packages raw source code and its `package.json`, then ships it to the target HarperDB engine, which runs `npm install --production` at deployment time. This architecture introduces two critical vulnerabilities:

**1. Monorepo Boundary Leaks:** If a developer adds an internal Turborepo workspace package (e.g., `@repo/logger-dummy`) to the schema's dependencies, the CI build passes locally, but the production deployment hard-crashes with a `404 Not Found` error because the engine attempts to fetch the private workspace package from the global NPM registry.

**2. Non-Deterministic Builds:** Forcing the destination server to resolve and download dependencies at runtime risks deployment failures due to transient NPM registry outages, unexpected sub-dependency updates, or network firewall restrictions.

**Impact:**
* **Deployment Reliability:** High risk of random pipeline failures during the physical deployment phase.
* **Developer Experience:** Silent boundary leaks where code works locally but crashes the engine during component unpacking.

### Proposed Solution
Implement one of the following approaches to achieve a fully self-contained deployment artifact:

**Option A — Introduce a Bundling Step:** Add a bundler (esbuild, tsup, or Turbopack) to the `packages/harper-dummy` build process. The bundler crawls the codebase, resolves all internal workspace packages (e.g., `@repo/logger-dummy`) and external NPM dependencies, and compiles them into a single, flat, self-contained JavaScript artifact.

**Option B — Leverage Turbo Prune:** Use `turbo prune` to physically isolate the schema workspace and its dependency tree into a standalone, self-contained payload — similar to how the Next.js-dummy web application is currently handled in the monorepo.

**Regardless of approach:**
* The final tarball shipped to HarperDB must be fully self-contained.
* Runtime `npm install` execution by the HarperDB engine upon receipt must be completely disabled/eliminated.
* The solution should be integrated into the existing CI/CD pipeline without requiring manual steps.

### User Stories
No response

### Alternatives Considered
No response

### Priority/Impact
None

### Examples or References
No response

### Additional Context
This architectural flaw was uncovered during the migration to Harper v5, where the deployment of the schema component consistently failed natively inside the Harper engine due to a local workspace dependency (`@repo/logger-dummy`) resolution error. The engine attempted to fetch `@repo/logger-dummy` from the public NPM registry, which resulted in a `404 Not Found` crash during component unpacking.

### Are you planning to fix this issue?
No, just reporting the issue

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.