envctl 2.3.1__py3-none-any.whl

envctl/__init__.py

@@ -0,0 +1,10 @@
+"""envctl package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__"]
+
+try:
+    __version__ = version("envctl")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

envctl/__main__.py

@@ -0,0 +1,6 @@
+"""Module entrypoint for `python -m envctl`."""
+
+from envctl.cli.app import app
+
+if __name__ == "__main__":
+    app()

envctl/adapters/dotenv.py

@@ -0,0 +1,76 @@
+"""Helpers for reading and writing dotenv-style files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def parse_env_text(content: str) -> dict[str, str]:
+    """Parse a dotenv-like text payload into a mapping."""
+    result: dict[str, str] = {}
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+
+        if not key:
+            continue
+
+        if len(value) >= 2 and (
+            (value.startswith('"') and value.endswith('"'))
+            or (value.startswith("'") and value.endswith("'"))
+        ):
+            value = value[1:-1]
+
+        result[key] = value
+
+    return result
+
+
+def load_env_file(path: Path) -> dict[str, str]:
+    """Load a dotenv file when present."""
+    if not path.exists():
+        return {}
+    return parse_env_text(path.read_text(encoding="utf-8"))
+
+
+def _needs_quotes(value: str) -> bool:
+    """Return whether a dotenv value should be quoted."""
+    if value == "":
+        return True
+
+    special_chars = {" ", "\t", "\n", "\r", "#", '"', "'"}
+    return any(char in value for char in special_chars)
+
+
+def _dump_env_value(value: str) -> str:
+    """Serialize one dotenv value safely for shell consumption."""
+    if not _needs_quotes(value):
+        return value
+
+    escaped = (
+        value.replace("\\", "\\\\").replace('"', '\\"').replace("$", "\\$").replace("`", "\\`")
+    )
+    return f'"{escaped}"'
+
+
+def dump_env(data: dict[str, str], header: str | None = None) -> str:
+    """Dump a mapping to dotenv text."""
+    lines: list[str] = []
+
+    if header:
+        lines.append(header.rstrip("\n"))
+        lines.append("")
+
+    for key in sorted(data):
+        value = data[key]
+        lines.append(f"{key}={_dump_env_value(value)}")
+
+    lines.append("")
+    return "\n".join(lines)

envctl/adapters/editor.py

@@ -0,0 +1,39 @@
+# src/envctl/adapters/editor.py
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+
+from envctl.errors import ExecutionError
+
+
+def resolve_editor() -> list[str]:
+    visual = os.environ.get("VISUAL", "").strip()
+    if visual:
+        return shlex.split(visual)
+
+    editor = os.environ.get("EDITOR", "").strip()
+    if editor:
+        return shlex.split(editor)
+
+    for candidate in ("nano", "vi"):
+        path = shutil.which(candidate)
+        if path:
+            return [path]
+
+    raise ExecutionError("No editor found. Set VISUAL or EDITOR.")
+
+
+def open_file(path: str) -> None:
+    command = [*resolve_editor(), path]
+
+    try:
+        completed = subprocess.run(command, check=False)
+    except OSError as exc:
+        raise ExecutionError(f"Failed to launch editor: {command[0]}") from exc
+
+    if completed.returncode != 0:
+        raise ExecutionError(f"Editor exited with code {completed.returncode}")

envctl/adapters/git.py

