task: add --only-matching prefilter

Bump version to 0.6.7.

Author: yieldthought

README.md

@@ -79,6 +79,11 @@ Take tasks from a GitHub Project (requires `gh-task`):
 ```bash
 codexapi task -p owner/projects/3 -n "Your Name" -s Ready task_a.yaml task_b.yaml
 ```
+Filter project issues by title before taking them:
+
+```bash
+codexapi task -p owner/projects/3 -n "Your Name" --only-matching "/n300/" task_a.yaml task_b.yaml
+```
 Reset owned tasks on a GitHub Project back to Ready:
 
 ```bash

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codexapi"
-version = "0.6.6"
+version = "0.6.7"
 description = "Minimal Python API for running the Codex CLI."
 readme = "README.md"
 requires-python = ">=3.8"

src/codexapi/__init__.py

@@ -27,4 +27,4 @@
     "task_result",
     "watch",
 ]
-__version__ = "0.6.6"
+__version__ = "0.6.7"

src/codexapi/cli.py

@@ -1106,6 +1106,13 @@ def main(argv=None):
         "--name",
         help="Owner label name for gh-task when using --project.",
     )
+    task_parser.add_argument(
+        "--only-matching",
+        help=(
+            "When using --project, only take issues whose title matches this regex. "
+            "Useful for filtering tasks by hardware encoded in the issue title/path."
+        ),
+    )
     task_parser.add_argument(
         "task_args",
         nargs="*",
@@ -1419,6 +1426,11 @@ def main(argv=None):
             raise SystemExit("--name is required with --project.")
         if not args.task_args:
             raise SystemExit("task --project requires one or more task files.")
+        if args.only_matching is not None:
+            try:
+                re.compile(args.only_matching)
+            except re.error as exc:
+                raise SystemExit(f"--only-matching regex is invalid: {exc}") from None
         from .gh_integration import GhTaskRunner, project_url
         from gh_task.errors import TakeError
 
@@ -1430,6 +1442,7 @@ def main(argv=None):
                         args.name,
                         args.task_args,
                         args.status,
+                        args.only_matching,
                         args.cwd,
                         args.yolo,
                         args.flags,
@@ -1457,6 +1470,7 @@ def main(argv=None):
                     args.name,
                     args.task_args,
                     args.status,
+                    args.only_matching,
                     args.cwd,
                     args.yolo,
                     args.flags,
@@ -1482,6 +1496,8 @@ def main(argv=None):
                 raise SystemExit(
                     "task -f --item requires {{item}} in the task file."
                 )
+        if args.only_matching is not None:
+            raise SystemExit("--only-matching is only supported with --project.")
         if args.check is not None:
             raise SystemExit("--check is not allowed with -f.")
         if args.max_iterations is not None:
@@ -1553,6 +1569,8 @@ def main(argv=None):
             raise SystemExit("--loop is only supported with -p.")
         if args.item is not None:
             raise SystemExit("--item is only supported with -f.")
+        if args.only_matching is not None:
+            raise SystemExit("--only-matching is only supported with --project.")
         if args.max_iterations is None:
             args.max_iterations = DEFAULT_MAX_ITERATIONS
         if args.max_iterations < 0:

src/codexapi/gh_integration.py

@@ -5,6 +5,7 @@
 
 from tqdm import tqdm
 
+from gh_task.errors import TakeError
 from gh_task.project import Project, UPDATE_STATUS_MUTATION
 
 from .taskfile import TaskFile
@@ -138,6 +139,34 @@ def _match_task_file(issue, task_map):
     return matches[0][1]
 
 
+def _take_matching_issue(project, status, only_matching):
+    """Take the first available issue whose title matches only_matching.
+
+    only_matching is a regular expression. When unset/empty, this behaves like
+    Project.take(status=...).
+    """
+    if not only_matching:
+        return project.take(status=status, return_issue=True)
+    try:
+        pattern = re.compile(only_matching)
+    except re.error as exc:
+        raise ValueError(f"Invalid only-matching regex {only_matching!r}: {exc}") from exc
+    status_name = project._resolve_status_name(status)
+    # Filter by title before fetching labels so we don't spam GitHub REST calls for
+    # obviously unsupported issues.
+    for issue in project._list_items():
+        if (issue.status or "").lower() != status_name.lower():
+            continue
+        title = issue.title or ""
+        if not pattern.search(title):
+            continue
+        if not project._issue_matches_label(issue):
+            continue
+        if project._try_take(issue, wait_seconds=1.0, strict=False):
+            return issue
+    raise TakeError(f"No available issues to take in status '{status_name}' matching {only_matching!r}")
+
+
 def _strip_progress_section(body):
     if not body:
         return ""
@@ -275,13 +304,14 @@ def __init__(
         name,
         task_files,
         status="Ready",
+        only_matching=None,
         cwd=None,
         yolo=True,
         flags=None,
     ):
         task_map = _task_file_map(task_files)
         self.project = Project(project, name, has_label=list(task_map))
-        self.issue = self.project.take(status=status, return_issue=True)
+        self.issue = _take_matching_issue(self.project, status, only_matching)
         self.issue = self.project.get_issue(self.issue)
         try:
             task_path = _match_task_file(self.issue, task_map)