kb2md 0.1.0__py3-none-any.whl

kb2md/__init__.py

@@ -0,0 +1,4 @@
+"""kb2md: Convert Confluence pages to Markdown with attachments."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

kb2md/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for `python -m kb2md`."""
+
+from kb2md.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kb2md/cli.py

@@ -0,0 +1,223 @@
+"""Command-line interface for kb2md."""
+
+import argparse
+import logging
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from kb2md import __version__, config, utils
+from kb2md.converter import ConfluenceToMarkdown
+from kb2md.subpage import SubpageDownloader
+
+LOGGER = logging.getLogger(__name__)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="kb2md",
+        description="Convert Confluence pages to local Markdown with attachments.",
+    )
+    parser.add_argument(
+        "page_ref",
+        nargs="?",
+        help="Confluence page ID or URL",
+    )
+    parser.add_argument(
+        "--url",
+        default=os.getenv("CONFLUENCE_URL"),
+        help="Confluence base URL (or set CONFLUENCE_URL)",
+    )
+    parser.add_argument(
+        "--token",
+        help="Confluence token/PAT (or set CONFLUENCE_TOKEN, or use --set-default-token)",
+    )
+    parser.add_argument(
+        "--output-dir",
+        default="./output",
+        help="Directory to save generated markdown and attachments",
+    )
+    parser.add_argument(
+        "--subpage",
+        action="store_true",
+        help="Download direct subpages into {page_id}_page/",
+    )
+    parser.add_argument(
+        "--all-subpage",
+        action="store_true",
+        help="Recursively download all subpages",
+    )
+    parser.add_argument(
+        "--no-chrome-cookies",
+        action="store_true",
+        help="Disable loading Chrome cookies for attachment download fallback",
+    )
+    parser.add_argument(
+        "--set-default-url",
+        dest="set_default_url",
+        metavar="URL",
+        help="Set the default Confluence URL and save it for future runs",
+    )
+    parser.add_argument(
+        "--set-default-token",
+        dest="set_default_token",
+        metavar="TOKEN",
+        help="Set the default Confluence token/PAT and save it for future runs",
+    )
+    parser.add_argument(
+        "--get-default-url",
+        action="store_true",
+        dest="get_default_url",
+        help="Show the currently saved default Confluence URL",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Enable verbose logging",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def _handle_default_config_args(args: argparse.Namespace) -> int | None:
+    """Handle config commands; return exit code or None."""
+    has_config_command = (
+        args.set_default_url is not None
+        or args.set_default_token is not None
+        or args.get_default_url
+    )
+    if not has_config_command:
+        return None
+
+    if args.page_ref:
+        LOGGER.error("Config commands cannot be used with a page reference.")
+        return 1
+
+    if args.set_default_url:
+        config.set_default_url(args.set_default_url)
+        print(f"Default URL set to: {config.get_default_url()}")
+
+    if args.set_default_token is not None:
+        token = args.set_default_token.strip()
+        if not token:
+            LOGGER.error("--set-default-token requires a non-empty token.")
+            return 1
+        config.set_default_token(token)
+        print("Default token saved.")
+
+    if args.get_default_url:
+        default_url = config.get_default_url()
+        if default_url:
+            print(default_url)
+        else:
+            print("No default URL configured.", file=sys.stderr)
+            return 1
+
+    return 0
+
+
+def _validate_args(args: argparse.Namespace) -> int | None:
+    """Validate positional/mutually-exclusive arguments; return exit code or None."""
+    # Using LOGGER.error instead of parser.error because ArgumentParser.error()
+    # raises SystemExit, making return-code assertions in unit tests harder.
+    if not args.page_ref:
+        LOGGER.error("Missing page reference. Provide a page ID or URL.")
+        return 1
+
+    if args.subpage and args.all_subpage:
+        LOGGER.error("--subpage and --all-subpage are mutually exclusive.")
+        return 1
+
+    return None
+
+
+def _resolve_conversion_inputs(args: argparse.Namespace) -> tuple[str, int] | int:
+    """Resolve URL and page ID from CLI args; return (url, page_id) or exit code."""
+    try:
+        base_url, page_id_str = utils.parse_page_ref(args.page_ref)
+    except ValueError as e:
+        LOGGER.error("Invalid page reference: %s", e)
+        return 1
+
+    try:
+        confluence_url = config.resolve_url(args.url, base_url)
+    except ValueError as e:
+        LOGGER.error("%s", e)
+        return 1
+
+    try:
+        page_id = int(page_id_str)
+    except ValueError:
+        LOGGER.error("Invalid page ID: %r is not a number.", page_id_str)
+        return 1
+
+    return confluence_url, page_id
+
+
+def _run_conversion(
+    confluence_url: str,
+    page_id: int,
+    token: str,
+    args: argparse.Namespace,
+) -> int:
+    """Run the main conversion and optional subpage download."""
+    try:
+        output_dir = Path(args.output_dir)
+        converter = ConfluenceToMarkdown(
+            confluence_url=confluence_url,
+            token=token,
+            use_chrome_cookies=not args.no_chrome_cookies,
+        )
+        output_dir.mkdir(parents=True, exist_ok=True)
+        result_file = converter.confluence_to_markdown(page_id, output_dir=output_dir)
+        LOGGER.info("Saved main page to: %s", result_file)
+
+        if args.subpage or args.all_subpage:
+            downloader = SubpageDownloader(converter)
+            downloader.download_subpages(page_id, output_dir, recursive=args.all_subpage)
+    except Exception as e:  # noqa: BLE001 - top-level CLI error handler
+        LOGGER.error("Conversion failed: %s", e, exc_info=args.verbose)
+        return 1
+
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point for the kb2md CLI."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(message)s",
+    )
+
+    if (result := _handle_default_config_args(args)) is not None:
+        return result
+
+    if (result := _validate_args(args)) is not None:
+        return result
+
+    resolved = _resolve_conversion_inputs(args)
+    if isinstance(resolved, int):
+        return resolved
+    confluence_url, page_id = resolved
+
+    token = config.resolve_token(args.token, os.getenv("CONFLUENCE_TOKEN"))
+    if not token:
+        LOGGER.error(
+            "Missing Confluence token. Use --token, set CONFLUENCE_TOKEN, "
+            "or use --set-default-token."
+        )
+        return 1
+
+    return _run_conversion(confluence_url, page_id, token, args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kb2md/config.py

@@ -0,0 +1,113 @@
+"""Persistent configuration for kb2md."""
+
+import json
+import logging
+import os
+import stat
+import uuid
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+from kb2md.utils import normalize_url
+
+CONFIG_DIR = Path.home() / ".kb2md"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+logger = logging.getLogger(__name__)
+
+
+def _load_config() -> dict[str, Any]:
+    """Load the config file, returning an empty dict if it is missing or invalid."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        data = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning("Failed to read config file %s: %s", CONFIG_FILE, exc)
+        return {}
+
+
+def _atomic_write(path: Path, content: str, mode: int) -> None:
+    """Write ``content`` to ``path`` atomically with the given permissions.
+
+    Writes to a temporary file in the same directory with ``mode``, then
+    atomically replaces ``path``. This ensures the file is never world-readable,
+    even transiently, and that readers always see a complete file.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.parent.chmod(stat.S_IRUSR | stat.S_IWUSR | stat.S_IXUSR)
+
+    tmp_path = path.with_suffix(f".tmp.{uuid.uuid4().hex}")
+    fd = os.open(tmp_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, mode)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        os.replace(tmp_path, path)
+        # Ensure final permissions are restrictive even if replace preserved old ones.
+        path.chmod(mode)
+    except Exception:
+        with suppress(OSError):
+            tmp_path.unlink()
+        raise
+
+
+def _save_config(data: dict[str, Any]) -> None:
+    """Save ``data`` to the config file with restrictive permissions."""
+    try:
+        _atomic_write(
+            CONFIG_FILE,
+            json.dumps(data, indent=2),
+            stat.S_IRUSR | stat.S_IWUSR,
+        )
+    except OSError as exc:
+        logger.error("Failed to write config file %s: %s", CONFIG_FILE, exc)
+        raise RuntimeError(f"Could not save configuration to {CONFIG_FILE}: {exc}") from exc
+
+
+def get_default_url() -> str | None:
+    """Return the configured default Confluence URL, or None."""
+    url = _load_config().get("default_url")
+    return normalize_url(url) if url else None
+
+
+def set_default_url(url: str) -> None:
+    """Save ``url`` as the default Confluence URL."""
+    data = _load_config()
+    data["default_url"] = normalize_url(url)
+    _save_config(data)
+
+
+def get_default_token() -> str | None:
+    """Return the configured default Confluence token, or None."""
+    token = _load_config().get("default_token")
+    return token if token else None
+
+
+def set_default_token(token: str) -> None:
+    """Save ``token`` as the default Confluence token."""
+    data = _load_config()
+    data["default_token"] = token
+    _save_config(data)
+
+
+def resolve_url(cli_url: str | None, env_url: str | None) -> str:
+    """Resolve the effective Confluence URL from CLI, env, or config."""
+    if cli_url:
+        return normalize_url(cli_url)
+    if env_url:
+        return normalize_url(env_url)
+    config_url = get_default_url()
+    if config_url:
+        return config_url
+    raise ValueError("No Confluence URL provided")
+
+
+def resolve_token(cli_token: str | None, env_token: str | None) -> str | None:
+    """Resolve the effective Confluence token from CLI, env, or config."""
+    if cli_token:
+        return cli_token
+    if env_token:
+        return env_token
+    return get_default_token()