tapps-agents 3.5.39__py3-none-any.whl → 3.5.40__py3-none-any.whl

tapps_agents/beads/hydration.py

@@ -0,0 +1,213 @@
+"""
+Hydration engine: create Beads issues from task specs, update specs from Beads.
+
+Hydrate: for specs without beads_issue, run bd create and save id; recreate
+dependency graph with bd dep add. Dehydrate: run bd list, update spec files
+with current status. Handles missing bd gracefully (log, no crash).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from .client import is_available, run_bd
+from .parse import parse_bd_id_from_stdout
+from .specs import TaskSpec, load_task_specs, save_task_spec
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HydrationReport:
+    """Summary of a hydration run."""
+
+    created: int = 0
+    skipped: int = 0
+    failed: int = 0
+    deps_added: int = 0
+    bd_unavailable: bool = False
+    dry_run: bool = False
+
+
+def hydrate_to_beads(
+    project_root: Path | None = None,
+    *,
+    dry_run: bool = False,
+) -> HydrationReport:
+    """
+    Create Beads issues for task specs that don't have beads_issue; recreate deps.
+
+    For each spec in .tapps-agents/task-specs/ without beads_issue, runs
+    bd create and stores the returned id in the spec file. Then runs
+    bd dep add for each dependency. If bd is not available, logs and returns
+    without raising.
+
+    Args:
+        project_root: Project root (default: cwd).
+        dry_run: If True, do not run bd or write files; report what would be done.
+
+    Returns:
+        HydrationReport with created/skipped/failed/deps_added counts.
+    """
+    project_root = project_root or Path.cwd()
+    report = HydrationReport(dry_run=dry_run)
+
+    if not is_available(project_root):
+        logger.warning("Hydration skipped: bd not available")
+        report.bd_unavailable = True
+        return report
+
+    specs = load_task_specs(project_root)
+    if not specs:
+        return report
+
+    # Map spec.id -> beads_issue id after creation
+    spec_to_bd: dict[str, str] = {}
+    for spec in specs:
+        if spec.beads_issue:
+            spec_to_bd[spec.id] = spec.beads_issue
+            report.skipped += 1
+            continue
+        if dry_run:
+            report.created += 1
+            continue
+        title = (spec.title or spec.id)[:200].strip()
+        desc = (spec.description or "")[:500].replace("\n", " ").strip()
+        args = ["create", title]
+        if desc:
+            args.extend(["-d", desc])
+        try:
+            r = run_bd(project_root, args)
+            if r.returncode != 0:
+                logger.warning("Hydration: bd create failed for %s: %s", spec.id, r.stderr)
+                report.failed += 1
+                continue
+            bd_id = parse_bd_id_from_stdout(r.stdout)
+            if bd_id:
+                spec_to_bd[spec.id] = bd_id
+                spec.beads_issue = bd_id
+                save_task_spec(spec, project_root)
+                report.created += 1
+            else:
+                logger.warning("Hydration: could not parse bd id for %s", spec.id)
+                report.failed += 1
+        except Exception as e:
+            logger.warning("Hydration: bd create failed for %s: %s", spec.id, e)
+            report.failed += 1
+
+    # Recreate dependency graph: bd dep add child parent (parent blocks child)
+    if dry_run:
+        for spec in specs:
+            if spec.dependencies and spec_to_bd.get(spec.id):
+                report.deps_added += len([d for d in spec.dependencies if spec_to_bd.get(d)])
+        return report
+
+    for spec in specs:
+        child_bd = spec_to_bd.get(spec.id)
+        if not child_bd or not spec.dependencies:
+            continue
+        for dep_id in spec.dependencies:
+            parent_bd = spec_to_bd.get(dep_id)
+            if not parent_bd:
+                continue
+            try:
+                r = run_bd(project_root, ["dep", "add", child_bd, parent_bd])
+                if r.returncode == 0:
+                    report.deps_added += 1
+                else:
+                    logger.warning(
+                        "Hydration: bd dep add %s %s failed: %s",
+                        child_bd,
+                        parent_bd,
+                        r.stderr,
+                    )
+            except Exception as e:
+                logger.warning("Hydration: bd dep add %s %s failed: %s", child_bd, parent_bd, e)
+
+    return report
+
+
+def dehydrate_from_beads(project_root: Path | None = None) -> int:
+    """
+    Update task spec files with current status from Beads.
+
+    Runs bd list (or equivalent), maps beads_issue id to status, and updates
+    each spec file. If bd is not available, logs and returns 0.
+
+    Args:
+        project_root: Project root (default: cwd).
+
+    Returns:
+        Number of spec files updated.
+    """
+    project_root = project_root or Path.cwd()
+
+    if not is_available(project_root):
+        logger.warning("Dehydration skipped: bd not available")
+        return 0
+
+    # Try bd list --json; fallback to parsing stdout if format differs
+    try:
+        r = run_bd(project_root, ["list", "--json"])
+    except Exception as e:
+        logger.warning("Dehydration: bd list failed: %s", e)
+        return 0
+
+    if r.returncode != 0:
+        logger.warning("Dehydration: bd list failed: %s", r.stderr)
+        return 0
+
+    bd_status_by_id: dict[str, str] = {}
+    try:
+        raw = json.loads(r.stdout or "[]")
+        if isinstance(raw, list):
+            for item in raw:
+                if isinstance(item, dict):
+                    bid = item.get("id") or item.get("bd_id") or item.get("issue_id")
+                    status = item.get("status") or item.get("state") or "todo"
+                    if bid:
+                        bd_status_by_id[str(bid)] = str(status).lower()
+        elif isinstance(raw, dict):
+            for bid, info in raw.items():
+                if isinstance(info, dict):
+                    status = info.get("status") or info.get("state") or "todo"
+                else:
+                    status = str(info)
+                bd_status_by_id[str(bid)] = str(status).lower()
+    except json.JSONDecodeError:
+        # Fallback: parse line-based output for "id status" or "id\tstatus"
+        for line in (r.stdout or "").splitlines():
+            parts = line.strip().split()
+            if len(parts) >= 2:
+                bd_status_by_id[parts[0]] = parts[1].lower()
+            elif len(parts) == 1:
+                bd_status_by_id[parts[0]] = "todo"
+
+    specs = load_task_specs(project_root)
+    updated = 0
+    for spec in specs:
+        if not spec.beads_issue:
+            continue
+        new_status = bd_status_by_id.get(spec.beads_issue)
+        if not new_status:
+            continue
+        # Map bd status to our status if needed
+        if new_status in ("todo", "open", "pending"):
+            mapped = "todo"
+        elif new_status in ("in-progress", "in_progress", "wip"):
+            mapped = "in-progress"
+        elif new_status in ("done", "closed", "completed"):
+            mapped = "done"
+        elif new_status == "blocked":
+            mapped = "blocked"
+        else:
+            mapped = spec.status
+        if spec.status != mapped:
+            spec = spec.model_copy(update={"status": mapped})
+            save_task_spec(spec, project_root)
+            updated += 1
+
+    return updated

tapps_agents/beads/specs.py

@@ -0,0 +1,206 @@
+"""
+Task specification schema and loader.
+
+Loads and saves task specification YAML files from .tapps-agents/task-specs/
+with validation. Supports hydration/dehydration pattern for multi-session workflows.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Literal
+
+import yaml
+
+logger = logging.getLogger(__name__)
+from pydantic import BaseModel, Field, field_validator
+
+
+class TaskSpec(BaseModel):
+    """Task specification schema for .tapps-agents/task-specs/ YAML files."""
+
+    id: str = Field(..., min_length=1, description="Unique task ID (e.g. enh-002-s1)")
+    title: str = Field(..., min_length=1, description="Task title")
+    description: str = Field(default="", description="Task description")
+    type: Literal["story", "epic", "task"] = Field(
+        default="story",
+        description="Task type",
+    )
+    priority: int = Field(default=0, ge=0, description="Priority (0=highest)")
+    story_points: int | None = Field(default=None, ge=0, description="Story points estimate")
+    epic: str | None = Field(default=None, description="Epic ID this task belongs to")
+    dependencies: list[str] = Field(
+        default_factory=list,
+        description="IDs of tasks this depends on",
+    )
+    github_issue: str | int | None = Field(default=None, description="GitHub issue number or ID")
+    beads_issue: str | None = Field(default=None, description="Beads issue ID (populated after create)")
+    status: Literal["todo", "in-progress", "done", "blocked"] = Field(
+        default="todo",
+        description="Current status",
+    )
+    workflow: str | None = Field(
+        default=None,
+        description="Workflow to run (build, fix, review, test, full)",
+    )
+    files: list[str] = Field(default_factory=list, description="Files or paths affected")
+    tests: list[str] = Field(default_factory=list, description="Test paths")
+
+    model_config = {"extra": "forbid"}
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def id_stripped(cls, v: object) -> str:
+        """Strip whitespace from id."""
+        if isinstance(v, str):
+            return v.strip()
+        return str(v)
+
+
+def _task_specs_dir(project_root: Path) -> Path:
+    """Return path to .tapps-agents/task-specs/."""
+    return project_root / ".tapps-agents" / "task-specs"
+
+
+def load_task_specs(project_root: Path | None = None) -> list[TaskSpec]:
+    """
+    Load all task specs from .tapps-agents/task-specs/.
+
+    Scans the directory for YAML files, parses valid ones, and returns a list
+    of validated TaskSpec. Validation errors are reported with file/field;
+    invalid files are skipped (not raised).
+
+    Args:
+        project_root: Project root (default: cwd).
+
+    Returns:
+        List of successfully loaded TaskSpec. Empty if directory missing or no valid files.
+    """
+    project_root = project_root or Path.cwd()
+    specs_dir = _task_specs_dir(project_root)
+    if not specs_dir.exists():
+        return []
+
+    result: list[TaskSpec] = []
+    for path in sorted(specs_dir.glob("*.yaml")):
+        try:
+            spec = _load_single_spec(path)
+            if spec:
+                result.append(spec)
+        except Exception as e:
+            logger.warning("Task spec validation failed %s: %s", path, e)
+            continue
+    return result
+
+
+def _load_single_spec(path: Path) -> TaskSpec | None:
+    """Load and validate a single task spec file."""
+    content = path.read_text(encoding="utf-8")
+    raw = yaml.safe_load(content)
+    if raw is None:
+        return None
+
+    if not isinstance(raw, dict):
+        raise ValueError(f"Expected YAML object at {path}, got {type(raw).__name__}")
+
+    # Support both top-level "task" key and flat structure
+    data = raw.get("task", raw)
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected task object at {path}")
+
+    return TaskSpec.model_validate(data)
+
+
+def load_task_spec(
+    spec_id: str,
+    project_root: Path | None = None,
+) -> TaskSpec | None:
+    """
+    Load a single task spec by ID.
+
+    Searches .tapps-agents/task-specs/ for a file containing the given id.
+    Naming convention: <epic-id>-<story-id>.yaml (e.g. enh-002-s1.yaml).
+
+    Args:
+        spec_id: Task ID (e.g. enh-002-s1).
+        project_root: Project root (default: cwd).
+
+    Returns:
+        TaskSpec if found and valid, else None.
+    """
+    project_root = project_root or Path.cwd()
+    specs_dir = _task_specs_dir(project_root)
+    if not specs_dir.exists():
+        return None
+
+    # Try direct filename: spec_id.yaml
+    candidate = specs_dir / f"{spec_id}.yaml"
+    if candidate.exists():
+        try:
+            return _load_single_spec(candidate)
+        except Exception:
+            return None
+
+    # Scan files for matching id
+    for path in specs_dir.glob("*.yaml"):
+        try:
+            spec = _load_single_spec(path)
+            if spec and spec.id == spec_id:
+                return spec
+        except Exception:
+            continue
+    return None
+
+
+def save_task_spec(
+    spec: TaskSpec,
+    project_root: Path | None = None,
+) -> Path:
+    """
+    Save task spec to .tapps-agents/task-specs/.
+
+    Uses naming convention <epic-id>-<story-id>.yaml when epic can be derived,
+    otherwise <spec.id>.yaml. Creates directory if needed.
+
+    Args:
+        spec: TaskSpec to save.
+        project_root: Project root (default: cwd).
+
+    Returns:
+        Path where spec was written.
+
+    Raises:
+        ValueError: On validation failure (should not occur for valid TaskSpec).
+    """
+    project_root = project_root or Path.cwd()
+    specs_dir = _task_specs_dir(project_root)
+    specs_dir.mkdir(parents=True, exist_ok=True)
+
+    # Naming: epic-id-story-id or spec.id
+    filename = f"{spec.id}.yaml"
+    out_path = specs_dir / filename
+
+    payload = {"task": spec.model_dump()}
+    out_path.write_text(
+        yaml.dump(payload, default_flow_style=False, sort_keys=False, allow_unicode=True),
+        encoding="utf-8",
+    )
+    return out_path
+
+
+def validate_task_spec_file(path: Path) -> tuple[TaskSpec | None, str | None]:
+    """
+    Validate a task spec file without loading into global list.
+
+    Args:
+        path: Path to YAML file.
+
+    Returns:
+        (TaskSpec, None) if valid, (None, error_message) if invalid.
+    """
+    try:
+        spec = _load_single_spec(path)
+        return (spec, None)
+    except Exception as e:
+        return (None, f"{path}: {e}")

