@jahanxu/trellis 0.4.1 → 0.5.0

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

@@ -1,38 +1,43 @@
 #!/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)
+Pool Management Script for Three-Role Collaboration Pipeline.
 
 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>
+    python3 pool.py init [pool-name...]         # Create pool JSON files
+    python3 pool.py add <pool> <id> <title> <path> [--handoff <path>]  # Add deliverable
+    python3 pool.py list [pool]                 # List available items
+    python3 pool.py status <pool> <id>          # Get item status
+    python3 pool.py consume <pool> <id> <consumed-by>  # Mark as consumed
 """
 
+from __future__ import annotations
+
+import sys
+
+# IMPORTANT: Force stdout to use UTF-8 on Windows
+# This fixes UnicodeEncodeError when outputting non-ASCII characters
+if sys.platform == "win32":
+    import io as _io
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    elif hasattr(sys.stdout, "detach"):
+        sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+
 import argparse
 import json
+import os
 import sys
-from datetime import datetime
+from datetime import datetime, timezone
 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
-# =============================================================================
+from common.paths import (
+    get_repo_root,
+    get_developer,
+    get_pool_dir,
+    get_pool_file,
+)
 
-POOL_DIR = ".trellis/pool"
-POOL_TYPES = ["requirements", "prototypes", "implementations"]
 
 # =============================================================================
 # Colors
@@ -48,280 +53,246 @@ class Colors:
 
 
 def colored(text: str, color: str) -> str:
+    """Apply color to text."""
     return f"{color}{text}{Colors.NC}"
 
 
 # =============================================================================
-# Helper Functions
+# Constants
 # =============================================================================
 
-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")
+DEFAULT_POOLS = ["requirements", "prototypes", "implementations"]
 
-    # Atomic replace
-    tmp_file.replace(pool_file)
+EMPTY_POOL = {"available": []}
 
 
-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)
+# =============================================================================
+# Pool I/O (atomic writes)
+# =============================================================================
 
-    for task in pool_data.get("consumed", []):
-        if task.get("id") == task_id:
-            return ("consumed", task)
+def _read_pool(pool_path: Path) -> dict:
+    """Read pool JSON file. Auto-create if missing, backup if corrupted."""
+    if not pool_path.is_file():
+        return {"available": []}
 
-    return (None, None)
+    try:
+        data = json.loads(pool_path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict) or "available" not in data:
+            raise ValueError("Invalid pool schema")
+        return data
+    except (json.JSONDecodeError, ValueError):
+        # Backup corrupted file
+        bak_path = pool_path.with_suffix(".json.bak")
+        try:
+            pool_path.rename(bak_path)
+            print(colored(f"  Warning: Corrupted pool backed up to {bak_path.name}", Colors.YELLOW))
+        except OSError:
+            pass
+        return {"available": []}
+
+
+def _write_pool(pool_path: Path, data: dict) -> bool:
+    """Write pool JSON atomically (write .tmp then os.replace)."""
+    tmp_path = pool_path.with_suffix(".json.tmp")
+    try:
+        pool_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path.write_text(
+            json.dumps(data, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+        os.replace(str(tmp_path), str(pool_path))
+        return True
+    except (OSError, IOError) as e:
+        print(colored(f"  Error writing pool: {e}", Colors.RED))
+        # Clean up tmp if it exists
+        try:
+            tmp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        return False
 
 
 # =============================================================================
-# Command: add
+# Subcommands
 # =============================================================================
 
-def cmd_add(args: argparse.Namespace) -> int:
-    """Add task to pool."""
+def cmd_init(args: argparse.Namespace) -> int:
+    """Create pool JSON files."""
     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)
+    pool_dir = get_pool_dir(repo_root)
+    pool_dir.mkdir(parents=True, exist_ok=True)
+
+    pool_names = args.pools if args.pools else DEFAULT_POOLS
+
+    for name in pool_names:
+        pool_path = pool_dir / f"{name}.json"
+        if pool_path.is_file():
+            print(colored(f"  Pool '{name}' already exists, skipping", Colors.YELLOW))
+            continue
+        if _write_pool(pool_path, EMPTY_POOL):
+            print(colored(f"  Created pool: {name}", Colors.GREEN))
         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))
+            print(colored(f"  Failed to create pool: {name}", Colors.RED))
             return 1
 
-    pool_file = get_pool_file(pool_type, repo_root)
-    pool_data = read_pool(pool_file)
+    print(colored("Pool initialization complete.", Colors.GREEN))
+    return 0
 
-    # 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"]]
+def cmd_add(args: argparse.Namespace) -> int:
+    """Add a deliverable to a pool."""
+    repo_root = get_repo_root()
+    pool_path = get_pool_file(args.pool, repo_root)
+
+    data = _read_pool(pool_path)
+
+    # Check for duplicate ID
+    for item in data["available"]:
+        if item["id"] == args.id:
+            print(colored(f"  Warning: ID '{args.id}' already exists in pool '{args.pool}', skipping", Colors.YELLOW))
+            return 0
+
+    developer = get_developer(repo_root) or "unknown"
+
+    entry = {
+        "id": args.id,
+        "title": args.title,
+        "path": args.path,
+        "completed_by": developer,
+        "completed_at": datetime.now(timezone.utc).isoformat(),
+        "handoff_doc": args.handoff if args.handoff else f"{args.path}/HANDOFF.md",
+        "status": "available",
+    }
 
-    # Add to available list
-    task_data["status"] = "available"
-    task_data["added_at"] = datetime.now().isoformat()
-    pool_data["available"].append(task_data)
+    data["available"].append(entry)
 
-    # Write back
-    write_pool_atomic(pool_file, pool_data)
+    if _write_pool(pool_path, data):
+        print(colored(f"  Added '{args.id}' to pool '{args.pool}'", Colors.GREEN))
+        return 0
+    return 1
 
-    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
+def cmd_list(args: argparse.Namespace) -> int:
+    """List available items in pools."""
+    repo_root = get_repo_root()
+    pool_dir = get_pool_dir(repo_root)
 
+    if not pool_dir.is_dir():
+        print(colored("No pool directory found. Run 'pool.py init' first.", Colors.YELLOW))
+        return 0
 
-# =============================================================================
-# Command: list
-# =============================================================================
+    pools_to_list = [args.pool] if args.pool else [
+        p.stem for p in sorted(pool_dir.glob("*.json"))
+    ]
 
-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
+    if not pools_to_list:
+        print(colored("No pools found.", Colors.YELLOW))
+        return 0
 
-    pool_file = get_pool_file(pool_type, repo_root)
-    pool_data = read_pool(pool_file)
+    for pool_name in pools_to_list:
+        pool_path = get_pool_file(pool_name, repo_root)
+        data = _read_pool(pool_path)
 
-    print(colored(f"=== {pool_type.capitalize()} Pool ===", Colors.BLUE))
-    print()
+        available = [i for i in data["available"] if i.get("status") == "available"]
+        consumed = [i for i in data["available"] if i.get("status") == "consumed"]
 
-    # 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()
+        print(colored(f"\n=== {pool_name} ===", Colors.CYAN))
+        print(f"  Available: {len(available)}  |  Consumed: {len(consumed)}")
 
-    # 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 available:
+            print(colored("  Available items:", Colors.GREEN))
+            for item in available:
+                print(f"    - {item['id']}: {item['title']} (by {item.get('completed_by', '?')})")
         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))
+            print(colored("  Consumed items:", Colors.YELLOW))
+            for item in consumed:
+                consumed_by = item.get("consumed_by", "?")
+                print(f"    - {item['id']}: {item['title']} (consumed by {consumed_by})")
 
+    print()
     return 0
 
 
-# =============================================================================
-# Command: consume
-# =============================================================================
-
-def cmd_consume(args: argparse.Namespace) -> int:
-    """Mark task as consumed."""
+def cmd_status(args: argparse.Namespace) -> int:
+    """Get status of a specific item."""
     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
+    pool_path = get_pool_file(args.pool, repo_root)
+    data = _read_pool(pool_path)
 
-        print(colored(f"Error: Task '{task_id}' not found in {pool_type} pool", Colors.RED))
-        return 1
+    for item in data["available"]:
+        if item["id"] == args.id:
+            print(json.dumps(item, indent=2, ensure_ascii=False))
+            return 0
 
-    # Move from available to consumed
-    pool_data["available"] = [t for t in pool_data["available"] if t["id"] != task_id]
+    print(colored(f"  Item '{args.id}' not found in pool '{args.pool}'", Colors.RED))
+    return 1
 
-    task["status"] = "consumed"
-    task["consumed_by"] = consumed_by
-    task["consumed_at"] = datetime.now().isoformat()
 
-    pool_data["consumed"].append(task)
+def cmd_consume(args: argparse.Namespace) -> int:
+    """Mark an item as consumed."""
+    repo_root = get_repo_root()
+    pool_path = get_pool_file(args.pool, repo_root)
+    data = _read_pool(pool_path)
+
+    for item in data["available"]:
+        if item["id"] == args.id:
+            if item.get("status") == "consumed":
+                consumed_by = item.get("consumed_by", "?")
+                print(colored(f"  Item '{args.id}' already consumed by {consumed_by}", Colors.YELLOW))
+                return 1
 
-    # Write back
-    write_pool_atomic(pool_file, pool_data)
+            item["status"] = "consumed"
+            item["consumed_by"] = args.consumed_by
+            item["consumed_at"] = datetime.now(timezone.utc).isoformat()
 
-    print(colored(f"✓ Marked task '{task_id}' as consumed", Colors.GREEN))
-    print(f"  Consumed by: {consumed_by}")
+            if _write_pool(pool_path, data):
+                print(colored(f"  Marked '{args.id}' as consumed by {args.consumed_by}", Colors.GREEN))
+                return 0
+            return 1
 
-    return 0
+    print(colored(f"  Item '{args.id}' not found in pool '{args.pool}'", Colors.RED))
+    return 1
 
 
 # =============================================================================
-# Command: check
+# CLI Parser
 # =============================================================================
 
-def cmd_check(args: argparse.Namespace) -> int:
-    """Check pool integrity."""
-    repo_root = get_repo_root()
-    pool_type = args.pool_type
+def build_parser() -> argparse.ArgumentParser:
+    """Build argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Pool management for three-role collaboration pipeline",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
 
