@jahanxu/trellis 0.4.1

package/dist/templates/trellis/scripts/pool.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Task Pool Management Script
+
+Manages three role-based task pools:
+- requirements.json  (PM outputs)
+- prototypes.json    (Designer outputs)
+- implementations.json (Frontend outputs)
+
+Usage:
+    python3 pool.py add <pool-type> <task-data-json>
+    python3 pool.py list <pool-type> [--status available|consumed]
+    python3 pool.py consume <pool-type> <task-id>
+    python3 pool.py check <pool-type>
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Tuple, Dict
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
+
+from common.paths import get_repo_root
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+POOL_DIR = ".trellis/pool"
+POOL_TYPES = ["requirements", "prototypes", "implementations"]
+
+# =============================================================================
+# Colors
+# =============================================================================
+
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    CYAN = "\033[0;36m"
+    NC = "\033[0m"
+
+
+def colored(text: str, color: str) -> str:
+    return f"{color}{text}{Colors.NC}"
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+def get_pool_file(pool_type: str, repo_root: Path) -> Path:
+    """Get pool JSON file path."""
+    if pool_type not in POOL_TYPES:
+        raise ValueError(f"Invalid pool type: {pool_type}. Must be one of {POOL_TYPES}")
+    return repo_root / POOL_DIR / f"{pool_type}.json"
+
+
+def read_pool(pool_file: Path) -> dict:
+    """Read pool JSON file."""
+    if not pool_file.exists():
+        return {"available": [], "consumed": [], "last_updated": None}
+
+    try:
+        return json.loads(pool_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        print(colored(f"Error reading pool file: {e}", Colors.RED), file=sys.stderr)
+        return {"available": [], "consumed": [], "last_updated": None}
+
+
+def write_pool_atomic(pool_file: Path, data: dict) -> None:
+    """Write pool JSON with atomic operation (no complex locking needed).
+
+    Uses temp file + rename for atomicity.
+    Based on risk analysis: low concurrency risk for most pools.
+    """
+    # Update timestamp
+    data["last_updated"] = datetime.now().isoformat()
+
+    # Write to temp file
+    tmp_file = pool_file.with_suffix(".tmp")
+    tmp_file.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    # Atomic replace
+    tmp_file.replace(pool_file)
+
+
+def find_task_in_pool(pool_data: dict, task_id: str) -> Tuple[Optional[str], Optional[dict]]:
+    """Find task in pool by ID.
+
+    Returns:
+        (status, task_data) where status is "available" or "consumed"
+    """
+    for task in pool_data.get("available", []):
+        if task.get("id") == task_id:
+            return ("available", task)
+
+    for task in pool_data.get("consumed", []):
+        if task.get("id") == task_id:
+            return ("consumed", task)
+
+    return (None, None)
+
+
+# =============================================================================
+# Command: add
+# =============================================================================
+
+def cmd_add(args: argparse.Namespace) -> int:
+    """Add task to pool."""
+    repo_root = get_repo_root()
+    pool_type = args.pool_type
+
+    # Parse task data
+    try:
+        if args.task_data.startswith("{"):
+            task_data = json.loads(args.task_data)
+        else:
+            # Load from file
+            task_file = Path(args.task_data)
+            if not task_file.exists():
+                print(colored(f"Error: File not found: {args.task_data}", Colors.RED))
+                return 1
+            task_data = json.loads(task_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        print(colored(f"Error: Invalid JSON: {e}", Colors.RED))
+        return 1
+
+    # Validate required fields
+    required_fields = ["id", "title", "path", "completed_by", "handoff_doc"]
+    for field in required_fields:
+        if field not in task_data:
+            print(colored(f"Error: Missing required field: {field}", Colors.RED))
+            return 1
+
+    pool_file = get_pool_file(pool_type, repo_root)
+    pool_data = read_pool(pool_file)
+
+    # Check if task already exists
+    status, existing = find_task_in_pool(pool_data, task_data["id"])
+    if status:
+        print(colored(f"Warning: Task '{task_data['id']}' already exists in {status} list", Colors.YELLOW))
+        if not args.force:
+            print("Use --force to overwrite")
+            return 1
+
+        # Remove existing task
+        if status == "available":
+            pool_data["available"] = [t for t in pool_data["available"] if t["id"] != task_data["id"]]
+        else:
+            pool_data["consumed"] = [t for t in pool_data["consumed"] if t["id"] != task_data["id"]]
+
+    # Add to available list
+    task_data["status"] = "available"
+    task_data["added_at"] = datetime.now().isoformat()
+    pool_data["available"].append(task_data)
+
+    # Write back
+    write_pool_atomic(pool_file, pool_data)
+
+    print(colored(f"✓ Added task '{task_data['id']}' to {pool_type} pool", Colors.GREEN))
+    print(f"  Path: {task_data['path']}")
+    print(f"  HANDOFF: {task_data['handoff_doc']}")
+
+    return 0
+
+
+# =============================================================================
+# Command: list
+# =============================================================================
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """List tasks in pool."""
+    repo_root = get_repo_root()
+    pool_type = args.pool_type
+    filter_status = args.status
+
+    pool_file = get_pool_file(pool_type, repo_root)
+    pool_data = read_pool(pool_file)
+
+    print(colored(f"=== {pool_type.capitalize()} Pool ===", Colors.BLUE))
+    print()
+
+    # Show available tasks
+    if not filter_status or filter_status == "available":
+        available = pool_data.get("available", [])
+        print(colored(f"Available ({len(available)}):", Colors.GREEN))
+        if available:
+            for task in available:
+                print(f"  • {colored(task['id'], Colors.CYAN)}: {task['title']}")
+                print(f"    Completed by: {task['completed_by']}")
+                print(f"    Path: {task['path']}")
+                print()
+        else:
+            print("  (none)")
+            print()
+
+    # Show consumed tasks
+    if not filter_status or filter_status == "consumed":
+        consumed = pool_data.get("consumed", [])
+        print(colored(f"Consumed ({len(consumed)}):", Colors.YELLOW))
+        if consumed:
+            for task in consumed:
+                print(f"  • {colored(task['id'], Colors.CYAN)}: {task['title']}")
+                print(f"    Consumed by: {task.get('consumed_by', 'unknown')}")
+                print(f"    Consumed at: {task.get('consumed_at', 'unknown')}")
+                print()
+        else:
+            print("  (none)")
+            print()
+
+    # Show summary
+    last_updated = pool_data.get("last_updated", "never")
+    print(colored(f"Last updated: {last_updated}", Colors.BLUE))
+
+    return 0
+
+
+# =============================================================================
+# Command: consume
+# =============================================================================
+
+def cmd_consume(args: argparse.Namespace) -> int:
+    """Mark task as consumed."""
+    repo_root = get_repo_root()
+    pool_type = args.pool_type
+    task_id = args.task_id
+    consumed_by = args.consumed_by
+
+    pool_file = get_pool_file(pool_type, repo_root)
+    pool_data = read_pool(pool_file)
+
+    # Find task in available list
+    task = None
+    for t in pool_data.get("available", []):
+        if t["id"] == task_id:
+            task = t
+            break
+
+    if not task:
+        # Check if already consumed
+        for t in pool_data.get("consumed", []):
+            if t["id"] == task_id:
+                print(colored(f"Task '{task_id}' is already consumed", Colors.YELLOW))
+                print(f"  Consumed by: {t.get('consumed_by', 'unknown')}")
+                print(f"  Consumed at: {t.get('consumed_at', 'unknown')}")
+                return 1
+
+        print(colored(f"Error: Task '{task_id}' not found in {pool_type} pool", Colors.RED))
+        return 1
+
+    # Move from available to consumed
+    pool_data["available"] = [t for t in pool_data["available"] if t["id"] != task_id]
+
+    task["status"] = "consumed"
+    task["consumed_by"] = consumed_by
+    task["consumed_at"] = datetime.now().isoformat()
+
+    pool_data["consumed"].append(task)
+
+    # Write back
+    write_pool_atomic(pool_file, pool_data)
+
+    print(colored(f"✓ Marked task '{task_id}' as consumed", Colors.GREEN))
+    print(f"  Consumed by: {consumed_by}")
+
+    return 0
+
+
+# =============================================================================
+# Command: check
+# =============================================================================
+
+def cmd_check(args: argparse.Namespace) -> int:
+    """Check pool integrity."""
+    repo_root = get_repo_root()
+    pool_type = args.pool_type
+
+    pool_file = get_pool_file(pool_type, repo_root)
+    pool_data = read_pool(pool_file)
+
+    print(colored(f"=== Checking {pool_type} Pool ===", Colors.BLUE))
+    print()
+
+    errors = 0
+    warnings = 0
+
+    # Check available tasks
+    for task in pool_data.get("available", []):
+        task_id = task.get("id", "unknown")
+
+        # Check required fields
+        for field in ["id", "title", "path", "handoff_doc"]:
+            if field not in task:
+                print(colored(f"✗ Task '{task_id}': Missing field '{field}'", Colors.RED))
+                errors += 1
+
+        # Check if path exists
+        if "path" in task:
+            path = repo_root / task["path"]
+            if not path.exists():
+                print(colored(f"✗ Task '{task_id}': Path not found: {task['path']}", Colors.RED))
+                errors += 1
+
+        # Check if HANDOFF exists
+        if "handoff_doc" in task:
+            handoff = repo_root / task["handoff_doc"]
+            if not handoff.exists():
+                print(colored(f"⚠ Task '{task_id}': HANDOFF not found: {task['handoff_doc']}", Colors.YELLOW))
+                warnings += 1
+
+    print()
+    if errors == 0 and warnings == 0:
+        print(colored("✓ All checks passed", Colors.GREEN))
+    else:
+        print(colored(f"✗ {errors} error(s), {warnings} warning(s)", Colors.RED if errors > 0 else Colors.YELLOW))
+
+    return 1 if errors > 0 else 0
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Task Pool Management")
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # add
+    p_add = subparsers.add_parser("add", help="Add task to pool")
+    p_add.add_argument("pool_type", choices=POOL_TYPES, help="Pool type")
+    p_add.add_argument("task_data", help="Task data JSON or file path")
+    p_add.add_argument("--force", "-f", action="store_true", help="Overwrite existing task")
+
+    # list
+    p_list = subparsers.add_parser("list", help="List tasks in pool")
+    p_list.add_argument("pool_type", choices=POOL_TYPES, help="Pool type")
+    p_list.add_argument("--status", "-s", choices=["available", "consumed"], help="Filter by status")
+
+    # consume
+    p_consume = subparsers.add_parser("consume", help="Mark task as consumed")
+    p_consume.add_argument("pool_type", choices=POOL_TYPES, help="Pool type")
+    p_consume.add_argument("task_id", help="Task ID")
+    p_consume.add_argument("consumed_by", help="Developer who consumed the task")
+
+    # check
+    p_check = subparsers.add_parser("check", help="Check pool integrity")
+    p_check.add_argument("pool_type", choices=POOL_TYPES, help="Pool type")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return 1
+
+    commands = {
+        "add": cmd_add,
+        "list": cmd_list,
+        "consume": cmd_consume,
+        "check": cmd_check,
+    }
+
+    return commands[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())