py-harness-cli 0.3.0__py3-none-any.whl

harness/ship/identity.py

@@ -0,0 +1,62 @@
+"""The GitHub identity python-vibe adds when it is used.
+
+The person who ran the tool stays the commit author. When the harness
+writes a commit or opens a pull request, it adds this account as
+co-author so GitHub shows it on that change. The account is created
+once at github.com/signup; this module only writes the trailer.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+
+CO_AUTHOR_LOGIN = "python-vibe"
+CO_AUTHOR_NAME = "python-vibe"
+# github.com/python-vibe, created 29 Aug 2026. The numbered noreply form
+# is what GitHub links on a Co-authored-by trailer.
+CO_AUTHOR_ID = 322567521
+CO_AUTHOR_EMAIL = f"{CO_AUTHOR_ID}+{CO_AUTHOR_LOGIN}@users.noreply.github.com"
+CO_AUTHOR_URL = "https://github.com/python-vibe"
+# Override only if the account's noreply address changes.
+#   export PYTHON_VIBE_COAUTHOR="python-vibe <322567521+python-vibe@users.noreply.github.com>"
+COAUTHOR_ENV = "PYTHON_VIBE_COAUTHOR"
+
+
+def co_author_line() -> str:
+    """The trailer written on a commit python-vibe made.
+
+    Casing does not decide whether GitHub links it; owning the address
+    does. The default address is the live github.com/python-vibe account.
+    """
+    identity = os.environ.get(COAUTHOR_ENV, "").strip()
+    if identity:
+        return f"Co-authored-by: {identity}"
+    return f"Co-authored-by: {CO_AUTHOR_NAME} <{CO_AUTHOR_EMAIL}>"
+
+
+def co_author_email() -> str:
+    identity = os.environ.get(COAUTHOR_ENV, "").strip()
+    match = re.search(r"<([^>]+)>", identity) if identity else None
+    return match.group(1) if match else CO_AUTHOR_EMAIL
+
+
+def co_author_links() -> bool:
+    """Whether GitHub can turn the trailer into a linked account.
+
+    A `users.noreply.github.com` address links only with the account's
+    numeric id in front of the name. The bare form was issued to older
+    accounts and links only if that account still holds it.
+    """
+    email = co_author_email()
+    if not email.endswith("@users.noreply.github.com"):
+        return "@" in email and "." in email.split("@")[-1]
+    return bool(re.match(r"\d+\+", email))
+
+
+def with_co_author(message: str) -> str:
+    """Append the trailer once, when python-vibe made the commit."""
+    text = message.rstrip()
+    if "co-authored-by: python-vibe" in text.lower():
+        return text
+    return f"{text}\n\n{co_author_line()}\n"

harness/ship/ticket.py

@@ -0,0 +1,251 @@
+"""Turn a GitHub issue or pull request into something to act on.
+
+Reading a ticket is not the same as knowing what to do with it. A ticket
+names files, functions and a list of things to finish, and all three are
+buried in prose. This pulls out the parts that point at code, checks them
+against the project in front of the agent, and quotes comments from other
+GitHub users on the same thread — using the signed-in `gh` user, the same
+account that can see those comments.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+MAX_BODY = 1600
+MAX_ITEMS = 8
+MAX_PEER = 400
+_PATH = re.compile(r"[\w./-]+\.(?:py|pyi|md|toml|yml|yaml|json|cfg|ini)\b")
+_SYMBOL = re.compile(
+    r"`([A-Za-z_]\w*)(?:\(\))?`|\b(?:def|function|class)\s+([A-Za-z_]\w*)"
+)
+_CHECK = re.compile(r"^\s*[-*]\s*\[( |x|X)\]\s*(.+)$", re.MULTILINE)
+_BULLET = re.compile(r"^\s*[-*]\s+(?!\[)(.+)$", re.MULTILINE)
+_DONE_WHEN = re.compile(r"^#+\s*(done when|acceptance|tasks?|todo)\b", re.I | re.MULTILINE)
+
+# github.com/claude comments on tickets when that product is used on a repo.
+# The login is a GitHub username, not a product name in the brief.
+WATCHED_LOGINS = frozenset({"claude", "claude[bot]"})
+
+
+@dataclass(frozen=True)
+class Ticket:
+    """A ticket, and where in this project it points."""
+
+    number: str
+    kind: str
+    title: str
+    body: str = ""
+    state: str = ""
+    files: tuple[str, ...] = ()
+    missing: tuple[str, ...] = ()
+    symbols: tuple[str, ...] = ()
+    todo: tuple[str, ...] = field(default_factory=tuple)
+    job: str = ""
+    viewer: str = ""
+    peers: tuple[tuple[str, str], ...] = ()
+
+
+def named_paths(text: str) -> list[str]:
+    """File paths the text mentions, in order, without repeats."""
+    seen: list[str] = []
+    for hit in _PATH.findall(text):
+        cleaned = hit.strip("./`,;:()[]'\"")
+        if cleaned and cleaned not in seen:
+            seen.append(cleaned)
+    return seen
+
+
+def named_symbols(text: str) -> list[str]:
+    """Functions or classes named in backticks or after def/class."""
+    seen: list[str] = []
+    for backticked, declared in _SYMBOL.findall(text):
+        name = backticked or declared
+        if not name or name in seen or len(name) < 3:
+            continue
+        if "." in name or name.endswith(".py"):
+            continue
+        seen.append(name)
+    return seen
+
+
+def unfinished_items(text: str) -> list[str]:
+    """What the ticket still asks for."""
+    boxes = _CHECK.findall(text)
+    if boxes:
+        return [item.strip() for mark, item in boxes if mark == " "][:MAX_ITEMS]
+    match = _DONE_WHEN.search(text)
+    if not match:
+        return []
+    section = text[match.end() :]
+    end = re.search(r"^#+\s", section, re.MULTILINE)
+    if end:
+        section = section[: end.start()]
+    return [item.strip() for item in _BULLET.findall(section)][:MAX_ITEMS]
+
+
+def ticket_job(text: str) -> str:
+    """Which write skill the ticket body is asking for."""
+    from harness.task import (
+        looks_like_add_feature,
+        looks_like_bugfix,
+        looks_like_fix_smell,
+        looks_like_ops,
+        looks_like_platform,
+        looks_like_write_tests,
+    )
+
+    if looks_like_write_tests(text):
+        return "write-tests"
+    if looks_like_ops(text):
+        return "write-workflow"
+    if looks_like_platform(text):
+        return "write-paths"
+    if looks_like_fix_smell(text):
+        return "fix-smell"
+    if looks_like_bugfix(text):
+        return "bugfix"
+    if looks_like_add_feature(text):
+        return "add-feature"
+    return ""
+
+
+def comments_from(data: dict) -> list[tuple[str, str]]:
+    """(login, body) from gh issue/pr JSON comments and reviews."""
+    found: list[tuple[str, str]] = []
+    blobs: list = []
+    for key in ("comments", "reviews"):
+        raw = data.get(key) or []
+        if isinstance(raw, dict):
+            raw = raw.get("nodes") or raw.get("comments") or []
+        if isinstance(raw, list):
+            blobs.extend(item for item in raw if isinstance(item, dict))
+    for item in blobs:
+        author = item.get("author")
+        if isinstance(author, dict):
+            login = str(author.get("login") or "")
+        else:
+            login = str(author or "")
+        body = str(item.get("body") or "").strip()
+        if login and body:
+            found.append((login, body))
+    return found
+
+
+def identity_from_user_json(payload: str) -> tuple[str, str, str]:
+    """login, name, email from `gh api user` JSON."""
+    try:
+        data = json.loads(payload)
+    except (json.JSONDecodeError, TypeError):
+        return "", "", ""
+    if not isinstance(data, dict):
+        return "", "", ""
+    login = str(data.get("login") or "").strip()
+    name = str(data.get("name") or login or "").strip()
+    email = str(data.get("email") or "").strip()
+    if login and not email:
+        email = f"{login}@users.noreply.github.com"
+    return login, name, email
+
+
+def parse_ticket(
+    payload: str,
+    project: Path,
+    *,
+    kind: str = "issue",
+    viewer: str = "",
+) -> Ticket | None:
+    """Read what `gh ... view --json` returned, and locate it in the project."""
+    try:
+        data = json.loads(payload)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    body = str(data.get("body") or "")
+    title = str(data.get("title") or "")
+    text = f"{title}\n{body}"
+    root = Path(project).resolve()
+    named = named_paths(text)
+    for item in data.get("files") or []:
+        if not isinstance(item, dict):
+            continue
+        rel = str(item.get("path") or item.get("filename") or "").strip()
+        if rel and rel not in named:
+            named.append(rel)
+    here = [rel for rel in named if (root / rel).is_file()]
+    peers = [
+        (login, body[:MAX_PEER])
+        for login, body in comments_from(data)
+        if login.lower() in WATCHED_LOGINS
+    ]
+    return Ticket(
+        number=str(data.get("number") or ""),
+        kind=kind,
+        title=title,
+        body=body[:MAX_BODY],
+        state=str(data.get("state") or ""),
+        files=tuple(here),
+        missing=tuple(rel for rel in named if rel not in here),
+        symbols=tuple(named_symbols(text)),
+        todo=tuple(unfinished_items(body)),
+        job=ticket_job(text),
+        viewer=viewer,
+        peers=tuple(peers),
+    )
+
+
+def next_ticket_action(ticket: Ticket) -> str:
+    """The one Action the 8B should take after reading the ticket."""
+    if ticket.files:
+        return f"Action: read Path: {ticket.files[0]}"
+    if ticket.symbols:
+        return f"Action: locate Query: {ticket.symbols[0]}"
+    words = " ".join(ticket.title.split()[:4]) or "the ask"
+    return f"Action: locate Query: {words}"
+
+
+def render_ticket(ticket: Ticket) -> str:
+    """What the agent is shown: the ask, then where it points."""
+    lines = [f"{ticket.kind} #{ticket.number}: {ticket.title}"]
+    if ticket.state:
+        lines.append(f"state: {ticket.state}")
+    if ticket.viewer:
+        lines.append(f"viewing as @{ticket.viewer} (signed-in gh user)")
+    else:
+        lines.append("viewing as: not signed in to gh")
+    if ticket.job:
+        lines.append(f"Job: {ticket.job}")
+    if ticket.todo:
+        lines.append("")
+        lines.append("Still to do:")
+        lines.extend(f"  - {item}" for item in ticket.todo)
+    if ticket.files:
+        lines.append("")
+        lines.append("Where (files in this project):")
+        lines.extend(f"  {rel}" for rel in ticket.files)
+    if ticket.missing:
+        lines.append("")
+        lines.append(
+            "Named but not here (do not create these blindly): "
+            + ", ".join(ticket.missing[:5])
+        )
+    if ticket.symbols:
+        lines.append("")
+        lines.append("Functions it names: " + ", ".join(ticket.symbols[:8]))
+    if ticket.peers:
+        lines.append("")
+        lines.append("Also on this ticket:")
+        for login, excerpt in ticket.peers:
+            one = " ".join(excerpt.split())
+            lines.append(f"  @{login}: {one}")
+    nxt = next_ticket_action(ticket)
+    lines.append("")
+    lines.append(f"Next: {nxt}")
+    if ticket.body:
+        lines.append("")
+        lines.append(ticket.body)
+    return "\n".join(lines)

