git-worktree-wrapper 0.1.0__py3-none-any.whl

gww/config/loader.py

@@ -0,0 +1,305 @@
+"""Configuration file loading using ruamel.yaml."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+from ruamel.yaml import YAML
+from ruamel.yaml.error import YAMLError
+
+from gww.utils.xdg import get_config_path
+
+
+class ConfigLoadError(Exception):
+    """Raised when config file cannot be loaded."""
+
+    pass
+
+
+class ConfigNotFoundError(ConfigLoadError):
+    """Raised when config file does not exist."""
+
+    pass
+
+
+def _create_yaml() -> YAML:
+    """Create a YAML instance configured for round-trip parsing.
+
+    Returns:
+        Configured YAML instance.
+    """
+    yaml = YAML(typ="rt")  # Round-trip mode preserves comments and formatting
+    yaml.preserve_quotes = True
+    yaml.indent(mapping=2, sequence=4, offset=2)
+    return yaml
+
+
+def load_config(config_path: Optional[Path] = None) -> dict[str, Any]:
+    """Load configuration from YAML file.
+
+    Args:
+        config_path: Path to config file. If None, uses default XDG path.
+
+    Returns:
+        Parsed configuration dictionary.
+
+    Raises:
+        ConfigNotFoundError: If config file does not exist.
+        ConfigLoadError: If config file cannot be parsed.
+    """
+    if config_path is None:
+        config_path = get_config_path()
+
+    if not config_path.exists():
+        raise ConfigNotFoundError(f"Config file not found: {config_path}")
+
+    yaml = _create_yaml()
+
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            data = yaml.load(f)
+    except YAMLError as e:
+        raise ConfigLoadError(f"Invalid YAML in config file {config_path}: {e}") from e
+    except OSError as e:
+        raise ConfigLoadError(f"Cannot read config file {config_path}: {e}") from e
+
+    if data is None:
+        # Empty file or only comments
+        return {}
+
+    if not isinstance(data, dict):
+        raise ConfigLoadError(
+            f"Config file must contain a mapping, got {type(data).__name__}"
+        )
+
+    return dict(data)
+
+
+def save_config(config: dict[str, Any], config_path: Optional[Path] = None) -> Path:
+    """Save configuration to YAML file.
+
+    Args:
+        config: Configuration dictionary to save.
+        config_path: Path to config file. If None, uses default XDG path.
+
+    Returns:
+        Path where config was saved.
+
+    Raises:
+        ConfigLoadError: If config file cannot be written.
+    """
+    if config_path is None:
+        config_path = get_config_path()
+
+    # Ensure parent directory exists
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    yaml = _create_yaml()
+
+    try:
+        with open(config_path, "w", encoding="utf-8") as f:
+            yaml.dump(config, f)
+    except OSError as e:
+        raise ConfigLoadError(f"Cannot write config file {config_path}: {e}") from e
+
+    return config_path
+
+
+def config_exists(config_path: Optional[Path] = None) -> bool:
+    """Check if config file exists.
+
+    Args:
+        config_path: Path to config file. If None, uses default XDG path.
+
+    Returns:
+        True if config file exists.
+    """
+    if config_path is None:
+        config_path = get_config_path()
+    return config_path.exists()
+
+
+DEFAULT_CONFIG_TEMPLATE = """\
+# GWW (Git Worktree Wrapper) Configuration
+# =========================================
+#
+# This file configures how gww manages your git repositories and worktrees.
+# Location: {config_path}
+
+# Template Functions and Variables Available
+# ===========================================
+#
+# SHARED FUNCTIONS (available in templates and 'when' conditions):
+# ----------------------------------------------------------------------------------
+#
+# URI Functions:
+#   path(n)              - URI path segment at index n (0-based, negative for reverse)
+#                         Example: path(-1) returns "repo", path(0) returns "user"
+#
+#   host()               - URI hostname (string)
+#                         Example: host() returns "github.com" from "https://github.com/user/repo"
+#
+#   uri()                - Full URI string (string)
+#                         Example: uri() returns "https://github.com/user/repo.git"
+#
+#   port()               - URI port number (string, empty if not specified)
+#                         Example: port() returns "3000" from "http://git.example.com:3000/path"
+#
+#   protocol()           - URI protocol/scheme (string)
+#                         Example: protocol() returns "https", "ssh", "git"
+#
+# Branch Functions (require branch context, available in worktree templates):
+#   branch()             - Current branch name (as-is)
+#                         Example: branch() from "feature/new-ui" → "feature/new-ui"
+#
+#   norm_branch(sep)     - Branch name with "/" replaced
+#                         - norm_branch(): replaces "/" with "-"
+#                         - norm_branch("_"): replaces "/" with "_"
+#                         Example: norm_branch() from "feature/new-ui" → "feature-new-ui"
+#
+# Utility Functions (template-only, not available in 'when' conditions):
+#   time_id(fmt)         - Generate datetime-based identifier string
+#                         The datetime is captured on first call and cached for subsequent
+#                         calls within the same template evaluation session.
+#                         - time_id(): default format "%Y%m%d-%H%M.%S" → "20260120-2134.03"
+#                         - time_id("%Y-%m-%d"): custom format → "2026-01-20"
+#                         - time_id("%H%M%S"): time only → "213403"
+#                         Format codes: https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes
+#                         Useful for creating unique branch/worktree names with timestamps.
+#
+# Tag Functions:
+#   tag(name)            - Get tag value by name (returns empty string if not set)
+#                         Tags are passed via --tag option
+#                         Example: tag("env") returns "prod" if --tag env=prod was used
+#
+#   tag_exist(name)      - Check if tag exists (returns True/False)
+#                         Useful in 'when' conditions for conditional routing and path templates
+#                         Example: tag_exist("env") returns True if --tag env was used
+#
+# PROJECT-SPECIFIC FUNCTIONS (only in project 'when' conditions):
+# ---------------------------------------------------------
+#   source_path(extra?)   - Absolute path to the source repository (string),
+#                           optionally joined with `extra` (which may itself be
+#                           a template). The CLI populates this for project
+#                           predicates; it is the same value in clone, add,
+#                           and before_remove.
+#                           Examples:
+#                             source_path() returns "/home/user/Developer/sources/github/user/repo"
+#                             source_path("local.properties")
+#                               returns "/home/user/Developer/sources/github/user/repo/local.properties"
+#
+#   current_worktree(extra?) - Absolute path to the operation target (the
+#                           freshly-cloned source for after_clone; the
+#                           worktree for after_add and before_remove),
+#                           optionally joined with `extra`.
+#                           Examples:
+#                             After clone: current_worktree() returns "/home/user/Developer/sources/github/user/repo"
+#                             After add:   current_worktree() returns "/home/user/Developer/worktrees/github/user/repo/feature-branch"
+#
+#   file_exists(path)    - Check if file exists in source repository (returns True/False)
+#                         Path is relative to source repository root
+#                         Example: file_exists("package.json") checks for package.json in repo
+#
+#   dir_exists(path)     - Check if directory exists in source repository (returns True/False)
+#                         Path is relative to source repository root
+#                         Example: dir_exists("src") checks for src/ directory in repo
+#
+#   path_exists(path)    - Check if path exists (file or directory) in source repository
+#                         Path is relative to source repository root
+#                         Example: path_exists("README.md") checks for README.md in repo
+
+# Default paths for sources (cloned repositories) and worktrees
+default_sources: ~/Developer/sources/default/path(-2)/path(-1)
+default_worktrees: ~/Developer/worktrees/default/path(-2)/path(-1)/norm_branch()
+
+# Source routing rules (optional)
+# Routes repositories to different locations based on URI conditions
+# Uncomment and customize as needed:
+
+# sources:
+#   github:
+#     when: '"github" in host()'
+#     sources: ~/Developer/sources/github/path(-2)/path(-1)
+#     worktrees: ~/Developer/worktrees/github/path(-2)/path(-1)/norm_branch()
+#
+#   gitlab:
+#     when: '"gitlab" in host()'
+#     sources: ~/Developer/sources/gitlab/path(-3)/path(-2)/path(-1)
+#     worktrees: ~/Developer/worktrees/gitlab/path(-3)/path(-2)/path(-1)/norm_branch()
+#
+#   custom:
+#     when: 'path(0) == "myorg"'
+#     sources: ~/Developer/sources/custom/path(-2)/path(-1)
+#
+#   # Tag-based routing examples:
+#   review:
+#     when: 'tag_exist("review")
+#     sources: ~/Developer/sources/custom/path(-2)/path(-1)
+#     worktrees: ~/Developer/worktrees/review/path(-2)/path(-1)/norm_branch()
+#
+#   # Tag-based path templates:
+#   tagged_sources:
+#     when: 'tag_exist("worktree-name")'
+#     sources: ~/Developer/sources/tag("project")/path(-2)/path(-1)
+#     worktrees: ~/Developer/worktrees/tag("project")/path(-2)/path(-1)/branch()-tag("worktree-name")
+#
+#   # Time-based worktree names (useful for temporary or timestamped worktrees):
+#   timestamped:
+#     when: 'tag_exist("timestamp")'
+#     worktrees: ~/Developer/worktrees/path(-2)/path(-1)/norm_branch()-time_id()
+#
+# Actions (optional)
+# Execute actions after clone or worktree creation based on project detection
+#
+# Action syntax:
+#   - command: "single string with optional template functions"
+#   - copy: ["source-template", "destination-template"]  # templates are evaluated first
+#   - Template functions are evaluated first; for `command` the result is
+#     then parsed as shell arguments, for `copy` the resolved source and
+#     destination are passed to the copy action.
+#   - Commands always execute with current_worktree() as the current working directory.
+#   - Use quotes for arguments with spaces: command: "echo 'hello world'"
+#   - Available functions: current_worktree(), source_path(), tag("name"), etc.
+#
+# Uncomment and customize as needed:
+
+# actions:
+#   - when: 'file_exists("local.properties")'
+#     after_clone:
+#       - copy: ["~/sources/default-local.properties", "local.properties"]
+#     after_add:
+#       - copy: ["source_path('local.properties')", "local.properties"]
+#       - command: "./setup-env.sh"
+#
+#   # Tag-based actions:
+#   - when: not file_exists("CLAUDE.md") and tag_exist("use-claude")
+#     after_clone:
+#       - command: "claude init"
+#     after_add:
+#       - copy: ["source_path('CLAUDE.md')", "CLAUDE.md"]
+#
+#   # Commands with template functions:
+#   - when: file_exists("CLAUDE.md") and tag_exist("use-claude") and tag_exist("review")
+#     after_add:
+#       - command: "claude -p tag('prompt') --cwd current_worktree()"
+#
+#   # Simple command with current_worktree:
+#   - when: 'file_exists("package.json")'
+#     after_add:
+#       - command: "npm install --prefix current_worktree()"
+"""
+
+
+def get_default_config(config_path: Optional[Path] = None) -> str:
+    """Get default configuration file content.
+
+    Args:
+        config_path: Path where config will be saved (for documentation).
+
+    Returns:
+        Default configuration YAML content.
+    """
+    if config_path is None:
+        config_path = get_config_path()
+    return DEFAULT_CONFIG_TEMPLATE.format(config_path=config_path)

gww/config/resolver.py

@@ -0,0 +1,188 @@
+"""Configuration resolver for path template evaluation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+from gww.config.validator import Config, SourceRule
+from gww.template.evaluator import TemplateError, evaluate_predicate, evaluate_template
+from gww.template.functions import TemplateContext, create_function_registry
+from gww.utils.uri import ParsedURI
+
+
+class ResolverError(Exception):
+    """Raised when path resolution fails."""
+
+    pass
+
+
+def _expand_home(path: str) -> str:
+    """Expand ~ to home directory in path string.
+
+    Args:
+        path: Path string that may contain ~.
+
+    Returns:
+        Path with ~ expanded to home directory.
+    """
+    if path.startswith("~"):
+        return str(Path(path).expanduser())
+    return path
+
+
+def _build_uri_context(uri: ParsedURI, tags: dict[str, str] = {}) -> dict[str, Any]:
+    """Build evaluation context for URI predicates.
+
+    Uses the unified FunctionRegistry to provide shared functions:
+    - URI functions: host(), port(), protocol(), uri(), path(index)
+    - Tag functions: tag(name), tag_exist(name)
+
+    Args:
+        uri: Parsed URI object.
+        tags: Optional dictionary of tag key-value pairs.
+
+    Returns:
+        Dictionary of context functions for predicate evaluation.
+    """
+    context = TemplateContext(uri=uri, tags=tags)
+    return create_function_registry(context)
+
+
+def find_matching_source_rule(
+    config: Config,
+    uri: ParsedURI,
+    tags: dict[str, str] = {},
+) -> Optional[SourceRule]:
+    """Find the first matching source rule for a URI.
+
+    Args:
+        config: Validated configuration.
+        uri: Parsed URI to match against.
+        tags: Optional dictionary of tag key-value pairs.
+
+    Returns:
+        Matching SourceRule, or None if no match.
+
+    Raises:
+        ResolverError: If predicate evaluation fails.
+    """
+    context = _build_uri_context(uri, tags)
+
+    for name, rule in config.sources.items():
+        try:
+            if evaluate_predicate(rule.when, context):
+                return rule
+        except TemplateError as e:
+            raise ResolverError(
+                f"Error evaluating 'when' for source rule '{name}': {e}"
+            ) from e
+
+    return None
+
+
+def resolve_source_path(
+    config: Config,
+    uri: ParsedURI,
+    tags: dict[str, str] = {},
+) -> Path:
+    """Resolve the source checkout path for a URI.
+
+    Args:
+        config: Validated configuration.
+        uri: Parsed URI for the repository.
+        tags: Optional dictionary of tag key-value pairs.
+
+    Returns:
+        Absolute path where repository should be cloned.
+
+    Raises:
+        ResolverError: If path resolution fails.
+    """
+    # Find matching rule or use default
+    rule = find_matching_source_rule(config, uri, tags)
+
+    if rule and rule.sources:
+        template = rule.sources
+    else:
+        template = config.default_sources
+
+    # Create context and evaluate template
+    context = TemplateContext(uri=uri, tags=tags)
+
+    try:
+        path_str = evaluate_template(template, context)
+    except TemplateError as e:
+        raise ResolverError(f"Error evaluating source path template: {e}") from e
+
+    # Expand ~ and resolve to absolute path
+    path_str = _expand_home(path_str)
+    return Path(path_str).resolve()
+
+
+def resolve_worktree_path(
+    config: Config,
+    uri: ParsedURI,
+    branch: str,
+    tags: dict[str, str] = {},
+) -> Path:
+    """Resolve the worktree path for a branch.
+
+    Args:
+        config: Validated configuration.
+        uri: Parsed URI for the repository.
+        branch: Branch name for the worktree.
+        tags: Optional dictionary of tag key-value pairs.
+
+    Returns:
+        Absolute path where worktree should be created.
+
+    Raises:
+        ResolverError: If path resolution fails.
+    """
+    # Find matching rule or use default
+    rule = find_matching_source_rule(config, uri, tags)
+
+    if rule and rule.worktrees:
+        template = rule.worktrees
+    else:
+        template = config.default_worktrees
+
+    # Create context and evaluate template
+    context = TemplateContext(
+        uri=uri,
+        branch=branch,
+        tags=tags,
+    )
+
+    try:
+        path_str = evaluate_template(template, context)
+    except TemplateError as e:
+        raise ResolverError(f"Error evaluating worktree path template: {e}") from e
+
+    # Expand ~ and resolve to absolute path
+    path_str = _expand_home(path_str)
+    return Path(path_str).resolve()
+
+
+def get_source_path_for_worktree(
+    config: Config,
+    uri: ParsedURI,
+    tags: dict[str, str] = {},
+) -> Path:
+    """Get the source path that corresponds to a worktree's repository.
+
+    This is useful when working from a worktree to find its source repository.
+
+    Args:
+        config: Validated configuration.
+        uri: Parsed URI for the repository.
+        tags: Optional dictionary of tag key-value pairs.
+
+    Returns:
+        Absolute path to the source repository.
+
+    Raises:
+        ResolverError: If path resolution fails.
+    """
+    return resolve_source_path(config, uri, tags)