clipsy 1.5.0__py3-none-any.whl

clipsy/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.5.0"
+__app_name__ = "Clipsy"

clipsy/__main__.py

@@ -0,0 +1,26 @@
+import logging
+import sys
+
+from clipsy.config import LOG_PATH
+from clipsy.utils import ensure_dirs
+
+
+def main():
+    ensure_dirs()
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        handlers=[
+            logging.FileHandler(LOG_PATH),
+            logging.StreamHandler(sys.stderr),
+        ],
+    )
+
+    from clipsy.app import ClipsyApp
+    app = ClipsyApp()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

clipsy/app.py

@@ -0,0 +1,199 @@
+import logging
+import webbrowser
+from pathlib import Path
+
+import rumps
+
+from clipsy import __version__
+from clipsy.config import DB_PATH, IMAGE_DIR, MENU_DISPLAY_COUNT, POLL_INTERVAL, REDACT_SENSITIVE, THUMBNAIL_SIZE
+from clipsy.models import ClipboardEntry, ContentType
+from clipsy.monitor import ClipboardMonitor
+from clipsy.storage import StorageManager
+from clipsy.utils import create_thumbnail, ensure_dirs
+
+logger = logging.getLogger(__name__)
+
+ENTRY_KEY_PREFIX = "clipsy_entry_"
+
+
+class ClipsyApp(rumps.App):
+    def __init__(self):
+        super().__init__("Clipsy", title="✂️", quit_button=None)
+        ensure_dirs()
+        self._storage = StorageManager(DB_PATH)
+        self._monitor = ClipboardMonitor(self._storage, on_change=self._refresh_menu)
+        self._entry_ids: dict[str, int] = {}
+        self._build_menu()
+
+    def _build_menu(self) -> None:
+        self.menu.clear()
+        self.menu = [
+            rumps.MenuItem(f"Clipsy v{__version__} - Clipboard History", callback=None),
+            None,  # separator
+            rumps.MenuItem("Search...", callback=self._on_search),
+            None,  # separator
+        ]
+
+        entries = self._storage.get_recent(limit=MENU_DISPLAY_COUNT)
+        self._entry_ids.clear()
+
+        if not entries:
+            self.menu.add(rumps.MenuItem("(No clipboard history)", callback=None))
+        else:
+            for entry in entries:
+                self.menu.add(self._create_entry_menu_item(entry))
+
+        self.menu.add(None)  # separator
+        self.menu.add(rumps.MenuItem("Clear History", callback=self._on_clear))
+        self.menu.add(None)  # separator
+        self.menu.add(rumps.MenuItem("Support Clipsy", callback=self._on_support))
+        self.menu.add(None)  # separator
+        self.menu.add(rumps.MenuItem("Quit Clipsy", callback=self._on_quit))
+
+    def _create_entry_menu_item(self, entry: ClipboardEntry) -> rumps.MenuItem:
+        """Create a menu item for a clipboard entry."""
+        key = f"{ENTRY_KEY_PREFIX}{entry.id}"
+        self._entry_ids[key] = entry.id
+        display_text = self._get_display_preview(entry)
+
+        if entry.content_type == ContentType.IMAGE:
+            thumb_path = self._ensure_thumbnail(entry)
+            if thumb_path:
+                item = rumps.MenuItem(
+                    display_text,
+                    callback=self._on_entry_click,
+                    icon=thumb_path,
+                    dimensions=(32, 32),
+                    template=False,
+                )
+            else:
+                item = rumps.MenuItem(display_text, callback=self._on_entry_click)
+        else:
+            item = rumps.MenuItem(display_text, callback=self._on_entry_click)
+
+        item._id = key
+        return item
+
+    def _get_display_preview(self, entry: ClipboardEntry) -> str:
+        """Get the display preview for an entry, masking sensitive data if enabled."""
+        if REDACT_SENSITIVE and entry.is_sensitive and entry.masked_preview:
+            return f"🔒 {entry.masked_preview}"
+        return entry.preview
+
+    def _ensure_thumbnail(self, entry: ClipboardEntry) -> str | None:
+        """Ensure a thumbnail exists for an image entry, generating if needed."""
+        if entry.thumbnail_path:
+            return entry.thumbnail_path
+
+        if not entry.image_path:
+            return None
+
+        # Generate thumbnail for legacy entries
+        image_path = Path(entry.image_path)
+        if not image_path.exists():
+            return None
+
+        thumb_filename = image_path.stem + "_thumb.png"
+        thumb_path = IMAGE_DIR / thumb_filename
+
+        if thumb_path.exists() or create_thumbnail(str(image_path), str(thumb_path), THUMBNAIL_SIZE):
+            self._storage.update_thumbnail_path(entry.id, str(thumb_path))
+            return str(thumb_path)
+
+        return None
+
+    def _refresh_menu(self) -> None:
+        self._build_menu()
+
+    @rumps.timer(POLL_INTERVAL)
+    def _poll_clipboard(self, _sender) -> None:
+        self._monitor.check_clipboard()
+
+    def _on_entry_click(self, sender) -> None:
+        entry_id = self._entry_ids.get(getattr(sender, "_id", ""))
+        if entry_id is None:
+            return
+
+        entry = self._storage.get_entry(entry_id)
+        if entry is None:
+            return
+
+        try:
+            from AppKit import NSPasteboard, NSPasteboardTypePNG, NSPasteboardTypeString
+
+            pb = NSPasteboard.generalPasteboard()
+
+            copied = False
+
+            if entry.content_type == ContentType.TEXT and entry.text_content:
+                pb.clearContents()
+                pb.setString_forType_(entry.text_content, NSPasteboardTypeString)
+                self._monitor.sync_change_count()
+                copied = True
+
+            elif entry.content_type == ContentType.IMAGE and entry.image_path:
+                from Foundation import NSData
+                img_data = NSData.dataWithContentsOfFile_(entry.image_path)
+                if img_data:
+                    pb.clearContents()
+                    pb.setData_forType_(img_data, NSPasteboardTypePNG)
+                    self._monitor.sync_change_count()
+                    copied = True
+
+            elif entry.content_type == ContentType.FILE and entry.text_content:
+                pb.clearContents()
+                pb.setString_forType_(entry.text_content, NSPasteboardTypeString)
+                self._monitor.sync_change_count()
+                copied = True
+
+            if copied:
+                self._storage.update_timestamp(entry_id)
+                self._refresh_menu()
+                rumps.notification("Clipsy", "", "Copied to clipboard", sound=False)
+        except Exception:
+            logger.exception("Error copying entry to clipboard")
+
+    def _on_search(self, _sender) -> None:
+        response = rumps.Window(
+            message="Search clipboard history:",
+            title="Clipsy Search",
+            default_text="",
+            ok="Search",
+            cancel="Cancel",
+            dimensions=(300, 24),
+        ).run()
+
+        if response.clicked and response.text.strip():
+            query = response.text.strip()
+            results = self._storage.search(query, limit=MENU_DISPLAY_COUNT)
+
+            if not results:
+                rumps.alert("Clipsy Search", f'No results for "{query}"')
+                return
+
+            self.menu.clear()
+            self._entry_ids.clear()
+            self.menu = [
+                rumps.MenuItem(f'Search: "{query}" ({len(results)} results)', callback=None),
+                None,
+                rumps.MenuItem("Show All", callback=lambda _: self._refresh_menu()),
+                None,
+            ]
+
+            for entry in results:
+                self.menu.add(self._create_entry_menu_item(entry))
+
+            self.menu.add(None)
+            self.menu.add(rumps.MenuItem("Quit Clipsy", callback=self._on_quit))
+
+    def _on_clear(self, _sender) -> None:
+        if rumps.alert("Clipsy", "Clear all clipboard history?", ok="Clear", cancel="Cancel"):
+            self._storage.clear_all()
+            self._refresh_menu()
+
+    def _on_support(self, _sender) -> None:
+        webbrowser.open("https://github.com/sponsors/brencon")
+
+    def _on_quit(self, _sender) -> None:
+        self._storage.close()
+        rumps.quit_application()

