$ show openclaw/imsgcrawl
imsgcrawl is a local-first CLI tool for reading, archiving, and searching Apple iMessage data. It operates by taking a read-only snapshot of the macOS Messages SQLite database (`chat.db`), extracting handles, chats, messages, and deletion events, then merging them into a local SQLite archive. The tool provides bounded commands for metadata, status, sync, chats, messages, full-text search, and phone-only contact export. It outputs both human-readable text (with terminal control escape protection) and stable JSON for automation. The architecture is cleanly separated into packages for archive management, message extraction (including attributed body decoding and edit/unsend reconstruction), and portable SQLite snapshotting with macOS copy-on-write support. The codebase demonstrates strong engineering practices: thorough test coverage including fuzzing, explicit privacy boundaries, identity validation for source databases, and careful handling of edge cases like malformed UTF‑16, hardlinked sidecars, and concurrent sync locking.
The LLM identified 5 files worth highlighting for reuse:
Decodes iMessage attributed bodies stored in NSArchiver/NSAttributedString format. Handles streamtyped length encoding, UTF-16 little/big endian, malformed UTF-8 rejection, leading NUL preservation, and unpaired surrogate validation. Isolated and reusable for decoding macOS attributed string data in other contexts.
Parses Apple's message_summary_info plist to reconstruct edited/unsent iMessage text. Handles edits, retractions, partial unsends, and UTF-16 part ranges with offset validation. Determines whether a message is fully unsent, partially retracted, or edited, and reconstructs the current visible body. Reusable for any tool that needs to parse iMessage revision metadata from binary plist data.
Validates that an archive path is safe to open or create: rejects foreign databases, orphaned or hardlinked SQLite sidecars, source-overlapping paths, and symlink/`..` paths that could alias unintended files. Uses canonical path resolution and stat comparisons. Reusable for any tool needing robust preflight checks before opening a SQLite file.
Creates a private, verifiable copy of a SQLite database bundle (main file, WAL, journal). Uses copy-on-write clones on macOS APFS when possible, falling back to byte copies. Verifies integrity by hashing each file, checking generation identity, and running `pragma quick_check` after opening. Includes retry logic for changing source files. Reusable for safe read-only SQLite access in any Go project.
Implements cross-process exclusive file locking using flock on a dedicated `.sync.lock` file. Locks are context-aware with retry (non-blocking try with polling), ensuring only one sync operation runs at a time. The lock file is opened with O_NOFOLLOW to prevent symlink attacks. Reusable for any Go program needing simple, portable, exclusive file locking on Unix.