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

gww/actions/__init__.py

@@ -0,0 +1,224 @@
+"""Project action matching and execution.
+
+This package replaces the old ``actions/matcher.py`` and ``actions/executor.py``
+split with a single entry point (:func:`apply_actions`) that returns typed
+:class:`Action` objects grouped per matched rule. Commands iterate over the
+returned bundles and call :meth:`Action.run` for each action.
+
+Public surface:
+
+* :class:`Action` protocol and concrete :class:`CopyAction`,
+  :class:`CommandAction` (in :mod:`gww.actions.types`)
+* :class:`ActionError` raised by ``run()`` on failure
+* :class:`MatcherError` raised by :func:`apply_actions` when a rule predicate
+  or command template cannot be evaluated
+* :class:`RuleActions` — a rule that matched, its index/predicate/criticality,
+  and the executable actions for the requested kind
+* :func:`apply_actions` — match rules and return executable bundles
+* :data:`ActionKind` — literal distinguishing ``after_clone`` vs ``after_add``
+  vs ``before_remove`` (ADR-0011)
+"""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass, field
+from typing import Literal
+
+from gww.actions.types import (
+    Action,
+    ActionError,
+    CommandAction,
+    CopyAction,
+)
+from gww.config.validator import Action as RawAction
+from gww.config.validator import ProjectRule
+from gww.template.evaluator import (
+    TemplateError,
+    evaluate_command_template,
+    evaluate_predicate,
+)
+from gww.template.functions import (
+    TemplateContext,
+    create_function_registry,
+    create_project_functions,
+)
+
+
+class MatcherError(Exception):
+    """Raised when project matching or command-template evaluation fails."""
+
+
+ActionKind = Literal["after_clone", "after_add", "before_remove"]
+
+_KIND_TO_FIELD: dict[str, str] = {
+    "after_clone": "after_clone",
+    "after_add": "after_add",
+    "before_remove": "before_remove",
+}
+
+
+@dataclass
+class RuleActions:
+    """A matched project rule plus the actions to execute for one kind.
+
+    Carries enough context (index, predicate text, criticality flag) for the
+    CLI loop to attribute per-action failures back to the rule that produced
+    them, and to decide whether the command should exit 1.
+
+    Attributes:
+        index: Position of the rule in ``config.actions`` — used as the rule's
+            identifier in error messages.
+        predicate: The ``when:`` expression as it appears in the config; kept
+            verbatim for diagnostics.
+        critical: Per-rule criticality flag from :class:`ProjectRule`. When
+            ``True``, a failing action aborts the rule's remaining actions
+            and causes the command to exit 1.
+        actions: Executable actions for the requested ``kind``, in the order
+            they appear in the rule's ``after_clone``/``after_add``/
+            ``before_remove`` list.
+    """
+
+    index: int
+    predicate: str
+    critical: bool
+    actions: list[Action] = field(default_factory=list)
+
+
+__all__ = [
+    "Action",
+    "ActionError",
+    "ActionKind",
+    "CommandAction",
+    "CopyAction",
+    "MatcherError",
+    "RuleActions",
+    "apply_actions",
+]
+
+
+def _create_predicate_context(context: TemplateContext) -> dict[str, object]:
+    """Build the evaluation context shared by ``when`` predicates and command
+    templates.
+
+    Adds project-specific functions (``source_path``, ``current_worktree``,
+    ``file_exists``, ``dir_exists``, ``path_exists``) on top of the unified
+    URI/branch/tag registry seeded by ``context``.
+    """
+    functions: dict[str, object] = dict(create_function_registry(context))
+    functions.update(create_project_functions(context))
+    return functions
+
+
+def _build_action(
+    raw: RawAction,
+    context: dict[str, object],
+) -> Action:
+    """Turn a config-level :class:`Action` into a typed executable.
+
+    For ``copy`` actions the two template-evaluated args become
+    :class:`CopyAction`'s ``source`` and ``destination`` (both template-
+    evaluated, so ``source_path('local.properties')`` resolves to an absolute
+    path before the action runs). For ``command`` actions the template is
+    evaluated against ``context`` and parsed with :mod:`shlex` so the
+    resulting :class:`CommandAction` already holds the resolved argv.
+    """
+    if raw.action_type == "copy":
+        if len(raw.args) < 2:
+            raise MatcherError("copy requires source and destination arguments")
+        try:
+            source = evaluate_command_template(raw.args[0], context)
+        except TemplateError as e:
+            raise MatcherError(
+                f"Error evaluating copy source '{raw.args[0]}': {e}"
+            ) from e
+        try:
+            destination = evaluate_command_template(raw.args[1], context)
+        except TemplateError as e:
+            raise MatcherError(
+                f"Error evaluating copy destination '{raw.args[1]}': {e}"
+            ) from e
+        return CopyAction(source=source, destination=destination)
+
+    if raw.action_type == "command":
+        template = raw.args[0] if raw.args else ""
+        try:
+            evaluated = evaluate_command_template(template, context)
+        except TemplateError as e:
+            raise MatcherError(
+                f"Error evaluating command template '{template}': {e}"
+            ) from e
+        try:
+            parsed = shlex.split(evaluated)
+        except ValueError as e:
+            raise MatcherError(f"Error parsing command '{evaluated}': {e}") from e
+        if not parsed:
+            raise MatcherError("command requires at least command name")
+        return CommandAction(command=parsed[0], args=parsed[1:])
+
+    raise MatcherError(f"Unknown action type: {raw.action_type}")
+
+
+def apply_actions(
+    rules: list[ProjectRule],
+    context: TemplateContext,
+    kind: ActionKind,
+) -> list[RuleActions]:
+    """Match rules and return executable bundles for the given ``kind``.
+
+    A :class:`RuleActions` bundle is produced for every rule whose ``when``
+    predicate evaluates truthy, even when that rule has no actions for the
+    requested ``kind`` — the bundle's ``actions`` list is simply empty. This
+    keeps the CLI loop's failure-tracking symmetric: a rule that ran zero
+    actions still has a known index/criticality for the summary.
+
+    The ``context`` carries the URI, branch, tags, source path, and
+    destination path that ``when`` predicates and command templates evaluate
+    against. Callers (``clone``, ``add``, ``remove``) populate it from the
+    operation in progress; see :class:`TemplateContext` for the field-level
+    contract.
+
+    Args:
+        rules: Project rules from the validated config.
+        context: Evaluation context — see :class:`TemplateContext`.
+        kind: Which action list to read — ``"after_clone"``, ``"after_add"``,
+            or ``"before_remove"`` (ADR-0011).
+
+    Returns:
+        Matched rules paired with their typed actions, in config order. Each
+        bundle carries the rule's index, predicate text, and criticality so
+        the CLI can attribute failures and choose exit codes.
+
+    Raises:
+        MatcherError: If a ``when`` predicate or a ``command`` template fails
+            to evaluate. The CLI converts this to a config-error exit (2);
+            it is never swallowed.
+    """
+    eval_context = _create_predicate_context(context)
+
+    bundles: list[RuleActions] = []
+    for i, rule in enumerate(rules):
+        try:
+            matched = evaluate_predicate(rule.when, eval_context)
+        except TemplateError as e:
+            raise MatcherError(
+                f"Error evaluating 'when' for project rule {i}: {e}"
+            ) from e
+        if not matched:
+            continue
+
+        source_actions = getattr(rule, _KIND_TO_FIELD[kind])
+        actions: list[Action] = []
+        for raw in source_actions:
+            actions.append(_build_action(raw, eval_context))
+
+        bundles.append(
+            RuleActions(
+                index=i,
+                predicate=rule.when,
+                critical=rule.critical,
+                actions=actions,
+            )
+        )
+
+    return bundles

