phab-feedback 0.1.0__py3-none-any.whl

phab_feedback/__init__.py

@@ -0,0 +1,3 @@
+"""Phabricator and Phorge feedback workflows."""
+
+__version__ = "0.1.0"

phab_feedback/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

phab_feedback/api.py

@@ -0,0 +1,107 @@
+"""Conduit and internal web API clients."""
+
+from __future__ import annotations
+
+import html
+import json
+import re
+from typing import Any, Mapping
+from urllib.parse import urlencode
+
+from .errors import APIError
+from .transport import Transport
+
+
+class ConduitClient:
+    def __init__(self, host: str, token: str, transport: Transport) -> None:
+        self.host = host
+        self._token = token
+        self._transport = transport
+
+    def call(self, method: str, params: Mapping[str, Any]) -> Any:
+        conduit_params = dict(params)
+        conduit_params["__conduit__"] = {"token": self._token}
+        data = urlencode(
+            {
+                "params": json.dumps(conduit_params, separators=(",", ":")),
+                "output": "json",
+                "__conduit__": "1",
+            }
+        ).encode()
+        response = self._transport.request(
+            "POST",
+            f"{self.host}/api/{method}",
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            data=data,
+        )
+        payload = _json_object(response.body, f"Conduit method {method}")
+        if payload.get("error_code"):
+            code = payload["error_code"]
+            info = str(payload.get("error_info") or "request rejected")
+            info = info.replace(self._token, "[redacted]")
+            raise APIError(f"Conduit {method} failed: {code}: {info}")
+        if "result" not in payload:
+            raise APIError(f"Conduit {method} returned no result")
+        return payload["result"]
+
+
+class WebClient:
+    def __init__(self, host: str, cookie_header: str, transport: Transport) -> None:
+        self.host = host
+        self._cookie_header = cookie_header
+        self._transport = transport
+        self._csrf: str | None = None
+
+    @property
+    def csrf(self) -> str:
+        if self._csrf is None:
+            response = self._transport.request(
+                "GET",
+                self.host,
+                headers={"Cookie": self._cookie_header},
+            )
+            decoded = html.unescape(
+                response.body.decode("utf-8", errors="replace")
+            )
+            patterns = (
+                r'name="__csrf__"\s+value="(B@[A-Za-z0-9]+)"',
+                r'"current":"(B@[A-Za-z0-9]+)"',
+                r'"token":"(B@[A-Za-z0-9]+)"',
+            )
+            for pattern in patterns:
+                match = re.search(pattern, decoded)
+                if match:
+                    self._csrf = match.group(1)
+                    break
+            if self._csrf is None:
+                raise APIError("Could not extract a CSRF token from the host")
+        return self._csrf
+
+    def post(self, path: str, data: Mapping[str, Any]) -> dict[str, Any]:
+        csrf = self.csrf
+        response = self._transport.request(
+            "POST",
+            f"{self.host}{path}",
+            headers={
+                "Cookie": self._cookie_header,
+                "X-Phabricator-Csrf": csrf,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            data=urlencode(data).encode(),
+        )
+        body = re.sub(rb"^for \(;;\);", b"", response.body)
+        payload = _json_object(body, f"Web endpoint {path}")
+        error = payload.get("error")
+        if error:
+            raise APIError(f"Web endpoint {path} failed: {error}")
+        return payload
+
+
+def _json_object(body: bytes, operation: str) -> dict[str, Any]:
+    try:
+        payload = json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise APIError(f"{operation} returned an invalid JSON response") from error
+    if not isinstance(payload, dict):
+        raise APIError(f"{operation} returned an unexpected response")
+    return payload

phab_feedback/cli.py

@@ -0,0 +1,241 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Sequence, TextIO
+
+from .api import ConduitClient, WebClient
+from .config import ConfigResolver
+from .errors import PhabFeedbackError, ValidationError
+from .service import FeedbackService
+from .transport import Transport, UrllibTransport
+
+
+CONDUIT_COMMANDS = {
+    "timeline",
+    "comment",
+    "reply-inline",
+    "remove-comment",
+    "mark-done",
+    "mark-helpful",
+    "mark-unhelpful",
+}
+WEB_COMMANDS = {
+    "reply-inline",
+    "remove-comment",
+    "mark-done",
+    "mark-helpful",
+    "mark-unhelpful",
+    "submit",
+    "request-ai-review",
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="phab-feedback",
+        description="Manage Phabricator and Phorge review feedback",
+    )
+    parser.add_argument("--host", help="Phabricator/Phorge base URL")
+    parser.add_argument(
+        "--config",
+        type=Path,
+        help="Path to config JSON (default: XDG config directory)",
+    )
+    parser.add_argument(
+        "--firefox-cookies",
+        action="store_true",
+        help="Read the web session from a local Firefox profile",
+    )
+    parser.add_argument(
+        "--firefox-profile",
+        type=Path,
+        help="Firefox profile directory (implies --firefox-cookies)",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    timeline = subparsers.add_parser(
+        "timeline", help="Show structured general and inline feedback"
+    )
+    timeline.add_argument("revision")
+
+    comment = subparsers.add_parser(
+        "comment", help="Post an immediate top-level revision comment"
+    )
+    comment.add_argument("revision")
+    _add_message_options(comment)
+
+    reply = subparsers.add_parser(
+        "reply-inline", help="Draft a true reply to an inline comment"
+    )
+    reply.add_argument("revision")
+    reply.add_argument("comment_id")
+    _add_message_options(reply)
+    reply.add_argument(
+        "--submit",
+        action="store_true",
+        help="Explicitly publish the new reply draft immediately",
+    )
+
+    remove = subparsers.add_parser(
+        "remove-comment", help="Remove an accidental top-level comment"
+    )
+    remove.add_argument("revision")
+    remove.add_argument("comment_id")
+
+    done = subparsers.add_parser(
+        "mark-done", help="Mark inline comments Done as drafts"
+    )
+    done.add_argument("revision")
+    done.add_argument("comment_ids", nargs="+")
+
+    submit = subparsers.add_parser(
+        "submit", help="Submit pending draft actions and comments"
+    )
+    submit.add_argument("revision")
+
+    helpful = subparsers.add_parser(
+        "mark-helpful",
+        help="Rate Review Helper feedback helpful (Mozilla only)",
+    )
+    helpful.add_argument("revision")
+    helpful.add_argument("comment_ids", nargs="+")
+
+    unhelpful = subparsers.add_parser(
+        "mark-unhelpful",
+        help="Rate Review Helper feedback unhelpful (Mozilla only)",
+    )
+    unhelpful.add_argument("revision")
+    unhelpful.add_argument("comment_ids", nargs="+")
+
+    request = subparsers.add_parser(
+        "request-ai-review",
+        help="Request a Review Helper AI review (Mozilla only)",
+    )
+    request.add_argument("revision")
+
+    return parser
+
+
+def _add_message_options(parser: argparse.ArgumentParser) -> None:
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--message", help="Message text")
+    group.add_argument(
+        "--message-file",
+        type=Path,
+        help="Read message from a file, or use - for stdin",
+    )
+
+
+def read_message(args: argparse.Namespace, stdin: TextIO) -> str:
+    if args.message is not None:
+        message = args.message
+    elif args.message_file is not None:
+        if str(args.message_file) == "-":
+            message = stdin.read()
+        else:
+            try:
+                message = args.message_file.read_text(encoding="utf-8")
+            except OSError as error:
+                raise ValidationError(
+                    f"Could not read message file: {args.message_file}"
+                ) from error
+    elif not stdin.isatty():
+        message = stdin.read()
+    else:
+        raise ValidationError(
+            "Provide --message, --message-file, or redirected stdin"
+        )
+    if not message.strip():
+        raise ValidationError("Message must not be empty")
+    return message
+
+
+def run(
+    argv: Sequence[str] | None = None,
+    *,
+    stdin: TextIO = sys.stdin,
+    stdout: TextIO = sys.stdout,
+    stderr: TextIO = sys.stderr,
+    resolver: ConfigResolver | None = None,
+    transport: Transport | None = None,
+) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    command = args.command
+    resolver = resolver or ConfigResolver()
+    transport = transport or UrllibTransport()
+    try:
+        credentials = resolver.resolve(
+            cli_host=args.host,
+            config_path=args.config,
+            require_token=command in CONDUIT_COMMANDS,
+            require_cookie=command in WEB_COMMANDS,
+            firefox_cookies=args.firefox_cookies
+            or args.firefox_profile is not None,
+            firefox_profile=args.firefox_profile,
+        )
+        conduit = (
+            ConduitClient(
+                credentials.host,
+                credentials.conduit_token or "",
+                transport,
+            )
+            if command in CONDUIT_COMMANDS
+            else None
+        )
+        web = (
+            WebClient(
+                credentials.host,
+                credentials.cookie_header or "",
+                transport,
+            )
+            if command in WEB_COMMANDS
+            else None
+        )
+        service = FeedbackService(conduit=conduit, web=web)
+
+        if command == "timeline":
+            result = service.timeline(args.revision)
+        elif command == "comment":
+            result = service.post_comment(
+                args.revision, read_message(args, stdin)
+            )
+        elif command == "reply-inline":
+            result = service.draft_inline_reply(
+                args.revision, args.comment_id, read_message(args, stdin)
+            )
+            if args.submit:
+                result["submission"] = service.submit(args.revision)
+        elif command == "remove-comment":
+            result = service.remove_comment(args.revision, args.comment_id)
+        elif command == "mark-done":
+            result = service.mark_done(args.revision, args.comment_ids)
+        elif command == "submit":
+            result = service.submit(args.revision)
+        elif command == "mark-helpful":
+            result = service.rate(
+                args.revision, args.comment_ids, helpful=True
+            )
+        elif command == "mark-unhelpful":
+            result = service.rate(
+                args.revision, args.comment_ids, helpful=False
+            )
+        elif command == "request-ai-review":
+            result = service.request_ai_review(args.revision)
+        else:
+            raise AssertionError(f"Unhandled command: {command}")
+    except PhabFeedbackError as error:
+        print(f"error: {error}", file=stderr)
+        return 1
+    json.dump(result, stdout, indent=2, sort_keys=True)
+    stdout.write("\n")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    return run(argv)

phab_feedback/config.py

@@ -0,0 +1,276 @@
+"""Configuration and credential discovery."""
+
+from __future__ import annotations
+
+import configparser
+import json
+import os
+import shutil
+import sqlite3
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+from urllib.parse import urlsplit
+
+from .errors import ConfigurationError
+
+
+@dataclass(frozen=True)
+class Credentials:
+    host: str
+    conduit_token: str | None = None
+    cookie_header: str | None = None
+
+
+class ConfigResolver:
+    def __init__(
+        self,
+        *,
+        env: Mapping[str, str] | None = None,
+        home: Path | None = None,
+    ) -> None:
+        self.env = dict(os.environ if env is None else env)
+        self.home = Path.home() if home is None else home
+
+    def resolve(
+        self,
+        *,
+        cli_host: str | None,
+        config_path: Path | None,
+        require_token: bool,
+        require_cookie: bool,
+        firefox_cookies: bool,
+        firefox_profile: Path | None,
+    ) -> Credentials:
+        config = self._read_config(config_path)
+        arcrc = self._read_arcrc()
+        host = self._resolve_host(cli_host, config, arcrc)
+        token = self._resolve_token(host, arcrc) if require_token else None
+        cookie = (
+            self._resolve_cookie(
+                host,
+                config,
+                firefox_cookies=firefox_cookies,
+                firefox_profile=firefox_profile,
+            )
+            if require_cookie
+            else None
+        )
+        return Credentials(host=host, conduit_token=token, cookie_header=cookie)
+
+    def _default_config_path(self) -> Path:
+        root = Path(
+            self.env.get("XDG_CONFIG_HOME", self.home / ".config")
+        ).expanduser()
+        return root / "phab-feedback" / "config.json"
+
+    def _read_config(self, path: Path | None) -> dict[str, object]:
+        selected = self._default_config_path() if path is None else path.expanduser()
+        if not selected.exists():
+            if path is not None:
+                raise ConfigurationError(f"Config file not found: {selected}")
+            return {}
+        try:
+            payload = json.loads(selected.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise ConfigurationError(f"Could not read config file: {selected}") from error
+        if not isinstance(payload, dict):
+            raise ConfigurationError("Config file must contain a JSON object")
+        return payload
+
+    def _arcrc_path(self) -> Path:
+        return Path(
+            self.env.get("PHAB_FEEDBACK_ARCRC", self.home / ".arcrc")
+        ).expanduser()
+
+    def _read_arcrc(self) -> dict[str, object]:
+        path = self._arcrc_path()
+        if not path.exists():
+            return {}
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise ConfigurationError(f"Could not read .arcrc: {path}") from error
+        if not isinstance(payload, dict):
+            raise ConfigurationError(".arcrc must contain a JSON object")
+        return payload
+
+    def _resolve_host(
+        self,
+        cli_host: str | None,
+        config: Mapping[str, object],
+        arcrc: Mapping[str, object],
+    ) -> str:
+        configured = cli_host or self.env.get("PHAB_FEEDBACK_HOST")
+        if configured is None:
+            value = config.get("host")
+            configured = value if isinstance(value, str) else None
+        if configured:
+            return normalize_host(configured)
+
+        hosts = arcrc.get("hosts")
+        available = list(hosts) if isinstance(hosts, dict) else []
+        if len(available) == 1:
+            return normalize_host(available[0])
+        if not available:
+            raise ConfigurationError(
+                "No Phabricator host configured; use --host, "
+                "PHAB_FEEDBACK_HOST, or the config file"
+            )
+        raise ConfigurationError(
+            "Multiple .arcrc hosts found; select one with --host or "
+            "PHAB_FEEDBACK_HOST"
+        )
+
+    def _resolve_token(
+        self, host: str, arcrc: Mapping[str, object]
+    ) -> str:
+        token = self.env.get("PHAB_FEEDBACK_TOKEN")
+        if token:
+            return token
+        hosts = arcrc.get("hosts")
+        if isinstance(hosts, dict):
+            for candidate, raw_settings in hosts.items():
+                if normalize_host(candidate) != host or not isinstance(
+                    raw_settings, dict
+                ):
+                    continue
+                value = raw_settings.get("token")
+                if isinstance(value, str) and value:
+                    return value
+        raise ConfigurationError(
+            f"No Conduit token found for {host}; configure .arcrc or "
+            "PHAB_FEEDBACK_TOKEN"
+        )
+
+    def _resolve_cookie(
+        self,
+        host: str,
+        config: Mapping[str, object],
+        *,
+        firefox_cookies: bool,
+        firefox_profile: Path | None,
+    ) -> str:
+        cookie_name = config.get("cookie_name", "phsid")
+        if not isinstance(cookie_name, str) or not cookie_name:
+            raise ConfigurationError("cookie_name must be a non-empty string")
+        raw = self.env.get("PHAB_FEEDBACK_SESSION_COOKIE")
+        if raw:
+            stripped = raw.strip()
+            if stripped.startswith(f"{cookie_name}=") or ";" in stripped:
+                return stripped
+            return f"{cookie_name}={stripped}"
+
+        use_firefox = firefox_cookies or config.get("firefox_cookies") is True
+        configured_profile = config.get("firefox_profile")
+        profile = firefox_profile
+        if profile is None and isinstance(configured_profile, str):
+            profile = Path(configured_profile).expanduser()
+        if use_firefox:
+            return discover_firefox_cookie(
+                hostname=urlsplit(host).hostname or "",
+                cookie_name=cookie_name,
+                profile=profile,
+                home=self.home,
+            )
+        raise ConfigurationError(
+            "This command needs a web session; set "
+            "PHAB_FEEDBACK_SESSION_COOKIE or pass --firefox-cookies"
+        )
+
+
+def normalize_host(host: str) -> str:
+    value = host.strip().rstrip("/")
+    if value.endswith("/api"):
+        value = value[:-4]
+    parsed = urlsplit(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ConfigurationError(
+            "Phabricator host must be an absolute http(s) URL"
+        )
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ConfigurationError(
+            "Phabricator host must not contain credentials, a query, or a fragment"
+        )
+    return f"{parsed.scheme}://{parsed.netloc}{parsed.path.rstrip('/')}"
+
+
+def discover_firefox_cookie(
+    *,
+    hostname: str,
+    cookie_name: str,
+    profile: Path | None,
+    home: Path,
+) -> str:
+    selected = profile or find_firefox_profile(home)
+    if selected is None:
+        raise ConfigurationError("No Firefox profile found")
+    database = selected / "cookies.sqlite"
+    if not database.exists():
+        raise ConfigurationError(f"Firefox cookie database not found: {database}")
+
+    temporary = tempfile.NamedTemporaryFile(suffix=".sqlite", delete=False)
+    temporary.close()
+    copy = Path(temporary.name)
+    try:
+        shutil.copy2(database, copy)
+        with sqlite3.connect(copy) as connection:
+            rows = connection.execute(
+                """
+                SELECT name, value FROM moz_cookies
+                WHERE name IN (?, 'phusr') AND (host = ? OR host = ?)
+                """,
+                (cookie_name, hostname, f".{hostname}"),
+            ).fetchall()
+    except (OSError, sqlite3.Error) as error:
+        raise ConfigurationError("Could not read Firefox cookie database") from error
+    finally:
+        copy.unlink(missing_ok=True)
+
+    values = {str(name): str(value) for name, value in rows}
+    session = values.get(cookie_name)
+    if not session:
+        raise ConfigurationError(
+            f"No {cookie_name} Firefox cookie found for {hostname}"
+        )
+    pairs = [f"{cookie_name}={session}"]
+    if values.get("phusr"):
+        pairs.append(f"phusr={values['phusr']}")
+    return "; ".join(pairs)
+
+
+def find_firefox_profile(home: Path) -> Path | None:
+    roots = [
+        home / "Library" / "Application Support" / "Firefox",
+        home / ".mozilla" / "firefox",
+    ]
+    for root in roots:
+        profiles_ini = root / "profiles.ini"
+        if profiles_ini.exists():
+            parser = configparser.ConfigParser()
+            parser.read(profiles_ini, encoding="utf-8")
+            candidates: list[tuple[bool, Path]] = []
+            for section in parser.sections():
+                if not section.startswith("Profile"):
+                    continue
+                raw_path = parser.get(section, "Path", fallback="")
+                if not raw_path:
+                    continue
+                candidate = Path(raw_path)
+                if parser.getboolean(section, "IsRelative", fallback=True):
+                    candidate = root / candidate
+                candidates.append(
+                    (parser.getboolean(section, "Default", fallback=False), candidate)
+                )
+            for _, candidate in sorted(candidates, reverse=True):
+                if candidate.exists():
+                    return candidate
+        profiles = root / "Profiles"
+        if profiles.exists():
+            matches = sorted(profiles.glob("*.default-release"))
+            matches.extend(sorted(profiles.glob("*.default")))
+            matches.extend(sorted(path for path in profiles.iterdir() if path.is_dir()))
+            if matches:
+                return matches[0]
+    return None

phab_feedback/errors.py

@@ -0,0 +1,21 @@
+"""Public error types."""
+
+
+class PhabFeedbackError(Exception):
+    """Base error suitable for display to CLI users."""
+
+
+class ConfigurationError(PhabFeedbackError):
+    """Configuration or credential resolution failed."""
+
+
+class NetworkError(PhabFeedbackError):
+    """A remote request failed."""
+
+
+class APIError(PhabFeedbackError):
+    """A remote API rejected an operation."""
+
+
+class ValidationError(PhabFeedbackError):
+    """A user-supplied identifier or operation was invalid."""

phab_feedback/service.py

@@ -0,0 +1,407 @@
+"""Feedback timeline and mutation workflows."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Iterable
+
+from .api import ConduitClient, WebClient
+from .errors import APIError, ValidationError
+
+
+def revision_number(revision: str) -> int:
+    value = revision.strip()
+    if value[:1].lower() == "d":
+        value = value[1:]
+    if not value.isdigit() or int(value) < 1:
+        raise ValidationError(f"Invalid revision identifier: {revision}")
+    return int(value)
+
+
+def comment_id(value: str | int) -> int:
+    text = str(value)
+    if not text.isdigit() or int(text) < 1:
+        raise ValidationError(f"Invalid comment ID: {value}")
+    return int(text)
+
+
+def active_comment(transaction: dict[str, Any]) -> dict[str, Any] | None:
+    versions = transaction.get("comments") or []
+    if not isinstance(versions, list) or not versions:
+        return None
+    latest = max(versions, key=lambda item: item.get("version", 0))
+    return None if latest.get("removed") else latest
+
+
+class FeedbackService:
+    def __init__(
+        self,
+        *,
+        conduit: ConduitClient | None = None,
+        web: WebClient | None = None,
+    ) -> None:
+        self.conduit = conduit
+        self.web = web
+
+    def revision_transactions(self, revision: str) -> list[dict[str, Any]]:
+        conduit = self._conduit()
+        identifier = f"D{revision_number(revision)}"
+        transactions: list[dict[str, Any]] = []
+        after: str | None = None
+        while True:
+            params: dict[str, Any] = {
+                "objectIdentifier": identifier,
+                "limit": 100,
+            }
+            if after:
+                params["after"] = after
+            result = conduit.call("transaction.search", params)
+            page = result.get("data", [])
+            if not isinstance(page, list):
+                raise APIError("transaction.search returned invalid data")
+            transactions.extend(page)
+            cursor = result.get("cursor") or {}
+            after = cursor.get("after")
+            if not after:
+                return transactions
+
+    def timeline(self, revision: str) -> dict[str, Any]:
+        conduit = self._conduit()
+        revision_id = revision_number(revision)
+        revisions = conduit.call(
+            "differential.revision.search",
+            {"constraints": {"ids": [revision_id]}},
+        ).get("data", [])
+        if not revisions:
+            raise ValidationError(f"D{revision_id} was not found")
+        current_diff_phid = revisions[0].get("fields", {}).get("diffPHID")
+        if not current_diff_phid:
+            raise APIError(f"D{revision_id} returned no current diff")
+        diffs = conduit.call(
+            "differential.diff.search",
+            {"constraints": {"phids": [current_diff_phid]}},
+        ).get("data", [])
+        if not diffs:
+            raise APIError(f"Current diff for D{revision_id} was not found")
+        current_diff = diffs[0]
+        transactions = self.revision_transactions(revision)
+        by_phid = {
+            version["phid"]: version["id"]
+            for transaction in transactions
+            for version in transaction.get("comments", [])
+            if version.get("phid")
+        }
+
+        general: list[dict[str, Any]] = []
+        inline: list[dict[str, Any]] = []
+        for transaction in transactions:
+            kind = transaction.get("type")
+            if kind not in {"comment", "inline"}:
+                continue
+            comment = active_comment(transaction)
+            if comment is None:
+                continue
+            base = {
+                "kind": "general" if kind == "comment" else "inline",
+                "id": comment.get("id"),
+                "phid": comment.get("phid"),
+                "transaction_id": transaction.get("id"),
+                "transaction_phid": transaction.get("phid"),
+                "created": _timestamp(comment.get("dateCreated")),
+                "content": (comment.get("content") or {}).get("raw"),
+            }
+            if kind == "comment":
+                general.append(base)
+                continue
+            fields = transaction.get("fields") or {}
+            diff = fields.get("diff") or {}
+            parent_phid = fields.get("replyToCommentPHID")
+            inline.append(
+                {
+                    **base,
+                    "diff_id": diff.get("id"),
+                    "diff_phid": diff.get("phid"),
+                    "on_current_diff": diff.get("phid") == current_diff_phid,
+                    "path": fields.get("path"),
+                    "line": fields.get("line"),
+                    "is_done": fields.get("isDone"),
+                    "reply_to_comment_id": by_phid.get(parent_phid),
+                    "reply_to_comment_phid": parent_phid,
+                }
+            )
+        general.sort(key=lambda item: item["created"] or "")
+        inline.sort(key=lambda item: item["created"] or "")
+        events = sorted(
+            [*general, *inline], key=lambda item: item["created"] or ""
+        )
+        return {
+            "revision_id": revision_id,
+            "current_diff": {
+                "id": current_diff.get("id"),
+                "phid": current_diff_phid,
+                "created": _timestamp(
+                    (current_diff.get("fields") or {}).get("dateCreated")
+                ),
+            },
+            "events": events,
+            "general_comments": general,
+            "inline_comments": inline,
+        }
+
+    def post_comment(self, revision: str, message: str) -> dict[str, Any]:
+        revision_id = revision_number(revision)
+        result = self._conduit().call(
+            "differential.revision.edit",
+            {
+                "objectIdentifier": f"D{revision_id}",
+                "transactions": [{"type": "comment", "value": message}],
+            },
+        )
+        return {"revision_id": revision_id, "posted": True, "result": result}
+
+    def reply_inline(
+        self, revision: str, parent_id: str | int
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        return self._find_comment(revision, parent_id, "inline")
+
+    def draft_inline_reply(
+        self, revision: str, parent_id: str | int, message: str
+    ) -> dict[str, Any]:
+        revision_id = revision_number(revision)
+        _, parent = self.reply_inline(revision, parent_id)
+        path = f"/differential/comment/inline/edit/{revision_id}/"
+        content = {
+            "hasContentState": "1",
+            "text": message,
+            "suggestionText": "",
+            "hasSuggestion": "0",
+        }
+        common = {"on_right": "1", "renderer": "2up", "__wflow__": "true", "__ajax__": "true"}
+        created = self._web().post(
+            path,
+            {
+                **common,
+                **content,
+                "op": "reply",
+                "replyToCommentPHID": parent["phid"],
+            },
+        )
+        reply_id = (
+            ((created.get("payload") or {}).get("inline") or {}).get("id")
+        )
+        if not reply_id:
+            raise APIError("Inline reply creation returned no comment ID")
+        self._web().post(
+            path,
+            {**common, **content, "op": "save", "id": str(reply_id)},
+        )
+        return {
+            "revision_id": revision_id,
+            "parent_comment_id": comment_id(parent_id),
+            "parent_comment_phid": parent["phid"],
+            "draft_comment_id": int(reply_id),
+            "draft": True,
+        }
+
+    def remove_comment(
+        self, revision: str, target_id: str | int
+    ) -> dict[str, Any]:
+        revision_id = revision_number(revision)
+        transaction, _ = self._find_comment(revision, target_id, "comment")
+        self._web().post(
+            f"/transactions/edit/{transaction['phid']}/",
+            {"text": "", "__form__": "1", "__ajax__": "true"},
+        )
+        updated = next(
+            (
+                item
+                for item in self.revision_transactions(revision)
+                if item.get("id") == transaction.get("id")
+            ),
+            None,
+        )
+        versions = updated.get("comments", []) if updated else []
+        latest = max(
+            versions,
+            key=lambda item: item.get("version", 0),
+            default=None,
+        )
+        if latest is None or not latest.get("removed"):
+            raise APIError(
+                f"Server did not confirm removal of comment {target_id}"
+            )
+        return {
+            "revision_id": revision_id,
+            "comment_id": comment_id(target_id),
+            "removed": True,
+        }
+
+    def mark_done(
+        self, revision: str, comment_ids: Iterable[str | int]
+    ) -> dict[str, Any]:
+        revision_id = revision_number(revision)
+        ids = self._validate_comments(revision, comment_ids, "inline")
+        path = f"/differential/comment/inline/edit/{revision_id}/"
+        results = []
+        for identifier in ids:
+            response = self._web().post(
+                path,
+                {
+                    "op": "done",
+                    "id": str(identifier),
+                    "__wflow__": "true",
+                    "__ajax__": "true",
+                },
+            )
+            payload = response.get("payload") or {}
+            results.append(
+                {
+                    "comment_id": identifier,
+                    "is_done": bool(payload.get("isChecked")),
+                    "draft": bool(payload.get("draftState")),
+                }
+            )
+        return {"revision_id": revision_id, "comments": results}
+
+    def rate(
+        self,
+        revision: str,
+        comment_ids: Iterable[str | int],
+        *,
+        helpful: bool,
+    ) -> dict[str, Any]:
+        revision_id = revision_number(revision)
+        ids = self._validate_comments(revision, comment_ids, "inline")
+        results = []
+        for identifier in ids:
+            response = self._web().post(
+                "/reviewhelper/feedback/",
+                {
+                    "commentID": str(identifier),
+                    "feedbackType": "up" if helpful else "down",
+                    "__ajax__": "true",
+                },
+            )
+            payload = response.get("payload") or {}
+            results.append(
+                {
+                    "comment_id": identifier,
+                    "helpful": helpful,
+                    "message": payload.get("message"),
+                }
+            )
+        return {
+            "revision_id": revision_id,
+            "mozilla_review_helper": True,
+            "comments": results,
+        }
+
+    def submit(self, revision: str) -> dict[str, Any]:
+        revision_id = revision_number(revision)
+        web = self._web()
+        response = web.post(
+            f"/differential/revision/edit/{revision_id}/comment/",
+            {
+                "__csrf__": web.csrf,
+                "__form__": "1",
+                "editengine.actions": "[]",
+                "comment": "",
+                "comment_metadata": "{}",
+                "__ajax__": "true",
+            },
+        )
+        return {
+            "revision_id": revision_id,
+            "submitted": True,
+            "redirect": (response.get("payload") or {}).get("redirect"),
+        }
+
+    def request_ai_review(self, revision: str) -> dict[str, Any]:
+        revision_id = revision_number(revision)
+        response = self._web().post(
+            f"/reviewhelper/request/{revision_id}/",
+            {"__wflow__": "true", "__ajax__": "true", "__metablock__": "6"},
+        )
+        dialog = str((response.get("payload") or {}).get("dialog", ""))
+        if "successfully" in dialog:
+            status = "requested"
+        elif "being processed" in dialog:
+            status = "already-in-progress"
+        else:
+            status = "response-received"
+        return {
+            "revision_id": revision_id,
+            "mozilla_review_helper": True,
+            "status": status,
+        }
+
+    def _validate_comments(
+        self,
+        revision: str,
+        values: Iterable[str | int],
+        expected_type: str,
+    ) -> list[int]:
+        ids = [comment_id(value) for value in values]
+        if not ids:
+            raise ValidationError("At least one comment ID is required")
+        transactions = self.revision_transactions(revision)
+        by_id: dict[int, dict[str, Any]] = {}
+        for transaction in transactions:
+            for version in transaction.get("comments", []):
+                raw_id = version.get("id")
+                if raw_id is not None:
+                    by_id[int(raw_id)] = transaction
+        for identifier in ids:
+            transaction = by_id.get(identifier)
+            if transaction is None:
+                raise ValidationError(
+                    f"Comment {identifier} was not found on "
+                    f"D{revision_number(revision)}"
+                )
+            actual = transaction.get("type") or "non-comment"
+            if actual != expected_type:
+                raise ValidationError(
+                    f"Comment {identifier} is a {actual} transaction, "
+                    f"not {expected_type}"
+                )
+            if active_comment(transaction) is None:
+                raise ValidationError(f"Comment {identifier} has been removed")
+        return ids
+
+    def _find_comment(
+        self, revision: str, target_id: str | int, expected_type: str
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        identifier = comment_id(target_id)
+        for transaction in self.revision_transactions(revision):
+            versions = transaction.get("comments", [])
+            if not any(int(version.get("id", 0)) == identifier for version in versions):
+                continue
+            actual = transaction.get("type") or "non-comment"
+            if actual != expected_type:
+                raise ValidationError(
+                    f"Comment {identifier} is a {actual} transaction, "
+                    f"not {expected_type}"
+                )
+            comment = active_comment(transaction)
+            if comment is None:
+                raise ValidationError(f"Comment {identifier} has been removed")
+            return transaction, comment
+        raise ValidationError(
+            f"Comment {identifier} was not found on D{revision_number(revision)}"
+        )
+
+    def _conduit(self) -> ConduitClient:
+        if self.conduit is None:
+            raise RuntimeError("Conduit client not configured")
+        return self.conduit
+
+    def _web(self) -> WebClient:
+        if self.web is None:
+            raise RuntimeError("Web client not configured")
+        return self.web
+
+
+def _timestamp(value: Any) -> str | None:
+    if value is None:
+        return None
+    return datetime.fromtimestamp(int(value), timezone.utc).isoformat()

phab_feedback/transport.py

@@ -0,0 +1,62 @@
+"""Minimal HTTP transport with a mockable boundary."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping, Protocol
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlsplit
+from urllib.request import Request, urlopen
+
+from .errors import NetworkError
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    status: int
+    body: bytes
+    headers: Mapping[str, str]
+
+
+class Transport(Protocol):
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        data: bytes | None = None,
+    ) -> HttpResponse: ...
+
+
+class UrllibTransport:
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: Mapping[str, str] | None = None,
+        data: bytes | None = None,
+    ) -> HttpResponse:
+        request = Request(url, data=data, method=method, headers=dict(headers or {}))
+        try:
+            with urlopen(request) as response:
+                return HttpResponse(
+                    status=response.status,
+                    body=response.read(),
+                    headers=dict(response.headers.items()),
+                )
+        except HTTPError as error:
+            raise NetworkError(
+                f"HTTP {error.code} from {_safe_location(url)}"
+            ) from error
+        except URLError as error:
+            reason = getattr(error, "reason", "connection failed")
+            raise NetworkError(
+                f"Request to {_safe_location(url)} failed: {reason}"
+            ) from error
+
+
+def _safe_location(url: str) -> str:
+    parsed = urlsplit(url)
+    return f"{parsed.scheme}://{parsed.netloc}{parsed.path}"

phab_feedback-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: phab-feedback
+Version: 0.1.0
+Summary: CLI for Phabricator and Phorge review feedback workflows
+Author: Logan Rosen
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/loganrosen/phab-feedback
+Project-URL: Repository, https://github.com/loganrosen/phab-feedback
+Project-URL: Issues, https://github.com/loganrosen/phab-feedback/issues
+Keywords: phabricator,phorge,code-review,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# phab-feedback
+
+`phab-feedback` is a small command-line client for reviewing and acting on
+Phabricator and Phorge feedback. It keeps inline replies as real inline-thread
+replies, exposes draft actions explicitly, and produces structured JSON suitable
+for both people and automation.
+
+## How this differs
+
+`arc` and `moz-phab` handle author-side Differential workflows such as creating
+or updating revisions from local commits, with `arc` also providing landing
+workflows. `phabfive` provides broader Conduit-based access to Phabricator and
+Phorge applications such as Maniphest, Paste, Diffusion, Passphrase, and User.
+
+`phab-feedback` complements those tools by focusing on structured Differential
+feedback, inline threads, explicit draft actions, and browser-only mutations
+that Conduit does not expose. Its optional Mozilla Review Helper rating and
+AI-review commands remain isolated from the generic Phabricator and Phorge
+behavior.
+
+## Install
+
+Python 3.10 or newer is required.
+
+After the first PyPI release is published, run the CLI without installing it:
+
+```bash
+uvx phab-feedback --help
+```
+
+For a persistent installation, `uv` is recommended:
+
+```bash
+uv tool install phab-feedback
+phab-feedback --help
+```
+
+`pipx` is an alternative:
+
+```bash
+pipx install phab-feedback
+phab-feedback --help
+```
+
+To try unreleased development from GitHub:
+
+```bash
+uv tool install git+https://github.com/loganrosen/phab-feedback.git
+```
+
+For local source development:
+
+```bash
+git clone https://github.com/loganrosen/phab-feedback.git
+cd phab-feedback
+python3 -m pip install -e .
+python3 -m unittest discover -s tests
+```
+
+## Configuration
+
+Choose a host with `--host`, `PHAB_FEEDBACK_HOST`, or
+`~/.config/phab-feedback/config.json`, in that order:
+
+```json
+{
+  "host": "https://phabricator.example.com",
+  "cookie_name": "phsid"
+}
+```
+
+If no host is configured and `~/.arcrc` contains exactly one host,
+`phab-feedback` uses it. Conduit tokens come from `PHAB_FEEDBACK_TOKEN` or the
+matching `~/.arcrc` entry. Tokens are never accepted as command-line arguments.
+
+Internal web actions need a logged-in browser session. Set
+`PHAB_FEEDBACK_SESSION_COOKIE` to a complete `Cookie` header value, or to the
+value of the configured session cookie. The value is never printed. Mozilla
+Phabricator users can instead pass `--firefox-cookies` to discover the session
+from a local Firefox profile; `--firefox-profile` selects a specific profile.
+
+`XDG_CONFIG_HOME` and `PHAB_FEEDBACK_ARCRC` are respected. The config file is
+for non-secret settings; keep tokens in `.arcrc` or the environment and session
+cookies in the environment or browser store.
+
+## Commands
+
+All successful commands write JSON to stdout. Message-taking commands accept
+exactly one of `--message`, `--message-file PATH`, or `--message-file -`.
+When stdin is redirected, it is also accepted without an option.
+
+```bash
+# Read the complete chronological feedback timeline.
+phab-feedback timeline D123
+
+# Post an immediate top-level revision comment through Conduit.
+phab-feedback comment D123 --message-file reply.txt
+
+# Create a true inline-thread reply draft, then publish it separately.
+printf '%s\n' 'Handled in the latest update.' |
+  phab-feedback reply-inline D123 456
+phab-feedback submit D123
+
+# Explicitly create and publish an inline reply in one invocation.
+phab-feedback reply-inline D123 456 --message 'Done.' --submit
+
+# Remove an accidental top-level comment after validating its type.
+phab-feedback remove-comment D123 789
+
+# Create Done drafts, then submit them.
+phab-feedback mark-done D123 456 457
+phab-feedback submit D123
+```
+
+`timeline`, `comment`, and the metadata validation used by mutations rely on
+standard Conduit APIs. Inline reply drafting, top-level comment removal, Done
+drafting, and draft submission use internal web endpoints available in upstream
+Phabricator and Phorge. Those endpoints are less stable than Conduit and may
+change between server releases.
+
+These commands are **Mozilla-only** because they use the Review Helper
+extension, not upstream Phabricator:
+
+```bash
+phab-feedback mark-helpful D123 456
+phab-feedback mark-unhelpful D123 457
+phab-feedback request-ai-review D123
+```
+
+Helpful and unhelpful ratings take effect immediately. Inline replies and Done
+states remain drafts until `submit`; `reply-inline --submit` is the only
+intentional combined workflow. Rating, Done, and reply actions are never
+combined implicitly.
+
+The repository also includes an optional thin agent skill. It contains workflow
+and approval guidance only; the CLI remains the single implementation of all
+deterministic behavior. Install it through the open Skills CLI:
+
+```bash
+npx skills add loganrosen/phab-feedback@phab-feedback -g
+```
+
+The Skills CLI handles the supported agent-specific installation paths. The
+Python package does not modify agent configuration or install the skill
+automatically.
+
+## Security
+
+Credentials are sent only in request headers or bodies to the configured host.
+Errors omit request bodies, tokens, and cookies. Avoid enabling shell tracing
+while setting credential environment variables.
+
+## License
+
+MIT

phab_feedback-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+phab_feedback/__init__.py,sha256=0TygQdigXXRf_sSl4G0fjbJeRxE8x8VjJyGHIxRnBWw,72
+phab_feedback/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+phab_feedback/api.py,sha256=Cjid6QlBb19a3ZJMMJ5HlqFtTVM0OrKFEJu1pvn3GCs,3775
+phab_feedback/cli.py,sha256=6PH6C9ZR5bChFzDy-MVHIe1Xj1XAMHQ1I-63YYBi790,7415
+phab_feedback/config.py,sha256=QwwSx8-3EzvZJg7usG5PcxGYb1ndjKj-VVzm1N9EoNk,9826
+phab_feedback/errors.py,sha256=eekOfwfXZaGe0XkcFlW-7M49b1qXYoe_EAxHbvOcK2k,490
+phab_feedback/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+phab_feedback/service.py,sha256=TD-Nnm4QDinszaKD95FY8yrQncO87fEkbdl6zwc9SfI,14876
+phab_feedback/transport.py,sha256=5BLeoFKkWVWIcdNBE1VQryA44oct8Zwj8yaVTvsPUoY,1722
+phab_feedback-0.1.0.dist-info/licenses/LICENSE,sha256=jBVfH2xxurzCGKzRu4_XThCqw1gUwAV1EMfsLNoNAGg,1068
+phab_feedback-0.1.0.dist-info/METADATA,sha256=LOFqyV_wVcGjNMW2QKqeosPMRwOQBMa3cZqnrx7MrGg,6302
+phab_feedback-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+phab_feedback-0.1.0.dist-info/entry_points.txt,sha256=6ne9fezYvTVdwflxC6FbkqwdSx5mbPA17WkhkVE03_8,57
+phab_feedback-0.1.0.dist-info/top_level.txt,sha256=D9rAP31Iv_e-2CsBFamVTzEWK4G_OY0y6LbxRqKpHuM,14
+phab_feedback-0.1.0.dist-info/RECORD,,

phab_feedback-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

phab_feedback-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+phab-feedback = phab_feedback.cli:main

phab_feedback-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Logan Rosen
+
+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.

phab_feedback-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+phab_feedback