qodev-gitlab-cli 0.1.0__py3-none-any.whl

qodev_gitlab_cli/context.py

@@ -0,0 +1,62 @@
+"""Global context shared across all commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from qodev_gitlab_api import GitLabClient
+
+
+@dataclass
+class Context:
+    """Shared state passed from the meta launcher to every command."""
+
+    json_mode: bool = False
+    token: str | None = None
+    base_url: str | None = None
+    project: str | None = None
+    limit: int = 25
+    page: int = 1
+
+    def client(self) -> GitLabClient:
+        kwargs: dict = {}
+        if self.token:
+            kwargs["token"] = self.token
+        if self.base_url:
+            kwargs["base_url"] = self.base_url
+        return GitLabClient(**kwargs)
+
+    def resolve_project(self) -> str:
+        if self.project:
+            return self.project
+        from qodev_gitlab_cli.project import detect_project_from_git
+
+        path = detect_project_from_git(self.base_url)
+        if not path:
+            from qodev_gitlab_api.exceptions import ConfigurationError
+
+            raise ConfigurationError(
+                "Could not detect project. Use --project/-p or run from a git repo with a GitLab remote."
+            )
+        return path
+
+    def configure(
+        self,
+        *,
+        json_mode: bool,
+        token: str | None,
+        base_url: str | None,
+        project: str | None,
+        limit: int,
+        page: int,
+    ) -> None:
+        self.json_mode = json_mode
+        self.token = token
+        self.base_url = base_url
+        self.project = project
+        self.limit = limit
+        self.page = page
+
+
+# Module-level singleton
+ctx = Context()

qodev_gitlab_cli/formatters/__init__.py

@@ -0,0 +1 @@
+"""Formatters for CLI output."""

qodev_gitlab_cli/formatters/generic.py

@@ -0,0 +1,94 @@
+"""Generic formatters for dicts and lists."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from qodev_gitlab_cli.output import md_table
+
+
+def detail_table(data: Any, fields: list[tuple[str, str]], *, title: str | None = None) -> str:
+    """Render a single record as a Field/Value markdown table.
+
+    Args:
+        data: dict
+        fields: List of (label, key) — key supports dot notation.
+        title: Optional heading.
+    """
+    d = data
+
+    lines: list[str] = []
+    if title:
+        lines.append(f"# {title}")
+        lines.append("")
+
+    lines.append("| Field | Value |")
+    lines.append("|-------|-------|")
+    for label, key in fields:
+        value = _get(d, key)
+        if value is None or value == "" or value == []:
+            continue
+        lines.append(f"| {label} | {_fmt(value)} |")
+    return "\n".join(lines)
+
+
+def list_table(
+    items: list[Any],
+    columns: list[tuple[str, str]],
+    *,
+    title: str = "Results",
+    total: int = 0,
+    page: int = 1,
+) -> str:
+    """Render a list of records as a markdown table."""
+    if not items:
+        return f"# {title}\n\n_No results found._"
+
+    header = f"# {title}"
+    if total:
+        header += f" (page {page}, {total} total)"
+
+    rows: list[dict[str, str]] = []
+    for item in items:
+        d = item
+        row = {}
+        for _, key in columns:
+            row[key] = _fmt(_get(d, key))
+        rows.append(row)
+
+    return f"{header}\n\n{md_table(rows, columns)}"
+
+
+def _get(d: dict, key: str) -> Any:
+    """Get a value from a dict, supporting dot notation."""
+    parts = key.split(".")
+    current: Any = d
+    for part in parts:
+        if isinstance(current, dict):
+            current = current.get(part)
+        else:
+            return None
+        if current is None:
+            return None
+    return current
+
+
+def _fmt(value: Any) -> str:
+    """Format a value for display in a markdown table cell."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "Yes" if value else "No"
+    if isinstance(value, list):
+        if not value:
+            return ""
+        # Extract names from list of user dicts (common GitLab pattern)
+        if value and isinstance(value[0], dict) and "name" in value[0]:
+            return ", ".join(v.get("name", "?") for v in value)
+        return ", ".join(str(v) for v in value)
+    if isinstance(value, dict):
+        # Extract name from user dict
+        if "name" in value:
+            return str(value["name"])
+        return str(value)
+    return str(value)

qodev_gitlab_cli/formatters/issues.py

@@ -0,0 +1,60 @@
+"""Issue formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from qodev_gitlab_cli.formatters.generic import detail_table, list_table
+
+ISSUE_DETAIL_FIELDS = [
+    ("IID", "iid"),
+    ("Title", "title"),
+    ("State", "state"),
+    ("Author", "author.name"),
+    ("Assignees", "assignees"),
+    ("Labels", "labels"),
+    ("Milestone", "milestone.title"),
+    ("URL", "web_url"),
+    ("Created", "created_at"),
+    ("Updated", "updated_at"),
+    ("Closed", "closed_at"),
+    ("Description", "description"),
+]
+
+ISSUE_LIST_COLUMNS = [
+    ("IID", "iid"),
+    ("Title", "title"),
+    ("Author", "author.name"),
+    ("Labels", "labels"),
+    ("State", "state"),
+    ("Updated", "updated_at"),
+]
+
+NOTE_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Author", "author.name"),
+    ("Body", "_body"),
+    ("Created", "created_at"),
+]
+
+
+def format_issue_detail(data: Any) -> str:
+    iid = data.get("iid", "?") if isinstance(data, dict) else "?"
+    return detail_table(data, ISSUE_DETAIL_FIELDS, title=f"Issue #{iid}")
+
+
+def format_issue_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    return list_table(items, ISSUE_LIST_COLUMNS, title="Issues", total=total, page=page)
+
+
+def format_note_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    rows = []
+    for n in items:
+        body = n.get("body", "")
+        rows.append(
+            {
+                **n,
+                "_body": (body[:80] + "...") if len(body) > 80 else body,
+            }
+        )
+    return list_table(rows, NOTE_LIST_COLUMNS, title="Notes", total=total, page=page)

