bluefox-cloud 0.1.0__tar.gz

bluefox_cloud-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,11 @@
+name: CI
+on: [push, pull_request]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: make install
+      - run: make ci

bluefox_cloud-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

bluefox_cloud-0.1.0/.gitignore

@@ -0,0 +1,88 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# macOS
+.DS_Store
+
+# UV
+#uv.lock
+
+# Cursor
+.cursorignore
+.cursorindexingignore

bluefox_cloud-0.1.0/Dockerfile.docs

@@ -0,0 +1,15 @@
+FROM python:3.12-slim AS builder
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+RUN uv pip install --system mkdocs-material mkdocs-minify-plugin
+
+COPY mkdocs.yml ./
+COPY docs/ docs/
+RUN mkdocs build
+
+FROM nginx:alpine
+COPY landing/ /usr/share/nginx/html/
+COPY --from=builder /app/site /usr/share/nginx/html/docs/
+EXPOSE 80

bluefox_cloud-0.1.0/Makefile

@@ -0,0 +1,45 @@
+.PHONY: install test lint format type-check ci fix clean docs docs-build landing
+
+# Install all dependencies (dev + test)
+install:
+	uv sync --group dev --extra test
+
+# Run all tests
+test:
+	uv run pytest tests/ -v --tb=short
+
+# Lint with ruff
+lint:
+	uv run ruff check bluefox_cloud/ tests/
+
+# Type check with ty
+type-check:
+	uv run ty check bluefox_cloud/ tests/
+
+# Check formatting
+format:
+	uv run ruff format --check bluefox_cloud/ tests/
+
+# Full CI pipeline: lint, format, type-check, tests
+ci: lint format type-check test
+
+# Auto-fix lint issues
+fix:
+	uv run ruff check --fix bluefox_cloud/ tests/
+	uv run ruff format bluefox_cloud/ tests/
+
+# Serve docs locally
+docs:
+	uv run mkdocs serve
+
+# Build docs
+docs-build:
+	uv run mkdocs build
+
+# Serve landing page locally
+landing:
+	python -m http.server 8090 --directory landing
+
+# Remove build artifacts
+clean:
+	rm -rf site/ dist/ *.egg-info .pytest_cache

bluefox_cloud-0.1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: bluefox-cloud
+Version: 0.1.0
+Summary: Infrastructure logic for BlueFox Cloud — Docker Swarm, Traefik, Cloudflare, and release pipeline
+Project-URL: Homepage, https://bluefox-cloud.bluefox.software
+Project-URL: Documentation, https://bluefox-cloud.bluefox.software/docs/
+Project-URL: Repository, https://github.com/blue-fox-software/bluefox-cloud
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.0
+Requires-Dist: bluefox-yml>=0.1.0
+Requires-Dist: docker>=7.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# bluefox-cloud
+
+Infrastructure logic for BlueFox Cloud — Docker Swarm, Traefik, Cloudflare, and release pipeline.

bluefox_cloud-0.1.0/README.md

@@ -0,0 +1,3 @@
+# bluefox-cloud
+
+Infrastructure logic for BlueFox Cloud — Docker Swarm, Traefik, Cloudflare, and release pipeline.

bluefox_cloud-0.1.0/bluefox_cloud/cloudflare/__init__.py

@@ -0,0 +1,4 @@
+from bluefox_cloud.cloudflare.client import CloudflareClient
+from bluefox_cloud.cloudflare.dns import DNSRecord, DNSRecordType, Zone
+
+__all__ = ["CloudflareClient", "DNSRecord", "DNSRecordType", "Zone"]

