xgic-gitlab-cli 0.1.1__py3-none-any.whl

xgic/cli/gitlab/__init__.py

@@ -0,0 +1,5 @@
+"""XGIC CLI GitLab module (``xgic.cli.gitlab``)."""
+
+__version__ = "0.1.1"
+
+__all__ = ["__version__"]

xgic/cli/gitlab/commands/__init__.py

@@ -0,0 +1 @@
+"""GitLab CLI command handlers."""

xgic/cli/gitlab/commands/backup.py

@@ -0,0 +1,86 @@
+"""``xgic gitlab backup`` — create a GitLab EE backup via Compose exec."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from xgic.cli.gitlab.compose import ComposeRunner
+from xgic.cli.gitlab.config import resolve_config
+from xgic.cli.utils.output import print_error, print_info, print_success, print_warning
+
+
+def run_backup(args: argparse.Namespace) -> int:
+    """Run ``gitlab-backup create`` inside the GitLab EE service container."""
+    cfg = resolve_config(args)
+    runner = ComposeRunner(cfg)
+    report: dict[str, Any] = {
+        "ok": False,
+        "action": "backup",
+        "config": cfg.public_dict(),
+        "command": [
+            "gitlab-backup",
+            "create",
+        ],
+        "detail": "",
+    }
+
+    if not runner.available():
+        report["detail"] = "docker CLI not found on PATH"
+        return _emit(args, report, 1)
+
+    running = runner.running_services()
+    if cfg.gitlab_service not in running:
+        report["detail"] = (
+            f"service {cfg.gitlab_service!r} is not running "
+            f"(running: {running or 'none'})"
+        )
+        return _emit(args, report, 1)
+
+    cmd = ["gitlab-backup", "create"]
+    # STRATEGY=copy is common for volume-friendly backups; keep optional via env later.
+    if cfg.dry_run:
+        report["ok"] = True
+        report["detail"] = (
+            f"dry-run: would exec in {cfg.gitlab_service}: {' '.join(cmd)} "
+            f"(host backup dir hint: {cfg.backup_dir})"
+        )
+        return _emit(args, report, 0)
+
+    print_info(f"Creating backup in service {cfg.gitlab_service}…")
+    proc = runner.exec_service(cfg.gitlab_service, cmd, dry_run=False)
+    if proc is None:
+        report["detail"] = "exec did not run"
+        return _emit(args, report, 1)
+
+    report["returncode"] = proc.returncode
+    report["stdout_tail"] = (proc.stdout or "")[-2000:]
+    report["stderr_tail"] = (proc.stderr or "")[-2000:]
+    if proc.returncode == 0:
+        report["ok"] = True
+        report["detail"] = (
+            f"backup create completed; copies typically land under the container "
+            f"backup path (host map often {cfg.backup_dir})"
+        )
+        return _emit(args, report, 0)
+
+    report["detail"] = f"gitlab-backup create failed (exit {proc.returncode})"
+    return _emit(args, report, proc.returncode or 1)
+
+
+def _emit(args: argparse.Namespace, report: dict[str, Any], exit_code: int) -> int:
+    if getattr(args, "json", False):
+        print(json.dumps(report, indent=2))
+        return exit_code
+
+    if report["ok"]:
+        print_success(report["detail"] or "Backup OK")
+    else:
+        print_error(report["detail"] or "Backup failed")
+
+    print_info(f"Service: {report['config']['gitlab_service']}")
+    print_info(f"Compose: {report['config']['compose_file']}")
+    if report.get("stderr_tail"):
+        print_warning(report["stderr_tail"][:500])
+    return exit_code

xgic/cli/gitlab/commands/health.py

@@ -0,0 +1,148 @@
+"""``xgic gitlab health`` — Compose + optional HTTP readiness checks."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from xgic.cli.gitlab.compose import ComposeRunner
+from xgic.cli.gitlab.config import resolve_config
+from xgic.cli.utils.output import print_error, print_info, print_success, print_warning
+
+
+def _http_ok(url: str, timeout: float = 5.0) -> tuple[bool, str]:
+    try:
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+            code = getattr(resp, "status", 200)
+            if 200 <= int(code) < 400:
+                return True, f"HTTP {code}"
+            return False, f"HTTP {code}"
+    except urllib.error.HTTPError as exc:
+        return False, f"HTTP {exc.code}"
+    except Exception as exc:  # noqa: BLE001 — surface any transport failure
+        return False, str(exc)
+
+
+def run_health(args: argparse.Namespace) -> int:
+    """Check stack service presence and optional HTTP health endpoints."""
+    cfg = resolve_config(args)
+    runner = ComposeRunner(cfg)
+    report: dict[str, Any] = {
+        "ok": False,
+        "config": cfg.public_dict(),
+        "docker_available": runner.available(),
+        "running_services": [],
+        "checks": [],
+    }
+
+    if not runner.available():
+        report["checks"].append(
+            {"name": "docker", "ok": False, "detail": "docker CLI not found on PATH"}
+        )
+        return _emit(args, report, exit_code=1)
+
+    running = runner.running_services()
+    report["running_services"] = running
+    report["checks"].append(
+        {
+            "name": "compose_ps",
+            "ok": True,
+            "detail": f"{len(running)} running service(s)",
+        }
+    )
+
+    for service, label in (
+        (cfg.xgic_service, "orchestration_service"),
+        (cfg.gitlab_service, "gitlab_ee_service"),
+    ):
+        present = service in running
+        report["checks"].append(
+            {
+                "name": label,
+                "ok": present,
+                "detail": f"{service}: {'running' if present else 'not running'}",
+            }
+        )
+
+    if cfg.gitlab_url:
+        health_url = cfg.gitlab_url.rstrip("/") + "/-/health"
+        ok, detail = _http_ok(health_url)
+        report["checks"].append(
+            {"name": "gitlab_http_health", "ok": ok, "detail": f"{health_url} → {detail}"}
+        )
+    else:
+        report["checks"].append(
+            {
+                "name": "gitlab_http_health",
+                "ok": True,
+                "detail": "skipped (set GITLAB_URL or --url to enable)",
+                "skipped": True,
+            }
+        )
+
+    # Optional local orchestration healthz when service is up (container network not required;
+    # operators may publish XGIC_GITLAB_PORT — we only probe if --url-style not used).
+    # Probe is best-effort via docker compose exec curl if service running.
+    if cfg.xgic_service in running and not cfg.dry_run:
+        proc = runner.exec_service(
+            cfg.xgic_service,
+            ["curl", "-fsS", "http://127.0.0.1:8080/healthz"],
+            dry_run=False,
+        )
+        ok = proc is not None and proc.returncode == 0
+        detail = "ok" if ok else (proc.stderr or proc.stdout or "failed" if proc else "n/a")
+        report["checks"].append(
+            {"name": "xgic_healthz", "ok": ok, "detail": str(detail).strip()[:200]}
+        )
+    elif cfg.dry_run and cfg.xgic_service in running:
+        report["checks"].append(
+            {
+                "name": "xgic_healthz",
+                "ok": True,
+                "detail": "dry-run: would exec curl healthz in orchestration service",
+                "skipped": True,
+            }
+        )
+
+    critical = [
+        c
+        for c in report["checks"]
+        if not c.get("skipped") and c["name"] in {"docker", "orchestration_service", "gitlab_ee_service", "gitlab_http_health", "xgic_healthz"}
+    ]
+    # compose_ps alone is not enough; require gitlab-ee running for overall ok
+    gitlab_ok = any(
+        c["name"] == "gitlab_ee_service" and c["ok"] for c in report["checks"]
+    )
+    failed = [c for c in critical if not c["ok"]]
+    report["ok"] = gitlab_ok and not failed
+
+    return _emit(args, report, exit_code=0 if report["ok"] else 1)
+
+
+def _emit(args: argparse.Namespace, report: dict[str, Any], *, exit_code: int) -> int:
+    if getattr(args, "json", False):
+        print(json.dumps(report, indent=2))
+        return exit_code
+
+    if report["ok"]:
+        print_success("GitLab stack health: OK")
+    else:
+        print_error("GitLab stack health: issues detected")
+
+    print_info(f"Compose: {report['config']['compose_file']} (project {report['config']['project_name']})")
+    if report["running_services"]:
+        print_info("Running: " + ", ".join(report["running_services"]))
+    else:
+        print_warning("No running Compose services detected")
+
+    for check in report["checks"]:
+        status = "ok" if check["ok"] else "FAIL"
+        if check.get("skipped"):
+            status = "skip"
+        print_info(f"[{status}] {check['name']}: {check['detail']}")
+
+    return exit_code

