td-ai-tools 1.2.2 → 1.2.3

package/skills/everhour-basecamp-estimates/scripts/update_estimates.py

@@ -1,654 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import subprocess
-import sys
-from dataclasses import dataclass
-from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
-from pathlib import Path
-from typing import Any
-from urllib.error import HTTPError, URLError
-from urllib.parse import quote, urlencode
-from urllib.request import Request, urlopen
-
-SKILL_ROOT = Path(__file__).resolve().parents[1]
-DEFAULT_ENV_FILE = SKILL_ROOT / ".env"
-EVERHOUR_BASE_URL = "https://api.everhour.com"
-TITLE_KEYS = ("title", "name", "content", "text")
-TRAILING_ESTIMATE_RE = re.compile(r"\s+\[(\d+(?:\.\d+)?)h\]$", re.IGNORECASE)
-WHITESPACE_RE = re.compile(r"\s+")
-
-
-@dataclass(frozen=True)
-class TodoItem:
-    id: str
-    title: str
-    api_url: str | None = None
-
-
-@dataclass(frozen=True)
-class MatchPlan:
-    todo: TodoItem
-    hours: Decimal
-    seconds: int
-    everhour_task_id: str
-    everhour_task_name: str
-    new_basecamp_title: str
-
-
-@dataclass(frozen=True)
-class TodoSelection:
-    active: list[TodoItem]
-    skipped_completed: list[TodoItem]
-
-
-class ScriptError(RuntimeError):
-    pass
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        description=(
-            "Update Everhour estimates for tasks matched from a Basecamp todo or "
-            "todolist URL, then append the estimate to the Basecamp todo titles."
-        )
-    )
-    parser.add_argument("basecamp_url", help="Basecamp todo or todolist URL")
-    parser.add_argument(
-        "hours",
-        help="Estimate in hours, or a JSON array of per-task estimates in hours",
-    )
-    parser.add_argument(
-        "--env-file",
-        default=str(DEFAULT_ENV_FILE),
-        help=f"Path to the skill-local .env file (default: {DEFAULT_ENV_FILE})",
-    )
-    parser.add_argument(
-        "--basecamp-bin",
-        default="basecamp",
-        help="Basecamp CLI executable name or path",
-    )
-    parser.add_argument(
-        "--dry-run",
-        action="store_true",
-        help="Print the planned changes without mutating Everhour or Basecamp",
-    )
-    return parser.parse_args()
-
-
-def load_env_file(path: Path) -> dict[str, str]:
-    if not path.exists():
-        raise ScriptError(
-            f"Missing env file: {path}. Copy {SKILL_ROOT / '.env.example'} to "
-            f"{path} and fill in the values."
-        )
-
-    values: dict[str, str] = {}
-    for line in path.read_text(encoding="utf-8").splitlines():
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        if "=" not in stripped:
-            raise ScriptError(f"Invalid line in {path}: {line}")
-        key, raw_value = stripped.split("=", 1)
-        values[key.strip()] = raw_value.strip().strip("'").strip('"')
-
-    for key, value in os.environ.items():
-        if key.startswith("EVERHOUR_"):
-            values[key] = value
-
-    missing = [key for key in ("EVERHOUR_API_KEY", "EVERHOUR_PROJECT_ID") if not values.get(key)]
-    if missing:
-        raise ScriptError(f"Missing required environment values: {', '.join(missing)}")
-
-    return values
-
-
-def parse_hours_to_seconds(raw_hours: str) -> tuple[Decimal, int]:
-    return parse_hours_value(raw_hours)
-
-
-def parse_hours_value(raw_hours: Any) -> tuple[Decimal, int]:
-    if isinstance(raw_hours, bool):
-        raise ScriptError(f"Invalid hours value: {raw_hours}")
-
-    if isinstance(raw_hours, Decimal):
-        hours = raw_hours
-    else:
-        try:
-            hours = Decimal(str(raw_hours))
-        except (InvalidOperation, ValueError) as exc:
-            raise ScriptError(f"Invalid hours value: {raw_hours}") from exc
-
-    if hours <= 0:
-        raise ScriptError("Hours must be greater than zero.")
-
-    seconds = int((hours * Decimal("3600")).quantize(Decimal("1"), rounding=ROUND_HALF_UP))
-    return hours, seconds
-
-
-def parse_hours_input(raw_hours: str, todo_count: int) -> list[tuple[Decimal, int]]:
-    stripped = raw_hours.strip()
-    if stripped.startswith("["):
-        try:
-            values = json.loads(stripped, parse_float=Decimal, parse_int=Decimal)
-        except json.JSONDecodeError as exc:
-            raise ScriptError(f"Invalid hours array: {raw_hours}") from exc
-
-        if not isinstance(values, list):
-            raise ScriptError("Hours array input must decode to a JSON array.")
-        if len(values) != todo_count:
-            raise ScriptError(
-                "Hours array length does not match active Basecamp todo count: "
-                f"expected {todo_count}, got {len(values)}."
-            )
-        return [parse_hours_value(value) for value in values]
-
-    hours, seconds = parse_hours_to_seconds(raw_hours)
-    return [(hours, seconds) for _ in range(todo_count)]
-
-
-def format_hours(hours: Decimal) -> str:
-    rendered = format(hours.normalize(), "f")
-    return rendered.rstrip("0").rstrip(".") if "." in rendered else rendered
-
-
-def strip_estimate_suffix(title: str) -> str:
-    return TRAILING_ESTIMATE_RE.sub("", title).strip()
-
-
-def normalize_title(title: str) -> str:
-    collapsed = WHITESPACE_RE.sub(" ", strip_estimate_suffix(title)).strip()
-    return collapsed.casefold()
-
-
-def build_estimated_title(title: str, hours: Decimal) -> str:
-    return f"{strip_estimate_suffix(title)} [{format_hours(hours)}h]"
-
-
-def run_basecamp_json(basecamp_bin: str, *args: str) -> Any:
-    command = [basecamp_bin, *args, "--agent"]
-    completed = subprocess.run(command, capture_output=True, text=True)
-    if completed.returncode != 0:
-        stderr = completed.stderr.strip()
-        stdout = completed.stdout.strip()
-        raise ScriptError(
-            f"Basecamp command failed: {' '.join(command)}\n"
-            f"{stderr or stdout or 'No output returned.'}"
-        )
-
-    stdout = completed.stdout.strip()
-    if not stdout:
-        raise ScriptError(f"Basecamp command returned no JSON: {' '.join(command)}")
-
-    try:
-        return json.loads(stdout)
-    except json.JSONDecodeError as exc:
-        raise ScriptError(
-            f"Basecamp command returned invalid JSON: {' '.join(command)}\n{stdout}"
-        ) from exc
-
-
-def extract_title(record: dict[str, Any]) -> str:
-    for key in TITLE_KEYS:
-        value = record.get(key)
-        if isinstance(value, str) and value.strip():
-            return value.strip()
-    raise ScriptError(f"Could not determine a title from Basecamp payload: {record}")
-
-
-def extract_api_url(record: dict[str, Any]) -> str | None:
-    value = record.get("url")
-    if isinstance(value, str) and value.strip():
-        return value.strip()
-    return None
-
-
-def extract_todo_objects(payload: Any) -> list[dict[str, Any]]:
-    if isinstance(payload, list):
-        candidates = [item for item in payload if is_todo_like(item)]
-        if candidates:
-            return candidates
-        return []
-
-    if not isinstance(payload, dict):
-        return []
-
-    for key in ("todos", "items", "entries", "records"):
-        value = payload.get(key)
-        if isinstance(value, list):
-            candidates = [item for item in value if is_todo_like(item)]
-            if candidates:
-                return candidates
-
-    for key, value in payload.items():
-        if "todo" in key.lower():
-            candidates = extract_todo_objects(value)
-            if candidates:
-                return candidates
-
-    for value in payload.values():
-        candidates = extract_todo_objects(value)
-        if candidates:
-            return candidates
-
-    return []
-
-
-def is_todo_like(value: Any) -> bool:
-    return (
-        isinstance(value, dict)
-        and "id" in value
-        and any(isinstance(value.get(key), str) and value.get(key).strip() for key in TITLE_KEYS)
-    )
-
-
-def is_todo_completed(record: dict[str, Any]) -> bool:
-    if record.get("completed") is True:
-        return True
-
-    status = record.get("status")
-    if isinstance(status, str) and status.strip().lower() in {"complete", "completed", "done", "closed"}:
-        return True
-
-    for key in ("completedAt", "completed_at", "completedOn", "completed_on"):
-        value = record.get(key)
-        if isinstance(value, str) and value.strip():
-            return True
-
-    return False
-
-
-def load_basecamp_todos(basecamp_bin: str, basecamp_url: str) -> TodoSelection:
-    parsed = run_basecamp_json(basecamp_bin, "url", "parse", basecamp_url)
-    resource_type = str(parsed.get("type", "")).strip().lower()
-    project_id = str(parsed.get("project_id", "")).strip()
-    recording_id = str(parsed.get("recording_id", "")).strip()
-
-    if resource_type in {"todo", "todos"}:
-        payload = run_basecamp_json(basecamp_bin, "todos", "show", basecamp_url)
-        todo = TodoItem(
-            id=str(payload["id"]),
-            title=extract_title(payload),
-            api_url=extract_api_url(payload),
-        )
-        if is_todo_completed(payload):
-            return TodoSelection(active=[], skipped_completed=[todo])
-        return TodoSelection(active=[todo], skipped_completed=[])
-
-    if resource_type in {"todolist", "todolists"}:
-        payload: Any = None
-        todo_objects: list[dict[str, Any]] = []
-        try:
-            payload = run_basecamp_json(basecamp_bin, "todolists", "show", basecamp_url)
-        except ScriptError:
-            payload = None
-
-        if payload is not None:
-            todo_objects = extract_todo_objects(payload)
-
-        # Some Basecamp CLI versions return an empty payload for todolists show even
-        # though the list exists. Fall back to listing todos scoped to the parsed
-        # project and todolist IDs.
-        if not todo_objects and project_id and recording_id:
-            fallback_payload = run_basecamp_json(
-                basecamp_bin,
-                "todos",
-                "list",
-                "--in",
-                project_id,
-                "--todolist",
-                recording_id,
-            )
-            todo_objects = extract_todo_objects(fallback_payload)
-
-        if not todo_objects:
-            raise ScriptError(
-                "The Basecamp todolist payload did not include any todo items. "
-                "Inspect the todolist manually to confirm the CLI output shape."
-            )
-        active: list[TodoItem] = []
-        skipped_completed: list[TodoItem] = []
-        for item in todo_objects:
-            todo = TodoItem(
-                id=str(item["id"]),
-                title=extract_title(item),
-                api_url=extract_api_url(item),
-            )
-            if is_todo_completed(item):
-                skipped_completed.append(todo)
-            else:
-                active.append(todo)
-        return TodoSelection(active=active, skipped_completed=skipped_completed)
-
-    raise ScriptError(
-        f"Unsupported Basecamp URL type: {resource_type or 'unknown'}. "
-        "Use a todo or todolist URL."
-    )
-
-
-class EverhourClient:
-    def __init__(self, api_key: str, project_id: str) -> None:
-        self.api_key = api_key
-        self.project_id = project_id
-        self._open_tasks_by_title: dict[str, list[dict[str, Any]]] | None = None
-
-    def _request(self, method: str, path: str, payload: dict[str, Any] | None = None) -> Any:
-        request = Request(
-            url=f"{EVERHOUR_BASE_URL}{path}",
-            method=method,
-            headers={
-                "Accept": "application/json",
-                "Content-Type": "application/json",
-                "X-Api-Key": self.api_key,
-            },
-            data=None if payload is None else json.dumps(payload).encode("utf-8"),
-        )
-
-        try:
-            with urlopen(request) as response:
-                raw_body = response.read().decode("utf-8")
-        except HTTPError as exc:
-            body = exc.read().decode("utf-8", errors="replace")
-            raise ScriptError(f"Everhour API error {exc.code} for {method} {path}: {body}") from exc
-        except URLError as exc:
-            raise ScriptError(f"Everhour API request failed for {method} {path}: {exc.reason}") from exc
-
-        if not raw_body:
-            return None
-
-        try:
-            return json.loads(raw_body)
-        except json.JSONDecodeError as exc:
-            raise ScriptError(f"Everhour API returned invalid JSON for {method} {path}: {raw_body}") from exc
-
-    def _project_path(self, suffix: str) -> str:
-        return f"/projects/{quote(self.project_id, safe='')}{suffix}"
-
-    def _task_path(self, task_id: str, suffix: str = "") -> str:
-        return f"/tasks/{quote(task_id, safe='')}{suffix}"
-
-    def list_open_tasks(self) -> dict[str, list[dict[str, Any]]]:
-        if self._open_tasks_by_title is not None:
-            return self._open_tasks_by_title
-
-        tasks_by_title: dict[str, list[dict[str, Any]]] = {}
-        page = 1
-        limit = 100
-
-        while True:
-            query = urlencode({"limit": limit, "page": page})
-            tasks = self._request("GET", self._project_path(f"/tasks?{query}"))
-            if not isinstance(tasks, list):
-                raise ScriptError("Everhour project tasks response was not a list.")
-
-            for task in tasks:
-                if not isinstance(task, dict) or "id" not in task:
-                    continue
-                tasks_by_title.setdefault(normalize_title(str(task.get("name", ""))), []).append(task)
-
-            if len(tasks) < limit:
-                break
-            page += 1
-
-        self._open_tasks_by_title = tasks_by_title
-        return tasks_by_title
-
-    def search_tasks(self, title: str) -> list[dict[str, Any]]:
-        query = urlencode(
-            {
-                "query": title,
-                "limit": 100,
-                "searchInClosed": "true",
-            }
-        )
-        tasks = self._request("GET", self._project_path(f"/tasks/search?{query}"))
-        if not isinstance(tasks, list):
-            raise ScriptError("Everhour task search response was not a list.")
-        return [task for task in tasks if isinstance(task, dict)]
-
-    def match_task(self, title: str, source_id: str) -> dict[str, Any]:
-        normalized = normalize_title(title)
-        open_matches = self.list_open_tasks().get(normalized, [])
-        open_match = select_single_task_match(title, open_matches, source_id)
-        if open_match is not None:
-            return open_match
-
-        search_matches = [
-            task
-            for task in self.search_tasks(strip_estimate_suffix(title))
-            if normalize_title(str(task.get("name", ""))) == normalized
-        ]
-        if not search_matches:
-            raise ScriptError(format_missing_match_error(title, self.project_id))
-        search_match = select_single_task_match(title, search_matches, source_id)
-        if search_match is not None:
-            return search_match
-
-        raise ScriptError(format_ambiguous_match_error(title, search_matches, source_id))
-
-    def update_task_estimate(self, task_id: str, total_seconds: int) -> None:
-        self._request(
-            "PUT",
-            self._task_path(task_id, "/estimate"),
-            {"total": total_seconds, "type": "overall"},
-        )
-
-
-def task_matches_source_id(task: dict[str, Any], source_id: str) -> bool:
-    normalized_source_id = str(source_id).strip()
-    if not normalized_source_id:
-        return False
-
-    task_id = str(task.get("id", "")).strip()
-    if task_id == normalized_source_id or task_id.endswith(f":{normalized_source_id}"):
-        return True
-
-    url = str(task.get("url", "")).strip().rstrip("/")
-    return bool(url) and url.endswith(f"/{normalized_source_id}")
-
-
-def select_single_task_match(
-    title: str,
-    tasks: list[dict[str, Any]],
-    source_id: str,
-) -> dict[str, Any] | None:
-    if len(tasks) == 1:
-        return tasks[0]
-    if len(tasks) == 0:
-        return None
-
-    source_matches = [task for task in tasks if task_matches_source_id(task, source_id)]
-    if len(source_matches) == 1:
-        return source_matches[0]
-    if len(source_matches) > 1:
-        raise ScriptError(format_ambiguous_match_error(title, source_matches, source_id))
-    return None
-
-
-def format_ambiguous_match_error(
-    title: str,
-    matches: list[dict[str, Any]],
-    source_id: str,
-) -> str:
-    match_ids = ", ".join(str(task.get("id")) for task in matches)
-    return (
-        f"Ambiguous Everhour matches for '{title}': {match_ids}. "
-        f"None could be uniquely matched to Basecamp todo {source_id}."
-    )
-
-
-def format_missing_match_error(title: str, project_id: str) -> str:
-    return f"No Everhour task match found for Basecamp title '{title}' in project {project_id}."
-
-
-def update_basecamp_title(basecamp_bin: str, todo: TodoItem, title: str) -> None:
-    if not todo.api_url:
-        raise ScriptError(f"Basecamp todo {todo.id} payload did not include an API URL.")
-    current = run_basecamp_json(basecamp_bin, "api", "get", todo.api_url)
-    if not isinstance(current, dict):
-        raise ScriptError(
-            f"Basecamp todo {todo.id} GET did not return a JSON object: {current!r}"
-        )
-    payload = build_basecamp_update_payload(current, title)
-    run_basecamp_json(
-        basecamp_bin,
-        "api",
-        "put",
-        todo.api_url,
-        "-d",
-        json.dumps(payload),
-    )
-
-
-def build_basecamp_update_payload(current: dict[str, Any], title: str) -> dict[str, Any]:
-    # Basecamp's PUT to a todo replaces all writable fields, so any field omitted
-    # here gets cleared. Carry over the assignees, completion subscribers, notes
-    # (description), and dates from the current record so we only change `content`.
-    payload: dict[str, Any] = {"content": title}
-
-    description = current.get("description")
-    if isinstance(description, str) and description:
-        payload["description"] = description
-
-    assignee_ids = _extract_person_ids(current.get("assignees"))
-    if assignee_ids:
-        payload["assignee_ids"] = assignee_ids
-
-    subscriber_ids = _extract_person_ids(current.get("completion_subscribers"))
-    if subscriber_ids:
-        payload["completion_subscriber_ids"] = subscriber_ids
-
-    for key in ("due_on", "starts_on"):
-        value = current.get(key)
-        if isinstance(value, str) and value:
-            payload[key] = value
-
-    return payload
-
-
-def _extract_person_ids(people: Any) -> list[Any]:
-    if not isinstance(people, list):
-        return []
-    ids: list[Any] = []
-    for person in people:
-        if isinstance(person, dict) and "id" in person:
-            ids.append(person["id"])
-    return ids
-
-
-def build_plan(
-    todos: list[TodoItem],
-    estimates: list[tuple[Decimal, int]],
-    everhour: EverhourClient,
-) -> list[MatchPlan]:
-    if len(todos) != len(estimates):
-        raise ScriptError(
-            "Estimate count does not match todo count: "
-            f"expected {len(todos)}, got {len(estimates)}."
-        )
-
-    plans: list[MatchPlan] = []
-    seen_titles: dict[str, TodoItem] = {}
-    seen_task_ids: dict[str, MatchPlan] = {}
-    for todo, (hours, seconds) in zip(todos, estimates):
-        normalized_title = normalize_title(todo.title)
-        prior_todo = seen_titles.get(normalized_title)
-        if prior_todo is not None:
-            raise ScriptError(
-                "Cannot map Basecamp todos one-to-one to Everhour tasks because "
-                f"'{todo.title}' duplicates todo {prior_todo.id} after normalization "
-                f"(conflicts with todo {todo.id})."
-            )
-        seen_titles[normalized_title] = todo
-
-        task = everhour.match_task(todo.title, source_id=todo.id)
-        task_id = str(task.get("id", "")).strip()
-        task_name = str(task.get("name", "")).strip()
-        if not task_id or not task_name:
-            raise ScriptError(f"Everhour task payload missing id or name: {task}")
-        plan = MatchPlan(
-            todo=todo,
-            hours=hours,
-            seconds=seconds,
-            everhour_task_id=task_id,
-            everhour_task_name=task_name,
-            new_basecamp_title=build_estimated_title(todo.title, hours),
-        )
-        prior_plan = seen_task_ids.get(task_id)
-        if prior_plan is not None:
-            raise ScriptError(
-                "Cannot update the same Everhour task for multiple Basecamp todos: "
-                f"todo {prior_plan.todo.id} and todo {todo.id} both matched Everhour "
-                f"task {task_id} ({task_name})."
-            )
-        seen_task_ids[task_id] = plan
-        plans.append(plan)
-    return plans
-
-
-def print_plan(
-    plans: list[MatchPlan],
-    skipped_completed: list[TodoItem],
-    dry_run: bool,
-) -> None:
-    mode = "DRY RUN" if dry_run else "PLAN"
-    distinct_estimates = {(plan.hours, plan.seconds) for plan in plans}
-    if len(distinct_estimates) == 1:
-        hours, seconds = next(iter(distinct_estimates))
-        print(f"{mode}: apply {format_hours(hours)}h ({seconds} seconds) to {len(plans)} task(s)")
-    else:
-        print(f"{mode}: apply per-task estimates to {len(plans)} task(s)")
-    if skipped_completed:
-        print(f"Skipping {len(skipped_completed)} completed Basecamp todo(s):")
-        for todo in skipped_completed:
-            print(f"- Basecamp todo {todo.id}: {todo.title}")
-    for plan in plans:
-        print(
-            f"- Basecamp todo {plan.todo.id}: {plan.todo.title}\n"
-            f"  Everhour task {plan.everhour_task_id}: {plan.everhour_task_name}\n"
-            f"  Estimate: {format_hours(plan.hours)}h ({plan.seconds} seconds)\n"
-            f"  New Basecamp title: {plan.new_basecamp_title}"
-        )
-
-
-def main() -> int:
-    args = parse_args()
-    env = load_env_file(Path(args.env_file))
-    selection = load_basecamp_todos(args.basecamp_bin, args.basecamp_url)
-    if not selection.active:
-        if selection.skipped_completed:
-            raise ScriptError("All matching Basecamp todos are already completed; nothing to update.")
-        raise ScriptError("No Basecamp todos were found for the provided URL.")
-    estimates = parse_hours_input(args.hours, len(selection.active))
-
-    everhour = EverhourClient(
-        api_key=env["EVERHOUR_API_KEY"],
-        project_id=env["EVERHOUR_PROJECT_ID"],
-    )
-    plans = build_plan(selection.active, estimates, everhour)
-    print_plan(plans, selection.skipped_completed, dry_run=args.dry_run)
-
-    if args.dry_run:
-        return 0
-
-    for plan in plans:
-        everhour.update_task_estimate(plan.everhour_task_id, plan.seconds)
-
-    for plan in plans:
-        update_basecamp_title(args.basecamp_bin, plan.todo, plan.new_basecamp_title)
-
-    print("Completed Everhour estimate updates and Basecamp title updates.")
-    return 0
-
-
-if __name__ == "__main__":
-    try:
-        raise SystemExit(main())
-    except ScriptError as exc:
-        print(f"Error: {exc}", file=sys.stderr)
-        raise SystemExit(1)