@blulotus/trellis 0.7.0

package/dist/templates/trellis/scripts/common/task_utils.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""
+Task utility functions.
+
+Provides:
+    is_safe_task_path   - Validate task path is safe to operate on
+    find_task_by_name   - Find task directory by name
+    resolve_task_dir    - Resolve task directory from name, relative, or absolute path
+    archive_task_dir    - Archive task to monthly directory
+    run_task_hooks      - Run lifecycle hooks for task events
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .paths import get_repo_root, get_tasks_dir
+
+
+# =============================================================================
+# Path Safety
+# =============================================================================
+
+def is_safe_task_path(task_path: str, repo_root: Path | None = None) -> bool:
+    """Check if a relative task path is safe to operate on.
+
+    Args:
+        task_path: Task path (relative to repo_root).
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True if safe, False if dangerous.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    normalized = task_path.replace("\\", "/")
+
+    # Check empty or null
+    if not normalized or normalized == "null":
+        print("Error: empty or null task path", file=sys.stderr)
+        return False
+
+    # Reject absolute paths
+    if Path(task_path).is_absolute():
+        print(f"Error: absolute path not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Reject ".", "..", paths starting with "./" or "../", or containing ".."
+    if normalized in (".", "..") or normalized.startswith("./") or normalized.startswith("../") or ".." in normalized:
+        print(f"Error: path traversal not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Final check: ensure resolved path is not the repo root
+    abs_path = repo_root / Path(normalized)
+    if abs_path.exists():
+        try:
+            resolved = abs_path.resolve()
+            root_resolved = repo_root.resolve()
+            if resolved == root_resolved:
+                print(f"Error: path resolves to repo root: {task_path}", file=sys.stderr)
+                return False
+        except (OSError, IOError):
+            pass
+
+    return True
+
+
+def is_within_tasks_dir(task_dir_abs: Path, repo_root: Path | None = None) -> bool:
+    """Check that a resolved task directory really is a task under the tasks dir.
+
+    A real task lives directly at ``.trellis/tasks/<name>``. This returns True
+    only when ``task_dir_abs`` is an immediate child of the tasks directory.
+
+    Guards archive: ``resolve_task_dir`` falls back to ``repo_root/<name>`` for
+    an unknown name, so a mistyped ``task.py archive src`` resolves to the real
+    ``src/`` source directory. Without this check archive would ``shutil.move``
+    it out of the repo. Also rejects the tasks dir itself and anything nested
+    under ``archive/`` (already-archived tasks).
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    try:
+        resolved = task_dir_abs.resolve()
+        tasks_resolved = get_tasks_dir(repo_root).resolve()
+    except (OSError, RuntimeError):
+        return False
+    if resolved.parent != tasks_resolved:
+        return False
+    return resolved.name != "archive"
+
+
+# =============================================================================
+# Task Lookup
+# =============================================================================
+
+def find_task_by_name(task_name: str, tasks_dir: Path) -> Path | None:
+    """Find task directory by name (exact or suffix match).
+
+    Args:
+        task_name: Task name to find.
+        tasks_dir: Tasks directory path.
+
+    Returns:
+        Absolute path to task directory, or None if not found.
+    """
+    if not task_name or not tasks_dir or not tasks_dir.is_dir():
+        return None
+
+    # Try exact match first
+    exact_match = tasks_dir / task_name
+    if exact_match.is_dir():
+        return exact_match
+
+    # Try suffix match (e.g., "my-task" matches "01-21-my-task")
+    for d in tasks_dir.iterdir():
+        if d.is_dir() and d.name.endswith(f"-{task_name}"):
+            return d
+
+    return None
+
+
+# =============================================================================
+# Archive Operations
+# =============================================================================
+
+def archive_task_dir(task_dir_abs: Path, repo_root: Path | None = None) -> Path | None:
+    """Archive a task directory to archive/{YYYY-MM}/.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to archived directory, or None on error.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return None
+
+    # Get tasks directory (parent of the task)
+    tasks_dir = task_dir_abs.parent
+    archive_dir = tasks_dir / "archive"
+    year_month = datetime.now().strftime("%Y-%m")
+    month_dir = archive_dir / year_month
+
+    # Create archive directory
+    try:
+        month_dir.mkdir(parents=True, exist_ok=True)
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create archive directory: {e}", file=sys.stderr)
+        return None
+
+    # Move task to archive
+    task_name = task_dir_abs.name
+    dest = month_dir / task_name
+
+    try:
+        shutil.move(str(task_dir_abs), str(dest))
+    except (OSError, IOError, shutil.Error) as e:
+        print(f"Error: Failed to move task to archive: {e}", file=sys.stderr)
+        return None
+
+    return dest
+
+
+def archive_task_complete(
+    task_dir_abs: Path,
+    repo_root: Path | None = None
+) -> dict[str, str]:
+    """Complete archive workflow: archive directory.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Dict with archive result info.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return {}
+
+    archive_dest = archive_task_dir(task_dir_abs, repo_root)
+    if archive_dest:
+        return {"archived_to": str(archive_dest)}
+
+    return {}
+
+
+# =============================================================================
+# Task Directory Resolution
+# =============================================================================
+
+def resolve_task_dir(target_dir: str, repo_root: Path) -> Path | None:
+    """Resolve task directory to absolute path.
+
+    Supports:
+    - Absolute path: /path/to/task
+    - Relative path: .trellis/tasks/01-31-my-task
+    - Task name: my-task (uses find_task_by_name for lookup)
+
+    Args:
+        target_dir: Task directory specification.
+        repo_root: Repository root path.
+
+    Returns:
+        Resolved absolute path, or None when it resolves outside
+        `repo_root`. Both sides are resolved before comparing, since
+        `repo_root` may itself sit behind a symlink (/tmp does on macOS).
+    """
+    if not target_dir:
+        return Path()
+
+    normalized = target_dir.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    # Absolute path
+    if Path(target_dir).is_absolute():
+        candidate = Path(target_dir)
+    # Relative path (contains path separator or starts with .trellis)
+    elif "/" in normalized or normalized.startswith(".trellis"):
+        candidate = repo_root / Path(normalized)
+    else:
+        # Task name - try to find in tasks directory; fall back to treating
+        # it as a relative path when not found.
+        tasks_dir = get_tasks_dir(repo_root)
+        found = find_task_by_name(target_dir, tasks_dir)
+        candidate = found if found else repo_root / Path(normalized)
+
+    try:
+        resolved = candidate.resolve()
+        root = repo_root.resolve()
+    except OSError:
+        return None
+
+    try:
+        resolved.relative_to(root)
+    except ValueError:
+        return None
+
+    return resolved
+
+
+# =============================================================================
+# Lifecycle Hooks
+# =============================================================================
+
+def run_task_hooks(event: str, task_json_path: Path, repo_root: Path) -> None:
+    """Run lifecycle hooks for a task event.
+
+    Args:
+        event: Event name (e.g. "after_create").
+        task_json_path: Absolute path to the task's task.json.
+        repo_root: Repository root for cwd and config lookup.
+    """
+    import os
+    import subprocess
+
+    from .config import get_hooks
+    from .log import Colors, colored
+
+    commands = get_hooks(event, repo_root)
+    if not commands:
+        return
+
+    env = {**os.environ, "TASK_JSON_PATH": str(task_json_path)}
+
+    for cmd in commands:
+        try:
+            result = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=repo_root,
+                env=env,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if result.returncode != 0:
+                print(
+                    colored(f"[WARN] Hook failed ({event}): {cmd}", Colors.YELLOW),
+                    file=sys.stderr,
+                )
+                if result.stderr.strip():
+                    print(f"  {result.stderr.strip()}", file=sys.stderr)
+        except Exception as e:
+            print(
+                colored(f"[WARN] Hook error ({event}): {cmd} — {e}", Colors.YELLOW),
+                file=sys.stderr,
+            )
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    repo = get_repo_root()
+    tasks = get_tasks_dir(repo)
+
+    print(f"Tasks dir: {tasks}")
+    print(f"is_safe_task_path('.trellis/tasks/test'): {is_safe_task_path('.trellis/tasks/test', repo)}")
+    print(f"is_safe_task_path('../test'): {is_safe_task_path('../test', repo)}")

