Add env and env_file support to machine configuration

[tuler]

Motivation

Environment variables are typically used to differentiate between multiple build or test scenarios. One classic examples are testnet vs devnet vs mainnet, but there may be other scenarios.

Currently the build process only supports environment variables defined inside the Dockerfile used by the cartesi build process. But the same variables defined in the Dockerfile may be necessary outside the cartesi build process. For example in a host build process that is not related to the cartesi build process at all. So in this case there is a duplication of environment variables values, which hurts maintenance.

By having .env files support we can maintain a single source of truth for environment variables and use it in both the cartesi build workflow and other workflows.

Summary

This PR adds support for injecting environment variables into the Cartesi Machine through two new configuration options in the [machine] section of cartesi.toml: an env table for inline key/value pairs and an env_file option pointing to a .env file.

Key Changes

• New configuration options: Added env (Record<string, string>) and envFile (optional string) to MachineConfig
• TOML parsing: Implemented parseStringRecord() to parse TOML tables into environment variable records, with automatic coercion of non-string scalar values (numbers, booleans) to strings
• .env file parsing: Added parseEnvFile() function that parses .env files with support for:
  • Blank lines and # comments
  • Optional export prefix
  • Single/double quoted values
  • Whitespace trimming
  • Preservation of = signs in values
• Environment variable precedence: Updated bootMachine() to merge environment variables with proper precedence (lowest to highest):
  1. Docker image ENV (when use_docker_env is enabled)
  2. Variables from env_file
  3. Variables from the env table
• Error handling: Added InvalidEnvError exception class for invalid env configurations
• Comprehensive tests: Added unit tests covering all parsing scenarios and edge cases

Implementation Details

• Environment variables are merged into a single map before being passed to cartesi-machine, allowing later sources to override earlier ones
• The .env file parser is robust and handles common .env file formats
• Non-string values in the env table are automatically converted to strings since environment variables are always strings
• The implementation maintains backward compatibility with existing configurations

https://claude.ai/code/session_016vnD51QAGwAvqaZuEZJypr

[changeset-bot]

🦋 Changeset detected

Latest commit: a6f9068

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cartesi/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🟢	Lines	98.82% (🎯 0%)	4851 / 4909
🔵	Statements	98.82%	4851 / 4909
🔵	Functions	96.3%	130 / 135
🔵	Branches	0%	0 / 0

📁 File Coverage (19 files)

File	Lines	Statements	Functions	Branches	Uncovered Lines
apps/cli/src/builder/directory.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/docker.ts	🟢 88.68%	🟢 88.68%	🟡 75%	🔴 0%	83-85, 139-147
apps/cli/src/builder/empty.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/none.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/builder/tar.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/compose/builder.ts	🟢 99.79%	🟢 99.79%	🟢 100%	🔴 0%	228
apps/cli/src/compose/common.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/compose/node.ts	🟢 99.24%	🟢 99.24%	🟢 100%	🔴 0%	106
apps/cli/src/config.ts	🟢 94.32%	🟢 94.32%	🟢 95.24%	🔴 0%	75-76, 251, 260, 269, 363, ...
apps/cli/src/contracts.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
...rc/errors/ForkChainValidationError.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
...c/errors/UnsupportedForkChainError.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
...c/exec/cartesi-machine-stored-hash.ts	🟢 92.86%	🟢 92.86%	🟢 100%	🔴 0%	36-37
apps/cli/src/exec/cartesi-machine.ts	🟡 75%	🟡 75%	🟡 66.67%	🔴 0%	10-12, 28-30
apps/cli/src/exec/genext2fs.ts	🟢 96.92%	🟢 96.92%	🟢 100%	🔴 0%	87-88
apps/cli/src/exec/index.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
apps/cli/src/exec/mksquashfs.ts	🟢 91.23%	🟢 91.23%	🟢 100%	🔴 0%	68-72
apps/cli/src/exec/util.ts	🟢 94.74%	🟢 94.74%	🟢 100%	🔴 0%	49-50
apps/cli/src/validations.ts	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-

[brunomenezes]

@tuler,
These slices are odd. Could it be done by using a destructuring based on the assumptions of the variable content?

e.g.

const [key, value=""] = variable.split("=");
envMap[key] = value;

[brunomenezes]

The PR description is strongly on the "how", but I don't understand clearly the "why". Does it help solve an issue Lyno opened?

• New Options to cartesi.toml #477

[tuler]

The PR description is strongly on the "how", but I don't understand clearly the "why".

Added a motivation section to the PR description.