painapple-code 1.0.0__py3-none-any.whl

painapple_code/helpers.py

@@ -0,0 +1,406 @@
+"""
+Helpers - Track install state of bundled CLI/agent helpers.
+
+Mirrors the FILES array in `tools/install-helpers.sh`. If you add a new
+helper there, add it here too (and vice versa).
+
+Surfaces install/freshness state via `helpers_status()`, used by the
+GET /api/app/helpers/status endpoint to drive the install-prompt UI.
+"""
+
+import hashlib
+import logging
+import os
+import re
+import shutil
+import stat as stat_mod
+import sys
+from pathlib import Path
+
+from painapple_code import PACKAGE_DIR
+
+logger = logging.getLogger(__name__)
+
+# Source-in-package (relative to PACKAGE_DIR) → install target (absolute, expanded $HOME).
+# Must mirror tools/install-helpers.sh:FILES.
+HELPER_FILES = [
+    ("tools/shadow-git", Path.home() / ".local" / "bin" / "shadow-git"),
+    ("tools/shadow-query", Path.home() / ".local" / "bin" / "shadow-query"),
+    ("tools/agents/shadow-git-helper.md",
+     Path.home() / ".claude" / "agents" / "shadow-git-helper.md"),
+]
+
+# Legacy install paths that earlier versions wrote — install + uninstall
+# both clean these up so users don't end up with both old and new agents
+# in `#` autocomplete after a rename. Safe to keep forever.
+LEGACY_TARGETS = [
+    Path.home() / ".claude" / "agents" / "shadow-git-researcher.md",
+    Path.home() / ".local" / "bin" / "dbq",
+]
+
+# These two helpers are bash scripts, which used to mean "not on Windows".
+# They do work there: Git for Windows ships bash and every coreutil they
+# call (sha256sum, sed, cut, awk...), and anyone using shadow-git already
+# has git. What they can't do is be *invoked* from the PowerShell the
+# terminal tab runs, so on Windows each one also gets a .cmd shim.
+SHELL_SCRIPT_SOURCES = {"tools/shadow-git", "tools/shadow-query"}
+
+_NO_BASH_REASON = "needs Git for Windows (bash) — not found"
+
+
+def find_bash() -> str | None:
+    """Absolute path to a bash that can run the shell helpers, or None.
+
+    On Windows, resolve Git for Windows' own bash from git.exe rather than
+    trusting PATH. `C:\\Windows\\System32\\bash.exe` is the WSL launcher: it
+    would run the helper inside a Linux filesystem namespace where
+    ~/.painapple-code is a DIFFERENT (empty) directory, so the helper would
+    succeed while querying nothing. Git ships bash at <root>/bin/bash.exe
+    and deliberately keeps it off PATH, so PATH alone finds the wrong one.
+    """
+    if sys.platform != "win32":
+        return shutil.which("bash")
+
+    git = shutil.which("git")
+    if git:
+        root = Path(git).parent.parent  # ...\Git\cmd\git.exe -> ...\Git
+        for cand in (root / "bin" / "bash.exe", root / "usr" / "bin" / "bash.exe"):
+            if cand.is_file():
+                return str(cand)
+
+    found = shutil.which("bash")
+    if found and Path(found).parent.name.lower() != "system32":
+        return found
+    return None
+
+
+def _shim_path(target: Path) -> Path:
+    """The .cmd next to `target` that makes it callable from PowerShell."""
+    return target.with_name(target.name + ".cmd")
+
+
+def _shim_body(bash: str, target: Path) -> str:
+    """A batch wrapper that hands the script to bash and forwards argv.
+
+    The bash path is resolved at install time, not runtime: a missing Git
+    then fails with a readable message from cmd instead of a silent
+    fall-through to whatever else answers to `bash`.
+    """
+    return (
+        "@echo off\r\n"
+        "rem Generated by painapple-code helper install. Re-run install to refresh.\r\n"
+        f'"{bash}" "{target}" %*\r\n'
+    )
+
+
+def _supported_here(src_rel: str) -> bool:
+    if sys.platform == "win32" and src_rel in SHELL_SCRIPT_SOURCES:
+        return find_bash() is not None
+    return True
+
+# The shadow-git-helper agent's model is user-selectable (see
+# paths.get_helper_agent_model). Its `model:` frontmatter line is kept
+# orthogonal to the freshness check so a non-default choice doesn't read as
+# "outdated", and is re-applied after every install (cp -f resets it).
+AGENT_SRC_REL = "tools/agents/shadow-git-helper.md"
+AGENT_TARGET = Path.home() / ".claude" / "agents" / "shadow-git-helper.md"
+
+# Matches the leading YAML frontmatter block only (anchored at start, up to the
+# first closing `---`), so example frontmatter later in the body is untouched.
+_FRONTMATTER_RE = re.compile(r"\A(---[ \t]*\r?\n)(.*?\r?\n)(---[ \t]*\r?\n?)", re.DOTALL)
+_MODEL_LINE_RE = re.compile(r"(?im)^[ \t]*model:.*\r?\n?")
+
+
+def _strip_model_line(text: str) -> str:
+    """Remove the `model:` line from the leading frontmatter only."""
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return text
+    body = _MODEL_LINE_RE.sub("", m.group(2))
+    return m.group(1) + body + m.group(3) + text[m.end():]
+
+
+def _set_model_line(text: str, model: str) -> str:
+    """Set `model: <model>` in the leading frontmatter, replacing any existing."""
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return text
+    body = _MODEL_LINE_RE.sub("", m.group(2))
+    if body and not body.endswith("\n"):
+        body += "\n"
+    body += f"model: {model}\n"
+    return m.group(1) + body + m.group(3) + text[m.end():]
+
+
+def read_installed_agent_model() -> str | None:
+    """Return the `model:` value parsed from the installed agent file, or None."""
+    try:
+        text = AGENT_TARGET.read_text(encoding="utf-8")
+    except Exception:
+        return None
+    m = _FRONTMATTER_RE.match(text)
+    if not m:
+        return None
+    mm = re.search(r"(?im)^[ \t]*model:[ \t]*(\S+)", m.group(2))
+    return mm.group(1).strip().lower() if mm else None
+
+
+def _sha256(path: Path) -> str | None:
+    """Return hex sha256 of a file's contents, or None if unreadable."""
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except Exception as e:
+        logger.debug(f"sha256 failed for {path}: {e}")
+        return None
+
+
+def _normalized_hash(path: Path) -> str | None:
+    """sha256 of file text with the frontmatter `model:` line removed, so the
+    user's model choice does not read as a freshness mismatch."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.debug(f"read failed for {path}: {e}")
+        return None
+    return hashlib.sha256(_strip_model_line(text).encode("utf-8")).hexdigest()
+
+
+def helpers_status() -> dict:
+    """
+    Per-file install + freshness state, plus aggregate flags.
+
+    Returns:
+        {
+          "files": [
+            {"name": "shadow-git", "src": "tools/shadow-git", "target": "/...",
+             "installed": bool, "up_to_date": bool},
+            ...
+          ],
+          "all_installed": bool,    # every target exists
+          "all_current": bool,      # every target exists AND matches source hash
+          "any_outdated": bool,     # at least one installed-but-stale file
+        }
+    """
+    files = []
+    all_installed = True
+    all_current = True
+    any_outdated = False
+
+    for src_rel, target in HELPER_FILES:
+        src_abs = PACKAGE_DIR / src_rel
+        installed = target.exists()
+        up_to_date = False
+
+        if not _supported_here(src_rel):
+            # Don't let a helper we deliberately never install drag
+            # all_installed/all_current to False forever — that would
+            # show a permanent "helpers outdated" nag on Windows.
+            files.append({
+                "name": target.name,
+                "src": src_rel,
+                "target": str(target),
+                "installed": False,
+                "up_to_date": False,
+                "unsupported": True,
+                "unsupported_reason": _NO_BASH_REASON,
+            })
+            continue
+
+        if installed:
+            if src_rel == AGENT_SRC_REL:
+                # Model choice is orthogonal to freshness — compare content
+                # with the `model:` frontmatter line stripped from both sides.
+                src_hash = _normalized_hash(src_abs)
+                tgt_hash = _normalized_hash(target)
+            else:
+                src_hash = _sha256(src_abs)
+                tgt_hash = _sha256(target)
+            up_to_date = src_hash is not None and src_hash == tgt_hash
+            if (up_to_date and sys.platform == "win32"
+                    and src_rel in SHELL_SCRIPT_SOURCES
+                    and not _shim_path(target).exists()):
+                # Script content is current but the .cmd is missing — an
+                # install from before shims existed. It's unreachable from
+                # the terminal's PowerShell, so surface it as stale and let
+                # the normal Install button regenerate the wrapper.
+                up_to_date = False
+            if not up_to_date:
+                any_outdated = True
+        else:
+            all_installed = False
+
+        if not (installed and up_to_date):
+            all_current = False
+
+        files.append({
+            "name": target.name,
+            "src": src_rel,
+            "target": str(target),
+            "installed": installed,
+            "up_to_date": up_to_date,
+        })
+
+    from painapple_code import paths
+
+    return {
+        "files": files,
+        "all_installed": all_installed,
+        "all_current": all_current,
+        "any_outdated": any_outdated,
+        # How to actually invoke the helper in THIS platform's terminal.
+        # PowerShell resolves a bare name through PATHEXT and finds the
+        # .cmd, but `~/.local/bin/shadow-git` (no extension) silently does
+        # nothing there — it exits 0 having run no command at all, which is
+        # worse than an error. POSIX shells take the explicit path.
+        "usage_command": ("shadow-git log" if sys.platform == "win32"
+                          else "~/.local/bin/shadow-git log"),
+        # Model the shadow-git-helper subagent runs on (full model ID or
+        # "inherit"); options mirror the main model selector + "inherit".
+        "agent_model": paths.get_helper_agent_model(),
+        "agent_model_options": paths.get_helper_agent_options(),
+    }
+
+
+def install_helpers_script_path() -> Path:
+    """Return the path to tools/install-helpers.sh — the equivalent shell
+    script users can run by hand. install_helpers() below does the same
+    work in-process; this stays for docs and manual installs."""
+    return PACKAGE_DIR / "tools" / "install-helpers.sh"
+
+
+def install_helpers(force: bool = True) -> dict:
+    """Copy the bundled helpers to their user-level targets.
+
+    A Python port of tools/install-helpers.sh --update (mkdir -p, cp -f,
+    chmod 755 when the source is executable). The endpoint used to shell
+    out to `bash`, which simply isn't there on a stock Windows box — and
+    uninstall was already pure Python, so the two halves now match.
+
+    Returns the same {ok, exit_code, stdout, stderr} shape the route
+    reports, so the frontend is unchanged.
+    """
+    lines = [f"painapple-code helpers — install (pkg: {PACKAGE_DIR})", ""]
+    errors = []
+
+    bash = find_bash() if sys.platform == "win32" else None
+
+    for src_rel, target in HELPER_FILES:
+        if not _supported_here(src_rel):
+            lines.append(f"  skip   {target}  ({_NO_BASH_REASON})")
+            continue
+        src_abs = PACKAGE_DIR / src_rel
+        if not src_abs.is_file():
+            errors.append(f"source missing: {src_abs}")
+            continue
+        existed = target.exists()
+        if existed and not force:
+            lines.append(f"  skip   {target}  (exists — use --update to overwrite)")
+            continue
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            # copyfile, not copy2: we deliberately do not carry over source
+            # mtimes (the freshness check hashes content instead).
+            shutil.copyfile(src_abs, target)
+            if os.access(src_abs, os.X_OK):
+                target.chmod(0o755)  # mirrors the script's `chmod 755`
+            lines.append(f"  {'update' if existed else 'install'} {target}")
+            if bash and src_rel in SHELL_SCRIPT_SOURCES:
+                # PowerShell (what the terminal tab runs) can't execute an
+                # extensionless bash script; the .cmd is what makes
+                # `shadow-git log` work there the way it does on a POSIX box.
+                shim = _shim_path(target)
+                shim.write_text(_shim_body(bash, target), encoding="ascii")
+                lines.append(f"  {'update' if existed else 'install'} {shim}")
+        except OSError as e:
+            logger.warning(f"install: failed to write {target}: {e}")
+            errors.append(f"{target}: {e}")
+
+    for legacy in LEGACY_TARGETS:
+        if legacy.exists():
+            try:
+                legacy.unlink()
+                lines.append(f"  remove {legacy}  (legacy)")
+            except OSError as e:
+                errors.append(f"{legacy}: {e}")
+
+    return {
+        "ok": not errors,
+        "exit_code": 0 if not errors else 1,
+        "stdout": "\n".join(lines) + "\n",
+        "stderr": "\n".join(errors),
+    }
+
+
+def uninstall_helpers() -> dict:
+    """
+    Remove every installed helper target from disk, plus any legacy
+    targets from earlier installs (renamed/moved files). Idempotent —
+    missing targets are skipped, not errors.
+
+    Returns:
+        {
+          "ok": bool,           # True if every target is gone after the call
+          "removed": [str],     # paths actually deleted this call
+          "missing": [str],     # paths that were already absent
+          "errors": [{"path": str, "error": str}],
+        }
+    """
+    removed: list[str] = []
+    missing: list[str] = []
+    errors: list[dict] = []
+
+    targets = [t for _, t in HELPER_FILES] + LEGACY_TARGETS
+    if sys.platform == "win32":
+        # Remove what install could have created — the PowerShell shims.
+        targets += [_shim_path(t) for src, t in HELPER_FILES
+                    if src in SHELL_SCRIPT_SOURCES]
+    for target in targets:
+        if not target.exists():
+            missing.append(str(target))
+            continue
+        try:
+            target.unlink()
+            removed.append(str(target))
+        except Exception as e:
+            logger.warning(f"uninstall: failed to remove {target}: {e}")
+            errors.append({"path": str(target), "error": str(e)})
+
+    return {
+        "ok": not errors,
+        "removed": removed,
+        "missing": missing,
+        "errors": errors,
+    }
+
+
+def apply_agent_model(model: str) -> bool:
+    """Write `model: <model>` into the installed shadow-git-helper frontmatter.
+
+    Returns True when the installed file exists and now carries that model
+    (whether it needed a write or was already correct), False otherwise.
+    """
+    if not AGENT_TARGET.exists():
+        return False
+    try:
+        text = AGENT_TARGET.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.warning(f"apply_agent_model: read failed: {e}")
+        return False
+    new_text = _set_model_line(text, model)
+    if new_text != text:
+        try:
+            AGENT_TARGET.write_text(new_text, encoding="utf-8")
+        except Exception as e:
+            logger.warning(f"apply_agent_model: write failed: {e}")
+            return False
+    return True
+
+
+def apply_agent_model_from_config() -> bool:
+    """Re-apply the persisted model choice to the installed agent file.
+
+    Called after install-helpers.sh, whose `cp -f` overwrites the installed
+    copy with the bundled default (model: sonnet).
+    """
+    from painapple_code import paths
+    return apply_agent_model(paths.get_helper_agent_model())