qodev_gitlab_cli/formatters/jobs.py

@@ -0,0 +1,39 @@
+"""Job formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from qodev_gitlab_cli.formatters.generic import detail_table, list_table
+
+JOB_DETAIL_FIELDS = [
+    ("ID", "id"),
+    ("Name", "name"),
+    ("Status", "status"),
+    ("Stage", "stage"),
+    ("Ref", "ref"),
+    ("Pipeline", "pipeline.id"),
+    ("URL", "web_url"),
+    ("Duration", "duration"),
+    ("Created", "created_at"),
+    ("Started", "started_at"),
+    ("Finished", "finished_at"),
+    ("Runner", "runner.description"),
+]
+
+JOB_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Name", "name"),
+    ("Stage", "stage"),
+    ("Status", "status"),
+    ("Duration", "duration"),
+]
+
+
+def format_job_detail(data: Any) -> str:
+    name = data.get("name", "?") if isinstance(data, dict) else "?"
+    return detail_table(data, JOB_DETAIL_FIELDS, title=f"Job: {name}")
+
+
+def format_job_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    return list_table(items, JOB_LIST_COLUMNS, title="Jobs", total=total, page=page)

qodev_gitlab_cli/formatters/mrs.py

@@ -0,0 +1,101 @@
+"""Merge request formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from qodev_gitlab_cli.formatters.generic import detail_table, list_table
+
+MR_DETAIL_FIELDS = [
+    ("IID", "iid"),
+    ("Title", "title"),
+    ("State", "state"),
+    ("Author", "author.name"),
+    ("Source", "source_branch"),
+    ("Target", "target_branch"),
+    ("URL", "web_url"),
+    ("Labels", "labels"),
+    ("Assignees", "assignees"),
+    ("Reviewers", "reviewers"),
+    ("Created", "created_at"),
+    ("Updated", "updated_at"),
+    ("Merged By", "merged_by.name"),
+    ("Merge Status", "merge_status"),
+]
+
+MR_LIST_COLUMNS = [
+    ("IID", "iid"),
+    ("Title", "title"),
+    ("Author", "author.name"),
+    ("Source", "source_branch"),
+    ("Target", "target_branch"),
+    ("State", "state"),
+]
+
+DISCUSSION_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Author", "_author"),
+    ("Resolved", "_resolved"),
+    ("Body", "_body"),
+]
+
+COMMIT_LIST_COLUMNS = [
+    ("Short ID", "short_id"),
+    ("Title", "title"),
+    ("Author", "author_name"),
+    ("Date", "created_at"),
+]
+
+
+def format_mr_detail(data: Any) -> str:
+    iid = data.get("iid", "?") if isinstance(data, dict) else "?"
+    return detail_table(data, MR_DETAIL_FIELDS, title=f"Merge Request !{iid}")
+
+
+def format_mr_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    return list_table(items, MR_LIST_COLUMNS, title="Merge Requests", total=total, page=page)
+
+
+def format_discussion_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    """Format discussions with first note content."""
+    rows = []
+    for d in items:
+        notes = d.get("notes", [])
+        first_note = notes[0] if notes else {}
+        rows.append(
+            {
+                "id": d.get("id", ""),
+                "_author": first_note.get("author", {}).get("name", ""),
+                "_resolved": "Yes"
+                if d.get("individual_note") is False
+                and all(n.get("resolved", False) for n in notes if n.get("resolvable"))
+                else "No"
+                if any(n.get("resolvable") for n in notes)
+                else "-",
+                "_body": (first_note.get("body", "")[:80] + "...")
+                if len(first_note.get("body", "")) > 80
+                else first_note.get("body", ""),
+            }
+        )
+    return list_table(rows, DISCUSSION_LIST_COLUMNS, title="Discussions", total=total, page=page)
+
+
+def format_commit_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    return list_table(items, COMMIT_LIST_COLUMNS, title="Commits", total=total, page=page)
+
+
+def format_approval_detail(data: Any) -> str:
+    lines = ["# Approval Status"]
+    approved_by = data.get("approved_by", [])
+    if approved_by:
+        lines.append(f"\nApproved by: {', '.join(a.get('user', {}).get('name', '?') for a in approved_by)}")
+    else:
+        lines.append("\n_Not yet approved._")
+
+    rules = data.get("approval_rules_left", [])
+    if rules:
+        lines.append("\n## Remaining Rules")
+        for rule in rules:
+            lines.append(f"- {rule.get('name', '?')} (needs {rule.get('approvals_required', '?')} approvals)")
+
+    return "\n".join(lines)

