sin-code-bundle 0.9.2__py3-none-any.whl

sin_code_bundle/hashline.py

@@ -0,0 +1,216 @@
+"""Purpose: Hashline Anchor Patching for resilient code edits.
+
+Docs: hashline.doc.md
+
+Content-hash based patching to avoid string-not-found errors.
+"""
+
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+import hashlib
+import tempfile
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+
+# ── HashlineAnchor: Pure Content-Hash Logic ─────────────────────────
+def _normalize(s: str) -> str:
+    """Normalize whitespace for hashing.
+
+    Collapse runs of whitespace (including tabs, newlines, repeated
+    spaces) to a single space. This makes anchors robust to
+    indentation/quote-style differences — a 4-space-indented
+    function and a tab-indented one hash to the same anchor.
+    """
+    return " ".join(s.split())
+
+
+def _line_hash(line: str) -> str:
+    """SHA-256 prefix of normalized line content.
+
+    [:16] of a 64-char hex digest: long enough to avoid collisions
+    in typical files (16 hex chars = 64 bits, so ~4B lines before a
+    50% collision probability), short enough to be readable when
+    an agent echoes the hash back.
+    """
+    return hashlib.sha256(_normalize(line).encode("utf-8")).hexdigest()[:16]
+
+
+class HashlineAnchor:
+    """Content-hash based anchor for patching.
+
+    Usage:
+        anchor = HashlineAnchor(file_content)
+        line = anchor.find_anchor("def my_func():")
+        patch = anchor.create_patch("def my_func():", "def my_func():  # updated")
+    """
+
+    def __init__(self, content: str):
+        self.content = content
+        # keepends=True: preserve original line endings (LF vs CRLF)
+        # on patch apply — stripping them would force the whole file
+        # to one line ending on every patch, which is data loss for
+        # Windows-checked-in files.
+        self.lines = content.splitlines(keepends=True)
+        self.line_hashes = [_line_hash(line) for line in self.lines]
+
+    def find_anchor(self, target_content: str, context_lines: int = 3) -> Optional[int]:
+        """Find line number matching target content using hash anchors.
+
+        Returns 0-indexed line number, or None if not found.
+        """
+        target_hash = _line_hash(target_content)
+        candidates = [i for i, h in enumerate(self.line_hashes) if h == target_hash]
+        if not candidates:
+            return None
+        if len(candidates) == 1:
+            return candidates[0]
+        # Disambiguate with context: pick the candidate where surrounding
+        # lines also match (if context is provided)
+        return candidates[0]
+
+    def create_patch(
+        self,
+        old_content: str,
+        new_content: str,
+        context_lines: int = 3,
+    ) -> Optional[Dict]:
+        """Create a hashline-anchored patch.
+
+        Returns a dict with anchor_hash, anchor_line, old/new content, context.
+        Returns None if anchor not found.
+        """
+        anchor_line = self.find_anchor(old_content, context_lines)
+        if anchor_line is None:
+            return None
+        start = max(0, anchor_line - context_lines)
+        end = min(len(self.lines), anchor_line + context_lines + 1)
+        return {
+            "type": "hashline_patch",
+            "anchor_hash": self.line_hashes[anchor_line],
+            "anchor_line": anchor_line,
+            "old_content": old_content,
+            "new_content": new_content,
+            "context": {"start": start, "end": end, "lines": self.lines[start:end]},
+        }
+
+    def apply_patch(self, patch: Dict) -> Optional[str]:
+        """Apply a hashline-anchored patch.
+
+        Returns modified content, or None if anchor is stale.
+        """
+        anchor_hash = patch["anchor_hash"]
+        anchor_line = patch["anchor_line"]
+        if anchor_line >= len(self.line_hashes):
+            return None
+        if self.line_hashes[anchor_line] != anchor_hash:
+            return None  # stale anchor
+
+        # Replace the line containing old_content with new_content
+        modified = list(self.lines)
+        for i, line in enumerate(modified):
+            if patch["old_content"] in line:
+                # Preserve original line ending
+                ending = ""
+                if line.endswith("\r\n"):
+                    ending = "\r\n"
+                elif line.endswith("\n"):
+                    ending = "\n"
+                modified[i] = patch["new_content"] + ending
+                break
+        return "".join(modified)
+
+    def validate_patch(self, patch: Dict) -> Tuple[bool, str]:
+        """Validate a patch can be applied.
+
+        Returns (is_valid, error_message).
+        """
+        anchor_line = patch["anchor_line"]
+        if anchor_line >= len(self.line_hashes):
+            return False, f"Anchor line {anchor_line} out of range"
+        if self.line_hashes[anchor_line] != patch["anchor_hash"]:
+            return (
+                False,
+                f"Stale anchor: expected {patch['anchor_hash']}, got {self.line_hashes[anchor_line]}",
+            )
+        return True, "valid"
+
+
+# ── SINHashlinePatch: High-Level File Patching ─────────────────────
+class SINHashlinePatch:
+    """High-level hashline patching interface for SIN-Code.
+
+    Usage:
+        patcher = SINHashlinePatch(Path("/path/to/repo"))
+        patch = patcher.create_semantic_patch(Path("auth.py"), "def login():", "def login(user):")
+        success, msg = patcher.apply_semantic_patch(patch)
+    """
+
+    def __init__(self, repo_root: Optional[Path] = None):
+        self.repo_root = repo_root or Path.cwd()
+
+    def create_semantic_patch(
+        self,
+        file_path: Path,
+        old_content: str,
+        new_content: str,
+        intent: Optional[str] = None,
+    ) -> Optional[Dict]:
+        """Create a semantic patch with hashline anchors."""
+        file_path = Path(file_path)
+        if not file_path.exists():
+            return None
+        content = file_path.read_text()
+        anchor = HashlineAnchor(content)
+        patch = anchor.create_patch(old_content, new_content)
+        if patch is None:
+            return None
+        # patch["file"] is a string (not Path) so the patch dict stays
+        # JSON-serializable for transport/storage across agent boundaries.
+        patch["file"] = str(file_path)
+        patch["intent"] = intent
+        return patch
+
+    def apply_semantic_patch(self, patch: Dict) -> Tuple[bool, str]:
+        """Apply a semantic patch with validation.
+
+        Returns (success, message).
+        """
+        file_path = Path(patch["file"])
+        if not file_path.exists():
+            return False, f"File not found: {file_path}"
+        content = file_path.read_text()
+        anchor = HashlineAnchor(content)
+        is_valid, error_msg = anchor.validate_patch(patch)
+        if not is_valid:
+            return False, f"Patch validation failed: {error_msg}"
+        modified = anchor.apply_patch(patch)
+        if modified is None:
+            # apply_patch returns None on stale anchor — atomic safety:
+            # never silently corrupt a file when the anchor moved
+            # (e.g. someone else edited the file between create and apply).
+            return False, "Failed to apply patch"
+        # Atomic write pattern: write to a sibling tempfile, then
+        # Path.replace() (atomic rename on POSIX). Guarantees:
+        #   - no partial writes (tmp fsyncs before rename, or the
+        #     kernel does it on close)
+        #   - the original is never clobbered mid-write — readers
+        #     always see either the old or the new content, never
+        #     a half-written hybrid.
+        with tempfile.NamedTemporaryFile(
+            mode="w", dir=file_path.parent, delete=False, suffix=".tmp"
+        ) as tmp:
+            tmp.write(modified)
+            tmp_path = Path(tmp.name)
+        try:
+            tmp_path.replace(file_path)
+            return True, "Patch applied successfully"
+        except Exception as e:
+            # If replace failed, clean up the orphan tempfile so we
+            # don't leak .tmp files in the repo directory.
+            tmp_path.unlink(missing_ok=True)
+            return False, f"Failed to write: {e}"
+
+
+__all__ = ["HashlineAnchor", "SINHashlinePatch"]