-    pool_file = get_pool_file(pool_type, repo_root)
-    pool_data = read_pool(pool_file)
+    # init
+    p_init = subparsers.add_parser("init", help="Create pool JSON files")
+    p_init.add_argument("pools", nargs="*", help="Pool names (default: requirements, prototypes, implementations)")
 
-    print(colored(f"=== Checking {pool_type} Pool ===", Colors.BLUE))
-    print()
+    # add
+    p_add = subparsers.add_parser("add", help="Add deliverable to pool")
+    p_add.add_argument("pool", help="Pool name (e.g., requirements)")
+    p_add.add_argument("id", help="Deliverable ID (e.g., user-login)")
+    p_add.add_argument("title", help="Deliverable title")
+    p_add.add_argument("path", help="Path to deliverable directory")
+    p_add.add_argument("--handoff", help="Path to HANDOFF.md (default: <path>/HANDOFF.md)")
 
-    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
+    # list
+    p_list = subparsers.add_parser("list", help="List available items")
+    p_list.add_argument("pool", nargs="?", help="Pool name (omit for all)")
 
-    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))
+    # status
+    p_status = subparsers.add_parser("status", help="Get item status")
+    p_status.add_argument("pool", help="Pool name")
+    p_status.add_argument("id", help="Item ID")
 
-    return 1 if errors > 0 else 0
+    # consume
+    p_consume = subparsers.add_parser("consume", help="Mark item as consumed")
+    p_consume.add_argument("pool", help="Pool name")
+    p_consume.add_argument("id", help="Item ID")
+    p_consume.add_argument("consumed_by", help="Consumer identity (e.g., designer-bob)")
+
+    return parser
 
 
 # =============================================================================
@@ -329,30 +300,7 @@ def cmd_check(args: argparse.Namespace) -> int:
 # =============================================================================
 
 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")
-
+    parser = build_parser()
     args = parser.parse_args()
 
     if not args.command:
@@ -360,10 +308,11 @@ def main() -> int:
         return 1
 
     commands = {
+        "init": cmd_init,
         "add": cmd_add,
         "list": cmd_list,
+        "status": cmd_status,
         "consume": cmd_consume,
-        "check": cmd_check,
     }
 
     return commands[args.command](args)