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

opcli/credentials.py

@@ -0,0 +1,139 @@
+"""Secure storage of OpenProject API tokens.
+
+Order of preference for reading a token:
+
+1. The ``OPCLI_TOKEN`` environment variable (used by CI / the test suite and
+   handy for one-off scripting).
+2. The operating-system keyring (Secret Service / macOS Keychain / Windows
+   Credential Locker) via the :mod:`keyring` library — the safe default.
+3. A ``0600`` fallback file in the config directory, used only when no real
+   keyring backend is available (headless boxes without a Secret Service).
+   We warn loudly in that case because the token is stored in clear text.
+
+The token is the only secret we persist. Everything else (base URL, the API
+username, TLS options) lives in the plain-text config file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+KEYRING_SERVICE = "op-cli"
+ENV_TOKEN = "OPCLI_TOKEN"
+
+
+def _config_dir() -> Path:
+    base = os.environ.get("OPCLI_CONFIG_DIR")
+    if base:
+        return Path(base)
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(xdg) if xdg else Path.home() / ".config"
+    return root / "op-cli"
+
+
+def _fallback_file() -> Path:
+    return _config_dir() / "credentials.json"
+
+
+def _keyring_available() -> bool:
+    try:
+        import keyring
+        from keyring.backends import fail
+
+        return not isinstance(keyring.get_keyring(), fail.Keyring)
+    except Exception:
+        return False
+
+
+def _read_fallback() -> dict[str, str]:
+    path = _fallback_file()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except Exception:
+        return {}
+
+
+def _write_fallback(data: dict[str, str]) -> None:
+    path = _fallback_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Create with 0600 from the start so the plaintext token is never briefly
+    # world-readable (mode 0o600 has no group/other bits, so umask can't widen it).
+    fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
+        json.dump(data, fh, indent=2)
+    try:
+        path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 0600 (also fixes a pre-existing file)
+    except OSError:
+        pass
+
+
+def backend_name() -> str:
+    """Human-readable name of the active secret backend (for `auth status`)."""
+    if os.environ.get(ENV_TOKEN):
+        return f"environment variable ${ENV_TOKEN}"
+    if _keyring_available():
+        try:
+            import keyring
+
+            return f"OS keyring ({keyring.get_keyring().__class__.__name__})"
+        except Exception:
+            pass
+    return f"plaintext fallback file ({_fallback_file()})"
+
+
+def store_token(profile: str, token: str) -> str:
+    """Persist *token* for *profile*. Returns the backend used."""
+    if _keyring_available():
+        try:
+            import keyring
+
+            keyring.set_password(KEYRING_SERVICE, profile, token)
+            return "keyring"
+        except Exception as exc:  # pragma: no cover - depends on host
+            print(f"warning: keyring store failed ({exc}); using fallback file", file=sys.stderr)
+    data = _read_fallback()
+    data[profile] = token
+    _write_fallback(data)
+    print(
+        f"warning: no OS keyring available — token stored in clear text at {_fallback_file()} (0600)",
+        file=sys.stderr,
+    )
+    return "file"
+
+
+def get_token(profile: str) -> str | None:
+    """Resolve the token for *profile*, honouring the env override first."""
+    env = os.environ.get(ENV_TOKEN)
+    if env:
+        return env
+    if _keyring_available():
+        try:
+            import keyring
+
+            tok = keyring.get_password(KEYRING_SERVICE, profile)
+            if tok:
+                return tok
+        except Exception:
+            pass
+    return _read_fallback().get(profile)
+
+
+def delete_token(profile: str) -> None:
+    """Remove any stored token for *profile* from every backend."""
+    if _keyring_available():
+        try:
+            import keyring
+
+            keyring.delete_password(KEYRING_SERVICE, profile)
+        except Exception:
+            pass
+    data = _read_fallback()
+    if profile in data:
+        del data[profile]
+        _write_fallback(data)

opcli/duration.py

@@ -0,0 +1,56 @@
+"""ISO-8601 duration <-> decimal hours.
+
+OpenProject stores time-ish values (``estimatedTime``, time-entry ``hours``)
+as ISO-8601 durations like ``PT2H30M`` and *rejects* plain decimals. Humans and
+agents want to type ``2.5``. These helpers bridge the two, both directions.
+"""
+
+from __future__ import annotations
+
+import re
+
+_ISO_RE = re.compile(
+    r"^P(?:(?P<w>\d+(?:\.\d+)?)W)?(?:(?P<d>\d+(?:\.\d+)?)D)?"
+    r"(?:T(?:(?P<h>\d+(?:\.\d+)?)H)?(?:(?P<m>\d+(?:\.\d+)?)M)?(?:(?P<s>\d+(?:\.\d+)?)S)?)?$"
+)
+
+
+def hours_to_iso(hours: float) -> str:
+    """``2.5`` -> ``"PT2H30M"``. Uses hours/minutes/seconds only."""
+    total = round(float(hours) * 3600)
+    if total == 0:
+        return "PT0S"
+    h, rem = divmod(total, 3600)
+    m, s = divmod(rem, 60)
+    out = "PT"
+    if h:
+        out += f"{h}H"
+    if m:
+        out += f"{m}M"
+    if s:
+        out += f"{s}S"
+    return out
+
+
+def iso_to_hours(value: str | None) -> float | None:
+    """``"PT2H30M"`` -> ``2.5``. Returns ``None`` for falsy input.
+
+    Days count as 24h and weeks as 7 days — adequate for OpenProject's usage
+    (it never emits year/month components for durations).
+    """
+    if not value:
+        return None
+    m = _ISO_RE.match(value.strip())
+    if not m:
+        return None
+    parts = {k: float(v) if v else 0.0 for k, v in m.groupdict().items()}
+    return parts["w"] * 168 + parts["d"] * 24 + parts["h"] + parts["m"] / 60 + parts["s"] / 3600
+
+
+def parse_hours_input(value: str) -> str:
+    """Accept either a decimal (``"2.5"``) or an ISO duration (``"PT2H30M"``)
+    from the user and normalise to the ISO form the API wants."""
+    v = value.strip()
+    if v.upper().startswith("P"):
+        return v  # already ISO
+    return hours_to_iso(float(v))

opcli/errors.py

@@ -0,0 +1,81 @@
+"""Exception types for the OpenProject CLI.
+
+Every user-facing failure funnels through :class:`OpError` so the CLI entry
+point can render a single, clean error line (and a JSON error object when
+``--output json`` is active) instead of a Python traceback.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class OpError(Exception):
+    """Base class for all expected, user-facing errors."""
+
+    exit_code = 1
+
+    def __init__(self, message: str, *, detail: Any = None):
+        super().__init__(message)
+        self.message = message
+        self.detail = detail
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"error": self.message}
+        if self.detail is not None:
+            out["detail"] = self.detail
+        return out
+
+
+class ConfigError(OpError):
+    """Something is wrong with configuration or stored credentials."""
+
+    exit_code = 3
+
+
+class AuthError(OpError):
+    """Authentication/authorization failed (401/403)."""
+
+    exit_code = 4
+
+
+class NotFoundError(OpError):
+    """A requested resource does not exist (404)."""
+
+    exit_code = 5
+
+
+class ConflictError(OpError):
+    """Optimistic-locking or uniqueness conflict (409/422 stale lockVersion)."""
+
+    exit_code = 6
+
+
+class ValidationError(OpError):
+    """The server rejected the request payload (422)."""
+
+    exit_code = 7
+
+    def __init__(self, message: str, *, detail: Any = None, field_errors: Any = None):
+        super().__init__(message, detail=detail)
+        self.field_errors = field_errors
+
+    def to_dict(self) -> dict[str, Any]:
+        out = super().to_dict()
+        if self.field_errors:
+            out["fieldErrors"] = self.field_errors
+        return out
+
+
+class ApiError(OpError):
+    """A non-specific API error carrying the HTTP status and server payload."""
+
+    def __init__(self, message: str, *, status: int | None = None, detail: Any = None):
+        super().__init__(message, detail=detail)
+        self.status = status
+
+    def to_dict(self) -> dict[str, Any]:
+        out = super().to_dict()
+        if self.status is not None:
+            out["status"] = self.status
+        return out

opcli/hal.py

@@ -0,0 +1,75 @@
+"""Helpers for OpenProject's HAL+JSON representation.
+
+OpenProject resources are HAL documents: attributes live at the top level,
+relationships live under ``_links`` (each a ``{"href": ...}`` or a list of
+them), and embedded resources live under ``_embedded``. Collections put their
+items in ``_embedded.elements`` with ``total``/``count``/``pageSize`` alongside.
+
+These helpers keep that structure out of the command code.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Iterable
+
+Json = dict[str, Any]
+
+
+def link(href: str | None) -> Json:
+    """Build a HAL link object. ``None`` clears a relationship (e.g. unassign)."""
+    return {"href": href}
+
+
+def ref(resource: str, id: Any) -> Json:
+    """Build a link to ``/api/v3/<resource>/<id>`` (the accepted path form)."""
+    return {"href": f"/api/v3/{resource}/{id}"}
+
+
+_ID_RE = re.compile(r"/api/v3/[^/]+/(\d+)(?:/.*)?$")
+
+
+def id_from_href(href: str | None) -> int | None:
+    if not href:
+        return None
+    m = _ID_RE.search(href)
+    return int(m.group(1)) if m else None
+
+
+def link_href(doc: Json, name: str) -> str | None:
+    node = (doc.get("_links") or {}).get(name)
+    if isinstance(node, dict):
+        return node.get("href")
+    return None
+
+
+def link_title(doc: Json, name: str) -> str | None:
+    node = (doc.get("_links") or {}).get(name)
+    if isinstance(node, dict):
+        return node.get("title")
+    return None
+
+
+def link_id(doc: Json, name: str) -> int | None:
+    return id_from_href(link_href(doc, name))
+
+
+def elements(collection: Json) -> list[Json]:
+    return (collection.get("_embedded") or {}).get("elements") or []
+
+
+def total(collection: Json) -> int:
+    return int(collection.get("total") or 0)
+
+
+def formattable(raw: str | None) -> Json:
+    """Wrap text as a Formattable (markdown) value used by description/comment."""
+    return {"raw": raw or ""}
+
+
+def iter_link_list(doc: Json, name: str) -> Iterable[Json]:
+    node = (doc.get("_links") or {}).get(name)
+    if isinstance(node, list):
+        yield from node
+    elif isinstance(node, dict):
+        yield node

opcli/output.py

@@ -0,0 +1,225 @@
+"""Rendering of command results.
+
+The CLI is *agent-first*, so JSON is the default output: stable, complete, and
+trivial to parse. A ``table`` mode (Rich) exists for humans. Commands hand the
+formatter the raw data plus an optional column spec; the formatter decides how
+to present it based on the active ``--output`` mode.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import json as jsonlib
+import sys
+from typing import Any, Callable, Sequence
+
+from rich.console import Console
+from rich.table import Table
+
+# A column is (header, accessor). accessor is a dict key or a callable(row)->value.
+Column = tuple[str, "str | Callable[[dict], Any]"]
+
+_err_console = Console(stderr=True)
+
+
+class OutputFormat(str, enum.Enum):
+    json = "json"
+    table = "table"
+    markdown = "markdown"
+
+    @classmethod
+    def coerce(cls, value: "str | OutputFormat | None") -> "OutputFormat | None":
+        """Parse a loose string (accepts 'md' for markdown). None passes through."""
+        if value is None or isinstance(value, cls):
+            return value
+        v = str(value).strip().lower()
+        if v in ("md", "markdown"):
+            return cls.markdown
+        if v in ("json", "j"):
+            return cls.json
+        if v in ("table", "tbl", "t"):
+            return cls.table
+        raise ValueError(f"unknown output format '{value}' (choose json, table, or markdown)")
+
+
+def _accessor_value(row: dict, accessor: "str | Callable[[dict], Any]") -> Any:
+    if callable(accessor):
+        try:
+            return accessor(row)
+        except Exception:
+            return None
+    return row.get(accessor)
+
+
+def _fmt_cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, (list, tuple)):
+        return ", ".join(str(v) for v in value)
+    return str(value)
+
+
+class Emitter:
+    def __init__(self, fmt: OutputFormat = OutputFormat.json, *, color: bool = True, fields: Sequence[str] | None = None):
+        self.fmt = fmt
+        self.console = Console(no_color=not color, highlight=False)
+        # user-selected fields (dotted paths ok, e.g. "assignee.name"); None = command defaults
+        self.fields = [f.strip() for f in fields if f.strip()] if fields else None
+
+    # ---- main entry --------------------------------------------------
+    def emit(
+        self,
+        data: Any,
+        *,
+        columns: Sequence[Column] | None = None,
+        title: str | None = None,
+        empty: str = "(no results)",
+    ) -> None:
+        if self.fields:
+            # --fields overrides both the JSON shape and the table/markdown columns
+            if self.fmt == OutputFormat.json:
+                self._emit_json(_project(data, self.fields))
+                return
+            columns = [(f, (lambda r, _f=f: _dotted_get(r, _f))) for f in self.fields]
+
+        if self.fmt == OutputFormat.json:
+            self._emit_json(data)
+            return
+        if self.fmt == OutputFormat.markdown:
+            self._emit_markdown(data, columns=columns, title=title, empty=empty)
+            return
+        self._emit_table(data, columns=columns, title=title, empty=empty)
+
+    def message(self, text: str) -> None:
+        """A human status line (table mode only; suppressed in json mode)."""
+        if self.fmt != OutputFormat.json:
+            self.console.print(text)
+
+    # ---- json --------------------------------------------------------
+    def _emit_json(self, data: Any) -> None:
+        sys.stdout.write(jsonlib.dumps(_jsonable(data), indent=2, ensure_ascii=False, default=str))
+        sys.stdout.write("\n")
+
+    # ---- table -------------------------------------------------------
+    def _emit_table(
+        self,
+        data: Any,
+        *,
+        columns: Sequence[Column] | None,
+        title: str | None,
+        empty: str,
+    ) -> None:
+        rows = data if isinstance(data, list) else [data] if isinstance(data, dict) else None
+        if rows is None:
+            self.console.print(str(data))
+            return
+        if not rows:
+            self.console.print(f"[dim]{empty}[/dim]")
+            return
+
+        if columns is None:
+            # key/value table for a single object, else fall back to JSON.
+            if len(rows) == 1 and isinstance(rows[0], dict):
+                self._kv_table(rows[0], title=title)
+                return
+            self._emit_json(data)
+            return
+
+        table = Table(title=title, show_lines=False, header_style="bold")
+        for header, _ in columns:
+            table.add_column(header)
+        for row in rows:
+            table.add_row(*[_fmt_cell(_accessor_value(row, acc)) for _, acc in columns])
+        self.console.print(table)
+
+    # ---- markdown ----------------------------------------------------
+    def _emit_markdown(self, data: Any, *, columns, title, empty) -> None:
+        out = sys.stdout
+        if title:
+            out.write(f"### {title}\n\n")
+        rows = data if isinstance(data, list) else [data] if isinstance(data, dict) else None
+        if rows is None:
+            out.write(f"{data}\n")
+            return
+        if not rows:
+            out.write(f"_{empty}_\n")
+            return
+
+        if columns is not None:
+            headers = [h for h, _ in columns]
+            cells = [[_md_cell(_accessor_value(r, acc)) for _, acc in columns] for r in rows]
+            out.write(_md_table(headers, cells))
+            return
+        if len(rows) == 1 and isinstance(rows[0], dict):
+            # single object -> Field/Value table
+            cells = [[_md_cell(k), _md_cell(v)] for k, v in rows[0].items()]
+            out.write(_md_table(["Field", "Value"], cells))
+            return
+        # list without a column spec -> fenced JSON (still valid markdown)
+        out.write("```json\n")
+        out.write(jsonlib.dumps(_jsonable(data), indent=2, ensure_ascii=False, default=str))
+        out.write("\n```\n")
+
+    def _kv_table(self, obj: dict, *, title: str | None) -> None:
+        table = Table(title=title, show_header=False, box=None)
+        table.add_column("field", style="bold cyan")
+        table.add_column("value")
+        for key, value in obj.items():
+            table.add_row(key, _fmt_cell(value))
+        self.console.print(table)
+
+
+def print_error(err: Any, fmt: OutputFormat) -> None:
+    """Render an error to stderr in the active format."""
+    if fmt == OutputFormat.json:
+        from .errors import OpError
+
+        payload = err.to_dict() if isinstance(err, OpError) else {"error": str(err)}
+        _err_console.file.write(jsonlib.dumps(payload, indent=2, ensure_ascii=False, default=str) + "\n")
+    else:
+        _err_console.print(f"[red]error:[/red] {err}")
+
+
+def _dotted_get(row: Any, path: str) -> Any:
+    """Fetch a possibly-nested value by dotted path, e.g. ``assignee.name``."""
+    cur = row
+    for part in path.split("."):
+        if isinstance(cur, dict):
+            cur = cur.get(part)
+        else:
+            return None
+    return cur
+
+
+def _project(data: Any, fields: Sequence[str]) -> Any:
+    """Keep only the selected fields (dotted paths allowed). The dotted string is
+    used as the output key so the projection is flat and predictable."""
+    if isinstance(data, list):
+        return [{f: _dotted_get(r, f) for f in fields} if isinstance(r, dict) else r for r in data]
+    if isinstance(data, dict):
+        return {f: _dotted_get(data, f) for f in fields}
+    return data
+
+
+def _md_cell(value: Any) -> str:
+    text = _fmt_cell(value)
+    # keep the table one row per record: escape pipes and flatten newlines
+    return text.replace("\\", "\\\\").replace("|", "\\|").replace("\n", "<br>")
+
+
+def _md_table(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> str:
+    lines = ["| " + " | ".join(headers) + " |", "| " + " | ".join("---" for _ in headers) + " |"]
+    for row in rows:
+        lines.append("| " + " | ".join(row) + " |")
+    return "\n".join(lines) + "\n"
+
+
+def _jsonable(obj: Any) -> Any:
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return dataclasses.asdict(obj)
+    if isinstance(obj, enum.Enum):
+        return obj.value
+    return obj