@@ -0,0 +1,76 @@
+"""Git repository helpers."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from envctl.errors import ExecutionError, ProjectDetectionError
+
+
+def _run_git(
+    args: list[str],
+    *,
+    cwd: Path | None = None,
+    check: bool = True,
+) -> str:
+    """Run a git command and return stripped stdout."""
+    try:
+        completed = subprocess.run(
+            ["git", *args],
+            cwd=str(cwd) if cwd else None,
+            check=check,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError as exc:
+        raise ProjectDetectionError("git executable not found") from exc
+    except subprocess.CalledProcessError as exc:
+        message = (exc.stderr or "").strip() or (exc.stdout or "").strip() or "git command failed"
+
+        if not check:
+            return ""
+
+        raise ProjectDetectionError(message) from exc
+
+    return completed.stdout.strip()
+
+
+def resolve_repo_root() -> Path:
+    """Resolve the current Git repository root."""
+    return Path(_run_git(["rev-parse", "--show-toplevel"])).resolve()
+
+
+def get_repo_remote(repo_root: Path) -> str | None:
+    """Return the origin remote URL when available."""
+    try:
+        value = _run_git(["remote", "get-url", "origin"], cwd=repo_root, check=False)
+    except ProjectDetectionError:
+        return None
+
+    return value or None
+
+
+def get_local_git_config(repo_root: Path, key: str) -> str | None:
+    """Return one local Git config value when present."""
+    value = _run_git(["config", "--local", "--get", key], cwd=repo_root, check=False)
+    return value or None
+
+
+def set_local_git_config(repo_root: Path, key: str, value: str) -> None:
+    """Persist one local Git config value."""
+    try:
+        _run_git(["config", "--local", key, value], cwd=repo_root, check=True)
+    except ProjectDetectionError as exc:
+        raise ExecutionError(str(exc)) from exc
+
+
+def unset_local_git_config(repo_root: Path, key: str) -> None:
+    """Remove one local Git config value when present."""
+    try:
+        _run_git(["config", "--local", "--unset", key], cwd=repo_root, check=True)
+    except ProjectDetectionError as exc:
+        message = str(exc).strip().lower()
+        if "no such section or key" in message or "key does not contain a section" in message:
+            return
+        raise ExecutionError(str(exc)) from exc

envctl/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package."""

envctl/cli/app.py

@@ -0,0 +1,92 @@
+"""Main Typer application."""
+
+from __future__ import annotations
+
+import typer
+
+from envctl.cli.callbacks import version_callback
+from envctl.cli.commands.add import add_command
+from envctl.cli.commands.check import check_command
+from envctl.cli.commands.config import config_app
+from envctl.cli.commands.doctor import doctor_command
+from envctl.cli.commands.explain import explain_command
+from envctl.cli.commands.export import export_command
+from envctl.cli.commands.fill import fill_command
+from envctl.cli.commands.init import init_command
+from envctl.cli.commands.inspect import inspect_command
+from envctl.cli.commands.profile import profile_app
+from envctl.cli.commands.project import project_app
+from envctl.cli.commands.remove import remove_command
+from envctl.cli.commands.run import run_command_cli
+from envctl.cli.commands.set import set_command
+from envctl.cli.commands.status import status_command
+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.domain.runtime import OutputFormat
+
+VERSION_OPTION = typer.Option(
+    None,
+    "--version",
+    "-V",
+    help="Show the version and exit.",
+    callback=version_callback,
+    is_eager=True,
+)
+JSON_OPTION = typer.Option(
+    False,
+    "--json",
+    help="Emit structured JSON output for supported commands.",
+)
+PROFILE_OPTION = typer.Option(
+    None,
+    "--profile",
+    "-p",
+    help="Select the active environment profile.",
+)
+
+app = typer.Typer(help="envctl - local environment control plane")
+app.add_typer(config_app, name="config")
+app.add_typer(vault_app, name="vault")
+app.add_typer(project_app, name="project")
+app.add_typer(profile_app, name="profile")
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: bool = VERSION_OPTION,
+    json_output: bool = JSON_OPTION,
+    profile: str | None = PROFILE_OPTION,
+) -> None:
+    """envctl - local environment control plane."""
+    del version
+
+    active_profile = profile.strip().lower() if profile is not None else resolve_default_profile()
+
+    set_cli_state(
+        ctx,
+        output_format=OutputFormat.JSON if json_output else OutputFormat.TEXT,
+        profile=active_profile,
+    )
+
+
+app.command("doctor")(doctor_command)
+app.command("init")(init_command)
+app.command("add")(add_command)
+app.command("set")(set_command)
+app.command("unset")(unset_command)
+app.command("remove")(remove_command)
+app.command("fill")(fill_command)
+app.command("check")(check_command)
+app.command("inspect")(inspect_command)
+app.command("explain")(explain_command)
+app.command("sync")(sync_command)
+app.command("export")(export_command)
+app.command(
+    "run",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)(run_command_cli)
+app.command("status")(status_command)