harness/skillkit/__init__.py

@@ -0,0 +1,6 @@
+"""Load skills and prepare them for a specific project.
+
+Reads `SKILL.md` files, selects the ones that apply to a task, and replaces
+the file paths inside them with paths that exist in the project being
+worked on.
+"""

harness/skillkit/catalog.py

@@ -0,0 +1,241 @@
+"""Load SKILL.md files. Deterministic. No model.
+
+Looks in the project `skills/` folder and the py-harness kit
+(`<repo>/skills`). Same name: project wins.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from harness.paths import KIT_SKILLS_DIR
+from harness.task import (
+    looks_like_add_feature,
+    looks_like_algorithm,
+    looks_like_analytics,
+    looks_like_design_loop,
+    looks_like_fix_smell,
+    looks_like_http_client,
+    looks_like_app_loop,
+    looks_like_app_overflow,
+    looks_like_new_package,
+    looks_like_ops,
+    looks_like_platform,
+    looks_like_question,
+    looks_like_script,
+    mentions_cli,
+    mentions_http,
+)
+
+_FRONT = re.compile(r"^---\n(.*?)\n---\n(.*)\Z", re.DOTALL)
+_NAME = re.compile(r"^name:\s*(.+)$", re.MULTILINE)
+_DESC = re.compile(r"^description:\s*(.+)$", re.MULTILINE)
+MAX_SKILL_CHARS = 2500
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    body: str
+    path: Path
+
+
+def kit_skills_dir() -> Path:
+    return KIT_SKILLS_DIR
+
+
+def _parse_skill(path: Path) -> Skill | None:
+    text = path.read_text(encoding="utf-8")
+    match = _FRONT.match(text)
+    if not match:
+        return None
+    meta, body = match.group(1), match.group(2).strip()
+    name = _NAME.search(meta)
+    desc = _DESC.search(meta)
+    raw_name = name.group(1).strip() if name else path.parent.name
+    if not raw_name or not desc:
+        return None
+    return Skill(
+        name=raw_name,
+        description=desc.group(1).strip(),
+        body=body,
+        path=path,
+    )
+
+
+def _scan_dir(root: Path) -> dict[str, Skill]:
+    found: dict[str, Skill] = {}
+    if not root.is_dir():
+        return found
+    for skill_md in sorted(root.glob("*/SKILL.md")):
+        parsed = _parse_skill(skill_md)
+        if parsed:
+            found[parsed.name] = parsed
+    return found
+
+
+def list_skills(project: Path | None = None, extra: Path | None = None) -> list[Skill]:
+    merged: dict[str, Skill] = {}
+    merged.update(_scan_dir(kit_skills_dir()))
+    if extra:
+        merged.update(_scan_dir(extra))
+    if project:
+        merged.update(_scan_dir(project.resolve() / "skills"))
+    return sorted(merged.values(), key=lambda item: item.name)
+
+
+def get_skill(name: str, project: Path | None = None) -> Skill | None:
+    key = name.strip().lower()
+    if not key:
+        return None
+    for skill in list_skills(project):
+        if skill.name.lower() == key:
+            return skill
+    return None
+
+
+def skill_from_action(
+    action: str, name: str = "", path: str = "", project: Path | None = None
+) -> Skill | None:
+    """Action: skill + Name:, or Action: write-tests as a shortcut."""
+    if action == "skill":
+        return get_skill(name or path, project)
+    return get_skill(action, project)
+
+
+def pick_skills(task: str, catalog: list[Skill]) -> list[Skill]:
+    picked: list[Skill] = []
+    if looks_like_question(task):
+        picked.extend(s for s in catalog if s.name == "answer-question")
+    from harness.task import (
+        looks_like_merge,
+        looks_like_ship,
+        looks_like_ticket,
+        looks_like_ticket_work,
+    )
+
+    if looks_like_merge(task):
+        picked.extend(s for s in catalog if s.name == "merge-pr")
+        return picked
+    if looks_like_ship(task) and not looks_like_ticket_work(task):
+        picked.extend(s for s in catalog if s.name == "open-pr")
+        return picked
+    if looks_like_ticket(task):
+        picked.extend(s for s in catalog if s.name == "read-issue")
+        if not looks_like_ticket_work(task) and not looks_like_ship(task):
+            return picked
+    if looks_like_new_package(task):
+        picked.extend(s for s in catalog if s.name == "new-package")
+        if looks_like_app_loop(task):
+            picked.extend(s for s in catalog if s.name == "write-cli-app")
+        if mentions_http(task):
+            picked.extend(s for s in catalog if s.name == "call-http")
+        elif mentions_cli(task):
+            picked.extend(s for s in catalog if s.name == "write-script")
+        if mentions_cli(task) or mentions_http(task):
+            picked.extend(s for s in catalog if s.name == "write-tests")
+        return picked
+    if looks_like_app_overflow(task):
+        picked.extend(s for s in catalog if s.name == "write-cli-app")
+        picked.extend(s for s in catalog if s.name == "call-http")
+        picked.extend(s for s in catalog if s.name == "write-tests")
+        return picked
+    if looks_like_fix_smell(task):
+        picked.extend(s for s in catalog if s.name == "fix-smell")
+        return picked
+    if looks_like_design_loop(task):
+        from harness.task import looks_like_review_code, task_paths
+
+        # "review src/app.py" is a review of one file; "review the project
+        # structure" is a review of the tree. The named path decides.
+        if task_paths(task) and looks_like_review_code(task):
+            picked.extend(s for s in catalog if s.name == "review-code")
+            return picked
+        picked.extend(
+            s
+            for s in catalog
+            if s.name in {"review-design", "refactor-split", "readable-layout"}
+        )
+        return picked
+    if looks_like_ops(task):
+        picked.extend(s for s in catalog if s.name == "write-workflow")
+        return picked
+    if looks_like_platform(task):
+        picked.extend(s for s in catalog if s.name == "write-paths")
+        picked.extend(s for s in catalog if s.name == "write-tests")
+        return picked
+    if looks_like_http_client(task):
+        picked.extend(s for s in catalog if s.name == "call-http")
+        picked.extend(s for s in catalog if s.name == "write-tests")
+        return picked
+    if looks_like_analytics(task):
+        picked.extend(s for s in catalog if s.name == "analyze-data")
+        picked.extend(s for s in catalog if s.name == "write-tests")
+        return picked
+    if looks_like_algorithm(task):
+        picked.extend(s for s in catalog if s.name == "write-algorithm")
+        picked.extend(s for s in catalog if s.name == "write-tests")
+        return picked
+    if looks_like_script(task):
+        picked.extend(s for s in catalog if s.name == "write-script")
+        picked.extend(s for s in catalog if s.name == "write-tests")
+        return picked
+    if looks_like_add_feature(task):
+        picked.extend(s for s in catalog if s.name == "add-feature")
+        picked.extend(s for s in catalog if s.name == "write-tests")
+    from harness.task import (
+        looks_like_archive,
+        looks_like_compare,
+        looks_like_review_code,
+        looks_like_walk_files,
+        looks_unclear,
+    )
+
+    # Scripting jobs: the model reaches for the shallow primitive on its own
+    # (os.listdir for "under a folder", a shell call for a zip), so the skill
+    # is what supplies the right one.
+    for matches, skill_name in (
+        (looks_like_archive, "use-archive"),
+        (looks_like_compare, "compare-things"),
+        (looks_like_walk_files, "walk-files"),
+    ):
+        if matches(task) and not any(s.name == skill_name for s in picked):
+            picked.extend(s for s in catalog if s.name == skill_name)
+            break
+
+    if looks_unclear(task):
+        picked.extend(s for s in catalog if s.name == "ask-when-unclear")
+    if looks_like_review_code(task) and not picked:
+        picked.extend(s for s in catalog if s.name == "review-code")
+    lowered = task.strip().lower()
+    if "test" in lowered and not any(s.name == "write-tests" for s in picked):
+        picked.extend(s for s in catalog if s.name == "write-tests")
+    return picked
+
+
+def render_catalog(catalog: list[Skill]) -> str:
+    if not catalog:
+        return "Skills: (none)"
+    lines = ["Skills (Action: skill + Name: …, or --skill):"]
+    for skill in catalog:
+        lines.append(f"  {skill.name} — {skill.description}")
+    return "\n".join(lines)
+
+
+def render_skill(skill: Skill, target=None, project: Path | None = None) -> str:
+    """Render one skill, repointed at `project` when a target is given.
+
+    Without a target the kit paths stay literal, which is only right for the
+    eval fixtures. See harness.skillkit.target.
+    """
+    body = skill.body
+    if target is not None:
+        from harness.skillkit.target import retarget
+
+        body = retarget(body, target, project)
+    if len(body) > MAX_SKILL_CHARS:
+        body = body[:MAX_SKILL_CHARS] + "\n# … skill truncated\n"
+    return f"# skill {skill.name}\n{skill.description}\n\n{body}"