bluefox_cloud-0.1.0/bluefox_cloud/cloudflare/client.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import httpx
+
+from bluefox_cloud.cloudflare.dns import DNSRecord, DNSRecordType, Zone
+
+BASE_URL = "https://api.cloudflare.com/client/v4"
+
+
+class CloudflareError(Exception):
+    """Raised when the Cloudflare API returns an error."""
+
+    def __init__(self, status_code: int, errors: list[dict]) -> None:
+        self.status_code = status_code
+        self.errors = errors
+        messages = "; ".join(e.get("message", str(e)) for e in errors)
+        super().__init__(f"Cloudflare API error ({status_code}): {messages}")
+
+
+class CloudflareClient:
+    """Async Cloudflare API client using httpx."""
+
+    def __init__(
+        self,
+        api_token: str,
+        *,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._client = client or httpx.AsyncClient(
+            base_url=BASE_URL,
+            headers={
+                "Authorization": f"Bearer {api_token}",
+                "Content-Type": "application/json",
+            },
+            timeout=30.0,
+        )
+        self._owns_client = client is None
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> CloudflareClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    def _check_response(self, response: httpx.Response) -> dict:
+        data = response.json()
+        if not data.get("success", False):
+            raise CloudflareError(
+                status_code=response.status_code,
+                errors=data.get("errors", [{"message": "Unknown error"}]),
+            )
+        return data
+
+    # --- Zones ---
+
+    async def get_zone(self, zone_id: str) -> Zone:
+        """Get a zone by ID."""
+        resp = await self._client.get(f"/zones/{zone_id}")
+        data = self._check_response(resp)
+        result = data["result"]
+        return Zone(id=result["id"], name=result["name"], status=result["status"])
+
+    async def list_zones(self, *, name: str | None = None) -> list[Zone]:
+        """List zones, optionally filtered by name."""
+        params: dict[str, str] = {}
+        if name:
+            params["name"] = name
+        resp = await self._client.get("/zones", params=params)
+        data = self._check_response(resp)
+        return [Zone(id=z["id"], name=z["name"], status=z["status"]) for z in data["result"]]
+
+    # --- DNS Records ---
+
+    async def list_records(
+        self,
+        zone_id: str,
+        *,
+        name: str | None = None,
+        record_type: DNSRecordType | None = None,
+    ) -> list[DNSRecord]:
+        """List DNS records in a zone."""
+        params: dict[str, str] = {}
+        if name:
+            params["name"] = name
+        if record_type:
+            params["type"] = record_type.value
+        resp = await self._client.get(f"/zones/{zone_id}/dns_records", params=params)
+        data = self._check_response(resp)
+        return [
+            DNSRecord(
+                id=r["id"],
+                zone_id=zone_id,
+                name=r["name"],
+                type=DNSRecordType(r["type"]),
+                content=r["content"],
+                proxied=r.get("proxied", False),
+                ttl=r.get("ttl", 1),
+            )
+            for r in data["result"]
+        ]
+
+    async def create_record(
+        self,
+        zone_id: str,
+        *,
+        name: str,
+        record_type: DNSRecordType,
+        content: str,
+        proxied: bool = False,
+        ttl: int = 1,
+    ) -> DNSRecord:
+        """Create a DNS record."""
+        payload = {
+            "type": record_type.value,
+            "name": name,
+            "content": content,
+            "proxied": proxied,
+            "ttl": ttl,
+        }
+        resp = await self._client.post(f"/zones/{zone_id}/dns_records", json=payload)
+        data = self._check_response(resp)
+        r = data["result"]
+        return DNSRecord(
+            id=r["id"],
+            zone_id=zone_id,
+            name=r["name"],
+            type=DNSRecordType(r["type"]),
+            content=r["content"],
+            proxied=r.get("proxied", False),
+            ttl=r.get("ttl", 1),
+        )
+
+    async def update_record(
+        self,
+        zone_id: str,
+        record_id: str,
+        *,
+        name: str,
+        record_type: DNSRecordType,
+        content: str,
+        proxied: bool = False,
+        ttl: int = 1,
+    ) -> DNSRecord:
+        """Update a DNS record (full replace)."""
+        payload = {
+            "type": record_type.value,
+            "name": name,
+            "content": content,
+            "proxied": proxied,
+            "ttl": ttl,
+        }
+        resp = await self._client.put(f"/zones/{zone_id}/dns_records/{record_id}", json=payload)
+        data = self._check_response(resp)
+        r = data["result"]
+        return DNSRecord(
+            id=r["id"],
+            zone_id=zone_id,
+            name=r["name"],
+            type=DNSRecordType(r["type"]),
+            content=r["content"],
+            proxied=r.get("proxied", False),
+            ttl=r.get("ttl", 1),
+        )
+
+    async def delete_record(self, zone_id: str, record_id: str) -> None:
+        """Delete a DNS record."""
+        resp = await self._client.delete(f"/zones/{zone_id}/dns_records/{record_id}")
+        self._check_response(resp)
+
+    async def upsert_record(
+        self,
+        zone_id: str,
+        *,
+        name: str,
+        record_type: DNSRecordType,
+        content: str,
+        proxied: bool = False,
+        ttl: int = 1,
+    ) -> DNSRecord:
+        """Create or update a DNS record. Matches on name + type."""
+        existing = await self.list_records(zone_id, name=name, record_type=record_type)
+        if existing:
+            return await self.update_record(
+                zone_id,
+                existing[0].id,
+                name=name,
+                record_type=record_type,
+                content=content,
+                proxied=proxied,
+                ttl=ttl,
+            )
+        return await self.create_record(
+            zone_id,
+            name=name,
+            record_type=record_type,
+            content=content,
+            proxied=proxied,
+            ttl=ttl,
+        )

bluefox_cloud-0.1.0/bluefox_cloud/cloudflare/dns.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class DNSRecordType(StrEnum):
+    A = "A"
+    AAAA = "AAAA"
+    CNAME = "CNAME"
+    TXT = "TXT"
+    MX = "MX"
+
+
+class Zone(BaseModel):
+    id: str
+    name: str
+    status: str
+
+
+class DNSRecord(BaseModel):
+    id: str
+    zone_id: str
+    name: str
+    type: DNSRecordType
+    content: str
+    proxied: bool = False
+    ttl: int = 1  # 1 = automatic

bluefox_cloud-0.1.0/bluefox_cloud/cloudflare/domains.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from bluefox_cloud.cloudflare.client import CloudflareClient
+from bluefox_cloud.cloudflare.dns import DNSRecordType
+
+
+async def setup_subdomain(
+    client: CloudflareClient,
+    zone_id: str,
+    *,
+    subdomain: str,
+    server_ip: str,
+) -> None:
+    """Point a subdomain A record at the server IP."""
+    await client.upsert_record(
+        zone_id,
+        name=subdomain,
+        record_type=DNSRecordType.A,
+        content=server_ip,
+        proxied=False,
+    )
+
+
+async def setup_wildcard(
+    client: CloudflareClient,
+    zone_id: str,
+    *,
+    server_ip: str,
+) -> None:
+    """Create a wildcard A record for *.domain."""
+    await client.upsert_record(
+        zone_id,
+        name="*",
+        record_type=DNSRecordType.A,
+        content=server_ip,
+        proxied=False,
+    )
+
+
+async def verify_custom_domain(
+    client: CloudflareClient,
+    zone_id: str,
+    *,
+    domain: str,
+    expected_cname: str,
+) -> bool:
+    """Check if a custom domain has a CNAME pointing to the expected target."""
+    records = await client.list_records(zone_id, name=domain, record_type=DNSRecordType.CNAME)
+    return any(r.content == expected_cname for r in records)

bluefox_cloud-0.1.0/bluefox_cloud/config.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel
+
+DEFAULT_CONFIG_DIR = Path.home() / ".bluefox"
+DEFAULT_CONFIG_PATH = DEFAULT_CONFIG_DIR / "cloud.yml"
+
+
+class ServerConfig(BaseModel):
+    ip: str = ""
+    ssh_port: int = 22
+    domain: str = ""
+    user: str = "deploy"
+
+
+class CloudflareConfig(BaseModel):
+    api_token: str = ""
+    zone_id: str = ""
+
+
+class CloudConfig(BaseModel):
+    platform_url: str = ""
+    api_key: str = ""
+    local: bool = False
+    server: ServerConfig = ServerConfig()
+    cloudflare: CloudflareConfig = CloudflareConfig()
+
+
+def load_config(path: Path = DEFAULT_CONFIG_PATH) -> CloudConfig:
+    """Load cloud config from YAML file. Raises FileNotFoundError if missing."""
+    raw = yaml.safe_load(path.read_text())
+    if raw is None:
+        return CloudConfig()
+    return CloudConfig.model_validate(raw)
+
+
+def save_config(config: CloudConfig, path: Path = DEFAULT_CONFIG_PATH) -> None:
+    """Save cloud config to YAML file. Creates parent directories if needed."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = config.model_dump()
+    path.write_text(yaml.dump(data, default_flow_style=False, sort_keys=False))

bluefox_cloud-0.1.0/bluefox_cloud/ssh/__init__.py

@@ -0,0 +1,3 @@
+from bluefox_cloud.ssh.client import SSHResult, ssh_run, ssh_upload_and_run
+
+__all__ = ["SSHResult", "ssh_run", "ssh_upload_and_run"]

bluefox_cloud-0.1.0/bluefox_cloud/ssh/client.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import subprocess
+from importlib import resources
+from pathlib import Path
+
+from pydantic import BaseModel
+
+
+class SSHResult(BaseModel):
+    stdout: str
+    stderr: str
+    returncode: int
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+def _ssh_base_args(host: str, user: str, port: int) -> list[str]:
+    return [
+        "ssh",
+        "-o",
+        "StrictHostKeyChecking=accept-new",
+        "-o",
+        "ConnectTimeout=10",
+        "-p",
+        str(port),
+        f"{user}@{host}",
+    ]
+
+
+def ssh_run(
+    host: str,
+    user: str,
+    port: int,
+    command: str,
+    *,
+    timeout: int = 300,
+) -> SSHResult:
+    """Execute a command on a remote host via SSH."""
+    args = [*_ssh_base_args(host, user, port), command]
+    result = subprocess.run(args, capture_output=True, text=True, timeout=timeout)
+    return SSHResult(stdout=result.stdout, stderr=result.stderr, returncode=result.returncode)
+
+
+def _scp_args(host: str, user: str, port: int, local_path: str, remote_path: str) -> list[str]:
+    return [
+        "scp",
+        "-o",
+        "StrictHostKeyChecking=accept-new",
+        "-o",
+        "ConnectTimeout=10",
+        "-P",
+        str(port),
+        local_path,
+        f"{user}@{host}:{remote_path}",
+    ]
+
+
+def ssh_upload_and_run(
+    host: str,
+    user: str,
+    port: int,
+    script_path: Path | str,
+    *,
+    timeout: int = 600,
+) -> SSHResult:
+    """Upload a script via SCP and execute it on the remote host."""
+    script_path = Path(script_path)
+    remote_path = f"/tmp/{script_path.name}"
+
+    # Upload
+    scp_args = _scp_args(host, user, port, str(script_path), remote_path)
+    scp_result = subprocess.run(scp_args, capture_output=True, text=True, timeout=60)
+    if scp_result.returncode != 0:
+        return SSHResult(
+            stdout=scp_result.stdout,
+            stderr=f"SCP upload failed: {scp_result.stderr}",
+            returncode=scp_result.returncode,
+        )
+
+    # Execute
+    return ssh_run(host, user, port, f"bash {remote_path}", timeout=timeout)
+
+
+def get_bundled_script(name: str) -> Path:
+    """Get the path to a bundled shell script in the ssh/scripts directory."""
+    scripts = resources.files("bluefox_cloud.ssh") / "scripts"
+    script = scripts / name
+    if not script.is_file():
+        raise FileNotFoundError(f"Bundled script not found: {name}")
+    return Path(str(script))
+
+
+def ssh_upload_and_run_bundled(
+    host: str,
+    user: str,
+    port: int,
+    script_name: str,
+    *,
+    timeout: int = 600,
+) -> SSHResult:
+    """Upload and run a bundled script from bluefox_cloud/ssh/scripts/."""
+    script_path = get_bundled_script(script_name)
+    return ssh_upload_and_run(host, user, port, script_path, timeout=timeout)

bluefox_cloud-0.1.0/bluefox_cloud/ssh/scripts/harden.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Server hardening script — placeholder for now.
+# Will be fleshed out during Step 14 (server hardening).
+set -euo pipefail
+echo "harden.sh: placeholder"

bluefox_cloud-0.1.0/bluefox_cloud/ssh/scripts/install_docker.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Docker installation script — placeholder for now.
+# Will be fleshed out during Step 15 (Docker + Swarm + Network).
+set -euo pipefail
+echo "install_docker.sh: placeholder"

bluefox_cloud-0.1.0/bluefox_cloud/swarm/__init__.py

@@ -0,0 +1,3 @@
+from bluefox_cloud.swarm.client import SwarmClient
+
+__all__ = ["SwarmClient"]