compman 1.9.0__py3-none-any.whl

compman/__main__.py

@@ -0,0 +1,4 @@
+from compman.cli import app
+
+if __name__ == "__main__":
+    app()

compman/_proc.py

@@ -0,0 +1,26 @@
+"""Shared subprocess timeout helpers.
+
+Kept free of heavy imports so that lazily loaded command modules can use it
+without pulling in AWS SDKs or the container-runtime layer.
+"""
+
+from __future__ import annotations
+
+import os
+
+# Sentinel for streaming passthru commands: omit the subprocess timeout kwarg
+# entirely so `docker logs -f`, `exec -it`, and `stats` (follow) never expire.
+PASSTHRU_UNBOUNDED = float("inf")
+
+
+def _env_timeout() -> float:
+    raw = os.environ.get("COMPMAN_TIMEOUT")
+    if raw is None:
+        return 300.0
+    try:
+        value = float(raw)
+    except ValueError:
+        return 300.0
+    if value <= 0:
+        return 300.0
+    return value

compman/_seed_assets.py

@@ -0,0 +1,39 @@
+"""Static assets embedded into generated seed projects."""
+
+from __future__ import annotations
+
+SEED_INDEX_HTML = (
+    '<!DOCTYPE html>\n'
+    '<html lang="en">\n'
+    '<head>\n'
+    '    <meta charset="UTF-8">\n'
+    '    <meta name="viewport" content="width=device-width, initial-scale=1.0">\n'
+    '    <meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">\n'
+    '    <meta http-equiv="Pragma" content="no-cache">\n'
+    '    <meta http-equiv="Expires" content="0">\n'
+    '    <title>compman Seed App</title>\n'
+    '    <style>\n'
+    '        body { font-family: system-ui, -apple-system, sans-serif; background: #0f172a; color: #f8fafc; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; }\n'
+    '        .card { background: #1e293b; border-radius: 1rem; padding: 2.5rem; border: 1px solid #334155; box-shadow: 0 25px 50px -12px rgba(0,0,0,0.5); text-align: center; max-width: 480px; width: 100%; }\n'
+    '        h1 { color: #38bdf8; margin-top: 0; font-size: 1.75rem; }\n'
+    '        .badge { background: #0284c7; color: white; padding: 0.25rem 0.75rem; border-radius: 9999px; font-size: 0.875rem; font-weight: 600; }\n'
+    '        .time { font-size: 1.15rem; font-family: monospace; color: #a5f3fc; margin: 1.5rem 0; background: #0f172a; padding: 0.75rem; border-radius: 0.5rem; border: 1px solid #1e293b; }\n'
+    '    </style>\n'
+    '</head>\n'
+    '<body>\n'
+    '    <div class="card">\n'
+    '        <h1>compman Seed App</h1>\n'
+    '        <p><span class="badge">Nginx Alpine High-Performance</span></p>\n'
+    '        <div class="time" id="clock">Loading time...</div>\n'
+    '        <p style="color: #94a3b8; font-size: 0.875rem;">Instant Sub-Millisecond Container Response</p>\n'
+    '    </div>\n'
+    '    <script>\n'
+    '        function updateTime() {\n'
+    '            document.getElementById("clock").innerText = new Date().toLocaleString();\n'
+    '        }\n'
+    '        setInterval(updateTime, 1000);\n'
+    '        updateTime();\n'
+    '    </script>\n'
+    '</body>\n'
+    '</html>\n'
+)

