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

cal_docs_client/cli.py

@@ -0,0 +1,518 @@
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   cli.py
+#   ──────
+#
+#   Command-line interface 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
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Imports
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+import json
+import os
+import sys
+import traceback
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+from typing import cast
+from .argbuilder import ArgsParser
+from .argbuilder import Namespace
+from .client import ClientError
+from .client import DocsClient
+from .common import bold
+from .common import cyan
+from .common import green
+from .common import red
+from .common import set_colours_enabled
+from .common import yellow
+from .version import VERSION_STR
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Constants
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+CONFIG_DIR = Path.home() / ".config" / "cal-docs-client"
+DEFAULT_CONFIG_PATH = CONFIG_DIR / "config.json"
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Config Loading
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+# ---
+def load_config(config_path: Path | None) -> dict[str, Any]:
+    """Load configuration from a JSON file.
+
+    Args:
+        config_path: Path to config file, or None to use default.
+
+    Returns:
+        Configuration dict, or empty dict if not found.
+
+    Config file format:
+        {
+            "server": "https://docs.example.com",
+            "token": "your-api-token",
+            "no_colour": false
+        }
+    """
+    # Determine which config file to use
+    if config_path:
+        path = config_path
+    else:
+        path = DEFAULT_CONFIG_PATH
+
+    if not path.exists():
+        return {}
+
+    try:
+        with path.open() as f:
+            data = json.load(f)
+            if not isinstance(data, dict):
+                print(
+                    yellow(
+                        f"Warning: Config file {path} is not a JSON object, ignoring"
+                    ),
+                    file=sys.stderr,
+                )
+                return {}
+            return cast("dict[str, Any]", data)
+    except json.JSONDecodeError as e:
+        print(
+            yellow(f"Warning: Invalid JSON in config file {path}: {e}"),
+            file=sys.stderr,
+        )
+        return {}
+    except OSError as e:
+        print(
+            yellow(f"Warning: Could not read config file {path}: {e}"),
+            file=sys.stderr,
+        )
+        return {}
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Argument Parser
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+# ---
+def create_parser() -> ArgsParser:
+    """Create the main argument parser with subcommands."""
+    parser = ArgsParser(
+        prog="cal-docs-client",
+        description="CLI client for cal-docs-server documentation API",
+        version=f"cal-docs-client {VERSION_STR}",
+    )
+
+    # =========== Common Options ===========
+
+    common = parser.create_common_collection()
+    common_group = common.add_group("Common Options")
+    common_group.add_argument(
+        "-s",
+        "--server",
+        metavar="URL",
+        help="Server URL (or set CAL_DOCS_SERVER env var, or config file)",
+    )
+    common_group.add_argument(
+        "-c",
+        "--config",
+        metavar="FILE",
+        type=Path,
+        help=f"Config file path (default: {DEFAULT_CONFIG_PATH})",
+    )
+    common_group.add_argument(
+        "--no-colour",
+        "--no-color",
+        action="store_true",
+        dest="no_colour",
+        help="Disable coloured output",
+    )
+    common_group.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Verbose output",
+    )
+
+    # =========== Version Command ===========
+
+    parser.add_command(
+        "version",
+        help="Show server and client version",
+        description="Show version information for both the server and this client.",
+    )
+
+    # =========== Projects Command ===========
+
+    projects_cmd = parser.add_command(
+        "projects",
+        help="List documentation projects",
+        description="List all documentation projects on the server.",
+    )
+    projects_cmd.add_argument(
+        "-q",
+        "--search",
+        metavar="TERM",
+        help="Filter projects by name",
+    )
+    projects_cmd.add_argument(
+        "-j",
+        "--json",
+        action="store_true",
+        help="Output as JSON",
+    )
+
+    # =========== Download Command ===========
+
+    download_cmd = parser.add_command(
+        "download",
+        help="Download documentation",
+        description="Download a documentation package as a zip file.",
+    )
+    download_cmd.add_argument(
+        "project",
+        help="Project name",
+    )
+    download_cmd.add_argument(
+        "doc_version",
+        nargs="?",
+        default="latest",
+        metavar="VERSION",
+        help="Version to download (default: latest)",
+    )
+    download_cmd.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="Output filename (default: {project}-{version}-docs.zip)",
+    )
+
+    # =========== Upload Command ===========
+
+    upload_cmd = parser.add_command(
+        "upload",
+        help="Upload documentation",
+        description=(
+            "Upload a documentation package to the server.\nRequires authentication via"
+            " --token, CAL_DOCS_TOKEN env var, or config file.\nFilename must match:"
+            " {project}-{version}[-docs].zip"
+        ),
+    )
+    upload_cmd.add_argument(
+        "file",
+        help="Zip file to upload",
+    )
+    upload_cmd.add_argument(
+        "-t",
+        "--token",
+        metavar="TOKEN",
+        help="Auth token (or set CAL_DOCS_TOKEN env var, or config file)",
+    )
+
+    # =========== Help Command ===========
+
+    parser.add_command(
+        "help",
+        help="Show server API help",
+        description="Fetch and display the server's API help documentation.",
+    )
+
+    # =========== Spec Command ===========
+
+    spec_cmd = parser.add_command(
+        "spec",
+        help="Show OpenAPI specification",
+        description="Fetch and display the server's OpenAPI specification.",
+    )
+    spec_cmd.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="Save specification to file",
+    )
+
+    return parser
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Command Handlers
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+
+# ---
+def cmd_version(client: DocsClient, _args: Namespace) -> int:
+    """Handle the 'version' command."""
+    client.verify_server()
+
+    print(
+        f"{bold('Server:')} cal-docs-server {client.server_version} (API"
+        f" v{client.api_version})"
+    )
+    print(f"{bold('Client:')} cal-docs-client {VERSION_STR}")
+    return 0
+
+
+# ---
+def cmd_projects(client: DocsClient, args: Namespace) -> int:
+    """Handle the 'projects' command."""
+    client.verify_server()
+
+    data = client.get_projects(args.search)
+
+    if args.json:
+        print(json.dumps(data, indent=2))
+        return 0
+
+    projects = data.get("projects", [])
+    count = data.get("count", len(projects))
+
+    if args.search:
+        print(
+            f"{bold('Projects')} matching '{args.search}' on {cyan(client.server_url)}"
+            f" ({count} found):\n"
+        )
+    else:
+        print(f"{bold('Projects')} on {cyan(client.server_url)} ({count} found):\n")
+
+    if not projects:
+        print(yellow("  No projects found."))
+        return 0
+
+    for proj in projects:
+        name = proj.get("name", proj.get("directory_name", "unknown"))
+        desc = proj.get("description", "")
+        versions = proj.get("versions", [])
+        latest = proj.get("latest_version_dir")
+
+        print(f"  {bold(name)}")
+        if desc:
+            print(f"    {desc}")
+
+        if versions:
+            version_strs = [v.get("version", "?") for v in versions[:5]]
+            if len(versions) > 5:
+                version_strs.append(f"... ({len(versions)} total)")
+            print(f"    Versions: {', '.join(version_strs)}")
+
+        if latest:
+            print(
+                "    Latest:"
+                f" {green(latest.rsplit('-', 1)[-1] if '-' in latest else latest)}"
+            )
+
+        print()
+
+    return 0
+
+
+# ---
+def cmd_download(client: DocsClient, args: Namespace) -> int:
+    """Handle the 'download' command."""
+    client.verify_server()
+
+    project = args.project
+    version = args.doc_version
+
+    # Determine output filename
+    if args.output:
+        output_path = Path(args.output)
+    else:
+        output_path = Path(f"{project}-{version}-docs.zip")
+
+    print(f"Downloading {cyan(project)} version {cyan(version)}...")
+
+    try:
+        data = client.download(project, version)
+    except ClientError as e:
+        print(red(f"Error: {e}"), file=sys.stderr)
+        return 1
+
+    output_path.write_bytes(data)
+    print(f"Saved to {green(str(output_path))} ({len(data):,} bytes)")
+    return 0
+
+
+# ---
+def cmd_upload(client: DocsClient, args: Namespace) -> int:
+    """Handle the 'upload' command."""
+    client.verify_server()
+
+    file_path = Path(args.file)
+
+    if not file_path.exists():
+        print(red(f"Error: File not found: {file_path}"), file=sys.stderr)
+        return 1
+
+    if not file_path.suffix.lower() == ".zip":
+        print(red("Error: File must be a .zip file"), file=sys.stderr)
+        return 1
+
+    if not client.token:
+        print(
+            red(
+                "Error: Authentication required. Set --token, CAL_DOCS_TOKEN env var,"
+                " or add token to config file."
+            ),
+            file=sys.stderr,
+        )
+        return 1
+
+    filename = file_path.name
+    data = file_path.read_bytes()
+
+    print(f"Uploading {cyan(filename)} ({len(data):,} bytes)...")
+
+    try:
+        result = client.upload(filename, data)
+    except ClientError as e:
+        print(red(f"Error: {e}"), file=sys.stderr)
+        return 1
+
+    if result.get("success"):
+        print(green("Upload successful!"))
+        print(f"  Project: {result.get('project', 'unknown')}")
+        print(f"  Version: {result.get('version', 'unknown')}")
+        print(f"  URL: {result.get('url', 'N/A')}")
+        print(f"  Files: {result.get('files_extracted', 'N/A')}")
+    else:
+        print(
+            red(f"Upload failed: {result.get('message', 'Unknown error')}"),
+            file=sys.stderr,
+        )
+        return 1
+
+    return 0
+
+
+# ---
+def cmd_help(client: DocsClient, _args: Namespace) -> int:
+    """Handle the 'help' command (server API help)."""
+    client.verify_server()
+
+    help_text = client.get_help()
+    print(help_text)
+    return 0
+
+
+# ---
+def cmd_spec(client: DocsClient, args: Namespace) -> int:
+    """Handle the 'spec' command."""
+    client.verify_server()
+
+    spec = client.get_spec()
+    output = json.dumps(spec, indent=2)
+
+    if args.output:
+        Path(args.output).write_text(output)
+        print(f"Specification saved to {green(args.output)}")
+    else:
+        print(output)
+
+    return 0
+
+
+# ────────────────────────────────────────────────────────────────────────────────────────
+#   Main Entry Point
+# ────────────────────────────────────────────────────────────────────────────────────────
+
+CommandHandler = Callable[[DocsClient, Namespace], int]
+
+COMMANDS: dict[str, CommandHandler] = {
+    "version": cmd_version,
+    "projects": cmd_projects,
+    "download": cmd_download,
+    "upload": cmd_upload,
+    "help": cmd_help,
+    "spec": cmd_spec,
+}
+
+
+# ---
+def main(argv: list[str] | None = None) -> int:
+    """Main entry point."""
+    if argv is None:
+        argv = sys.argv[1:]
+
+    try:
+        return _main_inner(argv)
+    except KeyboardInterrupt:
+        print()
+        print("---- Manually Terminated ----")
+        print()
+        return 1
+    except SystemExit as e:
+        return e.code if isinstance(e.code, int) else 1
+    except BaseException as e:
+        print("-" * 77, file=sys.stderr)
+        print("UNHANDLED EXCEPTION OCCURRED!!", file=sys.stderr)
+        print(file=sys.stderr)
+        print(traceback.format_exc(), file=sys.stderr)
+        print(f"EXCEPTION: {type(e).__name__}: {e}", file=sys.stderr)
+        print("-" * 77, file=sys.stderr)
+        return 1
+
+
+# ---
+def _main_inner(argv: list[str]) -> int:
+    """Inner main function that may raise exceptions."""
+    parser = create_parser()
+    args = parser.parse(argv)
+
+    # Load config file (CLI arg > default path)
+    config = load_config(args.config)
+
+    # Handle colour settings: CLI > config > default (auto)
+    if args.no_colour:
+        set_colours_enabled(False)
+    elif config.get("no_colour"):
+        set_colours_enabled(False)
+
+    # If no command, show help
+    if not args.command:
+        return 0  # ArgsParser already shows help
+
+    # Get server URL: CLI > env > config
+    server_url = (
+        args.server or os.environ.get("CAL_DOCS_SERVER") or config.get("server")
+    )
+    if not server_url:
+        print(
+            red(
+                "Error: Server URL required. Use --server, set CAL_DOCS_SERVER env var,"
+                " or add to config file."
+            ),
+            file=sys.stderr,
+        )
+        return 1
+
+    # Get token: CLI > env > config
+    token = args.token or os.environ.get("CAL_DOCS_TOKEN") or config.get("token")
+
+    # Create client
+    client = DocsClient(server_url, token)
+
+    # Get command handler
+    handler = COMMANDS.get(args.command)
+    if not handler:
+        print(red(f"Error: Unknown command: {args.command}"), file=sys.stderr)
+        return 1
+
+    try:
+        return handler(client, args)
+    except ClientError as e:
+        print(red(f"Error: {e}"), file=sys.stderr)
+        return 1