envctl 2.3.2__tar.gz → 2.3.4__tar.gz

{envctl-2.3.2/src/envctl.egg-info → envctl-2.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: envctl
-Version: 2.3.2
+Version: 2.3.4
 Summary: Local environment control plane for contract-driven development workflows
 Author-email: Alessandro Barbagallo <alessbarb@gmail.com>
 License-Expression: MIT
@@ -97,6 +97,8 @@ envctl check            # validate against the contract
 envctl run -- python app.py  # run with env injected
 ```
 
+If you use `envctl run -- docker run ...`, `envctl` injects into the Docker client process, not directly into the container. Forward container variables explicitly with `-e`, `--env`, or `--env-file`.
+
 ---
 
 ## Why not just `.env.local`?
@@ -134,6 +136,13 @@ Think of it like this:
 
 > the repo defines the rules, your machine provides the data, and envctl builds the final environment.
 
+Resolution now includes placeholder expansion as part of the runtime model, so `check`, `inspect`,
+`run`, `sync`, and `export` all see the same final value.
+
+Contracts can also attach an optional human-facing `group` label to variables for organization,
+filtering, and dotenv section rendering. `group` is not a namespace, is not hierarchical, and does
+not change resolution or dependency semantics.
+
 ---
 
 ### Example contract
@@ -162,6 +171,12 @@ variables:
     format: json
     required: false
     sensitive: false
+  APP_URL:
+    type: string
+    required: true
+    sensitive: false
+    group: Application
+    default: http://${APP_NAME}:${PORT}
 ```
 
 This file describes what exists.
@@ -169,6 +184,71 @@ It never contains real values.
 
 ---
 
+## Variable expansion
+
+`envctl` supports explicit placeholder expansion with `${VAR}` during resolution.
+
+That means the expansion happens before projection, so the effective expanded value is what:
+
+* `inspect` shows
+* `check` validates
+* `run` injects
+* `sync` writes
+* `export` prints
+
+Example:
+
+```dotenv
+INFRA_NEO4J_USER=neo4j
+INFRA_NEO4J_PASSWORD=super-secret
+INFRA_NEO4J_AUTH=${INFRA_NEO4J_USER}/${INFRA_NEO4J_PASSWORD}
+```
+
+`INFRA_NEO4J_AUTH` resolves to the final runtime value, not the literal expression.
+
+Rules:
+
+* only `${VAR}` is supported in v1
+* `$VAR` stays literal
+* if `VAR` is a declared envctl key, envctl resolves that key first
+* otherwise envctl falls back to the current process environment
+* `${HOME}` works when `HOME` exists in the current process environment
+* malformed placeholders or unresolved references make resolution invalid
+
+Compatibility notes:
+
+* before this feature, `${HOME}` stayed literal
+* now `${HOME}` is expanded during resolution
+* `${...}` literal escaping is not supported in v1
+
+## Optional groups
+
+Each contract variable may define an optional `group` label:
+
+```yaml
+variables:
+  DATABASE_URL:
+    type: url
+    required: true
+    sensitive: true
+    group: Database
+```
+
+`group` is used only for:
+
+* organization in the contract
+* CLI targeting with `--group`
+* grouped dotenv output from `sync` and `export --format dotenv`
+
+It does not:
+
+* create namespaces
+* affect `${VAR}` expansion rules
+* restrict cross-variable references
+* imply hierarchy, inheritance, or prefix matching
+
+---
+
 ## Profiles
 
 Instead of juggling multiple `.env` files:

{envctl-2.3.2 → envctl-2.3.4}/README.md

@@ -58,6 +58,8 @@ envctl check            # validate against the contract
 envctl run -- python app.py  # run with env injected
 ```
 
+If you use `envctl run -- docker run ...`, `envctl` injects into the Docker client process, not directly into the container. Forward container variables explicitly with `-e`, `--env`, or `--env-file`.
+
 ---
 
 ## Why not just `.env.local`?
@@ -95,6 +97,13 @@ Think of it like this:
 
 > the repo defines the rules, your machine provides the data, and envctl builds the final environment.
 
+Resolution now includes placeholder expansion as part of the runtime model, so `check`, `inspect`,
+`run`, `sync`, and `export` all see the same final value.
+
+Contracts can also attach an optional human-facing `group` label to variables for organization,
+filtering, and dotenv section rendering. `group` is not a namespace, is not hierarchical, and does
+not change resolution or dependency semantics.
+
 ---
 
 ### Example contract
@@ -123,6 +132,12 @@ variables:
     format: json
     required: false
     sensitive: false
+  APP_URL:
+    type: string
+    required: true
+    sensitive: false
+    group: Application
+    default: http://${APP_NAME}:${PORT}
 ```
 
 This file describes what exists.
@@ -130,6 +145,71 @@ It never contains real values.
 
 ---
 
+## Variable expansion
+
+`envctl` supports explicit placeholder expansion with `${VAR}` during resolution.
+
+That means the expansion happens before projection, so the effective expanded value is what:
+
+* `inspect` shows
+* `check` validates
+* `run` injects
+* `sync` writes
+* `export` prints
+
+Example:
+
+```dotenv
+INFRA_NEO4J_USER=neo4j
+INFRA_NEO4J_PASSWORD=super-secret
+INFRA_NEO4J_AUTH=${INFRA_NEO4J_USER}/${INFRA_NEO4J_PASSWORD}
+```
+
+`INFRA_NEO4J_AUTH` resolves to the final runtime value, not the literal expression.
+
+Rules:
+
+* only `${VAR}` is supported in v1
+* `$VAR` stays literal
+* if `VAR` is a declared envctl key, envctl resolves that key first
+* otherwise envctl falls back to the current process environment
+* `${HOME}` works when `HOME` exists in the current process environment
+* malformed placeholders or unresolved references make resolution invalid
+
+Compatibility notes:
+
+* before this feature, `${HOME}` stayed literal
+* now `${HOME}` is expanded during resolution
+* `${...}` literal escaping is not supported in v1
+
+## Optional groups
+
+Each contract variable may define an optional `group` label:
+
+```yaml
+variables:
+  DATABASE_URL:
+    type: url
+    required: true
+    sensitive: true
+    group: Database
+```
+
+`group` is used only for:
+
+* organization in the contract
+* CLI targeting with `--group`
+* grouped dotenv output from `sync` and `export --format dotenv`
+
+It does not:
+
+* create namespaces
+* affect `${VAR}` expansion rules
+* restrict cross-variable references
+* imply hierarchy, inheritance, or prefix matching
+
+---
+
 ## Profiles
 
 Instead of juggling multiple `.env` files:

{envctl-2.3.2 → envctl-2.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "envctl"
-version = "2.3.2"
+version = "2.3.4"
 description = "Local environment control plane for contract-driven development workflows"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -71,7 +71,7 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-addopts = "-q --strict-markers --strict-config"
+addopts = "-q --strict-markers --strict-config --import-mode=importlib"
 pythonpath = ["src"]
 
 [tool.ruff]

envctl-2.3.4/src/envctl/adapters/process_environment.py

@@ -0,0 +1,17 @@
+"""Access to process environment variables."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+
+class ProcessEnvironmentProvider:
+    """Resolve variables from the current process environment."""
+
+    def __init__(self, environ: Mapping[str, str] | None = None) -> None:
+        self._environ = environ if environ is not None else os.environ
+
+    def get(self, key: str) -> str | None:
+        """Return one process environment value."""
+        return self._environ.get(key)

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/app.py

@@ -24,7 +24,8 @@ from envctl.cli.commands.sync import sync_command
 from envctl.cli.commands.unset import unset_command
 from envctl.cli.commands.vault import vault_app
 from envctl.cli.runtime import set_cli_state
-from envctl.config.loader import resolve_default_profile
+from envctl.config.loader import load_config
+from envctl.config.profile_resolution import resolve_active_profile
 from envctl.domain.runtime import OutputFormat
 
 VERSION_OPTION = typer.Option(
@@ -46,6 +47,12 @@ PROFILE_OPTION = typer.Option(
     "-p",
     help="Select the active environment profile.",
 )
+GROUP_OPTION = typer.Option(
+    None,
+    "--group",
+    "-g",
+    help="Target only variables whose contract group matches LABEL exactly.",
+)
 
 app = typer.Typer(help="envctl - local environment control plane")
 app.add_typer(config_app, name="config")
@@ -60,16 +67,22 @@ def main(
     version: bool = VERSION_OPTION,
     json_output: bool = JSON_OPTION,
     profile: str | None = PROFILE_OPTION,
+    group: str | None = GROUP_OPTION,
 ) -> None:
     """envctl - local environment control plane."""
     del version
 
-    active_profile = profile.strip().lower() if profile is not None else resolve_default_profile()
+    config = load_config()
+    active_profile = resolve_active_profile(
+        profile,
+        config_default_profile=config.default_profile,
+    )
 
     set_cli_state(
         ctx,
         output_format=OutputFormat.JSON if json_output else OutputFormat.TEXT,
         profile=active_profile,
+        group=group.strip() or None if group is not None else None,
     )
 
 

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/commands/check/command.py

@@ -6,7 +6,7 @@ import typer
 
 from envctl.cli.decorators import handle_errors
 from envctl.cli.presenters import render_resolution_view
-from envctl.cli.runtime import get_active_profile, is_json_output
+from envctl.cli.runtime import get_active_profile, get_selected_group, is_json_output
 from envctl.cli.serializers import (
     emit_json,
     serialize_project_context,
@@ -24,7 +24,8 @@ def _is_check_ok(*, is_valid: bool, unknown_keys: list[str] | tuple[str, ...]) -
 @handle_errors
 def check_command() -> None:
     """Validate the current project environment against the contract."""
-    context, active_profile, report = run_check(get_active_profile())
+    selected_group = get_selected_group()
+    context, active_profile, report = run_check(get_active_profile(), group=selected_group)
     ok = _is_check_ok(
         is_valid=report.is_valid,
         unknown_keys=report.unknown_keys,
@@ -37,6 +38,7 @@ def check_command() -> None:
                 "command": "check",
                 "data": {
                     "active_profile": active_profile,
+                    "selected_group": selected_group,
                     "context": serialize_project_context(context),
                     "report": serialize_resolution_report(report),
                 },
@@ -48,6 +50,7 @@ def check_command() -> None:
 
     render_resolution_view(
         profile=active_profile,
+        group=selected_group,
         report=report,
     )
 

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/commands/explain/command.py

@@ -34,8 +34,12 @@ def explain_command(key: str = typer.Argument(...)) -> None:
         profile=active_profile,
         key=item.key,
         source=item.source,
+        raw_value=item.raw_value,
         value=item.value,
         masked=item.masked,
+        expansion_status=item.expansion_status,
+        expansion_refs=item.expansion_refs,
+        expansion_error=item.expansion_error.detail if item.expansion_error is not None else None,
         valid=item.valid,
         detail=item.detail,
     )

envctl-2.3.4/src/envctl/cli/commands/export/command.py

@@ -0,0 +1,38 @@
+"""Export command."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import typer
+
+from envctl.cli.decorators import handle_errors, text_output_only
+from envctl.cli.presenters import render_export_output
+from envctl.cli.runtime import get_active_profile, get_selected_group
+from envctl.services.export_service import run_export
+
+
+@handle_errors
+@text_output_only("export")
+def export_command(
+    format: Literal["shell", "dotenv"] = typer.Option(
+        "shell",
+        "--format",
+        help=(
+            "Choose the export format: 'shell' prints shell export lines, "
+            "'dotenv' prints KEY=value lines to stdout."
+        ),
+    ),
+) -> None:
+    """Print the resolved environment as shell export lines."""
+    _context, active_profile, rendered = run_export(
+        get_active_profile(),
+        format=format,
+        group=get_selected_group(),
+    )
+
+    if format == "dotenv":
+        print(rendered, end="")
+        return
+
+    render_export_output(profile=active_profile, rendered=rendered)

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/commands/inspect/command.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from envctl.cli.decorators import handle_errors
 from envctl.cli.presenters import render_resolution_view
-from envctl.cli.runtime import get_active_profile, is_json_output
+from envctl.cli.runtime import get_active_profile, get_selected_group, is_json_output
 from envctl.cli.serializers import (
     emit_json,
     serialize_project_context,
@@ -16,7 +16,8 @@ from envctl.services.inspect_service import run_inspect
 @handle_errors
 def inspect_command() -> None:
     """Inspect the resolved environment."""
-    context, active_profile, report = run_inspect(get_active_profile())
+    selected_group = get_selected_group()
+    context, active_profile, report = run_inspect(get_active_profile(), group=selected_group)
 
     if is_json_output():
         emit_json(
@@ -25,6 +26,7 @@ def inspect_command() -> None:
                 "command": "inspect",
                 "data": {
                     "active_profile": active_profile,
+                    "selected_group": selected_group,
                     "context": serialize_project_context(context),
                     "report": serialize_resolution_report(report),
                 },
@@ -34,5 +36,6 @@ def inspect_command() -> None:
 
     render_resolution_view(
         profile=active_profile,
+        group=selected_group,
         report=report,
     )

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/commands/remove/command.py

@@ -45,7 +45,9 @@ def remove_command(
         key=key,
         contract_path=result.repo_contract_path,
         removed_from_contract=result.removed_from_contract,
+        inspected_profiles=result.inspected_profiles,
         removed_from_profiles=result.removed_from_profiles,
+        missing_from_profiles=result.missing_from_profiles,
         affected_paths=result.affected_paths,
         repo_root=context.repo_root,
     )

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/commands/run/command.py

@@ -5,7 +5,8 @@ from __future__ import annotations
 import typer
 
 from envctl.cli.decorators import handle_errors, text_output_only
-from envctl.cli.runtime import get_active_profile
+from envctl.cli.presenters.run_presenter import render_run_warnings
+from envctl.cli.runtime import get_active_profile, get_selected_group
 from envctl.services.run_service import run_command
 
 COMMAND_ARGUMENT = typer.Argument(...)
@@ -15,8 +16,10 @@ COMMAND_ARGUMENT = typer.Argument(...)
 @text_output_only("run")
 def run_command_cli(command: list[str] = COMMAND_ARGUMENT) -> None:
     """Run a child process with the resolved environment injected."""
-    _context, _active_profile, exit_code = run_command(
+    _context, result = run_command(
         command,
         get_active_profile(),
+        group=get_selected_group(),
     )
-    raise typer.Exit(code=exit_code)
+    render_run_warnings(result.warnings)
+    raise typer.Exit(code=result.exit_code)

envctl-2.3.4/src/envctl/cli/commands/sync/command.py

@@ -0,0 +1,35 @@
+"""Sync command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from envctl.cli.decorators import handle_errors, requires_writable_runtime
+from envctl.cli.presenters import render_sync_result
+from envctl.cli.runtime import get_active_profile, get_selected_group
+from envctl.services.sync_service import run_sync
+
+OUTPUT_OPTION = typer.Option(
+    None,
+    "--output",
+    help=(
+        "Write the generated dotenv file to PATH instead of the default "
+        "profile-derived repo-local target."
+    ),
+)
+
+
+@handle_errors
+@requires_writable_runtime("sync")
+def sync_command(
+    output: Path | None = OUTPUT_OPTION,
+) -> None:
+    """Materialize the resolved environment into the repository env file."""
+    _context, active_profile, target_path = run_sync(
+        get_active_profile(),
+        output_path=output,
+        group=get_selected_group(),
+    )
+    render_sync_result(profile=active_profile, target_path=target_path)

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/presenters/__init__.py

@@ -32,6 +32,7 @@ from envctl.cli.presenters.resolution_presenter import (
     render_resolution,
     render_resolution_view,
 )
+from envctl.cli.presenters.run_presenter import render_run_warnings
 from envctl.cli.presenters.status_presenter import (
     render_status,
     render_status_view,
@@ -71,6 +72,7 @@ __all__ = [
     "render_remove_result",
     "render_resolution",
     "render_resolution_view",
+    "render_run_warnings",
     "render_set_result",
     "render_status",
     "render_status_view",

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/presenters/action_presenter.py

@@ -74,8 +74,12 @@ def render_explain_value(
     profile: str,
     key: str,
     source: str,
+    raw_value: str | None,
     value: str,
     masked: bool,
+    expansion_status: str,
+    expansion_refs: tuple[str, ...],
+    expansion_error: str | None,
     valid: bool,
     detail: str | None,
 ) -> None:
@@ -85,7 +89,14 @@ def render_explain_value(
     print_kv("profile", profile)
     print_kv("key", key)
     print_kv("source", source)
+    if raw_value is not None:
+        print_kv("raw_value", raw_value)
     print_kv("value", shown_value)
+    print_kv("expansion_status", expansion_status)
+    if expansion_refs:
+        print_kv("expansion_refs", ", ".join(expansion_refs))
+    if expansion_error is not None:
+        print_kv("expansion_error", expansion_error)
     print_kv("valid", "yes" if valid else "no")
 
     if detail:
@@ -166,7 +177,9 @@ def render_remove_result(
     key: str,
     contract_path: Path,
     removed_from_contract: bool,
+    inspected_profiles: tuple[str, ...],
     removed_from_profiles: tuple[str, ...],
+    missing_from_profiles: tuple[str, ...],
     affected_paths: tuple[Path, ...],
     repo_root: Path,
 ) -> None:
@@ -178,6 +191,14 @@ def render_remove_result(
         "removed_from_profiles",
         ", ".join(removed_from_profiles) if removed_from_profiles else "none",
     )
+    print_kv(
+        "inspected_profiles",
+        ", ".join(inspected_profiles) if inspected_profiles else "none",
+    )
+    print_kv(
+        "missing_from_profiles",
+        ", ".join(missing_from_profiles) if missing_from_profiles else "none",
+    )
 
     if affected_paths:
         print_kv("affected_paths", ", ".join(str(path) for path in affected_paths))

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/presenters/resolution_presenter.py

@@ -54,7 +54,13 @@ def _render_resolved_values(report: ResolutionReport) -> None:
         item = report.values[key]
         shown_value = mask_value(item.value) if item.masked else item.value
         suffix = "" if item.valid else f" — invalid: {item.detail or 'unknown reason'}"
-        typer.echo(f"  {key} = {shown_value} ({item.source}){suffix}")
+        expansion_suffix = ""
+        if item.expansion_status == "expanded":
+            refs = ", ".join(item.expansion_refs)
+            expansion_suffix = f" [expanded{': ' + refs if refs else ''}]"
+        elif item.expansion_status == "error" and item.expansion_error is not None:
+            expansion_suffix = f" [expansion error: {item.expansion_error.kind}]"
+        typer.echo(f"  {key} = {shown_value} ({item.source}){expansion_suffix}{suffix}")
 
 
 def render_resolution(report: ResolutionReport) -> None:
@@ -71,8 +77,11 @@ def render_resolution(report: ResolutionReport) -> None:
 def render_resolution_view(
     *,
     profile: str,
+    group: str | None,
     report: ResolutionReport,
 ) -> None:
     """Render one resolved environment view including the active profile."""
     print_kv("profile", profile)
+    if group is not None:
+        print_kv("group", group)
     render_resolution(report)

envctl-2.3.4/src/envctl/cli/presenters/run_presenter.py

@@ -0,0 +1,11 @@
+"""Presenters for run command advisories."""
+
+from __future__ import annotations
+
+from envctl.utils.output import print_warning
+
+
+def render_run_warnings(warnings: tuple[str, ...]) -> None:
+    """Render run command warnings."""
+    for warning in warnings:
+        print_warning(warning)

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/prompts/confirmation_prompts.py

@@ -25,6 +25,9 @@ def build_remove_confirmation_message(key: str, plan: RemovePlan) -> str:
     if plan.present_in_other_profiles:
         lines.append(f"- also present in: {', '.join(plan.present_in_other_profiles)}")
 
+    if plan.absent_in_other_profiles:
+        lines.append(f"- not present in: {', '.join(plan.absent_in_other_profiles)}")
+
     return "\n".join(lines)
 
 

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/runtime.py

@@ -17,6 +17,7 @@ class CliState:
 
     output_format: OutputFormat = OutputFormat.TEXT
     profile: str = DEFAULT_PROFILE
+    group: str | None = None
 
 
 def set_cli_state(
@@ -24,9 +25,10 @@ def set_cli_state(
     *,
     output_format: OutputFormat,
     profile: str = DEFAULT_PROFILE,
+    group: str | None = None,
 ) -> None:
     """Persist the CLI state on the Typer/Click context."""
-    ctx.obj = CliState(output_format=output_format, profile=profile)
+    ctx.obj = CliState(output_format=output_format, profile=profile, group=group)
 
 
 def get_cli_state() -> CliState:
@@ -52,6 +54,11 @@ def get_active_profile() -> str:
     return get_cli_state().profile
 
 
+def get_selected_group() -> str | None:
+    """Return the active CLI group filter."""
+    return get_cli_state().group
+
+
 def get_command_path() -> str | None:
     """Return the current command path when available.
 

{envctl-2.3.2 → envctl-2.3.4}/src/envctl/cli/serializers.py

@@ -46,12 +46,24 @@ def serialize_project_context(context: ProjectContext) -> dict[str, Any]:
 
 def serialize_resolved_value(item: ResolvedValue) -> dict[str, Any]:
     """Serialize one resolved value."""
+    shown_raw_value = None if item.raw_value is None or item.masked else item.raw_value
     shown_value = mask_value(item.value) if item.masked else item.value
     return {
         "key": item.key,
+        "raw_value": shown_raw_value,
         "value": shown_value,
         "source": item.source,
         "masked": item.masked,
+        "expansion_status": item.expansion_status,
+        "expansion_refs": list(item.expansion_refs),
+        "expansion_error": (
+            {
+                "kind": item.expansion_error.kind,
+                "detail": item.expansion_error.detail,
+            }
+            if item.expansion_error is not None
+            else None
+        ),
         "valid": item.valid,
         "detail": item.detail,
     }