clipsy/config.py

@@ -0,0 +1,16 @@
+import os
+from pathlib import Path
+
+DATA_DIR = Path(os.environ.get("CLIPSY_DATA_DIR", Path.home() / ".local" / "share" / "clipsy"))
+DB_PATH = DATA_DIR / "clipsy.db"
+IMAGE_DIR = DATA_DIR / "images"
+LOG_PATH = DATA_DIR / "clipsy.log"
+
+POLL_INTERVAL = 0.5  # seconds between clipboard checks
+MAX_ENTRIES = 500  # auto-purge threshold
+MAX_TEXT_SIZE = 1_000_000  # 1MB text limit
+MAX_IMAGE_SIZE = 10_000_000  # 10MB image limit
+PREVIEW_LENGTH = 60  # characters shown in menu item
+MENU_DISPLAY_COUNT = 10  # items shown in dropdown
+THUMBNAIL_SIZE = (32, 32)  # pixels, for menu icon display
+REDACT_SENSITIVE = True  # mask sensitive data in preview (API keys, passwords, etc.)

clipsy/models.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+
+class ContentType(str, Enum):
+    TEXT = "text"
+    IMAGE = "image"
+    FILE = "file"
+
+
+@dataclass
+class ClipboardEntry:
+    id: int | None
+    content_type: ContentType
+    text_content: str | None
+    image_path: str | None
+    preview: str
+    content_hash: str
+    byte_size: int
+    created_at: datetime
+    pinned: bool = False
+    source_app: str | None = None
+    thumbnail_path: str | None = None
+    is_sensitive: bool = False
+    masked_preview: str | None = None

clipsy/monitor.py