qodev_gitlab_cli/formatters/pipelines.py

@@ -0,0 +1,67 @@
+"""Pipeline formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from qodev_gitlab_cli.formatters.generic import detail_table, list_table
+
+PIPELINE_DETAIL_FIELDS = [
+    ("ID", "id"),
+    ("Status", "status"),
+    ("Ref", "ref"),
+    ("SHA", "sha"),
+    ("Source", "source"),
+    ("URL", "web_url"),
+    ("Created", "created_at"),
+    ("Updated", "updated_at"),
+    ("Duration", "duration"),
+]
+
+PIPELINE_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Status", "status"),
+    ("Ref", "ref"),
+    ("Source", "source"),
+    ("Created", "created_at"),
+]
+
+
+def format_pipeline_detail(data: Any) -> str:
+    pid = data.get("id", "?") if isinstance(data, dict) else "?"
+    return detail_table(data, PIPELINE_DETAIL_FIELDS, title=f"Pipeline #{pid}")
+
+
+def format_pipeline_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    return list_table(items, PIPELINE_LIST_COLUMNS, title="Pipelines", total=total, page=page)
+
+
+def format_wait_result(data: Any) -> str:
+    lines = [f"# Pipeline #{data.get('pipeline_id', '?')}"]
+    lines.append("")
+    lines.append(f"**Status:** {data.get('final_status', '?')}")
+    lines.append(f"**Duration:** {data.get('total_duration', '?')}s")
+    lines.append(f"**Checks:** {data.get('checks_performed', '?')}")
+
+    if data.get("pipeline_url"):
+        lines.append(f"**URL:** {data['pipeline_url']}")
+
+    summary = data.get("job_summary")
+    if summary:
+        lines.append("")
+        lines.append(
+            f"**Jobs:** {summary.get('total', 0)} total, {summary.get('success', 0)} success, {summary.get('failed', 0)} failed"
+        )
+
+    failed_jobs = data.get("failed_jobs", [])
+    if failed_jobs:
+        lines.append("")
+        lines.append("## Failed Jobs")
+        for job in failed_jobs:
+            lines.append(f"\n### {job.get('name', '?')} (#{job.get('id', '?')})")
+            if job.get("web_url"):
+                lines.append(f"URL: {job['web_url']}")
+            if job.get("last_log_lines"):
+                lines.append(f"\n```\n{job['last_log_lines']}\n```")
+
+    return "\n".join(lines)

qodev_gitlab_cli/formatters/projects.py

@@ -0,0 +1,39 @@
+"""Project formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from qodev_gitlab_cli.formatters.generic import detail_table, list_table
+
+PROJECT_DETAIL_FIELDS = [
+    ("ID", "id"),
+    ("Name", "name"),
+    ("Path", "path_with_namespace"),
+    ("Description", "description"),
+    ("URL", "web_url"),
+    ("Default Branch", "default_branch"),
+    ("Visibility", "visibility"),
+    ("Stars", "star_count"),
+    ("Forks", "forks_count"),
+    ("Open Issues", "open_issues_count"),
+    ("Created", "created_at"),
+    ("Updated", "last_activity_at"),
+]
+
+PROJECT_LIST_COLUMNS = [
+    ("ID", "id"),
+    ("Name", "name"),
+    ("Path", "path_with_namespace"),
+    ("Stars", "star_count"),
+    ("Updated", "last_activity_at"),
+]
+
+
+def format_project_detail(data: Any) -> str:
+    name = data.get("name", "Unknown") if isinstance(data, dict) else "Unknown"
+    return detail_table(data, PROJECT_DETAIL_FIELDS, title=f"Project: {name}")
+
+
+def format_project_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    return list_table(items, PROJECT_LIST_COLUMNS, title="Projects", total=total, page=page)

