agent-tool-openproject-cli 0.2.1__py3-none-any.whl

opcli/cli.py

@@ -0,0 +1,166 @@
+"""Top-level Typer application wiring together every command group."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import typer
+
+from . import __version__
+from .context import AppContext
+from .errors import OpError
+from .output import OutputFormat, print_error
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+app = typer.Typer(
+    name="openproject",
+    help=(
+        "Agent-friendly CLI for OpenProject (work packages, projects, time, search, invoicing).\n\n"
+        "Output is JSON on stdout by default (errors are JSON on stderr with a non-zero exit code); "
+        "add `-o table` or `-o markdown`, or trim with `--fields id,subject`. Pass names not ids "
+        "(`--assignee jane.doe`, `--status \"In progress\"`, `me`).\n\n"
+        "New here / no context? Run `openproject guide` for the full playbook, or "
+        "`openproject search fields` to discover what you can filter on."
+    ),
+    epilog=(
+        "Learn more:  `openproject guide`  ·  `openproject guide <topic>`  ·  "
+        "`openproject <group> --help`  ·  discover filters with `openproject search fields`."
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_show_locals=False,
+)
+
+# Remembered so the central error handler in main() can render errors in the
+# same format the user selected, even for failures raised before a command runs.
+_ERROR_FORMAT = OutputFormat.json
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    output: OutputFormat = typer.Option(
+        None, "--output", "-o",
+        help="Output format: json (default), table, or markdown. Also available as --format/-f anywhere on the line.",
+    ),
+    fields: str = typer.Option(
+        None, "--fields", "--columns",
+        help="Comma-separated fields to return/show, e.g. 'id,subject,status,assignee.name'. Works anywhere on the line.",
+    ),
+    profile: str = typer.Option(
+        None, "--profile", "-p", help="Configuration profile (overrides the active one)."
+    ),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable coloured output."),
+    version: bool = typer.Option(
+        None, "--version", "-V", callback=_version_callback, is_eager=True, help="Show version and exit."
+    ),
+) -> None:
+    if profile:
+        os.environ["OPCLI_PROFILE"] = profile
+    # Don't prompt for a default format for meta commands (settings/guide).
+    interactive = ctx.invoked_subcommand not in ("settings", "guide") and sys.stdin.isatty() and sys.stdout.isatty()
+    ctx.obj = AppContext(output=output, color=not no_color, interactive=interactive)
+    global _ERROR_FORMAT
+    _ERROR_FORMAT = ctx.obj.emitter.fmt
+
+
+_FORMAT_FLAGS = ("--format", "-f", "--output", "-o")
+_FIELDS_FLAGS = ("--fields", "--columns")
+
+
+def _pop_globals(argv: list[str]) -> tuple[str | None, str | None, list[str]]:
+    """Extract the output-format and --fields flags (with values) from anywhere on
+    the command line, so they work *after* a subcommand too — e.g.
+    ``openproject wp list -f markdown --fields id,subject``. Honours ``--``."""
+    out: list[str] = []
+    fmt: str | None = None
+    fields: str | None = None
+    i, stop = 0, False
+
+    def take_value(idx: int) -> tuple[str | None, int]:
+        return (argv[idx + 1], idx + 1) if idx + 1 < len(argv) else (None, idx)
+
+    while i < len(argv):
+        a = argv[i]
+        if not stop and a == "--":
+            stop = True
+            out.append(a)
+        elif not stop and a in _FORMAT_FLAGS:
+            fmt, i = take_value(i)
+        elif not stop and a in _FIELDS_FLAGS:
+            fields, i = take_value(i)
+        elif not stop and (a.startswith("--format=") or a.startswith("--output=") or a.startswith("-f=") or a.startswith("-o=")):
+            fmt = a.split("=", 1)[1]
+        elif not stop and (a.startswith("--fields=") or a.startswith("--columns=")):
+            fields = a.split("=", 1)[1]
+        else:
+            out.append(a)
+        i += 1
+    return fmt, fields, out
+
+
+# ---- command groups (registered below to avoid circular imports) ----
+from .commands import (  # noqa: E402
+    attachments,
+    auth,
+    comments,
+    costs,
+    custom_fields,
+    filelinks,
+    guide,
+    memberships,
+    notifications,
+    projects,
+    raw,
+    search,
+    settings,
+    time_entries,
+    users,
+    wiki,
+    workpackages,
+)
+
+app.command("guide", help="Built-in operating guide — how to use this CLI without external docs.")(guide.guide)
+
+app.add_typer(auth.app, name="auth", help="Log in, log out, inspect credentials.")
+app.add_typer(projects.app, name="project", help="Create, list, archive projects.")
+app.add_typer(workpackages.app, name="wp", help="Work packages: CRUD, move, assign, watch.")
+app.add_typer(search.app, name="search", help="Powerful work-package (and global) search.")
+app.add_typer(comments.app, name="comment", help="Add, edit, list work-package comments.")
+app.add_typer(time_entries.app, name="time", help="Log, edit, list time entries + reports.")
+app.add_typer(users.app, name="user", help="Users, groups, memberships, assignable people.")
+app.add_typer(memberships.app, name="member", help="Project memberships & roles.")
+app.add_typer(custom_fields.app, name="cf", help="Inspect custom fields / resource schemas.")
+app.add_typer(notifications.app, name="notify", help="In-app notifications.")
+app.add_typer(wiki.app, name="wiki", help="Wiki pages (read + write where supported).")
+app.add_typer(attachments.app, name="attach", help="Attachments / file uploads on work packages.")
+app.add_typer(filelinks.app, name="filelink", help="Nextcloud/file-storage links on work packages.")
+app.add_typer(costs.app, name="cost", help="Time & cost reporting per person/project (invoicing).")
+app.add_typer(raw.app, name="raw", help="Escape hatch: call any API endpoint directly.")
+app.add_typer(settings.app, name="settings", help="View & change CLI settings (default output format).")
+
+
+def main() -> None:
+    fmt, fields, argv = _pop_globals(sys.argv[1:])
+    if fmt is not None:
+        os.environ["OPCLI_CLI_FORMAT"] = fmt
+    if fields is not None:
+        os.environ["OPCLI_CLI_FIELDS"] = fields
+    try:
+        app(args=argv)
+    except OpError as exc:
+        print_error(exc, _ERROR_FORMAT)
+        sys.exit(exc.exit_code)
+    except KeyboardInterrupt:  # pragma: no cover
+        print_error(OpError("interrupted"), _ERROR_FORMAT)
+        sys.exit(130)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

opcli/client.py

@@ -0,0 +1,252 @@
+"""Thin, robust HTTP client for the OpenProject API v3 (HAL+JSON).
+
+Responsibilities:
+
+* Basic-auth with ``apikey:<token>`` (the standard OpenProject API-key scheme).
+* Normalising paths so callers may pass ``"work_packages"``,
+  ``"/api/v3/work_packages/1"`` or a full URL interchangeably (following the
+  ``href`` values the API returns "just works").
+* Turning HAL error bodies into typed :class:`opcli.errors.OpError` subclasses.
+* Auto-pagination of collection endpoints.
+* Optimistic-locking updates (fetch ``lockVersion`` → PATCH → retry on 409).
+* JSON *and* multipart requests (the latter for attachment uploads).
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+from typing import Any, Callable, Iterator
+
+import httpx
+
+from . import __version__, hal
+from .errors import (
+    ApiError,
+    AuthError,
+    ConflictError,
+    NotFoundError,
+    OpError,
+    ValidationError,
+)
+
+Json = dict[str, Any]
+
+USER_AGENT = f"agent-tool-openproject-cli/{__version__}"
+
+
+class Client:
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        verify_ssl: bool = True,
+        timeout: float = 60.0,
+    ):
+        self.base = base_url.rstrip("/")
+        self.api_root = self.base + "/api/v3"
+        self._http = httpx.Client(
+            auth=httpx.BasicAuth("apikey", token),
+            verify=verify_ssl,
+            timeout=timeout,
+            headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+            follow_redirects=True,
+        )
+
+    # ---- lifecycle ---------------------------------------------------
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ---- url handling ------------------------------------------------
+    def url(self, path: str) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        if path.startswith("/"):
+            return self.base + path
+        return self.api_root + "/" + path
+
+    # ---- low-level request -------------------------------------------
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: dict[str, Any] | None = None,
+        files: Any = None,
+        headers: dict[str, str] | None = None,
+        parse: bool = True,
+    ) -> Any:
+        url = self.url(path)
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+        # OpenProject rejects body-less writes with 406 unless a JSON content-type
+        # is present. Set it for JSON writes (but never for multipart uploads,
+        # where httpx must supply the multipart boundary itself).
+        eff_headers = dict(headers or {})
+        if files is None and method.upper() in ("POST", "PATCH", "PUT"):
+            eff_headers.setdefault("Content-Type", "application/json")
+        try:
+            resp = self._http.request(
+                method,
+                url,
+                params=clean_params or None,
+                json=json,
+                data=data,
+                files=files,
+                headers=eff_headers or None,
+            )
+        except httpx.ConnectError as exc:
+            raise ApiError(f"cannot connect to {self.base}: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise ApiError(f"request to {url} failed: {exc}") from exc
+
+        if resp.status_code >= 400:
+            self._raise_for_error(resp)
+
+        if not parse:
+            return resp
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        ctype = resp.headers.get("content-type", "")
+        if "json" in ctype:
+            return resp.json()
+        return resp.content
+
+    # ---- error mapping -----------------------------------------------
+    def _raise_for_error(self, resp: httpx.Response) -> None:
+        status = resp.status_code
+        payload: Any = None
+        message = f"HTTP {status}"
+        field_errors = None
+        try:
+            payload = resp.json()
+        except Exception:
+            payload = resp.text or None
+
+        if isinstance(payload, dict) and payload.get("_type") == "Error":
+            message = payload.get("message", message)
+            embedded = (payload.get("_embedded") or {}).get("errors")
+            if isinstance(embedded, list) and embedded:
+                field_errors = [e.get("message") for e in embedded if isinstance(e, dict)]
+                message = "; ".join(m for m in field_errors if m) or message
+
+        if status in (401,):
+            raise AuthError(
+                message if message != f"HTTP {status}" else "authentication failed — check your API token",
+                detail=payload,
+            )
+        if status in (403,):
+            raise AuthError(
+                message if message != f"HTTP {status}" else "forbidden — the API user lacks permission",
+                detail=payload,
+            )
+        if status == 404:
+            raise NotFoundError(message if message != f"HTTP {status}" else "resource not found", detail=payload)
+        if status == 409:
+            raise ConflictError(message, detail=payload)
+        if status == 422:
+            raise ValidationError(message, detail=payload, field_errors=field_errors)
+        raise ApiError(message, status=status, detail=payload)
+
+    # ---- verb helpers ------------------------------------------------
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> Json:
+        return self.request("GET", path, params=params)
+
+    def post(self, path: str, *, json: Any = None, params: dict[str, Any] | None = None) -> Json:
+        return self.request("POST", path, json=json, params=params)
+
+    def patch(self, path: str, *, json: Any = None, params: dict[str, Any] | None = None) -> Json:
+        return self.request("PATCH", path, json=json, params=params)
+
+    def delete(self, path: str, *, params: dict[str, Any] | None = None) -> Json:
+        return self.request("DELETE", path, params=params)
+
+    # ---- collections / pagination ------------------------------------
+    def paginate(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        page_size: int = 100,
+        limit: int | None = None,
+    ) -> Iterator[Json]:
+        """Yield every element of a collection endpoint, following pages.
+
+        OpenProject paginates with 1-based ``offset`` (page number) and
+        ``pageSize``. We stop when we've seen ``total`` items, an empty page,
+        or reached ``limit``.
+
+        Note: the server may cap ``pageSize`` below what we ask for, so we must
+        NOT stop merely because a page came back shorter than requested — we
+        rely on the authoritative ``total`` and on an empty page instead.
+        """
+        offset = 1
+        seen = 0
+        # guard against a server that never advances (pathological) — bounded by total
+        while True:
+            page_params = dict(params or {})
+            page_params["offset"] = offset
+            page_params["pageSize"] = page_size
+            doc = self.get(path, params=page_params)
+            batch = hal.elements(doc)
+            if not batch:
+                break
+            for el in batch:
+                yield el
+                seen += 1
+                if limit is not None and seen >= limit:
+                    return
+            if seen >= hal.total(doc):
+                break
+            offset += 1
+
+    def collect(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        page_size: int = 100,
+        limit: int | None = None,
+    ) -> list[Json]:
+        return list(self.paginate(path, params=params, page_size=page_size, limit=limit))
+
+    # ---- optimistic-locking update -----------------------------------
+    def update_locked(
+        self,
+        path: str,
+        patch: Json | Callable[[Json], Json],
+        *,
+        params: dict[str, Any] | None = None,
+        retries: int = 2,
+    ) -> Json:
+        """PATCH a resource, supplying the current ``lockVersion`` automatically.
+
+        ``patch`` may be a dict, or a callable receiving the freshly-fetched
+        resource and returning the patch body (useful when the new value
+        depends on the old one). Retries on 409 conflicts.
+        """
+        last_exc: OpError | None = None
+        for _ in range(retries + 1):
+            current = self.get(path)
+            body = patch(current) if callable(patch) else jsonlib.loads(jsonlib.dumps(patch))
+            lv = current.get("lockVersion")
+            if lv is not None:
+                body.setdefault("lockVersion", lv)
+            try:
+                return self.patch(path, json=body, params=params)
+            except ConflictError as exc:
+                last_exc = exc
+                continue
+        assert last_exc is not None
+        raise last_exc
+
+    # ---- convenience -------------------------------------------------
+    def me(self) -> Json:
+        return self.get("users/me")

opcli/commands/__init__.py

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

opcli/commands/_shared.py

@@ -0,0 +1,50 @@
+"""Helpers shared across command modules."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+
+from ..context import AppContext
+from ..errors import OpError
+
+
+def ctx_obj(ctx: typer.Context) -> AppContext:
+    return ctx.obj
+
+
+def parse_json_option(value: str | None, *, what: str = "value") -> Any:
+    """Parse a JSON string passed on the command line (``--fields '{...}'``)."""
+    if value is None:
+        return None
+    try:
+        return json.loads(value)
+    except json.JSONDecodeError as exc:
+        raise OpError(f"invalid JSON for {what}: {exc}") from exc
+
+
+def set_link(body: dict, name: str, href: str | None) -> None:
+    body.setdefault("_links", {})[name] = {"href": href}
+
+
+def apply_custom_fields(body: dict, raw: str | None) -> None:
+    """Merge a ``--custom-fields`` JSON object into a write body.
+
+    Scalars land at the top level; values shaped like ``{"href": ...}`` (or a
+    list of them) go under ``_links`` — matching OpenProject's split between
+    value and reference custom fields.
+    """
+    if not raw:
+        return
+    data = parse_json_option(raw, what="--custom-fields")
+    if not isinstance(data, dict):
+        raise OpError("--custom-fields must be a JSON object keyed by customFieldN")
+    for key, val in data.items():
+        if isinstance(val, dict) and set(val.keys()) <= {"href"}:
+            set_link(body, key, val.get("href"))
+        elif isinstance(val, list) and all(isinstance(v, dict) and "href" in v for v in val):
+            body.setdefault("_links", {})[key] = val
+        else:
+            body[key] = val

opcli/commands/attachments.py

@@ -0,0 +1,104 @@
+"""Attachment commands: list, upload, download, get, delete.
+
+Upload is multipart/form-data with two parts: a JSON ``metadata`` part
+(``fileName`` + optional ``description``) and the raw ``file`` part. Downloads
+follow the attachment's ``downloadLocation`` link (which may redirect to remote
+storage).
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+from pathlib import Path
+
+import typer
+
+from .. import hal, serialize
+from ..errors import OpError
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("ID", "id"),
+    ("File", "fileName"),
+    ("Size", "fileSize"),
+    ("Type", "contentType"),
+    ("Author", lambda r: (r.get("author") or {}).get("name")),
+    ("When", "createdAt"),
+]
+
+
+@app.command("list")
+def list_attachments(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+) -> None:
+    """List attachments on a work package."""
+    obj = ctx_obj(ctx)
+    rows = [serialize.attachment(a) for a in obj.client().collect(f"work_packages/{wp_id}/attachments")]
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no attachments)")
+
+
+@app.command()
+def upload(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    path: Path = typer.Argument(..., help="Local file to upload."),
+    name: str = typer.Option(None, "--name", help="Override the stored file name."),
+    description: str = typer.Option(None, "--description", "-d", help="Attachment description."),
+) -> None:
+    """Upload a file and attach it to a work package."""
+    obj = ctx_obj(ctx)
+    if not path.exists() or not path.is_file():
+        raise OpError(f"file not found: {path}")
+    file_name = name or path.name
+    metadata = {"fileName": file_name}
+    if description is not None:
+        metadata["description"] = description
+    content_type = mimetypes.guess_type(file_name)[0] or "application/octet-stream"
+    files = {
+        "metadata": (None, json.dumps(metadata), "application/json"),
+        "file": (file_name, path.read_bytes(), content_type),
+    }
+    doc = obj.client().request("POST", f"work_packages/{wp_id}/attachments", files=files)
+    obj.emitter.emit(serialize.attachment(doc))
+
+
+@app.command()
+def get(ctx: typer.Context, attachment_id: int = typer.Argument(..., help="Attachment id.")) -> None:
+    """Show attachment metadata."""
+    obj = ctx_obj(ctx)
+    obj.emitter.emit(serialize.attachment(obj.client().get(f"attachments/{attachment_id}")))
+
+
+@app.command()
+def download(
+    ctx: typer.Context,
+    attachment_id: int = typer.Argument(..., help="Attachment id."),
+    output: Path = typer.Option(None, "--output", "-O", help="Output path (default: original file name)."),
+) -> None:
+    """Download an attachment's content."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    meta = client.get(f"attachments/{attachment_id}")
+    href = hal.link_href(meta, "downloadLocation") or f"/api/v3/attachments/{attachment_id}/content"
+    resp = client.request("GET", href, parse=False)
+    dest = output or Path(meta.get("fileName") or f"attachment-{attachment_id}")
+    dest.write_bytes(resp.content)
+    obj.emitter.emit({"status": "downloaded", "attachment": attachment_id, "path": str(dest), "bytes": len(resp.content)})
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    attachment_id: int = typer.Argument(..., help="Attachment id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Delete an attachment."""
+    obj = ctx_obj(ctx)
+    if not yes:
+        typer.confirm(f"Delete attachment {attachment_id}?", abort=True)
+    obj.client().delete(f"attachments/{attachment_id}")
+    obj.emitter.emit({"status": "deleted", "attachment": attachment_id})

