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

qodev_gitlab_cli/__init__.py

@@ -0,0 +1 @@
+"""GitLab CLI — agent-friendly CLI for the GitLab API."""

qodev_gitlab_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m qodev_gitlab_cli`."""
+
+from qodev_gitlab_cli.app import main
+
+main()

qodev_gitlab_cli/app.py

@@ -0,0 +1,93 @@
+"""Root App definition, global options, and error handling."""
+
+from __future__ import annotations
+
+import sys
+from typing import Annotated
+
+from cyclopts import App, Group, Parameter
+from qodev_gitlab_api import APIError, AuthenticationError, ConfigurationError, NotFoundError
+
+import qodev_gitlab_cli.context as _ctx
+
+app = App(
+    name="qodev-gitlab",
+    help="Agent-friendly CLI for the GitLab API.",
+    version_flags=[],
+)
+
+app.meta.group_parameters = Group("Global Options", sort_key=0)
+
+# ---------------------------------------------------------------------------
+# Import and register command groups
+# ---------------------------------------------------------------------------
+from qodev_gitlab_cli.commands.issues import issues_app  # noqa: E402
+from qodev_gitlab_cli.commands.jobs import jobs_app  # noqa: E402
+from qodev_gitlab_cli.commands.mrs import mrs_app  # noqa: E402
+from qodev_gitlab_cli.commands.pipelines import pipelines_app  # noqa: E402
+from qodev_gitlab_cli.commands.projects import projects_app  # noqa: E402
+from qodev_gitlab_cli.commands.releases import releases_app  # noqa: E402
+from qodev_gitlab_cli.commands.variables import variables_app  # noqa: E402
+
+app.command(projects_app)
+app.command(mrs_app)
+app.command(pipelines_app)
+app.command(jobs_app)
+app.command(issues_app)
+app.command(releases_app)
+app.command(variables_app)
+
+# ---------------------------------------------------------------------------
+# Exit codes
+# ---------------------------------------------------------------------------
+EXIT_AUTH = 80
+EXIT_NOT_FOUND = 81
+EXIT_API = 82
+EXIT_VALIDATION = 83
+EXIT_CONFIG = 84
+
+
+# ---------------------------------------------------------------------------
+# Meta launcher — global options & error handling
+# ---------------------------------------------------------------------------
+@app.meta.default
+def launcher(
+    *tokens: Annotated[str, Parameter(show=False, allow_leading_hyphen=True)],
+    json: Annotated[bool, Parameter(name="--json", help="Output as JSON", negative="")] = False,
+    token: Annotated[
+        str | None, Parameter(name="--token", help="GitLab token (overrides GITLAB_TOKEN)", show=False)
+    ] = None,
+    url: Annotated[str | None, Parameter(name="--url", help="GitLab URL (overrides GITLAB_URL)", show=False)] = None,
+    project: Annotated[str | None, Parameter(name=["--project", "-p"], help="Project ID or path")] = None,
+    limit: Annotated[int, Parameter(name="--limit", help="Results per page")] = 25,
+    page: Annotated[int, Parameter(name="--page", help="Page number")] = 1,
+) -> None:
+    """GitLab CLI — manage projects, merge requests, pipelines, and more."""
+    _ctx.ctx.configure(json_mode=json, token=token, base_url=url, project=project, limit=limit, page=page)
+
+    try:
+        app(tokens)
+    except AuthenticationError as exc:
+        _handle_error(str(exc), code="authentication", exit_code=EXIT_AUTH)
+    except NotFoundError as exc:
+        _handle_error(str(exc), code="not_found", exit_code=EXIT_NOT_FOUND)
+    except APIError as exc:
+        _handle_error(str(exc), code="api_error", exit_code=EXIT_API)
+    except ConfigurationError as exc:
+        _handle_error(str(exc), code="configuration", exit_code=EXIT_CONFIG)
+    except SystemExit:
+        raise
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as exc:
+        _handle_error(f"Unexpected error: {exc}", code="unknown", exit_code=1)
+
+
+def _handle_error(message: str, *, code: str, exit_code: int) -> None:
+    from qodev_gitlab_cli.output import error
+
+    error(message, ctx=_ctx.ctx, code=code, exit_code=exit_code)
+
+
+def main() -> None:
+    app.meta()

qodev_gitlab_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command groups for the GitLab CLI."""

qodev_gitlab_cli/commands/issues.py

@@ -0,0 +1,102 @@
+"""Issue commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from qodev_gitlab_cli.context import ctx
+from qodev_gitlab_cli.formatters.issues import format_issue_detail, format_issue_list, format_note_list
+from qodev_gitlab_cli.output import output, output_list
+
+issues_app = App(name="issues", help="Manage issues.")
+
+
+@issues_app.command
+def list(
+    *,
+    state: Annotated[str, Parameter(name="--state", help="Filter: opened, closed, all")] = "opened",
+    labels: Annotated[str | None, Parameter(name="--labels", help="Filter by labels")] = None,
+    milestone: Annotated[str | None, Parameter(name="--milestone", help="Filter by milestone")] = None,
+) -> None:
+    """List issues."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.get_issues(project, state=state, labels=labels, milestone=milestone)
+    output_list(items=items, ctx=ctx, format_fn=format_issue_list)
+
+
+@issues_app.command
+def get(
+    iid: Annotated[int, Parameter(help="Issue IID")],
+) -> None:
+    """Get issue details."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.get_issue(project, iid)
+    output(result, ctx=ctx, format_fn=format_issue_detail)
+
+
+@issues_app.command
+def create(
+    *,
+    title: Annotated[str, Parameter(name="--title", help="Issue title")],
+    description: Annotated[str | None, Parameter(name="--description", help="Issue description")] = None,
+    labels: Annotated[str | None, Parameter(name="--labels", help="Comma-separated labels")] = None,
+) -> None:
+    """Create a new issue."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.create_issue(project, title=title, description=description, labels=labels)
+    output(result, ctx=ctx, format_fn=format_issue_detail)
+
+
+@issues_app.command
+def update(
+    iid: Annotated[int, Parameter(help="Issue IID")],
+    *,
+    title: Annotated[str | None, Parameter(name="--title", help="New title")] = None,
+    description: Annotated[str | None, Parameter(name="--description", help="New description")] = None,
+    labels: Annotated[str | None, Parameter(name="--labels", help="New labels")] = None,
+) -> None:
+    """Update an issue."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.update_issue(project, iid, title=title, description=description, labels=labels)
+    output(result, ctx=ctx, format_fn=format_issue_detail)
+
+
+@issues_app.command
+def close(
+    iid: Annotated[int, Parameter(help="Issue IID")],
+) -> None:
+    """Close an issue."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.close_issue(project, iid)
+    output(result, ctx=ctx, format_fn=format_issue_detail)
+
+
+@issues_app.command
+def comment(
+    iid: Annotated[int, Parameter(help="Issue IID")],
+    *,
+    body: Annotated[str, Parameter(name="--body", help="Comment text")],
+) -> None:
+    """Comment on an issue."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.create_issue_note(project, iid, body)
+    output(result, ctx=ctx)
+
+
+@issues_app.command
+def notes(
+    iid: Annotated[int, Parameter(help="Issue IID")],
+) -> None:
+    """List comments/notes on an issue."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.get_issue_notes(project, iid)
+    output_list(items=items, ctx=ctx, format_fn=format_note_list)

qodev_gitlab_cli/commands/jobs.py

@@ -0,0 +1,52 @@
+"""Job commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from qodev_gitlab_cli.context import ctx
+from qodev_gitlab_cli.formatters.jobs import format_job_detail
+from qodev_gitlab_cli.output import output, output_markdown
+
+jobs_app = App(name="jobs", help="Manage jobs.")
+
+
+@jobs_app.command
+def get(
+    id: Annotated[int, Parameter(help="Job ID")],
+) -> None:
+    """Get job details."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.get_job(project, id)
+    output(result, ctx=ctx, format_fn=format_job_detail)
+
+
+@jobs_app.command
+def log(
+    id: Annotated[int, Parameter(help="Job ID")],
+) -> None:
+    """Get job log output."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    log_text = client.get_job_log(project, id)
+
+    if ctx.json_mode:
+        from qodev_gitlab_cli.output import output_json
+
+        output_json({"job_id": id, "log": log_text})
+    else:
+        output_markdown(f"# Job #{id} Log\n\n```\n{log_text}\n```")
+
+
+@jobs_app.command
+def retry(
+    id: Annotated[int, Parameter(help="Job ID")],
+) -> None:
+    """Retry a failed job."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.retry_job(project, id)
+    output(result, ctx=ctx, format_fn=format_job_detail)

qodev_gitlab_cli/commands/mrs.py

@@ -0,0 +1,202 @@
+"""Merge request commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from qodev_gitlab_cli.context import ctx
+from qodev_gitlab_cli.formatters.mrs import (
+    format_approval_detail,
+    format_commit_list,
+    format_discussion_list,
+    format_mr_detail,
+    format_mr_list,
+)
+from qodev_gitlab_cli.output import output, output_list, output_markdown
+
+mrs_app = App(name="mrs", help="Manage merge requests.")
+
+
+@mrs_app.command
+def list(
+    *,
+    state: Annotated[str, Parameter(name="--state", help="Filter by state: opened, closed, merged, all")] = "opened",
+) -> None:
+    """List merge requests."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.get_merge_requests(project, state=state)
+    output_list(items=items, ctx=ctx, format_fn=format_mr_list)
+
+
+@mrs_app.command
+def get(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+) -> None:
+    """Get merge request details."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.get_merge_request(project, iid)
+    output(result, ctx=ctx, format_fn=format_mr_detail)
+
+
+@mrs_app.command
+def create(
+    *,
+    title: Annotated[str, Parameter(name="--title", help="MR title")],
+    source: Annotated[str | None, Parameter(name="--source", help="Source branch (default: current)")] = None,
+    target: Annotated[str, Parameter(name="--target", help="Target branch")] = "main",
+    description: Annotated[str | None, Parameter(name="--description", help="MR description")] = None,
+    labels: Annotated[str | None, Parameter(name="--labels", help="Comma-separated labels")] = None,
+    squash: Annotated[bool | None, Parameter(name="--squash", help="Squash commits on merge")] = None,
+) -> None:
+    """Create a new merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+
+    if source is None:
+        from qodev_gitlab_cli.project import get_current_branch
+
+        source = get_current_branch()
+        if not source:
+            from qodev_gitlab_cli.output import error
+
+            error("Could not detect current branch. Use --source.", ctx=ctx)
+
+    result = client.create_merge_request(
+        project,
+        source_branch=source,  # type: ignore[arg-type]
+        target_branch=target,
+        title=title,
+        description=description,
+        labels=labels,
+        squash=squash,
+    )
+    output(result, ctx=ctx, format_fn=format_mr_detail)
+
+
+@mrs_app.command
+def update(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+    *,
+    title: Annotated[str | None, Parameter(name="--title", help="New title")] = None,
+    description: Annotated[str | None, Parameter(name="--description", help="New description")] = None,
+    labels: Annotated[str | None, Parameter(name="--labels", help="New labels")] = None,
+    target: Annotated[str | None, Parameter(name="--target", help="New target branch")] = None,
+) -> None:
+    """Update a merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.update_mr(project, iid, title=title, description=description, labels=labels, target_branch=target)
+    output(result, ctx=ctx, format_fn=format_mr_detail)
+
+
+@mrs_app.command
+def merge(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+    *,
+    squash: Annotated[bool | None, Parameter(name="--squash", help="Squash commits")] = None,
+    when_pipeline_succeeds: Annotated[
+        bool, Parameter(name="--when-pipeline-succeeds", help="Merge when pipeline succeeds", negative="")
+    ] = False,
+) -> None:
+    """Merge a merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.merge_mr(project, iid, squash=squash, merge_when_pipeline_succeeds=when_pipeline_succeeds)
+    output(result, ctx=ctx, format_fn=format_mr_detail)
+
+
+@mrs_app.command
+def close(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+) -> None:
+    """Close a merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.close_mr(project, iid)
+    output(result, ctx=ctx, format_fn=format_mr_detail)
+
+
+@mrs_app.command
+def discussions(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+) -> None:
+    """List discussions on a merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.get_mr_discussions(project, iid)
+    output_list(items=items, ctx=ctx, format_fn=format_discussion_list)
+
+
+@mrs_app.command
+def changes(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+) -> None:
+    """Show changes/diff for a merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.get_mr_changes(project, iid)
+
+    if ctx.json_mode:
+        from qodev_gitlab_cli.output import output_json
+
+        output_json(result)
+    else:
+        diffs = result.get("changes", [])
+        lines = [f"# Changes for !{iid}", ""]
+        for diff in diffs:
+            lines.append(f"## {diff.get('new_path', '?')}")
+            lines.append(f"```diff\n{diff.get('diff', '')}\n```")
+            lines.append("")
+        output_markdown("\n".join(lines))
+
+
+@mrs_app.command
+def commits(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+) -> None:
+    """List commits in a merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.get_mr_commits(project, iid)
+    output_list(items=items, ctx=ctx, format_fn=format_commit_list)
+
+
+@mrs_app.command
+def approvals(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+) -> None:
+    """Show approval status for a merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.get_mr_approvals(project, iid)
+    output(result, ctx=ctx, format_fn=format_approval_detail)
+
+
+@mrs_app.command
+def comment(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+    *,
+    body: Annotated[str, Parameter(name="--body", help="Comment text")],
+) -> None:
+    """Comment on a merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.create_mr_note(project, iid, body)
+    output(result, ctx=ctx)
+
+
+@mrs_app.command
+def pipelines(
+    iid: Annotated[int, Parameter(help="Merge request IID")],
+) -> None:
+    """List pipelines for a merge request."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.get_mr_pipelines(project, iid)
+    from qodev_gitlab_cli.formatters.pipelines import format_pipeline_list
+
+    output_list(items=items, ctx=ctx, format_fn=format_pipeline_list)

qodev_gitlab_cli/commands/pipelines.py

@@ -0,0 +1,63 @@
+"""Pipeline commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from qodev_gitlab_cli.context import ctx
+from qodev_gitlab_cli.formatters.jobs import format_job_list
+from qodev_gitlab_cli.formatters.pipelines import format_pipeline_detail, format_pipeline_list, format_wait_result
+from qodev_gitlab_cli.output import output, output_list
+
+pipelines_app = App(name="pipelines", help="Manage pipelines.")
+
+
+@pipelines_app.command
+def list(
+    *,
+    ref: Annotated[str | None, Parameter(name="--ref", help="Filter by branch/tag")] = None,
+    limit: Annotated[int, Parameter(name="--limit", help="Max pipelines to return")] = 20,
+) -> None:
+    """List pipelines."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.get_pipelines(project, ref=ref, per_page=limit, max_pages=1)
+    output_list(items=items, ctx=ctx, format_fn=format_pipeline_list)
+
+
+@pipelines_app.command
+def get(
+    id: Annotated[int, Parameter(help="Pipeline ID")],
+) -> None:
+    """Get pipeline details."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.get_pipeline(project, id)
+    output(result, ctx=ctx, format_fn=format_pipeline_detail)
+
+
+@pipelines_app.command
+def jobs(
+    id: Annotated[int, Parameter(help="Pipeline ID")],
+) -> None:
+    """List jobs for a pipeline."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.get_pipeline_jobs(project, id)
+    output_list(items=items, ctx=ctx, format_fn=format_job_list)
+
+
+@pipelines_app.command
+def wait(
+    id: Annotated[int, Parameter(help="Pipeline ID")],
+    *,
+    timeout: Annotated[int, Parameter(name="--timeout", help="Timeout in seconds")] = 3600,
+    interval: Annotated[int, Parameter(name="--interval", help="Check interval in seconds")] = 10,
+) -> None:
+    """Wait for a pipeline to complete."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.wait_for_pipeline(project, id, timeout_seconds=timeout, check_interval=interval)
+    output(result, ctx=ctx, format_fn=format_wait_result)

qodev_gitlab_cli/commands/projects.py

@@ -0,0 +1,35 @@
+"""Project commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from qodev_gitlab_cli.context import ctx
+from qodev_gitlab_cli.formatters.projects import format_project_detail, format_project_list
+from qodev_gitlab_cli.output import output, output_list
+
+projects_app = App(name="projects", help="Manage projects.")
+
+
+@projects_app.command
+def list(
+    *,
+    owned: Annotated[bool, Parameter(name="--owned", help="Only owned projects", negative="")] = False,
+) -> None:
+    """List projects."""
+    client = ctx.client()
+    items = client.get_projects(owned=owned)
+    output_list(items=items, ctx=ctx, format_fn=format_project_list)
+
+
+@projects_app.command
+def get(
+    id: Annotated[str | None, Parameter(help="Project ID or path (defaults to auto-detected)")] = None,
+) -> None:
+    """Get project details."""
+    client = ctx.client()
+    project_id = id or ctx.resolve_project()
+    result = client.get_project(project_id)
+    output(result, ctx=ctx, format_fn=format_project_detail)

qodev_gitlab_cli/commands/releases.py

@@ -0,0 +1,48 @@
+"""Release commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from qodev_gitlab_cli.context import ctx
+from qodev_gitlab_cli.formatters.releases import format_release_detail, format_release_list
+from qodev_gitlab_cli.output import output, output_list
+
+releases_app = App(name="releases", help="Manage releases.")
+
+
+@releases_app.command
+def list() -> None:
+    """List releases."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.get_releases(project)
+    output_list(items=items, ctx=ctx, format_fn=format_release_list)
+
+
+@releases_app.command
+def get(
+    tag: Annotated[str, Parameter(help="Tag name")],
+) -> None:
+    """Get release details."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.get_release(project, tag)
+    output(result, ctx=ctx, format_fn=format_release_detail)
+
+
+@releases_app.command
+def create(
+    *,
+    tag: Annotated[str, Parameter(name="--tag", help="Tag name for the release")],
+    name: Annotated[str | None, Parameter(name="--name", help="Release title")] = None,
+    description: Annotated[str | None, Parameter(name="--description", help="Release notes")] = None,
+    ref: Annotated[str | None, Parameter(name="--ref", help="Commit SHA, branch, or tag")] = None,
+) -> None:
+    """Create a new release."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.create_release(project, tag_name=tag, name=name, description=description, ref=ref)
+    output(result, ctx=ctx, format_fn=format_release_detail)

qodev_gitlab_cli/commands/variables.py

@@ -0,0 +1,61 @@
+"""CI/CD variable commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+
+from qodev_gitlab_cli.context import ctx
+from qodev_gitlab_cli.formatters.variables import format_variable_detail, format_variable_list
+from qodev_gitlab_cli.output import output, output_list
+
+variables_app = App(name="variables", help="Manage CI/CD variables.")
+
+
+@variables_app.command
+def list() -> None:
+    """List CI/CD variables (values hidden)."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    items = client.list_project_variables(project)
+    output_list(items=items, ctx=ctx, format_fn=format_variable_list)
+
+
+@variables_app.command
+def get(
+    key: Annotated[str, Parameter(help="Variable key")],
+) -> None:
+    """Get a CI/CD variable."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    result = client.get_project_variable(project, key)
+    if result is None:
+        from qodev_gitlab_cli.output import error
+
+        error(f"Variable '{key}' not found.", ctx=ctx, code="not_found", exit_code=81)
+    else:
+        output(result, ctx=ctx, format_fn=format_variable_detail)
+
+
+@variables_app.command
+def set(
+    key: Annotated[str, Parameter(help="Variable key")],
+    value: Annotated[str, Parameter(help="Variable value")],
+    *,
+    protected: Annotated[bool, Parameter(name="--protected", help="Only in protected branches", negative="")] = False,
+    masked: Annotated[bool, Parameter(name="--masked", help="Hidden in job logs", negative="")] = False,
+) -> None:
+    """Set a CI/CD variable (create or update)."""
+    client = ctx.client()
+    project = ctx.resolve_project()
+    var, action = client.set_project_variable(project, key, value, protected=protected, masked=masked)
+
+    if ctx.json_mode:
+        from qodev_gitlab_cli.output import output_json
+
+        output_json({"variable": var, "action": action})
+    else:
+        from qodev_gitlab_cli.output import output_markdown
+
+        output_markdown(f"Variable `{key}` **{action}** successfully.")