qodev_gitlab_cli/formatters/releases.py

@@ -0,0 +1,33 @@
+"""Release formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from qodev_gitlab_cli.formatters.generic import detail_table, list_table
+
+RELEASE_DETAIL_FIELDS = [
+    ("Tag", "tag_name"),
+    ("Name", "name"),
+    ("Description", "description"),
+    ("Author", "author.name"),
+    ("Created", "created_at"),
+    ("Released", "released_at"),
+    ("Commit", "commit.short_id"),
+]
+
+RELEASE_LIST_COLUMNS = [
+    ("Tag", "tag_name"),
+    ("Name", "name"),
+    ("Author", "author.name"),
+    ("Released", "released_at"),
+]
+
+
+def format_release_detail(data: Any) -> str:
+    tag = data.get("tag_name", "?") if isinstance(data, dict) else "?"
+    return detail_table(data, RELEASE_DETAIL_FIELDS, title=f"Release: {tag}")
+
+
+def format_release_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    return list_table(items, RELEASE_LIST_COLUMNS, title="Releases", total=total, page=page)

qodev_gitlab_cli/formatters/variables.py

@@ -0,0 +1,34 @@
+"""CI/CD variable formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from qodev_gitlab_cli.formatters.generic import detail_table, list_table
+
+VARIABLE_DETAIL_FIELDS = [
+    ("Key", "key"),
+    ("Type", "variable_type"),
+    ("Protected", "protected"),
+    ("Masked", "masked"),
+    ("Raw", "raw"),
+    ("Environment", "environment_scope"),
+    ("Description", "description"),
+]
+
+VARIABLE_LIST_COLUMNS = [
+    ("Key", "key"),
+    ("Type", "variable_type"),
+    ("Protected", "protected"),
+    ("Masked", "masked"),
+    ("Environment", "environment_scope"),
+]
+
+
+def format_variable_detail(data: Any) -> str:
+    key = data.get("key", "?") if isinstance(data, dict) else "?"
+    return detail_table(data, VARIABLE_DETAIL_FIELDS, title=f"Variable: {key}")
+
+
+def format_variable_list(items: list[Any], *, total: int = 0, page: int = 1) -> str:
+    return list_table(items, VARIABLE_LIST_COLUMNS, title="CI/CD Variables", total=total, page=page)