opcli/commands/auth.py

@@ -0,0 +1,113 @@
+"""Authentication commands: login, logout, status, whoami."""
+
+from __future__ import annotations
+
+import os
+
+import typer
+
+from .. import credentials, serialize
+from ..client import Client
+from ..config import Profile
+from ..errors import AuthError, OpError
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command()
+def login(
+    ctx: typer.Context,
+    url: str = typer.Option(None, "--url", "-u", help="Base URL, e.g. https://op.example.com"),
+    token: str = typer.Option(None, "--token", "-t", help="API token (prompted if omitted)."),
+    name: str = typer.Option(None, "--name", help="Profile name to store under."),
+    username: str = typer.Option(None, "--username", help="Informational: the API user's login."),
+    no_verify_ssl: bool = typer.Option(False, "--no-verify-ssl", help="Skip TLS verification."),
+) -> None:
+    """Verify and store an API token securely (OS keyring by default).
+
+    Non-interactive example:
+      openproject auth login --url http://localhost:8090 --token opapi-xxxx
+    """
+    obj = ctx_obj(ctx)
+    profile_name = name or os.environ.get("OPCLI_PROFILE") or obj.config.current_profile or "default"
+
+    base_url = url or os.environ.get("OPCLI_BASE_URL")
+    if not base_url:
+        base_url = typer.prompt("OpenProject base URL")
+    if not token:
+        token = os.environ.get("OPCLI_TOKEN") or typer.prompt("API token", hide_input=True)
+
+    # Verify before persisting anything.
+    with Client(base_url, token, verify_ssl=not no_verify_ssl) as client:
+        try:
+            me = client.me()
+        except AuthError as exc:
+            raise AuthError(f"login failed: {exc.message}") from exc
+
+    prof = Profile(
+        name=profile_name,
+        base_url=base_url,
+        username=username or me.get("login"),
+        verify_ssl=not no_verify_ssl,
+    )
+    obj.config.upsert_profile(prof, make_current=True)
+    obj.config.save()
+    backend = credentials.store_token(profile_name, token)
+
+    obj.emitter.emit(
+        {
+            "status": "logged in",
+            "profile": profile_name,
+            "baseUrl": base_url,
+            "user": serialize.user(me),
+            "tokenStoredIn": backend,
+        }
+    )
+
+
+@app.command()
+def status(ctx: typer.Context) -> None:
+    """Show the active profile, credential backend, and connectivity."""
+    obj = ctx_obj(ctx)
+    try:
+        prof = obj.profile()
+    except OpError as exc:
+        obj.emitter.emit({"configured": False, "reason": exc.message})
+        return
+
+    info = {
+        "profile": prof.name,
+        "baseUrl": prof.base_url,
+        "username": prof.username,
+        "verifySsl": prof.verify_ssl,
+        "credentialBackend": credentials.backend_name(),
+        "hasToken": bool(obj.token()),
+    }
+    if obj.token():
+        try:
+            info["reachable"] = True
+            info["me"] = serialize.user(obj.client().me())
+        except OpError as exc:
+            info["reachable"] = False
+            info["error"] = exc.message
+    obj.emitter.emit(info)
+
+
+@app.command()
+def whoami(ctx: typer.Context) -> None:
+    """Print the authenticated user (GET /users/me)."""
+    obj = ctx_obj(ctx)
+    obj.emitter.emit(serialize.user(obj.client().me()))
+
+
+@app.command()
+def logout(
+    ctx: typer.Context,
+    name: str = typer.Option(None, "--name", help="Profile to log out (defaults to active)."),
+) -> None:
+    """Remove the stored API token for a profile."""
+    obj = ctx_obj(ctx)
+    profile_name = name or obj.config.active_profile_name()
+    credentials.delete_token(profile_name)
+    obj.emitter.emit({"status": "logged out", "profile": profile_name})