@mindfoldhq/trellis 0.3.10 → 0.4.0-beta.10

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

@@ -0,0 +1,37 @@
+"""
+JSON file I/O utilities.
+
+Provides read_json and write_json as the single source of truth
+for JSON file operations across all Trellis scripts.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def read_json(path: Path) -> dict | None:
+    """Read and parse a JSON file.
+
+    Returns None if the file doesn't exist, is invalid JSON, or can't be read.
+    """
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def write_json(path: Path, data: dict) -> bool:
+    """Write dict to JSON file with pretty formatting.
+
+    Returns True on success, False on error.
+    """
+    try:
+        path.write_text(
+            json.dumps(data, indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        return True
+    except (OSError, IOError):
+        return False

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

@@ -0,0 +1,45 @@
+"""
+Terminal output utilities: colors and structured logging.
+
+Single source of truth for Colors and log_* functions
+used across all Trellis scripts.
+"""
+
+from __future__ import annotations
+
+
+class Colors:
+    """ANSI color codes for terminal output."""
+
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    CYAN = "\033[0;36m"
+    DIM = "\033[2m"
+    NC = "\033[0m"  # No Color / Reset
+
+
+def colored(text: str, color: str) -> str:
+    """Apply ANSI color to text."""
+    return f"{color}{text}{Colors.NC}"
+
+
+def log_info(msg: str) -> None:
+    """Print info-level message with [INFO] prefix."""
+    print(f"{Colors.BLUE}[INFO]{Colors.NC} {msg}")
+
+
+def log_success(msg: str) -> None:
+    """Print success message with [SUCCESS] prefix."""
+    print(f"{Colors.GREEN}[SUCCESS]{Colors.NC} {msg}")
+
+
+def log_warn(msg: str) -> None:
+    """Print warning message with [WARN] prefix."""
+    print(f"{Colors.YELLOW}[WARN]{Colors.NC} {msg}")
+
+
+def log_error(msg: str) -> None:
+    """Print error message with [ERROR] prefix."""
+    print(f"{Colors.RED}[ERROR]{Colors.NC} {msg}")

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

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+Package discovery and context output.
+
+Provides:
+    get_packages_info           - Get structured package info
+    get_packages_section        - Build PACKAGES text section
+    get_context_packages_text   - Full packages text output (--mode packages)
+    get_context_packages_json   - Full packages JSON output (--mode packages --json)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .config import _is_true_config_value, get_default_package, get_packages, get_spec_scope
+from .paths import (
+    DIR_SPEC,
+    DIR_WORKFLOW,
+    get_current_task,
+    get_repo_root,
+)
+from .tasks import load_task
+
+
+# =============================================================================
+# Internal Helpers
+# =============================================================================
+
+def _scan_spec_layers(spec_dir: Path, package: str | None = None) -> list[str]:
+    """Scan spec directory for available layers (subdirectories).
+
+    For monorepo: scans spec/<package>/
+    For single-repo: scans spec/
+    """
+    target = spec_dir / package if package else spec_dir
+    if not target.is_dir():
+        return []
+    return sorted(
+        d.name for d in target.iterdir() if d.is_dir() and d.name != "guides"
+    )
+
+
+def _get_active_task_package(repo_root: Path) -> str | None:
+    """Get the package field from the active task's task.json."""
+    current = get_current_task(repo_root)
+    if not current:
+        return None
+    ct = load_task(repo_root / current)
+    return ct.package if ct and ct.package else None
+
+
+def _resolve_scope_set(
+    packages: dict,
+    spec_scope,
+    task_pkg: str | None,
+    default_pkg: str | None,
+) -> set | None:
+    """Resolve spec_scope to a set of allowed package names, or None for full scan."""
+    if not packages:
+        return None
+
+    if spec_scope is None:
+        return None
+
+    if isinstance(spec_scope, str) and spec_scope == "active_task":
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None
+
+    if isinstance(spec_scope, list):
+        valid = {e for e in spec_scope if e in packages}
+        if valid:
+            return valid
+        # All invalid: fallback
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None
+
+    return None
+
+
+# =============================================================================
+# Public Functions
+# =============================================================================
+
+def get_packages_info(repo_root: Path) -> list[dict]:
+    """Get structured package info for monorepo projects.
+
+    Returns list of dicts with keys: name, path, type, default, specLayers,
+    isSubmodule, isGitRepo.
+    Returns empty list for single-repo projects.
+    """
+    packages = get_packages(repo_root)
+    if not packages:
+        return []
+
+    default_pkg = get_default_package(repo_root)
+    spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+    result = []
+
+    for pkg_name, pkg_config in packages.items():
+        pkg_path = pkg_config.get("path", pkg_name) if isinstance(pkg_config, dict) else str(pkg_config)
+        pkg_type = pkg_config.get("type", "local") if isinstance(pkg_config, dict) else "local"
+        pkg_git = pkg_config.get("git", False) if isinstance(pkg_config, dict) else False
+        layers = _scan_spec_layers(spec_dir, pkg_name)
+
+        result.append({
+            "name": pkg_name,
+            "path": pkg_path,
+            "type": pkg_type,
+            "default": pkg_name == default_pkg,
+            "specLayers": layers,
+            "isSubmodule": pkg_type == "submodule",
+            "isGitRepo": _is_true_config_value(pkg_git),
+        })
+
+    return result
+
+
+def get_packages_section(repo_root: Path) -> str:
+    """Build the PACKAGES section for text output."""
+    spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+    pkg_info = get_packages_info(repo_root)
+
+    lines: list[str] = []
+    lines.append("## PACKAGES")
+
+    if not pkg_info:
+        lines.append("(single-repo mode)")
+        layers = _scan_spec_layers(spec_dir)
+        if layers:
+            lines.append(f"Spec layers: {', '.join(layers)}")
+        return "\n".join(lines)
+
+    default_pkg = get_default_package(repo_root)
+
+    for pkg in pkg_info:
+        layers_str = f"  [{', '.join(pkg['specLayers'])}]" if pkg["specLayers"] else ""
+        submodule_tag = "  (submodule)" if pkg["isSubmodule"] else ""
+        git_repo_tag = "  (git repo)" if pkg["isGitRepo"] else ""
+        default_tag = "  *" if pkg["default"] else ""
+        lines.append(
+            f"- {pkg['name']:<16} {pkg['path']:<20}{layers_str}{submodule_tag}{git_repo_tag}{default_tag}"
+        )
+
+    if default_pkg:
+        lines.append(f"Default package: {default_pkg}")
+
+    return "\n".join(lines)
+
+
+def get_context_packages_text(repo_root: Path | None = None) -> str:
+    """Get packages context as formatted text (for --mode packages)."""
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    pkg_info = get_packages_info(repo_root)
+    lines: list[str] = []
+
+    if not pkg_info:
+        spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+        lines.append("Single-repo project (no packages configured)")
+        lines.append("")
+        layers = _scan_spec_layers(spec_dir)
+        if layers:
+            lines.append(f"Spec layers: {', '.join(layers)}")
+        return "\n".join(lines)
+
+    # Resolve scope for annotations
+    packages_dict = get_packages(repo_root) or {}
+    default_pkg = get_default_package(repo_root)
+    spec_scope = get_spec_scope(repo_root)
+    task_pkg = _get_active_task_package(repo_root)
+    scope_set = _resolve_scope_set(packages_dict, spec_scope, task_pkg, default_pkg)
+
+    lines.append("## PACKAGES")
+    lines.append("")
+    for pkg in pkg_info:
+        default_tag = " (default)" if pkg["default"] else ""
+        type_tag = f" [{pkg['type']}]" if pkg["type"] != "local" else ""
+        git_tag = " [git repo]" if pkg["isGitRepo"] else ""
+
+        # Scope annotation
+        scope_tag = ""
+        if scope_set is not None and pkg["name"] not in scope_set:
+            scope_tag = " (out of scope)"
+
+        lines.append(f"### {pkg['name']}{default_tag}{type_tag}{git_tag}{scope_tag}")
+        lines.append(f"Path: {pkg['path']}")
+        if pkg["specLayers"]:
+            lines.append(f"Spec layers: {', '.join(pkg['specLayers'])}")
+            for layer in pkg["specLayers"]:
+                lines.append(f"  - .trellis/spec/{pkg['name']}/{layer}/index.md")
+        else:
+            lines.append("Spec: not configured")
+        lines.append("")
+
+    # Also show shared guides
+    guides_dir = repo_root / DIR_WORKFLOW / DIR_SPEC / "guides"
+    if guides_dir.is_dir():
+        lines.append("### Shared Guides (always included)")
+        lines.append("Path: .trellis/spec/guides/index.md")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def get_context_packages_json(repo_root: Path | None = None) -> dict:
+    """Get packages context as a dictionary (for --mode packages --json)."""
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    pkg_info = get_packages_info(repo_root)
+
+    if not pkg_info:
+        spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+        layers = _scan_spec_layers(spec_dir)
+        return {
+            "mode": "single-repo",
+            "specLayers": layers,
+        }
+
+    default_pkg = get_default_package(repo_root)
+    spec_scope = get_spec_scope(repo_root)
+    task_pkg = _get_active_task_package(repo_root)
+
+    return {
+        "mode": "monorepo",
+        "packages": pkg_info,
+        "defaultPackage": default_pkg,
+        "specScope": spec_scope,
+        "activeTaskPackage": task_pkg,
+    }

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