qodev_gitlab_cli/output.py

@@ -0,0 +1,116 @@
+"""Output formatting — JSON and Markdown modes."""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime
+from typing import Any
+
+from rich.console import Console
+from rich.markdown import Markdown
+
+from qodev_gitlab_cli.context import Context
+
+console = Console(stderr=True)
+stdout_console = Console()
+
+
+def serialize(obj: Any) -> Any:
+    """Convert an object to a JSON-serializable structure."""
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, list):
+        return [serialize(item) for item in obj]
+    if isinstance(obj, dict):
+        return {k: serialize(v) for k, v in obj.items()}
+    return obj
+
+
+def output_json(data: Any) -> None:
+    print(json.dumps(serialize(data), indent=2, default=str))
+
+
+def output_markdown(text: str) -> None:
+    stdout_console.print(Markdown(text))
+
+
+def output(data: Any, *, ctx: Context, format_fn: Any = None) -> None:
+    """Route output through the correct formatter."""
+    if ctx.json_mode:
+        output_json(data)
+    else:
+        md = format_fn(data) if format_fn else generic_markdown(data)
+        output_markdown(md)
+
+
+def output_list(
+    *,
+    items: list[Any],
+    total: int | None = None,
+    page: int = 1,
+    limit: int = 25,
+    ctx: Context,
+    format_fn: Any,
+) -> None:
+    """Output a paginated list."""
+    if total is None:
+        total = len(items)
+
+    if ctx.json_mode:
+        output_json({"items": serialize(items), "total": total, "page": page, "limit": limit})
+    else:
+        md = format_fn(items, total=total, page=page)
+        if total > page * limit:
+            md += f"\n\n*Showing {len(items)} of {total} results. Use `--page {page + 1}` for next page.*"
+        elif total > 0:
+            md += f"\n\n*Showing {len(items)} of {total} results.*"
+        output_markdown(md)
+
+
+def error(message: str, *, ctx: Context | None = None, code: str = "error", exit_code: int = 1) -> None:
+    """Output an error and exit."""
+    if ctx and ctx.json_mode:
+        print(json.dumps({"error": message, "code": code}))
+    else:
+        console.print(f"[red]Error:[/red] {message}")
+    sys.exit(exit_code)
+
+
+# ---------------------------------------------------------------------------
+# Generic markdown helpers
+# ---------------------------------------------------------------------------
+
+
+def generic_markdown(data: Any) -> str:
+    if isinstance(data, dict):
+        return _dict_to_md(data)
+    if isinstance(data, list):
+        if not data:
+            return "_No results._"
+        return "\n\n".join(generic_markdown(item) for item in data)
+    return str(data)
+
+
+def _dict_to_md(d: dict) -> str:
+    lines = ["| Field | Value |", "|-------|-------|"]
+    for key, value in d.items():
+        if isinstance(value, (dict, list)):
+            continue
+        display_key = key.replace("_", " ").title()
+        lines.append(f"| {display_key} | {value} |")
+    return "\n".join(lines)
+
+
+def md_table(rows: list[dict[str, str]], headers: list[tuple[str, str]]) -> str:
+    """Build a markdown table from rows."""
+    if not rows:
+        return "_No results._"
+
+    header_line = "| " + " | ".join(h for h, _ in headers) + " |"
+    sep_line = "| " + " | ".join("---" for _ in headers) + " |"
+    lines = [header_line, sep_line]
+    for row in rows:
+        cells = [str(row.get(key, "")) for _, key in headers]
+        lines.append("| " + " | ".join(cells) + " |")
+    return "\n".join(lines)