envctl/cli/callbacks.py

@@ -0,0 +1,33 @@
+"""CLI callbacks and helpers."""
+
+from __future__ import annotations
+
+import getpass
+
+import typer
+
+from envctl import __version__
+
+
+def version_callback(value: bool) -> None:
+    """Print the version and exit."""
+    if value:
+        typer.echo(f"envctl {__version__}")
+        raise typer.Exit()
+
+
+def typer_prompt(message: str, secret: bool, default: str | None) -> str:
+    """Prompt for a string value from the terminal."""
+    suffix = f" [{default}]" if default is not None else ""
+    full_message = f"{message}{suffix}"
+
+    if secret:
+        value = getpass.getpass(f"{full_message}: ")
+        return value if value else (default or "")
+
+    return str(typer.prompt(full_message, default=default or "", show_default=False))
+
+
+def typer_confirm(message: str, default: bool = False) -> bool:
+    """Prompt for a boolean confirmation from the terminal."""
+    return typer.confirm(message, default=default, show_default=True)

envctl/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands."""

envctl/cli/commands/add/__init__.py

@@ -0,0 +1,5 @@
+"""Add command package."""
+
+from envctl.cli.commands.add.command import add_command
+
+__all__ = ["add_command"]

envctl/cli/commands/add/command.py

@@ -0,0 +1,237 @@
+"""Add command."""
+
+from __future__ import annotations
+
+import typer
+
+from envctl.cli.callbacks import typer_confirm, typer_prompt
+from envctl.cli.decorators import (
+    handle_errors,
+    requires_writable_runtime,
+    text_output_only,
+)
+from envctl.cli.runtime import get_active_profile
+from envctl.domain.operations import AddVariableRequest
+from envctl.services.add_service import run_add
+from envctl.utils.output import print_kv, print_success, print_warning
+
+KEY_ARGUMENT = typer.Argument(...)
+VALUE_ARGUMENT = typer.Argument(...)
+TYPE_OPTION = typer.Option(None, "--type")
+REQUIRED_OPTION = typer.Option(False, "--required")
+OPTIONAL_OPTION = typer.Option(False, "--optional")
+SENSITIVE_OPTION = typer.Option(False, "--sensitive")
+NON_SENSITIVE_OPTION = typer.Option(False, "--non-sensitive")
+INTERACTIVE_OPTION = typer.Option(False, "--interactive")
+DESCRIPTION_OPTION = typer.Option(None, "--description")
+DEFAULT_OPTION = typer.Option(None, "--default")
+EXAMPLE_OPTION = typer.Option(None, "--example")
+PATTERN_OPTION = typer.Option(None, "--pattern")
+CHOICE_OPTION = typer.Option(None, "--choice")
+
+
+def _resolve_required(required: bool, optional: bool) -> bool | None:
+    """Resolve required/optional flags."""
+    if required and optional:
+        raise typer.BadParameter("Use either --required or --optional, not both.")
+    if required:
+        return True
+    if optional:
+        return False
+    return None
+
+
+def _resolve_sensitive(sensitive: bool, non_sensitive: bool) -> bool | None:
+    """Resolve sensitive/non-sensitive flags."""
+    if sensitive and non_sensitive:
+        raise typer.BadParameter("Use either --sensitive or --non-sensitive, not both.")
+    if sensitive:
+        return True
+    if non_sensitive:
+        return False
+    return None
+
+
+def _collect_interactive_overrides(
+    *,
+    type_: str | None,
+    description: str | None,
+    override_required: bool | None,
+    override_sensitive: bool | None,
+    default: str | None,
+    example: str | None,
+    pattern: str | None,
+    choice: list[str] | None,
+) -> tuple[
+    str | None,
+    str | None,
+    bool | None,
+    bool | None,
+    str | None,
+    str | None,
+    str | None,
+    list[str],
+]:
+    """Collect interactive metadata overrides."""
+    resolved_type = typer_prompt("Variable type", False, type_ or "string")
+    resolved_description = typer_prompt("Description", False, description or "")
+
+    resolved_required = override_required
+    if resolved_required is None:
+        resolved_required = typer_confirm("Required?", default=True)
+
+    resolved_sensitive = override_sensitive
+    if resolved_sensitive is None:
+        resolved_sensitive = typer_confirm("Sensitive?", default=False)
+
+    resolved_default = typer_prompt("Default value", False, default or "")
+    resolved_example = typer_prompt("Example", False, example or "")
+    resolved_pattern = typer_prompt("Pattern", False, pattern or "")
+    choices_text = typer_prompt(
+        "Choices (comma-separated)",
+        False,
+        ", ".join(choice or []),
+    )
+    resolved_choices = [item.strip() for item in choices_text.split(",") if item.strip()]
+
+    return (
+        resolved_type,
+        resolved_description,
+        resolved_required,
+        resolved_sensitive,
+        resolved_default,
+        resolved_example,
+        resolved_pattern,
+        resolved_choices,
+    )
+
+
+def _build_add_request(
+    *,
+    key: str,
+    value: str,
+    type_: str | None,
+    required: bool,
+    optional: bool,
+    sensitive: bool,
+    non_sensitive: bool,
+    interactive: bool,
+    description: str | None,
+    default: str | None,
+    example: str | None,
+    pattern: str | None,
+    choice: list[str] | None,
+) -> AddVariableRequest:
+    """Build the add request payload."""
+    override_required = _resolve_required(required, optional)
+    override_sensitive = _resolve_sensitive(sensitive, non_sensitive)
+
+    resolved_type = type_
+    resolved_description = description
+    resolved_default = default
+    resolved_example = example
+    resolved_pattern = pattern
+    resolved_choice = choice or []
+
+    if interactive:
+        (
+            resolved_type,
+            resolved_description,
+            override_required,
+            override_sensitive,
+            resolved_default,
+            resolved_example,
+            resolved_pattern,
+            resolved_choice,
+        ) = _collect_interactive_overrides(
+            type_=type_,
+            description=description,
+            override_required=override_required,
+            override_sensitive=override_sensitive,
+            default=default,
+            example=example,
+            pattern=pattern,
+            choice=choice,
+        )
+
+    return AddVariableRequest(
+        key=key,
+        value=value,
+        override_type=resolved_type,
+        override_required=override_required,
+        override_sensitive=override_sensitive,
+        override_description=resolved_description,
+        override_default=resolved_default or None,
+        override_example=resolved_example or None,
+        override_pattern=resolved_pattern or None,
+        override_choices=tuple(resolved_choice),
+    )
+
+
+def _render_inferred_spec(inferred_spec: dict[str, object] | None) -> None:
+    """Render inferred metadata details when present."""
+    if inferred_spec is None:
+        return
+
+    if "type" in inferred_spec:
+        print_kv("inferred_type", str(inferred_spec["type"]))
+    if "required" in inferred_spec:
+        print_kv("required", "yes" if inferred_spec["required"] else "no")
+    if "sensitive" in inferred_spec:
+        print_kv("sensitive", "yes" if inferred_spec["sensitive"] else "no")
+    if "description" in inferred_spec:
+        print_kv("description", str(inferred_spec["description"]))
+
+    print_warning("Review .envctl.schema.yaml to confirm the inferred metadata.")
+
+
+@handle_errors
+@requires_writable_runtime("add")
+@text_output_only("add")
+def add_command(
+    key: str = KEY_ARGUMENT,
+    value: str = VALUE_ARGUMENT,
+    type_: str | None = TYPE_OPTION,
+    required: bool = REQUIRED_OPTION,
+    optional: bool = OPTIONAL_OPTION,
+    sensitive: bool = SENSITIVE_OPTION,
+    non_sensitive: bool = NON_SENSITIVE_OPTION,
+    interactive: bool = INTERACTIVE_OPTION,
+    description: str | None = DESCRIPTION_OPTION,
+    default: str | None = DEFAULT_OPTION,
+    example: str | None = EXAMPLE_OPTION,
+    pattern: str | None = PATTERN_OPTION,
+    choice: list[str] | None = CHOICE_OPTION,
+) -> None:
+    """Add one variable to the contract and store its initial value in the active profile."""
+    request = _build_add_request(
+        key=key,
+        value=value,
+        type_=type_,
+        required=required,
+        optional=optional,
+        sensitive=sensitive,
+        non_sensitive=non_sensitive,
+        interactive=interactive,
+        description=description,
+        default=default,
+        example=example,
+        pattern=pattern,
+        choice=choice,
+    )
+
+    context, result = run_add(request, get_active_profile())
+
+    print_success(f"Added '{key}' to contract and profile '{result.active_profile}'")
+    print_kv("profile", result.active_profile)
+    print_kv("vault_values", str(result.profile_path))
+    print_kv("contract", str(context.repo_contract_path))
+
+    if result.contract_created:
+        print_kv("contract_created", "yes")
+    if result.contract_updated:
+        print_kv("contract_updated", "yes")
+    if result.contract_entry_created:
+        print_kv("contract_entry_created", "yes")
+
+    _render_inferred_spec(result.inferred_spec)

envctl/cli/commands/check/__init__.py

@@ -0,0 +1,5 @@
+"""Check command package."""
+
+from envctl.cli.commands.check.command import check_command
+
+__all__ = ["check_command"]

envctl/cli/commands/check/command.py

@@ -0,0 +1,49 @@
+"""Check command."""
+
+from __future__ import annotations
+
+import typer
+
+from envctl.cli.decorators import handle_errors
+from envctl.cli.formatters import render_resolution
+from envctl.cli.runtime import get_active_profile, is_json_output
+from envctl.cli.serializers import emit_json, serialize_project_context, serialize_resolution_report
+from envctl.services.check_service import run_check
+from envctl.utils.output import print_kv, print_success, print_warning
+
+
+@handle_errors
+def check_command() -> None:
+    """Validate the current project environment against the contract."""
+    context, active_profile, report = run_check(get_active_profile())
+
+    if is_json_output():
+        ok = report.is_valid and not report.unknown_keys
+        emit_json(
+            {
+                "ok": ok,
+                "command": "check",
+                "data": {
+                    "active_profile": active_profile,
+                    "context": serialize_project_context(context),
+                    "report": serialize_resolution_report(report),
+                },
+            }
+        )
+        if not ok:
+            raise typer.Exit(code=1)
+        return
+
+    print_kv("profile", active_profile)
+    typer.echo()
+    render_resolution(report)
+
+    if report.is_valid and not report.unknown_keys:
+        print_success("Environment contract satisfied")
+        return
+
+    if report.is_valid:
+        print_warning("Environment is valid, but the vault contains unknown keys")
+        raise typer.Exit(code=1)
+
+    raise typer.Exit(code=1)

envctl/cli/commands/config/__init__.py

@@ -0,0 +1,5 @@
+"""Config command package."""
+
+from envctl.cli.commands.config.app import config_app
+
+__all__ = ["config_app"]

envctl/cli/commands/config/app.py

@@ -0,0 +1,22 @@
+"""Config commands."""
+
+from __future__ import annotations
+
+import typer
+
+from envctl.cli.decorators import handle_errors, requires_writable_runtime, text_output_only
+from envctl.services.config_service import run_config_init
+from envctl.utils.output import print_kv, print_success
+
+config_app = typer.Typer(help="Manage envctl configuration.")
+
+
+@config_app.command("init")
+@handle_errors
+@requires_writable_runtime("config init")
+@text_output_only("config init")
+def config_init() -> None:
+    """Create the default envctl config file."""
+    config_path = run_config_init()
+    print_success("Created envctl config file")
+    print_kv("config", str(config_path))

envctl/cli/commands/doctor/__init__.py

@@ -0,0 +1,5 @@
+"""Doctor command package."""
+
+from envctl.cli.commands.doctor.command import doctor_command
+
+__all__ = ["doctor_command"]