@@ -221,6 +221,50 @@ def _get_current_task_file(repo_root: Path | None = None) -> Path:
     return repo_root / DIR_WORKFLOW / FILE_CURRENT_TASK
 
 
+def normalize_task_ref(task_ref: str) -> str:
+    """Normalize a task ref for stable storage in .current-task.
+
+    Stored refs should prefer repo-relative POSIX paths like
+    `.trellis/tasks/03-27-my-task`, even on Windows. Absolute paths are preserved
+    unless they can later be converted back to repo-relative form by callers.
+    """
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    if normalized.startswith(f"{DIR_TASKS}/"):
+        return f"{DIR_WORKFLOW}/{normalized}"
+
+    return normalized
+
+
+def resolve_task_ref(task_ref: str, repo_root: Path | None = None) -> Path | None:
+    """Resolve a task ref from .current-task to an absolute task directory path."""
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    normalized = normalize_task_ref(task_ref)
+    if not normalized:
+        return None
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return path_obj
+
+    if normalized.startswith(f"{DIR_WORKFLOW}/"):
+        return repo_root / path_obj
+
+    return repo_root / DIR_WORKFLOW / DIR_TASKS / path_obj
+
+
 def get_current_task(repo_root: Path | None = None) -> str | None:
     """Get current task directory path (relative to repo_root).
 
@@ -236,7 +280,8 @@ def get_current_task(repo_root: Path | None = None) -> str | None:
         return None
 
     try:
-        return current_file.read_text(encoding="utf-8").strip()
+        content = current_file.read_text(encoding="utf-8").strip()
+        return normalize_task_ref(content) if content else None
     except (OSError, IOError):
         return None
 
@@ -255,7 +300,7 @@ def get_current_task_abs(repo_root: Path | None = None) -> Path | None:
 
     relative = get_current_task(repo_root)
     if relative:
-        return repo_root / relative
+        return resolve_task_ref(relative, repo_root)
     return None
 
 
@@ -272,18 +317,24 @@ def set_current_task(task_path: str, repo_root: Path | None = None) -> bool:
     if repo_root is None:
         repo_root = get_repo_root()
 
-    if not task_path:
+    normalized = normalize_task_ref(task_path)
+    if not normalized:
         return False
 
     # Verify task directory exists
-    full_path = repo_root / task_path
-    if not full_path.is_dir():
+    full_path = resolve_task_ref(normalized, repo_root)
+    if full_path is None or not full_path.is_dir():
         return False
 
+    try:
+        normalized = full_path.relative_to(repo_root).as_posix()
+    except ValueError:
+        normalized = str(full_path)
+
     current_file = _get_current_task_file(repo_root)
 
     try:
-        current_file.write_text(task_path, encoding="utf-8")
+        current_file.write_text(normalized, encoding="utf-8")
         return True
     except (OSError, IOError):
         return False
@@ -333,6 +384,52 @@ def generate_task_date_prefix() -> str:
     return datetime.now().strftime("%m-%d")
 
 
+# =============================================================================
+# Monorepo / Package Paths
+# =============================================================================
+
+
+def get_spec_dir(package: str | None = None, repo_root: Path | None = None) -> Path:
+    """Get the spec directory path.
+
+    Single-repo: .trellis/spec
+    Monorepo with package: .trellis/spec/<package>
+
+    Uses lazy import to avoid circular dependency with config.py.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    from .config import get_spec_base
+
+    base = get_spec_base(package, repo_root)
+    return repo_root / DIR_WORKFLOW / base
+
+
+def get_package_path(package: str, repo_root: Path | None = None) -> Path | None:
+    """Get a package's source directory absolute path from config.
+
+    Returns:
+        Absolute path to the package directory, or None if not found.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    from .config import get_packages
+
+    packages = get_packages(repo_root)
+    if not packages or package not in packages:
+        return None
+
+    info = packages[package]
+    if isinstance(info, dict):
+        rel_path = info.get("path", package)
+    else:
+        rel_path = str(info)
+
+    return repo_root / rel_path
+
+
 # =============================================================================
 # Main Entry (for testing)
 # =============================================================================

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

@@ -19,25 +19,39 @@ Provides:
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 
+from .io import read_json, write_json
 
-def _read_json_file(path: Path) -> dict | None:
-    """Read and parse a JSON file."""
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (FileNotFoundError, json.JSONDecodeError, OSError):
-        return None
 
+# =============================================================================
+# Internal Helpers (operate on pre-loaded data dict)
+# =============================================================================
+
+def _total_phases(data: dict) -> int:
+    """Get total phases from pre-loaded data."""
+    next_action = data.get("next_action", [])
+    return len(next_action) if isinstance(next_action, list) else 0
 
-def _write_json_file(path: Path, data: dict) -> bool:
-    """Write dict to JSON file."""
-    try:
-        path.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
-        return True
-    except (OSError, IOError):
-        return False
+
+def _phase_action(data: dict, phase: int) -> str:
+    """Get action name for a phase from pre-loaded data."""
+    next_action = data.get("next_action", [])
+    if isinstance(next_action, list):
+        for item in next_action:
+            if isinstance(item, dict) and item.get("phase") == phase:
+                return item.get("action", "unknown")
+    return "unknown"
+
+
+def _phase_for_action(data: dict, action: str) -> int:
+    """Get phase number for an action name from pre-loaded data."""
+    next_action = data.get("next_action", [])
+    if isinstance(next_action, list):
+        for item in next_action:
+            if isinstance(item, dict) and item.get("action") == action:
+                return item.get("phase", 0)
+    return 0
 
 
 # =============================================================================
@@ -53,7 +67,7 @@ def get_current_phase(task_json: Path) -> int:
     Returns:
         Current phase number, or 0 if not found.
     """