compman/archive.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import tarfile
+import zipfile
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+from compman.errors import CommandError
+from compman.i18n import t
+
+ZSTD_SUFFIX = ".tar.zst"
+
+
+def _load_zstd(import_module=None):
+    import importlib
+
+    loader = import_module or importlib.import_module
+    try:
+        return loader("compression.zstd")  # Python 3.14+
+    except ImportError as exc:
+        raise CommandError(t("msg.zstd_requires_py314")) from exc
+
+
+def create_tar(source_dir: Path, dest: Path, *, zstd_format: bool = False, gzip_level: int = 6) -> None:
+    """Write ``source_dir`` as a tarball at ``dest`` (gzip default, zstd opt-in)."""
+    if not zstd_format:
+        with tarfile.open(dest, "w:gz", compresslevel=gzip_level) as tar:
+            tar.add(source_dir, arcname=".")
+        return
+    zstd = _load_zstd()
+    with zstd.open(dest, "wb") as zout:
+        with tarfile.open(fileobj=zout, mode="w") as tar:
+            tar.add(source_dir, arcname=".")
+
+
+def open_tarball(path: Path):
+    """Open a local backup archive for extraction, gating zstd on 3.14+."""
+    if path.name.lower().endswith(ZSTD_SUFFIX):
+        _load_zstd()
+        return tarfile.open(path, "r:*")
+    return tarfile.open(path, "r:gz")
+
+
+def extract_tar(archive: tarfile.TarFile, destination: Path, max_bytes: int | None = None) -> None:
+    members = archive.getmembers()
+    total = 0
+    for member in members:
+        _validate_path(destination, member.name)
+        if member.issym() or member.islnk():
+            raise ValueError(f"Archive links are not allowed: {member.name}")
+        if member.isdev() or member.isfifo():
+            raise ValueError(f"Unsupported archive member type: {member.name}")
+        total += member.size
+        if max_bytes is not None and total > max_bytes:
+            raise CommandError(t("msg.deploy_limit_exceeded", limit=_limit_mb(max_bytes), size=total))
+    for member in members:
+        archive.extract(member, destination)
+
+
+def extract_zip(archive: zipfile.ZipFile, destination: Path, max_bytes: int | None = None) -> None:
+    if max_bytes is not None:
+        total = sum(member.file_size for member in archive.infolist())
+        if total > max_bytes:
+            raise CommandError(t("msg.deploy_limit_exceeded", limit=_limit_mb(max_bytes), size=total))
+    for member in archive.infolist():
+        _validate_path(destination, member.filename)
+        archive.extract(member, destination)
+
+
+def _limit_mb(max_bytes: int) -> int:
+    return (max_bytes + 1024 * 1024 - 1) // (1024 * 1024)
+
+
+def _validate_path(destination: Path, name: str) -> None:
+    if not name or PurePosixPath(name).is_absolute() or PureWindowsPath(name).is_absolute():
+        raise ValueError(f"Unsafe archive path: {name}")
+    root = destination.resolve()
+    target = (destination / name).resolve()
+    if target != root and root not in target.parents:
+        raise ValueError(f"Unsafe archive path: {name}")

