runspec-gitlab 0.1.0__tar.gz

runspec_gitlab-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_gitlab-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `runspec-gitlab` are documented here.
+
+## [0.1.0]
+
+Initial release. One runnable, `gitlab`, with a read verb per tool of the
+[GitLab MCP server](https://docs.gitlab.com/user/model_context_protocol/mcp_server/),
+**ported onto the GitLab REST API (v4)** rather than proxying that server — so it
+runs over the runspec-console SSH fleet with no extra process. `runspec serve`
+re-expands each verb into its own leaf MCP tool (`gitlab_get-issue`,
+`gitlab_list-pipelines`, …).
+
+- Verbs (all `autonomy = "autonomous"` — read-only): `whoami`, `get-project`,
+  `search-projects`, `list-issues`, `get-issue`, `list-merge-requests`,
+  `get-merge-request`, `get-merge-request-changes`, `list-pipelines`,
+  `get-pipeline-jobs`, `get-job-log`, `get-file`, `list-tree`.
+- Global `--env` (dev/uat/prod) selects `GITLAB_<ENV>_*` env vars; auth is
+  `GITLAB_URL` (default `https://gitlab.com`) + `GITLAB_TOKEN`. `project` accepts
+  a numeric id or `group/project` path and falls back to `GITLAB_PROJECT`.
+- Thin wrapper over `runspec-gitlab-core` (the dependency-free REST logic core).

runspec_gitlab-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: runspec-gitlab
+Version: 0.1.0
+Summary: GitLab read runnable for runspec — issues, merge requests, pipelines, and repository reads, ported from the GitLab MCP server
+Requires-Python: >=3.10
+Requires-Dist: runspec-gitlab-core>=0.1.0
+Requires-Dist: runspec>=0.44.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'

runspec_gitlab-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-gitlab"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "GitLab read runnable for runspec — issues, merge requests, pipelines, and repository reads, ported from the GitLab MCP server"
+dependencies = [
+    # 0.44.0 surfaces inherited args (the global --env) on each leaf subcommand's
+    # MCP tool via `runspec serve`.
+    "runspec>=0.44.0",
+    "runspec-gitlab-core>=0.1.0",
+]
+
+[project.scripts]
+# Entry point name MUST match the runnable name in runspec.toml (`gitlab`).
+gitlab = "runspec_gitlab.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.15.20",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_gitlab-0.1.0/runspec_gitlab/__init__.py

@@ -0,0 +1,54 @@
+"""runspec-gitlab — GitLab reads as a runspec runnable (the ``gitlab`` runnable).
+
+Ported from the
+`GitLab MCP server <https://docs.gitlab.com/user/model_context_protocol/mcp_server/>`_.
+The pure REST logic lives in ``runspec-gitlab-core`` (importable with **no**
+runspec dependency); this package wraps each helper as a verb of the ``gitlab``
+runnable and is what ``runspec local`` / ``runspec serve`` discover.
+
+The core helpers are re-exported here for convenience / back-compat, so a caller
+that already depends on ``runspec-gitlab`` can ``from runspec_gitlab import
+list_issues`` without also naming ``runspec-gitlab-core``.
+"""
+
+from runspec_gitlab_core import (
+    GitlabConfig,
+    GitlabError,
+    config_from_env,
+    encode_project,
+    get_file,
+    get_issue,
+    get_job_log,
+    get_merge_request,
+    get_merge_request_changes,
+    get_pipeline_jobs,
+    get_project,
+    gitlab_request,
+    list_issues,
+    list_merge_requests,
+    list_pipelines,
+    list_tree,
+    search_projects,
+    whoami,
+)
+
+__all__ = [
+    "GitlabConfig",
+    "GitlabError",
+    "config_from_env",
+    "gitlab_request",
+    "encode_project",
+    "whoami",
+    "get_project",
+    "search_projects",
+    "list_issues",
+    "get_issue",
+    "list_merge_requests",
+    "get_merge_request",
+    "get_merge_request_changes",
+    "list_pipelines",
+    "get_pipeline_jobs",
+    "get_job_log",
+    "get_file",
+    "list_tree",
+]

runspec_gitlab-0.1.0/runspec_gitlab/cli.py

@@ -0,0 +1,132 @@
+"""cli.py — the ``gitlab`` entry point.
+
+One binary, a verb per GitLab MCP read tool. ``rs.parse("gitlab")`` resolves the
+subcommand and its args; we build a :class:`GitlabConfig` from the environment
+(scoped by the global ``--env``), unpack each ``.value`` at the boundary, and call
+the matching :mod:`runspec_gitlab_core` helper.
+
+Failures (the ``runspec_gitlab_core`` :class:`GitlabError` and arg-shape
+``ValueError``s) become a JSON ``{"error": ...}`` payload + a non-zero exit.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import runspec as rs
+from runspec_gitlab_core import (
+    GitlabConfig,
+    GitlabError,
+    config_from_env,
+    get_file,
+    get_issue,
+    get_job_log,
+    get_merge_request,
+    get_merge_request_changes,
+    get_pipeline_jobs,
+    get_project,
+    list_issues,
+    list_merge_requests,
+    list_pipelines,
+    list_tree,
+    search_projects,
+    whoami,
+)
+
+
+def _emit(payload: Any) -> None:
+    print(json.dumps(payload, default=str))
+
+
+def _dispatch(spec: rs.RunSpec, config: GitlabConfig) -> Any:
+    """Run the active verb against ``config``, unpacking ``spec.<arg>.value`` for
+    only the args the verb declares (globals + its own)."""
+    command = spec.runspec_command
+
+    if command == "whoami":
+        return whoami(config)
+    if command == "get-project":
+        return get_project(config, project=spec.project.value)
+    if command == "search-projects":
+        return search_projects(
+            config,
+            search=spec.search.value,
+            membership=spec.membership.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "list-issues":
+        return list_issues(
+            config,
+            project=spec.project.value,
+            state=spec.state.value,
+            labels=spec.labels.value,
+            search=spec.search.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-issue":
+        return get_issue(config, issue_iid=spec.issue_iid.value, project=spec.project.value)
+    if command == "list-merge-requests":
+        return list_merge_requests(
+            config,
+            project=spec.project.value,
+            state=spec.state.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-merge-request":
+        return get_merge_request(config, mr_iid=spec.mr_iid.value, project=spec.project.value)
+    if command == "get-merge-request-changes":
+        return get_merge_request_changes(config, mr_iid=spec.mr_iid.value, project=spec.project.value)
+    if command == "list-pipelines":
+        return list_pipelines(
+            config,
+            project=spec.project.value,
+            ref=spec.ref.value,
+            status=spec.status.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-pipeline-jobs":
+        return get_pipeline_jobs(
+            config,
+            pipeline_id=spec.pipeline_id.value,
+            project=spec.project.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+    if command == "get-job-log":
+        return get_job_log(config, job_id=spec.job_id.value, project=spec.project.value, tail=spec.tail.value)
+    if command == "get-file":
+        return get_file(config, file_path=spec.file_path.value, ref=spec.ref.value, project=spec.project.value)
+    if command == "list-tree":
+        return list_tree(
+            config,
+            path=spec.path.value,
+            ref=spec.ref.value,
+            recursive=spec.recursive.value,
+            project=spec.project.value,
+            per_page=spec.per_page.value,
+            page=spec.page.value,
+        )
+
+    # require-command = true makes a bare invocation unreachable.
+    raise SystemExit("no command — see `gitlab --help`")  # pragma: no cover
+
+
+def main() -> None:
+    spec = rs.parse("gitlab")
+    try:
+        config = config_from_env(env=spec.env.value)
+        result = _dispatch(spec, config)
+    except (GitlabError, ValueError) as exc:
+        _emit({"error": str(exc), "kind": type(exc).__name__})
+        sys.exit(1)
+    _emit(result)
+
+
+if __name__ == "__main__":
+    main()

runspec_gitlab-0.1.0/runspec_gitlab/runspec.toml

@@ -0,0 +1,156 @@
+#:schema https://runspec.app/runspec.schema.json
+
+# runspec-gitlab — GitLab reads as a runspec runnable, ported from the GitLab MCP
+# server: https://docs.gitlab.com/user/model_context_protocol/mcp_server/
+#
+# One runnable, `gitlab`, with a verb per read tool. `runspec serve` re-expands
+# each verb into its own leaf MCP tool (gitlab_get-issue, gitlab_list-pipelines,
+# …), so a runspec-console agent calls them individually — over SSH on any fleet
+# host.
+#
+# The tools are PORTED onto the GitLab REST API (v4), not proxied from GitLab's
+# hosted MCP server, so no extra process is involved. Auth is env-var driven:
+#   GITLAB_URL  (default https://gitlab.com) + GITLAB_TOKEN  (a personal access
+#   token). Per-environment overrides use a GITLAB_<ENV>_ prefix (e.g.
+#   GITLAB_UAT_TOKEN), selected with the global --env (dev/uat/prod) arg.
+#
+# `project` accepts a numeric id or a URL-path (`group/subgroup/project`); it
+# falls back to GITLAB_PROJECT when omitted.
+
+[config]
+autonomy-default = "confirm"
+
+[config.logging]
+store = "per-run"
+
+[gitlab]
+description = "Read GitLab issues, merge requests, pipelines, and repository files (over the REST API)"
+output = "json"
+require-command = true
+examples = [
+  {cmd = "gitlab whoami", description = "Verify the token and show the authenticated user"},
+  {cmd = "gitlab list-issues --project group/app --state opened", description = "List a project's open issues"},
+  {cmd = "gitlab get-merge-request-changes --project 42 --mr-iid 17", description = "Show a merge request's diffs"},
+  {cmd = "gitlab get-job-log --project group/app --job-id 9001 --tail 100", description = "Tail the last 100 lines of a CI job log"},
+  {cmd = "gitlab get-file --project group/app --file-path src/main.py --ref main", description = "Read a repository file at a ref"},
+]
+
+# ── global args (inherited by every verb) ──────────────────────────────────
+[gitlab.args]
+env = {type = "choice", options = ["dev", "uat", "prod"], short = "-e", required = false, description = "Target environment (selects GITLAB_<ENV>_* vars)"}
+
+# ── identity / projects ────────────────────────────────────────────────────
+
+[gitlab.commands.whoami]
+description = "Return the authenticated user for the configured token (a quick identity/token check)"
+autonomy = "autonomous"
+
+[gitlab.commands.get-project]
+description = "Fetch a single project's metadata by numeric id or namespace/project path"
+autonomy = "autonomous"
+[gitlab.commands.get-project.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+
+[gitlab.commands.search-projects]
+description = "Search visible projects by name/path"
+autonomy = "autonomous"
+[gitlab.commands.search-projects.args]
+search = {type = "str", required = true, description = "Text to match against project name/path"}
+membership = {type = "flag", default = false, description = "Only projects the token's user is a member of"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+# ── issues ─────────────────────────────────────────────────────────────────
+
+[gitlab.commands.list-issues]
+description = "List a project's issues, optionally filtered by state/labels/search"
+autonomy = "autonomous"
+[gitlab.commands.list-issues.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+state = {type = "choice", options = ["opened", "closed", "all"], required = false, description = "Issue state filter"}
+labels = {type = "str", required = false, description = "Comma-separated label list to filter by"}
+search = {type = "str", required = false, description = "Match title/description text"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+[gitlab.commands.get-issue]
+description = "Fetch a single issue by its project-scoped internal id (iid)"
+autonomy = "autonomous"
+[gitlab.commands.get-issue.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+issue-iid = {type = "int", required = true, description = "Issue internal id (the #N shown in the UI)"}
+
+# ── merge requests ─────────────────────────────────────────────────────────
+
+[gitlab.commands.list-merge-requests]
+description = "List a project's merge requests, optionally filtered by state"
+autonomy = "autonomous"
+[gitlab.commands.list-merge-requests.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+state = {type = "choice", options = ["opened", "closed", "merged", "locked", "all"], required = false, description = "Merge request state filter"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+[gitlab.commands.get-merge-request]
+description = "Fetch a single merge request by its project-scoped internal id (iid)"
+autonomy = "autonomous"
+[gitlab.commands.get-merge-request.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+mr-iid = {type = "int", required = true, description = "Merge request internal id (the !N shown in the UI)"}
+
+[gitlab.commands.get-merge-request-changes]
+description = "Fetch a merge request together with its file changes / diffs"
+autonomy = "autonomous"
+[gitlab.commands.get-merge-request-changes.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+mr-iid = {type = "int", required = true, description = "Merge request internal id (the !N shown in the UI)"}
+
+# ── pipelines / jobs ───────────────────────────────────────────────────────
+
+[gitlab.commands.list-pipelines]
+description = "List a project's CI/CD pipelines, optionally filtered by ref/status"
+autonomy = "autonomous"
+[gitlab.commands.list-pipelines.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+ref = {type = "str", required = false, description = "Branch or tag to filter by"}
+status = {type = "choice", options = ["created", "waiting_for_resource", "preparing", "pending", "running", "success", "failed", "canceled", "skipped", "manual", "scheduled"], required = false, description = "Pipeline status filter"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+[gitlab.commands.get-pipeline-jobs]
+description = "List the jobs of a pipeline (by pipeline id)"
+autonomy = "autonomous"
+[gitlab.commands.get-pipeline-jobs.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+pipeline-id = {type = "int", required = true, description = "Pipeline id (not the iid)"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}
+
+[gitlab.commands.get-job-log]
+description = "Fetch a CI job's log (trace) as text; pass --tail to return only the last N lines"
+autonomy = "autonomous"
+[gitlab.commands.get-job-log.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+job-id = {type = "int", required = true, description = "Job id"}
+tail = {type = "int", required = false, description = "Return only the last N lines (logs are large — usually pass this)"}
+
+# ── repository ─────────────────────────────────────────────────────────────
+
+[gitlab.commands.get-file]
+description = "Read a single repository file at a ref (base64 is decoded; non-UTF-8 files are flagged binary)"
+autonomy = "autonomous"
+[gitlab.commands.get-file.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+file-path = {type = "str", required = true, description = "Path within the repository (e.g. src/main.py)"}
+ref = {type = "str", default = "HEAD", description = "Branch, tag, or commit (default HEAD = the default branch tip)"}
+
+[gitlab.commands.list-tree]
+description = "List a repository tree at a path/ref; --recursive walks subdirectories"
+autonomy = "autonomous"
+[gitlab.commands.list-tree.args]
+project = {type = "str", short = "-p", required = false, description = "Project id or path (falls back to GITLAB_PROJECT)"}
+path = {type = "str", required = false, description = "Subdirectory to list (default: repository root)"}
+ref = {type = "str", required = false, description = "Branch, tag, or commit (default: the default branch)"}
+recursive = {type = "flag", default = false, description = "Walk subdirectories recursively"}
+per-page = {type = "int", default = 20, description = "Results per page (GitLab caps at 100)"}
+page = {type = "int", default = 1, description = "Page number"}

runspec_gitlab-0.1.0/tests/test_cli.py

@@ -0,0 +1,106 @@
+"""Wrapper logic: real parsed spec → `_dispatch` → core helper, with the core's
+httpx routed through a MockTransport (no real network), plus the main() error path."""
+
+import json
+from pathlib import Path
+
+import httpx
+import pytest
+from runspec.testing import ParseHarness
+from runspec_gitlab_core import GitlabConfig
+from runspec_gitlab_core import client as client_mod
+
+from runspec_gitlab import cli
+
+SPEC = Path(__file__).parent.parent / "runspec_gitlab" / "runspec.toml"
+CFG = GitlabConfig(base_url="https://gl", token="tok", project="grp/app")
+
+
+def _harness() -> ParseHarness:
+    return ParseHarness(script_name="gitlab", config_path=SPEC)
+
+
+def _capture(monkeypatch, response: httpx.Response) -> dict:
+    seen: dict = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        # raw_path keeps %2F encoded (the real wire path); .path would decode it.
+        seen["path"] = request.url.raw_path.decode().split("?")[0]
+        seen["query"] = dict(request.url.params)
+        return response
+
+    transport = httpx.MockTransport(handler)
+
+    def fake_request(method, url, **kwargs):
+        with httpx.Client(transport=transport) as c:
+            return c.request(method, url, **kwargs)
+
+    monkeypatch.setattr(client_mod.httpx, "request", fake_request)
+    return seen
+
+
+# ── _dispatch over a real parsed spec ───────────────────────────────────────
+
+
+def test_dispatch_list_issues_unpacks_args(monkeypatch) -> None:
+    seen = _capture(monkeypatch, httpx.Response(200, json=[{"iid": 1}]))
+    h = _harness()
+    spec = h.expect_ok(["list-issues", "--project", "grp/app", "--state", "opened", "--labels", "bug"])
+    result = cli._dispatch(spec, CFG)
+    h.close()
+    assert result == [{"iid": 1}]
+    assert seen["path"] == "/api/v4/projects/grp%2Fapp/issues"
+    assert seen["query"]["state"] == "opened"
+    assert seen["query"]["labels"] == "bug"
+
+
+def test_dispatch_get_job_log_tail(monkeypatch) -> None:
+    _capture(monkeypatch, httpx.Response(200, text="a\nb\nc\nd"))
+    h = _harness()
+    spec = h.expect_ok(["get-job-log", "--project", "grp/app", "--job-id", "5", "--tail", "2"])
+    result = cli._dispatch(spec, CFG)
+    h.close()
+    assert result["trace"] == "c\nd"
+    assert result["truncated"] is True
+
+
+def test_dispatch_whoami(monkeypatch) -> None:
+    seen = _capture(monkeypatch, httpx.Response(200, json={"username": "alice"}))
+    h = _harness()
+    spec = h.expect_ok(["whoami"])
+    assert cli._dispatch(spec, CFG) == {"username": "alice"}
+    h.close()
+    assert seen["path"] == "/api/v4/user"
+
+
+def test_dispatch_get_file_decodes(monkeypatch) -> None:
+    import base64
+
+    encoded = base64.b64encode(b"print('hi')").decode()
+    _capture(monkeypatch, httpx.Response(200, json={"encoding": "base64", "content": encoded}))
+    h = _harness()
+    spec = h.expect_ok(["get-file", "--project", "grp/app", "--file-path", "a.py", "--ref", "main"])
+    result = cli._dispatch(spec, CFG)
+    h.close()
+    assert result["content"] == "print('hi')"
+
+
+# ── main() error path ───────────────────────────────────────────────────────
+
+
+def test_main_missing_token_emits_error(monkeypatch, capsys) -> None:
+    # No GITLAB_* env → config_from_env raises GitlabError → JSON error + exit 1.
+    for var in ("GITLAB_TOKEN", "GITLAB_URL", "GITLAB_ENV"):
+        monkeypatch.delenv(var, raising=False)
+    # Build the spec via the real parser FIRST, then stub cli's parse to return
+    # it — patching parse before this would also break the harness's own call.
+    h = _harness()
+    spec = h.expect_ok(["whoami"])
+    h.close()
+    monkeypatch.setattr(cli.rs, "parse", lambda name: spec)
+    with pytest.raises(SystemExit) as exc:
+        cli.main()
+    assert exc.value.code == 1
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["kind"] == "GitlabError"
+    assert "token" in payload["error"].lower()

runspec_gitlab-0.1.0/tests/test_spec.py

@@ -0,0 +1,83 @@
+"""Wiring / parsing tests for the `gitlab` runnable — no mocks, real spec."""
+
+from pathlib import Path
+
+from runspec.testing import ParseHarness
+
+SPEC = Path(__file__).parent.parent / "runspec_gitlab" / "runspec.toml"
+
+
+def _harness() -> ParseHarness:
+    return ParseHarness(script_name="gitlab", config_path=SPEC)
+
+
+def test_smoke_all_verbs() -> None:
+    h = _harness()
+    # Walk the whole verb tree: --help exits 0, require-command is enforced,
+    # omitting required args exits 1, and a fully-populated invocation parses.
+    h.smoke(
+        values={
+            "project": "grp/app",
+            "search": "x",
+            "issue-iid": 1,
+            "mr-iid": 1,
+            "pipeline-id": 1,
+            "job-id": 1,
+            "file-path": "README.md",
+        }
+    )
+    h.close()
+
+
+def test_int_args_coerce() -> None:
+    h = _harness()
+    spec = h.expect_ok(["get-issue", "--project", "grp/app", "--issue-iid", "42"])
+    assert spec.runspec_command == "get-issue"
+    assert spec.issue_iid.value == 42
+    assert isinstance(spec.issue_iid.value, int)
+    h.close()
+
+
+def test_default_per_page() -> None:
+    h = _harness()
+    spec = h.expect_ok(["list-issues", "--project", "grp/app"])
+    assert spec.per_page.value == 20
+    assert spec.page.value == 1
+    assert spec.state.value is None
+    h.close()
+
+
+def test_global_env_choice_inherited() -> None:
+    h = _harness()
+    spec = h.expect_ok(["--env", "uat", "whoami"])
+    assert spec.env.value == "uat"
+    h.close()
+
+
+def test_get_file_ref_defaults_to_head() -> None:
+    h = _harness()
+    spec = h.expect_ok(["get-file", "--project", "grp/app", "--file-path", "a.py"])
+    assert spec.ref.value == "HEAD"
+    h.close()
+
+
+def test_bad_state_choice_rejected() -> None:
+    h = _harness()
+    h.expect_exit(
+        ["list-issues", "--project", "grp/app", "--state", "nope"],
+        contains="state",
+    )
+    h.close()
+
+
+def test_missing_required_issue_iid_rejected() -> None:
+    h = _harness()
+    h.expect_exit(["get-issue", "--project", "grp/app"], contains="issue-iid")
+    h.close()
+
+
+def test_list_tree_recursive_flag() -> None:
+    h = _harness()
+    spec = h.expect_ok(["list-tree", "--project", "grp/app", "--recursive"])
+    assert spec.recursive.value is True
+    h.close()