-    data = _read_json_file(task_json)
+    data = read_json(task_json)
     if not data:
         return 0
     return data.get("current_phase", 0) or 0
@@ -68,14 +82,10 @@ def get_total_phases(task_json: Path) -> int:
     Returns:
         Total phase count, or 0 if not found.
     """
-    data = _read_json_file(task_json)
+    data = read_json(task_json)
     if not data:
         return 0
-
-    next_action = data.get("next_action", [])
-    if isinstance(next_action, list):
-        return len(next_action)
-    return 0
+    return _total_phases(data)
 
 
 def get_phase_action(task_json: Path, phase: int) -> str:
@@ -88,16 +98,10 @@ def get_phase_action(task_json: Path, phase: int) -> str:
     Returns:
         Action name, or "unknown" if not found.
     """
-    data = _read_json_file(task_json)
+    data = read_json(task_json)
     if not data:
         return "unknown"
-
-    next_action = data.get("next_action", [])
-    if isinstance(next_action, list):
-        for item in next_action:
-            if isinstance(item, dict) and item.get("phase") == phase:
-                return item.get("action", "unknown")
-    return "unknown"
+    return _phase_action(data, phase)
 
 
 def get_phase_info(task_json: Path) -> str:
@@ -109,18 +113,18 @@ def get_phase_info(task_json: Path) -> str:
     Returns:
         Formatted string like "1/4 (implement)".
     """
-    data = _read_json_file(task_json)
+    data = read_json(task_json)
     if not data:
         return "N/A"
 
     current_phase = data.get("current_phase", 0) or 0
-    total_phases = get_total_phases(task_json)
-    action_name = get_phase_action(task_json, current_phase)
+    total = _total_phases(data)
+    action_name = _phase_action(data, current_phase)
 
     if current_phase == 0 or current_phase is None:
-        return f"0/{total_phases} (pending)"
+        return f"0/{total} (pending)"
     else:
-        return f"{current_phase}/{total_phases} ({action_name})"
+        return f"{current_phase}/{total} ({action_name})"
 
 
 def set_phase(task_json: Path, phase: int) -> bool:
@@ -133,12 +137,12 @@ def set_phase(task_json: Path, phase: int) -> bool:
     Returns:
         True on success, False on error.
     """
