cfglock 0.1.0__tar.gz

cfglock-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.3
+Name: cfglock
+Version: 0.1.0
+Summary: The official Python engine for the ConfigLock ecosystem
+Author: Philipp.Stahlberg
+Author-email: Philipp.Stahlberg <131917964+PhilippStahlbergGit@users.noreply.github.com>
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: requests>=2.34.2
+Requires-Dist: typer>=0.25.1
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://github.com/phalberg/configlock/actions/workflows/ci-cd.yaml/badge.svg" alt="CI Status" />
+  <img src="https://img.shields.io/badge/python-3.13-blue.svg" alt="Python Version" />
+  <a href="https://codecov.io/github/phalberg/configlock" > 
+ <img src="https://codecov.io/github/phalberg/configlock/graph/badge.svg?token=60JBRC22NB"/> 
+ </a>
+</p>
+
+# ConfigLock
+ConfigLock is a lightweight CLI tool designed to prevent production outages by configuration errors. It brings the concept of Lockfiles (inspiration from uv) to your application’s .yaml or .json configurations.
+
+# Quick start
+
+```
+# Clone the repo
+git clone https://github.com/phalberg/configlock
+cd configlock
+
+# Install dependencies
+uv sync
+
+# Initialize a lockfile
+uv run configlock init my_config.yaml
+
+# Sync after changes
+uv run configlock sync my_config.yaml
+```
+
+If you wish to not write `uv` each time, you can do as such:
+
+## CLI Usage
+
+Install the project in editable mode while developing:
+
+```bash
+pip install -e .
+```
+
+Run the command directly after install:
+
+```bash
+configlock --help
+configlock init {path_to_your_file}
+configlock lock {path_to_your_file}
+configlock sync {path_to_your_file}
+```
+
+Preview the docs locally with hot reload:
+
+```bash
+uv run docs-serve
+```
+
+# Status
+ConfigLock is a **personal hobby project** focused on learning robust CLI development and structural validation logic. 
+
+> [!NOTE]
+> This project is in an early prototype stage. It is a learning exercise in building developer tools with Python and Typer.
+
+### Roadmap
+- [x] Basic CLI integration with Typer
+- [x] GitHub Actions CI/CD pipeline
+- [x] Recursive Type & Structure checking
+- [ ] GitHub API integration (Fetch remote configs)
+- [ ] Web-based UI for configuration visualization
+
+# The problem
+In modern DevOps, non-technical team members often need to edit configuration files (YAML/JSON). One missing key or a wrong data type (e.g., entering a string where a boolean is expected) may crash a production environment.
+
+# Init 
+```bash
+init: Analyzes your YAML/JSON and creates a config.lock.json that stores the required structure and types.
+```
+_Note: ConfigLock generates one unique lockfile corresponding to the file path provided._
+
+# Sync
+
+```bash
+sync: Compares your current YAML/JSON against the lockfile. If a key is missing or a type has changed, you get an error.
+```
+
+# Lock
+```bash
+lock: Checks your current YAML/JSON and tries to replace the locked file with the new changed current file, if the change is not compatible, you get an error.
+
+```
+## Lock with strict ordering
+Please use the command:
+```bash
+configlock lock {path_to_your_file} --order-matters
+```
+If the order of the keys matter, if not the default:
+```bash
+configlock lock {path_to_your_file} --no-order-matters
+``` 
+will be set.
+
+# License
+
+This project is licensed under the terms of the MIT license.

cfglock-0.1.0/README.md