xgic/cli/gitlab/commands/info.py

@@ -0,0 +1,40 @@
+"""``xgic gitlab info`` — module status."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from xgic.cli.gitlab import __version__
+from xgic.cli.utils.output import print_info, print_success
+
+
+def run_info(args: argparse.Namespace) -> int:
+    """Print GitLab CLI module identity and capabilities."""
+    payload = {
+        "module": "xgic.cli.gitlab",
+        "package": "xgic-gitlab-cli",
+        "version": __version__,
+        "status": "experimental",
+        "commands": ["info", "health", "backup", "restore"],
+        "planned": [
+            "graphql-backed ops (optional extra)",
+        ],
+        "repository": "https://github.com/xgic/gitlab-cli",
+        "graph_client": "https://github.com/xgic/gitlab-graphql",
+        "config": {
+            "compose_file": "XGIC_GITLAB_COMPOSE_FILE / --compose-file",
+            "gitlab_url": "GITLAB_URL / --url (no default host)",
+            "token": "GITLAB_TOKEN / --token (never logged)",
+        },
+    }
+    if getattr(args, "json", False):
+        print(json.dumps(payload, indent=2))
+        return 0
+
+    print_success(f"XGIC GitLab CLI {__version__} (experimental)")
+    print_info("Namespace: xgic.cli.gitlab")
+    print_info("Repo: https://github.com/xgic/gitlab-cli")
+    print_info("Commands: info, health, backup, restore")
+    print_info("Config via env/flags only — no private host defaults")
+    return 0

xgic/cli/gitlab/commands/restore.py

@@ -0,0 +1,108 @@
+"""``xgic gitlab restore`` — restore a GitLab EE backup (destructive)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from typing import Any
+
+from xgic.cli.gitlab.compose import ComposeRunner
+from xgic.cli.gitlab.config import resolve_config
+from xgic.cli.utils.output import print_error, print_info, print_success, print_warning
+
+_BACKUP_ID_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def run_restore(args: argparse.Namespace) -> int:
+    """Restore from a backup id via ``gitlab-backup restore`` in the EE container.
+
+    Destructive: requires ``--yes`` unless ``--dry-run``.
+    """
+    cfg = resolve_config(args)
+    backup_id = str(getattr(args, "backup_id", "") or "").strip()
+    yes = bool(getattr(args, "yes", False))
+
+    report: dict[str, Any] = {
+        "ok": False,
+        "action": "restore",
+        "config": cfg.public_dict(),
+        "backup_id": backup_id,
+        "detail": "",
+    }
+
+    if not backup_id or not _BACKUP_ID_RE.match(backup_id):
+        report["detail"] = (
+            "invalid or missing backup id (use alphanumeric, dot, underscore, hyphen)"
+        )
+        return _emit(args, report, 2)
+
+    if not yes and not cfg.dry_run:
+        report["detail"] = (
+            "refusing restore without --yes (destructive). "
+            "Re-run with --yes after confirming the backup id, or use --dry-run."
+        )
+        return _emit(args, report, 2)
+
+    runner = ComposeRunner(cfg)
+    if not runner.available():
+        report["detail"] = "docker CLI not found on PATH"
+        return _emit(args, report, 1)
+
+    running = runner.running_services()
+    if cfg.gitlab_service not in running:
+        report["detail"] = (
+            f"service {cfg.gitlab_service!r} is not running "
+            f"(running: {running or 'none'})"
+        )
+        return _emit(args, report, 1)
+
+    # Official Omnibus restore pattern (BACKUP= timestamp id without _gitlab_backup.tar).
+    shell_cmd = f"gitlab-backup restore BACKUP={backup_id} force=yes"
+    if cfg.dry_run:
+        report["ok"] = True
+        report["detail"] = (
+            f"dry-run: would exec in {cfg.gitlab_service}: {shell_cmd}"
+        )
+        return _emit(args, report, 0)
+
+    print_warning("Restore is destructive and will overwrite GitLab application data.")
+    print_info(f"Restoring backup id {backup_id!r} in {cfg.gitlab_service}…")
+    proc = runner.exec_service(
+        cfg.gitlab_service,
+        ["bash", "-lc", shell_cmd],
+        dry_run=False,
+    )
+    if proc is None:
+        report["detail"] = "exec did not run"
+        return _emit(args, report, 1)
+
+    report["returncode"] = proc.returncode
+    report["stdout_tail"] = (proc.stdout or "")[-2000:]
+    report["stderr_tail"] = (proc.stderr or "")[-2000:]
+    if proc.returncode == 0:
+        report["ok"] = True
+        report["detail"] = (
+            "restore completed; reconfigure/restart GitLab EE if your runbook requires it"
+        )
+        return _emit(args, report, 0)
+
+    report["detail"] = f"gitlab-backup restore failed (exit {proc.returncode})"
+    return _emit(args, report, proc.returncode or 1)
+
+
+def _emit(args: argparse.Namespace, report: dict[str, Any], exit_code: int) -> int:
+    if getattr(args, "json", False):
+        print(json.dumps(report, indent=2))
+        return exit_code
+
+    if report["ok"]:
+        print_success(report["detail"] or "Restore OK")
+    else:
+        print_error(report["detail"] or "Restore failed")
+
+    print_info(f"Backup id: {report.get('backup_id')}")
+    print_info(f"Service: {report['config']['gitlab_service']}")
+    if report.get("stderr_tail"):
+        print_warning(report["stderr_tail"][:500])
+    return exit_code