package/dist/templates/trellis/scripts/common/tasks.py

@@ -0,0 +1,112 @@
+"""
+Task data access layer.
+
+Single source of truth for loading and iterating task directories.
+Replaces scattered task.json parsing across 9+ files.
+
+Provides:
+    load_task          — Load a single task by directory path
+    iter_active_tasks  — Iterate all non-archived tasks (sorted)
+    get_all_statuses   — Get {dir_name: status} map for children progress
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from .io import read_json
+from .paths import FILE_TASK_JSON
+from .types import TaskInfo
+
+
+def load_task(task_dir: Path) -> TaskInfo | None:
+    """Load task from a directory containing task.json.
+
+    Args:
+        task_dir: Absolute path to the task directory.
+
+    Returns:
+        TaskInfo if task.json exists and is valid, None otherwise.
+    """
+    task_json = task_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        return None
+
+    data = read_json(task_json)
+    if not data:
+        return None
+
+    return TaskInfo(
+        dir_name=task_dir.name,
+        directory=task_dir,
+        title=data.get("title") or data.get("name") or "unknown",
+        status=data.get("status", "unknown"),
+        assignee=data.get("assignee", ""),
+        priority=data.get("priority", "P2"),
+        children=tuple(data.get("children", [])),
+        parent=data.get("parent"),
+        package=data.get("package"),
+        raw=data,
+    )
+
+
+def iter_active_tasks(tasks_dir: Path) -> Iterator[TaskInfo]:
+    """Iterate all active (non-archived) tasks, sorted by directory name.
+
+    Skips the "archive" directory and directories without valid task.json.
+
+    Args:
+        tasks_dir: Path to the tasks directory.
+
+    Yields:
+        TaskInfo for each valid task.
+    """
+    if not tasks_dir.is_dir():
+        return
+
+    for d in sorted(tasks_dir.iterdir()):
+        if not d.is_dir() or d.name == "archive":
+            continue
+        info = load_task(d)
+        if info is not None:
+            yield info
+
+
+def get_all_statuses(tasks_dir: Path) -> dict[str, str]:
+    """Get a {dir_name: status} mapping for all active tasks.
+
+    Useful for computing children progress without loading full TaskInfo.
+
+    Args:
+        tasks_dir: Path to the tasks directory.
+
+    Returns:
+        Dict mapping directory names to status strings.
+    """
+    return {t.dir_name: t.status for t in iter_active_tasks(tasks_dir)}
+
+
+def children_progress(
+    children: tuple[str, ...] | list[str],
+    all_statuses: dict[str, str],
+) -> str:
+    """Format children progress string like " [2/3 done]".
+
+    Args:
+        children: List of child directory names.
+        all_statuses: Status map from get_all_statuses().
+
+    Returns:
+        Formatted string, or "" if no children.
+    """
+    if not children:
+        return ""
+    # A child missing from active statuses has been archived (cmd_archive
+    # sets status=completed before moving the dir). Count it as done so
+    # parent progress doesn't regress when children are archived.
+    done = sum(
+        1 for c in children
+        if c not in all_statuses or all_statuses.get(c) in ("completed", "done")
+    )
+    return f" [{done}/{len(children)} done]"

package/dist/templates/trellis/scripts/common/trellis_config.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""
+Standalone reader for .trellis/config.yaml.
+
+Mirrors a minimal subset of common.config so callers (hooks, workflow_phase)
+can read configuration without importing the full task/repo helpers. Returns
+an empty dict on missing/malformed files so callers stay simple.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+
+CONFIG_REL_PATH = ".trellis/config.yaml"
+
+
+def _unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+        return value[1:-1]
+    return value
+
+
+def _strip_inline_comment(value: str) -> str:
+    """Strip ` # …` inline comments while preserving `#` inside quoted strings.
+
+    YAML treats ` #` (space-hash) as a comment opener; bare `#` inside a token
+    is part of the value. Quoted strings are immune.
+    """
+    in_quote: str | None = None
+    for idx, ch in enumerate(value):
+        if in_quote:
+            if ch == in_quote:
+                in_quote = None
+            continue
+        if ch in ('"', "'"):
+            in_quote = ch
+            continue
+        if ch == "#" and (idx == 0 or value[idx - 1].isspace()):
+            return value[:idx]
+    return value
+
+
+def _next_content_line(lines: list[str], start: int) -> tuple[int, str]:
+    i = start
+    while i < len(lines):
+        stripped = lines[i].strip()
+        if stripped and not stripped.startswith("#"):
+            return i, lines[i]
+        i += 1
+    return i, ""
+
+
+def _parse_yaml_block(
+    lines: list[str], start: int, min_indent: int, target: dict
+) -> int:
+    i = start
+    current_list: list | None = None
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+
+        if not stripped or stripped.startswith("#"):
+            i += 1
+            continue
+
+        indent = len(line) - len(line.lstrip())
+        if indent < min_indent:
+            break
+
+        if stripped.startswith("- "):
+            if current_list is not None:
+                current_list.append(_unquote(stripped[2:].strip()))
+            i += 1
+        elif ":" in stripped:
+            key, _, value = stripped.partition(":")
+            key = key.strip()
+            value = _strip_inline_comment(value).strip()
+            was_quoted = len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'")
+            value = _unquote(value)
+            current_list = None
+
+            if value or was_quoted:
+                target[key] = value
+                i += 1
+            else:
+                next_i, next_line = _next_content_line(lines, i + 1)
+                if next_i >= len(lines):
+                    target[key] = {}
+                    i = next_i
+                elif next_line.strip().startswith("- "):
+                    current_list = []
+                    target[key] = current_list
+                    i += 1
+                else:
+                    next_indent = len(next_line) - len(next_line.lstrip())
+                    if next_indent > indent:
+                        nested: dict = {}
+                        target[key] = nested
+                        i = _parse_yaml_block(lines, i + 1, next_indent, nested)
+                    else:
+                        target[key] = {}
+                        i += 1
+        else:
+            i += 1
+
+    return i
+
+
+def parse_simple_yaml(content: str) -> dict:
+    """Parse a small subset of YAML. See common.config for full doc."""
+    lines = content.splitlines()
+    result: dict = {}
+    _parse_yaml_block(lines, 0, 0, result)
+    return result
+
+
+def read_trellis_config(repo_root: Optional[Path] = None) -> dict:
+    """Read .trellis/config.yaml. Returns {} on missing or malformed file."""
+    root = repo_root or Path.cwd()
+    config_file = root / CONFIG_REL_PATH
+    try:
+        content = config_file.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError):
+        return {}
+    try:
+        parsed = parse_simple_yaml(content)
+    except Exception:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}

package/dist/templates/trellis/scripts/common/types.py

@@ -0,0 +1,110 @@
+"""
+Core type definitions for Trellis task data.
+
+Provides:
+    TaskData     — TypedDict for task.json shape (read-path type hints only)
+    TaskInfo     — Frozen dataclass for loaded task (the public API type)
+    AgentRecord  — TypedDict for registry.json agent entries
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypedDict
+
+
+# =============================================================================
+# task.json shape (TypedDict — used only for read-path type hints)
+# =============================================================================
+
+class TaskData(TypedDict, total=False):
+    """Shape of task.json on disk.
+
+    Used only for type annotations when reading task.json.
+    Writes must use the original dict to avoid losing unknown fields.
+    """
+
+    id: str
+    name: str
+    title: str
+    description: str
+    status: str
+    dev_type: str
+    scope: str | None
+    package: str | None
+    priority: str
+    creator: str
+    assignee: str
+    createdAt: str
+    completedAt: str | None
+    branch: str | None
+    base_branch: str | None
+    worktree_path: str | None
+    commit: str | None
+    pr_url: str | None
+    subtasks: list[str]
+    children: list[str]
+    parent: str | None
+    relatedFiles: list[str]
+    notes: str
+    meta: dict
+
+
+# =============================================================================
+# Loaded task object (frozen dataclass — the public API type)
+# =============================================================================
+
+@dataclass(frozen=True)
+class TaskInfo:
+    """Immutable view of a loaded task.
+
+    Created by load_task() / iter_active_tasks().
+    Contains the commonly accessed fields; the original dict
+    is preserved in `raw` for write-back and uncommon field access.
+    """
+
+    dir_name: str
+    directory: Path
+    title: str
+    status: str
+    assignee: str
+    priority: str
+    children: tuple[str, ...]
+    parent: str | None
+    package: str | None
+    raw: dict  # original dict — use for writes and uncommon fields
+
+    @property
+    def name(self) -> str:
+        """Task name (id or name field)."""
+        return self.raw.get("name") or self.raw.get("id") or self.dir_name
+
+    @property
+    def description(self) -> str:
+        return self.raw.get("description", "")
+
+    @property
+    def branch(self) -> str | None:
+        return self.raw.get("branch")
+
+    @property
+    def meta(self) -> dict:
+        return self.raw.get("meta", {})
+
+
+# =============================================================================
+# registry.json agent entry
+# =============================================================================
+
+class AgentRecord(TypedDict, total=False):
+    """Shape of an agent entry in registry.json."""
+
+    id: str
+    pid: int
+    task_dir: str
+    worktree_path: str
+    branch: str
+    platform: str
+    started_at: str
+    status: str