envshield 4.7.0__tar.gz → 4.7.1__tar.gz

{envshield-4.7.0 → envshield-4.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: envshield
-Version: 4.7.0
+Version: 4.7.1
 Summary: EnvShield: environment variables as a version-controlled configuration contract.
 Author-email: Rabbil Yasar Sajal <rabbilyasar@gmail.com>
 License: MIT License
@@ -427,6 +427,24 @@ A supporting check alongside the contract, not the product itself. `secret = tru
 
 ---
 
+## Removing EnvShield
+
+```bash
+envshield uninstall
+```
+
+Removes EnvShield's Git hook integration while preserving your project configuration — it does not delete `envshield.yml`, any `env.schema.toml`, `.env.example`, any registered local configuration file (`.env`, a Python config module, etc.), `.gitignore`, or any code `envshield generate` has produced, regardless of whether EnvShield originally created any of it. Those are your project's own configuration contract and application config, not disposable installation artifacts.
+
+The only thing `uninstall` ever deletes is a Git hook whose content exactly matches what EnvShield would generate right now — the same ownership rule `hook remove` already uses. A hand-modified hook, a foreign hook (even one that happens to contain EnvShield's marker comment), or an EnvShield hook that's gone stale relative to your current `envshield.yml` (e.g. after registering a new service) is left in place and reported, never deleted or silently regenerated.
+
+```bash
+envshield uninstall --yes    # skip the confirmation prompt
+```
+
+`--yes` only skips the prompt — it never overrides the ownership check; a modified, foreign, or stale hook is preserved with `--yes` exactly as it is interactively. There is no `--force` and no `--purge`: `uninstall` is intentionally not a "delete everything EnvShield ever created" command. To remove EnvShield's configuration from a project entirely, delete `envshield.yml` and the schema files yourself once you're sure you no longer need them.
+
+---
+
 ## Known limitations
 
 EnvShield is built around the patterns real projects actually use. A few narrower cases aren't handled yet — none of them let a secret leak or let a genuinely missing required variable pass as clean:

{envshield-4.7.0 → envshield-4.7.1}/README.md

@@ -368,6 +368,24 @@ A supporting check alongside the contract, not the product itself. `secret = tru
 
 ---
 
+## Removing EnvShield
+
+```bash
+envshield uninstall
+```
+
+Removes EnvShield's Git hook integration while preserving your project configuration — it does not delete `envshield.yml`, any `env.schema.toml`, `.env.example`, any registered local configuration file (`.env`, a Python config module, etc.), `.gitignore`, or any code `envshield generate` has produced, regardless of whether EnvShield originally created any of it. Those are your project's own configuration contract and application config, not disposable installation artifacts.
+
+The only thing `uninstall` ever deletes is a Git hook whose content exactly matches what EnvShield would generate right now — the same ownership rule `hook remove` already uses. A hand-modified hook, a foreign hook (even one that happens to contain EnvShield's marker comment), or an EnvShield hook that's gone stale relative to your current `envshield.yml` (e.g. after registering a new service) is left in place and reported, never deleted or silently regenerated.
+
+```bash
+envshield uninstall --yes    # skip the confirmation prompt
+```
+
+`--yes` only skips the prompt — it never overrides the ownership check; a modified, foreign, or stale hook is preserved with `--yes` exactly as it is interactively. There is no `--force` and no `--purge`: `uninstall` is intentionally not a "delete everything EnvShield ever created" command. To remove EnvShield's configuration from a project entirely, delete `envshield.yml` and the schema files yourself once you're sure you no longer need them.
+
+---
+
 ## Known limitations
 
 EnvShield is built around the patterns real projects actually use. A few narrower cases aren't handled yet — none of them let a secret leak or let a genuinely missing required variable pass as clean:

envshield-4.7.1/envshield/__init__.py

@@ -0,0 +1 @@
+__version__ = "4.7.1"

{envshield-4.7.0 → envshield-4.7.1}/envshield/cli.py

@@ -1855,11 +1855,12 @@ def hook_remove(
         console.print("[yellow]Cancelled.[/yellow]")
         raise typer.Exit()
     try:
-        removed = scanner.remove_hooks()
+        results = scanner.remove_hooks()
     except EnvShieldException as e:
         console.print(f"[bold red]Error:[/bold red] {e}")
         raise typer.Exit(code=1)
 
+    removed = [r["name"] for r in results if r["status"] == "removed"]
     if not removed:
         console.print("[yellow]No EnvShield-installed hooks found to remove.[/yellow]")
         return
@@ -1867,6 +1868,125 @@ def hook_remove(
         console.print(f"[bold green]✓[/bold green] Removed {hook_name} hook.")
 
 
+@app.command()
+def uninstall(
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Skip the confirmation prompt."
+    ),
+):
+    """
+    Removes EnvShield's Git hook integration from this project.
+
+    Only ever deletes a hook file whose content exactly matches what
+    EnvShield would generate right now -- the same ownership standard
+    'hook remove' already uses. A hand-modified hook, a foreign hook, or
+    an EnvShield hook that's gone stale relative to your current
+    envshield.yml (e.g. after registering a new service) is left alone
+    and reported, never deleted.
+
+    Never touches project configuration -- envshield.yml, any
+    env.schema.toml, .env.example, or any registered local configuration
+    file are always preserved and reported, never removed. This is not a
+    "delete everything EnvShield ever created" command.
+    """
+    if not _confirm_hook_action(
+        "EnvShield will remove Git hooks that are verified as EnvShield-owned.\n"
+        "Project configuration and schema files will be preserved.\n\n"
+        "Continue?",
+        yes,
+    ):
+        console.print("[yellow]Cancelled.[/yellow]")
+        raise typer.Exit()
+
+    console.print("\n[bold]EnvShield uninstall[/bold]\n")
+
+    try:
+        hook_results = scanner.remove_hooks()
+    except EnvShieldException:
+        # No Git repository -- there are no hooks to remove, which isn't
+        # an error condition for a project-level uninstall the way it is
+        # for 'hook remove' (a command that only ever makes sense inside
+        # one). Continue on to reporting project configuration.
+        hook_results = []
+
+    # Reused, not re-derived: 'remove_hooks()' already resolves this same
+    # directory (respecting a configured 'core.hooksPath', e.g. Husky) to
+    # decide where to look/delete -- the report must name that same real
+    # location, never a hardcoded '.git/hooks/' that could be wrong.
+    # 'get_hooks_dir()' always returns an absolute path; displaying it
+    # relative to the current directory (when possible) is purely
+    # cosmetic -- it keeps the common case reading exactly as it always
+    # has, and avoids Rich hard-wrapping a long absolute path mid-string.
+    hooks_dir = git_utils.get_hooks_dir()
+    if hooks_dir:
+        try:
+            hooks_dir = os.path.relpath(hooks_dir, os.getcwd())
+        except ValueError:
+            pass
+    else:
+        hooks_dir = os.path.join(".git", "hooks")
+
+    removed_names = [r["name"] for r in hook_results if r["status"] == "removed"]
+    preserved_hooks = [r for r in hook_results if r["status"] == "preserved"]
+
+    if removed_names:
+        console.print("[bold]Removed:[/bold]")
+        for hook_name in removed_names:
+            console.print(
+                f"  [bold green]✓[/bold green] {os.path.join(hooks_dir, hook_name)}"
+            )
+        console.print()
+    else:
+        console.print(
+            "[yellow]Nothing to remove -- no safely-owned EnvShield hooks were found.[/yellow]\n"
+        )
+
+    # Everything below is report-only -- uninstall never deletes or
+    # modifies any of it, regardless of whether EnvShield originally
+    # created it (envshield.yml, a schema, .env.example) or only ever
+    # populated it (a registered local_file, which may hold real secret
+    # values and is never "EnvShield's own" to reclaim).
+    preserved_lines = []
+    for r in preserved_hooks:
+        preserved_lines.append(
+            (
+                os.path.join(hooks_dir, r["name"]),
+                "hook contents do not exactly match what EnvShield would "
+                "generate now -- hand-modified, foreign, or stale relative "
+                "to your current config",
+            )
+        )
+
+    if os.path.exists(config_manager.CONFIG_FILE_NAME):
+        preserved_lines.append(
+            (config_manager.CONFIG_FILE_NAME, "project configuration")
+        )
+
+    for service_name in config_manager.get_services():
+        schema_path = config_manager.get_service_schema_path(service_name)
+        if schema_path and os.path.exists(schema_path):
+            preserved_lines.append((schema_path, "project configuration"))
+
+        paths = config_manager.get_env_paths(service_name)
+        if os.path.exists(paths["example_file"]):
+            preserved_lines.append((paths["example_file"], "preserved"))
+        if os.path.exists(paths["local_file"]):
+            preserved_lines.append((paths["local_file"], "application configuration"))
+
+    if preserved_lines:
+        console.print("[bold]Preserved:[/bold]")
+        for path, reason in preserved_lines:
+            console.print(f"  • {path} -- {reason}")
+        console.print()
+
+    if removed_names:
+        console.print(
+            "[bold green]EnvShield Git hook integration removed safely.[/bold green]"
+        )
+    if preserved_lines:
+        console.print("Project configuration was preserved.")
+
+
 @app.command(name="import")
 def import_command(
     file: str = typer.Argument(

{envshield-4.7.0 → envshield-4.7.1}/envshield/core/hooks_manager.py

@@ -122,6 +122,14 @@ class HooksManager:
     def _do_install_hooks(self, force: bool = False) -> None:
         """Actually install the hooks (called after user confirms).
 
+        Only installs whichever hook(s) are actually missing -- an
+        already-present hook must not be touched (and re-prompted for its
+        own separate overwrite confirmation) merely because the OTHER hook
+        needed installing. `prompt_install_hooks`'s own "Install git
+        hooks? (...)" prompt already tells the user which hook(s) are
+        about to be installed; installing an unrelated, already-present
+        one here would silently do more than that prompt described.
+
         Args:
             force: If True, overwrite existing hooks.
         """
@@ -129,8 +137,11 @@ class HooksManager:
             # Import here to avoid circular imports
             from . import scanner
 
-            scanner.install_pre_commit_hook(force=force, non_interactive=False)
-            scanner.install_post_merge_hook(force=force, non_interactive=False)
+            pre_commit, post_merge = self.are_hooks_installed()
+            if not pre_commit:
+                scanner.install_pre_commit_hook(force=force, non_interactive=False)
+            if not post_merge:
+                scanner.install_post_merge_hook(force=force, non_interactive=False)
         except EnvShieldException as e:
             console.print(f"[bold yellow]⚠️  Warning:[/] {e}")
 

{envshield-4.7.0 → envshield-4.7.1}/envshield/core/scanner.py

@@ -890,39 +890,70 @@ def scan_result(
 ENVSHIELD_HOOK_MARKER = "# Hook installed by EnvShield"
 
 
-def remove_hooks() -> List[str]:
+def remove_hooks() -> List[Dict[str, str]]:
     """
-    Removes any EnvShield-installed Git hook (pre-commit, post-merge),
-    identified by the same '# Hook installed by EnvShield' marker `install`
-    already checks before offering to overwrite -- a hook that isn't
-    EnvShield's is left alone rather than deleted out from under whatever
-    else manages it (Husky, a hand-written script, etc.).
-
-    Returns the names of the hooks actually removed.
+    Removes only a hook file EnvShield can prove is its own, unmodified
+    output -- an exact content match against what EnvShield would generate
+    right now, the same ownership standard install_pre_commit_hook/
+    install_post_merge_hook already use (see their own comment: the marker
+    comment alone is not proof of ownership -- a user can modify a
+    generated hook, or hand-write one containing the same comment, while
+    keeping the marker text intact). A hook that isn't provably
+    EnvShield's own unmodified output is left alone -- whether it's
+    genuinely foreign (Husky, a hand-written script) or an EnvShield hook
+    a user has since extended.
+
+    Returns one {"name": ..., "status": ...} entry per hook type EnvShield
+    manages (pre-commit, post-merge), regardless of outcome -- "removed"
+    (deleted, exact match), "preserved" (a file exists but its content
+    doesn't exactly match current generated output -- hand-modified,
+    foreign, or stale relative to the current config), or "missing" (no
+    file at that path). This is the single source of truth for hook
+    ownership; 'hook remove' filters for "removed", 'uninstall' also
+    reports "preserved" -- neither re-derives the ownership check itself.
     """
     git_root = git_utils.get_git_root()
     if not git_root:
         raise EnvShieldException("Not inside a Git repository.")
 
     hooks_dir = git_utils.get_hooks_dir()
-    removed = []
-    for hook_name in ("pre-commit", "post-merge"):
+    generators = {
+        "pre-commit": _generate_pre_commit_hook_content,
+        "post-merge": _generate_post_merge_hook_content,
+    }
+    results = []
+    for hook_name, generate_content in generators.items():
         hook_path = os.path.join(hooks_dir, hook_name)
         if not os.path.exists(hook_path):
+            results.append({"name": hook_name, "status": "missing"})
             continue
         with open(hook_path, "r") as f:
             content = f.read()
-        if ENVSHIELD_HOOK_MARKER not in content:
+        if content != generate_content():
+            results.append({"name": hook_name, "status": "preserved"})
             continue
         os.remove(hook_path)
-        removed.append(hook_name)
-    return removed
+        results.append({"name": hook_name, "status": "removed"})
+    return results
 
 
-def _describe_existing_hook(content: str) -> str:
-    """Best-effort description of an existing hook file, for the overwrite warning."""
-    if ENVSHIELD_HOOK_MARKER in content:
+def _describe_existing_hook(content: str, is_safely_regeneratable: bool) -> str:
+    """
+    Best-effort description of an existing hook file, for the overwrite
+    warning. `is_safely_regeneratable` is an exact-content match against
+    what EnvShield would generate right now -- the marker comment alone is
+    not proof of that (see the call site's own comment): a user can modify
+    a generated hook, or hand-write one, while keeping the marker text
+    intact.
+    """
+    if is_safely_regeneratable:
         return "previously installed by EnvShield -- safe to regenerate"
+    if ENVSHIELD_HOOK_MARKER in content:
+        return (
+            "previously installed by EnvShield, but its contents no longer match "
+            "what EnvShield would generate now (hand-edited, or stale relative to "
+            "your current config) -- overwriting could discard those changes"
+        )
     if "husky.sh" in content or ".husky" in content:
         return "managed by Husky"
     non_comment_lines = [
@@ -1056,10 +1087,18 @@ def install_pre_commit_hook(force: bool = False, non_interactive: bool = False):
             with open(pre_commit_path, "r") as f:
                 existing_content = f.read()
 
-            # Regenerating EnvShield's own hook is always safe -- non-interactive
-            # mode only needs to hold back from a genuinely foreign one, not
-            # bail out on every re-run just because the file already exists.
-            if non_interactive and ENVSHIELD_HOOK_MARKER not in existing_content:
+            # A marker comment alone is not proof this file is EnvShield's own,
+            # untouched output -- a user can modify a generated hook (or
+            # hand-write one containing the same comment) while keeping the
+            # marker text intact. Only an exact match against what EnvShield
+            # would generate right now is provably safe to replace without
+            # asking; non-interactive mode's fast path is scoped to exactly
+            # that case -- anything else (including a marker-bearing file
+            # that no longer matches) falls through to the same protected
+            # confirmation/warning path as a genuinely foreign hook.
+            is_safely_regeneratable = existing_content == hook_script_content
+
+            if non_interactive and not is_safely_regeneratable:
                 console.print(
                     "[bold yellow]⚠️  Warning:[/] A pre-commit hook already exists. EnvShield was not installed automatically."
                 )
@@ -1070,7 +1109,7 @@ def install_pre_commit_hook(force: bool = False, non_interactive: bool = False):
 
             if not force and not non_interactive:
                 overwrite = questionary.confirm(
-                    f"A pre-commit hook already exists ({_describe_existing_hook(existing_content)}). Do you want to overwrite it?",
+                    f"A pre-commit hook already exists ({_describe_existing_hook(existing_content, is_safely_regeneratable)}). Do you want to overwrite it?",
                     default=False,
                 ).ask()
                 if not overwrite:
@@ -1179,10 +1218,13 @@ def install_post_merge_hook(force: bool = False, non_interactive: bool = False):
             with open(post_merge_path, "r") as f:
                 existing_content = f.read()
 
-            # Regenerating EnvShield's own hook is always safe -- non-interactive
-            # mode only needs to hold back from a genuinely foreign one, not
-            # bail out on every re-run just because the file already exists.
-            if non_interactive and ENVSHIELD_HOOK_MARKER not in existing_content:
+            # See install_pre_commit_hook's identical comment: a marker
+            # comment alone is not proof this file is EnvShield's own,
+            # untouched output. Only an exact match against what EnvShield
+            # would generate right now is treated as provably safe.
+            is_safely_regeneratable = existing_content == hook_script_content
+
+            if non_interactive and not is_safely_regeneratable:
                 console.print(
                     "[bold yellow]⚠️  Warning:[/] A post-merge hook already exists. EnvShield was not installed automatically."
                 )
@@ -1193,7 +1235,7 @@ def install_post_merge_hook(force: bool = False, non_interactive: bool = False):
 
             if not force and not non_interactive:
                 overwrite = questionary.confirm(
-                    f"A post-merge hook already exists ({_describe_existing_hook(existing_content)}). Do you want to overwrite it?",
+                    f"A post-merge hook already exists ({_describe_existing_hook(existing_content, is_safely_regeneratable)}). Do you want to overwrite it?",
                     default=False,
                 ).ask()
                 if not overwrite:

{envshield-4.7.0 → envshield-4.7.1}/envshield.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: envshield
-Version: 4.7.0
+Version: 4.7.1
 Summary: EnvShield: environment variables as a version-controlled configuration contract.
 Author-email: Rabbil Yasar Sajal <rabbilyasar@gmail.com>
 License: MIT License
@@ -427,6 +427,24 @@ A supporting check alongside the contract, not the product itself. `secret = tru
 
 ---
 
+## Removing EnvShield
+
+```bash
+envshield uninstall
+```
+
+Removes EnvShield's Git hook integration while preserving your project configuration — it does not delete `envshield.yml`, any `env.schema.toml`, `.env.example`, any registered local configuration file (`.env`, a Python config module, etc.), `.gitignore`, or any code `envshield generate` has produced, regardless of whether EnvShield originally created any of it. Those are your project's own configuration contract and application config, not disposable installation artifacts.
+
+The only thing `uninstall` ever deletes is a Git hook whose content exactly matches what EnvShield would generate right now — the same ownership rule `hook remove` already uses. A hand-modified hook, a foreign hook (even one that happens to contain EnvShield's marker comment), or an EnvShield hook that's gone stale relative to your current `envshield.yml` (e.g. after registering a new service) is left in place and reported, never deleted or silently regenerated.
+
+```bash
+envshield uninstall --yes    # skip the confirmation prompt
+```
+
+`--yes` only skips the prompt — it never overrides the ownership check; a modified, foreign, or stale hook is preserved with `--yes` exactly as it is interactively. There is no `--force` and no `--purge`: `uninstall` is intentionally not a "delete everything EnvShield ever created" command. To remove EnvShield's configuration from a project entirely, delete `envshield.yml` and the schema files yourself once you're sure you no longer need them.
+
+---
+
 ## Known limitations
 
 EnvShield is built around the patterns real projects actually use. A few narrower cases aren't handled yet — none of them let a secret leak or let a genuinely missing required variable pass as clean:

{envshield-4.7.0 → envshield-4.7.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "envshield"
-version = "4.7.0"  # must be a string for PEP 621 compliance
+version = "4.7.1"  # must be a string for PEP 621 compliance
 description = "EnvShield: environment variables as a version-controlled configuration contract."
 readme = "README.md"
 requires-python = ">=3.10"

envshield-4.7.0/envshield/__init__.py

@@ -1 +0,0 @@
-__version__ = "4.7.0"