mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-12 21:56:21 +00:00
kevinveenbirkenbachandClaude Opus 4.7
eb4bcd23a8
Three new lint tests close gaps in the INFINITO_* SPOT contract:
* tests/lint/filesystem/env/test_default_env_keys_handled.py
Every default.env key must be wired through a handler.
* tests/lint/filesystem/env/test_used_keys_declared.py
Every INFINITO_* in .sh/.py must live in env/{default,ci}.env or
a handler; per-line `# nocheck:` suppresses runtime-only refs.
* tests/lint/filesystem/python/test_no_infinito_get_defaults.py
Forbid ANY default in `.get("INFINITO_*", ...)` -- including the
empty-string fallback (which silently masks an unset key). The
nocheck check walks every physical line the call spans so an
autoformat-split call still honours the marker.
Cache namespace flattens to a single prefix:
INFINITO_PACKAGE_CACHE_* -> INFINITO_CACHE_PACKAGE_*
INFINITO_REGISTRY_CACHE_* -> INFINITO_CACHE_REGISTRY_*
The five previously driver-injected paths (APT_LIST, NPMRC,
PIP_CONF, REGISTRY_PROXY_CONF, FRONTEND_CA_FILE) move into
env/default.env and passthrough.STATIC_KEYS; the
`cache_env_overrides()` helper and its two call sites are gone
along with the test-fixture override for FRONTEND_CA_DIR.
SPOT-strict rewrites:
- 19 sites: `something.get("INFINITO_X", "")` -> subscript
`something["INFINITO_X"]` (loud KeyError when env loader did
not run; all keys live in env/default.env).
- 2 handler-internal bootstrap reads suppressed with
`# nocheck: handler-bootstrap-read`.
- 30 runtime-only / driver-injected / test-fixture references
annotated with `# nocheck: <reason>` per-line.
- Unit tests that previously removed SPOT-guaranteed keys via
`{k: v ... if k \!= KEY}` or `clear=True` switch to setting
the key to "" explicitly, matching the new contract.
Side fixes:
- INFINITO_DNS_DOMAIN + INFINITO_DNS_HOSTS_FILE move from
shell-side defaults in common.sh to env/default.env and
passthrough.STATIC_KEYS.
- dns_systemd_is_operational() drops the dead
INFINITO_DNS_FORCE_HOSTS_FALLBACK override branch (the
variable was never set anywhere).
- INFINITO_WORKER_FETCH switches from `os.environ.get(KEY, "1")`
to `os.environ[KEY]`.
- scripts/tests/code/wrapper.sh exec args move into a bash
array so `# nocheck:` on INFINITO_TEST_TYPE can live on its
own element line (SC2215 fix).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
47 lines
2.9 KiB
Markdown
47 lines
2.9 KiB
Markdown
# Environment Variables
|
|
|
|
The project's environment is owned by a single generator, not scattered across shell modules.
|
|
Every variable is documented INLINE next to its definition with a one-line `# ...` comment above the key.
|
|
This page is just a map of where to look.
|
|
|
|
## Where the defaults live
|
|
|
|
- [`default.env`](../../../env/default.env) holds the committed defaults for static keys, each preceded by a one-line comment.
|
|
Edit this file to change a default or to read the per-variable documentation.
|
|
- [`ci.env`](../../../env/ci.env) carries the defaults docker compose consumes via `--env-file env/ci.env` (DNS, subnet, gateway, domain).
|
|
Same per-key comment convention.
|
|
- `.env` (gitignored) is generated by `make dotenv`, which delegates to `python -m cli.meta.env`.
|
|
It combines `default.env` with runtime-resolved values (selected distro, GHA/Act flags, df/meminfo-derived cache sizes, sha256 secrets, repository owner, ...).
|
|
Each line in `.env` is preceded by its own comment, so the file is self-describing.
|
|
Open it after `make dotenv` to inspect the effective value-set together with its documentation.
|
|
|
|
## Regenerating
|
|
|
|
```bash
|
|
make dotenv
|
|
```
|
|
|
|
Override individual values by exporting them before `make dotenv`.
|
|
Already-set env vars take precedence over `default.env` defaults.
|
|
|
|
## Pipeline
|
|
|
|
- [`env/`](../../../utils/env/) (under `utils/`) holds the parser, runtime helpers, writer, and one handler module per dynamically-computed variable under [`handlers/`](../../../utils/env/handlers/).
|
|
- [`env/`](../../../cli/meta/env/) (under `cli/meta/`) provides the CLI entry point invoked as `python -m cli.meta.env`.
|
|
- [`load.sh`](../../../scripts/meta/env/load.sh) is the shell loader; it sources `.env` and auto-generates it on a cold clone.
|
|
|
|
## Variables NOT in `default.env`
|
|
|
|
A handful of variables are documented next to their consumer because they cannot have a static default:
|
|
|
|
- **Driver-injected** by `make up` and the dev CLI (cache override paths like `INFINITO_CACHE_REGISTRY_PROXY_CONF`, the package-cache config paths, the frontend CA file).
|
|
See [common.py](../../../cli/administration/deploy/development/common.py) and [compose.yml.md](../artefact/files/compose.yml.md).
|
|
- **Computed at container start** for `INFINITO_PATH`, set by [entry.sh](../../../scripts/docker/entry.sh).
|
|
- **Persisted on the deploy target** for `INFINITO_VERSION`, written by the [sys-version](../../../roles/sys-version/) role.
|
|
- **Compose literals** with no env-side knob, namely `GIT_SSL_NO_VERIFY` and `PYTHONHTTPSVERIFY`, documented in [compose.yml.md](../artefact/files/compose.yml.md).
|
|
|
|
## Role-scoped variables
|
|
|
|
App-specific container variables live next to the role that owns them, typically in `roles/<role>/templates/env.j2`, `roles/<role>/templates/bootstrap.env.j2`, or `roles/<role>/templates/playwright.env.j2`.
|
|
They are intentionally NOT centralised here so the app documentation and its generated env file stay in sync.
|