compman/archive_source.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import hashlib
+import tarfile
+import zipfile
+from pathlib import Path
+
+from compman.archive import extract_tar, extract_zip
+from compman.errors import CommandError
+from compman.i18n import t
+
+ARCHIVE_SUFFIXES = (".tar.gz", ".tgz", ".zip")
+_HASH_CHUNK_SIZE = 1024 * 1024
+
+
+def has_archive_suffix(path: str) -> bool:
+    return path.lower().endswith(ARCHIVE_SUFFIXES)
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as source:
+        for chunk in iter(lambda: source.read(_HASH_CHUNK_SIZE), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def ensure_digest(actual: str, expected: str) -> None:
+    if actual.lower() != expected.lower():
+        raise CommandError(t("msg.deploy_checksum_mismatch", expected=expected, actual=actual))
+
+
+def extract_archive(archive_path: Path, extract_dir: Path, max_bytes: int | None = None) -> Path:
+    extract_dir.mkdir()
+    if archive_path.name.lower().endswith(".zip"):
+        with zipfile.ZipFile(archive_path) as zip_source:
+            extract_zip(zip_source, extract_dir, max_bytes=max_bytes)
+    else:
+        with tarfile.open(archive_path) as tar_source:
+            extract_tar(tar_source, extract_dir, max_bytes=max_bytes)
+
+    contents = [path for path in extract_dir.iterdir() if path.name != ".gitkeep"]
+    return contents[0] if len(contents) == 1 and contents[0].is_dir() else extract_dir

compman/backup_store.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import shutil
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+import typer
+
+from compman.errors import CommandError, ConfigError
+from compman.i18n import t
+from compman.s3_source import create_client, s3_error_hint
+
+
+@dataclass(frozen=True)
+class LocalBackupStore:
+    """Backups stored in a directory inside the config tree."""
+
+    root: Path
+
+    @property
+    def is_remote(self) -> bool:
+        return False
+
+
+@dataclass(frozen=True)
+class S3BackupStore:
+    """Backups stored under ``s3://bucket/prefix``."""
+
+    bucket: str
+    prefix: str
+
+    @property
+    def is_remote(self) -> bool:
+        return True
+
+
+BackupStore = LocalBackupStore | S3BackupStore
+
+
+def parse_backup_store(value: str) -> BackupStore:
+    """Parse a ``dirs.backup`` value into a typed backup store."""
+    scheme, sep, rest = value.partition("://")
+    if not sep:
+        return LocalBackupStore(root=Path(value))
+    if scheme != "s3":
+        raise ConfigError(
+            f"'dirs.backup' must be a relative path or an 's3://bucket/prefix' URI: {value}"
+        )
+    bucket, _, prefix = rest.partition("/")
+    if not bucket:
+        raise ConfigError(f"'dirs.backup' S3 URI is missing a bucket name: {value}")
+    return S3BackupStore(bucket=bucket, prefix=prefix.strip("/"))
+
+
+def local_root(store: BackupStore) -> Path:
+    """Return the filesystem root of a local store."""
+    if not isinstance(store, LocalBackupStore):
+        raise ValueError("backup store is not local")
+    return store.root
+
+
+def archive_location(store: BackupStore, name: str) -> str:
+    """Return the user-facing location of an archive in the store."""
+    if isinstance(store, LocalBackupStore):
+        return str(store.root / name)
+    prefix = f"{store.prefix}/" if store.prefix else ""
+    return f"s3://{store.bucket}/{prefix}{name}"
+
+
+def _object_key(store: S3BackupStore, name: str) -> str:
+    return f"{store.prefix}/{name}" if store.prefix else name
+
+
+def new_backup_paths(store: BackupStore, stack: str, kind: str, *, zstd_format: bool = False) -> tuple[Path, Path]:
+    """Return a fresh (directory, tarball) pair for a new backup archive."""
+    if isinstance(store, LocalBackupStore):
+        root = store.root
+        now = datetime.now()
+        timestamp = now.strftime("%Y%m%d_%H%M%S")
+        backup_name = f"{stack}.{kind}.{timestamp}"
+        backup_dir = root / backup_name
+        tarball = root / f"{backup_name}{_suffix_for(zstd_format)}"
+        if backup_dir.exists() or tarball.exists():
+            timestamp = now.strftime("%Y%m%d_%H%M%S_%f")
+            backup_name = f"{stack}.{kind}.{timestamp}"
+            backup_dir = root / backup_name
+            tarball = root / f"{backup_name}{_suffix_for(zstd_format)}"
+        backup_dir.mkdir(parents=True, exist_ok=True)
+        return backup_dir, tarball
+    workdir = Path(tempfile.mkdtemp(prefix="compman-"))
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    tarball = workdir / f"{stack}.{kind}.{timestamp}{_suffix_for(zstd_format)}"
+    return workdir, tarball
+
+
+def put_archive(store: BackupStore, name: str, local_path: Path) -> str:
+    """Publish the finished archive and return its user-facing location.
+
+    A local store keeps archives in place. A remote store uploads the archive,
+    verifies the stored size, and then deletes the staged copy together with
+    its staging directory; on failure the staged archive is kept and named in
+    the error.
+    """
+    if isinstance(store, LocalBackupStore):
+        return str(local_path)
+    uri = archive_location(store, name)
+    local_size = local_path.stat().st_size
+    try:
+        key = _object_key(store, name)
+        s3 = create_client()
+        s3.upload_file(
+            Filename=str(local_path),
+            Bucket=store.bucket,
+            Key=key,
+            ExtraArgs={"ContentType": "application/zstd" if name.endswith(".tar.zst") else "application/gzip"},
+        )
+        remote_size = int(s3.head_object(Bucket=store.bucket, Key=key)["ContentLength"])
+    except Exception as exc:
+        hint = s3_error_hint(exc, uri) or exc
+        detail = f"{hint}; staged archive kept at {local_path}"
+        raise CommandError(t("msg.backup_store_error", detail=detail)) from exc
+    if remote_size != local_size:
+        detail = (
+            f"uploaded size {remote_size} != local size {local_size}; "
+            f"staged archive kept at {local_path}"
+        )
+        raise CommandError(t("msg.backup_store_error", detail=detail))
+    workdir = local_path.parent
+    local_path.unlink(missing_ok=True)
+    shutil.rmtree(workdir, ignore_errors=True)
+    return uri
+
+
+def fetch_archive(store: BackupStore, name: str, dest: Path) -> None:
+    """Materialize ``name`` at ``dest``.
+
+    Local archives are read in place, so fetching is a no-op; remote stores
+    download the object to ``dest``.
+    """
+    if isinstance(store, LocalBackupStore):
+        return
+    key = _object_key(store, name)
+    typer.echo(t("msg.backup_downloading", name=name, path=f"s3://{store.bucket}/{key}"))
+    try:
+        create_client().download_file(store.bucket, key, str(dest))
+    except Exception as exc:
+        hint = s3_error_hint(exc, f"s3://{store.bucket}/{key}") or exc
+        raise CommandError(t("msg.backup_store_error", detail=str(hint))) from exc
+
+
+def find_archive(store: BackupStore, stack: str, kind: str, timestamp: str) -> str | None:
+    """Return the stored base name (with suffix) for ``timestamp``, or None."""
+    for suffix in (".tar.gz", ".tar.zst"):
+        candidate = f"{stack}.{kind}.{timestamp}{suffix}"
+        if isinstance(store, LocalBackupStore):
+            if (store.root / candidate).is_file():
+                return candidate
+            continue
+        try:
+            create_client().head_object(Bucket=store.bucket, Key=_object_key(store, candidate))
+            return candidate
+        except Exception as exc:
+            from botocore.exceptions import ClientError as _ClientError
+
+            if isinstance(exc, _ClientError) and str(
+                exc.response.get("Error", {}).get("Code", "")
+            ) in ("404", "NoSuchKey", "NotFound"):
+                continue
+            raise
+    return None
+
+
+def delete_archive(store: BackupStore, name: str) -> None:
+    """Delete the archive ``name`` (a base name without extension) from the store.
+
+    Both gzip and zstd variants are removed when present; S3 deletions are
+    idempotent, so a missing object is not an error.
+    """
+    if isinstance(store, LocalBackupStore):
+        for suffix in (".tar.gz", ".tar.zst"):
+            (store.root / f"{name}{suffix}").unlink(missing_ok=True)
+        return
+    client = create_client()
+    for suffix in (".tar.gz", ".tar.zst"):
+        try:
+            client.delete_object(
+                Bucket=store.bucket, Key=_object_key(store, f"{name}{suffix}")
+            )
+        except Exception as exc:
+            uri = archive_location(store, f"{name}{suffix}")
+            hint = s3_error_hint(exc, uri) or exc
+            raise CommandError(t("msg.backup_store_error", detail=str(hint))) from exc
+
+
+def list_archives(store: BackupStore, stack: str, kind: str) -> list[str]:
+    """Return backup timestamps for ``stack`` and ``kind``, most recent first."""
+    if isinstance(store, LocalBackupStore):
+        pattern = f"{stack}.{kind}."
+        names = [
+            entry.name[len(pattern):]
+            for entry in store.root.glob(f"{pattern}*")
+            if entry.name.endswith((".tar.gz", ".tar.zst"))
+        ]
+        return sorted((_strip_suffix(n) for n in names), reverse=True)
+    prefix = f"{store.prefix}/" if store.prefix else ""
+    marker = f"{prefix}{stack}.{kind}."
+    timestamps: list[str] = []
+    try:
+        paginator = create_client().get_paginator("list_objects_v2")
+        pages = paginator.paginate(Bucket=store.bucket, Prefix=prefix)
+        for page in pages:
+            for obj in page.get("Contents", []):
+                key = obj["Key"]
+                if key.startswith(marker) and key.endswith((".tar.gz", ".tar.zst")):
+                    timestamps.append(_strip_suffix(key[len(marker):]))
+    except Exception as exc:
+        hint = s3_error_hint(exc, f"s3://{store.bucket}/{prefix}") or exc
+        raise CommandError(t("msg.backup_store_error", detail=str(hint))) from exc
+    return sorted(timestamps, reverse=True)
+
+
+@contextmanager
+def staged_archive(store: BackupStore, name: str) -> Iterator[Path]:
+    """Yield a readable path for ``name``, staging remote archives in a tempdir.
+
+    Local stores yield the archive where it lies; remote stores download into
+    a private staging directory that is removed on exit.
+    """
+    if isinstance(store, LocalBackupStore):
+        yield store.root / name
+        return
+    stage = Path(tempfile.mkdtemp(prefix="compman-"))
+    try:
+        tarball = stage / name
+        fetch_archive(store, name, tarball)
+        yield tarball
+    finally:
+        shutil.rmtree(stage, ignore_errors=True)
+
+
+def _suffix_for(zstd_format: bool) -> str:
+    return ".tar.zst" if zstd_format else ".tar.gz"
+
+
+def _strip_suffix(name: str) -> str:
+    for suffix in (".tar.zst", ".tar.gz"):
+        if name.endswith(suffix):
+            return name[: -len(suffix)]
+    return name