Skip to content

feat(discovery): XCIND_ENV_MAP — app-defined names for discovery variables - #101

Merged
simensen merged 1 commit into
mainfrom
feat/discovery-env-map
Nov 9, 2026
Merged

simensen merged 1 commit into
mainfrom
feat/discovery-env-map

Conversation

@simensen

@simensen simensen commented Nov 6, 2026

Copy link
Copy Markdown
Member

What

An app can now give its own names to discovery values. Each name is a template over XCIND_* discovery variables, and Xcind renders it with the right value for each view:

XCIND_ENV_MAP+=(
  'DATABASE_HOST=${XCIND_SHOP_DATABASE_HOST}'
  'DATABASE_URL=mysql://root@${XCIND_SHOP_DATABASE_HOST}:${XCIND_SHOP_DATABASE_PORT}/shop'
)
  • Container view: the mapped keys are added to every service's environment: in compose.discovery.yaml, after the XCIND_* variables.
  • Host view: the mapped keys are added to the XCIND_HOST_ENV_FILE body, after the XCIND_* variables.

With an assigned database export, DATABASE_HOST is shop-database in a container and 127.0.0.1 (or the assigned hostname) in the host env file.

Why

Today an app maps names in a dotenv file (DATABASE_HOST=${XCIND_SHOP_DATABASE_HOST}). Only a process that loads that file with expansion sees the value. Other tools in the same container, such as a database CLI, a Node service, or a shell script, do not. Compose cannot do the mapping either, because it interpolates from the shell that runs it, not from the variables that Xcind injects.

Rules

The full contract is in ADR-0025.

  • Templates: literal text plus ${XCIND_[A-Z0-9_]+} references. Any other $, a backslash, a backtick, or a control character is an error. So no rendered value contains $, Compose interpolation and dotenv expansion cannot change a value, and an entry cannot split into extra env entries.
  • Missing references: a reference missing from one view drops the entry from that view only (for example, a reference to an unpublished export is absent from the host file). A reference missing from both views fails generation and names the entry.
  • Keys: a key must be a valid env name and must not start with XCIND_. Identical repeats are emitted once. The same key with two templates is an error.
  • Precedence: a mapped key overrides the same key in the app's compose environment: or env_file:. This is documented, with no warning.
  • Validation timing: the discovery hook checks the map syntax before its yq soft-skip, so a syntax error fails generation even when the overlay is skipped.
  • Introspection: xcind-config --json reports the declared templates under a new envMap key. It shows the last template for a repeated key and does not validate.

When the map is not set, the generated overlay and host env file are byte-identical to main.

How

  • lib/xcind/xcind-discovery-lib.bash: new __xcind-discovery-validate-env-map (syntax only), __xcind-discovery-envmap-expand (scans the string, no eval), and __xcind-discovery-build-mapped-pairs <app_root> <view> [own_view_pairs]. The builder computes the other view so that it can detect a reference missing from both. Each hook passes in the view it already built, so a non-empty map adds one extra pair build per hook.
  • xcind-discovery-hook and __xcind-hostenv-execute-hook append the mapped pairs and fail on any map error. On failure the host env file is not written, and in block mode it stays byte-identical.
  • lib/xcind/xcind-lib.bash adds envMap to the JSON contract. The xcind-config help and the bash and zsh completions list it.

Tests

New cases in test/test-xcind.sh:

  • Values for each view, and proxied, assigned, and unpublished references.
  • Multiple references with literal text, literal-only templates, and a map with no exports.
  • Each invalid $ form, and control characters, backslash, and backtick (including a newline-injection case).
  • Invalid and XCIND_ keys, and identical and conflicting repeats.
  • A reference missing from both views.
  • Quotes in values, checked in the YAML and the dotenv output.
  • Validation without yq.
  • block mode keeps an existing file unchanged on error.
  • The envMap JSON key: set, unset, multi-line, and last-wins.

make check passes with 0 failures. An Opus review found one defect: a newline in an entry injected extra env entries. That defect and four smaller findings are fixed in this PR. A live check on a real workspace confirmed both views. A database CLI in a container and a client on the host both connected using only the mapped names, and a reference typo failed xcind-compose config.

Docs

  • New ADR-0025, a PROMOTE candidate for Scind as an env_map: block in application.yaml (ledger row XA-0046, plus a correspondence-map row).
  • Updated the environment-variables and generated-override-files specs, the engineering and user configuration and CLI references, the env-files guide (how to replace a dotenv mapping), and the glossary.

…ables

Let an app declare its own variable names as templates over XCIND_*
discovery variables:

  XCIND_ENV_MAP+=('DATABASE_HOST=${XCIND_SHOP_DATABASE_HOST}')

Each template is expanded from each view's pair set and appended after
the XCIND_* variables: to every service's environment in
compose.discovery.yaml, and to the XCIND_HOST_ENV_FILE body. A
reference missing from one view drops the entry from that view only; a
reference missing from both views fails generation.

Templates allow literal text plus ${XCIND_[A-Z0-9_]+} references. Any
other $, a backslash, a backtick, or a control character is an error,
so no rendered value can be changed by Compose interpolation or dotenv
expansion, and an entry can never split into extra env entries. Keys
must be valid env names and must not start with XCIND_. Identical
repeats are emitted once; conflicting repeats fail.

The discovery hook validates the map syntax before its yq soft-skip.
xcind-config --json reports the declared templates under envMap.

Recorded in ADR-0025 as a PROMOTE candidate (XA-0046).
@simensen
simensen merged commit 7ac6edb into main Nov 9, 2026
16 of 17 checks passed
@simensen
simensen deleted the feat/discovery-env-map branch November 9, 2026 13:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant