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

opcli/commands/memberships.py

@@ -0,0 +1,110 @@
+"""Project membership commands: list, add, update roles, remove.
+
+A membership links a principal (user/group) to a project with a set of roles.
+The ``roles`` link is an ARRAY that *replaces* the whole role set on write.
+"""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from .. import hal, resolve, serialize
+from ..errors import OpError
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("ID", "id"),
+    ("Principal", lambda r: (r.get("principal") or {}).get("name")),
+    ("Project", lambda r: (r.get("project") or {}).get("name")),
+    ("Roles", "roles"),
+]
+
+
+@app.command("list")
+def list_members(
+    ctx: typer.Context,
+    project: str = typer.Option(None, "--project", "-P", help="Filter by project."),
+    user: str = typer.Option(None, "--user", "-u", help="Filter by principal (login/name/id)."),
+    limit: int = typer.Option(100, "--limit", "-n", help="Maximum rows (0 = all)."),
+) -> None:
+    """List memberships."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    filters = []
+    if project:
+        filters.append({"project": {"operator": "=", "values": [str(resolve.project_id(client, project))]}})
+    if user:
+        href = resolve.user(client, user, project_ref=project)
+        filters.append({"principal": {"operator": "=", "values": [str(hal.id_from_href(href))]}})
+    params = {"filters": json.dumps(filters)} if filters else {}
+    rows = [serialize.membership(m) for m in client.collect("memberships", params=params, limit=limit or None)]
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no memberships)")
+
+
+def _role_hrefs(client, roles: list[str]) -> list[dict]:
+    return [{"href": resolve.role(client, r)} for r in roles]
+
+
+@app.command()
+def add(
+    ctx: typer.Context,
+    project: str = typer.Option(..., "--project", "-P", help="Project id/identifier."),
+    user: str = typer.Option(..., "--user", "-u", help="Principal (login/name/id or 'me')."),
+    role: list[str] = typer.Option(..., "--role", "-r", help="Role name (repeatable)."),
+) -> None:
+    """Add a member to a project with one or more roles.
+
+    Do this before assigning work packages — only project members can be assignees.
+    Example: openproject member add --project webshop --user jane.doe --role Member
+    """
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    pid = resolve.project_id(client, project)
+    principal = resolve.user(client, user, project_ref=project)
+    body = {
+        "_links": {
+            "project": {"href": f"/api/v3/projects/{pid}"},
+            "principal": {"href": principal},
+            "roles": _role_hrefs(client, role),
+        }
+    }
+    obj.emitter.emit(serialize.membership(client.post("memberships", json=body)))
+
+
+@app.command()
+def update(
+    ctx: typer.Context,
+    membership_id: int = typer.Argument(..., help="Membership id."),
+    role: list[str] = typer.Option(..., "--role", "-r", help="New role set (repeatable; replaces all)."),
+) -> None:
+    """Replace a membership's roles."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    body = {"_links": {"roles": _role_hrefs(client, role)}}
+    obj.emitter.emit(serialize.membership(client.patch(f"memberships/{membership_id}", json=body)))
+
+
+@app.command()
+def remove(
+    ctx: typer.Context,
+    membership_id: int = typer.Argument(..., help="Membership id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Remove a membership."""
+    obj = ctx_obj(ctx)
+    if not yes:
+        typer.confirm(f"Remove membership {membership_id}?", abort=True)
+    obj.client().delete(f"memberships/{membership_id}")
+    obj.emitter.emit({"status": "removed", "membership": membership_id})
+
+
+@app.command()
+def roles(ctx: typer.Context) -> None:
+    """List available roles."""
+    obj = ctx_obj(ctx)
+    rows = [{"id": r.get("id"), "name": r.get("name")} for r in obj.client().collect("roles")]
+    obj.emitter.emit(rows, columns=[("ID", "id"), ("Name", "name")])

opcli/commands/notifications.py

@@ -0,0 +1,130 @@
+"""In-app notification commands: list, get, mark read/unread, mark all read.
+
+``readIAN`` is boolean-encoded as the strings ``"t"``/``"f"``. Mark endpoints
+return 204 with an empty body.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+
+import typer
+
+from .. import resolve, serialize
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("ID", "id"),
+    ("Reason", "reason"),
+    ("Read", "readIAN"),
+    ("Subject", "subject"),
+    ("Resource", lambda r: (r.get("resource") or {}).get("name")),
+    ("When", "createdAt"),
+]
+
+
+@app.command("list")
+def list_notifications(
+    ctx: typer.Context,
+    state: str = typer.Option("unread", "--state", help="unread | read | all."),
+    reason: str = typer.Option(None, "--reason", help="mentioned, assigned, watched, ..."),
+    project: str = typer.Option(None, "--project", "-P", help="Filter by project."),
+    today: bool = typer.Option(False, "--today", help="Only notifications created today."),
+    limit: int = typer.Option(50, "--limit", "-n", help="Maximum rows (0 = all)."),
+) -> None:
+    """List your in-app notifications (unread by default)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    filters = _filters(client, state=state, reason=reason, project=project)
+    params = {"sortBy": json.dumps([["id", "desc"]])}
+    if filters:
+        params["filters"] = json.dumps(filters)
+    # `today` isn't a server-side filter for notifications, so scope client-side.
+    fetch_limit = None if today else (limit or None)
+    rows = [serialize.notification(n) for n in client.collect("notifications", params=params, limit=fetch_limit)]
+    if today:
+        prefix = _dt.date.today().isoformat()
+        rows = [r for r in rows if (r.get("createdAt") or "").startswith(prefix)]
+        if limit:
+            rows = rows[:limit]
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no notifications)")
+
+
+def _filters(client, *, state=None, reason=None, project=None) -> list[dict]:
+    filters = []
+    if state == "unread":
+        filters.append({"readIAN": {"operator": "=", "values": ["f"]}})
+    elif state == "read":
+        filters.append({"readIAN": {"operator": "=", "values": ["t"]}})
+    if reason:
+        filters.append({"reason": {"operator": "=", "values": [reason]}})
+    if project:
+        filters.append({"project": {"operator": "=", "values": [str(resolve.project_id(client, project))]}})
+    return filters
+
+
+@app.command()
+def count(
+    ctx: typer.Context,
+    today: bool = typer.Option(False, "--today", help="Also count today's notifications."),
+    project: str = typer.Option(None, "--project", "-P", help="Scope counts to a project."),
+) -> None:
+    """Count notifications (total + unread, and optionally today's)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+
+    def total(filters: list[dict]) -> int:
+        params = {"pageSize": 1}
+        if filters:
+            params["filters"] = json.dumps(filters)
+        return int(client.get("notifications", params=params).get("total", 0))
+
+    proj_filter = _filters(client, project=project)
+    out = {
+        "total": total(proj_filter),
+        "unread": total(_filters(client, state="unread", project=project)),
+    }
+    if today:
+        prefix = _dt.date.today().isoformat()
+        params = {"sortBy": json.dumps([["id", "desc"]])}
+        if proj_filter:
+            params["filters"] = json.dumps(proj_filter)
+        todays = [n for n in client.collect("notifications", params=params, limit=None)
+                  if (n.get("createdAt") or "").startswith(prefix)]
+        out["today"] = len(todays)
+        out["todayUnread"] = sum(1 for n in todays if not n.get("readIAN"))
+    obj.emitter.emit(out)
+
+
+@app.command()
+def get(ctx: typer.Context, notification_id: int = typer.Argument(..., help="Notification id.")) -> None:
+    """Show one notification."""
+    obj = ctx_obj(ctx)
+    obj.emitter.emit(serialize.notification(obj.client().get(f"notifications/{notification_id}")))
+
+
+@app.command()
+def read(ctx: typer.Context, notification_id: int = typer.Argument(..., help="Notification id.")) -> None:
+    """Mark a notification as read."""
+    obj = ctx_obj(ctx)
+    obj.client().post(f"notifications/{notification_id}/read_ian")
+    obj.emitter.emit({"status": "read", "notification": notification_id})
+
+
+@app.command()
+def unread(ctx: typer.Context, notification_id: int = typer.Argument(..., help="Notification id.")) -> None:
+    """Mark a notification as unread."""
+    obj = ctx_obj(ctx)
+    obj.client().post(f"notifications/{notification_id}/unread_ian")
+    obj.emitter.emit({"status": "unread", "notification": notification_id})
+
+
+@app.command("read-all")
+def read_all(ctx: typer.Context) -> None:
+    """Mark all notifications as read."""
+    obj = ctx_obj(ctx)
+    obj.client().post("notifications/read_ian")
+    obj.emitter.emit({"status": "all read"})

opcli/commands/projects.py

@@ -0,0 +1,149 @@
+"""Project commands: list, get, create, update, archive, unarchive, delete."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from .. import hal, resolve, serialize
+from ..errors import OpError
+from ._shared import apply_custom_fields, ctx_obj, set_link
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("ID", "id"),
+    ("Identifier", "identifier"),
+    ("Name", "name"),
+    ("Active", "active"),
+    ("Public", "public"),
+]
+
+
+@app.command("list")
+def list_projects(
+    ctx: typer.Context,
+    active: bool = typer.Option(None, "--active/--archived", help="Filter by active state."),
+    filters: str = typer.Option(None, "--filters", help="Raw OpenProject filters JSON (overrides --active)."),
+    sort: str = typer.Option("name", "--sort", help="Sort column (e.g. name, id, created_at)."),
+    limit: int = typer.Option(None, "--limit", "-n", help="Maximum rows."),
+) -> None:
+    """List projects (active by default include all unless filtered)."""
+    obj = ctx_obj(ctx)
+    params: dict = {"sortBy": json.dumps([[sort, "asc"]])}
+    if filters:
+        params["filters"] = filters
+    elif active is not None:
+        params["filters"] = json.dumps([{"active": {"operator": "=", "values": ["t" if active else "f"]}}])
+    rows = [serialize.project(p) for p in obj.client().collect("projects", params=params, limit=limit)]
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no projects)")
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    project: str = typer.Argument(..., help="Project id or identifier."),
+    raw: bool = typer.Option(False, "--raw", "-r", help="Return the full HAL document."),
+) -> None:
+    """Show a single project."""
+    obj = ctx_obj(ctx)
+    doc = resolve.project(obj.client(), project)
+    obj.emitter.emit(doc if raw else serialize.project(doc))
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Project name."),
+    identifier: str = typer.Option(None, "--identifier", help="URL identifier (auto from name if omitted)."),
+    description: str = typer.Option(None, "--description", "-d", help="Description (markdown)."),
+    parent: str = typer.Option(None, "--parent", help="Parent project id/identifier."),
+    public: bool = typer.Option(False, "--public", help="Make the project public."),
+    custom_fields: str = typer.Option(None, "--custom-fields", help='JSON of customFieldN values.'),
+) -> None:
+    """Create a project."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    body: dict = {"name": name, "public": public}
+    if identifier:
+        body["identifier"] = identifier
+    if description is not None:
+        body["description"] = {"raw": description}
+    if parent:
+        set_link(body, "parent", f"/api/v3/projects/{resolve.project_id(client, parent)}")
+    apply_custom_fields(body, custom_fields)
+    doc = client.post("projects", json=body)
+    obj.emitter.emit(serialize.project(doc))
+
+
+@app.command()
+def update(
+    ctx: typer.Context,
+    project: str = typer.Argument(..., help="Project id or identifier."),
+    name: str = typer.Option(None, "--name", help="New name."),
+    identifier: str = typer.Option(None, "--identifier", help="New identifier."),
+    description: str = typer.Option(None, "--description", "-d", help="New description."),
+    parent: str = typer.Option(None, "--parent", help="New parent id/identifier ('none' to detach)."),
+    public: bool = typer.Option(None, "--public/--private", help="Public flag."),
+    custom_fields: str = typer.Option(None, "--custom-fields", help="JSON of customFieldN values."),
+) -> None:
+    """Update project attributes (no lockVersion needed for projects)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    pid = resolve.project_id(client, project)
+    body: dict = {}
+    if name is not None:
+        body["name"] = name
+    if identifier is not None:
+        body["identifier"] = identifier
+    if description is not None:
+        body["description"] = {"raw": description}
+    if public is not None:
+        body["public"] = public
+    if parent is not None:
+        if parent.lower() == "none":
+            set_link(body, "parent", None)
+        else:
+            set_link(body, "parent", f"/api/v3/projects/{resolve.project_id(client, parent)}")
+    apply_custom_fields(body, custom_fields)
+    if not body:
+        raise OpError("nothing to update — pass at least one field")
+    doc = client.patch(f"projects/{pid}", json=body)
+    obj.emitter.emit(serialize.project(doc))
+
+
+def _set_active(ctx: typer.Context, project: str, active: bool) -> None:
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    pid = resolve.project_id(client, project)
+    doc = client.patch(f"projects/{pid}", json={"active": active})
+    obj.emitter.emit(serialize.project(doc))
+
+
+@app.command()
+def archive(ctx: typer.Context, project: str = typer.Argument(..., help="Project id/identifier.")) -> None:
+    """Archive a project (PATCH active=false)."""
+    _set_active(ctx, project, False)
+
+
+@app.command()
+def unarchive(ctx: typer.Context, project: str = typer.Argument(..., help="Project id/identifier.")) -> None:
+    """Restore an archived project (PATCH active=true)."""
+    _set_active(ctx, project, True)
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    project: str = typer.Argument(..., help="Project id or identifier."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Permanently delete a project (asynchronous on the server)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    pid = resolve.project_id(client, project)
+    if not yes:
+        typer.confirm(f"Delete project {pid}? This cannot be undone.", abort=True)
+    client.delete(f"projects/{pid}")
+    obj.emitter.emit({"status": "delete requested", "project": pid})

opcli/commands/raw.py

@@ -0,0 +1,83 @@
+"""Escape hatch: call any OpenProject API v3 endpoint directly.
+
+Useful for the agent to reach endpoints the typed commands don't wrap yet, and
+for debugging. Paths may be given as ``work_packages/1`` or
+``/api/v3/work_packages/1``. Bodies and query params are passed as JSON.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from ._shared import ctx_obj, parse_json_option
+
+app = typer.Typer(no_args_is_help=True)
+
+
+def _params(param: list[str]) -> dict:
+    out: dict = {}
+    for item in param or []:
+        if "=" not in item:
+            raise typer.BadParameter(f"--param must be key=value, got '{item}'")
+        k, v = item.split("=", 1)
+        out[k] = v
+    return out
+
+
+def _body(data: str | None, data_file: Path | None):
+    if data_file is not None:
+        return parse_json_option(data_file.read_text(), what="--data-file")
+    return parse_json_option(data, what="--data")
+
+
+def _run(ctx: typer.Context, method: str, path: str, param, data, data_file):
+    obj = ctx_obj(ctx)
+    result = obj.client().request(method, path, params=_params(param), json=_body(data, data_file))
+    obj.emitter.emit(result)
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    path: str = typer.Argument(..., help="API path, e.g. work_packages/1 or statuses."),
+    param: list[str] = typer.Option(None, "--param", "-p", help="Query param key=value (repeatable)."),
+) -> None:
+    """GET an endpoint."""
+    _run(ctx, "GET", path, param, None, None)
+
+
+@app.command()
+def post(
+    ctx: typer.Context,
+    path: str = typer.Argument(..., help="API path."),
+    data: str = typer.Option(None, "--data", "-d", help="JSON request body."),
+    data_file: Path = typer.Option(None, "--data-file", help="File containing the JSON body."),
+    param: list[str] = typer.Option(None, "--param", "-p", help="Query param key=value (repeatable)."),
+) -> None:
+    """POST to an endpoint."""
+    _run(ctx, "POST", path, param, data, data_file)
+
+
+@app.command()
+def patch(
+    ctx: typer.Context,
+    path: str = typer.Argument(..., help="API path."),
+    data: str = typer.Option(None, "--data", "-d", help="JSON request body."),
+    data_file: Path = typer.Option(None, "--data-file", help="File containing the JSON body."),
+    param: list[str] = typer.Option(None, "--param", "-p", help="Query param key=value (repeatable)."),
+) -> None:
+    """PATCH an endpoint. For work packages you MUST include the current lockVersion in the body
+    (fetch it with `raw get work_packages/<id>` first) — unlike `wp update`, which handles it."""
+    _run(ctx, "PATCH", path, param, data, data_file)
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    path: str = typer.Argument(..., help="API path."),
+    param: list[str] = typer.Option(None, "--param", "-p", help="Query param key=value (repeatable)."),
+) -> None:
+    """DELETE an endpoint."""
+    _run(ctx, "DELETE", path, param, None, None)