@baoanaz/cviauto 0.6.5

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

@@ -0,0 +1,274 @@
+#!/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
+
+
+# =============================================================================
+# 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:
+    """Resolve task directory to absolute path.
+
+    Supports:
+    - Absolute path: /path/to/task
+    - Relative path: .cviauto/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.
+    """
+    if not target_dir:
+        return Path()
+
+    normalized = target_dir.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    # Absolute path
+    if Path(target_dir).is_absolute():
+        return Path(target_dir)
+
+    # Relative path (contains path separator or starts with .cviauto)
+    if "/" in normalized or normalized.startswith(".cviauto"):
+        return repo_root / Path(normalized)
+
+    # Task name - try to find in tasks directory
+    tasks_dir = get_tasks_dir(repo_root)
+    found = find_task_by_name(target_dir, tasks_dir)
+    if found:
+        return found
+
+    # Fallback to treating as relative path
+    return repo_root / Path(normalized)
+
+
+# =============================================================================
+# 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('.cviauto/tasks/test'): {is_safe_task_path('.cviauto/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/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

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

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Workflow Phase Extraction.
+
+Extracts step-level content from .cviauto/workflow.md and optionally filters
+platform-specific blocks.
+
+Platform marker syntax in workflow.md:
+
+    [Claude Code, Cursor, ...]
+    agent-capable content
+    [/Claude Code, Cursor, ...]
+
+Provides:
+    get_phase_index   - Extract the Phase Index section (no --step)
+    get_step          - Extract a single step (#### X.X) section
+    filter_platform   - Strip platform blocks that don't include the given name
+"""
+
+from __future__ import annotations
+
+import re
+
+from .paths import DIR_WORKFLOW, get_repo_root
+
+
+def _workflow_md_path():
+    return get_repo_root() / DIR_WORKFLOW / "workflow.md"
+
+# Match a line that *is* a platform marker: "[A, B, C]" or "[/A, B, C]"
+_MARKER_RE = re.compile(r"^\[(/?)([A-Za-z][^\[\]]*)\]\s*$")
+
+# Step heading: "#### 1.0 Title" or "#### 1.0 ..."
+_STEP_HEADING_RE = re.compile(r"^####\s+(\d+\.\d+)\b.*$")
+
+# Phase Index starts here; Phase 1/2/3 step bodies follow; ends at Breadcrumbs.
+_PHASE_INDEX_HEADING = "## Phase Index"
+
+
+def _read_workflow() -> str:
+    path = _workflow_md_path()
+    if not path.exists():
+        raise FileNotFoundError(f"workflow.md not found: {path}")
+    return path.read_text(encoding="utf-8")
+
+
+def _parse_marker(line: str) -> tuple[bool, list[str]] | None:
+    """Parse a platform marker line.
+
+    Returns:
+        (is_closing, [platform_names]) if line is a marker, else None.
+    """
+    m = _MARKER_RE.match(line)
+    if not m:
+        return None
+    is_closing = m.group(1) == "/"
+    names = [p.strip() for p in m.group(2).split(",") if p.strip()]
+    return is_closing, names
+
+
+def get_phase_index() -> str:
+    """Return the compact Phase Index summary from workflow.md.
+
+    SessionStart and no-step phase context use this small summary as their
+    orientation payload. Detailed Phase 1/2/3 instructions are loaded with
+    ``get_step`` on demand. ``[workflow-state:STATUS]`` tag blocks are
+    consumed by the per-turn hook, so they're stripped from this output.
+    """
+    text = _read_workflow()
+    lines = text.splitlines()
+
+    start: int | None = None
+    end: int | None = None
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if start is None and stripped == _PHASE_INDEX_HEADING:
+            start = i
+            continue
+        if start is not None and stripped == "## Phase 1: Plan":
+            end = i
+            break
+
+    if start is None:
+        return ""
+    if end is None:
+        end = len(lines)
+
+    section = "\n".join(lines[start:end]).rstrip()
+    # Strip [workflow-state:STATUS]...[/workflow-state:STATUS] blocks since
+    # they're injected separately by inject-workflow-state.py per-turn.
+    import re as _re
+    tag_re = _re.compile(
+        r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n.*?\n\s*\[/workflow-state:\1\]\n?",
+        _re.DOTALL,
+    )
+    return tag_re.sub("", section).rstrip() + "\n"
+
+
+def get_step(step_id: str) -> str:
+    """Return the `#### X.X` section matching step_id (header + body).
+
+    Body ends at the next `####` or `---` or `##` heading (whichever comes first).
+    """
+    text = _read_workflow()
+    lines = text.splitlines()
+
+    start: int | None = None
+    for i, line in enumerate(lines):
+        m = _STEP_HEADING_RE.match(line)
+        if m and m.group(1) == step_id:
+            start = i
+            break
+    if start is None:
+        return ""
+
+    end: int = len(lines)
+    for j in range(start + 1, len(lines)):
+        line = lines[j]
+        if line.startswith("#### "):
+            end = j
+            break
+        if line.startswith("## "):
+            end = j
+            break
+        # Horizontal rule at column 0
+        if line.strip() == "---":
+            end = j
+            break
+
+    return "\n".join(lines[start:end]).rstrip() + "\n"
+
+
+def _platform_matches(platform: str, block_names: list[str]) -> bool:
+    """Case-insensitive fuzzy match: accept 'cursor', 'Cursor', 'claude-code', 'Claude Code'."""
+    needle = platform.lower().replace("-", "").replace("_", "").replace(" ", "")
+    for name in block_names:
+        hay = name.lower().replace("-", "").replace("_", "").replace(" ", "")
+        if needle == hay:
+            return True
+    return False
+
+
+def resolve_effective_platform(platform: str, config: dict) -> str:
+    """Map ``codex`` to a dispatch-mode-namespaced virtual platform name.
+
+    When ``--platform codex`` is passed, return ``"codex-inline"`` (default)
+    or ``"codex-sub-agent"`` based on ``.cviauto/config.yaml`` ``codex.dispatch_mode``.
+    ``filter_platform`` then surfaces blocks whose marker lists include the
+    namespaced name (e.g. ``[codex-sub-agent, ...]`` or ``[codex-inline, Kilo,
+    Antigravity, Devin]``).
+
+    Default is ``inline`` because Codex sub-agents run with ``fork_turns="none"``
+    isolation and can't inherit the parent session's task context — inline
+    keeps the main agent in charge so context isn't lost. Invalid / missing
+    values also fall back to inline.
+
+    Other platforms are returned unchanged.
+    """
+    if platform == "codex":
+        mode = "inline"
+        codex_cfg = config.get("codex") if isinstance(config, dict) else None
+        if isinstance(codex_cfg, dict):
+            cfg_mode = codex_cfg.get("dispatch_mode")
+            if cfg_mode in ("inline", "sub-agent"):
+                mode = cfg_mode
+        return f"codex-{mode}"
+    return platform
+
+
+def filter_platform(content: str, platform: str) -> str:
+    """Keep lines outside any `[...]` block + lines inside blocks that include platform.
+
+    Marker lines themselves are dropped from the output.
+    """
+    lines = content.splitlines()
+    out: list[str] = []
+
+    in_block = False
+    keep_block = False
+
+    for line in lines:
+        marker = _parse_marker(line)
+        if marker is not None:
+            is_closing, names = marker
+            if not is_closing:
+                in_block = True
+                keep_block = _platform_matches(platform, names)
+            else:
+                in_block = False
+                keep_block = False
+            continue  # drop the marker line itself
+
+        if in_block:
+            if keep_block:
+                out.append(line)
+            continue
+        out.append(line)
+
+    # Collapse runs of 3+ blank lines that may arise from dropped markers
+    collapsed: list[str] = []
+    blank_run = 0
+    for line in out:
+        if line.strip() == "":
+            blank_run += 1
+            if blank_run <= 2:
+                collapsed.append(line)
+        else:
+            blank_run = 0
+            collapsed.append(line)
+
+    return "\n".join(collapsed).rstrip() + "\n"