xgic/cli/gitlab/compose.py

@@ -0,0 +1,71 @@
+"""Thin Docker Compose runner for GitLab stack ops (stdlib only)."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from xgic.cli.gitlab.config import GitLabOpsConfig
+
+
+@dataclass
+class ComposeRunner:
+    """Run ``docker compose`` against the configured project."""
+
+    config: GitLabOpsConfig
+
+    def available(self) -> bool:
+        return shutil.which("docker") is not None
+
+    def base_cmd(self) -> list[str]:
+        return [
+            "docker",
+            "compose",
+            "-f",
+            self.config.compose_file,
+            "-p",
+            self.config.project_name,
+        ]
+
+    def run(
+        self,
+        *args: str,
+        check: bool = False,
+        capture: bool = True,
+    ) -> subprocess.CompletedProcess[str]:
+        cmd = [*self.base_cmd(), *args]
+        return subprocess.run(
+            cmd,
+            check=check,
+            capture_output=capture,
+            text=True,
+        )
+
+    def running_services(self) -> list[str]:
+        try:
+            result = self.run(
+                "ps",
+                "--services",
+                "--filter",
+                "status=running",
+                check=False,
+            )
+        except FileNotFoundError:
+            return []
+        if result.returncode != 0:
+            return []
+        return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+    def exec_service(
+        self,
+        service: str,
+        command: Sequence[str],
+        *,
+        dry_run: bool = False,
+    ) -> subprocess.CompletedProcess[str] | None:
+        """``docker compose exec -T <service> <command…>``."""
+        if dry_run:
+            return None
+        return self.run("exec", "-T", service, *command, check=False)

xgic/cli/gitlab/config.py

@@ -0,0 +1,152 @@
+"""Public-safe GitLab ops configuration (env + flags; no private defaults)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from dataclasses import dataclass
+
+# Environment keys (operators set these; package never ships private hosts/tokens).
+ENV_GITLAB_URL = "GITLAB_URL"
+ENV_GITLAB_TOKEN = "GITLAB_TOKEN"
+ENV_COMPOSE_FILE = "XGIC_GITLAB_COMPOSE_FILE"
+ENV_COMPOSE_PROJECT = "XGIC_GITLAB_COMPOSE_PROJECT"
+ENV_GITLAB_SERVICE = "XGIC_GITLAB_EE_SERVICE"
+ENV_XGIC_SERVICE = "XGIC_GITLAB_ORCH_SERVICE"
+ENV_BACKUP_DIR = "XGIC_GITLAB_BACKUP_DIR"
+
+DEFAULT_COMPOSE_FILE = "docker-compose.yml"
+DEFAULT_PROJECT_NAME = "xgic-gitlab"
+DEFAULT_GITLAB_SERVICE = "gitlab-ee"
+DEFAULT_XGIC_SERVICE = "xgic-gitlab"
+DEFAULT_BACKUP_DIR = "./gitlab-backups"
+
+
+@dataclass(frozen=True)
+class GitLabOpsConfig:
+    """Resolved ops settings for Compose-based GitLab stacks."""
+
+    compose_file: str
+    project_name: str
+    gitlab_service: str
+    xgic_service: str
+    backup_dir: str
+    gitlab_url: str | None
+    token: str | None
+    dry_run: bool
+
+    def public_dict(self) -> dict[str, object]:
+        """Serializable view safe for logs/JSON (token redacted)."""
+        return {
+            "compose_file": self.compose_file,
+            "project_name": self.project_name,
+            "gitlab_service": self.gitlab_service,
+            "xgic_service": self.xgic_service,
+            "backup_dir": self.backup_dir,
+            "gitlab_url": self.gitlab_url,
+            "token_set": bool(self.token),
+            "dry_run": self.dry_run,
+        }
+
+
+def _first(*values: str | None) -> str | None:
+    for v in values:
+        if v is not None and str(v).strip() != "":
+            return str(v).strip()
+    return None
+
+
+def resolve_config(args: argparse.Namespace) -> GitLabOpsConfig:
+    """Build config from argparse namespace and process environment."""
+    return GitLabOpsConfig(
+        compose_file=_first(
+            getattr(args, "compose_file", None),
+            os.environ.get(ENV_COMPOSE_FILE),
+        )
+        or DEFAULT_COMPOSE_FILE,
+        project_name=_first(
+            getattr(args, "project", None),
+            os.environ.get(ENV_COMPOSE_PROJECT),
+        )
+        or DEFAULT_PROJECT_NAME,
+        gitlab_service=_first(
+            getattr(args, "gitlab_service", None),
+            os.environ.get(ENV_GITLAB_SERVICE),
+        )
+        or DEFAULT_GITLAB_SERVICE,
+        xgic_service=_first(
+            getattr(args, "xgic_service", None),
+            os.environ.get(ENV_XGIC_SERVICE),
+        )
+        or DEFAULT_XGIC_SERVICE,
+        backup_dir=_first(
+            getattr(args, "backup_dir", None),
+            os.environ.get(ENV_BACKUP_DIR),
+        )
+        or DEFAULT_BACKUP_DIR,
+        gitlab_url=_first(
+            getattr(args, "url", None),
+            os.environ.get(ENV_GITLAB_URL),
+        ),
+        token=_first(
+            getattr(args, "token", None),
+            os.environ.get(ENV_GITLAB_TOKEN),
+        ),
+        dry_run=bool(getattr(args, "dry_run", False)),
+    )
+
+
+def add_common_ops_args(parser: argparse.ArgumentParser) -> None:
+    """Shared flags for health / backup / restore."""
+    parser.add_argument(
+        "--compose-file",
+        dest="compose_file",
+        default=None,
+        help=f"Compose file path (env {ENV_COMPOSE_FILE}; default {DEFAULT_COMPOSE_FILE})",
+    )
+    parser.add_argument(
+        "--project",
+        dest="project",
+        default=None,
+        help=f"Compose project name (env {ENV_COMPOSE_PROJECT}; default {DEFAULT_PROJECT_NAME})",
+    )
+    parser.add_argument(
+        "--gitlab-service",
+        dest="gitlab_service",
+        default=None,
+        help=f"GitLab EE service name (env {ENV_GITLAB_SERVICE}; default {DEFAULT_GITLAB_SERVICE})",
+    )
+    parser.add_argument(
+        "--xgic-service",
+        dest="xgic_service",
+        default=None,
+        help=f"Orchestration service name (env {ENV_XGIC_SERVICE}; default {DEFAULT_XGIC_SERVICE})",
+    )
+    parser.add_argument(
+        "--backup-dir",
+        dest="backup_dir",
+        default=None,
+        help=f"Host backup directory hint (env {ENV_BACKUP_DIR}; default {DEFAULT_BACKUP_DIR})",
+    )
+    parser.add_argument(
+        "--url",
+        dest="url",
+        default=None,
+        help=f"GitLab base URL for HTTP checks (env {ENV_GITLAB_URL}; no default host)",
+    )
+    parser.add_argument(
+        "--token",
+        dest="token",
+        default=None,
+        help=f"API token when needed (env {ENV_GITLAB_TOKEN}; never logged)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print planned actions without executing destructive or mutating steps",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit machine-readable JSON",
+    )