@@ -0,0 +1,100 @@
+<p align="center">
+  <img src="https://github.com/phalberg/configlock/actions/workflows/ci-cd.yaml/badge.svg" alt="CI Status" />
+  <img src="https://img.shields.io/badge/python-3.13-blue.svg" alt="Python Version" />
+  <a href="https://codecov.io/github/phalberg/configlock" > 
+ <img src="https://codecov.io/github/phalberg/configlock/graph/badge.svg?token=60JBRC22NB"/> 
+ </a>
+</p>
+
+# ConfigLock
+ConfigLock is a lightweight CLI tool designed to prevent production outages by configuration errors. It brings the concept of Lockfiles (inspiration from uv) to your application’s .yaml or .json configurations.
+
+# Quick start
+
+```
+# Clone the repo
+git clone https://github.com/phalberg/configlock
+cd configlock
+
+# Install dependencies
+uv sync
+
+# Initialize a lockfile
+uv run configlock init my_config.yaml
+
+# Sync after changes
+uv run configlock sync my_config.yaml
+```
+
+If you wish to not write `uv` each time, you can do as such:
+
+## CLI Usage
+
+Install the project in editable mode while developing:
+
+```bash
+pip install -e .
+```
+
+Run the command directly after install:
+
+```bash
+configlock --help
+configlock init {path_to_your_file}
+configlock lock {path_to_your_file}
+configlock sync {path_to_your_file}
+```
+
+Preview the docs locally with hot reload:
+
+```bash
+uv run docs-serve
+```
+
+# Status
+ConfigLock is a **personal hobby project** focused on learning robust CLI development and structural validation logic. 
+
+> [!NOTE]
+> This project is in an early prototype stage. It is a learning exercise in building developer tools with Python and Typer.
+
+### Roadmap
+- [x] Basic CLI integration with Typer
+- [x] GitHub Actions CI/CD pipeline
+- [x] Recursive Type & Structure checking
+- [ ] GitHub API integration (Fetch remote configs)
+- [ ] Web-based UI for configuration visualization
+
+# The problem
+In modern DevOps, non-technical team members often need to edit configuration files (YAML/JSON). One missing key or a wrong data type (e.g., entering a string where a boolean is expected) may crash a production environment.
+
+# Init 
+```bash
+init: Analyzes your YAML/JSON and creates a config.lock.json that stores the required structure and types.
+```
+_Note: ConfigLock generates one unique lockfile corresponding to the file path provided._
+
+# Sync
+
+```bash
+sync: Compares your current YAML/JSON against the lockfile. If a key is missing or a type has changed, you get an error.
+```
+
+# Lock
+```bash
+lock: Checks your current YAML/JSON and tries to replace the locked file with the new changed current file, if the change is not compatible, you get an error.
+
+```
+## Lock with strict ordering
+Please use the command:
+```bash
+configlock lock {path_to_your_file} --order-matters
+```
+If the order of the keys matter, if not the default:
+```bash
+configlock lock {path_to_your_file} --no-order-matters
+``` 
+will be set.
+
+# License
+
+This project is licensed under the terms of the MIT license.

