cal-docs-client 1.0.0b1__py3-none-any.whl

cal_docs_client/client.py

@@ -0,0 +1,265 @@
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   client.py
+#   ─────────
+#
+#   HTTP client for cal-docs-server API. Uses only Python stdlib (urllib.request).
+#
+#   (c) 2026 Cyber Assessment Labs — MIT License; see LICENSE in the project root.
+#
+#   Authors
+#   ───────
+#   bena (via Claude)
+#
+#   Version History
+#   ───────────────
+#   Feb 2026 - Created
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Imports
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Exceptions
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+class ClientError(Exception):
+    """Error from the API client."""
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Client
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+class DocsClient:
+    """HTTP client for cal-docs-server API."""
+
+    def __init__(self, server_url: str, token: str | None = None) -> None:
+        """Initialize the client.
+
+        Args:
+            server_url: Base URL of the cal-docs-server (e.g., "http://localhost:8080")
+            token: Optional API token for authenticated endpoints (upload)
+        """
+        self.server_url = server_url.rstrip("/")
+        self.token = token
+        self._verified = False
+        self._server_version: str | None = None
+        self._api_version: str | None = None
+
+    # ────────────────────────────────────────────────────────────────────────────────────
+    #   HTTP Methods
+    # ────────────────────────────────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        data: bytes | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float = 30.0,
+    ) -> bytes:
+        """Make an HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: URL path (e.g., "/api/version")
+            data: Optional request body
+            headers: Optional headers
+            timeout: Request timeout in seconds
+
+        Returns:
+            Response body as bytes
+
+        Raises:
+            ClientError: On HTTP or connection error
+        """
+        url = f"{self.server_url}{path}"
+        req_headers = headers.copy() if headers else {}
+
+        if self.token:
+            req_headers["X-Token"] = self.token
+
+        request = urllib.request.Request(
+            url,
+            data=data,
+            headers=req_headers,
+            method=method,
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                return response.read()
+        except urllib.error.HTTPError as e:
+            body = e.read().decode("utf-8", errors="replace")
+            try:
+                error_data = json.loads(body)
+                message = error_data.get("message", body)
+            except json.JSONDecodeError:
+                message = body
+            raise ClientError(f"HTTP {e.code}: {message}") from e
+        except urllib.error.URLError as e:
+            raise ClientError(f"Connection failed: {e.reason}") from e
+        except TimeoutError as e:
+            raise ClientError(f"Request timed out after {timeout}s") from e
+
+    def _get(self, path: str) -> bytes:
+        """Make a GET request."""
+        return self._request("GET", path)
+
+    def _get_json(self, path: str) -> Any:
+        """Make a GET request and parse JSON response."""
+        data = self._get(path)
+        try:
+            return json.loads(data)
+        except json.JSONDecodeError as e:
+            raise ClientError(f"Invalid JSON response: {e}") from e
+
+    def _post(
+        self,
+        path: str,
+        data: bytes,
+        content_type: str,
+        filename: str | None = None,
+    ) -> bytes:
+        """Make a POST request."""
+        headers = {"Content-Type": content_type}
+        if filename:
+            headers["X-Filename"] = filename
+        return self._request("POST", path, data, headers)
+
+    # ────────────────────────────────────────────────────────────────────────────────────
+    #   Server Verification
+    # ────────────────────────────────────────────────────────────────────────────────────
+
+    def verify_server(self) -> None:
+        """Verify the server is cal-docs-server with a compatible API version.
+
+        Accepts API version 1.x, rejects 2.x and above.
+
+        Raises:
+            ClientError: If server is not cal-docs-server or API version is incompatible
+        """
+        if self._verified:
+            return
+
+        data = self._get_json("/api/version")
+
+        product = data.get("product", "")
+        if product != "cal-docs-server":
+            raise ClientError(
+                f"Server is not cal-docs-server (product: {product or 'unknown'})"
+            )
+
+        api_version = data.get("apiVersion", "")
+        if not api_version:
+            raise ClientError("Server did not report an API version")
+
+        # Parse major version
+        try:
+            major = int(api_version.split(".")[0])
+        except ValueError, IndexError:
+            raise ClientError(f"Invalid API version format: {api_version}") from None
+
+        if major != 1:
+            raise ClientError(
+                f"Incompatible API version: {api_version} (this client requires 1.x)"
+            )
+
+        self._verified = True
+        self._server_version = data.get("version", "unknown")
+        self._api_version = api_version
+
+    @property
+    def server_version(self) -> str:
+        """Get the server version (requires verify_server to be called first)."""
+        return self._server_version or "unknown"
+
+    @property
+    def api_version(self) -> str:
+        """Get the API version (requires verify_server to be called first)."""
+        return self._api_version or "unknown"
+
+    # ────────────────────────────────────────────────────────────────────────────────────
+    #   API Methods
+    # ────────────────────────────────────────────────────────────────────────────────────
+
+    def get_version(self) -> dict[str, str]:
+        """Get server version information.
+
+        Returns:
+            Dict with 'product', 'version', and 'apiVersion' keys
+        """
+        return self._get_json("/api/version")
+
+    def get_help(self) -> str:
+        """Get the server's API help text.
+
+        Returns:
+            Plain text API documentation
+        """
+        return self._get("/api/help").decode("utf-8")
+
+    def get_spec(self) -> dict[str, Any]:
+        """Get the OpenAPI specification.
+
+        Returns:
+            OpenAPI spec as a dict
+        """
+        return self._get_json("/api/spec")
+
+    def get_projects(self, search: str | None = None) -> dict[str, Any]:
+        """List documentation projects.
+
+        Args:
+            search: Optional search term to filter projects
+
+        Returns:
+            Dict with 'projects' list and 'count' key
+        """
+        path = "/api/projects"
+        if search:
+            path = f"{path}?search={urllib.parse.quote(search)}"
+        return self._get_json(path)
+
+    def download(self, project: str, version: str = "latest") -> bytes:
+        """Download a documentation package.
+
+        Args:
+            project: Project name
+            version: Version to download (default: "latest")
+
+        Returns:
+            Zip file contents as bytes
+        """
+        path = (
+            f"/api/download/{urllib.parse.quote(project)}/{urllib.parse.quote(version)}"
+        )
+        return self._get(path)
+
+    def upload(self, filename: str, data: bytes) -> dict[str, Any]:
+        """Upload a documentation package.
+
+        Args:
+            filename: Name of the zip file (e.g., "myproject-1.0.0-docs.zip")
+            data: Zip file contents
+
+        Returns:
+            Server response with upload details
+
+        Raises:
+            ClientError: If upload fails (auth error, invalid file, etc.)
+        """
+        response = self._post("/api/upload", data, "application/zip", filename)
+        try:
+            return json.loads(response)
+        except json.JSONDecodeError as e:
+            raise ClientError(f"Invalid JSON response: {e}") from e

cal_docs_client/common/__init__.py

@@ -0,0 +1,32 @@
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   common/__init__.py
+#   ──────────────────
+#
+#   Common utilities for cal-docs-client.
+#
+#   (c) 2026 Cyber Assessment Labs — MIT License; see LICENSE in the project root.
+#
+#   Authors
+#   ───────
+#   bena (via Claude)
+#
+#   Version History
+#   ───────────────
+#   Feb 2026 - Created
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+from .colour import bold
+from .colour import cyan
+from .colour import green
+from .colour import red
+from .colour import set_colours_enabled
+from .colour import yellow
+
+__all__ = [
+    "bold",
+    "cyan",
+    "green",
+    "red",
+    "set_colours_enabled",
+    "yellow",
+]

cal_docs_client/common/colour.py

@@ -0,0 +1,107 @@
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   colour.py
+#   ─────────
+#
+#   ANSI colour output for terminal. Only applies colours when stdout is a TTY
+#   and colours are not disabled.
+#
+#   Uses colours that work well on both light and dark backgrounds.
+#
+#   (c) 2026 Cyber Assessment Labs — MIT License; see LICENSE in the project root.
+#
+#   Authors
+#   ───────
+#   bena (via Claude)
+#
+#   Version History
+#   ───────────────
+#   Feb 2026 - Created
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Imports
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+import sys
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   ANSI Codes
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+# These colours work well on both light and dark backgrounds
+RESET = "\033[0m"
+BOLD = "\033[1m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+RED = "\033[31m"
+CYAN = "\033[36m"
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   State
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+_colours_enabled: bool | None = None
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Functions
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def set_colours_enabled(enabled: bool) -> None:
+    """Explicitly enable or disable colours."""
+    global _colours_enabled
+    _colours_enabled = enabled
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def _should_use_colours() -> bool:
+    """Determine if colours should be used."""
+    global _colours_enabled
+
+    # If explicitly set, use that
+    if _colours_enabled is not None:
+        return _colours_enabled
+
+    # Auto-detect: use colours if stdout is a TTY
+    return sys.stdout.isatty()
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def green(text: str) -> str:
+    """Return text in green (for success)."""
+    if _should_use_colours():
+        return f"{GREEN}{text}{RESET}"
+    return text
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def yellow(text: str) -> str:
+    """Return text in yellow (for warning)."""
+    if _should_use_colours():
+        return f"{YELLOW}{text}{RESET}"
+    return text
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def red(text: str) -> str:
+    """Return text in red (for error)."""
+    if _should_use_colours():
+        return f"{RED}{text}{RESET}"
+    return text
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def cyan(text: str) -> str:
+    """Return text in cyan (for info)."""
+    if _should_use_colours():
+        return f"{CYAN}{text}{RESET}"
+    return text
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def bold(text: str) -> str:
+    """Return text in bold."""
+    if _should_use_colours():
+        return f"{BOLD}{text}{RESET}"
+    return text

cal_docs_client/version.py

@@ -0,0 +1,32 @@
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   version.py
+#   ──────────
+#
+#   Version handling for cal-docs-client.
+#
+#   (c) 2026 Cyber Assessment Labs — MIT License; see LICENSE in the project root.
+#
+#   Authors
+#   ───────
+#   bena (via Claude)
+#
+#   Version History
+#   ───────────────
+#   Feb 2026 - Created
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+def _get_version() -> str:
+    """Get the version string from the generated _version.py or return DEV."""
+    try:
+        # fmt: off
+        from ._version import __version__ as _v  # pyright: ignore[reportMissingImports,reportUnknownVariableType]  # noqa: I001
+        # fmt: on
+
+        return str(_v)  # pyright: ignore[reportUnknownArgumentType]
+    except ImportError:
+        return "DEV"
+
+
+VERSION_STR: str = _get_version()

cal_docs_client-1.0.0b1.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: cal-docs-client
+Version: 1.0.0b1
+Summary: CLI client for cal-docs-server documentation API
+Project-URL: Repository, https://gitlab.com/cyberassessmentlabs/public/tools/cal-docs-client
+Project-URL: Documentation, https://cyberassessmentlabs.gitlab.io/public/docs/cal-docs-client/latest
+Author: Cyber Assessment Labs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,cli,client,docs,documentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# cal-docs-client
+
+CLI client for [cal-docs-server](https://gitlab.com/cyberassessmentlabs/public/tools/cal-docs-server) documentation API.
+
+## Requirements
+
+- Python 3.14+
+- No external dependencies (stdlib only)
+
+## Installation
+
+```bash
+pip install cal-docs-client
+```
+
+Or install from source:
+
+```bash
+git clone https://gitlab.com/cyberassessmentlabs/public/tools/cal-docs-client.git
+cd cal-docs-client
+pip install .
+```
+
+## Configuration
+
+Configuration is optional. You can provide settings via command-line options, environment variables, or a config file.
+
+### Config File (Optional)
+
+For convenience, create a config file at `~/.config/cal-docs-client/config.json`:
+
+```json
+{
+    "server": "https://docs.example.com",
+    "token": "your-api-token",
+    "no_colour": false
+}
+```
+
+You can also specify a different config file with `-c`/`--config`.
+
+### Configuration Priority
+
+Settings are resolved in this order (first wins):
+1. Command-line arguments (`-s`, `--no-colour`)
+2. Environment variables (`CAL_DOCS_SERVER`, `CAL_DOCS_TOKEN`)
+3. Config file
+
+## Usage
+
+```bash
+# Show help
+cal-docs-client --help
+
+# Show server and client version
+cal-docs-client version
+
+# List all projects
+cal-docs-client projects
+
+# Search for projects
+cal-docs-client projects --search myproject
+
+# Download documentation
+cal-docs-client download myproject latest
+cal-docs-client download myproject 1.0.0 -o docs.zip
+
+# Upload documentation (requires token in config or -t)
+cal-docs-client upload myproject-1.0.0-docs.zip
+
+# Show server API help
+cal-docs-client help
+
+# Get OpenAPI specification
+cal-docs-client spec -o openapi.json
+```
+
+### Command-Line Options
+
+You can pass all settings directly on the command line:
+
+```bash
+cal-docs-client -s https://docs.example.com projects
+cal-docs-client -s https://docs.example.com upload -t YOUR_TOKEN docs.zip
+```
+
+### Environment Variables
+
+You can also use environment variables:
+
+- `CAL_DOCS_SERVER` - Server URL
+- `CAL_DOCS_TOKEN` - Authentication token
+
+## API Version Compatibility
+
+This client requires cal-docs-server API version 1.x. It will refuse to connect to servers with incompatible API versions.
+
+## License
+
+MIT License - (c) 2026 Cyber Assessment Labs

cal_docs_client-1.0.0b1.dist-info/RECORD

@@ -0,0 +1,14 @@
+cal_docs_client/__init__.py,sha256=-bKdz7ZdnfWxn04KMgNzpwUdxcKqRcR8DpcNM0NTBQA,929
+cal_docs_client/__main__.py,sha256=fuTDiIx-veSOTEVhxxyKG3poYiQ2rk87Ko2Wwvpjj-4,965
+cal_docs_client/_version.py,sha256=JQkLQAME1HDp3QVEh9RrTjuwWvqAl4Ya_t--FXT4jms,173
+cal_docs_client/argbuilder.py,sha256=5cWtNrndIgp31hT_Za6pKQ60CBFtOdaLrPakjlDR9zA,64965
+cal_docs_client/cli.py,sha256=ahGVrLz2LXYsPwKP-hA46hadoI77AOX1UV8G3WVNQ5Q,16895
+cal_docs_client/client.py,sha256=kqSrGUF6RPUXQ_FX4pzf6pv4n3vICQZKjFpPOl4_DqU,11089
+cal_docs_client/version.py,sha256=265arrq2YMLxGA3YJqtnoqiTSgY8LQBJJsu0XAmbHJ8,1573
+cal_docs_client/common/__init__.py,sha256=NtGfBqAAZKrZ1Il4ceHIlOxIZtybV5ApBeZDBsw6D_Q,1176
+cal_docs_client/common/colour.py,sha256=yIU4xb9HHXQSSMdZrJUyfTpij58CUHgO4YLsWVzVAn8,6527
+cal_docs_client-1.0.0b1.dist-info/METADATA,sha256=R8lAKPMiVYpbSXvoV75dxeLz4TsyBpWEk6mIDs8zl8s,3022
+cal_docs_client-1.0.0b1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+cal_docs_client-1.0.0b1.dist-info/entry_points.txt,sha256=IYL7hCO3QJ6Idq8_zAplfnRmoaMOaCNzg-3y4T_dQYs,61
+cal_docs_client-1.0.0b1.dist-info/licenses/LICENSE,sha256=zIXdXMPhkY8xLlrhw7lOsWiFOecEYRukxgZIjMTKPuE,1078
+cal_docs_client-1.0.0b1.dist-info/RECORD,,

cal_docs_client-1.0.0b1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cal_docs_client-1.0.0b1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cal-docs-client = cal_docs_client.cli:main

cal_docs_client-1.0.0b1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cyber Assessment Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.