xgic/cli/gitlab/plugin.py

@@ -0,0 +1,77 @@
+"""Register ``xgic.cli.gitlab`` subcommands on the core ``xgic`` CLI.
+
+All product commands live under the ``gitlab`` group for domain ownership::
+
+    xgic gitlab info
+    xgic gitlab health
+    xgic gitlab backup
+    xgic gitlab restore
+    xgic gitlab --help
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from xgic.cli.gitlab.commands.backup import run_backup
+from xgic.cli.gitlab.commands.health import run_health
+from xgic.cli.gitlab.commands.info import run_info
+from xgic.cli.gitlab.commands.restore import run_restore
+from xgic.cli.gitlab.config import add_common_ops_args
+
+
+def register(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Entry point: ``xgic.cli.commands`` → GitLab product commands."""
+    gitlab = subparsers.add_parser(
+        "gitlab",
+        help="GitLab product commands",
+    )
+    gitlab_sub = gitlab.add_subparsers(
+        dest="gitlab_command",
+        help="GitLab action",
+        metavar="ACTION",
+        required=True,
+    )
+
+    info = gitlab_sub.add_parser(
+        "info",
+        help="Show GitLab CLI module version and status",
+    )
+    info.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON",
+    )
+    info.set_defaults(func=run_info)
+
+    health = gitlab_sub.add_parser(
+        "health",
+        help="Check Compose services and optional GitLab HTTP health",
+    )
+    add_common_ops_args(health)
+    health.set_defaults(func=run_health)
+
+    backup = gitlab_sub.add_parser(
+        "backup",
+        help="Create a GitLab EE backup (docker compose exec gitlab-backup create)",
+    )
+    add_common_ops_args(backup)
+    backup.set_defaults(func=run_backup)
+
+    restore = gitlab_sub.add_parser(
+        "restore",
+        help="Restore a GitLab EE backup (destructive; requires --yes)",
+    )
+    restore.add_argument(
+        "backup_id",
+        help="Backup id (timestamp prefix; not the full tar filename)",
+    )
+    restore.add_argument(
+        "--yes",
+        action="store_true",
+        help="Confirm destructive restore",
+    )
+    add_common_ops_args(restore)
+    restore.set_defaults(func=run_restore)

