#typescript/src/infra

#typescript/src/infra

Infrastructure env vars: location roots, handshake signals, and the RelativeToRoot path marker, the three declared-infrastructure primitives. Mirrors Go WithInfraRoot/WithHandshakeEnv/RelativeToRoot (strictcli.go) with Python's infra_root/handshake_env as the divergence ground truth.

Roots are resolved EAGERLY at app construction: the env var's value if set, else the declared default, with a leading ~ expanded. Resolution has no argv dependency, which is exactly why roots are hermetic-immune -- --hermetic only suppresses argv-derived config/env behavior. Handshake vars are never captured; they are read LIVE from the environment at ctx.infraValue() time.

#InfraRootPath

export interface InfraRootPath

Opaque marker for a filesystem path built from a declared infrastructure root (identified by its env var name) joined with zero or more path parts. Built exclusively via the relativeToRoot() factory (branded like Outcome -- hand-forged objects are never recognized as markers). Accepted as a flag default: (resolved when defaults are applied at parse time; source label "infra") and as the config path (resolved eagerly at construction). A marker referencing an undeclared root is a registration-time hard error.

#relativeToRoot

export function relativeToRoot(

Builds a marker representing a path relative to a declared infrastructure root. envVar names the root (declared via createApp's infraRoot); parts are joined onto the resolved root path.

#isInfraRootPath

export function isInfraRootPath(v: unknown): v is InfraRootPath

#expandTilde

export function expandTilde(p: string): string

Expands a leading ~ (as ~ or ~/...) to the user's home directory.

#resolveInfraRootPath

export function resolveInfraRootPath(

Resolves a marker against the resolved roots map (env var -> path). Throws a plain Error (message from the catalog) when the marker references an undeclared root -- callers wrap it per context (registration validation throws RegistrationError first, so parse-time resolution cannot fail).

#validateFlagInfraMarker

export function validateFlagInfraMarker(

Registration-time hard error for a flag whose default is a marker referencing an undeclared root. cmdName selects the command-scoped message (Python's _build_and_validate_command form); global flags use the flag-scoped message both siblings share.

#buildInfraAccess

export function buildInfraAccess(

Snapshots an app's infra data for a Context (Go infraAccess): resolved root values, the set of declared handshake vars, and the set of declared connection vars (suppressed when hermetic is true). Null when nothing is declared, so ctx.infraValue() throws the not-declared error for everything.