-    data = _read_json_file(task_json)
+    data = read_json(task_json)
     if not data:
         return False
 
     data["current_phase"] = phase
-    return _write_json_file(task_json, data)
+    return write_json(task_json, data)
 
 
 def advance_phase(task_json: Path) -> bool:
@@ -150,19 +154,19 @@ def advance_phase(task_json: Path) -> bool:
     Returns:
         True on success, False on error or at final phase.
     """
-    data = _read_json_file(task_json)
+    data = read_json(task_json)
     if not data:
         return False
 
     current = data.get("current_phase", 0) or 0
-    total = get_total_phases(task_json)
+    total = _total_phases(data)
     next_phase = current + 1
 
     if next_phase > total:
         return False  # Already at final phase
 
     data["current_phase"] = next_phase
-    return _write_json_file(task_json, data)
+    return write_json(task_json, data)
 
 
 def get_phase_for_action(task_json: Path, action: str) -> int:
@@ -175,16 +179,10 @@ def get_phase_for_action(task_json: Path, action: str) -> int:
     Returns:
         Phase number, or 0 if not found.
     """
-    data = _read_json_file(task_json)
+    data = read_json(task_json)
     if not data:
         return 0
-
-    next_action = data.get("next_action", [])
-    if isinstance(next_action, list):
-        for item in next_action:
-            if isinstance(item, dict) and item.get("action") == action:
-                return item.get("phase", 0)
-    return 0
+    return _phase_for_action(data, action)
 
 
 def map_subagent_to_action(subagent_type: str) -> str:
@@ -231,8 +229,11 @@ def is_current_action(task_json: Path, action: str) -> bool:
     Returns:
         True if current phase matches the action.
     """
-    current = get_current_phase(task_json)
-    action_phase = get_phase_for_action(task_json, action)
+    data = read_json(task_json)
+    if not data:
+        return False
+    current = data.get("current_phase", 0) or 0
+    action_phase = _phase_for_action(data, action)
     return current == action_phase