cfglock-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "cfglock"
+version = "0.1.0"
+description = "The official Python engine for the ConfigLock ecosystem"
+readme = "README.md"
+authors = [
+    { name = "Philipp.Stahlberg", email = "131917964+PhilippStahlbergGit@users.noreply.github.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "dotenv>=0.9.9",
+    "pyyaml>=6.0.3",
+    "requests>=2.34.2",
+    "typer>=0.25.1",
+]
+
+[project.scripts]
+configlock = "cfglock.cli:app"
+cfglock = "cfglock.cli:app"
+cfl = "cfglock.cli:app"
+docs-serve = "cfglock.docs_server:main"
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.6.0",
+    "pyright>=1.1.410",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "radon>=6.0.1",
+    "reloadserver>=1.0.0",
+    "ruff>=0.15.15",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

cfglock-0.1.0/src/cfglock/__init__.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+from dotenv import load_dotenv
+
+env_file = Path(".env")
+if env_file.exists():
+    load_dotenv(env_file)
+else:
+    load_dotenv(Path(".env.example"))

cfglock-0.1.0/src/cfglock/cli.py

@@ -0,0 +1,68 @@
+import typer
+
+from cfglock.validator import ConfigLockError
+
+from .helper import (
+    write_json,
+    check_file_exists,
+    check_file_identicality,
+    check_comp_cli,
+    check_file_and_read_file,
+)
+from typing import Annotated
+
+app = typer.Typer(help="ConfigLock: Secure GitOps YAML validation engine.")
+
+
+@app.command()
+def init(
+    file_path: Annotated[
+        str, typer.Argument(help="the path for the newly proposed file")
+    ],
+) -> None:
+    """
+    Reads a YAML config and generates a lockfile.
+    """
+    if check_file_exists():
+        typer.echo("File already exists!")
+    else:
+        data = check_file_and_read_file(file_path)
+        write_json(data)
+
+
+@app.command()
+def sync(
+    file_path: Annotated[
+        str, typer.Argument(help="the path for the newly proposed file")
+    ],
+) -> None:
+    """
+    Used to check if lock file and proposed file are out of sync
+    """
+    if check_file_identicality(file_path):
+        typer.echo("The file has not changed.")
+    else:
+        raise ConfigLockError(
+            "The lock file is outdated, run sync to update the lock file!", error_code=1
+        )
+
+
+@app.command()
+def lock(
+    file_path: Annotated[
+        str, typer.Argument(help="the path for the newly proposed file")
+    ],
+    order_matters: bool = typer.Option(
+        False,
+        "--order-matters/--no-order-matters",
+        help="choose if the order of the keys matter or not",
+    ),
+) -> None:
+    """
+    Used to update the lock file, IF compatible
+    """
+
+    check_comp_cli(file_path, order_matters)
+    data = check_file_and_read_file(file_path)
+    write_json(data)
+

cfglock-0.1.0/src/cfglock/docs_server.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import argparse
+import contextlib
+import http.server
+import threading
+from pathlib import Path
+
+from watchdog.events import FileSystemEventHandler
+from watchdog.observers import Observer
+
+
+RELOAD_SCRIPT = b"""
+<script>
+async function waitForReload() {
+  try {
+    const response = await fetch('/__reload__', { cache: 'no-store' });
+    if (response.status === 204) {
+      location.reload();
+      return;
+    }
+  } catch (error) {
+    console.log('reload poll failed', error);
+  }
+  setTimeout(waitForReload, 1000);
+}
+waitForReload();
+</script>
+"""
+
+
+class ReloadState:
+    def __init__(self) -> None:
+        self.condition = threading.Condition()
+        self.generation = 0
+
+    def bump(self) -> None:
+        with self.condition:
+            self.generation += 1
+            self.condition.notify_all()
+
+    def wait_for_next(self, generation: int) -> None:
+        with self.condition:
+            self.condition.wait_for(lambda: self.generation > generation)
+
+
+class ReloadHandler(FileSystemEventHandler):
+    def __init__(self, state: ReloadState) -> None:
+        self.state = state
+
+    def on_any_event(self, event) -> None:
+        if not event.is_directory:
+            self.state.bump()
+
+
+class DocsHandler(http.server.SimpleHTTPRequestHandler):
+    def __init__(self, *args, docs_root: Path, state: ReloadState, **kwargs):
+        self.docs_root = docs_root
+        self.state = state
+        super().__init__(*args, directory=str(docs_root), **kwargs)
+
+    def end_headers(self) -> None:
+        if self.path.endswith(".html") or self.path in {"/", ""}:
+            self.send_header("Cache-Control", "no-store")
+        super().end_headers()
+
+    def do_GET(self) -> None:
+        if self.path == "/__reload__":
+            generation = self.state.generation
+            self.state.wait_for_next(generation)
+            self.send_response(204)
+            self.end_headers()
+            return
+        super().do_GET()
+
+    def copyfile(self, source, outputfile) -> None:
+        content = source.read()
+        if b"</html>" in content:
+            content = content.replace(b"</html>", RELOAD_SCRIPT + b"</html>")
+        elif self.path.endswith(".html") or self.path in {"/", ""}:
+            content += RELOAD_SCRIPT
+        outputfile.write(content)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Serve docs/ with live reload.")
+    parser.add_argument("port", nargs="?", type=int, default=8000)
+    parser.add_argument("--bind", default="127.0.0.1")
+    args = parser.parse_args()
+
+    docs_root = Path(__file__).resolve().parents[2] / "docs"
+    state = ReloadState()
+
+    observer = Observer()
+    observer.schedule(ReloadHandler(state), str(docs_root), recursive=True)
+    observer.start()
+
+    def handler_factory(*handler_args, **handler_kwargs):
+        return DocsHandler(
+            *handler_args,
+            docs_root=docs_root,
+            state=state,
+            **handler_kwargs,
+        )
+
+    try:
+        with contextlib.suppress(KeyboardInterrupt):
+            server = http.server.ThreadingHTTPServer(
+                (args.bind, args.port), handler_factory
+            )
+            print(f"Serving {docs_root} at http://{args.bind}:{args.port}/")
+            server.serve_forever()
+    finally:
+        observer.stop()
+        observer.join()

cfglock-0.1.0/src/cfglock/extraction.py

@@ -0,0 +1,24 @@
+import requests
+import json
+
+
+def ext_fr_gh_public(
+    user: str | None = "phalberg",
+    repo: str | None = "configlock",
+    branch: str | None = "main",
+    file: str | None = "config.lock.json",
+):
+    """
+    Extract from a public github repo in GitHub, the text content
+    """
+    raw_gh_url = "https://raw.githubusercontent.com"
+    com_url = f"{raw_gh_url}/{user}/{repo}/{branch}/{file}"
+    response = requests.get(com_url)
+    data = response.json()
+    return data
+
+
+if __name__ == "__main__":
+    json_data = json.dumps(ext_fr_gh_public(), indent=4)
+    with open("test_config.json", "w", encoding="utf-8") as f:
+        f.write(json_data)

cfglock-0.1.0/src/cfglock/helper.py

@@ -0,0 +1,127 @@
+import typer
+import yaml
+import json
+from pathlib import Path
+import filecmp
+from dotenv import load_dotenv
+import os
+
+from cfglock.validator import (
+    ValidationContext,
+    walk_yaml_in_order,
+    walk_yaml_with_no_order,
+)
+
+load_dotenv()
+CONFIG_LOG_FILE_PATH: str = os.environ.get("CONFIG_LOG_FILE_PATH", "config.lock.json")
+
+
+def check_file_identicality(
+    file_path: str, config_file_path: str = CONFIG_LOG_FILE_PATH
+):
+    """Checks if files are identical, if they are it returns True, False otherwise"""
+    try:
+        a = check_file_and_read_file(file_path)
+        b = read_json(config_file_path)
+        if a == b:
+            return True
+        filecmp.clear_cache()
+        res = filecmp.cmp(file_path, config_file_path, shallow=False)
+        return res
+    except Exception:
+        filecmp.clear_cache()
+        res = filecmp.cmp(file_path, config_file_path, shallow=False)
+        return res
+
+
+def check_file_exists(file_path: str = CONFIG_LOG_FILE_PATH) -> bool:
+    path = Path(file_path)
+    exists = path.exists()
+    if not exists:
+        typer.echo(f"The path does not exist: {path}")
+    return exists
+
+
+def read_yaml(file_path: str) -> dict:
+    try:
+        with open(file_path, "r") as f:
+            data = yaml.safe_load(f)
+    except FileNotFoundError:
+        raise
+    else:
+        typer.echo("Sucessfully read file")
+    return data
+
+
+def read_json(file_path: str) -> dict:
+    try:
+        with open(file_path, "r") as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        raise
+    else:
+        typer.echo("Sucessfully read file")
+    return data
+
+
+def write_json(data: dict, file_path: str = CONFIG_LOG_FILE_PATH) -> None:
+    data.update({"version": 1})
+    try:
+        with open(file_path, "w") as json_file:
+            json.dump(data, json_file, indent=4)
+    except TypeError:
+        raise
+    except Exception:
+        raise
+    else:
+        typer.echo("Sucessfully wrote file")
+
+
+def check_file_and_read_file(file_path: str) -> dict:
+    typer.echo(f"Reading {file_path}...")
+
+    path = Path(file_path)
+    suffix = path.suffix.lower()
+
+    reader_by_suffix = {
+        ".yaml": read_yaml,
+        ".yml": read_yaml,
+        ".json": read_json,
+    }
+
+    reader = reader_by_suffix.get(suffix)
+    if reader is None:
+        typer.echo(
+            f"File not suppported: {suffix}. Use .yaml, .yml, or .json.",
+            err=True,
+        )
+        raise ValueError("Error not able to read the file")
+
+    data = reader(file_path)
+
+    return data
+
+
+def check_comp_cli(new_file_path: str, order_matters: bool = False) -> None:
+    """ ""
+    Check compatiblity for the cli version
+    Keys => same names (must be the same, and (!) in the same (?order?)/precedence)
+    Values => must be of the same types
+    What about adding New entries? -> Fine
+    Deleting entries should not be allowed as it will obviously destroy Things. -> Fail
+    """
+
+    current_file_path = CONFIG_LOG_FILE_PATH
+    context = ValidationContext(
+        new_path=new_file_path,
+        current_path=current_file_path,
+        order_matters=bool(order_matters),
+    )
+
+    current_data = read_json(current_file_path)
+    new_data = check_file_and_read_file(new_file_path)
+
+    if order_matters:
+        walk_yaml_in_order(current_data, new_data, context)
+    else:
+        walk_yaml_with_no_order(current_data, new_data, context)

cfglock-0.1.0/src/cfglock/test_config.json

@@ -0,0 +1,9 @@
+{
+    "project_name": "ConfigLock",
+    "status": "Alpha",
+    "version": 1,
+    "team": {
+        "lead": "Philipp Stahlberg",
+        "contributors": []
+    }
+}

cfglock-0.1.0/src/cfglock/validator.py

@@ -0,0 +1,159 @@
+from dataclasses import dataclass
+from itertools import zip_longest
+
+keys_to_ignore = {"version"}
+
+
+"""
+Note:
+This is a strict class, meaning that webassembly will use this class.
+Beware of the contents, and try to be efficient, keep the class minimal.
+"""
+
+
+@dataclass
+class ValidationContext:
+    new_path: str
+    current_path: str
+    order_matters: bool
+
+
+# add other metadata if needed.
+
+
+class ConfigLockError(Exception):
+    """Basic Error"""
+
+    def __init__(self, message, error_code=1):
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+
+
+class ValidationError(ConfigLockError):
+    """Error for validation for syncing file"""
+
+    def __init__(
+        self,
+        path,
+        expected_value,
+        actual_value,
+        message="Validation Failed",
+        order_matters=False,
+    ):
+        super().__init__(message, error_code=100)
+        self.path = path
+        self.expected_value = expected_value
+        self.actual_value = actual_value
+        self.order_matters = order_matters
+
+    def __str__(self):
+        base_msg = f""" 
+        In path: {self.path} 
+        Expected: {self.expected_value}
+        Found: {self.actual_value}
+        """
+        if self.order_matters:
+            base_msg += "Additional: remember that order matters for keys!"
+        return f"{base_msg}\n(Error Code: {self.error_code})"
+
+
+def walk_yaml_with_no_order(
+    current_data, new_data, context: ValidationContext, depth=0
+):
+    """Recursively walks through a YAML-loaded object with no order."""
+
+    if isinstance(current_data, dict):
+        if not isinstance(new_data, dict):
+            accept_new_value(
+                current_value=current_data, new_value=new_data, context=context
+            )
+            return
+
+        for curr_k, curr_v in current_data.items():
+            # specific values for our own interpretation of versionings etc.
+            if curr_k in keys_to_ignore:
+                continue
+
+            if curr_k not in new_data:
+                accept_new_keys(curr_k, None, context)
+
+            new_v = new_data[curr_k]
+
+            walk_yaml_with_no_order(curr_v, new_v, context, depth + 1)
+
+    else:
+        accept_new_value(
+            current_value=current_data, new_value=new_data, context=context
+        )
+
+
+def walk_yaml_in_order(current_data, new_data, context: ValidationContext, depth=0):
+    """Recursively walks through a YAML-loaded object in order."""
+
+    if isinstance(current_data, dict):
+        for new_pair, curr_pair in zip_longest(
+            new_data.items(), current_data.items(), fillvalue=(None, None)
+        ):
+            new_k, new_v = new_pair
+            curr_k, curr_v = curr_pair
+
+            # specific values for our own interpretation of versionings etc.
+            if curr_k in keys_to_ignore:
+                continue
+
+            accept_new_keys(curr_k, new_k, context)
+
+            walk_yaml_with_no_order(new_v, curr_v, context, depth + 1)
+
+    else:
+        accept_new_value(
+            current_value=current_data, new_value=new_data, context=context
+        )
+
+
+# Not sure about this solution to this problem...
+def accept_new_keys(
+    current_key: str | None, new_key: str | None, context: ValidationContext
+) -> None:
+    """
+    General logic for accepting new keys:
+    1) the name of new_key cannot be different than the name of current_key
+    2) the order of new_key cannot be different than the current_key
+    3) the precedence (i.e indentation) cannot be different than the current_key
+    """
+
+    if current_key != new_key:
+        if context.order_matters:
+            raise ValidationError(
+                path=context.new_path,
+                expected_value=current_key,
+                actual_value=new_key,
+                order_matters=True,
+            )
+        else:
+            raise ValidationError(
+                path=context.new_path,
+                expected_value=current_key,
+                actual_value=new_key,
+                order_matters=False,
+            )
+
+
+def accept_new_value(current_value, new_value, context: ValidationContext) -> None:
+    """
+    General logic for accepting new values:
+    1) the type of the new_value cannot be different than the type of the current_value
+    """
+    type_curr = type(current_value)
+    type_new = type(new_value)
+
+    if type_curr != type_new:
+        type_curr_val = f"<{type_curr.__name__}> with value: {current_value}"
+        type_next_val = f"<{type_new.__name__}> with value: {new_value}"
+
+        raise ValidationError(
+            path=context.new_path,
+            expected_value=type_curr_val,
+            actual_value=type_next_val,
+        )