@pennixrv/trellis 0.6.17

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

@@ -0,0 +1,203 @@
+"""
+Git command execution utility.
+
+Single source of truth for running git commands across all Trellis scripts.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from pathlib import Path
+
+
+# Bounded retry for transient `.git/index.lock` contention. Another process
+# (IDE git integration, status daemon, a concurrent Trellis session) can hold
+# the lock for a fraction of a second; three attempts spread over ~1.5s ride
+# that out without making a genuinely stuck lock hang the command. One sleep
+# per retry, so the attempt count follows the backoff tuple.
+INDEX_LOCK_RETRY_BACKOFF = (0.5, 1.0)
+INDEX_LOCK_RETRY_ATTEMPTS = len(INDEX_LOCK_RETRY_BACKOFF) + 1
+
+# Whether a checkout is a linked worktree cannot change while a script runs, and
+# the answer costs two subprocesses. Developer-identity resolution asks several
+# times per command whenever the local `.developer` file is absent, so memoize.
+_CACHE_MISS = object()
+_MAIN_WORKTREE_CACHE: dict[Path, Path | None] = {}
+
+
+def run_git(
+    args: list[str],
+    cwd: Path | None = None,
+    timeout: float | None = None,
+) -> tuple[int, str, str]:
+    """Run a git command and return (returncode, stdout, stderr).
+
+    Uses UTF-8 encoding with -c i18n.logOutputEncoding=UTF-8 to ensure
+    consistent output across all platforms (Windows, macOS, Linux). Callers
+    may provide a timeout for best-effort probes; normal Git operations remain
+    unbounded by default.
+    """
+    try:
+        git_args = ["git", "-c", "i18n.logOutputEncoding=UTF-8"] + args
+        result = subprocess.run(
+            git_args,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+        )
+        return result.returncode, result.stdout, result.stderr
+    except Exception as e:
+        return 1, "", str(e)
+
+
+def stderr_indicates_index_lock(stderr: str) -> bool:
+    """git failed because another process holds `.git/index.lock`."""
+    if not stderr:
+        return False
+    return "index.lock" in stderr.lower()
+
+
+def run_git_retry_index_lock(
+    args: list[str],
+    cwd: Path | None = None,
+    timeout: float | None = None,
+) -> tuple[int, str, str]:
+    """Run a git command, retrying only while `.git/index.lock` is held.
+
+    Any other non-zero exit returns immediately — a retry loop around real
+    failures (bad path, nothing to commit, hook rejection) just delays the
+    error. Returns the last (returncode, stdout, stderr).
+    """
+    rc, out, err = run_git(args, cwd=cwd, timeout=timeout)
+    attempt = 1
+    while (
+        rc != 0
+        and attempt < INDEX_LOCK_RETRY_ATTEMPTS
+        and stderr_indicates_index_lock(err)
+    ):
+        time.sleep(INDEX_LOCK_RETRY_BACKOFF[attempt - 1])
+        attempt += 1
+        rc, out, err = run_git(args, cwd=cwd, timeout=timeout)
+    return rc, out, err
+
+
+def index_lock_path(repo_root: Path) -> str:
+    """Path of the lock file git is contending on, for diagnostics.
+
+    Asks git so worktrees and `GIT_DIR` setups name the real file rather
+    than a `.git/` guess that does not exist there.
+    """
+    rc, out, _ = run_git(["rev-parse", "--git-path", "index.lock"], cwd=repo_root)
+    if rc == 0 and out.strip():
+        return out.strip()
+    return ".git/index.lock"
+
+
+def resolve_default_branch(repo_root: Path) -> str | None:
+    """Resolve the repository's default branch (origin/HEAD target).
+
+    Tries the local `refs/remotes/origin/HEAD` symbolic ref first (no
+    network access), then falls back to `git remote show origin` (which
+    may hit the network but also repairs a missing/stale symbolic-ref).
+    Returns None when neither resolves, so callers can fall back to their
+    own pre-existing behavior.
+    """
+    rc, out, _ = run_git(["symbolic-ref", "refs/remotes/origin/HEAD"], cwd=repo_root)
+    if rc == 0 and out.strip():
+        return out.strip().rsplit("/", 1)[-1]
+
+    rc, out, _ = run_git(["remote", "show", "origin"], cwd=repo_root)
+    if rc == 0:
+        for line in out.splitlines():
+            line = line.strip()
+            if line.startswith("HEAD branch:"):
+                branch = line.split(":", 1)[1].strip()
+                if branch and branch != "(unknown)":
+                    return branch
+
+    return None
+
+
+def current_branch_name(repo_root: Path) -> str | None:
+    """Return the checked-out branch name, or None when there isn't one.
+
+    Empty output covers detached HEAD and "not a git repository" alike, and
+    callers treat both the same way: there is no branch worth recording.
+    """
+    rc, out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+    if rc != 0:
+        return None
+    return out.strip() or None
+
+
+def has_git_remote(repo_root: Path) -> bool:
+    """Whether the repository has at least one configured remote."""
+    rc, out, _ = run_git(["remote"], cwd=repo_root)
+    return rc == 0 and bool(out.strip())
+
+
+def main_worktree_root(repo_root: Path) -> Path | None:
+    """Root of the main working tree when `repo_root` is a linked worktree.
+
+    Returns None in the main working tree itself, outside a git repository, and
+    for a linked worktree of a bare repository (no main checkout to point at).
+
+    `git worktree list --porcelain` reports the main working tree as its first
+    record, so git identifies it rather than this code deriving it from the
+    `.git` layout. Deriving it — taking the parent of `--git-common-dir` — is
+    wrong for a bare repository that happens to sit inside an unrelated
+    checkout (`~/repos/project.git` under a `~/repos` that is itself a repo):
+    the parent is a real checkout with a real `.developer`, so the guess is
+    indistinguishable from a hit and identity leaks across repositories.
+    """
+    cached = _MAIN_WORKTREE_CACHE.get(repo_root, _CACHE_MISS)
+    if cached is not _CACHE_MISS:
+        return cached  # type: ignore[return-value]
+
+    result = _probe_main_worktree_root(repo_root)
+    _MAIN_WORKTREE_CACHE[repo_root] = result
+    return result
+
+
+def _probe_main_worktree_root(repo_root: Path) -> Path | None:
+    rc_list, listing, _ = run_git(["worktree", "list", "--porcelain"], cwd=repo_root)
+    rc_top, toplevel, _ = run_git(["rev-parse", "--show-toplevel"], cwd=repo_root)
+    if rc_list != 0 or rc_top != 0:
+        return None
+
+    lines = listing.splitlines()
+    if not lines or not lines[0].startswith("worktree "):
+        return None
+
+    # Records are blank-line separated; a `bare` attribute on the first one
+    # means the "main working tree" is a bare repo with nothing to inherit.
+    for line in lines[1:]:
+        if not line.strip():
+            break
+        if line.strip() == "bare":
+            return None
+
+    try:
+        main_root = Path(lines[0][len("worktree ") :].strip()).resolve()
+        current_root = Path(toplevel.strip()).resolve()
+    except (OSError, ValueError):
+        return None
+
+    if main_root == current_root:
+        return None
+    return main_root
+
+
+def branch_exists_locally(branch: str, repo_root: Path) -> bool:
+    """Check whether a local branch ref exists in the repository."""
+    if not branch:
+        return False
+    rc, _, _ = run_git(
+        ["rev-parse", "--verify", "--quiet", f"refs/heads/{branch}"],
+        cwd=repo_root,
+    )
+    return rc == 0

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

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Git and Session Context utilities.
+
+Entry shim — delegates to session_context and packages_context.
+
+Provides:
+    output_json - Output context in JSON format
+    output_text - Output context in text format
+"""
+
+from __future__ import annotations
+
+import json
+
+from .git import run_git
+from .session_context import (
+    get_context_json,
+    get_context_text,
+    get_context_record_json,
+    get_context_text_record,
+    output_json,
+    output_text,
+)
+from .packages_context import (
+    get_context_packages_text,
+    get_context_packages_json,
+)
+from .trellis_config import read_trellis_config
+from .workflow_phase import (
+    filter_platform,
+    get_phase_index,
+    get_step,
+    resolve_effective_platform,
+)
+
+# Backward-compatible alias — external modules import this name
+_run_git_command = run_git
+
+
+# =============================================================================
+# Main Entry
+# =============================================================================
+
+def main() -> None:
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Get Session Context for AI Agent")
+    parser.add_argument(
+        "--json",
+        "-j",
+        action="store_true",
+        help="Output in JSON format (works with any --mode)",
+    )
+    parser.add_argument(
+        "--mode",
+        "-m",
+        choices=["default", "record", "packages", "phase"],
+        default="default",
+        help="Output mode: default (full context), record (for record-session), packages (package info only), phase (workflow step extraction)",
+    )
+    parser.add_argument(
+        "--step",
+        help="Step id for --mode phase, e.g. 1.1, 2.2. Omit to get the Phase Index.",
+    )
+    parser.add_argument(
+        "--platform",
+        help="Platform name for --mode phase, e.g. cursor, claude-code. Filters platform-tagged blocks.",
+    )
+
+    args = parser.parse_args()
+
+    if args.mode == "record":
+        if args.json:
+            print(json.dumps(get_context_record_json(), indent=2, ensure_ascii=False))
+        else:
+            print(get_context_text_record())
+    elif args.mode == "packages":
+        if args.json:
+            print(json.dumps(get_context_packages_json(), indent=2, ensure_ascii=False))
+        else:
+            print(get_context_packages_text())
+    elif args.mode == "phase":
+        content = get_step(args.step) if args.step else get_phase_index()
+        if not content.strip():
+            if args.step:
+                parser.exit(2, f"Step not found: {args.step}\n")
+            else:
+                parser.exit(2, "Phase Index section not found in workflow.md\n")
+        if args.platform:
+            effective = resolve_effective_platform(
+                args.platform, read_trellis_config()
+            )
+            content = filter_platform(content, effective)
+        print(content, end="")
+    else:
+        if args.json:
+            output_json()
+        else:
+            output_text()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,160 @@
+"""
+File I/O utilities.
+
+Provides read_json / write_json as the single source of truth for JSON file
+operations, plus write_text_atomic for the Markdown state files (journal,
+index.md) that carry durable session state.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+JSON_READ_MISSING = "missing"
+JSON_READ_INVALID = "invalid"
+JSON_READ_UNREADABLE = "unreadable"
+JSON_READ_NOT_OBJECT = "not-object"
+JSON_READ_EMPTY = "empty"
+JSON_READ_UNDECODABLE = "undecodable"
+
+
+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.
+    Use this for optional reads only — a caller that is about to overwrite the
+    file, or that must tell a parse error from a permissions error, wants
+    read_json_checked instead.
+    """
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError, UnicodeDecodeError):
+        # UnicodeDecodeError is not an OSError. Without it here a non-UTF-8
+        # session file raises out of a tolerant read, so the hook path fails
+        # instead of degrading to "no active task".
+        return None
+
+
+def read_json_checked(path: Path) -> tuple[dict | None, str | None]:
+    """Read a JSON object, keeping the ways it can fail distinguishable.
+
+    Returns ``(data, None)`` on success, or ``(None, reason)`` where reason is
+    one of the ``JSON_READ_*`` constants. An empty object counts as a failure:
+    a state file that parses to ``{}`` carries none of the fields callers read,
+    and treating it as success would silently rebuild it from defaults.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None, JSON_READ_MISSING
+    except UnicodeDecodeError:
+        # Not an OSError, so it escaped both handlers and surfaced as a
+        # traceback. The point of this reader is that every failure mode stays
+        # nameable, and "not valid UTF-8" is a different repair from
+        # "not valid JSON".
+        return None, JSON_READ_UNDECODABLE
+    except OSError:
+        return None, JSON_READ_UNREADABLE
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return None, JSON_READ_INVALID
+
+    if not isinstance(data, dict):
+        return None, JSON_READ_NOT_OBJECT
+    if not data:
+        return None, JSON_READ_EMPTY
+    return data, None
+
+
+def describe_json_read_failure(path: Path, reason: str | None) -> tuple[str, str]:
+    """Return ``(what happened, what to do)`` for a read_json_checked reason."""
+    if reason == JSON_READ_MISSING:
+        return (f"{path}: file not found", "Pass an existing task directory, or create the task first.")
+    if reason == JSON_READ_UNREADABLE:
+        return (
+            f"{path}: could not be read (permission denied or I/O error)",
+            "Check the file and directory permissions, then retry.",
+        )
+    if reason == JSON_READ_INVALID:
+        return (
+            f"{path}: not valid JSON",
+            f"Fix the syntax (e.g. `python3 -m json.tool {path}`), then retry.",
+        )
+    if reason == JSON_READ_NOT_OBJECT:
+        return (
+            f"{path}: top level is not a JSON object",
+            "Restore the file to a JSON object ({ ... }), then retry.",
+        )
+    if reason == JSON_READ_EMPTY:
+        return (
+            f"{path}: contains an empty JSON object",
+            "Restore the task fields (or recreate the task), then retry.",
+        )
+    if reason == JSON_READ_UNDECODABLE:
+        return (
+            f"{path}: not valid UTF-8 text",
+            "Re-save the file as UTF-8 (or restore it from git), then retry.",
+        )
+    return (f"{path}: could not be loaded", "Inspect the file, then retry.")
+
+
+def write_json(path: Path, data: dict) -> bool:
+    """Write dict to JSON file with pretty formatting.
+
+    The write is atomic: content goes to a temp file in the same directory
+    and is then renamed over the target. A crash or Ctrl-C mid-write leaves
+    the existing file intact rather than truncated, so a corrupted task.json
+    can never make a task silently vanish from `task.py list`.
+
+    Returns True on success, False on error.
+    """
+    return write_text_atomic(path, json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def write_text_atomic(path: Path, text: str) -> bool:
+    """Write text to a file atomically (temp in same dir, then replace).
+
+    The same never-truncate-in-place guarantee as :func:`write_json`, for the
+    Markdown state files that hold durable session state (journal files,
+    index.md). A crash or Ctrl-C mid-write leaves the previous content intact
+    instead of a half-written record that no retry can classify.
+
+    Returns True on success, False on error.
+    """
+    try:
+        fd, tmp = tempfile.mkstemp(
+            dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp"
+        )
+    except OSError:
+        return False
+
+    try:
+        try:
+            f = os.fdopen(fd, "w", encoding="utf-8")
+        except OSError:
+            # fdopen never took ownership of fd; close it ourselves.
+            os.close(fd)
+            raise
+        with f:
+            f.write(text)
+        os.replace(tmp, path)
+        return True
+    except OSError:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        return False
+    except BaseException:
+        # Ctrl-C mid-write: drop the temp file, then let the interrupt through.
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise

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}")