phab-feedback 0.1.0__tar.gz

phab_feedback-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,155 @@
+# 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/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "phab-feedback"
+version = "0.1.0"
+description = "CLI for Phabricator and Phorge review feedback workflows"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Logan Rosen"}]
+keywords = ["phabricator", "phorge", "code-review", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Version Control",
+  "Typing :: Typed",
+]
+
+[project.scripts]
+phab-feedback = "phab_feedback.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/loganrosen/phab-feedback"
+Repository = "https://github.com/loganrosen/phab-feedback"
+Issues = "https://github.com/loganrosen/phab-feedback/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

phab_feedback-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

phab_feedback-0.1.0/src/phab_feedback/__init__.py

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

phab_feedback-0.1.0/src/phab_feedback/__main__.py

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

phab_feedback-0.1.0/src/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