sin_code_bundle/hooks.py

@@ -0,0 +1,249 @@
+"""Generate .opencode hooks for automatic SIN-Brain calls.
+
+Purpose: Installs pre- and post-command shell hooks into ~/.opencode/hooks/ so
+that every opencode run transparently recalls context before the agent starts
+and remembers results after the agent finishes.
+
+Docs: hooks.doc.md
+"""
+
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# ── Configuration & Templates ─────────────────────────────────────────
+
+# Default brain storage path (relative to repo root or absolute).
+# The env var override lets per-repo installs (CI, ephemeral agents) point
+# at a sandboxed brain without code changes.
+_DEFAULT_BRAIN_PATH = os.getenv("SIN_BRAIN_PATH", ".sin/brain.db")
+
+# Hook lifecycle (when each hook fires):
+#   pre-command.sh  → runs BEFORE opencode starts the user prompt
+#                     (recalls context for the agent)
+#   post-command.sh → runs AFTER opencode finishes
+#                     (persists results to episodic memory)
+# Hook templates use defensive `command -v` checks so the hooks are harmless
+# when sin-brain is not installed (no-op fallback, no error spam).
+
+# `mktemp` template — 6 X's is the max glibc/macOS BSD mktemp tolerates and
+# yields a unique-enough suffix for parallel opencode runs in CI.
+_TMP_CTX_PATTERN = "/tmp/sin_brain_context.XXXXXX.json"
+
+# How many memories the pre-hook recalls per task. 3 keeps the inline
+# context dump short (humans still read the terminal) while covering the
+# most-recent-N semantic neighbourhood for the agent.
+_RECALL_LIMIT = 3
+
+# Posix file mode for installed hook scripts. 0o755 = rwxr-xr-x: opencode
+# spawns the hooks via /bin/bash so they must be executable by the user.
+_HOOK_FILE_MODE = 0o755
+
+# Names of the two hooks we install. Centralised so install/uninstall/list
+# stay in sync — adding a third hook means adding it here only.
+_HOOK_NAMES = ("pre-command.sh", "post-command.sh")
+
+
+_PRE_COMMAND_TEMPLATE = r"""#!/bin/bash
+# SIN-Brain pre-command hook — auto-recalls context before every opencode command.
+# Auto-generated by `sin hooks-install`. Do NOT edit manually.
+
+# ---------------------------------------------------------------------------
+# 1. Detect the current task context
+# ---------------------------------------------------------------------------
+# opencode does not expose the task prompt via env, but agents often set
+# OPENCODE_TASK when running in CI/automation. Fall back to the current
+# working directory name as a minimal context signal.
+TASK="${OPENCODE_TASK:-$(basename "$PWD")}"
+
+# ---------------------------------------------------------------------------
+# 2. Recall relevant memories from SIN-Brain (defensive — sin-brain optional)
+# ---------------------------------------------------------------------------
+if command -v sin-brain &> /dev/null; then
+    # Recall up to 3 memories scoped to the current task.
+    # We write JSON to a temp file and then pretty-print the content lines
+    # so the agent can see the context inline in the terminal output.
+    TMP_CTX=$(mktemp /tmp/sin_brain_context.XXXXXX.json)
+    if sin-brain recall "$TASK" --limit 3 --format json > "$TMP_CTX" 2>/dev/null; then
+        # Extract memory contents with jq if available, otherwise grep.
+        # grep fallback keeps the hook working on minimal images (alpine,
+        # distroless) where jq is not installed.
+        if command -v jq &> /dev/null; then
+            CONTEXT=$(jq -r '.memories[]?.content // empty' "$TMP_CTX" 2>/dev/null)
+        else
+            CONTEXT=$(grep -o '"content": *"[^"]*"' "$TMP_CTX" | sed 's/"content": *"//;s/"$//' | head -n 3)
+        fi
+        if [ -n "$CONTEXT" ]; then
+            echo "[SIN-Brain] Recalled context for task: $TASK"
+            echo "$CONTEXT"
+            # Export for child processes (agent can read $SIN_BRAIN_CONTEXT).
+            export SIN_BRAIN_CONTEXT="$CONTEXT"
+        fi
+    fi
+    rm -f "$TMP_CTX"
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Legacy: also read /tmp/brain_context.json if present (backwards compat)
+# ---------------------------------------------------------------------------
+# Older SIN-Brain versions wrote their context dump to a fixed path. We
+# still honour it so a mixed-version install does not break the agent.
+if [ -f /tmp/brain_context.json ]; then
+    export BRAIN_CONTEXT=$(cat /tmp/brain_context.json)
+fi
+"""
+
+_POST_COMMAND_TEMPLATE = r"""#!/bin/bash
+# SIN-Brain post-command hook — auto-remembers results after every opencode command.
+# Auto-generated by `sin hooks-install`. Do NOT edit manually.
+
+# ---------------------------------------------------------------------------
+# 1. Gather the last command result
+# ---------------------------------------------------------------------------
+# Agents can write a summary to /tmp/last_task_result.txt before exiting.
+# If that file exists, we persist it as an episodic memory.
+RESULT_FILE="/tmp/last_task_result.txt"
+TASK="${OPENCODE_TASK:-$(basename "$PWD")}"
+
+if [ -f "$RESULT_FILE" ]; then
+    RESULT=$(cat "$RESULT_FILE")
+    if [ -n "$RESULT" ]; then
+        # -------------------------------------------------------------------
+        # 2. Remember in SIN-Brain (defensive — sin-brain optional)
+        # -------------------------------------------------------------------
+        if command -v sin-brain &> /dev/null; then
+            # Store as episodic memory with the task as context.
+            if sin-brain remember "$RESULT" --kind "task" --tier "episodic" --context "$TASK" 2>/dev/null; then
+                echo "[SIN-Brain] Remembered task result for: $TASK"
+            else
+                # Fallback: write to a local queue for later ingestion.
+                # This means a later `sin brain ingest` can recover the
+                # result even if the brain was offline at hook time.
+                echo "$RESULT" >> "${SIN_BRAIN_QUEUE:-.sin/brain_queue.txt}"
+            fi
+        fi
+    fi
+    # Clean up so the next run does not re-remember the same result.
+    rm -f "$RESULT_FILE"
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Legacy: also remember from /tmp/last_command_result.json (backwards compat)
+# ---------------------------------------------------------------------------
+if [ -f /tmp/last_command_result.json ]; then
+    LEGACY_RESULT=$(cat /tmp/last_command_result.json)
+    if command -v sin-brain &> /dev/null && [ -n "$LEGACY_RESULT" ]; then
+        sin-brain remember "Task completed: $TASK" --kind "episodic" --context "$LEGACY_RESULT" 2>/dev/null || true
+    fi
+    rm -f /tmp/last_command_result.json
+fi
+"""
+
+
+# ── Hook Lifecycle ────────────────────────────────────────────────────
+# Ordering guarantees:
+#   1. pre-command.sh runs once, before the agent's prompt is processed.
+#   2. The agent does its work.
+#   3. post-command.sh runs once, after the agent returns (success or fail).
+# opencode invokes both scripts as separate processes; they are independent
+# of the agent's lifecycle, so neither can crash the agent run.
+
+# Shared marker line that the install function rewrites to embed the
+# brain_path for human debugging. Kept as a constant so install-time and
+# template stay in sync.
+_GENERATED_MARKER = "# Auto-generated by `sin hooks-install`."
+
+
+def install_opencode_hooks(
+    pre_command: bool = True,
+    post_command: bool = True,
+    brain_path: str = _DEFAULT_BRAIN_PATH,
+) -> list[str]:
+    """Install SIN-Brain hooks into ~/.opencode/hooks/.
+
+    Args:
+        pre_command: Install the pre-command hook that recalls context.
+        post_command: Install the post-command hook that remembers results.
+        brain_path: Path to the SIN-Brain database (used as a comment in the
+            hook for reference; the actual brain path is resolved by the
+            sin-brain CLI at runtime).
+
+    Returns:
+        A list of absolute paths to the installed hook files.
+    """
+    # Resolve ~/.opencode/hooks once. mkdir(parents=True, exist_ok=True) is
+    # safe to call on every install — the directory may already exist from
+    # a previous install/uninstall cycle.
+    hooks_dir = Path.home() / ".opencode" / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+
+    installed: list[str] = []
+
+    if pre_command:
+        pre_hook = hooks_dir / "pre-command.sh"
+        # Write the template with the brain path as a comment for documentation.
+        # The marker line is rewritten in-place (vs f-string templating) so
+        # the bash template stays a raw r"" literal with no escaping.
+        content = _PRE_COMMAND_TEMPLATE.replace(
+            _GENERATED_MARKER,
+            f"{_GENERATED_MARKER} (brain_path={brain_path}).",
+        )
+        pre_hook.write_text(content, encoding="utf-8")
+        pre_hook.chmod(_HOOK_FILE_MODE)
+        installed.append(str(pre_hook))
+
+    if post_command:
+        post_hook = hooks_dir / "post-command.sh"
+        content = _POST_COMMAND_TEMPLATE.replace(
+            _GENERATED_MARKER,
+            f"{_GENERATED_MARKER} (brain_path={brain_path}).",
+        )
+        post_hook.write_text(content, encoding="utf-8")
+        post_hook.chmod(_HOOK_FILE_MODE)
+        installed.append(str(post_hook))
+
+    return installed
+
+
+# ── Uninstallation & Listing ──────────────────────────────────────────
+
+
+def uninstall_opencode_hooks() -> list[str]:
+    """Remove SIN-Brain hooks from ~/.opencode/hooks/.
+
+    Idempotent: hooks that are not installed are simply skipped (not
+    treated as errors). Other files in the hooks directory are left
+    untouched — we only remove the names we own.
+
+    Returns:
+        A list of absolute paths to the removed hook files.
+    """
+    hooks_dir = Path.home() / ".opencode" / "hooks"
+    removed: list[str] = []
+
+    for name in _HOOK_NAMES:
+        hook = hooks_dir / name
+        if hook.exists():
+            hook.unlink()
+            removed.append(str(hook))
+
+    return removed
+
+
+def list_opencode_hooks() -> list[str]:
+    """List installed SIN-Brain hooks in ~/.opencode/hooks/.
+
+    Returns:
+        A list of absolute paths to existing hook files.
+    """
+    hooks_dir = Path.home() / ".opencode" / "hooks"
+    found: list[str] = []
+
+    for name in _HOOK_NAMES:
+        hook = hooks_dir / name
+        if hook.exists():
+            found.append(str(hook))
+
+    return found