How starfysh-tech/appletscriptorium works
Project Type and Purpose
• AppletScriptorium is a collection of local macOS automation tools.
• It contains two standalone sub‐systems:
a. Summarizer – a full pipeline “intelligence digest generator” that processes Google Alert emails, fetches and cleans article content, uses a local LLM to summarize, and delivers a digest via SMTP.
b. ExtensionAuditor – a command-line Chrome extension security scanner that analyzes installed extensions and produces vulnerability reports.
File Structure Analysis
• Top-level:
• install scripts: install.sh, setup-mail-rule.sh, run_workflow.sh
• Summarizer/: Python package with modules, CLI entry point, templates, tests, sample fixtures, deployment scripts, requirements
• ExtensionAuditor/: standalone Python script + README
• Configuration templates: .env.template, Summarizer/templates
• Summarizer directory follows a modular pipeline pattern (extraction → fetching → cleaning → summarization → rendering → delivery), with both event-driven (AppleScript Mail rule) and scheduled (cron or shell) triggers.
• Key external integrations: Mail.app via AppleScript, SMTP service, local LLM backends (LM Studio, optional Ollama), url-to-md CLI, Jina Reader API.
Key README Insights
• Summarizer supports two invocation modes: Mail rule event and CLI/cron.
• Config driven by config.py and environment variables in .env.
a. Main Components
• Mail.app with Mail Rule
• AppleScript “process-alert.scpt”
• Summarizer CLI orchestration (cli.py)
• LinkExtractor (link_extractor.py)
• ArticleFetchers (urltomd_fetcher, jana_fetcher, article_fetcher)
• ContentCleaner + MarkdownCleanup
• Summarizer (LLM interface)
• DigestRenderer
• SMTP Server (external)
• Supporting scripts: run_workflow.sh, bin/run_alert.sh, cron job
• Optional extension: ExtensionAuditor tool
b. Relationships and Data Flow
1. Mail.app receives Google Alert → Mail rule triggers AppleScript
2. AppleScript invokes Summarizer CLI (or run_workflow.sh)
3. CLI calls link_extractor → yields URLs
4. Parallel fetch via article_fetcher / url-to-md / Jina fallback
5. Raw HTML → content_cleaner → markdown_cleanup
6. Markdown → summarizer module (local LLM backend)
7. Summaries → digest_renderer → HTML/text digest
8. SMTP module sends digest to recipients
9. Logs and output files written to runs/<timestamp>/
c. Architectural Patterns and Principles
• Pipeline pattern with clearly separated stages (extract, fetch, clean, summarize, render, deliver)
• Modular design: each stage is a distinct Python module
• Configurable backends via environment variables / config.py
• Event-driven vs scheduled invocation paths
• ThreadPoolExecutor for I/O-bound fetching; sequential summarization to throttle LLM
d. Technologies and Frameworks
• AppleScript (process-alert.scpt, fetch-alert-source.applescript)
• Python 3 modules and CLI (click or argparse patterns)
• Local LLM backends: LM Studio REST API, optional Ollama fallback
• url-to-markdown CLI, Jina Reader API
• SMTP libraries (smtplib)
• Pytest for testing pipeline modules
Essential Details to Capture
• Distinct invocation paths (AppleScript vs cron vs manual CLI).
• Parallel vs sequential stages.
• Environment configuration points (.env, config.py).
• LLM backend failover logic (LM Studio → Ollama → Jina).
• Output artifacts and logging directory structure.
• Separation between Summarizer and ExtensionAuditor subsystems.