tapps_agents/cli/commands/health.py

@@ -5,6 +5,7 @@ Health command handlers.
 from __future__ import annotations
 
 import json
+import logging
 import sys
 from collections import defaultdict
 from datetime import UTC, datetime, timedelta
@@ -557,7 +558,8 @@ def handle_health_overview_command(
     health_results = orchestrator.run_all_checks(save_metrics=True)
     overall = orchestrator.get_overall_health(health_results)
 
-    # 2. Usage (best-effort; prefer analytics, fallback to execution metrics)
+    # 2. Usage (best-effort; prefer analytics, fallback to execution metrics — HM-001-S1)
+    _log = logging.getLogger(__name__)
     usage_data = None
     try:
         usage_dashboard = AnalyticsDashboard()
@@ -565,6 +567,7 @@ def handle_health_overview_command(
     except Exception:
         pass
     # If analytics has no agent/workflow data, derive from execution metrics
+    fallback_used = False
     if usage_data:
         agents = usage_data.get("agents") or []
         workflows = usage_data.get("workflows") or []
@@ -572,9 +575,22 @@ def handle_health_overview_command(
             w.get("total_executions", 0) for w in workflows
         )
         if total_runs == 0:
-            usage_data = _usage_data_from_execution_metrics(project_root) or usage_data
+            fallback = _usage_data_from_execution_metrics(project_root)
+            if fallback:
+                fallback_used = True
+                usage_data = fallback
     else:
-        usage_data = _usage_data_from_execution_metrics(project_root) or usage_data
+        fallback = _usage_data_from_execution_metrics(project_root)
+        if fallback:
+            fallback_used = True
+            usage_data = fallback
+    if fallback_used and usage_data:
+        n_agents = len(usage_data.get("agents") or [])
+        n_workflows = len(usage_data.get("workflows") or [])
+        _log.info(
+            "Health overview: using execution metrics fallback (%s agents, %s workflows)",
+            n_agents, n_workflows,
+        )
 
     # 3. Build output
     feedback = get_feedback()