envshield 4.7.3__tar.gz → 4.7.4__tar.gz

{envshield-4.7.3 → envshield-4.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: envshield
-Version: 4.7.3
+Version: 4.7.4
 Summary: EnvShield: environment variables as a version-controlled configuration contract.
 Author-email: Rabbil Yasar Sajal <rabbilyasar@gmail.com>
 License: MIT License
@@ -270,7 +270,7 @@ Every command above documents its own options with `--help`; the full reference
 
 ## Git / CI workflow
 
-This is where the schema stops being documentation and starts being enforcement. Three concrete things EnvShield catches in a PR:
+This is where the schema stops being documentation and starts being enforcement. Three concrete things EnvShield catches before a change reaches production:
 
 **A new environment variable used in code but missing from the schema:**
 
@@ -284,12 +284,14 @@ envshield undeclared origin/main HEAD --service api
 envshield schema diff origin/main HEAD --service api
 ```
 
-**A secret accidentally introduced into a commit** — the pre-commit hook runs `scan --staged` automatically:
+**A secret accidentally introduced into a commit:**
 
 ```bash
 envshield hook install
 ```
 
+The pre-commit hook runs `scan --staged --enforce`, applying classification-based enforcement with interactive override for high-confidence findings on local commits, and strict blocking in CI. See [Secret safety](#secret-safety) for enforcement behavior details.
+
 In CI, diff against the merge-base, not the base branch's current tip (which can move while the PR is open):
 
 ```yaml
@@ -466,10 +468,84 @@ Source-code discovery (what powers `undeclared` and `explain`'s "used in source"
 
 ## Secret safety
 
-A supporting check alongside the contract, not the product itself. `secret = true` on a field tells EnvShield (and `setup`, and code generation) that it's sensitive — the schema records that fact, never the actual value. On top of that:
+A supporting check alongside the contract, not the product itself. `secret = true` on a field tells EnvShield (and `setup`, and code generation) that it's sensitive — the schema records that fact, never the actual value.
+
+### Secret scanning
+
+**`envshield scan`** looks for hardcoded secrets by pattern (Stripe, AWS, GitHub tokens, and more), and for env-var reads the schema doesn't declare, in one pass. Values are always redacted in output — a Stripe *publishable* key (`pk_...`) is never flagged, since detection matches the secret-key pattern (`sk_...`) by shape, not the variable's name.
+
+### Context-aware classification
+
+Python candidates are analyzed for syntactic context to distinguish code patterns from secret values:
+
+```python
+# Classified as code (suppressed):
+client(key=CONFIG_CONSTANT)
+
+
+def handler(api_key: str): ...
+
+
+# Classified as likely secret (detected):
+client(key="sk_live_abc123...")
+```
+
+This reduces false positives on ordinary code patterns without broadly suppressing secret-shaped values. Classification is lightweight and syntactic — it recognizes type annotations, function arguments, and identifier references, but doesn't perform semantic analysis beyond what the tokenizer can see.
+
+### Git hook enforcement
+
+**`envshield hook install`** wires secret scanning into your Git workflow with classification-based enforcement:
+
+```bash
+envshield hook install
+```
+
+The pre-commit hook runs `scan --staged --enforce`, which scans only staged content and applies an enforcement policy based on classification confidence.
+
+#### Enforcement behavior
+
+| Finding type | Interactive (local commit) | Non-interactive (CI) |
+|---|---|---|
+| No findings | Allow | Allow |
+| Clearly code-shaped | Suppressed | Suppressed |
+| Ambiguous | Block | Block |
+| High-confidence secret | Block + explicit override | Block |
+
+**Clearly code-shaped** candidates (type annotations, function keyword arguments, etc.) are suppressed by the classifier and don't produce findings.
+
+**Ambiguous** findings — insufficient context to confidently classify — block without override in both modes.
+
+**High-confidence secrets** (string literals matching secret patterns) block by default but offer an interactive override for local commits:
+
+```
+⚠ EnvShield found potential secrets
+
+HIGH CONFIDENCE
+  src/config.py:42    Generic API Key    [REDACTED (30 chars)]
+
+[1] Abort commit
+[2] Commit anyway
+
+Choice: 2
+
+Type COMMIT ANYWAY to confirm: COMMIT ANYWAY
+
+Proceeding with commit. The finding remains in the repository history.
+```
+
+The override requires exact confirmation text — `yes` or `Y` won't work. EOF (Ctrl+D) or Ctrl+C aborts. Raw secret values are never displayed in enforcement output.
+
+In CI or other non-interactive contexts, high-confidence findings block with no prompt — the commit is refused, and the scan exits non-zero.
+
+#### Scanning modes
+
+```bash
+envshield scan                      # Audit entire codebase
+envshield scan --staged             # Scan only staged Git content
+envshield scan --staged --enforce   # Staged scan + enforcement policy
+```
 
-- **`envshield scan`** looks for hardcoded secrets by pattern (Stripe, AWS, GitHub tokens, and more), and for env-var reads the schema doesn't declare, in one pass. Values are always redacted in output — a Stripe *publishable* key (`pk_...`) is never flagged, since detection matches the secret-key pattern (`sk_...`) by shape, not the variable's name. Python candidates are context-aware: code-shaped patterns like `key=CONSTANT` or `api_key: str` may be suppressed when they're clearly not secret values, while secret-shaped string literals remain detectable regardless of context.
-- **`envshield hook install`** wires `scan --staged` into a pre-commit hook, so a real secret is caught before it's committed, not after.
+The pre-commit hook uses the third form. `scan` without flags is for repository-wide audits, not commit-time enforcement.
 
 ---
 

{envshield-4.7.3 → envshield-4.7.4}/README.md

@@ -211,7 +211,7 @@ Every command above documents its own options with `--help`; the full reference
 
 ## Git / CI workflow
 
-This is where the schema stops being documentation and starts being enforcement. Three concrete things EnvShield catches in a PR:
+This is where the schema stops being documentation and starts being enforcement. Three concrete things EnvShield catches before a change reaches production:
 
 **A new environment variable used in code but missing from the schema:**
 
@@ -225,12 +225,14 @@ envshield undeclared origin/main HEAD --service api
 envshield schema diff origin/main HEAD --service api
 ```
 
-**A secret accidentally introduced into a commit** — the pre-commit hook runs `scan --staged` automatically:
+**A secret accidentally introduced into a commit:**
 
 ```bash
 envshield hook install
 ```
 
+The pre-commit hook runs `scan --staged --enforce`, applying classification-based enforcement with interactive override for high-confidence findings on local commits, and strict blocking in CI. See [Secret safety](#secret-safety) for enforcement behavior details.
+
 In CI, diff against the merge-base, not the base branch's current tip (which can move while the PR is open):
 
 ```yaml
@@ -407,10 +409,84 @@ Source-code discovery (what powers `undeclared` and `explain`'s "used in source"
 
 ## Secret safety
 
-A supporting check alongside the contract, not the product itself. `secret = true` on a field tells EnvShield (and `setup`, and code generation) that it's sensitive — the schema records that fact, never the actual value. On top of that:
+A supporting check alongside the contract, not the product itself. `secret = true` on a field tells EnvShield (and `setup`, and code generation) that it's sensitive — the schema records that fact, never the actual value.
+
+### Secret scanning
+
+**`envshield scan`** looks for hardcoded secrets by pattern (Stripe, AWS, GitHub tokens, and more), and for env-var reads the schema doesn't declare, in one pass. Values are always redacted in output — a Stripe *publishable* key (`pk_...`) is never flagged, since detection matches the secret-key pattern (`sk_...`) by shape, not the variable's name.
+
+### Context-aware classification
+
+Python candidates are analyzed for syntactic context to distinguish code patterns from secret values:
+
+```python
+# Classified as code (suppressed):
+client(key=CONFIG_CONSTANT)
+
+
+def handler(api_key: str): ...
+
+
+# Classified as likely secret (detected):
+client(key="sk_live_abc123...")
+```
+
+This reduces false positives on ordinary code patterns without broadly suppressing secret-shaped values. Classification is lightweight and syntactic — it recognizes type annotations, function arguments, and identifier references, but doesn't perform semantic analysis beyond what the tokenizer can see.
+
+### Git hook enforcement
+
+**`envshield hook install`** wires secret scanning into your Git workflow with classification-based enforcement:
+
+```bash
+envshield hook install
+```
+
+The pre-commit hook runs `scan --staged --enforce`, which scans only staged content and applies an enforcement policy based on classification confidence.
+
+#### Enforcement behavior
+
+| Finding type | Interactive (local commit) | Non-interactive (CI) |
+|---|---|---|
+| No findings | Allow | Allow |
+| Clearly code-shaped | Suppressed | Suppressed |
+| Ambiguous | Block | Block |
+| High-confidence secret | Block + explicit override | Block |
+
+**Clearly code-shaped** candidates (type annotations, function keyword arguments, etc.) are suppressed by the classifier and don't produce findings.
+
+**Ambiguous** findings — insufficient context to confidently classify — block without override in both modes.
+
+**High-confidence secrets** (string literals matching secret patterns) block by default but offer an interactive override for local commits:
+
+```
+⚠ EnvShield found potential secrets
+
+HIGH CONFIDENCE
+  src/config.py:42    Generic API Key    [REDACTED (30 chars)]
+
+[1] Abort commit
+[2] Commit anyway
+
+Choice: 2
+
+Type COMMIT ANYWAY to confirm: COMMIT ANYWAY
+
+Proceeding with commit. The finding remains in the repository history.
+```
+
+The override requires exact confirmation text — `yes` or `Y` won't work. EOF (Ctrl+D) or Ctrl+C aborts. Raw secret values are never displayed in enforcement output.
+
+In CI or other non-interactive contexts, high-confidence findings block with no prompt — the commit is refused, and the scan exits non-zero.
+
+#### Scanning modes
+
+```bash
+envshield scan                      # Audit entire codebase
+envshield scan --staged             # Scan only staged Git content
+envshield scan --staged --enforce   # Staged scan + enforcement policy
+```
 
-- **`envshield scan`** looks for hardcoded secrets by pattern (Stripe, AWS, GitHub tokens, and more), and for env-var reads the schema doesn't declare, in one pass. Values are always redacted in output — a Stripe *publishable* key (`pk_...`) is never flagged, since detection matches the secret-key pattern (`sk_...`) by shape, not the variable's name. Python candidates are context-aware: code-shaped patterns like `key=CONSTANT` or `api_key: str` may be suppressed when they're clearly not secret values, while secret-shaped string literals remain detectable regardless of context.
-- **`envshield hook install`** wires `scan --staged` into a pre-commit hook, so a real secret is caught before it's committed, not after.
+The pre-commit hook uses the third form. `scan` without flags is for repository-wide audits, not commit-time enforcement.
 
 ---
 

envshield-4.7.4/envshield/__init__.py

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

{envshield-4.7.3 → envshield-4.7.4}/envshield/cli.py

@@ -1128,6 +1128,12 @@ def _render_dependency_change_table(
         console.print(
             "\n[bold red]New source dependencies are missing from the contract.[/bold red]"
         )
+        console.print(
+            "[bold]Suggestion:[/bold] Review these -- not every read belongs "
+            "in the contract. For the ones that do, add them to "
+            "'env.schema.toml' (hand-edited, not generated). Re-run "
+            "'envshield undeclared' to confirm."
+        )
 
 
 def _print_dependency_error(

{envshield-4.7.3 → envshield-4.7.4}/envshield/config/manager.py

@@ -437,6 +437,22 @@ def add_service(
         entry["config_source"] = config_source
     services[name] = entry
 
+    if (
+        entry.get("local_file")
+        and not entry.get("example_file")
+        and not entry["local_file"].endswith(".py")
+        and os.path.basename(entry["local_file"]) != ".env"
+    ):
+        console.print(
+            f"[yellow]Note:[/yellow] service '{name}' overrides local_file to "
+            f"'{entry['local_file']}' but not example_file -- the template "
+            "will still default to '.env.example' in this service's "
+            "directory. If this local_file follows a different naming "
+            "convention (e.g. '.env.local' pairs with '.env.local.example'), "
+            "set example_file explicitly too, or Template Sync will look at "
+            "the wrong file."
+        )
+
     with open(CONFIG_FILE_NAME, "w") as f:
         yaml.dump(config, f, sort_keys=False, indent=2)
 

{envshield-4.7.3 → envshield-4.7.4}/envshield/core/hooks_manager.py

@@ -145,24 +145,70 @@ class HooksManager:
         except EnvShieldException as e:
             console.print(f"[bold yellow]⚠️  Warning:[/] {e}")
 
+    def _hook_status_line(
+        self, hooks_dir: str, filename: str, label: str, generator
+    ) -> str:
+        """
+        Describes one installed hook: missing, up to date, or stale --
+        present, and still carrying EnvShield's marker/shape, but no longer
+        byte-for-byte what EnvShield would generate right now (e.g. a
+        service was added to envshield.yml after this hook was installed,
+        so it's missing that service's block; or the file was hand-edited).
+
+        This is purely informational: unlike `are_hooks_installed` (used by
+        `hook install`/`uninstall`'s exact-match ownership check -- see
+        BL-119/BL-120), staleness here never gates or changes what those
+        commands do. A stale hook is not "not installed" -- it still runs
+        and still protects whatever it was generated to protect; this only
+        surfaces that it may no longer match the project's current config,
+        so nothing here needed to touch that exact-match safety invariant.
+        """
+        path = os.path.join(hooks_dir, filename)
+        if not os.path.exists(path):
+            return f"[dim]✗ {label}[/dim]"
+
+        try:
+            with open(path, "r") as f:
+                installed_content = f.read()
+        except OSError:
+            return f"[green]✓ {label}[/green]"
+
+        if installed_content == generator():
+            return f"[green]✓ {label}[/green]"
+
+        return (
+            f"[yellow]✓ {label} (stale -- doesn't match what EnvShield would "
+            "generate now; run 'envshield hook install --yes' to refresh)[/yellow]"
+        )
+
     def print_hook_status(self) -> None:
         """Print the current status of installed hooks."""
         if not self.git_root:
             console.print("[dim]Not in a git repository.[/dim]")
             return
 
-        pre_commit, post_merge = self.are_hooks_installed()
+        # Import here to avoid circular imports (same pattern as
+        # _do_install_hooks above).
+        from . import scanner
 
-        status = []
-        if pre_commit:
-            status.append("[green]✓ pre-commit hook[/green] (secret scanning)")
-        else:
-            status.append("[dim]✗ pre-commit hook[/dim]")
+        hooks_dir = git_utils.get_hooks_dir() or os.path.join(
+            self.git_root, ".git", "hooks"
+        )
 
-        if post_merge:
-            status.append("[green]✓ post-merge hook[/green] (config change detection)")
-        else:
-            status.append("[dim]✗ post-merge hook[/dim]")
+        status = [
+            self._hook_status_line(
+                hooks_dir,
+                "pre-commit",
+                "pre-commit hook (secret scanning)",
+                scanner._generate_pre_commit_hook_content,
+            ),
+            self._hook_status_line(
+                hooks_dir,
+                "post-merge",
+                "post-merge hook (config change detection)",
+                scanner._generate_post_merge_hook_content,
+            ),
+        ]
 
         console.print("\n[bold]Git Hooks:[/bold]")
         for s in status:

{envshield-4.7.3 → envshield-4.7.4}/envshield/core/scanner.py

@@ -1387,6 +1387,12 @@ def run_scan(
                         finding["variable_name"],
                     )
                 console.print(undeclared_table)
+                console.print(
+                    "\n[bold]Suggestion:[/bold] Review these -- not every read "
+                    "belongs in the contract. For the ones that do, add them to "
+                    "'env.schema.toml' (hand-edited, not generated), then re-stage "
+                    "and commit again."
+                )
 
             console.print(
                 "\n[bold red]Commit aborted. Please fix the issues above before committing.[/bold red]"
@@ -1438,7 +1444,10 @@ def run_scan(
             )
         console.print(undeclared_table)
         console.print(
-            "\n[bold]Suggestion:[/bold] Please add these variables to your 'env.schema.toml' to maintain your configuration contract."
+            "\n[bold]Suggestion:[/bold] Review these -- not every read belongs "
+            "in the contract. For the ones that do, add them to "
+            "'env.schema.toml' (hand-edited, not generated). Re-run "
+            "'envshield scan' to confirm."
         )
 
     # A skip means eligible content was never actually inspected -- this

{envshield-4.7.3 → envshield-4.7.4}/envshield/core/service_discovery.py

@@ -291,13 +291,30 @@ def detect_env_style(service_dir: str) -> Dict[str, Optional[str]]:
     ('<service_dir>/.env' / '<service_dir>/.env.example') -- i.e. for the
     python format, when the real dotenv file found isn't literally named
     '.env', or when only a template was found under a non-standard name.
+
+    When the real file isn't '.env' (e.g. Next.js's '.env.local'), its
+    paired template conventionally isn't '.env.example' either -- it's
+    '<real_file>.example' ('.env.local' -> '.env.local.example'). Without
+    checking for that file specifically, every downstream command
+    (doctor's Template Sync, 'schema sync', the pre-commit hook's
+    post-schema-change check) would keep resolving the untouched default
+    '.env.example' instead, reporting a real, in-sync template as missing.
+    This only sets `example_file` when that paired file is actually found
+    on disk -- evidence-gated, like the rest of this module's detection,
+    not guessed from the name alone.
     """
     real_file = _find_real_dotenv_file(service_dir)
     if real_file:
+        local_file = None if os.path.basename(real_file) == ".env" else real_file
+        example_file = None
+        if local_file:
+            paired_template = real_file + ".example"
+            if os.path.isfile(paired_template):
+                example_file = paired_template
         return {
             "format": "dotenv",
-            "local_file": None if os.path.basename(real_file) == ".env" else real_file,
-            "example_file": None,
+            "local_file": local_file,
+            "example_file": example_file,
         }
 
     template_file = _find_dotenv_template(service_dir)

{envshield-4.7.3 → envshield-4.7.4}/envshield.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: envshield
-Version: 4.7.3
+Version: 4.7.4
 Summary: EnvShield: environment variables as a version-controlled configuration contract.
 Author-email: Rabbil Yasar Sajal <rabbilyasar@gmail.com>
 License: MIT License
@@ -270,7 +270,7 @@ Every command above documents its own options with `--help`; the full reference
 
 ## Git / CI workflow
 
-This is where the schema stops being documentation and starts being enforcement. Three concrete things EnvShield catches in a PR:
+This is where the schema stops being documentation and starts being enforcement. Three concrete things EnvShield catches before a change reaches production:
 
 **A new environment variable used in code but missing from the schema:**
 
@@ -284,12 +284,14 @@ envshield undeclared origin/main HEAD --service api
 envshield schema diff origin/main HEAD --service api
 ```
 
-**A secret accidentally introduced into a commit** — the pre-commit hook runs `scan --staged` automatically:
+**A secret accidentally introduced into a commit:**
 
 ```bash
 envshield hook install
 ```
 
+The pre-commit hook runs `scan --staged --enforce`, applying classification-based enforcement with interactive override for high-confidence findings on local commits, and strict blocking in CI. See [Secret safety](#secret-safety) for enforcement behavior details.
+
 In CI, diff against the merge-base, not the base branch's current tip (which can move while the PR is open):
 
 ```yaml
@@ -466,10 +468,84 @@ Source-code discovery (what powers `undeclared` and `explain`'s "used in source"
 
 ## Secret safety
 
-A supporting check alongside the contract, not the product itself. `secret = true` on a field tells EnvShield (and `setup`, and code generation) that it's sensitive — the schema records that fact, never the actual value. On top of that:
+A supporting check alongside the contract, not the product itself. `secret = true` on a field tells EnvShield (and `setup`, and code generation) that it's sensitive — the schema records that fact, never the actual value.
+
+### Secret scanning
+
+**`envshield scan`** looks for hardcoded secrets by pattern (Stripe, AWS, GitHub tokens, and more), and for env-var reads the schema doesn't declare, in one pass. Values are always redacted in output — a Stripe *publishable* key (`pk_...`) is never flagged, since detection matches the secret-key pattern (`sk_...`) by shape, not the variable's name.
+
+### Context-aware classification
+
+Python candidates are analyzed for syntactic context to distinguish code patterns from secret values:
+
+```python
+# Classified as code (suppressed):
+client(key=CONFIG_CONSTANT)
+
+
+def handler(api_key: str): ...
+
+
+# Classified as likely secret (detected):
+client(key="sk_live_abc123...")
+```
+
+This reduces false positives on ordinary code patterns without broadly suppressing secret-shaped values. Classification is lightweight and syntactic — it recognizes type annotations, function arguments, and identifier references, but doesn't perform semantic analysis beyond what the tokenizer can see.
+
+### Git hook enforcement
+
+**`envshield hook install`** wires secret scanning into your Git workflow with classification-based enforcement:
+
+```bash
+envshield hook install
+```
+
+The pre-commit hook runs `scan --staged --enforce`, which scans only staged content and applies an enforcement policy based on classification confidence.
+
+#### Enforcement behavior
+
+| Finding type | Interactive (local commit) | Non-interactive (CI) |
+|---|---|---|
+| No findings | Allow | Allow |
+| Clearly code-shaped | Suppressed | Suppressed |
+| Ambiguous | Block | Block |
+| High-confidence secret | Block + explicit override | Block |
+
+**Clearly code-shaped** candidates (type annotations, function keyword arguments, etc.) are suppressed by the classifier and don't produce findings.
+
+**Ambiguous** findings — insufficient context to confidently classify — block without override in both modes.
+
+**High-confidence secrets** (string literals matching secret patterns) block by default but offer an interactive override for local commits:
+
+```
+⚠ EnvShield found potential secrets
+
+HIGH CONFIDENCE
+  src/config.py:42    Generic API Key    [REDACTED (30 chars)]
+
+[1] Abort commit
+[2] Commit anyway
+
+Choice: 2
+
+Type COMMIT ANYWAY to confirm: COMMIT ANYWAY
+
+Proceeding with commit. The finding remains in the repository history.
+```
+
+The override requires exact confirmation text — `yes` or `Y` won't work. EOF (Ctrl+D) or Ctrl+C aborts. Raw secret values are never displayed in enforcement output.
+
+In CI or other non-interactive contexts, high-confidence findings block with no prompt — the commit is refused, and the scan exits non-zero.
+
+#### Scanning modes
+
+```bash
+envshield scan                      # Audit entire codebase
+envshield scan --staged             # Scan only staged Git content
+envshield scan --staged --enforce   # Staged scan + enforcement policy
+```
 
-- **`envshield scan`** looks for hardcoded secrets by pattern (Stripe, AWS, GitHub tokens, and more), and for env-var reads the schema doesn't declare, in one pass. Values are always redacted in output — a Stripe *publishable* key (`pk_...`) is never flagged, since detection matches the secret-key pattern (`sk_...`) by shape, not the variable's name. Python candidates are context-aware: code-shaped patterns like `key=CONSTANT` or `api_key: str` may be suppressed when they're clearly not secret values, while secret-shaped string literals remain detectable regardless of context.
-- **`envshield hook install`** wires `scan --staged` into a pre-commit hook, so a real secret is caught before it's committed, not after.
+The pre-commit hook uses the third form. `scan` without flags is for repository-wide audits, not commit-time enforcement.
 
 ---
 

{envshield-4.7.3 → envshield-4.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "envshield"
-version = "4.7.3"  # must be a string for PEP 621 compliance
+version = "4.7.4"  # 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.3/envshield/__init__.py

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