HarperFast / HarperFast/harper

Root harper-config env: block (instance-wide literals, enc: envelopes, and store declarations)

Open
#1,589 0 comments 0 reactions 1 assignee Claimed by @heskew View on GitHub
area:components enhancement
Dominant language
JavaScript
Stars
89
Forks
10
Avg merge
2d 6h
Merged PRs (30d)
200

Description

Follow-up to #1550 / PR #1582, from the P1b design decision.

## Problem

PR #1582 introduced the `env:` config block — string = inline literal (including `enc:` envelopes), object = declaration resolved against the secrets store with load-gating — but only at the **component** config level. There is no equivalent at the root harper config (`harper-config.yaml`), so instance-wide environment values (e.g. `NODE_ENV`, shared API endpoints, an `enc:` value every component needs) must either be duplicated into every component's `env:` block or set out-of-band in the container/host environment.

## Proposal

Support the same `env:` block at the root of harper config:

- Same semantics as the component-level block: string values are literals (including `enc:` envelopes decrypted via the registered secret decryptor), object values are declarations resolved from `hdb_secret`.
- Root-level values materialize into the real `process.env` at boot, before component loading — they are instance-wide by definition, so the global tier is the only sensible target (no scoped-accessor tier at root).
- Precedence: real environment (container/host) > root `env:` > component `env:` literals — matching the existing "already-set process.env wins" rule in `componentSecrets.ts`.
- Load-gating on required root declarations should fail the boot (or degrade per the existing gate-reason machinery) rather than start with missing instance-critical values.

## Acceptance

- Root `env:` block parsed and materialized before component load, with literal + `enc:` + declaration forms covered by tests.
- Precedence rules pinned by tests.
- `get_components`-style visibility for unsatisfied root declarations (or documented equivalent surface).

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.