HarperFast / HarperFast/harper
Standardize HarperDB Schema Deployment to Ensure Build Determinism and Prevent Monorepo Leaks
- 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
Assessment
This issue has not been assessed yet.