xgic_gitlab_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: xgic-gitlab-cli
+Version: 0.1.1
+Summary: XGIC CLI GitLab module - GitLab ops commands and helpers (xgic.cli.gitlab).
+Project-URL: Homepage, https://github.com/xgic/gitlab-cli
+Project-URL: Repository, https://github.com/xgic/gitlab-cli
+Project-URL: Issues, https://github.com/xgic/gitlab-cli/issues
+Project-URL: Documentation, https://github.com/xgic/gitlab-cli#readme
+Project-URL: Changelog, https://github.com/xgic/gitlab-cli/releases
+Author: XGIC
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: cli,gitlab,orchestration,xgic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: rich>=13.7
+Requires-Dist: xgic-cli>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: graphql
+Requires-Dist: xgic-gitlab-graphql>=0.1.0; extra == 'graphql'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# XGIC GitLab CLI
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![CI](https://github.com/xgic/gitlab-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/xgic/gitlab-cli/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.14+-blue?logo=python&logoColor=white)](https://www.python.org/)
+
+**GitLab product commands for the modular [XGIC CLI](https://github.com/xgic/cli)—ops under
+`xgic gitlab …`.**
+
+Namespace: **`xgic.cli.gitlab`** · Console group: **`xgic gitlab …`** · Brand: **XGIC CLI only**
+([ADR-0005](https://github.com/xgic/ai/blob/main/docs/adr/0005-modular-xgic-cli-and-retirement-of-xde.md))
+
+Standards hub: [xgic/ai](https://github.com/xgic/ai) ·
+[README standards](https://github.com/xgic/ai/blob/main/docs/readme-standards.md)
+
+---
+
+## Vision
+
+Self-managed GitLab operators need a **stable, public-safe command surface** for versioned ops—
+not a grab bag of one-off scripts. This module owns the **GitLab product** namespace under `xgic`.
+The GraphQL client library lives in [gitlab-graphql](https://github.com/xgic/gitlab-graphql);
+the Compose **template** and orchestration **image producer** live in
+[gitlab](https://github.com/xgic/gitlab) and [gitlab-dev](https://github.com/xgic/gitlab-dev).
+
+One brand (`xgic`), clear ownership, and no private hosts or tracker IDs in the package.
+
+---
+
+## Why this module exists
+
+| Benefit | Detail |
+|---------|--------|
+| **Domain clarity** | Nested under `xgic gitlab`—no clash with core or Payload commands |
+| **Composable stack** | Depends on `xgic-cli`; optional GraphQL extra when automation lands |
+| **Public-safe by design** | Endpoints via env/flags—never hard-coded private inventory |
+| **AI + human parity** | Same command map in README and [AGENTS.md](AGENTS.md) |
+| **Open-source rigor** | Apache-2.0, Python 3.14+, RC → TestPyPI → PyPI |
+
+---
+
+## Ecosystem
+
+| Package / repo | Role |
+|----------------|------|
+| [xgic/cli](https://github.com/xgic/cli) | Thin core framework (`xgic`) |
+| [xgic/gitlab-graphql](https://github.com/xgic/gitlab-graphql) | GraphQL client library |
+| **This repo** | GitLab product module (`xgic.cli.gitlab`) |
+| [xgic/gitlab-dev](https://github.com/xgic/gitlab-dev) | Orchestration image **producer** (`ghcr.io/xgic/xgic-gitlab`) |
+| [xgic/gitlab](https://github.com/xgic/gitlab) | End-user Docker Compose **template** |
+
+Architecture: [ADR-0001](https://github.com/xgic/ai/blob/main/docs/adr/0001-xgic-gitlab-architecture-and-repository-naming.md)
+· [ADR-0005](https://github.com/xgic/ai/blob/main/docs/adr/0005-modular-xgic-cli-and-retirement-of-xde.md).
+
+---
+
+## Quick start
+
+### Development (editable) — current primary path
+
+```bash
+uv pip install -e ../cli
+uv pip install -e ".[dev]"
+xgic gitlab --help
+xgic gitlab info
+```
+
+Optional GraphQL extra (when GraphQL-backed commands ship):
+
+```bash
+uv pip install -e ".[graphql]"
+```
+
+### Install (PyPI)
+
+PyPI publish follows the hub
+[python-package-release.md](https://github.com/xgic/ai/blob/main/docs/python-package-release.md)
+path (RC → TestPyPI → PyPI). Until the first release is published:
+
+```bash
+# After first PyPI release:
+uv pip install "xgic-cli>=0.2.0" "xgic-gitlab-cli"
+xgic gitlab --help
+```
+
+### Requirements
+
+- Python **3.14+**
+- `xgic-cli` ≥ 0.2.0
+- Docker / Docker Compose for stack ops (`health` / `backup` / `restore`)
+
+---
+
+## Console commands
+
+All product commands nest under **`xgic gitlab`**:
+
+| Command | Purpose |
+|---------|---------|
+| `xgic gitlab info` | Module version and status (`--json` supported) |
+| `xgic gitlab health` | Compose service checks + optional HTTP `/-/health` |
+| `xgic gitlab backup` | `gitlab-backup create` via `docker compose exec` |
+| `xgic gitlab restore <id>` | Destructive restore (`--yes` required; prefer `--dry-run` first) |
+
+### Configuration (no private host defaults)
+
+| Setting | Flag | Environment |
+|---------|------|-------------|
+| Compose file | `--compose-file` | `XGIC_GITLAB_COMPOSE_FILE` (default `docker-compose.yml`) |
+| Project name | `--project` | `XGIC_GITLAB_COMPOSE_PROJECT` (default `xgic-gitlab`) |
+| GitLab EE service | `--gitlab-service` | `XGIC_GITLAB_EE_SERVICE` (default `gitlab-ee`) |
+| Orchestration service | `--xgic-service` | `XGIC_GITLAB_ORCH_SERVICE` (default `xgic-gitlab`) |
+| Backup dir hint | `--backup-dir` | `XGIC_GITLAB_BACKUP_DIR` |
+| GitLab URL | `--url` | `GITLAB_URL` (**no default**) |
+| Token | `--token` | `GITLAB_TOKEN` (never logged) |
+
+Shared: `--dry-run`, `--json`.
+
+### Examples
+
+```bash
+# From a checked-out xgic/gitlab template directory
+export GITLAB_URL=http://localhost:8929
+xgic gitlab health --json
+xgic gitlab backup --dry-run
+xgic gitlab restore 20240101_1200 --dry-run
+# after confirmation:
+xgic gitlab restore 20240101_1200 --yes
+```
+
+---
+
+## Status
+
+**0.1.1 — experimental.** Nested `xgic gitlab` commands: `info`, `health`, `backup`, `restore` against
+Docker Compose stacks (typically [xgic/gitlab](https://github.com/xgic/gitlab)).
+
+---
+
+## AI agent guidance
+
+- Use **`xgic gitlab …`** for product ops; do not hardcode private GitLab hostnames in public
+  artifacts or committed examples.
+- Prefer **fictional placeholders** (`https://gitlab.example.com`) in docs and tests.
+- Destructive restore always needs **`--yes`**; start with **`--dry-run`**.
+- Follow hub
+  [public-safe](https://github.com/xgic/ai/blob/main/docs/BASE-STANDARDS-FOR-ORCHESTRATED-REPOS.md)
+  rules before any public GitHub write.
+
+---
+
+## Public safety
+
+This package is **public-safe only**. Do not hardcode private GitLab hosts, internal inventory, or
+private tracker IDs. Operators configure endpoints via environment / flags.
+
+---
+
+## Publishing
+
+Follow
+[python-package-release.md](https://github.com/xgic/ai/blob/main/docs/python-package-release.md)
+(publish **after** `xgic-cli` for stack releases). Tags: `vX.Y.ZrcN` → TestPyPI; `vX.Y.Z` → PyPI.
+
+---
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).  
+Copyright form: `Copyright 2026 XGIC`.

xgic_gitlab_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+xgic/cli/gitlab/__init__.py,sha256=u_Vi3HUKvlPXr5z_OEN96NWBdizeCptNGz2Dgd29KxY,102
+xgic/cli/gitlab/compose.py,sha256=bb-ZFjrEO9y_Hrzbt2LZuqXMCBV4iNk1emWAtzROhOo,1834
+xgic/cli/gitlab/config.py,sha256=4yzCKhWnSpVkyavQXjZ9HUPIgyUhBc8y8UOL-VBqJG0,4803
+xgic/cli/gitlab/plugin.py,sha256=HFi8KUSook9UnYjiGLXgg7t1iOEtzzKsENazIiEclvU,2161
+xgic/cli/gitlab/commands/__init__.py,sha256=OpMcBC9eWBwov9CMkhsxNVDwblOvM4eX0c01pJGcvNw,35
+xgic/cli/gitlab/commands/backup.py,sha256=QDmzFpgnq935i_OO6EopoatxFaeBS-n88eK1TyZNvHc,2941
+xgic/cli/gitlab/commands/health.py,sha256=HAuLQrrjI49V0m3GR5ml0olRUbbJRgphtOn25uw4Q0A,5232
+xgic/cli/gitlab/commands/info.py,sha256=tKyP-MlvlhppYARknMDKtRwjGL-kSYncinOwg9EqpsM,1402
+xgic/cli/gitlab/commands/restore.py,sha256=K6y6s_IViFgr6imzdedbSKkJF907kxbMs6ThEO7B8pI,3683
+xgic_gitlab_cli-0.1.1.dist-info/METADATA,sha256=gVcgXIWMg2h-5L30foWlliaH3kl9cs2z_PWRCPHREws,7479
+xgic_gitlab_cli-0.1.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+xgic_gitlab_cli-0.1.1.dist-info/entry_points.txt,sha256=PpbKNTue84VAwrvDrkjfXaccDjBRpT19SQb2YCIjNTk,61
+xgic_gitlab_cli-0.1.1.dist-info/licenses/LICENSE,sha256=zR7vJ5cGf_9LgWHYDAugptsXPsV0_78I9kvVnf7VRk0,11335
+xgic_gitlab_cli-0.1.1.dist-info/licenses/NOTICE,sha256=u_0eKm5vtkPsSwUiJWQMqew39u_CfG7VEa8nobed68Y,207
+xgic_gitlab_cli-0.1.1.dist-info/RECORD,,

xgic_gitlab_cli-0.1.1.dist-info/WHEEL

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

xgic_gitlab_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xgic.cli.commands]
+gitlab = xgic.cli.gitlab.plugin:register

xgic_gitlab_cli-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 XGIC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

xgic_gitlab_cli-0.1.1.dist-info/licenses/NOTICE

@@ -0,0 +1,8 @@
+XGIC GitLab CLI
+Copyright 2026 XGIC
+
+This product includes software and documentation developed at XGIC
+(https://xgic.net).
+
+Licensed under the Apache License, Version 2.0.
+See the LICENSE file for details.