phable-cli 0.1.0__tar.gz

phable_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Balthazar Rouberol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

phable_cli-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.3
+Name: phable-cli
+Version: 0.1.0
+Summary: Manage Phabricator tasks from the comfort of your terminal
+License: MIT
+Author: Balthazar Rouberol
+Author-email: br@imap.cc
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: click (>=8.1.8,<9.0.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Description-Content-Type: text/markdown
+
+# phable
+Manage Phabricator tasks from the comfort of your terminal.
+
+`phable` is a CLI allowing you to manage your [Phorge/Phabricator](https://we.forge.it) tasks.
+
+It tries to be very simple and not go overboard with features. You can:
+- create a new task
+- display a task details
+- move a task to a column on its current board
+- assign a task to a user
+- add a comment to a task
+
+## Installation
+
+```console
+$ pip install phable-cli
+```
+
+## Usage
+
+```console
+$ phable --help
+Usage: phable [OPTIONS] COMMAND [ARGS]...
+
+  Manage Phabricator tasks from the comfort of your terminal
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  assign   Assign one or multiple task ids to a username
+  comment  Add a comment to a task
+  create   Create a new task
+  move     Move one or several task on their current project board
+  show     Show task details
+```
+

phable_cli-0.1.0/README.md

@@ -0,0 +1,36 @@
+# phable
+Manage Phabricator tasks from the comfort of your terminal.
+
+`phable` is a CLI allowing you to manage your [Phorge/Phabricator](https://we.forge.it) tasks.
+
+It tries to be very simple and not go overboard with features. You can:
+- create a new task
+- display a task details
+- move a task to a column on its current board
+- assign a task to a user
+- add a comment to a task
+
+## Installation
+
+```console
+$ pip install phable-cli
+```
+
+## Usage
+
+```console
+$ phable --help
+Usage: phable [OPTIONS] COMMAND [ARGS]...
+
+  Manage Phabricator tasks from the comfort of your terminal
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  assign   Assign one or multiple task ids to a username
+  comment  Add a comment to a task
+  create   Create a new task
+  move     Move one or several task on their current project board
+  show     Show task details
+```

phable_cli-0.1.0/phable_cli/cli.py

@@ -0,0 +1,246 @@
+import os
+import json
+
+import click
+
+from .phabricator import PhabricatorClient
+from .utils import text_from_cli_arg_or_fs_or_editor
+
+
+@click.group()
+def cli():
+    """Manage Phabricator tasks from the comfort of your terminal"""
+    pass
+
+
+class Task(int):
+    @classmethod
+    def from_str(cls, value: str) -> int:
+        return int(value.lstrip("T"))
+
+    @classmethod
+    def from_int(cls, value: int) -> str:
+        return f"T{value}"
+
+
+@cli.command(name="show")
+@click.option(
+    "--format",
+    type=click.Choice(("plain", "json")),
+    default="plain",
+    help="Output format",
+)
+@click.argument("task-id", type=Task.from_str)
+def show_task(task_id: int, format: str = "plain"):
+    """Show task details
+
+    \b
+    Examples:
+    $ phable show T123456                 # show task details as plaintext
+    $ phable show T123456  --format=json  # show task details as json
+
+    """
+    client = PhabricatorClient()
+    if task := client.show_task(task_id):
+        author = client.show_user(phid=task["fields"]["authorPHID"])
+        if owner_id := task["fields"]["ownerPHID"]:
+            owner = client.show_user(phid=owner_id)["fields"]["username"]
+        else:
+            owner = "Unassigned"
+        if project_ids := task["attachments"]["projects"]["projectPHIDs"]:
+            tags = [
+                (
+                    f"{project['fields']['parent']['name']} - {project['fields']['name']}"
+                    if project["fields"]["parent"]
+                    else project["fields"]["name"]
+                )
+                for project in client.show_projects(phids=project_ids)
+            ]
+        else:
+            tags = []
+        subtasks = client.find_subtasks(parent_id=task_id)
+        task["subtasks"] = subtasks
+        parent = client.find_parent_task(subtask_id=task_id)
+        task["parent"] = parent
+        if format == "json":
+            click.echo(json.dumps(task))
+        else:
+            parent_str = (
+                f"{Task.from_int(parent['id'])} - {parent['fields']['name']}"
+                if parent
+                else ""
+            )
+            click.echo(f"URL: {client.base_url}/{Task.from_int(task_id)}")
+            click.echo(f"Task: {Task.from_int(task_id)}")
+            click.echo(f"Title: {task['fields']['name']}")
+            click.echo(f"Author: {author['fields']['username']}")
+            click.echo(f"Owner: {owner}")
+            click.echo(f"Tags: {', '.join(tags)}")
+            click.echo(f"Status: {task['fields']['status']['name']}")
+            click.echo(f"Priority: {task['fields']['priority']['name']}")
+            click.echo(f"Description: {task['fields']['description']['raw']}")
+            click.echo(f"Parent: {parent_str}")
+            click.echo("Subtasks:")
+            if subtasks:
+                for subtask in subtasks:
+                    status = f"{'[x]' if subtask['fields']['status']['value'] == 'resolved' else '[ ]'}"
+                    if subtask_owner_id := subtask["fields"]["ownerPHID"]:
+                        owner = client.show_user(subtask_owner_id)["fields"]["username"]
+                    else:
+                        owner = ""
+                    click.echo(
+                        f"{status} - {Task.from_int(subtask['id'])} - @{owner:<10} - {subtask['fields']['name']}"
+                    )
+    else:
+        click.echo(f"Task {Task.from_int(task_id)} not found")
+
+
+@cli.command(name="create")
+@click.option("--title", required=True, help="Title of the task")
+@click.option(
+    "--description",
+    help="Task description or path to a file containing the description body. If not provided, an editor will be opened.",
+)
+@click.option(
+    "--priority",
+    type=click.Choice(["unbreaknow", "high", "normal", "low", "needs-triage"]),
+    help="Priority level of the task",
+    default="normal",
+)
+@click.option("--parent-id", type=int, help="ID of parent task")
+@click.pass_context
+def create_task(
+    ctx,
+    title: str,
+    description: str,
+    priority: str,
+    parent_id: str | None,
+):
+    """Create a new task
+
+    \b
+    Examples:
+    # Create a task with associated title, priority and desription
+    $ phable create --title 'Do the thing!' --priority high --description 'Address the thing right now'
+    \b
+    # Create a task with a given parent
+    $ phable create --title 'A subtask' --description 'Subtask description' --parent-id T123456
+    \b
+    # Create a task with a long description by pointing it to a description file
+    $ phable create --title 'A task' --description path/to/description.txt
+    \b
+    # Create a task with a long description by writing it in your favorite text editor
+    $ phable create --title 'A task'
+    """
+    client = PhabricatorClient()
+    description = text_from_cli_arg_or_fs_or_editor(description)
+    task_params = {
+        "title": title,
+        "description": description,
+        "projects.add": [os.environ["PHABRICATOR_DEFAULT_PROJECT_PHID"]],
+        "priority": priority,
+    }
+    if parent_id:
+        parent = client.show_task(parent_id)
+        task_params["parents.add"] = [parent["phid"]]
+
+    task = client.create_or_edit_task(task_params)
+    ctx.invoke(show_task, task_id=task["result"]["object"]["id"])
+
+
+@cli.command(name="assign")
+@click.option(
+    "--username",
+    required=False,
+    help="The username to assign the task to. Self-assign the task if not provided.",
+)
+@click.argument("task-ids", type=Task.from_str, nargs=-1)
+@click.pass_context
+def assign_task(ctx, task_ids: list[int], username: str | None):
+    """Assign one or multiple task ids to a username
+
+    \b
+    Examples:
+    $ phable assign T123456             # self assign task
+    $ phable assign T123456  brouberol  # asign to username
+
+    """
+    client = PhabricatorClient()
+    if not username:
+        user = client.current_user()
+    else:
+        user = client.find_user_by_username(username)
+        if not user:
+            ctx.fail(f"User {username} was not found")
+    for task_id in task_ids:
+        client.assign_task_to_user(task_id=task_id, user_phid=user["phid"])
+
+
+@cli.command(name="move")
+@click.option(
+    "--column",
+    type=str,
+    required=True,
+    help="Name of destination column on the current project board",
+)
+@click.argument("task-ids", type=Task.from_str, nargs=1)
+@click.pass_context
+def move_task(ctx, task_ids: list[int], column: str | None):
+    """Move one or several task on their current project board
+
+    If the task is moved to a 'Done' column, it will be automatically
+    marked as 'Resolved' as well.
+
+    \b
+    Example:
+    $ phable move T123456 --column 'In Progress'
+    $ phable move T123456 T234567 --column 'Done'
+
+    """
+    client = PhabricatorClient()
+    if not (
+        current_milestone := client.get_project_current_milestone(
+            project_phid=os.environ["PHABRICATOR_DEFAULT_PROJECT_PHID"]
+        )
+    ):
+        ctx.fail("Current milestone not found")
+    current_milestone_columns = client.list_project_columns(
+        project_phid=current_milestone["fields"]["proxyPHID"]
+    )
+    for col in current_milestone_columns:
+        if col["fields"]["name"].lower() == column:
+            column_phid = col["phid"]
+            break
+    else:
+        ctx.fail(
+            f"Column {column} not found in milestone {current_milestone['fields']['name']}"
+        )
+    for task_id in task_ids:
+        client.move_task_to_column(task_id=task_id, column_phid=column_phid)
+        if column["fields"]["name"].lower() == "done":
+            client.mark_task_as_resolved(task_id)
+
+
+@cli.command(name="comment")
+@click.option(
+    "--comment",
+    type=str,
+    help="Comment text or path to a text file containing the comment body. If not provided, an editor will be opened.",
+)
+@click.argument("task-id", type=Task.from_str)
+def comment_on_task(task_id: int, comment: str | None):
+    """Add a comment to a task
+
+    \b
+    Example:
+    $ phable comment T123456 --comment 'hello'              # set comment body from the cli itself
+    $ phable comment T123456 --comment path/to/comment.txt  # set comment body from a text file
+    $ phable comment T123456                                # set comment body from your own text editor
+    """
+    client = PhabricatorClient()
+    comment = text_from_cli_arg_or_fs_or_editor(comment)
+    client.create_or_edit_task(task_id=task_id, params={"comment": comment})
+
+
+if __name__ == "__main__":
+    cli()

phable_cli-0.1.0/phable_cli/phabricator.py

@@ -0,0 +1,164 @@
+import os
+import requests
+
+from typing import Any, TypeVar
+from functools import cache
+
+
+T = TypeVar("T")
+
+
+class PhabricatorClient:
+    """Phabricator API HTTP client.
+
+    See https://phabricator.wikimedia.org/conduit for the API capability and details.
+
+    """
+
+    def __init__(self):
+        self.base_url = os.environ["PHABRICATOR_URL"].rstrip("/")
+        self.token = os.environ["PHABRICATOR_TOKEN"]
+        self.session = requests.Session()
+        self.timeout = 5
+
+        if not self.base_url or not self.token:
+            raise ValueError(
+                "PHABRICATOR_URL and PHABRICATOR_TOKEN must be set in your envionment"
+            )
+
+    def _first(self, result_set: list[T]) -> T:
+        if result_set:
+            return result_set[0]
+
+    def _make_request(
+        self,
+        path: str,
+        params: dict[str, Any] = None,
+        headers: dict[str, str] = None,
+    ) -> dict[str, Any]:
+        """Helper method to make API requests"""
+        headers = headers or {}
+        headers |= {
+            "Content-Type": "application/x-www-form-urlencoded",
+        }
+        params = params or {}
+        data = {}
+        data["api.token"] = self.token
+        data["output"] = "json"
+        data |= params
+
+        try:
+            response = self.session.post(
+                f"{self.base_url}/api/{path}",
+                headers=headers,
+                data=data,
+                timeout=self.timeout,
+            )
+
+            response.raise_for_status()
+            resp_json = response.json()
+            if resp_json["error_code"]:
+                raise Exception(f"API request failed: {resp_json}")
+            return response.json()
+        except requests.RequestException as e:
+            raise Exception(f"API request failed: {str(e)}")
+
+    def create_or_edit_task(
+        self, params: dict[str, Any], task_id: int | None = None
+    ) -> dict[str, Any]:
+        """Create or edit (if a task_id is provided) a Maniphest task."""
+        raw_params = {}
+        for i, (key, value) in enumerate(params.items()):
+            raw_params[f"transactions[{i}][type]"] = key
+            if isinstance(value, list):
+                for j, subvalue in enumerate(value):
+                    raw_params[f"transactions[{i}][value][{j}]"] = subvalue
+            else:
+                raw_params[f"transactions[{i}][value]"] = value
+        if task_id:
+            raw_params["objectIdentifier"] = task_id
+        return self._make_request("maniphest.edit", params=raw_params)
+
+    def show_task(self, task_id: int) -> dict[str, Any]:
+        """Show a Maniphest task"""
+        return self._make_request(
+            "maniphest.search",
+            params={
+                "constraints[ids][0]": task_id,
+                "attachments[subscribers]": "true",
+                "attachments[projects]": "true",
+                "attachments[columns]": "true",
+            },
+        )["result"]["data"][0]
+
+    def find_subtasks(self, parent_id: int) -> list[dict[str, Any]]:
+        """Return details of all Maniphest subtasks of the provided task id"""
+        return self._make_request(
+            "maniphest.search", params={"constraints[parentIDs][0]": parent_id}
+        )["result"]["data"]
+
+    def find_parent_task(self, subtask_id: int) -> dict[str, Any] | None:
+        """Return details of the parent Maniphest task for the provided task id"""
+        return self._first(
+            self._make_request(
+                "maniphest.search", params={"constraints[subtaskIDs][0]": subtask_id}
+            )["result"]["data"]
+        )
+
+    def move_task_to_column(self, task_id: int, column_phid: str) -> dict[str, Any]:
+        """Move the argument task to column of associated column id"""
+        return self.create_or_edit_task(task_id=task_id, params={"column": column_phid})
+
+    def mark_task_as_resolved(self, task_id: int) -> dict[str, Any]:
+        """Set the status of the argument task to Resolved"""
+        return self.create_or_edit_task(task_id=task_id, params={"status": "Resolved"})
+
+    @cache
+    def show_user(self, phid: str) -> dict[str, Any] | None:
+        """Show details of a Maniphest user"""
+        user = self._make_request(
+            "user.search", params={"constraints[phids][0]": phid}
+        )["result"]["data"]
+        return self._first(user)
+
+    def show_projects(self, phids: list[str]) -> dict[str, Any]:
+        """Show details of the provided Maniphest projects"""
+        params = {}
+        for i, phid in enumerate(phids):
+            params[f"constraints[phids][{i}]"] = phid
+        return self._make_request("project.search", params=params)["result"]["data"]
+
+    def current_user(self) -> dict[str, Any]:
+        """Return details of the user associated with the phabricator API token"""
+        return self._make_request("user.whoami")["result"]
+
+    def find_user_by_username(self, username: str) -> dict[str, Any] | None:
+        """Return user details of the user with the provided username"""
+        user = self._make_request(
+            "user.search", params={"constraints[usernames][0]": username}
+        )["result"]["data"]
+        return self._first(user)
+
+    def assign_task_to_user(self, task_id: int, user_phid: int) -> dict[str, Any]:
+        """Set the owner of the argument task to the argument user id"""
+        return self.create_or_edit_task(task_id=task_id, params={"owner": user_phid})
+
+    def list_project_columns(
+        self,
+        project_phid: str,
+    ) -> list[dict[str, Any]]:
+        """Return the details of each column in a given project"""
+        return self._make_request(
+            "project.column.search", params={"constraints[projects][0]": project_phid}
+        )["result"]["data"]
+
+    def get_project_current_milestone(self, project_phid: str) -> dict[str, Any] | None:
+        """Return the first non hidden column associated with a subproject.
+
+        We assume it to be associated with the current milestone.
+
+        """
+        columns = self.list_project_columns(project_phid)
+        for column in columns:
+            if column["fields"]["proxyPHID"] and not column["fields"]["isHidden"]:
+                return column

phable_cli-0.1.0/phable_cli/utils.py

@@ -0,0 +1,28 @@
+import tempfile
+import subprocess
+import os
+from pathlib import Path
+
+
+def text_from_cli_arg_or_fs_or_editor(body_or_path: str) -> str:
+    """Return argument text/file content, or return prompted input text.
+
+    If some argument text is passed, and it matches a file path, return the file content.
+    If it does not match a file path, return the text itself.
+    Finally, if no argument is passed, open an editor and return the text written by the
+    user.
+
+    """
+    try:
+        if body_or_path is not None and (local_file := Path(body_or_path)).exists():
+            return local_file.read_text()
+    except OSError:
+        pass
+
+    if not body_or_path:
+        txt_tmpfile = tempfile.NamedTemporaryFile(
+            encoding="utf-8", mode="w", suffix=".md"
+        )
+        subprocess.run([os.environ["EDITOR"], txt_tmpfile.name])
+        return Path(txt_tmpfile.name).read_text()
+    return body_or_path

phable_cli-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "phable-cli"
+version = "0.1.0"
+description = "Manage Phabricator tasks from the comfort of your terminal"
+authors = ["Balthazar Rouberol <br@imap.cc>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+requests = "^2.32.3"
+click = "^8.1.8"
+
+[tool.poetry.scripts]
+phable = 'phable_cli.cli:cli'
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"