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

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/cleanup_agent.py

@@ -0,0 +1,92 @@
+"""
+Cleanup Agent command handlers
+"""
+import asyncio
+
+from ...agents.cleanup.agent import CleanupAgent
+from ..base import normalize_command
+from ..feedback import get_feedback
+from ..help.static_help import get_static_help
+from ..utils.agent_lifecycle import safe_close_agent_sync
+from .common import check_result_error
+
+
+def handle_cleanup_agent_command(args: object) -> None:
+    """Handle cleanup-agent commands."""
+    feedback = get_feedback()
+    command = normalize_command(getattr(args, "command", None))
+    output_format = getattr(args, "format", "json")
+    feedback.format_type = output_format
+
+    # Help commands first - no activation needed
+    if command == "help" or command is None:
+        help_text = get_static_help("cleanup-agent")
+        feedback.output_result(help_text)
+        return
+
+    # Cleanup agent runs offline (no network needed for file operations)
+    offline_mode = True
+
+    # Create and activate agent
+    cleanup = CleanupAgent()
+    try:
+        asyncio.run(cleanup.activate(offline_mode=offline_mode))
+
+        if command == "analyze":
+            result = asyncio.run(
+                cleanup.run(
+                    "analyze",
+                    path=getattr(args, "path", None),
+                    pattern=getattr(args, "pattern", "*.md"),
+                    output=getattr(args, "output", None),
+                )
+            )
+        elif command == "plan":
+            result = asyncio.run(
+                cleanup.run(
+                    "plan",
+                    analysis_file=getattr(args, "analysis_file", None),
+                    path=getattr(args, "path", None),
+                    pattern=getattr(args, "pattern", "*.md"),
+                    output=getattr(args, "output", None),
+                )
+            )
+        elif command == "execute":
+            # Handle dry-run flag (--no-dry-run disables dry-run)
+            dry_run = not getattr(args, "no_dry_run", False)
+            backup = not getattr(args, "no_backup", False)
+
+            result = asyncio.run(
+                cleanup.run(
+                    "execute",
+                    plan_file=getattr(args, "plan_file", None),
+                    path=getattr(args, "path", None),
+                    pattern=getattr(args, "pattern", "*.md"),
+                    dry_run=dry_run,
+                    backup=backup,
+                )
+            )
+        elif command == "run":
+            # Handle dry-run flag (--no-dry-run disables dry-run)
+            dry_run = not getattr(args, "no_dry_run", False)
+            backup = not getattr(args, "no_backup", False)
+
+            result = asyncio.run(
+                cleanup.run(
+                    "run",
+                    path=getattr(args, "path", None),
+                    pattern=getattr(args, "pattern", "*.md"),
+                    dry_run=dry_run,
+                    backup=backup,
+                )
+            )
+        else:
+            # Invalid command - show help
+            help_text = get_static_help("cleanup-agent")
+            feedback.output_result(help_text)
+            return
+
+        check_result_error(result)
+        feedback.output_result(result, message="Cleanup operation completed successfully")
+    finally:
+        safe_close_agent_sync(cleanup)

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()