@@ -0,0 +1,153 @@
+import logging
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+
+from AppKit import NSPasteboard, NSPasteboardTypePNG, NSPasteboardTypeTIFF, NSPasteboardTypeString, NSFilenamesPboardType
+
+from clipsy.config import IMAGE_DIR, MAX_IMAGE_SIZE, MAX_TEXT_SIZE, PREVIEW_LENGTH, REDACT_SENSITIVE, THUMBNAIL_SIZE
+from clipsy.models import ClipboardEntry, ContentType
+from clipsy.redact import detect_sensitive, mask_text
+from clipsy.storage import StorageManager
+from clipsy.utils import compute_hash, create_thumbnail, ensure_dirs, get_image_dimensions, truncate_text
+
+logger = logging.getLogger(__name__)
+
+
+class ClipboardMonitor:
+    def __init__(self, storage: StorageManager, on_change: Callable[[], None] | None = None):
+        self._storage = storage
+        self._on_change = on_change
+        self._pasteboard = NSPasteboard.generalPasteboard()
+        self._last_change_count = self._pasteboard.changeCount()
+        ensure_dirs()
+
+    def check_clipboard(self) -> bool:
+        current_count = self._pasteboard.changeCount()
+        if current_count == self._last_change_count:
+            return False
+
+        self._last_change_count = current_count
+
+        try:
+            entry = self._read_clipboard()
+            if entry is None:
+                return False
+
+            existing = self._storage.find_by_hash(entry.content_hash)
+            if existing:
+                self._storage.update_timestamp(existing.id)
+            else:
+                self._storage.add_entry(entry)
+                self._storage.purge_old()
+
+            if self._on_change:
+                self._on_change()
+            return True
+        except Exception:
+            logger.exception("Error reading clipboard")
+            return False
+
+    def sync_change_count(self) -> None:
+        self._last_change_count = self._pasteboard.changeCount()
+
+    def _read_clipboard(self) -> ClipboardEntry | None:
+        types = self._pasteboard.types()
+        if types is None:
+            return None
+
+        if NSPasteboardTypeString in types:
+            text = self._pasteboard.stringForType_(NSPasteboardTypeString)
+            if text:
+                text_bytes = text.encode("utf-8")
+                if len(text_bytes) <= MAX_TEXT_SIZE:
+                    content_hash = compute_hash(text_bytes)
+                    preview = truncate_text(text, PREVIEW_LENGTH)
+
+                    # Detect sensitive data
+                    is_sensitive = False
+                    masked_preview = None
+                    if REDACT_SENSITIVE:
+                        matches = detect_sensitive(text)
+                        if matches:
+                            is_sensitive = True
+                            masked_preview = truncate_text(mask_text(text, matches), PREVIEW_LENGTH)
+
+                    return ClipboardEntry(
+                        id=None,
+                        content_type=ContentType.TEXT,
+                        text_content=text,
+                        image_path=None,
+                        preview=preview,
+                        content_hash=content_hash,
+                        byte_size=len(text_bytes),
+                        created_at=datetime.now(),
+                        is_sensitive=is_sensitive,
+                        masked_preview=masked_preview,
+                    )
+
+        for img_type in (NSPasteboardTypePNG, NSPasteboardTypeTIFF):
+            if img_type in types:
+                data = self._pasteboard.dataForType_(img_type)
+                if data is None:
+                    continue
+                img_bytes = bytes(data)
+                if len(img_bytes) > MAX_IMAGE_SIZE:
+                    logger.warning("Image too large (%d bytes), skipping", len(img_bytes))
+                    return None
+                content_hash = compute_hash(img_bytes)
+                is_png = img_type == NSPasteboardTypePNG
+                image_path, thumbnail_path = self._save_image(img_bytes, content_hash, is_png)
+                width, height = get_image_dimensions(img_bytes)
+                preview = f"[Image: {width}x{height}]" if width > 0 else "[Image]"
+                return ClipboardEntry(
+                    id=None,
+                    content_type=ContentType.IMAGE,
+                    text_content=None,
+                    image_path=str(image_path),
+                    preview=preview,
+                    content_hash=content_hash,
+                    byte_size=len(img_bytes),
+                    created_at=datetime.now(),
+                    thumbnail_path=str(thumbnail_path) if thumbnail_path else None,
+                )
+
+        if NSFilenamesPboardType in types:
+            filenames = self._pasteboard.propertyListForType_(NSFilenamesPboardType)
+            if filenames:
+                file_list = list(filenames)
+                text = "\n".join(file_list)
+                content_hash = compute_hash(text)
+                if len(file_list) == 1:
+                    preview = truncate_text(Path(file_list[0]).name, PREVIEW_LENGTH)
+                else:
+                    preview = truncate_text(f"{len(file_list)} files: {Path(file_list[0]).name}, ...", PREVIEW_LENGTH)
+                return ClipboardEntry(
+                    id=None,
+                    content_type=ContentType.FILE,
+                    text_content=text,
+                    image_path=None,
+                    preview=preview,
+                    content_hash=content_hash,
+                    byte_size=len(text.encode("utf-8")),
+                    created_at=datetime.now(),
+                )
+
+        return None
+
+    def _save_image(self, img_bytes: bytes, content_hash: str, is_png: bool) -> tuple[Path, Path | None]:
+        ext = ".png" if is_png else ".tiff"
+        filename = content_hash[:12] + ext
+        path = IMAGE_DIR / filename
+        if not path.exists():
+            path.write_bytes(img_bytes)
+
+        # Generate thumbnail
+        thumb_filename = content_hash[:12] + "_thumb.png"
+        thumb_path = IMAGE_DIR / thumb_filename
+        if not thumb_path.exists():
+            if create_thumbnail(str(path), str(thumb_path), THUMBNAIL_SIZE):
+                return path, thumb_path
+            else:
+                return path, None
+        return path, thumb_path

clipsy/redact.py

