.gitignore additions, readme, and Mac/Linux dev testing automation script

.gitignore

@@ -1,6 +1,7 @@
 .antigravitycli/
 .pytest_cache/
 dist/
+__pycache__/
 
 
 

README.md

@@ -0,0 +1,54 @@
+# LibreOffice AutoSave Extension
+
+A lightweight, background-running extension for LibreOffice that automatically saves your documents while you work. Built with modern Python and packaged using Poetry.
+
+## Features
+
+- **Silent & Automatic:** Hooks into LibreOffice's global `OnLoad` and `OnNew` events to run completely in the background without needing a user interface.
+- **Smart Debouncing:** Waits for you to pause typing (default: 1 second delay) before issuing a save. Rapid continuous typing will dynamically delay the save loop to prevent UI stuttering on large documents.
+- **Atomic Backups:** Before triggering LibreOffice's internal synchronous `.store()`, the extension executes an atomic file-copy of the last known saved state to a hidden `.bak` file (e.g., `.filename.bak`). This protects your data payload from corruption if your OS or LibreOffice crashes during a complex write cycle.
+- **Safe Evaluation:** Will not blindly save new documents that have not been given an initial file path location, protecting you from unexpected file generation.
+
+## Manual Installation
+
+1. Grab the compiled `AutoSave.oxt` file from the `dist/` directory or the latest release.
+2. Open LibreOffice.
+3. Navigate to **Tools > Extension Manager**.
+4. Click **Add...** and select `AutoSave.oxt`.
+5. Restart LibreOffice. The listener is now globally attached and will silently watch your documents!
+
+## Development & Testing
+
+This repository uses [Poetry](https://python-poetry.org/) to handle dev dependencies, unit testing, and linting. Note that the runtime execution of the extension happens within LibreOffice's embedded Python interpreter.
+
+### Setup
+```bash
+# Initialize the virtual environment and install pytest
+poetry install
+```
+
+### Running Tests
+The test suite utilizes `unittest.mock` to heavily mock the internal PyUNO C++ bridge. You can run the test matrix without needing an active LibreOffice instance:
+```bash
+poetry run pytest
+```
+
+### Fast Deployment Loop
+To accelerate iteration speed when modifying the python codebase, use the provided deployment scripts. They will automatically build the ZIP archive, forcefully kill active LibreOffice instances to drop file locks, use the `unopkg` command-line utility to uninstall the old extension, and inject the freshly built `.oxt` before restarting Writer.
+
+**For Windows (PowerShell):**
+```powershell
+powershell -ExecutionPolicy Bypass -File .\deploy_and_test.ps1
+```
+
+**For macOS / Linux (Bash):**
+```bash
+chmod +x deploy_and_test.sh
+./deploy_and_test.sh
+```
+
+## Debugging
+
+If the AutoSave functionality fails silently, check the output log generated by the background thread. The extension writes timestamps and tracebacks directly to your home directory:
+- **Windows:** `C:\Users\YourUsername\workspace\LibreOfficeAutoSave\autosave_debug.log`
+- **Linux/Mac:** `~/autosave_debug.log`

deploy_and_test.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -e
+
+EXT_ID="org.libreoffice.extensions.autosave"
+
+echo -e "\033[0;36m1. Building the extension...\033[0m"
+python3 build_oxt.py
+
+echo -e "\033[0;36m2. Killing open LibreOffice instances...\033[0m"
+# Ignore kill errors if LibreOffice isn't running
+pkill -f soffice || true
+pkill -f libreoffice || true
+sleep 2
+
+# Detect OS and set paths appropriately
+if [[ "$OSTYPE" == "darwin"* ]]; then
+    # Mac OSX
+    UNOPKG="/Applications/LibreOffice.app/Contents/MacOS/unopkg"
+    SOFFICE="/Applications/LibreOffice.app/Contents/MacOS/soffice"
+else
+    # Linux (usually in PATH, but fallback to typical installation locations)
+    UNOPKG=$(command -v unopkg || echo "/usr/lib/libreoffice/program/unopkg")
+    SOFFICE=$(command -v libreoffice || command -v soffice || echo "/usr/bin/soffice")
+fi
+
+echo -e "\033[0;36m3. Uninstalling existing extension...\033[0m"
+# We ignore the exit code here in case the extension isn't currently installed
+"$UNOPKG" remove "$EXT_ID" 2>/dev/null || true
+
+echo -e "\033[0;36m4. Installing the new extension...\033[0m"
+"$UNOPKG" add -f dist/AutoSave.oxt
+
+echo -e "\033[0;36m5. Starting LibreOffice Writer...\033[0m"
+# Launch Writer as a detached background process
+"$SOFFICE" --writer >/dev/null 2>&1 &
+
+echo -e "\033[0;32mDeployment complete! Writer is launching in the background.\033[0m"