gww/actions/types.py

@@ -0,0 +1,187 @@
+"""Typed action objects executed by clone and add commands.
+
+Each action is a small class that knows how to run itself against a target
+directory. Actions are constructed by :func:`gww.actions.apply_actions`,
+which evaluates any predicate and command-template context for them.
+
+The concrete action classes cover the supported ``copy`` and ``command``
+action types from the YAML config (ADR-0012).
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Optional, Protocol
+
+
+class ActionError(Exception):
+    """Raised when an action fails to execute."""
+
+
+class Action(Protocol):
+    """Protocol every executable action implements.
+
+    Actions are run by the clone/add commands inside a ``for`` loop; calling
+    code is expected to wrap each invocation in its own try/except and decide
+    whether to surface the failure or continue with the remaining actions.
+    """
+
+    def run(
+        self,
+        source_dir: Optional[Path],
+        target_dir: Path,
+        pass_through_stdout: bool = False,
+    ) -> None:
+        """Execute the action against ``target_dir``.
+
+        Args:
+            source_dir: Path to the source repository. Currently unused by
+                the shipped action types but retained on the protocol to
+                avoid touching every call site (ADR-0012 §"Notes for future
+                readers").
+            target_dir: Path to operate on (source repo for ``after_clone``,
+                worktree for ``after_add`` and ``before_remove``).
+            pass_through_stdout: Only meaningful for :class:`CommandAction`.
+                When ``True``, the external command's stdout is inherited from
+                the parent (so the user sees its progress in real time) while
+                stderr stays captured for the :class:`ActionError` message.
+
+        Raises:
+            ActionError: If the action fails for any reason.
+        """
+        ...
+
+
+class CopyAction:
+    """Copy a file or directory tree from a resolved source into ``target_dir``.
+
+    The two constructor arguments are *template-evaluated* strings supplied
+    by :func:`gww.actions.apply_actions` (i.e. any ``source_path(extra)``,
+    ``current_worktree(extra)``, or absolute-literal reference has already
+    been resolved before the action is constructed). The operation itself
+    is selected by the resolved source's filesystem type — ``shutil.copy2``
+    (silent overwrite) for files, ``shutil.copytree(src, dst,
+    dirs_exist_ok=True)`` (merge into an existing directory) for directory
+    trees. The destination's parent is created with
+    ``mkdir(parents=True, exist_ok=True)`` before either operation runs.
+
+    Attributes:
+        source: Absolute source path (file or directory) as returned by the
+            template engine — no further template substitution happens here.
+        destination: Destination path relative to ``target_dir``. An absolute
+            destination bypasses the relative resolution and is used as-is.
+    """
+
+    def __init__(self, source: str, destination: str) -> None:
+        self.source = source
+        self.destination = destination
+
+    def run(
+        self,
+        source_dir: Optional[Path],
+        target_dir: Path,
+        pass_through_stdout: bool = False,
+    ) -> None:
+        """Copy ``source`` to ``target_dir / destination``.
+
+        Raises:
+            ActionError: If the source is missing, is neither a file nor a
+                directory, or the copy operation fails.
+        """
+        del source_dir, pass_through_stdout  # unused for copy
+        literal = Path(self.source).expanduser()
+        dest_path = Path(self.destination)
+        if not dest_path.is_absolute():
+            dest_path = target_dir / dest_path
+
+        if not os.path.lexists(literal):
+            raise ActionError(f"Source path not found for copy: {literal}")
+
+        # A broken symlink has ``is_symlink() == True`` but ``exists() ==
+        # False`` (the latter follows the link). ``Path.resolve()`` follows
+        # symlinks too, so a broken link resolves to its (non-existent)
+        # target — that would land in the "not found" branch above if we
+        # resolved first. Detect the broken-symlink case here so the error
+        # points at the symlink, not the missing target.
+        if literal.is_symlink() and not literal.exists():
+            raise ActionError(
+                f"Source is neither a file nor a directory for copy: {literal}"
+            )
+
+        source_path = literal.resolve()
+
+        if source_path.is_file():
+            dest_path.parent.mkdir(parents=True, exist_ok=True)
+            try:
+                shutil.copy2(source_path, dest_path)
+            except OSError as e:
+                raise ActionError(
+                    f"Failed to copy {source_path} to {dest_path}: {e}"
+                ) from e
+            return
+
+        if source_path.is_dir():
+            try:
+                shutil.copytree(source_path, dest_path, dirs_exist_ok=True)
+            except OSError as e:
+                raise ActionError(
+                    f"Failed to copy directory {source_path} to {dest_path}: {e}"
+                ) from e
+            return
+
+        raise ActionError(
+            f"Source is neither a file nor a directory for copy: {source_path}"
+        )
+
+
+class CommandAction:
+    """Run an external command with ``target_dir`` as the working directory.
+
+    Attributes:
+        command: Executable name or path (already evaluated and shlex-split).
+        args: Arguments to pass to the command.
+    """
+
+    def __init__(self, command: str, args: list[str]) -> None:
+        self.command = command
+        self.args = args
+
+    def run(
+        self,
+        source_dir: Optional[Path],
+        target_dir: Path,
+        pass_through_stdout: bool = False,
+    ) -> None:
+        """Invoke the command in ``target_dir``.
+
+        Raises:
+            ActionError: If the command exits non-zero, the executable is
+                missing, or the subprocess cannot be started.
+        """
+        del source_dir  # commands always run from target_dir
+        cmd = [self.command] + self.args
+
+        try:
+            result = subprocess.run(
+                cmd,
+                cwd=target_dir,
+                stdout=None if pass_through_stdout else subprocess.PIPE,
+                stderr=None if pass_through_stdout else subprocess.PIPE,
+                text=True,
+                check=False,
+            )
+        except FileNotFoundError as e:
+            raise ActionError(f"Command not found: {self.command}") from e
+        except OSError as e:
+            raise ActionError(f"Failed to execute command: {e}") from e
+
+        if result.returncode != 0:
+            stderr_text = (result.stderr or "").strip()
+            raise ActionError(
+                f"Command failed: {' '.join(cmd)}\n"
+                f"Exit code: {result.returncode}\n"
+                f"Stderr: {stderr_text}"
+            )

gww/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI module for sgw commands."""

gww/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command implementations."""

gww/cli/commands/add.py

@@ -0,0 +1,122 @@
+"""Add worktree command implementation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from gww.actions import ActionError, MatcherError, apply_actions
+from gww.cli.context import (
+    CommandContext,
+    CommandExit,
+    RuleFailure,
+    exit_on_error,
+    load_config_or_exit,
+    parse_uri_or_exit,
+    print_action_failure_summary,
+    resolve_source_repo_or_exit,
+)
+from gww.config.resolver import ResolverError, resolve_worktree_path
+from gww.git.branch import (
+    BranchExistsError,
+    branch_exists,
+    create_branch,
+)
+from gww.git.repository import (
+    GitCommandError,
+    get_current_commit,
+)
+from gww.git.worktree import WorktreeExistsError, add_worktree
+from gww.template.functions import TemplateContext
+
+
+@exit_on_error
+def run_add(ctx: CommandContext) -> int:
+    """Execute the add worktree command.
+
+    Args:
+        ctx: Per-invocation command context.
+
+    Returns:
+        Exit code (0 for success, 1 for runtime/action failure, 2 for config
+        error).
+    """
+    if ctx.branch is None:
+        raise CommandExit(1, "Error: Missing branch name.")
+
+    cwd = Path.cwd()
+    source_path, remote_uri = resolve_source_repo_or_exit(cwd)
+    uri = parse_uri_or_exit(remote_uri)
+    config = load_config_or_exit()
+
+    if not branch_exists(source_path, ctx.branch):
+        if ctx.create_branch:
+            try:
+                current_commit = get_current_commit(cwd)
+                create_branch(source_path, ctx.branch, current_commit)
+                ctx.verbose_msg(
+                    f"Created branch '{ctx.branch}' from {current_commit[:8]}"
+                )
+            except (GitCommandError, BranchExistsError) as e:
+                raise CommandExit(1, f"Error creating branch: {e}") from e
+        else:
+            raise CommandExit(
+                1,
+                f"Error: Branch '{ctx.branch}' not found. "
+                "Use -c/--create-branch to create from current commit.",
+            )
+
+    try:
+        worktree_path = resolve_worktree_path(config, uri, ctx.branch, ctx.tags)
+    except ResolverError as e:
+        raise CommandExit(2, f"Error resolving worktree path: {e}") from e
+
+    ctx.verbose_msg(f"Adding worktree for '{ctx.branch}' at {worktree_path}...")
+
+    try:
+        add_worktree(
+            source_path,
+            worktree_path,
+            ctx.branch,
+            pass_through_stdout=not ctx.quiet,
+        )
+    except (WorktreeExistsError, GitCommandError) as e:
+        raise CommandExit(1, f"Error adding worktree: {e}") from e
+
+    failures: list[RuleFailure] = []
+    if config.actions:
+        context = TemplateContext(
+            uri=uri,
+            branch=ctx.branch,
+            source_path=source_path,
+            dest_path=worktree_path,
+            tags=ctx.tags,
+        )
+        try:
+            rule_bundles = apply_actions(config.actions, context, kind="after_add")
+        except MatcherError as e:
+            raise CommandExit(2, f"Config error: {e}") from e
+
+        if rule_bundles:
+            ctx.verbose_msg(f"Executing {len(rule_bundles)} rule(s)...")
+            for bundle in rule_bundles:
+                for action in bundle.actions:
+                    try:
+                        action.run(
+                            source_dir=source_path,
+                            target_dir=worktree_path,
+                            pass_through_stdout=not ctx.quiet,
+                        )
+                    except ActionError as e:
+                        failures.append(RuleFailure(bundle, action, e))
+                        if bundle.critical:
+                            break
+
+    if failures:
+        print_action_failure_summary(failures)
+
+    if not failures:
+        ctx.say(str(worktree_path))
+
+    if any(f.bundle.critical for f in failures):
+        raise CommandExit(1, "")
+    return 0

gww/cli/commands/clone.py

@@ -0,0 +1,97 @@
+"""Clone command implementation."""
+
+from __future__ import annotations
+
+from gww.actions import ActionError, MatcherError, apply_actions
+from gww.cli.context import (
+    CommandContext,
+    CommandExit,
+    RuleFailure,
+    exit_on_error,
+    load_config_or_exit,
+    parse_uri_or_exit,
+    print_action_failure_summary,
+)
+from gww.config.resolver import ResolverError, resolve_source_path
+from gww.git.repository import (
+    GitCommandError,
+    clone_repository,
+    try_get_current_branch,
+)
+from gww.template.functions import TemplateContext
+
+
+@exit_on_error
+def run_clone(ctx: CommandContext) -> int:
+    """Execute the clone command.
+
+    Args:
+        ctx: Per-invocation command context.
+
+    Returns:
+        Exit code (0 for success, 1 for runtime/action failure, 2 for config
+        error).
+    """
+    if ctx.uri is None:
+        raise CommandExit(1, "Error: Missing repository URI.")
+
+    uri = parse_uri_or_exit(ctx.uri)
+    config = load_config_or_exit()
+
+    try:
+        source_path = resolve_source_path(config, uri, ctx.tags)
+    except ResolverError as e:
+        raise CommandExit(2, f"Error resolving source path: {e}") from e
+
+    if source_path.exists():
+        raise CommandExit(
+            1,
+            f"Error: Repository already exists at: {source_path}",
+        )
+
+    ctx.verbose_msg(f"Cloning {ctx.uri} to {source_path}...")
+
+    try:
+        clone_repository(ctx.uri, source_path, pass_through_stdout=not ctx.quiet)
+    except GitCommandError as e:
+        raise CommandExit(1, f"Error cloning repository: {e}") from e
+
+    failures: list[RuleFailure] = []
+    if config.actions:
+        branch = try_get_current_branch(source_path)
+        context = TemplateContext(
+            uri=uri,
+            branch=branch,
+            source_path=source_path,
+            dest_path=source_path,
+            tags=ctx.tags,
+        )
+        try:
+            rule_bundles = apply_actions(config.actions, context, kind="after_clone")
+        except MatcherError as e:
+            raise CommandExit(2, f"Config error: {e}") from e
+
+        if rule_bundles:
+            ctx.verbose_msg(f"Executing {len(rule_bundles)} rule(s)...")
+            for bundle in rule_bundles:
+                for action in bundle.actions:
+                    try:
+                        action.run(
+                            source_dir=None,
+                            target_dir=source_path,
+                            pass_through_stdout=not ctx.quiet,
+                        )
+                    except ActionError as e:
+                        failures.append(RuleFailure(bundle, action, e))
+                        if bundle.critical:
+                            break
+
+    if failures:
+        print_action_failure_summary(failures)
+
+    if not failures:
+        ctx.say(str(source_path))
+
+    if any(f.bundle.critical for f in failures):
+        raise CommandExit(1, "")
+    return 0