@@ -0,0 +1,211 @@
+"""Sensitive data detection and masking for clipboard entries."""
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+
+class SensitiveType(Enum):
+    """Types of sensitive data that can be detected."""
+
+    API_KEY = "api_key"
+    PASSWORD = "password"
+    SSN = "ssn"
+    CREDIT_CARD = "credit_card"
+    PRIVATE_KEY = "private_key"
+    CERTIFICATE = "certificate"
+    TOKEN = "token"
+
+
+@dataclass
+class SensitiveMatch:
+    """A detected sensitive data match."""
+
+    sensitive_type: SensitiveType
+    start: int
+    end: int
+    original: str
+    masked: str
+
+
+# Pattern definitions for sensitive data detection
+PATTERNS: dict[SensitiveType, list[re.Pattern]] = {
+    SensitiveType.API_KEY: [
+        re.compile(r"sk-[a-zA-Z0-9]{20,}", re.ASCII),  # OpenAI
+        re.compile(r"sk-proj-[a-zA-Z0-9_-]{20,}", re.ASCII),  # OpenAI project keys
+        re.compile(r"AKIA[A-Z0-9]{16}", re.ASCII),  # AWS Access Key
+        re.compile(r"ghp_[a-zA-Z0-9]{36}", re.ASCII),  # GitHub PAT
+        re.compile(r"gho_[a-zA-Z0-9]{36}", re.ASCII),  # GitHub OAuth
+        re.compile(r"github_pat_[a-zA-Z0-9_]{22,}", re.ASCII),  # GitHub fine-grained PAT
+        re.compile(r"xox[baprs]-[a-zA-Z0-9-]{10,}", re.ASCII),  # Slack tokens
+        re.compile(r"AIza[a-zA-Z0-9_-]{35}", re.ASCII),  # Google API Key
+        re.compile(r"sq0[a-z]{3}-[a-zA-Z0-9_-]{22,}", re.ASCII),  # Square
+        re.compile(r"sk_live_[a-zA-Z0-9]{24,}", re.ASCII),  # Stripe live
+        re.compile(r"sk_test_[a-zA-Z0-9]{24,}", re.ASCII),  # Stripe test
+        re.compile(r"rk_live_[a-zA-Z0-9]{24,}", re.ASCII),  # Stripe restricted
+        re.compile(r"pk_live_[a-zA-Z0-9]{24,}", re.ASCII),  # Stripe publishable
+        re.compile(r"pk_test_[a-zA-Z0-9]{24,}", re.ASCII),  # Stripe test publishable
+    ],
+    SensitiveType.PASSWORD: [
+        re.compile(r"(?:password|passwd|pwd|pass|secret|token|api_key|apikey|auth)[=:\s]+['\"]?(\S{6,})['\"]?", re.IGNORECASE),
+    ],
+    SensitiveType.SSN: [
+        re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),  # 123-45-6789
+        re.compile(r"\b\d{9}\b"),  # 123456789 (only if looks like SSN context)
+    ],
+    SensitiveType.CREDIT_CARD: [
+        re.compile(r"\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b"),  # 16 digits
+        re.compile(r"\b\d{4}[- ]?\d{6}[- ]?\d{5}\b"),  # Amex format
+    ],
+    SensitiveType.PRIVATE_KEY: [
+        re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----", re.ASCII),
+        re.compile(r"-----BEGIN RSA PRIVATE KEY-----", re.ASCII),
+        re.compile(r"-----BEGIN EC PRIVATE KEY-----", re.ASCII),
+        re.compile(r"-----BEGIN OPENSSH PRIVATE KEY-----", re.ASCII),
+    ],
+    SensitiveType.CERTIFICATE: [
+        re.compile(r"-----BEGIN CERTIFICATE-----", re.ASCII),
+        re.compile(r"-----BEGIN X509 CERTIFICATE-----", re.ASCII),
+    ],
+    SensitiveType.TOKEN: [
+        re.compile(r"eyJ[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}", re.ASCII),  # JWT
+        re.compile(r"Bearer\s+[a-zA-Z0-9_-]{20,}", re.ASCII),  # Bearer token
+    ],
+}
+
+
+def _mask_value(value: str, sensitive_type: SensitiveType) -> str:
+    """Mask a sensitive value based on its type."""
+    if sensitive_type == SensitiveType.SSN:
+        # Show last 4 digits: •••-••-6789
+        if "-" in value:
+            return "•••-••-" + value[-4:]
+        return "•••••" + value[-4:]
+
+    if sensitive_type == SensitiveType.CREDIT_CARD:
+        # Show last 4 digits: ••••-••••-••••-1234
+        digits = re.sub(r"[- ]", "", value)
+        return "••••-••••-••••-" + digits[-4:]
+
+    if sensitive_type in (SensitiveType.PRIVATE_KEY, SensitiveType.CERTIFICATE):
+        # Just indicate the type
+        if "PRIVATE KEY" in value:
+            return "[Private Key]"
+        return "[Certificate]"
+
+    if sensitive_type == SensitiveType.PASSWORD:
+        return "••••••••"
+
+    if sensitive_type == SensitiveType.TOKEN:
+        if value.startswith("Bearer "):
+            return "Bearer ••••••••"
+        # JWT - show first part only
+        if value.startswith("eyJ"):
+            return value[:10] + "••••••••"
+        return "••••••••"
+
+    # API keys - show prefix and last few chars
+    if len(value) > 12:
+        prefix_len = min(8, len(value) // 4)
+        suffix_len = 4
+        return value[:prefix_len] + "••••••••" + value[-suffix_len:]
+
+    return "••••••••"
+
+
+def detect_sensitive(text: str) -> list[SensitiveMatch]:
+    """Detect sensitive data in text.
+
+    Args:
+        text: The text to scan for sensitive data.
+
+    Returns:
+        List of SensitiveMatch objects for each detection.
+    """
+    matches: list[SensitiveMatch] = []
+
+    for sensitive_type, patterns in PATTERNS.items():
+        for pattern in patterns:
+            for match in pattern.finditer(text):
+                # For password patterns, we capture the password itself in group 1
+                if sensitive_type == SensitiveType.PASSWORD and match.lastindex:
+                    original = match.group(1)
+                    start = match.start(1)
+                    end = match.end(1)
+                else:
+                    original = match.group(0)
+                    start = match.start()
+                    end = match.end()
+
+                masked = _mask_value(original, sensitive_type)
+                matches.append(SensitiveMatch(
+                    sensitive_type=sensitive_type,
+                    start=start,
+                    end=end,
+                    original=original,
+                    masked=masked,
+                ))
+
+    # Sort by start position and remove overlapping matches
+    matches.sort(key=lambda m: m.start)
+    non_overlapping: list[SensitiveMatch] = []
+    last_end = -1
+    for match in matches:
+        if match.start >= last_end:
+            non_overlapping.append(match)
+            last_end = match.end
+
+    return non_overlapping
+
+
+def mask_text(text: str, matches: list[SensitiveMatch] | None = None) -> str:
+    """Mask sensitive data in text.
+
+    Args:
+        text: The original text.
+        matches: Pre-detected matches, or None to detect automatically.
+
+    Returns:
+        Text with sensitive data masked.
+    """
+    if matches is None:
+        matches = detect_sensitive(text)
+
+    if not matches:
+        return text
+
+    # Build masked text by replacing matched regions
+    result = []
+    last_pos = 0
+    for match in matches:
+        result.append(text[last_pos:match.start])
+        result.append(match.masked)
+        last_pos = match.end
+    result.append(text[last_pos:])
+
+    return "".join(result)
+
+
+def is_sensitive(text: str) -> bool:
+    """Check if text contains any sensitive data.
+
+    Args:
+        text: The text to check.
+
+    Returns:
+        True if sensitive data is detected.
+    """
+    return len(detect_sensitive(text)) > 0
+
+
+def get_sensitivity_summary(matches: list[SensitiveMatch]) -> str:
+    """Get a summary of detected sensitive types.
+
+    Args:
+        matches: List of sensitive matches.
+
+    Returns:
+        Human-readable summary like "API Key, Password".
+    """
+    types = sorted(set(m.sensitive_type.value.replace("_", " ").title() for m in matches))
+    return ", ".join(types)

clipsy/storage.py

@@ -0,0 +1,258 @@
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+
+from clipsy.config import DB_PATH, MAX_ENTRIES
+from clipsy.models import ClipboardEntry, ContentType
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS clipboard_entries (
+    id             INTEGER PRIMARY KEY AUTOINCREMENT,
+    content_type   TEXT NOT NULL CHECK(content_type IN ('text', 'image', 'file')),
+    text_content   TEXT,
+    image_path     TEXT,
+    preview        TEXT NOT NULL,
+    content_hash   TEXT NOT NULL,
+    byte_size      INTEGER NOT NULL DEFAULT 0,
+    created_at     TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%S', 'now', 'localtime')),
+    pinned         INTEGER NOT NULL DEFAULT 0,
+    source_app     TEXT,
+    thumbnail_path TEXT,
+    is_sensitive   INTEGER NOT NULL DEFAULT 0,
+    masked_preview TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_created_at ON clipboard_entries(created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_content_hash ON clipboard_entries(content_hash);
+CREATE INDEX IF NOT EXISTS idx_content_type ON clipboard_entries(content_type);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS clipboard_fts USING fts5(
+    preview,
+    text_content,
+    content='clipboard_entries',
+    content_rowid='id'
+);
+
+CREATE TRIGGER IF NOT EXISTS clipboard_ai AFTER INSERT ON clipboard_entries BEGIN
+    INSERT INTO clipboard_fts(rowid, preview, text_content)
+    VALUES (new.id, new.preview, new.text_content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS clipboard_ad AFTER DELETE ON clipboard_entries BEGIN
+    INSERT INTO clipboard_fts(clipboard_fts, rowid, preview, text_content)
+    VALUES ('delete', old.id, old.preview, old.text_content);
+END;
+"""
+
+
+class StorageManager:
+    def __init__(self, db_path: str | Path | None = None):
+        self._db_path = str(db_path) if db_path else str(DB_PATH)
+        self._conn = sqlite3.connect(self._db_path)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA foreign_keys=ON")
+        self.init_db()
+
+    def init_db(self) -> None:
+        self._conn.executescript(SCHEMA)
+        self._migrate_schema()
+        self._conn.commit()
+
+    def _migrate_schema(self) -> None:
+        """Add new columns to existing databases."""
+        cursor = self._conn.execute("PRAGMA table_info(clipboard_entries)")
+        columns = {row[1] for row in cursor.fetchall()}
+        if "thumbnail_path" not in columns:
+            self._conn.execute("ALTER TABLE clipboard_entries ADD COLUMN thumbnail_path TEXT")
+        if "is_sensitive" not in columns:
+            self._conn.execute("ALTER TABLE clipboard_entries ADD COLUMN is_sensitive INTEGER NOT NULL DEFAULT 0")
+        if "masked_preview" not in columns:
+            self._conn.execute("ALTER TABLE clipboard_entries ADD COLUMN masked_preview TEXT")
+
+    def add_entry(self, entry: ClipboardEntry) -> int:
+        cursor = self._conn.execute(
+            """INSERT INTO clipboard_entries
+               (content_type, text_content, image_path, preview, content_hash, byte_size, created_at, pinned, source_app, thumbnail_path, is_sensitive, masked_preview)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                entry.content_type.value,
+                entry.text_content,
+                entry.image_path,
+                entry.preview,
+                entry.content_hash,
+                entry.byte_size,
+                entry.created_at.isoformat(),
+                int(entry.pinned),
+                entry.source_app,
+                entry.thumbnail_path,
+                int(entry.is_sensitive),
+                entry.masked_preview,
+            ),
+        )
+        self._conn.commit()
+        return cursor.lastrowid
+
+    def get_recent(self, limit: int = 25) -> list[ClipboardEntry]:
+        rows = self._conn.execute(
+            "SELECT * FROM clipboard_entries ORDER BY created_at DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+        return [self._row_to_entry(r) for r in rows]
+
+    def search(self, query: str, limit: int = 25) -> list[ClipboardEntry]:
+        sanitized = self._sanitize_fts_query(query)
+        if not sanitized:
+            return []
+        rows = self._conn.execute(
+            """SELECT e.* FROM clipboard_entries e
+               JOIN clipboard_fts f ON e.id = f.rowid
+               WHERE clipboard_fts MATCH ?
+               ORDER BY e.created_at DESC
+               LIMIT ?""",
+            (sanitized, limit),
+        ).fetchall()
+        return [self._row_to_entry(r) for r in rows]
+
+    def get_entry(self, entry_id: int) -> ClipboardEntry | None:
+        row = self._conn.execute(
+            "SELECT * FROM clipboard_entries WHERE id = ?", (entry_id,)
+        ).fetchone()
+        return self._row_to_entry(row) if row else None
+
+    def delete_entry(self, entry_id: int) -> None:
+        entry = self.get_entry(entry_id)
+        if entry:
+            if entry.image_path:
+                path = Path(entry.image_path)
+                if path.exists():
+                    path.unlink()
+            if entry.thumbnail_path:
+                thumb = Path(entry.thumbnail_path)
+                if thumb.exists():
+                    thumb.unlink()
+        self._conn.execute("DELETE FROM clipboard_entries WHERE id = ?", (entry_id,))
+        self._conn.commit()
+
+    def find_by_hash(self, content_hash: str) -> ClipboardEntry | None:
+        row = self._conn.execute(
+            "SELECT * FROM clipboard_entries WHERE content_hash = ? ORDER BY created_at DESC LIMIT 1",
+            (content_hash,),
+        ).fetchone()
+        return self._row_to_entry(row) if row else None
+
+    def update_timestamp(self, entry_id: int) -> None:
+        now = datetime.now().isoformat()
+        self._conn.execute(
+            "UPDATE clipboard_entries SET created_at = ? WHERE id = ?",
+            (now, entry_id),
+        )
+        self._conn.commit()
+
+    def update_thumbnail_path(self, entry_id: int, thumbnail_path: str) -> None:
+        self._conn.execute(
+            "UPDATE clipboard_entries SET thumbnail_path = ? WHERE id = ?",
+            (thumbnail_path, entry_id),
+        )
+        self._conn.commit()
+
+    def purge_old(self, keep_count: int | None = None) -> int:
+        keep = keep_count if keep_count is not None else MAX_ENTRIES
+        rows = self._conn.execute(
+            """SELECT id, image_path, thumbnail_path FROM clipboard_entries
+               WHERE pinned = 0
+               ORDER BY created_at DESC
+               LIMIT -1 OFFSET ?""",
+            (keep,),
+        ).fetchall()
+
+        deleted = 0
+        for row in rows:
+            if row["image_path"]:
+                path = Path(row["image_path"])
+                if path.exists():
+                    path.unlink()
+            if row["thumbnail_path"]:
+                thumb = Path(row["thumbnail_path"])
+                if thumb.exists():
+                    thumb.unlink()
+            self._conn.execute("DELETE FROM clipboard_entries WHERE id = ?", (row["id"],))
+            deleted += 1
+
+        if deleted:
+            self._conn.commit()
+        return deleted
+
+    def toggle_pin(self, entry_id: int) -> bool:
+        entry = self.get_entry(entry_id)
+        if not entry:
+            return False
+        new_pinned = not entry.pinned
+        self._conn.execute(
+            "UPDATE clipboard_entries SET pinned = ? WHERE id = ?",
+            (int(new_pinned), entry_id),
+        )
+        self._conn.commit()
+        return new_pinned
+
+    def clear_all(self) -> None:
+        rows = self._conn.execute(
+            "SELECT image_path, thumbnail_path FROM clipboard_entries WHERE image_path IS NOT NULL OR thumbnail_path IS NOT NULL"
+        ).fetchall()
+        for row in rows:
+            if row["image_path"]:
+                path = Path(row["image_path"])
+                if path.exists():
+                    path.unlink()
+            if row["thumbnail_path"]:
+                thumb = Path(row["thumbnail_path"])
+                if thumb.exists():
+                    thumb.unlink()
+        self._conn.execute("DELETE FROM clipboard_entries")
+        self._conn.commit()
+
+    def count(self) -> int:
+        row = self._conn.execute("SELECT COUNT(*) as cnt FROM clipboard_entries").fetchone()
+        return row["cnt"]
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+    @staticmethod
+    def _sanitize_fts_query(query: str) -> str:
+        # Quote each token to prevent FTS5 syntax errors from special chars
+        tokens = query.split()
+        if not tokens:
+            return ""
+        quoted = ['"' + token.replace('"', '""') + '"' for token in tokens]
+        return " ".join(quoted)
+
+    def _row_to_entry(self, row: sqlite3.Row) -> ClipboardEntry:
+        # Handle columns which may not exist in older databases
+        keys = row.keys()
+        thumbnail_path = row["thumbnail_path"] if "thumbnail_path" in keys else None
+        is_sensitive = bool(row["is_sensitive"]) if "is_sensitive" in keys else False
+        masked_preview = row["masked_preview"] if "masked_preview" in keys else None
+        return ClipboardEntry(
+            id=row["id"],
+            content_type=ContentType(row["content_type"]),
+            text_content=row["text_content"],
+            image_path=row["image_path"],
+            preview=row["preview"],
+            content_hash=row["content_hash"],
+            byte_size=row["byte_size"],
+            created_at=datetime.fromisoformat(row["created_at"]),
+            pinned=bool(row["pinned"]),
+            source_app=row["source_app"],
+            thumbnail_path=thumbnail_path,
+            is_sensitive=is_sensitive,
+            masked_preview=masked_preview,
+        )

clipsy/utils.py

@@ -0,0 +1,72 @@
+import hashlib
+import struct
+from pathlib import Path
+
+from clipsy.config import DATA_DIR, IMAGE_DIR
+
+
+def compute_hash(data: str | bytes) -> str:
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    return hashlib.sha256(data).hexdigest()
+
+
+def truncate_text(text: str, max_len: int) -> str:
+    single_line = " ".join(text.split())
+    if len(single_line) <= max_len:
+        return single_line
+    return single_line[: max_len - 3] + "..."
+
+
+def ensure_dirs() -> None:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    IMAGE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def get_image_dimensions(png_bytes: bytes) -> tuple[int, int]:
+    if len(png_bytes) < 24 or png_bytes[:8] != b"\x89PNG\r\n\x1a\n":
+        return (0, 0)
+    width = struct.unpack(">I", png_bytes[16:20])[0]
+    height = struct.unpack(">I", png_bytes[20:24])[0]
+    return (width, height)
+
+
+def create_thumbnail(image_path: str, thumb_path: str, size: tuple[int, int] = (32, 32)) -> bool:
+    """Create a thumbnail from an image file using native NSImage.
+
+    Args:
+        image_path: Path to the source image
+        thumb_path: Path to save the thumbnail
+        size: Target size in pixels (width, height)
+
+    Returns:
+        True if thumbnail was created successfully, False otherwise
+    """
+    try:
+        from AppKit import NSBitmapImageRep, NSGraphicsContext, NSImage
+
+        original = NSImage.alloc().initWithContentsOfFile_(image_path)
+        if not original:
+            return False
+
+        resized = NSImage.alloc().initWithSize_(size)
+        resized.lockFocus()
+        NSGraphicsContext.currentContext().setImageInterpolation_(3)  # High quality
+        original.drawInRect_(((0, 0), size))
+        resized.unlockFocus()
+
+        tiff_data = resized.TIFFRepresentation()
+        if not tiff_data:
+            return False
+
+        bitmap_rep = NSBitmapImageRep.imageRepWithData_(tiff_data)
+        if not bitmap_rep:
+            return False
+
+        png_data = bitmap_rep.representationUsingType_properties_(4, None)  # 4 = PNG
+        if not png_data:
+            return False
+
+        return bool(png_data.writeToFile_atomically_(thumb_path, True))
+    except Exception:
+        return False

clipsy-1.5.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: clipsy
+Version: 1.5.0
+Summary: Lightweight clipboard history manager for macOS
+Author-email: Brendan Conrad <brendan.conrad@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/brencon/clipsy
+Project-URL: Repository, https://github.com/brencon/clipsy
+Project-URL: Issues, https://github.com/brencon/clipsy/issues
+Keywords: clipboard,macos,menu-bar,history,productivity
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rumps>=0.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Clipsy
+
+[![PyPI](https://img.shields.io/pypi/v/clipsy)](https://pypi.org/project/clipsy/)
+[![CI](https://github.com/brencon/clipsy/actions/workflows/ci.yml/badge.svg)](https://github.com/brencon/clipsy/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/brencon/clipsy/branch/main/graph/badge.svg)](https://codecov.io/gh/brencon/clipsy)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A lightweight clipboard history manager for macOS. Runs as a menu bar icon — no admin privileges, no code signing, no App Store required.
+
+## Features
+
+- **Clipboard history** — Automatically captures text, images, and file copies
+- **Image thumbnails** — Visual previews for copied images in the menu
+- **Sensitive data masking** — Auto-detects API keys, passwords, SSNs, credit cards, private keys, and tokens; displays masked previews with 🔒 icon
+- **Search** — Full-text search across all clipboard entries (SQLite FTS5)
+- **Click to re-copy** — Click any entry in the menu to put it back on your clipboard
+- **Deduplication** — Copying the same content twice bumps it to the top instead of creating a duplicate
+- **Auto-purge** — Keeps the most recent 500 entries, automatically cleans up old ones
+- **Persistent storage** — History survives app restarts (SQLite database)
+- **Corporate IT friendly** — Runs as a plain Python process, no `.app` bundle or Gatekeeper issues
+
+## Requirements
+
+- macOS
+- Python 3.10+ (Homebrew recommended: `brew install python3`)
+
+## Installation
+
+### Via pip (recommended)
+
+```bash
+pip install clipsy
+```
+
+### From source
+
+```bash
+git clone https://github.com/brencon/clipsy.git
+cd clipsy
+python3 -m venv .venv
+.venv/bin/pip install -e .
+```
+
+## Usage
+
+```bash
+# Run clipsy (a scissors icon appears in your menu bar)
+clipsy
+```
+
+Then just use your Mac normally. Every time you copy something, it shows up in the Clipsy menu:
+
+```
+[✂️ Icon]
+├── Clipsy - Clipboard History
+├── ──────────────────
+├── Search...
+├── ──────────────────
+├── "Meeting notes for Q3 plan..."
+├── "https://github.com/example..."
+├── 🔒 "password=••••••••"
+├── [thumbnail] "[Image: 1920x1080]"
+├── ... (up to 10 items)
+├── ──────────────────
+├── Clear History
+├── ──────────────────
+├── Support Clipsy
+├── ──────────────────
+└── Quit Clipsy
+```
+
+## Auto-Start on Login
+
+Run clipsy automatically when you log in — no terminal needed:
+
+```bash
+# Install as a LaunchAgent
+scripts/install_launchagent.sh install
+
+# Check status
+scripts/install_launchagent.sh status
+
+# Remove auto-start
+scripts/install_launchagent.sh uninstall
+```
+
+## Data Storage
+
+All data is stored in `~/.local/share/clipsy/`:
+
+| File | Purpose |
+|------|---------|
+| `clipsy.db` | SQLite database with clipboard entries |
+| `images/` | Saved clipboard images (PNG files) |
+| `clipsy.log` | Application log |
+
+## Development
+
+```bash
+# Install with dev dependencies
+.venv/bin/pip install -e ".[dev]"
+
+# Run tests
+.venv/bin/python -m pytest tests/ -v
+
+# Run with coverage
+.venv/bin/python -m pytest tests/ --cov=clipsy --cov-report=term-missing
+```
+
+## Architecture
+
+```
+NSPasteboard → monitor.py → redact.py → storage.py (SQLite) → app.py (menu bar UI)
+```
+
+- **`app.py`** — `rumps.App` subclass; renders the menu bar dropdown, handles clicks and search
+- **`monitor.py`** — Polls `NSPasteboard.changeCount()` every 0.5s; detects text, images, and file copies
+- **`storage.py`** — SQLite with FTS5 full-text search, SHA-256 deduplication, auto-purge
+- **`redact.py`** — Sensitive data detection and masking (API keys, passwords, SSN, credit cards, tokens)
+- **`config.py`** — Constants, paths, limits
+- **`models.py`** — `ClipboardEntry` dataclass, `ContentType` enum
+- **`utils.py`** — Hashing, text truncation, PNG dimension parsing, thumbnail generation
+
+### Dependencies
+
+Only one external dependency:
+
+- **`rumps`** — macOS menu bar app framework (brings `pyobjc-framework-Cocoa` transitively)
+- **`sqlite3`** — Built into Python
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

clipsy-1.5.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+clipsy/__init__.py,sha256=RfTNMAT90hngQkclaI0i0rdsR5s2s2IFJWzExWhvwjU,46
+clipsy/__main__.py,sha256=vCWOKz08ZY3Uc5orHOMND0sEgBnyvD0WkD4o6b4_6Mw,493
+clipsy/app.py,sha256=_IKuZgA-DvAE3KDsDN00S0aaMIxwBpiv_P1fpzwQFqU,7299
+clipsy/config.py,sha256=E9NCsGMeT2H0YXYCq5xYwbd27VkksV4S9txZSMX0RmE,672
+clipsy/models.py,sha256=i3KjD4Dcp7y_gTXkIBr2xZxFIIC6kHaMWmv6cSIDABM,563
+clipsy/monitor.py,sha256=UUKZToYcZ5pzu7LfiuJ_nnE4AA-d3uLW-WdQU_XrDME,6288
+clipsy/redact.py,sha256=EU2nq8oEDYLZ_I_9tX2bXACIF971a0V_ApKdvpN4VGY,7284
+clipsy/storage.py,sha256=QNox2-spkVx_gMPSWqKgF_yj-SMpRJ4UAT6yd9l6rVY,9794
+clipsy/utils.py,sha256=rztT20cXYJ7633q3oLwt6Fv0Ubq9hm5bPPKDkWyvxdI,2208
+clipsy-1.5.0.dist-info/licenses/LICENSE,sha256=bZ7uVihgPnLGryi5ugUgkVrEoho0_hFAd3bVdhYXGqs,1071
+clipsy-1.5.0.dist-info/METADATA,sha256=7lAWnXyqO69PZSLoFjOZKU1WuXaaykI0a3V-dUSRkUE,5693
+clipsy-1.5.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+clipsy-1.5.0.dist-info/entry_points.txt,sha256=ISIoWU3Zj-4NEuj2pJW96LxpsvjRJJH73otv9gA9YSs,48
+clipsy-1.5.0.dist-info/top_level.txt,sha256=trxprVJk4ZMudCshc7PD0N9iFgQO4Tq4sW5L5wLduns,7
+clipsy-1.5.0.dist-info/RECORD,,

clipsy-1.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

clipsy-1.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clipsy = clipsy.__main__:main

clipsy-1.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Brendan Conrad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clipsy-1.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+clipsy