@ahmed-g-gad/apothem 0.1.1

package/src/apothem/harnesses/_shared/install_driver_apply.py

@@ -0,0 +1,612 @@
+# SPDX-License-Identifier: MIT
+
+"""Per-mode install-entry appliers (write_text, replace_tree, merge_tree, agents, commands)."""
+
+from __future__ import annotations
+
+import contextlib
+import shutil
+from pathlib import Path
+
+from apothem.lib.propagation import (
+    InstallEntry,
+    resolve_target,
+)
+
+from .install_driver_backup import _replace_path, write_bytes_safely
+from .install_driver_converters import (
+    _codex_agent_text,
+    _gemini_agent_text,
+    _gemini_command_text,
+    _generated_skill_text,
+    _native_markdown_command_text,
+    _opencode_agent_text,
+    _qwen_agent_text,
+)
+from .install_driver_merge import (
+    _apply_operator_owned_file,
+    render_content_tokens,
+    write_text_safely,
+)
+from .install_driver_pathsafety import (
+    _allowed_write_root,
+    _root_for,
+    _validate_target_path,
+)
+from .install_driver_treeops import (
+    _directory_contents_equal,
+    _write_single_file_directory,
+    replace_tree,
+)
+from .install_driver_types import (
+    AuthorizeFn,
+    IgnoreFn,
+    MaterializationResult,
+    _is_excluded_path,
+    _result,
+    resolve_source,
+)
+
+
+def apply_write_text(
+    entry: InstallEntry,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+    authorize: AuthorizeFn | None = None,
+) -> list[MaterializationResult]:
+    """Apply a single ``write_text`` install entry as a template copy.
+
+    Operator-owned targets (e.g. ``settings.json``, ``hooks.json``) route
+    through the key-preserving merge with a unified diff and the
+    destructive-authorization gate; Apothem-owned targets (e.g. plugin
+    metadata) are written directly.
+    """
+    target = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    src = resolve_source(entry.source)
+    if not src.is_file():
+        return [
+            _result(
+                "skipped",
+                "write_text",
+                target,
+                "source file does not exist",
+                source=src,
+            )
+        ]
+    root = _root_for(harness_root, project_root)
+    allowed_root = _allowed_write_root(harness_root, project_root)
+    if entry.ownership_class == "operator-owned":
+        return _apply_operator_owned_file(
+            entry,
+            target=target,
+            src=src,
+            root=root,
+            harness_name=harness_name,
+            allowed_root=allowed_root,
+            authorize=authorize,
+            harness_root=harness_root,
+            project_root=project_root,
+        )
+    return [
+        write_text_safely(
+            target,
+            render_content_tokens(
+                src.read_text(encoding="utf-8"),
+                harness_root=harness_root,
+                project_root=project_root,
+            ),
+            install_root=root,
+            harness_name=harness_name,
+            allowed_root=allowed_root,
+        )
+    ]
+
+
+def apply_replace_tree(
+    entry: InstallEntry,
+    ignore: IgnoreFn,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+) -> list[MaterializationResult]:
+    """Apply a single ``replace_tree`` install entry."""
+    src = resolve_source(entry.source)
+    dst = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    return [
+        replace_tree(
+            src,
+            dst,
+            ignore,
+            install_root=_root_for(harness_root, project_root),
+            harness_name=harness_name,
+            allowed_root=_allowed_write_root(harness_root, project_root),
+        )
+    ]
+
+
+def apply_merge_tree_entries(
+    entry: InstallEntry,
+    ignore: IgnoreFn,
+    exclude: list[str],
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+) -> list[MaterializationResult]:
+    """Merge a source directory by replacing only its direct child entries."""
+    src = resolve_source(entry.source)
+    dst = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    if not src.is_dir():
+        return [
+            _result(
+                "skipped",
+                "merge_tree_entries",
+                dst,
+                "source directory does not exist",
+                source=src,
+            )
+        ]
+    allowed_root = _allowed_write_root(harness_root, project_root)
+    target_error = _validate_target_path(
+        dst,
+        allowed_root=allowed_root,
+        operation="merge_tree_entries",
+    )
+    if target_error is not None:
+        return [target_error]
+    dst.mkdir(parents=True, exist_ok=True)
+    root = _root_for(harness_root, project_root)
+    results: list[MaterializationResult] = []
+    for source_path in sorted(src.iterdir()):
+        if _is_excluded_path(source_path, exclude):
+            continue
+        # The copytree ignore callback only runs for nested directory copies.
+        if source_path.name in ignore(str(src), [source_path.name]):
+            continue
+        target = dst / source_path.name
+        if source_path.is_dir():
+            if _directory_contents_equal(source_path, target, ignore):
+                results.append(
+                    _result(
+                        "unchanged",
+                        "merge_tree_entries",
+                        target,
+                        "directory already matches",
+                        source=source_path,
+                    )
+                )
+                continue
+            removed = _replace_path(
+                target,
+                install_root=root,
+                harness_name=harness_name,
+                allowed_root=allowed_root,
+            )
+            if removed is not None and removed.outcome == "error":
+                results.append(removed)
+                continue
+            shutil.copytree(source_path, target, ignore=ignore)
+            results.append(
+                _result(
+                    "updated" if removed else "created",
+                    "merge_tree_entries",
+                    target,
+                    "copied directory entry",
+                    source=source_path,
+                    backup_path=(
+                        Path(removed.backup_path)
+                        if removed and removed.backup_path
+                        else None
+                    ),
+                )
+            )
+        elif source_path.is_file():
+            data = source_path.read_bytes()
+            if b"${" in data:
+                # Render install-time path tokens in text entries (e.g. the
+                # statusline command pointing at its installed render script).
+                with contextlib.suppress(UnicodeDecodeError):
+                    data = render_content_tokens(
+                        data.decode("utf-8"),
+                        harness_root=harness_root,
+                        project_root=project_root,
+                    ).encode("utf-8")
+            results.append(
+                write_bytes_safely(
+                    target,
+                    data,
+                    install_root=root,
+                    harness_name=harness_name,
+                    operation="merge_tree_entries",
+                    source=source_path,
+                    allowed_root=allowed_root,
+                )
+            )
+    return results
+
+
+def apply_command_skills(
+    entry: InstallEntry,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+) -> list[MaterializationResult]:
+    """Install Markdown command files as native skill directories."""
+    src = resolve_source(entry.source)
+    dst = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    if not src.is_dir():
+        return [
+            _result(
+                "skipped",
+                "command_skills",
+                dst,
+                "source directory does not exist",
+                source=src,
+            )
+        ]
+    allowed_root = _allowed_write_root(harness_root, project_root)
+    target_error = _validate_target_path(
+        dst,
+        allowed_root=allowed_root,
+        operation="command_skills",
+    )
+    if target_error is not None:
+        return [target_error]
+    dst.mkdir(parents=True, exist_ok=True)
+    root = _root_for(harness_root, project_root)
+    results: list[MaterializationResult] = []
+    for source_path in sorted(src.glob("*.md")):
+        if source_path.name in _COHORT_DOC_FILES:
+            continue
+        skill_dir = dst / source_path.stem
+        results.append(
+            _write_single_file_directory(
+                skill_dir,
+                "SKILL.md",
+                _generated_skill_text(
+                    source_path,
+                    harness_name=harness_name,
+                    install_root=root,
+                ),
+                root=root,
+                harness_name=harness_name,
+                operation="command_skills",
+                source=source_path,
+                allowed_root=allowed_root,
+            )
+        )
+    return results
+
+
+#: Documentation companions that live beside cohort members but are never
+#: materialized as members themselves.
+_COHORT_DOC_FILES: frozenset[str] = frozenset({"README.md", "AGENTS.md"})
+
+
+def apply_codex_agents(
+    entry: InstallEntry,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+) -> list[MaterializationResult]:
+    """Install Markdown agent files as Codex TOML custom agents."""
+    src = resolve_source(entry.source)
+    dst = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    if not src.is_dir():
+        return [
+            _result(
+                "skipped",
+                "codex_agents",
+                dst,
+                "source directory does not exist",
+                source=src,
+            )
+        ]
+    allowed_root = _allowed_write_root(harness_root, project_root)
+    target_error = _validate_target_path(
+        dst,
+        allowed_root=allowed_root,
+        operation="codex_agents",
+    )
+    if target_error is not None:
+        return [target_error]
+    dst.mkdir(parents=True, exist_ok=True)
+    root = _root_for(harness_root, project_root)
+    results: list[MaterializationResult] = []
+    for source_path in sorted(src.glob("*.md")):
+        if source_path.name in _COHORT_DOC_FILES:
+            continue
+        stale_markdown = dst / source_path.name
+        removed = _replace_path(
+            stale_markdown,
+            install_root=root,
+            harness_name=harness_name,
+            allowed_root=allowed_root,
+        )
+        if removed is not None:
+            results.append(removed)
+            if removed.outcome == "error":
+                continue
+        target = dst / f"{source_path.stem}.toml"
+        results.append(
+            write_bytes_safely(
+                target,
+                _codex_agent_text(source_path).encode("utf-8"),
+                install_root=root,
+                harness_name=harness_name,
+                operation="codex_agents",
+                source=source_path,
+                allowed_root=allowed_root,
+            )
+        )
+    return results
+
+
+def apply_gemini_agents(
+    entry: InstallEntry,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+) -> list[MaterializationResult]:
+    """Install normalized Gemini CLI Markdown subagent definitions."""
+    src = resolve_source(entry.source)
+    dst = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    if not src.is_dir():
+        return [
+            _result(
+                "skipped",
+                "gemini_agents",
+                dst,
+                "source directory does not exist",
+                source=src,
+            )
+        ]
+    allowed_root = _allowed_write_root(harness_root, project_root)
+    target_error = _validate_target_path(
+        dst,
+        allowed_root=allowed_root,
+        operation="gemini_agents",
+    )
+    if target_error is not None:
+        return [target_error]
+    dst.mkdir(parents=True, exist_ok=True)
+    root = _root_for(harness_root, project_root)
+    results: list[MaterializationResult] = []
+    for source_path in sorted(src.glob("*.md")):
+        if source_path.name in _COHORT_DOC_FILES:
+            continue
+        target = dst / source_path.name
+        results.append(
+            write_bytes_safely(
+                target,
+                _gemini_agent_text(source_path).encode("utf-8"),
+                install_root=root,
+                harness_name=harness_name,
+                operation="gemini_agents",
+                source=source_path,
+                allowed_root=allowed_root,
+            )
+        )
+    return results
+
+
+def apply_opencode_agents(
+    entry: InstallEntry,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+) -> list[MaterializationResult]:
+    """Install normalized OpenCode Markdown subagent definitions."""
+    src = resolve_source(entry.source)
+    dst = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    if not src.is_dir():
+        return [
+            _result(
+                "skipped",
+                "opencode_agents",
+                dst,
+                "source directory does not exist",
+                source=src,
+            )
+        ]
+    allowed_root = _allowed_write_root(harness_root, project_root)
+    target_error = _validate_target_path(
+        dst,
+        allowed_root=allowed_root,
+        operation="opencode_agents",
+    )
+    if target_error is not None:
+        return [target_error]
+    dst.mkdir(parents=True, exist_ok=True)
+    root = _root_for(harness_root, project_root)
+    results: list[MaterializationResult] = []
+    for source_path in sorted(src.glob("*.md")):
+        if source_path.name in _COHORT_DOC_FILES:
+            continue
+        target = dst / source_path.name
+        results.append(
+            write_bytes_safely(
+                target,
+                _opencode_agent_text(source_path).encode("utf-8"),
+                install_root=root,
+                harness_name=harness_name,
+                operation="opencode_agents",
+                source=source_path,
+                allowed_root=allowed_root,
+            )
+        )
+    return results
+
+
+def apply_qwen_agents(
+    entry: InstallEntry,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+) -> list[MaterializationResult]:
+    """Install normalized Qwen Code Markdown subagent definitions."""
+    src = resolve_source(entry.source)
+    dst = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    if not src.is_dir():
+        return [
+            _result(
+                "skipped",
+                "qwen_agents",
+                dst,
+                "source directory does not exist",
+                source=src,
+            )
+        ]
+    allowed_root = _allowed_write_root(harness_root, project_root)
+    target_error = _validate_target_path(
+        dst,
+        allowed_root=allowed_root,
+        operation="qwen_agents",
+    )
+    if target_error is not None:
+        return [target_error]
+    dst.mkdir(parents=True, exist_ok=True)
+    root = _root_for(harness_root, project_root)
+    results: list[MaterializationResult] = []
+    for source_path in sorted(src.glob("*.md")):
+        if source_path.name in _COHORT_DOC_FILES:
+            continue
+        target = dst / source_path.name
+        results.append(
+            write_bytes_safely(
+                target,
+                _qwen_agent_text(source_path).encode("utf-8"),
+                install_root=root,
+                harness_name=harness_name,
+                operation="qwen_agents",
+                source=source_path,
+                allowed_root=allowed_root,
+            )
+        )
+    return results
+
+
+def apply_gemini_commands(
+    entry: InstallEntry,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+) -> list[MaterializationResult]:
+    """Install Markdown command files as Gemini CLI TOML slash commands."""
+    src = resolve_source(entry.source)
+    dst = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    if not src.is_dir():
+        return [
+            _result(
+                "skipped",
+                "gemini_commands",
+                dst,
+                "source directory does not exist",
+                source=src,
+            )
+        ]
+    allowed_root = _allowed_write_root(harness_root, project_root)
+    target_error = _validate_target_path(
+        dst,
+        allowed_root=allowed_root,
+        operation="gemini_commands",
+    )
+    if target_error is not None:
+        return [target_error]
+    dst.mkdir(parents=True, exist_ok=True)
+    root = _root_for(harness_root, project_root)
+    results: list[MaterializationResult] = []
+    for source_path in sorted(src.glob("*.md")):
+        if source_path.name in _COHORT_DOC_FILES:
+            continue
+        target = dst / f"{source_path.stem}.toml"
+        results.append(
+            write_bytes_safely(
+                target,
+                _gemini_command_text(source_path).encode("utf-8"),
+                install_root=root,
+                harness_name=harness_name,
+                operation="gemini_commands",
+                source=source_path,
+                allowed_root=allowed_root,
+            )
+        )
+    return results
+
+
+def apply_markdown_commands(
+    entry: InstallEntry,
+    *,
+    harness_root: Path | None = None,
+    project_root: Path | None = None,
+    harness_name: str = "manual",
+) -> list[MaterializationResult]:
+    """Install Markdown command files as native Markdown slash commands."""
+    src = resolve_source(entry.source)
+    dst = resolve_target(
+        entry.target, harness_root=harness_root, project_root=project_root
+    )
+    if not src.is_dir():
+        return [
+            _result(
+                "skipped",
+                "markdown_commands",
+                dst,
+                "source directory does not exist",
+                source=src,
+            )
+        ]
+    allowed_root = _allowed_write_root(harness_root, project_root)
+    target_error = _validate_target_path(
+        dst,
+        allowed_root=allowed_root,
+        operation="markdown_commands",
+    )
+    if target_error is not None:
+        return [target_error]
+    dst.mkdir(parents=True, exist_ok=True)
+    root = _root_for(harness_root, project_root)
+    results: list[MaterializationResult] = []
+    for source_path in sorted(src.glob("*.md")):
+        if source_path.name in _COHORT_DOC_FILES:
+            continue
+        target = dst / source_path.name
+        results.append(
+            write_bytes_safely(
+                target,
+                _native_markdown_command_text(source_path).encode("utf-8"),
+                install_root=root,
+                harness_name=harness_name,
+                operation="markdown_commands",
+                source=source_path,
+                allowed_root=allowed_root,
+            )
+        )
+    return results